fvtt-world-cli 1.0.0

package/docs/compatibility.md

@@ -0,0 +1,26 @@
+# Foundry compatibility
+
+The bridge supports Foundry VTT v13 and v14. It capability-checks behavior whose availability or
+semantics differ by version and returns a structured error when it cannot provide the documented
+result honestly.
+
+## Operator contract
+
+- `fvtt-world-cli system info --json` reports the connected Foundry, system, module, limits, and
+  advertised command set.
+- `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.
+
+## Known differences
+
+| Area | v13 | v14 | CLI behavior |
+|---|---|---|---|
+| Measured templates | Available | Removed from core | Template commands are capability-gated |
+| Scene thumbnail rendering | Whole-scene behavior | Initial-level behavior | Reports the dimensions and stored path actually produced |
+| Scene thumbnail files | Stable scene-based filename | Content-derived filenames | Consumers use the returned path; cleanup policy differs |
+| 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 |
+
+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

@@ -0,0 +1,104 @@
+# Getting started
+
+This walkthrough covers the first run in detail: starting the daemon, pairing a Foundry GM client,
+and confirming the bridge, with what to expect at each step and what to do when something deviates.
+
+## 1. Start the daemon
+
+```bash
+fvtt-world-cli bridge serve
+```
+
+The daemon is the meeting point of the other two parts: the Foundry module connects to it, the CLI
+sends commands to it, and it routes each command into the GM session. It listens on
+`ws://127.0.0.1:47833` unless overridden and stays running in the foreground for as long as the
+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
+reload.
+
+## 2. Pair the Foundry GM client
+
+Pairing is how a browser gets its own permission to talk to the daemon; it happens once per
+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
+
+The same windows are also reachable through Configure Settings → Module Settings:
+
+![The module settings](images/module-settings.png)
+
+The module finds the daemon through its `Daemon URL` setting. By default it already points where
+the daemon listens, so there is nothing to configure; the setting exists for running the daemon on
+a custom port or address, and then it has to match the URL that `bridge serve` prints at startup.
+
+The `Browser label` field in the Authorization window is how this browser will be named in approval
+prompts and in `auth list`. It is editable until pairing; after pairing it is fixed, and changing
+it takes an Unpair followed by a new Pair. Each browser also carries its own permanent client
+identifier, so several browsers stay paired side by side and a re-pair replaces only that browser's
+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
+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
+`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:
+
+```bash
+fvtt-world-cli auth pending
+fvtt-world-cli auth approve <code>   # add --yes in a script to skip the confirmation
+```
+
+## 3. Confirm the bridge
+
+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.
+
+A first command confirms the connection end to end:
+
+```bash
+fvtt-world-cli system info --json
+```
+
+It reports `bridge.status` as `connected`.
+
+## When something deviates
+
+The Bridge status window (in the scene controls or the module settings) is the first place to
+look: it names the connection state in the same colours as the icon and shows the daemon URL, the
+last connection time, the reconnect attempts, and the reason behind a stop, updating itself while
+open.
+
+Two buttons cover recovery. Connect builds a fresh bridge client, which is also what clears a stop
+such as `BRIDGE_BUSY` or `DAEMON_UNAVAILABLE`, and during a reconnect wait it retries immediately
+instead of waiting out the backoff delay. Disconnect abandons the connection and tells the daemon
+goodbye, so the daemon frees its active bridge slot right away instead of waiting out an
+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.
+
+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
+reached: it clears only the browser's side, and the daemon's record stays active until
+`auth revoke <pairingId>` succeeds.

package/docs/images/icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" fill="#0b0a13"/>
+  <g fill="none" stroke="#fc6119" stroke-linecap="round" stroke-linejoin="round">
+    <g stroke-width="15">
+      <path d="M256 36 446.53 146V366L256 476 65.47 366V146Z"/>
+      <path d="M256 120 373.78 324H138.22Z"/>
+      <path d="M256 36 256 120M446.53 146 256 120M65.47 146 256 120"/>
+      <path d="M446.53 366 373.78 324M446.53 146 373.78 324M256 476 373.78 324"/>
+      <path d="M65.47 366 138.22 324M65.47 146 138.22 324M256 476 138.22 324"/>
+    </g>
+    <g stroke-width="12">
+      <path d="M223 240 251 268 223 296"/>
+      <path d="M266 296H306" stroke-linecap="butt"/>
+    </g>
+  </g>
+</svg>

package/docs/images/mark.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <g fill="none" stroke="#fc6119" stroke-linecap="round" stroke-linejoin="round">
+    <g stroke-width="15">
+      <path d="M256 36 446.53 146V366L256 476 65.47 366V146Z"/>
+      <path d="M256 120 373.78 324H138.22Z"/>
+      <path d="M256 36 256 120M446.53 146 256 120M65.47 146 256 120"/>
+      <path d="M446.53 366 373.78 324M446.53 146 373.78 324M256 476 373.78 324"/>
+      <path d="M65.47 366 138.22 324M65.47 146 138.22 324M256 476 138.22 324"/>
+    </g>
+    <g stroke-width="12">
+      <path d="M223 240 251 268 223 296"/>
+      <path d="M266 296H306" stroke-linecap="butt"/>
+    </g>
+  </g>
+</svg>

package/docs/protocol.md

@@ -0,0 +1,238 @@
+# Protocol
+
+This document describes the stable integration contract between CLI clients, the local daemon, and
+the Foundry bridge: what each party may assume, which guarantees survive reconnects and failures,
+and how errors and retries are classified. It deliberately contains no wire-level inventory. Exact
+message types, frame schemas, command names, request schemas, error codes, default timeouts, and
+size limits are defined by the protocol package and discoverable at runtime:
+
+- [`packages/protocol/src/commands.js`](../packages/protocol/src/commands.js)
+- [`packages/protocol/src/schemas/`](../packages/protocol/src/schemas/)
+- [`packages/protocol/src/constants.js`](../packages/protocol/src/constants.js)
+- [`packages/protocol/src/validation.js`](../packages/protocol/src/validation.js)
+- `fvtt-world-cli commands --json`, `fvtt-world-cli schema <command>`, and
+  `fvtt-world-cli system info --json` for the installed checkout and the connected 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.
+
+## 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
+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;
+they cannot assume the local-client role.
+
+Every message type has a closed top-level schema. A malformed message yields a structured
+`INVALID_MESSAGE` error where a response is possible, and an authenticated local client that sends
+a malformed control request receives a correlated error and may keep using its connection.
+
+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 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
+  own, and resuming is an explicit operator action.
+
+## Size limits
+
+The upload limit and the transport frame limit are distinct: the first bounds raw upload content,
+the second accounts for encoding and envelope overhead and is never lower than what legitimate
+large read responses require. The daemon advertises its effective limits during the handshake, and
+the bridge checks response size before sending, so an oversized response returns
+`PAYLOAD_TOO_LARGE` instead of destroying the shared session. A persisted upload-limit change is
+applied to the transport only after the daemon restarts.
+
+## Pairing
+
+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;
+- 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.
+
+### Client identity
+
+The pairing request carries a `client` object inside its identity: `id` is the browser's persistent
+client identifier, and `label` is a human name for that browser. Pairing records are unique per
+(Origin, world, user, client id), so two browsers signed in as the same GM on the same world hold two
+independent records and neither re-pair disturbs the other.
+
+- `id` is bounded to hexadecimal characters and dashes, 8 to 64 characters long.
+- `label` is 1 to 64 characters of Unicode text. Whitespace-only values are rejected, as are control
+  (C0/C1), zero-width, bidirectional-override, and Unicode tag characters. The schema is the
+  enforcement point because any local process can send a pairing request and the label is later
+  printed by `auth list` and `auth pending`.
+- Labels are not unique. Duplicate labels are accepted as they arrive, without suffixing.
+- A label is chosen once, in the browser, at pairing time. No control operation renames a stored
+  record; re-pairing is the way to change a label.
+
+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
+it, and the browser keeps a copy only to display it.
+
+## Daemon control
+
+Authenticated local clients manage pairings and the active bridge through closed,
+operation-discriminated control requests; responses repeat both the correlation id and the
+operation. The operation registry lives in the protocol package. `auth.approve` takes only an
+optional pairing `code`; the approved record's label comes from the pairing request itself.
+
+`auth.await` is the long-poll behind the interactive pairing wait. It answers at once with the
+earliest live pending request, in the same public shape `auth.pending` serializes and with no
+credential material; when nothing is pending it parks the response until a request arrives, or until a
+bounded daemon-side cap elapses and the result carries no request. Every parked waiter is answered by
+the next arriving request, and a waiter is discarded when its client socket closes. The cap is the
+invariant that keeps a parked response inside the caller's own request timeout; `timeoutMs` may ask
+for a shorter park and is bounded by the cap, so no caller can park longer than the daemon allows.
+
+`auth.prune` deletes idle pairing records. Its optional `olderThanDays` is a non-negative integer and
+defaults to 30; a record is removed when its `lastSeenAt` is older than that many days before the
+call. `lastSeenAt` is stamped when a pairing is approved, when its browser passes the bridge hello,
+again when that bridge connection closes, and when a hello whose credential the daemon accepted is
+rejected with `BRIDGE_BUSY`, so the cutoff measures how long a record has been idle rather than how
+long ago it last connected. A hello rejected with `UNAUTHORIZED` proves nothing about the record and
+never stamps it. The pairing that owns the active bridge, and the holder of a live
+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`
+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.
+
+The active bridge itself may use
+exactly one control operation: revoking its own pairing. A browser Unpair deletes its stored
+credential only after a correlated successful revocation; on failure the credential is retained for
+retry, and discarding it locally is a separate deliberate action.
+
+## Bridge sessions
+
+After Foundry is ready, the module presents its pairing identity, client identifier, world, user,
+versions, and the command set it can execute; the daemon forwards only commands advertised by the
+active session.
+
+- Authentication or protocol-version rejection is terminal for that module load, so a persistent
+  configuration problem does not become a reconnect loop.
+- A session that completed its handshake and later loses transport reconnects with bounded
+  exponential backoff.
+- `BRIDGE_BUSY` is terminal for that client instance but preserves the stored credential; the
+  operator releases the current owner and retries explicitly rather than pairing again.
+- Only the exact active authenticated socket can release ownership with a goodbye.
+- A same-pairing takeover immediately completes requests owned by the displaced socket with an
+  indeterminate-delivery error: the operation may already have committed, so callers inspect world
+  state before retrying.
+- If the connected user loses GM authority, the bridge answers the pending command with a
+  correlated `PERMISSION_DENIED` without dispatching it, so the caller knows the rejected command
+  started no mutation.
+
+## Commands and correlation
+
+Commands are explicit typed names registered in the protocol package; there is no generic RPC
+method. A request carries a caller-chosen correlation id and schema-validated parameters, validated
+in the CLI before connecting and again in the bridge before dispatch. The command must be both
+registered and advertised by the active bridge. The response repeats the correlation id and is
+exclusive: success carries a result, failure carries a structured error.
+
+## Result conventions
+
+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.
+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
+has-more flag, and filters apply before pagination.
+
+## Dry run
+
+Mutation commands accept a dry-run request that passes through validation, resolution,
+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
+world can change between preview and commit.
+
+## Idempotency
+
+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.
+
+## Batch requests and bulk writes
+
+Connection reuse (`exec --stdin`) is a client mechanism: each request keeps its own correlation id
+and success state, and failures are reported per request. Bulk write commands are ordinary typed
+commands over bounded arrays: elements are prevalidated, but Foundry persistence is not
+transactional, so the result reports overall completeness plus a per-element outcome, and every
+outcome carries its own meaning.
+
+## Error model
+
+Errors have a stable code, a human-readable message, and optional structured details. The code and
+documented detail fields are the stable contract for branching; message text is not. The exhaustive
+code set is exported by the protocol package. The classes consumers act on:
+
+| Class | Representative codes | Consumer response |
+|---|---|---|
+| 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 |
+| Capability | `UNSUPPORTED_OPERATION` | Choose a supported workflow or runtime |
+| Size/resource | `PAYLOAD_TOO_LARGE`, `QUERY_TOO_BROAD` | Reduce or page the request |
+| Bridge state | `BRIDGE_NOT_READY`, `BRIDGE_TIMEOUT`, `BRIDGE_DISCONNECTED` | Apply the delivery rules below |
+| 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.
+
+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.
+
+## Delivery states and retries
+
+Retry safety is a function of whether the request reached Foundry:
+
+| Condition | Forwarded to Foundry? | Retry meaning |
+|---|---:|---|
+| 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 |
+| 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
+details. Default waits, forward timeouts, heartbeats, and backoff bounds are defined in the
+protocol and CLI constants; runtime flags can override the client and daemon request timeouts.
+
+## Compatibility rules
+
+- Additive result and handshake fields are preferred for compatible evolution.
+- 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.
+
+Foundry-version behavior belongs in [Foundry compatibility](compatibility.md), while per-command
+request shape remains discoverable from the registry.

package/docs/security.md

@@ -0,0 +1,233 @@
+# Security
+
+fvtt-world-cli is a local administration tool. It gives an authenticated caller access to the
+authority of the connected Foundry GM client, within the typed command surface and explicit file
+boundary described here.
+
+## Trust boundary
+
+A request travels from the local CLI through the authenticated loopback daemon to the authenticated
+Foundry GM bridge, which executes it through Foundry's APIs. The CLI input is untrusted. The daemon
+authenticates and routes requests but does not grant Foundry permissions. The bridge validates
+requests again and executes them as the connected Foundry user.
+
+The design assumes a trusted local machine and a trusted GM-controlled Foundry session. It is not a
+public multi-tenant API.
+
+## Authentication
+
+- The daemon hard-rejects non-loopback listen hosts and validates the exact HTTP Host.
+- A random device-local credential authenticates CLI and future Companion clients with a first-message
+  `client.hello`; it is stored only in the per-user config file.
+- Every first frame and subsequent transport message is checked against a closed protocol schema
+  before role assignment or dispatch. Malformed first frames are closed immediately and cannot keep
+  an unauthenticated heartbeat connection alive.
+- Each browser/world/GM profile has an independent bridge credential. Only its SHA-256 digest is kept
+  by the daemon; the clear credential stays in client-scoped Foundry storage.
+- A pairing profile is identified by Origin, world, GM, and a per-browser client identifier that the
+  browser generates once and keeps in the same client-scoped storage as its credential. The identifier
+  is self-asserted and grants nothing: it only scopes which stored record a re-pair replaces, so one
+  browser re-pairing cannot rotate another browser's credential out from under it. Access remains
+  gated by human approval of the pairing code and by the credential-digest check on every hello, and a
+  hello whose client identifier does not match its pairing record is rejected as `UNAUTHORIZED`. That
+  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 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
+  `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.
+- The module removes those same characters from the label it collects in the Authorization window, and
+  also normalizes it to NFC, trims it, and caps its length, before the pairing request goes out. That
+  sanitizer is a usability layer, not the boundary: it keeps an honest browser from being refused over
+  a stray paste, while the schema check in the daemon remains the enforcement point, so a request from
+  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.
+- 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,
+  release, and revocation do not create a lease. Release uses a dedicated terminal close code so the
+  released browser cannot automatically reclaim the slot.
+- Only the exact active authenticated bridge socket can send `bridge.goodbye` or revoke its own
+  pairing. A socket is not assigned the bridge role or pairing identity until the complete handshake
+  has authenticated.
+- Browser Unpair deletes its clear credential only after a correlated successful revocation response.
+  On failure it retains the credential for retry; Forget local is a separate action that deliberately
+  leaves the daemon-side profile active.
+- Protocol-version or authentication rejection stops that bridge load until the Foundry client is
+  reloaded. `BRIDGE_BUSY` is reported separately, preserves the credential, and permits manual Retry
+  after the current owner is released.
+- A bridge that loses live GM authority returns correlated `PERMISSION_DENIED` before it closes and
+  does not route the denied command, preserving a determinate no-mutation outcome.
+
+Loopback reduces exposure but does not replace authentication. Other processes running as the same
+local user may be able to read local configuration or connect to local ports. The daemon accepts only
+the exact normalized Host authority configured for its listener; post-bind publication of a numeric
+runtime address does not broaden that authority or invalidate an explicitly configured `localhost`.
+
+## Command boundary
+
+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.
+
+Mutations use Foundry Document APIs or a reviewed typed Foundry action. Raw live world databases are
+outside the command surface.
+
+## Validation and protected metadata
+
+Closed document families enumerate writable fields. Open families allow Foundry-, system-, or
+module-defined data but pass every write and preview through shared protected-metadata sanitization.
+
+Document identity, statistics, authorship, and raw ownership are server-controlled. Ordinary content
+payloads cannot set them. Supported ownership changes use dedicated commands with GM and schema
+checks.
+
+Validation occurs in the CLI and again in the bridge. Foundry performs its own DataModel and
+permission validation before persistence.
+
+## Permissions and destructive actions
+
+The bridge requires a GM session for mutations. Delete commands can require explicit force where the
+document has high-risk references or consequences. A force flag acknowledges the command's defined
+guard; it does not bypass Foundry permissions, module hooks, validation, or filesystem containment.
+
+Foundry hooks can veto or partially apply writes. Mutation handlers confirm observable stored state
+where the command contract requires it and return structured partial or failed outcomes instead of
+claiming success.
+
+## Document ownership
+
+Ownership is access policy rather than ordinary document content. Raw `ownership` is excluded from
+normal create and update payloads. Dedicated `<family>.ownership.set` commands change the default or
+per-user level on supported families.
+
+Read projections expose ownership only where the public command contract intentionally includes it.
+Embedded documents often derive access from a parent and do not provide an independent ownership
+surface. What each family exposes is described by its own schema and result, not by another
+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.
+- 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.
+
+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
+universally. Operators must review system/module semantics when authoring content those extensions
+interpret.
+
+A typed Foundry action can also trigger existing GM-authored automation. Combat changes, table draws,
+card actions, document hooks, region triggers, and game-system workflows can cause secondary writes
+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.
+
+## Search
+
+`world.search` indexes selected authored world and optional compendium content in the connected GM
+client. Search results can reveal content visible to that GM, including text not visible to ordinary
+players.
+
+Queries and responses are bounded. Search indexes are runtime caches and can be stale until their
+invalidation or rebuild completes. Search is a discovery surface, not an authorization boundary.
+
+## File write boundary
+
+File commands operate only through Foundry's managed `data` source.
+
+Reads address normalized managed-data paths. Writes are restricted to the active world's
+`worlds/<worldId>/` tree and exclude:
+
+- `world.json`;
+- `data/` and all descendants;
+- `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.
+
+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
+local source file supplied by the operator, then sends its bytes as data.
+
+File mutation does not rewrite document references. Reference changes require an explicit document
+command so their intent and permissions remain visible.
+
+## Compendium imports
+
+Compendium commands are read-only with respect to packs. Supported import commands create a new world
+document from a pack entry using a closed, family-compatible override schema.
+
+Imports preserve legitimate authored source data after normalization. Installed system or module
+content can still carry data-driven behavior; importing is not a security audit of the source pack.
+The bridge does not expose arbitrary compendium writes.
+
+## Availability and resource limits
+
+The daemon and module bound uploads, WebSocket frames, search work, batch sizes, and selected result
+shapes. Oversized operations return structured errors where possible without dropping the shared
+bridge session.
+
+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.
+
+## Known risks
+
+- A stolen device credential lets a local process use the active bridge; a stolen bridge credential
+  lets a matching Origin/world/user runtime authenticate that pairing.
+- Another OS user able to reach loopback can submit a pairing request with a forged Origin, client
+  identifier, and label. Approval therefore trusts that the displayed pending request came from the
+  operator's own browser.
+- 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
+  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.
+- `auth approve` with no code refuses while several requests are pending, and the `auth` pairing wait
+  instead renders the earliest one and asks about it. A request a local process forged before the
+  operator clicked Pair in the browser is therefore the one the wait offers, which is a reason to read
+  the rendered identity rather than answer the prompt by reflex. Both commands approve only the request
+  whose identity they displayed.
+- A compromised GM browser session or installed Foundry module is already inside the trusted runtime.
+- Foundry, systems, and modules can attach hooks and side effects to otherwise ordinary writes.
+- Timeouts and disconnects can leave delivery indeterminate; a mutation may have committed.
+- 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.
+- Declarative content can reference existing executable or module-interpreted content.
+
+## Operator guidance
+
+- Keep the daemon on loopback, protect the per-user config, and review Origin/world/GM before approval.
+- Confirm the connected world and GM identity before mutation.
+- 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.
+- 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.