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

Author: davida-ps

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
-curl -sL https://clawsec.prompt.security/releases/latest/download/SKILL.md
+# Install the ClawSec security suite
+npx clawhub@latest install clawsec-suite
 ```
 
-The skill file contains deployment instructions. Your agent will:
-1. Detect its agent family (OpenClaw/MoltBot/ClawdBot or other)
-2. Install appropriate skills from the catalog
-3. Verify integrity using checksums
-4. Set up cron update checks
+After install, the suite can:
+1. Discover installable protections from the published skills catalog
+2. Verify release integrity using signed checksums
+3. Set up advisory monitoring and hook-based protection flows
+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 |
-| **deploy-pages.yml** | Push to main | Builds and deploys the web interface to GitHub Pages |
+| **skill-release.yml** | Skill tags + metadata PR changes | Validates version parity in PRs and publishes signed skill releases on tags |
+| **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,25 +412,34 @@ 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
 │   └── release-skill.sh       # Manual skill release helper
 ├── 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
-export const ADVISORY_FEED_URL = 'https://clawsec.prompt.security/releases/latest/download/feed.json';
+// Canonical hosted feed endpoint for fetching live advisories
+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