@abinnovision/payloadcms-mcpx 1.0.0-beta.13 → 1.0.0-beta.15

package/dist/schema/walk.mjs

@@ -2,50 +2,37 @@ import { allowedNodeTypes, nodeOptions } from "./lexical.mjs";
 import { translateAny } from "../i18n.mjs";
 import { fieldIsHiddenOrDisabled, fieldIsVirtual } from "payload/shared";
 //#region src/schema/walk.ts
-/**
-* Fields Payload maintains, which a client may neither address nor supply.
-*/ const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
+const RESERVED_FIELD_NAMES = /* @__PURE__ */ new Set([
 	"_status",
 	"createdAt",
 	"deletedAt",
 	"id",
 	"updatedAt"
 ]);
+const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
+/** No segments is the root pointer, `""`. */ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
+/** Unescapes `~1` and `~0`. The root pointer yields no segments. */ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
 /**
-* Shape a JSON Pointer must have to be parseable at all.
-*/ const JSON_POINTER_PATTERN = /^(\/([^~/]|~[01])*)*$/;
-/**
-* Joins segments into a JSON Pointer, so the segments `items`, `*`, `title`
-* read as one path to a subfield of every element of `items`. No segments is
-* the root pointer, `""`.
-*/ const joinPath = (parts) => parts.map((part) => `/${part.replace(/~/g, "~0").replace(/\//g, "~1")}`).join("");
-/**
-* Splits a JSON Pointer into its segments, unescaping `~1` and `~0`. The root
-* pointer yields no segments.
-*/ const splitPath = (path) => path.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
-/**
-* Restates a path Payload reports on a validation error (`layout.0.title`) as
-* a JSON Pointer, so everything this plugin hands back addresses documents the
-* same way. Payload's path already carries real indices, so it maps directly.
+* A path Payload reports on a validation error (`layout.0.title`) as a JSON
+* Pointer, so everything handed back addresses documents the same way. The
+* path already carries real indices, so it maps directly.
 */ const pointerFromPayloadPath = (path) => path ? joinPath(path.split(".")) : "";
+/** On a flattened field, whichever of `blockReferences` and `blocks` was declared. */ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
 /**
-* Blocks a blocks field accepts, by slug. On a flattened field, whichever of
-* `blockReferences` and `blocks` was declared carries the definitions.
-*/ const blockSlugsOf = (field) => [...new Set((field.blockReferences ?? field.blocks).map((block) => typeof block === "string" ? block : block.slug))];
-/**
-* Resolves one of a blocks field's slugs to its definition.
-*
-* A definition inlined on the field wins over the shared registry. A block's
-* own fields are identical wherever it appears, but the blocks its children
-* accept are not, so an inline definition has to be read at its position.
-* The registry (`config.blocks`) is the fallback for slugs referenced by name.
+* An inlined definition wins over the registry (`config.blocks`). A block's own
+* fields are identical wherever it appears, but the blocks its children accept
+* are not, so an inline definition has to be read at its position.
 */ const blockOf = (config, field, slug) => {
 	const declared = field.blockReferences ?? field.blocks;
 	const inline = declared.find((block) => typeof block !== "string" && block.slug === slug);
 	if (inline) return inline;
 	return declared.includes(slug) ? config.blocks?.find((block) => block.slug === slug) : void 0;
 };
-const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || fieldIsHiddenOrDisabled(field);
+/**
+* Payload's `fieldIsHiddenOrDisabled` reads `hidden` and `admin.disabled`, not
+* `admin.hidden`, which is what its own upload base fields carry.
+*/ const isAdminHidden = (field) => "admin" in field && field.admin.hidden === true;
+/** A field kept out of the admin panel is kept out of the MCP surface too. */ const isSkipped = (field) => !("name" in field) || field.type === "join" || RESERVED_FIELD_NAMES.has(field.name) || fieldIsVirtual(field) || isAdminHidden(field) || fieldIsHiddenOrDisabled(field);
 const isReadOnly = (field) => "admin" in field && field.admin.readOnly === true;
 const describeBase = (field, { path, readOnly, translate }) => {
 	const description = translate("admin" in field ? field.admin.description : void 0);
@@ -80,11 +67,9 @@ const withRows = (descriptor, field) => ({
 	...field.maxRows === void 0 ? {} : { maxRows: field.maxRows }
 });
 /**
-* Whether a descriptor stands for a construct that only holds other fields.
-*
-* These describe a position rather than a value, so everything that resolves a
-* path to something writable skips them; only {@link nodeDescriber} reports
-* them, to carry what the container itself declares.
+* A container describes a position rather than a value, so everything resolving
+* a path to something writable skips it. Only {@link nodeDescriber} reports one,
+* to carry what the container itself declares.
 */ const isContainer = (descriptor) => descriptor.type === "array" || descriptor.type === "group" || descriptor.type === "tab";
 /**
 * Whether a container declares anything a client could not infer from the
@@ -93,20 +78,16 @@ const withRows = (descriptor, field) => ({
 /**
 * Flattens a field list into descriptors addressed relative to the node.
 *
-* The input is Payload's own flattened shape, which has already merged every
-* construct that exists only in the admin UI (unnamed tabs, unnamed groups,
-* `row`, `collapsible`) and dropped `ui` fields. Named tabs, groups and
-* arrays contribute a path segment, and are described in their own right when
-* they declare something of their own: an array always, since its row counts
-* live nowhere else, a group or tab only when it carries a description or a
-* constraint. The walk stops at every blocks field and names the slugs instead
-* of descending, which keeps a node proportional to the number of blocks it
-* allows rather than to the size of their definitions.
+* The input is Payload's own flattened shape, so the admin-only constructs
+* (unnamed tabs and groups, `row`, `collapsible`, `ui`) are already gone. Named
+* tabs, groups and arrays contribute a path segment, and are described in their
+* own right when they declare something of their own: an array always, since
+* its row counts live nowhere else, a group or tab only when it carries a
+* description or a constraint. The walk stops at every blocks field and names
+* the slugs, which keeps a node proportional to the number of blocks it allows
+* rather than to the size of their definitions.
 *
-* `translate` resolves each `admin.description` to the request's language.
-* Callers that walk for paths alone leave it out and get the language-agnostic
-* default, so a missing argument costs language selection, never the
-* description itself.
+* Omitting `translate` costs language selection, never the description itself.
 */ const describeFields = (fields, translate = translateAny) => {
 	const walk = (current, prefix, parentReadOnly) => current.flatMap((field) => {
 		if (isSkipped(field)) return [];
@@ -135,9 +116,7 @@ const withRows = (descriptor, field) => ({
 * path against a document needs. A container describes a position rather than
 * a value, so only {@link nodeDescriber} reports one.
 */ const describeAddressableFields = (fields) => describeFields(fields).filter((descriptor) => !isContainer(descriptor));
-/**
-* Locates the field of `type` that a resolved descriptor path refers to.
-*/ const findFieldAt = (fields, path, type) => {
+const findFieldAt = (fields, path, type) => {
 	for (const field of fields) {
 		if (!("name" in field) || field.name !== path[0]) continue;
 		if (field.type === type && path.length === 1) return field;
@@ -145,14 +124,17 @@ const withRows = (descriptor, field) => ({
 		if (field.type === "array" && path[1] === "*") return findFieldAt(field.flattenedFields, path.slice(2), type);
 	}
 };
-/**
-* Locates the blocks field that a resolved descriptor path refers to.
-*/ const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
+const findBlocksField = (fields, path) => findFieldAt(fields, path, "blocks");
 /**
 * Locates the rich text field that a resolved descriptor path refers to, so
 * its editor can be introspected for the fields its nodes carry.
 */ const findRichTextField = (fields, path) => findFieldAt(fields, path, "richText");
-const targetOf = (config, ref) => {
+/**
+* Looks up the sanitized config for a collection or global, as a
+* {@link SchemaTarget}. Throws on an unknown slug rather than returning
+* undefined, because a reference reaching here has already been checked against
+* the key's capabilities and a miss means the config changed underneath it.
+*/ const targetOf = (config, ref) => {
 	const found = ref.kind === "collection" ? config.collections.find((candidate) => candidate.slug === ref.slug) : config.globals.find((candidate) => candidate.slug === ref.slug);
 	if (!found) throw new Error(`Unknown ${ref.kind} "${ref.slug}".`);
 	return found;

package/dist/tools/builtin.mjs

@@ -8,12 +8,10 @@ import { publishDocument } from "./publish-document.mjs";
 import { validateDocument } from "./validate-document.mjs";
 //#region src/tools/builtin.ts
 /**
-* The builtin tools in registration order. They are ordinary {@link McpxTool}s
-* that ship with the plugin and register through the same loop as the tools
-* from `options.tools`; only their `isEnabled` differs, deriving from the
-* key's collection and global capabilities rather than a checkbox of their
-* own. The surface is fixed: adding a collection, block or field never
-* changes it.
+* The builtin tools, in registration order. Fixed: adding a collection, block
+* or field never changes the surface. They differ from a custom tool only in
+* `isEnabled`, which derives from the key's capabilities rather than a
+* checkbox of their own.
 */ const BUILTIN_TOOLS = [
 	listCapabilities,
 	describeSchema,

package/dist/tools/create-document.mjs

@@ -1,17 +1,30 @@
 import { errorResult, jsonResult } from "../result.mjs";
 import { validateWriteValue } from "../schema/shape.mjs";
 import "../schema/index.mjs";
-import { draftSentence, localeOf, localeShape, readTarget, slugEnum } from "./shared.mjs";
+import { draftSentence, localeOf, localeShape, patchOnlySlugs, readTarget, slugEnum, slugsFor } from "./shared.mjs";
 import { resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { stripRowIds } from "../write/patch.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
 import { z } from "zod";
 //#region src/tools/create-document.ts
+/** Names the writable slugs this tool leaves out, so the gap reads as intent. */ const uploadSentence = (scope) => {
+	const slugs = patchOnlySlugs(scope);
+	return slugs.length === 0 ? "" : `\n\nLeft out of "collection" on purpose: ${slugs.join(", ")}. Those documents are files, and no tool here carries one. Upload the file in the admin panel, then edit its fields with patchDocument.`;
+};
 const DESCRIPTION = (scope) => `Creates a new document from a minimal seed. Only the fields describeSchema lists may appear in "data"; unknown keys are refused with the valid siblings, and "id" is Payload's to assign. The document may be incomplete: the response lists "publishBlockers", which patchDocument can then work through, and "publishBlockersUnavailable" when that check itself failed. Use this when no document exists yet; prefer patching an existing draft otherwise.
 
-${draftSentence(scope)}`;
-const createDocument = defineMcpxTool({
+${draftSentence(scope)}${uploadSentence(scope)}`;
+/**
+* Collection-only, because a global always exists, and never reaches an upload
+* collection, because a create there would have to carry the file.
+*
+* The seed is checked against the collection's fields before the create, so an
+* unknown key is refused with its valid siblings rather than dropped. Row ids
+* in the seed are stripped and a top-level `id` is refused outright. The new
+* document is re-read privileged afterwards to collect publish blockers, which
+* is why an incomplete seed still succeeds and comes back with a checklist.
+*/ const createDocument = defineMcpxTool({
 	name: "createDocument",
 	description: DESCRIPTION,
 	annotations: {
@@ -20,9 +33,9 @@ const createDocument = defineMcpxTool({
 		idempotentHint: false,
 		openWorldHint: false
 	},
-	isEnabled: (scope) => scope.writable.length > 0,
+	isEnabled: (scope) => slugsFor(scope, "create").collections.length > 0,
 	inputSchema: (scope) => ({
-		collection: slugEnum(scope.writable).describe("Collection to create the document in."),
+		collection: slugEnum(slugsFor(scope, "create").collections).describe("Collection to create the document in."),
 		...localeShape(scope, {
 			required: true,
 			description: "Locale the localized fields of the seed belong to."
@@ -30,7 +43,7 @@ const createDocument = defineMcpxTool({
 		data: z.record(z.string(), z.unknown()).describe("Initial field values, as describeSchema lists them.")
 	}),
 	handler: async ({ args, scope }) => {
-		const target = resolveTarget(scope, { collection: args.collection }, "write");
+		const target = resolveTarget(scope, { collection: args.collection }, "create");
 		const { payload } = scope.req;
 		const locale = localeOf(scope, args.locale);
 		if ("id" in args.data) return errorResult("Nothing was created.", { problems: ["/id: Payload assigns the id; it cannot be supplied."] });

package/dist/tools/describe-schema.mjs

@@ -6,7 +6,13 @@ import { targetShape } from "./shared.mjs";
 import { refOf, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
-const describeSchema = defineMcpxTool({
+/**
+* Describes each requested path independently and returns a per
+* path error object instead of failing the call, so a client exploring several
+* branches at once keeps the nodes that did resolve. `expand` swaps the
+* requested paths for every node reachable from the root and appends a
+* truncation notice past {@link REACHABLE_PATHS_LIMIT}.
+*/ const describeSchema = defineMcpxTool({
 	name: "describeSchema",
 	description: `Describes the writable shape of a document, one node at a time.
 
@@ -16,6 +22,8 @@ Call it with no "paths" to get a collection's own fields. Every "blocks" field s
 
 A "richText" field stops there too. It lists the Lexical node types it accepts in "nodes", and "next" carries a path for every node type that holds fields of its own: "/content/link" for a link node, "/content/block/callout" and "/content/inlineBlock/badge" for the block nodes. Descend to get the real field list instead of guessing what a node carries. Upload nodes are not addressable, because their fields depend on the collection the node points at.
 
+Write each Lexical node the way Lexical serializes it, with every property its type carries rather than a trimmed subset, and with the value Lexical would have written there. Every node needs a "version"; the root takes exactly "children", "direction", "format", "indent", "type" and "version" and refuses anything else; each node type adds its own on top. The admin editor rehydrates nodes through their classes, so a list item whose "indent" is missing, null or a string is stored and then throws on open, and a heading whose "tag" is a number is stored untagged. A write naming a property means exactly that.
+
 Paths here use the same JSON Pointer syntax as getDocument and patchDocument, and are already resolved through anything that does not nest in the stored document. The difference is only what stands in an element position: a path names an array element "*" and a block by its slug, where a pointer into a document carries a 0-based index. So "/items/*/title" is written at "/items/0/title", and "/layout/sections/hero" at "/layout/sections/0".
 
 Fields Payload maintains (id, _status, createdAt, updatedAt) are never listed and cannot be written. Fields marked readOnly are listed but refused on write.`,

package/dist/tools/find-documents.mjs

@@ -3,7 +3,14 @@ import { depthShape, localeOf, localeShape, slugEnum } from "./shared.mjs";
 import { resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
-const findDocuments = defineMcpxTool({
+/**
+* Collection-only: a global is a singleton, so there is nothing to list.
+*
+* The query goes to Payload with `overrideAccess: false`, so the collection's
+* own access control decides what comes back. `limit` and `depth` are bounded
+* by the configured limits in the schema itself, which puts the ceiling in
+* front of the client rather than silently clamping behind it.
+*/ const findDocuments = defineMcpxTool({
 	name: "findDocuments",
 	description: `Finds documents in a collection. "where" is a Payload query object, e.g. {"title":{"contains":"home"}} or {"and":[...]}; "select" picks fields, e.g. {"title":true}. Drafts are included by default so unpublished work is visible. Keep depth at 0 unless populated relationships are needed; ids are enough for writes.`,
 	annotations: {

package/dist/tools/get-document.mjs

@@ -6,7 +6,11 @@ import { requireIdFor, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { z } from "zod";
 import { Pointer } from "rfc6902";
-const getDocument = defineMcpxTool({
+/**
+* With `path` the handler returns the subtree plus the `id`, `_status` and
+* `updatedAt` a client needs to write back, so a caller reading one branch
+* still gets the timestamp `expectedUpdatedAt` wants without a second call.
+*/ const getDocument = defineMcpxTool({
 	name: "getDocument",
 	description: `Reads one document, or one subtree of it when "path" is given as a JSON pointer such as "/layout/sections/2". Returns the latest draft by default. Read before patching: the response carries "updatedAt" for expectedUpdatedAt and the indices pointers need.
 

package/dist/tools/list-capabilities.mjs

@@ -1,11 +1,18 @@
+import { canCreate } from "../capabilities.mjs";
 import { jsonResult } from "../result.mjs";
 import { translatorFor } from "../i18n.mjs";
 import { translateLabel } from "./shared.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { hasDraftValidationEnabled } from "payload/shared";
-const listCapabilities = defineMcpxTool({
+/**
+* Registered for every key, including one with no capabilities ticked, so a
+* client always has something to call and gets an empty surface described
+* rather than an empty tool list. The response is assembled from the request
+* scope and the sanitized config, never from the content model, so it stays the
+* same size as a deployment grows.
+*/ const listCapabilities = defineMcpxTool({
 	name: "listCapabilities",
-	description: `Lists what this key may do: the collections and globals it can read or write, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
+	description: `Lists what this key may do: the collections and globals it can read or write, whether a collection can also be created in, their draft behaviour and id type, the configured locales, the limits in force and the custom tools available. Call it first to orient; nothing here changes with the content model.
 
 A global is a singleton: it has no id, is not listed by findDocuments and cannot be created. Address one with the "global" argument where a collection document would take "collection" and "id".`,
 	annotations: {
@@ -32,6 +39,7 @@ A global is a singleton: it has no id, is not listed by findDocuments and cannot
 				...description === void 0 ? {} : { description },
 				read: capability.read,
 				write: capability.write,
+				create: capability.write && canCreate(entry),
 				publish: capability.publish,
 				drafts: entry.hasDrafts,
 				draftValidation: hasDraftValidationEnabled(config),

package/dist/tools/patch-document.mjs

@@ -42,7 +42,13 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 	const actual = pointer.get(saved);
 	return survives(expected, actual) ? [] : [operation.path];
 });
-const patchDocument = defineMcpxTool({
+/**
+* The handler validates the whole batch against the schema and the current
+* document before it writes anything, runs the write in a transaction, then
+* re-reads the saved document to report which pointers survived and what still
+* blocks publishing. Nothing here decides where the write lands: the draft
+* guard does that on the Payload operation.
+*/ const patchDocument = defineMcpxTool({
 	name: "patchDocument",
 	description: DESCRIPTION,
 	annotations: {

package/dist/tools/publish-document.mjs

@@ -5,7 +5,11 @@ import { defineMcpxTool } from "../types.mjs";
 import { withTransaction } from "../write/transaction.mjs";
 import { withPublishIntent } from "../write/publish-intent.mjs";
 import { z } from "zod";
-const publishDocument = defineMcpxTool({
+/**
+* The only tool that changes live content, available where the config sets
+* `write: "live"` on a versioned entity and the key has both the `write` and
+* `publish` checkboxes.
+*/ const publishDocument = defineMcpxTool({
 	name: "publishDocument",
 	description: `Publishes the current draft, which changes what the public sees. This is the only tool that does; every other write lands as a draft. Call validateDocument first: a document that still has publish blockers is refused, and nothing is written.
 
@@ -40,7 +44,7 @@ There is no unpublish: reverting to a draft stays a human action in the admin pa
 			});
 			if (args.expectedUpdatedAt !== void 0 && !sameInstant(doc["updatedAt"], args.expectedUpdatedAt)) return errorResult("The document changed since you read it. Read it again before publishing.", { updatedAt: doc["updatedAt"] });
 			const write = {
-				data: {},
+				data: withPublishIntent({}),
 				depth: 0,
 				draft: false,
 				fallbackLocale: false,
@@ -48,20 +52,14 @@ There is no unpublish: reverting to a draft stays a human action in the admin pa
 				req: scope.req,
 				...locale === void 0 ? {} : { locale }
 			};
-			await withPublishIntent({
-				kind: target.kind,
-				slug: target.slug,
+			if (target.kind === "collection") await payload.update({
+				...write,
+				collection: target.slug,
 				id
-			}, async () => {
-				if (target.kind === "collection") await payload.update({
-					...write,
-					collection: target.slug,
-					id
-				});
-				else await payload.updateGlobal({
-					...write,
-					slug: target.slug
-				});
+			});
+			else await payload.updateGlobal({
+				...write,
+				slug: target.slug
 			});
 			const saved = await readTarget(scope, {
 				target,

package/dist/tools/shared.mjs

@@ -1,10 +1,13 @@
-import { canPublish, isLiveWrite } from "../capabilities.mjs";
+import { canCreate, canPublish, isLiveWrite } from "../capabilities.mjs";
 import { translateStatic } from "../i18n.mjs";
 import { NotFound } from "payload";
 import { z } from "zod";
 //#region src/tools/shared.ts
-const slugEnum = (slugs) => z.enum(slugs);
-const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
+/**
+* An out-of-scope slug fails schema validation before a handler runs, so a
+* client only ever sees what its key may touch.
+*/ const slugEnum = (slugs) => z.enum(slugs);
+/** Payload's id type follows the adapter, so both forms are handed on as read. */ const idSchema = z.union([z.string(), z.number()]).describe("Document id.");
 const slugsWhere = (scope, predicate, allowed) => {
 	const pick = (entities, slugs) => entities.filter((entity) => slugs.includes(entity.slug) && predicate(entity)).map((entity) => entity.slug);
 	return [...pick(scope.exposure.collections, allowed.collections), ...pick(scope.exposure.globals, allowed.globals)];
@@ -17,33 +20,38 @@ const slugsWhere = (scope, predicate, allowed) => {
 	collections: scope.writable,
 	globals: scope.writableGlobals
 });
+/**
+* Slugs this key may write but never create in, because their documents are
+* files. Collection-only, since nothing creates a global either way.
+*/ const patchOnlySlugs = (scope) => slugsWhere(scope, (entity) => !canCreate(entity), {
+	collections: scope.writable,
+	globals: []
+});
 /** Slugs this key may write and, separately, publish. */ const publishableWriteSlugs = (scope) => slugsWhere(scope, canPublish, {
 	collections: scope.publishable,
 	globals: scope.publishableGlobals
 });
 /**
-* The sentence the write tools and the server instructions end on: what a write
-* actually does for this key, and what it takes to make it public. The three
-* groups are distinct — a live-write slug has no draft and no publish step, a
-* publishable one has both — so a client is never told its writes are drafts
-* while they are not, nor that publishing is out of reach when it is not.
+* What a write actually does for this key, and what it takes to make it public.
+* A live-write slug has no draft and no publish step; a publishable one has
+* both. Stated per key so a client is never told its writes are drafts while
+* they are not, nor that publishing is out of reach when it is not.
 */ const draftSentence = (scope) => {
 	const live = liveWriteSlugs(scope);
 	const publishable = publishableWriteSlugs(scope);
 	return `${live.length === 0 ? "Every write lands as a draft." : `Writes land as drafts, except for ${live.join(", ")}, which have no drafts: a write there changes the live document immediately.`} ${publishable.length === 0 ? "Nothing this key writes is ever published; publishing stays a human action in the admin panel." : `Publish a draft with publishDocument, which this key may do for ${publishable.join(", ")}. Publishing anything else stays a human action in the admin panel.`}`;
 };
-/**
-* Whether two timestamps name the same instant, which is how
-* `expectedUpdatedAt` is compared: the value a client read back is a string,
-* and what it is compared against may be a Date.
-*/ const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
-/**
-* Widens one branch to the superset a handler sees. The widening itself is
-* unchecked — the runtime shape really does vary — so `Branch` checks what it
-* can around it.
-*/ const widen = (branch) => branch;
-const slugsFor = (scope, operation) => {
+/** The value a client read back is a string; what it meets may be a Date. */ const sameInstant = (left, right) => typeof left === "string" && new Date(left).getTime() === new Date(right).getTime();
+/** Unchecked, because the runtime shape really does vary; `Branch` guards it. */ const widen = (branch) => branch;
+/** The one list the shape helpers and {@link resolveTarget} both read. */ const slugsFor = (scope, operation) => {
 	switch (operation) {
+		case "create": return {
+			collections: slugsWhere(scope, canCreate, {
+				collections: scope.writable,
+				globals: []
+			}),
+			globals: []
+		};
 		case "publish": return {
 			collections: scope.publishable,
 			globals: scope.publishableGlobals
@@ -59,13 +67,9 @@ const slugsFor = (scope, operation) => {
 	}
 };
 /**
-* The `collection` and `global` arguments.
-*
-* When the key can reach no global, `global` is left out of the shape entirely
-* and `collection` stays required, mirroring how {@link localeShape} omits
-* `locale` when localization is off. A deployment without globals therefore
-* sees exactly the schema it saw before. Only the mixed case makes either
-* argument optional, and the handler enforces the exclusivity there.
+* With no reachable global, `global` is left out and `collection` stays
+* required, so a deployment without globals sees an unchanged schema. Only the
+* mixed case makes either optional, and the handler enforces exclusivity there.
 */ const targetShape = (scope, operation, descriptions) => {
 	const { collections, globals } = slugsFor(scope, operation);
 	if (globals.length === 0) return widen({ collection: slugEnum(collections).describe(descriptions.collection) });
@@ -76,23 +80,23 @@ const slugsFor = (scope, operation) => {
 	});
 };
 /**
-* The `id` argument, which only a collection document has. Omitted when the key
-* can reach no collection, required when it can reach no global, and optional
-* in between, where `requireIdFor` enforces the dependency.
+* Only a collection document has one. Optional in the mixed case, where
+* `requireIdFor` enforces the dependency.
 */ const idShape = (scope, operation) => {
 	const { collections, globals } = slugsFor(scope, operation);
 	if (collections.length === 0) return widen({});
 	if (globals.length === 0) return widen({ id: idSchema });
 	return widen({ id: idSchema.optional().describe("Document id. Required with \"collection\"; must be omitted with \"global\".") });
 };
-/**
-* The `locale` argument, present only when localization is configured.
-*/ const localeShape = (scope, options) => {
+const localeShape = (scope, options) => {
 	if (!scope.locales) return widen({});
 	const locale = z.enum(scope.locales);
 	return widen({ locale: (options.required ? locale : locale.optional()).describe(options.description) });
 };
-const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.limits.maxDepth)}.`) });
+/**
+* Defaults to 0 rather than Payload's own default: a client usually wants ids
+* it can write back, and populating a relation costs a query.
+*/ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits.maxDepth).optional().describe(`Relationship population depth. Default 0, at most ${String(scope.limits.maxDepth)}.`) });
 /**
 * The locale to operate on: the explicit argument, else the request's, else
 * the default. `undefined` when localization is off.
@@ -133,9 +137,7 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits
 		slug: args.target.slug
 	});
 };
-/**
-* Resolves a collection label for the request's language.
-*/ const translateLabel = (scope, label, fallback) => {
+const translateLabel = (scope, label, fallback) => {
 	const { i18n, t } = scope.req;
 	const resolved = typeof label === "function" ? label({
 		i18n,
@@ -144,4 +146,4 @@ const depthShape = (scope) => ({ depth: z.number().int().min(0).max(scope.limits
 	return translateStatic(resolved, i18n) ?? fallback;
 };
 //#endregion
-export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };
+export { depthShape, draftSentence, idSchema, idShape, localeOf, localeShape, patchOnlySlugs, readTarget, sameInstant, slugEnum, slugsFor, targetShape, translateLabel };

package/dist/tools/target.mjs

@@ -6,13 +6,9 @@ const refOf = (target) => ({
 	slug: target.slug
 });
 /**
-* Resolves the `collection`/`global` arguments to one entity and checks the key
-* may perform `operation` on it.
-*
-* A tool's `inputSchema` returns a raw shape, which leaves no top-level
-* `.refine` to express "exactly one of collection and global". The rule is
-* enforced here instead, with a message naming the offending arguments so one
-* failed call teaches it.
+* A raw input shape leaves no top-level `.refine` to express "exactly one of
+* collection and global", so the rule is enforced here, with a message naming
+* the offending arguments.
 */ const resolveTarget = (scope, args, operation) => {
 	const { collection, global } = args;
 	const allowedSlugs = slugsFor(scope, operation);

package/dist/tools/validate-document.mjs

@@ -3,7 +3,15 @@ import { idShape, localeOf, localeShape, readTarget, targetShape } from "./share
 import { requireIdFor, resolveTarget } from "./target.mjs";
 import { defineMcpxTool } from "../types.mjs";
 import { collectPublishBlockers } from "../write/publish-blockers.mjs";
-const validateDocument = defineMcpxTool({
+/**
+* Gated on write rather than 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 runs over
+* every field rather than the subset the user can read. It carries no
+* `readOnlyHint`, because the traversal fires field hooks.
+*/ const validateDocument = defineMcpxTool({
 	name: "validateDocument",
 	description: `Reports what still prevents a human from publishing the draft, without writing anything. The same list patchDocument returns after a write; use it to check work or to answer "is this ready".