mindroom 2026.4.332__tar.gz → 2026.5.0__tar.gz

{mindroom-2026.4.332 → mindroom-2026.5.0}/.github/scripts/generate_skill_references.py

@@ -8,6 +8,7 @@ import subprocess
 import tempfile
 import tomllib
 from dataclasses import dataclass
+from itertools import pairwise
 from pathlib import Path
 from typing import Any
 
@@ -153,13 +154,66 @@ def _copy_main_outputs(site_dir: Path) -> None:
         shutil.copyfile(source, REFERENCES_DIR / filename)
 
 
-def _flatten_page_references(site_dir: Path) -> dict[str, str]:
+def _strip_frontmatter(text: str) -> str:
+    if not text.startswith("---\n"):
+        return text
+
+    _, separator, rest = text[4:].partition("\n---\n")
+    return rest if separator else text
+
+
+def _source_paragraph_lines(source_text: str) -> list[list[str]]:
+    paragraphs: list[list[str]] = []
+    current: list[str] = []
+    in_code = False
+
+    for line in _strip_frontmatter(source_text).splitlines():
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_code = not in_code
+
+        starts_block = (
+            in_code
+            or not stripped
+            or line.startswith((" ", "\t"))
+            or stripped.startswith(("#", "-", "*", "|", ">", "```", "===", "!!!"))
+            or stripped[0].isdigit()
+        )
+        if starts_block:
+            if current:
+                paragraphs.append(current)
+                current = []
+            continue
+
+        current.append(stripped)
+
+    if current:
+        paragraphs.append(current)
+
+    return paragraphs
+
+
+def _restore_source_line_breaks(rendered_text: str, source_text: str) -> str:
+    for paragraph in _source_paragraph_lines(source_text):
+        for left, right in pairwise(paragraph):
+            rendered_text = rendered_text.replace(f"{left} {right}", f"{left}\n{right}")
+
+    return rendered_text
+
+
+def _flatten_page_references(site_dir: Path, nav_pages: list[NavPage]) -> dict[str, str]:
     built_to_reference: dict[str, str] = {}
-    for source in sorted(site_dir.rglob("*.md")):
-        relative = source.relative_to(site_dir).as_posix()
-        reference_name = f"page__{relative.replace('/', '__')}"
-        shutil.copyfile(source, REFERENCES_DIR / reference_name)
-        built_to_reference[relative] = reference_name
+    for page in nav_pages:
+        generated = site_dir / page.built_path
+        assert generated.exists(), f"Expected generated page: {generated}"
+        source_path = DOCS_DIR / page.source_path
+        assert source_path.exists(), f"Expected docs source page: {source_path}"
+        reference_name = f"page__{page.built_path.replace('/', '__')}"
+        rendered_text = generated.read_text(encoding="utf-8")
+        source_text = source_path.read_text(encoding="utf-8")
+        restored_text = _restore_source_line_breaks(rendered_text, source_text)
+        (REFERENCES_DIR / reference_name).write_text(restored_text, encoding="utf-8")
+        built_to_reference[page.built_path] = reference_name
     return built_to_reference
 
 
@@ -206,7 +260,7 @@ def main() -> None:
 
         _clear_reference_dir()
         _copy_main_outputs(generated_site_dir)
-        built_to_reference = _flatten_page_references(generated_site_dir)
+        built_to_reference = _flatten_page_references(generated_site_dir, nav_pages)
         _write_reference_index(nav_pages, built_to_reference)
 
     CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)

{mindroom-2026.4.332 → mindroom-2026.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mindroom
-Version: 2026.4.332
+Version: 2026.5.0
 Summary: A universal interface for AI agents with persistent memory, where every conversation has a home
 Project-URL: documentation, https://github.com/mindroom-ai/mindroom
 Project-URL: homepage, https://github.com/mindroom-ai/mindroom

{mindroom-2026.4.332 → mindroom-2026.5.0}/docs/attachments.md

@@ -85,6 +85,7 @@ For worker-routed agents, prefer `get_attachment("att_...", mindroom_output_path
 `mindroom_output_path` must be a file path relative to the agent workspace.
 It must not be empty, absolute, point at the workspace root, contain `..` or NUL bytes, or use environment or user expansion.
 When the save succeeds, the response includes `mindroom_tool_output` with `status: "saved_to_file"`, `path`, byte count, `format: "binary"`, and `sha256`.
+In worker-routed shell and python tools, that workspace is also exposed as `~`, `$HOME`, and `$MINDROOM_AGENT_WORKSPACE`, so `incoming/file.ext` and `~/incoming/file.ext` refer to the same saved file.
 
 `attachment_ids` accepts only context attachment IDs (`att_*`).
 `attachment_file_paths` accepts local file paths and auto-registers them in the current context before sending.

{mindroom-2026.4.332 → mindroom-2026.5.0}/docs/configuration/agents.md

@@ -344,7 +344,8 @@ Isolation depends on the worker backend:
 
 Use `user_agent` if you need per-agent filesystem isolation.
 
-For per-workspace env that an agent can edit (PATH, npm/pip cache locations, etc.), drop a `.mindroom/worker-env.sh` script in the agent workspace; MindRoom sources it before each worker-routed `shell` or `python` request.
+For per-workspace env that an agent can edit (PATH, package indexes, npm cache locations, etc.), drop a `.mindroom/worker-env.sh` script in the agent workspace; MindRoom sources it before each worker-routed `shell` or `python` request.
+MindRoom-owned workspace identity, cache, and virtualenv env names are reasserted after the hook, so hooks cannot redirect `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `PYTHONPYCACHEPREFIX`, or `VIRTUAL_ENV`.
 With `worker_scope: user`, the same runtime can move between several agent workspaces, and the hook is discovered from the current request's workspace — different agents get different overlays automatically.
 See [Workspace env hook](../deployment/sandbox-proxy.md#workspace-env-hook-mindroomworker-envsh) for filename, filtering, and failure semantics.
 

{mindroom-2026.4.332 → mindroom-2026.5.0}/docs/deployment/kubernetes.md

@@ -168,7 +168,8 @@ Important behavior and constraints:
 - `google_vertex_adc` is intentionally unsupported for dedicated workers because workers do not receive ADC files or `GOOGLE_APPLICATION_CREDENTIALS`; keep Vertex ADC usage in the primary runtime.
 - Dedicated worker runtime env stays deny-by-default for provider and arbitrary `.env` values, while basic runtime plumbing such as `PATH`, `VIRTUAL_ENV`, and linker vars is set separately.
 - This matches the broader sandbox-proxy contract for `python` and `shell`: proxied execution is intentionally stricter than direct local execution and does not inherit ordinary runtime `.env` or provider env by default.
-- For agent-editable per-workspace env (extra PATH entries, npm/pip cache dirs, etc.), use the request-time `.mindroom/worker-env.sh` overlay documented in [Sandbox Proxy Isolation](sandbox-proxy.md#workspace-env-hook-mindroomworker-envsh). The overlay is sourced inside the running worker per request, so it does not change the worker Deployment, the startup manifest, the pod-template hash, or any Helm value, and does not require a worker restart when edited.
+- For agent-editable per-workspace env (extra PATH entries, package indexes, npm cache dirs, etc.), use the request-time `.mindroom/worker-env.sh` overlay documented in [Sandbox Proxy Isolation](sandbox-proxy.md#workspace-env-hook-mindroomworker-envsh). The overlay is sourced inside the running worker per request, so it does not change the worker Deployment, the startup manifest, the pod-template hash, or any Helm value, and does not require a worker restart when edited.
+- MindRoom-owned workspace identity, cache, and virtualenv env names remain controlled by the worker runtime and cannot be redirected by `.mindroom/worker-env.sh`: `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `PYTHONPYCACHEPREFIX`, and `VIRTUAL_ENV`.
 - Worker-local caches may still live under `kubernetesWorkerStorageSubpathPrefix/<worker-dir>/`.
 
 ### Storage Requirements

{mindroom-2026.4.332 → mindroom-2026.5.0}/docs/deployment/sandbox-proxy.md

@@ -266,11 +266,24 @@ Use `check_shell_command(handle)` to poll and `kill_shell_command(handle)` to st
 These handles are process-local to the sandbox runner: they survive multiple requests to the same runner process, but not runner restarts.
 To make that work, shell background-handle requests stay owned by the long-lived runner process even when `MINDROOM_SANDBOX_RUNNER_EXECUTION_MODE=subprocess`.
 
+## Workspace home contract
+
+For worker-routed shell or python requests with a resolved workspace, MindRoom sets `HOME` and `MINDROOM_AGENT_WORKSPACE` to that workspace before running the tool.
+This includes agent-routed calls, worker-keyed calls whose prepared runtime has a `base_dir`, and unkeyed static-sidecar calls with an explicit absolute `base_dir` override.
+It also sets `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_STATE_HOME` under that workspace.
+Workspace identity variables and worker cache variables are owned by MindRoom for the request.
+`HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_STATE_HOME` stay under the workspace.
+`XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, and `PYTHONPYCACHEPREFIX` stay under the worker cache directory when a worker root exists.
+`VIRTUAL_ENV` is preserved from the active worker environment and is not pointed at the agent workspace.
+MindRoom reasserts these owned variables after request env passthrough and after `.mindroom/worker-env.sh`, so hooks can read them but cannot redirect them.
+The practical contract is that `pwd`, `~`, `Path.home()`, attachment `mindroom_output_path` saves, and file/coding relative paths all refer to the same workspace.
+For example, after `get_attachment("att_...", mindroom_output_path="incoming/file.txt")`, worker-routed shell can read both `incoming/file.txt` and `~/incoming/file.txt`.
+
 ## Workspace env hook (`.mindroom/worker-env.sh`)
 
 Agents can drop a shell script at `<workspace>/.mindroom/worker-env.sh` to set custom env for worker-routed tool calls without changing config or redeploying.
 
-The runner sources this script with `bash` before each worker-routed `shell` or `python` request, then merges its exported env into the tool's execution environment.
+The runner sources this script with `bash` after applying the workspace home contract and before each worker-routed `shell` or `python` request, then merges its exported env into the tool's execution environment.
 
 **Discovery:**
 
@@ -292,7 +305,7 @@ The runner sources this script with `bash` before each worker-routed `shell` or
 `.mindroom/worker-env.sh` is sourced by bash that inherits the runner's process env, which contains tokens the runner needs to function (sandbox proxy auth, etc.).
 To prevent the runner from leaking its own control-plane credentials to tools, the overlay drops names in a small explicit denylist (`MINDROOM_API_KEY`, `MINDROOM_LOCAL_CLIENT_SECRET`, `MINDROOM_SANDBOX_PROXY_TOKEN`, `MINDROOM_SANDBOX_STARTUP_MANIFEST_PATH`) and any name starting with `MINDROOM_SANDBOX_`.
 Bash bookkeeping vars (`PWD`, `OLDPWD`, `SHLVL`, `_`, `PIPESTATUS`) are also dropped because they're noise, not values the script meant to export.
-Everything else passes through, including service tokens and provider credentials you intentionally export from the hook.
+After MindRoom-owned env names are reasserted, other exported values pass through, including service tokens and provider credentials you intentionally export from the hook.
 If you don't want a value to reach tools, don't export it.
 
 **Limits and failure handling:**

{mindroom-2026.4.332 → mindroom-2026.5.0}/docs/tools/execution-and-coding.md

@@ -181,7 +181,9 @@ kill_shell_command("shell:abcd1234")
 - In authored YAML, `extra_env_passthrough` and `shell_path_prepend` can be written as lists, and MindRoom normalizes them to the tool's comma-or-newline form.
 - Background handles survive multiple requests to the same long-lived runner process, but they do not survive runner restarts.
 - `shell_path_prepend` deduplicates PATH entries and only changes subprocess PATH, not the main MindRoom process PATH.
-- For per-workspace env that an agent can edit on the fly (PATH prefixes, `NPM_CONFIG_PREFIX`, `PIP_INDEX_URL`, etc.), drop a `.mindroom/worker-env.sh` script in the workspace and `export` the values you want — see "Workspace env hook" in `docs/deployment/sandbox-proxy.md`. Example:
+- For per-workspace env that an agent can edit on the fly (PATH prefixes, `NPM_CONFIG_PREFIX`, `NPM_CONFIG_CACHE`, `PIP_INDEX_URL`, etc.), drop a `.mindroom/worker-env.sh` script in the workspace and `export` the values you want — see "Workspace env hook" in `docs/deployment/sandbox-proxy.md`.
+- MindRoom-owned env names are reasserted after the hook and cannot be redirected from `.mindroom/worker-env.sh`: `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `PYTHONPYCACHEPREFIX`, and `VIRTUAL_ENV`.
+- Example:
 
 ```bash
 mkdir -p .mindroom .local/bin .cache/npm
@@ -237,7 +239,8 @@ list_files()
 - `restrict_to_base_dir` only constrains the file helper paths, not what arbitrary Python code can do once executed.
 - `safe_globals` and `safe_locals` are exposed directly from the upstream constructor and are mainly useful for advanced programmatic wiring, not typical hand-written YAML.
 - If you need runtime-scoped environment isolation, rely on worker-routed execution instead of assuming in-process Python emulation is a security boundary.
-- Worker-routed `python` execution also receives `.mindroom/worker-env.sh` overlay env via `os.environ` (e.g., `PIP_INDEX_URL`, `UV_CACHE_DIR`). See "Workspace env hook" in `docs/deployment/sandbox-proxy.md`.
+- Worker-routed `python` execution also receives `.mindroom/worker-env.sh` overlay env via `os.environ` (e.g., `PIP_INDEX_URL`). See "Workspace env hook" in `docs/deployment/sandbox-proxy.md`.
+- Workspace identity, worker cache, and virtualenv env names remain controlled by MindRoom, so hooks cannot redirect `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `PYTHONPYCACHEPREFIX`, or `VIRTUAL_ENV`.
 
 ## [`coding`]
 

{mindroom-2026.4.332 → mindroom-2026.5.0}/docs/tools/matrix-and-attachments.md

@@ -225,6 +225,7 @@ matrix_api(
 `get_attachment()` returns a single attachment record, including the runtime-local path, when called with only an attachment ID.
 `get_attachment(attachment_id, mindroom_output_path="relative/path")` saves the attachment bytes into the agent workspace and returns a `mindroom_tool_output` save receipt with the saved path, byte count, binary format, and SHA256 digest.
 Use `mindroom_output_path` before handing attachments to worker-routed workspace tools such as `file`, `coding`, `python`, or `shell`, because the runtime-local path may not exist inside the worker workspace.
+In worker-routed shell and python tools, the agent workspace is also `~`, `$HOME`, and `$MINDROOM_AGENT_WORKSPACE`, so a saved path like `incoming/file.txt` can also be read as `~/incoming/file.txt`.
 The path must be relative to the workspace and must not be empty, absolute, point at the workspace root, contain `..` or NUL bytes, or use environment or user expansion.
 `register_attachment()` turns a local file path into a new context-scoped `att_*` ID and appends that ID to the current runtime context so later tool calls in the same run can reuse it.
 Attachment records include kind, filename, MIME type, room ID, thread ID, sender, creation time, and an `available` flag that reports whether the local file still exists.

{mindroom-2026.4.332 → mindroom-2026.5.0}/skills/mindroom-docs/references/llms-full.txt

@@ -1517,7 +1517,7 @@ Isolation depends on the worker backend:
 
 Use `user_agent` if you need per-agent filesystem isolation.
 
-For per-workspace env that an agent can edit (PATH, npm/pip cache locations, etc.), drop a `.mindroom/worker-env.sh` script in the agent workspace; MindRoom sources it before each worker-routed `shell` or `python` request. With `worker_scope: user`, the same runtime can move between several agent workspaces, and the hook is discovered from the current request's workspace — different agents get different overlays automatically. See [Workspace env hook](https://docs.mindroom.chat/deployment/sandbox-proxy/#workspace-env-hook-mindroomworker-envsh) for filename, filtering, and failure semantics.
+For per-workspace env that an agent can edit (PATH, package indexes, npm cache locations, etc.), drop a `.mindroom/worker-env.sh` script in the agent workspace; MindRoom sources it before each worker-routed `shell` or `python` request. MindRoom-owned workspace identity, cache, and virtualenv env names are reasserted after the hook, so hooks cannot redirect `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `PYTHONPYCACHEPREFIX`, or `VIRTUAL_ENV`. With `worker_scope: user`, the same runtime can move between several agent workspaces, and the hook is discovered from the current request's workspace — different agents get different overlays automatically. See [Workspace env hook](https://docs.mindroom.chat/deployment/sandbox-proxy/#workspace-env-hook-mindroomworker-envsh) for filename, filtering, and failure semantics.
 
 ### Where Agent Data Lives
 
@@ -2484,7 +2484,9 @@ kill_shell_command("shell:abcd1234")
 - In authored YAML, `extra_env_passthrough` and `shell_path_prepend` can be written as lists, and MindRoom normalizes them to the tool's comma-or-newline form.
 - Background handles survive multiple requests to the same long-lived runner process, but they do not survive runner restarts.
 - `shell_path_prepend` deduplicates PATH entries and only changes subprocess PATH, not the main MindRoom process PATH.
-- For per-workspace env that an agent can edit on the fly (PATH prefixes, `NPM_CONFIG_PREFIX`, `PIP_INDEX_URL`, etc.), drop a `.mindroom/worker-env.sh` script in the workspace and `export` the values you want — see "Workspace env hook" in `docs/deployment/sandbox-proxy.md`. Example:
+- For per-workspace env that an agent can edit on the fly (PATH prefixes, `NPM_CONFIG_PREFIX`, `NPM_CONFIG_CACHE`, `PIP_INDEX_URL`, etc.), drop a `.mindroom/worker-env.sh` script in the workspace and `export` the values you want — see "Workspace env hook" in `docs/deployment/sandbox-proxy.md`.
+- MindRoom-owned env names are reasserted after the hook and cannot be redirected from `.mindroom/worker-env.sh`: `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `PYTHONPYCACHEPREFIX`, and `VIRTUAL_ENV`.
+- Example:
 
 ```
 mkdir -p .mindroom .local/bin .cache/npm
@@ -2536,7 +2538,8 @@ list_files()
 - `restrict_to_base_dir` only constrains the file helper paths, not what arbitrary Python code can do once executed.
 - `safe_globals` and `safe_locals` are exposed directly from the upstream constructor and are mainly useful for advanced programmatic wiring, not typical hand-written YAML.
 - If you need runtime-scoped environment isolation, rely on worker-routed execution instead of assuming in-process Python emulation is a security boundary.
-- Worker-routed `python` execution also receives `.mindroom/worker-env.sh` overlay env via `os.environ` (e.g., `PIP_INDEX_URL`, `UV_CACHE_DIR`). See "Workspace env hook" in `docs/deployment/sandbox-proxy.md`.
+- Worker-routed `python` execution also receives `.mindroom/worker-env.sh` overlay env via `os.environ` (e.g., `PIP_INDEX_URL`). See "Workspace env hook" in `docs/deployment/sandbox-proxy.md`.
+- Workspace identity, worker cache, and virtualenv env names remain controlled by MindRoom, so hooks cannot redirect `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `PYTHONPYCACHEPREFIX`, or `VIRTUAL_ENV`.
 
 ## \[`coding`\]
 
@@ -5646,7 +5649,7 @@ matrix_api(
 
 ### What It Does
 
-`attachments` exposes `list_attachments()`, `get_attachment()`, and `register_attachment()`. `list_attachments()` returns the attachment IDs currently available in tool runtime context, the resolved metadata payloads, and any `missing_attachment_ids`. `get_attachment()` returns a single attachment record, including the runtime-local path, when called with only an attachment ID. `get_attachment(attachment_id, mindroom_output_path="relative/path")` saves the attachment bytes into the agent workspace and returns a `mindroom_tool_output` save receipt with the saved path, byte count, binary format, and SHA256 digest. Use `mindroom_output_path` before handing attachments to worker-routed workspace tools such as `file`, `coding`, `python`, or `shell`, because the runtime-local path may not exist inside the worker workspace. The path must be relative to the workspace and must not be empty, absolute, point at the workspace root, contain `..` or NUL bytes, or use environment or user expansion. `register_attachment()` turns a local file path into a new context-scoped `att_*` ID and appends that ID to the current runtime context so later tool calls in the same run can reuse it. Attachment records include kind, filename, MIME type, room ID, thread ID, sender, creation time, and an `available` flag that reports whether the local file still exists. This tool does not send files by itself, but its IDs can be passed to `matrix_message` for `send`, `reply`, or `thread-reply`.
+`attachments` exposes `list_attachments()`, `get_attachment()`, and `register_attachment()`. `list_attachments()` returns the attachment IDs currently available in tool runtime context, the resolved metadata payloads, and any `missing_attachment_ids`. `get_attachment()` returns a single attachment record, including the runtime-local path, when called with only an attachment ID. `get_attachment(attachment_id, mindroom_output_path="relative/path")` saves the attachment bytes into the agent workspace and returns a `mindroom_tool_output` save receipt with the saved path, byte count, binary format, and SHA256 digest. Use `mindroom_output_path` before handing attachments to worker-routed workspace tools such as `file`, `coding`, `python`, or `shell`, because the runtime-local path may not exist inside the worker workspace. In worker-routed shell and python tools, the agent workspace is also `~`, `$HOME`, and `$MINDROOM_AGENT_WORKSPACE`, so a saved path like `incoming/file.txt` can also be read as `~/incoming/file.txt`. The path must be relative to the workspace and must not be empty, absolute, point at the workspace root, contain `..` or NUL bytes, or use environment or user expansion. `register_attachment()` turns a local file path into a new context-scoped `att_*` ID and appends that ID to the current runtime context so later tool calls in the same run can reuse it. Attachment records include kind, filename, MIME type, room ID, thread ID, sender, creation time, and an `available` flag that reports whether the local file still exists. This tool does not send files by itself, but its IDs can be passed to `matrix_message` for `send`, `reply`, or `thread-reply`.
 
 ### Configuration
 
@@ -9591,7 +9594,7 @@ agents:
 | `get_attachment(attachment_id, mindroom_output_path?)` | Return one context attachment record, or save its bytes to a workspace-relative path and return a save receipt                                 |
 | `register_attachment(file_path)`                       | Register a local file path as a context attachment ID (`att_*`)                                                                                |
 
-When `mindroom_output_path` is omitted, `get_attachment()` returns the attachment metadata response, including the runtime-local `local_path`. For worker-routed agents, prefer `get_attachment("att_...", mindroom_output_path="incoming/file.ext")` before processing an attachment with `file`, `coding`, `python`, or `shell`, because the runtime-local path may not exist inside the worker workspace. `mindroom_output_path` must be a file path relative to the agent workspace. It must not be empty, absolute, point at the workspace root, contain `..` or NUL bytes, or use environment or user expansion. When the save succeeds, the response includes `mindroom_tool_output` with `status: "saved_to_file"`, `path`, byte count, `format: "binary"`, and `sha256`.
+When `mindroom_output_path` is omitted, `get_attachment()` returns the attachment metadata response, including the runtime-local `local_path`. For worker-routed agents, prefer `get_attachment("att_...", mindroom_output_path="incoming/file.ext")` before processing an attachment with `file`, `coding`, `python`, or `shell`, because the runtime-local path may not exist inside the worker workspace. `mindroom_output_path` must be a file path relative to the agent workspace. It must not be empty, absolute, point at the workspace root, contain `..` or NUL bytes, or use environment or user expansion. When the save succeeds, the response includes `mindroom_tool_output` with `status: "saved_to_file"`, `path`, byte count, `format: "binary"`, and `sha256`. In worker-routed shell and python tools, that workspace is also exposed as `~`, `$HOME`, and `$MINDROOM_AGENT_WORKSPACE`, so `incoming/file.ext` and `~/incoming/file.ext` refer to the same saved file.
 
 `attachment_ids` accepts only context attachment IDs (`att_*`). `attachment_file_paths` accepts local file paths and auto-registers them in the current context before sending. Use `matrix_message(action="send"|"reply"|"thread-reply", attachment_ids=..., attachment_file_paths=...)` to send attachments.
 
@@ -12110,11 +12113,15 @@ If proxied shell commands need extra PATH entries such as wrapper directories, c
 
 Shell commands that exceed their timeout return a background handle. Use `check_shell_command(handle)` to poll and `kill_shell_command(handle)` to stop the process. These handles are process-local to the sandbox runner: they survive multiple requests to the same runner process, but not runner restarts. To make that work, shell background-handle requests stay owned by the long-lived runner process even when `MINDROOM_SANDBOX_RUNNER_EXECUTION_MODE=subprocess`.
 
+## Workspace home contract
+
+For worker-routed shell or python requests with a resolved workspace, MindRoom sets `HOME` and `MINDROOM_AGENT_WORKSPACE` to that workspace before running the tool. This includes agent-routed calls, worker-keyed calls whose prepared runtime has a `base_dir`, and unkeyed static-sidecar calls with an explicit absolute `base_dir` override. It also sets `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_STATE_HOME` under that workspace. Workspace identity variables and worker cache variables are owned by MindRoom for the request. `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `XDG_STATE_HOME` stay under the workspace. `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, and `PYTHONPYCACHEPREFIX` stay under the worker cache directory when a worker root exists. `VIRTUAL_ENV` is preserved from the active worker environment and is not pointed at the agent workspace. MindRoom reasserts these owned variables after request env passthrough and after `.mindroom/worker-env.sh`, so hooks can read them but cannot redirect them. The practical contract is that `pwd`, `~`, `Path.home()`, attachment `mindroom_output_path` saves, and file/coding relative paths all refer to the same workspace. For example, after `get_attachment("att_...", mindroom_output_path="incoming/file.txt")`, worker-routed shell can read both `incoming/file.txt` and `~/incoming/file.txt`.
+
 ## Workspace env hook (`.mindroom/worker-env.sh`)
 
 Agents can drop a shell script at `<workspace>/.mindroom/worker-env.sh` to set custom env for worker-routed tool calls without changing config or redeploying.
 
-The runner sources this script with `bash` before each worker-routed `shell` or `python` request, then merges its exported env into the tool's execution environment.
+The runner sources this script with `bash` after applying the workspace home contract and before each worker-routed `shell` or `python` request, then merges its exported env into the tool's execution environment.
 
 **Discovery:**
 
@@ -12133,7 +12140,7 @@ The runner sources this script with `bash` before each worker-routed `shell` or
 
 **Filtering:**
 
-`.mindroom/worker-env.sh` is sourced by bash that inherits the runner's process env, which contains tokens the runner needs to function (sandbox proxy auth, etc.). To prevent the runner from leaking its own control-plane credentials to tools, the overlay drops names in a small explicit denylist (`MINDROOM_API_KEY`, `MINDROOM_LOCAL_CLIENT_SECRET`, `MINDROOM_SANDBOX_PROXY_TOKEN`, `MINDROOM_SANDBOX_STARTUP_MANIFEST_PATH`) and any name starting with `MINDROOM_SANDBOX_`. Bash bookkeeping vars (`PWD`, `OLDPWD`, `SHLVL`, `_`, `PIPESTATUS`) are also dropped because they're noise, not values the script meant to export. Everything else passes through, including service tokens and provider credentials you intentionally export from the hook. If you don't want a value to reach tools, don't export it.
+`.mindroom/worker-env.sh` is sourced by bash that inherits the runner's process env, which contains tokens the runner needs to function (sandbox proxy auth, etc.). To prevent the runner from leaking its own control-plane credentials to tools, the overlay drops names in a small explicit denylist (`MINDROOM_API_KEY`, `MINDROOM_LOCAL_CLIENT_SECRET`, `MINDROOM_SANDBOX_PROXY_TOKEN`, `MINDROOM_SANDBOX_STARTUP_MANIFEST_PATH`) and any name starting with `MINDROOM_SANDBOX_`. Bash bookkeeping vars (`PWD`, `OLDPWD`, `SHLVL`, `_`, `PIPESTATUS`) are also dropped because they're noise, not values the script meant to export. After MindRoom-owned env names are reasserted, other exported values pass through, including service tokens and provider credentials you intentionally export from the hook. If you don't want a value to reach tools, don't export it.
 
 **Limits and failure handling:**
 
@@ -12414,7 +12421,8 @@ Important behavior and constraints:
 - `google_vertex_adc` is intentionally unsupported for dedicated workers because workers do not receive ADC files or `GOOGLE_APPLICATION_CREDENTIALS`; keep Vertex ADC usage in the primary runtime.
 - Dedicated worker runtime env stays deny-by-default for provider and arbitrary `.env` values, while basic runtime plumbing such as `PATH`, `VIRTUAL_ENV`, and linker vars is set separately.
 - This matches the broader sandbox-proxy contract for `python` and `shell`: proxied execution is intentionally stricter than direct local execution and does not inherit ordinary runtime `.env` or provider env by default.
-- For agent-editable per-workspace env (extra PATH entries, npm/pip cache dirs, etc.), use the request-time `.mindroom/worker-env.sh` overlay documented in [Sandbox Proxy Isolation](https://docs.mindroom.chat/deployment/sandbox-proxy/#workspace-env-hook-mindroomworker-envsh). The overlay is sourced inside the running worker per request, so it does not change the worker Deployment, the startup manifest, the pod-template hash, or any Helm value, and does not require a worker restart when edited.
+- For agent-editable per-workspace env (extra PATH entries, package indexes, npm cache dirs, etc.), use the request-time `.mindroom/worker-env.sh` overlay documented in [Sandbox Proxy Isolation](https://docs.mindroom.chat/deployment/sandbox-proxy/#workspace-env-hook-mindroomworker-envsh). The overlay is sourced inside the running worker per request, so it does not change the worker Deployment, the startup manifest, the pod-template hash, or any Helm value, and does not require a worker restart when edited.
+- MindRoom-owned workspace identity, cache, and virtualenv env names remain controlled by the worker runtime and cannot be redirected by `.mindroom/worker-env.sh`: `HOME`, `MINDROOM_AGENT_WORKSPACE`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`, `PIP_CACHE_DIR`, `UV_CACHE_DIR`, `PYTHONPYCACHEPREFIX`, and `VIRTUAL_ENV`.
 - Worker-local caches may still live under `kubernetesWorkerStorageSubpathPrefix/<worker-dir>/`.
 
 ### Storage Requirements

{mindroom-2026.4.332 → mindroom-2026.5.0}/skills/mindroom-docs/references/page__architecture__matrix__index.md

@@ -44,7 +44,10 @@ Rooms are auto-created via `_ensure_room_exists()` (private) and `ensure_all_roo
 
 MindRoom emits thread replies following [MSC3440](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3440-threading-via-relations.md), using `m.relates_to` with `rel_type: m.thread`.
 
-Explicit `m.thread` metadata remains the primary source of thread conversation context. For clients or bridges that send plain replies without thread metadata (`m.in_reply_to` but no `rel_type: m.thread`), MindRoom applies a transitive compatibility rule. If a reply chain eventually reaches explicit thread `T` or a proven thread root, MindRoom treats the new reply as part of `T`. Replies that never reach threaded context stay room-level.
+Explicit `m.thread` metadata remains the primary source of thread conversation context.
+For clients or bridges that send plain replies without thread metadata (`m.in_reply_to` but no `rel_type: m.thread`), MindRoom applies a transitive compatibility rule.
+If a reply chain eventually reaches explicit thread `T` or a proven thread root, MindRoom treats the new reply as part of `T`.
+Replies that never reach threaded context stay room-level.
 
 ### Resolution Rules
 
@@ -129,11 +132,16 @@ Messages exceeding the 64KB Matrix event limit are automatically handled by `pre
 
 ## Response Tracking
 
-MindRoom prevents duplicate responses using a `ResponseTracker` that records which events have already been processed. When a sync reconnection or retry delivers the same event twice, the tracker suppresses the duplicate so only one agent response is sent per triggering message. Tracking state is persisted under `mindroom_data/tracking/` and survives restarts.
+MindRoom prevents duplicate responses using a `ResponseTracker` that records which events have already been processed.
+When a sync reconnection or retry delivers the same event twice, the tracker suppresses the duplicate so only one agent response is sent per triggering message.
+Tracking state is persisted under `mindroom_data/tracking/` and survives restarts.
 
 ## Room Cleanup
 
-On startup, MindRoom detects orphaned bot memberships left over from a previous configuration. When an agent is removed from `config.yaml`, its Matrix bot account may still be a member of rooms it previously joined. The cleanup process leaves those rooms safely without ejecting currently configured entities from their required rooms. This runs automatically — no manual intervention is needed.
+On startup, MindRoom detects orphaned bot memberships left over from a previous configuration.
+When an agent is removed from `config.yaml`, its Matrix bot account may still be a member of rooms it previously joined.
+The cleanup process leaves those rooms safely without ejecting currently configured entities from their required rooms.
+This runs automatically — no manual intervention is needed.
 
 ## Identity Management
 
@@ -162,7 +170,8 @@ matrix_space:
   name: MindRoom       # Display name for the Space
 ```
 
-When enabled, `ensure_root_space()` creates the Space on first boot (or resolves an existing one by alias), links all managed rooms as children, and sets the Space avatar from workspace or bundled assets. The Space name is reconciled on each startup to match the configured value.
+When enabled, `ensure_root_space()` creates the Space on first boot (or resolves an existing one by alias), links all managed rooms as children, and sets the Space avatar from workspace or bundled assets.
+The Space name is reconciled on each startup to match the configured value.
 
 ## Configuration
 

{mindroom-2026.4.332 → mindroom-2026.5.0}/skills/mindroom-docs/references/page__architecture__orchestration__index.md

@@ -119,7 +119,8 @@ Event callbacks are wrapped in `_create_task_wrapper()` to run as background tas
 1. Check for team formation or individual response
 1. Generate response and store memory
 
-**Message edits**: When a user edits a message that already received an agent response, the agent regenerates its response for the updated content. The agent edits its own previous reply in place rather than sending a new message. Edits from other agents are ignored, and the feature requires that the original response event ID is tracked by the `ResponseTracker`.
+**Message edits**: When a user edits a message that already received an agent response, the agent regenerates its response for the updated content. The agent edits its own previous reply in place rather than sending a new message.
+Edits from other agents are ignored, and the feature requires that the original response event ID is tracked by the `ResponseTracker`.
 
 **`_on_media_message`**: Handles media events (images, videos, files, and audio). Downloads and decrypts media data, then processes it through the agent. When no agent is mentioned, AI routing is used to select the appropriate agent, similar to text messages.
 

{mindroom-2026.4.332 → mindroom-2026.5.0}/skills/mindroom-docs/references/page__attachments__index.md

@@ -1,6 +1,7 @@
 # Attachments
 
-MindRoom can process files, images, audio, and videos sent to Matrix rooms, passing them to agents for analysis or action. Supported attachment kinds: `audio`, `file`, `image`, `video`.
+MindRoom can process files, images, audio, and videos sent to Matrix rooms, passing them to agents for analysis or action.
+Supported attachment kinds: `audio`, `file`, `image`, `video`.
 
 ## Overview
 
@@ -41,13 +42,15 @@ Attachments work in both direct messages and threads, and with both individual a
 
 ## Attachment IDs
 
-Each uploaded file or video is assigned a stable attachment ID (e.g., `att_abc123`). The agent's prompt is augmented with the available IDs:
+Each uploaded file or video is assigned a stable attachment ID (e.g., `att_abc123`).
+The agent's prompt is augmented with the available IDs:
 
 ```
 Available attachment IDs: att_abc123. Use tool calls to inspect or process them.
 ```
 
-Attachment IDs are **context-scoped** -- an attachment registered in one room or thread is not accessible from another. This prevents cross-room data leakage for ID-based access. Voice raw-audio fallback uses the same attachment ID mechanism; see [Voice Fallback](https://docs.mindroom.chat/voice/#voice-fallback-no-stt-available).
+Attachment IDs are **context-scoped** -- an attachment registered in one room or thread is not accessible from another.
+This prevents cross-room data leakage for ID-based access. Voice raw-audio fallback uses the same attachment ID mechanism; see [Voice Fallback](https://docs.mindroom.chat/voice/#voice-fallback-no-stt-available).
 
 ## The `attachments` Tool
 
@@ -72,17 +75,26 @@ agents:
 | `get_attachment(attachment_id, mindroom_output_path?)` | Return one context attachment record, or save its bytes to a workspace-relative path and return a save receipt                                 |
 | `register_attachment(file_path)`                       | Register a local file path as a context attachment ID (`att_*`)                                                                                |
 
-When `mindroom_output_path` is omitted, `get_attachment()` returns the attachment metadata response, including the runtime-local `local_path`. For worker-routed agents, prefer `get_attachment("att_...", mindroom_output_path="incoming/file.ext")` before processing an attachment with `file`, `coding`, `python`, or `shell`, because the runtime-local path may not exist inside the worker workspace. `mindroom_output_path` must be a file path relative to the agent workspace. It must not be empty, absolute, point at the workspace root, contain `..` or NUL bytes, or use environment or user expansion. When the save succeeds, the response includes `mindroom_tool_output` with `status: "saved_to_file"`, `path`, byte count, `format: "binary"`, and `sha256`.
+When `mindroom_output_path` is omitted, `get_attachment()` returns the attachment metadata response, including the runtime-local `local_path`.
+For worker-routed agents, prefer `get_attachment("att_...", mindroom_output_path="incoming/file.ext")` before processing an attachment with `file`, `coding`, `python`, or `shell`, because the runtime-local path may not exist inside the worker workspace.
+`mindroom_output_path` must be a file path relative to the agent workspace.
+It must not be empty, absolute, point at the workspace root, contain `..` or NUL bytes, or use environment or user expansion.
+When the save succeeds, the response includes `mindroom_tool_output` with `status: "saved_to_file"`, `path`, byte count, `format: "binary"`, and `sha256`.
+In worker-routed shell and python tools, that workspace is also exposed as `~`, `$HOME`, and `$MINDROOM_AGENT_WORKSPACE`, so `incoming/file.ext` and `~/incoming/file.ext` refer to the same saved file.
 
-`attachment_ids` accepts only context attachment IDs (`att_*`). `attachment_file_paths` accepts local file paths and auto-registers them in the current context before sending. Use `matrix_message(action="send"|"reply"|"thread-reply", attachment_ids=..., attachment_file_paths=...)` to send attachments.
+`attachment_ids` accepts only context attachment IDs (`att_*`).
+`attachment_file_paths` accepts local file paths and auto-registers them in the current context before sending.
+Use `matrix_message(action="send"|"reply"|"thread-reply", attachment_ids=..., attachment_file_paths=...)` to send attachments.
 
 ### Why use this tool?
 
-Not all AI models support direct file inputs. The `attachments` tool lets any model work with files by calling tools that operate on attachment IDs, even if the model itself cannot ingest the raw bytes.
+Not all AI models support direct file inputs.
+The `attachments` tool lets any model work with files by calling tools that operate on attachment IDs, even if the model itself cannot ingest the raw bytes.
 
 ## Encryption
 
-Both unencrypted and E2E encrypted files and videos are supported. Encrypted media is decrypted transparently using the key material from the Matrix event.
+Both unencrypted and E2E encrypted files and videos are supported.
+Encrypted media is decrypted transparently using the key material from the Matrix event.
 
 ## Caching
 
@@ -90,7 +102,8 @@ AI response caching is automatically skipped when files, images, audio, or video
 
 ## Retention
 
-MindRoom automatically prunes attachment metadata and managed `incoming_media/` files older than 30 days. Pruning runs opportunistically during new attachment registration.
+MindRoom automatically prunes attachment metadata and managed `incoming_media/` files older than 30 days.
+Pruning runs opportunistically during new attachment registration.
 
 ## Limitations
 

{mindroom-2026.4.332 → mindroom-2026.5.0}/skills/mindroom-docs/references/page__chat-commands__index.md

@@ -1,6 +1,7 @@
 # Chat Commands
 
-MindRoom provides chat commands that users can type in any Matrix room where MindRoom agents are present. Commands start with `!` and are handled by the router agent.
+MindRoom provides chat commands that users can type in any Matrix room where MindRoom agents are present.
+Commands start with `!` and are handled by the router agent.
 
 ## Quick Reference
 
@@ -17,15 +18,19 @@ MindRoom provides chat commands that users can type in any Matrix room where Min
 
 ## Who Handles Commands
 
-The **router** handles all commands exclusively. Even in single-agent rooms, commands are always processed by the router, not the agent. Commands work in both main room messages and within threads.
+The **router** handles all commands exclusively.
+Even in single-agent rooms, commands are always processed by the router, not the agent.
+Commands work in both main room messages and within threads.
 
 Voice messages that contain commands (e.g., spoken `!schedule`) are recognized after transcription and processed the same way.
 
 ## Permission Behavior
 
-Commands are subject to the same authorization rules as normal messages. The sender must be authorized to interact with agents in the room (via `global_users`, `room_permissions`, or `default_room_access`). See [Authorization](https://docs.mindroom.chat/authorization/index.md) for details.
+Commands are subject to the same authorization rules as normal messages.
+The sender must be authorized to interact with agents in the room (via `global_users`, `room_permissions`, or `default_room_access`). See [Authorization](https://docs.mindroom.chat/authorization/index.md) for details.
 
-For `!config set`, only the user who requested the change can confirm or cancel it via reactions. Pending config changes expire after 24 hours.
+For `!config set`, only the user who requested the change can confirm or cancel it via reactions.
+Pending config changes expire after 24 hours.
 
 ## Commands
 
@@ -53,7 +58,8 @@ Show the welcome message for the current room, listing available agents, their r
 
 ### `!schedule`
 
-Schedule a one-time or recurring task using natural language. Tasks run in the thread where they were created.
+Schedule a one-time or recurring task using natural language.
+Tasks run in the thread where they were created.
 
 ```
 !schedule <natural-language-request>
@@ -76,14 +82,16 @@ Schedule a one-time or recurring task using natural language. Tasks run in the t
 
 **Conditional workflows (polling-based):**
 
-Conditional requests are converted to recurring cron-based polling schedules. These are periodic checks, not real event subscriptions.
+Conditional requests are converted to recurring cron-based polling schedules.
+These are periodic checks, not real event subscriptions.
 
 ```
 !schedule If I get an email about "urgent", @phone_agent call me
 !schedule When Bitcoin drops below $40k, @crypto_agent notify me
 ```
 
-Include `@agent_name` in your schedule to target specific agents. The scheduler validates that mentioned agents are available in the room before creating the task.
+Include `@agent_name` in your schedule to target specific agents.
+The scheduler validates that mentioned agents are available in the room before creating the task.
 
 Schedules use the timezone from `config.yaml` (defaults to UTC). See [Scheduling](https://docs.mindroom.chat/scheduling/index.md) for full details.
 
@@ -118,13 +126,15 @@ Replace an existing scheduled task with new timing and content.
 !edit_schedule <task-id> <new-task-description>
 ```
 
-The task description is re-parsed to update timing and content. Schedule type cannot be changed (one-time to recurring or vice versa) -- cancel and recreate instead.
+The task description is re-parsed to update timing and content.
+Schedule type cannot be changed (one-time to recurring or vice versa) -- cancel and recreate instead.
 
 **Aliases:** `!editschedule`, `!edit-schedule`
 
 ### `!config`
 
-View and modify MindRoom configuration from chat. Changes are validated against the Pydantic config schema before applying.
+View and modify MindRoom configuration from chat.
+Changes are validated against the Pydantic config schema before applying.
 
 **View configuration:**
 
@@ -159,7 +169,9 @@ When you use `!config set`, MindRoom:
 1. Adds reaction buttons to the preview message
 1. Waits for the requester to react with ✅ (confirm) or ❌ (cancel)
 
-Only the user who requested the change can confirm or cancel it. Pending changes are persisted in Matrix room state and survive restarts. Unconfirmed changes expire after 24 hours.
+Only the user who requested the change can confirm or cancel it.
+Pending changes are persisted in Matrix room state and survive restarts.
+Unconfirmed changes expire after 24 hours.
 
 Changes are saved to `config.yaml` immediately on confirmation and take effect for new agent interactions.
 
@@ -185,9 +197,12 @@ Plugins are also auto-reloaded on file save, typically about 1-2 seconds after s
 
 MindRoom supports cancelling in-progress responses via a reaction-based stop button, not a chat command.
 
-When `defaults.show_stop_button` is `true` (the default), MindRoom adds a 🛑 reaction to the agent's message while it is generating. React with 🛑 on the message to cancel the response. The agent finalizes the partial text with `**[Response cancelled by user]**`.
+When `defaults.show_stop_button` is `true` (the default), MindRoom adds a 🛑 reaction to the agent's message while it is generating.
+React with 🛑 on the message to cancel the response.
+The agent finalizes the partial text with `**[Response cancelled by user]**`.
 
-The stop button only works on messages currently being generated. Only non-agent users can trigger cancellation — agent reactions are ignored.
+The stop button only works on messages currently being generated.
+Only non-agent users can trigger cancellation — agent reactions are ignored.
 
 See [Streaming — Cancellation](https://docs.mindroom.chat/streaming/#cancellation-and-errors) for details on how cancelled responses are finalized.
 

{mindroom-2026.4.332 → mindroom-2026.5.0}/skills/mindroom-docs/references/page__cli__index.md

@@ -105,7 +105,11 @@ Generate and sync managed avatar assets.
 
 ## avatars generate
 
-Generate missing managed avatar files in the workspace. In a source checkout, generated files are written under `./avatars/`. In containerized deployments, generated overrides are written under the persistent MindRoom storage path. Existing managed files are skipped by default. Use `--force` to overwrite them after changing avatar prompts or styles.
+Generate missing managed avatar files in the workspace.
+In a source checkout, generated files are written under `./avatars/`.
+In containerized deployments, generated overrides are written under the persistent MindRoom storage path.
+Existing managed files are skipped by default.
+Use `--force` to overwrite them after changing avatar prompts or styles.
 
 ```
  Usage: root avatars generate [OPTIONS]
@@ -120,7 +124,9 @@ Generate missing managed avatar files in the workspace. In a source checkout, ge
 
 ## avatars sync
 
-Sync configured room and root-space avatars to Matrix using the initialized router account. Existing Matrix avatars are skipped by default. Use `--force` to replace them.
+Sync configured room and root-space avatars to Matrix using the initialized router account.
+Existing Matrix avatars are skipped by default.
+Use `--force` to replace them.
 
 ```
  Usage: root avatars sync [OPTIONS]
@@ -161,7 +167,8 @@ Runs a series of checks in one pass:
 
 ## config
 
-Manage MindRoom configuration files. The `config` subgroup contains commands for creating, viewing, editing, and validating your `config.yaml`.
+Manage MindRoom configuration files.
+The `config` subgroup contains commands for creating, viewing, editing, and validating your `config.yaml`.
 
 ```
  Usage: root config [OPTIONS] COMMAND [ARGS]...
@@ -211,7 +218,10 @@ mindroom config init --profile public-vertexai-anthropic
 mindroom config init --force
 ```
 
-The `public-codex` profile and `--provider codex` preset generate `provider: codex` with `id: gpt-5.5` and `context_window: 258000`. They set `extra_kwargs.reasoning_effort: medium`. Prompt caching is enabled automatically per active agent session; leave `prompt_cache_key` unset unless you intentionally want to override the derived key. Run `codex login` first so MindRoom can read `~/.codex/auth.json`.
+The `public-codex` profile and `--provider codex` preset generate `provider: codex` with `id: gpt-5.5` and `context_window: 258000`.
+They set `extra_kwargs.reasoning_effort: medium`.
+Prompt caching is enabled automatically per active agent session; leave `prompt_cache_key` unset unless you intentionally want to override the derived key.
+Run `codex login` first so MindRoom can read `~/.codex/auth.json`.
 
 ### config show
 
@@ -230,7 +240,8 @@ mindroom config show --path /custom/path/config.yaml
 
 ### config edit
 
-Open `config.yaml` in your default editor. Editor preference: `$EDITOR` → `$VISUAL` → `nano` → `vim` → `vi`.
+Open `config.yaml` in your default editor.
+Editor preference: `$EDITOR` → `$VISUAL` → `nano` → `vim` → `vi`.
 
 ```
 mindroom config edit
@@ -238,7 +249,9 @@ mindroom config edit
 
 ### config validate
 
-Validate `config.yaml` and check for common issues. Parses the YAML config using Pydantic and reports errors in a friendly format. Also checks whether required API keys are set as environment variables.
+Validate `config.yaml` and check for common issues.
+Parses the YAML config using Pydantic and reports errors in a friendly format.
+Also checks whether required API keys are set as environment variables.
 
 ```
 mindroom config validate