@f4bioo/berry-shield 2026.3.3-1

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

@@ -0,0 +1,98 @@
+---
+summary: "CLI reference for `openclaw bshield profile` (set policy profile to strict, balanced, or minimal)"
+read_when:
+  - You need to change policy behavior quickly without editing individual policy paths
+  - You want to standardize profile setup before security tests
+title: "profile"
+---
+
+# `openclaw bshield profile`
+
+Set the Berry Shield policy profile to `strict`, `balanced`, or `minimal`.
+
+## What it does
+- Validates profile argument against allowed values.
+- Writes profile into policy config path.
+- Returns explicit success or failure output.
+
+## When to use
+- When switching between policy behavior presets.
+- Before adaptive behavior validation.
+- When setting a consistent baseline in scripts.
+
+## Syntax
+
+### Set strict profile
+Use this profile when full policy injection is required each turn.
+```bash
+openclaw bshield profile strict
+```
+Expected: CLI confirms switch to STRICT profile.
+
+### Set balanced profile
+Use this profile as the default operating baseline.
+```bash
+openclaw bshield profile balanced
+```
+Expected: CLI confirms switch to BALANCED profile.
+
+### Set minimal profile
+Use this profile when low-noise behavior is preferred.
+```bash
+openclaw bshield profile minimal
+```
+Expected: CLI confirms switch to MINIMAL profile.
+
+## Options
+Positional argument:
+- `<profile>`: accepted values are `strict`, `balanced`, `minimal`.
+
+## Tuning guide
+
+| Profile | Use when | Expected behavior | Tradeoff |
+| --- | --- | --- | --- |
+| `strict` | You want maximum policy visibility and deterministic guardrails | Full policy is injected every turn | Strongest posture, highest context overhead |
+| `balanced` | You need default production behavior with adaptive control | Full at session start, then adaptive reminders/escalation | Best general balance between safety and noise |
+| `minimal` | You want low-noise interaction and rely on trigger-based escalation | No full injection on new session; escalates when needed | Lowest overhead, depends more on runtime triggers |
+
+## Examples
+
+### Apply balanced profile for standard operation
+Use the balanced syntax command shown above before routine enforce-mode workflows.
+Result: Policy profile is set to balanced and adaptive behavior follows balanced defaults.
+
+### Verify profile after update
+Use this check immediately after profile changes.
+```bash
+openclaw bshield status
+```
+Result: Policy section shows the selected profile in uppercase.
+
+## Common errors
+
+### Invalid profile value
+Use this to validate input checking behavior.
+```bash
+openclaw bshield profile advanced
+```
+Expected: CLI fails with an invalid profile message listing supported values.
+
+### Profile write failure
+Use this when a valid profile update command (for example `openclaw bshield profile strict`) reports operation failure.
+Expected: 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)
+- [policy](policy.md)
+- [status](status.md)
+- [mode](mode.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

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

@@ -0,0 +1,96 @@
+---
+summary: "CLI reference for `openclaw bshield rules remove custom` (delete one custom security rule by typed id)"
+read_when:
+  - You need to remove a custom Berry Shield rule
+  - You are cleaning up test or deprecated custom rules
+title: "remove"
+---
+
+# `openclaw bshield rules remove custom`
+
+Remove one custom Berry Shield rule by its identifier.
+
+## What it does
+- Looks up a custom rule by typed identifier (`type:name`).
+- Removes the rule from persistent custom storage.
+- Returns success output when the rule is removed.
+- Returns failure output when the rule does not exist.
+- Does not mutate baseline rules.
+
+## When to use
+- Removing obsolete custom patterns.
+- Cleaning up temporary testing rules.
+- Replacing a rule with a new pattern/version.
+
+## Syntax
+
+### Remove one custom rule by id
+Use this to remove one existing custom rule.
+```bash
+openclaw bshield rules remove custom <id>
+```
+Expected: CLI confirms successful removal or reports that rule was not found.
+
+## Options
+Positional arguments:
+- custom: required target for custom-rule removal.
+- `<id>`: custom rule identifier in `type:name` format.
+
+## Examples
+
+### Remove an existing custom rule
+Use this when the exact custom rule id is known.
+```bash
+openclaw bshield rules remove custom secret:MyToken
+```
+Result: CLI confirms custom rule removal.
+
+### Remove a custom file rule
+Use this when a file-pattern custom rule must be removed.
+```bash
+openclaw bshield rules remove custom file:team-key
+```
+Result: CLI confirms custom file-rule removal.
+
+### Verify removal through rules list
+Use this to confirm the removed rule is no longer present.
+```bash
+openclaw bshield rules list
+```
+Result: Removed custom rule no longer appears in custom entries.
+
+### Disable a baseline rule (separate command)
+Use this when the target is a baseline ID.
+```bash
+openclaw bshield rules disable baseline secret:openai-key
+```
+Result: Baseline rule is marked disabled in rules inventory.
+
+## Common errors
+
+### Wrong target
+Use this to validate explicit target semantics.
+```bash
+openclaw bshield rules remove baseline secret:openai-key
+```
+Expected: CLI returns usage error because remove supports only custom target.
+
+### Rule not found
+Use this to verify missing-rule behavior.
+```bash
+openclaw bshield rules remove custom secret:UnknownRule
+```
+Expected: CLI reports that the rule was not found.
+
+## Related commands
+- [index](README.md)
+- [rules](rules.md)
+- [list](list.md)
+- [add](add.md)
+- [test](test.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

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

@@ -0,0 +1,66 @@
+---
+summary: "CLI reference for `openclaw bshield report` (show or clear persisted audit events)"
+read_when:
+  - You need to inspect persisted Berry Shield audit events
+  - You need to clear audit history before controlled tests
+title: "report"
+---
+
+# `openclaw bshield report`
+
+Show persisted audit report data or clear it.
+
+## What it does
+- Reads persisted audit events from Berry Shield storage.
+- Prints event period, summary counters, and detail rows.
+- Clears persisted events when `--clear` is provided.
+
+## When to use
+- After tests to confirm `blocked` and `would_block` activity.
+- Before tests to reset report state.
+- During incident analysis to inspect recent security decisions.
+
+## Syntax
+
+### Show persisted report
+Use this to inspect current persisted audit events.
+```bash
+openclaw bshield report
+```
+Expected: CLI prints total events, period, summary counters, and detail rows.
+
+### Clear persisted report
+Use this to clear persisted audit events before a new test cycle.
+```bash
+openclaw bshield report --clear
+```
+Expected: CLI confirms clear operation and reports how many events were removed.
+
+## Options
+- `--clear`: clear persisted audit report data instead of printing it.
+
+## Common errors
+
+### Report backend read failure
+Use this when report rendering fails unexpectedly.
+Expected: CLI prints a report generation error and returns non-zero exit code.
+
+Possible causes:
+- Audit storage file is not readable.
+- Runtime/config path permission issue.
+- Corrupted persisted report payload.
+
+### In-flight write visibility after clear
+Use this when events appear shortly after `--clear`.
+Expected: clear succeeds, but buffered in-flight events may still be written after the clear operation.
+
+## Related commands
+- [index](README.md)
+- [status](status.md)
+- [mode](mode.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

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

@@ -0,0 +1,99 @@
+---
+summary: "CLI reference for `openclaw bshield reset defaults` (restore built-in and optional full defaults)"
+read_when:
+  - You need to restore built-in defaults after custom tuning
+  - You need to reset all custom state and policy to defaults
+title: "reset"
+---
+
+# `openclaw bshield reset`
+
+Restore Berry Shield defaults with explicit scope control.
+
+## What it does
+- Supports `reset defaults` as the default restoration target.
+- Scope builtins clears disabled built-in IDs only.
+- Scope all clears disabled built-ins, custom rules, and restores default policy.
+- Requests confirmation unless `--yes` is provided.
+
+## When to use
+- Reverting built-in tuning after a temporary exception.
+- Returning to baseline protection before deployment.
+- Recovering from heavy local customization during testing.
+
+## Syntax
+
+### Reset built-in defaults only
+Use this to restore built-in baseline and keep custom rules.
+```bash
+openclaw bshield reset defaults --scope builtins
+```
+Expected: Disabled built-in IDs are cleared; custom rules remain intact.
+
+### Reset full defaults
+Use this to restore both rule state and policy defaults.
+```bash
+openclaw bshield reset defaults --scope all
+```
+Expected: Disabled built-ins and custom rules are cleared; policy is restored to default config.
+
+### Non-interactive reset
+Use this in automation where prompts are not allowed.
+```bash
+openclaw bshield reset defaults --scope builtins --yes
+```
+Expected: Command executes without confirmation prompt.
+
+## Options
+Supported options:
+- `--scope <scope>`
+  - builtins (default): reset disabled built-in IDs only
+  - all: reset disabled built-ins + custom rules + policy defaults
+- `--yes`: skip confirmation prompt
+
+Positional arguments:
+- `<target>` currently supports defaults.
+
+## Examples
+
+### Restore only built-in baseline
+Use this to keep your custom rules while undoing built-in disables.
+```bash
+openclaw bshield reset defaults
+```
+Result: Same behavior as `--scope builtins`.
+
+### Restore full baseline for clean-room testing
+Use this before a full smoke test.
+```bash
+openclaw bshield reset defaults --scope all --yes
+```
+Result: Rules and policy return to default baseline without prompt.
+
+## Common errors
+
+### Invalid target
+Use this to validate target parsing behavior.
+```bash
+openclaw bshield reset unknown
+```
+Expected: CLI returns usage failure and exits with error.
+
+### Invalid scope
+Use this to validate scope values.
+```bash
+openclaw bshield reset defaults --scope unknown
+```
+Expected: CLI returns failure with valid scope values.
+
+## Related commands
+- [index](README.md)
+- [rules](rules.md)
+- [list](list.md)
+- [policy](policy.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

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

@@ -0,0 +1,161 @@
+---
+summary: "CLI reference for `openclaw bshield rules` (baseline/custom rule management)"
+read_when:
+  - You need to manage baseline and custom rule state from one namespace
+  - You are onboarding operators to the new rules command family
+title: "rules"
+---
+
+# `openclaw bshield rules`
+
+Manage baseline and custom Berry Shield rules from one command group.
+
+## What it does
+- Centralizes rule operations under rules.
+- Reads and writes custom rule state from `pluginConfig.customRules` (single CLI/Web source).
+- Lists baseline and custom inventory with explicit status.
+- Removes custom rules by target + id (`type:name`).
+- Enables or disables baseline and custom rules by ID or in bulk.
+
+## When to use
+- Day-to-day rule operations in terminal automation.
+- Security hardening sessions for baseline tuning.
+- Cleanup or rotation of custom patterns.
+
+## Syntax
+
+### List inventory
+Use this to review the current baseline and custom inventory before applying any change.
+```bash
+openclaw bshield rules list
+```
+Expected: Shows Baseline and Custom sections with explicit status.
+
+### List inventory with detailed patterns
+Use this to inspect identifier and raw pattern together.
+```bash
+openclaw bshield rules list --detailed
+```
+Expected: Shows the same inventory plus `pattern:` lines for baseline and custom rules.
+
+### Remove custom rule
+Use this to remove one custom rule by its stable custom identifier.
+```bash
+openclaw bshield rules remove custom <id>
+```
+Expected: Removes one custom rule by typed id (`secret:<name> | file:<name> | command:<name>`).
+
+### Disable one baseline rule
+Use this to disable a single baseline rule when you need a controlled exception.
+```bash
+openclaw bshield rules disable baseline <id>
+```
+Expected: Marks one baseline rule as disabled.
+
+### Disable one custom rule
+Use this to disable one custom rule without deleting it.
+```bash
+openclaw bshield rules disable custom <id>
+```
+Expected: Marks one custom rule as disabled and keeps it in inventory.
+
+### Enable one baseline rule
+Use this to re-enable a previously disabled baseline rule by ID.
+```bash
+openclaw bshield rules enable baseline <id>
+```
+Expected: Marks one baseline rule as enabled.
+
+### Enable one custom rule
+Use this to re-enable one custom rule by ID.
+```bash
+openclaw bshield rules enable custom <id>
+```
+Expected: Marks one custom rule as enabled.
+
+### Disable all baseline rules
+Use this only in controlled testing scenarios where default baseline coverage must be turned off.
+```bash
+openclaw bshield rules disable baseline --all --yes
+```
+Expected: Disables all baseline IDs and warns about protection impact.
+
+### Enable all baseline rules
+Use this to restore complete baseline coverage after bulk-disable scenarios.
+```bash
+openclaw bshield rules enable baseline --all --yes
+```
+Expected: Re-enables all baseline IDs.
+
+### Disable all custom rules
+Use this to keep custom entries persisted but inactive.
+```bash
+openclaw bshield rules disable custom --all --yes
+```
+Expected: Disables all custom entries across secret, file, and command categories.
+
+### Enable all custom rules
+Use this to reactivate all custom entries in one operation.
+```bash
+openclaw bshield rules enable custom --all --yes
+```
+Expected: Enables all custom entries across secret, file, and command categories.
+
+### Disable all rules globally
+Use this to disable baseline and custom rules together.
+```bash
+openclaw bshield rules disable --all --yes
+```
+Expected: Applies disable to full rule scope (`baseline + custom`) with impact warning.
+
+### Enable all rules globally
+Use this to restore full baseline and custom coverage in one step.
+```bash
+openclaw bshield rules enable --all --yes
+```
+Expected: Applies enable to full rule scope (`baseline + custom`).
+
+## Option rules
+- disable/enable accept exactly one mode:
+  - `<id>` OR `--all`
+- target is optional only for global `--all`.
+- Invalid combinations return usage failure:
+  - `<id> + --all`
+  - neither `<id>` nor `--all`
+- `--yes` is meaningful only for `--all` operations.
+
+## Common errors
+
+### Wrong target for remove
+Use this check to validate that remove only accepts the custom target.
+```bash
+openclaw bshield rules remove baseline secret:openai-key
+```
+Expected: Usage failure (remove supports only custom target).
+
+### Unknown baseline ID
+Use this check to validate error handling when an ID does not exist in baseline catalog.
+```bash
+openclaw bshield rules disable baseline secret:does-not-exist
+```
+Expected: Operation failure (`Unknown baseline rule id`).
+
+### Unknown custom ID
+Use this check to validate error handling when a custom rule is not found.
+```bash
+openclaw bshield rules disable custom secret:does-not-exist
+```
+Expected: Operation failure (`Unknown custom rule id`).
+
+## Related commands
+- [index](README.md)
+- [list](list.md)
+- [remove](remove.md)
+- [add](add.md)
+- [reset](reset.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)

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

@@ -0,0 +1,103 @@
+---
+summary: "CLI reference for `openclaw bshield status` (runtime mode, policy, rules, and layers)"
+read_when:
+  - You need to verify current Berry Shield runtime configuration
+  - You changed mode, profile, policy, or layers and want confirmation
+title: "status"
+---
+
+# `openclaw bshield status`
+
+Show the effective Berry Shield runtime state resolved from OpenClaw plugin config plus Berry defaults.
+
+## What it does
+- Reads plugin config from OpenClaw config storage.
+- Merges config with Berry Shield defaults.
+- Prints current plugin state (`Status`, `Mode`, and rule counters).
+- Prints policy state (`Profile`, adaptive values, and global escalation toggle).
+- Prints Vine state (`Mode`, thresholds, retention, and allowlist size).
+- Prints each security layer status as `ACTIVE` or `OFF`.
+
+## When to use
+- After changing `mode`, `profile`, or `policy`.
+- After toggling a layer.
+- Before and after smoke tests to confirm runtime posture.
+- During incident triage to verify what is effectively active.
+
+## Syntax
+
+### Base command
+Use this command to inspect the full Berry Shield state.
+```bash
+openclaw bshield status
+```
+Expected: Output includes Status, Mode, Rules, Policy, Vine, and Security Layers sections.
+
+## Options
+This command has no command-specific flags or positional arguments.
+
+## Output interpretation guide
+
+### Status and mode
+Command for this check: `openclaw bshield status`.
+Result expected for an active deployment:
+- `Status` should be `ENABLED`.
+- `Mode` should be either `AUDIT` or `ENFORCE`, matching your intended test posture.
+
+### Rules counters
+Command for this check: `openclaw bshield status`.
+Result expected:
+- `BASELINE` count represents baseline shipped protections.
+- `CUSTOM` count represents user-defined entries currently loaded.
+
+### Policy section
+Command for this check: `openclaw bshield status`.
+Result expected:
+- `Profile` is one of `STRICT`, `BALANCED`, `MINIMAL`.
+- `Escalation`, `Stale (min)`, `Heartbeat`, and `Global Escalation` reflect configured values.
+
+### Vine section
+Command for this check: `openclaw bshield status`.
+Result expected:
+- `Mode` shows Vine behavior (`BALANCED` or `STRICT`).
+- Thresholds and retention values match expected operational tuning.
+- `Allowlist` shows the number of exempt tools.
+
+### Security layers section
+Command for this check: `openclaw bshield status`.
+Result expected:
+- Each layer is explicitly shown as `ACTIVE` or `OFF`.
+- Use this as the authoritative source before any behavior validation run.
+
+## Common errors
+
+### Status command fails due to config read error
+Use this check when the status command exits with operation failure.
+Expected: CLI prints a failure message and returns non-zero exit code.
+
+Possible causes:
+- OpenClaw config path is unavailable or corrupted.
+- Runtime permission issue when reading config.
+- Unexpected config wrapper/backend failure.
+
+### Output does not reflect a recent change
+Use this check when you changed config in Web or CLI but output still looks stale.
+Expected: after OpenClaw restarts its gateway, `status` reflects the new effective values.
+
+Possible causes:
+- Gateway restart has not happened yet.
+- You edited a different environment/root than the active OpenClaw runtime.
+- Another write operation overwrote your previous setting.
+
+## Related commands
+- [index](README.md)
+- [mode](mode.md)
+- [profile](profile.md)
+- [policy](policy.md)
+- [vine](vine.md)
+
+---
+
+## Navigation
+- [Back to CLI Index](README.md)
+- [Back to Wiki Index](../../README.md)