chore: uptick

website/docs/user-guide/features/curator.md

@@ -23,6 +23,12 @@ The curator is triggered by an inactivity check, not a cron daemon. On CLI sessi
 
 If both are true, it spawns a background fork of `AIAgent` — the same pattern used by the memory/skill self-improvement nudges. The fork runs in its own prompt cache and never touches the active conversation.
 
+:::info First-run behavior
+On a brand-new install (or the first time a pre-curator install ticks after `hermes update`), the curator **does not run immediately**. The first observation seeds `last_run_at` to "now" and defers the first real pass by one full `interval_hours`. This gives you a full interval to review your skill library, pin anything important, or opt out entirely before the curator ever touches it.
+
+If you want to see what the curator *would* do before it runs for real, run `hermes curator run --dry-run` — it produces the same review report without mutating the library.
+:::
+
 A run has two phases:
 
 1. **Automatic transitions** (deterministic, no LLM). Skills unused for `stale_after_days` (30) become `stale`; skills unused for `archive_after_days` (90) are moved to `~/.hermes/skills/.archive/`.
@@ -80,6 +86,12 @@ Earlier releases used a one-off `curator.auxiliary.{provider,model}` block. That
 hermes curator status         # last run, counts, pinned list, LRU top 5
 hermes curator run            # trigger a review now (background by default)
 hermes curator run --sync     # same, but block until the LLM pass finishes
+hermes curator run --dry-run  # preview only — report without any mutations
+hermes curator backup         # take a manual snapshot of ~/.hermes/skills/
+hermes curator rollback       # restore from the newest snapshot
+hermes curator rollback --list     # list available snapshots
+hermes curator rollback --id <ts>  # restore a specific snapshot
+hermes curator rollback -y         # skip the confirmation prompt
 hermes curator pause          # stop runs until resumed
 hermes curator resume
 hermes curator pin <skill>    # never auto-transition this skill
@@ -87,6 +99,31 @@ hermes curator unpin <skill>
 hermes curator restore <skill>  # move an archived skill back to active
 ```
 
+## Backups and rollback
+
+Before every real curator pass, Hermes takes a tar.gz snapshot of `~/.hermes/skills/` at `~/.hermes/skills/.curator_backups/<utc-iso>/skills.tar.gz`. If a pass archives or consolidates something you didn't want touched, you can undo the whole run with one command:
+
+```bash
+hermes curator rollback        # restore newest snapshot (with confirmation)
+hermes curator rollback -y     # skip the prompt
+hermes curator rollback --list # see all snapshots with reason + size
+```
+
+The rollback itself is reversible: before replacing the skills tree, Hermes takes another snapshot tagged `pre-rollback to <target-id>`, so a mistaken rollback can be undone by rolling forward to that one with `--id`.
+
+You can also take manual snapshots at any time with `hermes curator backup --reason "before-refactor"`. The `--reason` string lands in the snapshot's `manifest.json` and is shown in `--list`.
+
+Snapshots are pruned to `curator.backup.keep` (default 5) to keep disk usage bounded:
+
+```yaml
+curator:
+  backup:
+    enabled: true
+    keep: 5
+```
+
+Set `curator.backup.enabled: false` to disable automatic snapshotting. The manual `hermes curator backup` command still works when backups are disabled only if you set `enabled: true` first — the flag gates both paths symmetrically so there's no way to accidentally skip the pre-run snapshot on mutating runs.
+
 `hermes curator status` also lists the five least-recently-used skills — a quick way to see what's likely to become stale next.
 
 The same subcommands are available as the `/curator` slash command inside a running session (CLI or gateway platforms).
@@ -104,6 +141,18 @@ Everything else in `~/.hermes/skills/` is fair game for the curator. This includ
 - Skills you created manually with a hand-written `SKILL.md`.
 - Skills added via external skill directories you've pointed Hermes at.
 
+:::warning Your hand-written skills look the same as agent-saved ones
+Provenance here is **binary** (bundled/hub vs. everything else). The curator cannot tell a hand-authored skill you rely on for private workflows apart from a skill the self-improvement loop saved mid-session. Both land in the "agent-created" bucket.
+
+Before the first real pass (7 days after installation by default), take a moment to:
+
+1. Run `hermes curator run --dry-run` to see exactly what the curator would propose.
+2. Use `hermes curator pin <name>` to fence off anything you don't want touched.
+3. Or set `curator.enabled: false` in `config.yaml` if you'd rather manage the library yourself.
+
+Archives are always recoverable via `hermes curator restore <name>`, but it's easier to pin up-front than to chase down a consolidation after the fact.
+:::
+
 If you want to protect a specific skill from ever being touched — for example a hand-authored skill you rely on — use `hermes curator pin <name>`. See the next section.
 
 ## Pinning a skill