@f4bioo/berry-shield 2026.3.3-1

package/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to Berry Shield 🍓
+
+Thank you for your interest in contributing! To maintain the quality and security of Berry Shield, please follow these guidelines.
+
+## 🤝 Support & Contributions
+This project is actively maintained, but it's built and supported in my free time.
+Issues, feedback, and Pull Requests are always welcome! While I can't promise immediate response times or a formal SLA, I do my best to review and help as soon as possible.
+
+## 🛠️ Technical Requirements
+Before submitting a Pull Request, ensure:
+1. **Language:** Code, comments, and documentation must be in **English**.
+2. **Technical Gates:** Your changes must pass all local checks:
+   - `npm run typecheck`
+   - `npm run test`
+   - `npm run build`
+3. **Wiki:** If you added or changed features, update the relevant files in `docs/wiki/`.
+
+## 🧬 Branching Model
+Berry Shield uses a **trunk-based** flow:
+1. Create a short-lived branch from `master`.
+2. Open a Pull Request targeting `master`.
+3. Merge after required checks and review pass.
+
+## 📝 Commit & PR Standards
+We use the **Conventional Commits** pattern for titles:
+`type(scope): description`
+*Examples: `feat(vine): add new heuristic`, `fix(stem): resolve file path bypass`*
+
+Your Pull Request body must follow the provided template and include a **Validation** section explaining how you tested the changes.
+
+---
+*By contributing to Berry Shield, you agree that your contributions will be licensed under the Apache-2.0 [LICENSE](LICENSE).*

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,251 @@
+# 🍓 Berry Shield
+
+Security plugin for OpenClaw that reduces data leakage risk and blocks unsafe operations in agent workflows.
+
+## 🧐 Why this exists
+
+Berry Shield was created from a practical problem: during routine setup checks, the agent could expose sensitive data directly in chat (API keys, tokens,
+SSH material, and other secrets).
+
+Typical examples included:
+- reading config files that contained credentials (`openclaw.json`, `.env`, cloud credentials)
+- returning sensitive command/file output without sanitization
+- exposing private paths or secret-bearing content in normal troubleshooting flows
+
+Design principles:
+- Agents can read or execute sensitive operations by mistake.
+- Prompt-only guardrails are not enough in real runtimes.
+- Security controls must be visible, configurable, and testable from CLI.
+
+The goal of `Berry Shield` is to reduce that risk in day-to-day usage by adding guardrails for access checks, runtime blocking, and output redaction.
+
+---
+
+## ✓ What it is / ✗ What it is not
+
+### ✓ What it is
+
+- `Berry Shield` is an `OpenClaw` plugin that adds layered guardrails, audit, and redaction for agent workflows.
+- Enforces a pre-flight security gate with `berry_check` before risky operations.
+- Intercepts tool calls and blocks destructive or sensitive access patterns.
+- Scans and redacts sensitive output before persistence and outbound delivery.
+- Supports `enforce` and `audit` modes for rollout and validation.
+- Provides CLI management for status, mode, policy, layers, rules, and report.
+
+### ✗ What it is not
+
+- Not a sandbox, VM, container isolation, or kernel boundary.
+- Not a replacement for host hardening, least privilege, or secrets management.
+- Not a guarantee against fully compromised hosts or malicious dependencies.
+
+---
+
+## 🧭 When to use / When not to use
+
+### Use Berry Shield when
+
+- Your agent has command/file capabilities and you need to reduce accidental leakage.
+- You operate on chat surfaces where unsafe output can be exposed quickly.
+- You need auditability for security decisions (`allowed`, `blocked`, `redacted`, `would_*`).
+
+### Do not use Berry Shield as
+
+- The only security boundary in untrusted multi-tenant environments.
+- A compliance silver bullet without operational governance.
+
+---
+
+## ⚡ 90-second demo
+
+Baseline runtime state before the demo (plugin enabled, `enforce` mode, all core layers active):
+
+<img src="https://raw.githubusercontent.com/F4bioo/berry-shield/master/docs/assets/demo/berry-shield-status.jpeg" alt="Berry Shield Status" width="720" />
+
+---
+
+### 1) Enforce: external-risk action is blocked (Vine)
+
+```bash
+# in chat/runtime: ingest external content with web_fetch, then preflight an exec write
+bash -lc 'printf DEMO_VINE > /tmp/demo-vine-proof.txt'
+```
+
+Expected: denied in `enforce` after external untrusted ingestion.
+
+<img src="https://raw.githubusercontent.com/F4bioo/berry-shield/master/docs/assets/demo/Berry.Vine-ENFORCE.gif" alt="Berry.Vine Enforce" />
+
+---
+
+### 2) Audit: same flow is allowed but logged as would_block
+
+```bash
+# same write-like operation under audit mode
+bash -lc 'printf VINE_AUDIT > /tmp/vine-audit-proof.txt'
+```
+
+Expected: allowed execution plus `would_block` evidence in report/audit logs.
+
+<img src="https://raw.githubusercontent.com/F4bioo/berry-shield/master/docs/assets/demo/Berry.Vine-AUDIT.gif" alt="Berry.Vine Audit" />
+
+---
+
+### 3) Sensitive file read is blocked (Stem)
+
+Expected: denied read when attempting to access protected files.
+
+<img src="https://raw.githubusercontent.com/F4bioo/berry-shield/master/docs/assets/demo/berry-shield-Berry.Stem-layer.jpeg" alt="Berry.Stem Block" width="520" />
+
+Runtime evidence:
+
+```text
+2026-02-27T15:53:59.195Z [gateway] [berry-shield] Berry.Stem: DENIED read - sensitive file: /home/zyn/.openclaw/openclaw.json
+```
+
+---
+
+### 4) Redaction: sensitive output is sanitized (Pulp)
+
+```bash
+openclaw config get channels.telegram
+```
+
+Expected: sensitive fields are masked in tool output, e.g. `botToken` becomes `[BOTTOKEN_REDACTED]`.
+
+Why this matters: even read-only tools can still return sensitive values during normal operations.
+Operator intent ("do not expose secrets") is useful, but not sufficient by itself; protection must happen in the output path.
+
+Implementation basis:
+- Berry.Pulp scans tool outputs at `tool_result_persist` and redacts matched secrets/PII before transcript persistence.
+- Berry.Pulp also scans `message_sending` to redact sensitive data in outgoing assistant messages when supported by runtime hooks.
+- In `audit`, events are logged as `would_redact`; in `enforce`, values are actively redacted.
+
+Evidence (real redacted output):
+
+```json
+{
+  "enabled": true,
+  "dmPolicy": "pairing",
+  "botToken": "[BOTTOKEN_REDACTED]",
+  "groupPolicy": "allowlist",
+  "streaming": "partial"
+}
+```
+
+<img src="https://raw.githubusercontent.com/F4bioo/berry-shield/master/docs/assets/demo/berry-shield-Berry.Pulp-layer.jpeg" alt="Berry.Pulp Redaction" width="520" />
+
+---
+
+## 🛡️ Security Audit & Installation Notice
+
+> [!WARNING]
+> **Expected heuristic warnings:**
+> During `openclaw plugins install`, OpenClaw may flag patterns such as `child_process` usage and environment-based runtime resolution.
+> In Berry Shield, these patterns are used for legitimate host integration (OpenClaw CLI/config bridge), not hidden execution paths.
+>
+> This is a heuristic warning, not a malware verdict.
+> For a code-level mapping of each warning, see [Security Audit](SECURITY_AUDIT.md).
+
+---
+
+## ⚡ Quickstart
+
+Install from npm package:
+
+```bash
+openclaw plugins install @f4bioo/berry-shield
+```
+
+**Note:** Berry Shield is plug-and-play after install. No extra setup is required for baseline protection.
+
+See more:
+- [Berry Shield Installation guide](docs/wiki/deploy/installation.md)
+
+---
+
+**Note:** If you want to customize mode, layers, or policy, use:
+
+```bash
+openclaw bshield --help
+```
+ 
+See more:
+- [Berry Shield CLI reference](docs/wiki/operation/cli/README.md)
+
+---
+
+## 🧠 Mental model (single flow)
+
+Berry Shield is designed with multiple layers. The idea is that if an interaction isn't caught by one layer, it might be caught by another.
+
+<img src="https://raw.githubusercontent.com/F4bioo/berry-shield/master/docs/assets/demo/mental-model-single-flow.jpeg" alt="Mental Model Single Flow" />
+
+## 🧬 Layers in plain language
+
+| Layer | Purpose | Practical effect |
+| :--- | :--- | :--- |
+| **Leaf** 🍃 | **Input audit** | Logs sensitive signals in incoming content for observability. |
+| **Root** 🌱 | **Prompt guard** | Injects security policy/reminders into agent context by profile strategy. |
+| **Stem** 🪵 | **Security gate** | `berry_check` tool decides if intended operation is allowed or denied. |
+| **Thorn** 🌵 | **Runtime blocker** | Intercepts tool calls and blocks risky command/file patterns in enforce mode. |
+| **Vine** 🌿 | **External guard** | Marks external-content risk and can block sensitive actions under active risk. |
+| **Pulp** 🍇 | **Output scanner** | Redacts sensitive data in tool results and outgoing messages in enforce mode. |
+
+See more:
+- [Berry Shield layers](docs/wiki/layers/README.md)
+
+---
+
+## ⚙️ Modes and profiles
+
+### Modes (`mode`)
+
+| Mode | Behavior |
+| :--- | :--- |
+| `enforce` | **Active Defense**: Blocks/Redacts when patterns match. |
+| `audit` | **Silent Observation**: Logs what *would* have happened (`would_block`, `would_redact`). |
+
+### Profiles (`policy.profile`)
+
+| Profile | Injection behavior |
+| :--- | :--- |
+| `strict` | **Full policy** injection every turn. |
+| `balanced` | **Adaptive**: Full on first turn, then `short`/`none` depending on risk/staleness. |
+| `minimal` | **Silent**: Minimal injection by default; escalates only on critical triggers. |
+
+
+See more:
+- [Berry Shield modes and profiles](docs/wiki/decision/modes.md)
+
+---
+
+## 🚧 Technical Limitations & SDK Diary
+
+Berry Shield's effectiveness is tied to the underlying OpenClaw SDK capabilities. We maintain a detailed diary that tracks known bugs and blind spots across OpenClaw versions.
+
+### Key Points for v2026.2.26:
+*   **Hook Reliability**: In our v2026.2.26 checkpoint, `before_tool_call` and `message_sending` were observed as functional, but hook behavior remains runtime/version-dependent.
+*   **Soft Guardrails**: Prompt-based defenses (`Berry.Root`) are advisory and can be bypassed by clever user instructions.
+*   **Timing Gaps**: Redaction happens during persistence, which might create a transient data exposure.
+
+See more: 
+-  [Security posture and known limits](docs/wiki/decision/posture.md)
+
+---
+
+## 📚 Docs map
+
+- Wiki overview: [docs/wiki/README.md](docs/wiki/README.md)
+- Install and deploy: [docs/wiki/deploy/installation.md](docs/wiki/deploy/installation.md)
+- CLI commands: [docs/wiki/operation/cli/README.md](docs/wiki/operation/cli/README.md)
+- Layer internals: [docs/wiki/layers/README.md](docs/wiki/layers/README.md)
+- Mode/profile decisions: [docs/wiki/decision/modes.md](docs/wiki/decision/modes.md)
+- Pattern strategy: [docs/wiki/decision/patterns.md](docs/wiki/decision/patterns.md)
+- Tutorials: [docs/wiki/tutorials/README.md](docs/wiki/tutorials/README.md)
+
+---
+
+## ⚖️ License
+
+Apache-2.0. See [LICENSE](LICENSE).
+
+For contributor workflow and internal quality process, see [CONTRIBUTING.md](CONTRIBUTING.md).

package/SECURITY_AUDIT.md

@@ -0,0 +1,96 @@
+---
+summary: "Security-audit note that maps OpenClaw install-time heuristic warnings to Berry Shield source paths"
+read_when:
+  - You saw OpenClaw install-time warnings and want a direct code-level explanation
+  - You are auditing why host integration patterns are flagged by static heuristics
+title: "Security Audit"
+---
+
+# `Berry Shield Security Audit`
+
+This project is open source and community-auditable by design.
+
+During `openclaw plugins install`, OpenClaw may show heuristic warnings such as:
+```text
+WARNING: Plugin "berry-shield" contains dangerous code patterns: Shell command execution detected (child_process) (.../berry-shield/dist/index.js:xxxx); Environment variable access combined with network send — possible credential harvesting (.../berry-shield/dist/index.js:xxxx)
+```
+
+For Berry Shield, these warnings are expected from legitimate host-integration behavior:
+- `src/config/wrapper.ts:1` uses Node `child_process` invocation to call OpenClaw CLI config commands.
+- `src/config/wrapper.ts:58` reads `OPENCLAW_EXECUTABLE` / `OPENCLAW_BIN` to resolve runtime binary path.
+
+**Note:** Line numbers reported in `dist/index.js` can point to bundled code regions and are not always a direct 1:1 map to source declarations.
+
+No hidden trust model is required:
+- install if you want,
+- audit if you want,
+- verify directly in source.
+
+## Positioning
+
+- Berry Shield is explicit about security behavior and limits.
+- Install-time warnings are treated as signals to inspect, not as automatic proof of malicious code.
+- Documentation must map warnings to concrete code paths whenever possible.
+
+## Why these patterns exist
+
+Berry Shield needs host integration to read/write plugin config through OpenClaw itself.
+Without this bridge, CLI and runtime config sync would be unreliable across environments.
+
+```javascript
+import { execFile } from "node:child_process";
+
+function getOpenClawCommand() {
+  // Host/runtime override for different environments (dev, CI, custom install)
+  return process.env.OPENCLAW_EXECUTABLE || process.env.OPENCLAW_BIN || "openclaw";
+}
+
+async function setPluginConfig(path, value) {
+  // Berry uses OpenClaw CLI as source of truth for persisted config
+  // (instead of writing random files directly).
+  const command = getOpenClawCommand();
+  await execFile(command, ["config", "set", path, JSON.stringify(value), "--json"]);
+}
+```
+
+Source of truth: [`src/config/wrapper.ts`](src/config/wrapper.ts)
+
+If this integration did not exist, Berry Shield would lose deterministic config behavior and cross-environment compatibility.
+
+---
+
+## Verification
+
+1. Verify installed plugin identity and runtime wiring:
+
+```bash
+openclaw plugins info berry-shield
+```
+Expected output:
+```terminaloutput
+Berry Shield
+id: berry-shield
+Security plugin designed to mitigate flagged commands and redact detected secrets/PII
+
+Status: loaded
+Source: ~/.openclaw/extensions/berry-shield/dist/index.js
+Origin: global
+Version: 2026.2.15
+Tools: berry_check
+CLI commands: bshield
+
+Install: path
+Source path: ~/berry-shield
+Install path: ~/.openclaw/extensions/berry-shield
+Recorded version: 2026.2.15
+Installed at: 2026-02-22T18:18:52.793Z
+```
+
+## Related pages
+- [Installation Guide](docs/wiki/deploy/installation.md)
+- [Security Posture](docs/wiki/decision/posture.md)
+
+---
+
+## Navigation
+- [Back to Repository README](README.md)

package/docs/wiki/README.md

@@ -0,0 +1,108 @@
+---
+summary: "Main wiki entrypoint with reading paths and full domain map"
+read_when:
+  - You need a complete overview of Berry Shield documentation
+  - You are onboarding and need a recommended reading path
+  - You are looking for where each topic is documented
+title: "Berry Shield Wiki"
+---
+
+# `Berry Shield Wiki`
+
+Berry Shield documentation for OpenClaw operators, contributors, and maintainers.
+This wiki follows a Diataxis-style split: tutorials, operations, decisions, internals, and deployment.
+
+## Read This First
+
+Berry Shield is an application-layer security plugin.
+It can enforce guardrails, block risky operations, and sanitize output paths.
+It is not host isolation or operating-system hardening.
+
+Known host/runtime constraints are documented in:
+- [Security Posture](decision/posture.md)
+- [Security Audit (root)](../../SECURITY_AUDIT.md)
+
+## Start Here (By Goal)
+
+- First-time setup and validation:
+  - [Your First Secure Session](tutorials/secure-session.md)
+- Choose behavior strategy before rollout:
+  - [Choose Your Profile](tutorials/choose-profile.md)
+  - [Tune Policy](tutorials/tune-policy.md)
+- Roll out to real workloads safely:
+  - [Audit-to-Enforce Rollout](tutorials/audit-to-enforce-rollout.md)
+- Investigate events and close coverage gaps:
+  - [Incident Triage with Report](tutorials/incident-triage-report.md)
+
+## Wiki Map
+
+### Tutorials (Learning-oriented)
+Guided, step-by-step workflows for operators and new users.
+
+- [Tutorial Index](tutorials/README.md)
+- [Your First Secure Session](tutorials/secure-session.md)
+- [Choose Your Profile](tutorials/choose-profile.md)
+- [Tune Policy](tutorials/tune-policy.md)
+- [Build Custom Rules](tutorials/build-custom-rules.md)
+- [Audit-to-Enforce Rollout](tutorials/audit-to-enforce-rollout.md)
+- [Incident Triage with Report](tutorials/incident-triage-report.md)
+
+### Operation (How-to)
+How to run Berry Shield through supported interaction surfaces.
+
+- [Operation Index](operation/README.md)
+- [CLI Reference](operation/cli/README.md)
+- [Web Reference](operation/web/README.md)
+
+### Decision (Explanation)
+Why behavior is designed this way: mode semantics, pattern strategy, and explicit limits.
+
+- [Decision Index](decision/README.md)
+- [Modes](decision/modes.md)
+- [Patterns](decision/patterns.md)
+- [Security Posture](decision/posture.md)
+
+### Layers (Architecture)
+Cross-layer model and responsibilities for Root, Leaf, Stem, Thorn, and Pulp.
+
+- [Layers Index](layers/README.md)
+- [Root](layers/root.md)
+- [Leaf](layers/leaf.md)
+- [Stem](layers/stem.md)
+- [Thorn](layers/thorn.md)
+- [Pulp](layers/pulp.md)
+
+### Engine (Internals)
+Detection/transformation internals and runtime cost model.
+
+- [Engine Index](engine/README.md)
+- [Redaction](engine/redaction.md)
+- [Match Engine](engine/match-engine.md)
+- [Performance](engine/performance.md)
+
+### Deploy (Build and release operations)
+Installation tracks, build gates, and doc quality gates.
+
+- [Deploy Index](deploy/README.md)
+- [Installation](deploy/installation.md)
+- [Build](deploy/build.md)
+- [Auditing](deploy/auditing.md)
+
+## Suggested Reading Paths
+
+- Operator path:
+  - `tutorials/secure-session.md` -> `operation/cli/README.md` -> `decision/modes.md`
+- Security-review path:
+  - `decision/posture.md` -> `layers/README.md` -> `engine/redaction.md`
+- Contributor path:
+  - `layers/README.md` -> `engine/README.md` -> `deploy/build.md`
+
+---
+
+> [!WARNING]
+> This wiki is actively maintained. If runtime behavior changes, update docs in the same change set.
+
+---
+
+## Navigation
+- [Back to Repository README](../../README.md)