docs: reconcile sandboxed plugin authoring guides (emdash-cms#3047)

* docs: correct unsafe deployment and recovery guidance

* docs: clarify safety guidance

* docs: trim repeated safety guidance

* docs: reconcile sandboxed plugin authoring guides

Author: ascorbic

docs/src/content/docs/plugins/creating-plugins/api-routes.mdx

@@ -12,7 +12,10 @@ EmDash's Block Kit lets sandboxed plugins describe their admin UI as JSON. The h
 </Aside>
 
 <Aside type="tip">
-	Block Kit elements are also used for [Portable Text block editing fields](/plugins/creating-native-plugins/portable-text-components/). When a plugin declares `fields` on a block type, the editor renders a Block Kit form for editing block data (URL, title, parameters, etc.).
+	Native plugins also use Block Kit elements to describe [Portable Text block editing
+	fields](/plugins/creating-native-plugins/portable-text-components/). Sandboxed plugins cannot
+	register custom Portable Text block types because their rendering components would need to load
+	into the host site at build time.
 </Aside>
 
 ## How it works
@@ -24,43 +27,77 @@ EmDash's Block Kit lets sandboxed plugins describe their admin UI as JSON. The h
 5. When the user interacts (clicks a button, submits a form), the admin sends the interaction back to the plugin.
 6. The plugin returns new blocks, and the cycle repeats.
 
-```typescript
-import type { SandboxedPlugin } from "emdash/plugin";
+Add `@emdash-cms/blocks` and `zod` to the plugin when it defines a Block Kit page:
+
+```sh
+pnpm add @emdash-cms/blocks zod
+```
 
-interface BlockInteraction {
-	type: "page_load" | "block_action" | "form_submit";
-	page?: string;
-	action_id?: string;
-	values?: Record<string, unknown>;
+Declare the page in the plugin manifest so the admin has a navigation entry to load:
+
+```jsonc title="emdash-plugin.jsonc"
+"admin": {
+	"pages": [{ "path": "/settings", "label": "Settings", "icon": "settings" }],
+}
+```
+
+The following `admin` route validates the interaction, renders a form on page load, and stores its values on submit:
+
+```typescript title="src/plugin.ts"
+import type { SandboxedPlugin } from "emdash/plugin";
+import type { BlockResponse } from "@emdash-cms/blocks";
+import { z } from "zod";
+
+const interactionSchema = z.discriminatedUnion("type", [
+	z.object({ type: z.literal("page_load"), page: z.string() }),
+	z.object({
+		type: z.literal("block_action"),
+		action_id: z.string(),
+		block_id: z.string().optional(),
+		value: z.unknown().optional(),
+	}),
+	z.object({
+		type: z.literal("form_submit"),
+		action_id: z.string(),
+		block_id: z.string().optional(),
+		values: z.object({ api_url: z.url(), enabled: z.boolean() }),
+	}),
+]);
+
+function renderSettings(): BlockResponse {
+	return {
+		blocks: [
+			{ type: "header", text: "Save Log settings" },
+			{
+				type: "form",
+				block_id: "settings",
+				fields: [
+					{ type: "text_input", action_id: "api_url", label: "API URL" },
+					{ type: "toggle", action_id: "enabled", label: "Enabled", initial_value: true },
+				],
+				submit: { label: "Save", action_id: "save" },
+			},
+		],
+	};
 }
 
 export default {
 	routes: {
 		admin: {
 			handler: async (routeCtx, ctx) => {
-				const interaction = routeCtx.input as BlockInteraction;
+				const parsed = interactionSchema.safeParse(routeCtx.input);
+				if (!parsed.success) return { blocks: [] };
+				const interaction = parsed.data;
 
 				if (interaction.type === "page_load") {
-					return {
-						blocks: [
-							{ type: "header", text: "My Plugin Settings" },
-							{
-								type: "form",
-								block_id: "settings",
-								fields: [
-									{ type: "text_input", action_id: "api_url", label: "API URL" },
-									{ type: "toggle", action_id: "enabled", label: "Enabled", initial_value: true },
-								],
-								submit: { label: "Save", action_id: "save" },
-							},
-						],
-					};
+					return renderSettings();
 				}
 
 				if (interaction.type === "form_submit" && interaction.action_id === "save") {
-					await ctx.kv.set("settings", interaction.values);
+					await ctx.kv.set("settings:apiUrl", interaction.values.api_url);
+					await ctx.kv.set("settings:enabled", interaction.values.enabled);
 					return {
-						blocks: [/* ... updated blocks ... */],
+						...renderSettings(),
 						toast: { message: "Settings saved", type: "success" },
 					};
 				}
@@ -72,7 +109,7 @@ export default {
 } satisfies SandboxedPlugin;
 ```
 
-The route handler takes two arguments: `routeCtx` (with `input`, `request`, `requestMeta`) and `ctx` (the `PluginContext`). `satisfies SandboxedPlugin` infers both.
+The `admin` route is private by default. EmDash sends the correct CSRF header when the admin calls it. The handler still validates `routeCtx.input` because its TypeScript type is `unknown` and a caller can invoke a private plugin route outside the Block Kit page.
 
 ## Block types
 
@@ -86,11 +123,16 @@ The route handler takes two arguments: `routeCtx` (with `input`, `request`, `req
 | `actions`   | Horizontal row of buttons and controls                                                  |
 | `stats`     | Dashboard metric cards with trend indicators                                            |
 | `form`      | Input fields with conditional visibility and submit                                     |
-| `image`     | Block-level image with caption                                                          |
+| `image`     | Block-level image with alt text and an optional title                                  |
 | `context`   | Small muted help text                                                                   |
 | `columns`   | 2–3 column layout with nested blocks                                                    |
-| `empty`     | Empty-state placeholder with icon, title, description, optional command line, and action buttons |
+| `empty`     | Empty-state title with an optional description, command, and action buttons            |
 | `accordion` | Collapsible section wrapping nested blocks                                              |
+| `chart`     | Line or bar time series, or a chart with custom options                                |
+| `banner`    | Status or alert message with a title or description                                     |
+| `meter`     | Numeric value displayed against a minimum and maximum                                   |
+| `code`      | Read-only TypeScript, TSX, JSONC, Bash, or CSS code                                     |
+| `tab`       | Labeled panels containing nested blocks                                                  |
 
 ## Element types
 
@@ -102,16 +144,22 @@ The route handler takes two arguments: `routeCtx` (with `input`, `request`, `req
 | `select`        | Dropdown select                              |
 | `toggle`        | On/off switch                                |
 | `secret_input`  | Masked input for API keys and tokens         |
+| `checkbox`      | Select several values from a fixed list      |
+| `combobox`      | Searchable single-value selection            |
+| `date_input`    | Date value                                   |
+| `radio`         | Single choice from a visible option list     |
+
+The Portable Text field editor also supports `repeater` and `media_picker`. They are not form fields for a sandboxed plugin admin page.
 
 ## Builder helpers
 
-The `@emdash-cms/blocks` package exports builder helpers for cleaner code:
+The `@emdash-cms/blocks` package exports the same shapes through `blocks` and `elements` builder objects. Builders reduce property-name mistakes while returning ordinary JSON-compatible objects:
 
 ```typescript
 import { blocks, elements } from "@emdash-cms/blocks";
 
-const { header, form, section, stats } = blocks;
-const { textInput, toggle, select, button } = elements;
+const { header, form } = blocks;
+const { textInput, toggle, select } = elements;
 
 return {
 	blocks: [
@@ -155,6 +203,8 @@ Form fields can be conditionally shown based on other field values:
 
 The `api_key` field only appears when `auth_enabled` is toggled on. Conditions are evaluated client-side with no round-trip.
 
+`secret_input` uses `has_value: true` to show that a value already exists; it does not accept or return the stored value on page load. The field masks typing in the browser, but it does not encrypt a value written to `ctx.kv`. Follow [Secret settings](/plugins/creating-plugins/settings/#secret-values) before storing credentials.
+
 ## Try it
 
 Use the [Block Playground](https://emdash-blocks.cto.cloudflare.dev/) to interactively build and test block layouts.

docs/src/content/docs/plugins/creating-plugins/block-kit.mdx

@@ -23,7 +23,7 @@ Capabilities live in `emdash-plugin.jsonc`, alongside `slug` and the rest of the
 }
 ```
 
-Declare only what the plugin actually needs. Capability declarations are also what the marketplace shows site operators on the consent dialog — extra capabilities are friction at install time and a security flag in audits.
+Declare only what the plugin actually needs. The marketplace shows these capabilities to site operators before installation, so every extra declaration asks them to approve access the plugin does not use.
 
 ## Capability reference
 
@@ -42,7 +42,7 @@ Declare only what the plugin actually needs. Capability declarations are also wh
 | `hooks.email-events:register`       | Allows registering `email:beforeSend` / `email:afterSend` hooks                   |
 | `hooks.page-fragments:register`     | Allows registering the `page:fragments` hook (native plugins only)                |
 
-A few things worth knowing:
+The following rules affect which capabilities a plugin needs:
 
 - **Implications.** `content:write` automatically implies `content:read`; `media:write` implies `media:read`; `network:request:unrestricted` implies `network:request`. You don't need to list both.
 - **Taxonomies are a separate, read-only surface.** `taxonomies:read` grants access to taxonomy definitions, their terms, and the terms assigned to an entry via `ctx.taxonomies`. It is independent of `content:read` — declare both if the plugin reads content *and* its classification. There is no taxonomy *write* access from plugins.
@@ -65,19 +65,19 @@ Locale matching is case-insensitive and stores the casing from the site's locale
 
 ## Network host allowlists
 
-Plugins with `network:request` can only fetch hosts listed in `allowedHosts`. Wildcards are supported for subdomains:
+Plugins with `network:request` can only fetch hosts listed in `allowedHosts`. A leading `*.` matches both the named domain and its subdomains:
 
 ```jsonc title="emdash-plugin.jsonc"
 "capabilities": ["network:request"],
 "allowedHosts": [
 	"api.example.com",     // exact host
-	"*.cdn.example.com"    // any subdomain of cdn.example.com
+	"*.cdn.example.com"    // cdn.example.com and any subdomain
 ]
 ```
 
 The bridge checks the request URL's host against the allowlist before forwarding the request. A request to a host that wasn't declared throws inside the plugin without ever leaving the sandbox.
 
-`network:request:unrestricted` skips the allowlist check entirely. It's intended for plugins where the operator configures the destination URL at runtime (webhook senders, generic HTTP forwarders). Avoid it for plugins where the destination is part of the plugin's design — declare `network:request` with explicit hosts instead, so the consent dialog tells operators exactly where the plugin is going to call.
+`network:request:unrestricted` skips the manifest host allowlist. The sandbox bridge still accepts only HTTP and HTTPS, blocks known internal hosts and private literal addresses, rechecks every redirect, and removes credential headers when a redirect crosses origins. Use unrestricted access only when an operator supplies the destination at runtime. For fixed destinations, declare `network:request` with explicit hosts so the consent dialog names them.
 
 ## What the sandbox enforces
 
@@ -87,37 +87,37 @@ When a sandbox runner is active, the runtime enforces:
 
 1. **Capability gating.** The PluginContext factory only populates `ctx.content`, `ctx.taxonomies`, `ctx.media`, `ctx.http`, `ctx.users`, `ctx.email` when the corresponding capability is declared. Calling a method on an undeclared capability isn't possible — there's no object there.
 
-2. **Storage and KV scoping.** Every storage and KV operation is scoped to the plugin's slug. A plugin can't read another plugin's KV or its storage collections, and it can only access storage collections it declared in the manifest.
+2. **Storage and KV scoping.** Every storage and KV operation is scoped to the runtime plugin ID. A plugin can't read another plugin's KV or storage collections, and it can access only collections declared in its manifest.
 
 3. **Network isolation.** Direct `fetch()` and other network primitives are blocked by the runner. The only way to reach the network is `ctx.http.fetch()`, which goes through the bridge's host validation.
 
 4. **No host bindings.** Sandboxed plugins don't see environment variables, the filesystem, or any platform bindings — even if your host worker has them. The plugin runtime is a clean isolate with only the bridge and the declared capabilities.
 
-5. **Resource limits.** The runner can enforce CPU, subrequest, wall-clock, and memory limits per invocation. The exact limits depend on which runner you're using; the Cloudflare runner uses the platform's Worker Loader limits (50ms CPU per invocation, 10 subrequests, 30 second wall-clock, ~128MB memory). The Node.js workerd runner (`@emdash-cms/sandbox-workerd`) enforces wall-clock time via `Promise.race`; CPU and memory limits are Cloudflare platform features and are not enforced by standalone workerd. Hooks that exceed the runner's limits are aborted; the EmDash hook timeout (`timeout` in the hook config) enforces a stricter ceiling on top of that.
+5. **Resource limits.** The Cloudflare runner defaults to 50 ms of CPU, 10 subrequests, and 30 seconds of wall time per invocation. Worker Loader enforces CPU and subrequests; the runner enforces wall time. Worker Loader has a platform memory ceiling, but its per-plugin `memoryMb` option is not currently enforceable. The Node.js workerd runner enforces only the 30-second wall-time default; it warns when a site configures CPU, memory, or subrequest limits that standalone workerd cannot enforce. A per-hook `timeout` applies only when the sandboxed-format plugin runs in process.
 
 </Steps>
 
 ## What the sandbox doesn't enforce
 
 A few things the capability system doesn't and can't cover:
 
-- **Behaviour within a granted capability.** A plugin with `content:write` can edit any content, not only its own. Capabilities are coarse — they say "this plugin can write content," not "this plugin can write only the content it created." Audit-time review is the only check on what a plugin actually does within its grant.
-- **Entry edit locks.** `ctx.content.update()` writes through an entry's [edit lock](/reference/rest-api/#entry-edit-lock), so an editor who has that entry open in the admin does not stop a plugin write. `ctx.content.delete()` behaves the same way, and releases the lock along with the entry it trashes.
+- **Behaviour within a granted capability.** A plugin with `content:write` can edit any content, not only its own. Capabilities are coarse — they say "this plugin can write content," not "this plugin can write only the content it created." An operator must evaluate the plugin's code and publisher before granting that access.
+- **Entry edit locks.** `ctx.content.update()` and `ctx.content.delete()` are programmatic writes. An editor holding the entry's advisory edit lock does not block them. Coordinate plugin writes with editors when both may update the same entry.
 - **Operator trust on Node.js.** When the configured sandbox runner reports unavailable (no Cloudflare Worker Loader, no Node-side runner installed, etc.), `sandboxed: []` plugins are skipped at startup. You can move them into `plugins: []` to run them in-process — but then there's no V8 isolate, no resource limits, and the plugin can call `fetch()` directly or read environment variables. Treat that as native-level trust.
 - **Side channels.** Timing, log output, and stored data are all visible to anyone with appropriate access to the host environment. Don't use the sandbox as a confidentiality boundary against the operator running it.
 
 ## Capability consent
 
 When an operator installs a sandboxed plugin from the marketplace, EmDash shows a consent dialog listing the declared capabilities. Updates that add capabilities — for example, a plugin that previously only read content now wants to make network requests — surface as a capability diff and require fresh approval before the new version takes effect.
 
-This is why declaring extra capabilities matters even if you "might use them later". They show up as friction at every install and update, and security audits flag plugins that ask for more than they obviously need. List exactly what the plugin uses, and add new capabilities in a real version when the plugin actually starts using them.
+Declaring capabilities for possible future use makes every installation or update ask for unnecessary access. List what the current version uses, then add a capability in the version that starts using it.
 
 ## Bundle-time validation
 
 `emdash-plugin bundle` and `emdash-plugin publish` perform additional checks:
 
 - Every declared capability must be in the recognised set (typos fail the build).
-- `network:request` requires a non-empty `allowedHosts`; `network:request:unrestricted` requires it to be empty. See [the manifest reference](/plugins/creating-plugins/manifest/#capabilities).
+- `network:request` requires a non-empty `allowedHosts`; `network:request:unrestricted` requires it to be empty. See [Capabilities and hosts](/plugins/creating-plugins/manifest/#capabilities-and-hosts).
 - The bundled `backend.js` can't import Node.js built-ins (`fs`, `path`, `child_process`, etc.) — sandbox runtimes don't provide them.
 
-See [Bundling and publishing](/plugins/creating-plugins/publishing/) for the full list of checks.
+See [the manifest reference](/plugins/creating-plugins/manifest/#trust-contract) for the authoring fields and [Bundling and publishing](/plugins/creating-plugins/publishing/#validation) for bundle checks.