@ryuhq/sdk 0.0.5 → 0.1.2

package/src/generated/plugin-manifest.ts

@@ -11,6 +11,36 @@
  *  manifest types change).
  */
 
+/**
+ * One selectable option for a [`SettingsFieldType::Select`] field.
+ *
+ * Accepts both spellings the desktop's `parseOptions` accepts: a bare string
+ * (value and label are the same) or an object with an explicit `label`. Keeping
+ * both is not indulgence — the bare-string form is what every hand-written
+ * manifest reaches for, and rejecting it would push authors into boilerplate for
+ * the common case.
+ */
+export type SettingsFieldOption =
+	| string
+	| {
+			/**
+			 * Display label. Absent = show the raw `value`.
+			 */
+			label?: string | null;
+			/**
+			 * The value persisted to the preference key.
+			 */
+			value: string;
+	  };
+/**
+ * What a capability provider acts on — see [`ProvidesEntry::target`].
+ *
+ * Deliberately two coarse values rather than a taxonomy. The only question a user
+ * needs answered before swapping is "will this act on the machine in front of me,
+ * or somewhere else?", and a finer vocabulary (container / VM / cloud / another
+ * host) would be guesswork the manifests cannot honestly support.
+ */
+export type ProviderTarget = "local-machine" | "remote-desktop";
 /**
  * A host surface a plugin can declare support for via `targets`.
  *
@@ -19,12 +49,12 @@
  * An **empty/absent** `targets` list means the plugin runs on *every* surface —
  * that is the backward-compatible default and MUST NOT be read as "hidden".
  */
-export type Surface = "gateway" | "core" | "desktop" | "island" | "mobile" | "extension" | "web" | "cli";
+export type Surface = "gateway" | "core" | "desktop" | "island" | "mobile" | "extension" | "web" | "cli" | "unknown";
 
 /**
- * An installable Ryu App manifest (`plugin.json`).
+ * An installable Ryu App manifest (`manifest.json`).
  *
- * Modelled on Codex's `plugin.json` pattern: a thin descriptor that bundles one or
+ * Modelled on Codex's `manifest.json` pattern: a thin descriptor that bundles one or
  * more [`RunnableEntry`] items (agents, workflows, tools, skills, companions,
  * channels, engines, policies), lists the permission grants the app requires, and
  * optionally declares a Companion surface (an in-desktop overlay or sidebar panel).
@@ -36,6 +66,10 @@ export type Surface = "gateway" | "core" | "desktop" | "island" | "mobile" | "ex
  * [`crate::schema::validate_runnable`] function.
  */
 export interface PluginManifest {
+	/**
+	 * Primary brand accent color, hex (Ryu extension: `accentColor`).
+	 */
+	accentColor?: string | null;
 	/**
 	 * Activation events that lazily wake the plugin — VS-Code `activationEvents`.
 	 * Recognised tokens: `"*"` (always active / eager), `"onStartup"`, `"onChat"`,
@@ -82,6 +116,12 @@ export interface PluginManifest {
 	 * [`ui_code_sha256`]: PluginManifest::ui_code_sha256
 	 */
 	backend_sha256?: string | null;
+	/**
+	 * Detail-page hero banner spec ({colors,style,seed}); opaque passthrough (Ryu ext).
+	 */
+	banner?: {
+		[k: string]: unknown;
+	};
 	/**
 	 * Human-readable capability strings (Ryu extension). When absent the detail
 	 * builder DERIVES these from `permission_grants` via
@@ -125,6 +165,29 @@ export interface PluginManifest {
 	 * Homepage/website URL (Claude `homepage`; emitted as `website`).
 	 */
 	homepage?: string | null;
+	/**
+	 * Icon-primitive id for the listing card (Ryu extension: `icon`). An
+	 * Iconify/icons0 `prefix:name`, a bare Hugeicons name, or a URL — resolved by
+	 * the shared `Icon` primitive. Distinct from `icon_url`: this is a GLYPH id the
+	 * card masks with `currentColor`, `icon_url` is a raster logo. When absent the
+	 * card falls back to `icon_url`, then a default glyph.
+	 */
+	icon?: string | null;
+	/**
+	 * CSS background for the icon square (Ryu extension: `iconBackground`).
+	 */
+	iconBackground?: string | null;
+	/**
+	 * Dithered-gradient background for the card's icon square (Ryu extension:
+	 * `iconDither`). Opaque passthrough `{ from, to?, direction? }` mirroring
+	 * dither-kit's `DitherGradient` props (`from`/`to` are a palette-colour name or
+	 * a hue number, `direction` is up|down|left|right). Kept as raw JSON like
+	 * `banner` so an untrusted/typo'd value never fails the manifest parse — the
+	 * render layer validates and falls back before painting.
+	 */
+	iconDither?: {
+		[k: string]: unknown;
+	};
 	/**
 	 * Logo URL (contract key `iconUrl`; Ryu extension).
 	 */
@@ -141,6 +204,20 @@ export interface PluginManifest {
 	 * SPDX license identifier (Claude `license`).
 	 */
 	license?: string | null;
+	/**
+	 * Declarative **stdio MCP servers** this plugin registers into Core's MCP
+	 * registry on enable and deregisters on disable/uninstall. Each entry is a
+	 * [`McpServerDecl`] keyed by the server name the registry uses (the same key a
+	 * user's `mcp.json` would use). This is the manifest-owned successor to Core's
+	 * hardcoded built-in MCP servers: a plugin declares its server here instead of
+	 * Core baking a `com.ryu.<app>` server into `builtin_servers()`. Empty for the
+	 * common case (a plugin that ships no MCP server). A user `mcp.json` entry with
+	 * the same name still wins (user-overrides-builtin precedence is preserved by
+	 * the registry).
+	 */
+	mcp_servers?: {
+		[k: string]: McpServerDecl;
+	};
 	/**
 	 * Human-readable display name shown in the app store / launcher.
 	 */
@@ -238,6 +315,15 @@ export interface PluginManifest {
 	 * common case (no bundled process).
 	 */
 	sidecars?: SidecarSpec[];
+	/**
+	 * Provenance hint for the marketplace index: `"builtin"`, an `owner/repo`
+	 * slug, or a git/raw URL an external plugin ships from. Absent ⇒ `"builtin"`.
+	 * This is an index HINT only — Core derives the real trust tier from
+	 * `plugins::builtins` membership at runtime, NOT from this field. Consumed by
+	 * the marketplace generator (`tools/mirror-plugins.sh`) to populate each
+	 * entry's `source`/`builtin` pair.
+	 */
+	source?: string | null;
 	/**
 	 * Per-surface support + UI declaration — the richer successor to [`targets`].
 	 *
@@ -311,17 +397,40 @@ export interface CompanionSurface {
 /**
  * VS-Code-style **contribution points** (`contributes` in `package.json`).
  *
- * Each field is a list of [`ContributionId`] references into the manifest's
- * `runnables`: the plugin *declares* that runnable `X` contributes to the
- * `commands`/`tools`/`agents`/… surface. This is declare-by-id, not a second
- * copy of the runnable — the loader cross-validates that every referenced id
- * exists in `runnables`, so a typo is caught at load.
+ * The original five surfaces (`commands`/`tools`/`agents`/`workflows`/`policies`)
+ * are lists of [`ContributionId`] references into the manifest's `runnables`: the
+ * plugin *declares* that runnable `X` contributes to that surface. This is
+ * declare-by-id, not a second copy of the runnable — the loader cross-validates
+ * that every referenced id exists in `runnables`, so a typo is caught at load.
+ *
+ * Most surfaces added since are **self-contained**: they carry their own payload
+ * and reference no runnable at all (`widgets`, `views`, `dock_panels`,
+ * `sidebar_sections`, `sidebar_buttons`, `settings_tabs`, `composer_controls`,
+ * `slash_commands`, `turn_hooks`, `tool_filters`, `lsp_servers`).
  *
  * # Extending
  *
- * Add a new surface = add a new `#[serde(default)] pub <surface>: Vec<ContributionId>`
- * field here. The cross-validation in [`Contributes::referenced_ids`] picks it
- * up automatically.
+ * Adding a surface is two decisions, and getting either wrong is silent:
+ *
+ * 1. **Id-reference or self-contained?** An id-reference surface is a
+ *    `Vec<ContributionId>` and MUST be chained into [`Contributes::referenced_ids`]
+ *    so the loader can catch a typo. A self-contained surface must be left OUT of
+ *    it — every id in it names something other than a runnable (a PATH binary, a
+ *    route, a tool namespace), so including it would reject every valid manifest.
+ *    `referenced_ids` therefore covers exactly the five original surfaces and
+ *    nothing else; that omission is deliberate, not an oversight to be tidied up.
+ * 2. **Core-interpreted or client-rendered?** If Core acts on the payload
+ *    (`tool_filters`, `turn_hooks`, `widgets`, `lsp_servers`) it gets a fully typed
+ *    struct, because a key Core does not know is by construction a key Core cannot
+ *    act on. If a client shell renders it (`views`, `dock_panels`,
+ *    `sidebar_sections`, `settings_tabs`, `composer_controls`) it stays opaque
+ *    JSON, because deserializing into a struct here would DROP any key this Core
+ *    build does not know about and a newer desktop would lose exactly the fields it
+ *    was shipped to render.
+ *
+ * Client-rendered surfaces are then served, tagged with the owning plugin id, from
+ * `GET /api/plugins/contributions`. Core-interpreted ones deliberately are not —
+ * they are gathered at their own consumption site instead.
  */
 export interface Contributes {
 	/**
@@ -334,12 +443,218 @@ export interface Contributes {
 	commands?: ContributionId[];
 	/**
 	 * Declarative **native** UI widgets the plugin contributes to the desktop
-	 * composer (e.g. a `toggle` that sets a `plugin_flags` entry, or a `chip`).
-	 * Core stores these verbatim and serves them via `GET /api/plugins/contributions`;
-	 * the desktop renders the known widget types. Opaque to Core (the renderer
-	 * owns interpretation) so new widget types need no Core change.
+	 * composer. Core stores these verbatim and serves them via
+	 * `GET /api/plugins/contributions` (tagged with the owning `plugin` id); the
+	 * desktop renders the known control types. Opaque to Core (the renderer owns
+	 * interpretation) so a new control type needs no Core change — an entry Core has
+	 * never heard of is forwarded byte-for-byte, so a desktop newer than the node it
+	 * talks to still gets everything it was shipped to render.
+	 *
+	 * # The control vocabulary
+	 *
+	 * Every entry is an object carrying `id`, a `type` discriminant, a `label` and a
+	 * `flag`; the remaining keys belong to that type. `flag` is universal because the
+	 * per-request `plugin_flags` map is the composer's ONLY channel to the turn — a
+	 * control the turn hook cannot observe would do nothing. `type` is deliberately NOT
+	 * an enum (same reasoning as [`ViewContribution::view`]): an unknown member must
+	 * reach a newer shell intact rather than being rejected at load by an older Core.
+	 * The vocabulary the desktop composer understands today:
+	 *
+	 * - `"toggle"` — a switch row in the composer "+" menu, with an optional
+	 *   `description`. Flipping it puts `flag: true` into `plugin_flags`. This is the
+	 *   original — and until now the ONLY — rendered type.
+	 * - `"select"` — a menu/segmented picker. Carries an `options` array of
+	 *   `{ value, label, description?, icon? }` plus an optional `default`. The chosen
+	 *   `value` (a string, not a bool) lands in `plugin_flags[flag]`, so a plugin can
+	 *   offer modes ("fast" / "thorough") instead of on/off.
+	 * - `"chip"` — an inline pill in the composer bar showing a LIVE value rather than
+	 *   a menu row. Carries an optional `icon` and a `source` (the same
+	 *   `@ryu/app-host/views` `ViewSource` a declarative view uses) the shell polls for
+	 *   the displayed text, and exposes/clears its value through `flag`. This is what a
+	 *   rich bespoke control (a recording indicator, a selected-clip pill) needs in
+	 *   order to stop being hand-written host code.
+	 * - `"action"` — a button that DISPATCHES rather than holding state. Carries an
+	 *   optional `icon` and a `capability` (+ optional `args`) the shell invokes
+	 *   through the plugin's granted capability seam — never inline code, and never a
+	 *   capability the owning plugin was not granted — then marks `flag` so the turn
+	 *   hook sees that it fired.
+	 *
+	 * A control may also carry `placement` (`"menu"`, the default, or `"bar"`) and
+	 * `order`; the renderer, not Core, decides what to do with an unknown key.
+	 *
+	 * Renderers MUST ignore an entry whose `type` they do not know (the desktop
+	 * filters by `type`), so shipping a new control type degrades to "not shown on
+	 * older shells" instead of breaking the composer.
 	 */
 	composer_controls?: unknown[];
+	/**
+	 * **Deletable data categories** the app owns — one "Delete all X" row in
+	 * Settings → Danger Zone (see [`DataCategoryContribution`]).
+	 *
+	 * The danger zone used to be two hardcoded lists that had to be edited
+	 * together: a `DataCategory` enum in Core and a `CATEGORIES` array carrying the
+	 * user-facing copy in the closed desktop source. Monitors and Meetings are
+	 * app-owned data, so both lists named apps — which meant a node where Monitors
+	 * was never enabled still offered to delete monitors, and the count was always
+	 * 0. Declaring the category here makes the owning app the single source of both
+	 * its existence and its wording, and makes the row appear and disappear with
+	 * the app instead of with a client-side feature-detect.
+	 *
+	 * # Core-interpreted, so a typed struct — and NOT on the contributions endpoint
+	 *
+	 * Core has to resolve the id to something that can actually count and delete
+	 * the rows, so per this type's own doc comment this gets a typed struct rather
+	 * than opaque JSON, and it is gathered at its consumption site
+	 * (`GET /api/data/counts`, which serves each category's descriptor next to its
+	 * live count) rather than at `GET /api/plugins/contributions` — the same
+	 * disposition as [`Contributes::tool_filters`] and [`Contributes::lsp_servers`].
+	 *
+	 * # Declaration, not implementation
+	 *
+	 * A declared category is served only when Core knows how to clear it; an id
+	 * Core does not implement is skipped with a warn rather than being offered as a
+	 * button that 400s. That split is deliberate and not a stepping stone to a
+	 * generic HTTP truncate: clearing monitors has to tear down each monitor's
+	 * backing scheduler job, and clearing meetings has to broadcast on the meetings
+	 * SSE stream, so a blind `DELETE /monitors` would leave jobs ticking forever.
+	 * The manifest owns *whether the row exists and what it says*; Core owns *what
+	 * deleting actually entails*.
+	 */
+	data_categories?: DataCategoryContribution[];
+	/**
+	 * App-registered **workspace dock panels** — a tab in the desktop's bottom or
+	 * right dock (Terminal / Code Review / Browser / Simulator live there today).
+	 * This is the seam that lets an app OWN its dock tab instead of the shell
+	 * welding the app into a closed `TabKind` union: `@ryu/browser` and
+	 * `@ryu/simulator` are apps, and their tabs are contributions, not enum
+	 * variants. Self-contained + opaque `spec` (see [`DockPanelContribution`]), so a
+	 * new panel capability needs no Core change; served + tagged with the owning
+	 * `plugin` id at `GET /api/plugins/contributions`.
+	 */
+	dock_panels?: DockPanelContribution[];
+	/**
+	 * **App events this plugin emits** — the *provider* half of the hook system,
+	 * and the mirror image of [`Contributes::turn_hooks`] (the *consumer* half).
+	 *
+	 * Core's own hook phases (`post_assistant_turn`, `pre_tool_use`, `context`, …)
+	 * are a closed set built into `plugin_host`, so before this surface existed a
+	 * plugin could only react to things happening *in a chat turn*. An app that
+	 * owns a real-world lifecycle — a meeting ending, a workflow run failing, an
+	 * alert firing — had no way to let anything else react to it. That forced the
+	 * classic anti-pattern: every consumer polls the producer's HTTP routes, and
+	 * every new integration is bespoke wiring between two apps that must both be
+	 * changed.
+	 *
+	 * Declaring an event here makes it a first-class hook phase. Any other plugin
+	 * consumes it by naming it in a `turn_hooks[].on`, and any workflow consumes it
+	 * with an `event` trigger — neither the producer nor Core learns anything about
+	 * the consumer. Apps therefore both **provide** and **consume** over one
+	 * mechanism.
+	 *
+	 * # Ids are namespaced, and that is what makes collisions impossible
+	 *
+	 * Every id MUST be `<owning plugin id>#<event name>` — the owning half is
+	 * checked against the manifest's own `id` at load, and the name half is
+	 * `[a-z0-9][a-z0-9._-]*`. Because a Core phase name never contains `/`, an app
+	 * literally cannot declare an event that shadows one, no reserved-word list
+	 * required. It is also why the emit path can authorize purely from the
+	 * manifest: the caller's authenticated plugin id must be the id in the event
+	 * name, so an app can only ever emit its **own** events.
+	 *
+	 * # Core-interpreted, so a typed struct
+	 *
+	 * Core reads this table to authorize emits and to serve the event catalog, so
+	 * per this type's own doc comment it gets a typed struct rather than opaque
+	 * JSON. It names event strings rather than runnable ids, so it is
+	 * **self-contained** and stays out of [`Contributes::referenced_ids`].
+	 */
+	hook_events?: HookEventContribution[];
+	/**
+	 * **Language servers** the plugin declares, keyed by server name — the
+	 * agent-neutral mirror of Claude Code's `.lsp.json` / `lspServers`, so a config
+	 * written for either host loads in the other:
+	 *
+	 * ```json
+	 * "lsp_servers": {
+	 *   "go": { "command": "gopls", "args": ["serve"], "extensionToLanguage": { ".go": "go" } }
+	 * }
+	 * ```
+	 *
+	 * Only the container key is Ryu's (`lsp_servers`, snake_case like every sibling
+	 * here); every key INSIDE a server entry is Claude's own camelCase spelling
+	 * verbatim, because that body is what actually travels between the two hosts.
+	 * No `lspServers` alias is accepted on purpose. `lsp_servers` — this exact
+	 * spelling — is registered in the SDK's zod mirror (`ContributesSchema` in
+	 * `packages/sdk/src/manifest.ts`), and that mirror STRIPS every key it does not
+	 * list. An alias would therefore parse here and be silently deleted at
+	 * `ryu pack` time, before the manifest is signed, which is a worse failure than
+	 * a key that never parsed at all. One spelling, registered in both places.
+	 *
+	 * The plugin ships CONFIG ONLY, never the server binary — `command` is resolved
+	 * from `PATH` at spawn time and a missing binary is a visible skip, not a load
+	 * error. Core spawns and supervises these processes itself, so unlike the
+	 * client-rendered surfaces above this one is fully typed
+	 * ([`LspServerContribution`]) and is NOT served from
+	 * `GET /api/plugins/contributions`; it is gathered at the spawn site, the same
+	 * disposition as [`Contributes::tool_filters`].
+	 *
+	 * # Ordering is part of the contract
+	 *
+	 * Registration is **first-registration-wins per file extension**: if two enabled
+	 * servers both claim `.go`, the first one registered owns it, the others never
+	 * start for that extension, and the spawn site warns naming the owner. That rule
+	 * is only reproducible if iteration order is, so this is a [`BTreeMap`] — it
+	 * iterates lexicographically by server key, never in hash order and never in
+	 * JSON authoring order. The full resolved invariant across a node is
+	 * **(plugin enable order, then server key ascending)**.
+	 *
+	 * Note this makes the tie-break deterministic, not byte-identical to Claude
+	 * Code's, which falls out of JS object insertion order. Two servers fighting
+	 * over one extension is a misconfiguration in either host; what matters is that
+	 * the same node always resolves it the same way and says who won.
+	 */
+	lsp_servers?: {
+		[k: string]: LspServerContribution;
+	};
+	/**
+	 * **Pi extensions** the plugin ships — TypeScript files the managed `ryu` (Pi)
+	 * agent loads at process start:
+	 *
+	 * ```json
+	 * "pi_extensions": [
+	 *   { "id": "shell", "file": "pi-extensions/ryu-shell.ts",
+	 *     "description": "background bash for the managed Pi agent" }
+	 * ]
+	 * ```
+	 *
+	 * Pi ships none of plan mode, sub-agents, permission prompts or background bash
+	 * and says so deliberately in its own docs — "you can build or install those
+	 * workflows as extensions or packages". This surface is that seam: the
+	 * capabilities Core used to hardcode into the spawn path become plugins the user
+	 * can enable and disable, and a third party can ship one at all.
+	 *
+	 * # This is UNSANDBOXED code, and the tier gate is not optional
+	 *
+	 * A [`Contributes::turn_hooks`] body runs in the deny-by-default Deno sandbox
+	 * behind capability-gated `host.*` calls. A file named here runs **inside the Pi
+	 * process** with full host privilege: the first-party ones spawn children and
+	 * POST to Core. That is the same arbitrary-code-execution class as
+	 * [`PluginManifest::mcp_servers`], so Core gates it identically — Core tier is
+	 * auto-allowed, Community tier needs an operator-allowlisted grant, and the gate
+	 * sits at the materializer, because writing the file is what makes it run.
+	 *
+	 * # Core-interpreted, so a typed struct — and NOT on the contributions endpoint
+	 *
+	 * Core resolves each `file` and projects it into the managed Pi's config dir, so
+	 * per this type's own doc comment it gets a typed struct and is gathered at its
+	 * consumption site (`pi_config::app_extensions`) rather than served from
+	 * `GET /api/plugins/contributions` — the same disposition as
+	 * [`Contributes::lsp_servers`].
+	 *
+	 * The `file` is deliberately NOT hydrated into an inline string the way a
+	 * `code_file` is; see [`PluginManifest::pi_extension_refs`] for why.
+	 */
+	pi_extensions?: PiExtensionContribution[];
 	/**
 	 * Gateway policies the plugin contributes (referenced by runnable id).
 	 */
@@ -347,24 +662,71 @@ export interface Contributes {
 	/**
 	 * Declarative settings tabs the plugin contributes (model pickers, text
 	 * fields bound to preference keys). Served + rendered the same way.
+	 *
+	 * The **contract** for each entry is [`SettingsTabContribution`] — that is what
+	 * the published JSON Schema advertises (`schemars(with = …)`) and what the
+	 * loader holds every manifest to at import (see `validate_settings_tab`), so a
+	 * malformed tab is rejected with a diagnostic instead of reaching the desktop
+	 * and being silently dropped by the renderer's defensive parser.
+	 *
+	 * The *stored* type stays `serde_json::Value` on purpose. `GET
+	 * /api/plugins/contributions` tags each entry in place with its owning `plugin`
+	 * id and forwards it verbatim; deserializing into the struct here would silently
+	 * DROP any key this Core build does not know about, so a desktop newer than the
+	 * node it talks to would lose exactly the fields it was shipped to render. Parse
+	 * once at the validation chokepoint, forward the original bytes.
+	 */
+	settings_tabs?: SettingsTabContribution[];
+	/**
+	 * App-registered sidebar **buttons** — a single nav row (e.g. Memory →
+	 * `/library/memory`). The button-shaped sibling of [`Contributes::sidebar_sections`]
+	 * (no live list, just a label/icon + a client route). See [`SidebarButtonContribution`].
+	 */
+	sidebar_buttons?: SidebarButtonContribution[];
+	/**
+	 * App-registered sidebar **sections** — a header plus a live list of rows the
+	 * shell fetches from a declared Core `/api/` path. Lets an app own its sidebar
+	 * section (Canvas/Whiteboard/Meetings recent-doc lists) instead of the shell
+	 * hardcoding it. Self-contained + opaque `spec` (see [`SidebarSectionContribution`]),
+	 * so a new section capability needs no Core change; served + tagged with the
+	 * owning `plugin` id at `GET /api/plugins/contributions`.
 	 */
-	settings_tabs?: unknown[];
+	sidebar_sections?: SidebarSectionContribution[];
 	/**
 	 * Slash commands the plugin contributes (e.g. `/goal`). The desktop maps the
 	 * command to a `plugin_flags`/message action; the plugin's turn hook reads
 	 * the resulting message. Served + rendered the same way.
 	 */
 	slash_commands?: unknown[];
+	/**
+	 * Tools this plugin wants **hidden** from the model's offered tool list —
+	 * the declarative half of a tool firewall (see [`ToolFilterContribution`]).
+	 *
+	 * Purely declarative here: this contract defines and validates the shape, and
+	 * the filter is applied where tools are offered to the model. Like
+	 * [`Contributes::turn_hooks`] this is self-contained (the ids name tools from
+	 * *other* plugins/servers by design — hiding your own tool is just not
+	 * declaring it), so it is NOT cross-validated against `runnables`.
+	 */
+	tool_filters?: ToolFilterContribution[];
 	/**
 	 * Callable tools the plugin contributes (referenced by runnable id).
 	 */
 	tools?: ContributionId[];
 	/**
-	 * Chat turn hooks the plugin contributes — server-side logic that runs at a
-	 * turn boundary (e.g. `post_assistant_turn`) and returns a directive. These
-	 * are **self-contained** (they carry their own inline `code`), so they are
-	 * NOT cross-validated against `runnables` like the id-reference surfaces
-	 * above; the Core `plugin_host` runtime executes them in the sandbox.
+	 * Hooks the plugin contributes — server-side logic that runs at a hook
+	 * boundary and returns a directive. These are **self-contained** (they carry
+	 * their own inline `code`), so they are NOT cross-validated against
+	 * `runnables` like the id-reference surfaces above; the Core `plugin_host`
+	 * runtime executes them in the sandbox.
+	 *
+	 * The field name is historical. It originally held only *chat* turn
+	 * boundaries (`post_assistant_turn`, `pre_user_turn`); a hook's `on` is now
+	 * any hook phase, including an **app event** another plugin declared in its
+	 * [`Contributes::hook_events`] (`@example/meetings#meeting.ended`). It is
+	 * deliberately NOT renamed: `turn_hooks` is load-bearing in every packaged
+	 * manifest, the published JSON Schema, the SDK's TS mirror and the loader's
+	 * invariant tests, and the rename would buy nothing but churn.
 	 */
 	turn_hooks?: TurnHookContribution[];
 	/**
@@ -410,18 +772,568 @@ export interface ContributionId {
 	 */
 	title?: string | null;
 }
+/**
+ * One **deletable data category** an app owns (see [`Contributes::data_categories`]).
+ *
+ * Everything the Danger Zone needs to draw and arm one destructive row, so the copy
+ * lives with the app whose data it describes rather than in the desktop's source.
+ */
+export interface DataCategoryContribution {
+	/**
+	 * The word the user must type to arm the delete. Absent = the [`noun`], which is
+	 * the right default often enough that requiring it would just be ceremony.
+	 * Matched case-insensitively by the client.
+	 *
+	 * [`noun`]: DataCategoryContribution::noun
+	 */
+	confirm_word?: string | null;
+	/**
+	 * Exactly what disappears, shown in the confirm dialog. Required, and required
+	 * to be specific: this is the last thing the user reads before an irreversible
+	 * delete, and "this cannot be undone" tells them nothing they did not know.
+	 */
+	detail: string;
+	/**
+	 * Stable id — this is the `category` a `POST /api/data/clear` names, so it is
+	 * the app's half of the delete contract and renaming it breaks the button.
+	 */
+	id: string;
+	/**
+	 * Plural noun for the live count line ("42 monitors" / "No monitors") and the
+	 * "N deleted" toast. Lower-case: it is used mid-sentence.
+	 */
+	noun: string;
+	/**
+	 * The destructive button label and confirm-dialog title ("Delete all monitors").
+	 */
+	title: string;
+}
+/**
+ * One app-registered **workspace dock panel** — a tab in the desktop's bottom or
+ * right dock (see [`Contributes::dock_panels`]).
+ *
+ * The dock sibling of [`ViewContribution`] / [`SidebarSectionContribution`]: a typed
+ * envelope (`id` / `title` / `icon` / `placement`) around an OPAQUE description of
+ * what the tab renders. Core stores it verbatim, tags it with the owning `plugin` id
+ * at `GET /api/plugins/contributions`, and never interprets `panel` or `spec` — so a
+ * new panel capability is a renderer change, never a Core change.
+ *
+ * # The `panel` vocabulary
+ *
+ * `panel` is the render-mode discriminant the desktop's dock renderer switches on.
+ * It is a plain `String` (not an enum) for the same reason [`ViewContribution::view`]
+ * is: an unknown member must reach a newer shell intact rather than being rejected at
+ * load by an older Core. The vocabulary the desktop understands today:
+ *
+ * - `"companion"` — mount the app's sandboxed companion surface in the dock. The
+ *   `spec` names it: `{ "companion": "<runnable id>" }`. This is the third-party
+ *   path: an app ships one companion UI and can surface it in the dock, the sidebar,
+ *   or a full tab without any host code.
+ * - `"view"` — render one of the plugin's own [`Contributes::views`] entries inside
+ *   the dock chrome: `{ "view": "<view id>" }`. Data-only, drawn with the host's own
+ *   `@ryu/ui` components, so a dock panel gets the Raycast tier for free.
+ * - `"native"` — the shell's OWN component, registered under `<plugin>/<id>`. This is
+ *   the migration seam for first-party apps whose panel is hand-written React driving
+ *   their sidecar through the ext-proxy (`@ryu/browser`, `@ryu/simulator`): the
+ *   *component* stays in the shell, but its existence, label, icon and placement stop
+ *   being a hardcoded `TabKind` variant and become the app's own declaration, so
+ *   disabling the app removes the tab. An unknown `<plugin>/<id>` simply renders
+ *   nothing — a native panel is never a code channel.
+ *
+ * The full `spec` shape is owned by the shared TS vocabulary (`@ryu/app-host/views`
+ * `DockPanelSpec`), NOT by this contract.
+ */
+export interface DockPanelContribution {
+	/**
+	 * Optional glyph id resolved by the shell's Icon primitive (Iconify/Hugeicons).
+	 */
+	icon?: string | null;
+	/**
+	 * Stable id for this panel within the plugin (the dock's tab key, namespaced by
+	 * the shell as `plugin:<pluginId>:<id>` so two apps can reuse an id).
+	 */
+	id: string;
+	/**
+	 * Optional ordering hint within the dock's tab-type menu (lower = earlier).
+	 */
+	order?: number | null;
+	/**
+	 * The render-mode discriminant (`"companion"`, `"view"`, `"native"`, …). Opaque
+	 * to Core; an unknown member is passed through so a newer shell can render it.
+	 */
+	panel: string;
+	/**
+	 * Which dock the panel opens in. Defaults to [`DockPanelPlacement::Bottom`], the
+	 * drawer a terminal-shaped panel belongs in — and falls back to it for an
+	 * unrecognised dock too, rather than failing the whole manifest
+	 * (see [`deserialize_dock_panel_placement`]).
+	 */
+	placement?: "bottom" | "right" | "both";
+	/**
+	 * The payload for the render mode (`{ "companion": … }` / `{ "view": … }` / any
+	 * future panel capability). Opaque to Core — the desktop dock renderer interprets
+	 * it per `panel`. Absent = the mode needs no payload (the `"native"` case).
+	 */
+	spec?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Tab label shown on the dock tab strip and in the "new tab" menu.
+	 */
+	title: string;
+}
+/**
+ * One **app event** a plugin declares it emits (a [`Contributes::hook_events`]
+ * row). This is a *declaration*, not code: the event is raised at runtime by the
+ * plugin's own sidecar calling the `events.emit` kernel capability, and Core
+ * checks the emit against this table.
+ *
+ * The payload the emitter sends is delivered to every consumer as `ctx.event`, so
+ * [`Self::payload_example`] is the contract a consumer author reads. Keep it
+ * honest — it is the only description of the payload anyone gets.
+ */
+export interface HookEventContribution {
+	/**
+	 * What the event means and, critically, *when* it fires — including whether it
+	 * can fire more than once for the same subject.
+	 */
+	description?: string | null;
+	/**
+	 * The fully-qualified event id: `<owning plugin id>#<event name>`, e.g.
+	 * `@example/meetings#meeting.ended`. Validated at load against the owning
+	 * manifest's `id`; see [`Contributes::hook_events`] for why the namespace is
+	 * mandatory rather than conventional.
+	 *
+	 * Name the event after **what happened**, in the past tense, never after who
+	 * should react to it: a consumer that renames the producer's event to suit
+	 * itself is exactly the coupling this surface removes. The house patterns are
+	 * `x.started` / `x.ended` / `x.failed` for a lifecycle, `x.ready` for a
+	 * produced artifact, and `x.created` / `x.updated` / `x.deleted` for state.
+	 */
+	id: string;
+	/**
+	 * An example of the payload delivered as `ctx.event`. Documentation, not a
+	 * schema: Core forwards whatever the emitter sends verbatim and validates
+	 * nothing beyond the size cap, so this exists for the human writing a consumer.
+	 */
+	payload_example?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Human-readable title for the event picker (workflow trigger UI, docs).
+	 */
+	title: string;
+}
+/**
+ * One **language server** a plugin declares (see [`Contributes::lsp_servers`]).
+ *
+ * Field-for-field Claude Code's language-server config, camelCase on the wire, so
+ * the same JSON body loads in either host. Required by Claude's spec: `command`
+ * and `extensionToLanguage`. Everything else is optional and defaulted here to
+ * Claude's documented default.
+ *
+ * # Why `command` and `extensionToLanguage` are `#[serde(default)]` anyway
+ *
+ * They are required by the SPEC, not by serde, and that is deliberate. Claude Code
+ * **skips** a server whose config is invalid and starts the rest; making either
+ * field a non-defaulted serde field would instead turn a missing one into a parse
+ * error on the entire [`PluginManifest`], costing the plugin every runnable,
+ * sidecar and tool it ships over one broken language-server entry. Defaulting them
+ * is what makes the per-server skip reachable at all: the manifest parses, and
+ * [`LspServerContribution::validate`] reports the reason at the spawn site.
+ *
+ * Unknown keys are dropped rather than rejected (no `deny_unknown_fields`
+ * anywhere in this file), so a field from a newer Claude release costs a plugin
+ * nothing.
+ */
+export interface LspServerContribution {
+	/**
+	 * Arguments passed to [`command`](LspServerContribution::command)
+	 * (e.g. `["serve"]` for `gopls`).
+	 */
+	args?: string[];
+	/**
+	 * The server executable, resolved from `PATH` at spawn time (`gopls`,
+	 * `rust-analyzer`, `typescript-language-server`, …).
+	 *
+	 * The plugin ships the CONFIG, never the binary. A `command` that is not on
+	 * `PATH` is a graceful skip with a visible reason — the user is told which
+	 * server did not start and why, and the rest of the node is unaffected.
+	 * Defaulted to `""` so a missing one is a skipped server, not a dead manifest
+	 * (see the type doc).
+	 */
+	command?: string;
+	/**
+	 * Push this server's diagnostics into the model's context after edits. Defaults
+	 * to **true** (Claude Code parity); same `default` caveat as
+	 * [`restart_on_crash`](LspServerContribution::restart_on_crash).
+	 */
+	diagnostics?: boolean;
+	/**
+	 * Extra environment variables for the server process, merged over the inherited
+	 * environment.
+	 */
+	env?: {
+		[k: string]: string;
+	};
+	/**
+	 * File extension → LSP language id (`{ ".go": "go" }`) — the map that decides
+	 * which files this server handles, and the thing two servers can collide on.
+	 *
+	 * Claude Code authors keys with a leading dot and in lowercase; a hand-written
+	 * manifest will not always. Compare through
+	 * [`normalize_lsp_extension_key`] (or read
+	 * [`normalized_extensions`](LspServerContribution::normalized_extensions))
+	 * rather than indexing this map directly, so `go`, `.go` and `.GO` all resolve
+	 * to the same entry. Empty ⇒ the server claims nothing and is skipped.
+	 */
+	extensionToLanguage?: {
+		[k: string]: string;
+	};
+	/**
+	 * Sent verbatim as `initializationOptions` in the LSP `initialize` request.
+	 * Opaque JSON on purpose: the shape is the individual language server's, and
+	 * Ryu is a courier for it, not an interpreter. Absent = send none.
+	 */
+	initializationOptions?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Cap on automatic restarts before the server is left down. Absent = the spawn
+	 * site's own default; meaningless when
+	 * [`restart_on_crash`](LspServerContribution::restart_on_crash) is false.
+	 */
+	maxRestarts?: number | null;
+	/**
+	 * Restart the server when it exits unexpectedly. Defaults to **true** (Claude
+	 * Code parity).
+	 *
+	 * Note this needs an explicit default fn: a bare `#[serde(default)]` on a
+	 * `bool` yields `false` and would silently invert the documented behaviour.
+	 * Like [`McpServerDecl::enabled`] it carries no `skip_serializing_if`, so the
+	 * value always ships and a reader never has to know the default.
+	 */
+	restartOnCrash?: boolean;
+	/**
+	 * Sent verbatim as the payload of `workspace/didChangeConfiguration` once the
+	 * server is initialized. Opaque for the same reason as
+	 * [`initialization_options`](LspServerContribution::initialization_options).
+	 * Absent = send nothing.
+	 */
+	settings?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Milliseconds to wait for a clean `shutdown`/`exit` before killing the
+	 * process. Absent = the spawn site's own default.
+	 *
+	 * That default is the one place this type knowingly parts company with Claude
+	 * Code, whose reference says an unset `shutdownTimeout` means **no timeout
+	 * applies** — it waits on a wedged server indefinitely. Ryu's spawn sites
+	 * impose a finite one (5s in `assets/pi-extensions/ryu-lsp.ts`, documented at
+	 * the constant), because Pi is spawned per session and an unbounded wait would
+	 * hold every teardown open behind one unresponsive server. An explicitly
+	 * declared value is honoured verbatim, so a config written for either host
+	 * still behaves identically; only the *unset* case differs.
+	 */
+	shutdownTimeout?: number | null;
+	/**
+	 * Milliseconds to wait for `initialize` to come back before giving up on the
+	 * server. Absent = the spawn site's own default.
+	 */
+	startupTimeout?: number | null;
+	/**
+	 * How the host talks to the server: `"stdio"` (the default, and the only
+	 * transport Core implements today) or `"socket"`.
+	 *
+	 * A plain `String` and not an enum, matching this file's other discriminants
+	 * ([`ViewContribution::view`], [`DockPanelContribution::panel`]). The reason is
+	 * sharper here than for those: [`DockPanelPlacement`] can afford to coerce an
+	 * unrecognised value to its default because a panel opening in the wrong dock is
+	 * cosmetic, whereas coercing an unrecognised transport to `stdio` would spawn a
+	 * process and then speak a protocol it does not understand. The verbatim string
+	 * survives instead, and the spawn site refuses what it cannot drive — see
+	 * [`LspTransport`] and [`LspServerContribution::transport_kind`].
+	 */
+	transport?: string;
+	/**
+	 * Root directory the server is rooted at. Absent (the common case) = the
+	 * session's workspace root, which is why this is an `Option` rather than a
+	 * defaulted `String`: "unset, inherit the workspace" and "explicitly rooted
+	 * somewhere" are different instructions.
+	 */
+	workspaceFolder?: string | null;
+}
+/**
+ * One **Pi extension** a plugin ships (a [`Contributes::pi_extensions`] row).
+ *
+ * Carries a path, never a body: unlike [`TurnHookContribution`] there is no inline
+ * `code` twin, because nothing downstream reads the source as a string.
+ */
+export interface PiExtensionContribution {
+	/**
+	 * Optional human-facing one-liner (what the extension adds to the agent).
+	 */
+	description?: string | null;
+	/**
+	 * Path to the TypeScript source, relative to the plugin root — exactly
+	 * `pi-extensions/<name>.ts`. See [`validate_pi_extension_path`].
+	 */
+	file: string;
+	/**
+	 * Stable id for this extension within the plugin (`[a-z0-9][a-z0-9._-]*`).
+	 *
+	 * Part of the materialized file name, so it is what makes one plugin's
+	 * extensions distinguishable from another's on disk — and why it is validated
+	 * with the same alphabet as an event name rather than left free-form.
+	 */
+	id: string;
+}
+/**
+ * One **settings tab** a plugin contributes (see [`Contributes::settings_tabs`]).
+ *
+ * A tab is EITHER declarative (`fields`, rendered by the shared plugin-settings
+ * renderer against Core's preference store) OR a named `view` the shell resolves to
+ * a bespoke component — for an app whose settings genuinely cannot be expressed as
+ * a list of fields. A tab with neither renders as an empty section, which the
+ * desktop's defensive parser drops on the floor; the loader rejects it instead so
+ * the author gets told.
+ */
+export interface SettingsTabContribution {
+	/**
+	 * The declarative fields this tab renders. Empty is only legal alongside a
+	 * `view`.
+	 */
+	fields?: SettingsFieldContribution[];
+	/**
+	 * Stable id for this tab within the plugin — the settings nav routes to it and
+	 * the renderer keys by it. Required: the desktop's fallback (`<plugin>.settings`)
+	 * collides the moment a plugin declares a second tab.
+	 */
+	id: string;
+	/**
+	 * Which settings dialog this tab lands in. Absent/unrecognised = `node`.
+	 */
+	scope?: "node" | "user";
+	/**
+	 * Header label for the section. Absent = `"Settings"`, matching the renderer.
+	 */
+	title?: string;
+	/**
+	 * A rich settings view this app ships instead of declarative `fields`. Opaque
+	 * here — the settings renderer owns the vocabulary and resolves the name to a
+	 * component (first-party) or a sandboxed UI (third-party).
+	 */
+	view?: string | null;
+}
+/**
+ * One configurable field inside a [`SettingsTabContribution`], bound to exactly
+ * one preference key.
+ *
+ * `pref_key` is both the storage binding (`GET/PUT /api/preferences/:key`) **and**
+ * the field's identity — the renderer keys its React elements by it — so two
+ * fields sharing one `pref_key` inside a tab is a bug, not a shorthand, and the
+ * loader rejects it.
+ *
+ * The `default`/`required`/`min`/`max`/`min_length`/`max_length` block is
+ * validation metadata: declaring it is how a plugin gets its settings checked at
+ * *import* instead of discovering at runtime that a user typed `"maybe"` into what
+ * the hook reads as a number. It is cross-checked against `type` at load, because
+ * validation metadata that is silently ignored (a `min` on a toggle) is worse than
+ * none — it reads as a guarantee that was never enforced.
+ */
+export interface SettingsFieldContribution {
+	/**
+	 * Default value, in the field's own JSON type (bool for a toggle, number for
+	 * a number, string elsewhere) — NOT the stringified form preferences are
+	 * stored in, so a manifest stays readable and the type is checkable.
+	 */
+	default?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Helper caption shown under the field.
+	 */
+	description?: string | null;
+	/**
+	 * Display label. Absent = the renderer shows the `pref_key`.
+	 */
+	label?: string | null;
+	/**
+	 * Inclusive upper bound for a [`SettingsFieldType::Number`].
+	 */
+	max?: number | null;
+	/**
+	 * Maximum length for a text/textarea value.
+	 */
+	max_length?: number | null;
+	/**
+	 * Inclusive lower bound for a [`SettingsFieldType::Number`].
+	 */
+	min?: number | null;
+	/**
+	 * Minimum length for a text/textarea value.
+	 */
+	min_length?: number | null;
+	/**
+	 * Choices for a [`SettingsFieldType::Select`]; required for that type and
+	 * inert for every other one.
+	 */
+	options?: SettingsFieldOption[];
+	/**
+	 * Placeholder for text / model-picker inputs.
+	 */
+	placeholder?: string | null;
+	/**
+	 * The preference key this field reads/writes. Required, non-empty, and
+	 * restricted to a path-safe alphabet (it becomes a URL path segment).
+	 */
+	pref_key: string;
+	/**
+	 * Whether the user must supply a value (advisory: enforced by the renderer,
+	 * declared here so the contract is one place).
+	 */
+	required?: boolean;
+	/**
+	 * Granularity for a [`SettingsFieldType::Number`] — the increment its stepper
+	 * moves by, and the grid a typed value must land on.
+	 *
+	 * Distinct from [`Self::min`]/[`Self::max`], which bound the range: a value can
+	 * sit inside the range and still be meaningless at this field's resolution
+	 * (`0.5` where the setting counts whole pages). The renderer enforces it, so a
+	 * field that declares it rejects an off-grid value rather than persisting one
+	 * the plugin cannot use.
+	 */
+	step?: number | null;
+	/**
+	 * The control to render. Absent or unrecognised = a plain text input.
+	 */
+	type?: "text" | "textarea" | "number" | "toggle" | "select" | "model_picker" | "agent_picker" | "secret";
+}
+/**
+ * One app-registered **sidebar button** — a single nav row (the button-shaped
+ * sibling of [`SidebarSectionContribution`]). No live list: just a label/icon and a
+ * client route the shell opens with `openTab`. Migrates hardcoded header-chrome
+ * buttons (e.g. Memory) to the owning app.
+ */
+export interface SidebarButtonContribution {
+	/**
+	 * Optional glyph id resolved by the shell's Icon primitive.
+	 */
+	icon?: string | null;
+	/**
+	 * Stable id for this button within the plugin.
+	 */
+	id: string;
+	/**
+	 * Optional placement hint among the sidebar buttons.
+	 */
+	order?: number | null;
+	/**
+	 * The client route this button opens (e.g. `"/library/memory"`).
+	 */
+	target: string;
+	/**
+	 * Button label.
+	 */
+	title: string;
+}
+/**
+ * One app-registered **sidebar section** — a header plus a live list of rows the
+ * desktop's compact sidebar renderer draws (the app-owned replacement for the
+ * hardcoded Canvas/Whiteboard/Meetings sections). A typed envelope around an opaque
+ * `spec` (the `SidebarSectionSpec` in `@ryu/app-host/views`: a `ViewSource` for the
+ * rows, an `itemTarget` route template for `openTab`, optional `itemActions` and a
+ * `create` action). Core stores it verbatim and tags it with the owning `plugin` id;
+ * the `spec` stays opaque so a new section capability is a renderer change, not a
+ * Core change.
+ */
+export interface SidebarSectionContribution {
+	/**
+	 * Optional glyph id resolved by the shell's Icon primitive (Iconify/Hugeicons).
+	 */
+	icon?: string | null;
+	/**
+	 * Stable id for this section within the plugin (namespaced into the shell's
+	 * section key as `plugin:<pluginId>:<id>`).
+	 */
+	id: string;
+	/**
+	 * Optional placement hint among the sidebar sections (lower = higher up).
+	 */
+	order?: number | null;
+	/**
+	 * The opaque section spec (source/itemTarget/itemActions/create). Interpreted by
+	 * the desktop renderer, never by Core. Absent = a header with no rows.
+	 */
+	spec?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Header label shown in the sidebar and the Customize dialog.
+	 */
+	title: string;
+}
+/**
+ * One **tool filter**: a fully-qualified tool id a plugin wants withheld from the
+ * model's offered tool list.
+ *
+ * Tools are namespaced `<server>__<tool>` (e.g. `browser__navigate`), so `tool`
+ * must carry the namespace — a bare `navigate` would be ambiguous across servers
+ * and is rejected at load. A **trailing** `*` is a prefix wildcard, which is how a
+ * plugin withholds a whole server (`shadow__*`); it is the only wildcard position
+ * allowed, because an interior or leading `*` invites a pattern that silently
+ * matches far more than the author pictured.
+ *
+ * This type is declaration + validation only. The filter is **applied** where the
+ * tool list is assembled for the model (the MCP offer site in
+ * `apps/core/src/sidecar/mcp`), which calls [`ToolFilterContribution::matches`] so
+ * the wildcard rule has exactly one implementation. Hiding a tool from the model
+ * is not a security boundary — it does not revoke the capability, it only stops the
+ * tool being advertised; enforcement stays with permissions and grants.
+ */
+export interface ToolFilterContribution {
+	/**
+	 * Why the plugin hides it — surfaced in the plugin's listing so a user can see
+	 * what a plugin is removing from the model's view before installing it.
+	 */
+	reason?: string | null;
+	/**
+	 * Fully-qualified tool id (`<server>__<tool>`), optionally ending in `*` to
+	 * hide every tool whose id starts with the preceding prefix.
+	 */
+	tool: string;
+}
 /**
  * A server-side chat turn hook contributed by a plugin. The `code` is a JS body
  * run in the plugin sandbox with `ctx` (the turn context) and `host` (the
  * capability bridge: `host.sideModel`, `host.storage`, `host.log`) in scope; it
  * returns a directive (`{kind:"none"}` | `{kind:"note",text}` |
  * `{kind:"continue",text}`). See Core's `plugin_host`.
+ *
+ * The body is authored as a **file** ([`code_file`]) and hydrated into [`code`]
+ * at parse time — see [`PluginManifest::hydrate_code_files`] for why the two
+ * fields are a source-form/wire-form pair rather than alternatives.
+ *
+ * [`code`]: Self::code
+ * [`code_file`]: Self::code_file
  */
 export interface TurnHookContribution {
 	/**
 	 * The JS hook body executed in the sandbox (returns a directive).
+	 *
+	 * Empty in a **source** manifest that declares [`Self::code_file`] instead;
+	 * [`PluginManifest::hydrate_code_files`] fills it in before any consumer sees
+	 * the manifest, and [`PluginManifest::validate`] refuses a manifest where it
+	 * is still empty. Every read site therefore keeps reading exactly this field.
 	 */
-	code: string;
+	code?: string;
+	/**
+	 * Path to the file holding the hook body, relative to the plugin root
+	 * (`hooks/<name>.js`) — the authoring form. Mutually exclusive with
+	 * [`Self::code`]; see [`PluginManifest::hydrate_code_files`].
+	 */
+	code_file?: string | null;
 	/**
 	 * Stable id for this hook (for logging/audit), unique within the plugin.
 	 */
@@ -546,6 +1458,51 @@ export interface EnginesReq {
 	 */
 	ryu: string;
 }
+/**
+ * One declarative **stdio MCP server** a plugin registers (see
+ * [`PluginManifest::mcp_servers`]).
+ *
+ * This is the manifest-side, dependency-free mirror of Core's runtime
+ * `McpServerConfig`: pure data (schemars/serde only) so it can live in
+ * kernel-contracts, with Core lowering it into its registry type on enable. A
+ * server is spawned per request as `command args…` (stdio); `command_env` lets
+ * the manifest name an env var Core resolves to an absolute binary path
+ * (e.g. `RYU_GHOST_BIN`) so a downloaded `~/.ryu/bin` binary can override the
+ * bare `command`.
+ */
+export interface McpServerDecl {
+	/**
+	 * Arguments passed to the command.
+	 */
+	args?: string[];
+	/**
+	 * Executable to spawn (e.g. `npx`, an absolute path, or a `~/.ryu/bin` name).
+	 */
+	command: string;
+	/**
+	 * Optional env var whose value, when set, OVERRIDES [`command`] with an
+	 * absolute binary path. Lets a plugin ship a bare `command` that Core repoints
+	 * at a profile-specific downloaded binary. Absent ⇒ use `command` verbatim.
+	 *
+	 * [`command`]: McpServerDecl::command
+	 */
+	command_env?: string | null;
+	/**
+	 * Optional human description for the MCP listing endpoint.
+	 */
+	description?: string | null;
+	/**
+	 * When false, the server is registered but skipped by list/call. Defaults to
+	 * true so a bare `{ command }` entry just works.
+	 */
+	enabled?: boolean;
+	/**
+	 * Extra environment variables for the server process.
+	 */
+	env?: {
+		[k: string]: string;
+	};
+}
 /**
  * The single, typed, **deny-by-default** permission set a plugin manifest
  * declares, lowered by Core to every sandbox backend.
@@ -614,6 +1571,12 @@ export interface ProvidesEntry {
 	 * this against their [`Requires::capabilities`].
 	 */
 	capability: string;
+	/**
+	 * Preferred pick among the providers of a [`Self::selectable`] capability when
+	 * the user has set no override. At most one provider per capability may declare
+	 * it. Meaningless (and ignored) on a non-selectable capability.
+	 */
+	default?: boolean;
 	/**
 	 * The grant a consumer must hold (Gateway-approved) to invoke this capability
 	 * via the broker. Absent = no extra grant beyond declaring the edge.
@@ -625,12 +1588,62 @@ export interface ProvidesEntry {
 	 * cross-validates that the named sidecar declares a matching route.
 	 */
 	route?: string | null;
+	/**
+	 * Opt in to the **selectable** flavour: many providers of this capability may
+	 * be enabled at once and the user *picks* one, exactly like a local engine.
+	 *
+	 * A non-selectable capability (the original, strict flavour used by `rag` /
+	 * `engines`) treats a second enabled provider as an explicit
+	 * `BindingError::Ambiguous` refusal. A selectable one resolves deterministically
+	 * instead: user override > sole provider > the provider declaring
+	 * [`Self::default_provider`] > lexicographically-lowest provider id. The pick is
+	 * a pure function of the candidate set, so the disable-safety reconstruction
+	 * argument in Core's binding registry is unchanged.
+	 *
+	 * Selectability is a property of the *capability*, so every provider of a given
+	 * capability must agree on the flag; the loader rejects a mixed declaration.
+	 */
+	selectable?: boolean;
 	/**
 	 * The local `name` of one of this manifest's declared `sidecars` that serves
 	 * the capability. The loader cross-validates it exists. Absent = an in-process
 	 * capability with no dedicated sidecar (the broker declines to proxy it).
 	 */
 	sidecar?: string | null;
+	/**
+	 * WHAT this provider acts on, when the capability controls a machine or an
+	 * environment rather than answering a query.
+	 *
+	 * Exists because "swap the provider" quietly means two different things.
+	 * Swapping `web.search` from exa to tavily changes who answers; the question is
+	 * the same. Swapping `computer.control` from ghost to bytebot changes **which
+	 * computer gets typed on** — ghost drives the machine Ryu runs on, bytebot
+	 * drives the desktop `bytebotd` runs on (a containerized Linux desktop in the
+	 * shipped product). A picker that renders those two swaps identically is
+	 * telling the user something false, and until this field existed the
+	 * distinction lived only in a prose `description` that nothing structured
+	 * could read.
+	 *
+	 * Absent = not applicable or unspecified. That is the honest default for the
+	 * capabilities where locality is meaningless (`web.search`, `memory`, `rag`),
+	 * and it is deliberately NOT [`ProviderTarget::LocalMachine`]: defaulting to
+	 * "this machine" would silently mislabel every future hosted provider that
+	 * forgets to declare it.
+	 */
+	target?: ProviderTarget | null;
+	/**
+	 * Capability **verb → this provider's tool** bindings, the seam that keeps the
+	 * model-visible tool surface stable across a swap.
+	 *
+	 * The key is a canonical verb from the host's capability verb table (e.g.
+	 * `"web__search"`); the value names the provider's own registered tool plus the
+	 * argument/response mapping into the canonical shape. A provider that omits a
+	 * verb simply does not serve it — the facade reports the verb unavailable
+	 * rather than guessing.
+	 */
+	tools?: {
+		[k: string]: CapabilityToolBinding;
+	};
 	/**
 	 * The capability's own semver version (independent of the plugin version), so
 	 * a consumer's [`CapabilityReq::min_version`] floor can be checked against the
@@ -638,6 +1651,198 @@ export interface ProvidesEntry {
 	 */
 	version: string;
 }
+/**
+ * How one capability **verb** maps onto a concrete provider tool.
+ *
+ * The facade tool (`web__search`, `browser__navigate`, …) is registered by the host
+ * from its canonical verb table; at call time it resolves the capability's bound
+ * provider, reads this binding, renames the arguments, re-enters tool dispatch on
+ * [`Self::tool`], and maps the response back. Swapping the provider therefore
+ * changes neither the tool id nor its schema.
+ */
+export interface CapabilityToolBinding {
+	/**
+	 * Optional provider-shipped ADAPTER: JavaScript that maps this verb onto the
+	 * provider's tool when the shapes are too far apart for the declarative fields
+	 * above to bridge.
+	 *
+	 * The declarative path ([`Self::args`] … [`Self::response`]) stays the default
+	 * and covers the ~80% of providers that are a rename plus a field map: no code
+	 * review, no sandbox, no supply-chain surface, and a third party ships one file.
+	 * But some provider shapes no amount of JSON can express — an async job API that
+	 * must be polled (`POST /crawl` → job id → `GET /crawl/{id}`), a token vocabulary
+	 * that needs per-provider normalization, a body that must read a `pref:` value.
+	 * Growing the grammar one vendor quirk at a time pushed provider-specific logic
+	 * into shared kernel code; an adapter puts it back in the provider's own manifest.
+	 *
+	 * Present = the adapter REPLACES the declarative mapping for this verb: it
+	 * receives the canonical arguments and returns the canonical result, and
+	 * [`Self::args`] / [`Self::arg_template`] / [`Self::arg_clamp`] / [`Self::response`]
+	 * are not applied (the adapter is doing that job). [`Self::tool`] still names the
+	 * target and is still the ONLY tool the adapter can reach.
+	 */
+	adapter?: CapabilityAdapter | null;
+	/**
+	 * Per-argument numeric limits this provider can actually honour, keyed by the
+	 * **canonical** argument name (before any rename).
+	 *
+	 * Exists because canonical schemas describe what agents may ask for, while
+	 * providers differ in what they accept: `web__search.limit` allows up to 100,
+	 * but Brave's `count` maxes at 20. Without this, selecting Brave turns a
+	 * perfectly valid `limit: 50` into an upstream 4xx — the swap stops being
+	 * transparent, which is the entire point of the facade. Clamping is the right
+	 * resolution rather than erroring: the caller asked for "up to N", and fewer
+	 * results is a normal outcome, whereas a failed search is not.
+	 */
+	arg_clamp?: {
+		[k: string]: ArgBounds;
+	};
+	/**
+	 * Constant arguments merged into every call (provider-specific knobs the
+	 * canonical schema does not expose, e.g. `{"search_depth": "advanced"}`).
+	 */
+	arg_defaults?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * A request-body TEMPLATE this provider needs, with `{canonical_arg}`
+	 * placeholders substituted from the call.
+	 *
+	 * `args` renames flat keys and `[]` wraps a scalar in an array; neither can build
+	 * a NESTED shape. Real APIs need them: Mem0's write endpoint takes
+	 * `messages: [{role, content}]`, so without a template the whole write half of
+	 * that provider is unbindable — which is precisely the gap that made Ryu's
+	 * memory bridges inert while Hermes, which writes per-provider adapter CODE, had
+	 * none. This closes it declaratively instead of admitting code per provider.
+	 *
+	 * A string that is EXACTLY `"{arg}"` is replaced by that argument's value with
+	 * its JSON type preserved (`5` stays a number); a string merely CONTAINING
+	 * `{arg}` interpolates as text. An argument consumed by the template is not also
+	 * passed through, so it cannot appear twice under two names.
+	 */
+	arg_template?: {
+		[k: string]: unknown;
+	};
+	/**
+	 * Canonical argument name → this provider's argument name. A canonical argument
+	 * with no entry is passed through under its own name; map it to the empty string
+	 * to drop it (the provider cannot express it).
+	 */
+	args?: {
+		[k: string]: string;
+	};
+	/**
+	 * Optional response normalization into the canonical result shape. Absent = the
+	 * provider's output is returned verbatim under `{ provider, raw }`.
+	 */
+	response?: CapabilityResponseMap | null;
+	/**
+	 * The provider's own fully-qualified tool id (e.g. `"exa__search"`,
+	 * `"app__firecrawl_scrape"`) that implements this verb.
+	 */
+	tool: string;
+}
+/**
+ * Provider-shipped JavaScript that maps one capability verb onto one provider tool.
+ *
+ * Runs in the SAME Deno sandbox as an `inline_deno` plugin tool, under the same
+ * [`crate`-level] grant model: the providing plugin must hold `tool:execute`, so
+ * shipping code is a visible, approvable act rather than a silent one.
+ *
+ * The program is handed:
+ * - `input` — the canonical verb arguments, after layer defaults are applied.
+ * - `defaults` — the provider's resolved `arg_defaults`, including any `pref:`
+ *   tokens already looked up. This is what lets an adapter read per-install
+ *   configuration a template could not (`arg_template` expands from the CALLER's
+ *   arguments, so it can never see a resolved preference).
+ * - `callTool(args)` — invokes the provider's own [`CapabilityToolBinding::tool`]
+ *   and resolves to its raw response. It takes NO tool id: the target is fixed by
+ *   the manifest, so sandboxed code cannot redirect the call at another tool. An
+ *   adapter therefore grants no authority the declarative path did not already
+ *   grant — it is strictly the same single re-entry, expressed as code.
+ *
+ * It returns the canonical result shape, which the facade passes through unchanged.
+ *
+ * **Bounded by the sandbox wall-clock.** A run gets `DEFAULT_DEADLINE_SECS` of
+ * active compute, and time spent awaiting a tool call counts against it. An
+ * adapter that polls an async job must therefore treat "still running" as a normal
+ * outcome to report, not something to wait out.
+ */
+export interface CapabilityAdapter {
+	/**
+	 * The adapter body. Evaluated as the tail of a sandbox program that has already
+	 * bound `input`, `defaults`, `callTool` and `callNamed`; it `return`s the
+	 * canonical result.
+	 *
+	 * Empty in a **source** manifest that declares [`Self::code_file`] instead;
+	 * [`PluginManifest::hydrate_code_files`] fills it in at parse time and
+	 * [`PluginManifest::validate`] refuses a manifest where it is still empty.
+	 */
+	code?: string;
+	/**
+	 * Path to the file holding the adapter body, relative to the plugin root
+	 * (`adapters/<verb>.js`) — the authoring form. Mutually exclusive with
+	 * [`Self::code`]; see [`PluginManifest::hydrate_code_files`].
+	 */
+	code_file?: string | null;
+	/**
+	 * ADDITIONAL provider tool ids this adapter may call, beyond
+	 * [`CapabilityToolBinding::tool`], reachable from the body as
+	 * `callNamed(id, args)`.
+	 *
+	 * Exists because a whole class of real APIs is two calls, not one: an async job
+	 * API starts work at one endpoint and reads the result from another
+	 * (`POST /crawl` → job id → `GET /crawl/{id}`). A single-tool adapter cannot
+	 * express that, so those providers would stay unbindable — the gap that
+	 * excluded every async API from every layer.
+	 *
+	 * This is an ALLOWLIST fixed by the manifest and checked host-side: a name not
+	 * listed here (and not [`CapabilityToolBinding::tool`]) is refused. Sandboxed
+	 * code chooses only *among* tools the provider declared, never a tool of its
+	 * own — which is what keeps the id-taking form from becoming an escalation seam.
+	 */
+	tools?: string[];
+}
+/**
+ * Inclusive numeric bounds a provider can honour for one canonical argument.
+ * Integers, not floats. Every clampable canonical argument is a COUNT — result
+ * limits, crawl depth, page caps — so `i64` is the honest type, and it keeps the
+ * whole manifest tree `Eq` (a float would force `PartialEq`-only all the way up
+ * through `ProvidesEntry` and `PluginManifest`) while avoiding float comparison.
+ */
+export interface ArgBounds {
+	/**
+	 * Largest value the provider accepts. Absent = no upper bound.
+	 */
+	max?: number | null;
+	/**
+	 * Smallest value the provider accepts. Absent = no lower bound.
+	 */
+	min?: number | null;
+}
+/**
+ * Normalizes one provider's response into the capability's canonical shape.
+ *
+ * Deliberately a flat rename table rather than a general transform language: the
+ * canonical shapes are small and list-of-records shaped, and a manifest that can
+ * run arbitrary extraction logic is a much larger trust surface.
+ */
+export interface CapabilityResponseMap {
+	/**
+	 * Canonical per-item field name → the provider's field name (dotted paths
+	 * allowed). Fields with no entry are dropped from the canonical item but remain
+	 * available under the item's `raw` key.
+	 */
+	fields?: {
+		[k: string]: string;
+	};
+	/**
+	 * Dotted path to the provider's result array within its response (e.g.
+	 * `"results"`, `"data.items"`). Absent = the response itself is the array, or —
+	 * when it is not an array — a single record.
+	 */
+	results?: string | null;
+}
 /**
  * `requires` block — the plugin's **plugin-to-plugin** dependencies.
  *
@@ -719,7 +1924,7 @@ export interface CapabilityReq {
 	min_version?: string | null;
 }
 /**
- * A single Runnable entry inside a `plugin.json` manifest.
+ * A single Runnable entry inside a `manifest.json` manifest.
  *
  * Each entry carries the identity fields from [`crate::runnable::RunnableMeta`]
  * plus an optional typed config blob. The `kind` field drives which config shape
@@ -945,6 +2150,20 @@ export interface SidecarSpec {
 	 * How Core obtains and runs the process.
 	 */
 	process: BinarySpec | ExternalRuntimeConfig1 | LocalProcessSpec | NodeProcessSpec;
+	/**
+	 * Optional **model-provider** declaration: when present, this sidecar serves an
+	 * OpenAI-compatible endpoint and Core registers it as a selectable provider once
+	 * the process reports healthy, then deregisters it when the plugin is disabled or
+	 * uninstalled. This is what makes a third-party *auth bridge* possible without a
+	 * Core change: the plugin performs its own login/refresh, serves `/v1`, and
+	 * declares that fact here. Absent = the sidecar is not a model provider.
+	 *
+	 * A sidecar cannot self-register: it holds only `RYU_EXT_TOKEN` (scoped to the
+	 * ext-proxy hop and `/api/host/*`), and the host-RPC vocabulary has no
+	 * provider-registration method. Registration is therefore Core-side, driven by
+	 * this declaration.
+	 */
+	provides_provider?: ProviderRegistrationSpec | null;
 }
 /**
  * Declares the host-API grant subset a sidecar *process* may exercise via the
@@ -1069,6 +2288,47 @@ export interface LocalProcessSpec {
 export interface NodeProcessSpec {
 	kind: "node";
 }
+/**
+ * Declares that a [`SidecarSpec`] serves an OpenAI-compatible model endpoint Core
+ * should register as a provider while the sidecar is healthy.
+ *
+ * Security posture: the declared [`id`] is validated against the built-in provider
+ * table at registration and a collision is REFUSED, never merged. Without that guard
+ * a plugin could claim a built-in id (`openai-codex`, `anthropic`) and silently
+ * redirect the user's subscription traffic — and their live bearer token — to an
+ * attacker-controlled `baseUrl`. Core also stamps [`OWNER_FIELD`] into the written
+ * entry so deregistration can only ever remove an entry this plugin created.
+ *
+ * [`id`]: ProviderRegistrationSpec::id
+ * [`OWNER_FIELD`]: crate::schema::PROVIDER_OWNER_FIELD
+ */
+export interface ProviderRegistrationSpec {
+	/**
+	 * Pi `api` type the endpoint speaks. Defaults to `"openai-completions"`.
+	 */
+	api?: string | null;
+	/**
+	 * Path prefix appended to `http://127.0.0.1:<port>` to form the provider's
+	 * `baseUrl`. Defaults to `"/v1"`.
+	 */
+	base_path?: string | null;
+	/**
+	 * Provider id as it appears in the model picker. Must not collide with a built-in
+	 * provider id, and must be a safe single token (lowercase alphanumerics, `-`, `_`).
+	 */
+	id: string;
+	/**
+	 * Human-readable label for the picker. Defaults to [`id`] when absent.
+	 *
+	 * [`id`]: ProviderRegistrationSpec::id
+	 */
+	label?: string | null;
+	/**
+	 * Optional model ids to seed the entry with, for an endpoint whose `GET /models`
+	 * discovery is unavailable or slow. Absent = rely on discovery.
+	 */
+	models?: string[];
+}
 /**
  * One [`PluginManifest::surfaces`] entry: the support level plus an optional UI
  * descriptor the surface shell resolves (opaque here — pure data).
@@ -1083,7 +2343,7 @@ export interface SurfaceEntry {
 	/**
 	 * How much of the plugin this surface supports.
 	 */
-	support?: "full" | "limited" | "list" | "commands" | "none";
+	support?: "full" | "limited" | "list" | "commands" | "none" | "unknown";
 	/**
 	 * Optional surface-specific UI descriptor (bundle id, mount point, …),
 	 * interpreted by the surface's app host. Opaque to the contract.