fvtt-world-cli 1.2.0 → 1.3.0

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.3.0";
 var PROTOCOL_COMPONENTS = Object.freeze({
   MODULE: "module",
   CLI_DAEMON: "cli-daemon",
@@ -76,6 +76,9 @@ function resolveEffectiveLimits(uploadLimitBytes = DEFAULT_UPLOAD_SIZE_LIMIT_BYT
     wsMaxPayloadBytes: Math.max(wsMaxPayloadForUploadLimit(uploadLimitBytes), DEFAULT_WS_MAX_PAYLOAD_BYTES)
   };
 }
+var BROWSER_STRING_MAX_LENGTH = 536870888;
+var READ_RESPONSE_ENVELOPE_RESERVE_CHARS = 1024 * 1024;
+var READ_ENCODING_CEILING_BYTES = Math.floor((BROWSER_STRING_MAX_LENGTH - READ_RESPONSE_ENVELOPE_RESERVE_CHARS) / 4) * 3;
 var BATCH_GET_MAX_IDS = 100;
 var BATCH_WRITE_MAX_ITEMS = 100;
 var BATCH_WRITE_STATUSES = Object.freeze([
@@ -102,6 +105,7 @@ var SCENE_THUMBNAIL_MAX_BYTES = 2 * 1024 * 1024;
 var SCENE_THUMBNAIL_RESPONSE_MAX_BYTES = 1024 * 1024;
 var TABLE_DRAW_MAX_COUNT = 100;
 var SETTING_VALUE_MAX_BYTES = 256 * 1024;
+var SERIALIZE_OMISSIONS_MAX = 100;
 var MACRO_EXECUTE_TIMEOUT_DEFAULT_MS = 3e4;
 var MACRO_EXECUTE_TIMEOUT_MAX_MS = 3e5;
 var SEARCH_MODES = Object.freeze(["name", "full"]);
@@ -189,6 +193,7 @@ var ERROR_CODES = Object.freeze({
   PLAYLIST_NOT_FOUND: "PLAYLIST_NOT_FOUND",
   PLAYLIST_SOUND_NOT_FOUND: "PLAYLIST_SOUND_NOT_FOUND",
   JOURNAL_CATEGORY_NOT_FOUND: "JOURNAL_CATEGORY_NOT_FOUND",
+  JOURNAL_PAGE_NOT_FOUND: "JOURNAL_PAGE_NOT_FOUND",
   CHAT_MESSAGE_NOT_FOUND: "CHAT_MESSAGE_NOT_FOUND",
   TABLE_NOT_FOUND: "TABLE_NOT_FOUND",
   TABLE_RESULT_NOT_FOUND: "TABLE_RESULT_NOT_FOUND",
@@ -204,7 +209,6 @@ var ERROR_CODES = Object.freeze({
   FOLDER_NOT_FOUND: "FOLDER_NOT_FOUND",
   SETTING_NOT_FOUND: "SETTING_NOT_FOUND",
   SETTING_READ_FAILED: "SETTING_READ_FAILED",
-  SETTING_VALUE_NOT_SERIALIZABLE: "SETTING_VALUE_NOT_SERIALIZABLE",
   SETTING_PROTECTED: "SETTING_PROTECTED",
   SETTING_UNREGISTERED: "SETTING_UNREGISTERED",
   MACRO_TIMEOUT: "MACRO_TIMEOUT",
@@ -312,7 +316,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"] } }
@@ -812,6 +819,11 @@ var actorCommands = {
     },
     { mutation: true }
   ),
+  ...batchWriteCommands("actor.item", {
+    scopeProperties: actorScopeProperties,
+    createSchema: embeddedItemDataSchema,
+    patchSchema: itemPatchSchema
+  }),
   ...batchWriteCommands("actor", {
     scopeProperties: emptyScopeProperties,
     patchSchema: actorPatchSchema,
@@ -1757,6 +1769,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
   })
 };
 
@@ -1797,6 +1819,22 @@ var auditFilesSchema = {
   },
   additionalProperties: false
 };
+var REFERENCE_SCOPES = deepFreeze([...AUDIT_FILE_SCOPES, "folder", "setting", "chat"]);
+var REFERENCE_DEFAULT_SCOPES = deepFreeze(REFERENCE_SCOPES.filter((scope) => scope !== "chat"));
+var worldReferencesSchema = {
+  type: "object",
+  required: ["uuid"],
+  properties: {
+    uuid: { type: "string", minLength: 1 },
+    scope: {
+      type: "array",
+      minItems: 1,
+      items: { type: "string", enum: [...REFERENCE_SCOPES] }
+    },
+    ...paginationProperties
+  },
+  additionalProperties: false
+};
 var fileCommands = {
   "file.list": cmd({
     type: "object",
@@ -1884,7 +1922,8 @@ var fileCommands = {
   )
 };
 var worldAuditCommands = {
-  "world.audit-files": cmd(auditFilesSchema)
+  "world.audit-files": cmd(auditFilesSchema),
+  "world.references": cmd(worldReferencesSchema)
 };
 
 // ../protocol/src/schemas/folder.js
@@ -2240,6 +2279,16 @@ var journalPageCreateSchema = {
 var journalPagePatchSchema = patchFrom(journalPageCreateSchema, {
   prepend: { id: { type: "string", minLength: 1 } }
 });
+var journalPageOwnPatchSchema = patchFrom(journalPageCreateSchema);
+var journalPageIdSchema = {
+  type: "object",
+  required: ["journalId", "pageId"],
+  properties: {
+    journalId: { type: "string", minLength: 1 },
+    pageId: { type: "string", minLength: 1 }
+  },
+  additionalProperties: false
+};
 var journalDataSchema = {
   type: "object",
   required: ["name"],
@@ -2407,6 +2456,58 @@ var journalCommands = {
     patchSchema: journalDocumentPatchSchema,
     verbs: ["update-many", "delete-many"]
   }),
+  "journal.page.list": cmd({
+    type: "object",
+    required: ["journalId"],
+    properties: {
+      journalId: { type: "string", minLength: 1 },
+      ...nameFilterProperty,
+      ...paginationProperties
+    },
+    additionalProperties: false
+  }),
+  "journal.page.get": cmd(journalPageIdSchema),
+  "journal.page.create": cmd(
+    {
+      type: "object",
+      required: ["journalId", "data"],
+      properties: {
+        journalId: { type: "string", minLength: 1 },
+        data: journalPageCreateSchema,
+        ...dryRunProperty,
+        ...idempotencyKeyProperty
+      },
+      additionalProperties: false
+    },
+    { mutation: true }
+  ),
+  "journal.page.update": cmd(
+    {
+      type: "object",
+      required: ["journalId", "pageId", "patch"],
+      properties: {
+        journalId: { type: "string", minLength: 1 },
+        pageId: { type: "string", minLength: 1 },
+        patch: journalPageOwnPatchSchema,
+        ...dryRunProperty
+      },
+      additionalProperties: false
+    },
+    { mutation: true }
+  ),
+  "journal.page.delete": cmd(
+    {
+      type: "object",
+      required: ["journalId", "pageId"],
+      properties: {
+        journalId: { type: "string", minLength: 1 },
+        pageId: { type: "string", minLength: 1 },
+        ...dryRunProperty
+      },
+      additionalProperties: false
+    },
+    { mutation: true }
+  ),
   "journal.category.list": cmd({
     type: "object",
     required: ["journalId"],
@@ -3223,7 +3324,8 @@ var sceneEmbeddedCommands = {
     properties: {
       sceneId: { type: "string", minLength: 1 },
       ...nameFilterProperty,
-      ...paginationProperties
+      ...paginationProperties,
+      ...tokenListIncludeProperty
     },
     additionalProperties: false
   }),
@@ -3293,6 +3395,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 +5471,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",
@@ -5506,6 +5622,11 @@ var DEFAULT_COMMAND_PROFILE = deepFreeze({
   "journal.ownership.set": "allow",
   "journal.update-many": "allow",
   "journal.delete-many": "approve",
+  "journal.page.list": "allow",
+  "journal.page.get": "allow",
+  "journal.page.create": "allow",
+  "journal.page.update": "allow",
+  "journal.page.delete": "approve",
   "journal.category.list": "allow",
   "journal.category.get": "allow",
   "journal.category.create": "allow",
@@ -5622,6 +5743,9 @@ var DEFAULT_COMMAND_PROFILE = deepFreeze({
   "actor.item.delete": "approve",
   "actor.item.clone": "allow",
   "actor.item.import-from-compendium": "allow",
+  "actor.item.create-many": "allow",
+  "actor.item.update-many": "allow",
+  "actor.item.delete-many": "approve",
   "actor.update-many": "allow",
   "actor.delete-many": "approve",
   "actor.effect.list": "allow",
@@ -5653,6 +5777,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",
@@ -5674,6 +5799,7 @@ var DEFAULT_COMMAND_PROFILE = deepFreeze({
   "setting.set-many": "deny",
   "actor.import-from-compendium": "allow",
   "world.audit-files": "allow",
+  "world.references": "allow",
   "world.search": "allow",
   "approval.await": "allow",
   "approval.cancel": "allow",
@@ -5682,7 +5808,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",
@@ -5747,6 +5878,17 @@ function editDistance(a, b) {
   }
   return previous[cols - 1];
 }
+function childPath(path, key) {
+  return key.includes(".") ? `${path}[${JSON.stringify(key)}]` : `${path}.${key}`;
+}
+function describeDottedKey(key, properties) {
+  const root = key.split(".")[0];
+  if (!key.includes(".") || !Object.hasOwn(properties, root)) {
+    return "";
+  }
+  const nested = key.split(".").reduceRight((inner, segment) => `{${JSON.stringify(segment)}: ${inner}}`, "...");
+  return `; a key at this level must be one of the listed field names, so nest the rest of the path inside "${root}": ${nested}`;
+}
 function describeAllowedFields(key, allowedFields) {
   if (allowedFields.length === 0) {
     return "";
@@ -5796,7 +5938,7 @@ function validateObjectSchema(schema, value, path, errors) {
   const additionalProperties = schema.additionalProperties ?? true;
   for (const key of required) {
     if (!Object.hasOwn(value, key)) {
-      errors.push(`${path}.${key} is required`);
+      errors.push(`${childPath(path, key)} is required`);
     }
   }
   const ownKeys = Object.keys(value);
@@ -5808,25 +5950,27 @@ function validateObjectSchema(schema, value, path, errors) {
     for (const key of ownKeys) {
       if (namePattern === null) {
         errors.push(
-          `${path}.${key} cannot be validated: ${schema.propertyNames.pattern} is not a valid unicode-mode pattern`
+          `${childPath(path, key)} cannot be validated: ${schema.propertyNames.pattern} is not a valid unicode-mode pattern`
         );
       } else if (!namePattern.test(key)) {
-        errors.push(`${path}.${key} is not an allowed property name`);
+        errors.push(`${childPath(path, key)} is not an allowed property name`);
       }
     }
   }
   for (const [key, propertyValue] of Object.entries(value)) {
     const propertySchema = properties[key];
     if (propertySchema) {
-      validateSchema(propertySchema, propertyValue, `${path}.${key}`, errors);
+      validateSchema(propertySchema, propertyValue, childPath(path, key), errors);
       continue;
     }
     if (additionalProperties === false) {
-      errors.push(`${path}.${key} is not allowed${describeAllowedFields(key, Object.keys(properties))}`);
+      errors.push(
+        `${childPath(path, key)} is not allowed${describeAllowedFields(key, Object.keys(properties))}` + describeDottedKey(key, properties)
+      );
       continue;
     }
     if (isPlainObject(additionalProperties)) {
-      validateSchema(additionalProperties, propertyValue, `${path}.${key}`, errors);
+      validateSchema(additionalProperties, propertyValue, childPath(path, key), errors);
     }
   }
 }
@@ -8833,7 +8977,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"]);
@@ -8990,7 +9137,10 @@ function createSceneCreateParams(options) {
 function createSceneCloneParams(options) {
   return {
     sceneId: options.sceneId,
-    ...optionalPatch(buildScenePatch(options))
+    ...optionalPatch({
+      ...buildScenePatch(options),
+      ...optionalJsonObject(options.patchJson, "--patch-json") ?? {}
+    })
   };
 }
 function createItemCloneParams(options) {
@@ -8999,7 +9149,8 @@ function createItemCloneParams(options) {
     ...stringField("img", options.img),
     ...folderField(options),
     ...numberField("sort", options.sort),
-    ...jsonObjectField("system", options.systemJson, "--system-json")
+    ...jsonObjectField("system", options.systemJson, "--system-json"),
+    ...optionalJsonObject(options.patchJson, "--patch-json") ?? {}
   };
   return {
     itemId: options.itemId,
@@ -9010,7 +9161,8 @@ function createJournalCloneParams(options) {
   const patch = {
     ...stringField("name", options.name),
     ...folderField(options),
-    ...numberField("sort", options.sort)
+    ...numberField("sort", options.sort),
+    ...optionalJsonObject(options.patchJson, "--patch-json") ?? {}
   };
   return {
     journalId: options.journalId,
@@ -9096,7 +9248,8 @@ function createMacroCloneParams(options) {
     ...stringField("command", options.command),
     ...stringField("img", options.img),
     ...folderField(options),
-    ...stringField("scope", options.scope)
+    ...stringField("scope", options.scope),
+    ...optionalJsonObject(options.patchJson, "--patch-json") ?? {}
   };
   return {
     macroId: options.macroId,
@@ -9219,6 +9372,34 @@ function createJournalCategoryUpdateParams(options) {
     })
   };
 }
+function buildJournalPageFields(options) {
+  return {
+    ...stringField("name", options.name),
+    ...stringField("type", options.type),
+    ...numberField("sort", options.sort),
+    ...options.clearCategory ? { category: null } : stringField("category", options.category),
+    ...stringField("src", options.src)
+  };
+}
+function createJournalPageCreateParams(options) {
+  return {
+    journalId: options.journalId,
+    data: {
+      ...buildJournalPageFields(options),
+      ...optionalJsonObject(options.dataJson, "--data-json") ?? {}
+    }
+  };
+}
+function createJournalPageUpdateParams(options) {
+  return {
+    journalId: options.journalId,
+    pageId: options.pageId,
+    patch: assertNonEmptyPatch({
+      ...buildJournalPageFields(options),
+      ...optionalJsonObject(options.patchJson, "--patch-json") ?? {}
+    })
+  };
+}
 function buildTableFields(options) {
   return {
     ...stringField("description", options.description),
@@ -9531,7 +9712,8 @@ function createActorItemCloneParams(options) {
     ...stringField("name", options.name),
     ...stringField("img", options.img),
     ...numberField("sort", options.sort),
-    ...jsonObjectField("system", options.systemJson, "--system-json")
+    ...jsonObjectField("system", options.systemJson, "--system-json"),
+    ...optionalJsonObject(options.patchJson, "--patch-json") ?? {}
   };
   return {
     actorId: options.actorId,
@@ -9610,7 +9792,10 @@ function createActorUpdateParams(options) {
 function createActorCloneParams(options) {
   return {
     actorId: options.actorId,
-    ...optionalPatch(buildActorPatch(options))
+    ...optionalPatch({
+      ...buildActorPatch(options),
+      ...optionalJsonObject(options.patchJson, "--patch-json") ?? {}
+    })
   };
 }
 function createActorImportParams(options) {
@@ -10366,8 +10551,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 +10667,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 +10693,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 +10739,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 +11278,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));
   }
@@ -11102,55 +11290,7 @@ function renderJournalDetails(journal) {
     });
   }
   pages.forEach((page, index) => {
-    const pageNumber = index + 1;
-    lines.push(`page ${pageNumber}: ${page?.id ?? ""}	${page?.name ?? ""}	${page?.type ?? ""}`);
-    const type = page?.type;
-    if (type === "image") {
-      if (page?.src) {
-        lines.push(`page ${pageNumber} src: ${page.src}`);
-      }
-      const caption = page?.image?.caption;
-      if (typeof caption === "string" && caption.length > 0) {
-        const shown = caption.length > 60 ? `${caption.slice(0, 60)}\u2026` : caption;
-        lines.push(`page ${pageNumber} caption: ${shown}`);
-      } else {
-        lines.push(`page ${pageNumber} caption: (none)`);
-      }
-    } else if (type === "video") {
-      if (page?.src) {
-        lines.push(`page ${pageNumber} src: ${page.src}`);
-      }
-    } else if (type === "pdf") {
-      if (page?.src) {
-        lines.push(`page ${pageNumber} src: ${page.src}`);
-      }
-    } else {
-      const format = page?.text?.format;
-      if (format === 2) {
-        lines.push(`page ${pageNumber} format: markdown`);
-      } else if (format === 1) {
-        lines.push(`page ${pageNumber} format: html`);
-      }
-      if (page?.text?.content) {
-        lines.push(`page ${pageNumber} text: ${page.text.content}`);
-      }
-      if (page?.src) {
-        lines.push(`page ${pageNumber} src: ${page.src}`);
-      }
-    }
-    const title = page?.title;
-    if (title && (title.show === false || typeof title.level === "number" && title.level !== 1)) {
-      const bits = [];
-      if (title.show === false) bits.push("show=false");
-      if (typeof title.level === "number" && title.level !== 1) bits.push(`level=${title.level}`);
-      lines.push(`page ${pageNumber} title: ${bits.join(" ")}`);
-    }
-    if (page?.category) {
-      lines.push(`page ${pageNumber} category: ${page.category}`);
-    }
-    if (page && Object.hasOwn(page, "ownership")) {
-      lines.push(...renderOwnershipLines(page.ownership).map((line) => `page ${pageNumber} ${line}`));
-    }
+    lines.push(...renderJournalPageLines(page, `page ${index + 1}`));
   });
   return lines.join("\n");
 }
@@ -11163,6 +11303,143 @@ function renderJournalCategoryDetails(journalId, category) {
     `sort: ${category?.sort ?? 0}`
   ].join("\n");
 }
+function renderJournalPageLines(page, label) {
+  const lines = [];
+  lines.push(`${label}: ${page?.id ?? ""}	${page?.name ?? ""}	${page?.type ?? ""}`);
+  const type = page?.type;
+  if (type === "image") {
+    if (page?.src) {
+      lines.push(`${label} src: ${page.src}`);
+    }
+    const caption = page?.image?.caption;
+    if (typeof caption === "string" && caption.length > 0) {
+      const shown = caption.length > 60 ? `${caption.slice(0, 60)}\u2026` : caption;
+      lines.push(`${label} caption: ${shown}`);
+    } else {
+      lines.push(`${label} caption: (none)`);
+    }
+  } else if (type === "video") {
+    if (page?.src) {
+      lines.push(`${label} src: ${page.src}`);
+    }
+  } else if (type === "pdf") {
+    if (page?.src) {
+      lines.push(`${label} src: ${page.src}`);
+    }
+  } else {
+    const format = page?.text?.format;
+    if (format === 2) {
+      lines.push(`${label} format: markdown`);
+    } else if (format === 1) {
+      lines.push(`${label} format: html`);
+    }
+    if (page?.text?.content) {
+      lines.push(`${label} text: ${page.text.content}`);
+    }
+    if (page?.src) {
+      lines.push(`${label} src: ${page.src}`);
+    }
+  }
+  const title = page?.title;
+  if (title && (title.show === false || typeof title.level === "number" && title.level !== 1)) {
+    const bits = [];
+    if (title.show === false) bits.push("show=false");
+    if (typeof title.level === "number" && title.level !== 1) bits.push(`level=${title.level}`);
+    lines.push(`${label} title: ${bits.join(" ")}`);
+  }
+  if (page?.category) {
+    lines.push(`${label} category: ${page.category}`);
+  }
+  if (page && Object.hasOwn(page, "ownership")) {
+    lines.push(...renderOwnershipLines(page.ownership).map((line) => `${label} ${line}`));
+  }
+  return lines;
+}
+function renderJournalPageDetails(journalId, page) {
+  return [`journal: ${journalId}`, ...renderJournalPageLines(page, "page")].join("\n");
+}
+
+// src/render/settings.ts
+function renderSettingSummaryLine(setting) {
+  const label = setting?.nameLocalized && setting.nameLocalized !== setting.name ? `${setting.nameLocalized} [${setting.name}]` : setting?.nameLocalized ?? setting?.name ?? "(unnamed)";
+  return [
+    setting?.id ?? `${setting?.namespace ?? "?"}.${setting?.key ?? "?"}`,
+    label,
+    `scope=${setting?.scope ?? "?"}`,
+    `type=${setting?.type?.kind ?? "-"}`,
+    `config=${Boolean(setting?.config)}`,
+    `reload=${Boolean(setting?.requiresReload)}`,
+    ...setting?.metadataReadFailed ? ["metadata=UNREADABLE"] : [],
+    ...setting?.unaddressable ? ["address=UNADDRESSABLE"] : [],
+    ...setting?.valueRedacted ? ["value=REDACTED"] : []
+  ].join("	");
+}
+function renderSettingValue(value) {
+  return JSON.stringify(value ?? null, null, 2);
+}
+function renderOmissionLines(label, omissions, truncated) {
+  if (!Array.isArray(omissions) || omissions.length === 0) return [];
+  return [
+    `${label} incomplete: ${omissions.length}${truncated ? "+" : ""} node(s) replaced by {"$unserializable": <reason>}`,
+    ...omissions.map((omission) => `  ${omission?.path ?? "?"}	${omission?.reason ?? "?"}`)
+  ];
+}
+function renderSettingWriteLines(row, dryRun) {
+  const verb = dryRun ? "would write" : row?.changed ? "wrote" : "left unchanged";
+  return [
+    `${verb}: ${row?.id ?? `${row?.namespace}.${row?.key}`} (scope: ${row?.scope ?? "?"})`,
+    `previous: ${renderSettingValue(row?.previous)}`,
+    ...renderOmissionLines("previous", row?.previousOmissions, row?.previousOmissionsTruncated),
+    `${dryRun ? "requested" : "value"}: ${renderSettingValue(row?.value)}`,
+    ...renderOmissionLines("value", row?.valueOmissions, row?.valueOmissionsTruncated),
+    `changed: ${Boolean(row?.changed)} / validated: ${Boolean(row?.validated)}`,
+    ...row?.requiresReload ? ["requiresReload: true \u2014 Foundry acts on this only after `system reload` or a manual browser reload"] : ["requiresReload: false"]
+  ];
+}
+function renderSettingWriteResult(result) {
+  return renderSettingWriteLines(result, Boolean(result?.dryRun)).join("\n");
+}
+function renderSettingWriteOutcomes(result) {
+  const outcomes = result?.outcomes ?? [];
+  const dryRun = Boolean(result?.dryRun);
+  const lines = [
+    `${dryRun ? "Would write" : "Wrote"} settings (${outcomes.length}) \u2014 complete: ${Boolean(result?.complete)}`,
+    ...outcomes.flatMap(
+      (outcome) => outcome?.status === "updated" || outcome?.status === "unchanged" ? [
+        `[${outcome.index}] ${outcome.status}`,
+        ...renderSettingWriteLines(outcome, dryRun).map((line) => `  ${line}`)
+      ] : [`[${outcome?.index}] ${outcome?.status}	${outcome?.id ?? ""}`]
+    )
+  ];
+  if (result?.failure) {
+    lines.push(`failure: ${result.failure.code} \u2014 ${result.failure.message}`);
+  }
+  return lines.join("\n");
+}
+function renderSettingBatchRows(setting) {
+  return [
+    renderSettingSummaryLine(setting),
+    ...setting?.error ? [`  error: ${setting.error.code} \u2014 ${setting.error.message}`] : [
+      `  value: ${renderSettingValue(setting?.value)}`,
+      ...renderOmissionLines("value", setting?.valueOmissions, setting?.valueOmissionsTruncated).map(
+        (line) => `  ${line}`
+      )
+    ]
+  ];
+}
+function renderSettingDetails(setting) {
+  return [
+    `setting: ${setting?.id ?? `${setting?.namespace}.${setting?.key}`}`,
+    `name: ${setting?.nameLocalized ?? "(none)"}${setting?.name && setting.name !== setting.nameLocalized ? ` (raw: ${setting.name})` : ""}`,
+    `hint: ${setting?.hintLocalized ?? "(none)"}${setting?.hint && setting.hint !== setting.hintLocalized ? ` (raw: ${setting.hint})` : ""}`,
+    `scope: ${setting?.scope ?? "?"}`,
+    `type: ${setting?.type?.kind ?? "(untyped)"}`,
+    `config: ${Boolean(setting?.config)} / requiresReload: ${Boolean(setting?.requiresReload)}`,
+    ...setting?.metadataReadFailed ? [`metadata: UNREADABLE (${setting.metadataReadError ?? "unknown error"})`] : [],
+    setting?.valueRedacted ? "value: null (REDACTED \u2014 authorization settings are never exposed through setting commands)" : `value: ${JSON.stringify(setting?.value ?? null, null, 2)}`,
+    ...renderOmissionLines("value", setting?.valueOmissions, setting?.valueOmissionsTruncated)
+  ].join("\n");
+}
 
 // src/render/macros.ts
 var CHAT_CAPTURE_NOTES = {
@@ -11185,6 +11462,9 @@ function renderMacroExecuteResult(result) {
     `type: ${result?.type ?? "(unknown)"}`,
     `returned: ${JSON.stringify(result?.returned ?? null, null, 2)}`
   ];
+  lines.push(
+    ...renderOmissionLines("returned", result?.returnedOmissions, result?.returnedOmissionsTruncated)
+  );
   if (result?.returnedOmitted) {
     lines.push(`returned omitted: ${result.returnedOmitted.code} \u2014 ${result.returnedOmitted.message}`);
   }
@@ -11206,7 +11486,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 +11509,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 +11568,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 +11608,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}`,
@@ -11520,73 +11818,6 @@ function renderRegionBehaviorDetails(sceneId, regionId, behavior) {
   ].join("\n");
 }
 
-// src/render/settings.ts
-function renderSettingSummaryLine(setting) {
-  const label = setting?.nameLocalized && setting.nameLocalized !== setting.name ? `${setting.nameLocalized} [${setting.name}]` : setting?.nameLocalized ?? setting?.name ?? "(unnamed)";
-  return [
-    setting?.id ?? `${setting?.namespace ?? "?"}.${setting?.key ?? "?"}`,
-    label,
-    `scope=${setting?.scope ?? "?"}`,
-    `type=${setting?.type?.kind ?? "-"}`,
-    `config=${Boolean(setting?.config)}`,
-    `reload=${Boolean(setting?.requiresReload)}`,
-    ...setting?.metadataReadFailed ? ["metadata=UNREADABLE"] : [],
-    ...setting?.unaddressable ? ["address=UNADDRESSABLE"] : [],
-    ...setting?.valueRedacted ? ["value=REDACTED"] : []
-  ].join("	");
-}
-function renderSettingValue(value) {
-  return JSON.stringify(value ?? null, null, 2);
-}
-function renderSettingWriteLines(row, dryRun) {
-  const verb = dryRun ? "would write" : row?.changed ? "wrote" : "left unchanged";
-  return [
-    `${verb}: ${row?.id ?? `${row?.namespace}.${row?.key}`} (scope: ${row?.scope ?? "?"})`,
-    `previous: ${renderSettingValue(row?.previous)}`,
-    `${dryRun ? "requested" : "value"}: ${renderSettingValue(row?.value)}`,
-    `changed: ${Boolean(row?.changed)} / validated: ${Boolean(row?.validated)}`,
-    ...row?.requiresReload ? ["requiresReload: true \u2014 Foundry acts on this only after `system reload` or a manual browser reload"] : ["requiresReload: false"]
-  ];
-}
-function renderSettingWriteResult(result) {
-  return renderSettingWriteLines(result, Boolean(result?.dryRun)).join("\n");
-}
-function renderSettingWriteOutcomes(result) {
-  const outcomes = result?.outcomes ?? [];
-  const dryRun = Boolean(result?.dryRun);
-  const lines = [
-    `${dryRun ? "Would write" : "Wrote"} settings (${outcomes.length}) \u2014 complete: ${Boolean(result?.complete)}`,
-    ...outcomes.flatMap(
-      (outcome) => outcome?.status === "updated" || outcome?.status === "unchanged" ? [
-        `[${outcome.index}] ${outcome.status}`,
-        ...renderSettingWriteLines(outcome, dryRun).map((line) => `  ${line}`)
-      ] : [`[${outcome?.index}] ${outcome?.status}	${outcome?.id ?? ""}`]
-    )
-  ];
-  if (result?.failure) {
-    lines.push(`failure: ${result.failure.code} \u2014 ${result.failure.message}`);
-  }
-  return lines.join("\n");
-}
-function renderSettingBatchRows(setting) {
-  return [
-    renderSettingSummaryLine(setting),
-    ...setting?.error ? [`  error: ${setting.error.code} \u2014 ${setting.error.message}`] : [`  value: ${renderSettingValue(setting?.value)}`]
-  ];
-}
-function renderSettingDetails(setting) {
-  return [
-    `setting: ${setting?.id ?? `${setting?.namespace}.${setting?.key}`}`,
-    `name: ${setting?.nameLocalized ?? "(none)"}${setting?.name && setting.name !== setting.nameLocalized ? ` (raw: ${setting.name})` : ""}`,
-    `hint: ${setting?.hintLocalized ?? "(none)"}${setting?.hint && setting.hint !== setting.hintLocalized ? ` (raw: ${setting.hint})` : ""}`,
-    `scope: ${setting?.scope ?? "?"}`,
-    `type: ${setting?.type?.kind ?? "(untyped)"}`,
-    `config: ${Boolean(setting?.config)} / requiresReload: ${Boolean(setting?.requiresReload)}`,
-    ...setting?.metadataReadFailed ? [`metadata: UNREADABLE (${setting.metadataReadError ?? "unknown error"})`] : [],
-    setting?.valueRedacted ? "value: null (REDACTED \u2014 authorization settings are never exposed through setting commands)" : `value: ${JSON.stringify(setting?.value ?? null, null, 2)}`
-  ].join("\n");
-}
-
 // src/render/tables.ts
 function renderTableResultLine(result, ownerColumns = []) {
   const range = Array.isArray(result?.range) ? result.range.join("-") : "";
@@ -11617,7 +11848,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));
   }
@@ -11892,6 +12123,28 @@ var RENDERERS = registerRenderers([
     }
     return lines.join("\n");
   }),
+  customRenderer("world.references", (result, offset) => {
+    const references = result.references ?? [];
+    const target = result.target ?? {};
+    const lines = [
+      `target: ${target.uuid ?? ""}	${humanCell(target.name)}	exists=${target.exists === null ? "unknown" : String(target.exists)}`
+    ];
+    if (references.length) {
+      lines.push(
+        `References (${references.length})`,
+        ...references.map(
+          (ref) => `${ref.uuid}	${humanCell(ref.name)}	${ref.field}	${ref.match}${ref.matchedUuid ? `	${ref.matchedUuid}` : ""}`
+        )
+      );
+    } else {
+      lines.push("No stored references found.");
+    }
+    lines.push(...listFooterLines(result, references.length, offset));
+    lines.push(
+      `summary: references=${result.total ?? references.length} scannedDocuments=${result.scannedDocuments ?? 0} selfReferences=${result.selfReferences ?? 0} scopes=${(result.scopes ?? []).join(",")}`
+    );
+    return lines.join("\n");
+  }),
   listRenderer("scene.list", {
     key: "scenes",
     empty: "No scenes found.",
@@ -12256,6 +12509,21 @@ var RENDERERS = registerRenderers([
   }),
   deleteRenderer("journal.delete", "journal"),
   detailRenderer("journal.show", (result) => renderJournalShowResult(result)),
+  listRenderer("journal.page.list", {
+    key: "pages",
+    empty: "No pages found.",
+    heading: "Pages",
+    prefix: (result) => [`journal: ${result.journalId}`],
+    row: (page) => `${page.id}	${page.name ?? ""}	${page.type ?? ""}	sort=${page.sort ?? 0}${page.textFormat === 2 ? "	format=markdown" : page.textFormat === 1 ? "	format=html" : ""}`
+  }),
+  detailRenderer(
+    ["journal.page.get", "journal.page.create", "journal.page.update"],
+    (result) => renderJournalPageDetails(result.journalId, result.page)
+  ),
+  detailRenderer(
+    "journal.page.delete",
+    (result) => result.deleted ? `Deleted journal page ${result.id} from journal ${result.journalId}` : `Would delete journal page ${result.id} from journal ${result.journalId}`
+  ),
   listRenderer("journal.category.list", {
     key: "categories",
     empty: "No categories found.",
@@ -12407,6 +12675,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 +12819,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.",
@@ -13384,6 +13664,28 @@ function addJournalCategoryFieldOptions(command, verb) {
   const ordered = verb === "create" ? [JOURNAL_CATEGORY_SORT_FIELD] : [JOURNAL_CATEGORY_NAME_FIELD, JOURNAL_CATEGORY_SORT_FIELD];
   return addFieldOptions(command, verb, ordered);
 }
+var JOURNAL_PAGE_FIELDS = [
+  {
+    flag: "--sort <sort>",
+    help: { create: "Page sort value", update: "New page sort value" },
+    parser: parseNumber
+  },
+  {
+    flag: "--category <categoryId>",
+    help: {
+      create: "Category id from journal category list",
+      update: "New category id from journal category list"
+    }
+  },
+  { flag: "--clear-category", help: "Explicitly set category to null", conflicts: "category" },
+  {
+    flag: "--src <src>",
+    help: { create: "Media path of an image, pdf or video page", update: "New media path" }
+  }
+];
+function addJournalPageFieldOptions(command, verb) {
+  return addFieldOptions(command, verb, JOURNAL_PAGE_FIELDS);
+}
 var PLAYLIST_FIELDS = [
   {
     flag: "--description <description>",
@@ -14248,7 +14550,7 @@ function registerActor({ program, dependencies }) {
   addActorFieldOptions(
     addIdempotencyKeyOption(actor.command("clone")).requiredOption("--actor-id <actorId>", "Source actor id").option("--name <name>", "Name override for the clone"),
     "clone"
-  ).action(async function cloneActorCommand(options) {
+  ).option("--patch-json <json>", "Override fields for the clone as a JSON object (merged last)").action(async function cloneActorCommand(options) {
     await executeRemoteCommand({
       commandName: "actor.clone",
       params: createActorCloneParams(options),
@@ -14273,6 +14575,12 @@ function registerActor({ program, dependencies }) {
     });
   });
   const actorItem = actor.command("item").description("Foundry actor embedded item commands");
+  registerBatchWriteCommands(actorItem, {
+    prefix: "actor.item",
+    noun: "item",
+    scope: "actor",
+    dataHelp: "Item data as a JSON ARRAY of objects; each element takes what `actor item create --data-json` takes plus name and type"
+  });
   addNameFilterOption(
     addPaginationOptions(actorItem.command("list").requiredOption("--actor-id <actorId>", "Actor id")).option(
       "--include <fields>",
@@ -14338,7 +14646,7 @@ function registerActor({ program, dependencies }) {
   addEmbeddedItemFieldOptions(
     addIdempotencyKeyOption(actorItem.command("clone")).requiredOption("--actor-id <actorId>", "Actor id").requiredOption("--item-id <itemId>", "Source item id").option("--name <name>", "Name override for the clone"),
     "clone"
-  ).action(async function cloneActorItem(options) {
+  ).option("--patch-json <json>", "Override fields for the clone as a JSON object (merged last)").action(async function cloneActorItem(options) {
     await executeRemoteCommand({
       commandName: "actor.item.clone",
       params: createActorItemCloneParams(options),
@@ -14996,7 +15304,7 @@ function registerBridge({ program, dependencies }) {
   });
   bridge.command("serve").description("Start the local bridge daemon").option("--request-timeout-ms <ms>", "Response timeout for forwarded Foundry requests", parsePositiveInt).option(
     "--upload-limit-bytes <size>",
-    "Override the file.upload size limit as bytes or a size like 100MiB (max 512MiB)"
+    "Override the file.upload and file.read size limit for this run, as bytes or a size like 100MiB (max 512MiB)"
   ).action(async function serveBridge(options) {
     const bridgeConfig = getBridgeDaemonConfig(this, options, dependencies);
     const flagUploadLimitBytes = typeof options.uploadLimitBytes === "string" ? parseUploadLimitBytes(options.uploadLimitBytes) : void 0;
@@ -15684,11 +15992,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 +16033,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 +16047,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
@@ -15756,7 +16083,9 @@ function registerConfig({ program, dependencies }) {
     write(dependencies.stdout, `${renderConfigGetHumanOutput(configPath, displayConfig)}
 `);
   });
-  config.command("set-upload-limit").description("Persist the file.upload size limit (raw bytes, pre-base64) for the daemon and CLI").argument("<size>", "Upload size limit as bytes or a size like 100MiB (max 512MiB)").action(function setUploadLimit(size) {
+  config.command("set-upload-limit").description(
+    "Persist the file.upload and file.read size limit (raw bytes, pre-base64) for the daemon and CLI"
+  ).argument("<size>", "Upload size limit as bytes or a size like 100MiB (max 512MiB)").action(function setUploadLimit(size) {
     const uploadLimitBytes = parseUploadLimitBytes(size);
     writeCliConfigUpdate(dependencies.configStore, { uploadLimitBytes });
     const payload = {
@@ -16027,8 +16356,13 @@ function registerFile({ program, dependencies }) {
       dependencies
     });
   });
-  file.command("read").requiredOption("--path <path>", "Data-relative file path").addOption(
+  file.command("read").description(
+    `Read a file's content; a file over the upload limit (system info: limits.uploadBytes) or about ${Math.floor(READ_ENCODING_CEILING_BYTES / (1024 * 1024))} MiB returns PAYLOAD_TOO_LARGE`
+  ).requiredOption("--path <path>", "Data-relative file path").addOption(
     new Option7("--encoding <encoding>", "Read encoding").choices(["text", "base64"]).makeOptionMandatory()
+  ).addHelpText(
+    "after",
+    "\nThe CLI's receive limit follows the persisted limit (config set-upload-limit), not bridge serve --upload-limit-bytes; a larger response closes this command's connection.\nText escapes control bytes in JSON; read a binary file as base64."
   ).action(async function readFileCommand(options) {
     await executeRemoteCommand({
       commandName: "file.read",
@@ -16303,7 +16637,7 @@ function registerItem({ program, dependencies }) {
   addItemFieldOptions(
     addIdempotencyKeyOption(item.command("clone")).requiredOption("--item-id <itemId>", "Source item id").option("--name <name>", "Name override for the clone"),
     "clone"
-  ).action(async function cloneItem(options) {
+  ).option("--patch-json <json>", "Override fields for the clone as a JSON object (merged last)").action(async function cloneItem(options) {
     await executeRemoteCommand({
       commandName: "item.clone",
       params: createItemCloneParams(options),
@@ -16474,7 +16808,7 @@ function registerJournal({ program, dependencies }) {
   addJournalFieldOptions(
     addIdempotencyKeyOption(journal.command("clone")).requiredOption("--journal-id <journalId>", "Source journal id").option("--name <name>", "Name override for the clone"),
     "clone"
-  ).action(async function cloneJournal(options) {
+  ).option("--patch-json <json>", "Override fields for the clone as a JSON object (merged last)").action(async function cloneJournal(options) {
     await executeRemoteCommand({
       commandName: "journal.clone",
       params: createJournalCloneParams(options),
@@ -16490,6 +16824,64 @@ function registerJournal({ program, dependencies }) {
       dependencies
     });
   });
+  const journalPage = journal.command("page").description("Journal-embedded page commands (one page at a time; journal update batches several)");
+  journalPage.addHelpText(
+    "after",
+    `
+Result key (--json): .result.page (get and writes) / .result.pages[] (list), with .result.journalId.
+list returns summaries without text, system or flags, with textFormat (1 HTML, 2 Markdown, null on media pages); get returns the full page.
+Text fields belong to text pages, src to image, pdf and video pages, image.caption to image pages (schema journal.page.create).
+Text content goes through --data-json/--patch-json, e.g. --patch-json '{"text":{"content":"<p>\u2026</p>"}}'.
+Page ownership: journal ownership set --journal-id <id> --page-id <pageId>.`
+  );
+  addNameFilterOption(
+    addPaginationOptions(journalPage.command("list").requiredOption("--journal-id <journalId>", "Journal id"))
+  ).action(async function listJournalPages(options) {
+    await executeRemoteCommand({
+      commandName: "journal.page.list",
+      params: { journalId: options.journalId, ...nameFilterParams(options), ...paginationParams(options) },
+      command: this,
+      dependencies
+    });
+  });
+  journalPage.command("get").requiredOption("--journal-id <journalId>", "Journal id").requiredOption("--page-id <pageId>", "Page id").action(async function getJournalPage(options) {
+    await executeRemoteCommand({
+      commandName: "journal.page.get",
+      params: { journalId: options.journalId, pageId: options.pageId },
+      command: this,
+      dependencies
+    });
+  });
+  addJournalPageFieldOptions(
+    addIdempotencyKeyOption(journalPage.command("create")).requiredOption("--journal-id <journalId>", "Journal id").requiredOption("--name <name>", "Page name").requiredOption("--type <type>", "Page type (text, image, pdf, video, or a system page type)"),
+    "create"
+  ).option("--data-json <json>", "Full/extra page data as a JSON object (merged last)").action(async function createJournalPage(options) {
+    await executeRemoteCommand({
+      commandName: "journal.page.create",
+      params: createJournalPageCreateParams(options),
+      command: this,
+      dependencies
+    });
+  });
+  addJournalPageFieldOptions(
+    journalPage.command("update").requiredOption("--journal-id <journalId>", "Journal id").requiredOption("--page-id <pageId>", "Page id").option("--name <name>", "New page name").option("--type <type>", "New page type"),
+    "update"
+  ).option("--patch-json <json>", "Full/extra page patch as a JSON object (merged last)").action(async function updateJournalPage(options) {
+    await executeRemoteCommand({
+      commandName: "journal.page.update",
+      params: createJournalPageUpdateParams(options),
+      command: this,
+      dependencies
+    });
+  });
+  journalPage.command("delete").requiredOption("--journal-id <journalId>", "Journal id").requiredOption("--page-id <pageId>", "Page id").action(async function deleteJournalPage(options) {
+    await executeRemoteCommand({
+      commandName: "journal.page.delete",
+      params: { journalId: options.journalId, pageId: options.pageId },
+      command: this,
+      dependencies
+    });
+  });
   const journalCategory = journal.command("category").description("Journal-embedded category commands (labels pages are grouped under)");
   journalCategory.addHelpText(
     "after",
@@ -16647,7 +17039,7 @@ function registerMacro({ program, dependencies }) {
   addMacroFieldOptions(
     addIdempotencyKeyOption(macro.command("clone")).requiredOption("--macro-id <macroId>", "Source macro id").option("--name <name>", "Name override for the clone"),
     "clone"
-  ).action(async function cloneMacroCommand(options) {
+  ).option("--patch-json <json>", "Override fields for the clone as a JSON object (merged last)").action(async function cloneMacroCommand(options) {
     const command = await resolveMacroCommandBody(options, dependencies);
     await executeRemoteCommand({
       commandName: "macro.clone",
@@ -16669,6 +17061,10 @@ function registerMacro({ program, dependencies }) {
       "--macro-timeout-ms <ms>",
       `How long the GM client waits for the macro, in ms (default ${MACRO_EXECUTE_TIMEOUT_DEFAULT_MS}, max ${MACRO_EXECUTE_TIMEOUT_MAX_MS}). Raise the global --timeout-ms above it, or the CLI stops waiting before MACRO_TIMEOUT can be reported.`
     ).argParser(parsePositiveInt)
+  ).addHelpText(
+    "after",
+    `
+A return value node with no JSON form (a function, an own accessor, a circular reference) comes back as {"$unserializable": "<reason>"} and is listed in .result.returnedOmissions (at most ${SERIALIZE_OMISSIONS_MAX} entries); a return value over the size limits is dropped and explained in .result.returnedOmitted.`
   ).action(async function executeMacroCommand(options) {
     await executeRemoteCommand({
       commandName: "macro.execute",
@@ -16954,7 +17350,7 @@ function registerScene({ program, dependencies }) {
   addSceneFieldOptions(
     addIdempotencyKeyOption(scene.command("clone")).requiredOption("--scene-id <sceneId>", "Source scene id").option("--name <name>", "Name override for the clone"),
     "clone"
-  ).action(async function cloneScene(options) {
+  ).option("--patch-json <json>", "Override fields for the clone as a JSON object (merged last)").action(async function cloneScene(options) {
     await executeRemoteCommand({
       commandName: "scene.clone",
       params: createSceneCloneParams(options),
@@ -17028,17 +17424,29 @@ 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
+  ).addHelpText(
+    "after",
+    "\nThe tokens of one actor across all scenes: world references --uuid Actor.<actorId> --scope scene"
   ).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({
@@ -17066,7 +17474,11 @@ function registerScene({ program, dependencies }) {
   addTokenFieldOptions(
     sceneToken.command("update").requiredOption("--scene-id <sceneId>", "Scene id").requiredOption("--token-id <tokenId>", "Token id"),
     "update"
-  ).option("--patch-json <json>", "Full/extra token patch as a JSON object (merged last)").action(async function updateSceneToken(options) {
+  ).option("--patch-json <json>", "Full/extra token patch as a JSON object (merged last)").addHelpText(
+    "after",
+    `
+A patch with "delta": {"items": []} keeps the token's item overrides. scene token restore-delta drops every token override; scene token item update/delete changes single items.`
+  ).action(async function updateSceneToken(options) {
     await executeRemoteCommand({
       commandName: "scene.token.update",
       params: createSceneTokenUpdateParams(options),
@@ -17093,6 +17505,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",
@@ -17162,12 +17584,13 @@ function registerScene({ program, dependencies }) {
   addEmbeddedItemFieldOptions(
     addIdempotencyKeyOption(sceneTokenItem.command("clone")).requiredOption("--scene-id <sceneId>", "Scene id").requiredOption("--token-id <tokenId>", "Token id").requiredOption("--item-id <itemId>", "Source item id").option("--name <name>", "Name override for the clone"),
     "clone"
-  ).action(async function cloneSceneTokenItem(options) {
+  ).option("--patch-json <json>", "Override fields for the clone as a JSON object (merged last)").action(async function cloneSceneTokenItem(options) {
     const patch = {
       ...stringField("name", options.name),
       ...stringField("img", options.img),
       ...numberField("sort", options.sort),
-      ...jsonObjectField("system", options.systemJson, "--system-json")
+      ...jsonObjectField("system", options.systemJson, "--system-json"),
+      ...optionalJsonObject(options.patchJson, "--patch-json") ?? {}
     };
     await executeRemoteCommand({
       commandName: "scene.token.item.clone",
@@ -18036,7 +18459,11 @@ function registerSetting({ program, dependencies }) {
       });
     }
   );
-  setting.command("get").requiredOption("--namespace <namespace>", 'Setting namespace (e.g. "core" or a module id)').requiredOption("--key <key>", "Setting key within the namespace").action(async function getSetting(options) {
+  setting.command("get").requiredOption("--namespace <namespace>", 'Setting namespace (e.g. "core" or a module id)').requiredOption("--key <key>", "Setting key within the namespace").addHelpText(
+    "after",
+    `
+A value node with no JSON form (an accessor property, a function, a circular reference) comes back as {"$unserializable": "<reason>"} and is listed in .result.setting.valueOmissions (at most ${SERIALIZE_OMISSIONS_MAX} entries; valueOmissionsTruncated marks a longer list). Such a value is incomplete: writing it back with setting set stores the markers as data.`
+  ).action(async function getSetting(options) {
     await executeRemoteCommand({
       commandName: "setting.get",
       params: { namespace: options.namespace, key: options.key },
@@ -18050,7 +18477,7 @@ function registerSetting({ program, dependencies }) {
     "--ids <list>",
     'Comma-separated setting ids in "namespace.key" form (e.g. core.chatBubbles,my-module.apiKey)',
     parseIdList
-  ).action(async function getManySettings(options) {
+  ).addHelpText("after", "\nEach row reports omissions like setting get, in valueOmissions.").action(async function getManySettings(options) {
     await executeRemoteCommand({
       commandName: "setting.get-many",
       params: { ids: options.ids },
@@ -18062,6 +18489,9 @@ function registerSetting({ program, dependencies }) {
     "--value-json <json>",
     'New value as a JSON literal \u2014 true, 42, "text", [..] or {..}; a quoted string stays distinct from a boolean or a number',
     (value) => parseJsonValue(value, "--value-json")
+  ).addHelpText(
+    "after",
+    '\nprevious and value report omissions like setting get, in previousOmissions and valueOmissions. {"$unserializable": ...} markers in --value-json are stored as data.'
   ).action(async function setSetting(options) {
     await executeRemoteCommand({
       commandName: "setting.set",
@@ -18622,6 +19052,7 @@ function registerWorld({ program, dependencies }) {
       "",
       "Result key (--json): .result.broken[] (+ .result.checkedRefs / .result.checkedFiles / .result.skipped[], total/hasMore over broken) for audit-files.",
       "Result key (--json): .result.results[] (+ .result.total / .result.hasMore / .result.index) for search.",
+      "Result key (--json): .result.references[] (+ .result.target / .result.total / .result.hasMore / .result.scannedDocuments / .result.selfReferences / .result.scopes) for references.",
       "",
       "search: results are SECTIONED \u2014 world rows first, then pack rows, each ranked among itself.",
       "`score` is comparable only WITHIN a section (the two corpora are separate indexes), so compare",
@@ -18653,6 +19084,53 @@ function registerWorld({ program, dependencies }) {
       dependencies
     });
   });
+  addPaginationOptions(
+    world.command("references").description("Report where stored world data references a document, by its UUID").requiredOption(
+      "--uuid <uuid>",
+      "Target document UUID: Actor.<id>, Scene.<id>.Token.<id>, Compendium.<package>.<pack>.<Type>.<id>, \u2026"
+    ).option(
+      "--scope <list>",
+      `Comma-separated document families to scan: ${REFERENCE_SCOPES.join(",")} (default: ${REFERENCE_DEFAULT_SCOPES.join(",")}; chat only on request)`,
+      parseScopeList
+    ).addHelpText(
+      "after",
+      [
+        "",
+        "Scans the stored data, flags and _stats included, of every world document in scope, its embedded",
+        "documents, and every user. Each row names the owning document by UUID and the dotted field path in it;",
+        "a match inside a token's delta is reported on the token (field delta.\u2026). An embedded target needs its",
+        "full UUID (Scene.<s>.Token.<t>).",
+        "match: uuid      a field holds the target UUID",
+        "       link      an @UUID[...] link or a legacy @Actor[<id>] / @Compendium[<pack>.<id>] link names the target",
+        "       embedded  a field holds the UUID of a document embedded in the target (matchedUuid); deleting the",
+        "                 target breaks it too",
+        "       key       an object key names the target; a dotted key Foundry stored nested is reported at the",
+        "                 target's id (flags.mod.Actor.<id>)",
+        "       relative  a relative link (@UUID[.<id>], @Embed[.<id>]) in journal page text or a roll table or",
+        "                 table result description resolves to the target or a document in it (matchedUuid)",
+        "       id        a foreign-key field of the target's type (token actorId, note entryId, folder, setting user,",
+        "                 chat speaker, \u2026) or a hotbar slot (hotbar.<slot>) holds the target's id; for an embedded",
+        "                 target only where the record also names its parent or sits inside it, and never for a",
+        "                 deeper target such as a token's actor",
+        "setting: world and user settings, read as stored JSON (rows Setting.<id>, name = key, field value[.<path>]).",
+        "Not found: compendium contents, client settings, bare ids outside foreign-key fields (system data, object",
+        "keys, chat whisper lists) or in fields Foundry maintains itself (_stats.lastModifiedBy), name-based links",
+        "(@Actor[Goblin]), relative links in other fields. References inside the target itself are counted in",
+        "selfReferences. target.exists is null for a compendium target, whose pack is not loaded."
+      ].join("\n")
+    )
+  ).action(async function findReferences(options) {
+    await executeRemoteCommand({
+      commandName: "world.references",
+      params: {
+        uuid: options.uuid,
+        ...options.scope ? { scope: options.scope } : {},
+        ...paginationParams(options)
+      },
+      command: this,
+      dependencies
+    });
+  });
   addPaginationOptions(
     world.command("search").description("Search world (and optionally compendium) documents through the bridge index").requiredOption("--query <query>", "Search query (2-256 characters; terms are AND-combined)").addOption(
       new Option15(