Merge main into #1003

# Conflicts:
#	crates/engine/src/lib.rs

docs/cli.md

@@ -4,7 +4,9 @@ FigCraft without a window: inspect, export, convert and render documents, run co
 commands, serve MCP and measure performance. Build it with
 `cargo build --release -p figcraft-cli` (binary `target/release/figcraft-cli`).
 
-Bad arguments print usage and exit with code 2; failures exit with 1. The CLI never panics on input.
+`figcraft-cli --help` (or `-h`, or `help`) prints usage on stdout and exits with 0, and so does
+`--help` or `-h` after a subcommand (`figcraft-cli mcp --help`). Bad arguments print usage and exit
+with code 2; failures exit with 1. The CLI never panics on input.
 
 ## Fonts
 
@@ -51,6 +53,10 @@ page 1 "Screens": 380 nodes, 4 top-level
 
 - `<out>` is a directory: one file per top-level frame of the page (default the first page), named
   after the frame (`Home.png`, `Settings.png`…); with no frames, one file per top-level layer.
+  The name is kept as it is, except for the characters file systems refuse (`/ \ : * ? " < > |`
+  and control characters), which become `_`, and leading or trailing spaces and dots, which are
+  dropped. A name is cut at 100 characters. The app's export replaces the same characters (there a
+  `/` makes a folder). Two layers with the same name get `Name 2`, `Name 3`…
 - `<out>` has an image extension: one file with the given `--node`, or the whole page composited.
 - `--node` takes a layer id (`12` or `0:12`) or a layer name.
 - `--format fig` (or an `<out>` ending in `.fig`) writes the whole file as `.fig`, experimental:
@@ -190,7 +196,9 @@ Serve MCP on stdio: headless by default, or attached to a running app started wi
 `figcraft --control PORT`. See [mcp.md](mcp.md). The automation roots (each repeatable; existing
 folders) confine the files the agent's calls read (inside a read or write root) and write (inside a
 write root); everything else is refused ([mcp.md › Confining file access](mcp.md#confining-file-access)).
-With `--attach` they are refused: start the app with them instead. The headless session can host, join and publish
+They apply to the headless session only, and that is why `--attach` refuses them: an attached server
+is confined by the app it attaches to, from the flags that app was started with. The headless
+session can host, join and publish
 live sessions (`collab.*`: without a key on a server open to the public, with `collab.serverInfo`,
 `collab.manageFile` for the owner token and `collab.report`) and use plugin directories
 (`plugin.directory.*`); the one-shot `run` can't (no network link).