docs(catalog): clarify CLI and CrowdSec contracts

Clarify state-changing CrowdSec hub updates and frame CLI Builder idempotency and JSON as contracts.

cli-builder/README.md

@@ -4,11 +4,11 @@ A comprehensive design guide and scaffold for building CLI tools that **AI agent
 
 ## Why Install This Skill
 
-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:
+When your agent loads this skill, it can **design, build, and refactor CLI tools** that agents can discover and use without human help. The goal is to establish and review explicit contracts for help, output, safety, and repeatable operations:
 
-- **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
+- **Treat `--help` as a contract** the agent parses to understand your tool
+- **Establish a documented `--json` contract** for machine-readable output, when the CLI supports it
+- **Design and verify idempotent operations** where repeatability is appropriate, with `--dry-run` previews for changes
 - **Authentication is lazy** — help and dry-run work without credentials
 - **Errors are structured** — different exit codes for different failure modes
 

crowdsec/SKILL.md

@@ -72,7 +72,8 @@ 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 version
+cscli hub list
 cscli collections list
 cscli alerts list --contain "scenario:ssh-bf"
 cscli decisions list -o json
@@ -80,9 +81,13 @@ cscli metrics -o json
 cscli explain --file /path/to/sample.log
 ```
 
-Manage hub items with `collections|parsers|scenarios install/list/upgrade/inspect`.
-Manage alerts and decisions with `alerts list/inspect` and
-`decisions add/list/delete`; mutation commands require the safety gate above.
+`cscli hub update` refreshes the local hub index and can change local state. It
+is optional, not part of the read-only triage path, and requires the safety gate
+above before running it. Manage hub items with
+`collections|parsers|scenarios install/list/upgrade/inspect`; those install,
+upgrade, and delete operations also require the safety gate. Manage alerts and
+decisions with `alerts list/inspect` and `decisions add/list/delete`; mutation
+commands require the safety gate above.
 Manage bouncers and machines with `bouncers add/list/delete` and
 `machines add/list/delete`. Use `console status`, `console enroll`, and
 `lapi register` only after confirming the destination and credentials. Load the

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; refreshing them with `cscli hub update` changes the local hub index, so treat it as an optional operation subject to the mutation safety gate.
 
 ## Gotchas
 

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` | Update the local hub index (state-changing; run only after the mutation safety gate) |
 | `cscli hub list` | List hub index info |
 | `cscli collections install <name>` | Install a collection |
 | `cscli collections list` | List installed collections |

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, then upgrade (state-changing; confirm the safety gate first)
 sudo cscli hub update
 sudo cscli collections upgrade crowdsecurity/nginx