@f4bioo/berry-shield 2026.3.3-1

package/docs/wiki/operation/cli/add.md

@@ -0,0 +1,157 @@
+---
+summary: "CLI reference for `openclaw bshield add` (create custom security rules via wizard or direct arguments)"
+read_when:
+  - You need to add custom secret, file, or command rules
+  - You want interactive rule creation with guided prompts
+title: "add"
+---
+
+# `openclaw bshield add`
+
+Add one custom Berry Shield rule, either through an interactive wizard or direct command arguments.
+
+## What it does
+- Opens the rule wizard when required arguments are missing.
+- Supports direct rule creation with command arguments.
+- Stores the new custom rule in persistent custom rule storage.
+- Prints operation success or failure details.
+
+## When to use
+- Adding organization-specific token patterns.
+- Adding custom sensitive file patterns.
+- Adding custom destructive command patterns.
+
+## Syntax
+
+### Interactive mode
+Use this to create a rule with guided prompts.
+```bash
+openclaw bshield add
+```
+Expected: Wizard prompts for type, pattern details, and confirmation.
+
+### Direct mode
+Use this when rule values are already known.
+```bash
+openclaw bshield add [type] --name <name> --pattern <regex>
+```
+Expected: CLI adds the rule directly and prints summary details.
+
+## Options
+Positional argument:
+- `[type]`: rule category selected by wizard or passed directly.
+
+Flags:
+- `--name <name>`: technical identifier for secret, file, and command rules.
+- `--pattern <regex>`: regex pattern to match.
+- `--placeholder <text>`: redaction placeholder for secret rules.
+- `--force`: overwrite existing custom rule with same identifier.
+
+## Examples
+
+### Add a secret rule directly
+Use this when you already have a validated token regex.
+```bash
+openclaw bshield add secret --name MyToken --pattern "sk_live_[0-9a-z]{24}"
+```
+Result: Rule is persisted as a custom secret rule.
+
+### Add a sensitive file rule directly
+Use this for local paths that should be treated as sensitive.
+```bash
+openclaw bshield add file --name team-key --pattern "/srv/app/keys/team.key"
+```
+Result: Rule is persisted as a custom sensitive file rule (`id: file:team-key`).
+
+### Add a destructive command rule directly
+Use this for command patterns that should be blocked as destructive.
+```bash
+openclaw bshield add command --name dangerous-rm-tmp --pattern "^(?:rm\\s+-rf\\s+/tmp/smoke)$"
+```
+Result: Rule is persisted as a custom destructive command rule (`id: command:dangerous-rm-tmp`).
+
+## Common errors
+
+### Invalid regex pattern
+Use this when pattern compilation is invalid.
+```bash
+openclaw bshield add secret --name BrokenRegex --pattern "(abc"
+```
+Expected: CLI fails with pattern validation/storage error.
+
+Other frequent failure causes:
+- Missing required values in direct mode.
+- Duplicate rule identifier without `--force`.
+
+## Interactive wizard flow
+
+### Step 1: Rule type selection
+The first prompt offers:
+- secret
+- file
+- command
+- cancel
+
+If cancel is selected, the wizard exits without persisting data.
+
+### Step 2: Preset or custom pattern
+After choosing type, the wizard offers:
+- custom pattern
+- built-in presets for the selected type
+- cancel
+
+If a preset is selected, name/pattern/placeholder values are prefilled from that preset.
+If custom is selected, manual inputs are requested.
+
+### Step 3: Manual inputs (custom path)
+For secret type:
+- name is required
+- pattern is required and regex-validated
+- placeholder is optional
+
+For file/command type:
+- name is required
+- pattern is required and regex-validated
+
+Invalid regex can block progress until a valid pattern is entered or the user cancels.
+
+### Step 4: Broad-pattern confirmation
+If the pattern is detected as broad, the wizard asks explicit confirmation.
+If the user does not confirm, the wizard exits without saving.
+
+### Step 5: Preview and validation loop
+Before save, the wizard enters a loop with sample tests:
+- select one preview sample or skip
+- see match/no-match result
+- see expectation status
+
+Then choose one action:
+- save rule
+- test another sample
+- edit pattern
+- cancel
+
+If edit pattern is selected, the wizard returns to pattern input and repeats validation.
+If cancel is selected, no data is persisted.
+
+### Step 6: Save result
+When save is selected, the command persists the rule and prints:
+- rule type
+- rule identifier
+- stored pattern
+- redaction placeholder (when available)
+
+### Cancellation behavior
+Cancel exits immediately and no new custom rule is written.
+
+## Related commands
+- [index](README.md)
+- [list](list.md)
+- [remove](remove.md)
+- [test](test.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

package/docs/wiki/operation/cli/help.md

@@ -0,0 +1,83 @@
+---
+summary: "CLI reference for `openclaw bshield --help` and command-specific help output"
+read_when:
+  - You are discovering available Berry Shield commands
+  - You need exact syntax for one command before execution
+title: "help"
+---
+
+# `openclaw bshield --help`
+
+Show Berry Shield command discovery output and command-specific usage details.
+
+## What it does
+- Lists available Berry Shield subcommands.
+- Shows command arguments and options.
+- Provides per-command help output for targeted usage checks.
+
+## When to use
+- First contact with Berry Shield CLI.
+- Before scripting command execution.
+- During troubleshooting for wrong argument shape.
+
+## Syntax
+
+### Global help
+Use this form to inspect the full Berry Shield command surface.
+```bash
+openclaw bshield --help
+```
+Expected: CLI prints the list of available bshield subcommands and basic usage.
+
+### Command-specific help
+Use this form to inspect usage for one command.
+```bash
+openclaw bshield mode --help
+```
+Expected: CLI prints the mode command syntax and accepted argument values.
+
+## Options
+Help output is exposed through standard help flags:
+- `--help`
+- `-h`
+
+## Examples
+
+### Inspect one command before execution
+Use this when you need argument details for policy operations.
+```bash
+openclaw bshield policy --help
+```
+Result: Output describes policy command usage, including action and argument format.
+
+## Common errors
+
+### Mistyped command name
+Use this check when help output is missing because the command name is invalid.
+```bash
+openclaw bshiled --help
+```
+Expected: Shell or CLI returns command-not-found or unknown command output.
+
+### Running global openclaw help by mistake
+Use this check when output is too broad and not Berry Shield-specific.
+```bash
+openclaw --help
+```
+Expected: OpenClaw global command index is shown instead of bshield-only help.
+
+## Related commands
+- [index](README.md)
+- [init](init.md)
+- [status](status.md)
+- [mode](mode.md)
+- [policy](policy.md)
+- [vine](vine.md)
+- [rules](rules.md)
+- [reset](reset.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

package/docs/wiki/operation/cli/init.md

@@ -0,0 +1,52 @@
+---
+summary: "CLI reference for `openclaw bshield init` (initialize Berry Shield config with defaults)"
+read_when:
+  - You need to bootstrap Berry Shield configuration on a new environment
+  - You want to ensure the plugin config entry exists before running other commands
+title: "init"
+---
+
+# `openclaw bshield init`
+
+Initialize Berry Shield configuration if it does not exist.
+
+## What it does
+- Checks whether the Berry Shield plugin config entry already exists.
+- If config already exists, it exits successfully without overwriting it.
+- If config is missing, it writes default Berry Shield settings.
+- Sets the Berry Shield enabled flag during initialization.
+
+## When to use
+- First setup on a new host/profile.
+- Recovery after config resets where the plugin entry is missing.
+- Preflight before mode/profile/policy commands on unknown environments.
+
+## Syntax
+
+### Initialize config
+Use this to create Berry Shield config only when it is missing.
+```bash
+openclaw bshield init
+```
+Expected: CLI shows either `Configuration already exists.` or `Initialized successfully with default settings.`
+
+## Common errors
+
+### Write or config backend failure
+Use this when init reports operation failure during config write/bootstrap.
+Expected: CLI prints `Failed to initialize: ...` and exits with a non-zero code.
+
+Possible causes:
+- No write permission to the OpenClaw config/state path.
+- Runtime/config backend unavailable.
+- Invalid or corrupted config store state.
+
+## Related commands
+- [index](README.md)
+- [status](status.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

package/docs/wiki/operation/cli/list.md

@@ -0,0 +1,78 @@
+---
+summary: "CLI reference for `openclaw bshield rules list` (compact vs detailed inventory)"
+read_when:
+  - You need to inspect current baseline/custom rule state
+  - You need to confirm ENABLED or DISABLED status after rule changes
+title: "list"
+---
+
+# `openclaw bshield rules list`
+
+Show current Berry Shield rule inventory grouped by source and status.
+
+## What it does
+- Loads rule state from plugin config/runtime.
+- Prints two sections: baseline and custom.
+- Shows each rule with status marker:
+  - `[ENABLED]`
+  - `[DISABLED]`
+- In detailed mode, adds one `pattern:` line per rule.
+
+## When to use
+- Before rule updates to capture a state snapshot.
+- After `rules enable` or `rules disable` to confirm final state.
+- During troubleshooting when behavior and expected coverage differ.
+
+## Syntax
+
+### Compact inventory
+Use this for quick state checks.
+```bash
+openclaw bshield rules list
+```
+Expected:
+- Prints Baseline and Custom sections.
+- Shows IDs and status markers only.
+
+### Detailed inventory
+Use this when you need exact regex visibility.
+```bash
+openclaw bshield rules list --detailed
+```
+Expected:
+- Prints the same sections and statuses as compact mode.
+- Adds one `pattern:` line for each rule entry.
+
+### Short flag for detailed mode
+Use this as a compact equivalent of `--detailed`.
+```bash
+openclaw bshield rules list -d
+```
+Expected: same output as `--detailed`.
+
+## Options
+- `--detailed` (`-d`): include raw pattern details for all listed entries.
+
+## Common errors
+
+### Runtime/config read failure
+Use this when command output is incomplete or the command fails unexpectedly while reading runtime/config state.
+Expected: CLI reports a runtime/config read error.
+
+Possible causes:
+- Invalid custom rule structure in config.
+- Read failure on plugin config storage path.
+
+## Related commands
+- [index](README.md)
+- [rules](rules.md)
+- [add](add.md)
+- [remove](remove.md)
+- [reset](reset.md)
+- [test](test.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

package/docs/wiki/operation/cli/mode.md

@@ -0,0 +1,93 @@
+---
+summary: "CLI reference for `openclaw bshield mode` (set runtime mode to audit or enforce)"
+read_when:
+  - You need to switch Berry Shield runtime behavior
+  - You are validating security behavior in audit vs enforce mode
+title: "mode"
+---
+
+# `openclaw bshield mode`
+
+Set Berry Shield runtime mode to `audit` or `enforce`.
+
+## What it does
+- Writes mode value to plugin config (`audit` or `enforce`).
+- Validates mode argument before write.
+- Returns explicit success or failure output.
+
+## When to use
+- Before security behavior tests.
+- Before production hardening checks.
+- When switching between observation and active protection workflows.
+
+## Audit semantics (important)
+- `audit` is shadow mode for block/redact decisions.
+- `audit` does not mean "Berry Shield fully disabled" or "100 percent passive".
+- Policy behavior (profile/adaptive injection strategy) still applies.
+- Message hygiene safeguards can still apply (for example leaked policy-block stripping).
+
+## Syntax
+
+### Set enforce mode
+Use this form for active blocking behavior.
+```bash
+openclaw bshield mode enforce
+```
+Expected: CLI confirms switch to ENFORCE mode.
+
+### Set audit mode
+Use this form for shadow behavior and monitoring.
+```bash
+openclaw bshield mode audit
+```
+Expected: CLI confirms switch to AUDIT mode.
+
+## Options
+Positional argument:
+- `<mode>`: accepted values are `audit` or `enforce`.
+
+## Examples
+
+### Switch to enforce before deny tests
+Use the enforce syntax command shown above before testing blocked behavior for sensitive operations.
+Result: Subsequent checks run under enforce behavior.
+
+### Switch to audit for observation
+Use the audit syntax command shown above when validating policy behavior without active block expectations.
+Result: Mode is set to audit for shadow-mode style verification.
+
+### Confirm mode after switch
+Use this to verify runtime state after mode change.
+```bash
+openclaw bshield status
+```
+Result: Status output mode field matches the last configured mode.
+
+## Common errors
+
+### Invalid mode value
+Use this to see expected validation behavior for wrong input.
+```bash
+openclaw bshield mode monitor
+```
+Expected: CLI fails with message: invalid mode, use `audit` or `enforce`.
+
+### Mode write failure
+Use this when a valid mode command (for example `openclaw bshield mode enforce`) reports operation failure.
+Expected: On failure, CLI prints operation failure and returns non-zero exit code.
+
+Possible causes:
+- Config write permission issue.
+- Config backend/runtime error.
+
+## Related commands
+- [index](README.md)
+- [status](status.md)
+- [profile](profile.md)
+- [policy](policy.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

package/docs/wiki/operation/cli/policy.md

@@ -0,0 +1,202 @@
+---
+summary: "CLI reference for `openclaw bshield policy` (interactive wizard, deterministic get/set)"
+read_when:
+  - You need to edit policy settings beyond profile-only changes
+  - You want deterministic policy operations for scripts and agents
+title: "policy"
+---
+
+# `openclaw bshield policy`
+
+Manage Berry Shield policy values through an interactive wizard or deterministic get/set actions.
+
+## What it does
+- Launches interactive policy wizard when called without action.
+- Supports deterministic set for one allowed path.
+- Supports deterministic get for full policy or one allowed path.
+- Validates value types and ranges before write.
+
+## When to use
+- Interactive manual tuning of adaptive/retention values.
+- Reproducible policy changes in scripts or CI.
+- Debugging current policy values quickly.
+
+## Syntax
+
+### Launch policy wizard
+Use this to edit policy values interactively with prompts and confirmation.
+```bash
+openclaw bshield policy
+```
+Expected: Wizard prompts for profile, adaptive values, and retention values.
+
+### Set one policy value
+Use this to update one specific policy path deterministically.
+```bash
+openclaw bshield policy set <path> <value>
+```
+Expected: CLI confirms the updated path and value.
+
+### Read policy values
+Use this to print policy values, either full tree or one path.
+```bash
+openclaw bshield policy get [path]
+```
+Expected: CLI prints policy rows for all values or for the selected path.
+
+## Options
+Supported actions:
+- set
+- get
+
+Supported paths:
+- `profile`
+- `adaptive.staleAfterMinutes`
+- `adaptive.escalationTurns`
+- `adaptive.heartbeatEveryTurns`
+- `adaptive.allowGlobalEscalation`
+- `retention.maxEntries`
+- `retention.ttlSeconds`
+
+Validation rules:
+- `profile`: `strict | balanced | minimal`
+- `adaptive.allowGlobalEscalation`: `true | false`
+- `adaptive.staleAfterMinutes`: integer `>= 1`
+- `adaptive.escalationTurns`: integer `>= 1`
+- `adaptive.heartbeatEveryTurns`: integer `>= 0`
+- `retention.maxEntries`: integer `>= 1`
+- `retention.ttlSeconds`: integer `>= 1`
+
+## Tuning guide
+
+| Field | Change when | Typical direction | Tradeoff |
+| --- | --- | --- | --- |
+| `profile` | You need broader or quieter policy injection behavior | `balanced -> strict` for stronger visibility, `balanced -> minimal` for lower noise | Stronger profiles improve policy visibility but can increase prompt overhead |
+| `adaptive.allowGlobalEscalation` | Session identity is missing and escalation still must apply | `false -> true` only in controlled single-session contexts | Useful fallback for missing identity, risky in multi-session environments |
+| `adaptive.escalationTurns` | Full-policy escalation feels too short or too long after denied events | Increase for stronger persistence, decrease for faster recovery | Higher values improve guard persistence but increase context load |
+| `adaptive.heartbeatEveryTurns` | Long sessions need periodic reminder, or reminder noise is too high | Increase interval to reduce reminders, set `0` to disable | More heartbeat improves continuity, less heartbeat reduces token usage |
+| `adaptive.staleAfterMinutes` | Session is considered stale too early or too late | Increase for longer continuity, decrease for faster stale detection | Longer windows reduce resets, shorter windows refresh posture sooner |
+| `retention.maxEntries` | High session churn or memory pressure appears | Decrease on constrained hosts, increase for larger workloads | Lower values save memory, higher values keep more adaptive history |
+| `retention.ttlSeconds` | Adaptive state expires too fast or remains too long | Increase for longer correlation, decrease for faster cleanup | Longer TTL helps continuity, shorter TTL reduces stale state risk |
+
+## Examples
+
+### Open wizard for manual policy updates
+Use the wizard command shown in Syntax when tuning multiple policy values in one flow.
+Result: Interactive flow collects values and asks for save confirmation.
+
+### Set profile through deterministic path
+Use this in scripts where profile change must be explicit.
+```bash
+openclaw bshield policy set profile balanced
+```
+Result: CLI confirms `profile = balanced`.
+
+### Set stale timeout deterministically
+Use this for adaptive timeout tuning.
+```bash
+openclaw bshield policy set adaptive.staleAfterMinutes 30
+```
+Result: CLI confirms `adaptive.staleAfterMinutes = 30`.
+
+### Read full policy
+Use this to inspect all policy values in one command.
+```bash
+openclaw bshield policy get
+```
+Result: CLI prints profile, adaptive values, and retention values.
+
+### Read one policy path
+Use this for focused checks in scripts.
+```bash
+openclaw bshield policy get adaptive.allowGlobalEscalation
+```
+Result: CLI prints only the selected path value.
+
+## Common errors
+
+### Invalid action
+Use this to verify action validation behavior.
+```bash
+openclaw bshield policy edit profile strict
+```
+Expected: CLI fails with message indicating valid actions are get and set.
+
+### Invalid path
+Use this to verify path allowlist enforcement.
+```bash
+openclaw bshield policy set adaptive.unknownField 1
+```
+Expected: CLI fails with usage/error message listing allowed paths.
+
+### Invalid typed value
+Use this to verify numeric/boolean/profile validation.
+```bash
+openclaw bshield policy set adaptive.staleAfterMinutes zero
+```
+Expected: CLI fails with an integer validation message.
+
+## Interactive wizard flow
+
+### Wizard entry
+Use the wizard command shown in Syntax to edit policy values interactively in one guided flow.
+Expected: Wizard prompts for profile, adaptive fields, and retention fields.
+
+### Step 1: Profile selection
+The first prompt offers:
+- strict
+- balanced
+- minimal
+- cancel
+
+If cancel is selected, the wizard exits without changes.
+
+### Step 2: Adaptive numeric inputs
+The wizard requests these values:
+- adaptive.staleAfterMinutes (integer >= 1)
+- adaptive.escalationTurns (integer >= 1)
+- adaptive.heartbeatEveryTurns (integer >= 0)
+
+Each field is validated inline and rejects invalid values until corrected or canceled.
+
+### Step 3: Adaptive boolean input
+The wizard asks for:
+- adaptive.allowGlobalEscalation (confirm prompt)
+
+Cancel exits without writing policy changes.
+
+### Step 4: Retention numeric inputs
+The wizard requests:
+- retention.maxEntries (integer >= 1)
+- retention.ttlSeconds (integer >= 1)
+
+Each field has inline numeric validation.
+
+### Step 5: Review screen
+Before persistence, the wizard prints a policy review table with:
+- selected profile
+- adaptive values
+- retention values
+
+### Step 6: Save confirmation
+Final prompt: save policy changes.
+
+If confirmed, each policy path is written to config.
+If canceled or declined, no policy values are written.
+
+### Wizard cancellation behavior
+Use this to validate safe exit before persistence while running the interactive wizard command.
+Result: Any cancel branch exits the flow and preserves previous policy values.
+
+## Related commands
+- [index](README.md)
+- [profile](profile.md)
+- [status](status.md)
+- [mode](mode.md)
+- [vine](vine.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)