plugin-scanner 2.0.3__tar.gz → 2.0.4__tar.gz

plugin_scanner-2.0.4/.github/dependabot.yml

@@ -0,0 +1,59 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "05:00"
+      timezone: "America/New_York"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "python"
+    commit-message:
+      prefix: "deps(pip)"
+    groups:
+      pip-patch-minor:
+        update-types:
+          - "minor"
+          - "patch"
+      pip-major:
+        update-types:
+          - "major"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "05:15"
+      timezone: "America/New_York"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "deps(actions)"
+    groups:
+      github-actions-all:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "05:30"
+      timezone: "America/New_York"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "docker"
+    commit-message:
+      prefix: "deps(docker)"
+    groups:
+      docker-all:
+        patterns:
+          - "*"

{plugin_scanner-2.0.3 → plugin_scanner-2.0.4}/.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: ${{ matrix.python-version }}
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
         with:
           enable-cache: true
       - run: uv sync --frozen --extra dev --python ${{ matrix.python-version }}
@@ -38,7 +38,7 @@ jobs:
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: ${{ matrix.python-version }}
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
         with:
           enable-cache: true
       - run: uv sync --frozen --extra dev --python ${{ matrix.python-version }}

{plugin_scanner-2.0.3 → plugin_scanner-2.0.4}/.github/workflows/codeql.yml

@@ -31,11 +31,11 @@ jobs:
           LEGACY_ROOT="/home/runner/work/codex-plugin-scanner"
           mkdir -p "$LEGACY_ROOT"
           ln -sfn "$GITHUB_WORKSPACE" "$LEGACY_ROOT/codex-plugin-scanner"
-      - uses: github/codeql-action/init@51f77329afa6477de8c49fc9c7046c15b9a4e79d
+      - uses: github/codeql-action/init@c10b8064de6f491fea524254123dbe5e09572f13
         with:
           languages: ${{ matrix.language }}
           build-mode: none
           source-root: .
-      - uses: github/codeql-action/analyze@51f77329afa6477de8c49fc9c7046c15b9a4e79d
+      - uses: github/codeql-action/analyze@c10b8064de6f491fea524254123dbe5e09572f13
         with:
           category: /language:${{ matrix.language }}

plugin_scanner-2.0.4/.github/workflows/dependabot-uv-lock.yml

@@ -0,0 +1,54 @@
+name: Dependabot Lockfile Sync
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+    paths:
+      - "pyproject.toml"
+      - "requirements.txt"
+      - "docker-requirements.txt"
+      - ".github/dependabot.yml"
+
+permissions:
+  contents: write
+
+jobs:
+  sync-lockfile:
+    if: github.actor == 'dependabot[bot]' && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.ref }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+        with:
+          enable-cache: true
+
+      - name: Refresh lockfile
+        run: uv lock --no-build
+
+      - name: Commit lockfile updates
+        run: |
+          if git diff --quiet -- uv.lock; then
+            echo "uv.lock unchanged"
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add uv.lock
+          git commit -m "chore: sync uv.lock for dependabot"
+          git push

plugin_scanner-2.0.4/.github/workflows/harness-smoke.yml

@@ -0,0 +1,114 @@
+name: Guard Harness Smoke
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 7 * * *"
+
+permissions:
+  contents: read
+
+jobs:
+  codex-release-gate:
+    name: Codex release gate
+    runs-on:
+      - self-hosted
+      - linux
+      - guard
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+        with:
+          enable-cache: true
+      - name: Prepare Guard environment
+        run: |
+          uv sync --frozen --extra dev
+          mkdir -p .guard-ci/codex-home/.codex .guard-ci/codex-workspace/.codex
+          cat > .guard-ci/codex-home/.codex/config.toml <<'EOF'
+          [mcp_servers.global_tools]
+          command = "python3"
+          args = ["-m", "http.server", "9000"]
+          EOF
+          cat > .guard-ci/codex-workspace/.codex/config.toml <<'EOF'
+          [mcp_servers.workspace_skill]
+          command = "node"
+          args = ["workspace-skill.js"]
+          EOF
+      - name: Guard detect and install for Codex
+        run: |
+          uv run hol-guard detect codex --home .guard-ci/codex-home --workspace .guard-ci/codex-workspace --json
+          uv run hol-guard install codex --home .guard-ci/codex-home --workspace .guard-ci/codex-workspace --json
+          uv run hol-guard run codex --home .guard-ci/codex-home --workspace .guard-ci/codex-workspace --dry-run --default-action allow --json
+      - name: Verify Codex runtime is available
+        run: |
+          command -v codex
+          codex mcp list
+
+  macos-release-gate:
+    name: Claude or Cursor release gate
+    runs-on:
+      - self-hosted
+      - macOS
+      - guard
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+        with:
+          enable-cache: true
+      - name: Prepare Guard environment
+        run: uv sync --frozen --extra dev
+      - name: Guard detect for Claude Code
+        run: uv run hol-guard detect claude-code --json
+      - name: Guard detect for Cursor
+        run: uv run hol-guard detect cursor --json
+      - name: Verify Claude Code or Cursor runtime
+        run: |
+          if command -v claude >/dev/null 2>&1; then
+            claude --help >/dev/null
+            exit 0
+          fi
+          command -v cursor-agent
+          cursor-agent mcp list
+
+  windows-release-gate:
+    name: Gemini or OpenCode release gate
+    runs-on:
+      - self-hosted
+      - windows
+      - guard
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+        with:
+          enable-cache: true
+      - name: Prepare Guard environment
+        shell: pwsh
+        run: uv sync --frozen --extra dev
+      - name: Guard detect for Gemini
+        shell: pwsh
+        run: uv run hol-guard detect gemini --json
+      - name: Guard detect for OpenCode
+        shell: pwsh
+        run: uv run hol-guard detect opencode --json
+      - name: Verify Gemini or OpenCode runtime
+        shell: pwsh
+        run: |
+          $gemini = Get-Command gemini -ErrorAction SilentlyContinue
+          if ($null -ne $gemini) {
+            gemini --help | Out-Null
+            exit 0
+          }
+          $opencode = Get-Command opencode -ErrorAction SilentlyContinue
+          if ($null -eq $opencode) {
+            throw "Expected gemini or opencode on the Windows Guard runner."
+          }
+          opencode --help | Out-Null

{plugin_scanner-2.0.3 → plugin_scanner-2.0.4}/.github/workflows/publish.yml

@@ -36,11 +36,11 @@ jobs:
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
         with:
           python-version: "3.12"
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e
+      - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57
         with:
           enable-cache: true
       - name: Install dependencies
-        run: uv sync --frozen --extra dev --group publish
+        run: uv sync --frozen --extra dev --extra publish
       - name: Compute publish version
         id: version
         env:
@@ -70,18 +70,75 @@ jobs:
         run: |
           sed -i "1,/^version = /{s/^version = .*/version = \"$VERSION\"/}" pyproject.toml
           sed -i "1,/^__version__ = /{s/^__version__ = .*/__version__ = \"$VERSION\"/}" src/codex_plugin_scanner/version.py
-      - name: Build primary package (hol-guard)
-        run: uv run --no-sync python -m build
-      - name: Build compatibility package (plugin-scanner)
+      - name: Build Guard package (hol-guard)
         run: |
           cp pyproject.toml pyproject.toml.bak
-          sed -i "1,/^name = /{s/^name = .*/name = \"plugin-scanner\"/}" pyproject.toml
+          python3 - <<'PY'
+          from pathlib import Path
+
+          path = Path("pyproject.toml")
+          text = path.read_text(encoding="utf-8")
+          text = text.replace('name = "hol-guard"', 'name = "hol-guard"', 1)
+          text = text.replace(
+              'description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."',
+              'description = "Protect local AI harnesses with HOL Guard before tools run in Codex, Claude Code, Cursor, Gemini, and OpenCode."',
+              1,
+          )
+          start = text.index("[project.scripts]")
+          end = text.index("\n\n[project.urls]")
+          scripts = "[project.scripts]\n" \
+              'hol-guard = "codex_plugin_scanner.cli:main"\n' \
+              'plugin-guard = "codex_plugin_scanner.cli:main"'
+          text = text[:start] + scripts + text[end:]
+          path.write_text(text, encoding="utf-8")
+          PY
+          uv run --no-sync python -m build
+          mv pyproject.toml.bak pyproject.toml
+      - name: Build scanner package (plugin-scanner)
+        run: |
+          cp pyproject.toml pyproject.toml.bak
+          python3 - <<'PY'
+          from pathlib import Path
+
+          path = Path("pyproject.toml")
+          text = path.read_text(encoding="utf-8")
+          text = text.replace('name = "hol-guard"', 'name = "plugin-scanner"', 1)
+          text = text.replace(
+              'description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."',
+              'description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."',
+              1,
+          )
+          start = text.index("[project.scripts]")
+          end = text.index("\n\n[project.urls]")
+          scripts = "[project.scripts]\n" \
+              'plugin-scanner = "codex_plugin_scanner.cli:main"\n' \
+              'plugin-ecosystem-scanner = "codex_plugin_scanner.cli:main"'
+          text = text[:start] + scripts + text[end:]
+          path.write_text(text, encoding="utf-8")
+          PY
           uv run --no-sync python -m build
           mv pyproject.toml.bak pyproject.toml
-      - name: Build compatibility package (codex-plugin-scanner)
+      - name: Build codex compatibility alias (codex-plugin-scanner)
         run: |
           cp pyproject.toml pyproject.toml.bak
-          sed -i "1,/^name = /{s/^name = .*/name = \"codex-plugin-scanner\"/}" pyproject.toml
+          python3 - <<'PY'
+          from pathlib import Path
+
+          path = Path("pyproject.toml")
+          text = path.read_text(encoding="utf-8")
+          text = text.replace('name = "hol-guard"', 'name = "codex-plugin-scanner"', 1)
+          text = text.replace(
+              'description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."',
+              'description = "Compatibility alias for teams still pinned to the codex-plugin-scanner package name."',
+              1,
+          )
+          start = text.index("[project.scripts]")
+          end = text.index("\n\n[project.urls]")
+          scripts = "[project.scripts]\n" \
+              'codex-plugin-scanner = "codex_plugin_scanner.cli:main"'
+          text = text[:start] + scripts + text[end:]
+          path.write_text(text, encoding="utf-8")
+          PY
           uv run --no-sync python -m build
           mv pyproject.toml.bak pyproject.toml
       - name: Verify distributions

{plugin_scanner-2.0.3 → plugin_scanner-2.0.4}/.github/workflows/scorecard.yml

@@ -21,7 +21,7 @@ jobs:
           results_file: results.sarif
           results_format: sarif
           publish_results: true
-      - uses: github/codeql-action/upload-sarif@51f77329afa6477de8c49fc9c7046c15b9a4e79d
+      - uses: github/codeql-action/upload-sarif@c10b8064de6f491fea524254123dbe5e09572f13
         with:
           sarif_file: results.sarif
         if: always()

{plugin_scanner-2.0.3 → plugin_scanner-2.0.4}/.gitignore

@@ -25,6 +25,12 @@ coverage/
 
 # Tooling
 .ruff_cache/
+dashboard/node_modules/
+dashboard/.vite/
+dashboard/dist/
+.guard-*/
+.guard-ui-review/
+.package-check/
 
 # IDE
 .idea/

{plugin_scanner-2.0.3 → plugin_scanner-2.0.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.3
-Summary: Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode.
+Version: 2.0.4
+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
 Project-URL: Issues, https://github.com/hashgraph-online/ai-plugin-scanner/issues
@@ -21,24 +21,27 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.10
+Requires-Dist: cisco-ai-skill-scanner~=2.0.8
 Requires-Dist: rich>=13.0
 Requires-Dist: tomli>=2.0; python_version < '3.11'
 Provides-Extra: cisco
-Requires-Dist: cisco-ai-skill-scanner==2.0.8; extra == 'cisco'
 Provides-Extra: dev
 Requires-Dist: build>=1.2.2; extra == 'dev'
 Requires-Dist: jsonschema>=4.23.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: publish
+Requires-Dist: twine>=6.1.0; extra == 'publish'
 Description-Content-Type: text/markdown
 
 # HOL Guard
 
-[![PyPI Version](https://img.shields.io/pypi/v/hol-guard.svg?logo=pypi&logoColor=white&cacheSeconds=300)](https://pypi.org/project/hol-guard/)
-[![Legacy Namespace](https://img.shields.io/badge/legacy-plugin--scanner_and_codex--plugin--scanner-6b7280?logo=pypi&logoColor=white)](https://pypi.org/project/plugin-scanner/)
-[![Python Versions](https://img.shields.io/pypi/pyversions/hol-guard)](https://pypi.org/project/hol-guard/)
-[![PyPI Downloads](https://img.shields.io/pypi/dm/hol-guard)](https://pypistats.org/packages/hol-guard)
+[![HOL Guard Version](https://img.shields.io/pypi/v/hol-guard.svg?logo=pypi&logoColor=white&cacheSeconds=300)](https://pypi.org/project/hol-guard/)
+[![Plugin Scanner Version](https://img.shields.io/pypi/v/plugin-scanner.svg?logo=pypi&logoColor=white&cacheSeconds=300)](https://pypi.org/project/plugin-scanner/)
+[![HOL Guard Downloads](https://img.shields.io/pypi/dm/hol-guard?logo=pypi&logoColor=white)](https://pypi.org/project/hol-guard/)
+[![Plugin Scanner Downloads](https://img.shields.io/pypi/dm/plugin-scanner?logo=pypi&logoColor=white)](https://pypi.org/project/plugin-scanner/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](#install-the-package-you-need)
 [![CI](https://github.com/hashgraph-online/ai-plugin-scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/hashgraph-online/ai-plugin-scanner/actions/workflows/ci.yml)
 [![Publish](https://github.com/hashgraph-online/ai-plugin-scanner/actions/workflows/publish.yml/badge.svg)](https://github.com/hashgraph-online/ai-plugin-scanner/actions/workflows/publish.yml)
 [![Container Image](https://img.shields.io/badge/ghcr-ai--plugin--scanner-2496ED?logo=docker&logoColor=white)](https://github.com/hashgraph-online/ai-plugin-scanner/pkgs/container/ai-plugin-scanner)
@@ -47,54 +50,78 @@ Description-Content-Type: text/markdown
 [![GitHub Stars](https://img.shields.io/github/stars/hashgraph-online/ai-plugin-scanner?style=social)](https://github.com/hashgraph-online/ai-plugin-scanner/stargazers)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-D7FF64.svg)](https://github.com/astral-sh/ruff)
 
-| ![Hashgraph Online Logo](https://hol.org/brand/Logo_Whole_Dark.png) | **Protect Codex, Claude Code, Cursor, Gemini, and OpenCode before local tools run.** HOL Guard watches the tools wired into your harness, shows you what changed, and records what you approved or blocked. The scanner commands stay available for teams that also want linting and CI checks for plugin, skill, MCP, and marketplace packages.<br><br>Start with `hol-guard` if you want local protection. Add the scanner commands later if you also publish or review packages in CI.<br><br>[PyPI Package (`hol-guard`)](https://pypi.org/project/hol-guard/)<br>[Legacy Namespace (`plugin-scanner`)](https://pypi.org/project/plugin-scanner/)<br>[Legacy Namespace (`codex-plugin-scanner`)](https://pypi.org/project/codex-plugin-scanner/)<br>[HOL Plugin Registry](https://hol.org/registry/plugins)<br>[HOL GitHub Organization](https://github.com/hashgraph-online)<br>[Report an Issue](https://github.com/hashgraph-online/ai-plugin-scanner/issues) |
+| ![Hashgraph Online Logo](https://hol.org/brand/Logo_Whole_Dark.png) | **Protect your harness locally with `hol-guard`.** Use `plugin-scanner` when you need maintainer and CI checks for plugins, skills, MCP servers, and marketplace packages.<br><br>[PyPI Package (`hol-guard`)](https://pypi.org/project/hol-guard/)<br>[PyPI Package (`plugin-scanner`)](https://pypi.org/project/plugin-scanner/)<br>[HOL Plugin Registry](https://hol.org/registry/plugins)<br>[HOL GitHub Organization](https://github.com/hashgraph-online)<br>[Report an Issue](https://github.com/hashgraph-online/ai-plugin-scanner/issues) |
 | :--- | :--- |
 
-## Protect A Harness In 60 Seconds
+## Start Here
+
+| If you want to... | Install | Start with |
+| :--- | :--- | :--- |
+| protect Codex, Claude Code, Cursor, Gemini, or OpenCode before tools run | `hol-guard` | `hol-guard start` |
+| lint and verify packages in CI before release | `plugin-scanner` | `plugin-scanner verify .` |
+
+## Guard Quickstart
 
 ```bash
-# See what Guard found on this machine
 pipx run hol-guard start
-
-# Install Guard in front of Codex
 pipx run hol-guard install codex
-
-# Record the current tool state once
 pipx run hol-guard run codex --dry-run
-
-# Launch through Guard after that
 pipx run hol-guard run codex
-
-# Check what Guard approved or blocked
+pipx run hol-guard approvals
 pipx run hol-guard receipts
 ```
 
-How Guard works:
-
-1. find the harnesses on your machine
-2. install a Guard launcher in front of the one you use
-3. record the current tool state once
-4. let Guard stop and review new or changed tools before launch
-5. check receipts locally
-6. connect sync later only if you want shared history
+What you get from Guard:
 
-Start here if you are trying to stay safe inside a harness:
-
-- `hol-guard start` shows the first steps
-- `hol-guard status` shows what Guard is watching now
-- `hol-guard install <harness>` creates the launcher
-- `hol-guard run <harness> --dry-run` records the current state
-- `hol-guard run <harness>` reviews changes before launch
-- `hol-guard diff <harness>` shows what changed
-- `hol-guard receipts` shows local history
+- Detects local harness config on your machine
+- Records a baseline before you trust a tool
+- Pauses cleanly on new or changed artifacts before launch
+- Queues blocked changes in a localhost approval center when the harness cannot prompt inline
+- Stores receipts locally so you can review decisions later
+- Keeps sync optional until you actually want shared history
 
 See [docs/guard/get-started.md](docs/guard/get-started.md) for the full local flow.
 
-## Use The Scanner In CI
+<details>
+<summary>Guard commands at a glance</summary>
+
+- `hol-guard start`
+  Shows the next step for the harnesses Guard found.
+- `hol-guard status`
+  Shows what Guard is watching now.
+- `hol-guard install <harness>`
+  Creates the launcher shim for that harness.
+- `hol-guard run <harness> --dry-run`
+  Records the current state once before you trust it.
+- `hol-guard run <harness>`
+  Reviews changes before launch and hands blocked sessions to the approval center when needed.
+- `hol-guard approvals`
+  Lists pending approvals or resolves them from the terminal.
+- `hol-guard receipts`
+  Shows local approval and block history.
+
+</details>
+
+<details>
+<summary>Harness approval strategy</summary>
+
+- `claude-code`
+  Guard prefers Claude hooks first, then the local approval center when the shell cannot prompt.
+- `codex`
+  Guard owns artifact approval today through the local approval center. App Server is the future path for richer in-client approvals.
+- `cursor`
+  Guard respects Cursor’s native tool approval and focuses on artifact trust before launch.
+- `opencode`
+  Guard authors package-level policy while OpenCode keeps native allow or deny rules.
+- `gemini`
+  Guard scans extensions and falls back to the local approval center for blocked changes.
+
+</details>
+
+## Scanner Quickstart
 
 ```bash
-# Install the package once, then use the scanner commands in your shell
-pipx install hol-guard
+pipx install plugin-scanner
 plugin-scanner lint .
 plugin-scanner verify .
 ```
@@ -109,30 +136,23 @@ plugin-scanner verify .
     min_score: 80
 ```
 
-If your repository uses a Codex marketplace root like `.agents/plugins/marketplace.json`, keep `plugin_dir: "."`. The scanner will discover local `./plugins/...` entries automatically, scan each local plugin manifest, and skip remote marketplace entries instead of treating the repo root as a single plugin.
-
-## Start With Guard, Add CI Later
-
-If you use Codex, Claude Code, Cursor, Gemini, or OpenCode every day, start with Guard.
-
-- Guard is the part that protects your local harness before tools run.
-- It helps when a new MCP server appears, when a tool changes after you trusted it, or when you want a receipt for what was approved or blocked.
-
-If you publish plugins, skills, or marketplace packages, add the scanner in CI too.
+When to add `plugin-scanner`:
 
-- The scanner checks manifests, metadata, runtime surfaces, and policy rules before a release or CI gate passes.
-- It is the publishing and repo review side of this package, not the first thing a local Guard user needs to learn.
+- You publish plugins, skills, or marketplace packages
+- You want a CI gate before release
+- You need SARIF, verification payloads, or submission artifacts
 
-## Use Scanner After `$plugin-creator`
+If your repository uses a Codex marketplace root like `.agents/plugins/marketplace.json`, keep `plugin_dir: "."`. The scanner will discover local `./plugins/...` entries automatically, scan each local plugin manifest, and skip remote marketplace entries instead of treating the repo root as a single plugin.
 
-If you are building and shipping packages, the scanner fits after `$plugin-creator`:
+## Need More Detail?
 
-1. Scaffold with `$plugin-creator`.
-2. Run `lint` locally to catch structure, metadata, and security issues early.
-3. Run `verify` in CI to block regressions and enforce quality policy.
-4. Ship or submit with confidence, backed by scanner artifacts and trust signals.
+- Contributor setup: jump to [Development](#development)
+- Local Guard docs: [docs/guard/get-started.md](docs/guard/get-started.md)
+- GitHub Action docs: [action/README.md](action/README.md)
+- Registry and trust references: keep reading below
 
-The score stays available as a trust and triage signal, but the day-to-day workflow is simple: check locally, verify in CI, then release.
+<details>
+<summary>Scanner reference: trust scoring, installs, ecosystems, and CLI commands</summary>
 
 ## How Trust Scoring Works
 
@@ -161,26 +181,27 @@ pip install -e ".[dev]"
 pytest -q
 ```
 
-## Install
+## Install The Package You Need
+
+Guard package:
 
 ```bash
 pip install hol-guard
 ```
 
-Cisco-backed skill scanning is optional:
+Scanner package:
 
 ```bash
-pip install "hol-guard[cisco]"
+pip install plugin-scanner
 ```
 
-The `cisco` extra installs the published `cisco-ai-skill-scanner` package from PyPI so the scanner remains publishable on PyPI and the optional Cisco analysis path works with standard package metadata.
+Cisco skill scanning support is included in the default `plugin-scanner` install (via `cisco-ai-skill-scanner`).
 
-You can also install once and use both Guard and scanner commands:
+If you want both tools in one shell during local development:
 
 ```bash
 pipx install hol-guard
-hol-guard start
-plugin-scanner ./my-plugin
+pipx install plugin-scanner
 ```
 
 Container-first environments can use the published image instead:
@@ -192,19 +213,11 @@ docker run --rm \
   scan /workspace --format text
 ```
 
-Backward compatibility remains available for teams still pinned to the historical package namespace:
-
-```bash
-pip install plugin-scanner
-pip install codex-plugin-scanner
-```
-
-Compatibility command names also stay available:
+Command names by package:
 
 ```bash
-plugin-guard start
+hol-guard start
 plugin-scanner verify .
-codex-plugin-scanner verify .
 ```
 
 ## Ecosystem Support
@@ -294,6 +307,11 @@ plugin-scanner submit ./my-plugin --profile public-marketplace --attest dist/plu
 plugin-scanner doctor ./my-plugin --component mcp --bundle dist/doctor.zip
 ```
 
+</details>
+
+<details>
+<summary>Advanced reference: specs, action publishing, automation, and examples</summary>
+
 ## Codex Spec Alignment
 
 The scanner follows the current Codex plugin packaging conventions more closely:
@@ -647,6 +665,8 @@ Final Score: 130/130
 
 Plugins that pass the scanner with a high score are candidates for listing in the [HOL Plugin Registry](https://hol.org/registry/plugins).
 
+</details>
+
 ## Resources
 
 - [HOL Plugin Registry](https://hol.org/registry/plugins)