fvtt-world-cli 1.1.1 → 1.1.2

package/README.md

@@ -1,27 +1,21 @@
 # World CLI for Foundry VTT
 
-[![Foundry VTT v13–v14](https://img.shields.io/badge/Foundry%20VTT-v13%E2%80%93v14-ff6400)](https://foundryvtt.com)
+[![Supported Foundry versions](https://img.shields.io/endpoint?url=https%3A%2F%2Ffoundryshields.com%2Fversion%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2FDroiD16%2Ffvtt-world-cli%2Fmain%2Fpackages%2Ffoundry-module%2Fmodule.json)](https://foundryvtt.com)
+[![npm](https://img.shields.io/npm/v/fvtt-world-cli)](https://www.npmjs.com/package/fvtt-world-cli)
+[![npm downloads](https://img.shields.io/npm/dm/fvtt-world-cli)](https://www.npmjs.com/package/fvtt-world-cli)
+[![license](https://img.shields.io/github/license/DroiD16/fvtt-world-cli)](LICENSE)
 
 Tell your AI agent what should change in your Foundry VTT world, and it happens in the live
 world, validated by Foundry, visible to your players immediately.
 
-```text
-You → agent:  "The scimitar in Valeros's inventory should burn targets on hit.
-               Add a Flaming effect to it."
-
-agent → fvtt-world-cli:
-              actor list --name Valeros            find the character
-              actor item list --name scimitar      find the sword in their inventory
-              actor item effect create …           add the effect to it
-
-agent → you:  "Done. Flaming effect added, already live in the world."
-```
+![An AI agent adds lights and goblins to a Foundry tavern scene, shown before and after](https://raw.githubusercontent.com/DroiD16/fvtt-world-cli/main/publishing/media/cover.webp)
 
 Modern agents already understand requests like that. What they have lacked is a safe way into
-Foundry: driving the browser UI is brittle and token consuming, and editing world files on disk
-bypasses everything Foundry does to keep a world consistent. fvtt-world-cli is the missing bridge,
-a command line wired into your open GM session that performs every change through Foundry's own
-APIs, exactly as if a GM had made it in the UI.
+Foundry. Driving the browser UI is brittle and uses extra tokens. Editing world files on disk
+bypasses Foundry's validation.
+
+World CLI for Foundry VTT connects your agent to your open GM session. Every change runs through
+Foundry's own APIs, exactly as if a GM had made it in the UI.
 
 Two things it's not. It is not an AI game master: it does not run the game, it only edits the
 world when asked. And it includes no AI of its own: you connect the agent you already use, such as
@@ -40,12 +34,12 @@ A few asks it handles end to end:
 - "Turn the bestiary goblin into a flying one that throws dynamite for 2d6 damage, and add it to
   the scene."
 
-[Commands](docs/commands.md) maps the full surface.
+See [Commands](docs/commands.md) for command families and usage examples.
 
 ## Setting up
 
-The simplest setup is one step: point your AI agent at this repository and ask it to set
-fvtt-world-cli up. Then follow its lead. It will most likely ask you to install the module in
+The simplest setup is one step: point your AI agent at this repository and ask it to set up
+World CLI for Foundry VTT. Then follow its lead. It will most likely ask you to install the module in
 Foundry and click *Pair* there, and it handles the rest itself.
 
 ### Manual setup
@@ -73,6 +67,9 @@ agent works with the world.
    fvtt-world-cli bridge serve
    ```
 
+   Keep this terminal open and use a second terminal for the remaining commands. Keep the target
+   world open in Foundry, logged in as a GM.
+
 4. Pair the browser: choose *Pair* in the module's Authorization window, reachable from the
    *World CLI* group in the scene controls or from the module's settings. Then approve the request
    from the terminal. It shows the requesting origin, world, GM, and browser, and asks for a yes
@@ -82,7 +79,10 @@ agent works with the world.
    fvtt-world-cli auth
    ```
 
-5. Optionally, install the packaged skill into your AI agent; the next section explains what it
+5. Check the connection in Foundry. The *World CLI* icon in the scene controls turns green when
+   connected. Open *Bridge status* from the same group to see the connection details.
+
+6. Optionally, install the packaged skill into your AI agent; the next section explains what it
    does:
 
    ```bash
@@ -106,11 +106,9 @@ instructions survive updates.
 
 ## Built to be trusted with a live world
 
-The whole design assumes an automated caller that must not be able to exceed its intended
-authority; [Security](docs/security.md) covers the boundaries in full. In short:
+You control which browser connects and which commands the agent may run. The main safeguards are:
 
-- Everything stays on your machine: the daemon accepts loopback connections only, and there is no
-  internet-facing mode.
+- The daemon accepts connections only from your machine, with no internet-facing mode.
 - Nothing connects without your approval: every browser pairs once through an explicit yes at your
   terminal, and no secrets are printed along the way.
 - Foundry remains the authority: every change runs through the same Document APIs and validation
@@ -119,21 +117,23 @@ authority; [Security](docs/security.md) covers the boundaries in full. In short:
   validation and guards as a real call and stops before mutation.
 - Every command has a permission in the active Foundry client: run, ask the GM, or refuse.
   Destructive commands ask the GM by default.
-- There is no arbitrary-code path: commands are typed and validated on both sides of the transport,
-  and executable content such as scripted region behaviors is blocked on every write route.
-- File access is confined to the active world's managed assets and always excludes its manifest,
-  databases, and packs.
+- Commands are typed and validated on both sides of the connection. Macro execution and regions
+  that trigger macros are disabled by default and require the GM to enable dedicated commands.
+  Region behaviors that execute script code are blocked on every write route.
+- File commands read assets within Foundry's managed `data` source. Writes are limited to the
+  active world's asset folders and always exclude its manifest, databases, and packs.
+
+[Security](docs/security.md) explains these safeguards and their limits.
 
 ## Foundry compatibility
 
-Supported on Foundry VTT v13 and v14 (both verified). Version-dependent behavior is
-capability-gated and reported per command; [Compatibility](docs/compatibility.md) lists the
-differences that matter to operators.
+Supported and verified on Foundry VTT v13 and v14. Some commands are available only on certain
+Foundry versions. See [Compatibility](docs/compatibility.md) for the differences.
 
 ## Documentation
 
-[docs/README.md](docs/README.md) maps the full set: commands, protocol, security, architecture,
-compatibility, and the agent skill. The same documents ship inside the package and are printed by
-`fvtt-world-cli docs [document]`, so the installed CLI is self-describing offline.
+The [documentation index](docs/README.md) links to the command reference, setup guides, security,
+compatibility, and technical documentation. These documents also ship with the CLI. Read them
+offline with `fvtt-world-cli docs [document]`.
 
 Bug reports and questions go to [GitHub Issues](https://github.com/DroiD16/fvtt-world-cli/issues).

package/dist/index.js

@@ -10,7 +10,7 @@ import { readFileSync as readFileSync2 } from "node:fs";
 import { createHash as createHash2, randomBytes as randomBytes2, randomUUID as randomUUID2, timingSafeEqual } from "node:crypto";
 
 // ../protocol/src/constants.js
-var PROTOCOL_VERSION = "1.1.1";
+var PROTOCOL_VERSION = "1.1.2";
 var PROTOCOL_COMPONENTS = Object.freeze({
   MODULE: "module",
   CLI_DAEMON: "cli-daemon",
@@ -228,7 +228,8 @@ var ERROR_CODES = Object.freeze({
   APPROVAL_TIMEOUT: "APPROVAL_TIMEOUT",
   APPROVAL_CANCELLED: "APPROVAL_CANCELLED",
   APPROVAL_QUEUE_FULL: "APPROVAL_QUEUE_FULL",
-  APPROVAL_UNKNOWN: "APPROVAL_UNKNOWN"
+  APPROVAL_UNKNOWN: "APPROVAL_UNKNOWN",
+  APPROVAL_STALE: "APPROVAL_STALE"
 });
 
 // ../protocol/src/schemas/shared.js

package/docs/README.md

@@ -1,71 +1,15 @@
 # Documentation
 
-The canonical command is `fvtt-world-cli`. The shorter `worldctl` executable is an equivalent bin
-entry for the same CLI and may be used in interactive workflows.
-
-fvtt-world-cli exposes a local, authenticated command line for inspecting and changing a live
-Foundry world through Foundry's own APIs.
-
-Authorization uses one-time pairing; the first-run flow is covered in
-[Getting started](getting-started.md). Config defaults are `$XDG_CONFIG_HOME/fvtt-world-cli`
-or `~/.config/fvtt-world-cli` on Linux, `~/Library/Application Support/fvtt-world-cli` on macOS, and
-`%APPDATA%\\fvtt-world-cli` on Windows.
-
-## Choose a route
-
-If you are operating the CLI yourself, start with [Commands](commands.md). It explains what the tool
-can do, groups related operations by task, and links to the detailed contracts that matter for each
-workflow.
-
-If an AI agent or another program is operating the CLI, install the packaged agent skill into the
-agent with `fvtt-world-cli skill install`. The skill carries the operating workflow and defers
-command specifics to the CLI's own discovery surface, so agents never rely on a copied command
-inventory in prose; [Agent skill](skill.md) explains why it exists and how it is kept current.
-
-## Documentation map
+Choose a guide for the task at hand. Examples use `fvtt-world-cli`; `worldctl` is an equivalent
+short alias. These guides also ship with the CLI, available through `fvtt-world-cli docs [document]`.
 
 | Document | Audience | Purpose |
 |---|---|---|
-| [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 |
+| [Getting started](getting-started.md) | People | Installation, pairing, updates, and troubleshooting |
+| [Commands](commands.md) | People | Commands, workflows, access management, and local configuration |
+| [Agent skill](skill.md) | Agent operators | Installing, updating, and removing the packaged skill |
 | [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 |
 | [Changelog](../CHANGELOG.md) | Users and contributors | Versioned history of user-visible changes |
-
-## Finding exact command syntax
-
-The running CLI is the authoritative reference for the installed version:
-
-```bash
-fvtt-world-cli commands
-fvtt-world-cli commands --json
-fvtt-world-cli schema actor.update
-fvtt-world-cli actor update --help
-fvtt-world-cli docs protocol
-```
-
-`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.
-
-## Sources of truth
-
-Documentation explains the public behavior but does not duplicate exhaustive machine-readable
-inventories.
-
-- Command names, mutation classification, and request schemas, per family:
-  [`packages/protocol/src/schemas/`](../packages/protocol/src/schemas/), assembled into the registry
-  by [`packages/protocol/src/commands.js`](../packages/protocol/src/commands.js)
-- Shared constants and stable error codes:
-  [`packages/protocol/src/constants.js`](../packages/protocol/src/constants.js)
-- Global flags, the JSON output contract printed in `--help`, and program assembly:
-  [`packages/cli/src/program.ts`](../packages/cli/src/program.ts)
-- Per-command flags and command registration, per group:
-  [`packages/cli/src/commands/`](../packages/cli/src/commands/)
-- Human-readable rendering of command results, per family:
-  [`packages/cli/src/render/`](../packages/cli/src/render/)
-- Foundry-side behavior: [`packages/foundry-module/scripts/`](../packages/foundry-module/scripts/)
-- Live coverage: [`scripts/live-smoke.mjs`](../scripts/live-smoke.mjs)

package/docs/architecture.md

@@ -1,248 +1,92 @@
 # Architecture
 
-fvtt-world-cli is a monorepo containing a command-line client, a local daemon, a shared protocol,
-and a Foundry module. The components share contracts but have distinct runtime responsibilities.
+The `fvtt-world-cli` monorepo contains a CLI, a local daemon, a shared protocol, and a Foundry
+module. Keeping them together lets their contracts change in one release.
 
 ## Runtime roles
 
-### CLI
+| Component | Owns |
+|---|---|
+| `packages/cli` | Command parsing, local configuration and validation, transport, discovery, and output |
+| Daemon, within `packages/cli` | Loopback listener, authentication, pairings, the active bridge, request routing, timeouts, and idempotency coordination |
+| `packages/protocol` | Command registry, request and transport schemas, mutation classification, error codes, and shared constants |
+| `packages/foundry-module` | GM checks, command permissions and approval, document validation, capability adapters, execution, serialization, and write confirmation |
 
-`packages/cli` owns:
-
-- command parsing and help;
-- local configuration;
-- local request-schema validation;
-- WebSocket client transport;
-- JSON and human-readable output;
-- local discovery commands;
-- reading explicitly supplied operator files for upload or macro input.
-
-The CLI does not load Foundry or mutate world storage. It converts CLI flags into typed protocol
-requests and presents structured responses.
-
-### Daemon
-
-The daemon runs as part of the CLI package and owns:
-
-- the loopback WebSocket listener;
-- device-local client authentication and the persistent pairing registry;
-- the single active bridge session;
-- request correlation and forwarding;
-- forward timeouts and heartbeat state;
-- transport size limits;
-- runtime idempotency coordination and caching.
-
-The daemon does not interpret Foundry document payloads or provide world access without an active
-authenticated bridge.
-
-### Protocol package
-
-`packages/protocol` owns:
-
-- protocol and message constants;
-- command names and mutation classification;
-- request schemas;
-- stable error codes;
-- shared limits and enums;
-- envelope validation.
-
-The protocol registry is the source for runtime command discovery. Exhaustive command inventories are
-not copied into documentation.
-
-### Foundry module
-
-`packages/foundry-module` runs inside the logged-in Foundry GM client and owns:
-
-- 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;
-- mutation preparation and dry-run previews;
-- execution through Foundry Document APIs and reviewed typed actions;
-- 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.
+The daemon routes requests without interpreting Foundry document payloads. The module ships
+browser-compatible JavaScript with a generated mirror of the protocol package.
 
 ## Core assumption
 
 An authenticated GM client is open in the target world. The bridge acts through that client's
-Foundry runtime and authority. It is not a headless database editor and does not bypass Foundry's
-document lifecycle, validation, permissions, hooks, or installed system/module behavior.
+runtime and authority, using Foundry's document lifecycle, permissions, validation, and hooks.
+Installed systems and modules remain part of the execution environment.
 
 ## Request flow
 
 ```text
 CLI invocation
   -> parse flags and validate request schema
-  -> connect and authenticate to local daemon
-  -> correlate and forward to active bridge
+  -> authenticate to local daemon
+  -> forward to the active bridge
   -> validate, authorize, sanitize, and capability-check
-  -> resolve Foundry documents
   -> prepare preview or execute through a Foundry API
-  -> serialize observed result or structured error
-  -> relay response by request ID
-  -> render JSON or human output
+  -> confirm and serialize the result, or return a structured error
+  -> relay by request ID and render output
 ```
 
-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 bridge advertises its commands during the handshake. The daemon forwards only advertised
+commands. A command that requires GM approval waits before execution and passes through the
+guards again after approval. The protocol registry supplies every command's default permission.
 
-The CLI validation pass provides fast feedback and avoids unnecessary connections. The bridge repeats
-validation because the transport input remains untrusted and because Foundry-side capability and
-document validation require the live runtime.
+## Validation and command design
 
-Closed protocol schemas define the complete accepted top-level field set for document families owned
-by the bridge. Open schemas preserve system/module extensibility but pass through shared sanitization
-before validation, diffing, preview, or dispatch.
+CLI validation gives early feedback. The bridge repeats it because transport input is untrusted
+and only the live runtime can check Foundry capabilities and document state.
 
-Foundry DataModels remain the final authority for system-specific and version-specific values.
+Closed schemas enumerate writable fields. Open schemas allow system and module data but use
+shared sanitization before validation, preview, or execution. Foundry DataModels validate the
+system-specific and version-specific values.
 
-## Command architecture
-
-Commands are explicit typed handlers rather than a generic RPC. Related document families share
-preparation, guard, serialization, and bulk seams so their behavior does not diverge between create,
-update, clone, dry-run, and bulk routes.
-
-CRUD handlers operate through document methods. Action handlers call a fixed reviewed Foundry method
-and report only the result that can be observed or confirmed. Command-specific behavior is discovered
-from the registry and CLI schema surface.
+Each command has an explicit schema and handler. Document handlers call Foundry document methods;
+action handlers call a fixed, reviewed Foundry method. Related operations reuse preparation,
+guards, serialization, and bulk helpers so a preview or bulk write cannot bypass a single
+command's restrictions.
 
 ## Mutation model
 
-Mutations are serialized where family behavior requires ordering, but the bridge does not claim a
-global transaction. The Foundry UI, systems, modules, and other clients remain concurrent writers.
-
-A dry run performs the same preparation and guards as a real command, then stops before persistence.
-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 dry run performs the same preparation and guards as a real command, then stops before
+persistence. It reserves no state. The Foundry UI, systems, modules, and other clients remain
+concurrent writers, and bulk calls are not transactions.
 
-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.
+Write handlers confirm stored state before reporting success, since Foundry can veto or modify a
+request without throwing. A valid no-op succeeds; a partial or unprovable write returns an error.
+[Write confirmation](protocol.md#write-confirmation) defines how the original request is preserved
+and compared with the result.
 
 ## Serialization
 
-Readers serialize authored source state from Foundry document sources. Derived runtime values are
-included only through explicit projections and are identified as derived.
-
-List rows are lean discovery projections. Single-document reads expose richer authored projections.
-This keeps large collections bounded while allowing callers to inspect a target before mutation.
-
-Result shapes are intentionally narrower than arbitrary Foundry document models. Extensible writes
-can therefore accept valid system/module data that a curated read does not echo field-for-field.
-
-## Managed files
+Reads return authored state from Foundry document sources. Derived runtime values require explicit
+projections and are identified as derived. Lists use smaller projections than single-document
+reads to keep collection responses bounded.
 
-File commands use Foundry's public managed-file APIs. Reads address the managed `data` source. Writes
-are contained to the active world's allowed asset tree and exclude the world manifest, databases,
-and packs.
-
-The bridge receives upload bytes over the local transport; it never resolves an operator-machine
-absolute path. File mutations and document-reference mutations remain separate explicit commands.
-
-See [Security](security.md#file-write-boundary) for the full boundary.
+Results expose selected fields, so an extensible write may accept system or module data that a
+read does not echo field-for-field.
 
 ## Session lifecycle
 
-The first bridge connection attempt occurs after Foundry is ready. Authentication or protocol
-rejection is terminal for that module load so a persistent configuration problem does not create a
-reconnect loop. A session that completed the handshake and later loses transport reconnects with
-bounded exponential backoff.
-
-The daemon persists multiple pairing profiles but routes through one active bridge. A profile is owned
-by one browser: its uniqueness key is Origin, world, GM, and the browser's own persistent client
-identifier, which is why the same person can keep two browsers paired to one world and GM and why
-re-pairing rotates only the re-pairing browser's credential. Making the browser the unit of ownership
-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, 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.
-
-While serving, the daemon owns authentication and connection configuration writes, and preserves a
-concurrently changed upload limit until a restart applies it to the transport. Daemon control
-operations for pairing, profiles, release, and client credential rotation form the future Companion
-boundary and remain separate from the Foundry command registry.
-
-One of those operations parks instead of answering at once: the wait for a pairing request holds its
-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
-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
-stated in [Security](security.md#authentication).
-
-### Client-side status signal
-
-The module's own UI needs to react to connection changes rather than read state once, so the bridge
-client publishes every status transition instead of assigning the field silently. The Foundry module
-re-emits those transitions as the `fvtt-world-cli.statusChanged` hook, which makes the same signal
-available to macros and other modules in the GM client. It is a client-side extension point only and
-carries no wire-protocol meaning; the daemon and the CLI neither send nor observe it.
-
-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`,
-`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.
-
-Credential changes are not transitions of this hook. Pairing and unpairing refresh the module's own
-windows and toolbar indicator through an internal signal, since the connection state itself has not
-changed at that moment.
+The daemon routes commands through one active GM browser, which determines their world and
+permissions. Pairing and connection management use separate daemon controls so they remain
+available without that browser.
+
+The browser owns command approvals; the daemon owns request routing and idempotency coordination.
+Both keep temporary state. [Protocol](protocol.md#bridge-sessions) defines ownership, reconnects,
+and failure handling, plus the module's [local status hook](protocol.md#client-side-status-signal).
 
 ## Compatibility strategy
 
-The bridge supports the designated Foundry major versions through narrow capability adapters and
-explicit guards. It refuses a version-dependent request when it cannot provide the documented result
-honestly.
+Narrow adapters handle differences between supported Foundry versions. Unsupported operations
+return `UNSUPPORTED_OPERATION`. The CLI, daemon, and module must share the same release version.
 
-Mocks verify contracts and edge cases but cannot establish real Foundry compatibility. The live smoke
-workflow is the authority for executed coverage. Current operator-visible differences are summarized
-in [Foundry compatibility](compatibility.md).
+Mocks check contracts and edge cases. Only the [live smoke workflow](../scripts/live-smoke.mjs)
+establishes which operations were exercised against Foundry. See
+[Foundry compatibility](compatibility.md) for differences users need to act on.