@abinnovision/payloadcms-mcpx 2.0.0-beta.14 → 2.0.0-beta.16

package/README.md

@@ -86,25 +86,25 @@ Claude Desktop and the MCP Inspector are covered in
 
 ## Options
 
-| Option                       | Default                                   | Description                                                                                                                         |
-| ---------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `collections`                | required                                  | Collections to expose. `true` means `{}`, everything it supports.                                                                   |
-| `collections.<slug>.read`    | `true`                                    | Expose the read tools for this collection.                                                                                          |
-| `collections.<slug>.write`   | `true`                                    | Expose the write tools. Without drafts, a write goes live.                                                                          |
-| `collections.<slug>.publish` | `true` with drafts                        | Expose `publishDocument`. Needs `versions.drafts` and `write`.                                                                      |
-| `collections.<slug>.delete`  | `false`                                   | Expose `deleteDocument`. Each delete is approved in the admin. `"unattended"` also offers trashing without approval; needs `trash`. |
-| `globals`                    | `{}`                                      | Globals to expose, with `read`, `write` and `publish`.                                                                              |
-| `userCollection`             | `config.admin.user`, then `users`         | Auth collection whose users the keys act as.                                                                                        |
-| `apiKeys.slug`               | `mcpx-api-keys`                           | Slug of the key collection.                                                                                                         |
-| `apiKeys.setupGuide`         | `true`                                    | Add the "Connect a client" tab to saved keys.                                                                                       |
-| `apiKeys.overrideCollection` | none                                      | Function that receives the key collection and returns it.                                                                           |
-| `endpoint.path`              | `/mcpx`                                   | Endpoint path below the API route.                                                                                                  |
-| `limits.maxLimit`            | `25`                                      | Highest `limit` a client may pass to a list tool.                                                                                   |
-| `limits.maxDepth`            | `1`                                       | Highest `depth` a client may pass to a read tool.                                                                                   |
-| `tools`                      | `[]`                                      | Custom tools, see [`docs/custom-tools.md`](./docs/custom-tools.md).                                                                 |
-| `auth.resolve`               | none                                      | Replace or wrap the key lookup.                                                                                                     |
-| `serverInfo`                 | `payloadcms-mcpx` and the package version | `{ name, version }` reported to clients.                                                                                            |
-| `diagnostics`                | `true`                                    | Expose the server version plus repository and issue links.                                                                          |
+| Option                       | Default                                   | Description                                                                                                                                       |
+| ---------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collections`                | required                                  | Collections to expose. `true` means `{}`, everything it supports.                                                                                 |
+| `collections.<slug>.read`    | `true`                                    | Expose the read tools for this collection.                                                                                                        |
+| `collections.<slug>.write`   | `true`                                    | Expose the write tools. Needs `read`. Without drafts, a write goes live.                                                                          |
+| `collections.<slug>.publish` | `true` with drafts                        | Expose `publishDocument`. Needs `versions.drafts` and `write`.                                                                                    |
+| `collections.<slug>.delete`  | `false`                                   | Expose `deleteDocument`. Needs `read`. Each delete is approved in the admin. `"unattended"` also offers trashing without approval; needs `trash`. |
+| `globals`                    | `{}`                                      | Globals to expose, with `read`, `write` and `publish`.                                                                                            |
+| `userCollection`             | `config.admin.user`, then `users`         | Auth collection whose users the keys act as.                                                                                                      |
+| `apiKeys.slug`               | `mcpx-api-keys`                           | Slug of the key collection.                                                                                                                       |
+| `apiKeys.setupGuide`         | `true`                                    | Add the "Connect a client" tab to saved keys.                                                                                                     |
+| `apiKeys.overrideCollection` | none                                      | Function that receives the key collection and returns it.                                                                                         |
+| `endpoint.path`              | `/mcpx`                                   | Endpoint path below the API route.                                                                                                                |
+| `limits.maxLimit`            | `25`                                      | Highest `limit` a client may pass to a list tool.                                                                                                 |
+| `limits.maxDepth`            | `1`                                       | Highest `depth` a client may pass to a read tool.                                                                                                 |
+| `tools`                      | `[]`                                      | Custom tools, see [`docs/custom-tools.md`](./docs/custom-tools.md).                                                                               |
+| `auth.resolve`               | none                                      | Replace or wrap the key lookup.                                                                                                                   |
+| `serverInfo`                 | `payloadcms-mcpx` and the package version | `{ name, version }` reported to clients.                                                                                                          |
+| `diagnostics`                | `true`                                    | Expose the server version plus repository and issue links.                                                                                        |
 
 The config only takes capabilities away: `true` exposes everything the entity supports, and a key's
 checkboxes decide what each key may do. `publish: false` keeps MCP writes as drafts. On an entity
@@ -116,19 +116,19 @@ every check.
 
 ## Tools
 
-| Tool               | What it does                                                       | Needs              |
-| ------------------ | ------------------------------------------------------------------ | ------------------ |
-| `listCapabilities` | Lists what this key may do. Clients call it first.                 | any key            |
-| `describeSchema`   | Describes the fields at one schema path, with the paths below it.  | `read`             |
-| `findDocuments`    | Queries a collection with a Payload `where`, `sort` and `select`.  | `read`             |
-| `getDocument`      | Reads a document, a subtree of it, an old version or a diff.       | `read`             |
-| `findVersions`     | Lists the version history of a document or global, without bodies. | `read`             |
-| `patchDocument`    | Applies JSON Patch operations to the current draft, or a new file. | `write`            |
-| `createDocument`   | Creates a draft from a seed, with a file in an upload collection.  | `write`            |
-| `validateDocument` | Lists what blocks publishing, without saving.                      | `write`            |
-| `publishDocument`  | Publishes the current draft.                                       | `write`, `publish` |
-| `deleteDocument`   | Asks to delete a document, which the key's user approves.          | `delete`           |
-| `runConfirmed`     | Runs the approved calls.                                           | `delete`           |
+| Tool               | What it does                                                       | Needs     |
+| ------------------ | ------------------------------------------------------------------ | --------- |
+| `listCapabilities` | Lists what this key may do. Clients call it first.                 | any key   |
+| `describeSchema`   | Describes the fields at one schema path, with the paths below it.  | `read`    |
+| `findDocuments`    | Queries a collection with a Payload `where`, `sort` and `select`.  | `read`    |
+| `getDocument`      | Reads a document, a subtree of it, an old version or a diff.       | `read`    |
+| `findVersions`     | Lists the version history of a document or global, without bodies. | `read`    |
+| `patchDocument`    | Applies JSON Patch operations to the current draft, or a new file. | `write`   |
+| `createDocument`   | Creates a draft from a seed, with a file in an upload collection.  | `write`   |
+| `validateDocument` | Lists what blocks publishing, without saving.                      | `write`   |
+| `publishDocument`  | Publishes the current draft.                                       | `publish` |
+| `deleteDocument`   | Asks to delete a document, which the key's user approves.          | `delete`  |
+| `runConfirmed`     | Runs the approved calls.                                           | `delete`  |
 
 Collections and globals use the same tools. A tool that addresses one document takes either
 `collection` and `id`, or `global` alone. [`docs/concepts.md`](./docs/concepts.md#tools) lists
@@ -142,15 +142,18 @@ The plugin config sets the upper bound: which collections and globals are expose
 each one is readable, writable and publishable. A key cannot go past it.
 
 Each key carries one checkbox per exposed entity and operation (`read`, `write`, `publish`,
-`delete`), and
-one per custom tool. The admin panel shows them as a matrix with a row per entity and a column per
-operation. A cell the config does not expose shows a dash. `publish` exists only where the config
-exposes `write` and `publish` on an entity with drafts, and counts only when `write` is ticked as
-well. A write checkbox on an entity without drafts is marked "Writes go live immediately."
+`delete`, `deleteUnattended`), and
+one per custom tool. The admin panel shows them as a matrix with a row per entity, an Access
+control (None, Read, Write, Publish) and a Delete control (Off, Approval, Trash). Each access level
+includes the ones before it, and a level the config does not expose has no segment. `publish`
+exists only where the config exposes `write` and `publish` on an entity with drafts, and counts
+only when `write` is ticked as well. `write` counts only when `read` is ticked, so a key never
+writes what it cannot read. An entity without drafts carries a "Live" badge, as its writes go live
+immediately.
 `delete` exists only where the config sets `delete: true` on a collection, and counts only when
-`read` is ticked as well. The row toggle leaves it alone. A delete runs only after the key's user
+`read` is ticked as well. Setting access to None clears it. A delete runs only after the key's user
 approved it on the key's edit view, except where the config sets `delete: "unattended"` and the
-key ticks "Delete without approval": there the document moves to trash at once. See
+key's Delete control is set to Trash: there the document moves to trash at once. See
 [deleting](./docs/concepts.md#deleting).
 
 `tools/list` follows the key. A tool the key cannot use is not listed, and each `collection` and

package/dist/admin/capability-matrix.d.mts

@@ -25,9 +25,10 @@ interface McpxCapabilityMatrixProps {
   withinTab?: boolean;
 }
 /**
- * What an API key may do, as one table per namespace: a row per entity, a
- * column per operation and a bulk toggle in each column header. The nested
- * checkbox fields back every cell, so the stored document is unaffected.
+ * What an API key may do, as one table per namespace: a row per entity with
+ * segmented Access and Delete controls, and an "All" row that sets every row.
+ * The nested checkbox fields back every control, so the stored document is
+ * unaffected.
  */
 export declare const McpxCapabilityMatrix: React.FC<McpxCapabilityMatrixProps>;
 //#endregion

package/dist/admin/capability-matrix.mjs

@@ -1,17 +1,28 @@
 "use client";
 import { CAPABILITIES_FIELD } from "../capabilities.mjs";
-import { CAPABILITY_OPERATIONS, capabilityPaths, cellPath, toolPath } from "../api-keys/capability-matrix.mjs";
-import { buildToggleActions, columnState, rowState, toolsState } from "./capability-toggles.mjs";
+import { CAPABILITY_OPERATIONS, STORED_OPERATIONS, capabilityPaths, toolPath } from "../api-keys/capability-matrix.mjs";
+import { accessLevelOf, accessLevelsOf, allAccessLevel, allDeleteMode, buildToggleActions, deleteModeOf, toolsState } from "./capability-toggles.mjs";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { CheckboxInput, FieldDescription, FieldLabel, useForm, useFormFields } from "@payloadcms/ui";
+import { Button, CheckboxInput, FieldDescription, FieldLabel, Pill, useForm, useFormFields } from "@payloadcms/ui";
 import { useCallback, useMemo } from "react";
 //#region src/admin/capability-matrix.tsx
-const NOT_EXPOSED = "The plugin config does not expose this.";
 const BASE_CLASS = "mcpx-capabilities";
+const LIVE_WRITE = "Writes go live immediately.";
 const SHEET = `
 .${BASE_CLASS} tbody tr:hover { background: var(--theme-elevation-50); }
-.${BASE_CLASS}__toggle:hover { text-decoration: underline; }
 .${BASE_CLASS} section:last-of-type { margin-bottom: 0; }
+.${BASE_CLASS}__segments {
+	display: inline-flex;
+	border: 1px solid var(--theme-elevation-150);
+	border-radius: var(--style-radius-s);
+	background: var(--theme-input-bg);
+}
+.${BASE_CLASS}__segments .btn { border: 0; border-radius: 0; white-space: nowrap; }
+.${BASE_CLASS}__segments .btn + .btn { border-inline-start: 1px solid var(--theme-elevation-150); }
+.${BASE_CLASS}__segments .btn:first-child { border-start-start-radius: inherit; border-end-start-radius: inherit; }
+.${BASE_CLASS}__segments .btn:last-child { border-start-end-radius: inherit; border-end-end-radius: inherit; }
+.${BASE_CLASS}__segments .btn--style-transparent { --hover-bg: var(--theme-elevation-100); }
+.${BASE_CLASS}__segments .${BASE_CLASS}__danger { --bg-color: var(--theme-error-500); --hover-bg: var(--theme-error-600); }
 `;
 const CELL_PADDING = "calc(var(--base) * 0.6)";
 const EDGE_PADDING = "calc(var(--base) * 0.8)";
@@ -57,30 +68,35 @@ const styles = {
 		fontWeight: "normal",
 		wordBreak: "break-word"
 	},
-	rowButton: {
-		padding: 0,
-		border: 0,
-		background: "none",
-		color: "inherit",
-		font: "inherit",
-		cursor: "pointer",
-		textAlign: "start",
-		textDecoration: "none"
-	},
 	hint: {
 		display: "block",
 		color: "var(--theme-elevation-400)"
 	},
+	badge: {
+		display: "inline-flex",
+		marginInlineStart: "calc(var(--base) * 0.4)",
+		verticalAlign: "middle",
+		cursor: "help"
+	},
+	visuallyHidden: {
+		position: "absolute",
+		width: "1px",
+		height: "1px",
+		overflow: "hidden",
+		clip: "rect(0 0 0 0)",
+		whiteSpace: "nowrap"
+	},
 	cell: {
 		padding: CELL_PADDING,
 		verticalAlign: "middle",
 		textAlign: "center"
 	},
-	lastCell: { paddingInlineEnd: EDGE_PADDING },
-	dash: {
-		color: "var(--theme-elevation-400)",
-		cursor: "help"
-	}
+	controlCell: {
+		padding: CELL_PADDING,
+		verticalAlign: "middle",
+		textAlign: "start"
+	},
+	lastCell: { paddingInlineEnd: EDGE_PADDING }
 };
 const Box = ({ label, onChange, readOnly, state }) => /*#__PURE__*/ jsx(CheckboxInput, {
 	checked: state === "on",
@@ -89,116 +105,250 @@ const Box = ({ label, onChange, readOnly, state }) => /*#__PURE__*/ jsx(Checkbox
 	partialChecked: state === "mixed",
 	readOnly
 });
+const descriptionOf = (operation) => STORED_OPERATIONS.find((candidate) => candidate.id === operation)?.description;
+const ACCESS_OPTIONS = [{
+	id: "none",
+	label: "None",
+	title: "No access"
+}, ...CAPABILITY_OPERATIONS.filter((operation) => operation.id !== "delete").map((operation) => ({
+	id: operation.id,
+	label: operation.label,
+	title: operation.description
+}))];
+const DELETE_OPTIONS = [
+	{
+		id: "off",
+		label: "Off",
+		title: "No delete"
+	},
+	{
+		id: "approve",
+		label: "Approval",
+		title: descriptionOf("delete")
+	},
+	{
+		id: "trash",
+		label: "Trash",
+		title: descriptionOf("deleteUnattended")
+	}
+];
+const ARROW_STEPS = {
+	ArrowDown: 1,
+	ArrowLeft: -1,
+	ArrowRight: 1,
+	ArrowUp: -1
+};
+const Segments = ({ included = [], label, onSelect, options, readOnly, selected }) => {
+	const focusable = options.some((option) => option.id === selected) ? selected : options[0]?.id;
+	const onKeyDown = (event) => {
+		const step = ARROW_STEPS[event.key];
+		if (readOnly || step === void 0) return;
+		event.preventDefault();
+		const radios = [...event.currentTarget.querySelectorAll("[role=\"radio\"]")];
+		const current = radios.findIndex((radio) => radio === document.activeElement);
+		const next = Math.min(Math.max(current + step, 0), radios.length - 1);
+		const option = options[next];
+		if (option) {
+			radios[next]?.focus();
+			onSelect(option.id);
+		}
+	};
+	return /*#__PURE__*/ jsx("div", {
+		"aria-label": label,
+		className: `${BASE_CLASS}__segments`,
+		onKeyDown,
+		role: "radiogroup",
+		children: options.map((option) => {
+			const checked = option.id === selected;
+			return /*#__PURE__*/ jsx(Button, {
+				buttonStyle: checked ? "primary" : included.includes(option.id) ? "pill" : "transparent",
+				className: checked && option.id === "trash" ? `${BASE_CLASS}__danger` : "",
+				disabled: readOnly,
+				extraButtonProps: {
+					"aria-checked": checked,
+					role: "radio",
+					tabIndex: option.id === focusable ? 0 : -1,
+					title: option.title
+				},
+				margin: false,
+				onClick: () => {
+					onSelect(option.id);
+				},
+				size: "small",
+				children: option.label
+			}, option.id);
+		})
+	});
+};
+const includedBelow = (options, level) => {
+	const selected = options.findIndex((option) => option.id === level);
+	return selected < 1 ? [] : options.slice(1, selected).map((option) => option.id);
+};
+const accessOptions = (rows) => ACCESS_OPTIONS.filter((option) => rows.some((row) => accessLevelsOf(row).includes(option.id)));
 const LABEL_WIDTH = "calc(var(--base) * 9)";
 const OPERATION_WIDTH = "calc(var(--base) * 3.5)";
-const Columns = ({ count }) => /*#__PURE__*/ jsxs("colgroup", { children: [/*#__PURE__*/ jsx("col", { style: { width: LABEL_WIDTH } }), Array.from({ length: count }, (_, index) => /*#__PURE__*/ jsx("col", { style: { width: OPERATION_WIDTH } }, index))] });
-const cellStyle = (isLast) => isLast ? {
+const ACCESS_WIDTH = "calc(var(--base) * 13)";
+const DELETE_WIDTH = "calc(var(--base) * 10)";
+const Columns = ({ widths }) => /*#__PURE__*/ jsxs("colgroup", { children: [/*#__PURE__*/ jsx("col", { style: { width: LABEL_WIDTH } }), widths.map((width, index) => /*#__PURE__*/ jsx("col", { style: { width } }, index))] });
+const lastCellStyle = {
 	...styles.cell,
 	...styles.lastCell
-} : styles.cell;
-const Dash = () => /*#__PURE__*/ jsx("span", {
-	"aria-label": NOT_EXPOSED,
-	style: styles.dash,
-	title: NOT_EXPOSED,
-	children: "—"
+};
+const controlStyle = (isLast) => isLast ? {
+	...styles.controlCell,
+	...styles.lastCell
+} : styles.controlCell;
+const LiveBadge = () => /*#__PURE__*/ jsx("span", {
+	style: styles.badge,
+	title: LIVE_WRITE,
+	children: /*#__PURE__*/ jsxs(Pill, {
+		pillStyle: "warning",
+		size: "small",
+		children: [/*#__PURE__*/ jsx("span", {
+			"aria-hidden": "true",
+			children: "Live"
+		}), /*#__PURE__*/ jsx("span", {
+			style: styles.visuallyHidden,
+			children: LIVE_WRITE
+		})]
+	})
 });
 const NamespaceTable = ({ matrix, namespace, path, readOnly, toggle, values }) => {
 	const rows = matrix[namespace.id];
-	const columns = CAPABILITY_OPERATIONS.filter((operation) => rows.some((row) => row[operation.id]));
+	const withDelete = rows.some((row) => row.delete);
+	const allOptions = accessOptions(rows);
+	const allLevel = allAccessLevel(matrix, path, namespace.id, values);
+	const entries = namespace.title.toLowerCase();
 	return /*#__PURE__*/ jsx("section", {
 		style: styles.section,
 		children: /*#__PURE__*/ jsxs("table", {
 			style: styles.table,
 			children: [
-				/*#__PURE__*/ jsx(Columns, { count: columns.length }),
+				/*#__PURE__*/ jsx(Columns, { widths: withDelete ? [ACCESS_WIDTH, DELETE_WIDTH] : [ACCESS_WIDTH] }),
 				/*#__PURE__*/ jsxs("thead", {
 					style: styles.head,
-					children: [/*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsx("th", {
-						scope: "col",
-						style: {
-							...styles.headTitle,
-							...styles.topStart
-						},
-						children: namespace.title
-					}), columns.map((operation, column) => /*#__PURE__*/ jsx("th", {
-						scope: "col",
-						style: column === columns.length - 1 ? {
-							...styles.headOperation,
-							...styles.topEnd
-						} : styles.headOperation,
-						title: operation.description,
-						children: operation.label
-					}, operation.id))] }), /*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsx("th", {
-						scope: "row",
-						style: {
-							...styles.headLabel,
-							...styles.rule
-						},
-						children: "All"
-					}), columns.map((operation, column) => {
-						const state = columnState(matrix, path, namespace.id, operation.id, values);
-						return /*#__PURE__*/ jsx("td", {
+					children: [/*#__PURE__*/ jsxs("tr", { children: [
+						/*#__PURE__*/ jsx("th", {
+							scope: "col",
 							style: {
-								...cellStyle(column === columns.length - 1),
+								...styles.headTitle,
+								...styles.topStart
+							},
+							children: namespace.title
+						}),
+						/*#__PURE__*/ jsx("th", {
+							scope: "col",
+							style: {
+								...styles.headOperation,
+								textAlign: "start",
+								...withDelete ? {} : styles.topEnd
+							},
+							children: "Access"
+						}),
+						withDelete ? /*#__PURE__*/ jsx("th", {
+							scope: "col",
+							style: {
+								...styles.headOperation,
+								textAlign: "start",
+								...styles.topEnd
+							},
+							children: "Delete"
+						}) : null
+					] }), /*#__PURE__*/ jsxs("tr", { children: [
+						/*#__PURE__*/ jsx("th", {
+							scope: "row",
+							style: {
+								...styles.headLabel,
 								...styles.rule
 							},
-							children: /*#__PURE__*/ jsx(Box, {
-								label: `${operation.label} every ${namespace.title.toLowerCase()} entry`,
-								onChange: () => {
+							children: "All"
+						}),
+						/*#__PURE__*/ jsx("td", {
+							style: {
+								...controlStyle(!withDelete),
+								...styles.rule
+							},
+							children: /*#__PURE__*/ jsx(Segments, {
+								included: includedBelow(allOptions, allLevel),
+								label: `Access for every ${entries} entry`,
+								onSelect: (level) => {
 									toggle({
-										kind: "column",
+										kind: "access",
 										namespace: namespace.id,
-										operation: operation.id,
-										value: state !== "on"
+										level
 									});
 								},
+								options: allOptions,
 								readOnly,
-								state
+								selected: allLevel
 							})
-						}, operation.id);
-					})] })]
+						}),
+						withDelete ? /*#__PURE__*/ jsx("td", {
+							style: {
+								...controlStyle(true),
+								...styles.rule
+							},
+							children: /*#__PURE__*/ jsx(Segments, {
+								label: `Delete for every ${entries} entry`,
+								onSelect: (mode) => {
+									toggle({
+										kind: "deleteMode",
+										namespace: namespace.id,
+										mode
+									});
+								},
+								options: DELETE_OPTIONS.filter((option) => option.id !== "trash"),
+								readOnly,
+								selected: allDeleteMode(matrix, path, namespace.id, values)
+							})
+						}) : null
+					] })]
 				}),
 				/*#__PURE__*/ jsx("tbody", { children: rows.map((row) => {
-					const state = rowState(path, namespace.id, row, values);
-					return /*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsxs("th", {
-						scope: "row",
-						style: styles.rowHeader,
-						children: [/*#__PURE__*/ jsx("button", {
-							className: `${BASE_CLASS}__toggle`,
-							disabled: readOnly,
-							onClick: () => {
-								toggle({
-									kind: "row",
-									namespace: namespace.id,
-									fieldName: row.fieldName,
-									value: state !== "on"
-								});
-							},
-							style: styles.rowButton,
-							title: `Toggle every capability for ${row.label}`,
-							type: "button",
-							children: row.label
-						}), row.hint ? /*#__PURE__*/ jsx("span", {
-							style: styles.hint,
-							children: row.hint
-						}) : null]
-					}), columns.map((operation, column) => /*#__PURE__*/ jsx("td", {
-						style: cellStyle(column === columns.length - 1),
-						children: row[operation.id] ? /*#__PURE__*/ jsx(Box, {
-							label: `${operation.label} ${row.label}`,
-							onChange: () => {
-								toggle({
-									kind: "cell",
-									namespace: namespace.id,
-									fieldName: row.fieldName,
-									operation: operation.id,
-									value: values[cellPath(path, namespace.id, row.fieldName, operation.id)] !== true
-								});
-							},
-							readOnly,
-							state: values[cellPath(path, namespace.id, row.fieldName, operation.id)] === true ? "on" : "off"
-						}) : /*#__PURE__*/ jsx(Dash, {})
-					}, operation.id))] }, row.fieldName);
+					const options = accessOptions([row]);
+					const level = accessLevelOf(path, namespace.id, row, values);
+					return /*#__PURE__*/ jsxs("tr", { children: [
+						/*#__PURE__*/ jsxs("th", {
+							scope: "row",
+							style: styles.rowHeader,
+							children: [row.label, row.live ? /*#__PURE__*/ jsx(LiveBadge, {}) : null]
+						}),
+						/*#__PURE__*/ jsx("td", {
+							style: controlStyle(!withDelete),
+							children: /*#__PURE__*/ jsx(Segments, {
+								included: includedBelow(options, level),
+								label: `Access for ${row.label}`,
+								onSelect: (next) => {
+									toggle({
+										kind: "access",
+										namespace: namespace.id,
+										fieldName: row.fieldName,
+										level: next
+									});
+								},
+								options,
+								readOnly,
+								selected: level
+							})
+						}),
+						withDelete ? /*#__PURE__*/ jsx("td", {
+							style: controlStyle(true),
+							children: row.delete ? /*#__PURE__*/ jsx(Segments, {
+								label: `Delete for ${row.label}`,
+								onSelect: (mode) => {
+									toggle({
+										kind: "deleteMode",
+										namespace: namespace.id,
+										fieldName: row.fieldName,
+										mode
+									});
+								},
+								options: DELETE_OPTIONS.filter((option) => option.id !== "trash" || row.deleteUnattended),
+								readOnly,
+								selected: deleteModeOf(path, namespace.id, row, values)
+							}) : null
+						}) : null
+					] }, row.fieldName);
 				}) })
 			]
 		})
@@ -211,7 +361,7 @@ const ToolsTable = ({ matrix, path, readOnly, toggle, values }) => {
 		children: /*#__PURE__*/ jsxs("table", {
 			style: styles.table,
 			children: [
-				/*#__PURE__*/ jsx(Columns, { count: 1 }),
+				/*#__PURE__*/ jsx(Columns, { widths: [OPERATION_WIDTH] }),
 				/*#__PURE__*/ jsxs("thead", {
 					style: styles.head,
 					children: [/*#__PURE__*/ jsxs("tr", { children: [/*#__PURE__*/ jsx("th", {
@@ -237,7 +387,7 @@ const ToolsTable = ({ matrix, path, readOnly, toggle, values }) => {
 						children: "All"
 					}), /*#__PURE__*/ jsx("td", {
 						style: {
-							...cellStyle(true),
+							...lastCellStyle,
 							...styles.rule
 						},
 						children: /*#__PURE__*/ jsx(Box, {
@@ -261,7 +411,7 @@ const ToolsTable = ({ matrix, path, readOnly, toggle, values }) => {
 						children: tool.description
 					})]
 				}), /*#__PURE__*/ jsx("td", {
-					style: cellStyle(true),
+					style: lastCellStyle,
 					children: /*#__PURE__*/ jsx(Box, {
 						label: `Enable ${tool.name}`,
 						onChange: () => {
@@ -280,9 +430,10 @@ const ToolsTable = ({ matrix, path, readOnly, toggle, values }) => {
 	});
 };
 /**
-* What an API key may do, as one table per namespace: a row per entity, a
-* column per operation and a bulk toggle in each column header. The nested
-* checkbox fields back every cell, so the stored document is unaffected.
+* What an API key may do, as one table per namespace: a row per entity with
+* segmented Access and Delete controls, and an "All" row that sets every row.
+* The nested checkbox fields back every control, so the stored document is
+* unaffected.
 */ const McpxCapabilityMatrix = ({ field, matrix, path = CAPABILITIES_FIELD, readOnly = false, withinTab = false }) => {
 	const { dispatchFields, setModified } = useForm();
 	const paths = useMemo(() => capabilityPaths(matrix, path), [matrix, path]);

package/dist/admin/capability-toggles.mjs

@@ -1,60 +1,59 @@
-import { CAPABILITY_OPERATIONS, cellPath, toolPath } from "../api-keys/capability-matrix.mjs";
+import { STORED_OPERATIONS, cellPath, toolPath } from "../api-keys/capability-matrix.mjs";
 //#region src/admin/capability-toggles.ts
-const stateOf = (paths, values) => {
-	if (paths.length === 0) return "off";
-	const granted = paths.filter((path) => values[path] === true).length;
+/**
+* How far a key may go with an entity. Each level includes the ones before it.
+*/ const ACCESS_LEVELS = [
+	"none",
+	"read",
+	"write",
+	"publish"
+];
+const toolsState = (matrix, basePath, values) => {
+	const granted = matrix.tools.filter((tool) => values[toolPath(basePath, tool.name)] === true).length;
 	if (granted === 0) return "off";
-	return granted === paths.length ? "on" : "mixed";
+	return granted === matrix.tools.length ? "on" : "mixed";
 };
 /**
-* Whether a column's bulk toggle reads as on, off or indeterminate. Cells the
-* config does not expose are ignored: two granted cells and one dash read as on.
-*/ const columnState = (matrix, basePath, namespace, operation, values) => stateOf(matrix[namespace].filter((row) => row[operation]).map((row) => cellPath(basePath, namespace, row.fieldName, operation)), values);
-const ROW_OPERATIONS = CAPABILITY_OPERATIONS.filter((operation) => operation.id !== "delete" && operation.id !== "deleteUnattended");
+* The levels a row offers: none, then each operation the config exposes.
+*/ const accessLevelsOf = (row) => ACCESS_LEVELS.filter((level) => level === "none" || row[level]);
 /**
-* Whether an entity's row toggle reads as on, off or indeterminate, over the
-* operations the config exposes for that row, deletes aside.
-*/ const rowState = (basePath, namespace, row, values) => stateOf(ROW_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)), values);
-const toolsState = (matrix, basePath, values) => stateOf(matrix.tools.map((tool) => toolPath(basePath, tool.name)), values);
+* The highest level whose flags are all granted, counting only operations the
+* config exposes. A write without a read reads as none, as on the server.
+*/ const accessLevelOf = (basePath, namespace, row, values) => {
+	let reached = "none";
+	for (const level of ACCESS_LEVELS) {
+		if (level === "none") continue;
+		if (!row[level] || values[cellPath(basePath, namespace, row.fieldName, level)] !== true) break;
+		reached = level;
+	}
+	return reached;
+};
+/**
+* The delete mode a row's stored flags read as.
+*/ const deleteModeOf = (basePath, namespace, row, values) => {
+	const granted = (operation) => values[cellPath(basePath, namespace, row.fieldName, operation)] === true;
+	if (!granted("read") || !granted("delete")) return "off";
+	return row.deleteUnattended && granted("deleteUnattended") ? "trash" : "approve";
+};
+const requiresOf = (operation) => {
+	const found = STORED_OPERATIONS.find((candidate) => candidate.id === operation);
+	return found && "requires" in found ? found.requires : void 0;
+};
+const prerequisitesOf = (operation) => {
+	const required = requiresOf(operation);
+	return required ? [required, ...prerequisitesOf(required)] : [];
+};
 const reconcile = (next, touched) => {
-	let result = next;
-	if (touched.has("publish") && result.publish) result = {
-		...result,
-		write: true
-	};
-	if (touched.has("write") && !result.write) result = {
-		...result,
-		publish: false
-	};
-	if (touched.has("deleteUnattended") && result.deleteUnattended) result = {
-		...result,
-		delete: true
-	};
-	if ((touched.has("delete") || touched.has("deleteUnattended")) && result.delete) result = {
-		...result,
-		read: true
-	};
-	if (touched.has("read") && !result.read) result = {
-		...result,
-		delete: false
-	};
-	if ((touched.has("delete") || touched.has("read")) && !result.delete) result = {
-		...result,
-		deleteUnattended: false
-	};
+	const result = { ...next };
+	for (const operation of touched) if (result[operation]) for (const required of prerequisitesOf(operation)) result[required] = true;
+	else for (const { id } of STORED_OPERATIONS) if (prerequisitesOf(id).includes(operation)) result[id] = false;
 	return result;
 };
 const rowActions = (basePath, namespace, row, values, changes) => {
-	const current = {
-		read: values[cellPath(basePath, namespace, row.fieldName, "read")] === true,
-		write: values[cellPath(basePath, namespace, row.fieldName, "write")] === true,
-		publish: values[cellPath(basePath, namespace, row.fieldName, "publish")] === true,
-		delete: values[cellPath(basePath, namespace, row.fieldName, "delete")] === true,
-		deleteUnattended: values[cellPath(basePath, namespace, row.fieldName, "deleteUnattended")] === true
-	};
+	const current = Object.fromEntries(STORED_OPERATIONS.map((operation) => [operation.id, values[cellPath(basePath, namespace, row.fieldName, operation.id)] === true]));
 	const touched = /* @__PURE__ */ new Set();
 	const next = { ...current };
-	for (const operation of CAPABILITY_OPERATIONS) {
+	for (const operation of STORED_OPERATIONS) {
 		const change = changes[operation.id];
 		if (change !== void 0 && row[operation.id]) {
 			next[operation.id] = change;
@@ -62,32 +61,57 @@ const rowActions = (basePath, namespace, row, values, changes) => {
 		}
 	}
 	const reconciled = reconcile(next, touched);
-	return CAPABILITY_OPERATIONS.filter((operation) => row[operation.id] && reconciled[operation.id] !== current[operation.id]).map((operation) => ({
+	return STORED_OPERATIONS.filter((operation) => row[operation.id] && reconciled[operation.id] !== current[operation.id]).map((operation) => ({
 		type: "UPDATE",
 		path: cellPath(basePath, namespace, row.fieldName, operation.id),
 		value: reconciled[operation.id]
 	}));
 };
+const grantsOf = (level) => {
+	const rank = ACCESS_LEVELS.indexOf(level);
+	return {
+		read: rank >= 1,
+		write: rank >= 2,
+		publish: rank >= 3
+	};
+};
 /**
-* The form-state updates one click implies, as literal actions. Every toggle
-* (cell, row, column or tool) comes through here, so the publish rule applies
-* to bulk grants too.
+* The form-state updates one click implies, as literal actions. Every click
+* comes through here, so the dependency rules apply to the "All" controls too:
+* picking Write ticks read, and lowering access to none clears delete.
 *
-* Only cells whose value changes get an action, so a bulk toggle that changes
-* nothing does not mark the form modified.
+* Only cells whose value changes get an action, so a click that changes
+* nothing does not mark the form modified. A level above a row's ceiling
+* grants what the row exposes and no more.
 */ const buildToggleActions = (matrix, basePath, values, intent) => {
 	if (intent.kind === "tool" || intent.kind === "tools") return matrix.tools.filter((tool) => intent.kind === "tools" || tool.name === intent.name).filter((tool) => values[toolPath(basePath, tool.name)] === true !== intent.value).map((tool) => ({
 		type: "UPDATE",
 		path: toolPath(basePath, tool.name),
 		value: intent.value
 	}));
-	const rows = matrix[intent.namespace].filter((row) => intent.kind === "column" || row.fieldName === intent.fieldName);
-	const changes = intent.kind === "row" ? {
-		read: intent.value,
-		write: intent.value,
-		publish: intent.value
-	} : { [intent.operation]: intent.value };
+	const rows = matrix[intent.namespace].filter((row) => intent.fieldName === void 0 || row.fieldName === intent.fieldName);
+	const changes = intent.kind === "access" ? grantsOf(intent.level) : {
+		delete: intent.mode !== "off",
+		deleteUnattended: intent.mode === "trash"
+	};
 	return rows.flatMap((row) => rowActions(basePath, intent.namespace, row, values, changes));
 };
+/**
+* The level a namespace's "All" control shows: the one that would change
+* nothing if picked, so rows capped below it still count. `undefined` while
+* the rows differ.
+*/ const allAccessLevel = (matrix, basePath, namespace, values) => ACCESS_LEVELS.find((level) => buildToggleActions(matrix, basePath, values, {
+	kind: "access",
+	namespace,
+	level
+}).length === 0);
+/**
+* The delete mode the "All" control shows, by the same rule. It offers no
+* trash, so a row that trashes directly reads as mixed.
+*/ const allDeleteMode = (matrix, basePath, namespace, values) => ["off", "approve"].find((mode) => buildToggleActions(matrix, basePath, values, {
+	kind: "deleteMode",
+	namespace,
+	mode
+}).length === 0);
 //#endregion
-export { buildToggleActions, columnState, rowState, toolsState };
+export { accessLevelOf, accessLevelsOf, allAccessLevel, allDeleteMode, buildToggleActions, deleteModeOf, toolsState };

package/dist/api-keys/capability-matrix.d.mts

@@ -2,8 +2,7 @@ import "../options.mjs";
 //#region src/api-keys/capability-matrix.d.ts
 /**
  * One entity's row. The booleans say what the plugin config exposes, not what
- * the key was granted. A `false` renders as a dash, so absence reads as a
- * refusal by config rather than a gap.
+ * the key was granted. A `false` leaves its segment out of the row's controls.
  */
 export interface CapabilityRow {
   fieldName: string;
@@ -17,9 +16,9 @@ export interface CapabilityRow {
   delete: boolean;
   deleteUnattended: boolean;
   /**
-   * Said only where a row departs from what its column header promises.
+   * Writes go live immediately, as the entity keeps no drafts.
    */
-  hint?: string;
+  live?: boolean;
 }
 interface CapabilityTool {
   name: string;

package/dist/api-keys/capability-matrix.mjs

@@ -2,12 +2,12 @@ import { CAPABILITIES_FIELD, canPublish, canWrite, isLiveWrite } from "../capabi
 //#region src/api-keys/capability-matrix.ts
 /**
 * The group's `admin.description`, rendered by the matrix in Payload's
-* description slot. It explains both markings in the table: an unticked box
-* and a dash.
-*/ const CAPABILITIES_DESCRIPTION = "What this key may do. An unticked box is a refusal, and a dash means the plugin config does not expose that operation at all.";
+* description slot. It explains how to read the segmented controls.
+*/ const CAPABILITIES_DESCRIPTION = "What this key may do. Each level includes the ones before it, and a missing segment means the plugin config does not expose it.";
 /**
 * The operations a collection or global can expose. The generated checkboxes
-* and the matrix column headers share this wording.
+* and the matrix segments share this wording. `requires` names the
+* operation a grant depends on, which the server and the matrix both enforce.
 */ const CAPABILITY_OPERATIONS = [
 	{
 		id: "read",
@@ -17,26 +17,35 @@ import { CAPABILITIES_FIELD, canPublish, canWrite, isLiveWrite } from "../capabi
 	{
 		id: "write",
 		label: "Write",
-		description: "Create, patch and validate drafts."
+		description: "Create, patch and validate drafts.",
+		requires: "read"
 	},
 	{
 		id: "publish",
 		label: "Publish",
-		description: "Promote the current draft to what the public sees."
+		description: "Promote the current draft to what the public sees.",
+		requires: "write"
 	},
 	{
 		id: "delete",
 		label: "Delete",
-		description: "Delete documents, each approved by this key's user in the admin panel."
-	},
-	{
-		id: "deleteUnattended",
-		label: "Delete without approval",
-		description: "Move documents to trash without asking this key's user."
+		description: "Delete documents. Each one is approved by this key's user in the admin panel, unless the config allows trashing directly and this key is set to.",
+		requires: "read"
 	}
 ];
-const LIVE_HINT = "Writes go live immediately.";
-const hintFor = (entity) => isLiveWrite(entity) ? { hint: LIVE_HINT } : {};
+/**
+* Stored as a checkbox of its own but drawn as the Trash segment of the Delete
+* control.
+*/ const DELETE_UNATTENDED = {
+	id: "deleteUnattended",
+	label: "Trash directly",
+	description: "Move documents to trash without asking this key's user.",
+	requires: "delete"
+};
+/**
+* Every operation with a stored checkbox: the capability operations plus
+* the unattended delete.
+*/ const STORED_OPERATIONS = [...CAPABILITY_OPERATIONS, DELETE_UNATTENDED];
 const toRow = (entity) => ({
 	fieldName: entity.fieldName,
 	label: entity.slug,
@@ -45,11 +54,11 @@ const toRow = (entity) => ({
 	publish: canPublish(entity),
 	delete: entity.delete,
 	deleteUnattended: entity.deleteUnattended,
-	...hintFor(entity)
+	...isLiveWrite(entity) ? { live: true } : {}
 });
 /**
 * The single description of what the config exposes. `createCapabilityFields`
-* and the admin component both draw from it, so a cell cannot appear without a
+* and the admin component both draw from it, so a control cannot appear without a
 * field behind it.
 */ const createCapabilityMatrix = (options) => ({
 	collections: options.collections.map(toRow),
@@ -63,6 +72,6 @@ const cellPath = (basePath, namespace, fieldName, operation) => `${basePath}.${n
 const toolPath = (basePath, name) => `${basePath}.tools.${name}`;
 /**
 * Every path the matrix can address, in a stable order.
-*/ const capabilityPaths = (matrix, basePath = CAPABILITIES_FIELD) => [...["collections", "globals"].flatMap((namespace) => matrix[namespace].flatMap((row) => CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)))), ...matrix.tools.map((tool) => toolPath(basePath, tool.name))];
+*/ const capabilityPaths = (matrix, basePath = CAPABILITIES_FIELD) => [...["collections", "globals"].flatMap((namespace) => matrix[namespace].flatMap((row) => STORED_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => cellPath(basePath, namespace, row.fieldName, operation.id)))), ...matrix.tools.map((tool) => toolPath(basePath, tool.name))];
 //#endregion
-export { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, capabilityPaths, cellPath, createCapabilityMatrix, toolPath };
+export { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, STORED_OPERATIONS, capabilityPaths, cellPath, createCapabilityMatrix, toolPath };

package/dist/api-keys/fields.mjs

@@ -1,5 +1,5 @@
 import { CAPABILITIES_FIELD } from "../capabilities.mjs";
-import { CAPABILITIES_DESCRIPTION, CAPABILITY_OPERATIONS, createCapabilityMatrix } from "./capability-matrix.mjs";
+import { CAPABILITIES_DESCRIPTION, STORED_OPERATIONS, createCapabilityMatrix } from "./capability-matrix.mjs";
 //#region src/api-keys/fields.ts
 const encryptKey = ({ req, value }) => typeof value === "string" ? req.payload.encrypt(value) : value;
 const decryptKey = ({ req, value }) => {
@@ -141,7 +141,7 @@ const SETUP_GUIDE_FIELD = "setupGuide";
 		name: row.fieldName,
 		type: "group",
 		label: row.label,
-		fields: CAPABILITY_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => checkbox(operation.id, operation.description))
+		fields: STORED_OPERATIONS.filter((operation) => row[operation.id]).map((operation) => checkbox(operation.id, operation.description))
 	}));
 	const collectionGroups = entityGroups(matrix.collections);
 	const globalGroups = entityGroups(matrix.globals);

package/dist/capabilities.mjs

@@ -17,7 +17,8 @@ import { isPlainObject } from "./guards.mjs";
 * Without drafts there is no draft stage, so every write is live.
 */ const isLiveWrite = (entity) => entity.write === "live" && !entity.hasDrafts;
 const flag = (group, name) => isPlainObject(group) && group[name] === true;
-const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write") && flag(group, "publish");
+const writeFlag = (entity, group) => canWrite(entity) && entity.read && flag(group, "read") && flag(group, "write");
+const publishFlag = (entity, group) => canPublish(entity) && writeFlag(entity, group) && flag(group, "publish");
 /**
 * Capabilities in force for a key: the plugin config decides what can exist,
 * the key's checkboxes decide what does. A missing checkbox is `false`, so keys
@@ -31,7 +32,7 @@ const publishFlag = (entity, group) => canPublish(entity) && flag(group, "write"
 			const deleting = entity.delete && flag(group, "read") && flag(group, "delete");
 			resolved[entity.slug] = {
 				read: entity.read && flag(group, "read"),
-				write: canWrite(entity) && flag(group, "write"),
+				write: writeFlag(entity, group),
 				publish: publishFlag(entity, group),
 				delete: deleting,
 				deleteUnattended: deleting && entity.deleteUnattended && flag(group, "deleteUnattended")

package/dist/options.mjs

@@ -64,18 +64,21 @@ const normalizeCapabilities = (kind, config, raw) => {
 	if (unknownKey !== void 0) fail(`${kind} "${slug}" has the unknown option "${unknownKey}". The options are ${names.join(", ")}.`);
 	const flag = (name) => readFlag(kind, slug, name, settings[name]);
 	const read = flag("read") ?? true;
-	const write = flag("write") ?? true;
+	const write = flag("write") ?? read;
 	const publish = flag("publish");
 	const hasDrafts = hasDraftsEnabled(config);
 	if (publish === false && write && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so every write goes live. Set write: false or remove publish: false.`);
 	if (publish === true && !hasDrafts) fail(`${kind} "${slug}" has no drafts, so there is nothing to publish. Enable versions.drafts or remove publish: true.`);
+	if (!read && (flag("write") === true || publish === true)) fail(`${kind} "${slug}" has read: false but write or publish on. Writing and publishing need read.`);
 	if (publish === true && !write) fail(`${kind} "${slug}" has publish: true but write: false. Publishing follows write.`);
+	const deleting = normalizeDelete(kind, config, settings["delete"]);
+	if (!read && deleting.delete) fail(`${kind} "${slug}" has read: false but delete on. Deleting needs read.`);
 	return {
 		read,
 		write: write ? publish === false ? "draft" : "live" : false,
 		hasDrafts,
 		hasVersions: read && Boolean(config.versions),
-		...normalizeDelete(kind, config, settings["delete"])
+		...deleting
 	};
 };
 const assertGlobalExposable = (global) => {

package/dist/tools/create-document.mjs

@@ -6,6 +6,7 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { assertAcceptsFile, fileShape, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
 import { liveWriteSentence, localeOf, localeShape, patchOnlySlugs, slugEnum, slugsFor } from "./shared.mjs";
 import { readDraft, resolveEntity } from "./document.mjs";
+import { documentLinks } from "./links.mjs";
 import { stripRowIds } from "../write/row-ids.mjs";
 import { z } from "zod";
 import { APIError } from "payload";
@@ -14,7 +15,7 @@ const uploadSentence = (scope) => {
 	const slugs = patchOnlySlugs(scope);
 	return slugs.length === 0 ? "" : ` Documents in ${slugs.join(", ")} are files and cannot be created here. Upload the file in the admin panel, then edit its fields with patchDocument.`;
 };
-const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only when the document does not exist yet. Returns "id", "status", "updatedAt" and, if any, "publishBlockers". "publishBlockersUnavailable" means that check failed. "data" may leave required fields empty for patchDocument to fill later, except in a collection whose listCapabilities entry has "draftValidation" true or "drafts" false. A field describeSchema does not list is refused, and "id" is always assigned.
+const DESCRIPTION = (scope) => `Creates a document in a collection. Use it only when the document does not exist yet. Returns "id", "status", "updatedAt" and, if any, "publishBlockers". "publishBlockersUnavailable" means that check failed. "data" may leave required fields empty for patchDocument to fill later, except in a collection whose listCapabilities entry has "draftValidation" true or "drafts" false. A field describeSchema does not list is refused, and "id" is always assigned. The response links the document with "adminUrl" and "previewUrl".
 
 ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 /**
@@ -104,6 +105,11 @@ ${liveWriteSentence(scope, "create")}${uploadSentence(scope)}`;
 			id: saved["id"],
 			status: saved["_status"],
 			updatedAt: saved["updatedAt"],
+			...await documentLinks(scope.req, {
+				target,
+				doc: saved,
+				locale
+			}),
 			...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
 			...validation.unavailable ? { publishBlockersUnavailable: true } : {}
 		});

package/dist/tools/links.mjs

@@ -0,0 +1,52 @@
+import { formatAdminURL } from "payload/shared";
+//#region src/tools/links.ts
+const livePreviewOf = (req, target) => {
+	if (target.config.admin.livePreview) return target.config.admin.livePreview;
+	const root = req.payload.config.admin.livePreview;
+	return (target.kind === "collection" ? root?.collections : root?.globals)?.includes(target.slug) ? root : void 0;
+};
+const previewOf = async (req, args) => {
+	const { target, doc, locale } = args;
+	const { preview } = target.config.admin;
+	if (preview) return await preview(doc, {
+		locale: locale ?? "",
+		req,
+		token: null
+	});
+	const url = livePreviewOf(req, target)?.url;
+	if (typeof url !== "function") return url;
+	const { localization } = req.payload.config;
+	const entry = localization ? localization.locales.find((item) => item.code === locale) : void 0;
+	return await url({
+		...target.kind === "collection" ? { collectionConfig: target.config } : { globalConfig: target.config },
+		data: doc,
+		locale: entry ?? {
+			code: locale ?? "",
+			label: locale ?? ""
+		},
+		payload: req.payload,
+		req
+	});
+};
+/**
+* The admin panel URL of a written document, and its preview URL where the
+* entity configures one. Both sit at the origin of `serverURL` when set, else
+* of the MCP request. A preview that fails is left out: the write has landed.
+*/ const documentLinks = async (req, args) => {
+	const { target, doc, locale } = args;
+	const { config } = req.payload;
+	const origin = config.serverURL || new URL(req.url ?? "").origin;
+	const path = target.kind === "collection" ? `/collections/${target.slug}/${String(doc["id"])}` : `/globals/${target.slug}`;
+	const adminUrl = formatAdminURL({
+		adminRoute: config.routes.admin,
+		path,
+		serverURL: origin
+	});
+	const preview = await previewOf(req, args).catch(() => void 0);
+	return {
+		adminUrl: locale ? `${adminUrl}?locale=${encodeURIComponent(locale)}` : adminUrl,
+		...preview ? { previewUrl: new URL(preview, origin).toString() } : {}
+	};
+};
+//#endregion
+export { documentLinks };

package/dist/tools/list-capabilities.mjs

@@ -37,7 +37,7 @@ const translateLabel = (scope, label, fallback) => {
 		const collections = scope.exposure.collections.flatMap((entry) => {
 			const capability = scope.capabilities.collections[entry.slug];
 			const collection = payload.collections[entry.slug];
-			if (!capability || !collection || !(capability.read || capability.write)) return [];
+			if (!capability || !collection || !capability.read) return [];
 			const { config } = collection;
 			const description = translate(config.admin.description);
 			return [{
@@ -60,7 +60,7 @@ const translateLabel = (scope, label, fallback) => {
 		const globals = scope.exposure.globals.flatMap((entry) => {
 			const capability = scope.capabilities.globals[entry.slug];
 			const config = payload.globals.config.find((candidate) => candidate.slug === entry.slug);
-			if (!capability || !config || !(capability.read || capability.write)) return [];
+			if (!capability || !config || !capability.read) return [];
 			const description = translate(config.admin.description);
 			return [{
 				slug: entry.slug,

package/dist/tools/patch-document.mjs

@@ -7,6 +7,7 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { assertAcceptsFile, fileShape, fileSlugs, fileWriteRefusal, uploadHandoff, uploadedFile } from "../upload/file.mjs";
 import { entityShape, idShape, liveWriteSentence, localeOf, localeShape } from "./shared.mjs";
 import { identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
+import { documentLinks } from "./links.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { applyPatchOperations, isElementPointer } from "../write/patch.mjs";
 import { buildWriteData } from "../write/write-data.mjs";
@@ -22,7 +23,7 @@ Read the document with getDocument right before patching. Append to a list with
 
 In a rich text field a pointer continues into the rich text state: "/content/root/children/2" is a node, "/content/root/children/2/tag" one of its properties and "/content/root/children/3/fields/tone" a field of a block node. getDocument "outline" lists each node's pointer and "version". Build nodes from describeSchema "nodeProperties". Check a position before writing to it, e.g. {"op":"test","path":"/content/root/children/2/type","value":"heading"}.
 
-The response carries "updatedAt" and, if any, "publishBlockers": what must be fixed before publishing. "publishBlockersUnavailable" means that check failed. The write stands either way. "notApplied" lists pointers whose value did not change or cannot be read back, for example where field access denies the update.`;
+The response carries "updatedAt" and, if any, "publishBlockers": what must be fixed before publishing. "publishBlockersUnavailable" means that check failed. The write stands either way. "notApplied" lists pointers whose value did not change or cannot be read back, for example where field access denies the update. The response links the document with "adminUrl" and "previewUrl".`;
 const POINTER = z.string().regex(JSON_POINTER_PATTERN);
 const PATCHES_LIMIT = 500;
 /**
@@ -130,6 +131,11 @@ const notAppliedPointers = (patches, intended, saved) => patches.flatMap((operat
 				...identityOf(target, saved["id"]),
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
+				...await documentLinks(scope.req, {
+					target,
+					doc: saved,
+					locale
+				}),
 				...validation.blockers.length > 0 ? { publishBlockers: validation.blockers } : {},
 				...validation.unavailable ? { publishBlockersUnavailable: true } : {},
 				...notApplied.length > 0 ? { notApplied } : {}

package/dist/tools/publish-document.mjs

@@ -2,6 +2,7 @@ import { defineMcpxTool } from "../define-tool.mjs";
 import { jsonResult } from "../result.mjs";
 import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectLocaleBlockers, identityOf, readDraft, resolveDocument, staleReadResult } from "./document.mjs";
+import { documentLinks } from "./links.mjs";
 import { withPublishIntent } from "../write/publish-intent.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { z } from "zod";
@@ -10,7 +11,7 @@ import { z } from "zod";
 * with drafts and the key has both the `write` and `publish` checkboxes.
 */ const publishDocument = defineMcpxTool({
 	name: "publishDocument",
-	description: `Makes the current draft of one document or global public, in every locale or only in "locale". A scoped publish keeps the other locales of localized fields as last published, and a never-published document goes live in full. A draft with publish blockers is refused, so call validateDocument first. Payload checks only the published locale, so "otherLocaleBlockers" lists what other locales still lack. There is no unpublish.`,
+	description: `Makes the current draft of one document or global public, in every locale or only in "locale". A scoped publish keeps the other locales of localized fields as last published, and a never-published document goes live in full. A draft with publish blockers is refused, so call validateDocument first. Payload checks only the published locale, so "otherLocaleBlockers" lists what other locales still lack. There is no unpublish. The response links the document with "adminUrl" and "previewUrl".`,
 	annotations: {
 		destructiveHint: true,
 		openWorldHint: false
@@ -63,6 +64,11 @@ import { z } from "zod";
 				...identityOf(target, saved["id"]),
 				status: saved["_status"],
 				updatedAt: saved["updatedAt"],
+				...await documentLinks(scope.req, {
+					target,
+					doc: saved,
+					locale
+				}),
 				...others.blockers.length > 0 ? { otherLocaleBlockers: others.blockers } : {},
 				...others.unavailable ? { otherLocaleBlockersUnavailable: true } : {}
 			});

package/dist/tools/validate-document.mjs

@@ -4,8 +4,8 @@ import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { entityShape, idShape, localeOf, localeShape } from "./shared.mjs";
 import { collectLocaleBlockers, identityOf, readDraft, resolveDocument } from "./document.mjs";
 /**
-* Gated on write rather than read, because publish blockers only mean something
-* to a caller who can act on them.
+* Gated on write, which implies read, because publish blockers only mean
+* something to a caller who can act on them.
 *
 * It reads the document twice on purpose: once under the key's own access to
 * refuse a caller who may not see it, then privileged, so the check covers every

package/dist/types.d.mts

@@ -36,7 +36,7 @@ export interface McpxCollectionOptions {
   /**
    * Expose `patchDocument`, `validateDocument` and `createDocument`. An upload
    * collection is created in only where MCP accepts its files. Without drafts
-   * a write changes live content. Default `true`.
+   * a write changes live content. Needs `read`. Default `true` while `read` is.
    */
   write?: boolean;
   /**
@@ -48,8 +48,8 @@ export interface McpxCollectionOptions {
   /**
    * Expose `deleteDocument`, which deletes one document once the key's user
    * approved the call in the admin panel. On a collection with `trash` it
-   * moves the document to trash. `"unattended"` also lets a key with its own
-   * checkbox move documents to trash without approval; it needs `trash`.
+   * moves the document to trash. `"unattended"` also lets a key set to it move
+   * documents to trash without approval; it needs `trash`. Needs `read`.
    * Default `false`.
    */
   delete?: boolean | "unattended";

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@abinnovision/payloadcms-mcpx",
-  "version": "2.0.0-beta.14",
+  "version": "2.0.0-beta.16",
   "description": "Payload CMS plugin exposing a fixed, schema-aware MCP tool surface with draft-only writes and per-API-key capabilities.",
   "keywords": [
     "payload",