@abinnovision/payloadcms-mcpx 1.0.0-beta.3 → 1.0.0-beta.5

package/README.md

@@ -44,6 +44,9 @@ export default buildConfig({
         posts: { read: true, write: true },
         tags: true, // shorthand for { read: true }
       },
+      globals: {
+        "site-settings": { read: true, write: true },
+      },
       limits: { maxLimit: 25, maxDepth: 1 },
     }),
   ],
@@ -56,8 +59,8 @@ The plugin adds:
   JSON responses; `GET`/`DELETE` answer 405),
 - an `mcpx-api-keys` collection (admin group "MCP") holding the keys and their
   capability checkboxes,
-- a draft guard on every collection, so any write carrying the MCP request
-  marker lands as a draft, including writes made by custom tools.
+- a draft guard on every collection and global, so any write carrying the MCP
+  request marker lands as a draft, including writes made by custom tools.
 
 ## API keys
 
@@ -118,35 +121,39 @@ Claude Desktop (no direct HTTP header support) via `mcp-remote`:
 
 ## Tools
 
-The surface is fixed at seven tools plus your custom ones. `tools/list`
-reflects the key: write tools disappear for read-only keys, and every
-`collection` enum contains only the slugs the key may touch.
+The surface is fixed at seven tools plus your custom ones; exposing a global
+adds an argument, never a tool. `tools/list` reflects the key: write tools
+disappear for read-only keys, and every `collection` and `global` enum contains
+only the slugs the key may touch.
 
 | Tool               | Purpose                                                     | Key arguments                                                                                |
 | ------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
 | `listCapabilities` | What this key may do; call first to orient.                 | none                                                                                         |
-| `describeSchema`   | Field shape of one node; `next` lists the drill-down paths. | `collection`, `paths?`, `expand?`                                                            |
+| `describeSchema`   | Field shape of one node; `next` lists the drill-down paths. | `collection` \| `global`, `paths?`, `expand?`                                                |
 | `findDocuments`    | Query documents.                                            | `collection`, `where?`, `sort?`, `limit?`, `page?`, `depth?`, `select?`, `locale?`, `draft?` |
-| `getDocument`      | Read one document or a subtree of it.                       | `collection`, `id`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`                    |
-| `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection`, `id`, `locale`, `patches`, `expectedUpdatedAt?`                                |
+| `getDocument`      | Read one document or a subtree of it.                       | `collection` + `id` \| `global`, `path?` (JSON pointer), `depth?`, `locale?`, `draft?`       |
+| `patchDocument`    | Apply RFC 6902 operations to the current draft.             | `collection` + `id` \| `global`, `locale`, `patches`, `expectedUpdatedAt?`                   |
 | `createDocument`   | Create a draft from a minimal seed.                         | `collection`, `locale`, `data`                                                               |
-| `validateDocument` | Publish blockers without writing.                           | `collection`, `id`, `locale`                                                                 |
+| `validateDocument` | Publish blockers without writing.                           | `collection` + `id` \| `global`, `locale`                                                    |
 
 Rules the tools enforce and explain in their own descriptions:
 
-- `describeSchema` paths are dotted and stop at blocks fields, which list the
-  block slugs they accept; every node carries `next`, the ready-to-use paths
-  for those blocks (`layout.sections.sectionWrapper`), so pass an entry of
-  `next` as a `paths` element to descend. A block is described as it exists at
-  that position.
+- `describeSchema` paths stop at blocks fields, which list the block slugs they
+  accept; every node carries `next`, the ready-to-use paths for those blocks
+  (`/layout/sections/sectionWrapper`), so pass an entry of `next` as a `paths`
+  element to descend. A block is described as it exists at that position.
 - Field and collection `admin.description` values are included in
   `describeSchema` and `listCapabilities`, so intent written for the admin
   panel reaches the client. Strings and locale-keyed records pass through;
   functions and components are dropped.
 - Builtin tools reject unknown arguments by name instead of silently ignoring
   them.
-- A schema path becomes a patch pointer by replacing `.` with `/`, adding a
-  leading `/`, and replacing each `[]` with a 0-based index.
+- Every path this plugin accepts or reports is a JSON Pointer. A schema path
+  and a pointer into a document differ only in what stands in an element
+  position: a schema path writes `*` for an array element and names a block by
+  its slug, where a pointer carries a 0-based index. So `/items/*/title` is
+  written at `/items/0/title`, and `/layout/sections/hero` at
+  `/layout/sections/0`.
 - Adding a block requires `blockType` on the value; append with `/-`.
 - Clearing is `replace` with `null`; a list is emptied with `[]` and refuses
   `null`. `remove` is only valid on list elements, because Payload keeps
@@ -158,13 +165,55 @@ Rules the tools enforce and explain in their own descriptions:
   `deletedAt`) are never listed and never writable; `readOnly` fields are
   listed but refused on write.
 
+## Globals
+
+A global is exposed the same way a collection is, and reached through the same
+tools rather than tools of its own:
+
+```ts
+mcpxPlugin({
+  collections: { pages: { read: true, write: true } },
+  globals: { "site-settings": { read: true, write: true } },
+});
+```
+
+Two rules follow from a global being a singleton, and because JSON Schema cannot
+state either one, both are enforced in the handler and repeated in every
+affected tool description:
+
+- Pass exactly **one** of `collection` and `global`.
+- `id` is required with `collection` and must be omitted with `global`.
+
+Refusals name the offending argument and the slug, so one failed call teaches
+the rule. `findDocuments` and `createDocument` stay collection-only: there is
+nothing to list and nothing to create when the document always exists. They
+reject a `global` argument by name.
+
+Globals get their own `capabilities.globals.<name>` checkbox group, a separate
+namespace from `capabilities.collections.<name>`, so a global may share a
+camelCase name with a collection. Keys issued before a global was exposed have
+no such group, and an absent checkbox reads as `false`, so they stay closed to
+every global until one is ticked.
+
+Globals always carry `updatedAt` — Payload appends it and there is no
+`timestamps: false` for globals — so `expectedUpdatedAt` behaves as it does for
+collections. The one exception is a global that has never been saved: it has no
+`updatedAt` to compare against, so the first write must omit
+`expectedUpdatedAt`, and supplying one is refused as a concurrency failure.
+
+If `tools/list` omits `global` entirely, no global is exposed to that key; the
+argument only appears once one is. A deployment that uses no globals sees the
+tool schemas exactly as they were.
+
 ## Drafts and publish blockers
 
 Draft-only writing is enforced on the Payload operation, not in the tool
 handlers: a `beforeOperation` hook forces `draft: true` and strips `_status`
 from every write carrying the MCP request marker, so custom tools and anything
 else writing through the same request are covered too. A `beforeChange` hook
-refuses any write that would still not land as a draft.
+refuses any write that would still not land as a draft. Globals expose the same
+`beforeOperation` interception point at the same position in the operation, so
+they are guarded exactly as strongly as collections, exposed or not.
 
 Publish blockers are advisory. Payload skips validation on draft saves (unless
 `versions.drafts.validate` is set), so after every write the plugin re-runs
@@ -175,7 +224,8 @@ validated; field `beforeChange` hooks run again during the check, so they must
 be pure; and the check runs privileged, so blocker paths and messages may name
 fields the key's user cannot read (values are never included).
 Collections with `versions.drafts.validate: true` refuse invalid drafts
-outright; those failures come back as `validationErrors`.
+outright; those failures come back as `validationErrors`. Both carry pointers,
+restated from the dotted paths Payload reports internally.
 
 Writes also report `notApplied`: pointers whose value Payload kept unchanged,
 which happens when field-level access denies the update.
@@ -220,6 +270,10 @@ Builtin tools reject them instead.
 | `collections.<slug>.read`            | `true`                         | Expose `describeSchema`, `findDocuments`, `getDocument`.                                                           |
 | `collections.<slug>.write`           | `false`                        | Expose `patchDocument`, `createDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`. |
 | `collections.<slug>.allowLiveWrites` | `false`                        | Permit writes to a collection without drafts (they land live).                                                     |
+| `globals`                            | `{}`                           | Allow-list of globals. `true` means `{ read: true }`.                                                              |
+| `globals.<slug>.read`                | `true`                         | Expose `describeSchema`, `getDocument`.                                                                            |
+| `globals.<slug>.write`               | `false`                        | Expose `patchDocument`, `validateDocument`. Requires `versions.drafts` unless `allowLiveWrites`.                   |
+| `globals.<slug>.allowLiveWrites`     | `false`                        | Permit writes to a global without drafts (they land live).                                                         |
 | `userCollection`                     | `config.admin.user` or `users` | Auth collection the keys act as.                                                                                   |
 | `apiKeys.slug`                       | `mcpx-api-keys`                | Slug of the generated key collection.                                                                              |
 | `apiKeys.overrideCollection`         | none                           | Final override applied to the generated collection.                                                                |
@@ -243,15 +297,14 @@ key of every user.
 - The endpoint authenticates with Bearer keys only; admin JWTs and cookies are
   ignored. Keys cannot authenticate REST or GraphQL.
 - Every operation runs under the linked user with `overrideAccess: false`.
-- Not covered in v1: `delete` (no tool exists and none is generated), globals,
-  uploads. Custom tools are trusted code and can do what the linked user may.
+- Not covered in v1: `delete` (no tool exists and none is generated), uploads.
+  Custom tools are trusted code and can do what the linked user may.
 
 ## Non-goals of v1 / roadmap
 
-Globals, deletes, uploads, markdown authoring for rich text, row addressing by
-id instead of index, cross-locale publish blockers, pagination of
-`describeSchema` with `expand`, and a handler-level timeout are all deliberate
-omissions for now.
+Deletes, uploads, markdown authoring for rich text, row addressing by id
+instead of index, cross-locale publish blockers, pagination of `describeSchema`
+with `expand`, and a handler-level timeout are all deliberate omissions for now.
 
 ## License
 

package/dist/api-keys/fields.mjs

@@ -56,9 +56,10 @@ const checkbox = (name, description) => ({
 	}
 ];
 /**
-* One checkbox per exposed operation, grouped per collection and per custom
-* tool. Only operations the plugin config exposes get a checkbox, so a key can
-* never enable more than the config allows. Everything defaults to off.
+* One checkbox per exposed operation, grouped per collection, per global and
+* per custom tool. Only operations the plugin config exposes get a checkbox, so
+* a key can never enable more than the config allows. Everything defaults to
+* off, which is why a key issued before a capability existed stays closed to it.
 */ const createCapabilityFields = (options) => {
 	const collectionGroups = options.collections.map((collection) => ({
 		name: collection.fieldName,
@@ -66,16 +67,30 @@ const checkbox = (name, description) => ({
 		label: collection.slug,
 		fields: [...collection.read ? [checkbox("read", "Describe, find and read documents.")] : [], ...collection.write ? [checkbox("write", "Create, patch and validate drafts.")] : []]
 	}));
-	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
-	const groups = [...collectionGroups.length > 0 ? [{
-		name: "collections",
-		type: "group",
-		fields: collectionGroups
-	}] : [], ...toolCheckboxes.length > 0 ? [{
-		name: "tools",
+	const globalGroups = options.globals.map((global) => ({
+		name: global.fieldName,
 		type: "group",
-		fields: toolCheckboxes
-	}] : []];
+		label: global.slug,
+		fields: [...global.read ? [checkbox("read", "Describe and read this global.")] : [], ...global.write ? [checkbox("write", "Patch and validate this global's draft.")] : []]
+	}));
+	const toolCheckboxes = options.tools.map((tool) => checkbox(tool.name, tool.description));
+	const groups = [
+		...collectionGroups.length > 0 ? [{
+			name: "collections",
+			type: "group",
+			fields: collectionGroups
+		}] : [],
+		...globalGroups.length > 0 ? [{
+			name: "globals",
+			type: "group",
+			fields: globalGroups
+		}] : [],
+		...toolCheckboxes.length > 0 ? [{
+			name: "tools",
+			type: "group",
+			fields: toolCheckboxes
+		}] : []
+	];
 	if (groups.length === 0) return [];
 	return [{
 		name: CAPABILITIES_FIELD,

package/dist/capabilities.mjs

@@ -8,6 +8,7 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 * issued before a capability existed stay closed.
 */ const resolveCapabilities = (options, keyCapabilities) => {
 	const collectionsGroup = isRecord(keyCapabilities) ? keyCapabilities["collections"] : void 0;
+	const globalsGroup = isRecord(keyCapabilities) ? keyCapabilities["globals"] : void 0;
 	const toolsGroup = isRecord(keyCapabilities) ? keyCapabilities["tools"] : void 0;
 	const collections = {};
 	for (const collection of options.collections) {
@@ -17,14 +18,26 @@ const flag = (group, name) => isRecord(group) && group[name] === true;
 			write: collection.write && flag(group, "write")
 		};
 	}
+	const globals = {};
+	for (const global of options.globals) {
+		const group = isRecord(globalsGroup) ? globalsGroup[global.fieldName] : void 0;
+		globals[global.slug] = {
+			read: global.read && flag(group, "read"),
+			write: global.write && flag(group, "write")
+		};
+	}
 	const tools = {};
 	for (const tool of options.tools) tools[tool.name] = flag(toolsGroup, tool.name);
 	return {
 		collections,
+		globals,
 		tools
 	};
 };
-const readableSlugs = (capabilities) => Object.entries(capabilities.collections).filter(([, value]) => value.read).map(([slug]) => slug);
-const writableSlugs = (capabilities) => Object.entries(capabilities.collections).filter(([, value]) => value.write).map(([slug]) => slug);
+const pick = (entries, operation) => Object.entries(entries).filter(([, value]) => value[operation]).map(([slug]) => slug);
+const readableSlugs = (capabilities) => pick(capabilities.collections, "read");
+const writableSlugs = (capabilities) => pick(capabilities.collections, "write");
+const readableGlobalSlugs = (capabilities) => pick(capabilities.globals, "read");
+const writableGlobalSlugs = (capabilities) => pick(capabilities.globals, "write");
 //#endregion
-export { CAPABILITIES_FIELD, readableSlugs, resolveCapabilities, writableSlugs };
+export { CAPABILITIES_FIELD, readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs };

package/dist/endpoint/handler.mjs

@@ -1,4 +1,4 @@
-import { readableSlugs, resolveCapabilities, writableSlugs } from "../capabilities.mjs";
+import { readableGlobalSlugs, readableSlugs, resolveCapabilities, writableGlobalSlugs, writableSlugs } from "../capabilities.mjs";
 import { resolveApiKeyAuth } from "../auth/resolve.mjs";
 import { jsonRpcError } from "./result.mjs";
 import { createMcpServer } from "./server.mjs";
@@ -12,6 +12,8 @@ const buildScope = (req, options, capabilities) => {
 		capabilities,
 		readable: readableSlugs(capabilities),
 		writable: writableSlugs(capabilities),
+		readableGlobals: readableGlobalSlugs(capabilities),
+		writableGlobals: writableGlobalSlugs(capabilities),
 		locales: localization ? localization.localeCodes : null,
 		defaultLocale: localization ? localization.defaultLocale : null
 	};

package/dist/endpoint/result.mjs

@@ -1,3 +1,4 @@
+import { pointerFromPayloadPath } from "../schema/walk.mjs";
 import { APIError, ValidationError } from "payload";
 //#region src/endpoint/result.ts
 /**
@@ -41,12 +42,17 @@ import { APIError, ValidationError } from "payload";
 * Maps an exception thrown by a tool to a result the client can read.
 *
 * Payload's public errors keep their message and status; a `ValidationError`
-* also surfaces its per-field detail. Anything else is logged and reported as
-* an internal error so no stack or driver message leaks to the client.
+* also surfaces its per-field detail, with each field's path restated as a
+* JSON Pointer so it reads like every other path this plugin reports. Anything
+* else is logged and reported as an internal error so no stack or driver
+* message leaks to the client.
 */ const toToolError = (error, logger) => {
 	if (error instanceof ValidationError) return errorResult(error.message, {
 		status: error.status,
-		validationErrors: error.data.errors
+		validationErrors: error.data.errors.map((entry) => ({
+			...entry,
+			path: pointerFromPayloadPath(entry.path)
+		}))
 	});
 	if (error instanceof APIError && error.isPublic) return errorResult(error.message, { status: error.status });
 	logger.error({

package/dist/endpoint/server.mjs

@@ -18,7 +18,7 @@ import { z } from "zod";
 	const server = new McpServer({
 		name: options.serverInfo.name,
 		version: options.serverInfo.version
-	}, { instructions: "Start with listCapabilities, then describeSchema for the collection you work on. Writes always land as drafts; a human publishes." });
+	}, { instructions: "Start with listCapabilities, then describeSchema for the collection or global you work on. Writes always land as drafts; a human publishes." });
 	const guarded = (run) => async () => {
 		try {
 			return await run();

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
+import { McpxAuthResult, McpxCollectionCapabilities, McpxCollectionOptions, McpxGlobalOptions, McpxPluginOptions, McpxRequestContext, McpxResolvedCapabilities, McpxTool, McpxToolExtra, defineMcpxTool } from "./types.mjs";
 import { mcpxPlugin } from "./plugin.mjs";
 import { isMcpxRequest } from "./write/draft-guard.mjs";
 import { PublishBlocker } from "./write/publish-blockers.mjs";
-export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };
+export { type McpxAuthResult, type McpxCollectionCapabilities, type McpxCollectionOptions, type McpxGlobalOptions, type McpxPluginOptions, type McpxRequestContext, type McpxResolvedCapabilities, type McpxTool, type McpxToolExtra, type PublishBlocker, defineMcpxTool, isMcpxRequest, mcpxPlugin };

package/dist/options.d.mts

@@ -0,0 +1,2 @@
+import "./types.mjs";
+import "payload";

package/dist/options.mjs

@@ -30,6 +30,19 @@ const assertWritable = (collection, options) => {
 	if (collection.timestamps === false) fail(`Collection "${slug}" has timestamps disabled, which write tools need for concurrency checks.`);
 	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Collection "${slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
 };
+/**
+* Refuses globals that must never be reachable. Globals cannot be auth or
+* upload entities, so only Payload's own reserved namespace is left to guard.
+*/ const assertGlobalExposable = (global) => {
+	if (global.slug.startsWith("payload-")) fail(`Global "${global.slug}" cannot be exposed.`);
+};
+/**
+* `GlobalConfig` has no `timestamps` option and `sanitizeGlobal` always appends
+* `createdAt`/`updatedAt`, so the concurrency check the collection path guards
+* for is always available here. Drafts are the only requirement left.
+*/ const assertGlobalWritable = (global, options) => {
+	if (!options.hasDrafts && !options.allowLiveWrites) fail(`Global "${global.slug}" has no drafts. Enable versions.drafts or set allowLiveWrites.`);
+};
 const normalizeCollections = (config, options, apiKeysSlug) => {
 	const collections = config.collections ?? [];
 	const fieldNames = /* @__PURE__ */ new Set();
@@ -54,6 +67,30 @@ const normalizeCollections = (config, options, apiKeysSlug) => {
 		return [normalized];
 	});
 };
+const normalizeGlobals = (config, options) => {
+	const globals = config.globals ?? [];
+	const fieldNames = /* @__PURE__ */ new Set();
+	return Object.entries(options.globals ?? {}).flatMap(([slug, raw]) => {
+		if (raw === void 0) return [];
+		const global = globals.find((candidate) => candidate.slug === slug);
+		if (!global) return fail(`Exposed global "${slug}" does not exist.`);
+		assertGlobalExposable(global);
+		const settings = raw === true ? {} : raw;
+		const hasDrafts = hasDraftsEnabled(global);
+		const normalized = {
+			slug,
+			read: settings.read ?? true,
+			write: settings.write ?? false,
+			allowLiveWrites: settings.allowLiveWrites ?? false,
+			hasDrafts,
+			fieldName: toCamelCase(slug)
+		};
+		if (normalized.write) assertGlobalWritable(global, normalized);
+		if (fieldNames.has(normalized.fieldName)) fail(`Global "${slug}" maps to capability field "${normalized.fieldName}", which another exposed global already uses.`);
+		fieldNames.add(normalized.fieldName);
+		return [normalized];
+	});
+};
 const assertUserCollection = (config, slug) => {
 	const collection = (config.collections ?? []).find((candidate) => candidate.slug === slug);
 	if (!collection) fail(`User collection "${slug}" does not exist.`);
@@ -91,6 +128,7 @@ const normalizeLimits = (limits) => {
 	assertTools(tools);
 	return {
 		collections: normalizeCollections(config, options, apiKeysSlug),
+		globals: normalizeGlobals(config, options),
 		userCollection,
 		apiKeysSlug,
 		endpointPath: options.endpoint?.path ?? DEFAULT_ENDPOINT_PATH,
@@ -99,7 +137,7 @@ const normalizeLimits = (limits) => {
 		auth: options.auth,
 		serverInfo: {
 			name: options.serverInfo?.name ?? "payloadcms-mcpx",
-			version: options.serverInfo?.version ?? "1.0.0-beta.3"
+			version: options.serverInfo?.version ?? "0.0.0"
 		}
 	};
 };

package/dist/plugin.d.mts

@@ -2,7 +2,7 @@ import { McpxPluginOptions } from "./types.mjs";
 //#region src/plugin.d.ts
 /**
  * Mounts the MCP endpoint, adds the API key collection and installs the
- * draft guard on every collection.
+ * draft guard on every collection and global.
  */
 declare const mcpxPlugin: (options: McpxPluginOptions) => import("payload").Plugin;
 //#endregion

package/dist/plugin.mjs

@@ -1,12 +1,12 @@
 import { createApiKeysCollection } from "./api-keys/collection.mjs";
 import { createMcpxHandler, methodNotAllowed } from "./endpoint/handler.mjs";
 import { normalizeOptions } from "./options.mjs";
-import { installDraftGuards } from "./write/draft-guard.mjs";
+import { installDraftGuards, installGlobalDraftGuards } from "./write/draft-guard.mjs";
 import { definePlugin } from "payload";
 //#region src/plugin.ts
 /**
 * Mounts the MCP endpoint, adds the API key collection and installs the
-* draft guard on every collection.
+* draft guard on every collection and global.
 */ const mcpxPlugin = definePlugin({
 	slug: "@abinnovision/payloadcms-mcpx",
 	order: 100,
@@ -17,6 +17,7 @@ import { definePlugin } from "payload";
 		return {
 			...config,
 			collections: installDraftGuards([...config.collections ?? [], apiKeysCollection]),
+			globals: installGlobalDraftGuards(config.globals ?? []),
 			endpoints: [
 				...config.endpoints ?? [],
 				{

package/dist/schema/describe.mjs

@@ -1,25 +1,26 @@
-import { blockOf, blockSlugsOf, collectionOf, describeFields, findBlocksField, joinPath, splitPath } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/describe.ts
 const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor) => descriptor.type === "blocks");
 /**
 * Walks a schema path to the field list it addresses.
 *
 * A schema path alternates a blocks field's own path with the slug of one of
-* the blocks it accepts, so `layout.sections.sectionWrapper.modules.hero`
-* reaches `hero` as it exists under `pages` specifically.
-*/ const fieldsAtSchemaPath = (config, collection, schemaPath) => {
-	let fields = collection.flattenedFields;
+* the blocks it accepts, so `/layout/sections/sectionWrapper/modules/hero`
+* reaches `hero` as it exists under `pages` specifically. The slug sits where
+* a pointer into a document would carry the element's index.
+*/ const fieldsAtSchemaPath = (config, target, schemaPath) => {
+	let fields = target.flattenedFields;
 	let blockType;
-	let remaining = splitPath(schemaPath).filter(Boolean);
+	let remaining = splitPath(schemaPath);
 	while (remaining.length > 0) {
 		/**
 		* A blocks field's own path may span several segments
-		* (`layout.sections`), so the longest matching one is taken.
+		* (`/layout/sections`), so the longest matching one is taken.
 		*/ const match = blocksDescriptors(fields).map((descriptor) => splitPath(descriptor.path)).filter((parts) => parts.every((part, offset) => part === remaining[offset])).sort((left, right) => right.length - left.length)[0];
 		if (!match) throw new Error(`"${joinPath(remaining)}" does not address a blocks field. Blocks fields here: ${blocksDescriptors(fields).map((descriptor) => descriptor.path).join(", ") || "none"}`);
 		const slug = remaining.at(match.length);
 		const field = findBlocksField(fields, match);
-		if (!field) throw new Error(`"${match.join(".")}" could not be resolved.`);
+		if (!field) throw new Error(`"${joinPath(match)}" could not be resolved.`);
 		if (slug === void 0) throw new Error(`"${joinPath(match)}" is a blocks field; append one of: ${blockSlugsOf(field).join(", ")}`);
 		const block = blockOf(config, field, slug);
 		if (!block) throw new Error(`"${slug}" is not allowed at "${joinPath(match)}". Allowed: ${blockSlugsOf(field).join(", ")}`);
@@ -33,28 +34,25 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 	};
 };
 /**
-* Describes a collection root, or one block reached through a schema path.
-*/ const describeNode = (config, collection, schemaPath = "") => {
-	const { blockType, fields } = fieldsAtSchemaPath(config, collectionOf(config, collection), schemaPath);
+* Describes a collection or global root, or one block reached through a schema
+* path.
+*/ const describeNode = (config, ref, schemaPath = "") => {
+	const { blockType, fields } = fieldsAtSchemaPath(config, targetOf(config, ref), schemaPath);
 	const descriptors = describeFields(fields);
-	const next = descriptors.flatMap((descriptor) => (descriptor.blocks ?? []).map((slug) => [
-		schemaPath,
-		descriptor.path,
-		slug
-	].filter(Boolean).join(".")));
+	const next = descriptors.flatMap((descriptor) => (descriptor.blocks ?? []).map((slug) => `${schemaPath}${descriptor.path}/${slug}`));
 	return {
 		...blockType === void 0 ? {} : { blockType },
-		collection,
+		...ref.kind === "collection" ? { collection: ref.slug } : { global: ref.slug },
 		fields: descriptors,
 		...next.length > 0 ? { next } : {},
 		schemaPath
 	};
 };
 /**
-* Every schema path reachable from a collection root, capped at
+* Every schema path reachable from an entity root, capped at
 * {@link REACHABLE_PATHS_LIMIT}. `truncated` tells the caller the cap was hit
 * and explicit paths are the way to go deeper.
-*/ const reachableSchemaPaths = (config, collection) => {
+*/ const reachableSchemaPaths = (config, ref) => {
 	const seen = [];
 	let truncated = false;
 	const walk = (schemaPath, visited) => {
@@ -63,13 +61,9 @@ const blocksDescriptors = (fields) => describeFields(fields).filter((descriptor)
 			return;
 		}
 		seen.push(schemaPath);
-		for (const descriptor of describeNode(config, collection, schemaPath).fields) for (const slug of descriptor.blocks ?? []) {
+		for (const descriptor of describeNode(config, ref, schemaPath).fields) for (const slug of descriptor.blocks ?? []) {
 			if (visited.includes(slug)) continue;
-			walk([
-				schemaPath,
-				descriptor.path,
-				slug
-			].filter(Boolean).join("."), [...visited, slug]);
+			walk(`${schemaPath}${descriptor.path}/${slug}`, [...visited, slug]);
 		}
 	};
 	walk("", []);

package/dist/schema/pointer.mjs

@@ -1,10 +1,7 @@
-import { blockOf, blockSlugsOf, collectionOf, describeFields, findBlocksField, joinPath, splitPath } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath, targetOf } from "./walk.mjs";
 //#region src/schema/pointer.ts
 const isIndexSegment = (segment) => segment === "-" || /^\d+$/.test(segment);
-/**
-* Decodes a JSON Pointer into its segments, unescaping `~1` and `~0`.
-*/ const pointerSegments = (pointer) => pointer.split("/").slice(1).map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
-const partMatches = (part, segment) => segment !== void 0 && (part === "[]" ? isIndexSegment(segment) : part === segment);
+const partMatches = (part, segment) => segment !== void 0 && (part === "*" ? isIndexSegment(segment) : part === segment);
 /**
 * Longest descriptor whose path is fully consumed by the leading segments.
 */ const longestMatch = (descriptors, segments) => descriptors.map((descriptor) => ({
@@ -35,10 +32,10 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "[]" ? is
 * can only be resolved by reading `blockType` off `sections[3]`, since a blocks
 * field admits many shapes at the same index.
 */ const resolveDataPointer = (config, target) => {
-	let fields = collectionOf(config, target.collection).flattenedFields;
+	let fields = targetOf(config, target.ref).flattenedFields;
 	let data = target.doc;
 	let blockType;
-	let segments = pointerSegments(target.pointer);
+	let segments = splitPath(target.pointer);
 	while (segments.length > 0) {
 		const descriptors = describeFields(fields);
 		const match = longestMatch(descriptors, segments);
@@ -46,7 +43,7 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "[]" ? is
 			if (isSubtreePrefix(descriptors, segments)) return {
 				...blockType === void 0 ? {} : { blockType },
 				fields,
-				prefix: joinPath(segments)
+				prefix: segments
 			};
 			throw new Error(`"${joinPath(segments)}" is not a field here. Available: ${descriptors.map((descriptor) => descriptor.path).join(", ")}`);
 		}
@@ -55,9 +52,9 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "[]" ? is
 			...blockType === void 0 ? {} : { blockType },
 			descriptor: match.descriptor,
 			fields,
-			prefix: ""
+			prefix: []
 		};
-		if (match.descriptor.type !== "blocks") throw new Error(`"${match.descriptor.path}" is a ${match.descriptor.type} field and has no "${rest.join("/")}" beneath it.`);
+		if (match.descriptor.type !== "blocks") throw new Error(`"${match.descriptor.path}" is a ${match.descriptor.type} field and has no "${joinPath(rest)}" beneath it.`);
 		const [index, ...remaining] = rest;
 		if (!isIndexSegment(index)) throw new Error(`"${match.descriptor.path}" is an array; "${index}" is not an index.`);
 		const parts = splitPath(match.descriptor.path);
@@ -76,8 +73,8 @@ const partMatches = (part, segment) => segment !== void 0 && (part === "[]" ? is
 	return {
 		...blockType === void 0 ? {} : { blockType },
 		fields,
-		prefix: ""
+		prefix: []
 	};
 };
 //#endregion
-export { pointerSegments, resolveDataPointer };
+export { resolveDataPointer };

package/dist/schema/shape.mjs

@@ -1,4 +1,4 @@
-import { blockOf, blockSlugsOf, describeFields, findBlocksField, joinPath, splitPath } from "./walk.mjs";
+import { blockOf, blockSlugsOf, describeFields, findBlocksField, splitPath } from "./walk.mjs";
 //#region src/schema/shape.ts
 /**
 * Keys Payload manages on a row that a client may echo back harmlessly.
@@ -36,7 +36,7 @@ const isPlainObject = (value) => typeof value === "object" && value !== null &&
 };
 const checkLeafValue = (scope, descriptor, value) => {
 	if (descriptor.readOnly) {
-		scope.problems.push(`${scope.pointer}: "${descriptor.path}" is read-only and cannot be written.`);
+		scope.problems.push(`${scope.pointer}: this field is read-only and cannot be written.`);
 		return;
 	}
 	if (descriptor.type === "richText") {
@@ -61,7 +61,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 			...scope,
 			fields: block.flattenedFields,
 			pointer: `${scope.pointer}/${String(index)}`,
-			prefix: ""
+			prefix: []
 		}, row);
 	});
 };
@@ -76,7 +76,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 * block would be stripped in silence.
 */ const checkValue = (scope, value) => {
 	if (!isPlainObject(value)) return;
-	const prefixParts = scope.prefix ? splitPath(scope.prefix) : [];
+	const prefixParts = scope.prefix;
 	const relative = describeFields(scope.fields).flatMap((descriptor) => {
 		const parts = splitPath(descriptor.path);
 		return prefixParts.every((part, offset) => part === parts[offset]) ? [{
@@ -100,7 +100,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 			}, exact.descriptor, entry);
 			continue;
 		}
-		if (candidates.some(({ parts }) => parts[1] === "[]")) {
+		if (candidates.some(({ parts }) => parts[1] === "*")) {
 			if (!Array.isArray(entry)) {
 				scope.problems.push(`${pointer}: expected an array.`);
 				continue;
@@ -109,11 +109,11 @@ const checkLeafValue = (scope, descriptor, value) => {
 				checkValue({
 					...scope,
 					pointer: `${pointer}/${String(index)}`,
-					prefix: joinPath([
+					prefix: [
 						...prefixParts,
 						key,
-						"[]"
-					])
+						"*"
+					]
 				}, row);
 			});
 			continue;
@@ -121,7 +121,7 @@ const checkLeafValue = (scope, descriptor, value) => {
 		checkValue({
 			...scope,
 			pointer,
-			prefix: joinPath([...prefixParts, key])
+			prefix: [...prefixParts, key]
 		}, entry);
 	}
 };