docs: clarify public executor setup surfaces

.dev/refactor/hermes-integration-plan.md

@@ -39,7 +39,7 @@ For this project, Hermes support should not assume plain OpenAI API keys. Many u
 
 ### Expected user flow
 
-Possible final UX:
+Possible final UX (now implemented as explicit print/fix/test steps):
 
 ```bash
 npm install -g @cafitac/hermit-agent
@@ -62,7 +62,7 @@ hermit install --fix-hermes-mcp
 hermes mcp test hermit-channel
 ```
 
-The `mcp add` syntax has been smoke-checked against the local Hermes CLI help/list behavior. A full `hermes mcp test hermit-channel` round trip remains a later smoke because it depends on local Hermes auth/runtime state.
+The `mcp add` syntax and the bounded `hermes mcp test hermit-channel` probe have now been smoke-checked through Hermit's public install helpers. The remaining gap is stronger isolated `HERMES_HOME` automation, not baseline operator readiness.
 
 ## Implementation slices
 
@@ -150,6 +150,7 @@ Suggested remaining smoke:
 Acceptance:
 - Smoke command and expected output are documented.
 - If full isolated Hermes model auth is unavailable, separate MCP wiring smoke from provider/auth smoke.
+- Public README and setup docs point operators at the explicit print/fix/test sequence.
 
 ## Open questions
 

.dev/refactor/roadmap.md

@@ -114,6 +114,12 @@ Acceptance:
 
 Objective: Hermit can be used from Hermes Agent as an executor lane.
 
+Status:
+- Public setup docs now cover Claude Code, Codex, and Hermes Agent separately so each orchestrator path matches the actual setup and runtime boundary.
+- Hermes-facing install surfaces exist in three explicit modes: `hermit install --print-hermes-mcp-config`, `hermit install --fix-hermes-mcp`, and `hermit install --test-hermes-mcp`.
+- Live runtime delivery remains the existing Hermit MCP server path; the Hermes wrapper is a setup/health adapter, not a second runtime.
+- Release smoke has already verified npm and PyPI packages can print, register, and test the Hermes-facing MCP configuration without requiring OpenAI API-key onboarding.
+
 Deliverables:
 - Hermes-facing setup guidance or installer surface.
 - Hermes MCP registration or one-shot subprocess bridge, selected by least fragile path.

README.md

@@ -15,7 +15,7 @@
 
 > Hidden expert. Quiet executor.
 >
-> Hermit is an MCP executor for Claude Code and Codex. Your main agent handles planning, review, and conversation; Hermit quietly handles edits, test runs, refactors, commits, and other mechanical execution on a cheaper local or flat-rate model.
+> Hermit is an MCP executor lane for Claude Code, Codex, and Hermes Agent. Your main agent handles planning, review, and conversation; Hermit quietly handles edits, test runs, refactors, commits, and other mechanical execution on a cheaper local or flat-rate model.
 
 ## How it works
 
@@ -31,13 +31,13 @@
 └──────────────┘
 ```
 
-Claude Code or Codex stays in charge of planning, interviewing, and review. Hermit takes the mechanical path: file edits, test runs, refactors, commits, and MCP-executed follow-through on predictable local or flat-rate execution models. The switch is one word in a slash command: `/foo` → `/foo-hermit`.
+Claude Code, Codex, or Hermes Agent stays in charge of planning, interviewing, and review. Hermit takes the mechanical path: file edits, test runs, refactors, commits, and MCP-executed follow-through on predictable local or flat-rate execution models. In Claude Code the switch is often one word in a slash command: `/foo` → `/foo-hermit`.
 
 Why Hermit stands out:
 - Keep your best reasoning model on the work that needs judgment, not boilerplate execution.
 - Use MCP to turn planner decisions into concrete repo changes, tests, commits, and release operations.
 - Default to predictable local / flat-rate executor routing instead of silently drifting onto a paid hosted fallback.
-- Work with both Claude Code and Codex instead of forcing a single orchestrator stack.
+- Work across Claude Code, Codex, and Hermes Agent instead of forcing a single orchestrator stack.
 
 ## Why not just use Claude Code or Codex directly?
 
@@ -47,7 +47,7 @@ Why Hermit stands out:
 | Repetitive repo work | Expensive or token-heavy | Offloaded to a cheaper MCP executor lane |
 | Multi-step follow-through | Manual context handoff | MCP tasks can carry edits, tests, commits, and release ops through |
 | Default execution cost | Can drift onto paid hosted models | Defaults to local / flat-rate executor routing |
-| Team adoption | Tied to one orchestrator workflow | Works as a shared executor layer across Claude Code and Codex |
+| Team adoption | Tied to one orchestrator workflow | Works as a shared executor layer across Claude Code, Codex, and Hermes Agent |
 
 Hermit is not trying to replace your orchestrator. It gives you a second lane: use the premium model for judgment, and use Hermit for the mechanical throughput that makes repositories expensive to operate at scale.
 
@@ -73,7 +73,19 @@ npm install -g @cafitac/hermit-agent
 hermit
 ```
 
-Requires Node.js 20+ and Python 3.11+. The npm package bootstraps a managed Python runtime under `~/.hermit/` on first run — no repo checkout needed. If Claude Code or Codex integration is still missing, `hermit` will offer guided setup automatically. You can still run `hermit install` directly when you want to force the full setup/repair flow. For CI or smoke checks that must avoid optional external hook installation, use `hermit install --yes --skip-agent-learner` plus any integration-specific skips you need. For Hermes Agent orchestration, start with the non-mutating snippet: `hermit install --print-hermes-mcp-config`. When you explicitly want Hermit to register itself in Hermes via the Hermes CLI, run `hermit install --fix-hermes-mcp`; then verify the live MCP wiring with `hermit install --test-hermes-mcp`.
+Requires Node.js 20+ and Python 3.11+. The npm package bootstraps a managed Python runtime under `~/.hermit/` on first run — no repo checkout needed. If Claude Code or Codex integration is still missing, `hermit` will offer guided setup automatically. You can still run `hermit install` directly when you want to force the full setup/repair flow.
+
+For CI or smoke checks that must avoid optional external hook installation, use `hermit install --yes --skip-agent-learner` plus any integration-specific skips you need.
+
+For Hermes Agent orchestration, start with the non-mutating snippet printer:
+- `hermit install --print-hermes-mcp-config` — print the exact `hermes mcp add ...` command without editing `~/.hermes`
+- `hermit install --fix-hermes-mcp` — explicitly register `hermit-channel` through the Hermes CLI
+- `hermit install --test-hermes-mcp` — run Hermes Agent's live `hermes mcp test hermit-channel` probe without changing config
+
+Setup guides:
+- Claude Code: `docs/cc-setup.md`
+- Codex: `docs/codex-setup.md`
+- Hermes Agent: `docs/hermes-setup.md`
 
 To upgrade: `hermit update`
 
@@ -83,13 +95,13 @@ To upgrade: `hermit update`
 hermit-mcp-server   # starts the gateway + MCP stdio server
 ```
 
-Then in Claude Code:
+Then connect your orchestrator:
 
-```
-/feature-develop-hermit <task>
-```
+- Claude Code: see `docs/cc-setup.md`, then run `/feature-develop-hermit <task>`
+- Codex: see `docs/codex-setup.md`
+- Hermes Agent: see `docs/hermes-setup.md`
 
-Claude interviews, writes the plan, and delegates implementation to Hermit over MCP. Executor tokens never hit your orchestrator bill.
+Claude Code remains the most polished slash-command path today, but all three integrations share the same core idea: the orchestrator does judgment, Hermit does the repetitive repo execution over MCP.
 
 ## Reference skills
 
@@ -170,7 +182,9 @@ MIT — see [LICENSE](LICENSE).
 ## See also
 
 - [docs/cc-setup.md](docs/cc-setup.md) — Claude Code MCP registration details
-- [docs/hermit-variants.md](docs/hermit-variants.md) — the `-hermit` skill family
+- [docs/codex-setup.md](docs/codex-setup.md) — Codex setup, marketplace registration, and runtime verification
+- [docs/hermes-setup.md](docs/hermes-setup.md) — Hermes Agent setup, explicit registration, and live MCP smoke checks
+- [docs/hermit-variants.md](docs/hermit-variants.md) — the Claude Code `-hermit` skill family
 - [docs/measure-savings.md](docs/measure-savings.md) — cost-savings measurement protocol
 - [docs/open-source-positioning.md](docs/open-source-positioning.md) — short public-facing copy for descriptions, releases, and future social previews
 - [docs/release-notes-template.md](docs/release-notes-template.md) — reusable release-note framing that matches Hermit's planner/executor positioning

docs/cc-setup.md

@@ -1,5 +1,7 @@
 # Register HermitAgent as a Claude Code MCP sub-agent
 
+This guide is specifically for Claude Code. If you want Codex or Hermes Agent instead, use `docs/codex-setup.md` or `docs/hermes-setup.md`.
+
 This is the setup that makes `/feature-develop-hermit`, `/code-apply-hermit`, etc. work from inside Claude Code. Five minutes, no Docker.
 
 ## 1. Install and initialize the gateway

docs/codex-setup.md

@@ -0,0 +1,83 @@
+# Register HermitAgent as a Codex executor lane
+
+This guide is specifically for Codex. If you want Claude Code or Hermes Agent instead, use `docs/cc-setup.md` or `docs/hermes-setup.md`.
+
+## What gets wired
+
+Hermit's Codex setup currently focuses on setup and health:
+- install or refresh the `codex-channels` runtime Hermit expects
+- register Hermit in Codex's marketplace/runtime path
+- register the `hermit-channel` MCP entry for Codex
+- remove the legacy reply hook when present
+
+Current boundary note:
+- The live task runtime still flows through Hermit's existing MCP server and Codex-side runtime path.
+- The adapter layer here is about setup/health truthfulness, not a new standalone runtime.
+
+## 1. Install Hermit
+
+```bash
+npm install -g @cafitac/hermit-agent
+hermit
+```
+
+Requires Node.js 20+ and Python 3.11+.
+
+## 2. Run the guided install
+
+For most users, the supported path is:
+
+```bash
+hermit install
+```
+
+For a non-interactive repair/setup pass:
+
+```bash
+hermit install --yes
+```
+
+If you are running CI or smoke checks and do not want optional agent-learner hook work:
+
+```bash
+hermit install --yes --skip-agent-learner
+```
+
+## 3. What success looks like
+
+A healthy Codex-oriented setup should leave you with:
+- a working Hermit managed runtime under `~/.hermit/`
+- `codex-channels` runtime installed
+- Codex marketplace/runtime registration refreshed when needed
+- Codex-facing MCP surface still named `hermit-channel`
+
+Hermit's doctor and status surfaces should report Codex readiness in setup terms such as `installed` rather than pretending the runtime boundary moved somewhere else.
+
+## 4. Verification
+
+Recommended checks:
+
+```bash
+hermit doctor
+hermit status
+```
+
+If setup succeeded but Codex still does not pick the integration up, restart Codex after install so it reloads the refreshed registration.
+
+## 5. Troubleshooting
+
+| Symptom | What to do |
+|---|---|
+| Codex integration reports missing | Re-run `hermit install` or `hermit install --yes`, then check `hermit doctor` |
+| Codex still behaves like Hermit is absent after install | Restart Codex so it reloads the refreshed registration |
+| You see old reply-hook behavior or stale configuration | Re-run `hermit install`; the current flow removes the legacy Codex reply hook when present |
+| You want a Claude Code-style slash command experience | That is still the most polished path today; see `docs/cc-setup.md` and `docs/hermit-variants.md` |
+
+## 6. Scope clarification
+
+This document is intentionally narrow:
+- it does not claim Codex uses a brand-new Hermit runtime boundary
+- it does not replace Codex as planner/reviewer
+- it does describe the setup/health surfaces Hermit currently verifies and repairs
+
+The important operator expectation remains simple: Codex should connect to Hermit through the `hermit-channel` MCP-facing surface while Hermit handles the repetitive repo execution underneath.

docs/hermes-setup.md

@@ -0,0 +1,106 @@
+# Register HermitAgent as a Hermes Agent MCP executor
+
+This guide is specifically for Hermes Agent. If you want Claude Code or Codex instead, use `docs/cc-setup.md` or `docs/codex-setup.md`.
+
+## What gets wired
+
+Hermit exposes a stdio MCP server at:
+
+```bash
+hermit mcp-server
+```
+
+For Hermes Agent, the important integration surface is the MCP server name `hermit-channel`. Once registered, Hermes can call Hermit's MCP tools such as `run_task`, `reply_task`, `check_task`, and `cancel_task`.
+
+Current boundary note:
+- The live task runtime stays on Hermit's existing MCP server path.
+- Hermes-facing setup helpers are for registration, repair, and smoke checks only.
+
+## 1. Install Hermit
+
+```bash
+npm install -g @cafitac/hermit-agent
+hermit
+```
+
+Requires Node.js 20+ and Python 3.11+.
+
+## 2. Print the non-mutating registration command
+
+Start with the safe path:
+
+```bash
+hermit install --print-hermes-mcp-config
+```
+
+This prints the exact `hermes mcp add ...` command for `hermit-channel` without editing `~/.hermes`.
+
+## 3. Register Hermit with Hermes Agent
+
+You have two supported options.
+
+### Option A — explicit manual registration
+
+Run the command printed by the previous step. It should look like:
+
+```bash
+hermes mcp add hermit-channel --command hermit --args mcp-server
+```
+
+### Option B — explicit Hermit-assisted repair/registration
+
+If you want Hermit to call the Hermes CLI for you:
+
+```bash
+hermit install --fix-hermes-mcp
+```
+
+This path is intentional and explicit: Hermit does not silently edit Hermes config by default.
+
+## 4. Verify the live MCP wiring
+
+Run the bounded live probe:
+
+```bash
+hermit install --test-hermes-mcp
+```
+
+Under the hood this executes Hermes Agent's live MCP check for `hermit-channel` without mutating config.
+
+You can also inspect Hermes directly:
+
+```bash
+hermes mcp list
+hermes mcp test hermit-channel
+```
+
+## 5. Troubleshooting
+
+| Symptom | What to do |
+|---|---|
+| `hermit install --print-hermes-mcp-config` shows setup text but Hermes still cannot see Hermit | Run the printed `hermes mcp add ...` command or `hermit install --fix-hermes-mcp`, then restart Hermes sessions that should load MCP servers |
+| `hermit install --test-hermes-mcp` fails | Run `hermit install --fix-hermes-mcp`, re-check `hermes mcp list`, then retry the test |
+| `hermes mcp test hermit-channel` prints an error even though the shell exit code looks successful | Prefer `hermit install --test-hermes-mcp`; Hermit treats known failure text as a failed smoke even when Hermes itself exits 0 |
+| You want OAuth-based OpenAI Codex / ChatGPT in Hermes | Configure Hermes itself for `openai-codex` / ChatGPT OAuth; Hermit's MCP registration does not require introducing OpenAI API keys |
+
+## 6. What this does not change
+
+- It does not replace Hermes Agent as your planner.
+- It does not require Anthropic configuration.
+- It does not require OpenAI API keys just to register Hermit as an MCP executor.
+- It does not change Claude Code or Codex integrations.
+
+## Suggested operator flow
+
+```bash
+npm install -g @cafitac/hermit-agent
+hermit install --print-hermes-mcp-config
+hermes mcp add hermit-channel --command hermit --args mcp-server
+hermit install --test-hermes-mcp
+```
+
+If the manual registration is already done or drifted, swap the middle step for:
+
+```bash
+hermit install --fix-hermes-mcp
+```

docs/known-issues.md

@@ -1,30 +1,42 @@
 # HermitAgent Known Issues and Stabilization Tasks
 
-> Last updated: 2026-04-18
+> Last updated: 2026-05-01
 
 ## Known Issues
 
 ### 1. Waiting Notification Loss [P1]
 
-**Symptom**: When HermitAgent transitions to `waiting` state (e.g., bash permission request, interview question), the notification occasionally fails to surface in the Claude Code session, causing the task to wait indefinitely.
+**Symptom**: When HermitAgent transitions to `waiting` state (for example a permission request or interview question), the notification can occasionally fail to surface in the Claude Code session, causing the task to wait longer than expected.
 
-**Cause**: `_send_channel_notification()` uses fire-and-forget — if CC drops the frame at that moment, it is lost.
+**Cause**: `_send_channel_notification()` is still fire-and-forget. If Claude Code drops the frame at that exact moment, the notification is lost.
 
-**Solution**: For `waiting` type notifications, retry every 30 seconds until a response is received. Stop retrying on receipt of `running` / `done` / `error`.
+**Current mitigation**: Retry logic in `hermit_agent/mcp_server.py` now re-sends `waiting` notifications until the task moves back to `running` or reaches a terminal state.
 
-**Status**: Retry logic implemented in `hermit_agent/mcp_server.py`; continue to monitor in real sessions.
+**Status**: Improved but still worth monitoring in real sessions.
 
 ---
 
-### 2. /tmp Disk Accumulation [P2]
+### 2. Hermes CLI MCP smoke can look successful even when the probe text says otherwise [P1]
+
+**Symptom**: `hermes mcp test hermit-channel` may print failure or cancellation text while still exiting with status code 0.
+
+**Why it matters**: Naive shell automation can misread the integration as healthy.
+
+**Current mitigation**: Hermit's `hermit install --test-hermes-mcp` smoke wraps the Hermes CLI probe and treats known failure text as a failed verification, even when Hermes exits 0.
+
+**Status**: Public docs now recommend `hermit install --test-hermes-mcp` as the safer readiness check.
+
+---
+
+### 3. /tmp Disk Accumulation [P2]
 
 **Symptom**: As Claude Code runs longer, task output files accumulate under `/private/tmp/claude-501/`, eventually causing ENOSPC.
 
-**Cause**: CC captures bash command output to files, but cleanup on session end is suspected to be incomplete.
+**Cause**: Claude Code captures bash command output to files, but cleanup on session end appears incomplete.
 
-**Solution**: Identify exact cause, then either file a CC upstream issue or add a periodic cleanup script.
+**Next step**: Confirm the exact upstream behavior, then either file a Claude Code issue or add a bounded cleanup helper.
 
-**Status**: Unresolved. Temporarily mitigated by `/tmp` cleanup on restart.
+**Status**: Unresolved. Restart-time cleanup is still the temporary mitigation.
 
 ---
 
@@ -75,4 +87,5 @@ HERMIT_LLM_URL=http://localhost:8080/v1
 ## Recurrence Prevention Notes
 
 - **MCP server restart impact**: modifying the MCP server code requires restarting the MCP transport; Claude Code will not auto-reconnect. Prefer applying changes when no tasks are in progress, and use `/mcp` to reconnect if needed.
-- **Incorrect cwd**: Passing a parent directory as `cwd` when running `/feature-develop` causes relative-path errors. **Lesson**: set `cwd` to the exact project root (e.g. `$HOME/Project/<your-repo>`), not a parent directory.
+- **Incorrect cwd**: Passing a parent directory as `cwd` when running `/feature-develop` causes relative-path errors. Set `cwd` to the exact project root (for example `$HOME/Project/<your-repo>`), not a parent directory.
+- **Hermes readiness probes**: when documenting Hermes setup, prefer Hermit's wrapper commands (`--print-hermes-mcp-config`, `--fix-hermes-mcp`, `--test-hermes-mcp`) over raw shell automation that only checks the Hermes CLI exit code.