vilvona 1.0.0

package/docs/cli/security.md

@@ -0,0 +1,135 @@
+---
+summary: "CLI reference for `openclaw security` (audit and fix common security footguns)"
+read_when:
+  - You want to run a quick security audit on config/state
+  - You want to apply safe "fix" suggestions (permissions, tighten defaults)
+title: "Security"
+---
+
+# `openclaw security`
+
+Security tools (audit + optional fixes).
+
+Related:
+
+- Security guide: [Security](/gateway/security)
+
+## Audit
+
+```bash
+openclaw security audit
+openclaw security audit --deep
+openclaw security audit --deep --password <password>
+openclaw security audit --deep --token <token>
+openclaw security audit --fix
+openclaw security audit --json
+```
+
+Plain `security audit` stays on the cold config/filesystem/read-only path. It does not discover plugin runtime security collectors by default, so routine audits do not load every installed plugin runtime. Use `--deep` to include best-effort live Gateway probes and plugin-owned security audit collectors; explicit internal callers may also opt into those plugin-owned collectors when they already have an appropriate runtime scope.
+
+The audit warns when multiple DM senders share the main session and recommends **secure DM mode**: `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
+This is for cooperative/shared inbox hardening. A single Gateway shared by mutually untrusted/adversarial operators is not a recommended setup; split trust boundaries with separate gateways (or separate OS users/hosts).
+It also emits `security.trust_model.multi_user_heuristic` when config suggests likely shared-user ingress (for example open DM/group policy, configured group targets, or wildcard sender rules), and reminds you that OpenClaw is a personal-assistant trust model by default.
+For intentional shared-user setups, the audit guidance is to sandbox all sessions, keep filesystem access workspace-scoped, and keep personal/private identities or credentials off that runtime.
+It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
+For webhook ingress, startup logs a non-fatal security warning and audit flags `hooks.token` reuse of active Gateway shared-secret auth values, including `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` and `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`. It also warns when:
+
+- `hooks.token` is short
+- `hooks.path="/"`
+- `hooks.defaultSessionKey` is unset
+- `hooks.allowedAgentIds` is unrestricted
+- request `sessionKey` overrides are enabled
+- overrides are enabled without `hooks.allowedSessionKeyPrefixes`
+
+If Gateway password auth is supplied only at startup, pass the same value to `openclaw security audit --auth password --password <password>` so the audit can check it against `hooks.token`.
+Run `openclaw doctor --fix` to rotate a persisted reused `hooks.token`, then update external hook senders to use the new hook token.
+
+It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when write/edit tools are disabled but `exec` is still available without a constraining sandbox filesystem boundary, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed plugin tools may be reachable under permissive tool policy.
+It also flags `gateway.allowRealIpFallback=true` (header-spoofing risk if proxies are misconfigured) and `discovery.mdns.mode="full"` (metadata leakage via mDNS TXT records).
+It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`.
+It also flags dangerous sandbox Docker network modes (including `host` and `container:*` namespace joins).
+It also warns when existing sandbox browser Docker containers have missing/stale hash labels (for example pre-migration containers missing `openclaw.browserConfigEpoch`) and recommends `openclaw sandbox recreate --browser --all`.
+It also warns when npm-based plugin/hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
+It warns when channel allowlists rely on mutable names/emails/tags instead of stable IDs (Discord, Slack, Google Chat, Microsoft Teams, Mattermost, IRC scopes where applicable).
+It warns when `gateway.auth.mode="none"` leaves Gateway HTTP APIs reachable without a shared secret (`/tools/invoke` plus any enabled `/v1/*` endpoint).
+Settings prefixed with `dangerous`/`dangerously` are explicit break-glass operator overrides; enabling one is not, by itself, a security vulnerability report.
+For the complete dangerous-parameter inventory, see the "Insecure or dangerous flags summary" section in [Security](/gateway/security).
+
+Intentional standing findings can be accepted with `security.audit.suppressions`.
+Each suppression matches an exact `checkId` and can be narrowed with
+`titleIncludes` and/or `detailIncludes` case-insensitive substrings:
+
+```json
+{
+  "security": {
+    "audit": {
+      "suppressions": [
+        {
+          "checkId": "plugins.tools_reachable_permissive_policy",
+          "detailIncludes": "Enabled extension plugins: gbrain",
+          "reason": "trusted local operator plugin"
+        }
+      ]
+    }
+  }
+}
+```
+
+Suppressed findings are removed from the active `summary` and `findings` list.
+JSON output keeps them under `suppressedFindings` for auditability.
+When suppressions are configured, active output also keeps an unsuppressible
+`security.audit.suppressions.active` info finding so readers can tell the audit
+was filtered. Dangerous config flags are emitted one flag per finding, so
+accepting one dangerous flag does not hide other enabled flags that share the
+same `config.insecure_or_dangerous_flags` checkId.
+Because suppressions can hide standing risk, adding or removing them through
+agent-run shell commands requires exec approval unless exec is already running
+with `security="full"` and `ask="off"` for trusted local automation.
+
+SecretRef behavior:
+
+- `security audit` resolves supported SecretRefs in read-only mode for its targeted paths.
+- If a SecretRef is unavailable in the current command path, audit continues and reports `secretDiagnostics` (instead of crashing).
+- `--token` and `--password` only override deep-probe auth for that command invocation; they do not rewrite config or SecretRef mappings.
+
+## JSON output
+
+Use `--json` for CI/policy checks:
+
+```bash
+openclaw security audit --json | jq '.summary'
+openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
+```
+
+If `--fix` and `--json` are combined, output includes both fix actions and final report:
+
+```bash
+openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
+```
+
+## What `--fix` changes
+
+`--fix` applies safe, deterministic remediations:
+
+- flips common `groupPolicy="open"` to `groupPolicy="allowlist"` (including account variants in supported channels)
+- when WhatsApp group policy flips to `allowlist`, seeds `groupAllowFrom` from
+  the stored `allowFrom` file when that list exists and config does not already
+  define `allowFrom`
+- sets `logging.redactSensitive` from `"off"` to `"tools"`
+- tightens permissions for state/config and common sensitive files
+  (`credentials/*.json`, `auth-profiles.json`, `sessions.json`, session
+  `*.jsonl`)
+- also tightens config include files referenced from `openclaw.json`
+- uses `chmod` on POSIX hosts and `icacls` resets on Windows
+
+`--fix` does **not**:
+
+- rotate tokens/passwords/API keys
+- disable tools (`gateway`, `cron`, `exec`, etc.)
+- change gateway bind/auth/network exposure choices
+- remove or rewrite plugins/skills
+
+## Related
+
+- [CLI reference](/cli)
+- [Security audit](/gateway/security)

package/docs/cli/sessions.md

@@ -0,0 +1,178 @@
+---
+summary: "CLI reference for `openclaw sessions` (list stored sessions + usage)"
+read_when:
+  - You want to list stored sessions and see recent activity
+title: "Sessions"
+---
+
+# `openclaw sessions`
+
+List stored conversation sessions.
+
+Session lists are not channel/provider liveness checks. They show persisted
+conversation rows from session stores. A quiet Discord, Slack, Telegram, or
+other channel can reconnect successfully without creating a new session row
+until a message is processed. Use `openclaw channels status --probe`,
+`openclaw status --deep`, or `openclaw health --verbose` when you need live
+channel connectivity.
+
+`openclaw sessions` and Gateway `sessions.list` responses are bounded by
+default so large long-lived stores cannot monopolize the CLI process or Gateway
+event loop. The CLI returns the newest 100 sessions by default; pass
+`--limit <n>` for a smaller/larger window or `--limit all` when you intentionally
+need the full store. JSON responses include `totalCount`, `limitApplied`, and
+`hasMore` when callers need to show that more rows exist.
+
+RPC clients can pass `configuredAgentsOnly: true` to keep the broad combined
+discovery source but return only rows for agents currently present in config.
+Control UI uses that mode by default so deleted or disk-only agent stores do
+not reappear in the Sessions view.
+
+```bash
+openclaw sessions
+openclaw sessions --agent work
+openclaw sessions --all-agents
+openclaw sessions --active 120
+openclaw sessions --limit 25
+openclaw sessions --verbose
+openclaw sessions --json
+```
+
+Scope selection:
+
+- default: configured default agent store
+- `--verbose`: verbose logging
+- `--agent <id>`: one configured agent store
+- `--all-agents`: aggregate all configured agent stores
+- `--store <path>`: explicit store path (cannot be combined with `--agent` or `--all-agents`)
+- `--limit <n|all>`: max rows to output (default `100`; `all` restores full output)
+
+Tail human-readable trajectory progress for stored sessions:
+
+```bash
+openclaw sessions tail
+openclaw sessions tail --follow
+openclaw sessions tail --session-key "agent:main:telegram:direct:123" --tail 25
+openclaw sessions --agent work tail --follow
+openclaw sessions --all-agents tail --follow
+```
+
+`openclaw sessions tail` renders recent trajectory JSONL events as compact progress lines. Without `--session-key`, it tails running sessions first, then the latest stored session. `--tail <count>` controls how many existing events print before follow mode; the default is `80`, and `0` starts at the current end. `--follow` keeps watching the selected trajectory files, including relocated files referenced by `<session>.trajectory-path.json`.
+
+The progress view is intentionally conservative: prompt text, tool arguments, and tool result bodies are not printed. Tool calls show the tool name with `{...redacted...}`; tool results show status such as `ok`, `error`, or `done`; model completion lines show provider/model and terminal status.
+
+Export a trajectory bundle for a stored session:
+
+```bash
+openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --workspace .
+openclaw sessions export-trajectory --session-key "agent:main:telegram:direct:123" --output bug-123 --json
+```
+
+This is the command path used by the `/export-trajectory` slash command after
+the owner approves the exec request. The output directory is always resolved
+inside `.openclaw/trajectory-exports/` under the selected workspace.
+
+`openclaw sessions --all-agents` reads configured agent stores. Gateway and ACP
+session discovery are broader: they also include disk-only stores found under
+the default `agents/` root or a templated `session.store` root. Those
+discovered stores must resolve to regular `sessions.json` files inside the
+agent root; symlinks and out-of-root paths are skipped.
+
+JSON examples:
+
+`openclaw sessions --all-agents --json`:
+
+```json
+{
+  "path": null,
+  "stores": [
+    { "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },
+    { "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }
+  ],
+  "allAgents": true,
+  "count": 2,
+  "totalCount": 2,
+  "limitApplied": 100,
+  "hasMore": false,
+  "activeMinutes": null,
+  "sessions": [
+    { "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
+    { "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
+  ]
+}
+```
+
+## Cleanup maintenance
+
+Run maintenance now (instead of waiting for the next write cycle):
+
+```bash
+openclaw sessions cleanup --dry-run
+openclaw sessions cleanup --agent work --dry-run
+openclaw sessions cleanup --all-agents --dry-run
+openclaw sessions cleanup --enforce
+openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
+openclaw sessions cleanup --dry-run --fix-dm-scope
+openclaw sessions cleanup --json
+```
+
+`openclaw sessions cleanup` uses `session.maintenance` settings from config:
+
+- Scope note: `openclaw sessions cleanup` maintains session stores, transcripts, and trajectory sidecars. It does not prune cron run history, which is managed by `cron.runLog.keepLines` in [Cron configuration](/automation/cron-jobs#configuration) and explained in [Cron maintenance](/automation/cron-jobs#maintenance).
+- Cleanup also prunes unreferenced primary transcripts, compaction checkpoints, and trajectory sidecars older than `session.maintenance.pruneAfter`; files still referenced by `sessions.json` are preserved.
+
+- `--dry-run`: preview how many entries would be pruned/capped without writing.
+  - In text mode, dry-run prints a per-session action table (`Action`, `Key`, `Age`, `Model`, `Flags`) so you can see what would be kept vs removed.
+- `--enforce`: apply maintenance even when `session.maintenance.mode` is `warn`.
+- `--fix-missing`: remove entries whose transcript files are missing or header-only/empty, even if they would not normally age/count out yet.
+- `--fix-dm-scope`: when `session.dmScope` is `main`, retire stale peer-keyed direct-DM rows left behind by earlier `per-peer`, `per-channel-peer`, or `per-account-channel-peer` routing. Use `--dry-run` first; applying the cleanup removes those rows from `sessions.json` and preserves their transcripts as deleted archives.
+- `--active-key <key>`: protect a specific active key from disk-budget eviction. Durable external conversation pointers, such as group sessions and thread-scoped chat sessions, are also kept by age/count/disk-budget maintenance.
+- `--agent <id>`: run cleanup for one configured agent store.
+- `--all-agents`: run cleanup for all configured agent stores.
+- `--store <path>`: run against a specific `sessions.json` file.
+- `--json`: print a JSON summary. With `--all-agents`, output includes one summary per store.
+
+When a Gateway is reachable, non-dry-run cleanup for configured agent stores is
+sent through the Gateway so it shares the same session-store writer as runtime
+traffic. Use `--store <path>` for explicit offline repair of a store file.
+
+`openclaw sessions cleanup --all-agents --dry-run --json`:
+
+```json
+{
+  "allAgents": true,
+  "mode": "warn",
+  "dryRun": true,
+  "stores": [
+    {
+      "agentId": "main",
+      "storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
+      "beforeCount": 120,
+      "afterCount": 80,
+      "missing": 0,
+      "dmScopeRetired": 0,
+      "pruned": 40,
+      "capped": 0
+    },
+    {
+      "agentId": "work",
+      "storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
+      "beforeCount": 18,
+      "afterCount": 18,
+      "missing": 0,
+      "dmScopeRetired": 0,
+      "pruned": 0,
+      "capped": 0
+    }
+  ]
+}
+```
+
+Related:
+
+- Session config: [Configuration reference](/gateway/config-agents#session)
+
+## Related
+
+- [CLI reference](/cli)
+- [Session management](/concepts/session)

package/docs/cli/setup.md

@@ -0,0 +1,60 @@
+---
+summary: "CLI reference for `openclaw setup` (initialize config plus workspace, optionally run onboarding)"
+read_when:
+  - You're doing first-run setup without full CLI onboarding
+  - You want to set the default workspace path
+  - You need every flag and how setup decides between baseline and wizard mode
+title: "Setup"
+---
+
+# `openclaw setup`
+
+Initialize the baseline config and agent workspace. With any onboarding flag present, also runs the wizard.
+
+<Note>
+`openclaw setup` is for mutable config installs. In Nix mode (`OPENCLAW_NIX_MODE=1`) OpenClaw refuses setup writes because the config file is managed by Nix. Use the first-party [nix-openclaw Quick Start](https://github.com/openclaw/nix-openclaw#quick-start) or the equivalent source config for another Nix package.
+</Note>
+
+## Options
+
+| Flag                       | Description                                                                                         |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| `--workspace <dir>`        | Agent workspace directory (default `~/.openclaw/workspace`; stored as `agents.defaults.workspace`). |
+| `--wizard`                 | Run interactive onboarding.                                                                         |
+| `--non-interactive`        | Run onboarding without prompts.                                                                     |
+| `--accept-risk`            | Acknowledge full-system agent access risk; required with `--non-interactive`.                       |
+| `--mode <mode>`            | Onboarding mode: `local` or `remote`.                                                               |
+| `--import-from <provider>` | Migration provider to run during onboarding.                                                        |
+| `--import-source <path>`   | Source agent home for `--import-from`.                                                              |
+| `--import-secrets`         | Import supported secrets during onboarding migration.                                               |
+| `--remote-url <url>`       | Remote Gateway WebSocket URL.                                                                       |
+| `--remote-token <token>`   | Remote Gateway token (optional).                                                                    |
+
+### Wizard auto-trigger
+
+`openclaw setup` runs the wizard when any of these flags are explicitly present, even without `--wizard`:
+
+`--wizard`, `--non-interactive`, `--accept-risk`, `--mode`, `--import-from`, `--import-source`, `--import-secrets`, `--remote-url`, `--remote-token`.
+
+## Examples
+
+```bash
+openclaw setup
+openclaw setup --workspace ~/.openclaw/workspace
+openclaw setup --wizard
+openclaw setup --wizard --import-from hermes --import-source ~/.hermes
+openclaw setup --non-interactive --accept-risk --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
+```
+
+## Notes
+
+- Plain `openclaw setup` initializes config and workspace without running the full onboarding flow.
+- After plain setup, run `openclaw onboard` for the full guided journey, `openclaw configure` for targeted changes, or `openclaw channels add` to add channel accounts.
+- If Hermes state is detected, interactive onboarding can offer migration automatically. Import onboarding requires a fresh setup; use [Migrate](/cli/migrate) for dry-run plans, backups, and overwrite mode outside onboarding.
+
+## Related
+
+- [CLI reference](/cli)
+- [Onboarding (CLI)](/start/wizard)
+- [Getting started](/start/getting-started)
+- [Install overview](/install)

package/docs/cli/skills.md

@@ -0,0 +1,156 @@
+---
+summary: "CLI reference for `openclaw skills` (search/install/update/verify/list/info/check/workshop)"
+read_when:
+  - You want to see which skills are available and ready to run
+  - You want to search ClawHub or install skills from ClawHub, Git, or local directories
+  - You want to verify a ClawHub skill with ClawHub
+  - You want to debug missing binaries/env/config for skills
+title: "Skills"
+---
+
+# `openclaw skills`
+
+Inspect local skills, search ClawHub, install skills from ClawHub/Git/local
+directories, verify ClawHub skills, and update ClawHub-tracked installs.
+
+Related:
+
+- Skills system: [Skills](/tools/skills)
+- Skill Workshop: [Skill Workshop](/tools/skill-workshop)
+- Skills config: [Skills config](/tools/skills-config)
+- ClawHub installs: [ClawHub](/clawhub/cli)
+
+## Commands
+
+```bash
+openclaw skills search "calendar"
+openclaw skills search --limit 20 --json
+openclaw skills install <slug>
+openclaw skills install <slug> --version <version>
+openclaw skills install git:owner/repo
+openclaw skills install git:owner/repo@main
+openclaw skills install ./path/to/skill --as custom-name
+openclaw skills install <slug> --force
+openclaw skills install <slug> --agent <id>
+openclaw skills install <slug> --global
+openclaw skills update <slug>
+openclaw skills update <slug> --global
+openclaw skills update --all
+openclaw skills update --all --agent <id>
+openclaw skills update --all --global
+openclaw skills verify <slug>
+openclaw skills verify <slug> --version <version>
+openclaw skills verify <slug> --tag <tag>
+openclaw skills verify <slug> --card
+openclaw skills verify <slug> --global
+openclaw skills list
+openclaw skills list --eligible
+openclaw skills list --json
+openclaw skills list --verbose
+openclaw skills list --agent <id>
+openclaw skills info <name>
+openclaw skills info <name> --json
+openclaw skills info <name> --agent <id>
+openclaw skills check
+openclaw skills check --agent <id>
+openclaw skills check --json
+openclaw skills workshop propose-create --name "qa-check" --description "QA checklist" --proposal ./PROPOSAL.md
+openclaw skills workshop propose-update qa-check --proposal ./PROPOSAL.md
+openclaw skills workshop list
+openclaw skills workshop inspect <proposal-id>
+openclaw skills workshop revise <proposal-id> --proposal ./PROPOSAL.md
+openclaw skills workshop apply <proposal-id>
+openclaw skills workshop reject <proposal-id> --reason "Not reusable"
+openclaw skills workshop quarantine <proposal-id> --reason "Needs security review"
+```
+
+`search`, `update`, and `verify` use ClawHub directly. `install <slug>` installs
+a ClawHub skill, `install git:owner/repo[@ref]` clones a Git skill, and
+`install ./path` copies a local skill directory. By default, `install`, `update`,
+and `verify` target the active workspace `skills/` directory; with `--global`,
+they target the shared managed skills directory. `list`/`info`/`check` still
+inspect the local skills visible to the current workspace and config.
+Workspace-backed commands resolve the target workspace from `--agent <id>`, then
+the current working directory when it is inside a configured agent workspace,
+then the default agent.
+
+Git and local directory installs expect `SKILL.md` at the source root. The
+install slug comes from `SKILL.md` frontmatter `name` when it is valid, then the
+source directory or repository name; use `--as <slug>` to override it. `--version`
+is ClawHub-only. Skill installs do not support npm package specs or zip/archive
+paths, and `openclaw skills update` updates ClawHub-tracked installs only.
+
+Gateway-backed skill dependency installs triggered from onboarding or Skills
+settings use the separate `skills.install` request path instead.
+
+Notes:
+
+- `search [query...]` accepts an optional query; omit it to browse the default
+  ClawHub search feed.
+- `search --limit <n>` caps returned results.
+- `install git:owner/repo[@ref]` installs a Git skill. Branch refs may contain
+  slashes, such as `git:owner/repo@feature/foo`.
+- `install ./path/to/skill` installs a local directory whose root contains
+  `SKILL.md`.
+- `install --as <slug>` overrides the inferred slug for Git and local directory
+  installs.
+- `install --version <version>` applies only to ClawHub skill slugs.
+- `install --force` overwrites an existing workspace skill folder for the same
+  slug.
+- `--global` targets the shared managed skills directory and cannot be combined
+  with `--agent <id>`.
+- `--agent <id>` targets one configured agent workspace and overrides current
+  working directory inference.
+- `update <slug>` updates a single tracked skill. Add `--global` to target the
+  shared managed skills directory instead of the workspace.
+- `update --all` updates tracked ClawHub installs in the selected workspace, or
+  in the shared managed skills directory when combined with `--global`.
+- `verify <slug>` prints ClawHub's `clawhub.skill.verify.v1` JSON envelope by
+  default. There is no `--json` flag because JSON is already the default.
+- `verify` uses `.clawhub/origin.json` for installed ClawHub skills, so it
+  verifies the installed version against the registry it came from. `--version`
+  and `--tag` override the version selector but keep that installed registry
+  when origin metadata exists.
+- `verify --card` prints the generated Skill Card Markdown instead of JSON. The
+  command exits non-zero when ClawHub returns `ok: false` or `decision: "fail"`;
+  unsigned signatures are informational unless ClawHub policy changes.
+- Installed ClawHub bundles can include a generated `skill-card.md`. OpenClaw
+  treats verification as a ClawHub server decision and does not reject an
+  installed skill just because that generated card changes the bundle
+  fingerprint.
+- `check --agent <id>` checks the selected agent's workspace and reports which
+  ready skills are actually visible to that agent's prompt or command surface.
+- `list` is the default action when no subcommand is provided.
+- `list`, `info`, and `check` write their rendered output to stdout. With
+  `--json`, that means the machine-readable payload stays on stdout for pipes
+  and scripts.
+
+## Skill Workshop
+
+`openclaw skills workshop` manages pending skill proposals in the selected
+workspace. Proposals are not active skills until applied. For proposal storage,
+support-file safeguards, Gateway methods, and approval policy, see
+[Skill Workshop](/tools/skill-workshop).
+
+```bash
+openclaw skills workshop propose-create \
+  --name "qa-check" \
+  --description "Repeatable QA checklist" \
+  --proposal ./PROPOSAL.md
+openclaw skills workshop propose-create \
+  --name "qa-check" \
+  --description "Repeatable QA checklist" \
+  --proposal-dir ./qa-check-proposal
+openclaw skills workshop propose-update qa-check --proposal ./PROPOSAL.md
+openclaw skills workshop list
+openclaw skills workshop inspect <proposal-id>
+openclaw skills workshop revise <proposal-id> --proposal ./PROPOSAL.md
+openclaw skills workshop apply <proposal-id>
+openclaw skills workshop reject <proposal-id> --reason "Duplicate"
+openclaw skills workshop quarantine <proposal-id> --reason "Needs security review"
+```
+
+## Related
+
+- [CLI reference](/cli)
+- [Skills](/tools/skills)

package/docs/cli/status.md

@@ -0,0 +1,45 @@
+---
+summary: "CLI reference for `openclaw status` (diagnostics, probes, usage snapshots)"
+read_when:
+  - You want a quick diagnosis of channel health + recent session recipients
+  - You want a pasteable "all" status for debugging
+title: "openclaw status"
+---
+
+Diagnostics for channels + sessions.
+
+```bash
+openclaw status
+openclaw status --all
+openclaw status --deep
+openclaw status --usage
+```
+
+Notes:
+
+- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
+- Plain `openclaw status` stays on the fast read-only path and marks memory as `not checked` instead of unavailable when it skips memory inspection. Heavy security audit, plugin compatibility, and memory-vector probes are left to `openclaw status --all`, `openclaw status --deep`, `openclaw security audit`, and `openclaw memory status --deep`.
+- `status --json --all` reports memory details from the active memory plugin runtime selected by `plugins.slots.memory`. Custom memory plugins can leave built-in `agents.defaults.memorySearch.enabled` disabled and still report their own files, chunks, vector, and FTS state.
+- `--usage` prints normalized provider usage windows as `X% left`.
+- Session status output separates `Execution:` from `Runtime:`. `Execution` is the sandbox path (`direct`, `docker/*`), while `Runtime` tells you whether the session is using `OpenClaw Default`, `OpenAI Codex`, a CLI backend, or an ACP backend such as `codex (acp/acpx)`. See [Agent runtimes](/concepts/agent-runtimes) for the provider/model/runtime distinction.
+- MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so OpenClaw inverts them before display; count-based fields win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label.
+- When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values.
+- `/status` includes compact Gateway process uptime and host system uptime.
+- Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one.
+- When a session is pinned to a model that differs from the configured primary, status prints both values, the reason (`session override`), and the clear hint (`/model <configured-default>` or `/reset`). The configured primary applies to new or unpinned sessions; existing pinned sessions keep their session selection until cleared.
+- For prompt-size accounting, transcript fallback prefers the larger prompt-oriented total when session metadata is missing or smaller, so custom-provider sessions do not collapse to `0` token displays.
+- Output includes per-agent session stores when multiple agents are configured.
+- Overview includes Gateway + node host service install/runtime status when available.
+- Overview includes update channel + git SHA (for source checkouts).
+- Update info surfaces in the Overview; if an update is available, status prints a hint to run `openclaw update` (see [Updating](/install/updating)).
+- Model pricing refresh failures are shown as optional pricing warnings. They do
+  not mean the Gateway or channels are unhealthy.
+- Read-only status surfaces (`status`, `status --json`, `status --all`) resolve supported SecretRefs for their targeted config paths when possible.
+- If a supported channel SecretRef is configured but unavailable in the current command path, status stays read-only and reports degraded output instead of crashing. Human output shows warnings such as "configured token unavailable in this command path", and JSON output includes `secretDiagnostics`.
+- When command-local SecretRef resolution succeeds, status prefers the resolved snapshot and clears transient "secret unavailable" channel markers from the final output.
+- `status --all` includes a Secrets overview row and a diagnosis section that summarizes secret diagnostics (truncated for readability) without stopping report generation.
+
+## Related
+
+- [CLI reference](/cli)
+- [Doctor](/gateway/doctor)

package/docs/cli/system.md

@@ -0,0 +1,89 @@
+---
+summary: "CLI reference for `openclaw system` (system events, heartbeat, presence)"
+read_when:
+  - You want to enqueue a system event without creating a cron job
+  - You need to enable or disable heartbeats
+  - You want to inspect system presence entries
+title: "System"
+---
+
+# `openclaw system`
+
+System-level helpers for the Gateway: enqueue system events, control heartbeats,
+and view presence.
+
+All `system` subcommands use Gateway RPC and accept the shared client flags:
+
+- `--url <url>`
+- `--token <token>`
+- `--timeout <ms>`
+- `--expect-final`
+
+## Common commands
+
+```bash
+openclaw system event --text "Check for urgent follow-ups" --mode now
+openclaw system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
+openclaw system heartbeat enable
+openclaw system heartbeat last
+openclaw system presence
+```
+
+## `system event`
+
+Enqueue a system event on the **main** session by default. The next heartbeat
+will inject it as a `System:` line in the prompt. Use `--mode now` to trigger
+the heartbeat immediately; `next-heartbeat` waits for the next scheduled tick.
+
+Pass `--session-key` to target a specific session (for example to relay an
+async-task completion back to the channel that started it).
+
+> **Timing exception with `--session-key`:** when `--session-key` is supplied,
+> `--mode next-heartbeat` collapses to an immediate targeted wake instead of
+> waiting for the next scheduled tick. Targeted wakes use heartbeat intent
+> `immediate` so they bypass the runner's not-due gate that would otherwise
+> defer (and effectively drop) an `event`-intent wake. If you want delayed
+> delivery, omit `--session-key` so the event lands on the main session and
+> rides the next regular heartbeat.
+
+Flags:
+
+- `--text <text>`: required system event text.
+- `--mode <mode>`: `now` or `next-heartbeat` (default).
+- `--session-key <sessionKey>`: optional; target a specific agent session
+  instead of the agent's main session. Keys that do not belong to the
+  resolved agent fall back to the agent's main session.
+- `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
+
+## `system heartbeat last|enable|disable`
+
+Heartbeat controls:
+
+- `last`: show the last heartbeat event.
+- `enable`: turn heartbeats back on (use this if they were disabled).
+- `disable`: pause heartbeats.
+
+Flags:
+
+- `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
+
+## `system presence`
+
+List the current system presence entries the Gateway knows about (nodes,
+instances, and similar status lines).
+
+Flags:
+
+- `--json`: machine-readable output.
+- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
+
+## Notes
+
+- Requires a running Gateway reachable by your current config (local or remote).
+- System events are ephemeral and not persisted across restarts.
+
+## Related
+
+- [CLI reference](/cli)