fvtt-world-cli 1.1.1 → 1.1.2

package/docs/compatibility.md

@@ -1,28 +1,19 @@
 # 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.
+The bridge supports Foundry VTT v13 and v14. Check your connected version with
+`fvtt-world-cli system info --json`.
 
-## Operator contract
-
-- `fvtt-world-cli system info --json` reports the connected Foundry, system, module, limits, and
-  discoverable command inventory.
-- `UNSUPPORTED_OPERATION` is a capability result, not a transient transport failure.
-- A dry run validates a proposed mutation; it does not forecast values that require execution.
+| Area | v13 | v14 | What to do |
+|---|---|---|---|
+| Measured templates | Available | Removed from core | Use `scene.template` commands on v13. They are unavailable on v14. |
+| Scene thumbnail rendering | Renders the scene | Renders the scene's initial level by default | On v14, expect the initial level in the thumbnail. Check the returned dimensions and image. |
+| Scene thumbnail files | Uses a stable scene-based filename | Uses a filename based on the image content | Use the returned path. On v14, a changed image can leave an older thumbnail file behind. |
+| User permission names | `TEMPLATE_CREATE` | `REGION_CREATE` | Use the permission keys reported by the connected Foundry version when calling `user.permissions.set`. |
 
-## Known differences
+Scene placeable fields and available region behavior types also differ. Read the target document
+before preparing a patch; valid data from one version is not automatically valid on the other.
 
-| 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 |
-| Scene activation | `Scene#activate` runs for any caller | `Scene#activate` throws for non-GM users | The bridge requires GM authority on both versions |
-| User permission names | `TEMPLATE_CREATE` | Renamed to `REGION_CREATE` | `user.permissions.set` validates keys against the connected version's live permission set rather than a fixed list |
+## When an operation is unavailable
 
-This table describes current operator-visible differences, not implementation evidence. Exact
-capabilities remain defined by the connected bridge and exercised by live smoke tests.
+`UNSUPPORTED_OPERATION` means the connected Foundry runtime cannot perform the requested operation.
+Repeating the same request will not fix it. Choose a supported operation or use a compatible runtime.

package/docs/getting-started.md

@@ -1,113 +1,115 @@
 # 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.
+## Before you begin
 
-## 1. Start the daemon
+You need Node.js 20 or newer, Foundry VTT v13 or v14, and a GM account in the target world.
+Install the CLI on the machine where you use your AI agent and GM browser. The Foundry server
+can be hosted elsewhere; the bridge runs in your browser.
+
+Install the CLI:
 
 ```bash
-fvtt-world-cli bridge serve
+npm install -g fvtt-world-cli
 ```
 
-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.
+In Foundry's *Install Module* dialog, paste this manifest URL:
 
-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.
+```
+https://github.com/DroiD16/fvtt-world-cli/releases/latest/download/module.json
+```
 
-## 2. Pair the Foundry GM client
+Enable *World CLI for Foundry VTT* in the target world. The CLI and module must come from the
+same release. If either was already installed, follow [Updating](#updating) to bring them into sync.
 
-Pairing is how a browser gets its own permission to talk to the daemon; it happens once per
-browser.
+## 1. Start the daemon
 
-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:
+```bash
+fvtt-world-cli bridge serve
+```
 
-- muted grey: not paired yet
-- amber: connecting
-- green: the bridge is up
-- red: stopped or failed
+The daemon connects the CLI to your GM browser. By default it listens on
+`ws://127.0.0.1:47833` and stays running in this terminal for as long as you use the tool.
+Keep the terminal open and use a second terminal for the remaining commands.
 
-The same windows are also reachable through Configure Settings → Module Settings:
+With the daemon running, open the world in your GM browser. If the world was already open when
+you started the daemon, choose *Connect* in the World CLI scene controls or reload the client.
 
-![The module settings](images/module-settings.png)
+## 2. Pair the Foundry GM client
+
+Open *Authorization* from the *World CLI* group in the left scene controls. The same window is
+available through Configure Settings → Module Settings → World CLI for Foundry VTT.
 
-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 module settings](images/module-settings.png)
 
-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.
+Enter a *Browser label* that you will recognize in the terminal, then choose *Pair*.
 
 ![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:
+In your second terminal, run:
 
 ```bash
 fvtt-world-cli auth
 ```
 
-The command waits for the pairing request; starting it before or after clicking Pair works either
-way. It shows who is asking, with the origin, world, GM, browser label, and client id, and asks
-`Approve pairing request <code>? [y/N]`. Typing `y` and pressing Enter approves it; any other
-answer denies it. To read a request over before deciding, or to approve from a script, the same
-approval exists as two steps:
+The command shows the requesting origin, world, GM, browser label, and client id. Check that
+these match the browser you just paired. At `Approve pairing request <code>? [y/N]`, type `y`
+and press Enter to approve. Any other answer denies the request.
 
-```bash
-fvtt-world-cli auth pending
-fvtt-world-cli auth approve <code>   # add --yes in a script to skip the confirmation
-```
+Pairing is saved for this browser, world, and GM; you do not repeat it on each use.
+
+## 3. Check the connection
 
-## 3. Confirm the bridge
+After pairing approval, the *World CLI* icon in the scene controls turns green. Open *Bridge status*
+from the same group to see the connection details. No reload is needed after pairing.
 
-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.
+On later runs, start the daemon before opening the world. The browser reconnects automatically
+unless you disable *Connect automatically* in the module settings.
 
-A first command confirms the connection end to end:
+## Start working
+
+To give your AI agent the operating instructions, install the packaged skill:
 
 ```bash
-fvtt-world-cli system info --json
+fvtt-world-cli skill install
 ```
 
-It reports `bridge.status` as `connected`.
+[Agent skill](skill.md) explains installation options and updates. For manual use, start with the
+[common workflows](commands.md#common-workflows).
+
+## Updating
+
+Update the CLI and Foundry module to the same release. Components from different releases refuse
+to connect, even when their command lists look the same.
+
+1. Stop the daemon with Ctrl+C in its terminal.
+2. Update the CLI:
+
+   ```bash
+   npm install -g fvtt-world-cli@latest
+   ```
 
-Commands use the permissions stored for that browser profile. Run `fvtt-world-cli commands` after
-the bridge connects to see which commands the client will run. A daemon that rejects the browser
-credential returns an error instead of the static registry.
+3. Update *World CLI for Foundry VTT* in Foundry's module management screen.
+4. Start `fvtt-world-cli bridge serve` again, then open or reload the GM client.
+5. Check that the *World CLI* icon is green.
 
-Destructive commands ask the GM by default. Set each command's behavior under Configure Settings →
-Module Settings → World CLI → Command permissions. Set the waiting time in the `Approval timeout
-(minutes)` field in the main Module Settings form. [Commands](commands.md#command-permissions-and-approval)
-describes the behavior in full.
+Existing browser pairings remain valid.
 
-## When something deviates
+## Troubleshooting
 
-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.
+Open *Bridge status* first. It shows the daemon URL, connection state, and the reason for a stop.
 
-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.
+| What you see | What to do |
+|---|---|
+| The daemon was unavailable when the world loaded | Start the daemon, then choose *Connect* or reload the GM client. |
+| `BRIDGE_BUSY` | Another paired browser holds the connection. Choose *Disconnect* there, then *Connect* in the browser you want to use. Keep the existing pairing. |
+| A protocol-version mismatch | Follow [Updating](#updating). The status window identifies the component that needs an update when it can compare the versions. |
+| The daemon URL does not match | Set the module's *Daemon URL* to the address printed by `bridge serve`. The defaults already match. |
+| *Connect automatically* is disabled | Choose *Connect*, or enable that setting for future world loads. |
+| A command waits for GM approval | Answer the Command Approval window in Foundry. The command continues after approval. |
+| Unpair cannot reach the daemon | Restore the daemon and retry. *Forget local* removes only the browser's credential; the daemon profile remains until `auth revoke <pairingId>` succeeds. |
 
-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.
+If the active browser is unavailable, `fvtt-world-cli bridge release` frees its slot. The released
+browser stays stopped until its operator chooses *Connect*.
 
-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.
+For pairing management, scripted approval, and profile removal, see
+[Authorization commands](commands.md#authorization-commands).