diff --git a/docs/src/content/docs/guides/dependencies.md b/docs/src/content/docs/guides/dependencies.md
index 4b8a5702..38f0550c 100644
--- a/docs/src/content/docs/guides/dependencies.md
+++ b/docs/src/content/docs/guides/dependencies.md
@@ -336,6 +336,32 @@ mcp:
 - `url` — required for `http`, `sse`, `streamable-http` transports
 - `command` — required for `stdio` transport
 
+#### `${input:...}` Variable Resolution
+
+You can use `${input:<id>}` placeholders in `env` and `headers` values for secrets that should be prompted at runtime rather than stored in files:
+
+```yaml
+mcp:
+  - name: internal-knowledge-base
+    registry: false
+    transport: http
+    url: "https://mcp.internal.example.com"
+    env:
+      API_TOKEN: "${input:api-token}"
+    headers:
+      Authorization: "Bearer ${input:api-token}"
+```
+
+When targeting **VS Code / Copilot extension** (`.vscode/mcp.json`), APM automatically generates matching `inputs` entries that prompt users for the value at runtime — no additional configuration needed.
+
+For runtimes that don't support input prompts (**Copilot CLI**, **Codex CLI**), APM emits a warning during `apm install` so you know the placeholder will remain unresolved:
+
+```
+[!]  Warning: ${input:api-token} in server 'internal-knowledge-base' will not be resolved — Copilot CLI does not support input variable prompts
+```
+
+For those runtimes, `${input:...}` and `${VAR}` placeholders in `env`/`headers` are not resolved and will be written literally. Omit secrets from your `apm.yml` and set any required API tokens as real environment variables in your shell or Copilot/Codex CLI configuration so the runtime process inherits them normally.
+
 ⚠️ **Transitive trust rule:** Self-defined servers from direct dependencies (depth=1 in the lockfile) are auto-trusted. Self-defined servers from transitive dependencies (depth > 1) are skipped with a warning by default. You can either re-declare them in your own `apm.yml`, or use `--trust-transitive-mcp` to trust all self-defined servers from upstream packages:
 
 ```bash
diff --git a/docs/src/content/docs/reference/cli-commands.md b/docs/src/content/docs/reference/cli-commands.md
index 9ee13cfb..23d47069 100644
--- a/docs/src/content/docs/reference/cli-commands.md
+++ b/docs/src/content/docs/reference/cli-commands.md
@@ -211,10 +211,11 @@ When you run `apm install`, APM automatically integrates primitives from install
 
 **Diagnostic Summary:**
 
-After installation completes, APM prints a grouped diagnostic summary instead of inline warnings. Categories include collisions (skipped files), cross-package skill replacements, warnings, and errors.
+After installation completes, APM prints a grouped diagnostic summary instead of inline warnings. Categories include collisions (skipped files), cross-package skill replacements, info hints, warnings, and errors.
 
 - **Normal mode**: Shows counts and actionable tips (e.g., "9 files skipped -- use `apm install --force` to overwrite")
 - **Verbose mode** (`--verbose`): Additionally lists individual file paths grouped by package, and full error details
+- **Info hints** (`[i]`): Guidance shown when beneficial but non-blocking — for example, a reminder to pin dependency versions when any dependency has no explicit ref
 
 ```bash
 # See exactly which files were skipped or had issues