@f4bioo/berry-shield 2026.3.3-1

package/docs/wiki/deploy/github-ci-cd.md

@@ -0,0 +1,107 @@
+---
+summary: "GitHub Actions release workflow reference for prepare-release and publish-release"
+read_when:
+  - You are preparing an official Berry Shield release
+  - You need to run publish-release safely with target version
+  - You need deterministic recovery for partial release failures
+title: "github-ci-cd"
+---
+
+# `GitHub CI/CD Release Flow`
+
+This page documents the official release workflow executed in GitHub Actions.
+It is self-contained and intended for operators with no prior project context.
+
+## Preconditions
+
+- Repository flow is trunk-based (`master` only).
+- `NPM_TOKEN` is configured in repository secrets.
+- `BERRY_SHIELD_APP_ID` is configured in repository secrets.
+- `BERRY_SHIELD_APP_PRIVATE_KEY` is configured in repository secrets.
+- Repository permissions allow workflow-created branches, tags, PRs, and releases.
+
+## Workflow 1: Prepare Release (`master`)
+
+### Trigger
+
+```bash
+GitHub Actions -> Prepare Release -> Run workflow (branch: master)
+```
+Expected: workflow runs on `master` and does not skip.
+
+### What it does
+
+1. Evaluates CalVer date vs current date.
+2. Decides whether to bump, reuse, or no-op based on workflow inputs.
+3. Creates or updates PR `release/v{version} -> master`.
+4. Writes `Release-Mode` in PR body (`release_now` or `bump_only`).
+5. On merge of release PR, if `release_now`:
+   - creates tag `v{version}`
+   - creates draft release
+   - attaches `.tgz` and `SHA256SUMS`.
+6. If there is no required bump and `create_release_after_merge=true`, workflow can create draft release directly from `prepare` when skip conditions are met (no empty PR).
+7. If there is no required bump and `create_release_after_merge=false`, workflow ends as `NO_OP/IDLE` (no branch, no PR, no release).
+
+### Expected output
+
+- A release branch exists or an existing release PR is updated.
+- A release PR to `master` exists with `Release-Mode` marker in body.
+- Or `NO_OP/IDLE` is reported explicitly when no release action is required.
+
+## Release Notes Behavior (Draft Creation)
+
+When draft release notes are generated:
+- only PR titles with public types are included (`feat`, `fix`, `perf`, `security`);
+- bot-authored PRs are excluded;
+- first release falls back to `firstReleaseNotes` from `.github/common-contract.json`. <!-- doc-sanity:ignore "firstReleaseNotes" -->
+
+## Workflow 2: Publish Release (`master`)
+
+### Trigger
+
+```bash
+GitHub Actions -> Publish Release -> Run workflow (branch: master)
+```
+Expected: workflow runs on `master` and does not skip.
+
+### Inputs
+
+- `target_version` (required): `vYYYY.M.D` or `YYYY.M.D` (supports `-N`)
+- `confirm_publish` (required): must be `PUBLISH_NOW`
+
+## Publish flow
+
+1. Resolves draft release by exact `target_version` (fail-closed).
+2. Downloads draft assets.
+3. Validates `SHA256SUMS`.
+4. Verifies npm target version does not already exist.
+5. Publishes the exact downloaded `.tgz`.
+6. Promotes release draft to published.
+
+## Release Assets Contract
+
+Every successful publish must end with GitHub Release assets:
+- `<package>-<version>.tgz` (from `npm pack`)
+- `SHA256SUMS` (hash file for the same `.tgz`)
+
+This keeps artifact parity between npm and GitHub Release.
+
+## Operational DoD (Required Evidence per release cycle)
+
+1. `prepare-release` completed successfully.
+2. Release branch `release/v{version}` exists and PR `release/v{version} -> master` exists.
+3. Release PR checks are green and merged into `master`.
+4. `publish-release` completed successfully with `target_version`.
+5. Release moved from draft to published with the same assets used in npm publish.
+
+## Related pages
+- [deploy index](README.md)
+- [installation](installation.md)
+- [build (local dev)](build.md)
+- [auditing](auditing.md)
+
+---
+
+## Navigation
+- [Back to Deploy Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/deploy/installation.md

@@ -0,0 +1,348 @@
+---
+summary: "Installation guide for Berry Shield using source-truth and release-truth tracks"
+read_when:
+  - You are deploying Berry Shield for local or production-like usage
+  - You need a source-built deployment path
+  - You need to verify plugin activation after installation
+title: "installation"
+---
+
+# `Installation guide`
+
+Berry Shield is an OpenClaw plugin.
+This guide defines two installation tracks and when each one should be used.
+
+## Prerequisites
+
+- Node.js 20 or newer.
+- OpenClaw runtime available in environment.
+- Git available in environment.
+
+## SDK compatibility contract
+
+Berry Shield validates OpenClaw SDK compatibility through:
+- `package.json` peer range (`peerDependencies.openclaw`)
+- internal compat constants (`src/constants.ts`, `COMPAT_POLICY`)
+- compatibility test contract (`__tests__/compat-policy.test.ts`)
+
+Practical rule:
+- Installing a local SDK version outside the declared peer range can fail compatibility tests.
+- Keep local `node_modules/openclaw` aligned with the declared peer range.
+
+## Official host reference
+
+For official OpenClaw plugin installation behavior, see:
+- https://docs.openclaw.ai/tools/plugin
+
+
+### Quick navigation
+
+> Choose one install track, then complete Section 3.
+
+1. Source-truth installation: [Section 1](#section-1-source-truth-installation) (hard way)
+2. Release-truth installation: [Section 2](#section-2-release-truth-installation) (easy way)
+
+---
+
+## Section 1: Source-truth installation
+
+Use this flow when you want to install `Berry Shield` directly from the repository source code.
+
+### Step 1: Clone repository from GitHub
+
+```bash
+git clone https://github.com/F4bioo/berry-shield.git
+```
+Expected: repository files are copied to a local `berry-shield` folder.
+
+### Step 1.1: Check permissions on the cloned repository
+
+Before installing the plugin, check the permissions of the cloned repository. OpenClaw can block plugin installation if the plugin directory is `world-writable`.
+
+Linux/macOS:
+```bash
+ls -ld ./berry-shield
+```
+Expected (Linux/macOS):
+- secure example: `drwxr-xr-x` (`755`) or stricter
+- insecure example: any mode where `others` has write (`...w...`), such as `777`
+- goal: `others` must NOT have write permission.
+
+Optional fix (only if permissions are too broad):
+```bash
+chmod -R u=rwX,go=rX ./berry-shield
+```
+
+Expected (Linux/macOS after applying correct permissions):
+- command is silent (no output) when successful
+
+Windows (PowerShell):
+```powershell
+Get-Acl .\berry-shield | Format-List
+```
+Expected (Windows):
+- ACL does not grant broad write access to untrusted principals (for example, `Everyone` or generic `Users` with write/modify).
+- write/modify should remain restricted to the owner/admin context.
+
+Optional fix (only if permissions are too broad):
+```powershell
+icacls .\berry-shield /inheritance:e /grant:r "${env:USERNAME}:(OI)(CI)F" "*S-1-5-32-545:(OI)(CI)RX" /t
+```
+
+Expected (Windows after applying correct permissions):
+- `processed file: .\berry-shield`
+- `Successfully processed 1 files; Failed processing 0 files`
+
+### Step 2: Enter repository root
+
+```bash
+cd berry-shield
+```
+Expected: terminal is at the Berry Shield project root.
+
+### Step 3: Install dependencies
+
+**Note:** If dependencies are already installed and current, skip to Step 4.
+
+```bash
+npm install
+```
+Expected: dependencies are installed without lockfile or platform errors.
+
+### Step 4: Build plugin artifact
+
+```bash
+npm run build
+```
+Expected: `dist/index.js` is generated successfully.
+
+### Step 5: Install plugin from local source path
+
+Run from the root of the local `berry-shield` project folder.
+```bash
+openclaw plugins install .
+```
+Expected: 
+```terminaloutput
+Installed plugin: berry-shield
+Restart the gateway to load plugins.
+```
+
+### Step 6: Restart Gateway runtime
+
+Restart the OpenClaw Gateway process used by your environment.
+Expected: plugin registry reloads and Berry CLI becomes available.
+
+**Next:** [complete Section 3](#section-3-common-post-install-actions-applies-to-both-tracks).
+
+---
+
+## Section 2: Release-truth installation
+
+Use this flow when you want to install Berry Shield from the published package in the registry.
+
+### Step 1: Install from registry
+
+```bash
+openclaw plugins install @f4bioo/berry-shield
+```
+Expected: 
+```terminaloutput
+Installed plugin: berry-shield
+Restart the gateway to load plugins.
+```
+
+### Step 2: Restart Gateway runtime
+
+Restart the OpenClaw Gateway process used by your environment.
+Expected: plugin registry reloads and Berry CLI becomes available.
+
+**Next:** [complete Section 3](#section-3-common-post-install-actions-applies-to-both-tracks).
+
+---
+
+## Section 3: Common post-install actions (applies to both tracks)
+
+### Step 1: Initialize plugin defaults
+
+Run this command in the same environment where OpenClaw resolves Berry CLI commands and plugin config paths.
+```bash
+openclaw bshield init
+```
+Expected: Berry config is created/updated and plugin enabled state is prepared.
+
+```terminaloutput
+18:29:23 [plugins] 🍓 Initializing Berry Shield configuration...
+
+ ◇ Berry Shield Initialization ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+   ✓ Configuration already exists.
+
+   🍓 Berry Shield 2026.2.15 - Tip: Root layer injects runtime safety policy before agent execution starts.
+```
+
+> If you see this output, Berry Shield is already installed and initialized. You can skip the remaining installation steps and continue with the Wiki
+> index [Learn more](../README.md).
+
+---
+
+### Step 2: Verify runtime status
+
+Run this command immediately after initialization to confirm active runtime settings.
+```bash
+openclaw bshield status
+```
+Expected:
+```terminaloutput
+ ◇ Berry Shield ─────────────────────────────────────────────────────────────
+
+   Status       ENABLED
+   Mode         ENFORCE
+   Rules        Built-in (143) - Custom (0)
+
+   ◇ Policy
+   Profile           BALANCED
+   Escalation        3
+   Stale (min)       30
+   Heartbeat         0
+   Global Escalation OFF
+
+   ◇ Vine
+   Mode                BALANCED
+   Signals to Escalate 1
+   Guard Turns         3
+   Retention (entries) 10000
+   Retention (ttl sec) 86400
+   Allowlist           0 tool(s)
+
+   ◇ Security Layers
+   Root (Prompt Guard)   ACTIVE
+   Pulp (Output Scanner) ACTIVE
+   Thorn (Tool Blocker)  ACTIVE
+   Leaf (Input Audit)    ACTIVE
+   Stem (Security Gate)  ACTIVE
+   Vine (External Guard) ACTIVE
+
+   🍓 Berry Shield 2026.2.15 - Tip: Use 'openclaw bshield add' to create custom rules.
+```
+
+### Validation checklist
+
+1. Confirm plugin status is enabled.
+2. Confirm desired mode (`enforce` or `audit`) is set.
+3. Run one safe gate test and one deny-path test.
+4. Confirm report command can read events.
+
+### CLI customization shortcut
+
+Use this command to discover mode, layer, policy, and rules commands.
+
+```bash
+openclaw bshield --help
+```
+Usage Example: run this before changing defaults to review available command paths.
+
+Expected:
+```terminaloutput
+Usage: openclaw bshield [options] [command]
+
+Berry Shield - Custom security rules management
+
+Options:
+  -h, --help  display help for command
+
+Commands:
+  add         Add a new security rule (interactive wizard if no args)
+  help        display help for command
+  init        Initialize Berry Shield configuration
+  mode        Set operation mode (audit | enforce)
+  policy      Manage policy settings (wizard, get, set)
+  profile     Set policy profile (strict | balanced | minimal)
+  report      Show global audit report from persisted events
+  reset       Reset defaults (builtins or full scope)
+  rules       Manage baseline and custom rules
+  status      Show current status and configuration
+  test        Test if input matches any security pattern
+  toggle      Toggle a security layer on/off
+  vine        Manage Berry.Vine settings and tool allowlist
+
+For more info, visit: https://github.com/F4bioo/berry-shield
+
+
+   🍓 Berry Shield 2026.2.15 - Tip: Redaction replaces sensitive data with markers to ensure privacy.
+```
+
+See more:
+- [Berry Shield CLI reference](../operation/cli/README.md)
+
+---
+
+### Uninstall Berry Shield
+
+Step 1 removes Berry Shield from OpenClaw runtime config and install records.
+
+```bash
+openclaw plugins uninstall berry-shield
+```
+Expected: OpenClaw confirms `Removed: config entry, install record` and asks for gateway restart.
+
+Step 2 is a double-check for leftover local files.
+- If no Berry Shield folder is found, uninstall is complete.
+- If the folder still exists, run the delete command for your OS.
+
+Linux/macOS - verify leftovers:
+```bash
+ls -la ~/.openclaw/extensions/berry-shield
+```
+Expected:
+- `No such file or directory`: uninstall already complete.
+- folder listing shown: proceed to delete.
+
+Linux/macOS - delete leftovers:
+```bash
+rm -rf ~/.openclaw/extensions/berry-shield
+```
+Expected: command finishes silently and the folder no longer exists.
+
+Windows (PowerShell) - verify leftovers:
+```powershell
+Get-ChildItem -Force "$env:USERPROFILE\\.openclaw\\extensions\\berry-shield"
+```
+Expected:
+- `Cannot find path`: uninstall already complete.
+- folder listing shown: proceed to delete.
+
+Windows (PowerShell) - delete leftovers:
+```powershell
+Remove-Item -Recurse -Force "$env:USERPROFILE\\.openclaw\\extensions\\berry-shield"
+```
+Expected: command completes without error and the folder is removed.
+
+Windows (CMD) - verify leftovers:
+```cmd
+dir "%USERPROFILE%\\.openclaw\\extensions\\berry-shield"
+```
+Expected:
+- `File Not Found`: uninstall already complete.
+- directory listing shown: proceed to delete.
+
+Windows (CMD) - delete leftovers:
+```cmd
+rmdir /s /q "%USERPROFILE%\\.openclaw\\extensions\\berry-shield"
+```
+Expected: command returns to prompt and the folder is removed.
+
+---
+
+## Related pages
+- [deploy index](README.md)
+- [build](build.md)
+- [CLI init](../operation/cli/init.md)
+- [CLI status](../operation/cli/status.md)
+- [CLI report](../operation/cli/report.md)
+
+---
+
+## Navigation
+- [Back to Deploy Index](README.md)
+- [Back to Wiki Index](../README.md)

package/docs/wiki/engine/README.md

@@ -0,0 +1,53 @@
+---
+summary: "Engine index for Berry scanning, matching, and performance behavior"
+read_when:
+  - You need a technical map of content-processing internals
+  - You are debugging detection or redaction behavior
+  - You are evaluating runtime cost and safety tradeoffs
+title: "Engine Reference"
+---
+
+# `Engine reference`
+
+This page is the entry point for Berry engine internals.
+It covers how matching, redaction, and performance characteristics fit together.
+
+## Engine pages
+
+- [redaction](redaction.md): transformation behavior for string/object payloads
+- [match engine](match-engine.md): safe CLI regex matching behavior
+- [performance](performance.md): runtime cost model and optimization tradeoffs
+
+## Engine interaction (single view)
+
+```mermaid
+flowchart TD
+    IN[Input or output payload] --> M1[Match evaluation]
+    M1 --> D{Transform required?}
+    D -->|No| FAST[Fast return path]
+    D -->|Yes| RED[Redaction traversal path]
+    RED --> OUT[Sanitized payload]
+    FAST --> OUT
+    CLI[CLI rule tests] --> SAFE[Safe match engine with timeout]
+    SAFE --> M1
+    PERF[Performance controls] --> M1
+    PERF --> RED
+```
+
+## Responsibility boundaries
+
+- Redaction page explains how content is transformed.
+- Match engine page explains safe CLI regex execution.
+- Performance page explains cost drivers, optimization levers, and tradeoffs.
+
+## Related pages
+- [wiki index](../README.md)
+- [layers index](../layers/README.md)
+- [decision patterns](../decision/patterns.md)
+
+---
+
+## Navigation
+- [Back to Wiki Index](../README.md)
+- [Back to Repository README](../../../README.md)
+

package/docs/wiki/engine/match-engine.md

@@ -0,0 +1,91 @@
+---
+summary: "Engine reference for safe regex matching used by Berry CLI rule validation paths"
+read_when:
+  - You are debugging CLI pattern test behavior
+  - You are validating regex safety in rule preview flows
+  - You need to understand timeout behavior in pattern matching
+title: "match engine"
+---
+
+# `Match engine`
+
+Berry match engine is the safe regex matching utility used by CLI validation paths.
+Its goal is to reduce catastrophic-regex risk during interactive or deterministic pattern checks.
+
+## Engine responsibilities
+
+- Compile and evaluate regex patterns for CLI matching operations.
+- Apply bounded execution timeout for regex test runs.
+- Support case-insensitive prefix normalization.
+- Fail safely on invalid patterns.
+
+## Runtime flow
+
+```mermaid
+flowchart TD
+    A[Input text + raw pattern] --> N[Normalize pattern and flags]
+    N --> V[Run regex test in VM context]
+    V --> T{Execution outcome}
+    T -->|match/no match| OK[Return boolean result]
+    T -->|timeout| ERR[Throw timeout safety error]
+    T -->|invalid regex| SAFE[Return false]
+```
+
+## Processing details
+
+### Pattern normalization
+
+- default flags are case-insensitive global matching
+- inline prefix `(?i)` is normalized into case-insensitive behavior
+
+### Safe execution boundary
+
+- matching runs in a VM execution context
+- timeout is bounded (default 100ms, configurable)
+- timeout triggers explicit safety error describing potential ReDoS condition
+
+### Failure behavior
+
+- invalid regex syntax returns false
+- timeout raises explicit error to surface risk
+
+## Where this engine is used
+
+- CLI test command pattern checks
+- CLI wizard preview checks for rule creation paths
+
+This utility is a CLI-side matcher.
+Runtime layer interception/redaction uses separate utilities optimized for layer execution paths.
+
+## Operational value
+
+This engine provides:
+- safer CLI pattern experimentation
+- predictable behavior for bad regex input
+- early signal for potentially catastrophic patterns
+
+## Limits and caveats
+
+- Timeout-based control reduces risk but does not replace regex quality review.
+- Behavior is scoped to CLI matching paths, not all runtime matching paths.
+- Very large inputs still increase work, even with timeout bounds.
+
+## Validation checklist
+
+1. Confirm normal pattern returns expected boolean.
+2. Confirm invalid regex returns false without process crash.
+3. Confirm catastrophic pattern triggers timeout safety error.
+4. Confirm wizard/test commands produce consistent matching decisions.
+
+## Related pages
+- [engine index](README.md)
+- [redaction](redaction.md)
+- [performance](performance.md)
+- [CLI test command](../operation/cli/test.md)
+
+---
+
+## Navigation
+- [Back to Engine Index](README.md)
+- [Back to Wiki Index](../README.md)
+