docs(distribution): describe per-root merge of skills/ and cron/ on update

The user guide, command reference, `hermes profile update --help` and the
install-over-plain-profile warning all said skills/ and cron/ are overwritten
wholesale; they are now merged per skill / cron job, so say so, and document the
symlinked-container refusal.
This commit is contained in:
teknium1
2026-09-14 17:54:20 -07:00
committed by Teknium
parent 2bf8b143bf
commit ab7b97f55e
4 changed files with 12 additions and 6 deletions
+2 -1
View File
@@ -59,7 +59,8 @@ def _render_distribution_plan(plan) -> None:
else:
print(
" ⚠ Profile exists but is NOT a distribution. Installing here will\n"
" overwrite its SOUL.md, skills/, cron/, and mcp.json.\n"
" overwrite its SOUL.md and mcp.json and replace any skill or cron job\n"
" of the same name the distribution ships.\n"
" Your memories, sessions, auth.json, and .env will be preserved,\n"
" but any hand-edits to distribution-owned files will be lost."
)
+2 -1
View File
@@ -125,7 +125,8 @@ def build_profile_parser(subparsers, *, cmd_profile: Callable) -> None:
profile_update = profile_subparsers.add_parser(
"update", help="Re-pull a distribution and apply updates (user data preserved)",
description="Fetch the distribution from its recorded source and overwrite "
"distribution-owned files (SOUL.md, skills/, cron/, mcp.json). "
"distribution-owned files (SOUL.md, mcp.json) and the skills and cron jobs "
"the distribution ships; skills or cron jobs you added yourself stay in place. "
"User data (memories, sessions, auth, .env) is never touched. "
"config.yaml is preserved unless --force-config is passed.")
profile_update.add_argument("profile_name", help="Profile to update")
+6 -2
View File
@@ -357,8 +357,12 @@ hermes profile update <name> [--force-config] [--yes]
```
Re-clones the distribution from its recorded source and applies updates.
Distribution-owned files (SOUL.md, skills/, cron/, mcp.json) are
overwritten; user data (memories, sessions, auth, .env) is never touched.
Distribution-owned files (SOUL.md, mcp.json) are overwritten and the
skills and cron jobs the distribution ships are replaced; skills or cron
jobs you added under `skills/` or `cron/` yourself stay in place. User data
(memories, sessions, auth, .env) is never touched. A symlinked `skills/` or
`cron/` is refused before anything is written — replace the link with a real
directory and re-run.
`config.yaml` is preserved by default to keep your local overrides.
Pass `--force-config` to reset it to the distribution's shipped config.
@@ -265,7 +265,7 @@ When an installer updates to a new version, some things get replaced (author's d
| Category | Paths | On update |
|---|---|---|
| **Distribution-owned** | `SOUL.md`, `config.yaml`, `mcp.json`, `skills/`, `cron/`, `distribution.yaml` | Replaced from the new clone |
| **Distribution-owned** | `SOUL.md`, `config.yaml`, `mcp.json`, `skills/`, `cron/`, `distribution.yaml` | Files are replaced from the new clone. Directories are merged per entry: each skill or cron job the new clone ships replaces its counterpart wholesale (files the author retired disappear), while skills or cron jobs you added yourself stay in place. |
| **Config override** | `config.yaml` | Actually preserved by default — the installer may have tuned model or provider. Pass `--force-config` on update to reset. |
| **User-owned** | `memories/`, `sessions/`, `state.db*`, `auth.json`, `.env`, `logs/`, `workspace/`, `plans/`, `home/`, `*_cache/`, `local/` | Never touched |
@@ -403,7 +403,7 @@ hermes profile update research-bot
What happens:
1. Re-clones the repo from the recorded source URL.
2. Replaces distribution-owned files (SOUL, skills, cron, mcp.json).
2. Replaces distribution-owned files (SOUL, mcp.json) and every skill or cron job the distribution ships; skills and cron jobs you added to the profile yourself are left alone.
3. **Preserves** your `config.yaml` — you may have tuned the model, temperature, or other settings. Pass `--force-config` to overwrite.
4. **Never touches** user data: memories, sessions, auth, `.env`, logs, state.