[docs] Update documentation for features from 2026-05-02#1107
Open
danielmeppiel wants to merge 1 commit intomainfrom
Open
[docs] Update documentation for features from 2026-05-02#1107danielmeppiel wants to merge 1 commit intomainfrom
danielmeppiel wants to merge 1 commit intomainfrom
Conversation
- Update pipeline diagram: apm unpack -> apm install <bundle> - Correct plugin-format lockfile row: now embeds apm.lock.yaml with pack.bundle_files sha256 manifest (SBOM) since v0.12 - Add apm install <bundle> restore section documenting the unified restore primitive, integrity verification, and air-gapped behavior - Mark apm unpack as deprecated (v0.12), removal scheduled for v0.13 - Add apm install <local-bundle> behavior entry in cli-commands.md Triggered by: #1099 (feat: apm install <local-bundle> + lockfile-embedded plugin packs) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
danielmeppiel
added
the
automation
danielmeppiel
added
the
documentation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the user-facing docs for the recent local-bundle install workflow, lockfile-embedded plugin bundles, and the deprecation of apm unpack. It fits into the docs set by aligning the Starlight guides/reference pages with the new bundle restore path introduced in the install/pack pipeline.
Changes:
- Add
apm install <local-bundle>to the CLI reference behavior list. - Update the pack/distribute guide to describe plugin bundles embedding
apm.lock.yamlwithpack.bundle_files. - Document the new bundle-restore workflow and add an
apm unpackdeprecation note.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/cli-commands.md | Adds CLI reference text for local-bundle installs. |
| docs/src/content/docs/guides/pack-distribute.md | Updates workflow, bundle-format details, restore docs, and unpack deprecation guidance. |
Copilot's findings
Comments suppressed due to low confidence (2)
docs/src/content/docs/guides/pack-distribute.md:309
- The deprecation timeline here doesn't match the CLI.
apm unpackcurrently warns that it will be removed in v0.14, not v0.13, and legacy--format apmbundles still requireapm unpackrather thanapm install <bundle>.
Extracts an APM bundle (produced with `--format apm`) into a project directory. Accepts both `.tar.gz` archives and unpacked bundle directories. Plugin-format output should be restored with `apm install <bundle>`, not `apm unpack`.
> **Deprecated**: `apm unpack` is deprecated as of v0.12. Use `apm install <bundle>` instead — it is the unified restore primitive for both plugin-format and APM-format bundles. `apm unpack` will be removed in v0.13.
docs/src/content/docs/reference/cli-commands.md:133
- This says the deployment is always recorded in the project lockfile, but
apm install <bundle> --globalwrites to the user-scope lockfile underPath.home(). The current wording is only correct for project-scope installs.
- `apm install <local-bundle>`: Restores a packed plugin bundle (directory or `.tar.gz`) produced by `apm pack`. Verifies the sha256 manifest embedded in the bundle's `apm.lock.yaml`, then deploys files to the target directory. Does not mutate `apm.yml`. Records deployed paths under `local_deployed_files` in the project lockfile. Rejected flags: `--resolver`, `--registry`, `--mcp`, `--policy`/`--no-policy`, `--skill`, `--dev`, `--update`, `--trust-transitive-mcp`, `--allow-insecure`. See [Pack & Distribute](../../guides/pack-distribute/#apm-install-bundle-restore) for the full workflow.
- Files reviewed: 2/2 changed files
- Comments generated: 3
| **Behavior:** | ||
| - `apm install` (no args): Installs **all** packages from `apm.yml` and deploys the project's own `.apm/` content | ||
| - `apm install <package>`: Installs **only** the specified package (adds to `apm.yml` if not present) | ||
| - `apm install <local-bundle>`: Restores a packed plugin bundle (directory or `.tar.gz`) produced by `apm pack`. Verifies the sha256 manifest embedded in the bundle's `apm.lock.yaml`, then deploys files to the target directory. Does not mutate `apm.yml`. Records deployed paths under `local_deployed_files` in the project lockfile. Rejected flags: `--resolver`, `--registry`, `--mcp`, `--policy`/`--no-policy`, `--skill`, `--dev`, `--update`, `--trust-transitive-mcp`, `--allow-insecure`. See [Pack & Distribute](../../guides/pack-distribute/#apm-install-bundle-restore) for the full workflow. |
| ## `apm install <bundle>` (restore) | ||
|
|
||
| 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`. | ||
| Restores a packed plugin bundle (directory or `.tar.gz`) produced by `apm pack`. This is the single restore primitive — matching the `pip install ./wheel` / `cargo install --path` mental model. |
| apm install ./build/my-plugin-1.0.0.tar.gz --dry-run | ||
| ``` | ||
|
|
||
| `apm install <bundle>` verifies the sha256 manifest embedded in the bundle's `apm.lock.yaml` before writing any files. Path-traversal entries are rejected at the install boundary. Installed paths are recorded in the project lockfile under `local_deployed_files` — `apm.yml` is never mutated. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation Updates - 2026-05-02
This PR updates the documentation based on features merged in the last 24 hours.
Features Documented
apm install <local-bundle>unified restore primitive (from feat(install): apm install <local-bundle> + lockfile-embedded plugin packs (#1098) #1099)apm.lock.yamlwith sha256 SBOM (from feat(install): apm install <local-bundle> + lockfile-embedded plugin packs (#1098) #1099)apm unpackdeprecated in v0.12, removal in v0.13 (from feat(install): apm install <local-bundle> + lockfile-embedded plugin packs (#1098) #1099)Changes Made
docs/src/content/docs/guides/pack-distribute.md:apm unpack->apm install <bundle>apm.lock.yamlis now embedded in plugin bundles withpack.bundle_filessha256 manifestapm.lock.yaml)apm install <bundle> (restore)section documenting the unified restore primitive, integrity verification, air-gapped behavior, and--as ALIASflagapm unpacksectiondocs/src/content/docs/reference/cli-commands.md:apm install <local-bundle>behavior entry to the Behavior list, linking to the pack-distribute guideMerged PRs Referenced
apm install <local-bundle>+ lockfile-embedded plugin packsNotes
PR #1090 (docs: show maintainer affiliations) and PRs #1093/#1102 (refactor: apm-review-panel) are internal changes that do not require user-facing documentation updates.
Note
🔒 Integrity filter blocked 2 items
The following items were blocked because they don't meet the GitHub integrity level.
search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".search_pull_requests: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".To allow these resources, lower
min-integrityin your GitHub frontmatter: