docs: sync with goclaw source changes c5bfbc96..c083622f (EN+VI+ZH) (#47)

P1 — High priority updates:
- reference/database-schema: migration 036 (secure_cli_agent_grants table)
- agents/system-prompt-anatomy: 19+ → 23 sections, added Credentialed CLI
- deployment/upgrading: added migration 036
- advanced/cli-credentials: full per-agent grants documentation
- providers/openai: reasoning_defaults + override_mode API

P2 — Medium priority updates:
- providers/overview: BytePlus Seedream/Seedance, Codex pool routing
- core-concepts/tools-overview: BytePlus media tools
- channels/slack: mention dedup behavior
- advanced/exec-approval: 15 shell deny groups + per-agent override
- reference/rest-api: CLI credential agent grants endpoints
- reference/websocket-protocol: VI/ZH sync

P3 — Verified & fixed:
- advanced/skills: 5-tier → 6-tier hierarchy fix
- advanced/api-keys-rbac: no-auth role RoleOperator → RoleAdmin fix
- reference/config-reference: pending_compaction defaults 50/15 → 200/40
- deployment/security-hardening, advanced/sandbox: SHA bump (accurate)

Author: thieung

advanced/api-keys-rbac.md

@@ -63,7 +63,7 @@ A key can hold multiple scopes — the highest-privilege scope wins.
 
 ## Backward Compatibility
 
-If `GOCLAW_GATEWAY_TOKEN` is empty (no gateway token configured), all requests — including unauthenticated ones — are granted `RoleOperator` access automatically. This lets self-hosted setups work without strict auth. Once a token is set, all requests must provide valid credentials or they receive `401 Unauthorized`.
+If `gateway.token` is empty (no gateway token configured), all requests — including unauthenticated ones — are granted `RoleAdmin` access automatically. This lets self-hosted setups work without strict auth. Once a token is set, all requests must provide valid credentials or they receive `401 Unauthorized`.
 
 ---
 
@@ -259,4 +259,4 @@ When a key is created or revoked, a `cache.invalidate` event is broadcast on the
 - [Security Hardening](/deploy-security) — full 5-layer permission overview
 - [CLI Credentials](./cli-credentials.md) — SecureCLI: inject credentials into CLI tools (gh, aws, gcloud) without exposing secrets to the agent
 
-<!-- goclaw-source: 57754a5 | updated: 2026-03-23 -->
+<!-- goclaw-source: c083622f | updated: 2026-04-05 -->

advanced/cli-credentials.md

@@ -1,17 +1,146 @@
 # CLI Credentials
 
-> Securely store and manage named credential sets for shell tool execution.
-
-🚧 **This page is under construction.** Content coming soon.
+> Securely store and manage named credential sets for shell tool execution, with per-agent access control via grants.
 
 ## Overview
 
-CLI Credentials let you define named credential sets (API keys, tokens, connection strings) that agents can reference when running shell commands via the `exec` tool — without exposing secrets in the system prompt or conversation history. Includes built-in preset templates for common tools.
+CLI Credentials let you define named credential sets (API keys, tokens, connection strings) that agents can reference when running shell commands via the `exec` tool — without exposing secrets in the system prompt or conversation history.
+
+Each credential is stored as a **secure CLI binary** — a named configuration that maps a binary (e.g. `gh`, `gcloud`, `aws`) to an AES-256-GCM encrypted set of environment variables. When an agent runs the binary, GoClaw decrypts the env vars and injects them into the child process at execution time.
+
+## Global vs Per-Agent Binaries
+
+Since migration 036, the access model uses a **grants system** instead of per-binary agent assignment:
+
+- **Global binaries** (`is_global = true`): available to all agents unless a grant overrides settings
+- **Restricted binaries** (`is_global = false`): only accessible to agents that have an explicit grant
+
+This separates credential definition from access control, allowing you to define a binary once and grant it to specific agents with optional per-agent overrides.
+
+```
+secure_cli_binaries (credential + defaults)
+        │
+        ├── is_global = true  → all agents can use it
+        └── is_global = false → only agents with a grant
+                    │
+                    └── secure_cli_agent_grants (per-agent override)
+                            ├── deny_args (NULL = use binary default)
+                            ├── deny_verbose (NULL = use binary default)
+                            ├── timeout_seconds (NULL = use binary default)
+                            ├── tips (NULL = use binary default)
+                            └── enabled
+```
+
+## Agent Grants
+
+The `secure_cli_agent_grants` table links a binary to a specific agent and optionally overrides any of the binary's default settings. `NULL` fields inherit the binary default.
+
+| Field | Behaviour |
+|-------|-----------|
+| `deny_args` | Override forbidden argument patterns for this agent |
+| `deny_verbose` | Override verbose flag stripping for this agent |
+| `timeout_seconds` | Override process timeout for this agent |
+| `tips` | Override the hint injected into TOOLS.md for this agent |
+| `enabled` | Disable a grant without deleting it |
+
+When an agent runs a binary, GoClaw resolves settings in this order:
+1. Binary defaults
+2. Grant overrides (any non-null fields replace the binary default)
+
+## REST API
+
+All grant endpoints are nested under the binary resource and require the `admin` role.
+
+### List grants for a binary
+
+```
+GET /v1/cli-credentials/{id}/agent-grants
+```
+
+```json
+{
+  "grants": [
+    {
+      "id": "019...",
+      "binary_id": "019...",
+      "agent_id": "019...",
+      "deny_args": null,
+      "timeout_seconds": 60,
+      "enabled": true,
+      "created_at": "2026-04-05T00:00:00Z",
+      "updated_at": "2026-04-05T00:00:00Z"
+    }
+  ]
+}
+```
+
+### Create a grant
+
+```
+POST /v1/cli-credentials/{id}/agent-grants
+```
+
+```json
+{
+  "agent_id": "019...",
+  "timeout_seconds": 120,
+  "tips": "Use --output json for all commands"
+}
+```
+
+Omitted fields (`deny_args`, `deny_verbose`, `tips`, `enabled`) default to `null` / `true`.
+
+### Get a grant
+
+```
+GET /v1/cli-credentials/{id}/agent-grants/{grantId}
+```
+
+### Update a grant
+
+```
+PUT /v1/cli-credentials/{id}/agent-grants/{grantId}
+```
+
+Send only the fields to change. Allowed fields: `deny_args`, `deny_verbose`, `timeout_seconds`, `tips`, `enabled`.
+
+### Delete a grant
+
+```
+DELETE /v1/cli-credentials/{id}/agent-grants/{grantId}
+```
+
+Deleting a grant from a restricted binary (`is_global = false`) immediately revokes the agent's access to that binary.
+
+## Common Patterns
+
+### Allow only one agent to use a sensitive CLI tool
+
+1. Create the binary with `is_global = false`
+2. Create a grant for the target agent
+
+### Give all agents access but restrict args for one agent
+
+1. Create the binary with `is_global = true`
+2. Create a grant for the restricted agent with `deny_args` set to additional blocked patterns
+
+### Temporarily disable an agent's access
+
+Update the grant: `{"enabled": false}`. The binary remains accessible to other agents.
+
+## Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| Agent cannot run a binary | Check `is_global` on the binary — if `false`, the agent needs an explicit grant |
+| Grant overrides not applied | Verify the grant `enabled = true` and that override fields are non-null |
+| `403` on grant endpoints | Requires admin role — check API key scopes |
 
 ## What's Next
 
+- [Database Schema → secure_cli_agent_grants](/database-schema)
 - [Exec Approval](/exec-approval)
 - [API Keys & RBAC](/api-keys-rbac)
 - [Security Hardening](/deploy-security)
 
-<!-- goclaw-source: 57754a5 | updated: 2026-03-18 -->
+<!-- goclaw-source: c083622f | updated: 2026-04-05 -->

advanced/exec-approval.md

@@ -180,6 +180,69 @@ Set `"always": true` to permanently allow this binary for the lifetime of the pr
 
 ---
 
+## Shell Deny Groups
+
+In addition to the approval flow, GoClaw applies **deny groups** — named sets of shell command patterns that are blocked regardless of approval settings. All groups are enabled by default.
+
+### Available Deny Groups
+
+| Group | Description | Examples Blocked |
+|-------|-------------|-----------------|
+| `destructive_ops` | Destructive Operations | `rm -rf`, `dd if=`, `shutdown`, fork bombs |
+| `data_exfiltration` | Data Exfiltration | `curl \| sh`, `wget --post-data`, DNS lookups via dig/nslookup |
+| `reverse_shell` | Reverse Shell | `nc`, `socat`, `python -c '...socket...'`, `mkfifo` |
+| `code_injection` | Code Injection & Eval | `eval $()`, `base64 -d \| sh` |
+| `privilege_escalation` | Privilege Escalation | `sudo`, `su`, `mount`, `nsenter`, `pkexec` |
+| `dangerous_paths` | Dangerous Path Operations | `chmod +x /tmp/...`, `chown ... /` |
+| `env_injection` | Environment Variable Injection | `LD_PRELOAD=`, `DYLD_INSERT_LIBRARIES=`, `BASH_ENV=` |
+| `container_escape` | Container Escape | `/var/run/docker.sock`, `/proc/sys/kernel/`, `/sys/kernel/` |
+| `crypto_mining` | Crypto Mining | `xmrig`, `cpuminer`, `stratum+tcp://` |
+| `filter_bypass` | Filter Bypass (CVE mitigations) | `sed .../e`, `sort --compress-program`, `git --upload-pack=` |
+| `network_recon` | Network Reconnaissance & Tunneling | `nmap`, `ssh user@host`, `ngrok`, `chisel` |
+| `package_install` | Package Installation | `pip install`, `npm install`, `apk add` |
+| `persistence` | Persistence Mechanisms | `crontab`, writing to `~/.bashrc` or `~/.profile` |
+| `process_control` | Process Manipulation | `kill -9`, `killall`, `pkill` |
+| `env_dump` | Environment Variable Dumping | `printenv`, `env \| ...`, reading `GOCLAW_` secrets |
+
+### Per-Agent Deny Group Overrides
+
+Each agent can selectively enable or disable specific deny groups via `shell_deny_groups` in its config. This is a `map[string]bool` where `true` means deny (block) and `false` means allow (unblock).
+
+All groups default to `true` (denied). Explicitly set a group to `false` to allow those commands for a specific agent.
+
+**Example: allow package installs but keep everything else blocked**
+
+```json
+{
+  "agents": {
+    "my-agent": {
+      "shell_deny_groups": {
+        "package_install": false
+      }
+    }
+  }
+}
+```
+
+**Example: allow SSH/tunneling for a DevOps agent, but block crypto mining**
+
+```json
+{
+  "agents": {
+    "devops-agent": {
+      "shell_deny_groups": {
+        "network_recon": false,
+        "crypto_mining": true
+      }
+    }
+  }
+}
+```
+
+Deny groups and the exec approval flow operate independently — a command can pass the deny-group check but still be held for human approval based on your `ask` mode setting.
+
+---
+
 ## Common Issues
 
 | Problem | Cause | Fix |
@@ -198,4 +261,4 @@ Set `"always": true` to permanently allow this binary for the lifetime of the pr
 - [Custom Tools](/custom-tools) — define tools backed by shell commands
 - [Security Hardening](/deploy-security) — full five-layer security overview
 
-<!-- goclaw-source: 57754a5 | updated: 2026-03-18 -->
+<!-- goclaw-source: c083622f | updated: 2026-04-05 -->

advanced/sandbox.md

@@ -246,4 +246,4 @@ docker ps --filter "label=goclaw.sandbox=true"
 - [Exec Approval](/exec-approval) — require human approval before any command runs, sandboxed or not
 - [Scheduling & Cron](/scheduling-cron) — run sandboxed agent turns on a schedule
 
-<!-- goclaw-source: 941a965 | updated: 2026-03-19 -->
+<!-- goclaw-source: c083622f | updated: 2026-04-05 -->

advanced/skills.md

@@ -48,19 +48,20 @@ The `{baseDir}` placeholder is replaced at load time with the absolute path to t
 | `name` | Human-readable display name (defaults to directory name) |
 | `description` | One-line summary used by `skill_search` to match queries |
 
-## 5-Tier Hierarchy
+## 6-Tier Hierarchy
 
-GoClaw loads skills from five locations in priority order. A skill in a higher-priority location overrides one with the same slug from a lower one:
+GoClaw loads skills from six locations in priority order. A skill in a higher-priority location overrides one with the same slug from a lower one:
 
 | Priority | Location | Source label |
 |---|---|---|
 | 1 (highest) | `<workspace>/skills/` | `workspace` |
 | 2 | `<workspace>/.agents/skills/` | `agents-project` |
 | 3 | `~/.agents/skills/` | `agents-personal` |
-| 4 | `~/.goclaw/skills/` (managed DB) | `managed-skills` |
-| 5 (lowest) | Built-in (bundled with binary) | `builtin` |
+| 4 | `~/.goclaw/skills/` | `global` |
+| 5 | `~/.goclaw/skills-store/` (DB-seeded, versioned) | `managed` |
+| 6 (lowest) | Built-in (bundled with binary) | `builtin` |
 
-Skills uploaded via the Dashboard are stored in `~/.goclaw/skills-store/` (managed directory, backed by PostgreSQL) and act at the `managed-skills` level. The `file_path` DB column is used to resolve the versioned directory for each skill on disk.
+Skills uploaded via the Dashboard are stored in `~/.goclaw/skills-store/` using a versioned subdirectory structure (`<slug>/<version>/SKILL.md`). They act at the `managed` level — above builtin but below the four file-system tiers. The loader always serves the highest-numbered version for each slug.
 
 **Precedence example:** if you have a `code-reviewer` skill in both `~/.goclaw/skills/` and `<workspace>/skills/`, the workspace version wins.
 
@@ -342,4 +343,4 @@ See [Agent Evolution](agent-evolution.md) for full details on the `skill_manage`
 - [Custom Tools](/custom-tools) — add shell-backed tools to your agents
 - [Scheduling & Cron](/scheduling-cron) — run agents on a schedule
 
-<!-- goclaw-source: 941a965 | updated: 2026-03-23 -->
+<!-- goclaw-source: c083622f | updated: 2026-04-05 -->