From b7658419e6d3bf09a3d51b8b5f79cf48a5cb51d2 Mon Sep 17 00:00:00 2001 From: Daniel Meppiel <51440732+danielmeppiel@users.noreply.github.com> Date: Sun, 3 May 2026 14:56:16 +0200 Subject: [PATCH] docs: update pack-distribute for local bundle install (v0.12) - Replace pipeline diagram reference from 'apm unpack' to 'apm install ' - Update targeting mental model section to use 'apm install ' phrasing - Add new 'apm install ' section documenting the unified install entrypoint, sha256 integrity verification, air-gapped restore, and lockfile recording - Deprecate 'apm unpack' section with explicit v0.13 removal notice Refs: #1099 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/guides/pack-distribute.md | 48 ++++++++++++------- 1 file changed, 30 insertions(+), 18 deletions(-) diff --git a/docs/src/content/docs/guides/pack-distribute.md b/docs/src/content/docs/guides/pack-distribute.md index 93a7d4d81..9f594cc31 100644 --- a/docs/src/content/docs/guides/pack-distribute.md +++ b/docs/src/content/docs/guides/pack-distribute.md @@ -26,7 +26,7 @@ Common motivations: The pack/distribute workflow fits between install and consumption: ``` -apm install -> apm pack -> upload artifact -> download -> apm unpack (or tar xzf) +apm install -> apm pack -> upload artifact -> download -> apm install (or tar xzf) ``` The left side (install, pack) runs where APM is available. The right side (download, unpack) runs anywhere — a CI job, a dev container, a colleague's laptop. The bundle is the boundary. @@ -100,23 +100,23 @@ The enriched lockfile inside the bundle uses the remapped paths, so the bundle i ### Targeting mental model -**Choose your target when you pack. Unpack delivers exactly what was packed.** +**Choose your target when you pack. Install delivers exactly what was packed.** A bundle is a deployable snapshot, not a retargetable source artifact. Target selection happens at pack time because that is when the full context is available -- which file types are remappable (skills, agents) and which are target-specific (commands, instructions, hooks). -`apm unpack` does not remap paths. If the bundle was packed for Claude, the files land under `.claude/`. If you need a different target, re-pack from source with the desired `--target` flag, or use `--target all` to include all platforms. +`apm install ` does not remap paths. If the bundle was packed for Claude, the files land under `.claude/`. If you need a different target, re-pack from source with the desired `--target` flag, or use `--target all` to include all platforms. -When unpacking, APM reads the bundle's `pack:` metadata and shows the target it was packed for. If the bundle target does not match the project's detected target, a warning is displayed: +When installing a local bundle, APM reads the bundle's `pack:` metadata and shows the target it was packed for. If the bundle target does not match the project's detected target, a warning is displayed: ``` -$ apm unpack team-skills.tar.gz -[*] Unpacking team-skills.tar.gz -> . +$ apm install team-skills.tar.gz +[*] Installing team-skills.tar.gz -> . [i] Bundle target: claude (1 dep(s), 3 file(s)) [!] Bundle target 'claude' differs from project target 'copilot' -[+] Unpacked 3 file(s) (verified) +[+] Installed 3 file(s) (verified) ``` -This is informational -- the files still extract. The warning helps users understand why their tool may not see the unpacked files and suggests the correct workflow. +This is informational -- the files still deploy. The warning helps users understand why their tool may not see the installed files and suggests the correct workflow. ## Plugin format vs APM format @@ -280,22 +280,34 @@ dependencies: The `pack:` section records the bundle `format`, the effective `target` filter, and a `packed_at` UTC timestamp. Plugin-format output has no `apm.lock.yaml` -- consumers verify by re-running the upstream pack instead. -## `apm unpack` +## `apm install ` -Extracts an APM bundle (produced with `--format apm`) into a project directory. Accepts both `.tar.gz` archives and unpacked bundle directories. Plugin-format output is consumed directly by Claude Code and other plugin hosts and does not need `apm unpack`. +Deploys an APM bundle (directory or `.tar.gz` archive) produced by `apm pack --format apm` into a project directory without touching the network or the dependency resolver -- mirroring the `pip install ./wheel` / `cargo install --path` mental model. ```bash -# Extract and verify -apm unpack ./build/my-project-1.0.0.tar.gz +# Install a bundle directory +apm install ./build/my-project-1.0.0/ -# Extract to a specific directory -apm unpack ./build/my-project-1.0.0.tar.gz -o ./ +# Install a .tar.gz archive +apm install ./build/my-project-1.0.0.tar.gz -# Skip integrity check -apm unpack --skip-verify ./build/my-project-1.0.0.tar.gz +# Override log label (does not affect lockfile) +apm install ./build/my-project-1.0.0.tar.gz --as my-label # Preview without writing -apm unpack ./build/my-project-1.0.0.tar.gz --dry-run +apm install ./build/my-project-1.0.0.tar.gz --dry-run +``` + +APM detects that the argument is a local path when it exists on disk and contains a `plugin.json` at the bundle root. Integrity is verified against the `pack.bundle_files` sha256 manifest embedded in `apm.lock.yaml` inside the bundle before any file is written. Deployed paths are recorded in the project's `apm.lock.yaml` under `local_deployed_files`. + +Plugin-format output is consumed directly by Claude Code and other plugin hosts; `apm install ` handles both formats. + +## `apm unpack` (deprecated since 0.12) + +> **Deprecated.** Use `apm install ` instead. `apm unpack` remains available for one release cycle (removal planned for v0.13). + +```bash +apm unpack ./build/my-project-1.0.0.tar.gz ``` ### Options @@ -312,7 +324,7 @@ apm unpack ./build/my-project-1.0.0.tar.gz --dry-run - **Additive-only**: `unpack` writes files listed in the bundle's lockfile. It never deletes existing files in the target directory. - **Overwrite on conflict**: if a file already exists at the target path, the bundle file wins. - **Verification**: by default, `unpack` checks that every path in the bundle's `deployed_files` manifest exists in the bundle before extracting. Pass `--skip-verify` to skip this check for partial bundles. -- **Lockfile not copied**: the bundle's enriched `apm.lock.yaml` is metadata for verification only — it is not written to the output directory. +- **Lockfile not copied**: the bundle's enriched `apm.lock.yaml` is metadata for verification only -- it is not written to the output directory. ## Consumption scenarios