@nexus-aethra/dsh-box-sandbox 0.1.0 → 0.2.0

package/README.md

@@ -81,8 +81,48 @@ container.
 
     pnpm install
     pnpm typecheck
+    pnpm check:outputs   # static: schema vs what the daemon returns
+    pnpm check:tools     # live: every tool called against a running Box
     pnpm build
-    node smoke.mjs   # 10 checks against a running DSH Box
 
-`smoke.mjs` needs a live daemon: it reads the real discovery record, pings
-it, forces a stale-port failure, and verifies recovery.
+`check:tools` needs a running daemon: it imports the built plugin with a stub
+host context, calls every tool's `execute` for real, and validates each answer
+against that tool's own output schema — the same check the host applies, at the
+moment the answer comes back. It exists because a tool whose schema disagrees
+with its result does not fail at build time; it fails when someone presses the
+button, and the only way to see that is to press it.
+
+`check:tools` is a local check and does not run in CI, which has no daemon.
+The tag pipeline runs `check:outputs` instead, because that one needs nothing
+but the repository.
+
+    node smoke.mjs   # transport-level: ping, stale-port failure, recovery
+
+`smoke.mjs` reads the real discovery record and checks the wire contract.
+
+## Releasing
+
+This package's version is the DSH Box app's version. One tag, one release, and
+`release.yml` checks all four manifests against it before anything is built —
+bumping the app and forgetting this one fails the pipeline rather than
+publishing a plugin whose version claims to match a build it was never part of.
+
+To release:
+
+1. Bump `version` in this `package.json`, the root `package.json`,
+   `src-tauri/tauri.conf.json` and `src-tauri/Cargo.toml` to the same number.
+2. Run `pnpm check:tools` against a real Box. CI cannot — it has no daemon —
+   so this is the only place the live check happens.
+3. Commit, tag `v<version>`, push the tag.
+
+The `publish-plugin` job runs after the installers are built, so a release
+whose app build failed does not put a version on npm. It typechecks, runs the
+schema reconciliation, builds `dist/` (gitignored, so never restored from the
+commit), prints the tarball contents, skips a version npm already has, refuses
+to publish below what npm has, and publishes with provenance.
+
+Auth is npm trusted publishing over OIDC — there is no long-lived token to
+leak. One-time setup on npmjs.com, under the package's Settings → Trusted
+Publishers: provider **GitHub Actions**, account `aethra-tech`, repository
+`DSHBox`, workflow filename `release.yml`. Rename that file and npm has to be
+told again.

package/dist/index.d.mts

@@ -4,9 +4,9 @@ import { Context } from "@deepseek-ai/cordis";
 /** Cordis plugin name used by loader diagnostics and the patch overlay. */
 declare const name = "dsh-box-sandbox";
 /**
- * Services this plugin depends on. Empty for now: the client is pure
- * transport and needs no host service. Tools built on top of it will
- * declare their own.
+ * Services this plugin depends on. `tools` to register the box_* surface and
+ * `systemPrompt` for the cross-tool workflow section; the client itself is
+ * pure transport and needs nothing.
  */
 declare const inject: string[];
 /**

package/dist/index.mjs

@@ -165,11 +165,6 @@ async function withSession(id, method, params) {
 		});
 	}
 }
-function base64Of(value) {
-	const data = asRecord(value).data;
-	if (typeof data !== "string") throw new Error("screenshot result carried no image data");
-	return data;
-}
 /**
 * Register one tool against the host registry.
 *
@@ -211,6 +206,14 @@ function nextHint(next) {
 	return "\nnext: " + next;
 }
 /**
+* A string that may legitimately be absent.
+*
+* The daemon reports these as ${Option<String>}: a miss is null, not
+* an empty string, and a schema that says $string alone rejects it — so a
+* click that worked is reported as a failed tool call.
+*/
+const nullable = { oneOf: [{ type: "string" }, { type: "null" }] };
+/**
 * Render a click, distinguishing the two outcomes an agent must not confuse.
 *
 * A dispatched event is not a delivered one. When something covers the target
@@ -236,7 +239,7 @@ function renderClick(value, target) {
 function applyBoxTools(ctx) {
 	registerTool(ctx, {
 		name: "box_screenshot",
-		description: "Save what a running dshbox container currently renders as a PNG, and report where.This is the one tool whose picture you do not get: a tool result is assistant-side contentand the host sends text only on that side, so you receive the dimensions and nothing else.Asking yourself to look at the image asks for something that cannot arrive, and re-readingthe file path does not change that. So take one to leave something a person can look at,and use box_page_text to find out what is on the page. In practice: describe the page inyour answer, and save a PNG when the layout or a rendering is what is worth showingrather than describing.",
+		description: "Save what a running dshbox container currently renders as a PNG, and report where.You get the file path and the image size, not the picture: a tool result is assistant-sidecontent and the host sends text only on that side, so an image cannot arrive. Hand the pathto a person to look at, and use box_page_text to find out what is on the page. In practice:describe the page in your answer from box_page_text, and take a screenshot when the layoutor a rendering is what is worth showing rather than describing.",
 		parameters: {
 			type: "object",
 			properties: {
@@ -258,35 +261,38 @@ function applyBoxTools(ctx) {
 				additionalProperties: false,
 				properties: {
 					containerId: { type: "string" },
-					attachment: { type: "object" }
+					path: { type: "string" },
+					width: { type: "number" },
+					height: { type: "number" },
+					bytes: { type: "number" }
 				},
-				required: ["containerId", "attachment"]
+				required: [
+					"containerId",
+					"path",
+					"width",
+					"height",
+					"bytes"
+				]
 			},
 			render: (_args, value) => {
 				const record = asRecord(value);
-				const shot = asRecord(record.attachment);
 				return [{
 					type: "text",
-					text: "Screenshot of container " + String(record.containerId) + " at " + String(shot.width) + "x" + String(shot.height) + "."
-				}, {
-					type: "image",
-					attachment: record.attachment
+					text: "Screenshot of container " + String(record.containerId) + " (" + String(record.width) + "x" + String(record.height) + ", " + String(record.bytes) + " bytes) saved to " + String(record.path) + "."
 				}];
 			}
 		},
 		async execute(args) {
 			const containerId = containerIdOf(args);
-			const raw = await withSession(containerId, "debug_capture_screenshot", {
-				format: "png",
-				fullPage: asRecord(args).fullPage === true
-			});
-			const data = Buffer.from(base64Of(raw), "base64");
+			const result = await withSession(containerId, "debug_capture_screenshot", { fullPage: asRecord(args).fullPage === true });
+			const path = result.path;
+			if (typeof path !== "string" || path === "") throw new Error("screenshot result carried no file path");
 			return {
 				containerId,
-				attachment: await hostServices(ctx).attachments.saveImage({
-					data: new Uint8Array(data),
-					mediaType: "image/png"
-				})
+				path,
+				width: result.width,
+				height: result.height,
+				bytes: result.bytes
 			};
 		}
 	});
@@ -327,12 +333,12 @@ function applyBoxTools(ctx) {
 				properties: {
 					containerId: { type: "string" },
 					name: { type: "string" },
-					matched: { type: "string" },
+					matched: nullable,
 					landed: { type: "boolean" },
-					hitTag: { type: "string" },
-					hitText: { type: "string" },
-					occludedBy: { type: "string" },
-					selector: { type: "string" },
+					hitTag: nullable,
+					hitText: nullable,
+					occludedBy: nullable,
+					selector: nullable,
 					x: { type: "number" },
 					y: { type: "number" },
 					tag: { type: "string" },
@@ -406,12 +412,17 @@ function applyBoxTools(ctx) {
 				properties: {
 					containerId: { type: "string" },
 					x: { type: "number" },
-					y: { type: "number" }
+					y: { type: "number" },
+					landed: { type: "boolean" },
+					hitTag: nullable,
+					hitText: nullable,
+					occludedBy: nullable
 				},
 				required: [
 					"containerId",
 					"x",
-					"y"
+					"y",
+					"landed"
 				]
 			},
 			render: (_args, value) => renderClick(value, "at (" + String(asRecord(value).x) + ", " + String(asRecord(value).y) + ")")
@@ -533,7 +544,9 @@ function applyBoxTools(ctx) {
 					scrollHeight: { type: "number" },
 					viewportHeight: { type: "number" },
 					screensBelow: { type: "number" },
-					moved: { type: "boolean" }
+					moved: { type: "boolean" },
+					scroller: nullable,
+					scrollerIsDocument: { type: "boolean" }
 				},
 				required: [
 					"containerId",
@@ -587,7 +600,7 @@ function applyBoxTools(ctx) {
 				properties: {
 					containerId: { type: "string" },
 					inserted: { type: "number" },
-					focused: { type: "string" },
+					focused: nullable,
 					landed: { type: "boolean" }
 				},
 				required: [
@@ -608,9 +621,97 @@ function applyBoxTools(ctx) {
 			const containerId = containerIdOf(args);
 			const record = asRecord(args);
 			if (typeof record.text !== "string" || record.text === "") throw new Error("text is required and must be non-empty");
+			const result = await withSession(containerId, "debug_type_text", { text: record.text });
 			return {
 				containerId,
-				...await withSession(containerId, "debug_type_text", { text: record.text })
+				inserted: result.inserted,
+				focused: result.focused,
+				landed: result.focused !== null
+			};
+		}
+	});
+	registerTool(ctx, {
+		name: "box_console",
+		description: "Read what the page has logged, and clear the buffer — a second call reports only what arrived since the first. Uncaught errors are included whether or not any code caught them, which is the point: a client plugin that fails to register leaves a page that looks fine and says nothing, and this is the only tool that sees it. Repeated identical lines are collapsed into one entry with a count. The levels default to error and warning because log-level traffic is usually dozens of lines per page load; pass levels to ask for the rest when the failures are not the problem.",
+		parameters: {
+			type: "object",
+			properties: {
+				containerId: {
+					type: "string",
+					description: "Container whose console to read."
+				},
+				levels: {
+					type: "array",
+					items: {
+						type: "string",
+						enum: [
+							"log",
+							"info",
+							"debug",
+							"warning",
+							"error",
+							"assert"
+						]
+					},
+					description: "Which severities to return. Defaults to error and warning."
+				},
+				limit: {
+					type: "number",
+					description: "Most recent entries to return. Defaults to 50, capped at 500."
+				}
+			},
+			required: ["containerId"]
+		},
+		timeoutMs: WARM_BUDGET_MS,
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					containerId: { type: "string" },
+					entries: { type: "array" },
+					total: { type: "number" },
+					truncated: { type: "boolean" },
+					raw: { type: "number" },
+					methods: { type: "array" }
+				},
+				required: [
+					"containerId",
+					"entries",
+					"total",
+					"truncated",
+					"raw",
+					"methods"
+				]
+			},
+			render: (_args, value) => {
+				const record = asRecord(value);
+				const entries = Array.isArray(record.entries) ? record.entries : [];
+				if (entries.length === 0) return [{
+					type: "text",
+					text: "The page in container " + String(record.containerId) + " logged nothing at the levels asked for, and logged nothing since the last read." + nextHint("if the page was just loaded, try again after the failing step, or widen levels to log")
+				}];
+				const lines = entries.map((entry) => {
+					const item = asRecord(entry);
+					const where = item.source ? " (" + String(item.source) + ")" : "";
+					const times = Number(item.count ?? 1) > 1 ? " x" + String(item.count) : "";
+					return "[" + String(item.level) + "]" + where + " " + String(item.text) + times;
+				});
+				return [{
+					type: "text",
+					text: "Console of container " + String(record.containerId) + " — " + String(record.total) + " distinct message(s), oldest first" + (record.truncated === true ? " (truncated to the most recent)" : "") + ". Reading this cleared the buffer.\n" + lines.join("\n")
+				}];
+			}
+		},
+		async execute(args) {
+			const containerId = containerIdOf(args);
+			const record = asRecord(args);
+			const request = {};
+			if (Array.isArray(record.levels) && record.levels.length > 0) request.levels = record.levels;
+			if (typeof record.limit === "number") request.limit = record.limit;
+			return {
+				containerId,
+				...await withSession(containerId, "debug_console", request)
 			};
 		}
 	});
@@ -681,8 +782,8 @@ function applyBoxTools(ctx) {
 					kind: { type: "string" },
 					path: { type: "string" },
 					configured: { type: "boolean" },
-					configuredPath: { type: "string" },
-					problem: { type: "string" }
+					configuredPath: nullable,
+					problem: nullable
 				},
 				required: ["available"]
 			},
@@ -739,7 +840,7 @@ function applyBoxTools(ctx) {
 			const containerId = containerIdOf(args);
 			return {
 				containerId,
-				...await getRpc().call("debug_close", { id: containerId })
+				closed: (await getRpc().call("debug_close", { id: containerId })).closed === true
 			};
 		}
 	});
@@ -935,6 +1036,8 @@ function registerManageTools(ctx) {
 					"inject",
 					"rm",
 					"rm-view",
+					"view-on",
+					"view-off",
 					"prune",
 					"types",
 					"views"
@@ -965,7 +1068,7 @@ function registerManageTools(ctx) {
 				},
 				viewId: {
 					type: "string",
-					description: "Which resource view to remove."
+					description: "Which resource view to act on: the type a Resources tab stands for. Required by rm-view, view-on and view-off."
 				},
 				name: {
 					type: "string",
@@ -1083,8 +1186,20 @@ function registerManageTools(ctx) {
 				case "rm-view": return {
 					action,
 					containerId,
-					result: asObject(await rpc.call("delete_resource_view", { id: required(record, "viewId") }))
+					result: asObject(await rpc.call("delete_resource_view", { viewId: required(record, "viewId") }))
 				};
+				case "view-on":
+				case "view-off": {
+					const enabled = action === "view-on";
+					return {
+						action,
+						containerId,
+						result: asObject(await rpc.call("set_resource_view_enabled", {
+							viewId: required(record, "viewId"),
+							enabled
+						}))
+					};
+				}
 				case "prune": return {
 					action,
 					containerId,
@@ -1119,6 +1234,8 @@ function registerManageTools(ctx) {
 					"inject",
 					"rm",
 					"rm-view",
+					"view-on",
+					"view-off",
 					"prune",
 					"types",
 					"views"
@@ -1260,6 +1377,7 @@ function registerManageTools(ctx) {
 				};
 				const title = optional(record, "title");
 				if (title !== void 0) params.title = title;
+				if (flag(record, "restart")) params.restart = true;
 				const added = await rpc.call("add_container_workspace", params);
 				return {
 					action,
@@ -1725,7 +1843,7 @@ function registerManageTools(ctx) {
 					"from-version",
 					"describe",
 					"url",
-					"browse"
+					"browse-paths"
 				]),
 				name: {
 					type: "string",
@@ -1741,7 +1859,7 @@ function registerManageTools(ctx) {
 				},
 				containerId: {
 					type: "string",
-					description: "Which container, for describe, url and browse."
+					description: "Which container, for describe, url and browse-paths."
 				},
 				profile: {
 					type: "string",
@@ -1815,6 +1933,7 @@ function registerManageTools(ctx) {
 					action,
 					result: asObject(await rpc.call("container_url", { id: needId() }))
 				};
+				case "browse-paths":
 				case "browse": return {
 					action,
 					result: asObject(await rpc.call("browse_container_paths", { id: needId() }))
@@ -1824,7 +1943,7 @@ function registerManageTools(ctx) {
 					"from-version",
 					"describe",
 					"url",
-					"browse"
+					"browse-paths"
 				]);
 			}
 		}
@@ -2124,15 +2243,11 @@ function asArray(value) {
 /** Cordis plugin name used by loader diagnostics and the patch overlay. */
 const name = "dsh-box-sandbox";
 /**
-* Services this plugin depends on. Empty for now: the client is pure
-* transport and needs no host service. Tools built on top of it will
-* declare their own.
+* Services this plugin depends on. `tools` to register the box_* surface and
+* `systemPrompt` for the cross-tool workflow section; the client itself is
+* pure transport and needs nothing.
 */
-const inject = [
-	"tools",
-	"attachments",
-	"systemPrompt"
-];
+const inject = ["tools", "systemPrompt"];
 /**
 * Effective configuration after defaults.
 *
@@ -2195,7 +2310,7 @@ async function status(config) {
 * anything a tool already reports belongs in that tool.
 */
 const WORKFLOW_PROMPT_SECTION = "dsh-box-sandbox:page-workflow";
-const WORKFLOW_PROMPT_ORDER = 3050;
+const WORKFLOW_PROMPT_ORDER = 3350;
 function pageWorkflowPrompt() {
 	return [
 		"Debugging a page with the box_* tools:",
@@ -2211,7 +2326,11 @@ function pageWorkflowPrompt() {
 		"Before typing, click the field. box_type_text reports the focused element and inserts nothing",
 		"when no editable field holds focus.",
 		"If a page tool cannot find a browser, box_set_browser reports which one is in use and pins a",
-		"different one."
+		"different one.",
+		"When a page looks right but behaves wrongly — a client bundle that never registered, a control",
+		"that does nothing — read box_console. A page that failed to load its own assets says so only",
+		"there; the rest of the surface reports a page that is present, which is exactly what a broken",
+		"one also is."
 	].join("\n");
 }
 /** Register the plugin against a freshly mounted Cordis context. */

package/dist/rpc.d.mts

@@ -115,6 +115,15 @@ declare class DshboxRpc {
    * never retried -- they are answers, not outages.
    */
   call<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+  /**
+   * The message for "discovery.json names a daemon that is not there".
+   *
+   * Staleness has two causes needing different fixes: the file may be
+   * missing (the daemon was never started) or it may name a pid that has
+   * exited (it crashed, or the machine rebooted). Both arrive here as a
+   * refused connection, so the record is read again to tell them apart.
+   */
+  private unreachable;
   /** Liveness probe. Resolves to the daemon's own status frame. */
   ping(): Promise<{
     pid: number;

package/dist/rpc.mjs

@@ -148,17 +148,34 @@ var DshboxRpc = class {
 	* never retried -- they are answers, not outages.
 	*/
 	async call(method, params) {
+		let lastStale = null;
 		for (let attempt = 0; attempt < 2; attempt++) {
 			const record = this.discovery();
 			try {
 				return await this.send(record, method, params);
 			} catch (error) {
-				if (attempt === 0 && isStaleEndpoint(error)) continue;
-				throw error;
+				if (!isStaleEndpoint(error)) throw error;
+				lastStale = error;
+				if (attempt === 0) continue;
+				throw this.unreachable(method, lastStale);
 			}
 		}
-		/* c8 ignore next 2 */
-		throw new DshboxUnavailableError("dshbox daemon unreachable for " + method);
+		/* c8 ignore next */
+		throw this.unreachable(method, lastStale);
+	}
+	/**
+	* The message for "discovery.json names a daemon that is not there".
+	*
+	* Staleness has two causes needing different fixes: the file may be
+	* missing (the daemon was never started) or it may name a pid that has
+	* exited (it crashed, or the machine rebooted). Both arrive here as a
+	* refused connection, so the record is read again to tell them apart.
+	*/
+	unreachable(method, cause) {
+		const path = discoveryPath(this.configDir);
+		const record = readDiscovery(this.configDir);
+		if (record === null) return new DshboxUnavailableError("dshbox is not running, so " + method + " has nothing to talk to. Start it from the desktop app, or run `dshbox` once, then retry. No discovery record at " + path + ".", { cause });
+		return new DshboxUnavailableError("dshbox is not running, so " + method + " has nothing to talk to. The discovery record at " + path + " is stale: it names pid " + record.pid + " on port " + record.port + ", and nothing is listening there. Start the desktop app (or run `dshbox`) to bring up a new daemon; the stale record is replaced on startup.", { cause });
 	}
 	/** Liveness probe. Resolves to the daemon's own status frame. */
 	ping() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexus-aethra/dsh-box-sandbox",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Host-side bridge from a DSH session to the DSH Box daemon: typed box_* tools an agent can call without a shell.",
   "keywords": [
     "dsh",
@@ -10,13 +10,13 @@
     "box",
     "tools"
   ],
-  "homepage": "https://github.com/aethra-tech/DSHBox/tree/main/plugins/dsh-box-sandbox",
+  "homepage": "https://github.com/Nexus-Aethra/DSHBox/tree/main/plugins/dsh-box-sandbox",
   "bugs": {
-    "url": "https://github.com/aethra-tech/DSHBox/issues"
+    "url": "https://github.com/Nexus-Aethra/DSHBox/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/aethra-tech/DSHBox.git",
+    "url": "git+https://github.com/Nexus-Aethra/DSHBox.git",
     "directory": "plugins/dsh-box-sandbox"
   },
   "author": "Nexus Aethra",
@@ -37,6 +37,7 @@
   },
   "files": [
     "dist/",
+    "skills/",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"
@@ -46,6 +47,14 @@
       "patch": "./cordis.patch.yml"
     }
   },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "check:outputs": "node scripts/check-output-schemas.mjs",
+    "check:tools": "node scripts/check-tool-outputs.mjs",
+    "deploy": "node scripts/deploy.mjs"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"
   },
@@ -53,10 +62,5 @@
     "@types/node": "^22.10.0",
     "tsdown": "^0.22.2",
     "typescript": "^5.6.0"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "watch": "tsdown --watch",
-    "typecheck": "tsc --noEmit"
   }
-}
+}

package/skills/dsh-box-tools/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: dsh-box-tools
+description: Use when you need to inspect, start, or change DSH Box containers, templates, plugins or resources from inside a container session — cover box_overview, box_lifecycle, box_create, box_resources, box_plugins, box_templates, box_settings, box_task and the browser page tools.
+---
+
+# Driving DSH Box with the `box_*` tools
+
+You run inside a DSH Box container, and this profile mounts the sandbox plugin
+(`@nexus-aethra/dsh-box-sandbox`) that bridges to the `dshboxd` daemon on the host.
+It registers a typed `box_*` tool surface, so you never have to shell out to `dshbox`
+or parse its stdout. Every tool is one JSON call; every answer is the daemon's own
+result, not a summary.
+
+## Read this first
+
+- **`box_overview` before anything else.** It is the only listing tool: containers,
+  templates, and the plugins the box knows. Acting on an id you guessed is the
+  failure this tool removes.
+- **Anything that changes state through a task needs `box_task`.** Call it with
+  `action: 'status'` and the task id the action returned, or `action: 'list'` to
+  find what is already running. A task that has not finished has not happened.
+- **A call that disappears is an outage, not an answer.** When the daemon is down
+  every tool fails with a message naming the discovery record it looked for; that
+  means "the box is not running", not "the thing does not exist".
+
+## The tool surface
+
+| Tool | What it does |
+|---|---|
+| `box_overview` | Containers, templates, plugins. Start here. |
+| `box_lifecycle` | start / stop / stop-now / restart / rebuild / remove a container |
+| `box_create` | from-template, from-version, describe, url, browse-paths |
+| `box_resources` | list, read, write, extract, inject, rm, rm-view, view-on, view-off, prune, types, views |
+| `box_plugins` | list, installed, container, add, add-extension, copy, remove-plugin, import, export, export-installed, import-workspace, install-bundle, bundle, prune, graph |
+| `box_templates` | list, show, pull, import, export, remove, prune, catalog |
+| `box_settings` | toolchains, installed, catalog, refresh-catalog, data, references, template-info, template-list, save-mirrors, set-runtime-directory, uninstall-dsh |
+| `box_task` | list, status, cancel, delete |
+| `box_workspace` | list, add |
+| `box_build` | build a template from a boxfile; apply a resource document |
+
+## Rules that are easy to get wrong
+
+1. **This container cannot be restarted from inside it.** `box_lifecycle` refuses
+   when the target is the container you are running in — stopping it kills the host
+   that is executing your call, so the result can never come back. Use `box_task`
+   to watch, and let a person or the CLI act on that container.
+2. **`add`, `import` and `pull` are tasks.** They return a task id, not a finished
+   object. `box_task` with `action: 'status'` is how you learn whether it worked;
+   the task's `logPath` is where the daemon writes the step-by-step log.
+3. **Closing a resource type is not deleting it.** `box_resources` with
+   `view-off` hides the type's tab and keeps its row and every copy taken under it;
+   `rm-view` removes the type itself and leaves the copies alone. Choose deliberately.
+4. **Injection refuses rather than overwrites.** `inject` will not replace an
+   existing destination without `overwrite`, and will not touch a running container
+   without `restart`. That refusal is the safety property, not an error to work around.
+5. **Three actions change the whole box and need `confirm: true`.**
+   `save-mirrors`, `set-runtime-directory`, `uninstall-dsh` affect every container
+   and every future session. The tool refuses without the flag.
+
+## Debugging a page (separate tool family)
+
+The same plugin also registers browser tools against a headless Chromium session:
+`box_page_text`, `box_click_element`, `box_click_at`, `box_type_text`, `box_press_key`,
+`box_scroll`, `box_screenshot`, `box_console`, `box_set_viewport`, `box_set_browser`,
+`box_close`.
+
+When using them, always start with the observation tool and act only on what it
+returned. The tool descriptions carry the full workflow; follow them.
+
+## Worked example: take a resource copy and check it landed
+
+1. `box_overview` -> find the container id, e.g. `container-<timestamp>`.
+2. `box_resources` with `action: 'list'` and that `containerId` -> see which kinds
+   exist and where.
+3. `box_resources` with `action: 'extract'`, `kind: 'sessions'` -> returns a task id.
+4. `box_task` with `action: 'status'`, that id -> `succeeded` means the copy exists.
+5. `box_resources` with `action: 'stored'` -> confirm the new copy is listed.
+
+If a step fails, the daemon's message names what it refused and why. Read it; do not
+retry with a different flag to see if that works.