diff --git a/docs/src/content/docs/getting-started/first-package.md b/docs/src/content/docs/getting-started/first-package.md
index 0fd783b0..9e9b1ff3 100644
--- a/docs/src/content/docs/getting-started/first-package.md
+++ b/docs/src/content/docs/getting-started/first-package.md
@@ -48,9 +48,16 @@ author: your-handle
 dependencies:
   apm: []
   mcp: []
+includes: auto
 scripts: {}
 ```
 
+`includes: auto` is the field that makes step 4 work: with no remote
+dependencies declared, `apm install` walks your local `.apm/` tree
+and deploys what it finds. Set `includes: []` (or omit the field) and
+local content stops deploying. Override with an explicit list of
+paths to gate exactly what ships.
+
 ## 2. Add a skill
 
 A **skill** is a chunk of expertise that the runtime activates automatically
@@ -169,11 +176,17 @@ Output:
 
 ```
 [+] <project root> (local)
-|-- 1 agent integrated -> .github/agents/
-|-- 1 skill(s) integrated -> .github/skills/
+|-- 1 agents integrated -> .github/agents/
+|-- 1 skill(s) integrated -> .agents/skills/
 [i] Added apm_modules/ to .gitignore
 ```
 
+Note the split: **agents** are runtime-specific and land under
+`.github/agents/` (Copilot's directory). **Skills** land under
+`.agents/skills/` -- the cross-client universal location that
+Copilot, Cursor, OpenCode, Codex, and Gemini all read. Claude Code
+is the exception: it reads `.claude/skills/`.
+
 Your tree now has source on the left and runtime-ready output on the right:
 
 ```
@@ -183,9 +196,10 @@ team-skills/
 |   |   +-- pr-description/SKILL.md
 |   +-- agents/
 |       +-- team-reviewer.agent.md
-+-- .github/                           # generated by apm install
++-- .agents/                           # generated -- cross-client skills
 |   +-- skills/
-|   |   +-- pr-description/SKILL.md
+|       +-- pr-description/SKILL.md
++-- .github/                           # generated -- runtime-specific
 |   +-- agents/
 |       +-- team-reviewer.agent.md
 +-- apm.yml