docs(wiki): sync from fefecaa60a

2026-06-13 05:28:02 +03:00 · 2026-02-26 08:43:46 +00:00
parent c484329145
commit e0511f64db
11 changed files with 746 additions and 14 deletions
@@ -1,9 +1,9 @@
 # Wiki Generation Metadata

- Commit hash: `448aed326192d38812cb508820f967cb74e77ae9`
- Branch name: `main`
- Generation timestamp (local): `2026-02-25T20:59:57+0200`
- Generation mode: `initial`
+- Commit hash: `d5aadfbee15b48ebb4872dfb838e4df88c611d56`
+- Branch name: `codex/wiki-tab-ui`
+- Generation timestamp (local): `2026-02-26T09:16:02+0200`
+- Generation mode: `update`
 - Output language: `English`
 - Assets copied into `wiki/assets/`:
  - `overview_img_01_prompt-security-logo.png` (from `img/Black+Color.png`)
@@ -11,8 +11,8 @@
  - `architecture_img_01_prompt-line.svg` (from `public/img/prompt_line.svg`)

 ## Notes
- This is a first-time generation (`wiki/` did not exist before this run).
- Index sections were generated from repository structure and created wiki pages.
+- Migrated root documentation pages from `docs/` into dedicated `wiki/` operation pages.
+- Updated index and cross-links to use `wiki/` as the documentation source of truth.
 - Future updates should preserve existing headings and append `Update Notes` sections when making deltas.

 ## Source References
@@ -24,3 +24,8 @@
 - wiki/dependencies.md
 - wiki/data-flow.md
 - wiki/glossary.md
+- wiki/security-signing-runbook.md
+- wiki/migration-signed-feed.md
+- wiki/platform-verification.md
+- wiki/remediation-plan.md
+- wiki/compatibility-report.md
@@ -5,7 +5,7 @@
 - Tech stack: React 19 + Vite + TypeScript frontend, Node/ESM scripts, Python utilities, Bash automation, GitHub Actions pipelines.
 - Entry points: `index.tsx`, `App.tsx`, `scripts/prepare-to-push.sh`, `scripts/populate-local-feed.sh`, `scripts/populate-local-skills.sh`, workflow files under `.github/workflows/`.
 - Where to start: Read [Overview](overview.md), then [Architecture](architecture.md), then module pages for the area you are editing.
- How to navigate: Use Guides for cross-cutting concerns, Modules for implementation boundaries, and Source References at the end of each page to jump into code.
+- How to navigate: Use Guides for cross-cutting concerns, Operations for runbooks and migration plans, Modules for implementation boundaries, and Source References at the end of each page to jump into code.

 ## Start Here
 - [Overview](overview.md)
@@ -19,6 +19,13 @@
 - [Workflow](workflow.md)
 - [Security](security.md)

+## Operations
+- [Security Signing Runbook](security-signing-runbook.md)
+- [Signed Feed Migration Plan](migration-signed-feed.md)
+- [Platform Verification Checklist](platform-verification.md)
+- [Cross-Platform Remediation Plan](remediation-plan.md)
+- [Cross-Platform Compatibility Report](compatibility-report.md)
+
 ## Modules
 - [Frontend Web App](modules/frontend-web.md)
 - [ClawSec Suite Core](modules/clawsec-suite.md)
@@ -32,6 +39,9 @@
 ## Generation Metadata
 - [Generation Metadata](GENERATION.md)

+## Update Notes
+- 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages.
+
 ## Source References
 - README.md
 - App.tsx
@@ -5,7 +5,7 @@
 - Tech stack: React 19 + Vite + TypeScript frontend, Node/ESM scripts, Python utilities, Bash automation, GitHub Actions pipelines.
 - Entry points: `index.tsx`, `App.tsx`, `scripts/prepare-to-push.sh`, `scripts/populate-local-feed.sh`, `scripts/populate-local-skills.sh`, workflow files under `.github/workflows/`.
 - Where to start: Read [Overview](overview.md), then [Architecture](architecture.md), then module pages for the area you are editing.
- How to navigate: Use Guides for cross-cutting concerns, Modules for implementation boundaries, and Source References at the end of each page to jump into code.
+- How to navigate: Use Guides for cross-cutting concerns, Operations for runbooks and migration plans, Modules for implementation boundaries, and Source References at the end of each page to jump into code.

 ## Start Here
 - [Overview](overview.md)
@@ -19,6 +19,13 @@
 - [Workflow](workflow.md)
 - [Security](security.md)

+## Operations
+- [Security Signing Runbook](security-signing-runbook.md)
+- [Signed Feed Migration Plan](migration-signed-feed.md)
+- [Platform Verification Checklist](platform-verification.md)
+- [Cross-Platform Remediation Plan](remediation-plan.md)
+- [Cross-Platform Compatibility Report](compatibility-report.md)
+
 ## Modules
 - [Frontend Web App](modules/frontend-web.md)
 - [ClawSec Suite Core](modules/clawsec-suite.md)
@@ -32,6 +39,9 @@
 ## Generation Metadata
 - [Generation Metadata](GENERATION.md)

+## Update Notes
+- 2026-02-26: Added Operations pages and updated navigation guidance after migrating root docs into wiki pages.
+
 ## Source References
 - README.md
 - App.tsx
@@ -0,0 +1,111 @@
+# Cross-Platform Compatibility Report
+
+## 1) Executive Summary
+
+### Overall status by OS
+- Linux: **Good**, primary workflows validated; still some POSIX-only scripts/docs.
+- macOS: **Good**, with caveats around POSIX tool availability and Homebrew-specific assumptions.
+- Windows: **Partial**, Node/Python pieces work, but many shell-first install/release workflows still require WSL/Git Bash.
+
+### Highest-risk incompatibilities
+1. **(Fixed)** Literal `$HOME` path creation risk in audit watchdog cron setup payload generation.
+2. **(Fixed)** Path env vars accepted as raw strings in multiple Node entrypoints without expansion/validation.
+3. **(Open)** Large portions of manual install/release guidance remain POSIX-only (`bash`, `jq`, `curl`, `unzip`, `chmod`, `find -exec`).
+
+### SKILLS install path-expansion root cause
+Root cause was a combination of:
+- shell-side literal env assignment (for example, `PROMPTSEC_INSTALL_DIR='$HOME/...')`
+- Node scripts not expanding home tokens
+- cron payload construction escaping `$` (`\$HOME`), forcing literal interpretation in downstream shell execution
+
+This could produce paths like `~/.openclaw/workspace/$HOME/...`.
+
+---
+
+## 2) Findings Table
+
+| ID | Severity | OS Impact | Component | Description | Proposed Fix | Status |
+|---|---|---|---|---|---|---|
+| CP-001 | Blocker | Linux/macOS/Windows | `skills/openclaw-audit-watchdog/scripts/setup_cron.mjs` | Literal `$HOME` could be propagated into cron payload, creating wrong runtime paths. | Expand/normalize home tokens and reject unresolved escaped tokens before job creation. | **Fixed** |
+| CP-002 | High | Linux/macOS/Windows | `skills/clawsec-suite/hooks/.../handler.ts`, `.../scripts/guarded_skill_install.mjs`, `.../lib/suppression.mjs`, `skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs` | Env path vars treated as opaque strings; `~`, `$HOME` not consistently handled. | Shared/consistent path resolution + fail-fast validation. | **Fixed** |
+| CP-003 | Medium | macOS/Windows | `skills/openclaw-audit-watchdog/test/render_report_suppression.test.mjs`, `.../scripts/codex_review.sh` | Hardcoded `/opt/homebrew` and `which` assumptions. | Use `process.execPath` for tests; PATH-first Codex discovery. | **Fixed** |
+| CP-004 | Medium | Windows (+ CI) | repo-wide line endings | Missing `.gitattributes` could introduce CRLF script breakage (`env bash^M`). | Add `.gitattributes` with LF enforcement for scripts/config/text. | **Fixed** |
+| CP-005 | Medium | macOS/Windows | `.github/workflows/ci.yml` | TS/lint/build checks were Linux-only. | Add OS matrix for Node checks (`ubuntu`, `macos`, `windows`). | **Fixed** |
+| CP-006 | High | Windows | Multiple SKILL docs and shell scripts | Install/maintenance flow is still heavily POSIX-shell based. | Add PowerShell equivalents or Node wrappers for critical flows. | Open |
+| CP-007 | Medium | Linux/macOS/Windows | `skills/soul-guardian/scripts/soul_guardian.py` | `Path(...).expanduser()` handles `~` but not `$HOME`/`%USERPROFILE%`. | Add explicit env-token expansion + validation for `--state-dir`. | Open |
+| CP-008 | Medium | Windows | `scripts/release-skill.sh`, `scripts/populate-local-*.sh` | GNU/BSD shell toolchain assumptions block native Windows usage. | Provide cross-platform Node/Python replacements or PowerShell equivalents. | Open |
+| CP-009 | Low | Windows | documentation + scripts using `chmod 600/644` | POSIX permission semantics are partial/non-portable on Windows. | Document best-effort behavior and Windows ACL alternatives. | Open |
+| CP-010 | Low | macOS/Windows | CI non-Node jobs | Shell/Python/security scan jobs remain Ubuntu-only. | Add scoped matrix or dedicated non-Linux smoke jobs where practical. | Open |
+
+---
+
+## 3) Detailed Findings
+
+## Paths
+- Fixed: centralized home-token expansion and suspicious token rejection for critical runtime/install path env vars.
+- Fixed: path normalization before filesystem access and before cron payload construction.
+- Open: `soul_guardian.py` still expands only `~`, not `$HOME`/Windows env tokens.
+
+## Shell / Command Dependencies
+- Confirmed extensive POSIX dependencies (`bash`, `curl`, `jq`, `mktemp`, `chmod`, `find`, `unzip`, `openssl`, `shasum/sha256sum`).
+- Fixed minor hardcoded binary path assumptions.
+- Open: no full native PowerShell parity for core shell workflows.
+
+## Permissions / Filesystem Semantics
+- Confirmed many scripts rely on POSIX permission commands.
+- Existing `state.ts` already handles `chmod` failures on unsupported filesystems.
+- Open: documentation still mostly assumes POSIX permissions.
+
+## Line Endings
+- Fixed by adding `.gitattributes` with LF rules for scripts and key text/config files.
+
+## Runtime Dependencies
+- Node scripts generally portable.
+- Python utilities are portable.
+- OpenSSL usage in documentation/workflows remains shell/toolchain dependent.
+
+## CI / Automation
+- Fixed: TS/lint/build matrix now runs on Linux/macOS/Windows.
+- Open: remaining security/shell/python jobs are Linux-only by design.
+
+---
+
+## 4) SKILLS Install Investigation
+
+### Reproduction (pre-fix)
+1. Set install dir with literal token (common quoting mistake):
+   - `export PROMPTSEC_INSTALL_DIR='$HOME/.config/security-checkup'`
+2. Run:
+   - `node skills/openclaw-audit-watchdog/scripts/setup_cron.mjs`
+3. The generated payload command used escaped `$` in `cd` path, resulting in literal token usage at execution time (`cd "\$HOME/..."`), which can resolve under current working directory (for example, `~/.openclaw/workspace/$HOME/...`).
+
+### Root cause analysis
+- POSIX single quotes prevent variable expansion.
+- Node does not auto-expand env vars inside strings.
+- Existing payload escaping converted `$` to literal in shell command text.
+
+### Fix implemented
+- Added explicit path resolution (supports `~`, `$HOME`, `${HOME}`, `%USERPROFILE%`, `$env:USERPROFILE`) and normalization.
+- Added fail-fast validation for unresolved/escaped home tokens.
+- Applied to watchdog cron setup, watchdog suppression config loader, suite hook handler, suite advisory suppression loader, and suite guarded installer.
+- Added tests covering expansion and escaped-token rejection.
+
+### Validation targets
+- `bash` / `zsh`: expanded env values and reject literal escaped home tokens.
+- `sh` (where scripts are invoked through Node entrypoints): same path behavior in Node layer.
+- Windows PowerShell: `%USERPROFILE%` / `$env:USERPROFILE` expansion and path normalization validated in Node tests.
+
+## Source References
+- .gitattributes
+- .github/workflows/ci.yml
+- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
+- skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/suppression.mjs
+- skills/clawsec-suite/scripts/guarded_skill_install.mjs
+- skills/openclaw-audit-watchdog/scripts/setup_cron.mjs
+- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
+- skills/soul-guardian/scripts/soul_guardian.py
+- scripts/release-skill.sh
+- scripts/populate-local-feed.sh
+- scripts/populate-local-skills.sh
+- wiki/remediation-plan.md
+- wiki/platform-verification.md
@@ -0,0 +1,176 @@
+# Migration Plan: Unsigned Feed → Signed Feed
+
+## 1) Objective
+
+Move ClawSec advisory distribution from unsigned `feed.json` delivery to detached-signature verification with minimal disruption.
+
+This plan is written against the current repository behavior:
+- feed is produced by `poll-nvd-cves.yml` and `community-advisory.yml`
+- feed is published by `deploy-pages.yml`
+- suite consumers currently load unsigned JSON from remote/local fallback paths
+
+## 2) Baseline (today)
+
+Current feed paths in active use:
+- Source of truth: `advisories/feed.json`
+- Skill copy: `skills/clawsec-feed/advisories/feed.json`
+- Pages copy: `public/advisories/feed.json`
+- Latest mirror copy: `public/releases/latest/download/advisories/feed.json`
+
+Current consumer defaults:
+- `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`
+- `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
+- default URL: `https://raw.githubusercontent.com/prompt-security/clawsec/main/advisories/feed.json`
+
+## 3) Migration principles
+
+- **Dual-publish first**: publish signatures before enforcing verification.
+- **Fail-open only during transition**: temporary compatibility period is explicit and time-bounded.
+- **Measured rollout**: enforce verification after telemetry confirms stable signed publishing.
+- **Fast rollback**: preserve a path back to unsigned behavior while root cause is investigated.
+
+## 4) Phased timeline
+
+### Phase 0 — Preparation (Week 0)
+
+Deliverables:
+- signing keys generated and fingerprints recorded
+- GitHub secrets created
+- public key(s) added in repo
+- runbooks approved (`security-signing-runbook.md`, this file)
+
+Exit criteria:
+- key fingerprints verified by reviewer
+- protected branch/workflow controls enabled
+
+### Phase 1 — CI signing enabled, no client enforcement (Week 1)
+
+Implement:
+- add feed signing step/workflow to produce `advisories/feed.json.sig`
+- optionally produce `advisories/checksums.json` + `.sig`
+- ensure CI verifies signatures before publishing artifacts
+
+Also update deployment:
+- copy `.sig` artifacts to `public/advisories/`
+- mirror `.sig` in `public/releases/latest/download/advisories/`
+
+Exit criteria:
+- signatures generated successfully for all feed update paths
+- deploy artifacts contain both payload and signature companions
+
+### Phase 2 — Consumer dual-read/dual-verify support (Week 2)
+
+Implement in consumers:
+- read `feed.json` and `feed.json.sig`
+- verify with pinned public key
+- keep controlled temporary unsigned fallback during migration window
+
+Validation:
+- test remote signed path
+- test local signed fallback path
+- test invalid signature rejection
+
+Exit criteria:
+- verification logic released and tested
+- no false-positive verification failures in soak period
+
+### Phase 3 — Enforcement (Week 3)
+
+Actions:
+- disable temporary unsigned fallback behavior in default paths
+- add CI/publish gates that fail when `.sig` is missing
+- announce enforcement date in release notes and docs
+
+Exit criteria:
+- all production clients verify signatures by default
+- no unsigned feed dependency in standard installation flow
+
+### Phase 4 — Stabilization (Week 4)
+
+Actions:
+- run first key rotation tabletop drill
+- run rollback tabletop drill
+- close migration with post-implementation review
+
+## 5) Rollback plan
+
+### Rollback triggers
+
+Initiate rollback if any of the following occur:
+- sustained signature verification failures across clients
+- signing workflow cannot produce valid signatures
+- key compromise suspected but replacement key is not yet deployed
+- deployment path publishes mismatched payload/signature pairs
+
+### Rollback levels
+
+### Level 1 (preferred): Verification bypass window, keep signed publishing
+
+Use when: signing is healthy, client-side verifier has a defect.
+
+Actions:
+1. Re-enable temporary unsigned-acceptance behavior in client release branch.
+2. Ship patch release with explicit expiry date for bypass.
+3. Keep signing pipeline active to avoid authenticity gap.
+
+Recovery target: restore strict verification within 24–48h.
+
+### Level 2: Signed pipeline paused, unsigned feed temporarily authoritative
+
+Use when: signing pipeline is unstable or producing inconsistent artifacts.
+
+Actions:
+1. Disable signing workflow or signing step.
+2. Continue publishing unsigned `advisories/feed.json` via existing workflows.
+3. Revert deploy gates that require `.sig` artifacts.
+4. Open incident record and track time in unsigned mode.
+
+Recovery target: restore signed publishing ASAP, ideally <72h.
+
+### Level 3: Full release freeze
+
+Use when: compromise or integrity of repository/workflows is in doubt.
+
+Actions:
+1. Pause feed mutation and deployment workflows.
+2. Restore known-good commit for advisory files/workflows.
+3. Rotate keys and credentials.
+4. Resume pipeline only after security review sign-off.
+
+### Roll-forward after rollback
+
+- identify root cause
+- add regression tests/gates
+- redeploy signed artifacts
+- publish incident + remediation summary
+
+## 6) Communication plan
+
+For enforcement and rollback events, communicate:
+- what changed
+- expected operator/client action
+- duration of temporary compatibility mode (if any)
+- verification commands for users
+
+Recommended channels:
+- GitHub release notes
+- repository README/docs updates
+- issue/incident report in repository
+
+## 7) Go/No-Go checklist
+
+Go only if all are true:
+- signing workflow success rate is stable
+- signatures are mirrored to all documented feed endpoints
+- consumer verification path tested for remote + local fallback
+- rollback owner is assigned and reachable
+- key rotation procedure has been dry-run at least once
+
+## Source References
+- .github/workflows/poll-nvd-cves.yml
+- .github/workflows/community-advisory.yml
+- .github/workflows/deploy-pages.yml
+- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
+- skills/clawsec-suite/scripts/guarded_skill_install.mjs
+- advisories/feed.json
+- wiki/security-signing-runbook.md
@@ -18,7 +18,7 @@
 | `.github/workflows/` | CI/CD pipelines | CI, releases, NVD polling, community advisory ingestion, pages deploy. |
 | `utils/` | Python utilities | Skill validation and checksum packaging helpers. |
 | `public/` | Published static assets | Site media, mirrored advisories, and generated skill artifacts. |
-| `docs/` | Operational docs | Signing runbooks, migration plans, compatibility and verification guides. |
+| `wiki/` | Documentation hub | Architecture, operations runbooks, compatibility, and verification guides. |

 ## Entry Points
 | Entry | Type | Purpose |
@@ -84,6 +84,9 @@ npm run build
 - Skill release automation expects version parity between `skill.json` and `SKILL.md` frontmatter.
 - Some scripts are POSIX shell oriented; Windows users should prefer PowerShell equivalents or WSL.

+## Update Notes
+- 2026-02-26: Updated repo layout to point operational documentation at `wiki/` instead of the removed root `docs/` directory.
+
 ## Source References
 - README.md
 - package.json
@@ -0,0 +1,98 @@
+# Platform Verification Checklist
+
+Use this checklist to validate portability and path-handling behavior after changes.
+
+## Linux Verification
+
+1. Run core Node tests:
+   ```bash
+   node skills/clawsec-suite/test/path_resolution.test.mjs
+   node skills/clawsec-suite/test/guarded_install.test.mjs
+   node skills/clawsec-suite/test/advisory_suppression.test.mjs
+   node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
+   ```
+   Expected: all tests pass.
+
+2. Verify no literal `$HOME` path acceptance:
+   ```bash
+   CLAWSEC_LOCAL_FEED='\$HOME/advisories/feed.json' \
+   node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
+   ```
+   Expected: exits non-zero with `Unexpanded home token` error.
+
+3. Verify `$HOME` expansion works:
+   ```bash
+   HOME=/tmp/clawsec-home node skills/clawsec-suite/test/path_resolution.test.mjs
+   ```
+   Expected: `$HOME` expansion tests pass.
+
+## macOS Verification
+
+1. Run the same Node test suite as Linux.
+2. Confirm OpenSSL tooling path assumptions are documented:
+   - If using LibreSSL/OpenSSL variations, ensure checks use tested command forms from docs.
+3. Verify tilde expansion in config path:
+   ```bash
+   OPENCLAW_AUDIT_CONFIG=~/.openclaw/security-audit.json \
+   node skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs --enable-suppressions
+   ```
+   Expected: path resolves correctly (or clear file-not-found error at expanded location).
+
+## Windows Verification (PowerShell)
+
+1. Run Node tests:
+   ```powershell
+   node skills/clawsec-suite/test/path_resolution.test.mjs
+   node skills/clawsec-suite/test/guarded_install.test.mjs
+   node skills/clawsec-suite/test/advisory_suppression.test.mjs
+   ```
+   Expected: all pass.
+
+2. Verify PowerShell env path expansion behavior:
+   ```powershell
+   $env:CLAWSEC_LOCAL_FEED = '$env:USERPROFILE\advisories\feed.json'
+   node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
+   ```
+   Expected: path token is expanded/normalized or fails with a clear error if target files are missing.
+
+3. Verify escaped literal token rejection:
+   ```powershell
+   $env:CLAWSEC_LOCAL_FEED = '\$HOME\advisories\feed.json'
+   node skills/clawsec-suite/scripts/guarded_skill_install.mjs --skill test-skill --dry-run
+   ```
+   Expected: `Unexpanded home token` error; no directory creation with literal `$HOME`.
+
+## Line Endings Sanity
+
+1. Confirm LF policy is present:
+   ```bash
+   test -f .gitattributes && grep -n "eol=lf" .gitattributes
+   ```
+   Expected: script/config file patterns enforce LF.
+
+2. After a CRLF-prone checkout, verify scripts still parse:
+   ```bash
+   bash -n scripts/populate-local-feed.sh
+   bash -n scripts/populate-local-skills.sh
+   ```
+   Expected: no `^M` shebang/parse errors.
+
+## Explicit Bug Check: No Literal `$HOME` Directory Creation
+
+1. Configure a path with a literal/escaped token.
+2. Run setup/install command.
+3. Verify command fails early with token error.
+4. Confirm no `$HOME` segment directory was created under working directories.
+
+Expected outcome: **no directories containing literal `$HOME` are created by supported setup scripts.**
+
+## Source References
+- .gitattributes
+- scripts/populate-local-feed.sh
+- scripts/populate-local-skills.sh
+- skills/clawsec-suite/test/path_resolution.test.mjs
+- skills/clawsec-suite/test/guarded_install.test.mjs
+- skills/clawsec-suite/test/advisory_suppression.test.mjs
+- skills/clawsec-suite/scripts/guarded_skill_install.mjs
+- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
+- skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
@@ -0,0 +1,85 @@
+# Cross-Platform Remediation Plan
+
+## Phase 1: Immediate Risk Closure (Completed)
+
+### Milestones
+- Implement explicit home-path expansion + suspicious token rejection in high-risk runtime/install paths.
+- Add regression tests for path expansion and escaped-token rejection.
+- Add `.gitattributes` LF policy.
+- Expand Node lint/type/build CI coverage to Linux/macOS/Windows.
+- Update install docs with shell-specific guidance and literal `$HOME` troubleshooting.
+
+### Outcomes
+- Literal `$HOME` path propagation bug addressed at source.
+- Core advisory/install path config now fails fast on invalid path tokens.
+
+---
+
+## Phase 2: Windows Parity for Critical Workflows (Next)
+
+### Quick wins
+- Add PowerShell equivalents for the most-used manual install/check commands in:
+  - `skills/clawsec-suite/SKILL.md`
+  - `skills/openclaw-audit-watchdog/SKILL.md`
+  - `README.md`
+- Add a lightweight `scripts/preflight.mjs` to detect missing tools and print OS-specific install hints.
+
+### Milestones
+- Native PowerShell instructions for suite setup and advisory hook.
+- WSL/Git Bash fallback documented where shell scripts are unavoidable.
+
+---
+
+## Phase 3: Reduce POSIX Shell Surface (Deeper Refactor)
+
+### Refactor targets
+- `scripts/populate-local-feed.sh`
+- `scripts/populate-local-skills.sh`
+- `scripts/release-skill.sh`
+
+### Approach
+- Re-implement critical paths in Node/Python to remove dependency on `jq/sed/awk/find/chmod` pipelines.
+- Preserve shell wrappers for backward compatibility; route to new cross-platform implementations.
+
+### Migration notes
+- Keep old script entrypoints as wrappers for at least one minor release.
+- Emit deprecation warnings with exact migration commands.
+
+---
+
+## Phase 4: CI Hardening and Ongoing Verification
+
+### Milestones
+- Keep Node matrix (Linux/macOS/Windows) as required check.
+- Add targeted Windows smoke tests for install path handling.
+- Add macOS check for OpenSSL command compatibility notes where relevant.
+
+### Test strategy
+- Local:
+  - Run Node test suites that cover path expansion/suppression/install behavior.
+  - Run syntax checks for modified scripts.
+- CI:
+  - Matrix Node checks + guarded installer/suppression/path tests.
+  - Linux-only security scans remain, but explicitly marked as Linux-scoped.
+
+---
+
+## Rollout / Release Considerations
+
+- No breaking interface changes introduced in this patch set; behavior is stricter only for invalid/unexpanded path tokens.
+- Communicate in release notes:
+  - path token validation now enforced
+  - how to correct invalid quoted env values
+  - where PowerShell examples live
+
+## Source References
+- .gitattributes
+- .github/workflows/ci.yml
+- scripts/populate-local-feed.sh
+- scripts/populate-local-skills.sh
+- scripts/release-skill.sh
+- skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
+- skills/clawsec-suite/scripts/guarded_skill_install.mjs
+- skills/openclaw-audit-watchdog/scripts/load_suppression_config.mjs
+- wiki/platform-verification.md
+- wiki/compatibility-report.md
@@ -0,0 +1,228 @@
+# ClawSec Signing Operations Runbook
+
+## 1) Purpose
+
+This runbook defines operational procedures for introducing and running cryptographic signing in the ClawSec repository.
+
+It covers:
+- key generation
+- GitHub secret management
+- signing workflow integration
+- key rotation and revocation
+- incident response
+
+## 2) Current branch reality (important)
+
+As of branch `integration/signing-work`, advisory distribution is **unsigned**:
+
+- Feed writers:
+  - `.github/workflows/poll-nvd-cves.yml` writes `advisories/feed.json` and `skills/clawsec-feed/advisories/feed.json`
+  - `.github/workflows/community-advisory.yml` writes the same files
+- Feed publish path:
+  - `.github/workflows/deploy-pages.yml` copies to `public/advisories/feed.json`
+  - also mirrors to `public/releases/latest/download/advisories/feed.json`
+- Feed consumers:
+  - `skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts`
+  - `skills/clawsec-suite/scripts/guarded_skill_install.mjs`
+  - both default to `https://clawsec.prompt.security/advisories/feed.json`
+
+This document defines the **target operating model** for signed artifacts while preserving compatibility during migration.
+
+## 3) Target signed artifacts
+
+### Advisory feed channel
+- `advisories/feed.json` (payload)
+- `advisories/feed.json.sig` (detached Ed25519 signature; base64)
+- `advisories/feed-signing-public.pem` (pinned public key)
+
+### Release artifact channel (recommended)
+- `<release>/checksums.json`
+- `<release>/checksums.sig`
+- `advisories/release-signing-public.pem` (or equivalent repo-pinned location)
+
+## 4) Key roles and custody
+
+- **Security owner**: approves key lifecycle changes and incident actions.
+- **Platform owner**: maintains workflows and GitHub secrets.
+- **Reviewer**: validates fingerprints in PRs/releases.
+
+Policy:
+- private keys are never committed
+- public keys are committed and code-reviewed
+- key generation occurs on trusted operator workstation or HSM-backed environment
+
+## 5) Key generation (Ed25519)
+
+> Run from a secure workstation. Do not run on shared CI runners.
+
+```bash
+# Feed signing keypair
+openssl genpkey -algorithm Ed25519 -out feed-signing-private.pem
+openssl pkey -in feed-signing-private.pem -pubout -out feed-signing-public.pem
+
+# Release checksums signing keypair (optional separate key)
+openssl genpkey -algorithm Ed25519 -out release-signing-private.pem
+openssl pkey -in release-signing-private.pem -pubout -out release-signing-public.pem
+```
+
+Generate fingerprints (store in ticket/change record):
+
+```bash
+openssl pkey -pubin -in feed-signing-public.pem -outform DER | shasum -a 256
+openssl pkey -pubin -in release-signing-public.pem -outform DER | shasum -a 256
+```
+
+Optional test-sign before publishing:
+
+```bash
+echo '{"probe":"ok"}' > /tmp/probe.json
+openssl pkeyutl -sign -rawin -inkey feed-signing-private.pem -in /tmp/probe.json -out /tmp/probe.sig.bin
+openssl base64 -A -in /tmp/probe.sig.bin -out /tmp/probe.sig
+openssl base64 -d -A -in /tmp/probe.sig -out /tmp/probe.sig.bin
+openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/probe.json -sigfile /tmp/probe.sig.bin
+```
+
+## 6) GitHub secrets setup
+
+### Required secrets
+
+- `CLAWSEC_SIGNING_PRIVATE_KEY` — PEM-encoded Ed25519 private key (used for both feed and release signing)
+- `CLAWSEC_SIGNING_PRIVATE_KEY_PASSPHRASE` — (optional) passphrase if the private key is encrypted
+
+### Procedure
+
+1. Go to **Repo Settings → Secrets and variables → Actions → New repository secret**.
+2. Paste full PEM including header/footer.
+3. Prefer GitHub **Environment secrets** (with required reviewers) for workflow scoping when possible.
+4. Record change ticket with:
+   - secret name
+   - creator
+   - creation time
+   - key fingerprint
+
+### Recommended environment protections
+
+- Require manual approval for workflows that can use signing secrets.
+- Restrict who can edit protected workflows.
+- Enable branch protection for `main` and require review for workflow changes.
+
+## 7) Workflow integration points
+
+This repo already has feed mutation and deployment workflows. Signing should be inserted as a post-mutation, pre-publish control.
+
+### Feed pipeline
+
+Current feed mutation points:
+- `.github/workflows/poll-nvd-cves.yml`
+- `.github/workflows/community-advisory.yml`
+
+Target addition:
+- add signing step/workflow that:
+  1. regenerates deterministic feed checksums manifest (optional but recommended)
+  2. signs `advisories/feed.json` into `advisories/feed.json.sig`
+  3. verifies signature in CI before commit/publish
+
+### Pages pipeline
+
+Current publisher:
+- `.github/workflows/deploy-pages.yml`
+
+Target update:
+- copy `.sig` files to `public/advisories/` and `public/releases/latest/download/advisories/`
+- fail deploy if expected signed companions are missing after migration enforcement date
+
+### Skill release pipeline (recommended hardening)
+
+Current release generator:
+- `.github/workflows/skill-release.yml` creates `checksums.json`
+
+Target update:
+- sign `checksums.json` before `softprops/action-gh-release`
+- attach `checksums.sig` to each release
+
+## 8) Rotation policy and runbook
+
+### Rotation cadence
+- Routine: every 90 days (or stricter org policy).
+- Immediate: on suspected exposure, unauthorized workflow change, or unexplained signature mismatch.
+
+### Routine rotation steps
+
+1. Generate new keypair(s).
+2. Open PR that updates public key file(s) and fingerprints documentation.
+3. Add new private key(s) as GitHub secret(s).
+4. Merge workflow changes that use new key(s).
+5. Re-sign latest feed/release manifests.
+6. Validate verification in CI and in one external client.
+7. Remove old private key secret(s).
+8. Keep old public key reference only as long as required for historical verification.
+
+### Revocation steps
+
+1. Disable workflows using compromised key.
+2. Remove compromised GitHub secret(s).
+3. Commit revocation note and new public key.
+4. Re-sign latest artifacts with replacement key.
+5. Publish incident advisory with timestamp and impacted window.
+
+## 9) Incident response playbook (signing-specific)
+
+### Triggers
+- signature verification fails for newly published feed/release
+- unknown commits/workflow edits touching signing paths
+- leaked key material, accidental logging, or suspicious secret access
+
+### Severity guide
+- **SEV-1**: key exfiltration confirmed or maliciously signed payload published
+- **SEV-2**: verification failures with unknown cause
+- **SEV-3**: procedural non-compliance, no active compromise
+
+### Response phases
+
+1. **Containment**
+   - pause signing/publish workflows
+   - block further feed merges if authenticity is uncertain
+2. **Investigation**
+   - review workflow run logs
+   - review commits affecting `.github/workflows/`, `advisories/`, and key files
+   - determine first-bad timestamp and affected artifacts
+3. **Eradication**
+   - rotate/revoke compromised key(s)
+   - restore trusted artifacts from known-good commit
+4. **Recovery**
+   - re-sign artifacts
+   - redeploy pages/releases
+   - verify via independent client check
+5. **Post-incident**
+   - publish timeline and remediation summary
+   - tighten controls (review gates, protected environments, secret scope)
+
+## 10) Audit evidence checklist
+
+For each release cycle or feed-signing run, retain:
+- workflow run URL and commit SHA
+- signer key fingerprint in use
+- verification result logs
+- operator/reviewer approvals
+- any exception or bypass rationale
+
+## 11) Minimum acceptance criteria before enforcement
+
+Before requiring signatures in all clients:
+- signed artifacts are produced consistently for at least 2 weeks
+- deploy pipeline mirrors signature companions
+- one rollback drill and one key rotation drill completed successfully
+- incident response on-call owner identified and documented
+
+## Source References
+- advisories/feed.json
+- advisories/feed.json.sig
+- advisories/feed-signing-public.pem
+- clawsec-signing-public.pem
+- .github/actions/sign-and-verify/action.yml
+- .github/workflows/poll-nvd-cves.yml
+- .github/workflows/community-advisory.yml
+- .github/workflows/deploy-pages.yml
+- .github/workflows/skill-release.yml
+- scripts/ci/verify_signing_key_consistency.sh
+- wiki/migration-signed-feed.md
@@ -29,8 +29,8 @@
 - Release docs include manual verification commands for downstream consumers.

 ## Incident and Rotation Playbooks
- `docs/SECURITY-SIGNING.md` defines key generation, custody, rotation, and incident phases.
- `docs/MIGRATION-SIGNED-FEED.md` defines staged enforcement and rollback levels.
+- `wiki/security-signing-runbook.md` defines key generation, custody, rotation, and incident phases.
+- `wiki/migration-signed-feed.md` defines staged enforcement and rollback levels.
 - Rollback paths prioritize preserving signed publishing where possible and time-boxing any bypass.

 ## Example Snippets
@@ -56,10 +56,13 @@ openssl pkey -pubin -in clawsec-signing-public.pem -outform DER | shasum -a 256
 - Add explicit tests for workflow-level signature failure scenarios.
 - Increase runtime telemetry for advisory fetch/verification failures to simplify incident triage.

+## Update Notes
+- 2026-02-26: Repointed signing and migration references from root `docs/` files to dedicated `wiki/` operations pages.
+
 ## Source References
 - SECURITY.md
- docs/SECURITY-SIGNING.md
- docs/MIGRATION-SIGNED-FEED.md
+- wiki/security-signing-runbook.md
+- wiki/migration-signed-feed.md
 - scripts/ci/verify_signing_key_consistency.sh
 - .github/actions/sign-and-verify/action.yml
 - .github/workflows/poll-nvd-cves.yml
@@ -57,6 +57,9 @@ node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
 3. For feed/signing changes, run suite verification tests first (`feed_verification`, `guarded_install`).
 4. For workflow or release changes, also run `scripts/validate-release-links.sh` and key consistency script.

+## Update Notes
+- 2026-02-26: Updated source references to the migrated `wiki/platform-verification.md` checklist.
+
 ## Source References
 - AGENTS.md
 - scripts/prepare-to-push.sh
@@ -70,4 +73,4 @@ node skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
 - skills/clawsec-suite/test/path_resolution.test.mjs
 - skills/openclaw-audit-watchdog/test/suppression_config.test.mjs
 - skills/clawsec-clawhub-checker/test/reputation_check.test.mjs
- docs/PLATFORM_VERIFICATION.md
+- wiki/platform-verification.md