fvtt-world-cli 1.2.0 → 1.3.0

package/docs/commands.md

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

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

package/package.json

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

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

@@ -1 +1 @@
-248c52464e776236de6f937530e220dcb77b45a8b5cc754adbb4cfb4671a8c66
+07f46d03812a74d1643f7483eb3eb926244dd1837b7afb11280c3072bfa3d5bd