plugin-scanner 2.0.107__tar.gz → 2.0.109__tar.gz

{plugin_scanner-2.0.107 → plugin_scanner-2.0.109}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.107
+Version: 2.0.109
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner
@@ -302,33 +302,44 @@ The scanner evaluates only the surfaces a plugin actually exposes, then normaliz
 
 ```bash
 # Scan a plugin directory
-plugin-scanner ./my-plugin
+plugin-scanner scan ./my-plugin
 
 # Auto-detect all supported ecosystems inside a repo (default)
-plugin-scanner ./plugins-repo --ecosystem auto
+plugin-scanner scan ./plugins-repo --ecosystem auto
 
 # Scan only Claude package surfaces
-plugin-scanner ./plugins-repo --ecosystem claude
+plugin-scanner scan ./plugins-repo --ecosystem claude
 
 # List supported ecosystems
 plugin-scanner --list-ecosystems
 
 # Output JSON
-plugin-scanner ./my-plugin --json
+plugin-scanner scan ./my-plugin --format json
 
 # Write a SARIF report for GitHub code scanning
-plugin-scanner ./my-plugin --format sarif --output plugin-scanner.sarif
+plugin-scanner scan ./my-plugin --format sarif --output plugin-scanner.sarif
 
 # Fail CI on findings at or above high severity
-plugin-scanner ./my-plugin --fail-on-severity high
+plugin-scanner scan ./my-plugin --fail-on-severity high
 
 # Require Cisco skill scanning with a strict policy
-plugin-scanner ./my-plugin --cisco-skill-scan on --cisco-policy strict
+plugin-scanner scan ./my-plugin --cisco-skill-scan on --cisco-policy strict
 
 # Require optional Cisco MCP static analysis
-plugin-scanner ./my-plugin --cisco-mcp-scan on
+plugin-scanner scan ./my-plugin --cisco-mcp-scan on
 ```
 
+Use the bare `plugin-scanner ./my-plugin` form only for compatibility with older automation. New scripts and docs should
+prefer explicit subcommands so `scan`, `lint`, `verify`, `submit`, and `doctor` have predictable help, flags, and output.
+
+| Need | Command | Output contract |
+| :--- | :--- | :--- |
+| Human release summary | `plugin-scanner scan ./my-plugin` | terminal summary first, optional JSON/Markdown/SARIF with `--format` |
+| Rule-level authoring feedback | `plugin-scanner lint ./my-plugin` | human findings by default, JSON with `--format json` |
+| Runtime readiness details | `plugin-scanner verify ./my-plugin` | human pass/fail by default, JSON with `--format json` |
+| Publishable quality artifact | `plugin-scanner submit ./my-plugin --attest dist/plugin-quality.json` | writes one artifact for one plugin directory |
+| Troubleshooting bundle | `plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip` | diagnostic JSON and bundle artifacts |
+
 ## Quality Suite Commands
 
 ```bash

{plugin_scanner-2.0.107 → plugin_scanner-2.0.109}/README.md

@@ -262,33 +262,44 @@ The scanner evaluates only the surfaces a plugin actually exposes, then normaliz
 
 ```bash
 # Scan a plugin directory
-plugin-scanner ./my-plugin
+plugin-scanner scan ./my-plugin
 
 # Auto-detect all supported ecosystems inside a repo (default)
-plugin-scanner ./plugins-repo --ecosystem auto
+plugin-scanner scan ./plugins-repo --ecosystem auto
 
 # Scan only Claude package surfaces
-plugin-scanner ./plugins-repo --ecosystem claude
+plugin-scanner scan ./plugins-repo --ecosystem claude
 
 # List supported ecosystems
 plugin-scanner --list-ecosystems
 
 # Output JSON
-plugin-scanner ./my-plugin --json
+plugin-scanner scan ./my-plugin --format json
 
 # Write a SARIF report for GitHub code scanning
-plugin-scanner ./my-plugin --format sarif --output plugin-scanner.sarif
+plugin-scanner scan ./my-plugin --format sarif --output plugin-scanner.sarif
 
 # Fail CI on findings at or above high severity
-plugin-scanner ./my-plugin --fail-on-severity high
+plugin-scanner scan ./my-plugin --fail-on-severity high
 
 # Require Cisco skill scanning with a strict policy
-plugin-scanner ./my-plugin --cisco-skill-scan on --cisco-policy strict
+plugin-scanner scan ./my-plugin --cisco-skill-scan on --cisco-policy strict
 
 # Require optional Cisco MCP static analysis
-plugin-scanner ./my-plugin --cisco-mcp-scan on
+plugin-scanner scan ./my-plugin --cisco-mcp-scan on
 ```
 
+Use the bare `plugin-scanner ./my-plugin` form only for compatibility with older automation. New scripts and docs should
+prefer explicit subcommands so `scan`, `lint`, `verify`, `submit`, and `doctor` have predictable help, flags, and output.
+
+| Need | Command | Output contract |
+| :--- | :--- | :--- |
+| Human release summary | `plugin-scanner scan ./my-plugin` | terminal summary first, optional JSON/Markdown/SARIF with `--format` |
+| Rule-level authoring feedback | `plugin-scanner lint ./my-plugin` | human findings by default, JSON with `--format json` |
+| Runtime readiness details | `plugin-scanner verify ./my-plugin` | human pass/fail by default, JSON with `--format json` |
+| Publishable quality artifact | `plugin-scanner submit ./my-plugin --attest dist/plugin-quality.json` | writes one artifact for one plugin directory |
+| Troubleshooting bundle | `plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip` | diagnostic JSON and bundle artifacts |
+
 ## Quality Suite Commands
 
 ```bash

{plugin_scanner-2.0.107 → plugin_scanner-2.0.109}/docs/guard/get-started.md

@@ -76,6 +76,30 @@ Use it when you want to protect a harness before local MCP servers, skills, hook
    hol-guard device rotate
    ```
 
+## Which command should I use?
+
+| Situation | Command | What it answers |
+| :--- | :--- | :--- |
+| I need the current protection posture | `hol-guard status` | What is Guard watching, is sync connected, and what is the next action? |
+| I need setup or runtime troubleshooting | `hol-guard doctor <harness>` | Why is this harness or Guard runtime not behaving correctly? |
+| A launch was blocked or changed | `hol-guard diff <harness>` | What changed since the last recorded snapshot? |
+| I need to resolve a queued block | `hol-guard approvals` | Which requests are waiting, and how do I approve or deny them? |
+| I need decision history | `hol-guard receipts` | What decisions did Guard record locally? |
+| I need the tracked catalog | `hol-guard inventory` | Which artifacts are currently tracked and present? |
+| I need an exportable evidence artifact | `hol-guard abom` | What local AI-BOM can I attach to an audit or handoff? |
+| I need the chronological log | `hol-guard events` | What happened over time on this machine? |
+
+## Troubleshooting
+
+| Symptom | Start here | Then try |
+| :--- | :--- | :--- |
+| Guard did not find my harness | `hol-guard detect --json` | `hol-guard doctor <harness> --json` for adapter-specific warnings |
+| `hol-guard run` paused a launch | `hol-guard diff <harness>` | `hol-guard approvals`, then retry `hol-guard run <harness>` |
+| I approved a prompt and want proof | `hol-guard receipts` | `hol-guard explain <artifact-id>` for the latest receipt and diff context |
+| I need audit or handoff evidence | `hol-guard inventory` | `hol-guard abom --format json` for machine-readable export |
+| I need to understand recent activity | `hol-guard events` | Use `--name <event>` to filter a noisy local timeline |
+| Cloud sync or pairing looks wrong | `hol-guard status` | `hol-guard connect` or `hol-guard sync --json` depending on the status output |
+
 ## Evidence-first decisions
 
 Guard now scores local decisions from structured evidence, not only string heuristics. Each changed artifact carries:

{plugin_scanner-2.0.107 → plugin_scanner-2.0.109}/docs/guard/testing-matrix.md

@@ -10,6 +10,8 @@ Automated coverage in this phase includes:
 - consumer-mode JSON contract generation against scanner fixtures
 - local HTTP sync against a live in-process server instead of mocked transport
 - scheduled self-hosted harness smoke through `.github/workflows/harness-smoke.yml`
+- CLI DX contract tests for summary-first `run`, `explain`, `doctor`, `scan`, `lint`, and `verify` output
+- scanner command consistency tests for nonexistent target handling across `scan`, `lint`, `verify`, `doctor`, and `submit`
 
 Manual verification should include:
 
@@ -32,6 +34,14 @@ Manual verification should include:
 - `hol-guard install codex`
 - `hol-guard run codex --dry-run --default-action allow --json`
 - `hol-guard receipts`
+- `hol-guard explain codex:project:<artifact-name>`
+- `hol-guard diff codex`
+- `hol-guard events`
+- `hol-guard abom`
+- `plugin-scanner scan tests/fixtures/good-plugin --format json`
+- `plugin-scanner lint tests/fixtures/good-plugin --format json`
+- `plugin-scanner verify tests/fixtures/good-plugin --format json`
+- `plugin-scanner doctor tests/fixtures/good-plugin --component mcp --bundle dist/doctor.zip`
 - `codex mcp list`
 - `cursor-agent mcp list`
 - `antigravity --help`

{plugin_scanner-2.0.107 → plugin_scanner-2.0.109}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.107"
+version = "2.0.109"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.107 → plugin_scanner-2.0.109}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.107"
+version = "2.0.109"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.107 → plugin_scanner-2.0.109}/src/codex_plugin_scanner/guard/cli/commands.py

@@ -97,6 +97,7 @@ from ..runtime.secret_file_requests import (
     extract_sensitive_tool_action_request,
     is_explicitly_benign_tool_action_request,
 )
+from ..runtime.secret_sensitivity import SecretContentMatch, classify_secret_content
 from ..runtime.surface_server import GuardSurfaceRuntime
 from ..store import GuardStore
 from .approval_commands import add_approval_parser, run_approval_command
@@ -149,7 +150,15 @@ _GUARD_HELP_GROUPS = (
     "  bootstrap    Detect, install, and launch the approval center\n"
     "  install      Enable Guard management for a harness\n"
     "  uninstall    Disable Guard management for a harness\n"
-    "  update       Update hol-guard in the current environment"
+    "  update       Update hol-guard in the current environment\n"
+    "\n"
+    "Command selection:\n"
+    "  Use status for current posture and the next safe step\n"
+    "  Use doctor for setup and runtime probes\n"
+    "  Use diff for changed artifacts after a blocked launch\n"
+    "  Use explain for detailed artifact evidence\n"
+    "  Use approvals for queued decisions and receipts for audit history\n"
+    "  Use events for the local timeline"
 )
 
 
@@ -3962,10 +3971,6 @@ def _hook_runtime_artifact(
     )
 
 
-_CODEX_SECRET_OUTPUT_PATTERN = re.compile(
-    r"(?i)(?:fake[_-]?credential|fake[_-]?secret|"
-    r"(?:api[_-]?key|auth[_-]?token|credential|npm[_-]?token|private[_-]?key|secret|token|password)\s*[:=])"
-)
 _CODEX_PROMPT_SECRET_KEY_MARKERS = ("TOKEN", "SECRET", "PASSWORD", "PASS", "API_KEY", "API-KEY", "AUTH", "CREDENTIAL")
 _CODEX_TOOL_RESPONSE_MAX_DEPTH = 5
 _CODEX_TOOL_RESPONSE_TEXT_LIMIT = 20000
@@ -3980,13 +3985,19 @@ def _codex_post_tool_output_artifact(
     cwd: Path | None,
 ) -> GuardArtifact | None:
     response_text = _collect_codex_tool_response_text(payload.get("tool_response"))
-    if not response_text or _CODEX_SECRET_OUTPUT_PATTERN.search(response_text) is None:
+    content_matches = classify_secret_content(response_text)
+    if not content_matches:
         return None
     tool_name = _coalesce_string(payload.get("tool_name"), "Bash")
     command_text = _codex_post_tool_command_text(payload)
     if not command_text:
         command_text = tool_name
-    if _codex_command_is_read_only_source_inspection(command_text, cwd=cwd):
+    if _codex_source_inspection_can_skip_secret_output(
+        command_text=command_text,
+        response_text=response_text,
+        content_matches=content_matches,
+        cwd=cwd,
+    ):
         return None
     fingerprint = hashlib.sha256(
         json.dumps(
@@ -4109,6 +4120,10 @@ _CODEX_SOURCE_SEARCH_EXTENSIONS = frozenset(
         ".yml",
     }
 )
+_CODEX_BENIGN_SOURCE_DOTFILES = frozenset({".nvmrc"})
+_CODEX_BENIGN_SECRET_FIXTURE_ASSIGNMENT_PATTERN = re.compile(
+    r"(?i)\s*fake[_-]?(?:credential|secret|token)\s*[:=]\s*(?:\"[^\r\n\"]+\"|'[^\r\n']+'|[^\s\"',}]+)\s*"
+)
 _CODEX_SENSITIVE_SEARCH_BASENAMES = frozenset(
     {
         ".aws",
@@ -4127,6 +4142,35 @@ _CODEX_SENSITIVE_SEARCH_BASENAMES = frozenset(
 _CODEX_SED_PRINT_SCRIPT_PATTERN = re.compile(r"^\s*(?:\$|\d+)?(?:\s*,\s*(?:\$|\d+))?p\s*$")
 
 
+def _codex_source_inspection_can_skip_secret_output(
+    *,
+    command_text: str,
+    response_text: str,
+    content_matches: tuple[SecretContentMatch, ...],
+    cwd: Path | None,
+) -> bool:
+    if not _codex_command_is_read_only_source_inspection(command_text, cwd=cwd):
+        return False
+    if any(match.sensitivity != "medium" for match in content_matches):
+        return False
+    if _codex_command_references_benign_source_dotfile(command_text):
+        return _codex_output_is_only_benign_secret_fixture(response_text)
+    return True
+
+
+def _codex_output_is_only_benign_secret_fixture(response_text: str) -> bool:
+    lines = [line for line in response_text.splitlines() if line.strip()]
+    return bool(lines) and all(_CODEX_BENIGN_SECRET_FIXTURE_ASSIGNMENT_PATTERN.fullmatch(line) for line in lines)
+
+
+def _codex_command_references_benign_source_dotfile(command_text: str) -> bool:
+    try:
+        parts = shlex.split(command_text)
+    except ValueError:
+        return False
+    return any(Path(part).name.lower() in _CODEX_BENIGN_SOURCE_DOTFILES for part in parts)
+
+
 def _codex_command_is_read_only_source_inspection(command_text: str, *, cwd: Path | None) -> bool:
     command = command_text.strip()
     if not command:
@@ -4644,13 +4688,16 @@ def _codex_search_target_is_source_like(target: str, *, cwd: Path | None) -> boo
     lowered_parts = [part.lower() for part in parts]
     if any(part in _CODEX_SENSITIVE_SEARCH_BASENAMES for part in lowered_parts):
         return False
-    if any(part.startswith(".") for part in parts):
+    hidden_parts = [part for part in lowered_parts if part.startswith(".")]
+    if hidden_parts and not all(part in _CODEX_BENIGN_SOURCE_DOTFILES for part in hidden_parts):
         return False
     normalized = "/".join(parts)
     if normalized in {prefix.rstrip("/") for prefix in _CODEX_SOURCE_SEARCH_PREFIXES}:
         return True
     if any(normalized.startswith(prefix) for prefix in _CODEX_SOURCE_SEARCH_PREFIXES):
         return True
+    if Path(stripped).name.lower() in _CODEX_BENIGN_SOURCE_DOTFILES:
+        return True
     return Path(stripped).suffix.lower() in _CODEX_SOURCE_SEARCH_EXTENSIONS
 
 
@@ -4745,7 +4792,7 @@ def _codex_prompt_credential_file_artifact(
                 content = handle.read(_PROMPT_CONTENT_SCAN_MAX_BYTES).decode("utf-8", errors="ignore")
         except OSError:
             continue
-        if _CODEX_SECRET_OUTPUT_PATTERN.search(content) is None:
+        if not classify_secret_content(content):
             continue
         normalized_path = str(path)
         fingerprint = hashlib.sha256(

{plugin_scanner-2.0.107 → plugin_scanner-2.0.109}/src/codex_plugin_scanner/guard/cli/render.py

@@ -285,37 +285,37 @@ def _render_doctor(console: Console, payload: dict[str, object]) -> None:
         )
         adapters = _coerce_dict_list(payload.get("adapters"))
         console.print(_build_harness_table(adapters))
-        return
-
-    warnings = _coerce_string_list(payload.get("warnings"))
-    summary = Table.grid(padding=(0, 1))
-    summary.add_row("Harness", f"[bold]{payload.get('harness', 'unknown')}[/bold]")
-    summary.add_row("Installed", _bool_label(bool(payload.get("installed"))))
-    summary.add_row("Command", _bool_label(bool(payload.get("command_available"))))
-    summary.add_row("Artifacts", str(len(_coerce_dict_list(payload.get("artifacts")))))
-    registry = payload.get("runtime_detector_registry")
-    if isinstance(registry, dict):
-        registry_state = "enabled" if bool(registry.get("enabled")) else "disabled"
-        timeout_ms = registry.get("timeout_ms")
-        summary.add_row("Detector registry", f"{registry_state}, {timeout_ms} ms")
-    summary.add_row("Warnings", str(len(warnings)))
-    console.print(Panel(summary, title="Guard doctor", border_style="cyan"))
-    if warnings:
-        warning_text = "\n".join(
-            textwrap.fill(
-                f"• {warning}",
-                width=72,
-                subsequent_indent="  ",
+    else:
+        warnings = _coerce_string_list(payload.get("warnings"))
+        summary = Table.grid(padding=(0, 1))
+        summary.add_row("Harness", f"[bold]{payload.get('harness', 'unknown')}[/bold]")
+        summary.add_row("Installed", _bool_label(bool(payload.get("installed"))))
+        summary.add_row("Command", _bool_label(bool(payload.get("command_available"))))
+        summary.add_row("Artifacts", str(len(_coerce_dict_list(payload.get("artifacts")))))
+        registry = payload.get("runtime_detector_registry")
+        if isinstance(registry, dict):
+            registry_state = "enabled" if bool(registry.get("enabled")) else "disabled"
+            timeout_ms = registry.get("timeout_ms")
+            summary.add_row("Detector registry", f"{registry_state}, {timeout_ms} ms")
+        summary.add_row("Warnings", str(len(warnings)))
+        console.print(Panel(summary, title="Guard doctor", border_style="cyan"))
+        if warnings:
+            warning_text = "\n".join(
+                textwrap.fill(
+                    f"• {warning}",
+                    width=72,
+                    subsequent_indent="  ",
+                )
+                for warning in warnings
             )
-            for warning in warnings
-        )
-        console.print(Panel(Text(warning_text), title="Attention", border_style="yellow"))
-    runtime_probe = payload.get("runtime_probe")
-    if isinstance(runtime_probe, dict):
-        console.print(_build_runtime_probe_panel(runtime_probe))
-    artifacts = _coerce_dict_list(payload.get("artifacts"))
-    if artifacts:
-        console.print(_build_artifact_table(artifacts))
+            console.print(Panel(Text(warning_text), title="Attention", border_style="yellow"))
+        runtime_probe = payload.get("runtime_probe")
+        if isinstance(runtime_probe, dict):
+            console.print(_build_runtime_probe_panel(runtime_probe))
+        artifacts = _coerce_dict_list(payload.get("artifacts"))
+        if artifacts:
+            console.print(_build_artifact_table(artifacts))
+    console.print(_build_diagnostic_command_panel())
 
 
 def _render_run(console: Console, payload: dict[str, object]) -> None:
@@ -481,7 +481,11 @@ def _render_advisories(console: Console, payload: dict[str, object]) -> None:
             border_style="cyan",
         )
     )
-    table = Table(box=box.SIMPLE_HEAVY, show_header=True)
+    console.print(_build_advisory_table(items))
+
+
+def _build_advisory_table(items: list[dict[str, object]], *, title: str | None = None) -> Table:
+    table = Table(title=title, box=box.SIMPLE_HEAVY, show_header=True)
     table.add_column("Publisher", style="bold")
     table.add_column("Severity")
     table.add_column("Headline")
@@ -493,7 +497,7 @@ def _render_advisories(console: Console, payload: dict[str, object]) -> None:
             str(item.get("headline") or item.get("cache_key") or "advisory"),
             str(item.get("updated_at") or "unknown"),
         )
-    console.print(table)
+    return table
 
 
 def _render_events(console: Console, payload: dict[str, object]) -> None:
@@ -1077,6 +1081,40 @@ def _render_scan(console: Console, payload: dict[str, object]) -> None:
     _render_cisco_evidence(console, payload)
 
 
+def _render_explain(console: Console, payload: dict[str, object]) -> None:
+    advisories = _coerce_dict_list(payload.get("advisories"))
+    if "artifact_snapshot" in payload:
+        console.print(Panel(_build_consumer_summary_table(payload), title="Path evidence", border_style="cyan"))
+        _render_consumer_evidence_panels(console, payload)
+        _render_cisco_evidence(console, payload)
+        if advisories:
+            console.print(_build_advisory_table(advisories, title="Matching advisories"))
+        return
+    artifact = payload.get("artifact")
+    if not isinstance(artifact, dict):
+        _render_fallback(console, payload)
+        return
+    latest_receipt = payload.get("latest_receipt")
+    latest_diff = payload.get("latest_diff")
+    body = Table.grid(padding=(0, 1))
+    body.add_row("Artifact", str(artifact.get("artifact_name") or artifact.get("artifact_id") or "unknown"))
+    body.add_row("Harness", str(artifact.get("harness") or "unknown"))
+    body.add_row("Type", str(artifact.get("artifact_type") or "artifact"))
+    body.add_row("Scope", str(artifact.get("source_scope") or "unknown"))
+    body.add_row("Present", _bool_label(bool(artifact.get("present"))))
+    if isinstance(latest_receipt, dict):
+        body.add_row("Latest decision", _action_text(str(latest_receipt.get("policy_decision") or "warn")))
+        body.add_row("Receipt time", str(latest_receipt.get("timestamp") or "unknown"))
+    if isinstance(latest_diff, dict):
+        changed_fields = ", ".join(_coerce_string_list(latest_diff.get("changed_fields"))) or "no field changes"
+        body.add_row("Latest diff", changed_fields)
+        body.add_row("Current hash", str(latest_diff.get("current_hash") or "unknown"))
+    body.add_row("Advisories", str(len(advisories)))
+    console.print(Panel(body, title="Guard artifact evidence", border_style="cyan"))
+    if advisories:
+        console.print(_build_advisory_table(advisories, title="Matching advisories"))
+
+
 def _render_preflight(console: Console, payload: dict[str, object]) -> None:
     install_verdict = payload.get("install_verdict")
     install_target = payload.get("install_target")
@@ -1209,6 +1247,21 @@ def _build_steps_panel(steps: list[dict[str, object]]) -> Panel:
     return Panel("\n\n".join(lines), title="Next steps", border_style="green")
 
 
+def _build_diagnostic_command_panel() -> Panel:
+    return Panel(
+        "\n".join(
+            (
+                "Use status for current posture: hol-guard status",
+                "Use doctor for setup and runtime probes: hol-guard doctor <harness>",
+                "Use diff for changed artifacts: hol-guard diff <harness>",
+                "Use events for the local timeline: hol-guard events",
+            )
+        ),
+        title="Which diagnostic command?",
+        border_style="blue",
+    )
+
+
 def _render_harness_detail(console: Console, detection: dict[str, object]) -> None:
     artifacts = _coerce_dict_list(detection.get("artifacts"))
     warnings = _coerce_string_list(detection.get("warnings"))
@@ -1308,13 +1361,7 @@ def _build_run_steps(payload: dict[str, object], *, blocked: bool, dry_run: bool
     approvals_command = payload.get("approvals_command")
     if blocked and dry_run:
         review_command = (
-            str(approvals_command)
-            if approval_center_url and isinstance(approvals_command, str) and approvals_command
-            else "hol-guard approvals"
-            if approval_center_url
-            else str(rerun_command)
-            if isinstance(rerun_command, str) and rerun_command
-            else f"hol-guard run {harness}"
+            str(rerun_command) if isinstance(rerun_command, str) and rerun_command else f"hol-guard run {harness}"
         )
         inspect_command = (
             str(diff_command) if isinstance(diff_command, str) and diff_command else f"hol-guard diff {harness}"
@@ -1324,12 +1371,29 @@ def _build_run_steps(payload: dict[str, object], *, blocked: bool, dry_run: bool
             if isinstance(review_hint, str) and review_hint
             else "Rerun without --dry-run to review the full blocker set and continue into the harness launch."
         )
-        return [
+        steps = [
             {
                 "title": "Resolve the blocked launch",
                 "command": review_command,
                 "detail": review_detail,
             },
+        ]
+        if approval_center_url:
+            approval_command = (
+                str(approvals_command)
+                if isinstance(approvals_command, str) and approvals_command
+                else "hol-guard approvals"
+            )
+            steps.append(
+                {
+                    "title": "Open the approvals queue",
+                    "command": approval_command,
+                    "detail": (
+                        "Review any queued approval requests after the prompt appears, then retry the guarded command."
+                    ),
+                }
+            )
+        steps.append(
             {
                 "title": "Inspect only the changed config entries (optional)",
                 "command": inspect_command,
@@ -1338,17 +1402,19 @@ def _build_run_steps(payload: dict[str, object], *, blocked: bool, dry_run: bool
                     "Guard still needs you to review."
                 ),
             },
-        ]
-    if blocked and isinstance(review_hint, str) and review_hint:
-        command = (
-            str(approvals_command)
-            if approval_center_url and isinstance(approvals_command, str) and approvals_command
-            else "hol-guard approvals"
-            if approval_center_url
-            else str(rerun_command)
-            if isinstance(rerun_command, str) and rerun_command
-            else f"hol-guard run {harness}"
         )
+        return steps
+    if blocked and isinstance(review_hint, str) and review_hint:
+        if approval_center_url:
+            command = (
+                str(approvals_command)
+                if isinstance(approvals_command, str) and approvals_command
+                else "hol-guard approvals"
+            )
+        elif isinstance(rerun_command, str) and rerun_command:
+            command = str(rerun_command)
+        else:
+            command = f"hol-guard run {harness}"
         return [{"title": "Resolve the blocked launch", "command": command, "detail": review_hint}]
     if dry_run:
         launch_command = (
@@ -1749,5 +1815,5 @@ _RENDERERS: dict[str, Any] = {
     "protect": _render_protect,
     "preflight": _render_preflight,
     "scan": _render_scan,
-    "explain": _render_scan,
+    "explain": _render_explain,
 }