@openclaw/plugin-inspector 0.3.12 → 0.3.13

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.3.13 - 2026-06-09
+
+### Changed
+
+- Add `authorRemediation.summary` and `authorRemediation.docsUrl` guidance to author-facing compatibility issues and Markdown reports.
+- Add `--author-facing` for `check`, `ci`, and `batch` reports while keeping default output complete for internal coverage findings.
+- Replace the recent `--include-inspector-gaps` option with a clear error pointing to `--author-facing`.
+
 ## 0.3.12 - 2026-06-09
 
 ### Changed

package/README.md

@@ -187,7 +187,7 @@ Common options:
 | `--mock-sdk` / `--sdk mock` | Use generated SDK and external-package mocks for runtime capture. |
 | `--real-sdk` / `--sdk real` | Use installed real SDK dependencies instead of mocks. |
 | `--allow-execute` | Permit commands that import plugin code. |
-| `--include-inspector-gaps` | Include maintainer-facing scanner coverage gaps in `check`, `ci`, and `batch` output. |
+| `--author-facing` | Limit `check`, `ci`, and `batch` reports to findings with `authorRemediation` guidance. |
 | `--json` | Print machine-readable JSON to stdout. |
 | `--sarif [path]` | Write SARIF from `check` or `inspect`; `ci` enables this by default. |
 | `--junit [path]` | Write JUnit XML from `check` or `inspect`; `ci` enables this by default. |
@@ -307,9 +307,10 @@ Important report sections:
 | `logs` | Informational inventory and coverage rows. |
 | `decisions` | Maintainer-facing follow-up or compatibility-policy decisions. |
 
-Author-facing `check`, `ci`, and `batch` output hides inspector gaps by default
-because they are scanner coverage backlog, not plugin-author fixes. Pass
-`--include-inspector-gaps` for Crabpot-style maintainer coverage reports.
+Default `check`, `ci`, and `batch` reports include both author-facing and
+internal findings. Pass `--author-facing` when producing plugin-author output;
+that filtered view includes only findings with `authorRemediation.summary` and
+`authorRemediation.docsUrl`.
 
 ## CI Policy And Shared Reporting Primitives
 

package/package.json

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

package/src/advanced.js

@@ -77,6 +77,7 @@ export {
   classifyIssueFinding,
   deprecatedCompatRecords,
   issueId,
+  isAuthorFacingFinding,
   issueMetadata,
   issueMetadataByCode,
   knownIssueCodes,

package/src/api.js

@@ -43,8 +43,8 @@ export async function loadPluginConfig(options = {}) {
 export async function inspectPluginRoot(options = {}) {
   const config = await loadPluginConfig(options);
   return inspectCompatibilityFixtureSet(config, {
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
-    includeInspectorGaps: options.includeInspectorGaps,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
@@ -59,8 +59,8 @@ export async function inspectFixtureSetConfig(options = {}) {
 export async function inspectCompatibilityFixtureSetConfig(options = {}) {
   const config = await loadFixtureSetConfig(options);
   return inspectCompatibilityFixtureSet(config, {
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
-    includeInspectorGaps: options.includeInspectorGaps,
     openclawPath: options.openclawPath,
     executionResults: options.executionResults,
     targetOpenClaw: options.targetOpenClaw,
@@ -114,8 +114,8 @@ export async function buildFixtureSetColdImportReadiness(options = {}) {
   const report =
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
+      authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
-      includeInspectorGaps: options.includeInspectorGaps,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,
@@ -147,8 +147,8 @@ export async function buildFixtureSetWorkspacePlan(options = {}) {
   const report =
     options.report ??
     (await inspectCompatibilityFixtureSet(config, {
+      authorFacing: options.authorFacing,
       generatedAt: options.generatedAt,
-      includeInspectorGaps: options.includeInspectorGaps,
       openclawPath: options.openclawPath,
       executionResults: options.executionResults,
       targetOpenClaw: options.targetOpenClaw,

package/src/batch.js

@@ -108,9 +108,9 @@ async function inspectBatchPlugin(pluginRoot, options) {
   try {
     const { report } = await runPluginCheck({
       allowExecution: options.allowExecution,
+      authorFacing: options.authorFacing,
       capture: options.capture,
       configPath: options.configPath,
-      includeInspectorGaps: options.includeInspectorGaps,
       mockSdk: options.mockSdk,
       openclawPath: options.openclawPath,
       outDir: options.outDir,
@@ -148,17 +148,20 @@ async function inspectBatchPlugin(pluginRoot, options) {
 }
 
 function normalizeReportFindings(report) {
-  return [
-    ...(report.breakages ?? []).map((finding) => normalizeFinding(finding, "error")),
-    ...(report.issues ?? []).map((finding) =>
-      normalizeFinding(
-        finding,
-        finding.status === "blocking" || finding.severity === "P0" ? "error" : "warning",
-      ),
+  const issueFindings = (report.issues ?? []).map((finding) =>
+    normalizeFinding(
+      finding,
+      finding.status === "blocking" || finding.severity === "P0" ? "error" : "warning",
     ),
+  );
+  const issueKeys = new Set(issueFindings.map(findingKey));
+  const rawFindings = [
+    ...(report.breakages ?? []).map((finding) => normalizeFinding(finding, "error")),
     ...(report.warnings ?? []).map((finding) => normalizeFinding(finding, "warning")),
     ...(report.suggestions ?? []).map((finding) => normalizeFinding(finding, "warning")),
-  ];
+  ].filter((finding) => !issueKeys.has(findingKey(finding)));
+
+  return [...issueFindings, ...rawFindings];
 }
 
 function normalizeFinding(finding, kind) {
@@ -169,9 +172,18 @@ function normalizeFinding(finding, kind) {
     issueClass: finding.issueClass,
     message: finding.message ?? finding.title ?? "See plugin report.",
     evidence: finding.evidence,
+    ...(finding.authorRemediation ? { authorRemediation: finding.authorRemediation } : {}),
   };
 }
 
+function findingKey(finding) {
+  return [
+    finding.fixture ?? "",
+    finding.code ?? "",
+    ...(Array.isArray(finding.evidence) ? finding.evidence : []),
+  ].join("\n");
+}
+
 function findingFrequencyRows(entries) {
   const byCode = new Map();
   for (const entry of entries) {

package/src/cli.js

@@ -64,7 +64,7 @@ async function runBatch(commandArgs) {
   const json = commandArgs.includes("--json");
   const check = commandArgs.includes("--check");
   const keepPluginReports = commandArgs.includes("--keep-plugin-reports");
-  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   if (!inputDir) {
     throw new Error("batch requires a folder of plugin roots");
   }
@@ -73,7 +73,7 @@ async function runBatch(commandArgs) {
     outDir,
     openclawPath,
     concurrency,
-    includeInspectorGaps,
+    authorFacing,
     keepPluginReports,
   });
 
@@ -110,12 +110,12 @@ async function runCheck(commandArgs) {
   const mockSdk = readMockSdkFlag(commandArgs);
   const allowExecution = readAllowExecutionFlag(commandArgs);
   const ciOutputs = readCiOutputFlags(commandArgs);
-  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const { report, paths } = await runPluginCheck({
     allowExecution,
+    authorFacing,
     capture,
     configPath,
-    includeInspectorGaps,
     mockSdk,
     openclawPath,
     outDir,
@@ -168,12 +168,18 @@ async function runInit(commandArgs) {
 async function runReport(command, commandArgs) {
   const configPath = readFlag(commandArgs, "--config");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
+  const openclawPath = commandArgs.includes("--no-openclaw") ? false : readFlag(commandArgs, "--openclaw");
   const check = commandArgs.includes("--check") || command === "ci";
   const json = commandArgs.includes("--json");
   const ciOutputs = readCiOutputFlags(commandArgs);
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const config = await loadInspectorConfig(configPath);
-  const report = await inspectFixtureSet(config);
-  const paths = await writeReport(report, { outDir });
+  const report = authorFacing
+    ? await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath })
+    : await inspectFixtureSet(config);
+  const paths = authorFacing
+    ? await writeCompatibilityReport(report, { cwd: config.rootDir, outDir })
+    : await writeReport(report, { outDir });
   await writeCiOutputArtifacts(report, {
     ...ciOutputs,
     cwd: path.dirname(paths.jsonPath),
@@ -201,12 +207,12 @@ async function runCi(commandArgs) {
   const mockSdk = readMockSdkFlag(commandArgs);
   const allowExecution = readAllowExecutionFlag(commandArgs);
   const ciOutputs = readCiOutputFlags(commandArgs, { defaultEnabled: true });
-  const includeInspectorGaps = commandArgs.includes("--include-inspector-gaps");
+  const authorFacing = readAuthorFacingFlag(commandArgs);
   const { report, reportDir } = await runCiCompatibilityReport({
     allowExecution,
+    authorFacing,
     capture,
     configPath,
-    includeInspectorGaps,
     mockSdk,
     openclawPath,
     outDir,
@@ -245,9 +251,9 @@ async function runCi(commandArgs) {
 
 async function runCiCompatibilityReport({
   allowExecution,
+  authorFacing,
   capture,
   configPath,
-  includeInspectorGaps,
   mockSdk,
   openclawPath,
   outDir,
@@ -255,7 +261,7 @@ async function runCiCompatibilityReport({
 }) {
   if (configPath) {
     const config = await loadInspectorConfig(configPath, { cwd: pluginRoot });
-    const report = await inspectCompatibilityFixtureSet(config, { includeInspectorGaps, openclawPath });
+    const report = await inspectCompatibilityFixtureSet(config, { authorFacing, openclawPath });
     await writeCompatibilityReport(report, { cwd: config.rootDir, outDir });
     return {
       report,
@@ -265,8 +271,8 @@ async function runCiCompatibilityReport({
 
   const { report } = await runPluginCheck({
     allowExecution,
+    authorFacing,
     capture,
-    includeInspectorGaps,
     mockSdk,
     openclawPath,
     outDir,
@@ -373,6 +379,15 @@ function readAllowExecutionFlag(commandArgs) {
   return commandArgs.includes("--allow-execute");
 }
 
+function readAuthorFacingFlag(commandArgs) {
+  if (commandArgs.includes("--include-inspector-gaps")) {
+    throw new Error(
+      "--include-inspector-gaps has been replaced by --author-facing; default output now includes internal findings.",
+    );
+  }
+  return commandArgs.includes("--author-facing");
+}
+
 function renderCiTextSummary(summary) {
   return [
     `Status: ${summary.status.toUpperCase()}`,
@@ -437,18 +452,18 @@ function printHelp() {
 
 Usage:
   plugin-inspector
-  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--include-inspector-gaps] [--json]
+  plugin-inspector check [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json]
   plugin-inspector config [--plugin-root <path>] [--config <path>] [--json]
   plugin-inspector init [--plugin-root <path>] [--config <path>] [--ci] [--scripts] [--package-manager npm|pnpm|yarn|bun] [--dry-run] [--json] [--force]
-  plugin-inspector report --config <path> [--out <dir>] [--check] [--json]
-  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--include-inspector-gaps] [--check] [--json]
-  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
-  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--include-inspector-gaps] [--json] [--no-sarif] [--no-junit]
+  plugin-inspector report --config <path> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json]
+  plugin-inspector batch <folder> [--out <dir>] [--openclaw <path>] [--no-openclaw] [--concurrency <n>] [--keep-plugin-reports] [--author-facing] [--check] [--json]
+  plugin-inspector inspect [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--author-facing] [--check] [--json] [--sarif [path]] [--junit [path]] [--allow-execute]
+  plugin-inspector ci [--plugin-root <path>] [--config <path>] [--out <dir>] [--openclaw <path>] [--no-openclaw] [--runtime] [--mock-sdk|--real-sdk] [--allow-execute] [--author-facing] [--json] [--no-sarif] [--no-junit]
   plugin-inspector capture <entrypoint> [--mock-sdk|--real-sdk] [--allow-execute] [--plugin-root <path>] [--output <path>]
 
 Default check runs from the current plugin root and writes reports/ unless --out is set.
 CI writes SARIF and JUnit artifacts by default; check/inspect can write them with --sarif and --junit.
 Runtime capture is opt-in because it imports plugin code; use --runtime with --allow-execute or PLUGIN_INSPECTOR_EXECUTE_ISOLATED=1.
-Inspector coverage gaps are hidden by default; pass --include-inspector-gaps for maintainer coverage reports.
+Default output includes author-facing and internal findings; pass --author-facing to show only findings with author remediation docs.
 `);
 }

package/src/compatibility-report.js

@@ -250,10 +250,23 @@ function issueBlock(issue, options) {
     `  - state: ${issueState(issue)}`,
     "  - evidence:",
     ...evidenceList(issue.evidence, options).map((item) => `    - ${item}`),
+    ...remediationList(issue),
     ...runtimeCoverageList(issue, options),
   ].join("\n");
 }
 
+function remediationList(issue) {
+  const remediation = issue.authorRemediation;
+  if (!remediation?.summary) {
+    return [];
+  }
+  return [
+    "  - author remediation:",
+    `    - ${remediation.summary}`,
+    `    - docs: ${remediation.docsUrl}`,
+  ];
+}
+
 function issueState(issue) {
   const flags = [
     issue.status,

package/src/index.js

@@ -217,7 +217,7 @@ export {
   validateImportLoopProfile,
   writeImportLoopProfile,
 } from "./import-loop-profile.js";
-export { classifyIssueFinding, issueId, knownIssueCodes } from "./issues.js";
+export { classifyIssueFinding, issueId, isAuthorFacingFinding, knownIssueCodes } from "./issues.js";
 export { inspectFixtureSet, inspectPlugin, inspectSourceText } from "./inspector.js";
 export { openClawTargetPathCandidates, readOpenClawTargetSurface } from "./openclaw-target.js";
 export {

package/src/inspector.js

@@ -35,9 +35,9 @@ export async function inspectCompatibilityFixtureSet(config, options = {}) {
     config,
     inspections,
     failures,
+    authorFacing: options.authorFacing,
     generatedAt: options.generatedAt,
     executionResults: options.executionResults,
-    includeInspectorGaps: options.includeInspectorGaps,
     targetOpenClaw,
     buildFixtureReport: ({ fixture, inspection }) =>
       buildCompatibilityFixtureReport({

package/src/issues.js

@@ -45,6 +45,12 @@ export const knownIssueCodes = new Set([
   "unrecognized-security-manifest",
 ]);
 
+const authorRemediationDocsUrl = (code) => `https://docs.openclaw.ai/clawhub/plugin-validation-fixes#${code}`;
+
+const authorRemediation = (summary) => ({ summary });
+
+const migrationRemediation = authorRemediation;
+
 export const issueMetadataByCode = {
   "before-tool-call-probe": {
     severity: "P1",
@@ -63,6 +69,13 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "channelEnvVars legacy manifest metadata must stay covered",
+    authorRemediation: migrationRemediation(
+      "Move legacy channel environment variable metadata into the current setup/config metadata while keeping the old field until your supported OpenClaw range no longer needs it.",
+      [
+        "Mirror each channel environment variable into the current setup or provider configuration metadata.",
+        "Keep channelEnvVars only as backwards compatibility for older OpenClaw versions you still support.",
+      ],
+    ),
   },
   "conversation-access-hook": {
     severity: "P1",
@@ -75,12 +88,27 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "legacy before_agent_start hook compatibility is still used",
+    authorRemediation: migrationRemediation(
+      "Replace the legacy before_agent_start hook with the current prompt/model hooks.",
+      [
+        "Move model-selection work to before_model_resolve when possible.",
+        "Move prompt mutation work to before_prompt_build.",
+        "Keep before_agent_start only if your declared compatibility range still includes OpenClaw versions that require it.",
+      ],
+    ),
   },
   "legacy-root-sdk-import": {
     severity: "P2",
     owner: "core",
     decision: "core-compat-adapter",
     title: "root plugin SDK barrel is still used by fixtures",
+    authorRemediation: migrationRemediation(
+      "Prefer focused public plugin SDK subpath imports instead of the legacy root barrel.",
+      [
+        "Replace imports from openclaw/plugin-sdk with the documented subpath for the API you use.",
+        "Keep the root import only while supporting older OpenClaw versions that do not expose the subpath.",
+      ],
+    ),
   },
   "sdk-export-missing": {
     severity: "P1",
@@ -93,12 +121,26 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin imports reserved bundled-plugin SDK compatibility subpaths",
+    authorRemediation: authorRemediation(
+      "Stop importing reserved bundled-plugin SDK compatibility paths.",
+      [
+        "Replace reserved OpenClaw internal SDK imports with documented public openclaw/plugin-sdk subpaths.",
+        "If no public API exists for the behavior, vendor a plugin-local helper or request a public OpenClaw API.",
+      ],
+    ),
   },
   "security-manifest-schema-unavailable": {
     severity: "P3",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin security manifest references an unavailable schema",
+    authorRemediation: authorRemediation(
+      "Remove or update the unsupported security manifest schema reference.",
+      [
+        "Delete the schema URL from openclaw.security.json if it is advisory-only.",
+        "Use a documented versioned schema once OpenClaw publishes one.",
+      ],
+    ),
   },
   "missing-compat-record": {
     severity: "P1",
@@ -117,18 +159,37 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest display name is missing",
+    authorRemediation: authorRemediation(
+      "Add a display name to the plugin manifest.",
+      ["Set a non-empty name field in openclaw.plugin.json."],
+      '{\n  "name": "My Plugin"\n}',
+    ),
   },
   "manifest-unknown-contracts": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest declares unsupported contract keys",
+    authorRemediation: authorRemediation(
+      "Remove unsupported manifest contract keys or move them to a documented OpenClaw contract field.",
+      [
+        "Compare the contracts object to the OpenClaw manifest fields supported by your target version.",
+        "Delete custom contract keys unless OpenClaw has a versioned schema for them.",
+      ],
+    ),
   },
   "manifest-unknown-fields": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "manifest uses unsupported top-level fields",
+    authorRemediation: authorRemediation(
+      "Move unsupported top-level manifest fields into supported package metadata or remove them.",
+      [
+        "Keep openclaw.plugin.json limited to fields supported by the target OpenClaw manifest schema.",
+        "Move package-level metadata into package.json openclaw metadata when that field is supported.",
+      ],
+    ),
   },
   "package-build-artifact-entrypoint": {
     severity: "P2",
@@ -147,72 +208,159 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package entrypoint is missing",
+    authorRemediation: authorRemediation(
+      "Publish the entrypoint declared in OpenClaw package metadata or update the metadata to point at an existing file.",
+      [
+        "Check package.json openclaw.extensions and openclaw.runtimeExtensions.",
+        "Ensure the referenced file exists in the published artifact, usually under dist/ after build.",
+      ],
+    ),
   },
   "package-install-metadata-incomplete": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package install metadata is incomplete",
+    authorRemediation: authorRemediation(
+      "Complete the OpenClaw install metadata so ClawHub can identify the install target.",
+      [
+        "Fill package.json openclaw.install with the supported release target.",
+        "Align clawhubSpec, npmSpec, and defaultChoice with the package you publish.",
+      ],
+    ),
   },
   "package-json-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package metadata is missing",
+    authorRemediation: authorRemediation(
+      "Add a package.json to the plugin package.",
+      [
+        "Include the package name and version.",
+        "Add an openclaw metadata block describing extensions, compatibility, and install details.",
+      ],
+    ),
   },
   "package-manifest-version-drift": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package and manifest versions drift",
+    authorRemediation: authorRemediation(
+      "Align the plugin version declared in package.json and openclaw.plugin.json.",
+      [
+        "Use the same version in both files, or remove stale manifest version metadata if package.json is authoritative.",
+        "Republish with a new package version after changing published metadata.",
+      ],
+    ),
   },
   "package-min-host-version-drift": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package minimum host version drifts from build target",
+    authorRemediation: authorRemediation(
+      "Set the package minimum host version to the OpenClaw version range the plugin was built and tested against.",
+      [
+        "Update package.json openclaw.install.minHostVersion or compatibility metadata.",
+        "Keep it semver-compatible with the target OpenClaw build version.",
+      ],
+    ),
   },
   "package-npm-pack-entrypoint-missing": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact is missing OpenClaw entrypoints",
+    authorRemediation: authorRemediation(
+      "Include the declared OpenClaw entrypoints in the npm-packed artifact.",
+      [
+        "Run npm pack locally and inspect the tarball contents.",
+        "Update package.json files so dist files and manifests are included.",
+        "Build before packing if the entrypoint is generated.",
+      ],
+    ),
   },
   "package-npm-pack-metadata-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact is missing OpenClaw metadata",
+    authorRemediation: authorRemediation(
+      "Include OpenClaw metadata files in the npm-packed artifact.",
+      [
+        "Run npm pack locally and inspect package.json and OpenClaw manifest files.",
+        "Update package.json files so required metadata is not excluded.",
+      ],
+    ),
   },
   "package-npm-pack-unavailable": {
     severity: "P1",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "advertised npm artifact cannot be packed",
+    authorRemediation: authorRemediation(
+      "Make the package packable before publishing it through ClawHub.",
+      [
+        "Remove private:true if this package is intended to publish.",
+        "Ensure package.json has a valid name and version.",
+        "Fix package scripts or files entries that make npm pack fail.",
+      ],
+    ),
   },
   "package-openclaw-entry-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package entrypoint metadata is missing",
+    authorRemediation: authorRemediation(
+      "Declare the plugin runtime entrypoint in package.json OpenClaw metadata.",
+      [
+        "Add openclaw.extensions for extension entrypoints.",
+        "Add openclaw.runtimeExtensions when the plugin has runtime-side code.",
+      ],
+    ),
   },
   "package-openclaw-metadata-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "OpenClaw package metadata is missing",
+    authorRemediation: authorRemediation(
+      "Add the package.json openclaw metadata block.",
+      [
+        "Describe extension entrypoints, plugin API compatibility, and install metadata.",
+        "Keep package metadata in sync with openclaw.plugin.json when both files are present.",
+      ],
+    ),
   },
   "package-openclaw-unsupported-metadata": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "package declares unsupported OpenClaw metadata",
+    authorRemediation: authorRemediation(
+      "Remove unsupported OpenClaw package metadata fields.",
+      [
+        "Delete openclaw.bundle and other fields not accepted by the current package schema.",
+        "Move bundle-specific data to documented manifest fields when available.",
+      ],
+    ),
   },
   "package-plugin-api-compat-missing": {
     severity: "P2",
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin API compatibility range is missing",
+    authorRemediation: authorRemediation(
+      "Declare the OpenClaw plugin API range this package supports.",
+      [
+        "Add package.json `openclaw.compat.pluginApi` with the OpenClaw plugin API range you tested.",
+        "If known, include the OpenClaw build/version used to produce the package metadata.",
+      ],
+      '"openclaw": {\n  "compat": {\n    "pluginApi": ">=0.1.0"\n  }\n}',
+    ),
   },
   "package-typescript-source-entrypoint": {
     severity: "P2",
@@ -225,6 +373,13 @@ export const issueMetadataByCode = {
     owner: "core",
     decision: "core-compat-adapter",
     title: "providerAuthEnvVars legacy manifest metadata must stay covered",
+    authorRemediation: migrationRemediation(
+      "Move legacy provider authentication environment variables into current provider setup metadata.",
+      [
+        "Mirror providerAuthEnvVars into setup.providers[].envVars or the current provider-choice metadata.",
+        "Keep the legacy field only while supporting older OpenClaw versions that still read it.",
+      ],
+    ),
   },
   "registration-capture-gap": {
     severity: "P2",
@@ -255,6 +410,13 @@ export const issueMetadataByCode = {
     owner: "plugin",
     decision: "plugin-upstream-fix",
     title: "plugin ships an unsupported security manifest",
+    authorRemediation: authorRemediation(
+      "Remove unsupported security manifest files until OpenClaw documents a versioned security manifest schema.",
+      [
+        "Delete openclaw.security.json if it is advisory-only and not consumed by OpenClaw.",
+        "Reintroduce it only when the schema and ClawHub behavior are documented.",
+      ],
+    ),
   },
 };
 
@@ -284,6 +446,14 @@ export function buildIssues({ breakages = [], warnings = [], suggestions = [], t
       evidence: finding.evidence ?? [],
       compatRecord: finding.compatRecord ?? null,
       runtimeCoverage: finding.runtimeCoverage ?? null,
+      ...(finding.authorRemediation
+        ? {
+            authorRemediation: {
+              summary: finding.authorRemediation.summary,
+              docsUrl: authorRemediationDocsUrl(finding.code),
+            },
+          }
+        : {}),
     }));
 }
 
@@ -305,9 +475,18 @@ export function issueMetadata(finding, targetOpenClaw) {
     decision: "inspector-follow-up",
     title: finding.message,
   };
+  const authorMetadata = metadata.authorRemediation
+    ? {
+        authorRemediation: {
+          summary: metadata.authorRemediation.summary,
+          docsUrl: authorRemediationDocsUrl(finding.code),
+        },
+      }
+    : {};
   return {
     ...finding,
     ...metadata,
+    ...authorMetadata,
     ...classifyIssueFinding(finding, targetOpenClaw, metadata),
   };
 }
@@ -337,6 +516,10 @@ export function isInspectorGapFinding(finding, targetOpenClaw) {
   return issueMetadata(finding, targetOpenClaw).issueClass === "inspector-gap";
 }
 
+export function isAuthorFacingFinding(finding, targetOpenClaw) {
+  return Boolean(issueMetadata(finding, targetOpenClaw).authorRemediation);
+}
+
 export function summarizeIssueClasses(issues) {
   const summary = {
     "compat-gap": 0,

package/src/report.js

@@ -3,7 +3,7 @@ import { renderMarkdownTable, writeArtifacts, writeJsonMarkdownArtifacts } from
 import { renderCompatibilityIssuesReport, renderCompatibilityMarkdownReport } from "./compatibility-report.js";
 import { buildContractProbes } from "./contract-probes.js";
 import { classifyCompatibilityFixture } from "./fixture-summary.js";
-import { buildIssues, isInspectorGapFinding, summarizeIssueClasses } from "./issues.js";
+import { buildIssues, isAuthorFacingFinding, summarizeIssueClasses } from "./issues.js";
 import { sanitizeReportArtifact } from "./report-sanitizer.js";
 import { applyRuntimeExecutionCoverage } from "./runtime-reconciliation.js";
 
@@ -141,14 +141,16 @@ export async function buildCompatibilityReport(options = {}) {
     decisions,
   });
 
+  const visibleBreakages = filterVisibleFindings(breakages, targetOpenClaw, options);
   const visibleWarnings = filterVisibleFindings(warnings, targetOpenClaw, options);
   const visibleSuggestions = filterVisibleFindings(suggestions, targetOpenClaw, options);
+  const visibleDecisions = options.authorFacing === true ? [] : decisions;
   const runtimeCoverage = applyRuntimeExecutionCoverage({
     findings: [...visibleWarnings, ...visibleSuggestions],
     executionResults: options.executionResults,
   });
   const issues = buildIssues({
-    breakages,
+    breakages: visibleBreakages,
     warnings: visibleWarnings,
     suggestions: visibleSuggestions,
     targetOpenClaw,
@@ -166,14 +168,14 @@ export async function buildCompatibilityReport(options = {}) {
   return {
     generatedAt: options.generatedAt ?? "deterministic",
     targetOpenClaw,
-    status: breakages.length === 0 ? "pass" : "fail",
+    status: visibleBreakages.length === 0 ? "pass" : "fail",
     summary: {
       fixtureCount: fixtureReports.length,
       highPriorityFixtures: fixtureReports.filter((fixture) => fixture.priority === "high").length,
-      breakageCount: breakages.length,
+      breakageCount: visibleBreakages.length,
       warningCount: visibleWarnings.length,
       suggestionCount: visibleSuggestions.length,
-      decisionCount: decisions.length,
+      decisionCount: visibleDecisions.length,
       logCount: logs.length,
       issueCount: issues.length,
       openIssueCount: openIssues.length,
@@ -195,21 +197,21 @@ export async function buildCompatibilityReport(options = {}) {
       contractProbeCount: contractProbes.length,
     },
     fixtures: fixtureReports,
-    breakages,
+    breakages: visibleBreakages,
     warnings: visibleWarnings,
     suggestions: visibleSuggestions,
     issues,
     contractProbes,
     logs,
-    decisions,
+    decisions: visibleDecisions,
   };
 }
 
 function filterVisibleFindings(findings, targetOpenClaw, options) {
-  if (options.includeInspectorGaps === true) {
+  if (options.authorFacing !== true) {
     return findings;
   }
-  return findings.filter((finding) => !isInspectorGapFinding(finding, targetOpenClaw));
+  return findings.filter((finding) => isAuthorFacingFinding(finding, targetOpenClaw));
 }
 
 export function classifyCompatRecordCoverage({ targetOpenClaw, findings, suggestions, logs, decisions }) {