From d05ac13bfcb9dfafeb27943ca617517d454911d4 Mon Sep 17 00:00:00 2001
From: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
Date: Mon, 4 May 2026 13:20:55 +0200
Subject: [PATCH] docs: fix first-package guide (includes: auto, skill paths)

Three corrections, all verified empirically against latest main:

1. The shown apm.yml is missing 'includes: auto'. apm init -y emits
   that field today (added in #887 so day-2 audits don't surprise the
   maintainer with an 'includes not declared' advisory). Without it,
   step 4's 'apm install with no args deploys local content' is a lie.

2. Explain WHY apm install (no args) deploys .apm/. The mechanism is
   includes: auto -- it's the load-bearing field the previous version
   left invisible. Without this paragraph, removing the field looks
   harmless and silently breaks local deployment.

3. Skill output path was wrong. Post-skill-routing convergence,
   skills land under .agents/skills/ (the cross-client universal
   location) for Copilot/Cursor/OpenCode/Codex/Gemini. Only Claude
   keeps .claude/skills/. The doc still showed .github/skills/ for
   both the install output snippet and the tree diagram.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../docs/getting-started/first-package.md     | 22 +++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/docs/src/content/docs/getting-started/first-package.md b/docs/src/content/docs/getting-started/first-package.md
index 0fd783b0a..9e9b1ff36 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