docs: update agent setup content

Author: codeaholicguy

web/content/docs/9-agent-setup.md

@@ -5,7 +5,7 @@ slug: agent-setup
 order: 10
 ---
 
-The `ai-devkit install` command applies your saved project configuration (`.ai-devkit.json`) to your workspace.  
+The `ai-devkit install` command applies your saved project configuration (`.ai-devkit.json`) to your workspace.
 It is the best command for repeatable setup, onboarding, and syncing agent files after configuration changes.
 
 Before running these commands:
@@ -18,6 +18,7 @@ Use `ai-devkit init` when:
 - You are setting up AI DevKit in a project for the first time
 - You want interactive prompts to choose environments and phases
 - You want non-interactive bootstrap from a template file (`ai-devkit init --template`)
+- You want to install AI DevKit built-in skills (prompted interactively, or pass `--built-in` for CI)
 
 Use `ai-devkit install` when:
 - `.ai-devkit.json` already exists
@@ -26,6 +27,34 @@ Use `ai-devkit install` when:
 
 ## Basic Usage
 
+The simplest way to get started is the interactive setup. This walks you through choosing environments, phases, and built-in skills:
+
+```bash
+ai-devkit init
+```
+
+Once `.ai-devkit.json` exists in your project, apply or re-apply the setup with:
+
+```bash
+ai-devkit install
+```
+
+Use a non-default config file if your project stores AI DevKit config elsewhere:
+
+```bash
+ai-devkit install --config ./.ai-devkit.team.json
+```
+
+Overwrite existing install artifacts without extra prompts:
+
+```bash
+ai-devkit install --overwrite
+```
+
+### Template-based Setup
+
+For repeatable, non-interactive setup, create a template file. This is useful for sharing a standard configuration across teams or running in CI.
+
 Create a file named `fullstack-engineer.yaml` in your project root with this content:
 
 ```yaml
@@ -39,6 +68,8 @@ phases:
   - planning
   - implementation
   - testing
+paths:
+  docs: docs/ai
 skills:
   - registry: codeaholicguy/ai-devkit
     skill: debug
@@ -52,30 +83,44 @@ Initialize from that template:
 ai-devkit init --template ./fullstack-engineer.yaml
 ```
 
-If `.ai-devkit.json` already exists in this project, apply setup with:
+Use a custom directory for AI documentation (default is `docs/ai`):
 
 ```bash
-ai-devkit install
+ai-devkit init --docs-dir ./ai-docs
 ```
 
-Use a non-default config file if your project stores AI DevKit config elsewhere:
+#### Adding MCP Servers to a Template
 
-```bash
-ai-devkit install --config ./.ai-devkit.team.json
+Templates can also define [MCP servers](https://modelcontextprotocol.io/) that agents connect to for extended capabilities such as persistent memory or external tool access. Add a `mcpServers` section to your template:
+
+```yaml
+mcpServers:
+  memory:
+    transport: stdio
+    command: npx
+    args:
+      - "@ai-devkit/memory"
 ```
 
-Overwrite existing install artifacts without extra prompts:
+After running `ai-devkit init --template`, MCP server definitions are saved to `.ai-devkit.json`. Run `ai-devkit install` to generate the agent-specific MCP config files.
+
+## Built-in Skills
+
+When running `ai-devkit init` interactively (without a template), you are prompted to install AI DevKit's built-in skills. In non-interactive environments such as CI, pass `--built-in` to install them automatically:
 
 ```bash
-ai-devkit install --overwrite
+ai-devkit init --environment cursor,claude --all --built-in
 ```
 
+When using a template with a `skills` section, skills from the template are installed instead of the built-in prompt.
+
 ## What `ai-devkit install` Sets Up
 
 Based on your configured environments, AI DevKit installs or updates files such as:
 - `AGENTS.md` or `CLAUDE.md`
 - Environment command folders (for example `.cursor/commands/`, `.claude/commands/`, `.codex/commands/`)
 - Agent skill files (for example `.cursor/skills/`, `.claude/skills/`, `.agents/skills/` for Codex, and `.agent/skills/` for Antigravity)
+- MCP server configuration files for supported environments
 - Other environment-specific templates defined by AI DevKit
 
 The exact artifacts depend on the environments configured in `.ai-devkit.json`.
@@ -90,7 +135,7 @@ The exact artifacts depend on the environments configured in `.ai-devkit.json`.
 ai-devkit init
 ```
 
-Or initialize deterministically from template:
+Or initialize deterministically from a template:
 
 ```bash
 ai-devkit init --template ./fullstack-engineer.yaml
@@ -118,7 +163,7 @@ ai-devkit init
 
 This creates the configuration file used by `install`.
 
-If you prefer non-interactive setup, use the template command shown in Basic Usage.
+If you prefer non-interactive setup, use the template command shown in [Template-based Setup](#template-based-setup).
 
 ### Existing files are not updated