Docs: document CoreHub install planning

Author: febrinanda

docs/corehub/cli.md

@@ -58,6 +58,15 @@ npm run corehub -- package download plugin-lab --output plugin-lab.corehub-manif
 
 Without `--output`, the CLI requests `redirect=false` from the Registry API and prints the package, publisher, artifact checksum, storage URL, and signature metadata. With `--output`, it fetches the signed storage URL, verifies the downloaded byte count and SHA-256 checksum, and writes the artifact only after verification passes.
 
+6. Produce a dry-run installer plan:
+
+```sh
+npm run corehub -- package install plugin-lab --registry https://coreblow.com/corehub
+npm run corehub -- package install plugin-lab --output plugin-lab.corehub-manifest.json --registry https://coreblow.com/corehub
+```
+
+`package install` does not modify CoreBlow plugin state yet. It resolves the package, checks publisher and artifact metadata, and reports the install steps that would run. With `--output`, it also performs the verified artifact download and includes the verification result in the plan.
+
 ## Package-Compatible Commands
 
 CoreHub keeps ClawHub-style package commands so clients can grow around stable registry habits:
@@ -71,6 +80,8 @@ npm run corehub -- package files plugin-lab
 npm run corehub -- package artifact plugin-lab
 npm run corehub -- package download plugin-lab
 npm run corehub -- package download plugin-lab --output plugin-lab.corehub-manifest.json
+npm run corehub -- package install plugin-lab
+npm run corehub -- package install plugin-lab --output plugin-lab.corehub-manifest.json
 ```
 
 ## Hosted Registry Reads
@@ -88,6 +99,8 @@ npm run corehub -- package files plugin-lab --registry https://coreblow.com/core
 npm run corehub -- package artifact plugin-lab --registry https://coreblow.com/corehub
 npm run corehub -- package download plugin-lab --registry https://coreblow.com/corehub
 npm run corehub -- package download plugin-lab --output plugin-lab.corehub-manifest.json --registry https://coreblow.com/corehub
+npm run corehub -- package install plugin-lab --registry https://coreblow.com/corehub
+npm run corehub -- package install plugin-lab --output plugin-lab.corehub-manifest.json --registry https://coreblow.com/corehub
 npm run corehub -- registry info --registry https://coreblow.com/corehub
 ```
 
@@ -118,6 +131,25 @@ If the byte count or SHA-256 checksum does not match the artifact manifest, the
 
 For the signed redirect behavior behind this command, see [Downloads](/corehub/downloads). For the full trust chain, see [Trust Model](/corehub/trust-model).
 
+## Install Planning
+
+`corehub package install <id>` is currently an install planner. It returns JSON with:
+
+| Field | Purpose |
+| --- | --- |
+| `dryRun` | Always `true` until CoreBlow plugin install wiring lands. |
+| `install.status` | Planned install action and whether CoreBlow state would be modified. |
+| `download.verified` | Whether the artifact was fetched and checksum verified. |
+| `plan` | Ordered install steps for package resolution, publisher verification, artifact fetch, and plugin install. |
+
+Use `--output <path>` when you want the planner to prove the artifact bytes:
+
+```sh
+npm run corehub -- package install plugin-lab --output plugin-lab.corehub-manifest.json --registry https://coreblow.com/corehub
+```
+
+The command remains dry-run after writing the verified artifact; it does not install the plugin into CoreBlow yet.
+
 ## Command Map
 
 | Command | Status | Purpose |
@@ -136,5 +168,6 @@ For the signed redirect behavior behind this command, see [Downloads](/corehub/d
 | `corehub package files <id>` | Available | Show file metadata from the artifact manifest. |
 | `corehub package artifact <id>` | Available | Show artifact manifest metadata, checksum, provenance, and download policy. |
 | `corehub package download <id>` | Available | Print signed download metadata or write a verified artifact with `--output`. |
+| `corehub package install <id>` | Available | Produce a dry-run install plan, optionally with a verified artifact download. |
 | `corehub package publish <source>` | Planned | Publish package artifacts after registry writes land. |
 | `corehub registry info` | Available | Read the API discovery document. |

docs/corehub/downloads.md

@@ -62,8 +62,11 @@ The JSON response includes:
 ```sh
 npm run corehub -- package download plugin-lab --registry https://coreblow.com/corehub
 npm run corehub -- package download plugin-lab --output plugin-lab.corehub-manifest.json --registry https://coreblow.com/corehub
+npm run corehub -- package install plugin-lab --output plugin-lab.corehub-manifest.json --registry https://coreblow.com/corehub
 ```
 
 Without `--output`, the CLI requests `redirect=false` and prints the signed download metadata. With `--output`, it fetches the signed storage URL, verifies `artifact.size` and `artifact.sha256`, then writes the artifact to disk.
 
+`package install` uses the same verified download path when `--output` is present, but the command still returns a dry-run install plan instead of modifying CoreBlow plugin state.
+
 For the security model behind this flow, see the [Trust Model](/corehub/trust-model). For endpoint details and status codes, see the [Registry API](/corehub/api).

docs/corehub/publishing-roadmap.md

@@ -12,6 +12,7 @@ CoreHub publishing is planned as a controlled registry workflow. The current reg
 | Publisher-owned versions | Live now |
 | Artifact manifests | Live now |
 | Storage-backed signed downloads | Live now |
+| Dry-run install planning | Live now |
 | Remote publish writes | Planned |
 | Artifact upload API | Planned |
 | Review and moderation queue | Planned |
@@ -128,13 +129,14 @@ Some operations stay blocked until the write-side registry is ready:
 
 The recommended implementation order is:
 
-1. Verified CLI download with checksum and size enforcement.
-2. Publisher registration model.
-3. Package submission draft API.
-4. Artifact upload and storage policy.
-5. Review and moderation queue.
-6. Publish approval flow.
-7. Ownership transfer workflow.
-8. Aggregate install analytics.
+1. Verified CLI download with checksum and size enforcement. Done.
+2. Dry-run install planning that wires verified downloads into install intent. Done.
+3. Publisher registration model.
+4. Package submission draft API.
+5. Artifact upload and storage policy.
+6. Review and moderation queue.
+7. Publish approval flow.
+8. Ownership transfer workflow.
+9. Aggregate install analytics.
 
 This keeps the CoreHub trust chain intact while moving from read-only registry data toward controlled publisher writes.