@aporthq/aport-agent-guardrails 1.0.8

package/docs/QUICKSTART_OPENCLAW_PLUGIN.md

@@ -0,0 +1,470 @@
+# QuickStart: OpenClaw Plugin (Deterministic Enforcement)
+
+**5-minute setup for deterministic, platform-level policy enforcement in OpenClaw.**
+
+**One command to get started** (recommended — no clone):
+
+```bash
+npx @aporthq/aport-agent-guardrails
+```
+
+If you already have an agent_id from aport.io (e.g. after creating a passport there), run `npx @aporthq/aport-agent-guardrails <agent_id>` to use a hosted passport and skip the passport prompt. See [Hosted passport setup](HOSTED_PASSPORT_SETUP.md).
+
+This uses the [npm package](https://www.npmjs.com/package/@aporthq/aport-agent-guardrails): it downloads the package (policies + plugin), runs the setup wizard, installs the APort OpenClaw plugin, and runs a smoke test.
+
+Then start OpenClaw with the generated config (e.g. `openclaw gateway start --config ~/.openclaw/config.yaml`). The plugin will enforce policies on every tool call.
+
+**Alternative: clone the repo** (e.g. to hack on the code or use without npm):
+
+```bash
+git clone https://github.com/aporthq/aport-agent-guardrails.git && \
+  cd aport-agent-guardrails && \
+  git submodule update --init --recursive && \
+  ./bin/openclaw
+```
+
+*Already have the repo?* From the repo root run: `./bin/openclaw`
+
+---
+
+## Why Use the Plugin?
+
+| Approach | Deterministic? | Bypass Risk | Security Level |
+|----------|----------------|-------------|----------------|
+| **OpenClaw Plugin** ✅ | Yes | None | 🟢 Secure |
+| AGENTS.md prompts | No | High | 🔴 Not secure |
+
+**Bottom line:** With the plugin, the platform enforces policy before every tool execution. The AI cannot bypass it.
+
+---
+
+## Installation (Automatic)
+
+**Recommended:** Use `npx @aporthq/aport-agent-guardrails` (see top of this doc). If you cloned the repo instead, from the repo root run:
+
+```bash
+./bin/openclaw
+```
+
+The script will:
+1. Ask for your OpenClaw config directory (default `~/.openclaw`)
+2. Create your passport (OAP v1.0) there
+3. Prompt to install the APort OpenClaw plugin
+4. Ask for mode (default: **API**; or local) and generate `config.yaml` with plugin settings (passport path, guardrail script path, apiUrl for API mode)
+5. Install guardrail wrappers in the config dir’s `.skills/` (including `aport-guardrail-bash.sh` used by the plugin in local mode)
+6. **Update your passport** — the installer sets `allowed_commands: ["*"]` automatically so normal exec works with no manual editing. You only need to edit the passport later if you want to restrict commands more tightly.
+7. Run a **self-check** (guardrail invoked the same way OpenClaw will use it); if it’s denied, the script exits with a clear message so you know the setup is incomplete.
+8. Optionally install the APort skill and AGENTS.md rule, and run a smoke test
+9. Verify plugin installation
+
+**That's it!** Start OpenClaw with that config (e.g. `openclaw gateway start --config ~/.openclaw/config.yaml`). The plugin will enforce policies on every tool call; no extra steps required.
+
+---
+
+## Installation (Manual)
+
+If you prefer manual installation:
+
+### 1. Create Passport
+
+```bash
+./bin/aport-create-passport.sh --output ~/.openclaw/aport/passport.json
+```
+
+### 2. Install Plugin
+
+```bash
+openclaw plugins install /path/to/aport-agent-guardrails/extensions/openclaw-aport
+```
+
+### 3. Configure Plugin
+
+Create or edit `~/.openclaw/config.yaml`:
+
+```yaml
+plugins:
+  enabled: true
+  entries:
+    openclaw-aport:
+      enabled: true
+      config:
+        # Mode: "api" (default, recommended) or "local" (guardrail script, no network)
+        mode: api
+
+        # Passport file location
+        passportFile: ~/.openclaw/aport/passport.json
+
+        # For local mode: path to guardrail script
+        guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
+
+        # Fail-closed: block on error (default: true)
+        failClosed: true
+```
+
+For **API mode (default)**, set:
+```yaml
+        mode: api
+        apiUrl: https://api.aport.io
+```
+Set `APORT_API_KEY` in the environment if your API requires auth. Do not put `${APORT_API_KEY}` in the config file (OpenClaw will require the var to exist at load time).
+
+### 4. Install Guardrail Scripts (local mode only)
+
+If you **did not** run `./bin/openclaw`, you need the guardrail script for local mode. If you **did** run the setup script, it already created `CONFIG_DIR/.skills/aport-guardrail-bash.sh`; skip this step.
+
+Otherwise:
+
+```bash
+mkdir -p ~/.openclaw/.skills
+# Create wrapper that points to this repo (replace /path/to with real path)
+cat > ~/.openclaw/.skills/aport-guardrail-bash.sh << 'EOF'
+#!/bin/bash
+APORT_REPO_ROOT="/path/to/aport-agent-guardrails"
+export OPENCLAW_PASSPORT_FILE="${OPENCLAW_PASSPORT_FILE:-$HOME/.openclaw/aport/passport.json}"
+export OPENCLAW_DECISION_FILE="${OPENCLAW_DECISION_FILE:-$HOME/.openclaw/aport/decision.json}"
+exec "$APORT_REPO_ROOT/bin/aport-guardrail-bash.sh" "$@"
+EOF
+chmod +x ~/.openclaw/.skills/aport-guardrail-bash.sh
+```
+
+### 5. Verify Installation
+
+```bash
+# Check plugin is installed
+openclaw plugins list | grep openclaw-aport
+
+# Should show: openclaw-aport (enabled)
+```
+
+---
+
+## How It Works
+
+```
+User → AI: "Delete all log files"
+         ↓
+    OpenClaw: AI wants to use tool "exec.run"
+         ↓
+    Platform: Fires before_tool_call hook
+         ↓
+  APort Plugin: Maps "exec.run" → "system.command.execute.v1"
+         ↓
+  APort Plugin: Calls guardrail script/API
+         ↓
+    Guardrail: Evaluates against passport + limits
+         ↓
+   ┌──────────┴──────────┐
+   │                     │
+ ALLOW                 DENY
+   │                     │
+   ↓                     ↓
+Tool executes      Returns { block: true, blockReason }
+                         ↓
+                   OpenClaw throws error
+                         ↓
+                   Tool NEVER executes
+```
+
+**Key:** The platform enforces policy. The AI cannot skip this check.
+
+---
+
+## Testing
+
+### 1. Start OpenClaw with Plugin
+
+```bash
+openclaw gateway start --config ~/.openclaw/config.yaml
+```
+
+### 2. Test Allowed Action
+
+Try a simple command that should be allowed:
+
+```bash
+# Via OpenClaw agent
+"Run: node --version"
+```
+
+Expected: Command executes (allowed by passport limits)
+
+### 3. Test Denied Action
+
+Try a command that exceeds your passport limits:
+
+```bash
+# Via OpenClaw agent
+"Delete all files in /tmp"
+```
+
+Expected: Tool blocked with message:
+```
+🛡️ APort Policy Denied
+
+Policy: system.command.execute.v1
+Reason: Command exceeds allowed scope
+
+To override, update your passport at: ~/.openclaw/aport/passport.json (or ~/.openclaw/passport.json for legacy)
+```
+
+---
+
+## Modes
+
+**API mode** is still the default and recommended. **Local mode** now has full parity with API for exec mapping (fixed); both evaluate the same policies. Messaging runs at assurance L0 by default.
+
+### API Mode (default, recommended)
+
+**Best for:** Production, full OAP policy (JSON Schema, assurance, evaluation rules), signed decisions, cloud kill switch, audit logs.
+
+```yaml
+config:
+  mode: api
+  passportFile: ~/.openclaw/aport/passport.json
+  apiUrl: https://api.aport.io
+```
+Set `APORT_API_KEY` in the environment only if your API requires auth.
+
+**How it works:**
+- Plugin loads local passport
+- Sends passport + context to APort API
+- API evaluates (passport NOT stored, stateless)
+- Returns signed decision
+- **Network required**
+
+### Local Mode
+
+**Best for:** Privacy, offline use, no network dependency
+
+```yaml
+config:
+  mode: local
+  passportFile: ~/.openclaw/aport/passport.json
+  guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
+```
+
+**How it works:**
+- Plugin calls local bash script
+- Script evaluates policy using local passport (subset of OAP; see [Verification methods](VERIFICATION_METHODS.md))
+- Returns decision (exit 0 = allow, exit 1 = deny)
+- **No network required**
+
+---
+
+## Troubleshooting
+
+### Plugin not loading
+
+```bash
+# Check plugin list
+openclaw plugins list
+
+# Should show: openclaw-aport (enabled)
+```
+
+If not listed:
+1. Verify installation: `openclaw plugins install /path/to/extensions/openclaw-aport`
+2. Check config.yaml has `plugins.entries.openclaw-aport.enabled: true`
+3. Restart OpenClaw gateway
+
+### Tools not being blocked
+
+Check:
+1. **Plugin enabled?** `openclaw plugins list` should show `openclaw-aport (enabled)`
+2. **Tool mapped?** See tool-to-policy mapping in plugin README
+3. **Passport allows it?** The installer sets `allowed_commands: ["*"]` by default. If you intentionally tightened the allowlist, re-add the commands you need to `limits.system.command.execute.allowed_commands` in your passport.
+4. **Script working?** Test directly:
+   ```bash
+   ~/.openclaw/.skills/aport-guardrail-bash.sh system.command.execute '{"command":"ls"}'
+   ```
+
+### Error: "Failed to run guardrail script"
+
+Check:
+1. Script exists: `ls -l ~/.openclaw/.skills/aport-guardrail-bash.sh`
+2. Script executable: `chmod +x ~/.openclaw/.skills/aport-guardrail-bash.sh`
+3. Script works: Run test command above
+
+### Guardrail DENY / `oap.passport_version_mismatch`
+
+If the guardrail denies every call and `~/.openclaw/aport/decision.json` (or `~/.openclaw/decision.json`) shows reason `oap.passport_version_mismatch` ("Passport spec version is 'unknown', expected 'oap/1.0'"):
+
+1. **Passport must have `spec_version: "oap/1.0"`** (OAP spec). If your passport has only `"version": "1.0.0"` in metadata and no top-level `spec_version`, it was created by an older or non–spec-compliant tool.
+2. **Limits must be nested per capability.** The verifier expects e.g. `limits["system.command.execute"]` with `allowed_commands`, `blocked_patterns`, not a flat `limits.allowed_commands` at the top level.
+
+**Fix:** Re-run the installer so it can normalize the passport:
+
+```bash
+npx @aporthq/aport-agent-guardrails
+```
+
+Choose to overwrite the existing passport when prompted, or run the wizard with `--output` to a new file. The installer now ensures `spec_version: "oap/1.0"` and nested limits. If you prefer to fix the file manually, add `"spec_version": "oap/1.0"` at the top level and move any top-level `allowed_commands` / `blocked_patterns` under `limits["system.command.execute"]`. See [agent-passport/spec/oap](https://github.com/aporthq/agent-passport/tree/main/spec/oap) for the canonical schema.
+
+---
+
+## Configuration Reference
+
+### Minimum Configuration (API mode — default)
+
+```yaml
+plugins:
+  enabled: true
+  entries:
+    openclaw-aport:
+      enabled: true
+      config:
+        mode: api
+        passportFile: ~/.openclaw/aport/passport.json
+        apiUrl: https://api.aport.io
+        failClosed: true
+```
+
+### Full Configuration (API mode)
+
+```yaml
+plugins:
+  enabled: true
+  entries:
+    openclaw-aport:
+      enabled: true
+      config:
+        # Mode: "api" (default) or "local"
+        mode: api
+
+        # Passport file location
+        passportFile: ~/.openclaw/aport/passport.json
+
+        # For local mode: path to guardrail script
+        guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
+
+        # For API mode: APort API endpoint
+        apiUrl: https://api.aport.io  # or your self-hosted API URL
+        # Optional: set APORT_API_KEY in the environment if your API requires auth
+
+        # Fail-closed: block on error (default: true)
+        failClosed: true
+```
+
+### Minimum Configuration (Local mode)
+
+```yaml
+plugins:
+  enabled: true
+  entries:
+    openclaw-aport:
+      enabled: true
+      config:
+        mode: local
+        passportFile: ~/.openclaw/aport/passport.json
+        guardrailScript: ~/.openclaw/.skills/aport-guardrail-bash.sh
+        failClosed: true
+```
+
+---
+
+## Tool-to-Policy Mapping
+
+The plugin automatically maps OpenClaw tool names to APort policy packs:
+
+| OpenClaw Tool | APort Policy |
+|---------------|--------------|
+| `git.create_pr`, `git.merge`, `git.push` | `code.repository.merge.v1` |
+| `exec.run`, `system.command.*`, `bash` | `system.command.execute.v1` |
+| `message.send`, `messaging.*` | `messaging.message.send.v1` |
+| `mcp.*` | `mcp.tool.execute.v1` |
+| `session.create` | `agent.session.create.v1` |
+| `tool.register` | `agent.tool.register.v1` |
+| `payment.refund` | `finance.payment.refund.v1` |
+| `payment.charge` | `finance.payment.charge.v1` |
+| `data.export` | `data.export.create.v1` |
+
+Unmapped tools are allowed (fail-open for flexibility).
+
+---
+
+## Security Considerations
+
+### Fail-Closed by Default
+
+By default, `failClosed: true` means **any error blocks the tool**:
+- Script not found → BLOCK
+- API unreachable → BLOCK
+- Invalid passport → BLOCK
+
+This is secure-by-default. To fail-open (not recommended):
+
+```yaml
+config:
+  failClosed: false  # Allow on error (NOT RECOMMENDED)
+```
+
+### Plugin Trust
+
+Plugins run **in-process** with full access to OpenClaw. Only install from trusted sources:
+- Official APort plugin (this)
+- Your own forks/modifications
+
+Use `plugins.allow` allowlist in config.yaml:
+
+```yaml
+plugins:
+  allow:
+    - openclaw-aport
+    - your-other-trusted-plugin
+```
+
+### Bypass Prevention
+
+**With plugin:** AI **cannot** bypass policy enforcement. The platform calls `before_tool_call` before every tool.
+
+**Without plugin (AGENTS.md only):** AI **can** bypass via:
+- Prompt injection
+- Forgetting to call guardrail
+- Deciding action is "safe"
+
+**Bottom line:** Plugin = deterministic. AGENTS.md = best-effort (not secure).
+
+---
+
+## Next Steps
+
+1. **Run the setup (once):** From repo root: `./bin/openclaw`. Use the default config dir or choose a path.
+2. **Choose "yes"** when prompted to install the plugin.
+3. **Start OpenClaw** with the generated config: `openclaw gateway start --config <your-config-dir>/config.yaml` (e.g. `~/.openclaw/config.yaml`).
+4. **Test enforcement:** Run the agent; try an allowed action (e.g. `node --version`) and one that should be blocked by your passport (e.g. `rm -rf /`). The plugin blocks before the tool runs.
+5. **Customize passport:** Edit `<config-dir>/aport/passport.json` (or `<config-dir>/passport.json` for legacy) to adjust limits and allowed commands.
+
+---
+
+## Support
+
+- **Full documentation:** [`extensions/openclaw-aport/README.md`](../extensions/openclaw-aport/README.md)
+- **Issues:** [GitHub Issues](https://github.com/aporthq/aport-agent-guardrails/issues)
+- **Discord:** [discord.gg/aport](https://discord.gg/aport)
+
+---
+
+## Summary
+
+✅ **One command:** Run `./bin/openclaw` from the repo root to create passport, install plugin, write config and wrappers, and verify. You only need this once per config dir.
+✅ **Deterministic enforcement:** The plugin runs before every tool; the platform enforces, the AI cannot bypass.
+✅ **Fail-closed:** Blocks on error by default.
+✅ **API (default) or local:** Full OAP via API, or local script for offline/privacy.
+✅ **Zero OpenClaw core changes:** Uses the existing OpenClaw plugin API.
+
+**After setup, start OpenClaw with the generated config—your agent is then secured by APort policy.**
+
+---
+
+## How it all fits together
+
+| Step | What happens |
+|------|----------------|
+| You run `./bin/openclaw` | Script asks for config dir, creates passport, installs plugin, writes `config.yaml`, installs wrappers in `<config-dir>/.skills/`, and **updates the passport** with default `allowed_commands` (bash, sh, ls, mkdir, npm, etc.) so normal exec works. |
+| `config.yaml` | Contains `passportFile` and `guardrailScript` pointing to `<config-dir>/aport/passport.json` and `<config-dir>/.skills/aport-guardrail-bash.sh`. |
+| Passport allowlist | The installer sets `allowed_commands: ["*"]` automatically. No manual editing needed unless you want to restrict commands. |
+| Wrapper script | `<config-dir>/.skills/aport-guardrail-bash.sh` is a small script that calls this repo’s `bin/aport-guardrail-bash.sh` with the same args and env (passport path, etc.). |
+| You start OpenClaw | `openclaw gateway start --config <config-dir>/config.yaml` (or use that config when running the agent). |
+| On every tool call | OpenClaw runs the plugin’s `before_tool_call` hook → plugin calls the guardrail script with tool name and params → script evaluates against passport and policy → allow = tool runs, deny = plugin returns `block: true` and the tool never runs. |
+
+**So: one run of `./bin/openclaw` is all you need.** No manual editing of config or wrapper paths if you use the default config dir.

package/docs/README.md

@@ -0,0 +1,28 @@
+# APort Agent Guardrails — Documentation
+
+**Public documentation** (for users integrating OpenClaw + APort guardrails):
+
+| Doc | Purpose |
+|-----|---------|
+| [QUICKSTART_OPENCLAW_PLUGIN.md](QUICKSTART_OPENCLAW_PLUGIN.md) | **OpenClaw plugin** — 5-minute setup, deterministic enforcement (RECOMMENDED) |
+| [**HOSTED_PASSPORT_SETUP.md**](HOSTED_PASSPORT_SETUP.md) | **Use passport from aport.io** — create at aport.io, then `npx @aporthq/aport-agent-guardrails <agent_id>` (or choose hosted in wizard) |
+| [QUICKSTART.md](QUICKSTART.md) | Interactive setup and step-by-step with passport wizard |
+| [OPENCLAW_LOCAL_INTEGRATION.md](OPENCLAW_LOCAL_INTEGRATION.md) | Full OpenClaw setup: API, passport, policies, Python example |
+| [OPENCLAW_TOOLS_AND_POLICIES.md](OPENCLAW_TOOLS_AND_POLICIES.md) | exec, allowed_commands, unmapped tools, passport limits |
+| [TOOL_POLICY_MAPPING.md](TOOL_POLICY_MAPPING.md) | How tool names map to policy packs |
+| [IMPLEMENTING_YOUR_OWN_EVALUATOR.md](IMPLEMENTING_YOUR_OWN_EVALUATOR.md) | Build your own evaluator from the OAP spec |
+| [OPENCLAW_COMPATIBILITY.md](OPENCLAW_COMPATIBILITY.md) | OpenClaw version alignment, paths, OPENCLAW_HOME |
+| [AGENTS.md.example](AGENTS.md.example) | Example AGENTS.md section for pre-action authorization |
+| [REPO_LAYOUT.md](REPO_LAYOUT.md) | What `bin/`, `src/`, `extensions/`, `external/` do |
+
+**Launch & checklists** (internal / maintainers):
+
+| Doc | Purpose |
+|-----|---------|
+| [LAUNCH_READINESS_CHECKLIST.md](LAUNCH_READINESS_CHECKLIST.md) | Launch checklist + guardrail execution gate |
+| [launch/LAUNCH_STRATEGY_SUMMARY.md](launch/LAUNCH_STRATEGY_SUMMARY.md) | Timing, content, evidence, pre-flight |
+| [launch/QUICK_LAUNCH_CHECKLIST.md](launch/QUICK_LAUNCH_CHECKLIST.md) | Final verification before each post |
+| [launch/OPENCLAW_FEEDBACK_AND_FIXES.md](launch/OPENCLAW_FEEDBACK_AND_FIXES.md) | OpenClaw feedback summary + two fixes (allowlist, capabilities) |
+| [launch/POST_1_VALENTINE_IMPROVED.md](launch/POST_1_VALENTINE_IMPROVED.md) | Post 1 draft (Valentine) |
+| [launch/POST_2_GUARDRAIL_IMPROVED.md](launch/POST_2_GUARDRAIL_IMPROVED.md) | Post 2 draft (Guardrail) |
+| [ANNOUNCEMENT_GUIDE.md](ANNOUNCEMENT_GUIDE.md) | Announcement messaging and materials |

package/docs/RELEASE.md

@@ -0,0 +1,87 @@
+# Release process and version policy
+
+**Current release:** 1.0.8 (see [CHANGELOG.md](../CHANGELOG.md)).
+
+We keep **one version number** across all published packages (Node core, Python core, and every framework adapter). That avoids “core is 1.2 but CLI is 0.9” and keeps the story simple for users and support.
+
+---
+
+## 1. Version policy summary
+
+| What | Policy |
+|------|--------|
+| **Core packages** | `@aporthq/aport-agent-guardrails` (root/CLI), `@aporthq/aport-agent-guardrails-core`, `aport-agent-guardrails` (Python) always share the same version (e.g. `1.3.0`). |
+| **Framework adapters** | Node: `@aporthq/aport-agent-guardrails-langchain`, `-crewai`, `-cursor` (published). `-n8n` is **not published yet** (coming soon). Python: `aport-agent-guardrails-langchain`, `aport-agent-guardrails-crewai`. They depend on core with `>=` and publish with the same version as core. |
+| **Repo tag** | Git tag `v1.3.0` matches the released version so docs and installs stay aligned. |
+
+So: **one version for the whole suite.** If only the LangChain adapter changed, we still bump core (and all other packages) to the same new version so everything stays in lockstep.
+
+---
+
+## 1.1. Why two npm packages: @aporthq/aport-agent-guardrails vs @aporthq/aport-agent-guardrails-core?
+
+| Package | What it is | Who installs it |
+|---------|------------|------------------|
+| **@aporthq/aport-agent-guardrails** (root) | The **CLI and setup tool**: `bin/agent-guardrails`, framework installers (bash scripts), docs, OpenClaw extension. No TypeScript evaluator — it runs the passport wizard and writes config. | Users who want the one-line setup: `npx @aporthq/aport-agent-guardrails langchain` (or cursor, crewai, openclaw). |
+| **@aporthq/aport-agent-guardrails-core** | The **Node library**: Evaluator, config, passport loading, `verify` / `verifySync`. Used inside your app to enforce policy. | Anyone using the **framework adapters** (e.g. `@aporthq/aport-agent-guardrails-langchain`) — they depend on core. Also apps that want only the evaluator without the CLI. |
+
+So: **root = CLI/setup**; **core = library**. We publish core so that (1) the adapters can declare it as a dependency and npm can resolve it, and (2) users can install just the evaluator if they don’t need the full CLI.
+
+---
+
+## 2. Tooling
+
+- **Changesets** (Node): fixed mode so all workspace packages are in one “fixed” group and get the same version on release.
+- **sync-version script**: after `changeset version`, copies the new version from root `package.json` into all Python `pyproject.toml` and `aport_guardrails/__init__.py`.
+
+---
+
+## 3. Release flow
+
+1. **Merge PRs** → run automated tests (e.g. CI).
+2. **Bump version and changelogs**  
+   ```bash
+   npm run version
+   ```  
+   This runs `changeset version` (updates all Node `package.json` and CHANGELOGs) then `node scripts/sync-version.mjs` (updates Python packages to the same version).
+3. **Commit** the version bump and changelog updates (e.g. “chore(release): 1.3.0”).
+4. **Tag and push** — this triggers the release workflow and publishes both npm and PyPI:
+   ```bash
+   git tag v1.3.0
+   git push origin v1.3.0
+   ```
+5. **CI (`.github/workflows/release.yml`)**: on tag push `v*`:
+   - **publish-npm**: publishes the **root** package `@aporthq/aport-agent-guardrails` (CLI) and workspace packages `@aporthq/aport-agent-guardrails-core`, `-langchain`, `-crewai`, `-cursor` to npm. The **n8n** package is not published yet (coming soon). Uses `NPM_TOKEN` secret.
+   - **publish-python**: builds and publishes `aport-agent-guardrails`, `aport-agent-guardrails-langchain`, and `aport-agent-guardrails-crewai` to PyPI (uses `PYPI_TOKEN` secret). Skips upload if aport-agent-guardrails version already exists.
+   - **create-release**: creates the GitHub Release with install notes for both ecosystems.
+
+   **PyPI**: In [PyPI project settings](https://pypi.org/help/#project-urls), set Repository and (if using trusted publishing) add this repo and workflow name **Release**. Otherwise configure the `PYPI_TOKEN` secret in the GitHub repo.
+
+---
+
+## 4. Adding a changeset (before release)
+
+After making any change that should go into the next release:
+
+```bash
+npx changeset
+# or
+npm run changeset
+```
+
+- Choose **patch** / **minor** / **major**.
+- Write a short summary for the changelog.
+- Commit the new file under `.changeset/`.
+
+When you run `npm run version`, that changeset will drive a single version bump for the whole fixed group; then `sync-version` keeps Python in sync.
+
+---
+
+## 5. Long-term flexibility
+
+If we later need finer control (e.g. enterprise adapters that shouldn’t force a full suite release), we can:
+
+- Move to independent versioning for some adapters, and/or
+- Introduce a “meta” package that pins compatible versions.
+
+For now, a single version across all packages keeps the ecosystem coherent and avoids support confusion.

package/docs/REPO_LAYOUT.md

@@ -0,0 +1,47 @@
+# Repository Layout
+
+Quick reference for what each part of the repo does.
+
+## `bin/`
+
+CLI and guardrail entrypoints used by OpenClaw (or any framework):
+
+| Script | Purpose |
+|--------|---------|
+| **openclaw** | One-command setup: passport wizard, plugin install, config, `.skills` wrappers |
+| **aport-create-passport.sh** | Interactive OAP v1.0 passport wizard (capabilities, limits, L0 default) |
+| **aport-guardrail-bash.sh** | **Local evaluator** — evaluates policy using passport + `external/aport-policies`; no API, no network |
+| **aport-guardrail-api.sh** | Calls APort API (cloud or self-hosted); uses **src/evaluator.js** |
+| **aport-guardrail.sh** | Backward-compat wrapper → runs bash guardrail |
+| **aport-guardrail-v2.sh** | Backward-compat wrapper → runs API guardrail |
+| **aport-status.sh** | Show passport summary and status |
+
+## `src/`
+
+Node.js code for **API-based** evaluation and optional proxy:
+
+| File | Purpose |
+|------|---------|
+| **evaluator.js** | **APort API client** — calls `POST /api/verify/policy/{packId}` with passport (local mode) or `agent_id` (cloud mode). Used by `bin/aport-guardrail-api.sh` and by any programmatic caller (e.g. `require('./src/evaluator')`). Supports `APORT_API_URL`, `APORT_AGENT_ID`, `APORT_API_KEY`. Loads policy packs from `external/aport-policies` and passports from file. |
+| **server/index.js** | **Optional HTTP proxy** — forwards requests to the agent-passport API (e.g. `APORT_API_BASE=https://api.aport.io`). Run with `npm run server` (port 8788). Use when you need a proxy in front of the API; most users call the API directly. |
+
+**Summary:** For **local evaluation with no network**, the repo uses **bin/aport-guardrail-bash.sh** (bash + jq + policies from submodule). For **API evaluation** (cloud or self-hosted agent-passport), it uses **src/evaluator.js** (Node) and **bin/aport-guardrail-api.sh** (which invokes the evaluator).
+
+## `extensions/openclaw-aport/`
+
+OpenClaw plugin — `before_tool_call` hook that invokes the guardrail script or API before every tool execution. Deterministic enforcement; AI cannot bypass.
+
+## `external/`
+
+Git submodules (run `npm run sync-submodules` or `sync-submodules:latest`):
+
+- **aport-spec** — OAP passport/decision schema and spec
+- **aport-policies** — Policy packs (system.command.execute, messaging.message.send, mcp.tool.execute, etc.)
+
+## `local-overrides/`
+
+Local policy and passport templates that override or extend the submodule content (e.g. `system.command.execute.v1` when the policy is not yet in aport-policies).
+
+## `tests/`
+
+OAP v1 test suite: guardrail allow/deny, passport creation, suspend (passport status), four verification methods, API evaluator (when API is up). Run with `make test`.