@rubytech/create-sitedesk-code 0.1.522 → 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.

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/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

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

@@ -882,8 +882,13 @@ if (!readOnly) {
             .string()
             .optional()
             .describe("Active Task elementId for autonomous-workflow writes. When set, an inbound :PRODUCED edge from this Task is composed into relationships before the write. Task must share the same accountId; mismatch is rejected. Omit for direct conversation asks — the platform composes the edge from the active conversation instead."),
+        mergeOn: z
+            .array(z.string())
+            .min(1)
+            .optional()
+            .describe("Natural-key properties for an idempotent write. When set, the node and its relationships MERGE on accountId plus these properties, so re-writing the same row updates it in place instead of creating a duplicate. Every named property must also appear in `properties`; accountId is always part of the key and must not be named here. Omit for a plain create."),
         targetAccountId: z.string().optional().describe(XACCT_DESC),
-    }, async ({ labels, properties, scope, relationships, producedByTaskId, targetAccountId }) => {
+    }, async ({ labels, properties, scope, relationships, producedByTaskId, mergeOn, targetAccountId }) => {
         const scoped = resolveToolAccount("memory-write", targetAccountId);
         if ("reject" in scoped)
             return scoped.reject;
@@ -902,6 +907,7 @@ if (!readOnly) {
                 },
                 validator,
                 producedByTaskId,
+                mergeOn,
             });
             return {
                 content: [
@@ -2635,14 +2641,15 @@ lifelineTool(server, "image-fetch", [
 // ===================================================================
 // Report MCP tools (Task 332) are registered earlier in this file.
 // Dream-run calls the same writer in-process for the per-run :Report.
-lifelineTool(server, "memory-dream-run", "Operator-initiated dream-cycle: graph-hygiene sweep across seven phases " +
+lifelineTool(server, "memory-dream-run", "Operator-initiated dream-cycle: graph-hygiene sweep across eight phases " +
     "(orphan detection, stale compiled-truth, edges to :Trashed targets, citation audit on :TimelineEvent, " +
-    "prune compiled-truth revisions, materialise :BACKLINKS edges, tag normalisation). " +
+    "prune compiled-truth revisions, materialise :BACKLINKS edges, tag normalisation, estate-agent census). " +
     "Writes a :Report node at the end. Failure of any phase logs and continues. " +
     "Pass phases=[4] to run only the citation audit (e.g. after a bulk ingest), phases=[5] for revision prune only, " +
-    "or phases=[6,7] for backlink/tag maintenance only.", {
+    "phases=[6,7] for backlink/tag maintenance only, or phases=[8] for the estate-agent census alone " +
+    "(public listings with no image, properties with no listing; skips on non-estate accounts).", {
     operatorId: z.string().optional().describe("Identifier of the operator who triggered the run; appears in the report and log line."),
-    phases: z.array(z.number().int().min(1).max(7)).optional().describe("Subset of phases to run. Default [1,2,3,4,5,6,7]. Order is fixed."),
+    phases: z.array(z.number().int().min(1).max(8)).optional().describe("Subset of phases to run. Default [1,2,3,4,5,6,7,8]. Order is fixed."),
     maxEventsPerRun: z.number().int().positive().optional().describe("Phase 4 cap on :TimelineEvent rows scanned per run. Default 200."),
     targetAccountId: z.string().optional().describe(XACCT_DESC),
 }, async ({ operatorId, phases, maxEventsPerRun, targetAccountId }) => {