codex-plugin-doctor 1.27.0 → 1.28.0

package/README.md

@@ -11,23 +11,23 @@ It catches packaging, metadata, security, and runtime protocol problems before a
 
 ## Status
 
-Codex Plugin Doctor is a public stable CLI for local and CI validation.
+Codex Plugin Doctor is a public stable CLI for local and CI validation.
 
 - Primary surface: GitHub repository and npm package
 - Distribution today: `npm install -g`, local source install, `npm link`, `npm pack`, GitHub Releases
 - Public npm package: `codex-plugin-doctor`
 - License: [MIT](./LICENSE)
 
-## 1.0 Stability
-
-The 1.0 line is the stable compatibility baseline for plugin authors and CI consumers.
-
-- Public JSON schema surfaces and existing rule IDs/default severities are treated as stable through 1.0.
-- Runtime probing remains opt-in because it executes package-local MCP servers.
-- The project remains Codex-first; broader MCP Doctor positioning stays a post-1.0 expansion path.
-- Post-1.0 feature work should stay additive unless a documented major-version decision is made.
-
-See [v1.0 Readiness Checklist](./docs/engineering/v1.0-readiness-checklist.md) for the stable release evidence and smoke plan.
+## 1.0 Stability
+
+The 1.0 line is the stable compatibility baseline for plugin authors and CI consumers.
+
+- Public JSON schema surfaces and existing rule IDs/default severities are treated as stable through 1.0.
+- Runtime probing remains opt-in because it executes package-local MCP servers.
+- The project remains Codex-first; broader MCP Doctor positioning stays a post-1.0 expansion path.
+- Post-1.0 feature work should stay additive unless a documented major-version decision is made.
+
+See the [documentation index](./docs/README.md) for architecture, usage, security, and contributor guides.
 
 ## Why This Exists
 
@@ -64,7 +64,7 @@ Security scorecard with `security`:
 - MCP server `cwd` paths that escape the package root
 - plain HTTP remote transport warnings
 
-Runtime MCP validation with `--runtime`:
+Runtime MCP validation with `--runtime`:
 
 - `initialize`
 - `notifications/initialized`
@@ -76,9 +76,9 @@ Runtime MCP validation with `--runtime`:
 - `prompts/list`
 - `prompts/get`
 - paginated list responses
-- runtime capability scorecard
-- redacted verbose transcript with `--verbose-runtime`
-- optional runtime approval gating with a precomputed `doctor runtime-plan` digest
+- runtime capability scorecard
+- redacted verbose transcript with `--verbose-runtime`
+- optional runtime approval gating with a precomputed `doctor runtime-plan` digest
 
 Output formats:
 
@@ -195,14 +195,14 @@ codex-plugin-doctor doctor contract
 codex-plugin-doctor doctor contract --json --output output-contract.json
 codex-plugin-doctor doctor corpus
 codex-plugin-doctor doctor corpus --json --output validation-corpus.json
-codex-plugin-doctor doctor npm <published-plugin-package>
-codex-plugin-doctor doctor npm <published-plugin-package> --json --output npm-preinstall.json
-codex-plugin-doctor doctor attest .
-codex-plugin-doctor doctor attest . --json --output attestation.json
-codex-plugin-doctor doctor attest . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY --output attestation.json
-codex-plugin-doctor doctor attest verify attestation.json --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
-codex-plugin-doctor doctor attest verify attestation.json --target . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
-codex-plugin-doctor doctor inspector .
+codex-plugin-doctor doctor npm <published-plugin-package>
+codex-plugin-doctor doctor npm <published-plugin-package> --json --output npm-preinstall.json
+codex-plugin-doctor doctor attest .
+codex-plugin-doctor doctor attest . --json --output attestation.json
+codex-plugin-doctor doctor attest . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY --output attestation.json
+codex-plugin-doctor doctor attest verify attestation.json --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
+codex-plugin-doctor doctor attest verify attestation.json --target . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
+codex-plugin-doctor doctor inspector .
 codex-plugin-doctor doctor inspector . --server context7 --json --output inspector-command.json
 codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin
 codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin --json --output risk-diff.json
@@ -210,20 +210,20 @@ codex-plugin-doctor doctor recommend .
 codex-plugin-doctor doctor recommend . --json --output recommendations.json
 codex-plugin-doctor doctor trust .
 codex-plugin-doctor doctor trust . --json --output trust-score.json
-codex-plugin-doctor doctor perf .
-codex-plugin-doctor doctor perf . --json --output perf.json
-codex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=500
-codex-plugin-doctor doctor runtime-plan .
-codex-plugin-doctor doctor runtime-plan . --json --output runtime-plan.json
-codex-plugin-doctor doctor runtime-plan . --markdown --output runtime-plan.md
-codex-plugin-doctor doctor runtime-policy .
-codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json
-codex-plugin-doctor doctor review-bundle . --output review-bundle --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
-codex-plugin-doctor doctor review-bundle verify review-bundle --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
-codex-plugin-doctor doctor review-bundle diff --before old-review-bundle --after review-bundle
-codex-plugin-doctor doctor mcp .
-codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json
-codex-plugin-doctor doctor export --bundle .
+codex-plugin-doctor doctor perf .
+codex-plugin-doctor doctor perf . --json --output perf.json
+codex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=500
+codex-plugin-doctor doctor runtime-plan .
+codex-plugin-doctor doctor runtime-plan . --json --output runtime-plan.json
+codex-plugin-doctor doctor runtime-plan . --markdown --output runtime-plan.md
+codex-plugin-doctor doctor runtime-policy .
+codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json
+codex-plugin-doctor doctor review-bundle . --output review-bundle --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
+codex-plugin-doctor doctor review-bundle verify review-bundle --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY
+codex-plugin-doctor doctor review-bundle diff --before old-review-bundle --after review-bundle
+codex-plugin-doctor doctor mcp .
+codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json
+codex-plugin-doctor doctor export --bundle .
 codex-plugin-doctor doctor export --bundle . --output doctor-bundle.json
 codex-plugin-doctor doctor snapshot
 codex-plugin-doctor doctor snapshot --json
@@ -232,18 +232,18 @@ codex-plugin-doctor doctor clients
 codex-plugin-doctor doctor --update-check
 codex-plugin-doctor audit --installed
 codex-plugin-doctor audit --installed --security --compat
-codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
-codex-plugin-doctor audit --installed --security --compat --cache
-codex-plugin-doctor audit --installed --changed --cache
-codex-plugin-doctor audit deps .
-codex-plugin-doctor audit deps . --json --output dependency-audit.json
-codex-plugin-doctor watch .
-codex-plugin-doctor watch . --json --output watch-latest.json --debounce-ms 500
-codex-plugin-doctor init-git-hooks .
-codex-plugin-doctor init-git-hooks . --json
-codex-plugin-doctor mcp .
-codex-plugin-doctor mcp . --json
-codex-plugin-doctor mcp . --json --output mcp-doctor.json
+codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json
+codex-plugin-doctor audit --installed --security --compat --cache
+codex-plugin-doctor audit --installed --changed --cache
+codex-plugin-doctor audit deps .
+codex-plugin-doctor audit deps . --json --output dependency-audit.json
+codex-plugin-doctor watch .
+codex-plugin-doctor watch . --json --output watch-latest.json --debounce-ms 500
+codex-plugin-doctor init-git-hooks .
+codex-plugin-doctor init-git-hooks . --json
+codex-plugin-doctor mcp .
+codex-plugin-doctor mcp . --json
+codex-plugin-doctor mcp . --json --output mcp-doctor.json
 codex-plugin-doctor init my-plugin
 codex-plugin-doctor init my-mcp --template mcp-stdio
 codex-plugin-doctor init remote-mcp --template mcp-http
@@ -282,10 +282,10 @@ codex-plugin-doctor check . --badge-json --output doctor-badge.json
 codex-plugin-doctor check . --badge-markdown
 codex-plugin-doctor check . --sarif --output results.sarif
 codex-plugin-doctor check . --ascii
-codex-plugin-doctor check . --no-animations
-codex-plugin-doctor check . --runtime
-codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
-codex-plugin-doctor check . --config .codex-doctor.json
+codex-plugin-doctor check . --no-animations
+codex-plugin-doctor check . --runtime
+codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256:<approved-plan-digest>
+codex-plugin-doctor check . --config .codex-doctor.json
 codex-plugin-doctor check . --history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl
 codex-plugin-doctor history validation-history.jsonl --json
@@ -298,23 +298,23 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`.
 
-`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. The JSON report includes tarball metadata such as filename, path, integrity, shasum, sizes, file count, and extracted package root so automation can prove which archive was scanned. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+`doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm <package>` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. The JSON report includes tarball metadata such as filename, path, integrity, shasum, sizes, file count, and extracted package root so automation can prove which archive was scanned. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest <path>` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify <attestation.json> --target <path> --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan <path>` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy <path>` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle <path> --output <dir> --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before <dir> --after <dir>` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest <digest>` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence <path> --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release-evidence verify <evidence.json> --target <path> --sign-key-env NAME` verifies a shared release evidence artifact offline against an explicit package path; the artifact target path is treated as display metadata, not trusted input. `doctor release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME` writes a signed release evidence file and prints the `gh release upload` command; add `--upload` to run the upload through GitHub CLI with `--clobber`. `doctor inspector <path>` builds a safe MCP Inspector launch command from a packaged `.mcp.json` file without starting the Inspector proxy automatically. Use `--server <name>` when the package contains multiple MCP server entries. `doctor diff --before <path> --after <path>` compares two package roots and reports new findings, resolved findings, trust score delta, and whether risk increased. `doctor recommend <path>` turns validation, security, and compatibility signals into a prioritized action plan with blocker, high, medium, and info actions. Add `--json` for automation or `--output recommendations.json` to write the report to disk. `doctor trust <path>` creates a local trust score from package lifecycle scripts, dependency specs, and MCP security findings. Use it before release when you want supply-chain risks summarized as one score. `doctor perf <path>` profiles the shared package analysis pipeline and reports per-stage durations for validation, config, security, compatibility, trust, recommendations, and total runtime. Add `--max-total-ms <ms>` or repeatable `--max-stage-ms stage=ms` to fail CI when a budget is exceeded. `doctor mcp <path>` exposes the generic MCP static health report under the doctor command family without starting local MCP servers. `doctor export --bundle <path>` creates a redacted operator handoff bundle that includes validation JSON, security scorecard data, compatibility matrix, recommendations, and trust score in one file. `doctor snapshot` creates a redacted diagnostics bundle with environment health, client config readiness, installed plugin metadata, and next commands. Add `--json` for machine-readable output or `--output doctor-snapshot.json` to write the bundle to disk. `doctor clients` reports local Codex, Claude Desktop, Cursor, Cline, and Windsurf config readiness. `doctor --update-check` compares the installed CLI version with the latest npm version and prints the upgrade command when a newer release is available.
+
+`audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
+
+`audit deps <path>` runs `npm audit --json` for the target package and normalizes dependency vulnerability results into a stable `schemaVersion: "1.0.0"` report. Use `--json --output dependency-audit.json` when CI needs machine-readable status, vulnerability counts, and the raw npm audit payload.
+
+`watch <path>` continuously validates a plugin package after file changes. Use `--debounce-ms <ms>` to tune noisy repositories, `--runtime` when runtime probes are required, and `--json --output watch-latest.json` when another process should consume the latest validation snapshot.
 
-`audit --installed` runs a local ecosystem audit against every discovered Codex plugin in the installed plugin cache. Add `--security` to include security scorecards, `--compat` to include the all-client compatibility matrix, and `--json --output local-audit.json` when you want a shareable machine-readable report. Add `--cache` to reuse unchanged plugin results between runs; add `--changed` to only report plugins whose fingerprint changed since the last cached audit. Use `--cache-file path/to/audit-cache.json` when CI or scripted runs need an explicit cache location.
-
-`audit deps <path>` runs `npm audit --json` for the target package and normalizes dependency vulnerability results into a stable `schemaVersion: "1.0.0"` report. Use `--json --output dependency-audit.json` when CI needs machine-readable status, vulnerability counts, and the raw npm audit payload.
-
-`watch <path>` continuously validates a plugin package after file changes. Use `--debounce-ms <ms>` to tune noisy repositories, `--runtime` when runtime probes are required, and `--json --output watch-latest.json` when another process should consume the latest validation snapshot.
-
-`init-git-hooks [path]` installs generated pre-commit and pre-push hooks that run Codex Plugin Doctor validation before local commits and pushes. Add `--force` to overwrite existing hooks and `--json` when setup automation needs the written hook paths.
-
-`--policy codex-publish|mcp-strict|security` applies opinionated gates without requiring a local `.codex-doctor.json`. `codex-publish` fails warnings and enables runtime probes for release checks, `mcp-strict` does the same for MCP-heavy packages, and `security` fails warning-level security findings so advisory risks can block a local audit or CI gate.
+`init-git-hooks [path]` installs generated pre-commit and pre-push hooks that run Codex Plugin Doctor validation before local commits and pushes. Add `--force` to overwrite existing hooks and `--json` when setup automation needs the written hook paths.
+
+`--policy codex-publish|mcp-strict|security` applies opinionated gates without requiring a local `.codex-doctor.json`. `codex-publish` fails warnings and enables runtime probes for release checks, `mcp-strict` does the same for MCP-heavy packages, and `security` fails warning-level security findings so advisory risks can block a local audit or CI gate.
 
 `mcp <path>` diagnoses generic MCP packages that may not have a Codex plugin manifest. It looks for `.mcp.json` or a manifest `mcpServers` reference, validates the top-level `mcpServers` object and server transports, adds MCP command-surface security findings, and includes the all-client compatibility matrix in the same report.
 
 `init [path] --template ...` creates targeted starter packages. `skill-only` is the default minimal skill package, `mcp-stdio` adds a local stdio MCP config and mock server, `mcp-http` scaffolds a streamable HTTP MCP config, and `full-runtime` generates a stdio sample that passes the runtime protocol probes.
 
-`security <path>` renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, `cwd` values outside the plugin root, and plain HTTP URLs. Findings include structured, instance-specific evidence such as manifest fields, skill paths, server names, protocol methods, dependency sections, env keys, and bounded payload lengths. Deterministic SHA-256 fingerprints derive from the rule ID and canonical evidence, with package paths normalized for cross-machine stability. Secrets, prompt bodies, resource contents, tool payloads, stderr, and encoded commands are not copied into evidence. Use `--json` for automation or `--scorecard` for a compact status view.
+`security <path>` renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, `cwd` values outside the plugin root, and plain HTTP URLs. Findings include structured, instance-specific evidence such as manifest fields, skill paths, server names, protocol methods, dependency sections, env keys, and bounded payload lengths. Deterministic SHA-256 fingerprints derive from the rule ID and canonical evidence, with package paths normalized for cross-machine stability. Secrets, prompt bodies, resource contents, tool payloads, stderr, and encoded commands are not copied into evidence. Use `--json` for automation or `--scorecard` for a compact status view.
 
 `compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
 
@@ -336,27 +336,46 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `fix --dry-run` renders safe automatic fix plans without changing files. `fix --interactive --backup` shows the same numbered plan, then applies everything after `yes` or only selected action numbers such as `1,3`. `fix --apply --backup` applies supported safe fixes, such as manifest defaults and missing skills directories, after creating backups.
 
-Optional local policy file:
-
-```json
-{
-  "ignoreRules": ["plugin.heuristic.description.too_long"],
-  "suppressions": [
-    {
-      "fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
-      "reason": "Accepted until the upstream package layout is corrected.",
-      "expiresAt": "2026-07-31"
-    }
-  ],
-  "failOnWarnings": true
-}
-```
-
-`ignoreRules` disables every finding with a matching rule ID. Prefer `suppressions` when accepting one specific finding instance: each record requires the exact 64-character lowercase SHA-256 fingerprint shown in Doctor reports, a non-empty review reason, and a real `YYYY-MM-DD` expiration date.
-
-Active suppressions remove only the matching finding from the active result and preserve it under `suppressedFindings` for audit output. Expired or invalid records do not suppress findings; Doctor emits `suppression.expired` or `suppression.invalid` warnings instead. Duplicate active records use the first valid match.
-
-Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:
+Optional local policy file:
+
+```json
+{
+  "ignoreRules": ["plugin.heuristic.description.too_long"],
+  "suppressions": [
+    {
+      "fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      "reason": "Accepted until the upstream package layout is corrected.",
+      "expiresAt": "2026-07-31"
+    }
+  ],
+  "failOnWarnings": true
+}
+```
+
+`ignoreRules` disables every finding with a matching rule ID. Prefer `suppressions` when accepting one specific finding instance: each record requires the exact 64-character lowercase SHA-256 fingerprint shown in Doctor reports, a non-empty review reason, and a real `YYYY-MM-DD` expiration date.
+
+Active suppressions remove only the matching finding from the active result and preserve it under `suppressedFindings` for audit output. Expired or invalid records do not suppress findings; Doctor emits `suppression.expired` or `suppression.invalid` warnings instead. Duplicate active records use the first valid match.
+
+### Manage suppressions
+
+```bash
+codex-plugin-doctor suppress add .
+codex-plugin-doctor suppress list .
+codex-plugin-doctor suppress remove .
+```
+
+Interactive add selects one active fingerprinted finding and defaults to an expiration 30 local calendar days from today. The stored `YYYY-MM-DD` record remains active through that UTC calendar date and expires at `00:00 UTC` on the following day. Suppressions match only the exact finding fingerprint; invalid or expired records never hide findings.
+
+For automation, supply all add fields or one remove selector and add `--json` when machine-readable output is required:
+
+```bash
+codex-plugin-doctor suppress add . --fingerprint <sha256> --reason "Accepted temporarily." --expires-at 2026-07-31 --json
+codex-plugin-doctor suppress list . --json
+codex-plugin-doctor suppress remove . --index 0 --json
+codex-plugin-doctor suppress remove . --fingerprint <sha256> --json
+```
+
+Run these when you want Codex Plugin Doctor to find plugins from the local Codex installation:
 
 ```bash
 codex-plugin-doctor list --installed
@@ -380,22 +399,22 @@ jobs:
   doctor:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.27.0
-        with:
-          version: "1.27.0"
+      - uses: actions/checkout@v5
+      - uses: Esquetta/CodexPluginDoctor@v1.28.0
+        with:
+          version: "1.28.0"
           path: .
-          runtime: "true"
-          policy: codex-publish
-          corpus: "true"
-          contract: "true"
-          upload-artifact: "true"
-          artifact-name: codex-plugin-doctor-reports
-          review-bundle: "true"
-          review-bundle-verify: "true"
-```
-
-The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional `validation-corpus.json`, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/engineering/github-action-usage.md).
+          runtime: "true"
+          policy: codex-publish
+          corpus: "true"
+          contract: "true"
+          upload-artifact: "true"
+          artifact-name: codex-plugin-doctor-reports
+          review-bundle: "true"
+          review-bundle-verify: "true"
+```
+
+The action writes `codex-plugin-doctor-summary.md`, `codex-plugin-doctor-report.json`, `codex-plugin-doctor-action-manifest.json`, optional `codex-plugin-doctor.sarif`, optional `validation-corpus.json`, optional `output-contract.json`, and optional signed `review-bundle/` files to `codex-plugin-doctor-reports`, appends the Markdown report to the GitHub Actions step summary, uploads the report directory as an artifact, and then returns the real validation exit code. Review bundle generation requires a signing key environment variable such as `CODEX_PLUGIN_DOCTOR_SIGNING_KEY`. For runtime probing, SARIF output, corpus and contract artifacts, review bundle artifacts, installed plugin cache checks, CI policy presets, and pinned release examples, see [GitHub Action Usage](./docs/guides/github-action.md).
 
 To self-test this repository after cloning it:
 
@@ -406,7 +425,7 @@ codex-plugin-doctor check examples/codex-doctor-runtime --runtime --no-animation
 ## Repository Layout
 
 ```text
-docs/                 Product, engineering, security, and release docs
+docs/                 Public architecture, guides, rules, security, and contributor docs
 examples/             Manual plugin packs for local CLI testing
 src/                  CLI, validation logic, runtime probing, reports
 tests/                Fixture-based regression tests
@@ -417,7 +436,7 @@ validation-sessions/  Real-world validation waves and tuning notes
 
 The validator is tuned against local fixtures and real marketplace-style plugin packages. See:
 
-- [Real-World Validation Workflow](./docs/engineering/real-world-validation-workflow.md)
+- [Real-World Validation Workflow](./docs/guides/real-world-validation.md)
 - [Validation Sessions](./validation-sessions/README.md)
 - [Examples](./examples/README.md)
 - [Rule Catalog](./docs/rules/catalog.md)
@@ -446,9 +465,9 @@ Related docs:
 - [Contributing](./CONTRIBUTING.md)
 - [Security Policy](./SECURITY.md)
 - [Code of Conduct](./CODE_OF_CONDUCT.md)
-- [NPM Release Checklist](./docs/engineering/npm-release-checklist.md)
-- [Release Candidate Workflow](./docs/engineering/release-candidate-workflow.md)
-- [v1.0 Readiness Checklist](./docs/engineering/v1.0-readiness-checklist.md)
+- [NPM Release Checklist](./docs/contributing/npm-release-checklist.md)
+- [Release Candidate Workflow](./docs/contributing/release-candidates.md)
+- [Versioning and Releases](./docs/contributing/releasing.md)
 
 ## Contributing
 

package/dist/core/doctor-config-store.d.ts

@@ -0,0 +1,12 @@
+import { rename as renameFile } from "node:fs/promises";
+export type RawDoctorConfig = Record<string, unknown>;
+export interface LoadedDoctorConfig {
+    configPath: string;
+    exists: boolean;
+    value: RawDoctorConfig;
+}
+export declare function resolveDoctorConfigPath(targetPath: string, explicitConfigPath?: string | null): string;
+export declare function readRawDoctorConfig(targetPath: string, explicitConfigPath?: string | null): Promise<LoadedDoctorConfig>;
+export declare function writeRawDoctorConfig(configPath: string, value: RawDoctorConfig, options?: {
+    rename?: typeof renameFile;
+}): Promise<void>;

package/dist/core/doctor-config-store.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, rename as renameFile, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { parseJsonText } from "./read-json-file.js";
+export function resolveDoctorConfigPath(targetPath, explicitConfigPath) {
+    return explicitConfigPath
+        ? path.resolve(explicitConfigPath)
+        : path.join(path.resolve(targetPath), ".codex-doctor.json");
+}
+function isRawDoctorConfig(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export async function readRawDoctorConfig(targetPath, explicitConfigPath) {
+    const configPath = resolveDoctorConfigPath(targetPath, explicitConfigPath);
+    try {
+        const parsed = parseJsonText(await readFile(configPath, "utf8"));
+        if (!isRawDoctorConfig(parsed)) {
+            throw new Error("Doctor config root must be a JSON object");
+        }
+        return {
+            configPath,
+            exists: true,
+            value: parsed
+        };
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return {
+                configPath,
+                exists: false,
+                value: {}
+            };
+        }
+        if (error instanceof SyntaxError) {
+            throw new Error(`Unable to parse Doctor config at ${configPath}: ${error.message}`, { cause: error });
+        }
+        throw error;
+    }
+}
+export async function writeRawDoctorConfig(configPath, value, options = {}) {
+    const rename = options.rename ?? renameFile;
+    const directoryPath = path.dirname(configPath);
+    const tempPath = path.join(directoryPath, `${path.basename(configPath)}.${process.pid}.${randomUUID()}.tmp`);
+    await mkdir(directoryPath, { recursive: true });
+    try {
+        await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+        await rename(tempPath, configPath);
+    }
+    catch (error) {
+        try {
+            await rm(tempPath, { force: true });
+        }
+        catch {
+            // Best effort cleanup should not replace the original failure.
+        }
+        throw error;
+    }
+}

package/dist/core/doctor-config.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { withFindingFingerprint } from "../reporting/finding-fingerprint.js";
+import { classifySuppressionRecord } from "./suppression-record.js";
 const defaultConfig = {
     ignoreRules: [],
     failOnWarnings: false,
@@ -42,28 +43,28 @@ export function applyDoctorConfig(result, config, options = {}) {
         invalid: 0
     };
     for (const [index, suppression] of config.suppressions.entries()) {
-        const validation = validateSuppression(suppression);
-        if (!validation.valid) {
+        const classified = classifySuppressionRecord(suppression, now);
+        if (classified.status === "invalid") {
             summary.invalid += 1;
             governanceWarnings.push(buildGovernanceWarning(result.targetPath, "suppression.invalid", "A targeted suppression record is invalid and was not applied.", "Invalid suppression records can create false confidence because they do not match or expire as intended.", "Fix or remove the invalid suppression record in `.codex-doctor.json`.", {
                 suppressionIndex: index,
-                field: validation.field
+                field: classified.field
             }));
             continue;
         }
-        if (isExpired(validation.expiresAt, now)) {
+        if (classified.status === "expired") {
             summary.expired += 1;
             governanceWarnings.push(buildGovernanceWarning(result.targetPath, "suppression.expired", "A targeted suppression has expired and was not applied.", "Expired risk acceptance must be reviewed again before the finding can be suppressed.", "Remove the expired suppression or replace it with a newly reviewed expiration date.", {
                 suppressionIndex: index,
-                fingerprint: validation.fingerprint,
-                expiresAt: validation.expiresAt
+                fingerprint: classified.fingerprint,
+                expiresAt: classified.expiresAt
             }));
             continue;
         }
-        if (!activeSuppressions.has(validation.fingerprint)) {
-            activeSuppressions.set(validation.fingerprint, {
-                reason: validation.reason,
-                expiresAt: validation.expiresAt
+        if (!activeSuppressions.has(classified.fingerprint)) {
+            activeSuppressions.set(classified.fingerprint, {
+                reason: classified.reason,
+                expiresAt: classified.expiresAt
             });
         }
     }
@@ -105,47 +106,6 @@ export function applyDoctorConfig(result, config, options = {}) {
             : {})
     };
 }
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isRealDate(value) {
-    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
-    if (!match) {
-        return false;
-    }
-    const year = Number(match[1]);
-    const month = Number(match[2]);
-    const day = Number(match[3]);
-    const date = new Date(Date.UTC(year, month - 1, day));
-    return (date.getUTCFullYear() === year &&
-        date.getUTCMonth() === month - 1 &&
-        date.getUTCDate() === day);
-}
-function validateSuppression(value) {
-    if (!isPlainObject(value)) {
-        return { valid: false, field: "record" };
-    }
-    if (typeof value.fingerprint !== "string" ||
-        !/^[a-f0-9]{64}$/.test(value.fingerprint)) {
-        return { valid: false, field: "fingerprint" };
-    }
-    if (typeof value.reason !== "string" || value.reason.trim().length === 0) {
-        return { valid: false, field: "reason" };
-    }
-    if (typeof value.expiresAt !== "string" || !isRealDate(value.expiresAt)) {
-        return { valid: false, field: "expiresAt" };
-    }
-    return {
-        valid: true,
-        fingerprint: value.fingerprint,
-        reason: value.reason.trim(),
-        expiresAt: value.expiresAt
-    };
-}
-function isExpired(expiresAt, now) {
-    const expirationBoundary = Date.parse(`${expiresAt}T00:00:00.000Z`) + 86_400_000;
-    return now.getTime() >= expirationBoundary;
-}
 function buildGovernanceWarning(targetPath, id, message, impact, suggestedFix, evidence) {
     return withFindingFingerprint({
         id,

package/dist/core/npm-package-doctor.js

@@ -16,6 +16,13 @@ function npmCommand(args) {
     }
     return { command: "npm", args };
 }
+function npmPackEnvironment() {
+    const environment = Object.fromEntries(Object.entries(process.env).filter(([key]) => key.toLowerCase() !== "npm_config_dry_run"));
+    return {
+        ...environment,
+        npm_config_dry_run: "false"
+    };
+}
 function isPathWithinRoot(rootPath, candidatePath) {
     const relativePath = path.relative(rootPath, candidatePath);
     return (relativePath === "" ||
@@ -96,6 +103,7 @@ async function packNpmPackage(packageSpec, destinationPath) {
     ]);
     const { stdout } = await execFileAsync(npmPackCommand.command, npmPackCommand.args, {
         cwd: destinationPath,
+        env: npmPackEnvironment(),
         maxBuffer: 10 * 1024 * 1024
     });
     const packEntries = JSON.parse(stdout);

package/dist/core/output-contract.js

@@ -55,6 +55,24 @@ const publicSchemaDefinitions = [
         outputKind: "doctor.git.hooks",
         required: ["schemaVersion", "kind", "rootPath", "hookPaths", "preExisting"]
     },
+    {
+        id: "doctor.suppress.add.json",
+        command: "codex-plugin-doctor suppress add <path> --fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD --json",
+        outputKind: "doctor.suppress.add",
+        required: ["schemaVersion", "kind", "command", "configPath", "index", "suppression"]
+    },
+    {
+        id: "doctor.suppress.list.json",
+        command: "codex-plugin-doctor suppress list <path> --json",
+        outputKind: "doctor.suppress.list",
+        required: ["schemaVersion", "kind", "command", "configPath", "suppressions"]
+    },
+    {
+        id: "doctor.suppress.remove.json",
+        command: "codex-plugin-doctor suppress remove <path> --index <n> --json",
+        outputKind: "doctor.suppress.remove",
+        required: ["schemaVersion", "kind", "command", "configPath", "index", "suppression"]
+    },
     {
         id: "doctor.history.json",
         command: "codex-plugin-doctor history <history.jsonl> --json",

package/dist/core/suppression-management.d.ts

@@ -0,0 +1,34 @@
+import type { RawDoctorConfig } from "./doctor-config-store.js";
+import { type SuppressionRecordField } from "./suppression-record.js";
+export interface ManagedSuppressionRecord {
+    index: number;
+    status: "active" | "expired" | "invalid";
+    fingerprint?: string;
+    reason?: string;
+    expiresAt?: string;
+    invalidField?: SuppressionRecordField;
+}
+export interface SuppressionMutationResult {
+    config: RawDoctorConfig;
+    index: number;
+    suppression: unknown;
+}
+export type SuppressionManagementErrorCode = "suppression_non_array" | "suppression_invalid_record" | "suppression_duplicate_fingerprint" | "suppression_invalid_index" | "suppression_invalid_fingerprint" | "suppression_fingerprint_not_found" | "suppression_fingerprint_ambiguous";
+type SuppressionManagementErrorDetails = {
+    code: SuppressionManagementErrorCode;
+    field?: SuppressionRecordField;
+    index?: number;
+    indexes?: number[];
+};
+export declare class SuppressionManagementError extends Error {
+    readonly code: SuppressionManagementErrorCode;
+    readonly field?: SuppressionRecordField;
+    readonly index?: number;
+    readonly indexes?: number[];
+    constructor(message: string, details: SuppressionManagementErrorDetails);
+}
+export declare function listSuppressions(config: RawDoctorConfig, now?: Date): ManagedSuppressionRecord[];
+export declare function addSuppression(config: RawDoctorConfig, record: unknown): SuppressionMutationResult;
+export declare function removeSuppressionByIndex(config: RawDoctorConfig, index: number): SuppressionMutationResult;
+export declare function removeSuppressionByFingerprint(config: RawDoctorConfig, fingerprint: string): SuppressionMutationResult;
+export {};