@rubytech/create-sitedesk-code 0.1.506 → 0.1.508

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what SiteDesk ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:6333dcde1f052035148393349684b0d1311a2f645c990066c96672c5fa61c1ce
+content-hash: sha256:b15d0e491d957f75523ecf7056f8004bafcdf448767c0c3dd64b40a73926b58b
 brand: sitedesk-code
 product-name: SiteDesk
 ---
@@ -474,6 +474,32 @@ Skill content, plugin manifests, agent templates, and reference files reference
 
 The runtime substitution happens at every read site that flows content into a system prompt or operator-visible UI: the admin agent's `plugin-read` tool (references + `PLUGIN.md`), the `skill-load` tool (SKILL.md by skill name — one-call resolver+reader, the canonical primitive for SKILL.md), the public agent's recursive plugin assembly, and `IDENTITY` / `SOUL` / `AGENTS` / `KNOWLEDGE` markdown reads. Missing or empty `productName` hard-fails — there is no fallback to a default brand string. See [.docs/agents.md](../../.docs/agents.md) § "Brand templating" for the full contract.
 
+## Tool risk classes (for plugin authors)
+
+Every tool a plugin declares in its `PLUGIN.md` `tools:` block carries three mandatory
+fields. `publicAllowlist` and `adminAllowlist` say who may call the tool. `riskClass`
+says what happens when they do, and takes one of four values:
+
+- `read` changes no state anywhere. A remote lookup counts as `read`; reaching the
+  network is not by itself consequential.
+- `write_local` mutates account files or the graph on this device and transmits nothing.
+- `exec` runs an operating-system command, or code supplied by the caller or the operator.
+- `external` transmits to, or changes state on, a system outside this device, or delivers
+  a message to a person.
+
+Leaving the field out is a refusal-to-boot condition, not a silent default. The platform
+refuses to start rather than treat an undeclared consequence as harmless, because a tool
+that quietly reads as `read` escapes every check downstream of it.
+
+Declaring the class does not yet gate anything. It gives any consumer one honest answer
+to the question "is this tool consequential?" without maintaining a list of tool names,
+which is what the checks in `platform/plugins/admin/hooks/` have had to do until now.
+
+A publish-time gate flags declarations that contradict what the tool's own name says it
+does, and a boot line reports the census across all four classes. The classification
+rule, the exception mechanism, and the diagnostic commands are in
+`.docs/tool-risk-classes.md`.
+
 ## MCP Plugin Observability (for plugin authors)
 
 Every `console.error` line from a plugin's MCP server is captured to a per-server raw log. Capture is automatic and needs no import or call: the `mcp-spawn-tee` shim spawns every MCP server and mirrors its stderr to `mcp-<name>-<sessionId>.log` (or `mcp-<name>-nosession.log` for a spawn with no session). That file is keyed by session, which is the conversation, and that is where you grep. Prefix your diagnostics `[your-tool]` so a grep isolates one tool.
@@ -3078,8 +3104,11 @@ not-found|rm-error>`.
 
 ### Agents
 
-The Agents surface (`/agents`) is the admin view of the account's agents, of two
-kinds, each card tagged `Public` or `Specialist`:
+The Agents surface (`/agents`) is the admin view of the account's agents. Each
+card is tagged by **origin**, which says who put the agent there and therefore
+what the operator may do with it. Origin is a different question to `kind`, which
+says what shape the agent is: a shipped specialist and a user-created one are
+both `kind: 'specialist'` and differ only by origin.
 
 - **Public agents** — the per-agent directories under `<accountDir>/agents/<slug>/`,
   each carrying a `config.json` (`displayName`, `status`, `model`,
@@ -3090,19 +3119,63 @@ kinds, each card tagged `Public` or `Specialist`:
   to the public URL (computed client-side: an `admin.` host maps to the `public.`
   host), plus a **delete** behind a confirm that runs the loud-fail `DELETE`
   (graph projection cleanup precedes file removal).
-- **User-created specialists** — the agent files under
+- **User-created specialists** (`origin: 'specialist'`) — the agent files under
   `<accountDir>/plugins/<plugin>/agents/<plugin>--<name>.md` (written by
-  `agent-builder`). `<accountDir>/plugins` is the user-created tree, so only
-  user-created specialists list here; shipped premium and core specialists (whose
-  plugins live under `PLATFORM_ROOT`) do not. 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.
+  `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.
+- **Shipped specialists** (`origin: 'shipped'`) — the union of
+  `<accountDir>/specialists/agents/`, `<accountDir>/specialists/agents-disabled/`
+  and `PLATFORM_ROOT/templates/specialists/agents/`, in that precedence order.
+  `sidebar-artefacts.ts` reads the same union minus the quarantine directory, so
+  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.
 
 The former "Public" flyout toggle in the account menu was removed; this page is
 the sole agent surface.
 
+**Risk class.** Every classified card carries a green/amber/red badge derived
+from the agent's declared `tools:` line: green when every tool is `read`, amber
+when the worst is `write_local`, red on any `exec` or `external`, and red when
+any tool resolves to no class at all. Resolution has two sources, because
+frontmatter names tools in Claude Code's namespace: a plugin tool is a direct
+lookup in `ToolSurface.riskByTool`, which is keyed by the same
+canonical `mcp__plugin_<p>_<p>__<tool>` string frontmatter writes, and the
+eleven built-ins carry their own table in `server/lib/agent-risk.ts`. An empty
+tool list is red: no `tools:` line means the full surface, not none of it.
+
+A public agent carries `risk: null` and shows no badge. Its tool surface
+resolves through `ADMIN_CORE_TOOLS` plus the plugin allowlists rather than a
+`tools:` line, and classifying its empty list would paint every public agent red
+on a premise nothing established.
+
+The detail modal renders one chip per declared tool carrying **that tool's own**
+class, so a `read` tool inside a red agent still reads as harmless; a tool with
+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.
+
+**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.
+
 **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
@@ -3116,8 +3189,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) plus its user-created specialists from `plugins/*/agents/*.md`, each row tagged `kind`. Returns `{agents, accountId, skipped, specialistsSkipped}` — `accountId` names the account resolved (the client sends it back on a delete); `skipped` counts public dirs whose `config.json` failed to parse; `specialistsSkipped` counts specialist `.md` files with no parseable `name`. 401 when the session maps to no account. |
-| `GET /api/admin/agents/:slug` | Session-scoped. Without `?plugin=`, 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=`, returns that plugin's specialist `{kind, model, tools, systemPrompt, skills}`. Unknown 404s, 401 as above. |
+| `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`, `worstTool`, `unresolved` and `disabled`. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped}`. 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, worstTool, 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. 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. 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. |
 | `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. |
 
@@ -3144,6 +3219,35 @@ Agents page survived undiagnosed on a multi-account install.
 - `op=delete accountId=<id8> slug=<…> outcome=<ok|failed>` with
   `reason=<graph-cleanup-failed|rm-error>` on failure (files preserved on a
   graph-cleanup throw).
+- `op=classify account=<id8> agent=<name> origin=<shipped|public|specialist>
+  risk=<green|amber|red> worstTool=<tool> tools=<n> unresolved=<comma-list|none>
+  disabled=<bool>` — one line per classified agent per listing, so it fires on
+  every page load. `worstTool` makes a wrong class diagnosable without
+  re-deriving it. **A non-empty `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.
+- `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.
+- `op=<disable|enable> accountId=<id8> slug=<…> outcome=<ok|failed>`, with
+  `moved=<bool>` on disable and `reason=nothing-quarantined` on a failed enable.
+
+**Disable is a no-event failure, so it needs a standing check.** If the store
+names an agent whose file is still in `specialists/agents/`, nothing throws, the
+card reads disabled, and the agent keeps being dispatched. The five-minute
+`account-dir-schema-reconcile` pass reports it as
+`[fs-reconcile] op=agent-parity account=<id8> disabled=<n> stillOnDisk=<list>`,
+fired only on disagreement. The per-cycle heartbeat is `agent-drift=0` on that
+pass's summary line, which is what makes the absence of a per-account line
+readable as "clean" rather than "never audited" — grep the summary line, not the
+per-account one, to confirm the check is running.
 
 ### Graph
 
@@ -3277,9 +3381,29 @@ the Web Share API and is disabled where unavailable. Signals:
 `[data-ui] op=mount header=operator home=absent`, `op=select-enter`,
 `op=select-exit reason=<cancel|action>`, `op=share supported=<bool> count=<n>`.
 
+**The dashboard has a surface ramp and a display type tier.** Every page sits on
+a page plane, cards rise onto a raised plane, and inputs and scroll regions
+recede onto an inset plane. Each brand chooses how the card separates: SiteDesk's
+card is a shade lighter than its page and casts no shadow, Real Agent's card and
+page are both white and a shadow does the work. The page header is an inverted
+band carrying the page title at the display size. Colours, radii, shadows and
+type weights all come from the brand's own tokens; nothing is hardcoded, and a
+token that resolves to nothing fails the build rather than painting invisibly.
+
+**Folders open beside a rail on a wide screen.** At 1280px and above the folder
+view splits in two: a list of the account's folders on the left, the files on
+the right, with the folder you are in highlighted. Below that width the rail is
+hidden and the breadcrumb does the same job.
+
+**Status colours are shared.** Success, warning, error and info each carry a
+solid fill, a pale tint and a text colour for that tint. Every pairing meets the
+WCAG AA contrast minimum, on every brand.
+
 **`/data` opens on the account's own folders, as cards.** With no `#path=` in
 the URL the browser lands on **home**: the account's business folders (the
-entity folders of its trade, plus `projects`, `contacts` and `documents`) shown
+entity folders of its trade, plus documents, projects, contacts, the work it
+has produced for you, anything a client has sent in, and any websites it
+has published) shown
 one per card, each listing the first 20 things inside it and a `+N more` row
 past that. Tapping a card opens that folder in the ordinary list or grid. There
 are never loose files at this level. Everything the platform and its plugins

package/payload/platform/plugins/admin/skills/whats-new/SKILL.md

@@ -9,6 +9,20 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-07-25 (0.1.508)
+
+- SiteDesk's screens now use a single, cleaner typeface throughout, and the old olive-green colour is gone.
+- You can now disable an agent from the Agents page, and each one shows its risk level.
+- Dashboard sections appear as soon as each one loads, instead of the whole page waiting on the slowest one.
+- Real Agent's icons and imagery were redrawn to match its colour palette.
+
+## 2026-07-25 (0.1.507)
+
+- Chat now updates the moment a message or permission prompt arrives, instead of checking every couple of seconds.
+- The dashboard has a visual refresh: cards now fill in properly instead of looking transparent.
+- The Data page has a new two-pane view with a folder rail on wider screens, and uploads/sites are now correctly grouped under Home.
+- Every assistant tool now carries a declared risk level, checked automatically so it cannot silently drift.
+
 ## 2026-07-25 (0.1.506)
 
 - Fixed a bug where the Agents page and a few other admin screens could resolve the wrong account.

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

@@ -5,12 +5,15 @@ tools:
   - name: aeo-emit-jsonld
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: write_local
   - name: aeo-write-llms-txt
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: write_local
   - name: aeo-audit-page
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: write_local
 skills:
   - skills/structured-answer/SKILL.md
 always: false

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

@@ -5,57 +5,75 @@ tools:
   - name: browser-render
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
   - name: browser-navigate
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
   - name: browser-snapshot
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
   - name: browser-click
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: external
   - name: browser-fill
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: external
   - name: browser-fill-form
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: external
   - name: browser-type
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: external
   - name: browser-press-key
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: external
   - name: browser-hover
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
   - name: browser-select-option
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: external
   - name: browser-wait-for
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
   - name: browser-handle-dialog
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: external
   - name: browser-evaluate
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: exec
   - name: browser-console-messages
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
   - name: browser-tabs
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
   - name: browser-pdf-save
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: write_local
   - name: browser-screenshot
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: write_local
   - name: browser-resize
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
 always: true
 embed: false
 metadata: {"platform":{}}

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

@@ -5,15 +5,19 @@ tools:
   - name: connector-register
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: write_local
   - name: connector-call
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: external
   - name: connector-list
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: read
   - name: connector-deregister
     publicAllowlist: false
     adminAllowlist: true
+    riskClass: write_local
 metadata: {"platform":{"optional":true,"pluginKey":"connector"}}
 mcp:
   command: node

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

@@ -5,30 +5,39 @@ tools:
   - name: contact-create
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: write_local
   - name: contact-lookup
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: read
   - name: contact-update
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: write_local
   - name: contact-delete
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: write_local
   - name: contact-list
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: read
   - name: contact-export
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: write_local
   - name: contact-erase
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: write_local
   - name: group-create
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: write_local
   - name: group-manage
     publicAllowlist: false
     adminAllowlist: false
+    riskClass: write_local
 always: false
 embed: false
 metadata: {"platform":{}}

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

@@ -151,8 +151,11 @@ not-found|rm-error>`.
 
 ### Agents
 
-The Agents surface (`/agents`) is the admin view of the account's agents, of two
-kinds, each card tagged `Public` or `Specialist`:
+The Agents surface (`/agents`) is the admin view of the account's agents. Each
+card is tagged by **origin**, which says who put the agent there and therefore
+what the operator may do with it. Origin is a different question to `kind`, which
+says what shape the agent is: a shipped specialist and a user-created one are
+both `kind: 'specialist'` and differ only by origin.
 
 - **Public agents** — the per-agent directories under `<accountDir>/agents/<slug>/`,
   each carrying a `config.json` (`displayName`, `status`, `model`,
@@ -163,19 +166,63 @@ kinds, each card tagged `Public` or `Specialist`:
   to the public URL (computed client-side: an `admin.` host maps to the `public.`
   host), plus a **delete** behind a confirm that runs the loud-fail `DELETE`
   (graph projection cleanup precedes file removal).
-- **User-created specialists** — the agent files under
+- **User-created specialists** (`origin: 'specialist'`) — the agent files under
   `<accountDir>/plugins/<plugin>/agents/<plugin>--<name>.md` (written by
-  `agent-builder`). `<accountDir>/plugins` is the user-created tree, so only
-  user-created specialists list here; shipped premium and core specialists (whose
-  plugins live under `PLATFORM_ROOT`) do not. 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.
+  `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.
+- **Shipped specialists** (`origin: 'shipped'`) — the union of
+  `<accountDir>/specialists/agents/`, `<accountDir>/specialists/agents-disabled/`
+  and `PLATFORM_ROOT/templates/specialists/agents/`, in that precedence order.
+  `sidebar-artefacts.ts` reads the same union minus the quarantine directory, so
+  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.
 
 The former "Public" flyout toggle in the account menu was removed; this page is
 the sole agent surface.
 
+**Risk class.** Every classified card carries a green/amber/red badge derived
+from the agent's declared `tools:` line: green when every tool is `read`, amber
+when the worst is `write_local`, red on any `exec` or `external`, and red when
+any tool resolves to no class at all. Resolution has two sources, because
+frontmatter names tools in Claude Code's namespace: a plugin tool is a direct
+lookup in `ToolSurface.riskByTool`, which is keyed by the same
+canonical `mcp__plugin_<p>_<p>__<tool>` string frontmatter writes, and the
+eleven built-ins carry their own table in `server/lib/agent-risk.ts`. An empty
+tool list is red: no `tools:` line means the full surface, not none of it.
+
+A public agent carries `risk: null` and shows no badge. Its tool surface
+resolves through `ADMIN_CORE_TOOLS` plus the plugin allowlists rather than a
+`tools:` line, and classifying its empty list would paint every public agent red
+on a premise nothing established.
+
+The detail modal renders one chip per declared tool carrying **that tool's own**
+class, so a `read` tool inside a red agent still reads as harmless; a tool with
+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.
+
+**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.
+
 **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
@@ -189,8 +236,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) plus its user-created specialists from `plugins/*/agents/*.md`, each row tagged `kind`. Returns `{agents, accountId, skipped, specialistsSkipped}` — `accountId` names the account resolved (the client sends it back on a delete); `skipped` counts public dirs whose `config.json` failed to parse; `specialistsSkipped` counts specialist `.md` files with no parseable `name`. 401 when the session maps to no account. |
-| `GET /api/admin/agents/:slug` | Session-scoped. Without `?plugin=`, 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=`, returns that plugin's specialist `{kind, model, tools, systemPrompt, skills}`. Unknown 404s, 401 as above. |
+| `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`, `worstTool`, `unresolved` and `disabled`. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped}`. 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, worstTool, 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. 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. 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. |
 | `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. |
 
@@ -217,6 +266,35 @@ Agents page survived undiagnosed on a multi-account install.
 - `op=delete accountId=<id8> slug=<…> outcome=<ok|failed>` with
   `reason=<graph-cleanup-failed|rm-error>` on failure (files preserved on a
   graph-cleanup throw).
+- `op=classify account=<id8> agent=<name> origin=<shipped|public|specialist>
+  risk=<green|amber|red> worstTool=<tool> tools=<n> unresolved=<comma-list|none>
+  disabled=<bool>` — one line per classified agent per listing, so it fires on
+  every page load. `worstTool` makes a wrong class diagnosable without
+  re-deriving it. **A non-empty `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.
+- `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.
+- `op=<disable|enable> accountId=<id8> slug=<…> outcome=<ok|failed>`, with
+  `moved=<bool>` on disable and `reason=nothing-quarantined` on a failed enable.
+
+**Disable is a no-event failure, so it needs a standing check.** If the store
+names an agent whose file is still in `specialists/agents/`, nothing throws, the
+card reads disabled, and the agent keeps being dispatched. The five-minute
+`account-dir-schema-reconcile` pass reports it as
+`[fs-reconcile] op=agent-parity account=<id8> disabled=<n> stillOnDisk=<list>`,
+fired only on disagreement. The per-cycle heartbeat is `agent-drift=0` on that
+pass's summary line, which is what makes the absence of a per-account line
+readable as "clean" rather than "never audited" — grep the summary line, not the
+per-account one, to confirm the check is running.
 
 ### Graph
 
@@ -350,9 +428,29 @@ the Web Share API and is disabled where unavailable. Signals:
 `[data-ui] op=mount header=operator home=absent`, `op=select-enter`,
 `op=select-exit reason=<cancel|action>`, `op=share supported=<bool> count=<n>`.
 
+**The dashboard has a surface ramp and a display type tier.** Every page sits on
+a page plane, cards rise onto a raised plane, and inputs and scroll regions
+recede onto an inset plane. Each brand chooses how the card separates: SiteDesk's
+card is a shade lighter than its page and casts no shadow, Real Agent's card and
+page are both white and a shadow does the work. The page header is an inverted
+band carrying the page title at the display size. Colours, radii, shadows and
+type weights all come from the brand's own tokens; nothing is hardcoded, and a
+token that resolves to nothing fails the build rather than painting invisibly.
+
+**Folders open beside a rail on a wide screen.** At 1280px and above the folder
+view splits in two: a list of the account's folders on the left, the files on
+the right, with the folder you are in highlighted. Below that width the rail is
+hidden and the breadcrumb does the same job.
+
+**Status colours are shared.** Success, warning, error and info each carry a
+solid fill, a pale tint and a text colour for that tint. Every pairing meets the
+WCAG AA contrast minimum, on every brand.
+
 **`/data` opens on the account's own folders, as cards.** With no `#path=` in
 the URL the browser lands on **home**: the account's business folders (the
-entity folders of its trade, plus `projects`, `contacts` and `documents`) shown
+entity folders of its trade, plus documents, projects, contacts, the work it
+has produced for you, anything a client has sent in, and any websites it
+has published) shown
 one per card, each listing the first 20 things inside it and a `+N more` row
 past that. Tapping a card opens that folder in the ordinary list or grid. There
 are never loose files at this level. Everything the platform and its plugins

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

@@ -150,6 +150,32 @@ Skill content, plugin manifests, agent templates, and reference files reference
 
 The runtime substitution happens at every read site that flows content into a system prompt or operator-visible UI: the admin agent's `plugin-read` tool (references + `PLUGIN.md`), the `skill-load` tool (SKILL.md by skill name — one-call resolver+reader, the canonical primitive for SKILL.md), the public agent's recursive plugin assembly, and `IDENTITY` / `SOUL` / `AGENTS` / `KNOWLEDGE` markdown reads. Missing or empty `productName` hard-fails — there is no fallback to a default brand string. See [.docs/agents.md](../../.docs/agents.md) § "Brand templating" for the full contract.
 
+## Tool risk classes (for plugin authors)
+
+Every tool a plugin declares in its `PLUGIN.md` `tools:` block carries three mandatory
+fields. `publicAllowlist` and `adminAllowlist` say who may call the tool. `riskClass`
+says what happens when they do, and takes one of four values:
+
+- `read` changes no state anywhere. A remote lookup counts as `read`; reaching the
+  network is not by itself consequential.
+- `write_local` mutates account files or the graph on this device and transmits nothing.
+- `exec` runs an operating-system command, or code supplied by the caller or the operator.
+- `external` transmits to, or changes state on, a system outside this device, or delivers
+  a message to a person.
+
+Leaving the field out is a refusal-to-boot condition, not a silent default. The platform
+refuses to start rather than treat an undeclared consequence as harmless, because a tool
+that quietly reads as `read` escapes every check downstream of it.
+
+Declaring the class does not yet gate anything. It gives any consumer one honest answer
+to the question "is this tool consequential?" without maintaining a list of tool names,
+which is what the checks in `platform/plugins/admin/hooks/` have had to do until now.
+
+A publish-time gate flags declarations that contradict what the tool's own name says it
+does, and a boot line reports the census across all four classes. The classification
+rule, the exception mechanism, and the diagnostic commands are in
+`.docs/tool-risk-classes.md`.
+
 ## MCP Plugin Observability (for plugin authors)
 
 Every `console.error` line from a plugin's MCP server is captured to a per-server raw log. Capture is automatic and needs no import or call: the `mcp-spawn-tee` shim spawns every MCP server and mirrors its stderr to `mcp-<name>-<sessionId>.log` (or `mcp-<name>-nosession.log` for a spawn with no session). That file is keyed by session, which is the conversation, and that is where you grep. Prefix your diagnostics `[your-tool]` so a grep isolates one tool.