diff --git a/docs/src/content/docs/troubleshooting/install-failures.md b/docs/src/content/docs/troubleshooting/install-failures.md
index 1f9766489..d0df938b8 100644
--- a/docs/src/content/docs/troubleshooting/install-failures.md
+++ b/docs/src/content/docs/troubleshooting/install-failures.md
@@ -166,7 +166,24 @@ apm audit --check drift
 
 A non-zero exit means the working tree has diverged from `apm.lock.yaml` -- either re-run `apm install` to restore parity, or commit the new lockfile if the drift was intentional.
 
-For the full flag list see [`apm install`](../reference/cli/install/).
+### Policy blocked after lockfile wipe
+
+If `apm install` fails with `Policy violation: required-packages-deployed` right after a lockfile wipe, hand-edit, or partial-install crash, the lockfile has an empty `deployed_files` list for a required package even though the files are on disk.
+
+Re-run `apm install` -- APM now auto-adopts byte-identical existing files and repopulates `deployed_files`, which lets the policy gate pass:
+
+```bash
+apm install
+```
+
+On APM versions older than v0.14, use `--no-policy` once to break the loop:
+
+```bash
+apm install --no-policy   # one-time: repopulates deployed_files
+apm install               # policy now passes
+```
+
+For full diagnosis of policy failures, see [Debugging policy failures](./policy-debugging/).
 
 ## 4. Cache problems
 
diff --git a/docs/src/content/docs/troubleshooting/policy-debugging.md b/docs/src/content/docs/troubleshooting/policy-debugging.md
index 589285102..f50b029bc 100644
--- a/docs/src/content/docs/troubleshooting/policy-debugging.md
+++ b/docs/src/content/docs/troubleshooting/policy-debugging.md
@@ -87,6 +87,9 @@ Common surprises:
 - A child sets `mcp.transport.allow: [stdio, http]` but the parent
   pinned `[http]` -- the child's broader list is ignored.
 - Severity can only be raised by a child, never lowered.
+- `dependencies.require` and `dependencies.deny` from an org floor are
+  correctly inherited when a repo policy uses `extends: org`. An absent
+  repo-level block no longer silently drops the org requirement.
 
 The full merge semantics live in
 [Policy schema -> Merge rules (tighten-only)](../reference/policy-schema/#merge-rules-tighten-only).
@@ -171,6 +174,23 @@ shortest path to green.
   defines the required set; check
   [Policy schema](../reference/policy-schema/).
 
+### `required-packages-deployed`
+
+- **Symptom:** `Policy violation: required-packages-deployed -- 1 required package(s) not deployed: <org>/<repo>/...` even though the package files appear to be on disk.
+- **Cause:** The lockfile (`apm.lock.yaml`) has an empty `deployed_files` list for the required package. This can happen after a lockfile wipe, a hand-edit, a partial-install crash, or an older APM build that did not record the entry. The policy gate runs before `apm install` deploys files, so it fires on the stale (empty) lockfile state.
+- **Fix (v0.14+):** Re-run `apm install`. APM now auto-adopts byte-identical existing files, which repopulates `deployed_files` without overwriting your content. The next `apm install` will then pass the policy gate.
+
+  ```bash
+  apm install          # repopulates deployed_files; policy passes on this run
+  ```
+
+- **Fix (older versions):** Use `--no-policy` once to break the loop, then run normally:
+
+  ```bash
+  apm install --no-policy   # one-time: repopulates deployed_files
+  apm install               # policy now passes
+  ```
+
 ### `unmanaged_files.action: deny`
 
 - **Symptom:** `Unmanaged file detected in target directory: