Merge #905: M1: say that the automation roots reach only the headless side (#835) (@xiaou61)

apps/figcraft-cli/src/main.rs

@@ -46,10 +46,11 @@ the FIGCRAFT_SERVER_KEY environment variable (which keeps it out of the shell hi
 `--automation-read-root DIR` / `--automation-write-root DIR` (each may be repeated; the folders
 must exist) confine the files a subcommand touches: reads only inside a read or write root, writes
 only inside a write root, everything else refused -- so giving no write root denies writing
-altogether. They are taken by `mcp`, to confine the agent's commands, and by `info`, `export`,
-`convert`, `render` and `run`, to confine that one run; without them a subcommand reads and writes
-as the user who started it, as before. A running app confines itself: start it with
-`figcraft --control PORT` and the same flags (`--attach` refuses them).
+altogether. They reach the headless side only: `mcp` takes them to confine the agent's commands,
+and `info`, `export`, `convert`, `render` and `run` to confine that one run; without them a
+subcommand reads and writes as the user who started it, as before. A `mcp --attach` server is
+confined by the app it attaches to, not by flags passed to the CLI: start that app with
+`figcraft --control PORT` and the same roots (`--attach` refuses them).
 See docs/cli.md and docs/mcp.md.";
 
 /// The automation roots a file subcommand was given, if any. Omitting both leaves the run

docs/cli.md

@@ -192,7 +192,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).

docs/mcp.md

@@ -34,6 +34,10 @@ of the window itself (`screenshot` with `window`) needs it on screen: it is then
 
 ### Confining file access
 
+The roots below belong to the **headless** side: the session `figcraft-cli mcp` runs itself, with
+no window. A server attached with `--attach` runs the commands inside the app instead, so the app
+confines them — from the flags it was started with, not from anything passed to the CLI.
+
 ```sh
 figcraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project/out
 ```