@rubytech/create-sitedesk-code 0.1.521 → 0.1.523

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -110,13 +110,95 @@ The route (`server/routes/admin/routines.ts`) is account-scoped like `calendar.t
 | `GET /api/admin/routines` | Lists automation Events: `recurrence IS NOT NULL OR agentChannel IS NOT NULL OR actionPlugin IS NOT NULL`. Keyed by the `eventId` property. |
 | `GET /api/admin/routines/:eventId` | One routine, same automation+account guard. |
 | `PATCH /api/admin/routines/:eventId` | Edits `agentPrompt` and/or `recurrence`. Cron validation and the timezone-aware `nextRun` recompute copy the scheduling plugin's `schedule-update` tool. An invalid cron is rejected 400 with no write. Only creation and deletion stay agent-only (`schedule-event`/`schedule-cancel`). |
+| `POST /api/admin/routines/:eventId/suspend` | Writes `eventStatus = 'suspended'` on a routine currently `'scheduled'`. 404s otherwise, so a second suspend is not a silent no-op. |
+| `POST /api/admin/routines/:eventId/resume` | Returns a suspended routine to `'scheduled'`. 404s if it is not suspended, 409s if it cannot be resumed. |
+| `POST /api/admin/routines/suspend-all` | Suspends every routine currently `'scheduled'` and marks each one. Returns the count. |
+| `POST /api/admin/routines/resume-all` | Resumes only the routines `suspend-all` marked. Returns `restored` and a `refused` list. |
+
+**Suspension is the reversible stop.** Before it, the only way to stop a routine
+from the dashboard was to delete it. A suspended routine keeps its schedule, its
+instruction and its history; it simply stops being selected. The enforcement is
+not a new guard: all four `eventStatus = 'scheduled'` predicates in
+`check-due-events.ts` are equalities, so any other status is excluded by
+construction, and `'suspended'` is the literal the shipped roster already seeds
+with.
+
+The status write lives on dedicated routes rather than on `PATCH`, which admits
+only `agentPrompt` and `recurrence` and 400s on anything else. Widening `PATCH`
+would put a free-form status on the edit path.
+
+**Resume schedules forward and never backfills.** For a recurring routine
+`nextRun` is recomputed from the cron in the routine's own timezone; the stored
+value is deliberately not restored, because the sweep selects `nextRun <= now`
+and a stale one fires on the next tick. A one-time routine has no cron to
+advance, so resuming one whose date has passed is refused (409) with the date
+named — resuming it would run it immediately, for a window the operator did not
+choose. A one-time routine still in the future resumes with its date untouched.
+
+**Suspend-all acts on exactly the dispatchable set**, so the number on the
+control is the number of routines that could have fired; rows already due,
+cancelled or suspended are untouched and a deliberately cancelled routine is
+never re-armed. Each row it stops is marked, and resume-all selects only marked
+rows — a routine suspended one at a time carries no mark and stays suspended,
+which is what makes resume-all safe to press. The seeded roster is unmarked by
+construction, so resume-all never enables it.
 
 Observability rides `[admin:routines]`: `op=list accountId=<8> count=<n>`,
-`op=get id=<8> found=<bool>`, and `op=patch id=<8> fields=<…> outcome=ok|rejected
-reason=<invalid-cron|not-found> nextRun=<…> cron=<serialized>`. A `count=0` while
-routines exist for the account is the account-scope-miss signature; the logged
-`cron=` on `outcome=ok` confirms the persisted expression without opening the
-graph.
+`op=get id=<8> found=<bool>`, `op=patch id=<8> fields=<…> outcome=ok|rejected
+reason=<invalid-cron|not-found> nextRun=<…> cron=<serialized>`, and
+`op=suspend|resume id=<8> scope=<one|all> outcome=<applied|refused|failed>` with
+`count=`/`restored=` and, on a refusal, `reason=<not-scheduled|not-suspended|
+past-one-time|invalid-cron>`. A `count=0` while routines exist for the account is
+the account-scope-miss signature; the logged `cron=` on `outcome=ok` confirms the
+persisted expression without opening the graph.
+
+Two scheduler-side lines close the loop, because a suspend that the sweep ignores
+looks identical to a healthy routine until it fires. `[schedule-sweep]
+op=skip-suspended account=<8> count=<n>` is emitted every sweep for every local
+account including zero, filtered to automation rows by the same predicate the
+routes and the census use, so all three count one set. Nothing else in the sweep
+ever mentions a suspended row, so without this line the whole class is invisible
+there and a suspension that stopped holding would look exactly like one that
+still holds. `[schedule-audit] op=suspension-census acct=<8> routines=<n>
+dispatchable=<n> suspended=<n> due=<n> cancelled=<n> completed=<n> other=<n>` is
+the standing reconciliation: the named buckets are the whole shipped status enum
+plus `suspended`, so they sum to `routines` by construction and `other` above
+zero means a routine carries a status the system does not handle — nothing else
+would say so. `completed` gets its own bucket even though no code path writes it
+today, because `schedule-update` takes `eventStatus` as an unvalidated string and
+one completed routine would otherwise pin `other` above zero forever and kill the
+alarm.
+
+**The shipped roster.** Every account starts with ten routines — `start-of-day`,
+`inbound-check`, `end-of-day`, `appointment-reminder`, `commitment-chase`,
+`calendar-reconcile`, `contact-reconcile`, `crm-reconcile`, `finance-reconcile`,
+`weekly-digest` — seeded `eventStatus:'suspended'` with `nextRun` NULL and no
+channel or destination, so `/routines` is a catalogue to enable rather than a
+blank page. The list query applies no status filter and `AUTOMATION_WHERE`
+admits them on `recurrence IS NOT NULL`, so they render with no change here.
+They cannot fire: every dispatch query in `check-due-events.ts` selects
+`eventStatus = 'scheduled'`, and the recurring one additionally requires
+`nextRun IS NOT NULL`.
+
+Enabling one is `schedule-update {eventId, eventStatus:'scheduled', recurrence,
+timezone}` — all four arguments. `eventStatus` on its own does not touch
+`nextRun`, so the row would read enabled and never fire; omitting `timezone`
+recomputes `nextRun` in the server's zone rather than the operator's, so it
+fires at the wrong hour and still looks healthy. Binding a channel and a
+destination is separate and equally required: `chooseDispatchMode` returns
+`{kind:'none'}` unless `agentChannel`, `agentDestination` and `agentPrompt` are
+all present, and a destination cannot be seeded because
+`validateAgentDestination` is fail-closed against the account's
+`whatsapp.adminPhones` / `telegram.adminUsers`, both empty on a fresh install.
+
+The seed re-runs on every upgrade and never writes `eventStatus`,
+`agentChannel`, `agentDestination`, `recurrence` or `timezone` on a row that
+already exists, so an upgrade cannot re-suspend an enabled routine, unbind a
+bound destination or reset a retimed cron. Three standing checks ride the
+scheduling heartbeat and report on every tick including zero:
+`[schedule-audit] op=roster` (a seed that never ran or ran short),
+`op=dispatch-mode-none` (a routine that fires and delivers nothing) and
+`op=null-timezone` (a routine that fires at the box's hour).
 
 ### Skills
 
@@ -171,7 +253,9 @@ both `kind: 'specialist'` and differ only by origin.
   `agent-builder`). The specialist modal shows the model, tools, the owning
   plugin's skills, and the system-prompt body. Specialists are authored, edited,
   and deleted through chat (`agent-builder` / `specialist-management`), so the
-  specialist modal offers no delete or open-agent link.
+  specialist modal offers no delete or open-agent link. **These are the only
+  agents that can be switched off from this page**, and the route enforces that
+  rather than relying on the UI to withhold the control.
 - **Shipped specialists** (`origin: 'shipped'`) — the union of
   `<accountDir>/specialists/agents/`, `<accountDir>/specialists/agents-disabled/`
   and `PLATFORM_ROOT/templates/specialists/agents/`, in that precedence order.
@@ -179,22 +263,27 @@ both `kind: 'specialist'` and differ only by origin.
   a disabled agent still appears there through its bundled-template row. The
   route once walked only the account plugins tree, so the twelve
   highest-capability agents on the box were the ones the operator could not see.
-  These are the only agents that can be disabled, and the route enforces that
-  rather than relying on the UI to withhold the control.
+  **A shipped agent cannot be switched off here.** It is part of the product, so
+  disabling one breaks a capability the operator did not author and cannot
+  repair, and it is not what runs unattended: an agent runs only when something
+  dispatches it, an inbound message is operator-initiated, so the only autonomous
+  path is the scheduler. The modal says so and points at the routines instead.
   **A file in the LIVE directory whose name also exists under
   `<accountDir>/plugins/*/agents/` is excluded from this set.** `agent-builder`
   copies the authored file into `specialists/agents/` because presence there is
   what makes an agent dispatchable, so the live directory says nothing about who
   wrote the agent and every activated user-created specialist used to render
   twice, the second time as Shipped. The account plugin tree is the authorship
-  evidence and its row wins, which is also why `disable` refuses a slug present
-  under `plugins/*/agents/`: quarantine exists to stop provisioning re-delivering
-  a file, and provisioning never writes that tree. Both gates read filenames off
-  disk, so a plugin file whose frontmatter does not parse still suppresses its
-  live twin — it is authored either way, and `specialistsSkipped` is what reports
-  the parse failure. The exclusion applies to the live copy only: a copy found in
-  quarantine is operator state, keeps its Shipped row and its `disabled:true`,
-  and is therefore still switchable back on. Each exclusion logs
+  evidence and its row wins; it is the same discriminator `disable` requires.
+  Both gates read filenames off disk, so a plugin file whose frontmatter does not
+  parse still suppresses its live twin — it is authored either way, and
+  `specialistsSkipped` is what reports the parse failure. **The exclusion covers
+  both account directories, live and quarantine.** It was live-only while only a
+  shipped agent could be quarantined; now that an authored specialist can be
+  switched off, its specialist row carries the plugin, the skills, the detail
+  route and its own disabled state, so a second row from the shipped walk would
+  be a duplicate with none of that. The bundled templates are never deduped: a
+  bundled name is shipped by definition. Each exclusion logs
   `op=list-shipped-dedup file=<name>` and the count rides `op=list` and the
   response as `deduped`.
 
@@ -222,35 +311,137 @@ no class is dashed and uncoloured rather than painted as if it were understood.
 Badge colours come from the shared semantic status set: `-solid` with white text
 for the badge, `-tint` with `-textOnTint` for a chip, never white.
 
+**No tool name on a card.** The card renders the badge word and the plugin (or,
+for a public agent, its status). It does not render `riskiestTool`: a qualified
+tool symbol tells the person reading this dashboard nothing the badge word did
+not. `riskiestTool` stays on the wire and on the `op=risk` line as a diagnostic,
+so a wrong class is still traceable to the tool that set it without re-deriving
+the classification.
+
+**Combination rules.** The per-tool max answers "what is the worst single thing
+this agent can do". It cannot answer "what can it do in sequence", which is the
+question the person reading the dashboard is actually asking: an agent that
+reads a customer record and an agent that emails a stranger are both red, and so
+is the one that does both. Four rules in `server/lib/agent-risk.ts` run *after*
+the max. A rule fires when **every** risk class it names is present among the
+resolved tools and its own class is not below the class the max produced; the
+first match in table order wins and supplies the sentence the modal renders.
+
+| Rule | Fires when the agent holds | Class | What the operator reads |
+|---|---|---|---|
+| `changes-and-sends` | a `write_local` tool and an `external` tool | red | It can change your records and also send messages out, so a wrong change can reach someone outside the business. |
+| `reads-and-sends` | a `read` tool and an `external` tool | red | It can read what is held on this device and also send things out of it, so anything it reads can leave. |
+| `changes-and-runs` | a `write_local` tool and an `exec` tool | red | It can change files on this device and run commands, so a mistake is not confined to one file. |
+| `reads-and-runs` | a `read` tool and an `exec` tool | red | It can read what is held on this device and run commands on it. |
+
+The order is the priority order: reaching outside the business outranks running
+a command inside it, and changing something outranks reading it. A rule may only
+**raise** a class, never lower one, and because `exec` and `external` both
+saturate at red today every rule is itself red — so on the shipped fleet the
+rules change no colour and their whole product is the named hazard in words. A
+rule whose class sat below the derived one would be skipped rather than applied,
+so a softer sentence can never be attached to a harder class.
+
+With no rule matched the sentence comes from the class itself: green says it can
+only read, amber says it can change what is held here and nothing reaches
+outside, red says it can run commands or reach services outside. The three
+forced-red paths carry their own sentences instead, because none of them derived
+a capability: a tool with no risk class on this install, an agent with no
+`tools:` line at all, and a plugin registry that failed to load.
+
+Of the four rules, three fire on the twelve shipped specialists
+(`changes-and-sends`, `changes-and-runs`, `reads-and-runs`) and `reads-and-sends`
+fires on none of them, which is what the `op=rule-census` line exists to report
+across real accounts.
+
 **Disable.** `<accountDir>/specialists/agents/` is the live dispatchable set —
 `spawn-context.ts` reads it to build the spawn manifest — so disabling **moves**
-the agent file to `<accountDir>/specialists/agents-disabled/` and records the
-basename in a 0600 `<accountDir>/agents-disabled.json`. A flag alone would leave
-the agent running while the card claimed otherwise.
-
-The file is moved, never deleted: a premium `--` agent and an operator-edited
-override each exist only in the account dir, so deleting one and later restoring
-from the bundled template would hand back a different agent than the operator
-switched off. A disabled agent stays listed, marked `Disabled`, because an agent
-that vanished from the surface that disabled it could never be switched back on.
-
-`provision-account-dir.sh` re-reads the store after its core-specialist recopy
-and removes anything named in it, so an upgrade does not silently re-deliver a
-disabled agent. An unreadable store withholds nothing and says so: a corrupt
-file is not evidence that an agent was disabled.
-
-Disabling also reconciles the admin's routing prose. `agents/admin/AGENTS.md`
-carries one `- **specialists:<name>**:` line per dispatchable specialist, and
+the agent file to `<accountDir>/specialists/agents-disabled/`. A flag alone would
+leave the agent running while the card claimed otherwise. `agent-builder` copies
+an authored specialist into that same live directory, because presence there is
+what makes it dispatchable, so the same move applies to it.
+
+The file is moved, never deleted: an authored specialist's activated copy can
+carry operator edits its plugin-tree original does not, so deleting one and later
+restoring "the original" would hand back a different agent than the operator
+switched off. A disabled agent stays listed, because an agent that vanished from
+the surface that disabled it could never be switched back on.
+
+**Authorisation is drawn in both states.** Every specialist card carries a
+`Live` or `Stood down` pill, and the header above the list reads
+`<n> agents · <n> stood down`, derived from the same rows the cards render.
+Drawing only the disabled half made a live agent indistinguishable from a pill
+that failed to render, and left the operator counting cards to answer how much
+of the fleet was switched off. Public agents carry no pill: they have no disable
+path, so `Live` there would assert something the surface never derived.
+
+**The disable confirm names what stops.** Before the confirm it reads
+`Stop this agent being dispatched?` plus the skills that run through the agent
+and the fact that nothing can hand it work until it is switched back on. It does
+**not** name the routines that dispatch the agent, and cannot: a routine
+`:Event` stores `agentChannel`, `agentDestination` and `agentPrompt`, never an
+agent, so there is nothing on disk to join against. A shipped agent's detail
+also carries no skills, because a shipped specialist owns no skills directory, so
+today the skills clause appears only on a plugin-backed specialist. The
+shipped-agent sentence is a different thing and does not conflict: it names
+suspending routines as the general way to stop unattended dispatch, which is
+true of every shipped agent, rather than claiming this one's routines can be
+listed.
+
+Three cases, no more. Authored with a live copy → moved to quarantine. Authored
+with no live copy → refused 409: it is not in the dispatchable set, so there is
+nothing to switch off and recording one would claim work that did not happen.
+Not authored → refused 404, naming the routines as what stops it instead.
+
+**Enable is deliberately not symmetric, and takes no authorship check.** An
+install that disabled a shipped agent before the gate was inverted holds it in
+the quarantine directory and names it in `agents-disabled.json`; requiring
+authorship on enable would strand it there with no route back through the
+product. So enable serves both classes: a quarantined authored specialist, and a
+shipped agent disabled under the old rule (whether it was moved, or was
+bundled-only and recorded in the store alone).
+
+**Nothing writes `agents-disabled.json` any more.** That 0600 store exists only
+to stop the next provisioning run re-delivering a withheld shipped file —
+`provision-account-dir.sh` re-reads it after its core-specialist recopy and
+removes anything named in it — and shipped disable is now refused, so no new
+entry can be created. An authored specialist needs no entry either: provisioning
+never writes the account plugin tree, so the quarantined file is its whole state.
+The store is now read-and-clear: the listing reads it for shipped rows and enable
+clears entries from it, rewriting it whole and re-applying 0600 explicitly
+(`writeFileSync`'s `mode` applies only on creation, and nothing creates this file
+now). An unreadable store withholds nothing and says so: a corrupt file is not
+evidence that an agent was disabled.
+
+Both routes reconcile the admin's routing prose. `agents/admin/AGENTS.md` carries
+one `- **specialists:<name>**:` line per dispatchable specialist, and
 `agents-md-bootstrap.sh` used to only ever append, so a disabled agent stayed
 advertised and the admin dispatched to a file that was no longer there. The
-script now withholds a line for every name in the store, and both routes exec it
-after the move, so the prose is right immediately rather than after the next
+script withholds a line for every name in the store and both routes exec it after
+the move, so the prose is right immediately rather than after the next
 provisioning run. It emits `[agents-md] op=specialist-lines account=<id8>
-kept=<n> withheld=<comma-list|none|store-unreadable>`. `system-status` reads the
-same store, so a disabled agent reports `disabled (operator)` rather than
+kept=<n> withheld=<comma-list|none|store-unreadable>`. Note the reach, because it is not
+symmetric: the script skips every `--` filename as out of scope, and its prune is
+keyed on a store basename (`acme--helper`) while the routing line is keyed on the
+frontmatter name (`helper`) that the activation path in `specialist-management`
+wrote. So the bootstrap can neither remove nor restore an authored specialist's
+line, and before this change that did not matter because that class could not be
+disabled at all. It is now the only class that can be, so the route makes a
+second, targeted pass for it, reading the name from whichever copy of the file
+exists after the move and emitting `op=agents-md-authored`. Without it the admin
+would keep advertising a specialist whose file is quarantined and dispatch would
+fail inside the turn, which is the defect the bootstrap's prune was written to
+prevent, on the one class it does not reach. `system-status` reads the same store, so a shipped agent
+disabled under the old rule reports `disabled (operator)` rather than
 `missing file`, and the header counts the two separately
 (`<n> registered, missing=<x> disabled=<y>`).
 
+Observability rides `[admin/agents] op=disable|enable accountId=<8> slug=<s>
+origin=<specialist|shipped> eligible=<bool> outcome=<applied|refused|failed>`
+with `reason=<not-user-created|not-dispatchable|not-disabled>` on a refusal.
+`eligible=false outcome=refused` is what proves the gate is live rather than
+merely re-labelled in the UI.
+
 **Account scope.** The route (`server/routes/admin/agents.ts`) never infers an
 account from device state. The two reads resolve from the caller's admin session
 (`requireAdminSession` + the shared `accountDirForSession` in
@@ -264,10 +455,10 @@ explicit `?plugin=` parameter, not inferred from `--` in the slug.
 
 | Route | Behaviour |
 |-------|-----------|
-| `GET /api/admin/agents` | Session-scoped. Lists the session account's public `agents/*/` dirs (never the `admin` agent), its user-created specialists from `plugins/*/agents/*.md`, and its shipped specialists, each row tagged `kind` and `origin` and carrying `risk`, `riskiestTool`, `unresolved` and `disabled`. A live-directory candidate whose filename also exists under `plugins/*/agents/` is dropped and counted, so an activated user-created agent is listed once. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped, deduped, riskSurfaceFailed}`. 401 when the session maps to no account. |
-| `GET /api/admin/agents/:slug` | Session-scoped. Without `?plugin=` or `?origin=`, returns a public agent's config fields + four owned docs + a `present` map (a missing or unreadable doc is `''`/`present.<role>=false`, never a 500). With `?plugin=`, that plugin's user-created specialist; with `?origin=shipped`, the shipped one. Both specialist shapes add `{risk, riskiestTool, unresolved, byTool, disabled}`, where `byTool` is one class per declared tool. Selection is explicit rather than inferred, because a premium file and a user-created specialist under a plugin of the same name produce the same slug. Unknown 404s, 401 as above. |
-| `POST /api/admin/agents/:slug/disable?accountId=` | Shipped agents only, enforced here: a slug present in none of the three shipped directories 404s, and so does a slug present under `plugins/*/agents/` (a user-created specialist, `reason=user-created-specialist`), because its activated copy in the live directory would otherwise pass the shipped test. Moves the file from `specialists/agents/` to `specialists/agents-disabled/` and records the basename in the 0600 store. Returns `{ok, moved}`; `moved:false` means the agent existed only as a bundled template, so nothing was there to move and the store entry is what stops the next provisioning run delivering it. The store is read strictly before anything moves, so an unreadable store 500s with the file untouched rather than rewriting the file whole from an empty set and dropping every other disabled agent. Returns `routingReconciled`, which is `false` when the AGENTS.md reconcile threw: the move and the store write already happened, so the request is not failed, and the caller is told rather than left assuming the prose is correct. Same `accountId` contract as delete. |
-| `POST /api/admin/agents/:slug/enable?accountId=` | Covers both of disable's outcomes. Returns `{ok, restored}`: a quarantined file moves back (`restored:true`); a bundled-only agent has nothing to move, so clearing the store entry is the whole job (`restored:false`), which is what stops provisioning withholding it. Treating that second case as "nothing to restore" made disable a one-way door. 404 only when neither directory nor store knows the agent. Carries the same `routingReconciled` field; the restored file is what puts the routing line back. |
+| `GET /api/admin/agents` | Session-scoped. Lists the session account's public `agents/*/` dirs (never the `admin` agent), its user-created specialists from `plugins/*/agents/*.md`, and its shipped specialists, each row tagged `kind` and `origin` and carrying `risk`, `riskiestTool`, `riskRule`, `riskReason`, `unresolved` and `disabled`. A live-directory candidate whose filename also exists under `plugins/*/agents/` is dropped and counted, so an activated user-created agent is listed once. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped, deduped, riskSurfaceFailed}`. 401 when the session maps to no account. |
+| `GET /api/admin/agents/:slug` | Session-scoped. Without `?plugin=` or `?origin=`, returns a public agent's config fields + four owned docs + a `present` map (a missing or unreadable doc is `''`/`present.<role>=false`, never a 500). With `?plugin=`, that plugin's user-created specialist; with `?origin=shipped`, the shipped one. Both specialist shapes add `{risk, riskiestTool, riskRule, riskReason, unresolved, byTool, disabled}`, where `byTool` is one class per declared tool. Selection is explicit rather than inferred, because a premium file and a user-created specialist under a plugin of the same name produce the same slug. Unknown 404s, 401 as above. |
+| `POST /api/admin/agents/:slug/disable?accountId=` | Agents the operator authored only, enforced here rather than left to the UI: a slug NOT present under `plugins/*/agents/` 404s (`reason=not-user-created`), and the message names suspending the routines as what stops a shipped agent instead. An authored slug with no copy in `specialists/agents/` 409s (`reason=not-dispatchable`): it is already not dispatchable, so there is nothing to move and nothing to record. Otherwise it moves the file from `specialists/agents/` to `specialists/agents-disabled/` and returns `{ok, moved:true}` — the only outcome, since the two other cases refuse. It writes NO store entry: `agents-disabled.json` exists to stop provisioning re-delivering a withheld shipped file, and provisioning never writes the account plugin tree. Returns `routingReconciled`, false when either AGENTS.md pass threw; the move already happened and already stopped dispatch, so the request is not failed and the caller is told rather than left assuming the prose is right. Same `accountId` contract as delete. |
+| `POST /api/admin/agents/:slug/enable?accountId=` | Takes NO authorship check, and that asymmetry with disable is deliberate: an install that switched a shipped agent off under the old gate must still reach this route, or inverting the gate strands it. For an authored slug the quarantined file is the whole state — 404 when it is absent, `restored:true` when it moves back, and the store is never touched. For a shipped slug it covers both of the old disable's outcomes: a quarantined file moves back (`restored:true`), and a bundled-only agent has nothing to move so clearing the store entry is the whole job (`restored:false`), which is what stops provisioning withholding it. 404 only when neither the quarantine directory nor the store knows the slug. The store is read strictly first, because this is the read half of a read-modify-write that rewrites the file whole, and it is written back only when an entry was actually removed — so enabling never creates a store an account did not have. |
 | `DELETE /api/admin/agents/:slug?accountId=` | Public agents only, on the named validated account. Removes the dir after `deleteAgentProjection`; refuses the `admin` slug (403) and a missing/unknown `accountId` (400) with no write. Loud-fail: a graph-cleanup throw aborts the file removal. |
 | `POST /api/admin/agents/:slug/project?accountId=` | Re-projects the named account's on-disk agent into the graph. Same `accountId` contract as delete. |
 
@@ -301,25 +492,40 @@ Agents page survived undiagnosed on a multi-account install.
   does not add up is visible without reproducing anything. The over-exclusion to
   watch for is a `deduped` line naming a file that is also a bundled or premium
   agent: the authored file then hides a genuinely shipped one.
-- `op=classify account=<id8> agent=<name> origin=<shipped|public|specialist>
-  risk=<green|amber|red> riskiestTool=<tool> tools=<n> unresolved=<comma-list|none>
-  disabled=<bool>` — one line per classified agent per listing, so it fires on
-  every page load. `riskiestTool` makes a wrong class diagnosable without
-  re-deriving it. Its value is the FULL canonical tool name, while the card
-  renders only the segment after the plugin prefix. One load
-  showing `riskiest tool: memory-update` on the card and
-  `riskiestTool=mcp__plugin_memory_memory__memory-update` on this line is the
-  confirmation that both derive from one value.
-  **A non-empty `unresolved=` is the one to act on**: the agent
+- `[agents] op=risk account=<id8> slug=<name> origin=<shipped|public|specialist>
+  class=<green|amber|red> rule=<id|none> riskiestTool=<tool> tools=<n>
+  unresolved=<n> unresolvedTools=<comma-list|none> disabled=<bool>` — one line
+  per classified agent per listing, so it fires on every page load.
+  **`rule=` is the field that proves the combination table is live**: a
+  mis-specified rule emits nothing of its own and is otherwise indistinguishable
+  from an absent one. `riskiestTool` makes a wrong class diagnosable without
+  re-deriving it; its value is the FULL canonical tool name and it is no longer
+  rendered anywhere, so this line is where it is read.
+  **A non-zero `unresolved=` is the one to act on**: the agent
   is forced red, and the cause is that the built-in table or the registry
-  mapping has drifted, not that the agent changed.
-- `op=risk-surface status=load-failed reason=<msg>` — the plugin registry did
-  not parse, so every row is forced red and the listing returns
-  `riskSurfaceFailed: true`. Without the forced red, every plugin tool would
-  land in `unresolved` and a registry outage would read as agent drift across
-  every card at once; without the response field, a red row would be
-  indistinguishable from a genuinely dangerous agent, because nothing resolved
-  so `unresolved` is empty and the per-tool explanation cannot fire.
+  mapping has drifted, not that the agent changed. `unresolvedTools=` says which.
+- `[agents] op=rule-census account=<id8> rules=<n> classified=<n> fired=<n>
+  never=<comma-list|none>` — one line per listing, not per agent.
+  **This is the standing check.** A rule that never fires produces no evidence of
+  its own, so nothing except this line would ever say so; a rule id permanently
+  in `never` across every account is dead or wrong. `fired + never` always equals
+  `rules`. Read `never` only when `classified` is non-zero: an account with no
+  specialists puts every rule in `never` and would otherwise be
+  indistinguishable from a table that was never wired. Today `reads-and-sends`
+  sits in `never` on an install whose agents are all shipped, which is expected
+  and not a fault.
+- `op=risk-surface status=load-failed reason=<msg>`, emitted with
+  `[agents] op=risk-surface-failed reason=registry-unreadable detail=<msg>` — the
+  plugin registry did not parse, so every row is forced red and the listing
+  returns `riskSurfaceFailed: true`. Both lines say the same thing; the second is
+  the greppable shape, so one pattern (`\[agents\] op=(risk|rule-census|risk-surface-failed)`)
+  covers the per-agent lines, the census and the outage that forced them. Without
+  the forced red, every plugin tool would land in `unresolved` and a registry
+  outage would read as agent drift across every card at once; without the
+  response field, a red row would be indistinguishable from a genuinely dangerous
+  agent, because nothing resolved so `unresolved` is empty and the per-tool
+  explanation cannot fire. Every row's reason then says the registry is the
+  cause rather than asserting a capability the derivation never produced.
 - `op=disabled-store status=parse-failed reason=<msg>` — the listing then treats
   every agent as enabled, which is what they actually are. A read surface shows
   the true dispatchable set rather than a comforting one.
@@ -712,6 +918,16 @@ authoritative. This section names the surfaces and what backs each.
 > - **Dashboard home** renders on `/` (a greeting, stat cards, a Live-now column,
 >   a Recent artefacts card, and a Channels column), consuming existing endpoints
 >   only.
+> - **Channels card rows.** A WhatsApp row shows a profile picture,
+>   the conversation's name, its last message, and the time, matching the layout
+>   of the WhatsApp client. The name is the one WhatsApp itself holds: a group
+>   shows its group subject, a 1:1 shows the contact name saved on the paired
+>   phone. A group row carries an extra `Group` chip. When no name has been
+>   captured yet, a group falls back to its group id and a 1:1 to its phone
+>   number; neither ever shows a group member's name or the install's own
+>   WhatsApp display name. The existing `Public` chip (the message came from
+>   outside) and `House` / `Client` chip (which account owns the thread) are
+>   unchanged.
 > - **Per-surface header.** Each surface carries its own header (`PageHeader`):
 >   the sidebar collapse toggle, the page title, and a Claude status pill on the
 >   right (Connected / Connect, driven by `/api/health`). The pill replaces the

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

@@ -560,8 +560,12 @@ For estate-agent client work surfaced on the `/tasks` operator page, `work-creat
 
 Two surfaces feed the gate. (1) **Workflow path:** `memory-write` accepts an optional `producedByTaskId` parameter. When set, an inbound `:PRODUCED` edge from that Task is composed into the write's relationships before the gate runs — the typical agent-side pattern is to call `work-create` at the start of an autonomous flow, capture `taskId`, and pass it as `producedByTaskId` on every subsequent `memory-write` for a gated label. The gate verifies Task and write share the same `accountId`; mismatch is rejected loud. (2) **Direct-ask path:** the admin server resolves the active `:AdminConversation`'s `sessionId` UUID and stamps it as `SESSION_NODE_ID` in the spawn env at PTY-spawn time. The same stamp propagates onto specialist subagent spawns the admin dispatches so listing-curator, content-producer, database-operator etc. inherit the same conversation anchor. The `contact-create` and `memory-write` wrappers call `injectConversationProvenance` (exported from [`@maxy/graph-write`](../../../lib/graph-write/src/conversation-provenance.ts)) which MATCHes `(c:Conversation {sessionId, accountId})` — account isolation is part of the natural key, not a separate gate — and prepends the synthetic `:PRODUCED` edge (composed by Neo4j elementId, which the helper reads off the MATCH). No agent-visible schema field changes. `memory-write` uses the env-stamp only as a fallback when `producedByTaskId` is unset; `contact-create` has no `producedByTaskId` parameter today and relies on the env-stamp alone. Autonomous (cron-driven) specialists with no parent conversation legitimately have no env-stamp; those must thread `producedByTaskId`.
 
+A task also carries a **workspace** edge, distinct from the two provenance ones above: `(t:Task)-[:WORKED_ON_IN]->(c:Conversation)` is the session an operator works the task in, written only by the `/tasks` page Session control. `RAISED_DURING` and `PART_OF` say where a task was *raised*, so neither can answer "which chat do I continue this task in" — a task raised in an unrelated conversation would resume that one. At most one such edge exists per task: the control's link route deletes any edge to a different Conversation before merging the new one, which is how a resume the session manager redirected to a live fork re-points itself rather than staying on the dead source. The `:Task` also carries `sessionSpawnRequestedAt`, stamped before the spawn and removed when the link lands, so a session that was created but never linked is countable rather than invisible.
+
 Operator audit cyphers:
 - "What entities did this conversation's actions produce?" — `MATCH (c:AdminConversation {sessionId:$id})<-[:RAISED_DURING]-(t:Task)-[:PRODUCED]->(e) RETURN labels(e), e.name, t.kind, t.status`
+- "Which session is this task worked in?" — `MATCH (t:Task {taskId:$id})-[:WORKED_ON_IN]->(c:Conversation) RETURN c.sessionId, c.name`
+- "Which tasks were marked for a session spawn that never linked?" — `MATCH (t:Task {accountId:$acct}) WHERE t.sessionSpawnRequestedAt IS NOT NULL AND NOT (t)-[:WORKED_ON_IN]->(:Conversation) RETURN t.taskId, t.name, t.sessionSpawnRequestedAt`
 - "What cloudflare resources did this tunnel-login produce?" — `MATCH (t:Task {kind:'cloudflare-tunnel-login', status:'completed'})-[:PRODUCED]->(r) RETURN t.taskId, r.tunnelId, r.hostnameValue ORDER BY t.completedAt DESC`
 
 See `.docs/neo4j.md § Process provenance doctrine` for the full enforcement contract, observability surface, and out-of-scope deferrals.

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

@@ -144,12 +144,22 @@ Every new node in {{productName}}'s graph is created with at least one connectio
 
 Every node also carries a provenance stamp — which agent wrote it, in which session, via which tool. You never see these fields, but they are how operators trace unusual growth back to the code path that produced it, and why your graph stays clean over time.
 
-**Two write surfaces, one substrate.** General agents write through schema-aware helpers — {{productName}} can record a new contact, a new commitment, a new preference without ever typing a database query, and the helper enforces the connection-and-provenance rule above structurally. The graph-steward role (the specialist {{productName}} dispatches when you ask for graph hygiene — "merge those two duplicate contacts," "wire those four tasks to the meeting," "rename the legacy label across the graph") additionally has a raw Cypher write tool for the multi-step operations the helpers cannot express. The steward role internalises the same connection-and-provenance discipline in its prompt; a post-write audit emits a warning on every breach so the same rules apply to both surfaces. Both paths feed the same hourly orphan trend and the same forensic provenance fields — read-side, you cannot tell the two apart, and that is the point.
+**Two write surfaces, one substrate.** General agents write through schema-aware helpers — {{productName}} can record a new contact, a new commitment, a new preference without ever typing a database query, and the helper enforces the connection-and-provenance rule above structurally. The librarian (the specialist {{productName}} dispatches for ingest and graph hygiene — "merge those two duplicate contacts," "wire those four tasks to the meeting," "import this archive") additionally has a raw Cypher write tool, scoped to executing templates other tools emit, for the multi-step operations the helpers cannot express. The steward role internalises the same connection-and-provenance discipline in its prompt; a post-write audit emits a warning on every breach so the same rules apply to both surfaces. Both paths feed the same hourly orphan trend and the same forensic provenance fields — read-side, you cannot tell the two apart, and that is the point.
 
 ## Vertical schemas
 
 On top of the base graph, each brand boots one optional **vertical** — an extra set of entity types tailored to a trade. The vertical is named by `brand.json#vertical` and defined in a `schema-<name>.md` reference; the memory plugin loads it at startup and validates every write against base + the active vertical. Real Agent boots `schema-estate-agent` (Listing, Property, Viewing, Offer). SiteDesk boots `schema-construction`, the canonical JobLogic-derived field-service ontology, which adds the service-delivery entities — `Job`, `Customer`, `Site`, `Asset`, `Visit`, `Quote`, `QuoteLine`, `Valuation`, `VariationNote`, `JobCost`, `Part`, `PurchaseOrder`, `Invoice`, `InboundInvoice`, `PpmContract`, `WhatsAppGroup` (with `Engineer` and `Supplier` as additional labels on `Person`/`Organization`) — grounded in real builder job folders so a job's customer, site, quote, valuations, variations, costs, and received supplier invoices all hang off one `Job` node. The default SiteDesk brand boots no vertical (base graph only).
 
+### Estate agents: a listing needs no photo, a property needs no listing
+
+Two things {{productName}} used to refuse, and no longer does.
+
+**A listing can be recorded before it has a photo.** You take the instruction on Monday and the photographer comes on Thursday. The listing exists as a business fact for those three days, so {{productName}} records it as soon as you tell it about it, with the photo and the live page link added whenever they arrive. The same applies to the link: a property's page does not exist until the site is published.
+
+**A property can be recorded before it has a listing.** A property you have valued, or been asked to appraise, or are holding off-market is a real property. {{productName}} records it as the property itself, with no marketing attached, and the listing hangs off it later — the same property can be listed for sale, withdrawn, and re-listed to let without ever becoming three properties.
+
+Neither gap is forgotten. Once a day {{productName}} counts the listings visible to the public that still have no photo, and the properties that still have no listing, so a gap that should have closed by now can be seen rather than guessed at. If a public listing genuinely has no photo, its property card is shown as text without one rather than with a broken image.
+
 ## Public-facing summaries for customer-readable subjects
 
 Some entities in your graph are knowable by people outside your team — companies you work with, projects you've delivered, the business itself. For those entities ({{productName}} treats `:Organization`, `:Concept`, `:Project`, and `:LocalBusiness` this way), {{productName}} maintains two summaries: a private one only you and your specialist agents see, and a customer-facing public one your public agents are allowed to surface.

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

@@ -6,7 +6,7 @@ The `outlook` plugin gives the admin agent access to Microsoft 365 / Outlook.com
 
 1. **No app to register.** The client ID ships with the brand (`brand.json#outlookClientId`), and the installer stamps it onto the session-manager env, so there is zero operator Azure work. On a brand that ships an empty value the plugin stays inert until its vendor app exists — see `platform/plugins/outlook/references/auth.md` for the one-time-per-brand vendor provisioning runbook (a vendor step, not an operator or end-user step), including setting **Allow public client flows** to Yes.
 2. **Per account: register the Outlook account** — in admin chat, ask the agent to "register my Outlook account". The agent runs `outlook-account-register`, which returns a short user code and the URL `microsoft.com/devicelogin` and relays both to you.
-3. **Consent on any device** — open `microsoft.com/devicelogin` on your phone or laptop, enter the code, sign in to your Microsoft account, and consent to the requested scopes (`offline_access`, `User.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.ReadWrite`, `Contacts.Read`). `Mail.Send` enables sending and `Calendars.ReadWrite` enables calendar control; a mailbox last consented on an older read-only scope set must re-register before send or any calendar write succeeds. Nothing else to do: the server finishes the sign-in automatically once you consent, usually within about half a minute, and the mailbox is then connected.
+3. **Consent on any device** — open `microsoft.com/devicelogin` on your phone or laptop, enter the code, sign in to your Microsoft account, and consent to the requested scopes (`offline_access`, `User.Read`, `Mail.ReadWrite`, `Mail.Send`, `Mail.ReadWrite.Shared`, `Mail.Send.Shared`, `Calendars.ReadWrite`, `Contacts.Read`). `Mail.Send` enables sending, `Calendars.ReadWrite` enables calendar control, and the two `.Shared` scopes let this mailbox reach a shared mailbox it has Full Access to; a mailbox last consented on an older scope set must re-register before send, any calendar write, or any shared mailbox succeeds. Nothing else to do: the server finishes the sign-in automatically once you consent, usually within about half a minute, and the mailbox is then connected.
 4. **Done.** Subsequent tool calls (mail, calendar, contacts) use the persisted refresh token transparently.
 5. **Several mailboxes on one account.** Register again to add a second mailbox; it is stored alongside the first, not in place of it. Every operational tool then takes an optional `mailbox` argument — an email address or graphUserId. With one mailbox, omit it. With two or more, name it; omitting it returns a refusal listing the connected mailboxes. `outlook-mailbox-list` shows every connected mailbox. Only one registration runs at a time per account; starting another while one is live returns an in-progress signal.
 
@@ -33,12 +33,32 @@ The `outlook` plugin gives the admin agent access to Microsoft 365 / Outlook.com
 | `outlook-calendar-freebusy` | Availability for one or more addresses over a window. |
 | `outlook-contacts-list` | Top contacts. Default top=50. |
 | `outlook-mailbox-info` | Health probe for one mailbox — auth state, refresh-window, folder count. Name the mailbox with `mailbox` when several are attached. |
-| `outlook-mailbox-list` | Every connected mailbox with its email, scopes, and token health. Local only — no network — so it also flags a mailbox whose stored credentials cannot be read. |
+| `outlook-mailbox-list` | Every connected mailbox with its email, scopes, and token health, signed-in and shared alike (`kind`, and `via` for a shared one). Local only by default — no network — so it also flags a mailbox whose stored credentials cannot be read. `verify:true` additionally probes each shared mailbox and reports `reachable`. |
+| `outlook-shared-mailbox-add` | Attach a shared mailbox (no sign-in, no licence) through the Full Access of a mailbox that is already connected. `address` is the shared mailbox; `via` names the connected mailbox when more than one is attached. Proves the access before storing anything, so a refusal is the real answer. |
+| `outlook-shared-mailbox-remove` | Detach a shared mailbox. Drops the pointer only; no credential is touched. |
 | `outlook-mail-send` | Send a message. No attachments → `POST /me/sendMail`; with attachments → draft, attach, send (`/me/sendMail` carries attachments inline and cannot fit a large file). to/cc/bcc arrays, subject, body, isHtml, attachments (account-dir paths, 25 MB/file). Success asserted on Graph 202; no message id on either route. Needs `Mail.Send` (+ `Mail.ReadWrite` to attach). |
 | `outlook-draft` | Create a draft in Drafts, either a new message or a threaded reply. Returns the draft id; never sends. Attachments are attached before the id is returned, so the draft is ready to send. Needs `Mail.ReadWrite`. **New message** (no `replyToMessageId`): `POST /me/messages`, requires `to` + `subject`, same body model as `outlook-mail-send`, threads under nothing. **Threaded reply** (`replyToMessageId` = the id of the message being answered): `POST /me/messages/{id}/createReply` — the draft carries the parent's conversationId, so it lands under the original. This is the only way to draft a reply without sending it: `outlook-mail-reply` threads but always sends. Graph sets the recipients and `RE:` subject from the original and composes the body above its own quote, matching what `outlook-mail-reply` sends, so the threaded path is **plain text only** — `to`, `subject`, and `isHtml: true` are **refused** (not ignored) when replying. `replyAll` includes everyone on the original; `cc`/`bcc` add recipients. |
 | `outlook-draft-edit` | Update an existing draft in place (`PATCH /me/messages/{draftId}`) and/or add and remove attachments. Graph drafts are mutable — pass draftId plus the fields to change (to/cc/bcc/subject/body/isHtml/attachments/removeAttachments). `attachments` adds; `removeAttachments` takes files off by name or attachment id; both together replace a file in one call. Sent messages cannot be edited. Needs `Mail.ReadWrite`. |
 | `outlook-draft-send` | Send an existing draft by id (`POST /me/messages/{id}/send`). Graph consumes the draft, returns 202. Needs `Mail.Send`. |
 
+## Shared mailboxes
+
+A shared mailbox (`team@`, `info@`, `accounts@`) has no sign-in of its own, so nobody can connect it the way a normal mailbox is connected. **It does not need a licence and should never be given one for this.** Whoever has Full Access to it connects their own mailbox in the normal way, then attaches the shared one to it:
+
+```
+outlook-shared-mailbox-add address=team@yourcompany.com
+```
+
+Add `via=<your address>` if this account has more than one mailbox connected. From then on the shared address works as the `mailbox` argument on any mail tool, and `outlook-mailbox-list` shows it as `kind:delegated`.
+
+The attach call checks the access before it stores anything, so what it says back is the real state of things:
+
+- **"does not have Full Access"** — the delegation is missing. Grant it in the Microsoft 365 admin centre: Teams & groups → Shared mailboxes → the mailbox → Members / Read and manage. Nothing is purchased.
+- **"no mailbox with this address in the tenant"** — the address is wrong, or it is a distribution list. A distribution list has no mailbox and cannot be attached.
+- **"connected without the Mail.ReadWrite.Shared scope"** — your mailbox was connected before the plugin asked for the shared scopes. Register it again and it will work.
+
+Mail only: calendar and contacts tools refuse on a shared mailbox and say so. If a shared mailbox stops answering, the delegation was probably removed in Exchange — `outlook-mailbox-list verify:true` reports which ones are still reachable.
+
 ## Drafting to a Contact
 
 When the admin agent drafts or sends a message to a known contact, it reads that contact's record first and applies any routing the record carries, for example a preferred send-to address, showing the result for your approval before anything is sent.
@@ -58,7 +78,10 @@ All log lines start with `[outlook-mcp]` and write to `server.log`. They are key
 | /me failed post-token | `me-failed account=<id> status=<N>` |
 | Auth ok | `auth-ok account=<id> graphUserId=<id> mail=<addr> scopes=<csv> tokenExpSec=<N>` |
 | Registration already in flight | `register-in-progress account=<id>` (start refused; one device-code flow at a time) |
-| Credential resolve | `cred-resolve account=<id> mailbox=<id-or-empty> source=arg|sole|none|refused` — names the resolved mailbox and how it was chosen; `source=refused` is the ambiguity/not-found refusal |
+| Credential resolve | `cred-resolve account=<id> mailbox=<id-or-empty> source=arg|sole|none|refused kind=signed-in|delegated via=<delegator-or-empty>` — names the resolved mailbox and how it was chosen; `source=refused` is the ambiguity/not-found refusal, and `kind=delegated` means the call ran against a shared mailbox through `via` |
+| Shared mailbox attached | `shared-add account=<id> address=<addr> via=<key> outcome=ok|ok-reattached|no-scope|forbidden|not-found` — every refusal path is named, so a failed attach is diagnosable without reproducing it |
+| Shared mailbox detached | `shared-remove account=<id> address=<addr> outcome=ok|absent` |
+| Calendar/contacts on a shared mailbox | `shared-tool-refused account=<id> tool=<tool> prefix=<users-path>` — refused before any request is built |
 | Token refreshed | `token-refreshed account=<id> oldExpSec=<N> newExpSec=<N>` |
 | Refresh failed | `token-refresh-failed account=<id> reason=<err>` (terminal) |
 | Mail list | `mail-list op=resolve account=<id> folderIn=<name> folderResolved=<token> asRawId=<bool> count=<N> elapsedMs=<N>` (on error, `error=<msg>` replaces `count`) |
@@ -76,7 +99,7 @@ All log lines start with `[outlook-mcp]` and write to `server.log`. They are key
 | Scope insufficient | `scope-insufficient tool=<t> account=<id> missing=Calendars.ReadWrite` (stale read-only consent) |
 | Contacts list | `contacts-list account=<id> count=<N> elapsedMs=<N>` |
 | Mailbox info | `mailbox-info account=<id> tokenWithinRefreshWindow=<bool> folderCount=<N>` |
-| Mailbox list | `mailbox-list account=<id> count=<N> unreadable=<N>` (unreadable>0 flags an orphaned or corrupt mailbox store) |
+| Mailbox list | `mailbox-list account=<id> count=<N> unreadable=<N> addressable=<N> delegated=<N> verified=<N>` — `count` covers signed-in plus delegated entries, `addressable` counts only signed-in ones that are usable by their email, `delegated` counts the attached shared mailboxes, and `verified` is how many of those were probed (0 unless `verify:true`). `unreadable>0` flags an orphaned or corrupt mailbox store |
 | Graph error | `graph-error account=<id> status=<N> code=<graphErrorCode> retryAfterMs=<N-or-null>` — writes flow through the same `callGraph` loop, so a failed write logs `graph-error` too |
 | On-prem rejected | `on-prem-rejected account=<id> mailServer=<host>` (terminal) |
 | Scope insufficient | `scope-insufficient account=<id> tool=<t> missing=Mail.Send` (terminal — re-register to grant send) |

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

@@ -1,6 +1,6 @@
 {
   "name": "graph",
-  "description": "Raw Neo4j Cypher proxy. Wraps the upstream `mcp-neo4j-cypher` server (spawned under uvx by `platform/lib/graph-mcp`) under the stable `maxy-graph` namespace, so its tools register as `maxy-graph-read_neo4j_cypher`, `maxy-graph-get_neo4j_schema`, and `maxy-graph-write_neo4j_cypher`. The read and schema tools are admin-allowlisted for schema checks and read-only queries; the write tool is specialist-only (database-operator / librarian execute operator-confirmed `mergeCypher` templates through it, never hand-authored Cypher). The shim validates write Cypher against the live schema, stamps provenance, and rejects unknown labels/edges. Account isolation is per-brand Neo4j; the shim adds no query-layer tenant filter.",
+  "description": "Raw Neo4j Cypher proxy. Wraps the upstream `mcp-neo4j-cypher` server (spawned under uvx by `platform/lib/graph-mcp`) under the stable `maxy-graph` namespace, so its tools register as `maxy-graph-read_neo4j_cypher`, `maxy-graph-get_neo4j_schema`, and `maxy-graph-write_neo4j_cypher`. The read and schema tools are admin-allowlisted for schema checks and read-only queries; the write tool is specialist-only: the `librarian` executes operator-confirmed `mergeCypher` templates through it, never hand-authored Cypher. `database-operator` does not hold it: that specialist is scoped to the wrapped writers and stays narrow. The shim validates write Cypher against the live schema, stamps provenance, and rejects unknown labels/edges. Account isolation is per-brand Neo4j; the shim adds no query-layer tenant filter.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

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

@@ -27,7 +27,7 @@ mcp:
     SESSION_ID: ${SESSION_ID}
     NEO4J_URI: ${NEO4J_URI}
     NEO4J_PASSWORD: ${NEO4J_PASSWORD}
-description: "Raw Neo4j Cypher proxy. Wraps the upstream `mcp-neo4j-cypher` server (spawned under uvx by `platform/lib/graph-mcp`) under the stable `maxy-graph` namespace, so its tools register as `maxy-graph-read_neo4j_cypher`, `maxy-graph-get_neo4j_schema`, and `maxy-graph-write_neo4j_cypher`. The read and schema tools are admin-allowlisted for schema checks and read-only queries; the write tool is specialist-only (database-operator / librarian execute operator-confirmed `mergeCypher` templates through it, never hand-authored Cypher). The shim validates write Cypher against the live schema, stamps provenance, and rejects unknown labels/edges. Account isolation is per-brand Neo4j; the shim adds no query-layer tenant filter."
+description: "Raw Neo4j Cypher proxy. Wraps the upstream `mcp-neo4j-cypher` server (spawned under uvx by `platform/lib/graph-mcp`) under the stable `maxy-graph` namespace, so its tools register as `maxy-graph-read_neo4j_cypher`, `maxy-graph-get_neo4j_schema`, and `maxy-graph-write_neo4j_cypher`. The read and schema tools are admin-allowlisted for schema checks and read-only queries; the write tool is specialist-only: the `librarian` executes operator-confirmed `mergeCypher` templates through it, never hand-authored Cypher. `database-operator` does not hold it: that specialist is scoped to the wrapped writers and stays narrow. The shim validates write Cypher against the live schema, stamps provenance, and rejects unknown labels/edges. Account isolation is per-brand Neo4j; the shim adds no query-layer tenant filter."
 ---
 
 # graph

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

@@ -33,7 +33,7 @@ tools:
     riskClass: write_local
   - name: kd-classify
     publicAllowlist: false
-    adminAllowlist: false
+    adminAllowlist: true
     riskClass: write_local
   - name: memory-ingest-extract
     publicAllowlist: false