Fix OpenClaw plugin registration and compat

Author: G9Pedro

README.md

@@ -267,23 +267,27 @@ clawvault setup --theme neural --canvas --bases
 
 ## OpenClaw Integration
 
-For hook-based lifecycle integration with OpenClaw:
+For native plugin-based lifecycle integration with OpenClaw:
 
 ```bash
-# Install and enable hook pack
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
+# Install ClawVault and allow the plugin
+npm install -g clawvault
+openclaw config set plugins.allow '["clawvault"]'
+openclaw config set plugins.slots.memory clawvault
+
+# Configure the plugin
+openclaw config set plugins.entries.clawvault.config.vaultPath ~/memory
+openclaw config set plugins.entries.clawvault.config.allowClawvaultExec true
 
 # Verify
-openclaw hooks list --verbose
-openclaw hooks check
+openclaw doctor
 clawvault compat
 ```
 
-The hook automatically:
-- Detects context death and injects recovery alerts
-- Auto-checkpoints before session resets
-- Provides `--profile auto` for context queries
+The plugin can automatically:
+- Detect context death and inject recovery alerts
+- Auto-checkpoint before session resets
+- Provide structured memory tools and lifecycle-driven recall
 
 ### MEMORY.md vs Vault
 
@@ -351,27 +355,29 @@ clawvault compat
 
 ## OpenClaw Setup (Canonical)
 
-If you want hook-based lifecycle integration, use this sequence:
+If you want native OpenClaw plugin integration, use this sequence:
 
 ```bash
 # Install CLI
 npm install -g clawvault
 
-# Install and enable hook pack
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
+# Enable the native plugin slot
+openclaw config set plugins.allow '["clawvault"]'
+openclaw config set plugins.slots.memory clawvault
+
+# Configure the plugin
+openclaw config set plugins.entries.clawvault.config.vaultPath ~/memory
+openclaw config set plugins.entries.clawvault.config.allowClawvaultExec true
 
 # Verify
-openclaw hooks list --verbose
-openclaw hooks info clawvault
-openclaw hooks check
+openclaw doctor
 clawvault compat
 ```
 
 Important:
 
-- `clawhub install clawvault` installs skill guidance, but does not replace hook-pack installation.
-- After enabling hooks, restart the OpenClaw gateway process so hook registration reloads.
+- `clawhub install clawvault` installs skill guidance, but does not replace native plugin configuration.
+- Legacy `openclaw hooks install ...` / `openclaw hooks enable ...` flows are compatibility-only guidance for older deployments and should not be your primary install path.
 
 ## Minimal AGENTS.md Additions
 
@@ -489,8 +495,8 @@ vault/
   - `qmd` is optional; in-process BM25 search is available without it
   - if you want fallback compatibility, ensure `qmd --version` works in the same shell
 - Hook/plugin not active in OpenClaw:
-  - run `openclaw hooks install clawvault`
-  - run `openclaw hooks enable clawvault`
+  - run `openclaw config set plugins.allow '["clawvault"]'`
+  - run `openclaw config set plugins.slots.memory clawvault`
   - verify with `openclaw hooks list --verbose`
 - OpenClaw integration drift:
   - run `clawvault compat`

SECURITY.md

@@ -1,6 +1,6 @@
 # Security Model: ClawVault OpenClaw Plugin
 
-This document explains the security posture of the OpenClaw plugin (`hooks/clawvault/handler.js`), why child process execution exists, and how risk is constrained.
+This document explains the security posture of the native OpenClaw plugin (`openclaw.plugin.json` + `dist/openclaw-plugin.js`), why child process execution exists, and how risk is constrained.
 
 ## Threat Model
 
@@ -22,7 +22,7 @@ This document explains the security posture of the OpenClaw plugin (`hooks/clawv
 
 ## Why child process execution is required
 
-The plugin integrates with the existing `clawvault` CLI as the compatibility contract with OpenClaw hooks.  
+The plugin integrates with the existing `clawvault` CLI for selected lifecycle features such as recovery, context injection, checkpointing, and observation workflows.
 `clawvault context` and related commands may invoke `qmd` for retrieval/search. This is required for semantic/BM25 lookup and cannot be replaced by static in-process data access without duplicating core CLI behavior.
 
 Security controls are applied around this execution path instead of removing it:
@@ -33,18 +33,16 @@ Security controls are applied around this execution path instead of removing it:
 
 ## Execution hardening controls
 
-`hooks/clawvault/integrity.js` implements:
-- `resolveExecutablePath(...)`  
-  Resolves an absolute executable path (explicit path or PATH search), rejects non-executable targets.
-- `sanitizeExecArgs(...)`  
-  Enforces array-based argv and rejects null-byte arguments.
-- `verifyExecutableIntegrity(...)`  
-  Optional SHA-256 verification for pinned binary integrity.
+`src/plugin/integrity.ts` implements:
+- `resolveExecutablePath(...)`
+- `sanitizeExecArgs(...)`
+- `verifyExecutableIntegrity(...)`
 
-`hooks/clawvault/handler.js` enforces:
-- `shell: false` for all `execFileSync` calls.
-- No string-concatenated command lines.
-- Execution only when `allowClawvaultExec=true`.
+The native plugin runtime enforces:
+- `shell: false` for child-process execution paths
+- no string-concatenated command lines
+- execution only when `allowClawvaultExec=true`
+- manifest-based configuration validation before runtime load
 
 ## Privileged feature opt-ins
 
@@ -67,18 +65,12 @@ Legacy aliases remain supported for compatibility (`autoCheckpoint`, `observeOnH
 
 The plugin intentionally limits env reads to a documented allowlist:
 
-- `OPENCLAW_STATE_DIR` *(only when `allowEnvAccess=true`)*  
-  Resolve OpenClaw state location for active-session observation.
-- `OPENCLAW_HOME` *(only when `allowEnvAccess=true`)*  
-  Fallback state root for OpenClaw session files.
-- `OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH` *(only when `allowEnvAccess=true`)*  
-  OpenClaw-injected vault path fallback.
-- `CLAWVAULT_PATH` *(only when `allowEnvAccess=true`)*  
-  Operator-provided fallback vault path.
-- `OPENCLAW_AGENT_ID` *(only when `allowEnvAccess=true`)*  
-  Agent resolution fallback when session key is absent.
-- `PATH` / `PATHEXT`  
-  Used only for executable path resolution when `clawvaultBinaryPath` is not pinned.
+- `OPENCLAW_STATE_DIR` *(only when `allowEnvAccess=true`)*
+- `OPENCLAW_HOME` *(only when `allowEnvAccess=true`)*
+- `OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH` *(only when `allowEnvAccess=true`)*
+- `CLAWVAULT_PATH` *(only when `allowEnvAccess=true`)*
+- `OPENCLAW_AGENT_ID` *(only when `allowEnvAccess=true`)*
+- `PATH` / `PATHEXT`
 
 No broad environment enumeration is performed.
 

SKILL.md

@@ -15,14 +15,14 @@ metadata: {"openclaw":{"emoji":"🐘","requires":{"bins":["clawvault","qmd"],"en
 
 An elephant never forgets. Structured memory for OpenClaw agents.
 
-> **Built for [OpenClaw](https://openclaw.ai)**. Canonical install: npm CLI + hook install + hook enable.
+> **Built for [OpenClaw](https://openclaw.ai)**. Canonical install: npm CLI + native plugin enablement via `plugins.allow` and `plugins.slots.memory`.
 
 ## Security & Transparency
 
 **What this skill does:**
 - Reads/writes markdown files in your vault directory (`CLAWVAULT_PATH` or auto-discovered)
 - `repair-session` reads and modifies OpenClaw session transcripts (`~/.openclaw/agents/`) — creates backups before writing
-- Provides an OpenClaw **hook pack** (`hooks/clawvault/handler.js`) with lifecycle events (`gateway:startup`, `gateway:heartbeat`, `command:new`, `session:start`, `compaction:memoryFlush`, `cron.weekly`). Hook is opt-in and must be installed/enabled.
+- Provides a native OpenClaw **memory plugin** via `openclaw.plugin.json` + `dist/openclaw-plugin.js`, plus legacy hook-compatible guidance for older deployments. Native plugin enablement is opt-in.
 - `observe --compress` makes LLM API calls (Gemini Flash by default) to compress session transcripts into observations
 
 **Environment variables used:**
@@ -32,25 +32,25 @@ An elephant never forgets. Structured memory for OpenClaw agents.
 
 **No cloud sync — all data stays local. No network calls except LLM API for observe compression.**
 
-**This is a full CLI tool, not instruction-only.** It writes files, registers hooks, and runs code.
+**This is a full CLI tool, not instruction-only.** It writes files, registers the native OpenClaw memory plugin, and runs code.
 
-**Auditability:** the published ClawHub skill bundle includes `SKILL.md`, `HOOK.md`, and `hooks/clawvault/handler.js` so users can inspect hook behavior before enabling it.
+**Auditability:** the published package ships `openclaw.plugin.json` and `dist/openclaw-plugin.js` so users can inspect plugin metadata and runtime behavior before enabling it.
 
 ## Install (Canonical)
 
 ```bash
 npm install -g clawvault
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
-
-# Verify and reload
-openclaw hooks list --verbose
-openclaw hooks info clawvault
-openclaw hooks check
-# restart gateway process
+openclaw config set plugins.allow '["clawvault"]'
+openclaw config set plugins.slots.memory clawvault
+openclaw config set plugins.entries.clawvault.config.vaultPath ~/my-vault
+openclaw config set plugins.entries.clawvault.config.allowClawvaultExec true
+
+# Verify
+openclaw doctor
+clawvault compat
 ```
 
-`clawhub install clawvault` can install skill guidance, but does not replace explicit hook pack installation.
+`clawhub install clawvault` can install skill guidance, but does not replace explicit native plugin configuration.
 
 ### Recommended Safe Install Flow
 
@@ -62,16 +62,17 @@ npm view clawvault version dist.integrity dist.tarball repository.url
 npm install -g clawvault@latest
 npm install -g github:tobi/qmd
 
-# 3) Install hook pack, but DO NOT enable yet
-openclaw hooks install clawvault
+# 3) Review the shipped native plugin manifest before enabling
+node -e "const fs=require('fs');const p='openclaw.plugin.json';console.log(fs.readFileSync(p,'utf8'))"
 
-# 4) Review hook source locally before enabling
-node -e "const fs=require('fs');const p='hooks/clawvault/handler.js';console.log(fs.existsSync(p)?p:'hook file not found in current directory')"
-openclaw hooks info clawvault
+# 4) Enable the native memory plugin explicitly
+openclaw config set plugins.allow '["clawvault"]'
+openclaw config set plugins.slots.memory clawvault
+openclaw config set plugins.entries.clawvault.config.vaultPath ~/my-vault
 
-# 5) Enable only after review
-openclaw hooks enable clawvault
-openclaw hooks check
+# 5) Verify before working
+openclaw doctor
+clawvault compat
 ```
 
 ## Setup
@@ -104,6 +105,10 @@ clawvault sleep "PR review + type guards" --next "respond to CI" --blocked "wait
 clawvault doctor
 ```
 
+## Legacy Hook Compatibility
+
+If you still operate an older hook-pack-based OpenClaw deployment, treat it as legacy compatibility mode rather than the primary install flow. Prefer the native plugin path above for new installs.
+
 ## Reality Checks Before Use
 
 ```bash
@@ -332,7 +337,7 @@ Backups are created automatically (use `--no-backup` to skip).
 - **Inbox backlog warning** — process or archive inbox items
 - **"unexpected tool_use_id" error** — run `clawvault repair-session`
 - **OpenClaw integration drift** — run `clawvault compat`
-- **Hook enable fails / hook not found** — run `openclaw hooks install clawvault`, then `openclaw hooks enable clawvault`, restart gateway, and verify via `openclaw hooks list --verbose`
+- **Plugin not active** — run `openclaw config set plugins.allow '["clawvault"]'`, `openclaw config set plugins.slots.memory clawvault`, confirm `plugins.entries.clawvault.config.vaultPath`, then verify with `openclaw doctor` and `clawvault compat`
 - **Graph out of date** — run `clawvault graph --refresh`
 - **Wrong context for task** — try `clawvault context --profile incident` or `--profile planning`
 

docs/clawhub-security-release-playbook.md

@@ -1,10 +1,10 @@
 # ClawHub Security Release Playbook
 
-This playbook captures what kept the ClawHub/OpenClaw security review stable for `clawvault` and what repeatedly caused "suspicious" regressions.
+This playbook captures what kept the ClawHub/OpenClaw security review stable for `clawvault` and what repeatedly caused suspicious regressions.
 
 ## Goal
 
-Keep ClawHub scanner classification at least `Benign` by ensuring bundle metadata, SKILL frontmatter, and shipped files stay consistent.
+Keep ClawHub scanner classification at least `Benign` by ensuring bundle metadata, SKILL frontmatter, plugin manifest metadata, and shipped files stay consistent.
 
 ## Known-good frontmatter contract
 
@@ -19,21 +19,19 @@ For `openclaw` and `metadata.openclaw`, use only documented fields:
 
 - `emoji`
 - `requires.bins`
-- `requires.env` (can be `[]` if no required env vars)
-- `install` (installer spec array)
+- `requires.env`
+- `install`
 - `homepage`
 
-Avoid non-spec keys inside `openclaw` metadata (for example ad-hoc fields such as `env_optional`), because strict scanners may treat the metadata block as invalid and fall back to "no requirements/install spec".
-
 ## Bundle composition
 
 Always publish a minimal auditable bundle:
 
 - `SKILL.md`
-- `hooks/clawvault/HOOK.md`
-- `hooks/clawvault/handler.js`
+- `openclaw.plugin.json`
+- `dist/openclaw-plugin.js`
 
-If the hook file is not present in the published bundle, scanners flag a visibility/supply-chain concern.
+If the native manifest or built plugin entrypoint is not present in the published bundle, scanners and operators lose the cheap metadata path that OpenClaw uses for discovery and config validation.
 
 ## Required pre-publish checks
 
@@ -42,7 +40,8 @@ If the hook file is not present in the published bundle, scanners flag a visibil
    - frontmatter metadata (`requires.bins`, `install`)
    - human docs in SKILL (`Install (Canonical)`, safe install flow)
 3. Confirm `source` and `homepage` fields are present and accurate.
-4. Confirm hook paths referenced in SKILL exist in the bundle.
+4. Confirm `package.json#openclaw.plugin` and `package.json#openclaw.extensions` point to files that exist in the bundle.
+5. Run `clawvault compat` against the release workspace to verify package metadata, manifest, and extension alignment.
 
 ## Publish + verify workflow
 
@@ -57,8 +56,6 @@ If the hook file is not present in the published bundle, scanners flag a visibil
 
 ## If scanner regresses
 
-If warning text mentions mismatch between registry metadata and SKILL/docs:
-
 1. Compare scanner claim to frontmatter values first.
 2. Remove unsupported keys from metadata block.
 3. Re-publish patch version with normalized metadata.
@@ -68,8 +65,8 @@ If warning text mentions mismatch between registry metadata and SKILL/docs:
 
 Even with clean metadata, this skill can still receive cautionary language because it:
 
-- runs lifecycle hooks,
+- runs lifecycle-aware memory automation,
 - reads/modifies OpenClaw session files,
 - and relies on external CLI packages (`clawvault`, `qmd`).
 
-That caution is expected and should be addressed with transparent docs, explicit safe-install guidance, and auditable shipped hook code.
+That caution is expected and should be addressed with transparent docs, explicit safe-install guidance, and auditable shipped plugin metadata/runtime code.

docs/getting-started/installation.md

@@ -82,5 +82,5 @@ clawvault doctor
   - This is optional. In-process BM25 search still works.
   - Install qmd only if you need fallback compatibility paths.
 - OpenClaw plugin not registered
-  - Run: `openclaw hooks install clawvault && openclaw hooks enable clawvault`
-  - Verify: `openclaw hooks list --verbose`
+  - Run: `openclaw config set plugins.allow '["clawvault"]' && openclaw config set plugins.slots.memory clawvault`
+  - Verify: `openclaw doctor`

docs/openclaw-plugin-usage.md

@@ -8,8 +8,9 @@ See the [README](../README.md#openclaw-integration) for canonical installation s
 
 ```bash
 npm install -g clawvault
-openclaw hooks install clawvault
-openclaw hooks enable clawvault
+openclaw config set plugins.allow '["clawvault"]'
+openclaw config set plugins.slots.memory clawvault
+openclaw config set plugins.entries.clawvault.config.vaultPath ~/my-vault
 ```
 
 ## MEMORY.md vs Vault: Understanding the Relationship
@@ -161,7 +162,7 @@ openclaw config set plugins.entries.clawvault.config.maxContextResults 6
 openclaw config set plugins.entries.clawvault.config.contextProfile planning
 ```
 
-See [HOOK.md](../hooks/clawvault/HOOK.md) for all configuration options.
+The native plugin manifest is shipped at [openclaw.plugin.json](../openclaw.plugin.json). Use `clawvault compat` to verify the package metadata, manifest, and built extension stay aligned.
 
 ## Workflow Integration
 
@@ -202,12 +203,12 @@ If MEMORY.md and vault conflict, instruct the agent to trust `clawvault wake` ou
 
 ### Context injection not working
 
-1. Verify hook is enabled: `openclaw hooks list --verbose`
-2. Check vault path: `openclaw config get plugins.entries.clawvault`
-3. Run compatibility check: `clawvault compat`
+1. Verify the plugin is allowed and selected: `openclaw config get plugins.allow` and `openclaw config get plugins.slots.memory`
+2. Check plugin config: `openclaw config get plugins.entries.clawvault`
+3. Run `openclaw doctor` and `clawvault compat`
 
 ## Related Documentation
 
 - [README: OpenClaw Integration](../README.md#openclaw-integration)
-- [HOOK.md: Hook Configuration](../hooks/clawvault/HOOK.md)
+- [openclaw.plugin.json: Native Plugin Manifest](../openclaw.plugin.json)
 - [SKILL.md: Skill Documentation](../SKILL.md)