fvtt-world-cli 1.1.1 → 1.2.0

package/docs/skill.md

@@ -1,15 +1,7 @@
 # Agent skill
 
-fvtt-world-cli ships with `foundry-world-editor`, an installable Agent Skill, a short operating
-manual that teaches an AI agent to drive this CLI safely: how to bring the stack up and check its
-health, the read → preview → commit → verify loop, how to classify failures before retrying, and
-where the hard safety boundaries are. Skills follow the open Agent Skills standard, so the same
-file works in Claude Code, Codex, and every other agent that reads `SKILL.md` files.
-
-The skill deliberately contains no command inventory. Agents discover the exact command surface
-from the CLI itself (`commands --json`, `schema <command>`), so the skill stays valid as commands
-evolve; it carries only the knowledge that runtime discovery cannot provide. The skill itself lives
-at [`skills/foundry-world-editor/SKILL.md`](../skills/foundry-world-editor/SKILL.md).
+The package includes [foundry-world-editor](../skills/foundry-world-editor/SKILL.md), operating
+instructions for AI agents that support Agent Skills.
 
 ## Installing
 
@@ -17,10 +9,8 @@ at [`skills/foundry-world-editor/SKILL.md`](../skills/foundry-world-editor/SKILL
 fvtt-world-cli skill install
 ```
 
-The default installation delegates to the ecosystem's skills CLI (`npx skills add`), which detects
-the agents present on the machine. It keeps one canonical copy under `~/.agents/skills`, the
-vendor-neutral location of the Agent Skills standard, and points each agent's own skill directory
-at it, so every agent reads the same single copy.
+The default installation runs `npx skills add`, which detects the agents present on the machine.
+It keeps a shared copy under `~/.agents/skills` and links the agents' skill directories to it.
 
 An explicit destination works without the skills CLI or network access:
 
@@ -28,35 +18,27 @@ An explicit destination works without the skills CLI or network access:
 fvtt-world-cli skill install --to <skills-directory>
 ```
 
-`--to` performs a direct copy and records the location in the CLI's local configuration, so that
-copy participates in updates later. `--link` symlinks instead of copying, which keeps the installed
-skill permanently identical to the CLI it came from.
+The CLI records this destination for later updates. Add `--link` to use the packaged skill
+directly through a symlink:
 
-A bridge daemon started while no copy is installed anywhere prints a reminder with the
-installation command, so a missing skill does not go unnoticed.
+```bash
+fvtt-world-cli skill install --to <skills-directory> --link
+```
 
-## Staying up to date
+`--link` requires `--to`. A linked skill follows CLI package updates automatically.
 
-The skill is versioned together with the CLI, and the CLI keeps installed copies current on its
-own: the bridge daemon checks every known copy at startup and refreshes outdated ones, so a package
-update takes effect the next time the daemon starts. The check runs inside the CLI itself; nothing
-about installation or updates relies on npm lifecycle scripts, which npm blocks by default. For
-updates, a copy is one of two kinds:
+## Staying up to date
 
-- An **unmodified** copy, exactly what some version of the CLI shipped, is replaced silently with
-  the current version.
-- A **modified** copy, one with local edits, is never replaced automatically. It produces a
-  warning instead, and keeps producing it until the difference is resolved.
+At startup, the daemon updates unmodified copies in the shared directory and recorded `--to`
+locations. It preserves locally edited copies and warns instead of overwriting them.
 
-The explicit update command follows the same rule and can override it:
+To update manually:
 
 ```bash
 fvtt-world-cli skill update
-fvtt-world-cli skill update --force
 ```
 
-The CLI tells an old shipped version apart from a local edit by a content checksum recorded inside
-every installed copy, so an outdated installation is never mistaken for a customized one.
+Add `--force` to replace a locally edited copy with the packaged version.
 
 ## Removing
 
@@ -67,3 +49,12 @@ fvtt-world-cli skill remove --to <skills-directory>
 
 The default removal uninstalls the canonical copy, the agent links pointing at it, and every
 location recorded for `--to` installations; `--to` removes one location and forgets it.
+
+## JSON output
+
+For `skill install`, `skill update`, and `skill remove`, `--json` requires an explicit `--to`
+destination:
+
+```bash
+fvtt-world-cli skill install --to <skills-directory> --json
+```

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "fvtt-world-cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Safe local CLI and authenticated bridge for automating live Foundry VTT worlds.",
+  "keywords": [
+    "foundry-vtt",
+    "foundryvtt",
+    "fvtt",
+    "virtual-tabletop",
+    "ttrpg",
+    "cli",
+    "automation",
+    "ai",
+    "ai-agent",
+    "agent-skills"
+  ],
   "license": "MIT",
   "author": "DroiD16",
   "repository": {
@@ -44,6 +56,6 @@
     "zod": "^3.24.3"
   },
   "devDependencies": {
-    "@fvtt-world-cli/protocol": "1.1.1"
+    "@fvtt-world-cli/protocol": "1.2.0"
   }
 }

package/skills/foundry-world-editor/SKILL.md

@@ -75,6 +75,11 @@ A macro that throws fails `macro.execute` with a partial outcome — read what i
 retrying — while a macro that catches its own errors still returns `null`, which proves nothing;
 verify effects with reads, and treat `MACRO_TIMEOUT` as indeterminate — the macro may still be
 running.
+On Foundry v14 maps live on levels: pass `levels` in `scene.create`, then use `scene.level.*`;
+level ids in a preview are provisional.
+Deleting a level also deletes its tokens and every placeable only on that level, and the dry run
+does not list them: read the scene's placeables (token `level`, others' `levels`) and tell the user
+what the delete removes before running it.
 `setting.set` cannot touch this module's own namespace (`SETTING_PROTECTED` is final; never retry).
 When a setting write returns `requiresReload: true`, the change needs a GM-client reload to take
 effect; `system.reload` performs it, drops the bridge, and requires a reconnect wait before the
@@ -135,7 +140,8 @@ details}}`, alongside `protocolVersion`, `type`, and the correlation `id` (echoi
 Documents live under a type-named key inside `result` that varies between commands but is stable
 for each one. `id` is the public identifier; a `_id` mirror may accompany it. Values requested
 through `include` flags may be derived or version-dependent. Write them back only when the
-update schema explicitly accepts them.
+update schema explicitly accepts them. Actor reads return `itemCount` in place of owned items; add
+`--include items` when the task needs them, or use `actor item list` and `actor item get`.
 
 ## Retry classification
 
@@ -155,8 +161,16 @@ Classify a failure before reacting:
 - `APPROVAL_DENIED`, `APPROVAL_TIMEOUT`, and `APPROVAL_CANCELLED` mean nothing ran. Report the outcome
   and wait for user direction. `APPROVAL_QUEUE_FULL` also means nothing ran, but it can clear after
   earlier requests settle.
+- `APPROVAL_STALE` means the GM allowed a macro execution whose body or type changed — or whose
+  macro was deleted — after it was shown, so nothing ran. Read the macro again and re-send the execution if the current content is
+  still what the user wants; that opens a fresh approval.
 - `APPROVAL_UNKNOWN` and unconfirmed cancellation are indeterminate. Read the affected documents,
   report the result, and use a fresh key if the operation still needs to run.
+- For an update `INTERNAL_ERROR` with `details.partial: true` or `details.indeterminate: true`,
+  read the affected document before retrying. `changedFields` names requested top-level fields
+  observed to change, not fully applied nested values. An embedded creation without a requested
+  id may already exist despite an indeterminate error. Send only the remaining changes as a new
+  operation with a fresh idempotency key, if using one.
 - Correct a structured Foundry rejection and submit the corrected content as a new operation.
 
 ## Bulk writes and actions

package/skills/foundry-world-editor/SKILL.md.sha256

@@ -1 +1 @@
-1834777e1d540cb4cc11b6eac862ff99878a6e4920ebbc1e2599871893e19dc9
+248c52464e776236de6f937530e220dcb77b45a8b5cc754adbb4cfb4671a8c66

package/docs/images/icon.svg

@@ -1,16 +0,0 @@
-<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

@@ -1,15 +0,0 @@
-<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>