diff --git a/cli-builder/README.md b/cli-builder/README.md
index 2585882..51ae845 100644
--- a/cli-builder/README.md
+++ b/cli-builder/README.md
@@ -7,8 +7,8 @@ A comprehensive design guide and scaffold for building CLI tools that **AI agent
 When your agent loads this skill, it can **design, build, and refactor CLI tools** that agents can discover and use without human help. That means:
 
 - **Every `--help` output becomes a contract** the agent parses to understand your tool
-- **Every command supports `--json`** for machine-readable output the agent consumes
-- **Every operation is idempotent** — `--dry-run` previews changes before they happen
+- **Design `--json` as a documented contract** for machine-readable output agents can consume
+- **Establish or review idempotency** so safe reruns are explicit rather than assumed
 - **Authentication is lazy** — help and dry-run work without credentials
 - **Errors are structured** — different exit codes for different failure modes
 
diff --git a/crowdsec/SKILL.md b/crowdsec/SKILL.md
index aa9fb30..83359db 100644
--- a/crowdsec/SKILL.md
+++ b/crowdsec/SKILL.md
@@ -72,7 +72,6 @@ Use `cscli -o json` for automation and capture command output, version, host,
 and time as evidence. Read-only triage commonly uses:
 
 ```bash
-cscli hub update
 cscli collections list
 cscli alerts list --contain "scenario:ssh-bf"
 cscli decisions list -o json
diff --git a/crowdsec/references/appsec-deep-dive.md b/crowdsec/references/appsec-deep-dive.md
index 68df280..a54972b 100644
--- a/crowdsec/references/appsec-deep-dive.md
+++ b/crowdsec/references/appsec-deep-dive.md
@@ -105,7 +105,7 @@ action: ban
 
 ## Virtual Patching
 
-Virtual patching rules protect against known CVEs without modifying application code. These are maintained by CrowdSec and updated via `cscli hub update`.
+Virtual patching rules protect against known CVEs without modifying application code. These are maintained by CrowdSec and can be refreshed with the optional, state-changing `cscli hub update`; confirm the target, scope, rollback, and maintenance window under the safety gate before running it.
 
 ## Gotchas
 
diff --git a/crowdsec/references/cscli-command-reference.md b/crowdsec/references/cscli-command-reference.md
index b765bd6..5a11153 100644
--- a/crowdsec/references/cscli-command-reference.md
+++ b/crowdsec/references/cscli-command-reference.md
@@ -20,7 +20,7 @@ Full reference for `cscli` — the CrowdSec command-line tool for managing the e
 
 | Command | Description |
 |---------|-------------|
-| `cscli hub update` | Update the local hub index |
+| `cscli hub update` | Refresh the local hub index (state-changing; apply the safety gate first) |
 | `cscli hub list` | List hub index info |
 | `cscli collections install <name>` | Install a collection |
 | `cscli collections list` | List installed collections |
diff --git a/crowdsec/references/hub-collections.md b/crowdsec/references/hub-collections.md
index db2a08e..c0e7e60 100644
--- a/crowdsec/references/hub-collections.md
+++ b/crowdsec/references/hub-collections.md
@@ -81,7 +81,7 @@ sudo cscli collections list --all
 # Inspect (shows version + runtime metrics)
 sudo cscli collections inspect crowdsecurity/nginx
 
-# Upgrade
+# Refresh the hub index and upgrade (state-changing; apply the safety gate first)
 sudo cscli hub update
 sudo cscli collections upgrade crowdsecurity/nginx