fvtt-world-cli 1.0.0

package/docs/README.md

@@ -0,0 +1,71 @@
+# 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
+
+| 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 |
+| [Protocol](protocol.md) | Implementers and automation consumers | Transport, session, delivery, and error semantics — the integration contract |
+| [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 command registry 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

@@ -0,0 +1,216 @@
+# 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.
+
+## Runtime roles
+
+### CLI
+
+`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;
+- 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 module ships plain browser-compatible JavaScript. Its generated protocol mirror is produced from
+the canonical 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.
+
+## Request flow
+
+```text
+CLI invocation
+  -> parse flags and validate request schema
+  -> connect and authenticate to local daemon
+  -> correlate and forward to 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
+```
+
+The bridge advertises its supported commands during the handshake. The daemon forwards only commands
+advertised by the active session.
+
+## Validation boundaries
+
+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.
+
+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.
+
+Foundry DataModels remain the final authority for 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.
+
+## 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.
+
+Idempotency keys reduce duplicate effects across response loss while the relevant daemon/bridge cache
+entry exists. They do not create durable distributed transactions.
+
+## 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
+
+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.
+
+## 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; 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
+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
+wait into one.
+
+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`, 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.
+`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.
+
+## 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.
+
+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).

package/docs/commands.md

@@ -0,0 +1,367 @@
+# Commands
+
+This is the human-readable overview of the `fvtt-world-cli` command surface. The `worldctl` executable
+is an equivalent short alias. This guide uses the canonical name. It explains shared behavior
+and helps you find the relevant command family. For exact syntax in the installed version, use the
+CLI's discovery commands.
+
+```bash
+fvtt-world-cli commands
+fvtt-world-cli schema <protocol-command>
+fvtt-world-cli <command path> --help
+fvtt-world-cli docs [document]
+```
+
+For example, `fvtt-world-cli schema actor.update` shows the protocol request schema while
+`fvtt-world-cli actor update --help` shows its CLI flags. `docs` lists and prints the documentation
+shipped with the installed CLI, this guide included. Agents operate through the packaged agent
+skill, managed with the `fvtt-world-cli skill install`, `skill update`, and `skill remove`
+commands; [Agent skill](skill.md) covers the whole lifecycle.
+
+## Before you begin
+
+Start the local daemon and keep an authenticated GM client open in the target Foundry world:
+
+```bash
+fvtt-world-cli bridge serve
+```
+
+On first run, that GM client is paired once. With the daemon running, Foundry's Module Settings →
+Authorization carries a Pair button, and one command in the terminal covers the rest: it waits for
+the request, prints the Origin, world, GM, and browser label it carries, and asks for a yes or no.
+
+```bash
+fvtt-world-cli auth
+```
+
+The wait can be started before or after Pair is clicked: a request that is already pending surfaces
+immediately. Reading a request over before deciding, or approving from a script, is the two-step path
+instead, where non-interactive approval requires `--yes`:
+
+```bash
+fvtt-world-cli auth pending
+fvtt-world-cli auth approve [code]
+```
+
+The full first-run walkthrough is in [Getting started](getting-started.md).
+
+Confirm the connection before reading or writing:
+
+```bash
+fvtt-world-cli system info --json
+```
+
+Profiles can be inspected with `auth list`, revoked independently or pruned once they fall idle, and
+the active slot can be cleared with `bridge release`. The daemon never prints a secret.
+
+### Authorization commands
+
+- `auth` with no subcommand waits for a pairing request and approves it on the spot. It prints an
+  instruction to click Pair in the module's Authorization window, and the request surfaces in the
+  terminal as soon as the daemon receives it, including one that was already pending when the command
+  started. Several live requests are not an obstacle to it as they are to `auth approve` with no code:
+  the wait renders the earliest one and asks about that, and a later request stays pending for another
+  run. The wait itself is indefinite: it ends on Ctrl+C, on an answer, or if the daemon connection
+  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.
+  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.
+- `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.
+- `auth approve [code] [--yes]` approves one request. The code may be omitted only when exactly one
+  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.
+- `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
+  a browser that needs a different label unpairs and pairs again. A browser that only forgot its local
+  credential keeps its record, and the next approval adopts the label that request carried. Labels are
+  not unique, so two browsers may share one. A profile's `lastSeenAt` is stamped when it is approved,
+  when its browser connects the bridge, when that connection ends, and when a hello is turned away
+  because another profile owns the slot, so the timestamp measures how long the profile has been idle
+  rather than how long ago it last connected. A second browser that is opened daily while the first
+  one holds the bridge therefore stays fresh and is never pruned out from under its owner.
+- `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
+  `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,
+  against the cutoff as it stands when the command runs, and its own result is what the command prints.
+  The executed set can therefore be larger than the one the prompt counted, because a profile that
+  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 —
+  `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
+  output, and without it the command stops with exit 2.
+- `auth revoke <pairingId>` deletes one daemon profile and disconnects it if active.
+- `auth rotate-client --yes` replaces the device-local CLI/Companion credential and closes existing
+  local-client sockets without invalidating browser pairings.
+- `bridge release` clears the active slot or abnormal-disconnect lease without deleting a profile.
+  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.
+
+In Foundry, Connect reuses the stored browser credential and Disconnect releases the slot without
+touching it. Unpair waits for confirmed daemon revocation
+before deleting that credential. If revocation cannot be confirmed, it retains the credential and
+offers Forget local as the explicit recovery path; Forget local does not revoke the daemon profile.
+`BRIDGE_BUSY` likewise preserves the credential: release the current bridge and choose Connect.
+
+### Local configuration
+
+- `config get` shows the config path and non-secret settings.
+- `config set-upload-limit <size>` persists the raw upload-byte limit. The daemon preserves this
+  field across later pairing and bridge-session writes, but a running daemon must be restarted before
+  its WebSocket transport and the browser bridge advertise the new limit. JSON output includes
+  `daemonRestartRequired: true`.
+
+## Finding the right command
+
+Command names describe the document nesting. Dots are used in the protocol registry; spaces are used
+on the CLI:
+
+| Goal | Protocol family | CLI shape |
+|---|---|---|
+| World actors | `actor.*` | `fvtt-world-cli actor …` |
+| Items embedded in an actor | `actor.item.*` | `fvtt-world-cli actor item …` |
+| Effects on an actor item | `actor.item.effect.*` | `fvtt-world-cli actor item effect …` |
+| 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
+varies by family, so a nearby document family is not a reliable guide to what another one supports.
+
+## Capability map
+
+### World content
+
+- `actor`, `item`, `journal`, `scene`, `macro`, `playlist`, `table`, and `cards` manage world
+  documents.
+- `chat` reads, creates, and deletes chat messages.
+- `combat` manages encounters and exposes explicit encounter transitions.
+- `folder` manages document organization.
+- Dedicated `*.ownership.set` commands change supported document ownership.
+
+Common world-document operations include `list`, `get`, `get-many`, `create`, `update`, `clone`, and
+`delete`. The exact set varies by family.
+
+### Embedded content
+
+- `actor.item` manages an actor's embedded items.
+- `*.effect` families manage ActiveEffects on actors, items, actor items, tokens, and token items.
+- `journal.category` manages journal page categories.
+- `playlist.sound` manages playlist tracks.
+- `table.result` manages roll-table rows.
+- `cards.card` manages cards inside a stack.
+- `combat.combatant` and `combat.group` manage encounter membership.
+- `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)).
+
+Embedded commands require the complete parent ID chain; a read of the parent supplies those IDs when
+they are not already known.
+
+### Actions
+
+Some commands invoke a typed Foundry action instead of ordinary CRUD:
+
+- playlist and playlist-sound playback;
+- roll-table draw and reset;
+- card shuffle, reset, deal, draw, and pass;
+- combat start, activation, advancement, and initiative;
+- scene thumbnail generation and fog reset.
+
+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
+reading before automating it.
+
+### Discovery and maintenance
+
+- `world.search` finds content across supported world and optional compendium indexes.
+- `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.
+
+### Managed files
+
+`file` commands operate on Foundry's managed `data` source. Reads can inspect managed assets. Writes
+are restricted to the active world's allowed tree and exclude its manifest, databases, and packs.
+Document references are updated separately with an explicit document command.
+
+See [Security](security.md#file-write-boundary) before automating file writes.
+
+## Shared command behavior
+
+### JSON output
+
+Use `--json` for automation. Successful requests use a stable envelope:
+
+```json
+{
+  "protocolVersion": "…",
+  "type": "command.response",
+  "id": "…",
+  "ok": true,
+  "result": {
+    "actor": {}
+  }
+}
+```
+
+Documents are stored under a type-named result key such as `actor`, `items`, `scene`, or `outcomes`.
+The key varies between commands but is stable for each one, so a first response shows what to script
+against. Errors use `ok: false`, a stable code, a
+message, and optional details; see [Protocol](protocol.md#error-model).
+
+Serialized Foundry documents generally expose `id` as the public identifier and may also expose the
+source `_id` mirror. Use the documented `id` fields for subsequent commands.
+
+### Input validation
+
+Input is validated locally and again at the Foundry boundary. Unknown options, missing required
+options, and malformed CLI values are usage errors. Protocol payloads use closed schemas where the
+bridge owns the writable field set and sanitized open schemas where Foundry or a game system owns
+extensible data.
+
+Use JSON flags such as `--data-json`, `--patch-json`, and family-specific JSON flags for structured
+values. The command schema is the definitive description of accepted keys.
+
+### Lists, filters, and pagination
+
+List-like commands that support pagination accept `limit` and `offset` and return collection data
+plus `total` and `hasMore`. One response is not guaranteed to contain the entire collection; paging
+continues until `hasMore` is false.
+
+Some collections support a case-insensitive `name` filter before pagination. Search commands use
+their own matching rules and are not interchangeable with a list filter. Whether a filter exists is
+recorded in each command's schema.
+
+### Reads and projections
+
+Single-document `get` operations return the documented authored projection. Some commands accept
+`include` values for derived or expensive data. Derived data is explicitly identified and can vary by
+Foundry version and game system.
+
+List rows are intentionally smaller than `get` results and are not sufficient to construct an update
+from; that starts from a fresh `get`.
+
+### Updates and merge semantics
+
+Updates are patches, not full replacements:
+
+- nested objects merge recursively;
+- ordinary arrays replace as a whole;
+- dotted paths target a nested leaf where the schema permits them;
+- Foundry deletion syntax can remove permitted nested keys;
+- embedded-document collections follow their family-specific Foundry semantics.
+
+Arrays and extensible system data are the easiest fields to clobber: an array patch replaces the
+whole array, so one built from stale state silently drops entries. A fresh read before editing, the
+smallest patch that expresses the change, and a read-back afterwards avoid that.
+
+### Dry run
+
+All mutation commands accept the global `--dry-run` flag:
+
+```bash
+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).
+
+### Idempotency and retries
+
+Commands with duplicate-creation or non-repeatable-action risk may require or accept an idempotency
+key. An operation that timed out or disconnected may already have reached Foundry, so a blind retry
+can apply it twice. Key semantics and delivery-state retry rules are defined in
+[Protocol](protocol.md#idempotency) and
+[Protocol](protocol.md#delivery-states-and-retries).
+
+### Batch reads and bulk writes
+
+`get-many` reduces round trips for independent reads. `exec --stdin` sends NDJSON commands over one
+connection while retaining an individual response for each request.
+
+Families that expose `create-many`, `update-many`, or `delete-many` validate the envelope and each
+element before dispatch, but the persistence layer is not transactional. Inspect `complete` and every
+entry in `outcomes`; see [Protocol](protocol.md#batch-requests-and-bulk-writes).
+
+### File paths
+
+Pass literal managed-data paths. The bridge normalizes and encodes document asset references where
+appropriate; callers should not pre-encode ordinary filename characters. URLs, virtual texture IDs,
+and other special values follow the receiving field's schema.
+
+## Common workflows
+
+### Find, inspect, update, verify
+
+```bash
+fvtt-world-cli actor list --name "Goblin" --json
+fvtt-world-cli actor get --actor-id <id> --json
+fvtt-world-cli --dry-run actor update --actor-id <id> --name "Goblin Scout" --json
+fvtt-world-cli actor update --actor-id <id> --name "Goblin Scout" --json
+fvtt-world-cli actor get --actor-id <id> --json
+```
+
+### Discover an unfamiliar command
+
+```bash
+fvtt-world-cli commands --json
+fvtt-world-cli schema scene.token.create
+fvtt-world-cli scene token create --help
+```
+
+### Work with an embedded document
+
+```bash
+fvtt-world-cli scene token list --scene-id <sceneId> --json
+fvtt-world-cli scene token get --scene-id <sceneId> --token-id <tokenId> --json
+```
+
+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.