fvtt-world-cli 1.2.0 → 1.2.1

package/dist/index.js

@@ -10,7 +10,7 @@ import { readFileSync as readFileSync2 } from "node:fs";
 import { createHash as createHash2, randomBytes as randomBytes2, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
 
 // ../protocol/src/constants.js
-var PROTOCOL_VERSION = "1.2.0";
+var PROTOCOL_VERSION = "1.2.1";
 var PROTOCOL_COMPONENTS = Object.freeze({
   MODULE: "module",
   CLI_DAEMON: "cli-daemon",
@@ -312,7 +312,10 @@ var batchIdsProperty = {
   }
 };
 var tokenIncludeProperty = {
-  include: { type: "array", items: { type: "string", enum: ["prepared"] } }
+  include: { type: "array", items: { type: "string", enum: ["prepared", "delta"] } }
+};
+var tokenListIncludeProperty = {
+  include: { type: "array", items: { type: "string", enum: ["delta"] } }
 };
 var compendiumIncludeProperty = {
   include: { type: "array", items: { type: "string", enum: ["effects"] } }
@@ -1757,6 +1760,16 @@ var compendiumCommands = {
       ...compendiumIncludeProperty
     },
     additionalProperties: false
+  }),
+  "compendium.get-many": cmd({
+    type: "object",
+    required: ["pack", "ids"],
+    properties: {
+      pack: { type: "string", minLength: 1 },
+      ...batchIdsProperty,
+      ...compendiumIncludeProperty
+    },
+    additionalProperties: false
   })
 };
 
@@ -3223,7 +3236,8 @@ var sceneEmbeddedCommands = {
     properties: {
       sceneId: { type: "string", minLength: 1 },
       ...nameFilterProperty,
-      ...paginationProperties
+      ...paginationProperties,
+      ...tokenListIncludeProperty
     },
     additionalProperties: false
   }),
@@ -3293,6 +3307,19 @@ var sceneEmbeddedCommands = {
     },
     { mutation: true }
   ),
+  "scene.token.restore-delta": cmd(
+    {
+      type: "object",
+      required: ["sceneId", "tokenId"],
+      properties: {
+        sceneId: { type: "string", minLength: 1 },
+        tokenId: { type: "string", minLength: 1 },
+        ...dryRunProperty
+      },
+      additionalProperties: false
+    },
+    { mutation: true }
+  ),
   ...batchWriteCommands("scene.token", {
     scopeProperties: sceneScopeProperties,
     createSchema: tokenCreateSchema,
@@ -5356,6 +5383,7 @@ var DEFAULT_COMMAND_PROFILE = deepFreeze({
   "scene.token.update": "allow",
   "scene.token.delete": "approve",
   "scene.token.clone": "allow",
+  "scene.token.restore-delta": "approve",
   "scene.token.create-many": "allow",
   "scene.token.update-many": "allow",
   "scene.token.delete-many": "approve",
@@ -5653,6 +5681,7 @@ var DEFAULT_COMMAND_PROFILE = deepFreeze({
   "compendium.list": "allow",
   "compendium.index": "allow",
   "compendium.get": "allow",
+  "compendium.get-many": "allow",
   "folder.list": "allow",
   "folder.get": "allow",
   "folder.create": "allow",
@@ -5682,7 +5711,12 @@ var DEFAULT_COMMAND_PROFILE = deepFreeze({
 
 // ../protocol/src/command-risk.js
 var DESTRUCTIVE_VERBS = Object.freeze(["delete", "delete-many"]);
-var DESTRUCTIVE_COMMANDS = Object.freeze(["chat.flush", "file.move", "scene.fog.reset"]);
+var DESTRUCTIVE_COMMANDS = Object.freeze([
+  "chat.flush",
+  "file.move",
+  "scene.fog.reset",
+  "scene.token.restore-delta"
+]);
 var APPROVE_EXTRA_COMMANDS = Object.freeze(["system.reload", "user.create"]);
 var DENIED_BY_DEFAULT_COMMANDS = Object.freeze([
   "macro.execute",
@@ -8833,7 +8867,10 @@ function parseActorIncludeFields(value) {
   ]);
 }
 function parseTokenIncludeFields(value) {
-  return parseAllowedIncludeFields(value, ["prepared"]);
+  return parseAllowedIncludeFields(value, ["prepared", "delta"]);
+}
+function parseTokenListIncludeFields(value) {
+  return parseAllowedIncludeFields(value, ["delta"]);
 }
 function parseSystemInfoIncludeFields(value) {
   return parseAllowedIncludeFields(value, ["modules"]);
@@ -10366,8 +10403,11 @@ function renderBroadcastLines(result) {
     `dispatched: ${Boolean(result?.dispatched)} \u2014 a broadcast writes nothing, so there is no state to confirm afterwards`
   ];
 }
-function renderCompendiumSourceLines(document) {
-  return document?.compendiumSource ? [`compendiumSource: ${document.compendiumSource}`] : [];
+function renderProvenanceLines(document) {
+  return [
+    ...document?.compendiumSource ? [`compendiumSource: ${document.compendiumSource}`] : [],
+    ...document?.duplicateSource ? [`duplicateSource: ${document.duplicateSource}`] : []
+  ];
 }
 function renderOwnershipLines(ownership) {
   if (!ownership || typeof ownership !== "object") {
@@ -10479,7 +10519,7 @@ function renderItemDetails(item, prefixLines = []) {
   if (item && Object.hasOwn(item, "effects")) {
     lines.push(`effects: ${JSON.stringify(item.effects ?? [], null, 2)}`);
   }
-  lines.push(...renderCompendiumSourceLines(item));
+  lines.push(...renderProvenanceLines(item));
   if (item && Object.hasOwn(item, "ownership")) {
     lines.push(...renderOwnershipLines(item.ownership));
   }
@@ -10505,7 +10545,7 @@ function renderActorDetails(actor) {
   if (actor && Object.hasOwn(actor, "effects")) {
     lines.push(`effects: ${JSON.stringify(actor.effects ?? [], null, 2)}`);
   }
-  lines.push(...renderCompendiumSourceLines(actor));
+  lines.push(...renderProvenanceLines(actor));
   if (actor && Object.hasOwn(actor, "ownership")) {
     lines.push(...renderOwnershipLines(actor.ownership));
   }
@@ -10551,7 +10591,7 @@ function renderCardsDetails(cards) {
     `cards: ${rows.length}`,
     ...rows.map((card) => `  ${renderCardLine(card)}`)
   ];
-  lines.push(...renderCompendiumSourceLines(cards));
+  lines.push(...renderProvenanceLines(cards));
   if (cards && Object.hasOwn(cards, "ownership")) {
     lines.push(...renderOwnershipLines(cards.ownership));
   }
@@ -11090,7 +11130,7 @@ function renderJournalDetails(journal) {
     `sort: ${journal?.sort ?? 0}`,
     `pages: ${pages.length}`
   ];
-  lines.push(...renderCompendiumSourceLines(journal));
+  lines.push(...renderProvenanceLines(journal));
   if (journal && Object.hasOwn(journal, "ownership")) {
     lines.push(...renderOwnershipLines(journal.ownership));
   }
@@ -11206,7 +11246,7 @@ function renderMacroDetails(macro) {
     `flags: ${JSON.stringify(macro?.flags ?? {}, null, 2)}`,
     `command: ${macro?.command ?? ""}`
   ];
-  lines.push(...renderCompendiumSourceLines(macro));
+  lines.push(...renderProvenanceLines(macro));
   if (macro && Object.hasOwn(macro, "ownership")) {
     lines.push(...renderOwnershipLines(macro.ownership));
   }
@@ -11229,7 +11269,7 @@ function renderPlaylistDetails(playlist) {
     `flags: ${JSON.stringify(playlist?.flags ?? {}, null, 2)}`,
     `sounds: ${playlist?.sounds?.length ?? 0}`
   ];
-  lines.push(...renderCompendiumSourceLines(playlist));
+  lines.push(...renderProvenanceLines(playlist));
   if (playlist && Object.hasOwn(playlist, "ownership")) {
     lines.push(...renderOwnershipLines(playlist.ownership));
   }
@@ -11288,7 +11328,7 @@ function renderSceneDetails(scene) {
   for (const level of Array.isArray(scene?.levels) ? scene.levels : []) {
     lines.push(`level: ${renderLevelRow(level)}`);
   }
-  lines.push(...renderCompendiumSourceLines(scene));
+  lines.push(...renderProvenanceLines(scene));
   if (scene && Object.hasOwn(scene, "ownership")) {
     lines.push(...renderOwnershipLines(scene.ownership));
   }
@@ -11328,11 +11368,29 @@ function renderTokenDetails(sceneId, token) {
     `disposition: ${token?.disposition ?? ""}`,
     `texture: ${JSON.stringify(token?.texture ?? null)}`
   ];
+  if (token && Object.hasOwn(token, "delta")) {
+    lines.push(`delta: ${token.delta === null ? "none" : "stored (use --json for values)"}`);
+  }
   if (token && Object.hasOwn(token, "prepared")) {
     lines.push(`prepared: ${Object.keys(token.prepared ?? {}).join(", ")} (use --json for values)`);
   }
   return lines.join("\n");
 }
+function tokenDeltaSummaryCell(token) {
+  if (!token || !Object.hasOwn(token, "deltaSummary")) return "";
+  const summary = token.deltaSummary;
+  if (summary === null) return "	overrides=none";
+  return `	overrides=${(summary.overriddenKeys ?? []).join(",")} (item entries ${summary.itemEntries}, effect entries ${summary.effectEntries})`;
+}
+function renderTokenDeltaRestore(result) {
+  const discarded = result.discarded;
+  const verb = result.dryRun ? "[dry-run] would discard" : "Discarded";
+  return [
+    `scene: ${result.sceneId}`,
+    `token: ${result.tokenId}`,
+    result.changed ? `${verb} token overrides: ${(discarded?.overriddenKeys ?? []).join(", ")} (item entries ${discarded?.itemEntries ?? 0}, effect entries ${discarded?.effectEntries ?? 0})` : "No token-level overrides; nothing to restore."
+  ].join("\n");
+}
 function tokenItemPrefix(result) {
   const lines = [
     `scene: ${result.sceneId}`,
@@ -11617,7 +11675,7 @@ function renderTableDetails(table) {
     `results: ${results.length}`,
     ...results.map((result) => `  ${renderTableResultLine(result)}`)
   ];
-  lines.push(...renderCompendiumSourceLines(table));
+  lines.push(...renderProvenanceLines(table));
   if (table && Object.hasOwn(table, "ownership")) {
     lines.push(...renderOwnershipLines(table.ownership));
   }
@@ -12407,6 +12465,17 @@ var RENDERERS = registerRenderers([
       `document: ${JSON.stringify(result.document ?? null, null, 2)}`
     ].join("\n")
   ),
+  customRenderer("compendium.get-many", (result) => {
+    const entries = result.entries ?? [];
+    return [
+      `pack: ${result.pack}`,
+      `Entries (${entries.length})`,
+      ...entries.map(
+        (entry) => `${entry.entryId}	${entry.documentName ?? ""}	${entry.document?.name ?? ""}${Array.isArray(entry.effects) ? `	effects=${entry.effects.length}` : ""}`
+      ),
+      "(use --json for the documents)"
+    ].join("\n");
+  }),
   listRenderer("folder.list", {
     key: "folders",
     empty: "No folders found.",
@@ -12540,13 +12609,14 @@ var RENDERERS = registerRenderers([
     empty: "No tokens found.",
     heading: "Tokens",
     prefix: scenePrefix,
-    row: (token) => `${token.id}	${token.name}	actor=${token.actorId ?? "-"}	linked=${String(Boolean(token.actorLink))}	(${token.x},${token.y})${levelMembershipCell(token)}`
+    row: (token) => `${token.id}	${token.name}	actor=${token.actorId ?? "-"}	linked=${String(Boolean(token.actorLink))}	(${token.x},${token.y})${levelMembershipCell(token)}${tokenDeltaSummaryCell(token)}`
   }),
   detailRenderer(
     ["scene.token.get", "scene.token.create", "scene.token.update", "scene.token.clone"],
     (result) => renderTokenDetails(result.sceneId, result.token)
   ),
   deleteRenderer("scene.token.delete", "token", { suffix: sceneSuffix }),
+  detailRenderer("scene.token.restore-delta", (result) => renderTokenDeltaRestore(result)),
   listRenderer("scene.token.item.list", {
     key: "items",
     empty: "No items found.",
@@ -15684,11 +15754,18 @@ function registerCombat({ program, dependencies }) {
 }
 
 // src/commands/compendium.ts
+function addCompendiumIncludeOption(command) {
+  return command.option(
+    "--include <fields>",
+    "Comma-separated extra fields to include (allowed: effects)",
+    parseCompendiumIncludeFields
+  );
+}
 function registerCompendium({ program, dependencies }) {
   const compendium = program.command("compendium").description("Foundry compendium pack commands (read)");
   compendium.addHelpText(
     "after",
-    "\nResult key (--json): .result.packs[] (list), .result.entries[] (index), .result.document (get \u2014 Foundry's raw source object)."
+    "\nResult key (--json): .result.packs[] (list), .result.entries[] (index), .result.document (get \u2014 Foundry's raw source object plus id, compendiumSource and duplicateSource), .result.entries[] (get-many \u2014 one get result per requested id, in request order)."
   );
   addPaginationOptions(compendium.command("list")).action(async function listCompendiums(options) {
     await executeRemoteCommand({
@@ -15718,10 +15795,8 @@ function registerCompendium({ program, dependencies }) {
       dependencies
     });
   });
-  compendium.command("get").requiredOption("--pack <pack>", "Compendium pack id").requiredOption("--entry-id <entryId>", "Compendium entry id").option(
-    "--include <fields>",
-    "Comma-separated extra fields to include (allowed: effects)",
-    parseCompendiumIncludeFields
+  addCompendiumIncludeOption(
+    compendium.command("get").requiredOption("--pack <pack>", "Compendium pack id").requiredOption("--entry-id <entryId>", "Compendium entry id")
   ).action(async function getCompendiumEntry(options) {
     await executeRemoteCommand({
       commandName: "compendium.get",
@@ -15734,6 +15809,20 @@ function registerCompendium({ program, dependencies }) {
       dependencies
     });
   });
+  addCompendiumIncludeOption(
+    compendium.command("get-many").description("Read several entries of one compendium pack in a single call").requiredOption("--pack <pack>", "Compendium pack id").requiredOption("--ids <list>", "Comma-separated entry ids (atomic: all must exist)", parseIdList)
+  ).action(async function getManyCompendiumEntries(options) {
+    await executeRemoteCommand({
+      commandName: "compendium.get-many",
+      params: {
+        pack: options.pack,
+        ids: options.ids,
+        ...options.include ? { include: options.include } : {}
+      },
+      command: this,
+      dependencies
+    });
+  });
 }
 
 // src/commands/config.ts
@@ -17028,17 +17117,26 @@ function registerScene({ program, dependencies }) {
   const sceneToken = scene.command("token").description("Scene-embedded token commands");
   addNameFilterOption(
     addPaginationOptions(sceneToken.command("list").requiredOption("--scene-id <sceneId>", "Scene id"))
+  ).option(
+    "--include <fields>",
+    "Comma-separated extra fields to include (allowed: delta \u2014 a derived per-token summary of the token-level overrides, null when there are none)",
+    parseTokenListIncludeFields
   ).action(async function listSceneTokens(options) {
     await executeRemoteCommand({
       commandName: "scene.token.list",
-      params: { sceneId: options.sceneId, ...nameFilterParams(options), ...paginationParams(options) },
+      params: {
+        sceneId: options.sceneId,
+        ...nameFilterParams(options),
+        ...paginationParams(options),
+        ...options.include ? { include: options.include } : {}
+      },
       command: this,
       dependencies
     });
   });
   sceneToken.command("get").requiredOption("--scene-id <sceneId>", "Scene id").requiredOption("--token-id <tokenId>", "Token id").option(
     "--include <fields>",
-    "Comma-separated extra fields to include (allowed: prepared)",
+    "Comma-separated extra fields to include (allowed: prepared, delta \u2014 the stored ActorDelta source, null for a linked token or when none is stored)",
     parseTokenIncludeFields
   ).action(async function getSceneToken(options) {
     await executeRemoteCommand({
@@ -17093,6 +17191,16 @@ function registerScene({ program, dependencies }) {
       dependencies
     });
   });
+  sceneToken.command("restore-delta").description(
+    "Discard every token-level override of an unlinked token (items, effects, system data, name, \u2026) so it follows its world actor again"
+  ).requiredOption("--scene-id <sceneId>", "Scene id").requiredOption("--token-id <tokenId>", "Unlinked token id").action(async function restoreSceneTokenDelta(options) {
+    await executeRemoteCommand({
+      commandName: "scene.token.restore-delta",
+      params: { sceneId: options.sceneId, tokenId: options.tokenId },
+      command: this,
+      dependencies
+    });
+  });
   registerBatchWriteCommands(sceneToken, {
     prefix: "scene.token",
     noun: "token",

package/docs/commands.md

@@ -17,8 +17,9 @@ becomes `scene token get`. Nested commands require the parent IDs as well as the
 
 With a bridge connected, discovery omits denied commands and marks approval requirements with
 `approval: true`. If the daemon or bridge is unavailable, it returns the static registry with
-`policy.applied: false`. Authentication and protocol errors do not trigger that fallback.
-`schema` and `--help` always describe the static registry, including denied commands.
+`policy.applied: false`; `policy` sits at the top level of the response, beside `result`.
+Authentication and protocol errors do not trigger that fallback. `schema` and `--help` always
+describe the static registry, including denied commands.
 
 ## Capability map
 
@@ -164,13 +165,15 @@ Use JSON flags such as `--data-json` and `--patch-json` for structured values. U
 
 - Nested objects merge recursively.
 - Ordinary arrays replace as a whole.
-- Dotted paths target object properties where permitted; dotted writes inside arrays are refused.
-- Foundry deletion syntax can remove permitted nested keys.
+- Dotted paths target object properties where permitted; a top-level dotted write into an array
+  field, such as `c.0`, is refused.
+- Foundry's operator keys work at any permitted nested level: `{"-=key": null}` deletes the key,
+  and `{"==key": value}` replaces the key's whole value instead of merging into it.
 - Embedded collections follow their family's Foundry semantics.
 
 Read arrays before editing and preserve unchanged values. For a wall's `c` field, send the complete
-`[x1, y1, x2, y2]`, not `c.0`. Invalid or ambiguous patch shapes return `INVALID_PARAMS` before
-mutation, including in bulk writes and dry runs. Correct the fields identified by the error.
+`[x1, y1, x2, y2]`, not `c.0`. Array writes that Foundry would discard return `INVALID_PARAMS`
+before mutation, including in bulk writes and dry runs. Correct the fields identified by the error.
 
 Prefer dedicated commands for creating embedded documents. A parent update that adds entries
 without `_id`, such as new `behaviors` in `scene.region.update`, can create them but return an
@@ -190,6 +193,12 @@ A timeout or disconnect can happen after a write commits. An update error with `
 or `details.indeterminate` can also mean that some changes persisted. Read affected state before
 retrying and send only what remains to be done.
 
+An update whose stored state differs from the request fails with `INTERNAL_ERROR`, and
+`details.paths` lists the differing paths with the requested and the stored value. Foundry core, the
+game system or a module may have changed the value; Foundry stores a raw `&` in rich text as
+`&`, for example. The bridge cannot tell which, so the caller judges from the values. Sending
+the same patch again stores the same result.
+
 An idempotency key identifies one logical request and can prevent duplicate effects while its
 cached state survives. Reuse it only for the same request; a corrected or remaining patch is a
 new operation and needs a fresh key. Follow the [delivery rules](protocol.md#delivery-states-and-retries)

package/docs/compatibility.md

@@ -11,6 +11,7 @@ The bridge supports Foundry VTT v13 and v14. Check your connected version with
 | Scene thumbnail rendering | Renders the scene | Renders the scene's initial level by default | On v14, expect the initial level in the thumbnail. Check the returned dimensions and image. |
 | Scene thumbnail files | Uses a stable scene-based filename | Uses a filename based on the image content | Use the returned path. On v14, a changed image can leave an older thumbnail file behind. |
 | User permission names | `TEMPLATE_CREATE` | `REGION_CREATE` | Use the permission keys reported by the connected Foundry version when calling `user.permissions.set`. |
+| Legacy update operators `-=key` (deletion) and `==key` (forced replacement) | Work without a warning | Work, and the GM browser console logs a deprecation warning for each such key, stating that support will be removed in Version 16 | Nothing changes for v13 or v14 writes. The bridge passes the operator keys through without translating them to Foundry 14's operator objects, so they will stop working once Foundry removes them. |
 
 Scene placeable fields and available region behavior types also differ. Read the target document
 before preparing a patch; valid data from one version is not automatically valid on the other.

package/docs/protocol.md

@@ -181,6 +181,9 @@ filters apply before pagination. Previewed documents have no persistent identity
 observed during a preview must not be reused. Some result fields depend on the connected Foundry
 version; [Foundry compatibility](compatibility.md) lists them.
 
+World document reads carry `compendiumSource` and `duplicateSource`, hoisted from Foundry's
+`_stats` and `null` when absent.
+
 Broadcast actions report `dispatched` and target users rather than a confirmed player-side result.
 The active/inactive split is included where knowable.
 
@@ -196,10 +199,12 @@ world state when the return value does not establish the effect.
 
 ### Setting results
 
-Setting writes return the observed `value` and its `previous` value. Registered types or callbacks
-may normalize the input. Confirmation establishes that the previous value changed, not that the
-requested value was stored exactly. Writing an already-stored value succeeds as unchanged without
-calling Foundry. `requiresReload: true` indicates that the GM client needs a reload.
+Setting writes return the observed `value` and its `previous` value, as `game.settings.get`
+returns them after the registered type's cast. Confirmation compares the JSON Foundry stores with
+the JSON of the validated request; a different stored value, for example one rewritten by an
+`onChange` callback, is a mismatch error with a `paths` entry for `value`. Writing an
+already-stored value succeeds as unchanged without calling Foundry. `requiresReload: true`
+indicates that the GM client needs a reload.
 
 ## Write confirmation
 
@@ -207,11 +212,24 @@ Document writes report success only after confirmation. Foundry can resolve a ve
 write without throwing, and hooks can remove or rewrite part of a patch. Single and bulk updates
 pass Foundry a private copy, then compare stored state with the original request.
 
+Confirmation compares each requested leaf path that survives Foundry's cleaning with the stored
+source. Foundry drops a key the document's schema does not declare without an error before that
+comparison, so a write made only of undeclared keys reports success with nothing stored. A deletion (`-=key` or
+Foundry 14's `ForcedDeletion`) is confirmed when the key is absent. A forced replacement (`==key`
+or Foundry 14's `ForcedReplacement`) is confirmed when the whole stored value at that path equals the requested
+value after Foundry's cleaning.
+
 A valid patch whose requested state is already stored remains a successful no-op. A validation
 failure recovered after an unwritten update returns `INVALID_PARAMS`. Unconfirmed, partial, or
 indeterminate updates can return `INTERNAL_ERROR` with these details:
 
-- `fields`: requested fields whose state was not confirmed.
+- `fields`: requested top-level fields whose state was not confirmed.
+- `paths`: up to 20 entries `{ path, requested, stored }`, one per leaf path where the stored value
+  differs from the request. `absent: "stored"` replaces `stored` when the key is missing from the
+  stored source, and `absent: "requested"` replaces `requested` for a deletion that did not land.
+  A long string, or an object or array whose JSON is long, is shortened to a window around the
+  first differing character; `truncated` then carries `format` (`text` or `json`), `offset`, and
+  the full `requestedLength` and `storedLength`. `pathsTruncated` counts the entries beyond 20.
 - `partial: true`: stored data changed in a requested field, but the full requested state was
   not reached. A hook may have applied only part of a nested object or replaced a value.
 - `changedFields`: requested top-level fields observed to change, including fields that changed
@@ -221,6 +239,12 @@ indeterminate updates can return `INTERNAL_ERROR` with these details:
 - `indeterminate: true`: confirmation could not establish the outcome. Some or all of the write
   may have persisted. `changedFields` is `null` when the before/after comparison was unavailable.
 
+When stored differs from requested, the message says that the bridge cannot verify whether Foundry
+core, the game system or a module normalized the value, or whether a hook rewrote, dropped or vetoed
+the change. A blocking module is listed as one possible cause, never as the diagnosis. Resending the
+same patch does not change the result. Every confirmed write that can report a mismatch carries the
+same `paths`, and so does a `dropped` bulk outcome when the stored state was compared.
+
 Parent patches that create embedded entries without `_id`, such as new `behaviors` in
 `scene.region.update`, return an indeterminate error after writing because parent update results
 cannot confirm those creations. A retry may duplicate them. Read the embedded collection first,
@@ -231,10 +255,10 @@ new operation with a fresh idempotency key if using one.
 
 ### Patch shape checks
 
-Single updates, bulk updates, and dry runs reject ambiguous field spellings, invalid or discarded
-array values, and dotted writes inside arrays with `INVALID_PARAMS` before mutation. Recognized
-legacy fields are checked against their migrated destinations as well. Send whole arrays; ordinary
-dotted object-property writes remain supported where the schema permits them.
+Single updates, bulk updates, and dry runs reject invalid or discarded array values, top-level
+dotted writes into array fields, and writes to legacy fields the running core moved, with
+`INVALID_PARAMS` before mutation. Send whole arrays; ordinary dotted object-property writes remain
+supported where the schema permits them. Other key spellings reach Foundry as written.
 
 Errors identify the `field` and may include `arrayField`, `requested`, `stored`, or migration
 destination details. Bulk failures add the entry's `index` and `id`; single failures use document

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fvtt-world-cli",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Safe local CLI and authenticated bridge for automating live Foundry VTT worlds.",
   "keywords": [
     "foundry-vtt",
@@ -56,6 +56,6 @@
     "zod": "^3.24.3"
   },
   "devDependencies": {
-    "@fvtt-world-cli/protocol": "1.2.0"
+    "@fvtt-world-cli/protocol": "1.2.1"
   }
 }

package/skills/foundry-world-editor/SKILL.md

@@ -80,6 +80,9 @@ level ids in a preview are provisional.
 Deleting a level also deletes its tokens and every placeable only on that level, and the dry run
 does not list them: read the scene's placeables (token `level`, others' `levels`) and tell the user
 what the delete removes before running it.
+An unlinked token keeps its own overrides, which edits to its world actor never reach. Before
+editing an actor that has placed tokens, read its tokens' overrides and tell the user which tokens
+the edit will not change.
 `setting.set` cannot touch this module's own namespace (`SETTING_PROTECTED` is final; never retry).
 When a setting write returns `requiresReload: true`, the change needs a GM-client reload to take
 effect; `system.reload` performs it, drops the bridge, and requires a reconnect wait before the
@@ -92,12 +95,13 @@ signal, not a failure — reconnect and continue rather than retrying the reload
 Discover → inspect schema → locate → read → smallest patch → dry-run → commit → verify. Never
 guess a command name or parameter.
 
-1. Run `fvtt-world-cli commands --json`. Continue only when `policy.applied` is `true` and the
-   required command is present. A `false` value means no bridge answered and the output is the static
-   registry, not the client's permissions. Report an absent command instead of seeking another way
-   to produce the same effect. Warn the user before a command marked `"approval": true`, and prefer
-   one `*-many` command when it can replace several approvals. Dotted protocol names map to spaced
-   CLI subcommands, such as `actor.item.update` to `actor item update`.
+1. Run `fvtt-world-cli commands --json`. Continue only when `policy.applied` (top level, beside
+   `result`) is `true` and the required command is present. A `false` value means no bridge
+   answered and the output is the static registry, not the client's permissions. Report an absent
+   command instead of seeking another way to produce the same effect. Warn the user before a
+   command marked `"approval": true`, and prefer one `*-many` command when it can replace several
+   approvals. Dotted protocol names map to spaced CLI subcommands, such as `actor.item.update` to
+   `actor item update`.
 2. `fvtt-world-cli schema <command>` shows the exact request parameters, required fields, enums,
    and whether unknown fields are accepted; `fvtt-world-cli <command path> --help` maps flags.
 3. Locate targets with the narrowest query: a family `list --name <substring> --limit <n>` when
@@ -106,8 +110,9 @@ guess a command name or parameter.
    never the basis of a write.
 4. `get` the complete target before mutating and work from the returned ids.
 5. Build the smallest valid patch. Nested objects merge recursively; plain arrays replace
-   wholesale; dotted paths reach permitted leaves; deletion operators remove permitted keys. A
-   `get` result contains read-only and derived fields, so build the patch from accepted fields only.
+   wholesale; dotted paths reach permitted leaves; `{"-=key": null}` deletes a permitted key, and
+   `{"==key": value}` replaces its whole value instead of merging. A `get` result contains
+   read-only and derived fields, so build the patch from accepted fields only.
    For arrays and extensible `system`/`flags` data: read, preserve everything that
    stays, change only the intended part.
 6. Dry-run every nontrivial mutation with the global `--dry-run` flag. It runs the same
@@ -171,6 +176,10 @@ Classify a failure before reacting:
   observed to change, not fully applied nested values. An embedded creation without a requested
   id may already exist despite an indeterminate error. Send only the remaining changes as a new
   operation with a fresh idempotency key, if using one.
+- An update `INTERNAL_ERROR` with `details.paths` is a stored-vs-requested mismatch. Compare
+  `requested` and `stored` for each path. A representation-only difference, such as HTML escaping (`&` stored as `&amp;`) or
+  whitespace, can be accepted as done. Report any other difference to the user. The same patch
+  stores the same result, so the next request is either a different patch or none.
 - Correct a structured Foundry rejection and submit the corrected content as a new operation.
 
 ## Bulk writes and actions

package/skills/foundry-world-editor/SKILL.md.sha256

@@ -1 +1 @@
-248c52464e776236de6f937530e220dcb77b45a8b5cc754adbb4cfb4671a8c66
+5b4188ba39ed8f9f1c041cec9c5f0c3fb5d05db7910670d0ff2bb9c5d7d43dde