Skip to content

The agent that grows with you

docs(skills): regenerate skill pages for the document-skill and tmux recipe edits

Tekniumad09ca5b4421
diff --git a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
index a0f39f317ed..c9ed3dd4f6c 100644
--- a/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
+++ b/website/docs/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent.md
@@ -158,23 +158,34 @@ terminal(command="hermes chat -q 'Set up CI/CD for ~/myapp'", background=true)
### Interactive PTY Mode (via tmux)
-Hermes uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning:
+Hermes uses prompt_toolkit, which requires a real terminal. Use tmux for interactive spawning. Send the text and `Enter` as two `send-keys` calls: text and Enter in one call reach Hermes as one burst, and the Enter lands as a newline inside the message instead of submitting it.
```
# Start
terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'hermes'", timeout=10)
# Wait for startup, then send a message
-terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)
+terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' && sleep 0.5 && tmux send-keys -t agent1 Enter", timeout=15)
# Read output
terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)
# Send follow-up
-terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)
+terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' && sleep 0.5 && tmux send-keys -t agent1 Enter", timeout=5)
# Exit
-terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)
+terminal(command="tmux send-keys -t agent1 '/exit' && sleep 0.5 && tmux send-keys -t agent1 Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)
+```
+
+**No tmux** (`command -v tmux` prints nothing, e.g. an older Hermes Docker image): run Hermes as a PTY background process and drive it with `process_manage`. Stdin only exists with `pty=true`. Send the text and the Enter key (`"\r"`) as two separate `write` calls, for the same reason as with tmux; `submit` appends `"\n"`, which Hermes reads as a newline, never as Enter.
+
+```
+terminal(command="hermes", background=true, pty=true) # returns session_id
+process_manage(action="write", session_id="<id>", data="Build a FastAPI auth service")
+process_manage(action="write", session_id="<id>", data="\r")
+process_manage(action="log", session_id="<id>", limit=40) # read the screen
+process_manage(action="write", session_id="<id>", data="/exit")
+process_manage(action="write", session_id="<id>", data="\r")
```
### Multi-Agent Coordination
@@ -182,15 +193,15 @@ terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill
```
# Agent A: backend
terminal(command="tmux new-session -d -s backend -x 120 -y 40 'hermes -w'", timeout=10)
-terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)
+terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' && sleep 0.5 && tmux send-keys -t backend Enter", timeout=15)
# Agent B: frontend
terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'hermes -w'", timeout=10)
-terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)
+terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' && sleep 0.5 && tmux send-keys -t frontend Enter", timeout=15)
# Check progress, relay context between them
terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
-terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)
+terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' && sleep 0.5 && tmux send-keys -t frontend Enter", timeout=5)
```
### Session Resume
@@ -209,7 +220,7 @@ terminal(command="tmux new-session -d -s resumed 'hermes --resume 20260225_14305
- **Use `-w` (worktree mode)** when spawning agents that edit code — prevents git conflicts
- **Set timeouts** for one-shot mode — complex tasks can take 5-10 minutes
- **Use `hermes chat -q` for fire-and-forget** — no PTY needed
-- **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt_toolkit
+- **Prefer tmux for interactive sessions when it is installed** — `capture-pane` reads the rendered screen; the PTY-background fallback only has the raw output log
- **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry
- **"delegate_task is capped at N" reports** — see `references/delegate-task-concurrency-diagnosis.md`. Three real cap paths in Hermes; if none fired, the model is self-limiting and rationalising it as "the runtime caps."
- **"Can $external_app use my Nous Portal subscription / OAuth?"** — see `references/portal-auth-for-third-party-apps.md`. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md b/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md
index 707a695d015..cbc5da4009f 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-docx.md
@@ -53,8 +53,26 @@ fields, and package health checks. It does not render documents itself
## Prerequisites
-- Python 3.10+ with `python-docx` installed:
- `pip install python-docx` (import name is `docx`; lxml comes with it).
+- Python 3.10+ with `python-docx` (import name `docx`; lxml comes with it).
+- Pick the interpreter with `terminal`. Use `python` when it already imports
+ the libraries (the Hermes Docker image ships them); otherwise use a
+ persistent side environment under the Hermes home, which survives container
+ restarts and never touches the Hermes install itself:
+
+ ```bash
+ export PY=python
+ if ! "$PY" -c "import docx" 2>/dev/null; then
+ DOCS_ENV="${HERMES_HOME:-$HOME/.hermes}/environments/documents"
+ PY="$DOCS_ENV/bin/python"
+ "$PY" -c "" 2>/dev/null || python -m venv --clear "$DOCS_ENV" # new, or broken by a Python upgrade
+ "$PY" -c "import docx" 2>/dev/null || "$PY" -m pip install -q python-docx
+ fi
+ "$PY" scripts/docx_create.py --help
+ ```
+
+ Run every helper below with `"$PY"`. On Windows the side interpreter is
+ `%HERMES_HOME%\environments\documents\Scripts\python.exe`. Never
+ `pip install` into the interpreter that runs Hermes.
- Comments `add` uses the native API on python-docx >= 1.2 and an XML
fallback on older versions — both are automatic.
- For image blocks: the image files must exist locally (PNG/JPEG).
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md b/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md
index ddf2d91450f..ee52e0b0e44 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-pdf.md
@@ -48,9 +48,27 @@ Create PDFs from structured specs, build and fill AcroForm forms (with layout li
## Prerequisites
-- Python 3.10+ with `pypdf`, `reportlab`, `pdfplumber`:
- `python -m pip install pypdf reportlab pdfplumber`
-- Optional, for page rasterization (`pdf_page_image.py`, overlay rendering): `python -m pip install pypdfium2`, or poppler's `pdftoppm` on PATH. Scripts fall back pypdfium2 → pdftoppm and report `{"rendered": false, "missing": [...]}` (exit 0) when neither exists.
+- Python 3.10+ with `pypdf`, `reportlab`, `pdfplumber`.
+- Pick the interpreter with `terminal`. Use `python` when it already imports
+ the libraries (the Hermes Docker image ships them); otherwise use a
+ persistent side environment under the Hermes home, which survives container
+ restarts and never touches the Hermes install itself:
+
+ ```bash
+ export PY=python
+ if ! "$PY" -c "import pypdf, reportlab, pdfplumber" 2>/dev/null; then
+ DOCS_ENV="${HERMES_HOME:-$HOME/.hermes}/environments/documents"
+ PY="$DOCS_ENV/bin/python"
+ "$PY" -c "" 2>/dev/null || python -m venv --clear "$DOCS_ENV" # new, or broken by a Python upgrade
+ "$PY" -c "import pypdf, reportlab, pdfplumber" 2>/dev/null || "$PY" -m pip install -q pypdf reportlab pdfplumber
+ fi
+ "$PY" scripts/pdf_create.py --help
+ ```
+
+ Run every helper below with `"$PY"`. On Windows the side interpreter is
+ `%HERMES_HOME%\environments\documents\Scripts\python.exe`. Never
+ `pip install` into the interpreter that runs Hermes.
+- Optional, for page rasterization (`pdf_page_image.py`, overlay rendering): `pypdfium2` installed into that side environment (`"$DOCS_ENV/bin/python" -m pip install pypdfium2`, then use it as `$PY`), or poppler's `pdftoppm` on PATH. Scripts fall back pypdfium2 → pdftoppm and report `{"rendered": false, "missing": [...]}` (exit 0) when neither exists.
- Each helper script checks imports lazily and prints an install hint if a dependency is missing.
## How to Run
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md
index c90ac0690d2..6900ad8940c 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-powerpoint.md
@@ -50,15 +50,33 @@ and slide rendering — all offline, no PowerPoint installation required.
## Prerequisites
-- Python 3.10+ with `python-pptx` installed
- (`pip install python-pptx`).
+- Python 3.10+ with `python-pptx` (import name `pptx`).
+- Pick the interpreter with `terminal`. Use `python` when it already imports
+ the libraries (the Hermes Docker image ships them); otherwise use a
+ persistent side environment under the Hermes home, which survives container
+ restarts and never touches the Hermes install itself:
+
+ ```bash
+ export PY=python
+ if ! "$PY" -c "import pptx" 2>/dev/null; then
+ DOCS_ENV="${HERMES_HOME:-$HOME/.hermes}/environments/documents"
+ PY="$DOCS_ENV/bin/python"
+ "$PY" -c "" 2>/dev/null || python -m venv --clear "$DOCS_ENV" # new, or broken by a Python upgrade
+ "$PY" -c "import pptx" 2>/dev/null || "$PY" -m pip install -q python-pptx
+ fi
+ "$PY" scripts/pptx_create.py --help
+ ```
+
+ Run every helper below with `"$PY"`. On Windows the side interpreter is
+ `%HERMES_HOME%\environments\documents\Scripts\python.exe`. Never
+ `pip install` into the interpreter that runs Hermes.
- Optional: LibreOffice (`soffice`) plus poppler (`pdftoppm` or
`pdftocairo`) for rendering slides to PNGs and for PDF export.
`pptx_render.py` detects both with `shutil.which` and degrades
gracefully (reports `{"rendered": false, "missing": [...]}`, exit 0)
when absent — all create/read/edit operations work without them.
- Check availability via `terminal`:
- `python -c "import pptx; print(pptx.__version__)"` and `which soffice pdftoppm`.
+ `"$PY" -c "import pptx; print(pptx.__version__)"` and `which soffice pdftoppm`.
## How to Run
diff --git a/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md b/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md
index 235b232d73f..3ece82fa551 100644
--- a/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md
+++ b/website/docs/user-guide/skills/bundled/productivity/productivity-xlsx.md
@@ -55,8 +55,27 @@ scripts are argparse CLIs that print JSON and use explicit UTF-8 I/O.
## Prerequisites
-- Python 3.10+ with `openpyxl` (`pip install openpyxl`). No other
- third-party packages are needed; everything else is stdlib.
+- Python 3.10+ with `openpyxl`. No other third-party packages are
+ needed; everything else is stdlib.
+- Pick the interpreter with `terminal`. Use `python` when it already imports
+ the libraries (the Hermes Docker image ships them); otherwise use a
+ persistent side environment under the Hermes home, which survives container
+ restarts and never touches the Hermes install itself:
+
+ ```bash
+ export PY=python
+ if ! "$PY" -c "import openpyxl" 2>/dev/null; then
+ DOCS_ENV="${HERMES_HOME:-$HOME/.hermes}/environments/documents"
+ PY="$DOCS_ENV/bin/python"
+ "$PY" -c "" 2>/dev/null || python -m venv --clear "$DOCS_ENV" # new, or broken by a Python upgrade
+ "$PY" -c "import openpyxl" 2>/dev/null || "$PY" -m pip install -q openpyxl
+ fi
+ "$PY" scripts/xlsx_create.py --help
+ ```
+
+ Run every helper below with `"$PY"`. On Windows the side interpreter is
+ `%HERMES_HOME%\environments\documents\Scripts\python.exe`. Never
+ `pip install` into the interpreter that runs Hermes.
- Optional: LibreOffice (`soffice`) for headless recalculation or
format conversion.
diff --git a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
index 60a9dc20bc8..e27251af3d2 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-excel-author.md
@@ -43,10 +43,22 @@ Adapted from Anthropic's `xlsx-author` and `audit-xls` skills in the [anthropics
## Setup
+Use `python` when it already imports `openpyxl` (the Hermes Docker image
+ships it). Otherwise install into a persistent side environment under the
+Hermes home, never into the interpreter that runs Hermes:
+
```bash
-pip install "openpyxl>=3.0"
+export PY=python
+if ! "$PY" -c "import openpyxl" 2>/dev/null; then
+ DOCS_ENV="${HERMES_HOME:-$HOME/.hermes}/environments/documents"
+ PY="$DOCS_ENV/bin/python"
+ "$PY" -c "" 2>/dev/null || python -m venv --clear "$DOCS_ENV"
+ "$PY" -c "import openpyxl" 2>/dev/null || "$PY" -m pip install -q "openpyxl>=3.0"
+fi
```
+Run the model-building Python with `"$PY"`.
+
## Core conventions (non-negotiable)
### Blue / black / green cell color
diff --git a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
index 22b1bd39fea..86095104a35 100644
--- a/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
+++ b/website/docs/user-guide/skills/optional/finance/finance-pptx-author.md
@@ -44,10 +44,22 @@ For the broader, already-shipped PowerPoint authoring skill (slides, speaker not
## Setup
+Use `python` when it already imports `pptx` (the Hermes Docker image ships
+it). Otherwise install into a persistent side environment under the Hermes
+home, never into the interpreter that runs Hermes:
+
```bash
-pip install "python-pptx>=0.6"
+export PY=python
+if ! "$PY" -c "import pptx" 2>/dev/null; then
+ DOCS_ENV="${HERMES_HOME:-$HOME/.hermes}/environments/documents"
+ PY="$DOCS_ENV/bin/python"
+ "$PY" -c "" 2>/dev/null || python -m venv --clear "$DOCS_ENV"
+ "$PY" -c "import pptx" 2>/dev/null || "$PY" -m pip install -q "python-pptx>=0.6"
+fi
```
+Run the deck-building Python with `"$PY"`.
+
## Core conventions
### One idea per slide