Use marketplace-only plugin installs and organize documentation

.github/workflows/marketplace.yml

@@ -22,8 +22,8 @@ jobs:
           python-version: '3.12'
       - name: Check marketplace contracts
         run: python scripts/check-marketplace.py
-      - name: Validate complete plugin packaging
-        run: python scripts/test-plugin-packaging.py
+      - name: Validate runtime packaging
+        run: python scripts/test-runtime-packaging.py
       - name: Select component validation
         id: plan
         run: python scripts/ci-plan.py
@@ -38,12 +38,16 @@ jobs:
           dotnet-version: '10.0.401'
           cache: true
           cache-dependency-path: src/HyperVControl/packages.lock.json
-      - name: Build self-contained EXE and plugin
+      - name: Build self-contained runtime
         shell: pwsh
         run: ./scripts/build-hyperv-control.ps1
       - name: Verify pinned runtime reproducibility
         shell: pwsh
-        run: git diff --exit-code -- plugins/hyper-v-control/runtime.json
+        run: |
+          git diff --exit-code -- plugins/hyper-v-control/runtime.json
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          python scripts/test-runtime-packaging.py --hyperv-release build/hyperv-control/runtime-release
+          exit $LASTEXITCODE
       - name: Unit and stdio protocol validation
         shell: pwsh
         run: |
@@ -52,14 +56,15 @@ jobs:
           dotnet run --project tests/HyperVControl.Tests -c Release -- smoke $PWD
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
           ./scripts/test-release-isolation.ps1
+          ./scripts/test-hyperv-launcher.ps1
           exit $LASTEXITCODE
       - uses: actions/upload-artifact@v4
         if: github.event_name == 'workflow_dispatch'
         with:
           name: hyper-v-control-win-x64
           if-no-files-found: error
           path: |
-            build/hyperv-control/release/hyper-v-control-win-x64-v*.exe
-            build/hyperv-control/release/hyper-v-control-plugin-v*-win-x64.zip
-            build/hyperv-control/release/hyper-v-control-v*-release.json
-            build/hyperv-control/release/hyper-v-control-v*-SHA256SUMS.txt
+            build/hyperv-control/runtime-release/hyper-v-control-win-x64-v*.exe
+            build/hyperv-control/runtime-release/hyper-v-control-v*-NOTICES.txt
+            build/hyperv-control/runtime-release/hyper-v-control-v*-release.json
+            build/hyperv-control/runtime-release/hyper-v-control-v*-SHA256SUMS.txt

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Maintaining and extending the marketplace
 
-Each plugin is an independent product. Keep its installed files self-contained, its dependencies explicit, and its releases separate. Shared code belongs at the repository level only when multiple plugins actually use it.
+Each plugin is an independent product installed through the marketplace. Keep its installed files self-contained and its runtime dependencies explicit. GitHub Releases carry native runtimes; do not publish separate plugin ZIPs or skill downloads. Shared code belongs at the repository level only when multiple plugins actually use it.
 
 ## Repository map
 
@@ -11,7 +11,7 @@ Each plugin is an independent product. Keep its installed files self-contained,
 | `src/<Product>/` | Native application or MCP implementation; currently Hyper-V Control |
 | `tests/<Product>.Tests/` | Native protocol and behavior validation |
 | `scripts/` | Maintainer builds, packaging, and repository checks; never an installed plugin dependency |
-| `docs/` | Build/release procedures and recorded validation evidence |
+| `docs/` | [Documentation index](docs/README.md): guides, references, and validation records grouped by component and run |
 | `sources/`, `patches/`, `bundle.lock.json` | Pinned Rizin upstream sources, compatibility patches, and build dependencies |
 | `build/` | Ignored generated files, downloads, binaries, and local experiment output |
 
@@ -23,32 +23,32 @@ Within Hyper-V Control, `HyperVTools*` exposes the MCP contract, `Services/` own
 
 - Edit `plugins/<id>/plugin.json` for plugin identity, version, and interface metadata. Run `python scripts/check-marketplace.py --sync` to generate `.codex-plugin/plugin.json`; do not maintain the compatibility copy independently.
 - Compiled downloads use the plugin's `runtime.json` for the exact artifact and hash. Rizin's independently versioned runtime and build inputs are in `bundle.lock.json`. Keep dependency versions in metadata and lockfiles.
-- Hyper-V's project, CLI, and protocol versions must match its plugin manifest. The repository checker rejects partial updates; the build verifies the executable version and runtime hash.
-- README files explain purpose, setup, and usage. Keep current version numbers, release dates, and changelogs out of them. The [download catalog](docs/releases.md#release-index) is the maintained entrypoint for current releases.
+- Hyper-V's project, CLI, and protocol versions must match its runtime pin. The plugin version can advance independently for launcher or skill updates. The repository checker rejects inconsistent runtime updates; the build verifies the executable version and hash.
+- README files explain purpose, setup, and usage. Keep current version numbers, release dates, and changelogs out of them. The [download catalog](docs/guides/releases.md#release-index) is the maintained entrypoint for current releases.
 - Skills explain how an agent should choose tools and interpret results. Put detailed task procedures in their `references/` directory and scripts needed at runtime inside the plugin.
 - Record experiments in validation reports. Imported Frida material under `references/legacy/` and `docs/migration/` is historical evidence, not the maintained entrypoint; preserve its provenance and licenses.
 
-Links inside distributed plugin documentation must resolve inside that plugin or use an absolute repository/web URL. A relative link to `../../docs/` works in a checkout but breaks when the plugin ZIP is extracted.
+Links inside distributed plugin documentation must resolve inside that plugin or use an absolute repository/web URL. A relative link to `../../docs/` works in a checkout but breaks in the installed plugin cache.
 
 ## Add a plugin
 
 1. Choose a stable lowercase ID and create `plugins/<id>/` with `plugin.json`, `README.md`, `LICENSE`, and `skills/<skill-id>/SKILL.md`. Keep plugin content in English. Add only the references, assets, and helpers that the installed plugin needs.
 2. Add a local catalog entry pointing to `./plugins/<id>`, then run the manifest sync/check command. New catalog plugins are discovered by the checker automatically.
 3. If it needs a native executable, put its source and tests under `src/` and `tests/`. Give it a dedicated builder, verified installer, and versioned installation directory. A source-only skill/CLI plugin does not need an MCP server or binary release.
 4. Add component-specific validation to the existing PR workflow. Keep expensive job selection in `scripts/ci-plan.py`; extend it for the component's actual inputs. Do not introduce a second push or tag workflow for the same checks.
-5. Test an extracted package in a fresh directory. It must work without the repository checkout, another plugin, or a developer's absolute paths. Follow the [release guide](docs/releases.md) for publication and asset naming.
+5. Test the marketplace-installed plugin from a fresh directory. It must work without the repository checkout, another plugin, or a developer's absolute paths. Publish runtime assets only when the plugin requires them; follow the [release guide](docs/guides/releases.md).
 
 ## Check a change
 
 ```powershell
 python scripts/check-marketplace.py
-python scripts/test-plugin-packaging.py
+python scripts/test-runtime-packaging.py
 ```
 
-These fast checks validate the catalog, compatibility manifests, bundled skill paths, runtime pins, README policy, entrypoint links, and Rizin plugin packaging. They do not install plugin dependencies or operate a VM.
+These fast checks validate the catalog, compatibility manifests, bundled skill paths, runtime pins, documentation layout/links, README policy, and runtime packaging. They do not install plugin dependencies or operate a VM.
 
 The single PR workflow runs these checks for all changes. It runs Windows build/protocol/installer checks only when their inputs change. Pure documentation changes avoid native builds, newer commits cancel obsolete runs, and merging or tagging does not repeat CI. Use a manual workflow run when downloadable build artifacts are needed.
 
-For behavior changes, also run the affected component's documented tests: [Hyper-V Control](plugins/hyper-v-control/README.md#development-and-validation), [Rizin](docs/build.md), [Frida](scripts/frida-use-experiments/README.md), or [Capstone](plugins/capstone-binary-patching/README.md#validation-and-boundaries). Live tests must have a defined target, restoration plan, and recorded limits; CI never discovers and operates on a developer's VMs automatically.
+For behavior changes, also run the affected component's documented tests: [Hyper-V Control](plugins/hyper-v-control/README.md#development-and-validation), [Rizin](docs/guides/rizin-build.md), [Frida](scripts/frida-use-experiments/README.md), or [Capstone](plugins/capstone-binary-patching/README.md#validation-and-boundaries). Live tests must have a defined target, restoration plan, and recorded limits; CI never discovers and operates on a developer's VMs automatically.
 
 Before removing a release, check both runtime installers and build lockfiles for references. Preserve active dependencies first. Published primary EXEs and ZIPs are immutable; publish changed bytes under a new version. Documentation-only edits do not require rebuilding an unchanged runtime.

README.md

@@ -2,40 +2,39 @@
 
 **Windows reverse engineering and automation for AI agents.**
 
-A collection of focused plugins for understanding software, investigating live behavior, making verifiable changes, and running repeatable experiments. Each plugin combines specialist tools with guidance that helps your agent choose a useful workflow and interpret the results.
+Understand unfamiliar software, investigate live behavior, make verifiable changes, and run repeatable experiments. Each plugin pairs specialist tools with practical workflows for your agent.
 
-## The plugins
+## Plugins
 
-### [Rizin RE Toolkit](plugins/rizin-re-toolkit)
+| Plugin | What it helps you do |
+| --- | --- |
+| [Rizin RE Toolkit](plugins/rizin-re-toolkit) | Understand executables and memory dumps through disassembly, multiple decompilers, signatures, and pattern matching. |
+| [Frida Use](plugins/frida-use) | Observe running programs, trace API calls, inspect runtime values, and test reversible behavior changes. |
+| [Capstone Binary Patching](plugins/capstone-binary-patching) | Compare instructions, create precise binary patches, verify the result, and roll changes back. |
+| [Hyper-V Control](plugins/hyper-v-control) | Manage VMs and checkpoints, interact with guest desktops, transfer files, and debug applications or the Windows kernel. |
 
-Explore native executables and memory dumps without starting from scratch. Disassembly, multiple decompilers, signatures, and pattern matching help you understand unfamiliar code and cross-check what you find. A good starting point for binary triage, program analysis, and investigating captured memory.
+Use them independently or together: understand a program, observe it running, verify a change, and repeat the experiment from a known VM state.
 
-### [Frida Use](plugins/frida-use)
+## Install
 
-See what a program actually does while it runs. Trace API calls, inspect arguments and return values, and try reversible changes to live behavior. Use it to investigate a suspicious call, follow a runtime-only code path, or test a hypothesis from static analysis.
-
-### [Capstone Binary Patching](plugins/capstone-binary-patching)
-
-Turn a proposed binary change into a precise, verifiable patch. Compare bytes and instructions, construct patches, check the result, and roll changes back. Useful when you need to explain exactly what changed, port a patch between versions, or preserve the original file for comparison.
-
-### [Hyper-V Control](plugins/hyper-v-control)
+```powershell
+codex plugin marketplace add JerryLinLinLin/jerry-plugin-marketplace --ref main
+```
 
-Give your agent control of a Windows VM lab: manage VM lifecycles and checkpoints, interact with guest desktops, transfer files, and debug applications or the Windows kernel. Checkpoints make experiments repeatable, while desktop interaction and debugging let you investigate the same VM from several angles.
+Open **Jerry's Plugin Marketplace** in Codex and install the plugins you need. Follow each plugin's setup guide, then describe your task to the agent.
 
-Use any plugin on its own, or combine them: understand a binary with Rizin, inspect its behavior with Frida, verify a patch with Capstone, and use Hyper-V to repeat the experiment from a known state.
+## Releases
 
-## Get started
+[Releases](https://github.com/JerryLinLinLin/jerry-plugin-marketplace/releases)
 
-```powershell
-codex plugin marketplace add JerryLinLinLin/jerry-plugin-marketplace --ref main
-```
+## Contributing
 
-In Codex, open **Jerry's Plugin Marketplace** and install the plugins you need. Each plugin includes its skill. Follow the linked setup guides above for runtime requirements, then describe the task to your agent.
+[Contribution guide](CONTRIBUTING.md)
 
-## Downloads
+## Release guidelines
 
-The [download catalog](docs/releases.md#release-index) lists prebuilt Windows packages: a standalone EXE or complete plugin for Hyper-V Control, and a complete plugin plus portable runtime for Rizin RE Toolkit.
+[Release guide](docs/guides/releases.md)
 
-Frida Use and Capstone Binary Patching are available through the marketplace. Install only what you need; plugins have independent setup and releases.
+## License
 
-[Contributing](CONTRIBUTING.md) · [Release guide](docs/releases.md) · [MIT license](LICENSE). Bundled third-party components retain their own licenses.
+[MIT](LICENSE)

docs/README.md

@@ -0,0 +1,34 @@
+# Documentation
+
+## Guides
+
+- [Contributing and repository layout](../CONTRIBUTING.md)
+- [Runtime releases and distribution](guides/releases.md)
+- [Build the Rizin runtime](guides/rizin-build.md)
+- [Use the portable Rizin runtime](guides/rizin-runtime.md)
+
+Plugin setup and agent workflows belong to each plugin's own directory; start from the [plugin catalog](../README.md#plugins).
+
+## Reference
+
+- [Rizin third-party components and licenses](reference/rizin-third-party.md)
+- [Hyper-V feature inventory](../plugins/hyper-v-control/docs/extraction.md)
+
+## Validation records
+
+These are dated or versioned records of what was tested, including environment details and known limits. They are historical evidence, not installation guides.
+
+| Component | Record |
+| --- | --- |
+| Rizin | [Runtime validation](validation/rizin/runtime-v0.3.1/report.md) |
+| Capstone Binary Patching | [Native patching experiments](validation/capstone-binary-patching/plugin-v0.1.0/report.md) |
+| Frida Use | [Windows instrumentation experiments and evidence](validation/frida-use/2026-10-01/report.md) |
+| Hyper-V Control | [VM, console, and debugger validation](validation/hyper-v-control/runtime-v0.1.0/report.md) |
+
+## Where new documents belong
+
+- `guides/`: maintained task procedures.
+- `reference/`: component facts, formats, and notices.
+- `validation/<component>/<version-or-date>/`: one report and its retained evidence for each run.
+
+Keep this directory root limited to this index. Link to existing plugin documentation rather than duplicating it. Add new validation runs alongside previous records; update links when moving documents, and keep generated binaries and large captures under ignored `build/`.

docs/guides/releases.md

@@ -0,0 +1,51 @@
+# Runtime releases
+
+Install plugins through **Jerry's Plugin Marketplace** in Codex. The marketplace distributes their manifests, skills, launchers, and setup helpers. GitHub Releases distribute native runtimes and their supporting notices, checksums, and build metadata. Do not publish plugin ZIPs or standalone skill files.
+
+This repository uses the [official marketplace installation workflow](https://developers.openai.com/plugins/build/plugins#add-a-marketplace-from-the-cli).
+
+## Release index
+
+| Runtime | Release | Download |
+| --- | --- | --- |
+| Hyper-V Control | [Windows x64](https://github.com/JerryLinLinLin/jerry-plugin-marketplace/releases/tag/hyper-v-control-v0.1.0) | Self-contained MCP executable |
+| Rizin | [Windows x64](https://github.com/JerryLinLinLin/jerry-plugin-marketplace/releases/tag/rizin-v0.3.1) | Portable runtime; RetDec build SDK is a separate maintainer asset |
+
+Frida and Capstone dependencies are installed by their plugin setup workflows. They do not need a binary release in this repository.
+
+## Versions and installation
+
+Plugin versions live in `plugins/<id>/plugin.json`. Native runtime versions are independent: Hyper-V records its executable pin in `runtime.json`, and Rizin records its runtime/build inputs in `bundle.lock.json`. A launcher or skill update can ship through the marketplace without rebuilding an unchanged executable.
+
+Hyper-V's launcher downloads and verifies a missing runtime before starting the MCP. Rizin's skill invokes its verified runtime installer when needed. Each component uses its own versioned installation directory. Never use the repository-wide Latest release to resolve a runtime: pin an exact asset, or filter and paginate within the intended runtime stream.
+
+## Asset naming
+
+| Item | Pattern |
+| --- | --- |
+| Runtime tag | `<component>-v<version>` |
+| Executable | `<component>-<rid>-v<version>.exe` |
+| Runtime archive | `<component>-runtime-<rid>-v<version>.zip` |
+| Notices | `<component>-v<version>-NOTICES.txt` |
+| Asset inventory | `<component>-v<version>-release.json` |
+| Checksums | `<component>-v<version>-SHA256SUMS.txt` |
+
+Use platform identifiers such as `win-x64`. Keep established Rizin runtime filenames and `SHA256SUMS` compatible with its installer. Runtime archives contain executable dependencies and support data; marketplace content stays under `plugins/`.
+
+## Build and publish
+
+1. Build and test the runtime. Hyper-V uses `scripts/build-hyperv-control.ps1`; its SDK and framework are pinned in the CI workflow and project. Rizin uses the [build guide](rizin-build.md).
+2. Commit matching runtime pins and metadata. Run the repository checks and affected component tests, then merge the PR.
+3. Tag the merged commit. Publish only the builder's runtime assets, notices, inventory, and checksums. Inspect explicit filenames; do not upload an entire shared build directory.
+4. Download the published files, verify their hashes, and exercise the installer in a fresh directory.
+5. Update the release index above. Keep release notes to a short introduction, user-facing changes, and download/setup links.
+
+Hyper-V outputs four files in `build/hyperv-control/runtime-release`: the EXE, notices, inventory, and checksum file. Rizin outputs its runtime ZIP, manifest, checksums, and any separately produced verification report. Packaging rejects unrelated files in the output directory.
+
+Publish changed runtime bytes under a new version. Preserve current runtime URLs and hashes during metadata corrections. Before retiring an old release, check both installers and build lockfiles and migrate any active dependency. Keep source tags and historical validation records.
+
+## CI
+
+One workflow runs for PRs targeting `main`. Fast marketplace/runtime-packaging checks run for every PR; `scripts/ci-plan.py` selects expensive Windows validation when its inputs change. Updated PRs cancel obsolete runs. Pushes, merge commits, and tags do not repeat validation.
+
+Manual workflow runs can upload runtime artifacts. They do not publish a GitHub Release automatically. See [CONTRIBUTING](../../CONTRIBUTING.md) for component boundaries and local checks.