[docs] Update documentation for features from 2026-03-26

[danielmeppiel]

Description

Updates user-facing documentation to reflect recently merged behavior fixes from #456.

Features Documented

• Installer pip fallback for devcontainers with older glibc (from fix: batch bug fixes -- installer fallback, target registry, lockfile idempotency #456 / [BUG] installer fails inside a devcontainer #451)
• Skill deployment to all active targets via presence-driven target registry (from fix: batch bug fixes -- installer fallback, target registry, lockfile idempotency #456 / [BUG] always installing to .github #453, [BUG] Neither apm install nor apm compile add skills from third-party transitive dependencies #447)
• Lockfile idempotency -- no rewrite when dependencies unchanged (from fix: batch bug fixes -- installer fallback, target registry, lockfile idempotency #456 / [BUG] apm.lock.yaml changes on every apm install due to generated_at timestamp #450)

Changes Made

• Updated docs/src/content/docs/getting-started/installation.md: Added troubleshooting entry for binary install failures on older Linux (devcontainers, Debian-based images). Uses a generic glibc version reference instead of hardcoding a specific version, explains the Bookworm/Ubuntu 24.04 mismatch as context, documents the automatic pip fallback behavior and PATH considerations, and includes a recommended fix for devcontainers (switch from bookworm to trixie). Also fixed a broken markdown code block that was missing the pip install command and closing fence.

• 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. Fixed Unicode em dash to ASCII per repo encoding policy.

• Updated docs/src/content/docs/reference/lockfile-spec.md: Updated the lifecycle table to document that apm install is idempotent -- the lockfile is only written when semantic content changes (dependencies, MCP servers/configs, lockfile_version), with no churn from generated_at or apm_version fields.

Notes

All three changes are user-facing behavior fixes that were missing from docs. No breaking changes to document.

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[Copilot]

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 install lockfile 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/-t option (target flags exist on apm compile/apm pack). This "Override" example is likely misleading; consider removing the apm install example or replacing it with apm compile --target ... and/or the apm.yml target: setting.

Override with:
```bash
apm install skill-name --target vscode
apm compile --target claude

</details>

[Copilot]

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").

Suggested change

	### 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`:

[lirantal]

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.

[danielmeppiel]

@copilot take this into account and improve docs "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."

[Copilot]

@copilot take this into account and improve docs "the glibc issue solved on my end was moving from the Microsoft devcontainer's 24-bookworm to 24-trixie which has the glibc compatible ...

Updated in 52541ea. The troubleshooting section now:

• Uses a generic glibc version reference instead of hardcoding 2.39 (matches the reviewer feedback about REQUIRED_GLIBC="2.35" in install.sh)
• Explains why Bookworm-based devcontainers are affected (glibc 2.36 vs binary built on Ubuntu 24.04 with glibc 2.39)
• Adds a Recommended fix for devcontainers callout: switch from bookworm to trixie (e.g., mcr.microsoft.com/devcontainers/universal:24-trixie)
• Fixes the broken code block that was missing the pip install --user apm-cli command and closing fence