From 8575a70b81b94c96d35f4633920af42f5f907d12 Mon Sep 17 00:00:00 2001
From: Juber Shaikh <40266375+CodeWithJuber@users.noreply.github.com>
Date: Fri, 4 Sep 2026 03:44:03 +0200
Subject: [PATCH] docs: add honest OpenClaw bundle integration

---
 README.md             | 14 ++++++++++++++
 docs/COMPATIBILITY.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/README.md b/README.md
index 7b67adf..66f4de9 100644
--- a/README.md
+++ b/README.md
@@ -195,6 +195,20 @@ If the install summary asks you to activate the plugin, run `/reload-plugins`. T
 
 The root [`kimi.plugin.json`](kimi.plugin.json) points to `./skills/` and supplies routing guidance through `skillInstructions`. Add the repository as a Kimi plugin, or package the repository for the relevant catalog flow.
 
+### OpenClaw
+
+OpenClaw can install this repository as a Codex-compatible bundle; no separate native plugin is required for the portable skills:
+
+```bash
+openclaw plugins install git:github.com/CodeWithJuber/hikmah-stack --accept-capabilities
+openclaw plugins inspect hikmah-stack
+openclaw gateway restart
+```
+
+The bundle exposes the six directories under `skills/` as normal OpenClaw skills. Verify them after restart with `openclaw skills list` or `openclaw skills check`.
+
+This integration is skills-only at runtime. OpenClaw detects the Codex hook declaration, but `hooks/codex.json` is not an OpenClaw `HOOK.md` plus `handler.ts`/`handler.js` hook pack, so OpenClaw does not execute it. The Rust kernel also remains a separate local CLI/library; installing the bundle does not register kernel tools, an MCP server, or a model provider.
+
 ### Other skill-aware hosts
 
 Reuse the required directories under `skills/`. Keep host-specific adapters thin and review executable hooks before enabling them.
diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md
index 28a1d67..b32d4a4 100644
--- a/docs/COMPATIBILITY.md
+++ b/docs/COMPATIBILITY.md
@@ -20,6 +20,34 @@ The repository keeps a Claude Code manifest, marketplace metadata, a read-only o
 
 Kimi plugins bundle a root `kimi.plugin.json` manifest with a `skills/` directory. Hikmah Stack keeps the manifest at the repository root pointing at `./skills/`, so no repackaging or path rewriting is needed: the repo-level `docs/`, `playbooks/`, and `lenses/` paths referenced inside skills resolve in place. The manifest's `skillInstructions` tell the host when to route to each of the six skills.
 
+## OpenClaw
+
+OpenClaw supports compatible plugin bundles from several ecosystems and detects this repository through its existing `.codex-plugin/plugin.json` marker. Installing that bundle loads the manifest's `./skills/` root through OpenClaw's normal skill loader, preserving the same Codex, Claude Code, and Kimi manifests rather than introducing a competing native manifest.
+
+```bash
+openclaw plugins install git:github.com/CodeWithJuber/hikmah-stack --accept-capabilities
+openclaw plugins inspect hikmah-stack
+openclaw gateway restart
+openclaw skills check
+```
+
+Review third-party source before accepting capabilities. A local packaging smoke test with OpenClaw 2026.8.2 identified the repository as `Format: bundle`, `Bundle format: codex`, and discovered all six skills as eligible.
+
+The supported boundary is deliberately narrow:
+
+- the portable `skills/` content is loaded;
+- `hooks/codex.json` is detected as a declared bundle capability but is not executed because it is not an OpenClaw hook pack (`HOOK.md` plus `handler.ts` or `handler.js`);
+- Claude `hooks/hooks.json` remains detect-only in OpenClaw;
+- the Rust kernel is not automatically built, started, or exposed as tools;
+- no native OpenClaw plugin, MCP server, model provider, or autonomous runtime is claimed.
+
+Do not enable or translate either existing hook merely to make it run under another host. A future OpenClaw hook should be added only with an explicit event contract, tests, and an honest security review.
+
+Current references:
+- https://docs.openclaw.ai/plugins/bundles
+- https://docs.openclaw.ai/cli/plugins
+- https://docs.openclaw.ai/tools/skills
+
 ## Other agents
 
 MCP's official documentation describes Agent Skills as portable instruction sets and documents manual installation for multiple agents. For a skills-only package such as Hikmah Stack, copying the required skill directories is often enough. If future capabilities require tools or external systems, an MCP server can provide a standardized integration layer.