@openclaw/plugin-inspector 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.2 - 2026-04-27
+
+### Added
+
+- Add public SDK subpath mocks, registrar return profiles, richer lifecycle capture probes, and plugin-root `init`/`--plugin-root` CLI flows.
+
+### Changed
+
+- Harden runtime capture for TypeScript entrypoints, extensionless local imports, mocked external packages, namespace imports, async output capture, and explicit mock/real SDK lanes.
+- Refresh README and CI examples around `npx @openclaw/plugin-inspector check --no-openclaw` and opt-in runtime capture.
+
 ## 0.1.1 - 2026-04-27
 
 ### Changed

package/README.md

@@ -1,36 +1,46 @@
 <img src="docs/plugin-inspector-banner.jpg" alt="openclaw plugin inspector banner"/>
 
-# 💊 OpenClaw Plugin Inspector
+# OpenClaw Plugin Inspector
 
-`plugin-inspector` is the reusable OpenClaw plugin compatibility inspector. It
-wraps the static inspection, registration capture, and report model prototyped
-in crabpot into an npm-publishable package.
+`plugin-inspector` is the offline compatibility check for OpenClaw plugins. Run
+it from a plugin root to inspect package metadata, `openclaw.plugin.json`, SDK
+imports, `api.on(...)`, `api.register*`, and optional runtime registration
+capture.
 
-## Install
+## Quick Start
 
-Install it as a dev dependency in a plugin repo:
+From a plugin package directory:
 
 ```bash
-npm install --save-dev @openclaw/plugin-inspector
+npx @openclaw/plugin-inspector
 ```
 
-Then run it from the plugin root:
+That runs `check`, writes report artifacts to `reports/`, and exits non-zero
+when compatibility breakages are found.
+
+Add a local config and GitHub Actions workflow:
 
 ```bash
-npx @openclaw/plugin-inspector check
+npx @openclaw/plugin-inspector init --ci
 ```
 
-## CLI
+Or install it as a dev dependency:
 
-Run the default plugin-root check from a plugin package directory:
+```bash
+npm install --save-dev @openclaw/plugin-inspector
+npx plugin-inspector check
+```
+
+## Commands
 
 ```bash
-plugin-inspector check
+npx @openclaw/plugin-inspector check
+npx @openclaw/plugin-inspector check --plugin-root ./plugins/weather
+npx @openclaw/plugin-inspector init --ci --package-manager pnpm
 ```
 
-That command reads the current directory as one plugin, inspects package
-metadata, `openclaw.plugin.json`, source imports, `api.on(...)`,
-`api.register*`, and writes:
+`check` reads the current directory as one plugin unless `--plugin-root` is set.
+It writes:
 
 - `reports/plugin-inspector-report.json`
 - `reports/plugin-inspector-report.md`
@@ -43,8 +53,8 @@ checkout:
 plugin-inspector check --no-openclaw
 ```
 
-Use a simple plugin-root config when you want stable fixture metadata or
-expected seams:
+Use `plugin-inspector.config.json` when CI needs stable fixture metadata,
+expected seams, or runtime capture defaults:
 
 ```json
 {
@@ -58,6 +68,9 @@ expected seams:
       "registrations": ["registerTool"]
     }
   },
+  "capture": {
+    "mockSdk": true
+  },
   "openclaw": {
     "defaultCheckoutPath": "../openclaw"
   }
@@ -70,48 +83,51 @@ Then run:
 plugin-inspector check --config plugin-inspector.config.json
 ```
 
-Copy-ready examples live in `examples/plugin-inspector.config.json` and
+`init --ci` writes this shape for you, plus
+`.github/workflows/plugin-inspector.yml`. Copy-ready examples also live in
+`examples/plugin-inspector.config.json` and
 `examples/github-actions-plugin-inspector.yml`.
 
-Fixture-set configs are still supported for crabpot-style compatibility suites:
-
-```bash
-plugin-inspector report --config crabpot.config.json --out reports
-```
+## Runtime Capture
 
-Capture a plugin entrypoint in an explicitly isolated execution lane:
+Runtime capture imports plugin entrypoints in an isolated subprocess and records
+the registrations made during `register(api)`. It is opt-in because it executes
+plugin code:
 
 ```bash
-PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture ./dist/index.js --mock-sdk
+PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector check --runtime --mock-sdk
 ```
 
-Run the optional runtime capture smoke during `check`:
-
-```bash
-PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --no-openclaw --capture
-```
+By default, runtime capture uses a generated mock for `openclaw/plugin-sdk` and
+common external packages so plugin code can load in clean CI without OpenClaw
+installed. Use `--real-sdk` only when the plugin workspace already has real SDK
+dependencies installed and you intentionally want to test that path.
 
-Runtime capture creates a temporary mock `openclaw/plugin-sdk` package, imports
-declared OpenClaw package entrypoints, calls their `register(api)` function with
-the capture API, and writes:
+Runtime capture writes:
 
 - `reports/plugin-inspector-runtime-capture.json`
 - `reports/plugin-inspector-runtime-capture.md`
 
-### CI
+You can also capture one entrypoint directly:
 
-With a dev dependency:
+```bash
+PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture ./dist/index.js --mock-sdk
+```
+
+## CI
+
+Minimal package scripts:
 
 ```json
 {
   "scripts": {
     "plugin:check": "plugin-inspector check --no-openclaw",
-    "plugin:check:runtime": "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --no-openclaw --capture"
+    "plugin:check:runtime": "PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector check --no-openclaw --runtime --mock-sdk"
   }
 }
 ```
 
-GitHub Actions:
+GitHub Actions without a local dev dependency:
 
 ```yaml
 name: plugin-inspector
@@ -131,8 +147,8 @@ jobs:
           node-version: 24
           cache: npm
       - run: npm ci
-      - run: npm run plugin:check
-      - run: npm run plugin:check:runtime
+      - run: npx @openclaw/plugin-inspector check --no-openclaw
+      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector check --no-openclaw --runtime --mock-sdk
       - uses: actions/upload-artifact@v5
         if: always()
         with:
@@ -140,6 +156,31 @@ jobs:
           path: reports/plugin-inspector-*
 ```
 
+## Fixture Suites
+
+Fixture-set configs are still supported for crabpot-style compatibility suites:
+
+```bash
+plugin-inspector report --config crabpot.config.json --out reports
+```
+
+Use fixture suites when one repo wants to inspect many plugins. Use plugin-root
+`check` for normal plugin CI.
+
+## Mocking Model
+
+Default inspection is static, offline, and credential-free. Runtime capture is
+the only mode that imports plugin code.
+
+When `--mock-sdk` is enabled, the inspector generates temporary modules for
+`openclaw/plugin-sdk` subpaths and unresolved external packages discovered in
+the plugin import graph. The mock SDK captures registrations; it does not call
+network services, launch OpenClaw, run provider SDKs, or emulate service
+lifecycle side effects.
+
+Use the mock lane for plugin compatibility CI. Keep live provider/service tests
+in the plugin repo behind their own credentials and explicit opt-in flags.
+
 ## Scope
 
 Default inspection is offline and credential-free. It reads manifests, package
@@ -148,5 +189,5 @@ metadata, and source files, then reports observed `api.on(...)`,
 OpenClaw target checkout parsing is limited to public compatibility registries,
 SDK package exports, manifest types, hooks, and captured registrar metadata.
 
-Cold import capture and synthetic contract probes are explicit opt-in modes.
-Live lanes will stay credential-gated and must never run in default CI.
+Cold import capture, synthetic contract probes, and runtime capture are explicit
+opt-in modes. Live lanes stay credential-gated and must never run in default CI.

package/examples/github-actions-plugin-inspector.yml

@@ -15,8 +15,8 @@ jobs:
           node-version: 24
           cache: npm
       - run: npm ci
-      - run: npm run plugin:check
-      - run: npm run plugin:check:runtime
+      - run: npx @openclaw/plugin-inspector check --no-openclaw
+      - run: PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 npx @openclaw/plugin-inspector check --no-openclaw --runtime --mock-sdk
       - uses: actions/upload-artifact@v5
         if: always()
         with:

package/examples/plugin-inspector.config.json

@@ -9,6 +9,9 @@
       "registrations": ["registerTool"]
     }
   },
+  "capture": {
+    "mockSdk": true
+  },
   "openclaw": {
     "defaultCheckoutPath": "../openclaw"
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/advanced.js

@@ -116,12 +116,21 @@ export {
   defaultPluginRootConfigFiles,
   fixtureCheckoutPath,
   fixtureSourceRoot,
+  inferPluginSeams,
   loadInspectorConfig,
   loadPluginRootConfig,
   normalizeInspectorConfig,
   normalizePluginRootConfig,
+  packageId,
   validateInspectorConfig,
 } from "./config.js";
+export {
+  buildPluginInspectorConfig,
+  defaultInitConfigPath,
+  defaultInitWorkflowPath,
+  renderGithubActionsWorkflow,
+  writePluginInspectorInit,
+} from "./init.js";
 export {
   buildPlatformProbes,
   defaultPlatformTargets,

package/src/api.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { createCaptureApi } from "./capture-api.js";
 import { loadInspectorConfig, loadPluginRootConfig } from "./config.js";
+import { writePluginInspectorInit } from "./init.js";
 import { captureEntrypoint } from "./inspector.js";
 import { renderTextSummary, writeCompatibilityReport } from "./report.js";
 import { buildRuntimeCaptureReport, writeRuntimeCaptureReport } from "./runtime-capture-report.js";
@@ -45,24 +46,25 @@ export async function writePluginReports(report, options = {}) {
 
 export async function runPluginCheck(options = {}) {
   const outDir = options.outDir ?? "reports";
-  const report = await inspectPluginRoot(options);
-  const paths = await writePluginReports(report, { ...options, outDir });
+  const config = await loadPluginConfig(options);
+  const report = await inspectPluginRoot({ ...options, config });
+  const paths = await writePluginReports(report, { ...options, pluginRoot: config.rootDir, outDir });
   const result = { report, paths };
+  const capture = options.capture ?? config.capture?.runtime ?? false;
+  const mockSdk = options.mockSdk ?? config.capture?.mockSdk ?? true;
 
-  if (options.capture === true) {
+  if (capture === true) {
     if (process.env.PLUGIN_INSPECTOR_EXECUTE_ISOLATED !== "1") {
       throw new Error("runtime capture imports plugin code; rerun with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 in an isolated workspace");
     }
-    const config = await loadPluginConfig(options);
     const runtimeCapture = await buildRuntimeCaptureReport({
-      mockSdk: options.mockSdk ?? true,
+      mockSdk,
       report,
       rootDir: config.rootDir,
     });
-    const outputRoot = options.cwd ?? options.pluginRoot ?? process.cwd();
     const runtimeCapturePaths = await writeRuntimeCaptureReport(runtimeCapture, {
-      jsonPath: path.resolve(outputRoot, outDir, "plugin-inspector-runtime-capture.json"),
-      markdownPath: path.resolve(outputRoot, outDir, "plugin-inspector-runtime-capture.md"),
+      jsonPath: path.resolve(config.rootDir, outDir, "plugin-inspector-runtime-capture.json"),
+      markdownPath: path.resolve(config.rootDir, outDir, "plugin-inspector-runtime-capture.md"),
     });
     result.runtimeCapture = runtimeCapture;
     result.runtimeCapturePaths = runtimeCapturePaths;
@@ -82,4 +84,8 @@ export async function capturePluginEntrypoint(entrypoint, options = {}) {
   return captureEntrypoint(entrypoint, options);
 }
 
+export async function setupPluginInspector(options = {}) {
+  return writePluginInspectorInit(options);
+}
+
 export { createCaptureApi, renderTextSummary };

package/src/capture-api.js

@@ -1,15 +1,68 @@
+export const defaultCaptureApiRegistrarProfiles = {
+  registerChannel: {
+    returnValue: ({ args }) => registrationObject(args, { id: "channel" }),
+  },
+  registerCli: {
+    returnValue: ({ args }) => registrationObject(args, { name: "cli" }),
+  },
+  registerCommand: {
+    returnValue: ({ args }) => registrationObject(args, { name: "command" }),
+  },
+  registerContextEngine: {
+    returnValue: ({ args }) => registrationObject(args, { id: "context-engine" }),
+  },
+  registerGatewayMethod: {
+    returnValue: ({ args }) => registrationObject(args, { name: "gateway.method" }),
+  },
+  registerHook: {
+    returnValue: ({ api }) => api,
+  },
+  registerHttpRoute: {
+    returnValue: ({ args }) => ({
+      ...registrationObject(args, { method: "GET", path: "/" }),
+      unregister() {},
+    }),
+  },
+  registerInteractiveHandler: {
+    returnValue: ({ args }) => registrationObject(args, { id: "interactive-handler" }),
+  },
+  registerMemoryPromptSection: {
+    returnValue: ({ args }) => registrationObject(args, { id: "memory-prompt-section" }),
+  },
+  registerMemoryRuntime: {
+    returnValue: ({ args }) => registrationObject(args, { id: "memory-runtime" }),
+  },
+  registerProvider: {
+    returnValue: ({ args }) => registrationObject(args, { id: "provider" }),
+  },
+  registerService: {
+    returnValue: ({ args }) => ({
+      ...registrationObject(args, { name: "service" }),
+      start: async () => undefined,
+      stop: async () => undefined,
+    }),
+  },
+  registerSpeechProvider: {
+    returnValue: ({ args }) => registrationObject(args, { id: "speech-provider" }),
+  },
+  registerTool: {
+    returnValue: ({ args }) => registrationObject(args, { name: "tool" }),
+  },
+};
+
 export function createCaptureApi(options = {}) {
   const captured = [];
   const retained = [];
-  const knownRegistrars = new Set(options.knownRegistrars ?? []);
+  const registrarProfiles = {
+    ...defaultCaptureApiRegistrarProfiles,
+    ...(options.registrarProfiles ?? {}),
+  };
+  const knownRegistrars = new Set(options.knownRegistrars ?? Object.keys(registrarProfiles));
   const retainHandlers = options.retainHandlers === true;
 
   const api = new Proxy(
     {
-      config: options.config ?? {},
-      logger: options.logger ?? console,
-      pluginConfig: options.pluginConfig ?? {},
-      runtime: options.runtime ?? {},
+      ...createCaptureContext(options),
       on(name, handler) {
         const captureIndex =
           captured.push({
@@ -42,6 +95,7 @@ export function createCaptureApi(options = {}) {
         }
         if (typeof property === "string" && isRegistrarProperty(property)) {
           return (...args) => {
+            const returnValue = registrationReturnValue(property, args, { api, registrarProfiles });
             const captureIndex =
               captured.push({
                 kind: "registration",
@@ -54,10 +108,11 @@ export function createCaptureApi(options = {}) {
                 kind: "registration",
                 name: property,
                 arguments: args,
+                returnValue,
                 captureIndex,
               });
             }
-            return registrationReturnValue(property, args);
+            return returnValue;
           };
         }
         return undefined;
@@ -68,19 +123,122 @@ export function createCaptureApi(options = {}) {
   return api;
 }
 
+export function createCaptureContext(options = {}) {
+  return {
+    config: options.config ?? {},
+    logger: options.logger ?? console,
+    pluginConfig: options.pluginConfig ?? {},
+    runtime: options.runtime ?? createRuntimeContext(options),
+    secrets: options.secrets ?? createSecretContext(options),
+    store: options.store ?? createStoreContext(options),
+    paths: options.paths ?? {
+      cacheDir: ".plugin-inspector/cache",
+      configDir: ".plugin-inspector/config",
+      dataDir: ".plugin-inspector/data",
+    },
+    agent: options.agent ?? {
+      id: "plugin-inspector-agent",
+      accountId: "default",
+    },
+    gateway: options.gateway ?? {
+      baseUrl: "http://127.0.0.1:0",
+      registerRoute(route) {
+        return {
+          ...route,
+          unregister() {},
+        };
+      },
+    },
+    fetch: options.fetch ?? (async () => ({ ok: true, status: 200, json: async () => ({}), text: async () => "" })),
+  };
+}
+
 function isRegistrarProperty(property) {
   return property.startsWith("register") || property.startsWith("define");
 }
 
-function registrationReturnValue(name, args) {
-  if (name === "registerService") {
+function registrationReturnValue(name, args, context) {
+  const profile = context.registrarProfiles[name];
+  if (profile?.returnValue) {
+    return profile.returnValue({ name, args, api: context.api });
+  }
+  return registrationObject(args, {});
+}
+
+function createRuntimeContext(options) {
+  const runtime = options.runtime ?? {};
+  return {
+    ...runtime,
+    agent: runtime.agent ?? {},
+    env: options.env ?? {},
+    logger: options.logger ?? console,
+    now: () => new Date(0),
+    tts: runtime.tts ?? {},
+    state: {
+      resolveStateDir: () => options.stateDir ?? process.cwd(),
+      ...(runtime.state ?? {}),
+    },
+  };
+}
+
+function createSecretContext(options) {
+  const secrets = new Map(Object.entries(options.secretValues ?? {}));
+  return {
+    async get(name) {
+      return secrets.get(name) ?? null;
+    },
+    async has(name) {
+      return secrets.has(name);
+    },
+    async require(name) {
+      if (!secrets.has(name)) {
+        throw new Error(`Missing mocked secret: ${name}`);
+      }
+      return secrets.get(name);
+    },
+    async resolve(value) {
+      return typeof value === "string" && value.startsWith("secret:") ? (secrets.get(value.slice(7)) ?? null) : value;
+    },
+  };
+}
+
+function createStoreContext() {
+  const values = new Map();
+  return {
+    async delete(key) {
+      return values.delete(key);
+    },
+    async get(key) {
+      return values.get(key);
+    },
+    async list() {
+      return [...values.keys()].sort();
+    },
+    async set(key, value) {
+      values.set(key, value);
+      return value;
+    },
+  };
+}
+
+function registrationObject(args, defaults) {
+  const first = args[0];
+  if (first && typeof first === "object") {
     return {
-      name: objectName(args[0]),
-      start: async () => undefined,
-      stop: async () => undefined,
+      ...defaults,
+      ...first,
+      name: objectName(first) ?? defaults.name,
+      id: objectId(first) ?? defaults.id,
     };
   }
-  return objectName(args[0]) ?? undefined;
+  if (typeof first === "string") {
+    return {
+      ...defaults,
+      name: first,
+      id: defaults.id,
+    };
+  }
+  return { ...defaults };
 }
 
 function summarizeArguments(args) {
@@ -113,3 +271,13 @@ function objectName(value) {
   }
   return typeof value.id === "string" ? value.id : null;
 }
+
+function objectId(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  if (typeof value.id === "string") {
+    return value.id;
+  }
+  return typeof value.name === "string" ? value.name : null;
+}

package/src/cli.js

@@ -7,6 +7,7 @@ import {
   captureEntrypoint,
   inspectFixtureSet,
   loadInspectorConfig,
+  writePluginInspectorInit,
   writeArtifacts,
   writeReport,
 } from "./advanced.js";
@@ -20,6 +21,8 @@ try {
     printHelp();
   } else if (command === "check") {
     await runCheck(commandArgs);
+  } else if (command === "init") {
+    await runInit(commandArgs);
   } else if (command === "inspect" || command === "report" || command === "ci") {
     await runReport(command, commandArgs);
   } else if (command === "capture") {
@@ -34,11 +37,13 @@ try {
 
 async function runCheck(commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
+  const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
   const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
   const json = commandArgs.includes("--json");
-  const capture = commandArgs.includes("--capture");
-  const { report } = await runPluginCheck({ configPath, outDir, openclawPath, capture });
+  const capture = readRuntimeFlag(commandArgs);
+  const mockSdk = readMockSdkFlag(commandArgs);
+  const { report } = await runPluginCheck({ configPath, pluginRoot, outDir, openclawPath, capture, mockSdk });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));
@@ -51,6 +56,25 @@ async function runCheck(commandArgs) {
   }
 }
 
+async function runInit(commandArgs) {
+  const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
+  const configPath = readFlag(commandArgs, "--config") ?? undefined;
+  const workflowPath = readFlag(commandArgs, "--workflow") ?? undefined;
+  const packageManager = readFlag(commandArgs, "--package-manager") ?? "npm";
+  const result = await writePluginInspectorInit({
+    pluginRoot,
+    configPath,
+    workflowPath,
+    packageManager,
+    ci: commandArgs.includes("--ci"),
+    force: commandArgs.includes("--force"),
+  });
+
+  for (const filePath of result.written) {
+    console.log(`wrote ${filePath}`);
+  }
+}
+
 async function runReport(command, commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
@@ -75,7 +99,7 @@ async function runCapture(commandArgs) {
   const entrypoint = commandArgs.find((arg) => !arg.startsWith("-"));
   const outputPath = readFlag(commandArgs, "--output");
   const pluginRoot = readFlag(commandArgs, "--plugin-root");
-  const mockSdk = commandArgs.includes("--mock-sdk");
+  const mockSdk = readMockSdkFlag(commandArgs) ?? commandArgs.includes("--mock-sdk");
   if (!entrypoint) {
     throw new Error("capture requires an entrypoint path");
   }
@@ -100,14 +124,49 @@ function readFlag(commandArgs, name) {
   return commandArgs[index + 1] ?? null;
 }
 
+function readRuntimeFlag(commandArgs) {
+  if (commandArgs.includes("--runtime") || commandArgs.includes("--capture")) {
+    return true;
+  }
+  if (commandArgs.includes("--no-runtime") || commandArgs.includes("--no-capture")) {
+    return false;
+  }
+  return undefined;
+}
+
+function readMockSdkFlag(commandArgs) {
+  const sdk = readFlag(commandArgs, "--sdk");
+  if (sdk === "mock") {
+    return true;
+  }
+  if (sdk === "real") {
+    return false;
+  }
+  if (sdk && !["mock", "real"].includes(sdk)) {
+    throw new Error("--sdk must be mock or real");
+  }
+  if (commandArgs.includes("--mock-sdk")) {
+    return true;
+  }
+  if (commandArgs.includes("--real-sdk")) {
+    return false;
+  }
+  return undefined;
+}
+
 function printHelp() {
   console.log(`plugin-inspector
 
 Usage:
-  plugin-inspector check [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--capture] [--json]
+  plugin-inspector
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--json]
+  plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--package-manager npm|pnpm|yarn|bun] [--force]
   plugin-inspector report --config <path> [--out <dir>] [--check] [--json]
   plugin-inspector inspect --config <path> [--out <dir>] [--check] [--json]
   plugin-inspector ci --config <path> [--out <dir>]
-  PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture <entrypoint> [--mock-sdk] [--plugin-root <path>] [--output <path>]
+  PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1 plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--plugin-root <path>] [--output <path>]
+
+Default check runs from the current plugin root and writes reports/ unless --out is set.
+Runtime capture is opt-in because it imports plugin code; use --runtime with PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
 `);
 }