[docs] Update documentation for features from 2026-03-26#461
[docs] Update documentation for features from 2026-03-26#461danielmeppiel wants to merge 1 commit intomainfrom
Conversation
- installation.md: add troubleshooting entry for glibc/devcontainer binary fallback to pip (#451) - skills.md: clarify presence-driven target deployment; Copilot always active, others deploy only when root dir exists; fix .opencode note (#453, #447) - lockfile-spec.md: document idempotent install -- no rewrite when dependencies are unchanged (#450) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
danielmeppiel
added
automation
documentation
There was a problem hiding this comment.
Pull request overview
Updates user-facing documentation to reflect recently merged behavior fixes (installer pip fallback on incompatible Linux binaries, presence-driven multi-target skill deployment including OpenCode, and idempotent lockfile writes).
Changes:
- Add installation troubleshooting note for older-Linux/devcontainer binary incompatibility and automatic pip fallback.
- Update skills guide to describe presence-driven target activation and skill deployment to active targets (including
.opencode/skills/). - Update lockfile spec lifecycle table to document idempotent
apm installlockfile writes (no timestamp churn when unchanged).
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/src/content/docs/getting-started/installation.md | Documents installer behavior when the binary cannot run on older glibc systems and the pip fallback path. |
| docs/src/content/docs/guides/skills.md | Updates skill integration + target detection docs to match presence-driven deployment and OpenCode support. |
| docs/src/content/docs/reference/lockfile-spec.md | Notes idempotent lockfile write behavior for subsequent installs. |
Comments suppressed due to low confidence (1)
docs/src/content/docs/guides/skills.md:304
- The docs suggest
apm install ... --target vscode, but the install command does not appear to support a--target/-toption (target flags exist onapm compile/apm pack). This "Override" example is likely misleading; consider removing theapm installexample or replacing it withapm compile --target ...and/or theapm.ymltarget:setting.
Override with:
```bash
apm install skill-name --target vscode
apm compile --target claude
</details>
| - **Compatibility**: `.claude/skills/{skill-name}/` — Only if `.claude/` folder already exists | ||
| - **Compatibility**: `.cursor/skills/{skill-name}/` — Only if `.cursor/` folder already exists | ||
| - **Compatibility**: `.opencode/skills/{skill-name}/` — Only if `.opencode/` folder already exists | ||
| - **Copilot (always)**: `.github/skills/{skill-name}/` — Created automatically; works with Copilot, Codex, Gemini |
There was a problem hiding this comment.
This line uses a Unicode em dash ("—"), which violates the repo's ASCII-only documentation/output policy (non-ASCII chars can break Windows cp1252 terminals). Replace it with an ASCII alternative like " - " or "--" and keep the line strictly within printable ASCII.
| - **Copilot (always)**: `.github/skills/{skill-name}/` — Created automatically; works with Copilot, Codex, Gemini | |
| - **Copilot (always)**: `.github/skills/{skill-name}/` - Created automatically; works with Copilot, Codex, Gemini |
| ### Binary install fails on older Linux (devcontainers, Debian Bookworm) | ||
|
|
||
| On systems with glibc older than 2.39 (e.g., Debian Bookworm with glibc 2.36), the | ||
| pre-built binary may fail to run. The installer automatically detects this and falls | ||
| back to `pip install`: |
There was a problem hiding this comment.
The glibc version threshold here doesn't match the current installer logic: install.sh performs an early glibc check with REQUIRED_GLIBC="2.35" and triggers pip fallback when glibc is older than that. With the current docs ("older than 2.39" / Bookworm 2.36), readers may expect a fallback on systems where the script would not trigger it. Update the docs to reflect the actual required glibc version (or keep it generic: "older than the required glibc version").
| ### Binary install fails on older Linux (devcontainers, Debian Bookworm) | |
| On systems with glibc older than 2.39 (e.g., Debian Bookworm with glibc 2.36), the | |
| pre-built binary may fail to run. The installer automatically detects this and falls | |
| back to `pip install`: | |
| ### Binary install fails on older Linux (devcontainers, Debian-based images) | |
| On systems with a glibc version older than the minimum required by the pre-built | |
| binary, the binary may fail to run. The installer automatically detects incompatible | |
| glibc versions and falls back to `pip install`: |
| back to `pip install`: | ||
|
|
||
| ``` | ||
| [!] Binary failed (glibc mismatch). Falling back to pip install... | ||
| [+] apm installed via pip | ||
| ``` | ||
|
|
||
| No manual action is required. If you prefer to install via pip directly: | ||
|
|
||
| ```bash | ||
| pip install apm-cli |
There was a problem hiding this comment.
This section says "No manual action is required", but the installer falls back to pip install --user apm-cli and may require the user to add ~/.local/bin to PATH if apm is not found. Consider adjusting the wording to mention the possible PATH update (and avoid presenting exact output lines unless they match the script's messages).
| back to `pip install`: | |
| ``` | |
| [!] Binary failed (glibc mismatch). Falling back to pip install... | |
| [+] apm installed via pip | |
| ``` | |
| No manual action is required. If you prefer to install via pip directly: | |
| ```bash | |
| pip install apm-cli | |
| back to installing APM via `pip install --user apm-cli`. | |
| This installs the `apm` command into your user `bin` directory (commonly `~/.local/bin`). | |
| If `apm` is not found after installation, ensure that this directory is on your `PATH`. | |
| If you prefer to install via pip directly: | |
| ```bash | |
| pip install --user apm-cli |
| |-------|----------------------| | ||
| | `apm install` (first run) | Created. All dependencies resolved, commits pinned, files recorded. | | ||
| | `apm install` (subsequent) | Read. Locked commits reused. New dependencies appended. | | ||
| | `apm install` (subsequent) | Read. Locked commits reused. New dependencies appended. File only written if dependencies changed (idempotent -- no `generated_at` churn when content is unchanged). | |
There was a problem hiding this comment.
This row says the lockfile is only written if "dependencies" changed, but the implementation skips writing when the lockfile is semantically equivalent, which also considers mcp_servers, mcp_configs, and lockfile_version (and ignores generated_at/apm_version). To avoid under-specifying the behavior, consider rewording to "only written if semantic content changed" (deps and MCP-related fields), rather than only dependencies.
| | `apm install` (subsequent) | Read. Locked commits reused. New dependencies appended. File only written if dependencies changed (idempotent -- no `generated_at` churn when content is unchanged). | | |
| | `apm install` (subsequent) | Read. Locked commits reused. New dependencies appended. File only written when semantic content changes (dependencies, MCP servers/configs, `lockfile_version`); no churn from `generated_at` or `apm_version` fields. | |
|
thanks @danielmeppiel for putting this PR together the glibc issue solved on my end was moving from the Microsoft devcontainer's 24-bookworm to 24-trixie which has the glibc compatible version. Perhaps some notes on that on the README or on the failure could help agents/humans quickly understand the error and the go-to fix. |
Documentation Updates - 2026-03-26
This PR updates the documentation based on fixes merged in the last 24 hours (#456).
Features Documented
apm installnorapm compileadd skills from third-party transitive dependencies #447)Changes Made
Updated
docs/src/content/docs/getting-started/installation.md: Added troubleshooting entry for binary install failures on older Linux (glibc < 2.39 / Debian Bookworm / devcontainers). Documents the automatic pip fallback behavior.Updated
docs/src/content/docs/guides/skills.md: Corrected Step 2 description and Target Detection table to accurately reflect presence-driven deployment. Copilot (.github/skills/) is always active; Claude, Cursor, and OpenCode only deploy when their root directory exists. Also clarifies that.opencode/skills/now receives skill deployments.Updated
docs/src/content/docs/reference/lockfile-spec.md: Updated the lifecycle table to document thatapm installis idempotent -- the lockfile is only written when dependencies actually change, eliminatinggenerated_attimestamp churn in version control.Merged PRs Referenced
Notes
All three changes are user-facing behavior fixes that were missing from docs. No breaking changes to document.