fvtt-world-cli 1.1.2 → 1.2.1

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
 
@@ -29,6 +30,7 @@ Use these families to narrow your search, then check their help for supported op
 | 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 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` |
@@ -63,6 +65,29 @@ fvtt-world-cli scene token list --scene-id <sceneId> --json
 fvtt-world-cli scene token get --scene-id <sceneId> --token-id <tokenId> --json
 ```
 
+### Build a scene with levels
+
+On Foundry v14 a scene's maps live on its levels. Pass the levels when you create the scene:
+
+```bash
+fvtt-world-cli scene create --name "Tower" --json \
+  --data-json '{"levels":[{"name":"Ground","background":{"src":"worlds/<worldId>/maps/ground.webp"}},
+                          {"name":"Roof","elevation":{"bottom":20,"top":40}}]}'
+fvtt-world-cli scene level list --scene-id <sceneId> --json
+fvtt-world-cli scene level update --scene-id <sceneId> --level-id <levelId> \
+  --patch-json '{"foreground":{"src":"worlds/<worldId>/maps/roof.webp"}}' --json
+```
+
+The first supplied level becomes the initial one. To start players on another level, run `scene
+update --scene-id <sceneId> --initial-level <levelId>`; `--patch-json '{"initialLevel":null}'` goes
+back to the first level. A scene keeps at least one level, so `scene level delete` and `delete-many`
+refuse to remove the last one.
+
+Deleting a level also deletes its tokens and every placeable that exists only on that level. A dry
+run does not list them, so read the scene's placeables before deleting a level.
+
+[Compatibility](compatibility.md) lists the scene map fields each Foundry version accepts.
+
 ### Send a batch of commands
 
 Save these lines as `requests.ndjson`:
@@ -131,19 +156,24 @@ List rows contain fewer fields than `get` results. Read the target with `get` be
 update. Reads return authored state; some commands accept `include` options for derived or expensive
 data. Check the command's help for available projections and filters.
 
+Actor results carry `itemCount` in place of the owned items; `actor get` and `actor get-many`
+return the items with `--include items`. `system info --include modules` lists installed modules.
+
 ### Updates and merge semantics
 
 Use JSON flags such as `--data-json` and `--patch-json` for structured values. Updates are patches:
 
 - 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
@@ -163,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
+`&amp;`, 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)
@@ -207,7 +243,7 @@ inspect `auth pending`, then use `auth approve <code> --yes` for the selected re
 
 | Command | Effect |
 |---|---|
-| `auth status` | Show bridge state and public profile metadata |
+| `auth status` | Show bridge state, the commands the connected bridge advertised, and public profile metadata |
 | `auth pending` | List pending codes, expiry, and browser/world/GM identity |
 | `auth approve [code] [--yes]` | Approve a selected request; omit the code only when exactly one is pending |
 | `auth deny <code>` | Reject a pending request |

package/docs/compatibility.md

@@ -6,9 +6,12 @@ The bridge supports Foundry VTT v13 and v14. Check your connected version with
 | Area | v13 | v14 | What to do |
 |---|---|---|---|
 | Measured templates | Available | Removed from core | Use `scene.template` commands on v13. They are unavailable on v14. |
+| Scene maps | One map per scene: `background`, `backgroundColor`, `foreground`, `foregroundElevation` and `fog.overlay` on the scene | Each level has its own map; the scene has `levels` and `initialLevel` | On v14, set maps through `levels` in `scene.create` or with `scene.level` commands. The scene-level map fields, including `fog.overlay`, are refused on v14, and `scene.level`, `levels` and `initialLevel` are refused on v13. |
+| Placeable levels | Placeables have no level fields | A token sits on one `level`; tiles, walls, lights, sounds, notes, drawings and regions have a `levels` list, where an empty list means every level | On v14, read `level` or `levels` from placeable results to see what a level holds before deleting it. Placeable writes that set `level` or `levels` are refused on v13. |
 | Scene thumbnail rendering | Renders the scene | Renders the scene's initial level by default | On v14, expect the initial level in the thumbnail. Check the returned dimensions and image. |
 | Scene thumbnail files | Uses a stable scene-based filename | Uses a filename based on the image content | Use the returned path. On v14, a changed image can leave an older thumbnail file behind. |
 | User permission names | `TEMPLATE_CREATE` | `REGION_CREATE` | Use the permission keys reported by the connected Foundry version when calling `user.permissions.set`. |
+| Legacy update operators `-=key` (deletion) and `==key` (forced replacement) | Work without a warning | Work, and the GM browser console logs a deprecation warning for each such key, stating that support will be removed in Version 16 | Nothing changes for v13 or v14 writes. The bridge passes the operator keys through without translating them to Foundry 14's operator objects, so they will stop working once Foundry removes them. |
 
 Scene placeable fields and available region behavior types also differ. Read the target document
 before preparing a patch; valid data from one version is not automatically valid on the other.

package/docs/protocol.md

@@ -178,7 +178,11 @@ The protocol package exports `REQUEST_SCHEMA` and `COMMAND_RESPONSE_SCHEMA` for
 Document results use type-named keys and expose `id` as the public identifier. A source `_id`
 mirror may accompany it. List responses use smaller projections than single-document reads;
 filters apply before pagination. Previewed documents have no persistent identity, so an id
-observed during a preview must not be reused.
+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.
@@ -195,10 +199,12 @@ world state when the return value does not establish the effect.
 
 ### Setting results
 
-Setting writes return the observed `value` and its `previous` value. Registered types or callbacks
-may normalize the input. Confirmation establishes that the previous value changed, not that the
-requested value was stored exactly. Writing an already-stored value succeeds as unchanged without
-calling Foundry. `requiresReload: true` indicates that the GM client needs a reload.
+Setting writes return the observed `value` and its `previous` value, as `game.settings.get`
+returns them after the registered type's cast. Confirmation compares the JSON Foundry stores with
+the JSON of the validated request; a different stored value, for example one rewritten by an
+`onChange` callback, is a mismatch error with a `paths` entry for `value`. Writing an
+already-stored value succeeds as unchanged without calling Foundry. `requiresReload: true`
+indicates that the GM client needs a reload.
 
 ## Write confirmation
 
@@ -206,11 +212,24 @@ Document writes report success only after confirmation. Foundry can resolve a ve
 write without throwing, and hooks can remove or rewrite part of a patch. Single and bulk updates
 pass Foundry a private copy, then compare stored state with the original request.
 
+Confirmation compares each requested leaf path that survives Foundry's cleaning with the stored
+source. Foundry drops a key the document's schema does not declare without an error before that
+comparison, so a write made only of undeclared keys reports success with nothing stored. A deletion (`-=key` or
+Foundry 14's `ForcedDeletion`) is confirmed when the key is absent. A forced replacement (`==key`
+or Foundry 14's `ForcedReplacement`) is confirmed when the whole stored value at that path equals the requested
+value after Foundry's cleaning.
+
 A valid patch whose requested state is already stored remains a successful no-op. A validation
 failure recovered after an unwritten update returns `INVALID_PARAMS`. Unconfirmed, partial, or
 indeterminate updates can return `INTERNAL_ERROR` with these details:
 
-- `fields`: requested fields whose state was not confirmed.
+- `fields`: requested top-level fields whose state was not confirmed.
+- `paths`: up to 20 entries `{ path, requested, stored }`, one per leaf path where the stored value
+  differs from the request. `absent: "stored"` replaces `stored` when the key is missing from the
+  stored source, and `absent: "requested"` replaces `requested` for a deletion that did not land.
+  A long string, or an object or array whose JSON is long, is shortened to a window around the
+  first differing character; `truncated` then carries `format` (`text` or `json`), `offset`, and
+  the full `requestedLength` and `storedLength`. `pathsTruncated` counts the entries beyond 20.
 - `partial: true`: stored data changed in a requested field, but the full requested state was
   not reached. A hook may have applied only part of a nested object or replaced a value.
 - `changedFields`: requested top-level fields observed to change, including fields that changed
@@ -220,6 +239,12 @@ indeterminate updates can return `INTERNAL_ERROR` with these details:
 - `indeterminate: true`: confirmation could not establish the outcome. Some or all of the write
   may have persisted. `changedFields` is `null` when the before/after comparison was unavailable.
 
+When stored differs from requested, the message says that the bridge cannot verify whether Foundry
+core, the game system or a module normalized the value, or whether a hook rewrote, dropped or vetoed
+the change. A blocking module is listed as one possible cause, never as the diagnosis. Resending the
+same patch does not change the result. Every confirmed write that can report a mismatch carries the
+same `paths`, and so does a `dropped` bulk outcome when the stored state was compared.
+
 Parent patches that create embedded entries without `_id`, such as new `behaviors` in
 `scene.region.update`, return an indeterminate error after writing because parent update results
 cannot confirm those creations. A retry may duplicate them. Read the embedded collection first,
@@ -230,10 +255,10 @@ new operation with a fresh idempotency key if using one.
 
 ### Patch shape checks
 
-Single updates, bulk updates, and dry runs reject ambiguous field spellings, invalid or discarded
-array values, and dotted writes inside arrays with `INVALID_PARAMS` before mutation. Recognized
-legacy fields are checked against their migrated destinations as well. Send whole arrays; ordinary
-dotted object-property writes remain supported where the schema permits them.
+Single updates, bulk updates, and dry runs reject invalid or discarded array values, top-level
+dotted writes into array fields, and writes to legacy fields the running core moved, with
+`INVALID_PARAMS` before mutation. Send whole arrays; ordinary dotted object-property writes remain
+supported where the schema permits them. Other key spellings reach Foundry as written.
 
 Errors identify the `field` and may include `arrayField`, `requested`, `stored`, or migration
 destination details. Bulk failures add the entry's `index` and `id`; single failures use document
@@ -341,8 +366,8 @@ The wait has two phases because the decision can outlast a normal request timeou
   policy can change before dispatch.
 
 The module supplies each opaque `approvalId`; callers do not construct one. Approval request schemas
-are closed. `approval.await`, `approval.cancel`, and `policy.snapshot` do not appear in `commands`,
-`system.info` command inventory, or bridge status. `schema <command>` still returns their schemas.
+are closed. `approval.await`, `approval.cancel`, and `policy.snapshot` do not appear in `commands` or
+bridge status. `schema <command>` still returns their schemas.
 The bridge handshake advertises them because the daemon must forward them.
 
 ## Delivery states and retries

package/package.json

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

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

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

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

@@ -1 +1 @@
-d1757739e55e01589814ed919912bbe5423afa99aee16a1422fbaee5bed11c8a
+5b4188ba39ed8f9f1c041cec9c5f0c3fb5d05db7910670d0ff2bb9c5d7d43dde