fvtt-world-cli 1.2.1 → 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.1";
+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",
@@ -815,6 +819,11 @@ var actorCommands = {
     },
     { mutation: true }
   ),
+  ...batchWriteCommands("actor.item", {
+    scopeProperties: actorScopeProperties,
+    createSchema: embeddedItemDataSchema,
+    patchSchema: itemPatchSchema
+  }),
   ...batchWriteCommands("actor", {
     scopeProperties: emptyScopeProperties,
     patchSchema: actorPatchSchema,
@@ -1810,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",
@@ -1897,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
@@ -2253,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"],
@@ -2420,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"],
@@ -5534,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",
@@ -5650,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",
@@ -5703,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",
@@ -5781,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 "";
@@ -5830,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);
@@ -5842,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);
     }
   }
 }
@@ -9027,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) {
@@ -9036,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,
@@ -9047,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,
@@ -9133,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,
@@ -9256,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),
@@ -9568,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,
@@ -9647,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) {
@@ -11142,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");
 }
@@ -11203,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 = {
@@ -11225,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}`);
   }
@@ -11578,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("-") : "";
@@ -11950,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.",
@@ -12314,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.",
@@ -13454,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>",
@@ -14318,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),
@@ -14343,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>",
@@ -14408,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),
@@ -15066,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;
@@ -15845,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 = {
@@ -16116,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",
@@ -16392,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),
@@ -16563,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),
@@ -16579,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",
@@ -16736,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",
@@ -16758,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",
@@ -17043,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),
@@ -17121,6 +17428,9 @@ function registerScene({ program, dependencies }) {
     "--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",
@@ -17164,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),
@@ -17270,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",
@@ -18144,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 },
@@ -18158,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 },
@@ -18170,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",
@@ -18730,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",
@@ -18761,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(

package/docs/commands.md

@@ -28,13 +28,13 @@ Use these families to narrow your search, then check their help for supported op
 | Task | Command families |
 |---|---|
 | Edit world content | `actor`, `item`, `journal`, `scene`, `macro`, `playlist`, `table`, `cards` |
-| Edit embedded content | Nested families such as `actor.item`, `playlist.sound`, `table.result`, and `*.effect` |
+| Edit embedded content | Nested families such as `actor.item`, `journal.page`, `playlist.sound`, `table.result`, and `*.effect` |
 | Edit scene placeables | `scene.token`, `scene.wall`, `scene.region`, and related families |
 | Edit scene levels (v14) | `scene.level` |
 | Manage encounters | `combat`, `combat.combatant`, `combat.group` |
 | Organize content and access | `folder`, `*.ownership.set`, `user` |
 | Manage chat and settings | `chat`, `setting` |
-| Find content or missing assets | `world.search`, `world.audit-files` |
+| Find content, references, or missing assets | `world.search`, `world.references`, `world.audit-files` |
 | Read packs or import world documents | `compendium`, supported `*.import-from-compendium` commands |
 | Manage assets | `file` |
 | Control playback and gameplay | Actions within `playlist`, `table`, `cards`, `combat`, `scene`, and `game` |
@@ -277,7 +277,7 @@ For scripts and JSON output, pass `--yes` to skip the listing and prompt.
 ## Local configuration
 
 `config get` shows the config path and non-secret settings. `config set-upload-limit <size>`
-changes the raw upload-byte limit; restart the daemon for it to take effect.
+changes the raw byte limit for uploads and file reads; it takes effect after a daemon restart.
 
 If set, `XDG_CONFIG_HOME` places configuration under `$XDG_CONFIG_HOME/fvtt-world-cli`. Otherwise:
 

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`. |
+| Relative content links | `@UUID[..<id>]` points at nothing | `@UUID[..<id>]` names a document one parent up | `world.references` reports a `..` link only on v14. |
 | 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

package/docs/protocol.md

@@ -27,12 +27,13 @@ a correlated control-request error.
 
 ## Size limits
 
-The upload limit and the transport frame limit are distinct: the first bounds raw upload content,
-the second accounts for encoding and envelope overhead and is never lower than what legitimate
-large read responses require. The daemon advertises its effective limits during the handshake, and
-the bridge checks response size before sending, so an oversized response returns
-`PAYLOAD_TOO_LARGE` instead of destroying the shared session. A persisted upload-limit change is
-applied to the transport only after the daemon restarts.
+The upload limit and the transport frame limit are distinct: the first bounds raw upload content
+and the raw size of a `file.read`, the second accounts for encoding and envelope overhead and is
+never lower than what legitimate large read responses require. The daemon advertises its effective
+limits during the handshake, and the bridge checks response size before sending, so an oversized
+response, or one the browser cannot serialize, returns `PAYLOAD_TOO_LARGE` instead of destroying the
+shared session. A persisted upload-limit change is applied to the transport only after the daemon
+restarts.
 
 ## Pairing
 
@@ -187,6 +188,11 @@ World document reads carry `compendiumSource` and `duplicateSource`, hoisted fro
 Broadcast actions report `dispatched` and target users rather than a confirmed player-side result.
 The active/inactive split is included where knowable.
 
+A setting value or macro return value node with no JSON form, such as a function, an own accessor
+property or a circular reference, is replaced by `{"$unserializable": "<reason>"}` and listed with
+its path in an `...Omissions` field. A value with omissions is incomplete; writing it back stores the
+markers as data.
+
 ### Macro results
 
 `macro.execute` returns the macro's value and observed chat messages. `chatCapture` describes the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fvtt-world-cli",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "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.1"
+    "@fvtt-world-cli/protocol": "1.3.0"
   }
 }

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

@@ -19,10 +19,11 @@ fvtt-world-cli system info --json
 ```
 
 Proceed only when `.result.bridge.status` is `connected`, and verify the reported world and GM are
-the intended targets. If the daemon is not running, start `fvtt-world-cli bridge serve` as a
-persistent background process (it does not daemonize itself) and leave it running for the whole
-session. If no bridge connects, a GM must have the target world open in a browser with the
-`fvtt-world-cli` module enabled and paired.
+the intended targets. If `system info` answers at all, a daemon is running; use it. Start
+`fvtt-world-cli bridge serve` only when the daemon is unreachable, as a persistent background
+process (it does not daemonize itself), and leave it running for the whole session. If no bridge
+connects, a GM must have the target world open in a browser with the `fvtt-world-cli` module
+enabled and paired.
 
 Pairing is a first-run trust decision that needs the human: ask the GM to open Module Settings →
 Authorization, name the browser in the `Browser label` field, and choose Pair; run
@@ -81,8 +82,11 @@ Deleting a level also deletes its tokens and every placeable only on that level,
 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.
+editing an actor that has placed tokens, read its tokens' overrides
+(`scene token get --include delta,prepared`) and tell the user which tokens the edit will not
+change.
+Before deleting or relinking a document, run `world references --uuid <uuid>` and tell the user
+which stored references will point at nothing.
 `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

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

@@ -1 +1 @@
-5b4188ba39ed8f9f1c041cec9c5f0c3fb5d05db7910670d0ff2bb9c5d7d43dde
+07f46d03812a74d1643f7483eb3eb926244dd1837b7afb11280c3072bfa3d5bd