@datafog/fogclaw 0.1.0

package/docs/plugins/fogclaw.md

@@ -0,0 +1,95 @@
+---
+summary: "FogClaw plugin for agent message redaction and PII scanning"
+read_when:
+  - You want optional built-in privacy tooling in OpenClaw
+  - You need configurable redaction, blocking, or warning for sensitive content
+  - You are setting up a custom entity scanner in your agent workflow
+title: "FogClaw Plugin"
+---
+
+# FogClaw (plugin)
+
+FogClaw is an OpenClaw plugin that protects agent workflows by detecting and handling sensitive data before or during tool execution.
+
+It provides both proactive guardrail behavior (via the `before_agent_start` hook) and explicit tools:
+
+- `fogclaw_scan`: scans text for PII and custom entities.
+- `fogclaw_redact`: scans and redacts sensitive matches.
+
+## Install
+
+```bash
+openclaw plugins install @datafog/fogclaw
+```
+
+After install, restart the Gateway and enable/configure `plugins.entries.fogclaw`.
+
+## Plugin entry
+
+The package exports the plugin manifest and entry as:
+
+- plugin id: `fogclaw`
+- package name: `@datafog/fogclaw`
+- extension entry: `./dist/index.js`
+
+## What it scans
+
+- Structured PII via regex (for example emails, phone numbers, SSNs, credit cards)
+- Custom named-entity labels via GLiNER zero-shot detection
+
+You can also define custom entity labels and per-entity actions in config (for example `redact`, `block`, or `warn`).
+
+## Behavior at a glance
+
+- Runs as a plugin loaded by the standard OpenClaw plugin pipeline.
+- Supports local-only and hosted environments; works from OpenClaw extensions path.
+- Fails safely to regex-only mode if optional GLiNER model initialization is unavailable.
+
+## Configuration reference
+
+Set plugin config under `plugins.entries.fogclaw.config`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      fogclaw: {
+        enabled: true,
+        config: {
+          enabled: true,
+          guardrail_mode: "redact",
+          redactStrategy: "token",
+          confidence_threshold: 0.5,
+          custom_entities: ["project codename", "competitor name"],
+          entityActions: {
+            EMAIL: "redact",
+            PHONE: "redact",
+            SSN: "block",
+            CREDIT_CARD: "block",
+            PERSON: "warn",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Use in the OpenClaw tool policy
+
+When enabled, the plugin registers the `before_agent_start` hook and two tools:
+
+- `fogclaw_scan`
+- `fogclaw_redact`
+
+These tools accept a required `text` field and optional strategy / custom label overrides.
+
+For install and reproducible package metadata evidence, use the package's `openclaw.extensions` field:
+
+```json
+{
+  "openclaw": {
+    "extensions": ["./dist/index.js"]
+  }
+}
+```

package/docs/runbooks/address-review-findings.md

@@ -0,0 +1,30 @@
+---
+title: "Address Review Findings"
+use_when: "You have review findings in an active plan and need a consistent process to fix, re-run review, and document what changed."
+called_from:
+  - he-review
+  - he-implement
+---
+
+# Address Review Findings
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+## Workflow
+
+1. Triage findings by priority.
+2. For each `critical`/`high`, do one of:
+   - fix it (preferred), or
+   - escalate per `he-review` SKILL.md § Escalation if behavior is ambiguous or risk is unclear.
+3. For `medium`/`low`, either:
+   - fix it, or
+   - accept it explicitly in the plan with rationale and follow-up link.
+4. Update evidence:
+   - rerun the most relevant tests
+   - update `Artifacts and Notes` with new proof
+5. Update `Progress`, `Decision Log`, and `Revision Notes` in the plan to reflect what changed and why.
+6. Re-run `he-review` if the change materially altered behavior or implementation.
+
+## Re-entry Rules
+
+See `he-review` SKILL.md § Re-entry Rules for the canonical gates (design-level issues and material behavior changes).

package/docs/runbooks/ci-failures.md

@@ -0,0 +1,46 @@
+---
+title: "Remediate CI Failures"
+use_when: "A verify/release gate fails due to build/test/lint failures locally or in CI; you need a consistent triage and stop/escalate policy."
+called_from:
+  - he-verify-release
+  - he-implement
+---
+
+# Remediate CI Failures
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+Treat CI failures as signal. The goal is not to make CI green by any means; it is to restore correctness with minimal, root-cause fixes.
+
+## Triage Order
+
+1. Confirm you are testing the right thing (branch, commit, env).
+2. Identify failure class:
+   - deterministic test failure
+   - flaky test
+   - lint/format/typecheck
+   - build/tooling regression
+3. Reduce to the smallest reproducer command.
+
+## Deterministic Failures
+
+- Add or adjust a real unit/e2e test when the failure indicates a missing assertion.
+- Fix the underlying behavior; avoid "just loosen the test" unless the test is truly wrong.
+
+## Flaky Failures
+
+- If you can reproduce locally, fix like deterministic.
+- If you cannot reproduce:
+  - mark as `judgment required` and escalate with evidence per the calling skill's § Escalation
+  - do not disable tests silently
+
+## Tooling Failures
+
+- Keep changes minimal and reversible.
+- Prefer pinning/fixing the tool invocation over broad refactors.
+
+## Required Evidence
+
+- Command used to reproduce
+- Short failure output excerpt
+- Command/output showing the fix

package/docs/runbooks/code-review.md

@@ -0,0 +1,34 @@
+---
+title: "Code Review"
+use_when: "Running he-review to perform structured review fanout, write Review Findings into the active plan, and decide whether the work can proceed to verify/release."
+called_from:
+  - he-review
+---
+
+# Code Review
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+The skill `he-review` enforces stable gates (fanout, findings format, and priority blocking). This document carries the details that change per project. Inputs: active plan (`docs/plans/active/<slug>-plan.md` with `## Review Findings`) and current branch diff/test evidence.
+
+## Output
+
+Populate `## Review Findings` with:
+
+- a prioritized list of findings (see `docs/runbooks/review-findings.md`)
+- accepted medium/low items (explicitly called out)
+- any required re-entry decision (`he-implement` vs `he-plan`)
+
+## What Review Must Cover (Customize Per Repo)
+
+Keep this list short and concrete:
+
+- correctness and edge cases in the changed area
+- tests: coverage of new behavior and regression prevention
+- user-visible behavior (if applicable) with evidence
+- security/data boundaries (if applicable)
+- performance or reliability impact (if applicable)
+
+## Escalation
+
+If review requires judgment (risk unclear, expected behavior ambiguous, flaky failures), stop and escalate per `he-review` SKILL.md § Escalation.

package/docs/runbooks/merge-change.md

@@ -0,0 +1,28 @@
+---
+title: "Merge Change"
+use_when: "You have a GO decision and need the minimum merge gate (checks/approvals/evidence) before merging to the main branch."
+called_from:
+  - he-verify-release
+---
+
+# Merge Change
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+This runbook captures the repo-specific merge gate. Keep it short and make it objective where possible.
+
+## Preconditions
+
+See `he-github` SKILL.md § Merge for the canonical merge gate. Add repo-specific preconditions below.
+
+## Merge Checklist (Customize Per Repo)
+
+- Required approvals obtained
+- Required checks passing
+- Versioning/release notes updated (if applicable)
+- Post-merge verification steps queued (see `docs/runbooks/verify-release.md`)
+
+## Post-Merge
+
+- Run the post-release checks documented in the plan
+- If any regression is found, open a follow-up and record it in learnings

package/docs/runbooks/pull-request.md

@@ -0,0 +1,45 @@
+---
+title: "Pull Request"
+use_when: "You need to open or update a PR that links the initiative plan and evidence, and you want a consistent PR hygiene/checks workflow."
+called_from:
+  - he-github
+  - he-implement
+  - he-review
+---
+
+# Pull Request
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+This runbook describes repo-specific PR conventions (title/body conventions, labels, reviewers, and required checks).
+
+## Preflight
+
+- `git status --short --branch`
+- `git diff`
+- `gh auth status`
+
+## Create Or Update PR (Customize Per Repo)
+
+Recommended `gh` flow:
+
+- Push:
+  - `git push -u origin HEAD`
+- Create:
+  - `gh pr create --fill`
+- Update:
+  - `gh pr edit --body-file <path>`
+
+## Required Links In PR Description
+
+- Spec: `docs/specs/<slug>-spec.md`
+- Plan: `docs/plans/active/<slug>-plan.md`
+- Evidence (if any): `docs/artifacts/<slug>/...`
+
+## Checks
+
+- View checks:
+  - `gh pr checks`
+- View a failing run:
+  - `gh run view --log-failed`
+

package/docs/runbooks/record-evidence.md

@@ -0,0 +1,43 @@
+---
+title: "Record Evidence"
+use_when: "You need screenshots or short recordings as proof of failure and proof of resolution, especially for UI or behavior changes."
+called_from:
+  - he-video
+  - he-verify-release
+  - he-implement
+---
+
+# Record Evidence
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+Evidence should be easy to review, easy to find, and tied to an artifact (plan/PR) so it does not get lost.
+
+## What To Capture
+
+- Failure evidence: what is broken, with a minimal reproduction
+- Resolution evidence: the same reproduction after the fix
+- Any relevant logs or error output (short)
+
+## Where To Put It
+
+- Link evidence from:
+  - `docs/plans/active/<slug>-plan.md` under `Artifacts and Notes` and `Verify/Release Decision`
+  - the PR description (if one exists)
+
+## Naming Convention
+
+Use predictable names so evidence is searchable:
+
+- `<slug>-failure.<ext>`
+- `<slug>-resolution.<ext>`
+
+If multiple clips exist:
+
+- `<slug>-failure-1.<ext>`, `<slug>-resolution-1.<ext>`
+
+## Minimum Bar
+
+- If you claim a bug exists, there is at least one artifact showing it.
+- If you claim it is fixed, there is at least one artifact showing the fix under the same scenario.
+- Prefer short clips (10-60s) over long walkthroughs.

package/docs/runbooks/reproduce-bug.md

@@ -0,0 +1,42 @@
+---
+title: "Reproduce Bug"
+use_when: "You have a bug report and need a minimal, reliable reproduction with evidence before implementing a fix."
+called_from:
+  - he-implement
+  - he-video
+---
+
+# Reproduce Bug
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+The goal is a smallest-possible reproducer you can run repeatedly to prove the bug exists and prove it is fixed.
+
+## Repro Checklist
+
+1. Write down the expected behavior vs observed behavior in plain language.
+2. Reduce to one of:
+   - a single command (unit/integration test, script, request), or
+   - a single UI flow script (agent-browser), or
+   - a single minimal fixture (input file, request payload).
+3. Make it deterministic:
+   - pin any randomness, time, or external dependencies when possible
+   - record env/config assumptions
+
+## Evidence Capture
+
+- For UI/behavior: capture a short `failure` video via `he-video`.
+- For non-UI: capture terminal output (command + short excerpt) and link it in the plan.
+
+## Test Strategy (Preferred)
+
+- Add a real unit or e2e test that fails on the current state.
+- Avoid mock-only tests unless the repo explicitly documents an exception.
+
+## Plan Updates
+
+Update `docs/plans/active/<slug>-plan.md`:
+
+- `Progress`: add/mark the repro artifact as complete only when repeatable
+- `Artifacts and Notes`: link the repro command/script and evidence paths
+

package/docs/runbooks/respond-to-feedback.md

@@ -0,0 +1,42 @@
+---
+title: "Respond To Feedback"
+use_when: "A PR has review comments or requested changes, and you need a consistent loop to address them with evidence and minimal diffs."
+called_from:
+  - he-github
+  - he-review
+  - he-implement
+---
+
+# Respond To Feedback
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+Treat feedback as new requirements. The objective is to address comments with the smallest correct change and keep the plan/evidence accurate.
+
+## Triage
+
+1. Group comments by theme (correctness, security/data, architecture, taste).
+2. Identify which comments require code changes vs explanation-only.
+3. For any comment that is ambiguous or high risk, escalate per `he-review` SKILL.md § Escalation.
+
+## Commands (Recommended)
+
+- Read comments:
+  - `gh pr view --comments`
+- Re-check CI:
+  - `gh pr checks`
+- Pull failed logs:
+  - `gh run view --log-failed`
+
+## Fix Loop
+
+1. Make the root-cause fix.
+2. Update tests/e2e evidence as needed.
+3. Update the active plan:
+   - `Progress` items
+   - `Review Findings` (if you’re tracking findings there)
+   - `Artifacts and Notes`
+4. Push and re-check (when approved):
+   - `git push`
+   - `gh pr checks`
+

package/docs/runbooks/review-findings.md

@@ -0,0 +1,31 @@
+---
+title: "Review Findings"
+use_when: "Writing or interpreting review findings in docs/plans/active/<slug>-plan.md under the Review Findings section."
+called_from:
+  - he-review
+---
+
+# Review Findings
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+Review findings must be actionable and verifiable. The goal is to let a future reader fix issues without rediscovering context.
+
+## Required Fields
+
+Each finding includes:
+
+- priority: `critical|high|medium|low`
+- location: file path + symbol or short pointer
+- issue summary: what is wrong
+- required action: what must change or what proof is missing
+- owner: who is responsible (team/name/agent)
+
+## Priority Rubric, No-Mocks Policy, Mandatory Coverage
+
+Canonical definitions live in `he-review` SKILL.md. Add repo-specific examples or exceptions below — do not redefine the severity levels or gate rules.
+
+## Acceptance Rules
+
+- Unresolved `critical` or `high` blocks progression to verify/release.
+- `medium` and `low` can proceed only if explicitly accepted in writing in the plan.

package/docs/runbooks/submit-openclaw-plugin.md

@@ -0,0 +1,68 @@
+---
+title: "Submitting a third-party plugin for official OpenClaw listing"
+called_from:
+  - he-learn
+  - he-implement
+  - he-verify-release
+read_when:
+  - You need to submit an external plugin package for official OpenClaw intake
+  - You are preparing a reviewable PR to openclaw/openclaw for plugin visibility
+---
+
+# Submitting a third-party plugin for official OpenClaw listing
+
+This repository is the third-party plugin source, while OpenClaw core intake is handled through `openclaw/openclaw`. Use this checklist when promoting a plugin from an external repo to official listing visibility.
+
+## Scope
+
+Apply this process for a plugin that is already validated in its own repo and needs official OpenClaw documentation/intake handling.
+
+## Prerequisites (in plugin repo)
+
+- Plugin manifest and metadata validated (`openclaw.plugin.json`, `package.json#openclaw.extensions`, `package.json#name`).
+- Plugin smoke/contract checks pass.
+- Runtime evidence available for plugin load and behavior.
+
+## Prepare upstream fork PR
+
+Because `openclaw/openclaw` generally expects cross-repo PRs from a fork, use this sequence unless the plugin repo is itself an existing fork.
+
+1. Use an org-owned fork as the preferred source (for this repository: `DataFog/openclaw`).
+2. Create a branch in the fork (for example `openclaw-fogclaw-submission`).
+3. Copy only official-listing artifacts from the plugin source repo (typically one or more docs/pages under `docs/plugins/`).
+4. Open PR from the fork branch to `openclaw/openclaw` (base `main`).
+
+- If an org-owned fork does not exist yet, use the fastest available forking path to open a temporary PR, then migrate to the org-owned fork once created.
+
+Do **not** include unrelated code changes in this PR unless required by maintainer feedback.
+
+## Evidence to include in PR body
+
+Use a compact, reproducible evidence block:
+
+- `npm test`
+- `npm run build` or `pnpm build` (repo-specific)
+- `npm run test:plugin-smoke`
+- `npm pkg get openclaw`
+- Node import smoke from `dist/index.js`
+
+## Useful PR body sections
+
+- Summary and impact
+- What changed and what did not change (scope boundary)
+- Security impact
+- Commands + expected outputs
+- Human verification
+- Compatibility/rollback
+
+## Review-time guardrails
+
+- Verify PR template expectations from `.github/pull_request_template.md` in upstream repo.
+- Keep PR title clear and scoped to official-listing changes.
+- Track maintainer feedback separately; only apply plugin code changes if explicitly requested.
+
+## Post-creation tracking
+
+- Record PR URL, branch/commit, and CI check status in the active initiative plan.
+- Keep plugin evidence/release status in sync with maintainer review and upstream merge checks.
+- If `@openclaw/<plugin>` is not yet visible in npm, record that as an explicit follow-up item rather than conflating it with code issues.

package/docs/runbooks/update-agents-md.md

@@ -0,0 +1,59 @@
+---
+title: "Update AGENTS.md"
+use_when: "Creating or updating a project's AGENTS.md (agent instructions, conventions, and workflows)."
+called_from:
+  - he-bootstrap
+  - he-learn
+  - he-doc-gardening
+---
+
+# Update AGENTS.md
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+AGENTS.md is the agent-facing README: a predictable place to put the few repo-specific instructions an agent needs to work effectively.
+
+When `he-bootstrap` runs in a repo that already has `AGENTS.md`, it appends a managed block once using:
+
+- `<!-- he-bootstrap:start -->`
+- `<!-- he-bootstrap:end -->`
+
+Do not edit outside your repo's intended scope when touching this managed block.
+
+## What To Optimize For
+
+- Keep it short and stable (a map, not an encyclopedia).
+- Put only high-leverage, repo-specific guidance here: build/test commands, conventions, and hard constraints.
+- Add rules over time when you observe repeated failure modes; do not try to predict everything up front.
+
+## What To Put Elsewhere
+
+- Long procedures, checklists, and evolving processes: `docs/runbooks/<topic>.md` and link from AGENTS.md.
+- One-off migrations or multi-hour work: a plan/spec doc under `docs/` (not in AGENTS.md).
+
+## Minimum Sections (Good Starting Point)
+
+- Setup commands (install, dev, test, lint) in copy-pastable form.
+- Repo map (where the important stuff lives; key entrypoints).
+- Conventions (formatting, naming, dependency rules, boundaries).
+- Safety and verification (what not to do; how to prove the change works here).
+- Runbook index (links into `docs/runbooks/` for process).
+
+## Rules Of Thumb When Editing AGENTS.md
+
+- If it changes often, it probably belongs in a runbook, not AGENTS.md.
+- Prefer "When X, do Y" over vague guidance.
+- Make requirements verifiable (a command, a file path, an expected output).
+- Avoid duplicating information already in `docs/`; link instead.
+- Keep any `he-bootstrap` managed block concise and link-first to avoid disrupting existing user conventions.
+
+## Quick Update Checklist
+
+1. Confirm scope: are you editing the right AGENTS.md for the files you are touching (root vs nested)?
+2. Keep it minimal: can you replace paragraphs with a link to a runbook?
+3. Verify paths/commands exist:
+
+```sh
+rg -n "docs/runbooks|PLANS\\.md|Runbooks|Setup|test|lint" AGENTS.md
+find docs/runbooks -type f -maxdepth 2 -name "*.md" -print
+```

package/docs/runbooks/update-domain-docs.md

@@ -0,0 +1,42 @@
+---
+title: "Update Domain Docs"
+use_when: "A change introduces new product/engineering policy (security, reliability, frontend, observability, design) that should be captured as durable guidance for future work."
+called_from:
+  - he-plan
+  - he-implement
+  - he-learn
+  - he-doc-gardening
+---
+
+# Update Domain Docs
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+Domain docs live under `docs/` and capture stable, repo-specific policy. Update them when you learn something that will prevent future bugs, regressions, or confusion.
+
+## What Counts As A Domain-Doc Change
+
+- A recurring decision rule ("we always do X when Y").
+- A new constraint or boundary (security model, data sensitivity, performance guardrails).
+- An operational expectation (SLOs, monitoring, alerts, rollback rules).
+- A UI/UX standard or accessibility requirement.
+
+If it's a one-off procedure or checklist, prefer a runbook in `docs/runbooks/`.
+
+## Where To Put It
+
+- The registry: `docs/DOMAIN_DOCS.md` (what exists and why).
+- The doc itself (when present): `docs/SECURITY.md`, `docs/RELIABILITY.md`, `docs/FRONTEND.md`, `docs/OBSERVABILITY.md`, `docs/DESIGN.md`, `docs/PRODUCT_SENSE.md`.
+
+## How To Update (Minimum)
+
+1. Add the smallest rule that will prevent the problem from recurring (short, testable language).
+2. Include a concrete anchor:
+   - a file path, command, config key, or observable behavior.
+3. Avoid long procedures; link to a runbook if needed.
+4. If the change implies enforcement, note the guardrail candidate (lint/test/CI gate) so it can be promoted later.
+
+## When To Do This
+
+- During `he-learn`, when converting "what happened" into durable prevention.
+- During review, if you discover undocumented constraints the next contributor will trip over.

package/docs/runbooks/validate-current-state.md

@@ -0,0 +1,41 @@
+---
+title: "Validate Current State"
+use_when: "Starting an initiative and you need to confirm you understand the current behavior, repo state, and baseline signals before changing code."
+called_from:
+  - he-workflow
+  - he-implement
+---
+
+# Validate Current State
+
+This runbook is repo-specific and **additive only**. It must not waive or override any gates enforced by skills.
+
+This runbook defines the minimum baseline checks before claiming you understand "what's broken" (or "what exists") today.
+
+## Repo Baseline
+
+- Confirm you are in the intended workspace (worktree/branch):
+  - `git status --short --branch`
+- Confirm clean-ish state (or record intentional local changes):
+  - `git diff`
+- Confirm remote + default branch context:
+  - `git remote -v`
+
+## Behavior Baseline (Customize Per Repo)
+
+Record the exact commands used and a short excerpt of the output in the active plan.
+
+- Boot the app/service:
+  - `<command>`
+- Run the fastest “is it alive” check:
+  - `<command>`
+- Run targeted tests for the area (if they exist):
+  - `<command>`
+
+## Evidence
+
+Link evidence from `docs/plans/active/<slug>-plan.md` under:
+
+- `Surprises & Discoveries` (what you observed)
+- `Artifacts and Notes` (logs, screenshots, recordings)
+