fvtt-world-cli 1.0.0 → 1.1.0

package/docs/README.md

@@ -29,7 +29,7 @@ inventory in prose; [Agent skill](skill.md) explains why it exists and how it is
 | [Getting started](getting-started.md) | People | First-run daemon, pairing, and bridge walkthrough |
 | [Commands](commands.md) | People | Capabilities, common workflows, shared command behavior, and navigation by task |
 | [Agent skill](skill.md) | Agent operators | Why the packaged skill exists, installing it, how updates and removal work |
-| [Protocol](protocol.md) | Implementers and automation consumers | Transport, session, delivery, and error semantics — the integration contract |
+| [Protocol](protocol.md) | Implementers and automation consumers | Integration contract for transport, sessions, delivery, approval, and errors |
 | [Architecture](architecture.md) | Contributors | Component responsibilities and request flow |
 | [Security](security.md) | Operators and contributors | Trust boundaries, permissions, managed files, and known risks |
 | [Foundry compatibility](compatibility.md) | Operators and contributors | Current differences between supported Foundry major versions |
@@ -47,7 +47,7 @@ fvtt-world-cli actor update --help
 fvtt-world-cli docs protocol
 ```
 
-`commands --json` enumerates the command registry and identifies mutations. `schema` returns the
+`commands --json` enumerates the available commands and identifies mutations. `schema` returns the
 request schema used by local validation. Command help maps protocol parameters to CLI flags. `docs`
 lists and prints these documentation files as shipped with the installed CLI.
 

package/docs/architecture.md

@@ -55,6 +55,7 @@ not copied into documentation.
 
 - second-boundary request validation;
 - GM permission checks;
+- the command-permission gate and the human approval loop it opens;
 - protected-metadata sanitization;
 - document lookup and serialization;
 - capability adaptation across supported Foundry versions;
@@ -63,6 +64,18 @@ not copied into documentation.
 - observable write confirmation;
 - managed-file containment.
 
+The bridge checks command permissions after readiness, GM authority, parameter validation, and write
+permission. It checks them immediately before handler lookup. Direct commands and commands released
+by GM approval therefore use the same guards. The approved route skips only the permission gate for
+that invocation.
+
+The default permission profile is generated from one three-bucket rule in the protocol package,
+with deny taking precedence over approve over allow: an explicit list denies commands that can
+execute code, change who can do what, or persist outside the world's own data; destructive
+commands and listed exceptions require approval; everything else is allowed. Keeping the rule in
+the protocol package, next to the registry, means a new command cannot ship without a default
+behavior, and the generated profile is byte-pinned so the rule and its output cannot drift apart.
+
 The module ships plain browser-compatible JavaScript. Its generated protocol mirror is produced from
 the canonical protocol package.
 
@@ -90,6 +103,11 @@ CLI invocation
 The bridge advertises its supported commands during the handshake. The daemon forwards only commands
 advertised by the active session.
 
+A command that requires GM approval pauses before dispatch. The module keeps the invocation in
+memory and returns a pending approval. The CLI then requests the outcome through short polls keyed by
+the approval identifier. If the GM allows the command, the module runs the normal guard sequence
+again before dispatch.
+
 ## Validation boundaries
 
 The CLI validation pass provides fast feedback and avoids unnecessary connections. The bridge repeats
@@ -121,6 +139,10 @@ A dry run performs the same preparation and guards as a real command, then stops
 Real commands confirm stored state where their contract depends on a write landing. Native Foundry
 batch calls can partially apply, so bulk results include per-element outcomes.
 
+A capability check asks whether the connected Foundry can perform an operation. Approval is the GM's
+decision to let one invocation run. Confirmation checks whether Foundry persisted a completed write.
+An approved command can still fail during execution or confirmation.
+
 Idempotency keys reduce duplicate effects across response loss while the relevant daemon/bridge cache
 entry exists. They do not create durable distributed transactions.
 
@@ -160,11 +182,11 @@ re-pairing rotates only the re-pairing browser's credential. Making the browser
 also makes the human label meaningful, so the label travels with the pairing request instead of being
 editable daemon-side metadata: it is fixed between pairing approvals, and an approval that reuses an
 existing record adopts the label that request carried. The design keeps slot ownership
-unambiguous: a socket receives its role only after completed authentication rather
-than from a claimed message type; only a same-pairing socket can take over the slot, as the
-tab-reload recovery path; intentional goodbye, release, and revocation clear ownership before close
-handling, while only an abnormal close creates a short reclaim lease; and daemon-initiated release is
-terminal for the released client so reconnection remains an explicit operator action. Every way a
+unambiguous. A socket receives its role only after completed authentication rather than from a
+claimed message type, and only a same-pairing socket can take over the slot, as the tab-reload
+recovery path. Intentional goodbye, release, and revocation clear ownership before close handling,
+while only an abnormal close creates a short reclaim lease. Daemon-initiated release is terminal
+for the released client, so reconnection remains an explicit operator action. Every way a
 pairing attempt can end shares one idempotent cleanup path, so the authorization UI cannot retain a
 stale pending state.
 
@@ -177,7 +199,15 @@ One of those operations parks instead of answering at once: the wait for a pairi
 response until a request arrives or the daemon's own park cap elapses. That cap is what keeps a parked
 answer inside the caller's request timeout, so an unanswered wait ends in an empty result the CLI
 re-issues rather than in a transport failure; a cap at or above the client's wait would turn every
-wait into one.
+unanswered wait into a transport failure.
+
+Approval waits use the same bounded polling pattern inside the Foundry module. The module answers the
+original request with a pending approval. Later polls wait within the transport timeout and ask again
+after an ordinary reconnect.
+
+Both halves of the wait use runtime state. The browser session holds the decision and retained
+outcome. The daemon links an idempotency key to the approval in its idempotency store. Neither half
+persists this state. Losing it produces an indeterminate result rather than an automatic retry.
 
 Normative handshake, takeover, lease, and release semantics are defined in
 [Protocol](protocol.md#bridge-sessions); the authentication guarantees and host validation rules are
@@ -193,11 +223,13 @@ carries no wire-protocol meaning; the daemon and the CLI neither send nor observ
 
 The hook fires once per actual change, on the client transport status or on the handshake
 acknowledgement, and receives the same snapshot that `system info` reports as `bridge`: `status`,
-`url`, `helloAcknowledged`, `hasEstablishedSession`, `lastConnectedAt`, `reconnectAttempts`, and
-`terminalStopReason`. Readiness is `status === "connected"` together with `helloAcknowledged`, because
-an open socket precedes the daemon's acknowledgement. A snapshot never reports an acknowledged
-handshake on a client that is no longer connected: losing the socket resets the acknowledgement before
-the status transition that publishes it, so consumers cannot observe that contradictory pair.
+`url`, `helloAcknowledged`, `hasEstablishedSession`, `lastConnectedAt`, `reconnectAttempts`,
+`terminalStopReason`, and `protocolVersionMismatch`. The last field is `null` unless the module
+refuses a handshake because the protocol versions differ. It then reports both versions and names
+the older component as `module`, `cli-daemon`, or `unknown`. The status window uses that value to
+show the required update. Readiness requires `status === "connected"` and `helloAcknowledged` because
+the socket opens before the daemon acknowledges the handshake. Losing the socket clears the
+acknowledgement before publishing the status change.
 `helloAcknowledged` stays in the snapshot for consumers that need the distinction; the module's own
 windows fold it into the connection state they display rather than showing it as its own field.
 

package/docs/commands.md

@@ -65,21 +65,23 @@ the active slot can be cleared with `bridge release`. The daemon never prints a
   drops, which is reported as `DAEMON_UNAVAILABLE` rather than a silent stop and is safe to re-run once
   the daemon is back. `y` or `yes` approves the displayed code and exits 0, any other answer denies that
   code and exits 1 with `PAIRING_DECLINED`.
-  Ctrl+C, or an ended stdin, at the confirmation instead leaves the request untouched, and it stays
-  pending until it expires or another run answers for it. An ended stdin, and Ctrl+C while output goes
-  to the terminal too, report `PAIRING_PROMPT_ABORTED` and exit 1; with output redirected the prompt
-  does not read keystrokes itself, so Ctrl+C ends the run as an ordinary interrupt instead.
+  Interrupting the confirmation instead leaves the request untouched: after Ctrl+C or an ended
+  stdin it stays pending until it expires or another run answers for it. An ended stdin reports
+  `PAIRING_PROMPT_ABORTED` and exits 1, and Ctrl+C does the same while output goes to the terminal;
+  with output redirected the prompt does not read keystrokes itself, so Ctrl+C ends the run as an
+  ordinary interrupt instead.
   Delivery is a long-poll control call the CLI re-issues on its own, and the daemon answers each call
   inside its own park cap, so an ordinary wait does not end in a timeout; a daemon that stops answering
   altogether still trips the client's request timeout and is reported as `DAEMON_UNAVAILABLE`. The
   command is interactive-only: `--json`, and a stdin that is not a terminal, each fail
   immediately and name `auth pending` plus `auth approve --yes` as the path for scripts.
-  `--timeout-ms` cannot cut the wait short either — a value below the daemon's park cap plus five
-  seconds is raised to it for the long-poll call, because a smaller client wait would abandon a parked
-  response the daemon is still holding. That long poll is the only call the flag cannot shorten: the
-  approval or denial that follows the answer, and the listing an interactive `auth approve` or
-  `auth prune` reads before its prompt, take `--timeout-ms` as given for their client wait, as the
-  other `auth` verbs and `bridge release` do; without the flag that wait is 60 seconds.
+  `--timeout-ms` cannot cut the wait short either. For the long-poll call, a value below the
+  daemon's park cap plus five seconds is raised to it, because a smaller client wait would abandon
+  a parked response the daemon is still holding. That long poll is the only call the flag cannot
+  shorten. The approval or denial that follows the answer takes `--timeout-ms` as given for its
+  client wait, and so does the listing an interactive `auth approve` or `auth prune` reads before
+  its prompt, as the other `auth` verbs and `bridge release` do. Without the flag that wait is
+  60 seconds.
 - `auth status` shows bridge state and public profile metadata.
 - `auth pending` lists approval candidates with code, expiry, exact Origin, world, GM, browser client
   id, browser label, and module version.
@@ -87,13 +89,13 @@ the active slot can be cleared with `bridge release`. The daemon never prints a
   request is pending. Interactive use confirms the displayed identity, including the browser label and
   client id, and then approves that exact request: one that expired or disappeared while the prompt
   waited fails rather than approving whatever else is pending. When no single pending request can be
-  shown — nothing pending, an unknown code, or several candidates — it names the live pending codes and
-  stops instead of asking. Answering anything but `y` or `yes` cancels the approval, reports
-  `PAIRING_DECLINED` and exits 1 — the same code and exit the bare `auth` wait reports for a declined
-  request, which the wait also denies outright while this verb leaves it pending. Interrupting the
-  prompt also leaves the request pending, and reports `PAIRING_PROMPT_ABORTED` with exit 1 on the same
-  terms as the wait. Scripts must pass `--yes`. The stored label is the one the browser sent — approval
-  does not rename it.
+  shown, because nothing is pending, the code is unknown, or several candidates exist, it names the
+  live pending codes and stops instead of asking. Answering anything but `y` or `yes` cancels the
+  approval, reports `PAIRING_DECLINED` and exits 1, the same code and exit the bare `auth` wait
+  reports for a declined request; the wait also denies the request outright, while this verb leaves
+  it pending. Interrupting the prompt also leaves the request pending, and reports
+  `PAIRING_PROMPT_ABORTED` with exit 1 on the same terms as the wait. Scripts must pass `--yes`.
+  The stored label is the one the browser sent; approval does not rename it.
 - `auth deny <code>` rejects a pending request.
 - `auth list` shows non-secret profile metadata, including each profile's `clientId` and `label`.
   A label is set in the browser at pairing time and no control operation renames a stored record, so
@@ -107,11 +109,11 @@ the active slot can be cleared with `bridge release`. The daemon never prints a
 - `auth prune [--older-than <days>] [--yes]` deletes the profiles that have gone unused. A profile is
   a candidate when its `lastSeenAt` is older than the cutoff, which defaults to 30 days; the active
   bridge profile and the holder of an abnormal-disconnect lease are never deleted, however idle their
-  stored timestamp looks. Interactive use lists the candidates it found — label, client id, world, GM,
-  last-seen timestamp, and pairing id — and asks once for the whole set. The listing skips the profile
-  `auth list` reports as active, so a browser that has stayed connected past the cutoff is neither shown
-  nor counted in the prompt, matching what the daemon will do. Answering anything but `y` or
-  `yes` removes nothing, reports `PAIRING_DECLINED` and exits 1; interrupting the prompt reports
+  stored timestamp looks. Interactive use lists the candidates it found, with label, client id,
+  world, GM, last-seen timestamp, and pairing id, and asks once for the whole set. The listing
+  skips the profile `auth list` reports as active, so a browser that has stayed connected past the
+  cutoff is neither shown nor counted in the prompt, matching what the daemon will do. Answering
+  anything but `y` or `yes` removes nothing, reports `PAIRING_DECLINED` and exits 1; interrupting the prompt reports
   `PAIRING_PROMPT_ABORTED` and exits 1 on the same terms as `auth approve`. A listing that found no
   candidate asks nothing and still runs the operation, so the command's output is the daemon's own empty
   result rather than a local verdict. The listing is a preview only: the daemon recomputes the set,
@@ -120,7 +122,7 @@ the active slot can be cleared with `bridge release`. The daemon never prints a
   crossed the cutoff while the prompt waited is removed although it was never listed; it can equally be
   smaller, because a profile that became active or was already removed between the two steps is
   reported as the daemon left it. There is no dry-run mode, and `--older-than 0` treats every profile
-  as idle, which is the one case where a preview can name a lease holder the daemon then keeps —
+  as idle, which is the one case where a preview can name a lease holder the daemon then keeps.
   `auth list` does not expose the lease, and a lease holder's last-seen timestamp is fresh by
   definition, so no realistic threshold selects it. Scripts pass `--yes`, which skips both the preview
   and the prompt; `--json` requires `--yes` as well, because the confirmation is never mixed into JSON
@@ -132,8 +134,8 @@ the active slot can be cleared with `bridge release`. The daemon never prints a
   An active browser stopped by release stays stopped until its operator chooses Connect.
 
 Every command in this section is answered by the daemon alone, with no Foundry browser involved, so
-a daemon that is not running or not reachable ends any of them — the `auth` verbs and
-`bridge release` alike — with `DAEMON_UNAVAILABLE` and exit 3 rather than a command-level failure.
+a daemon that is not running or not reachable ends any of them, the `auth` verbs and
+`bridge release` alike, with `DAEMON_UNAVAILABLE` and exit 3 rather than a command-level failure.
 
 In Foundry, Connect reuses the stored browser credential and Disconnect releases the slot without
 touching it. Unpair waits for confirmed daemon revocation
@@ -162,8 +164,10 @@ on the CLI:
 | Tokens embedded in a scene | `scene.token.*` | `fvtt-world-cli scene token …` |
 | Effects on a placed token | `scene.token.effect.*` | `fvtt-world-cli scene token effect …` |
 
-Use `fvtt-world-cli commands --json` for the complete current inventory. The exact operation set
+Use `fvtt-world-cli commands --json` for the current inventory. The exact operation set
 varies by family, so a nearby document family is not a reliable guide to what another one supports.
+With a bridge connected, that inventory is also filtered by the GM client's command permissions, as
+[Discovery under a policy](#discovery-under-a-policy) describes.
 
 ## Capability map
 
@@ -171,7 +175,22 @@ varies by family, so a nearby document family is not a reliable guide to what an
 
 - `actor`, `item`, `journal`, `scene`, `macro`, `playlist`, `table`, and `cards` manage world
   documents.
-- `chat` reads, creates, and deletes chat messages.
+- `chat` reads, creates, and deletes chat messages. `chat flush` erases the entire log at once and
+  asks for GM approval by default because nothing brings the messages back.
+- `user` manages Foundry user accounts. `user update` edits harmless profile fields, `user create`
+  and `user delete` ask for approval by default, and `user role set` plus `user permissions set` are
+  [off by default](#commands-that-are-off-by-default). No command reads or writes a password, and
+  the account holding the bridge cannot demote or delete itself; see
+  [Security](security.md#users).
+- `setting` lists registrations and reads values, including `setting get-many` for batch reads.
+  `setting set` and `setting set-many` write world, client, and user scopes but are
+  [off by default](#commands-that-are-off-by-default); they refuse this module's own namespace in
+  every mode, and a write to an already-stored value is reported as unchanged without touching
+  Foundry. The result's `value` is the value read back after the write, not the value requested: a
+  setting's registered type or `onChange` handler may normalize or clamp what was asked for, so
+  compare `value` against the requested input when the exact stored form matters. The write is
+  confirmed only in that Foundry no longer holds the `previous` value. A result carrying
+  `requiresReload: true` names the follow-up that Foundry expects, which `system reload` performs.
 - `combat` manages encounters and exposes explicit encounter transitions.
 - `folder` manages document organization.
 - Dedicated `*.ownership.set` commands change supported document ownership.
@@ -191,7 +210,11 @@ Common world-document operations include `list`, `get`, `get-many`, `create`, `u
 - `scene.token`, `tile`, `sound`, `wall`, `note`, `drawing`, `light`, `template`, and `region` manage
   scene placeables.
 - `scene.region.behavior` manages region behaviors; writes that supply executable core behavior
-  types are rejected (see [Security](security.md#executable-content)).
+  types are rejected (see [Security](security.md#executable-content)). The separate
+  `scene.region.behavior.executable` family, [off by default](#commands-that-are-off-by-default),
+  authors `executeMacro` behaviors that reference an existing world macro; `executeScript` has no
+  command surface at all. Deleting an executable behavior uses the ordinary
+  `scene region behavior delete`.
 
 Embedded commands require the complete parent ID chain; a read of the parent supplies those IDs when
 they are not already known.
@@ -204,7 +227,38 @@ Some commands invoke a typed Foundry action instead of ordinary CRUD:
 - roll-table draw and reset;
 - card shuffle, reset, deal, draw, and pass;
 - combat start, activation, advancement, and initiative;
-- scene thumbnail generation and fog reset.
+- scene thumbnail generation and fog reset;
+- scene activation (`scene activate`) and pulling active users to a scene (`scene pull-users`);
+- showing a journal entry (`journal show`) or an image (`image show`) to players;
+- pausing or resuming the game clock for everyone (`game pause`);
+- reloading the GM client (`system reload`), which asks for approval by default because it drops
+  the bridge until the client reconnects;
+- macro execution (`macro execute`), [off by default](#commands-that-are-off-by-default).
+
+`scene pull-users`, `journal show`, and `image show` reach every connected player when no
+`--user-ids` list is given. A supplied list has to name at least one user: an empty one is
+indistinguishable from "everyone" on the Foundry side, while the result would report that nobody was
+addressed.
+
+`macro execute` runs a world macro the GM can already execute, waits for it to finish up to a
+bounded `--macro-timeout-ms`, and reports the returned value plus the chat messages it observed the
+macro create. A macro that outlives the timeout keeps running in the GM browser and the command
+returns the indeterminate `MACRO_TIMEOUT`, so the effect is verified by reads. A script macro that
+throws fails the command and the error names what the macro raised; the outcome is partial, because
+whatever the macro changed before it threw stays changed. A macro that catches its own errors still
+reports a `null` return, and a macro is free to reload the page or navigate away, which ends the
+bridge session the same way any disconnect does. Effects therefore deserve a read-back whenever the
+return value alone does not prove them.
+
+Each key of `--args-json` becomes a named variable Foundry splices into the compiled macro, so an
+argument name must be a plain JavaScript identifier (letters, digits, `_` or `$`, not starting with
+a digit) and cannot reuse a name Foundry already binds (`speaker`, `actor`, `token`, `character`,
+`scope`). Any other name is refused before the macro runs.
+
+The result's `chatCapture` field says how much of the chat the run observed: `captured` when every
+message the macro was expected to create was seen, `not-created` when a chat macro created none,
+`partial` when only some were seen, and `unknown` when this client could not watch the chat log at
+all.
 
 Actions can have Foundry, system, or module side effects. Their result describes what the bridge can
 confirm, which may differ from a document post-state, so each action's schema and help are worth
@@ -216,7 +270,8 @@ reading before automating it.
 - `world.audit-files` finds document references to missing managed assets.
 - `compendium.list`, `compendium.index`, and `compendium.get` read pack content.
 - Supported `*.import-from-compendium` commands create world documents from pack sources.
-- `user` and `setting` provide read-only discovery surfaces.
+- `user list`/`user get` and `setting list`/`setting get`/`setting get-many` are the discovery
+  side of the [user and setting families](#world-content).
 
 ### Managed files
 
@@ -228,6 +283,106 @@ See [Security](security.md#file-write-boundary) before automating file writes.
 
 ## Shared command behavior
 
+### Command permissions and approval
+
+Every command has one of three behaviors in the GM client that holds the bridge: allow, approve, or
+deny. A GM edits them under Configure Settings → Module Settings → World CLI → Command permissions.
+The settings belong to the browser profile, so another browser or machine can apply a different
+policy.
+
+An approved command waits for the GM instead of failing. Foundry opens the Command Approval window.
+It shows the command, its targets, and its parameters. The CLI writes one status line to stderr:
+
+```
+Waiting for GM approval in Foundry (command actor.delete, expires 2026-08-28T18:20:00.000Z). Press Ctrl+C to request cancellation.
+```
+
+The line uses stderr in both output modes, so `--json` stdout still carries one envelope. Allow runs
+the command at the time of the decision. The module repeats the normal guards first because world
+state and permissions may have changed while the request waited. The CLI then returns the command's
+success or error.
+
+The wait tolerates short daemon outages, bridge reconnects, and poll timeouts while the approval
+remains open. Other outcomes use structured errors:
+
+| Code | Meaning | State |
+|---|---|---|
+| `COMMAND_DENIED` | The permission is deny, whether at the request or by the time an approved command runs | Not executed |
+| `APPROVAL_DENIED` | The GM chose Deny | Not executed |
+| `APPROVAL_TIMEOUT` | No decision was taken before the approval expired | Not executed |
+| `APPROVAL_CANCELLED` | A cancellation the GM client confirmed won the decision | Not executed |
+| `APPROVAL_QUEUE_FULL` | The module refused admission before showing the request | Not executed |
+| `APPROVAL_UNKNOWN` | The module no longer holds the decision | Indeterminate |
+
+`APPROVAL_UNKNOWN` means the client can no longer prove whether the command ran. Read the affected
+world state before trying again. `APPROVAL_QUEUE_FULL` means the module refused the request before
+execution. Retry after the GM clears earlier requests.
+
+Ctrl+C asks the GM client to cancel a waiting decision. Only `APPROVAL_CANCELLED` proves that the
+command will not run. If the command has started or the client cannot confirm cancellation, the CLI
+reports an indeterminate result.
+
+The default policy sorts commands into the three behaviors by what a mistake would cost. Commands
+that can execute code, change who can do what, or persist outside the world's own data are denied
+until a human enables them; the next section lists them. Commands that destroy world data ask for
+approval, as do `system.reload` and `user.create`; the destructive set is the `delete` and
+`delete-many` verbs, plus `file.move`, `scene.fog.reset`, and `chat.flush`. The remaining commands
+run on their own unless they are exempt from the policy. The Command permissions window and
+`fvtt-world-cli commands --json` show the current inventory.
+
+#### Commands that are off by default
+
+The following commands ship with the deny behavior. They stay invisible to
+[discovery](#discovery-under-a-policy) and refuse to run, even as dry runs, until a GM enables
+them in the Command permissions window of the browser profile holding the bridge:
+
+- `macro.execute`
+- `setting.set`
+- `setting.set-many`
+- `user.role.set`
+- `user.permissions.set`
+- `scene.region.behavior.executable.create`
+- `scene.region.behavior.executable.update`
+- `scene.region.behavior.executable.clone`
+
+They are denied by default because each one executes code, changes who can do what, or persists
+outside the world's own data. Enabling one is a per-browser-profile decision, and the approval
+behavior remains available as a middle ground: a GM who wants to see every macro body before it
+runs sets `macro.execute` to approve rather than allow. [Security](security.md) describes what each
+of these surfaces can and cannot do.
+
+`system.ping`, `system.info`, and the internal approval-wait commands always run. This keeps the
+bridge able to report its state and finish an existing decision. The permissions window omits those
+commands. Pairing and other `auth` operations run in the daemon, outside the command policy.
+
+Foundry plays its standard interface notification when a request enters an empty queue. The `Play a
+sound on approval requests` setting controls it. Browsers may delay the first sound until the GM
+interacts with the page after a reload.
+
+Set the approval deadline with `Approval timeout (minutes)` in the main Module Settings form. The
+form and protocol enforce the supported range. Expiry refuses the command without running it.
+
+Approval state lives in the GM client's memory. Reloading that client or ending its bridge session
+can produce `BRIDGE_DISCONNECTED` or `APPROVAL_UNKNOWN`. Both are indeterminate. Read the affected
+world state before another write, then use a fresh idempotency key if the command still needs to run.
+The complete state and retry contract is in [Protocol](protocol.md#approval-flow).
+
+### Discovery under a policy
+
+With the bridge reachable, `commands` and `commands --json` describe what that GM client will
+actually run. The listing omits denied commands. JSON marks approval waits with `"approval": true`;
+plain output uses an `approval` tag. The JSON envelope also contains
+`policy: { "applied": true, "source": "bridge" }`.
+
+When no bridge answers, the listing falls back to the full static registry and says so:
+`policy: { "applied": false, "source": "static", "reason": … }` in JSON, and a warning on stderr in
+plain output. Only an unavailable daemon or bridge triggers fallback. Authentication, validation,
+and protocol failures return errors.
+
+`schema`, `--help`, and this documentation describe the whole static registry. If a caller sends a
+denied command found there, the GM client returns `COMMAND_DENIED`. Discovery hides; the client
+enforces.
+
 ### JSON output
 
 Use `--json` for automation. Successful requests use a stable envelope:
@@ -303,9 +458,13 @@ All mutation commands accept the global `--dry-run` flag:
 fvtt-world-cli --dry-run actor update --actor-id <id> --name "New name" --json
 ```
 
-The result uses the normal command shape and includes `dryRun: true`. The preview contract — what a
-dry run executes, what it can report, and its non-reservation of state — is defined in
-[Protocol](protocol.md#dry-run).
+The result uses the normal command shape and includes `dryRun: true`. The preview contract is
+defined in [Protocol](protocol.md#dry-run): what a dry run executes, what it can report, and its
+non-reservation of state.
+
+Approval does not hold a preview. A command whose permission is approve previews without asking the
+GM, and its result carries `approvalRequired: true` so the caller knows the commit will wait. The GM
+client returns `COMMAND_DENIED` for a denied preview.
 
 ### Idempotency and retries
 
@@ -361,7 +520,9 @@ First-run setup is covered in [Getting started](getting-started.md).
 
 ## Unsupported boundaries
 
-The CLI intentionally does not provide arbitrary JavaScript execution, direct world-database writes,
-unrestricted filesystem access, generic RPC, compendium editing, setting writes, or transactional
-Foundry batches. Consult [Security](security.md) for the trust boundary and
-[Foundry compatibility](compatibility.md) for version-dependent capabilities.
+The CLI intentionally does not provide arbitrary JavaScript evaluation, direct world-database
+writes, unrestricted filesystem access, generic RPC, compendium editing, or transactional Foundry
+batches. Code runs only through `macro.execute` and `executeMacro` region behaviors, both off by
+default; when a GM keeps them on approve, the window shows a macro execution's own body and names
+the macro a region behavior would run. [Security](security.md) describes the trust
+boundary and [Foundry compatibility](compatibility.md) the version-dependent capabilities.

package/docs/compatibility.md

@@ -7,9 +7,9 @@ result honestly.
 ## Operator contract
 
 - `fvtt-world-cli system info --json` reports the connected Foundry, system, module, limits, and
-  advertised command set.
+  discoverable command inventory.
 - `UNSUPPORTED_OPERATION` is a capability result, not a transient transport failure.
-- A dry run validates a proposed mutation, but values that require execution are not a forecast.
+- A dry run validates a proposed mutation; it does not forecast values that require execution.
 
 ## Known differences
 
@@ -21,6 +21,8 @@ result honestly.
 | Scene placeable fields | Older document models | Some families add fields | Open-family writes pass through sanitized data; reads expose the documented projection |
 | Region behaviors | Core v13 type set | Additional core types | Executable core behavior types remain guarded; other types are Foundry-validated |
 | Combat and action APIs | Version-specific signatures | Version-specific signatures | The bridge adapts known signatures and refuses unsupported behavior |
+| Scene activation | `Scene#activate` runs for any caller | `Scene#activate` throws for non-GM users | The bridge requires GM authority on both versions |
+| User permission names | `TEMPLATE_CREATE` | Renamed to `REGION_CREATE` | `user.permissions.set` validates keys against the connected version's live permission set rather than a fixed list |
 
 This table describes current operator-visible differences, not implementation evidence. Exact
 capabilities remain defined by the connected bridge and exercised by live smoke tests.

package/docs/getting-started.md

@@ -16,7 +16,7 @@ tool is in use.
 
 The daemon should be running before the Foundry GM client loads the world: the module tries to
 connect once when the world loads, and if the daemon is down at that moment it gives up with a
-warning. Connecting after that is a manual retry — Connect in the scene controls, or a client
+warning. Connecting after that is a manual retry: Connect in the scene controls, or a client
 reload.
 
 ## 2. Pair the Foundry GM client
@@ -27,10 +27,10 @@ browser.
 It starts in the module's Authorization window. The quickest way there is the `World CLI` group at
 the bottom of the left scene controls; its icon doubles as a status light:
 
-- muted grey — not paired yet
-- amber — connecting
-- green — the bridge is up
-- red — stopped or failed
+- muted grey: not paired yet
+- amber: connecting
+- green: the bridge is up
+- red: stopped or failed
 
 The same windows are also reachable through Configure Settings → Module Settings:
 
@@ -48,15 +48,15 @@ record.
 
 ![The Authorization window before pairing](images/authorization-window.png)
 
-Choose Pair, then approve the request from a terminal on the daemon's machine — the approval is
+Choose Pair, then approve the request from a terminal on the daemon's machine. The approval is
 what turns the request into a stored permission:
 
 ```bash
 fvtt-world-cli auth
 ```
 
-The command waits for the pairing request (starting it before or after clicking Pair both work),
-shows who is asking — origin, world, GM, browser label, client id — and asks
+The command waits for the pairing request; starting it before or after clicking Pair works either
+way. It shows who is asking, with the origin, world, GM, browser label, and client id, and asks
 `Approve pairing request <code>? [y/N]`. Typing `y` and pressing Enter approves it; any other
 answer denies it. To read a request over before deciding, or to approve from a script, the same
 approval exists as two steps:
@@ -68,7 +68,7 @@ fvtt-world-cli auth approve <code>   # add --yes in a script to skip the confirm
 
 ## 3. Confirm the bridge
 
-On approval the browser stores its pairing credential and starts the bridge immediately — no
+On approval the browser stores its pairing credential and starts the bridge immediately. No
 reload is needed, and the scene-controls icon turns green. From now on the bridge connects on its
 own as soon as the world loads: that is the client-scoped `Connect automatically` setting, enabled
 by default; with it disabled the bridge stays offline until Connect is chosen.
@@ -81,6 +81,15 @@ fvtt-world-cli system info --json
 
 It reports `bridge.status` as `connected`.
 
+Commands use the permissions stored for that browser profile. Run `fvtt-world-cli commands` after
+the bridge connects to see which commands the client will run. A daemon that rejects the browser
+credential returns an error instead of the static registry.
+
+Destructive commands ask the GM by default. Set each command's behavior under Configure Settings →
+Module Settings → World CLI → Command permissions. Set the waiting time in the `Approval timeout
+(minutes)` field in the main Module Settings form. [Commands](commands.md#command-permissions-and-approval)
+describes the behavior in full.
+
 ## When something deviates
 
 The Bridge status window (in the scene controls or the module settings) is the first place to
@@ -96,7 +105,7 @@ abnormal-disconnect lease.
 
 One bridge is active at a time, so a second paired browser's connection attempt stops on
 `BRIDGE_BUSY` and stays stopped. Switching browsers is a Disconnect on the active one followed by
-Connect on the other — pairing plays no part in it.
+Connect on the other; pairing plays no part in it.
 
 Authorization holds the two exits. Unpair revokes this browser's access and removes its credential
 once the daemon confirms the revocation. Forget local is the recovery for a daemon that cannot be