docs(web): improve agent setup guide with template-based init

Author: codeaholicguy

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

@@ -0,0 +1,134 @@
+---
+title: Agent Setup
+description: Use `ai-devkit install` to apply or reconcile AI agent setup from your project configuration.
+---
+
+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:
+- Install AI DevKit (`npm install -g ai-devkit`) or use `npx ai-devkit@latest ...`
+- Run commands from your project root directory
+
+## When to Use `install` vs `init`
+
+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`)
+
+Use `ai-devkit install` when:
+- `.ai-devkit.json` already exists
+- You want deterministic setup without re-answering prompts
+- You want to reconcile missing agent files or command folders
+
+## Basic Usage
+
+Create a file named `fullstack-engineer.yaml` in your project root with this content:
+
+```yaml
+environments:
+  - cursor
+  - claude
+  - codex
+phases:
+  - requirements
+  - design
+  - planning
+  - implementation
+  - testing
+skills:
+  - registry: codeaholicguy/ai-devkit
+    skill: debug
+  - registry: codeaholicguy/ai-devkit
+    skill: dev-lifecycle
+```
+
+Initialize from that template:
+
+```bash
+ai-devkit init --template ./fullstack-engineer.yaml
+```
+
+If `.ai-devkit.json` already exists in this project, apply setup with:
+
+```bash
+ai-devkit install
+```
+
+Overwrite existing install artifacts without extra prompts:
+
+```bash
+ai-devkit install --overwrite
+```
+
+## 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/`)
+- Other environment-specific templates defined by AI DevKit
+
+The exact artifacts depend on the environments configured in `.ai-devkit.json`.
+
+## Typical Agent Setup Flow
+
+1. Initialize once:
+
+```bash
+ai-devkit init
+```
+
+Or initialize deterministically from template:
+
+```bash
+ai-devkit init --template ./fullstack-engineer.yaml
+```
+
+2. Commit `.ai-devkit.json` to your repository.
+
+3. On another machine or for another teammate, run:
+
+```bash
+ai-devkit install
+```
+
+This keeps agent setup consistent across contributors and CI-like automation workflows.
+
+## Troubleshooting
+
+### `.ai-devkit.json` not found
+
+Run:
+
+```bash
+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.
+
+### Existing files are not updated
+
+If you want to force replacement of install-managed artifacts, run:
+
+```bash
+ai-devkit install --overwrite
+```
+
+### I changed environments but setup still looks old
+
+Re-run:
+
+```bash
+ai-devkit install
+```
+
+This re-applies setup using the current `.ai-devkit.json` content.
+
+## Next Steps
+
+- [Supported AI Agents & Environments](/docs/2-supported-agents)
+- [Getting Started](/docs/1-getting-started)
+- [Development with AI DevKit](/docs/3-development-with-ai-devkit)