docs: refresh README, contributing guide, and wiki accuracy (#81)

* docs(repo): refresh docs and wiki alignment

* fix(feed): align frontend advisory URL with canonical endpoint

AGENTS.md

@@ -5,6 +5,8 @@ ClawSec combines a Vite + React frontend with security skill packages and releas
 - Frontend entrypoints: `index.tsx`, `App.tsx`
 - UI and routes: `components/`, `pages/`
 - Shared types/constants: `types.ts`, `constants.ts`
+- Wiki source docs: `wiki/` (synced to GitHub Wiki by `.github/workflows/wiki-sync.yml`)
+- Generated wiki exports: `public/wiki/` (`llms.txt` outputs; generated locally/CI and gitignored)
 - Skills: `skills/<skill-name>/` (`skill.json`, `SKILL.md`, optional `scripts/`, `test/`)
 - Advisory feed: `advisories/feed.json`, `advisories/feed.json.sig`
 - Automation: `scripts/`, `.github/workflows/`
@@ -15,7 +17,9 @@ ClawSec combines a Vite + React frontend with security skill packages and releas
 - `npm run dev`: run local Vite server.
 - `npm run build`: create production build (CI gate).
 - `npm run preview`: preview built app.
+- `npm run gen:wiki-llms`: generate wiki `llms.txt` exports from `wiki/` into `public/wiki/`.
 - `./scripts/prepare-to-push.sh [--fix]`: run lint, types, build, and security checks.
+- `./scripts/populate-local-wiki.sh`: regenerate local wiki `llms.txt` exports for preview.
 - `npx eslint . --ext .ts,.tsx,.js,.jsx,.mjs --max-warnings 0`: lint JS/TS.
 - `npx tsc --noEmit`: type-check TypeScript.
 - `node skills/clawsec-suite/test/feed_verification.test.mjs`: run a skill-local Node test.
@@ -31,6 +35,7 @@ ClawSec combines a Vite + React frontend with security skill packages and releas
 There is no root `npm test`; tests are mostly skill-local.
 - Run changed tests directly: `node skills/<skill>/test/<name>.test.mjs`.
 - For frontend/config changes, run ESLint, `npx tsc --noEmit`, and `npm run build`.
+- For wiki rendering/export changes, run `npm run gen:wiki-llms` and `npm run build`.
 - For Python utility updates, run `ruff check utils/` and `bandit -r utils/ -ll`.
 
 ## Pull Request Guidelines
@@ -39,6 +44,7 @@ There is no root `npm test`; tests are mostly skill-local.
 - Keep PRs focused and include summary, security benefit, and testing performed.
 - Keep versions aligned between `skills/<skill>/skill.json` and `skills/<skill>/SKILL.md`.
 - Do not push release tags from PR branches; releases are tagged from `main`.
+- Do not commit generated `public/wiki/` artifacts; edit `wiki/` source files instead.
 
 ## Agent Collaboration & Git Safety
 - Delete unused or obsolete files only when your changes make them irrelevant; revert files only when the change is yours or explicitly requested. If a git operation creates uncertainty about another agent’s in-flight work, stop and coordinate instead of deleting.

CONTRIBUTING.md

@@ -654,7 +654,7 @@ Wait for a verified patched version.
 
 Once your advisory is published:
 
-1. **Agents receive it** - The feed is served from raw GitHub, so agents see it on their next feed check
+1. **Agents receive it** - The feed is served at `https://clawsec.prompt.security/advisories/feed.json` (with signature/checksum artifacts), so agents see it on their next feed check
 2. **You're credited** - Your issue is linked in the advisory
 3. **Community is protected** - Agents using ClawSec Feed will be alerted
 

README.md

@@ -6,7 +6,7 @@
 
 <div align="center">
 
-## Secure Your OpenClaw Bots with a Complete Security Skill Suite
+## Secure Your OpenClaw and NanoClaw Agents with a Complete Security Skill Suite
 
 <h4>Brought to you by <a href="https://prompt.security">Prompt Security</a>, the Platform for AI Security</h4>
 
@@ -37,7 +37,7 @@ ClawSec is a **complete security skill suite for AI agent platforms**. It provid
 
 ### Supported Platforms
 
-- **OpenClaw** (Moltbot, Clawdbot, and clones) - Full suite with skill installer, file integrity protection, and security audits
+- **OpenClaw** (MoltBot, Clawdbot, and clones) - Full suite with skill installer, file integrity protection, and security audits
 - **NanoClaw** - Containerized WhatsApp bot security with MCP tools for advisory monitoring, signature verification, and file integrity
 
 ### Core Capabilities
@@ -74,21 +74,25 @@ Direct link: [soul-guardian-demo.mp4](public/video/soul-guardian-demo.mp4)
 ### For AI Agents
 
 ```bash
-# Fetch and install the ClawSec security suite
+# Install the ClawSec security suite
-curl -sL https://clawsec.prompt.security/releases/latest/download/SKILL.md
+npx clawhub@latest install clawsec-suite
 ```
 
-The skill file contains deployment instructions. Your agent will:
+After install, the suite can:
-1. Detect its agent family (OpenClaw/MoltBot/ClawdBot or other)
+1. Discover installable protections from the published skills catalog
-2. Install appropriate skills from the catalog
+2. Verify release integrity using signed checksums
-3. Verify integrity using checksums
+3. Set up advisory monitoring and hook-based protection flows
-4. Set up cron update checks
+4. Add optional scheduled checks
+
+Manual/source-first option:
+
+> Read https://github.com/prompt-security/clawsec/releases/latest/download/SKILL.md and follow the installation instructions.
 
 ### For Humans
 
 Copy this instruction to your AI agent:
 
-> Read https://clawsec.prompt.security/releases/latest/download/SKILL.md and follow the instructions to install the protection skill suite.
+> Install ClawSec with `npx clawhub@latest install clawsec-suite`, then complete the setup steps from the generated instructions.
 
 ### Shell and OS Notes
 
@@ -160,13 +164,13 @@ The **clawsec-suite** is a skill-of-skills manager that installs, verifies, and
 | Skill | Description | Installation | Compatibility |
 |-------|-------------|--------------|---------------|
 | 📡 **clawsec-feed** | Security advisory feed monitoring with live CVE updates | ✅ Included by default | All agents |
-| 🔭 **openclaw-audit-watchdog** | Automated daily audits with email reporting | ⚙️ Optional (install separately) | OpenClaw/MoltBot/ClawdBot |
+| 🔭 **openclaw-audit-watchdog** | Automated daily audits with email reporting | ⚙️ Optional (install separately) | OpenClaw/MoltBot/Clawdbot |
 | 👻 **soul-guardian** | Drift detection and file integrity guard with auto-restore | ⚙️ Optional | All agents |
 | 🤝 **clawtributor** | Community incident reporting | ❌ Optional (Explicit request) | All agents |
 
 > ⚠️ **clawtributor** is not installed by default as it may share anonymized incident data. Install only on explicit user request.
 
-> ⚠️ **openclaw-audit-watchdog** is tailored for the OpenClaw/MoltBot/ClawdBot agent family. Other agents receive the universal skill set.
+> ⚠️ **openclaw-audit-watchdog** is tailored for the OpenClaw/MoltBot/Clawdbot agent family. Other agents receive the universal skill set.
 
 ### Suite Features
 
@@ -188,6 +192,9 @@ ClawSec maintains a continuously updated security advisory feed, automatically p
 curl -s https://clawsec.prompt.security/advisories/feed.json | jq '.advisories[] | select(.severity == "critical" or .severity == "high")'
 ```
 
+Canonical endpoint: `https://clawsec.prompt.security/advisories/feed.json`  
+Compatibility mirror (legacy): `https://clawsec.prompt.security/releases/latest/download/feed.json`
+
 ### Monitored Keywords
 
 The feed polls CVEs related to:
@@ -233,7 +240,7 @@ The feed polls CVEs related to:
 ```
 
 **Platform values:**
-- `"openclaw"` - OpenClaw/ClawdBot/MoltBot only
+- `"openclaw"` - OpenClaw/Clawdbot/MoltBot only
 - `"nanoclaw"` - NanoClaw only
 - `["openclaw", "nanoclaw"]` - Both platforms
 - (empty/missing) - All platforms (backward compatible)
@@ -248,10 +255,13 @@ ClawSec uses automated pipelines for continuous security updates and skill distr
 
 | Workflow | Trigger | Description |
 |----------|---------|-------------|
+| **ci.yml** | PRs to `main`, pushes to `main` | Lint/type/build + skill test suites |
+| **pages-verify.yml** | PRs to `main` | Verifies Pages build and signing outputs without publishing |
 | **poll-nvd-cves.yml** | Daily cron (06:00 UTC) | Polls NVD for new CVEs, updates feed |
 | **community-advisory.yml** | Issue labeled `advisory-approved` | Processes community reports into advisories |
-| **skill-release.yml** | `<skill>-v*.*.*` tags | Packages individual skills with checksums to GitHub Releases |
+| **skill-release.yml** | Skill tags + metadata PR changes | Validates version parity in PRs and publishes signed skill releases on tags |
-| **deploy-pages.yml** | Push to main | Builds and deploys the web interface to GitHub Pages |
+| **deploy-pages.yml** | `workflow_run` after successful trusted CI/release or manual dispatch | Builds and deploys the web interface to GitHub Pages |
+| **wiki-sync.yml** | Pushes to `main` touching `wiki/**` | Syncs `wiki/` to the GitHub Wiki mirror |
 
 ### Skill Release Pipeline
 
@@ -262,7 +272,7 @@ When a skill is tagged (e.g., `soul-guardian-v1.0.0`), the pipeline:
 3. **Generates Checksums** - Creates `checksums.json` with SHA256 hashes for all SBOM files
 4. **Signs + verifies** - Signs `checksums.json` and validates the generated `signing-public.pem` fingerprint against canonical repo key material
 5. **Releases** - Publishes to GitHub Releases with all artifacts
-6. **Supersedes Old Releases** - Marks older versions (same major) as pre-releases
+6. **Supersedes Old Releases** - Deletes older versions within the same major line (tags remain)
 7. **Triggers Pages Update** - Refreshes the skills catalog on the website
 
 ### Signing Key Consistency Guardrails
@@ -378,8 +388,15 @@ npm run dev
 
 # Generate wiki llms exports from wiki/ (for local preview)
 ./scripts/populate-local-wiki.sh
+
+# Direct generator entrypoint (used by predev/prebuild)
+npm run gen:wiki-llms
 ```
 
+Notes:
+- `npm run dev` and `npm run build` automatically regenerate wiki `llms.txt` exports (`predev`/`prebuild` hooks).
+- `public/wiki/` is generated output (local + CI) and is intentionally gitignored.
+
 ### Build
 
 ```bash
@@ -395,7 +412,9 @@ npm run build
 │   └── feed.json              # Main advisory feed (auto-updated from NVD)
 ├── components/                 # React components
 ├── pages/                      # Page components
+├── wiki/                       # Source-of-truth docs (synced to GitHub Wiki)
 ├── scripts/
+│   ├── generate-wiki-llms.mjs # wiki/*.md -> public/wiki/**/llms.txt
 │   ├── populate-local-feed.sh # Local CVE feed populator
 │   ├── populate-local-skills.sh # Local skills catalog populator
 │   ├── populate-local-wiki.sh # Local wiki llms export populator
@@ -403,17 +422,24 @@ npm run build
 ├── skills/
 │   ├── clawsec-suite/       # 📦 Suite installer (skill-of-skills)
 │   ├── clawsec-feed/        # 📡 Advisory feed skill
+│   ├── clawsec-nanoclaw/    # 📱 NanoClaw platform security suite
+│   ├── clawsec-clawhub-checker/ # 🧪 ClawHub reputation checks
 │   ├── clawtributor/           # 🤝 Community reporting skill
 │   ├── openclaw-audit-watchdog/ # 🔭 Automated audit skill
+│   ├── prompt-agent/          # 🧠 Prompt-focused protection workflows
 │   └── soul-guardian/         # 👻 File integrity skill
 ├── utils/
 │   ├── package_skill.py       # Skill packager utility
 │   └── validate_skill.py      # Skill validator utility
 ├── .github/workflows/
+│   ├── ci.yml                 # Cross-platform lint/type/build + tests
+│   ├── pages-verify.yml       # PR-only pages build verification
 │   ├── poll-nvd-cves.yml      # CVE polling pipeline
+│   ├── community-advisory.yml # Approved issue -> advisory PR
 │   ├── skill-release.yml      # Skill release pipeline
+│   ├── wiki-sync.yml          # Sync repo wiki/ to GitHub Wiki
 │   └── deploy-pages.yml       # Pages deployment
-└── public/                     # Static assets and published skills
+└── public/                     # Static assets + generated publish artifacts
 ```
 
 ---
@@ -445,6 +471,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#submitting-security-advisories) for detail
 
 For all wiki content, edit files under `wiki/` in this repository. The GitHub Wiki (`<repo>.wiki.git`) is synced from `wiki/` by `.github/workflows/wiki-sync.yml` when `wiki/**` changes on `main`.
 
+LLM exports are generated from `wiki/` into `public/wiki/`:
+- `/wiki/llms.txt` is the LLM-ready export for `wiki/INDEX.md` (or a generated fallback index if `INDEX.md` is missing).
+- `/wiki/<page>/llms.txt` is the LLM-ready export for that single wiki page.
+
 ---
 
 ## 📄 License

constants.ts

@@ -1,7 +1,9 @@
 
-// Feed URL for fetching live advisories
+// Canonical hosted feed endpoint for fetching live advisories
-export const ADVISORY_FEED_URL = 'https://clawsec.prompt.security/releases/latest/download/feed.json';
+export const ADVISORY_FEED_URL = 'https://clawsec.prompt.security/advisories/feed.json';
+
+// Compatibility mirror for legacy clients; keep as last-resort fallback only
+export const LEGACY_ADVISORY_FEED_URL = 'https://clawsec.prompt.security/releases/latest/download/feed.json';
 
 // Local feed path for development
 export const LOCAL_FEED_PATH = '/advisories/feed.json';
-

pages/AdvisoryDetail.tsx

@@ -3,7 +3,11 @@ import { useParams, Link } from 'react-router-dom';
 import { ArrowLeft, ExternalLink, Shield, AlertTriangle, Github, User, Bot } from 'lucide-react';
 import { Footer } from '../components/Footer';
 import { Advisory, AdvisoryFeed } from '../types';
-import { ADVISORY_FEED_URL, LOCAL_FEED_PATH } from '../constants';
+import {
+  ADVISORY_FEED_URL,
+  LEGACY_ADVISORY_FEED_URL,
+  LOCAL_FEED_PATH,
+} from '../constants';
 
 export const AdvisoryDetail: React.FC = () => {
   const { advisoryId } = useParams<{ advisoryId: string }>();
@@ -16,13 +20,17 @@ export const AdvisoryDetail: React.FC = () => {
       if (!advisoryId) return;
 
       try {
-        // Try local feed first (for development), then fall back to GitHub releases
+        // Try local feed first (dev), then canonical hosted endpoint, then legacy mirror.
         let response = await fetch(LOCAL_FEED_PATH);
 
         if (!response.ok) {
           response = await fetch(ADVISORY_FEED_URL);
         }
 
+        if (!response.ok) {
+          response = await fetch(LEGACY_ADVISORY_FEED_URL);
+        }
+
         if (!response.ok) {
           throw new Error(`Failed to fetch feed: ${response.status}`);
         }

pages/FeedSetup.tsx

@@ -4,7 +4,11 @@ import { Link } from 'react-router-dom';
 import { Footer } from '../components/Footer';
 import { AdvisoryCard } from '../components/AdvisoryCard';
 import { Advisory, AdvisoryFeed } from '../types';
-import { ADVISORY_FEED_URL, LOCAL_FEED_PATH } from '../constants';
+import {
+  ADVISORY_FEED_URL,
+  LEGACY_ADVISORY_FEED_URL,
+  LOCAL_FEED_PATH,
+} from '../constants';
 
 const ITEMS_PER_PAGE = 9;
 
@@ -21,13 +25,17 @@ export const FeedSetup: React.FC = () => {
       setError(null);
 
       try {
-        // Try local feed first (for development), then fall back to GitHub releases
+        // Try local feed first (dev), then canonical hosted endpoint, then legacy mirror.
         let response = await fetch(LOCAL_FEED_PATH);
 
         if (!response.ok) {
           response = await fetch(ADVISORY_FEED_URL);
         }
 
+        if (!response.ok) {
+          response = await fetch(LEGACY_ADVISORY_FEED_URL);
+        }
+
         if (!response.ok) {
           throw new Error(`Failed to fetch feed: ${response.status}`);
         }

wiki/architecture.md

@@ -81,6 +81,7 @@ flowchart TD
   <Route path="/skills/:skillId" element={<SkillDetail />} />
   <Route path="/feed" element={<FeedSetup />} />
   <Route path="/feed/:advisoryId" element={<AdvisoryDetail />} />
+  <Route path="/wiki/*" element={<WikiBrowser />} />
 </Routes>
 ```
 
@@ -102,7 +103,7 @@ const remoteFeed = await loadRemoteFeed(feedUrl, {
 | --- | --- | --- |
 | Vite app (`npm run dev`) | Local frontend server | Interactive web app for feed/skills. |
 | GitHub CI | Multi-OS matrix + dedicated jobs | Lint/type/build/security and test confidence. |
-| Skill release workflow | Tag-driven | Release assets, signed checksums, optional ClawHub publish. |
+| Skill release workflow | Tag-driven publish + PR dry-run checks | Release assets, signed checksums, optional ClawHub publish. |
 | Pages deploy workflow | Triggered by CI/Release success | Static site + mirrored advisories/releases. |
 | Runtime hooks | OpenClaw event hooks / NanoClaw IPC | Advisory alerts, gating decisions, integrity checks. |
 
@@ -117,6 +118,7 @@ const remoteFeed = await loadRemoteFeed(feedUrl, {
 - pages/SkillsCatalog.tsx
 - pages/FeedSetup.tsx
 - pages/AdvisoryDetail.tsx
+- pages/WikiBrowser.tsx
 - skills/clawsec-suite/hooks/clawsec-advisory-guardian/handler.ts
 - skills/clawsec-suite/hooks/clawsec-advisory-guardian/lib/feed.mjs
 - skills/clawsec-suite/scripts/guarded_skill_install.mjs

wiki/data-flow.md

@@ -11,7 +11,7 @@
 2. JSON transform logic normalizes severity/type/affected fields and deduplicates by advisory ID.
 3. Signature/checksum steps generate detached signatures and checksum manifests.
 4. Deploy workflow mirrors signed artifacts under `public/` and `public/releases/latest/download/`.
-5. UI and runtime consumers fetch feed/index files and validate format/signatures before use.
+5. UI consumers validate JSON shape/content; runtime consumers additionally verify signatures/checksums before trusting feed data.
 6. Matchers compare `affected` specifiers to skill names/versions and emit alerts or enforce confirmation.
 
 ## Inputs and Outputs

wiki/dependencies.md

@@ -4,7 +4,7 @@
 | Layer | Primary Dependencies | Why It Exists |
 | --- | --- | --- |
 | Frontend runtime | `react`, `react-dom`, `react-router-dom`, `lucide-react` | UI rendering, routing, iconography. |
-| Markdown rendering | `react-markdown`, `remark-gfm` | Render skill docs/readmes in detail pages. |
+| Markdown rendering | `react-markdown`, `remark-gfm` | Render skill docs/readmes and in-app wiki markdown pages. |
 | Build tooling | `vite`, `@vitejs/plugin-react`, `typescript` | Fast TS/TSX bundling and production builds. |
 | Python utilities | stdlib + `ruff`/`bandit` policy from `pyproject.toml` | Validate/package skills and run static checks. |
 | Shell automation | `bash`, `jq`, `curl`, `openssl`, `sha256sum`/`shasum` | Feed polling, signing, checksum generation, release checks. |
@@ -45,7 +45,7 @@
 | Ruff | `ruff check utils/` | Python style and bug pattern checks. |
 | Bandit | `bandit -r utils/ -ll` | Python security checks. |
 | Trivy | Workflow + optional local run | FS/config vulnerability scans. |
-| Gitleaks | Workflow + optional local run | Secret leak detection. |
+| Gitleaks | `scripts/prepare-to-push.sh` optional local run | Secret leak detection before push. |
 
 ## Example Snippets
 ```json

wiki/migration-signed-feed.md

@@ -1,26 +1,30 @@
-# Migration Plan: Unsigned Feed → Signed Feed
+# Migration Record: Unsigned Feed → Signed Feed (Completed)
 
-## 1) Objective
+## 1) Objective and Status
 
-Move ClawSec advisory distribution from unsigned `feed.json` delivery to detached-signature verification with minimal disruption.
+Document how ClawSec advisory distribution moved from unsigned `feed.json` delivery to detached-signature verification, with compatibility preserved for legacy clients.
 
-This plan is written against the current repository behavior:
+Current status on `main`:
-- feed is produced by `poll-nvd-cves.yml` and `community-advisory.yml`
+- Signed feed publishing is active in advisory workflows and deploy workflow.
-- feed is published by `deploy-pages.yml`
+- Suite and NanoClaw consumers default to signed feed endpoints.
-- suite consumers currently load unsigned JSON from remote/local fallback paths
+- Unsigned behavior exists only as explicit compatibility bypass (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`).
 
-## 2) Baseline (today)
+## 2) Baseline (today, post-migration)
 
 Current feed paths in active use:
 - Source of truth: `advisories/feed.json`
+- Source signature: `advisories/feed.json.sig`
 - Skill copy: `skills/clawsec-feed/advisories/feed.json`
+- Skill copy signature: `skills/clawsec-feed/advisories/feed.json.sig`
 - Pages copy: `public/advisories/feed.json`
-- Latest mirror copy: `public/releases/latest/download/advisories/feed.json`
+- Pages signature: `public/advisories/feed.json.sig`
+- Latest mirror copy: `public/releases/latest/download/advisories/feed.json` (+ `.sig`)
 
 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`
+- `skills/clawsec-nanoclaw/lib/advisories.ts`
+- default URL: `https://clawsec.prompt.security/advisories/feed.json`
 
 ## 3) Migration principles
 
@@ -29,9 +33,9 @@ Current consumer defaults:
 - **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
+## 4) Phased timeline (historical)
 
-### Phase 0 — Preparation (Week 0)
+### Phase 0 — Preparation (Completed)
 
 Deliverables:
 - signing keys generated and fingerprints recorded
@@ -43,7 +47,7 @@ Exit criteria:
 - key fingerprints verified by reviewer
 - protected branch/workflow controls enabled
 
-### Phase 1 — CI signing enabled, no client enforcement (Week 1)
+### Phase 1 — CI signing enabled, no client enforcement (Completed)
 
 Implement:
 - add feed signing step/workflow to produce `advisories/feed.json.sig`
@@ -58,7 +62,7 @@ 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)
+### Phase 2 — Consumer dual-read/dual-verify support (Completed)
 
 Implement in consumers:
 - read `feed.json` and `feed.json.sig`
@@ -74,7 +78,7 @@ Exit criteria:
 - verification logic released and tested
 - no false-positive verification failures in soak period
 
-### Phase 3 — Enforcement (Week 3)
+### Phase 3 — Enforcement (Completed)
 
 Actions:
 - disable temporary unsigned fallback behavior in default paths
@@ -85,7 +89,7 @@ Exit criteria:
 - all production clients verify signatures by default
 - no unsigned feed dependency in standard installation flow
 
-### Phase 4 — Stabilization (Week 4)
+### Phase 4 — Stabilization (Ongoing)
 
 Actions:
 - run first key rotation tabletop drill

wiki/modules/automation-release.md

@@ -8,10 +8,12 @@
 
 ## Key Files
 - `.github/workflows/ci.yml`: lint/type/build/security/test matrix.
+- `.github/workflows/pages-verify.yml`: PR-only Pages build/signing verification (no publish).
 - `.github/workflows/poll-nvd-cves.yml`: daily NVD advisory ingestion.
 - `.github/workflows/community-advisory.yml`: issue-label-driven advisory publishing.
 - `.github/workflows/skill-release.yml`: release validation, packaging, signing, and publishing.
 - `.github/workflows/deploy-pages.yml`: site build + asset mirroring to GitHub Pages.
+- `.github/workflows/wiki-sync.yml`: syncs repository `wiki/` into GitHub Wiki.
 - `.github/actions/sign-and-verify/action.yml`: shared Ed25519 sign/verify composite action.
 - `scripts/prepare-to-push.sh`: local CI-like quality gate.
 - `scripts/release-skill.sh`: manual helper for version bump + tag workflow.
@@ -20,10 +22,12 @@
 | Interface | Trigger | Outcome |
 | --- | --- | --- |
 | CI workflow | Push/PR on `main` | Fails fast on lint/type/build/test/security regressions. |
+| Pages Verify workflow | PR on `main` | Validates Pages build/signing artifacts without production deploy. |
 | NVD poll workflow | Cron + dispatch | Updates advisory feed with deduped, normalized CVEs. |
 | Community advisory workflow | Issue labeled `advisory-approved` | Opens PR adding signed advisory records. |
-| Skill release workflow | Tag `<skill>-v*` | Creates GitHub release assets and signatures. |
+| Skill release workflow | Metadata PR changes + tag `<skill>-v*` | PR dry-run/version checks and tagged release publishing. |
 | Deploy pages workflow | Successful CI/release run | Publishes site + mirrored artifacts to Pages. |
+| Sync wiki workflow | Push `wiki/**` on `main` | Publishes repository wiki content into GitHub Wiki remote. |
 
 ## Inputs and Outputs
 Inputs/outputs are summarized in the table below.
@@ -83,6 +87,8 @@ on:
 - .github/workflows/community-advisory.yml
 - .github/workflows/skill-release.yml
 - .github/workflows/deploy-pages.yml
+- .github/workflows/pages-verify.yml
+- .github/workflows/wiki-sync.yml
 - .github/workflows/codeql.yml
 - .github/workflows/scorecard.yml
 - .github/actions/sign-and-verify/action.yml

wiki/modules/frontend-web.md

@@ -2,6 +2,7 @@
 
 ## Responsibilities
 - Render the ClawSec website for home, skills catalog/detail, and advisory feed/detail experiences.
+- Render repository wiki content from `wiki/` markdown and expose per-page `llms.txt` links.
 - Provide resilient JSON fetch behavior that handles SPA HTML fallback cases.
 - Display install commands, checksums, and advisory metadata in a browser-focused UX.
 
@@ -13,6 +14,7 @@
 - `pages/SkillDetail.tsx`: Loads `skill.json`, checksums, README/SKILL docs with markdown renderer.
 - `pages/FeedSetup.tsx`: Advisory listing UI with pagination.
 - `pages/AdvisoryDetail.tsx`: Advisory deep-dive view and source links.
+- `pages/WikiBrowser.tsx`: In-app wiki renderer with wiki-page and `llms.txt` links.
 - `components/Layout.tsx` + `components/Header.tsx`: Shared shell and nav behavior.
 
 ## Public Interfaces
@@ -22,11 +24,14 @@
   - `/skills/:skillId`
   - `/feed`
   - `/feed/:advisoryId`
+  - `/wiki/*`
 - Static fetch targets:
   - `/skills/index.json`
   - `/skills/<skill>/skill.json`
   - `/skills/<skill>/checksums.json`
   - `/advisories/feed.json`
+  - `/wiki/llms.txt`
+  - `/wiki/<page>/llms.txt`
 - Display contracts:
   - `SkillMetadata`, `SkillJson`, `SkillChecksums`, `AdvisoryFeed`, `Advisory` from `types.ts`.
 
@@ -37,7 +42,7 @@ Inputs/outputs are summarized in the table below.
 | --- | --- | --- | --- |
 | Input | Skills index JSON | `/skills/index.json` | List of published skills and metadata. |
 | Input | Skill payload files | `/skills/<id>/skill.json`, markdown docs, `checksums.json` | Detail-page content and integrity table. |
-| Input | Advisory feed JSON | `/advisories/feed.json` or remote URL fallback | Advisory list/detail content. |
+| Input | Advisory feed JSON | `/advisories/feed.json`, then `https://clawsec.prompt.security/advisories/feed.json` (legacy mirror fallback to `/releases/latest/download/feed.json`) | Advisory list/detail content. |
 | Output | Route-specific UI states | Browser view state | Loading, empty, error, and populated experiences. |
 | Output | Copy-to-clipboard commands | Clipboard API | Install and checksum snippets copied for users. |
 
@@ -46,6 +51,7 @@ Inputs/outputs are summarized in the table below.
   - `vite.config.ts` (port, host, path alias)
   - `index.html` Tailwind config + custom fonts/colors
   - `constants.ts` (`ADVISORY_FEED_URL`, `LOCAL_FEED_PATH`)
+- Wiki markdown source lives in `wiki/`; `scripts/generate-wiki-llms.mjs` generates `public/wiki/**/llms.txt` (via `predev`/`prebuild`).
 - Runtime behavior assumptions:
   - JSON responses may be empty or HTML fallback and must be validated.
   - Advisory list pagination uses `ITEMS_PER_PAGE = 9`.
@@ -66,6 +72,7 @@ if (!raw.trim() || contentType.includes('text/html') || isProbablyHtmlDocument(r
 // Route map defined in App.tsx
 <Route path="/skills/:skillId" element={<SkillDetail />} />
 <Route path="/feed/:advisoryId" element={<AdvisoryDetail />} />
+<Route path="/wiki/*" element={<WikiBrowser />} />
 ```
 
 ## Edge Cases
@@ -89,6 +96,7 @@ if (!raw.trim() || contentType.includes('text/html') || isProbablyHtmlDocument(r
 - pages/SkillDetail.tsx
 - pages/FeedSetup.tsx
 - pages/AdvisoryDetail.tsx
+- pages/WikiBrowser.tsx
 - pages/Checksums.tsx
 - components/Layout.tsx
 - components/Header.tsx
@@ -96,3 +104,4 @@ if (!raw.trim() || contentType.includes('text/html') || isProbablyHtmlDocument(r
 - types.ts
 - vite.config.ts
 - index.html
+- scripts/generate-wiki-llms.mjs

wiki/modules/nanoclaw-integration.md

@@ -76,7 +76,7 @@ if (baseline.mode === 'restore' && autoRestore) {
 | Test Scope | File/Path | Notes |
 | --- | --- | --- |
 | Type contracts | `skills/clawsec-nanoclaw/lib/types.ts` | Defines tool/IPC DB payload contracts. |
-| Operational docs | `docs/SKILL_SIGNING.md`, `docs/INTEGRITY.md` | Describes verification/integrity usage patterns. |
+| Operational docs | `skills/clawsec-nanoclaw/docs/SKILL_SIGNING.md`, `skills/clawsec-nanoclaw/docs/INTEGRITY.md` | Describes verification/integrity usage patterns. |
 | Cross-module behavior | Reuses suite verification patterns | Signature/checksum primitives ported from suite logic. |
 
 ## Source References

wiki/overview.md

@@ -24,11 +24,12 @@
 | Entry | Type | Purpose |
 | --- | --- | --- |
 | `index.tsx` | Frontend bootstrap | Mounts React app into `#root`. |
-| `App.tsx` | Frontend router | Defines route map for home, skills, and feed pages. |
+| `App.tsx` | Frontend router | Defines route map for home, skills, feed, and wiki pages. |
 | `scripts/prepare-to-push.sh` | Dev workflow | Runs lint/type/build/security checks before push. |
 | `scripts/populate-local-feed.sh` | Data bootstrap | Pulls CVEs from NVD and updates local advisory feeds. |
 | `scripts/populate-local-skills.sh` | Data bootstrap | Builds `public/skills/index.json` and per-skill checksums. |
-| `.github/workflows/skill-release.yml` | Release entry | Handles tag-based skill packaging/signing/release. |
+| `scripts/generate-wiki-llms.mjs` | Docs export | Generates `public/wiki/llms.txt` and per-page wiki exports. |
+| `.github/workflows/skill-release.yml` | Release entry | Handles PR version-parity/dry-run checks and tag-based packaging/signing/release. |
 | `.github/workflows/poll-nvd-cves.yml` | Scheduled feed updates | Polls NVD and updates advisories. |
 
 ## Key Artifacts
@@ -37,7 +38,8 @@
 | `advisories/feed.json` | NVD poll + community advisory workflows | Web UI, clawsec-suite hook, installers. |
 | `advisories/feed.json.sig` | Signing workflow steps | Signature verification in suite/nanoclaw tooling. |
 | `public/skills/index.json` | Deploy workflow / local populate script | `pages/SkillsCatalog.tsx` and `pages/SkillDetail.tsx`. |
-| `public/checksums.json` + `public/checksums.sig` | Deploy workflow | Client-side integrity verification flows. |
+| `public/wiki/llms.txt` + `public/wiki/**/llms.txt` | Wiki generator script + build hooks | LLM-ready wiki exports linked from the wiki UI. |
+| `public/checksums.json` + `public/checksums.sig` | Deploy workflow | Published integrity artifacts for operators and runtime clients. |
 | `release-assets/checksums.json` | Skill release workflow | Release consumers verifying zip integrity. |
 | `skills/*/skill.json` | Skill authors | Site catalog generation, validators, and release pipelines. |
 
@@ -68,7 +70,7 @@ npm run build
 - Read `README.md` for product positioning and install paths.
 - Open `App.tsx` and `pages/` to understand user-facing behavior.
 - Open `skills/clawsec-suite/skill.json` to understand the suite contract and embedded components.
-- Review `.github/workflows/ci.yml`, `.github/workflows/skill-release.yml`, and `.github/workflows/deploy-pages.yml` for production behavior.
+- Review `.github/workflows/ci.yml`, `.github/workflows/pages-verify.yml`, `.github/workflows/skill-release.yml`, `.github/workflows/deploy-pages.yml`, and `.github/workflows/wiki-sync.yml` for production behavior.
 
 ## How to Navigate
 - UI behavior is centered in `pages/`; visual wrappers sit in `components/`.
@@ -101,5 +103,7 @@ npm run build
 - scripts/populate-local-skills.sh
 - skills/clawsec-suite/skill.json
 - .github/workflows/ci.yml
+- .github/workflows/pages-verify.yml
 - .github/workflows/skill-release.yml
 - .github/workflows/deploy-pages.yml
+- .github/workflows/wiki-sync.yml

wiki/security-signing-runbook.md

@@ -11,22 +11,26 @@ It covers:
 - key rotation and revocation
 - incident response
 
-## 2) Current branch reality (important)
+## 2) Current operating state (important)
 
-As of branch `integration/signing-work`, advisory distribution is **unsigned**:
+On `main`, advisory and release channels are signed and verified by default:
 
 - Feed writers:
-  - `.github/workflows/poll-nvd-cves.yml` writes `advisories/feed.json` and `skills/clawsec-feed/advisories/feed.json`
+  - `.github/workflows/poll-nvd-cves.yml` updates `advisories/feed.json` and signs `advisories/feed.json.sig`
-  - `.github/workflows/community-advisory.yml` writes the same files
+  - `.github/workflows/community-advisory.yml` does the same for approved issue reports
+  - both sync signed feed artifacts into `skills/clawsec-feed/advisories/`
 - Feed publish path:
-  - `.github/workflows/deploy-pages.yml` copies to `public/advisories/feed.json`
+  - `.github/workflows/deploy-pages.yml` publishes `public/advisories/feed.json` + `.sig`
-  - also mirrors to `public/releases/latest/download/advisories/feed.json`
+  - generates and signs `public/checksums.json` + `public/checksums.sig`
+  - publishes canonical key as `public/signing-public.pem` and `public/advisories/feed-signing-public.pem`
+  - mirrors compatibility artifacts under `public/releases/latest/download/` (including `feed.json`, `feed.json.sig`, `checksums.json`, `checksums.sig`, `signing-public.pem`)
 - 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`
+  - `skills/clawsec-nanoclaw/lib/advisories.ts`
+  - default feed URL is `https://clawsec.prompt.security/advisories/feed.json`
 
-This document defines the **target operating model** for signed artifacts while preserving compatibility during migration.
+Unsigned mode remains an explicit compatibility bypass (`CLAWSEC_ALLOW_UNSIGNED_FEED=1`) and is not the steady-state operating model.
 
 ## 3) Target signed artifacts
 
@@ -35,10 +39,10 @@ This document defines the **target operating model** for signed artifacts while
 - `advisories/feed.json.sig` (detached Ed25519 signature; base64)
 - `advisories/feed-signing-public.pem` (pinned public key)
 
-### Release artifact channel (recommended)
+### Release artifact channel
 - `<release>/checksums.json`
 - `<release>/checksums.sig`
-- `advisories/release-signing-public.pem` (or equivalent repo-pinned location)
+- `<release>/signing-public.pem`
 
 ## 4) Key roles and custody
 
@@ -108,7 +112,7 @@ openssl pkeyutl -verify -rawin -pubin -inkey feed-signing-public.pem -in /tmp/pr
 
 ## 7) Workflow integration points
 
-This repo already has feed mutation and deployment workflows. Signing should be inserted as a post-mutation, pre-publish control.
+This repo enforces signing as a post-mutation, pre-publish control.
 
 ### Feed pipeline
 
@@ -116,29 +120,31 @@ Current feed mutation points:
 - `.github/workflows/poll-nvd-cves.yml`
 - `.github/workflows/community-advisory.yml`
 
-Target addition:
+Current behavior:
-- add signing step/workflow that:
+- workflow step signs `advisories/feed.json` into `advisories/feed.json.sig`
-  1. regenerates deterministic feed checksums manifest (optional but recommended)
+- signing action verifies generated signatures during workflow execution
-  2. signs `advisories/feed.json` into `advisories/feed.json.sig`
+- signed artifacts are committed via PR automation
-  3. verifies signature in CI before commit/publish
 
 ### Pages pipeline
 
 Current publisher:
 - `.github/workflows/deploy-pages.yml`
 
-Target update:
+Current behavior:
-- copy `.sig` files to `public/advisories/` and `public/releases/latest/download/advisories/`
+- copies payload/signature to `public/advisories/`
-- fail deploy if expected signed companions are missing after migration enforcement date
+- generates + signs `public/checksums.json` and `public/checksums.sig`
+- publishes signing key to `public/signing-public.pem` and `public/advisories/feed-signing-public.pem`
+- mirrors advisory + signature/checksum/key companions into `public/releases/latest/download/` compatibility paths
 
 ### Skill release pipeline (recommended hardening)
 
 Current release generator:
-- `.github/workflows/skill-release.yml` creates `checksums.json`
+- `.github/workflows/skill-release.yml`
 
-Target update:
+Current behavior:
-- sign `checksums.json` before `softprops/action-gh-release`
+- creates `checksums.json`, signs it as `checksums.sig`, and verifies signature before publish
-- attach `checksums.sig` to each release
+- includes `signing-public.pem` in release assets
+- validates generated public-key fingerprint against canonical key material
 
 ## 8) Rotation policy and runbook
 
@@ -206,9 +212,9 @@ For each release cycle or feed-signing run, retain:
 - operator/reviewer approvals
 - any exception or bypass rationale
 
-## 11) Minimum acceptance criteria before enforcement
+## 11) Minimum acceptance criteria before stricter policy changes
 
-Before requiring signatures in all clients:
+Before tightening policy further (for example, removing compatibility bypass paths):
 - 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

wiki/security.md

@@ -23,7 +23,8 @@
 | Integrity baseline monitor | `soul-guardian` + NanoClaw integrity monitor | Drift detection, quarantine, restore, auditable history. |
 
 ## Supply-Chain and CI Controls
-- CI runs Trivy, npm audit, gitleaks, CodeQL, and Scorecard workflows.
+- CI runs Trivy, npm audit, CodeQL, and Scorecard workflows.
+- Local pre-push checks can run `gitleaks detect` when `gitleaks` is installed.
 - Release workflows validate SBOM file existence before packaging.
 - Deploy workflow verifies generated signing key fingerprint against canonical key material.
 - Release docs include manual verification commands for downstream consumers.

wiki/testing.md

@@ -13,7 +13,8 @@
 | Skill unit tests | `node skills/<skill>/test/*.test.mjs` | Signature, matching, suppression, installer contracts. |
 | Python quality | `ruff check utils/`, `bandit -r utils/ -ll` | Utility correctness and security patterns. |
 | Shell/script quality | ShellCheck + manual script smoke runs | Script hygiene and command robustness. |
-| CI security scans | Trivy, npm audit, gitleaks, CodeQL, Scorecard | Dependency, config, and supply-chain security posture. |
+| CI security scans | Trivy, npm audit, CodeQL, Scorecard | Dependency, config, and supply-chain security posture. |
+| Local pre-push security scan | optional `gitleaks detect` via `scripts/prepare-to-push.sh` | Secret leak detection before push. |
 
 ## Skill Test Matrix
 | Skill | Test Files | Primary Focus |

wiki/workflow.md

@@ -3,18 +3,22 @@
 ## End-to-End Lifecycle
 - Development starts with local coding + local data population for realistic UI preview.
 - PR CI validates quality/security and skill test suites.
+- PR Pages-verify validates production build/signing behavior without publishing.
 - Tag-driven release workflow packages and signs skill artifacts.
 - Pages deploy workflow mirrors release/advisory artifacts and publishes the static site.
+- Wiki-sync workflow publishes repo `wiki/` docs to GitHub Wiki on `main`.
 - Scheduled workflows continuously enrich advisory feed and supply-chain visibility.
 
 ## Primary Workflow Map
 | Workflow | Trigger | Main Steps |
 | --- | --- | --- |
 | CI | PR/push to `main` | Lint, typecheck, build, Python checks, security scans, skill tests. |
+| Pages Verify | PRs to `main` | Build Pages artifact and validate signing outputs (no publish). |
 | Poll NVD CVEs | Daily cron + manual dispatch | Fetch CVEs, transform/dedupe, update feed, sign artifacts, PR changes. |
 | Process Community Advisory | Issue label `advisory-approved` | Parse issue form, create advisory, sign feed, open PR, comment issue. |
-| Skill Release | Tag `<skill>-v*` | Validate versions, package SBOM files, sign checksums, publish release. |
+| Skill Release | Skill tags + metadata PR changes | PR: version-parity + dry-run checks; tags: package/sign/publish release assets. |
 | Deploy Pages | Successful CI/Release or manual dispatch | Discover releases, mirror assets, sign public advisories/checksums, deploy site. |
+| Sync Wiki | Pushes to `main` touching `wiki/**` + manual dispatch | Sync `wiki/` into `<repo>.wiki.git` and generate `Home.md` from `INDEX.md`. |
 
 ## Local Operator Workflow
 | Step | Command | Outcome |
@@ -22,6 +26,7 @@
 | Install deps | `npm install` | Ready local environment. |
 | Populate local catalog | `./scripts/populate-local-skills.sh` | `public/skills/index.json` and file checksums. |
 | Populate local feed | `./scripts/populate-local-feed.sh --days 120` | Updated local advisory feed copy. |
+| Generate wiki llms exports | `npm run gen:wiki-llms` | Updates `public/wiki/llms.txt` and per-page exports. |
 | Run local gate | `./scripts/prepare-to-push.sh` | CI-like pass/fail signal. |
 | Start dev UI | `npm run dev` | Browser preview at local Vite endpoint. |
 
@@ -64,11 +69,14 @@ on:
 - scripts/prepare-to-push.sh
 - scripts/populate-local-feed.sh
 - scripts/populate-local-skills.sh
+- scripts/generate-wiki-llms.mjs
 - .github/workflows/ci.yml
 - .github/workflows/poll-nvd-cves.yml
 - .github/workflows/community-advisory.yml
 - .github/workflows/skill-release.yml
 - .github/workflows/deploy-pages.yml
+- .github/workflows/pages-verify.yml
+- .github/workflows/wiki-sync.yml
 - .github/workflows/codeql.yml
 - .github/workflows/scorecard.yml
 - .github/actions/sign-and-verify/action.yml