fvtt-world-cli 1.0.0 → 1.1.0

package/docs/protocol.md

@@ -15,15 +15,18 @@ size limits are defined by the protocol package and discoverable at runtime:
 
 ## Versioning
 
-The protocol is versioned. Every transport message carries the protocol version, and an unsupported
-version is rejected at the bridge handshake and during command handling rather than degraded
-silently. The current version is `3.0`; matching is exact, so a daemon and a Foundry module from
-different releases refuse each other at the handshake instead of negotiating a subset.
+The protocol version equals the product release version. Every transport message carries it, and all
+components in one installation must match exactly. The daemon and Foundry module reject a mismatch
+instead of negotiating a subset of the contract.
+
+Recover by updating the older component. Restart the daemon after updating the CLI package, or reload
+the GM client after updating the Foundry module. A refused module load does not reconnect on its own.
+Mismatch errors identify the older component when the two versions can be ordered.
 
 ## Transport model
 
 The daemon listens on a loopback WebSocket endpoint. Credentials never appear in URLs. A local
-client — the CLI or a future Companion — has no browser Origin and must establish its role with its
+client, the CLI or a future Companion, has no browser Origin and must establish its role with its
 first message: the daemon enforces a short deadline for a valid first frame, closes malformed
 openings immediately, and never assigns a role before authentication has succeeded. Browser sockets
 are identified by their exact HTTP(S) Origin and participate only in pairing and bridge sessions;
@@ -36,7 +39,7 @@ a malformed control request receives a correlated error and may keep using its c
 The daemon accepts one active authenticated bridge at a time:
 
 - another pairing cannot displace the active bridge and is rejected as `BRIDGE_BUSY`;
-- a new socket from the same pairing takes the slot over — the tab-reload recovery path;
+- a new socket from the same pairing takes the slot over, the tab-reload recovery path;
 - a clean goodbye releases the slot immediately, while an abnormal close reserves it briefly for
   the same pairing;
 - a daemon-initiated release is terminal for the released client: it does not reconnect on its
@@ -56,13 +59,13 @@ applied to the transport only after the daemon restarts.
 Pairing is the one-time exchange that lets a GM browser become a bridge. Its guarantees:
 
 - a pending request is bound to the socket that made it and disappears when that socket closes;
-- approval codes expire after a bounded interval;
+- pairing codes expire after a bounded interval;
 - the daemon persists only a digest of the bridge credential; the clear credential is delivered
   exactly once, to the requesting socket, only after the digest has been persisted;
 - approving the same Origin/world/user/client again re-pairs that client's existing profile by
   rotating its credential instead of accumulating duplicates;
-- expiry, denial, socket close, and approval all end the attempt through one idempotent path, so
-  the browser-side authorization UI is never left waiting after daemon shutdown or expiry.
+- expiry, denial, socket close, and a granted pairing all end the attempt through one idempotent
+  path, so the browser-side authorization UI is never left waiting after daemon shutdown or expiry.
 
 ### Client identity
 
@@ -82,7 +85,7 @@ independent records and neither re-pair disturbs the other.
 
 The bridge hello carries `clientId` at the top level, beside `pairingId` and `credential`, because it
 is authentication material rather than session content: the daemon rejects a hello whose client id
-does not match the stored pairing. The label is not resent on hello — the daemon's pairing record owns
+does not match the stored pairing. The label is not resent on hello; the daemon's pairing record owns
 it, and the browser keeps a copy only to display it.
 
 ## Daemon control
@@ -110,8 +113,8 @@ never stamps it. The pairing that owns the active bridge, and the holder of a li
 abnormal-disconnect lease, are excluded from removal regardless of their timestamps, so pruning can
 never unpair the browser that is connected or the one the daemon is still holding a slot for. The
 config is rewritten only when at least one record is removed. The result is `{ olderThanDays, pruned }`,
-where `olderThanDays` is the cutoff the daemon applied — including the default when the caller omitted
-it — and `pruned` carries the removed records in the same public, digest-free shape `auth.list`
+where `olderThanDays` is the cutoff the daemon applied, including the default when the caller omitted
+it, and `pruned` carries the removed records in the same public, digest-free shape `auth.list`
 serializes. The daemon computes the set at execution time; a caller that previewed candidates from
 `auth.list` holds an advisory list, not the outcome, and the executed set may be wider than that
 preview when a record crosses the cutoff between the two calls.
@@ -153,6 +156,12 @@ exclusive: success carries a result, failure carries a structured error.
 
 Document results live under a type-named key inside the result. Collection, action, and bulk
 results use their documented keys, which vary between commands but are stable for each one.
+Broadcast commands that change no document, pulling users to a scene and showing a journal entry
+or image, report `dispatched` rather than a confirmed post-state, because a socket broadcast offers
+nothing to read back; the result names the users it targeted and the active/inactive split where
+that is knowable. `macro.execute` reports the macro's returned value and observed chat messages,
+and a timeout there is indeterminate: the macro keeps running in the GM client, so `MACRO_TIMEOUT`
+callers verify effects by reads instead of retrying blindly.
 Serialized projections expose `id` as the public identifier; a source `_id` mirror may accompany
 it. A previewed new document has no persistent identity, and an id observed during a preview must
 not be reused. List-like responses that paginate return their collection with a total and a
@@ -164,7 +173,7 @@ Mutation commands accept a dry-run request that passes through validation, resol
 sanitization, permission checks, capability checks, and preparation, then returns before
 persistence using the normal result shape with an explicit dry-run marker. Only values knowable
 before execution are reported: random selection, rendering, hooks, and other execution-dependent
-observations may be absent or explicitly unconfirmed. A successful preview reserves nothing — the
+observations may be absent or explicitly unconfirmed. A successful preview reserves nothing; the
 world can change between preview and commit.
 
 ## Idempotency
@@ -172,9 +181,9 @@ world can change between preview and commit.
 Commands with duplicate-creation or non-repeatable-action risk accept or require an idempotency
 key identifying one logical request. Reusing a key with a different command or payload is rejected
 as `IDEMPOTENCY_KEY_CONFLICT`. Idempotency memory is runtime state: bounded, and cleared by daemon
-restart, bridge replacement, world switch, expiry, or eviction. It reduces duplicate effects across
-response loss; it is not a durable transaction, so an indeterminate delivery still ends with a
-world-state read.
+restart, bridge replacement, world switch, or expiry. The daemon may also evict cached successes.
+Idempotency reduces duplicate effects across response loss. It is not a durable transaction, so an
+indeterminate delivery still ends with a world-state read.
 
 ## Batch requests and bulk writes
 
@@ -184,6 +193,12 @@ commands over bounded arrays: elements are prevalidated, but Foundry persistence
 transactional, so the result reports overall completeness plus a per-element outcome, and every
 outcome carries its own meaning.
 
+Batch reads (`get-many`) fail the whole request when any requested id cannot be read, with one
+exception: `setting.get-many` reports an unregistered key on its own result row (`SETTING_NOT_FOUND`)
+rather than failing the request, because a world routinely registers settings only for the systems
+and modules it has active, so a partially resolvable set of keys is the normal case rather than an
+error.
+
 ## Error model
 
 Errors have a stable code, a human-readable message, and optional structured details. The code and
@@ -195,21 +210,90 @@ code set is exported by the protocol package. The classes consumers act on:
 | Request/schema | `INVALID_PARAMS`, `UNKNOWN_COMMAND` | Correct the request or resolve version skew |
 | Authentication/permission | `UNAUTHORIZED`, `PERMISSION_DENIED` | Restore credentials or authority |
 | Pairing | `PAIRING_REQUIRED`, `PAIRING_EXPIRED`, `BRIDGE_BUSY` | Pair, retry revocation, or release the active owner as indicated |
-| Lookup | `*_NOT_FOUND` | Refresh ids and world state |
-| Safety/policy | `DELETE_FORBIDDEN`, `PATH_NOT_ALLOWED` | Change the requested operation |
+| Lookup | `*_NOT_FOUND`, `SETTING_UNREGISTERED` | Refresh ids and world state |
+| Safety/policy | `DELETE_FORBIDDEN`, `PATH_NOT_ALLOWED`, `SETTING_PROTECTED`, `USER_SELF_PROTECTED` | Change the requested operation |
 | Capability | `UNSUPPORTED_OPERATION` | Choose a supported workflow or runtime |
-| Size/resource | `PAYLOAD_TOO_LARGE`, `QUERY_TOO_BROAD` | Reduce or page the request |
+| Size/resource | `PAYLOAD_TOO_LARGE`, `QUERY_TOO_BROAD`, `IDEMPOTENCY_STORE_FULL` | Reduce, page, or resend the request later |
+| Command policy | `COMMAND_DENIED` | Treat the command as unavailable on that GM client |
+| Approval | `APPROVAL_PENDING`, `APPROVAL_DENIED`, `APPROVAL_TIMEOUT`, `APPROVAL_CANCELLED`, `APPROVAL_QUEUE_FULL`, `APPROVAL_UNKNOWN` | Apply the approval rules below |
 | Bridge state | `BRIDGE_NOT_READY`, `BRIDGE_TIMEOUT`, `BRIDGE_DISCONNECTED` | Apply the delivery rules below |
+| Indeterminate outcome | `MACRO_TIMEOUT` | Verify the effect by reads before retrying |
 | Unexpected | `INTERNAL_ERROR` | Preserve details and investigate |
 
 Foundry DataModel validation failures surface as parameter errors and are distinguished in details
 where available. A failed nested lookup identifies the level that failed.
 
+`UNSUPPORTED_PROTOCOL_VERSION` details carry `expectedVersion`, `actualVersion`, the rejecting
+`handshake`, and `staleComponent`. The component is `module`, `cli-daemon`, or `unknown`. Consumers
+can name the component that needs an update when the comparison identifies it. An unordered version
+or unidentified peer produces `unknown`.
+
 With JSON output, a failed command emits one structured error envelope on stdout and exits
 non-zero. The exit code is a coarse process classification; the structured error code is the
 authoritative automation signal. `exec --stdin` reports per-line errors and uses its own aggregate
 exit status.
 
+## Approval flow
+
+A GM client's command policy can require approval before a command runs. Approval is the GM's
+decision about one invocation. Pairing approval grants a browser credential, while confirmation
+checks a completed write. The active GM client's policy controls the invocation.
+
+The wait has two phases because the decision can outlast a normal request timeout:
+
+- The original request returns `APPROVAL_PENDING`. Its details contain `approvalId`, `expiresAt` in
+  epoch milliseconds, and `command`. A consumer without approval support stops on this error. The CLI
+  converts it into a blocking wait.
+- `approval.await { approvalId, waitMs? }` asks for the current state. `waitMs` cannot exceed
+  `APPROVAL_AWAIT_PARK_CAP_MS`. The result is either
+  `{ approvalId, status: "pending", expiresAt? }` or
+  `{ approvalId, status: "resolved", outcome, response? }`. Once execution starts, the approval can
+  no longer expire.
+- Terminal outcomes are `approved`, `denied`, `timeout`, and `cancelled`. An approved outcome carries
+  the command response, including handler errors, and uses the approval identifier as its envelope
+  `id`. The other outcomes mean the command did not run. The CLI reports them as `APPROVAL_DENIED`,
+  `APPROVAL_TIMEOUT`, or `APPROVAL_CANCELLED`.
+- The module retains terminal outcomes for bounded repeat reads. It may discard an outcome after a
+  client has read it, but it does not discard an unread outcome to admit a new request. A later read
+  of discarded state returns `APPROVAL_UNKNOWN`.
+- `approval.cancel { approvalId }` returns `cancelled`, `executing`, `resolved`, or `unknown`. Only
+  `cancelled` proves that the command will not run. Use `approval.await` after `resolved` to read the
+  decision.
+- `APPROVAL_QUEUE_FULL` means the module refused admission before display or execution. Its `reason`
+  is `pending-count`, `pending-bytes`, or `retained-count`. The request is safe to retry after earlier
+  approvals clear.
+- `APPROVAL_UNKNOWN` means the module no longer holds that approval. Reloading the GM client, ending
+  its bridge session, or expiry can remove the state. The command may not have started, or it may have
+  completed. Read world state before another write.
+- A dry run bypasses approval and reports `approvalRequired: true` when the real command would wait.
+  The policy still refuses denied commands during a dry run.
+- `policy.snapshot` reports `{ approve: [names], deny: [names] }`. The result is advisory because the
+  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.
+The bridge handshake advertises them because the daemon must forward them.
+
+An idempotency key covers the request and its approval:
+
+- After `APPROVAL_PENDING`, the daemon links the key to that approval. A byte-identical retry returns
+  the same pending response. A different request with that key returns
+  `IDEMPOTENCY_KEY_CONFLICT`.
+- An approved outcome becomes the cached final response. A denial, timeout, or confirmed
+  cancellation removes the link, so the same request can start a new approval.
+- If the daemon cannot read the approval outcome, the key remains indeterminate and returns
+  `APPROVAL_UNKNOWN` until expiry. Read world state before retrying under a fresh key.
+- If a bridge session ends before the daemon receives the first response, the daemon retains the key
+  as lost in flight. Reuse returns `BRIDGE_DISCONNECTED` with `reason: "lost-in-flight"`. Read world
+  state, then use a fresh key if the operation still needs to run.
+- The daemon reserves bounded space before forwarding a keyed request. If no slot is available, it
+  returns `IDEMPOTENCY_STORE_FULL` before Foundry receives the request. Retry after earlier keys
+  settle or expire.
+- Daemon restart, world switch, pairing switch, and expiry clear runtime idempotency state. A later
+  request can reach Foundry as a new operation, so an indeterminate result still requires a state
+  read first.
+
 ## Delivery states and retries
 
 Retry safety is a function of whether the request reached Foundry:
@@ -219,8 +303,13 @@ Retry safety is a function of whether the request reached Foundry:
 | Client could not connect | No | Safe to retry after restoring the daemon |
 | `BRIDGE_NOT_READY` | No | Safe to retry after a bridge connects |
 | Response timeout after send | Possibly | May have committed; inspect state or reuse the same idempotency key |
-| `BRIDGE_TIMEOUT` | Yes | May have committed; inspect state or reuse the same idempotency key |
-| `BRIDGE_DISCONNECTED` | Yes or in flight | May have committed; inspect state |
+| `BRIDGE_TIMEOUT` | Yes | May have committed; inspect state or reuse the same idempotency key while that bridge session lasts |
+| `BRIDGE_DISCONNECTED` | Yes or in flight | May have committed; inspect state, then re-request under a fresh idempotency key |
+| `COMMAND_DENIED` | Refused before dispatch | Not executed; the command is unavailable on that GM client |
+| `APPROVAL_DENIED`, `APPROVAL_TIMEOUT`, `APPROVAL_CANCELLED` | Reached Foundry, never dispatched | Not executed; the same request is safe to send again |
+| `APPROVAL_QUEUE_FULL` | Refused before admission | Not executed; safe to retry when the waiting decisions clear |
+| `IDEMPOTENCY_STORE_FULL` | No | Not executed; safe to retry when earlier keys settle or expire |
+| `APPROVAL_UNKNOWN` | Unknown | May have committed; inspect state, then re-request under a fresh idempotency key |
 | Structured command rejection | Resolved with an error | Correct according to the code |
 
 The distinction between connection-phase and response-wait failures is carried in structured error
@@ -229,8 +318,10 @@ protocol and CLI constants; runtime flags can override the client and daemon req
 
 ## Compatibility rules
 
-- Additive result and handshake fields are preferred for compatible evolution.
-- Request schemas remain explicit and versioned.
+- One release ships the CLI, daemon, and Foundry module as a compatible set. They share that release's
+  version. The bridge refuses mixed-release operation and does not negotiate a subset.
+- Within a release line, additive result and handshake fields are how the contract evolves without
+  changing the meaning of existing fields; request schemas remain explicit and versioned.
 - A bridge advertises the command set it can execute; the daemon forwards only advertised commands.
 - Unsupported version-dependent behavior produces a predictable error rather than a false success.
 

package/docs/security.md

@@ -33,15 +33,16 @@ public multi-tenant API.
   storage is shared by every tab of one browser, so a first-use identifier can be generated twice when
   two tabs start pairing at once; the browser discards an approved credential whose identifier no longer
   matches the stored one instead of keeping a pairing the hello gate would refuse.
-- The browser label attached to a pairing is constrained by the protocol schema — 1 to 64 characters,
-  with whitespace-only values rejected along with control, zero-width, bidirectional-override, and
-  Unicode tag characters — and a violating request is refused rather than repaired. Rejecting a
-  whitespace-only label removes the simplest way to send a label that reads as nothing; it is not a
-  guarantee that a label renders visibly, because blank-rendering filler characters pass the pattern.
+- The browser label attached to a pairing is constrained by the protocol schema to 1 to 64
+  characters, with whitespace-only values rejected along with control, zero-width,
+  bidirectional-override, and Unicode tag characters; a violating request is refused rather than
+  repaired. Rejecting a whitespace-only label removes the simplest way to send a label that reads
+  as nothing; it is not a guarantee that a label renders visibly, because blank-rendering filler
+  characters pass the pattern.
   The client identifier printed beside the label is what reliably distinguishes two browsers, including
   two that share one label. The pairing socket is unauthenticated, so any local process can send a
   pairing request, and an unfiltered label would reach a terminal as an escape-sequence injection or as
-  hidden text in agent output: both approval prompts, the one `auth approve` shows and the one the
+  hidden text in agent output. Both approval prompts, the one `auth approve` shows and the one the
   `auth` pairing wait shows, print it as raw text, and JSON output escapes C0 control characters but
   not C1, zero-width, bidirectional-override, or tag ones. The constraint covers the label field only;
   the identity fields printed beside it are described under Known risks.
@@ -52,7 +53,9 @@ public multi-tenant API.
   any other local process is still refused rather than repaired.
 - Browser pairing and bridge sockets require a syntactically valid HTTP(S) Origin, matched exactly
   after pairing. Credentials never appear in URLs, command lines, environment variables, or output.
-- The bridge starts only for a configured GM client.
+- The bridge starts only for a configured GM client. The module hides its settings and category from
+  users below the Assistant GM role, and only gamemasters can open its windows. The settings remain
+  registered in that browser profile for a later GM session.
 - Another pairing cannot displace the active bridge. A same-pairing reconnect may take over after a
   reload; requests already forwarded to the displaced socket fail immediately as indeterminate.
   Abnormal close retains a 30-second lease against other pairings, while intentional goodbye,
@@ -79,7 +82,7 @@ runtime address does not broaden that authority or invalidate an explicitly conf
 
 The bridge accepts only explicit commands registered in the protocol and advertised during the
 handshake. Each command has a schema and a known handler. There is no generic method invocation or
-universal “edit anything” endpoint.
+universal "edit anything" endpoint.
 
 Mutations use Foundry Document APIs or a reviewed typed Foundry action. Raw live world databases are
 outside the command surface.
@@ -106,6 +109,43 @@ Foundry hooks can veto or partially apply writes. Mutation handlers confirm obse
 where the command contract requires it and return structured partial or failed outcomes instead of
 claiming success.
 
+Every command also carries an allow, approve, or deny permission in the GM client holding the
+bridge. The Foundry module enforces it after authentication, GM authority, and write-permission
+checks but before dispatch. It covers reads, writes, bulk envelopes, and previews. The default
+policy denies commands that can execute code, change who can do what, or persist outside the
+world's own data; requires approval for destructive commands plus `system.reload` and
+`user.create`, where the destructive set is the `delete` and `delete-many` verbs, `file.move`,
+`scene.fog.reset`, and `chat.flush`; and allows the other policy-controlled commands. A
+denied-by-default command is a deliberate opt-in: it exists so a GM can enable it knowingly, not
+so it can run out of the box.
+
+`system.ping`, `system.info`, and the internal approval-wait commands always run. They let the bridge
+report its state and finish decisions already taken without changing world content. Stored policy
+overrides cannot change them, and the permissions window omits them. Pairing and other `auth`
+operations run in the daemon, so the command policy does not apply.
+
+A denied command is absent from the CLI's `commands` listing while the bridge is reachable. This
+reduces irrelevant choices for automated callers but does not enforce the policy. The Foundry module
+enforces it at dispatch and returns `COMMAND_DENIED` if a caller sends the command anyway.
+
+The original request does not execute a command that requires approval. The module holds it in
+memory until the GM decides. After Allow, the module repeats readiness, GM authority, parameter,
+write-permission, policy, and family checks. A command changed to deny while waiting returns
+`COMMAND_DENIED`. Changing it between allow and approve does not create a second approval. A denied,
+expired, or confirmed-cancelled request never runs.
+
+The module returns a random 128-bit `approvalId` only to the original caller. Reading or cancelling
+the decision requires that identifier.
+
+The GM-only Command Approval window shows the command, remaining time, target documents or managed
+paths, and parameters. It reports binary upload content by size instead of rendering the payload,
+and any text longer than 16,384 characters, including a macro body, by its character count for the
+same reason. A macro long enough to cross that line is therefore approved on its name and origin
+rather than on its code, and `macro.create` runs by itself under the shipped defaults, so a GM who
+wants every body reviewable moves `macro.create` and `macro.update` to approve as well. The command
+envelope has no caller identity, so the window cannot name the requester. The GM approves the
+displayed invocation, not a person or process.
+
 ## Document ownership
 
 Ownership is access policy rather than ordinary document content. Raw `ownership` is excluded from
@@ -119,13 +159,36 @@ family's behavior.
 
 ## Executable content
 
-CLI-supplied data cannot create an arbitrary JavaScript execution path through the bridge.
-
-- Macro bodies and chat content can be stored but are not executed or routed through command
-  processors.
+The bridge executes no JavaScript that the GM has not explicitly enabled and cannot see before it
+runs. There is no `eval`-style command, and CLI-supplied data cannot create a hidden execution path
+through ordinary writes.
+
+- `macro.execute` is the one way to run code, and it runs only stored world macros. It is denied by
+  default; a GM who enables it can keep it on approve, where the Command Approval window shows the
+  macro's type and its command body, up to the length cap described above, before anything runs.
+  The `macro.create → macro.execute → macro.delete` chain is the sanctioned path for ad-hoc code,
+  so a GM who wants only vetted macros to run sets `macro.create` and `macro.update` to approve or
+  deny while `macro.execute` stays enabled. A script macro that throws fails the command with a
+  structured error naming what the macro raised, and the failure is partial by nature: whatever
+  the macro changed before it threw stays changed. A macro that catches its own errors still
+  reports a `null` return, so results do not prove success and effects deserve a read-back.
+- Macro bodies and chat content written by ordinary document commands are stored, not executed.
 - Action commands invoke only their fixed typed Foundry methods.
-- Writes that supply core script- or macro-executing RegionBehavior types are rejected through a
-  shared guard.
+- Ordinary region-behavior writes reject core script- or macro-executing types through a shared
+  guard, including on nested behaviors supplied with a region write. The dedicated
+  `scene.region.behavior.executable` commands, denied by default, accept exactly the `executeMacro`
+  type and require the referenced world macro to exist; the approval window names the macro, the
+  trigger events, and whether the behavior fires for everyone. Those commands accept a behavior's
+  `system` only in a spelling the guard and that window can both read: a create takes only the plain
+  `system` object, an update or clone also accepts single-field `system.<field>` paths, and no route
+  accepts both spellings at once, a path deeper than one field (`system.events.<n>`), a
+  forced-replacement or forced-deletion operator key, or a read field carrying the wrong type (a
+  non-array `events`, a non-boolean `everyone`). Each of those could store a macro reference or a
+  trigger set that differs from the one the macro check validated and the approval window showed. An
+  `executeMacro` behavior triggers later on player-driven region events, with `everyone: true`
+  running the macro on every connected client.
+- `executeScript` behaviors are not supported on any route: Foundry runs their source in every
+  connected player's browser with no per-user execution check, which no popup can make reviewable.
 
 Installed systems and modules remain trusted Foundry code. They can register behavior types, hooks,
 ActiveEffect interpretations, or other data-driven features whose effects the bridge cannot classify
@@ -138,11 +201,49 @@ or chat output after the direct command.
 
 ## Settings
 
-Setting discovery is read-only. Listing returns registration metadata, while reading a value requires
-an explicit namespace and key. Values are serialized with bounded depth, node count, and byte size.
-
-The CLI does not expose setting writes because settings can alter global security and runtime
-behavior and frequently invoke module callbacks.
+Listing returns registration metadata, while reading a value requires an explicit namespace and key,
+singly or in a batch. Values are serialized with bounded depth, node count, and byte size, and this
+module's own secret-bearing settings are redacted from every read.
+
+`setting.set` and `setting.set-many` exist because module configuration is a legitimate
+administration task, and they are denied by default because settings can alter global security and
+runtime behavior and frequently invoke module callbacks: a write to `core.permissions` or
+`core.moduleConfiguration` changes what the GM client itself can do or load. Writes go through
+Foundry's own registration and DataField validation, and only registered settings are writable. The
+approval behavior shows the stored value next to the proposed one before a write runs.
+
+The command policy stays beyond the CLI's reach by construction: the write commands refuse this
+module's namespace with a structured error in every mode, real, dry-run, and per bulk element
+alike, so no policy setting, credential, or approval timeout can be changed from the surface the
+policy governs. The client-scoped `commandPolicy` and `approvalTimeoutMinutes` settings remain readable
+because they contain no secrets, and only a GM using Foundry changes them: the Command permissions
+window writes the policy, and the main Module Settings form writes the timeout and enforces its
+bounds. Another browser profile or machine has its own values.
+
+## Users
+
+User accounts are managed through explicit per-purpose commands rather than one open patch surface.
+
+- No command reads or writes `password` or `passwordSalt`. Foundry transmits a set password in
+  clear text and hashes it server-side, so a password path through the bridge would expose secrets
+  in transcripts and logs; password changes stay in Foundry's own UI.
+- `user.update` edits profile fields and is allowed by default because none of them grant
+  authority; the fields are name, color, pronouns, avatar, assigned character, and flags.
+- `user.create` and `user.delete` ask for approval by default. `user.role.set` and
+  `user.permissions.set` are denied by default because they change who can do what.
+- A `user.create` carries whatever role it asks for, up to the caller's own, so an approved one can
+  mint a gamemaster. That is why it asks for approval rather than running by itself: the approval
+  window names the account and the role, including the player role Foundry gives when the command
+  asks for none, and the GM reading it is the review point. A GM who does not want that decision
+  in the loop at all sets `user.create` to deny.
+- The bridge GM's own account is self-protected: `user.role.set`, `user.permissions.set`, and
+  `user.delete` aimed at the user holding the bridge are refused with a structured error, so
+  automation cannot demote, remove, or strip the restricted menus from the account it runs through.
+  A second GM account carries no such guard; deciding about it is exactly what enabling the command
+  means.
+- Foundry's server-side limits stay in force underneath: a role cannot be raised above the caller's
+  own, and the last gamemaster account can be neither demoted nor deleted. Those refusals surface
+  as permission errors with Foundry's own message.
 
 ## Search
 
@@ -165,8 +266,11 @@ Reads address normalized managed-data paths. Writes are restricted to the active
 - `packs/` and all descendants.
 
 Containment and exclusions are segment-aware and are checked before payload decoding or capability
-dispatch. Absolute host paths, traversal, sibling-prefix tricks, and encoded attempts to cross the
-boundary are rejected.
+dispatch. Path normalization rejects a segment whose literal or percent-decoded form is `.` or `..`,
+and a segment whose decoded form contains a path separator (so a percent-encoded `/` or `\` cannot
+smuggle traversal inside one segment). Absolute host paths, traversal, sibling-prefix tricks, and
+percent-encoded traversal (`%2e%2e`, `..%2f..`) therefore cannot cross the boundary; this applies to
+every managed-path caller, including `image show`.
 
 The module accepts upload content over the authenticated local transport and a managed data-relative
 destination. It does not read arbitrary files from the operator machine. The CLI may read an explicit
@@ -190,6 +294,9 @@ The daemon and module bound uploads, WebSocket frames, search work, batch sizes,
 shapes. Oversized operations return structured errors where possible without dropping the shared
 bridge session.
 
+The module limits the number and combined size of approval requests. It refuses an excess request
+before display or execution. It does not discard an unread outcome to admit a new request.
+
 The system remains susceptible to ordinary local denial of service by an authorized caller issuing
 many expensive Foundry operations. It is designed for cooperative local automation, not hostile
 multi-user scheduling.
@@ -204,7 +311,7 @@ multi-user scheduling.
 - The label and the client identifier are the only pairing identity fields constrained against terminal
   escape sequences. World title and GM name arrive on the same unauthenticated pairing request without
   that constraint, and the CLI prints them as raw text wherever it renders a pending request or a
-  stored profile — both approval prompts and the `auth prune` candidate listing, which precedes an
+  stored profile: both approval prompts and the `auth prune` candidate listing, which precedes an
   irreversible deletion. A local process can therefore redraw the identity lines an operator reads
   before answering, and a title that survived one approval is re-rendered from the stored record every
   time a later command lists it.
@@ -219,7 +326,28 @@ multi-user scheduling.
 - Native Foundry batch operations are not transactional and can partially apply.
 - Search and read commands can expose GM-visible world content to the local caller.
 - Large but permitted content can consume browser memory and processing time.
+- An approved command executes when the GM decides, so the world may have changed while it waited.
+  Approval does not lock world state.
+- Decisions waiting for a GM live only in that browser session. Reloading the GM client or ending
+  its bridge session discards them. Waiting callers receive an indeterminate result.
+- A caller that disappears without a confirmed cancellation leaves its request actionable on the
+  GM's screen until the GM decides or the timeout expires. The command envelope carries no client
+  identity, so the module cannot tell that the caller is gone.
+- The daemon keeps reservations, approval links, and lost-in-flight idempotency keys in one bounded
+  store shared by its clients. It returns `IDEMPOTENCY_STORE_FULL` instead of evicting an
+  indeterminate key. Capacity returns when earlier keys settle or expire, or when a daemon restart,
+  world switch, or pairing switch clears the store.
+- Command permissions belong to a browser profile. A second paired browser, or the same browser with
+  a fresh profile, holds its own permissions, and whichever client holds the bridge is the one whose
+  permissions apply.
 - Declarative content can reference existing executable or module-interpreted content.
+- `image show` accepts an arbitrary off-host `http(s)` URL as its source and pushes it to the
+  targeted players' clients unchanged, so an enabled caller can make those browsers fetch and display
+  a remote image the operator did not host. Only local sources are confined to the managed data
+  boundary; a URL source is a display of external content, not a file read.
+- An enabled `macro.execute` or executable-behavior command makes the GM's enablement and approval
+  discipline the effective code-review boundary; an enabled `setting.set` can change core settings
+  that alter the GM client's own capabilities or take it down until a reload.
 
 ## Operator guidance
 
@@ -228,6 +356,11 @@ multi-user scheduling.
 - Use JSON output, dry runs, stable idempotency keys, and post-write reads for automation.
 - Review every outcome of a bulk operation.
 - Treat forwarded timeouts and disconnects as potentially committed.
+- Set the approval timeout to the time a GM realistically needs to answer. A long timeout keeps a
+  request actionable long after its caller gave up; a short one refuses work the GM would have
+  approved. Either way the expiry never executes the command.
+- Configure command permissions in every browser profile that holds the bridge, and review them
+  after an update that adds commands.
 - Review installed systems and modules before authoring automation-sensitive data.
 - Back up important worlds before large migrations.
 - Run the live smoke workflow only in a designated test world.

package/docs/skill.md

@@ -1,6 +1,6 @@
 # Agent skill
 
-fvtt-world-cli ships with `foundry-world-editor`, an installable Agent Skill — a short operating
+fvtt-world-cli ships with `foundry-world-editor`, an installable Agent Skill, a short operating
 manual that teaches an AI agent to drive this CLI safely: how to bring the stack up and check its
 health, the read → preview → commit → verify loop, how to classify failures before retrying, and
 where the hard safety boundaries are. Skills follow the open Agent Skills standard, so the same
@@ -18,8 +18,8 @@ fvtt-world-cli skill install
 ```
 
 The default installation delegates to the ecosystem's skills CLI (`npx skills add`), which detects
-the agents present on the machine. It keeps one canonical copy under `~/.agents/skills` — the
-vendor-neutral location of the Agent Skills standard — and points each agent's own skill directory
+the agents present on the machine. It keeps one canonical copy under `~/.agents/skills`, the
+vendor-neutral location of the Agent Skills standard, and points each agent's own skill directory
 at it, so every agent reads the same single copy.
 
 An explicit destination works without the skills CLI or network access:
@@ -36,12 +36,12 @@ skill permanently identical to the CLI it came from.
 
 The skill is versioned together with the CLI, and the CLI keeps installed copies current on its
 own: updating the npm package refreshes them, and the daemon performs the same check at startup for
-installations updated by other means, such as a git checkout. For updating purposes a copy is one
+installations updated by other means, such as a git checkout. For updates, a copy is one
 of two kinds:
 
-- An **unmodified** copy — exactly what some version of the CLI shipped — is replaced silently with
+- An **unmodified** copy, exactly what some version of the CLI shipped, is replaced silently with
   the current version.
-- A **modified** copy — one with local edits — is never replaced automatically. It produces a
+- A **modified** copy, one with local edits, is never replaced automatically. It produces a
   warning instead, and keeps producing it until the difference is resolved.
 
 The explicit update command follows the same rule and can override it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fvtt-world-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Safe local CLI and authenticated bridge for automating live Foundry VTT worlds.",
   "license": "MIT",
   "author": "DroiD16",
@@ -45,6 +45,6 @@
     "zod": "^3.24.3"
   },
   "devDependencies": {
-    "@fvtt-world-cli/protocol": "1.0.0"
+    "@fvtt-world-cli/protocol": "1.1.0"
   }
 }