diff --git a/docs/src/content/docs/getting-started/installation.md b/docs/src/content/docs/getting-started/installation.md
index ca5cb0669..125e8cccf 100644
--- a/docs/src/content/docs/getting-started/installation.md
+++ b/docs/src/content/docs/getting-started/installation.md
@@ -169,6 +169,27 @@ Use `sudo` for system-wide installation, or install to a user-writable directory
 curl -sSL https://aka.ms/apm-unix | APM_INSTALL_DIR=$HOME/.local/bin sh
 ```
 
+### 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 (currently glibc 2.35), the binary will fail to run. 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 on very old base images:** switch to a base
+image with glibc 2.35 or newer (e.g., the Debian `trixie` family, or
+`mcr.microsoft.com/devcontainers/universal:24-trixie`), which runs the pre-built
+binary directly without the pip fallback.
+
+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 699645964..f39b42a61 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 --format apm` | Enriched. A `pack:` section is prepended to the bundled copy (see [section 6](#6-pack-enrichment)). Plugin format (the default) does not emit `apm.lock.yaml` inside the bundle. |