docs: record OpenClaw plugin investigations

What:
- document the QMD/mcporter packaging decision for maintainers
- capture the native OpenClaw plugin gap and proposed nix-openclaw fix

Why:
- preserve the Discord investigation so the feature work can resume later
- distinguish PR #81's bundled manifest fix from external native plugin support

Tests:
- git diff --check: pass
- nix build .#checks.aarch64-darwin.package-contents --no-link: pass

Co-authored-by: Codex <noreply@openai.com>

docs/plugins-maintainers.md

@@ -7,6 +7,22 @@ Purpose: extend OpenClaw capabilities without bloating core; ship tools + skills
 - **Not:** new transports/providers; model plumbing; secrets baked in; inline scripts or ad-hoc package-manager installs; a place for random config outside its scope.
 - Why not skills-only: skills without binaries can hallucinate capability. Plugins ground skills in real tools and deliver versioned, reproducible functionality.
 
+## Native OpenClaw Plugin Gap
+
+OpenClaw also has native runtime plugins: a plugin directory with `openclaw.plugin.json` plus a JS/TS entry loaded by the gateway. Channel plugins such as `openclaw-weixin` live in this layer.
+
+Current nix-openclaw `customPlugins` only implements the Nix-native capability bundle contract: package binaries on the gateway PATH, materialize skills, create state dirs, validate env files, and render optional tool settings. It does not yet tell OpenClaw to load a native plugin directory or enable the matching `plugins.entries.<id>` entry.
+
+PR #81 (`fix: copy plugin manifests into dist/extensions`) was related but not the missing external-plugin feature. It fixed bundled upstream plugin manifests missing from the packaged gateway `dist/extensions/*/openclaw.plugin.json` tree. Current packaging already copies those manifests and checks them in `openclaw-package-contents`.
+
+The next feature slice should bridge the existing Nix contract to OpenClaw native plugins:
+
+- Extend `openclawPlugin` with an optional native plugin declaration, for example `nativePlugins = [ { id = "openclaw-weixin"; path = "${pkg}/lib/openclaw/plugins/openclaw-weixin"; enable = true; } ];`.
+- For each enabled instance, append those paths to generated `plugins.load.paths`.
+- Add default `plugins.entries.<id>.enabled = true`, with user config still able to override it.
+- Keep native plugin config in `programs.openclaw.config` / `instances.<name>.config` so upstream schema validation remains the source of truth.
+- Add a fixture shaped like `openclaw-weixin` so `customPlugins = [{ source = ...; }]` proves both package/skill wiring and native plugin load wiring.
+
 ## Interface Contract (reference implementation: nix-openclaw)
 Every plugin artifact exposes the same fields (flake output `openclawPlugin` today, but the shape is host-agnostic):
 

maintainers/packaging.md

@@ -29,3 +29,12 @@ This repo ships a working Nix package for OpenClaw users, not just a pin mirror.
 - Keep runtime tools internal to the `openclaw` wrapper unless they are intentionally part of the public package surface.
 - QMD is the Nix-supported batteries-included local memory backend. Keep `qmd` internal to the `openclaw` wrapper PATH; users opt in with upstream config.
 - Keep files under 400 lines unless a maintainer explicitly accepts the larger file.
+
+## Investigations
+
+### mcporter and QMD
+
+- `mcporter` is an OpenClaw-owned optional MCP/CLI bridge, not a QMD requirement.
+- OpenClaw defaults to direct `qmd` CLI execution. Keep that as the Nix-supported baseline until measured startup or per-query overhead proves otherwise.
+- Package `mcporter` in `nix-openclaw-tools` as an optional tool when needed, but do not add it to the default `openclaw` runtime PATH just because QMD is bundled.
+- If `memory.qmd.mcporter.enabled = true`, nix-openclaw should make `mcporter` visible to that instance and require the matching mcporter server config for `qmd mcp`.