v0.2.5: Fix host↔Docker plugin root; rename upgrade→hermit-upgrade, status→hermit-state

Author: gtapps

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-hermit",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "A personal assistant that lives in your project — memory-driven learning, daily rhythm, idle agency, and operational hygiene for Claude Code",
   "author": {
     "name": "gtapps"

.claude/skills/release/SKILL.md

@@ -4,7 +4,7 @@ description: Bump the plugin version, write a detailed changelog entry for the u
 ---
 # Release
 
-Bump version, write changelog, commit, and push. The changelog entry is critical because the upgrade skill (`skills/upgrade/SKILL.md`) reads it to know what to tell hermits during `/claude-code-hermit:upgrade`.
+Bump version, write changelog, commit, and push. The changelog entry is critical because the upgrade skill (`skills/hermit-upgrade/SKILL.md`) reads it to know what to tell hermits during `/claude-code-hermit:hermit-upgrade`.
 
 ## Steps
 
@@ -43,7 +43,7 @@ Prepend a new entry to `CHANGELOG.md` immediately after the `# Changelog` header
 
 ### Upgrade Instructions
 
-Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
+Run `/claude-code-hermit:hermit-upgrade`. The upgrade skill handles:
 
 1. **What it does** — Explanation of what the upgrade skill will do automatically.
 
@@ -53,7 +53,7 @@ Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
 **The Upgrade Instructions section is the most important part.** The upgrade skill reads this to know what actions to take for each hermit. Be specific about:
 - Whether CLAUDE-APPEND needs refreshing (it almost always does)
 - Whether templates changed
-- Whether config.json needs new keys (reference the table in `skills/upgrade/SKILL.md` if adding new interactive/silent keys)
+- Whether config.json needs new keys (reference the table in `skills/hermit-upgrade/SKILL.md` if adding new interactive/silent keys)
 - Whether there are manual steps the operator needs to take
 - What is NOT affected (so the upgrade skill doesn't touch things unnecessarily)
 

CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.2.5] - 2026-04-01
+
+### Fixed
+
+- **`hermit-run` now resolves plugin root across host↔Docker moves** — When `hermit-init` is run in Docker, `_plugin_root` is written with the container's home path (e.g., `/home/claude/.claude/...`). Running `hermit-start` on the host then fails with "Plugin root not found or invalid" because that path doesn't exist there. The existing `CLAUDE_CONFIG_DIR` remap only fired inside Docker (where the env var is set), not on the host. Fixed by adding a `$HOME/.claude/{suffix}` fallback that always fires: both environments share the same path suffix (`plugins/marketplaces/claude-code-hermit`) with only the home prefix differing. The remap is not written back to `config.json` so the value remains portable across both environments.
+
+### Changed
+
+- **Renamed `upgrade` skill to `hermit-upgrade`** — The bare name `upgrade` conflicted with Claude Code's native `/upgrade` command. Now invoked as `/claude-code-hermit:hermit-upgrade`. All documentation, skill cross-references, scripts, and CLAUDE-APPEND template updated.
+
+- **Renamed `status` skill to `hermit-state`** — The bare name `status` risks collision with native Claude Code commands. Now invoked as `/claude-code-hermit:hermit-state`. All cross-references updated.
+
+### Files affected
+
+| File | Change |
+|------|--------|
+| `state-templates/bin/hermit-run` | Added `$HOME/.claude` fallback remap; unified both remap branches |
+| `skills/hermit-upgrade/SKILL.md` | Renamed from `skills/upgrade/SKILL.md` |
+| `skills/hermit-state/SKILL.md` | Renamed from `skills/status/SKILL.md` |
+| `CLAUDE.md` | Updated skill list and quick reference |
+| `state-templates/CLAUDE-APPEND.md` | Updated skill invocation references |
+| `scripts/hermit-start.py`, `scripts/check-upgrade.sh` | Updated invocation references |
+| `state-templates/bin/hermit-run` | Updated invocation reference |
+| `docs/HOW-TO-USE.md`, `docs/TROUBLESHOOTING.md`, `docs/UPGRADING.md` | Updated references |
+| `skills/session/SKILL.md`, `skills/monitor/SKILL.md` | Updated status references |
+| `skills/hermit-init/SKILL.md` | Updated upgrade reference in next-steps |
+
+### Upgrade Instructions
+
+Run `/claude-code-hermit:hermit-upgrade`. The upgrade skill handles:
+
+1. **Boot script update** — Copies updated `hermit-run` from `state-templates/bin/` into `.claude-code-hermit/bin/` (step 5b). Required to get the host↔Docker fix and updated skill name references.
+2. **CLAUDE-APPEND block update** — Refreshes the session discipline block in `CLAUDE.md`, which now references `hermit-state` and `hermit-upgrade` instead of the old names.
+
+**No config.json changes required.** No template changes other than `CLAUDE-APPEND.md`.
+
+---
+
 ## [0.2.4] - 2026-04-01
 
 ### Changed
@@ -17,7 +55,7 @@
 
 ### Upgrade Instructions
 
-Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
+Run `/claude-code-hermit:hermit-upgrade`. The upgrade skill handles:
 
 1. **CLAUDE-APPEND block update** — Refreshed session discipline block (no content change in this version, but the upgrade skill always checks).
 
@@ -55,7 +93,7 @@ Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
 
 ### Upgrade Instructions
 
-Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
+Run `/claude-code-hermit:hermit-upgrade`. The upgrade skill handles:
 
 1. **CLAUDE-APPEND block update** — Refreshed session discipline block (no content change in this version, but the upgrade skill always checks).
 
@@ -79,7 +117,7 @@ Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
 
 ### Upgrade Instructions
 
-Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
+Run `/claude-code-hermit:hermit-upgrade`. The upgrade skill handles:
 
 1. **CLAUDE-APPEND block update** — Refreshed session discipline block (no content change in this version, but the upgrade skill always checks).
 
@@ -110,7 +148,7 @@ Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
 
 ### Upgrade Instructions
 
-Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
+Run `/claude-code-hermit:hermit-upgrade`. The upgrade skill handles:
 
 1. **CLAUDE-APPEND block update** — The session discipline block in your project's CLAUDE.md is refreshed to include the new "Proposal Pipeline (mandatory)" section. This is the primary fix — it prevents hermits from skipping the proposal workflow.
 
@@ -172,7 +210,7 @@ Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
 
 ### Upgrade Instructions
 
-Run `/claude-code-hermit:upgrade`. The upgrade skill handles:
+Run `/claude-code-hermit:hermit-upgrade`. The upgrade skill handles:
 
 1. **Task list ID setup** — Writes `CLAUDE_CODE_TASK_LIST_ID` to `.claude/settings.local.json` (derived from project basename). This makes native Tasks persistent and lets hooks read task files.
 
@@ -334,7 +372,7 @@ Then rebuild: `docker compose -f docker-compose.hermit.yml build`
 
 ### Upgrade Instructions
 
-Run `/claude-code-hermit:upgrade` to refresh templates and migrate existing files.
+Run `/claude-code-hermit:hermit-upgrade` to refresh templates and migrate existing files.
 
 **Migration: Session reports to YAML frontmatter**
 
@@ -408,7 +446,7 @@ Report: "Migrated N proposals with YAML frontmatter."
 
 **What you need to do:**
 
-1. Run `/claude-code-hermit:upgrade` to migrate config and refresh templates
+1. Run `/claude-code-hermit:hermit-upgrade` to migrate config and refresh templates
 2. Review migrated routines: `/claude-code-hermit:hermit-settings routines`
 3. Optionally add `## When Idle` to OPERATOR.md and set `idle_behavior` to `discover`
 
@@ -441,7 +479,7 @@ Report: "Migrated N proposals with YAML frontmatter."
 
 **What you need to do:**
 
-1. Run `/claude-code-hermit:upgrade` to refresh templates
+1. Run `/claude-code-hermit:hermit-upgrade` to refresh templates
 2. **Deny patterns (recommended):** Add safety deny rules to `.claude/settings.json` — run `/claude-code-hermit:hermit-init` step 9 or add manually:
    ```json
    "permissions": {
@@ -480,7 +518,7 @@ Env vars are now managed in `config.json` `env` and written to `.claude/settings
 
 **What you need to do:**
 
-1. Run `/claude-code-hermit:upgrade` — it adds the `env` key to your config.json with defaults
+1. Run `/claude-code-hermit:hermit-upgrade` — it adds the `env` key to your config.json with defaults
 2. If you have channels configured, the upgrade also adds `DISCORD_STATE_DIR` / `TELEGRAM_STATE_DIR` to `env`
 3. If you use Docker: rebuild (`docker compose -f docker-compose.hermit.yml build`) and regenerate compose with `/claude-code-hermit:docker-setup` to get the slimmed-down `environment:` section — or just remove the 5 non-auth env vars from your existing compose file manually
 
@@ -540,9 +578,9 @@ The hermit state directory has moved from `.claude/.claude-code-hermit/` to `.cl
    - `"Edit(.claude/.claude-code-hermit/**)"` → `"Edit(.claude-code-hermit/**)"`
    - `"Write(.claude/.claude-code-hermit/**)"` → `"Write(.claude-code-hermit/**)"`
 
-4. **If you have a custom hermit** with skills, agents, or scripts that reference `.claude/.claude-code-hermit/` — update those references to `.claude-code-hermit/` before running `/claude-code-hermit:upgrade`
+4. **If you have a custom hermit** with skills, agents, or scripts that reference `.claude/.claude-code-hermit/` — update those references to `.claude-code-hermit/` before running `/claude-code-hermit:hermit-upgrade`
 
-Then run `/claude-code-hermit:upgrade` — it will refresh templates and clean up any remaining stale permissions.
+Then run `/claude-code-hermit:hermit-upgrade` — it will refresh templates and clean up any remaining stale permissions.
 
 ---
 
@@ -699,7 +737,7 @@ Valid values: `"default"`, `"acceptEdits"`, `"dontAsk"`, `"bypassPermissions"`.
 3. Update `NEXT-MISSION.md` → `NEXT-TASK.md` in any skill that reads/writes it
 4. Update `CLAUDE-APPEND.md` to use new section names
 5. Replace "domain pack" or "hermit agent" with "hermit" in docs and skill descriptions
-6. Run `/claude-code-hermit:upgrade` in target projects to refresh templates
+6. Run `/claude-code-hermit:hermit-upgrade` in target projects to refresh templates
 
 ### Added
 

CLAUDE.md

@@ -16,7 +16,7 @@ After install, run `/claude-code-hermit:hermit-init` in the target project to cr
 ## Plugin Structure
 
 - `agents/` — subagent definitions (session-mgr only; hermit plugins add more subagents)
-- `skills/` — skill definitions (namespaced as `/claude-code-hermit:*`): session, session-start, session-close, status, brief, monitor, heartbeat, hermit-settings, proposal-create, proposal-list, proposal-act, reflect, channel-responder, hermit-init, upgrade, docker-setup, hermit-takeover, hermit-hand-back
+- `skills/` — skill definitions (namespaced as `/claude-code-hermit:*`): session, session-start, session-close, hermit-state, brief, monitor, heartbeat, hermit-settings, proposal-create, proposal-list, proposal-act, reflect, channel-responder, hermit-init, hermit-upgrade, docker-setup, hermit-takeover, hermit-hand-back
 - `hooks/hooks.json` — hook registrations
 - `scripts/` — hook implementation scripts + boot scripts (hermit-start.py, hermit-stop.py)
 - `state-templates/` — templates copied into target projects by the `hermit-init` skill
@@ -86,12 +86,12 @@ Common skills (full list: [Skills Reference](docs/SKILLS.md)):
 
 - `/claude-code-hermit:session` — start or resume a session
 - `/claude-code-hermit:session-close` — full shutdown with quality checks
-- `/claude-code-hermit:status` — compact summary (auto-triggers on "status", "progress")
+- `/claude-code-hermit:hermit-state` — compact summary (auto-triggers on "status", "progress")
 - `/claude-code-hermit:brief` — executive summary (auto-triggers on "brief", "what happened")
 - `/claude-code-hermit:heartbeat` — background checklist (run/start/stop/status/edit)
 - `/claude-code-hermit:hermit-settings` — view/change config
 - `/claude-code-hermit:proposal-list` — view proposals (auto-triggers on "any proposals")
 - `/claude-code-hermit:proposal-act` — accept, defer, or dismiss a proposal
-- `/claude-code-hermit:upgrade` — update config and templates after plugin update
+- `/claude-code-hermit:hermit-upgrade` — update config and templates after plugin update
 - `/claude-code-hermit:docker-setup` — generate Docker scaffolding for always-on
 - `/claude-code-hermit:hermit-takeover` / `hermit-hand-back` — operator control

README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
   <a href="https://code.claude.com/docs/en/plugins"><img src="https://img.shields.io/badge/Claude%20Code-plugin-orange.svg" alt="Claude Code Plugin" /></a>
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.2.4-green.svg" alt="Version 0.2.4" /></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.2.5-green.svg" alt="Version 0.2.5" /></a>
   <img src="https://img.shields.io/badge/Claude-Pro%20%7C%20Max-blueviolet.svg" alt="Claude Pro/Max Compatible" />
   <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome" />
 </p>

docs/HOW-TO-USE.md

@@ -104,7 +104,7 @@ You're always in control. Hermit suggests. You decide.
 ## Tips
 
 - **Don't create session/proposal files by hand.** Skills handle lifecycle tracking.
-- **After plugin updates**, run `/claude-code-hermit:upgrade`.
+- **After plugin updates**, run `/claude-code-hermit:hermit-upgrade`.
 - **Talk to your hermit.** Ask how it can improve. It gets better when you tell it what you need.
 
 ---

docs/TROUBLESHOOTING.md

@@ -73,7 +73,7 @@ SHELL.md from a crashed session persists. Choose **resume** or **start new** (ge
 
 As of v0.0.8, reflect checks dismissed and deferred proposals before creating new ones. If you're still seeing re-suggestions:
 - Check your plugin version: the proposal is in `.claude-plugin/plugin.json` — should be `0.0.8` or later.
-- Run `/claude-code-hermit:upgrade` to ensure the latest reflect skill is active.
+- Run `/claude-code-hermit:hermit-upgrade` to ensure the latest reflect skill is active.
 - If significantly more evidence has accumulated since the dismissal, Hermit may intentionally revisit — this is by design.
 
 ## SHELL.md Getting Large / Bloated

docs/UPGRADING.md

@@ -17,7 +17,7 @@ claude plugin marketplace add gtapps/claude-code-hermit
 Inside Claude Code, in each project that uses the plugin:
 
 ```
-/claude-code-hermit:upgrade
+/claude-code-hermit:hermit-upgrade
 ```
 
 This detects the version gap, shows what changed, prompts for new settings, refreshes templates, and updates the CLAUDE.md session discipline block.
@@ -36,7 +36,7 @@ Hermits (e.g., `claude-code-dev-hermit`) upgrade the same way:
 claude plugin marketplace add your-org/claude-code-dev-hermit
 ```
 
-Then `/claude-code-hermit:upgrade` — it detects hermit version gaps automatically and updates their CLAUDE-APPEND blocks.
+Then `/claude-code-hermit:hermit-upgrade` — it detects hermit version gaps automatically and updates their CLAUDE-APPEND blocks.
 
 Each hermit's version is tracked independently in `config.json`:
 
@@ -105,7 +105,7 @@ These aren't upgrades — just how your project evolves:
 
 ### Automatic migration
 
-Running `/claude-code-hermit:upgrade` handles:
+Running `/claude-code-hermit:hermit-upgrade` handles:
 - `heartbeat.morning_routine` → `routines[{id:"morning",...}]`
 - `heartbeat.evening_routine` → `routines[{id:"evening",...}]`
 - `heartbeat.idle_agency` → `idle_behavior` (`true` → `"discover"`, `false` → `"wait"`)
@@ -115,7 +115,7 @@ Running `/claude-code-hermit:upgrade` handles:
 
 ### What you need to do
 
-1. Run `/claude-code-hermit:upgrade` to migrate config and refresh templates
+1. Run `/claude-code-hermit:hermit-upgrade` to migrate config and refresh templates
 2. Review migrated routines: `/claude-code-hermit:hermit-settings routines`
 3. Optionally add a `## When Idle` section to your OPERATOR.md
 4. Optionally set `idle_behavior` to `discover`: `/claude-code-hermit:hermit-settings idle`

scripts/check-upgrade.sh

@@ -21,4 +21,4 @@ CONFIG_VER=$(python3 -c "import json,sys; c=json.load(open(sys.argv[1])); print(
 [ "$PLUGIN_VER" = "$CONFIG_VER" ] && exit 0
 
 echo "---Upgrade Available---"
-echo "Plugin v${PLUGIN_VER} ≠ config v${CONFIG_VER}. Run /claude-code-hermit:upgrade"
+echo "Plugin v${PLUGIN_VER} ≠ config v${CONFIG_VER}. Run /claude-code-hermit:hermit-upgrade"

scripts/hermit-start.py

@@ -98,7 +98,7 @@ def check_for_upgrade(config):
         config_ver = config.get('_hermit_versions', {}).get('claude-code-hermit', '0.0.0')
         if plugin_ver != config_ver:
             print(f'[hermit] Upgrade available: v{config_ver} -> v{plugin_ver}')
-            print('[hermit] Run /claude-code-hermit:upgrade inside Claude Code')
+            print('[hermit] Run /claude-code-hermit:hermit-upgrade inside Claude Code')
     except (OSError, ValueError, KeyError):
         pass