diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md
index f40da1fa..2e69e3f3 100644
--- a/docs/src/content/docs/getting-started/installation.md
+++ b/docs/src/content/docs/getting-started/installation.md
@@ -145,6 +145,27 @@ mkdir -p ~/bin
 # then install the binary to ~/bin/apm and add ~/bin to PATH
 ```
 
+### Binary install fails on older Linux (devcontainers, Debian-based images)
+
+On systems with a glibc version older than what the pre-built binary requires, the
+binary will fail to run. This commonly affects Debian Bookworm-based devcontainers
+(glibc 2.36) since the binary is built on Ubuntu 24.04 (glibc 2.39). The installer
+automatically detects incompatible glibc versions and falls back to
+`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`.
+
+**Recommended fix for devcontainers:** switch your base image from `bookworm` to
+`trixie` (e.g., `mcr.microsoft.com/devcontainers/universal:24-trixie`), which ships
+glibc 2.40+ and runs the pre-built binary directly.
+
+If you prefer to install via pip directly:
+
+```bash
+pip install --user apm-cli
+```
+
 ### Authentication errors when installing packages
 
 See [Authentication -- Troubleshooting](../authentication/#troubleshooting) for token setup, SSO authorization, and diagnosing auth failures.
diff --git a/docs/src/content/docs/reference/lockfile-spec.md b/docs/src/content/docs/reference/lockfile-spec.md
index 36962cd6..222fc753 100644
--- a/docs/src/content/docs/reference/lockfile-spec.md
+++ b/docs/src/content/docs/reference/lockfile-spec.md
@@ -52,7 +52,7 @@ The lock file serves four goals:
 | Event | Effect on `apm.lock.yaml` |
 |-------|----------------------|
 | `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 when semantic content changes (dependencies, MCP servers/configs, `lockfile_version`); no churn from `generated_at` or `apm_version` fields. |
 | `apm install --update` | Re-resolved. All refs re-resolved to latest matching commits. |
 | `apm deps update` | Re-resolved. Refreshes versions for specified or all dependencies. |
 | `apm pack` | Enriched. A `pack:` section is prepended to the bundled copy (see [section 6](#6-pack-enrichment)). |