docs: clarify plugin package live proof (#99962)

Summary:
- The branch adds plugin package live-proof guidance to the testing skill and plugin docs, separating npm-pack package validation from official-trust proof and documenting runtime dependency and compiled-entry checks.
- PR surface: Docs +111. Total +111 across 3 files.
- Reproducibility: not applicable. this is a documentation and skill-guidance clarification PR rather than a bug report. I validated the documented claims against current source, adjacent docs, tests, and live PR checks.

Automerge notes:
- No ClawSweeper repair was needed after automerge opt-in.

Validation:
- ClawSweeper review passed for head b56efcffc5.
- Required merge gates passed before the squash merge.

Prepared head SHA: b56efcffc5
Review: https://github.com/openclaw/openclaw/pull/99962#issuecomment-4882084565

Co-authored-by: Mason Huang <masonxhuang@tencent.com>
Approved-by: hxy91819

.agents/skills/openclaw-testing/SKILL.md

@@ -88,6 +88,36 @@ node scripts/run-vitest.mjs <path-or-filter>
 That keeps the test scoped without giving pnpm a chance to run dependency
 status checks or install reconciliation in a linked worktree.
 
+## Plugin Package And Live Proof
+
+When validating an external or official plugin package, prove the package shape
+and trust shape separately. Do not use raw archive/path installs to prove the
+managed dependency path, and do not treat `npm-pack:` as proof of catalog-linked
+official trust.
+
+- For local release-candidate proof, pack the plugin and install it with
+  `openclaw plugins install npm-pack:<path.tgz> --force`. This uses the managed
+  per-plugin npm project and is the closest local substitute for the registry
+  artifact's dependency behavior.
+- If the behavior depends on bundled-plugin or trusted official plugin status,
+  add a second proof through a catalog-backed official install or a published
+  package path that records official trust. Local `npm-pack:` proof alone is
+  not sufficient for privileged helpers or trusted-official scope handling.
+- Treat missing runtime imports as package-manifest bugs first. Runtime code
+  must depend on packages declared in the plugin package `dependencies` or
+  `optionalDependencies`; do not make a final proof depend on manually running
+  `npm install` inside `~/.openclaw/npm/projects/...`.
+- If the plugin ships `npm-shrinkwrap.json`, regenerate or check it after
+  moving dependencies between dev and runtime sections.
+- Inspect the packed tarball when dependency ownership or generated `dist/`
+  matters: verify `package/package.json`, the expected runtime files, and any
+  package-local shrinkwrap before installing it on a live host.
+- After installing the package, restart the Gateway when the touched surface is
+  plugin registration, runtime dependency loading, privileged helpers, provider
+  routing, or generated dist.
+- For live provider or channel probes, add only temporary config needed for the
+  proof, then remove it and verify the cleanup state before closeout.
+
 ## Command Semantics
 
 - `pnpm check` and `pnpm check:changed` do not run Vitest tests. They are for

docs/plugins/building-plugins.md

@@ -63,6 +63,12 @@ local proof.
   "name": "@myorg/openclaw-my-plugin",
   "version": "1.0.0",
   "type": "module",
+  "dependencies": {
+    "typebox": "1.1.39"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.24-beta.2"
+  },
   "openclaw": {
     "extensions": ["./index.ts"],
     "compat": {
@@ -169,6 +175,39 @@ local proof.
 
   </Step>
 
+  <Step title="Test the package install">
+    Before publishing a package-ready plugin, test the same install shape users
+    will get. First add a build step, point runtime entries such as
+    `openclaw.extensions` at built JavaScript like `./dist/index.js`, and make
+    sure `npm pack` includes that `dist/` output. TypeScript source entries are
+    only for source checkouts and local development paths.
+
+    Then pack the plugin and install the tarball with `npm-pack:`:
+
+    ```bash
+    npm pack --pack-destination /tmp
+    openclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --force
+    openclaw plugins inspect my-plugin --runtime --json
+    ```
+
+    `npm-pack:` uses OpenClaw's managed per-plugin npm project, so it catches
+    runtime dependency mistakes that source checkout testing can hide. It proves
+    the package and dependency shape, not catalog-linked official trust.
+    Runtime imports must be in `dependencies` or `optionalDependencies`;
+    dependencies left only in `devDependencies` will not be installed for the
+    managed runtime project.
+
+    Do not use a raw archive/path install as the final proof for official or
+    privileged plugin behavior. Raw sources are useful for local debugging, but
+    they do not prove the same dependency path as npm or ClawHub installs. If
+    your plugin relies on trusted official plugin status, add a second proof
+    through a catalog-backed official install or a published package path that
+    records official trust. See
+    [Plugin dependency resolution](/plugins/dependency-resolution) for
+    install-root and dependency ownership details.
+
+  </Step>
+
   <Step title="Publish">
     Validate the package before publishing:
 

docs/plugins/dependency-resolution.md

@@ -54,6 +54,26 @@ trusting the plugin.
 This is intended for package-acceptance and release-candidate proof where a
 local pack artifact should behave like the registry artifact it simulates.
 
+Use `npm-pack:` when testing official or external plugin packages before
+publish. A raw archive or path install is useful for local debugging, but it
+does not prove the same dependency path as an installed npm or ClawHub package.
+`npm-pack:` proves the managed package install shape; it is not, by itself,
+proof that the plugin is catalog-linked official content.
+
+When behavior depends on bundled-plugin or trusted official plugin status, pair
+the local package proof with a catalog-backed official install or a published
+package path that records official trust. Privileged helper access and
+trusted-official scope handling should be validated on that trusted install
+path, not inferred from a local tarball install.
+
+If a plugin fails at runtime with a missing import, fix the package manifest
+instead of repairing the managed project by hand. Runtime imports belong in the
+plugin package `dependencies` or `optionalDependencies`; `devDependencies` are
+not installed for managed runtime projects. A local `npm install` inside
+`~/.openclaw/npm/projects/<encoded-package>` can unblock a temporary diagnostic,
+but it is not package-acceptance proof because the next install or update will
+recreate the project from package metadata.
+
 npm may hoist transitive dependencies to the per-plugin project's
 `node_modules` beside the plugin package. OpenClaw scans the managed project
 root before trusting the install and removes that project during uninstall, so
@@ -76,6 +96,28 @@ policy, and writes `extensions/<id>/npm-shrinkwrap.json` for each
 OpenClaw does not require it for community packages, but npm will respect it
 when present.
 
+Before treating a local package as release-candidate proof, inspect the tarball
+that will be installed:
+
+```bash
+npm pack --pack-destination /tmp
+tar -xOf /tmp/<plugin-package>.tgz package/package.json
+tar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'
+```
+
+For dependency changes, also verify a production install can resolve the
+runtime packages without dev dependencies:
+
+```bash
+tmpdir=$(mktemp -d)
+(
+  cd "$tmpdir"
+  npm init -y >/dev/null
+  npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/<plugin-package>.tgz
+)
+rm -rf "$tmpdir"
+```
+
 OpenClaw-owned npm plugin packages can also publish with explicit
 `bundledDependencies`. The npm publish path overlays the runtime dependency
 name list, removes dev-only workspace metadata from the published package