diff --git a/README.md b/README.md
index 0b2320bd..912f8d34 100644
--- a/README.md
+++ b/README.md
@@ -83,7 +83,7 @@ Pick one install target, then rerun `madar doctor` and `madar status` so the fir
 
 After you generate `out/graph.json`, `madar doctor` and `madar status` check the local install wiring for Claude Code, Cursor, Gemini CLI, and GitHub Copilot CLI. They also lint the AGENTS-based Madar instruction profiles for Codex CLI, OpenCode, and Aider; if a profile drifts, they mark the agent as `partial` and suggest the matching reinstall command.
 
-Install details, generated files, profiles, and uninstall behavior live in the [CLI and MCP reference](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md) and [compatibility guide](https://github.com/mohanagy/madar/blob/main/docs/integrations/compatibility.md).
+Install details, generated files, profiles, uninstall behavior, and verified copy/paste quickstarts live in the [CLI and MCP reference](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md), [compatibility guide](https://github.com/mohanagy/madar/blob/main/docs/integrations/compatibility.md), and [agent quickstarts](https://github.com/mohanagy/madar/blob/main/docs/tutorials/agent-quickstarts.md).
 
 **Without MCP**, compile a prompt or pack directly:
 
@@ -226,6 +226,7 @@ Limitations to know:
 | Need | Link |
 | --- | --- |
 | First run | [Getting started](https://github.com/mohanagy/madar/blob/main/docs/tutorials/getting-started.md) |
+| Agent quickstarts | [Agent quickstarts](https://github.com/mohanagy/madar/blob/main/docs/tutorials/agent-quickstarts.md) |
 | Small demo repo | [Sample workspace](https://github.com/mohanagy/madar/blob/main/docs/tutorials/sample-workspace.md) |
 | Context packs, Pack Schema v1, adaptive renderings | [Context packs and task evidence](https://github.com/mohanagy/madar/blob/main/docs/concepts/context-packs.md) |
 | CLI commands, MCP tools, agent installers | [CLI and MCP reference](https://github.com/mohanagy/madar/blob/main/docs/reference/cli-and-mcp.md) |
diff --git a/docs/integrations/compatibility.md b/docs/integrations/compatibility.md
index fb971891..8e46a019 100644
--- a/docs/integrations/compatibility.md
+++ b/docs/integrations/compatibility.md
@@ -2,6 +2,8 @@
 
 This guide is the user-facing install matrix for the current CLI contract. It focuses on the commands users actually run, the files each path writes, how to verify the result, and the most important behavior or limitation to know before choosing a surface.
 
+If you want one copy/paste walkthrough per main agent target, use the [agent quickstarts](https://github.com/mohanagy/madar/blob/main/docs/tutorials/agent-quickstarts.md) after you pick a row from this matrix.
+
 ## Dedicated project install commands
 
 These commands write repo-local instructions, hooks, rules, MCP config, or plugins for the current checkout. Some of them also install a matching home skill when that is part of the current dedicated flow.
diff --git a/docs/tutorials/agent-quickstarts.md b/docs/tutorials/agent-quickstarts.md
new file mode 100644
index 00000000..5d25a446
--- /dev/null
+++ b/docs/tutorials/agent-quickstarts.md
@@ -0,0 +1,157 @@
+# Agent quickstarts
+
+Use this page when you already know which agent you want to wire and you want one verified install path plus one copy/paste Smoke test.
+
+Before any agent-specific install, start with the [getting started tutorial](https://github.com/mohanagy/madar/blob/main/docs/tutorials/getting-started.md) and its one-command trial flow so the repo has a graph and you know Madar itself is behaving locally:
+
+```bash
+madar try "how does auth work?"
+madar generate . --no-html
+```
+
+That trial flow is the shared baseline for every quickstart below.
+
+## Claude Code
+
+- Install: `madar claude install [--profile core\|full\|strict]`
+- Expected files/config: `CLAUDE.md`, `.claude/settings.json`, `.mcp.json`
+- Verify: `madar doctor` / `madar status`
+
+```bash
+madar claude install
+madar doctor
+madar status
+madar pack "how does password reset request enqueue the reset email" --task explain
+```
+
+Known limitation: The `UserPromptSubmit` hook only injects guidance for local code tasks.
+
+Common failure modes:
+
+- If `madar doctor` says the MCP wiring is missing, rerun the install command from the repo root.
+- If the agent ignores Madar guidance, inspect `CLAUDE.md` and `.claude/settings.json` before reinstalling.
+
+## Cursor
+
+- Install: `madar cursor install [--profile core\|full\|strict]`
+- Expected files/config: `.cursor/rules/madar.mdc`, `.cursor/mcp.json`
+- Verify: `madar doctor` / `madar status`
+
+```bash
+madar cursor install
+madar doctor
+madar status
+madar pack "how does password reset request enqueue the reset email" --task explain
+```
+
+Known limitation: Cursor has no separate prompt hook; the rule file plus MCP config are the managed surface.
+
+Common failure modes:
+
+- If Cursor does not show the MCP server, confirm `.cursor/mcp.json` exists and rerun the install from the project root.
+- If the rule file drifted, compare `.cursor/rules/madar.mdc` against the generated version and reinstall.
+
+## GitHub Copilot CLI
+
+- Install: `madar copilot install [--profile core\|full\|strict]`
+- Expected files/config: `~/.copilot/skills/madar/SKILL.md`, `.vscode/mcp.json`
+- Verify: `madar doctor` / `madar status` for `.vscode/mcp.json`, then inspect the installed home skill for slash-command availability.
+
+```bash
+madar copilot install
+madar doctor
+madar status
+madar pack "how does password reset request enqueue the reset email" --task explain
+```
+
+Known limitation: The repo-local verifier checks the MCP wiring; the home skill is a separate install surface.
+
+Common failure modes:
+
+- If the repo-local MCP verifier passes but slash commands are missing, inspect `~/.copilot/skills/madar/SKILL.md`.
+- If `.vscode/mcp.json` is missing, rerun the install inside the repo instead of relying on `madar install --platform copilot`.
+
+## Gemini CLI
+
+- Install: `madar gemini install [--profile core\|full\|strict]`
+- Expected files/config: `~/.gemini/skills/madar/SKILL.md`, `GEMINI.md`, `.gemini/settings.json`
+- Verify: `madar doctor` / `madar status` for `.gemini/settings.json`, then inspect the installed home skill for slash-command availability.
+
+```bash
+madar gemini install
+madar doctor
+madar status
+madar pack "how does password reset request enqueue the reset email" --task explain
+```
+
+Known limitation: Use `madar prompt --provider gemini` when you need a one-shot export instead of live MCP.
+
+Common failure modes:
+
+- If `GEMINI.md` exists but slash-command support is missing, inspect `~/.gemini/skills/madar/SKILL.md`.
+- If `.gemini/settings.json` drifted, rerun the install command from the repo root.
+
+## Codex CLI
+
+- Install: `madar codex install`
+- Expected files/config: `AGENTS.md`, `.codex/hooks.json`
+- Verify: `madar doctor` / `madar status`
+
+```bash
+madar codex install
+madar doctor
+madar status
+madar pack "how does password reset request enqueue the reset email" --task explain
+```
+
+This is an instruction-only plus hook quickstart. Known limitation: No project-local MCP entry is installed for Codex.
+
+Common failure modes:
+
+- If `madar status` marks Codex as partial, inspect `.codex/hooks.json` and rerun the install.
+- If Codex ignores the guidance, confirm `AGENTS.md` still contains the Madar-owned rules.
+
+## Aider
+
+- Install: `madar aider install`
+- Expected files/config: `AGENTS.md`
+- Verify: `madar doctor` / `madar status`
+
+```bash
+madar aider install
+madar doctor
+madar status
+madar pack "how does password reset request enqueue the reset email" --task explain
+```
+
+This is an instruction-only quickstart. Known limitation: Aider has no PreToolUse-style hook equivalent.
+
+Common failure modes:
+
+- If `madar status` reports partial guidance, inspect `AGENTS.md` and rerun the install.
+- If you need portable context outside the AGENTS profile, switch to `madar pack` or `madar prompt`.
+
+## OpenCode
+
+- Install: `madar opencode install`
+- Expected files/config: `AGENTS.md`, `.opencode/plugins/madar.js`, `opencode.json` or `opencode.jsonc`
+- Verify: `madar doctor` / `madar status`
+
+```bash
+madar opencode install
+madar doctor
+madar status
+madar pack "how does password reset request enqueue the reset email" --task explain
+```
+
+Known limitation: Verification expects the Madar-owned plugin and `mcp.madar` entry to stay intact.
+
+Common failure modes:
+
+- If verification fails, inspect `.opencode/plugins/madar.js` plus the `mcp.madar` entry in `opencode.json` or `opencode.jsonc`.
+- If the plugin exists but the MCP entry was replaced, rerun the install to restore the Madar-owned wiring.
+
+## Not currently supported as verified quickstarts
+
+- VS Code + GitHub Copilot extension is not a supported quickstart today. Use the GitHub Copilot CLI path above instead.
+- Claw, Factory Droid, Trae, and Trae CN stay outside the verified quickstart set because they are skill-only or instruction-only paths without the same repo-local doctor/status proof.
diff --git a/tests/unit/install-compatibility.test.ts b/tests/unit/install-compatibility.test.ts
index 520565ba..cbe2291b 100644
--- a/tests/unit/install-compatibility.test.ts
+++ b/tests/unit/install-compatibility.test.ts
@@ -30,6 +30,15 @@ interface CompatibilityRow {
 }
 
 type HomeSkillPlatform = Exclude<InstallPlatform, 'cursor' | 'gemini'>
+const PRIMARY_QUICKSTART_PLATFORMS = new Set<InstallPlatform>([
+  'claude',
+  'cursor',
+  'copilot',
+  'gemini',
+  'aider',
+  'codex',
+  'opencode',
+])
 
 const DEDICATED_COMMAND_ROWS: CompatibilityRow[] = [
   {
@@ -357,6 +366,26 @@ describe('install compatibility guide', () => {
     expect(readme).toContain('docs/integrations/compatibility.md')
   })
 
+  it('publishes verified quickstarts and smoke tests for the primary agent targets', () => {
+    const readme = readFileSync(resolve('README.md'), 'utf8')
+    const quickstarts = readFileSync(resolve('docs/tutorials/agent-quickstarts.md'), 'utf8')
+
+    expect(readme).toContain('docs/tutorials/agent-quickstarts.md')
+    expect(quickstarts).toContain('# Agent quickstarts')
+    expect(quickstarts).toContain('madar try')
+    expect(quickstarts).toContain('docs/tutorials/getting-started.md')
+    expect(quickstarts).toContain('Smoke test')
+    expect(quickstarts).toContain('Common failure modes')
+    expect(quickstarts).toContain('not a supported quickstart')
+    expect(quickstarts).toContain('instruction-only')
+
+    for (const row of DEDICATED_COMMAND_ROWS.filter((candidate) => PRIMARY_QUICKSTART_PLATFORMS.has(candidate.platform))) {
+      for (const expected of [row.label, row.command, ...row.docArtifacts, row.verify, row.limitation]) {
+        expect(quickstarts).toContain(expected)
+      }
+    }
+  })
+
   it('covers the documented install commands, artifacts, verification paths, profiles, and limitations', () => {
     const compatibilityGuide = readFileSync(resolve('docs/integrations/compatibility.md'), 'utf8')