From ab7b97f55ec5df3be18fd77a2732dbc3b5068ca4 Mon Sep 17 00:00:00 2001 From: teknium1 <127238744+teknium1@users.noreply.github.com> Date: Mon, 14 Sep 2026 17:54:20 -0700 Subject: [PATCH] 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. --- hermes_cli/profile_cmd.py | 3 ++- hermes_cli/subcommands/profile.py | 3 ++- website/docs/reference/profile-commands.md | 8 ++++++-- website/docs/user-guide/profile-distributions.md | 4 ++-- 4 files changed, 12 insertions(+), 6 deletions(-) diff --git a/hermes_cli/profile_cmd.py b/hermes_cli/profile_cmd.py index 68d9a438b9..c4d0d8d071 100644 --- a/hermes_cli/profile_cmd.py +++ b/hermes_cli/profile_cmd.py @@ -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." ) diff --git a/hermes_cli/subcommands/profile.py b/hermes_cli/subcommands/profile.py index 7202871ca6..3a11dc838a 100644 --- a/hermes_cli/subcommands/profile.py +++ b/hermes_cli/subcommands/profile.py @@ -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") diff --git a/website/docs/reference/profile-commands.md b/website/docs/reference/profile-commands.md index efa13bf9f2..af90bef5be 100644 --- a/website/docs/reference/profile-commands.md +++ b/website/docs/reference/profile-commands.md @@ -357,8 +357,12 @@ hermes profile update [--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. diff --git a/website/docs/user-guide/profile-distributions.md b/website/docs/user-guide/profile-distributions.md index 14bbba02f7..0ea7f46dda 100644 --- a/website/docs/user-guide/profile-distributions.md +++ b/website/docs/user-guide/profile-distributions.md @@ -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.