ai-driven-dev · alexsoyes · Jul 26, 2026
@@ -30,6 +30,6 @@ The recipe file at `aidd_docs/recipes/<slug>.md`, filled from the template.
 ## Test
 
 - A new or substantially-updated recipe is drafted from `research` results, not from memory.
-- `aidd_docs/recipes/<slug>.md` exists and follows the recipe contract: opens with a one-sentence description (no Goal label, no table), each step a `#### N)` emoji heading with a real example, no `<...>` placeholder left.
+- `aidd_docs/recipes/<slug>.md` exists and follows the recipe contract: opens with a one-sentence description (no Goal label, no table), uses `### N)` for direct steps or `#### N)` below a `###` category without skipping heading levels, gives every step a real example, and leaves no `<...>` placeholder.
 - A bundled recipe is never overwritten unless the user explicitly asks to change a bundled/framework recipe.
 - A new recipe that highly overlaps an existing project or bundled recipe triggers an update-or-create prompt before scaffolding.
@@ -1,50 +1,37 @@
-# <Recipe title>
+# Recipe title
 
 <One sentence describing what this recipe gets the reader.>
 
+- [Recipe title](#recipe-title)
+  - [Why](#why)
+  - [Steps to ](#steps-to-)
+    - [1)  First step title](#1--first-step-title)
+  - [Verify ](#verify-)
+
 ## Why
 
 <Short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.>
 
 ## Steps to <the outcome the reader achieves>
 
-### 🟢 Beginner
+<!--
+Keep heading levels continuous:
+- Without categories, steps use level 3 headings, as below.
+- With a level 3 category, its steps use level 4 headings.
+Never place a level 4 step directly below this level 2 section.
+-->
 
-#### 1) <emoji> <First step title>
+### 1) <emoji> First step title
 
 <One benefit-focused line of what and why, in prose.>
 
 1. <where it is, then install it from its URL>
 2. <how to invoke it — its real command or slash>
 
-```bash
-$ <command the reader runs>
-<the useful output it prints, trimmed to what matters>
-```
-
-### 🟡 Intermediate
-
-#### 2) <emoji> <Next step title>
-
-<Benefit-focused what and why, in prose.>
-
-1. <action>
-2. <action>
-
 ```<lang>
 <a config or snippet the reader can copy>
 ```
 
-### 🔴 Expert
-
-#### 3) <emoji> <Last step title — until the goal is reached>
-
-<Benefit-focused what and why, in prose.>
-
-1. <action>
-
-![<what this screenshot or video shows>](<path-or-url>)
-
-## Verify
+## Verify <!-- (optional) -->
 
 - <Optional. An observable check that proves it worked: a command, a UI state, a file that now exists.>
@@ -1,27 +1,35 @@
 # Install AIDDy in Codex
 
-Install AIDDy, the Agent Y mascot, as a local Codex pet.
+Install AIDDy, the Agent Y mascot, as a local custom pet in the ChatGPT desktop app.
+
+- [Install AIDDy in Codex](#install-aiddy-in-codex)
+  - [Why](#why)
+  - [Steps to install and wake AIDDy](#steps-to-install-and-wake-aiddy)
+    - [1) 🔗 Open the AIDDy installer](#1--open-the-aiddy-installer)
+    - [2) 📦 Confirm the installation](#2--confirm-the-installation)
+    - [3) 🐾 Select AIDDy](#3--select-aiddy)
+    - [4) ▶️ Wake AIDDy](#4-️-wake-aiddy)
+  - [Verify](#verify)
 
 ## Why
 
-**AIDDy** reflects Codex task activity with the AI-Driven Development mascot.
+**AIDDy** reflects ChatGPT task activity with the AI-Driven Development mascot.
 
 **Sprite version 2** ensures Codex reads the extended 11-row animation atlas correctly.
 
 ## Steps to install and wake AIDDy
 
-#### 1) 🔗 Open the AIDDy installer
+### 1) 🔗 Open the AIDDy installer
 
-The versioned deep link opens the Codex pet installer with the canonical AIDDy atlas.
+The immutable deep link opens the pet installer with the canonical AIDDy atlas.
 
-1. Use a machine with the Codex desktop app and internet access.
-2. Click [Install AIDDy](codex://pets/install?name=AIDDy&imageUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fai-driven-dev%2Fframework%2Fmain%2Fassets%2Fpets%2Faiddy-spritesheet.webp&description=Agent%20Y%20for%20AI-Driven%20Development&spriteVersionNumber=2).
+1. In the ChatGPT desktop app, click [Install AIDDy](codex://pets/install?name=AIDDy&imageUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fai-driven-dev%2Fframework%2F1a52770253628062e4e8cbcda1bd062452354c27%2Fassets%2Fpets%2Faiddy-spritesheet.webp&description=Agent%20Y%20for%20AI-Driven%20Development&spriteVersionNumber=2).
 
 ```text
-codex://pets/install?name=AIDDy&imageUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fai-driven-dev%2Fframework%2Fmain%2Fassets%2Fpets%2Faiddy-spritesheet.webp&description=Agent%20Y%20for%20AI-Driven%20Development&spriteVersionNumber=2
+codex://pets/install?name=AIDDy&imageUrl=https%3A%2F%2Fraw.githubusercontent.com%2Fai-driven-dev%2Fframework%2F1a52770253628062e4e8cbcda1bd062452354c27%2Fassets%2Fpets%2Faiddy-spritesheet.webp&description=Agent%20Y%20for%20AI-Driven%20Development&spriteVersionNumber=2
 ```
 
-#### 2) 📦 Confirm the installation
+### 2) 📦 Confirm the installation
 
 The confirmation screen lets you verify the pet before writing it to local Codex storage.
 
@@ -34,14 +42,21 @@ Description: Agent Y for AI-Driven Development
 Sprite version: 2
 ```
 
-#### 3) 🐾 Wake AIDDy
+### 3) 🐾 Select AIDDy
+
+Selecting the installed custom pet makes it active in the ChatGPT desktop app.
+
+1. Open **Settings > Pets**, select **Refresh** if needed, then choose **AIDDy**.
+
+```text
+Settings > Pets > AIDDy
+```
+
+### 4) ▶️ Wake AIDDy
 
-Selecting the custom pet makes it available as the animated task companion documented in [Codex pets](https://learn.chatgpt.com/docs/pets).
+The `/pet` command wakes the selected companion so it can report task activity.
 
-1. Open **Settings > Pets**.
-2. Refresh custom pets if AIDDy is not visible yet.
-3. Select **AIDDy**.
-4. Enter `/pet` in a task.
+1. Enter `/pet` in a task.
 
 ```text
 /pet
@@ -51,4 +66,5 @@ Selecting the custom pet makes it available as the animated task companion docum
 
 - AIDDy appears in **Settings > Pets** as a custom pet.
 - `/pet` shows AIDDy and its animation changes with task activity.
-- The link uses only the supported [pet install parameters](https://learn.chatgpt.com/docs/reference/app-commands#pets), including `spriteVersionNumber=2`.
+- The link uses only the supported [pet install parameters](https://learn.chatgpt.com/docs/reference/commands#pets), including `spriteVersionNumber=2`.
+- The pinned atlas has SHA-256 `a97872f637a6711da4a88cbbb56f9038b2fcb4ce870e021c9d2355a3421ad5a4`.
@@ -1,60 +1,155 @@
 # MCP installations
 
-Decide when to use an MCP server vs a CLI, and wire up the recommended ones.
+Choose between a CLI and MCP by capability, then install the integration through the configuration native to your AI client.
+
+- [MCP installations](#mcp-installations)
+  - [Why](#why)
+  - [Steps to install the right integration](#steps-to-install-the-right-integration)
+    - [1) 🔎 Choose by capability](#1--choose-by-capability)
+    - [2) ⌨️ Install the CLI route](#2-️-install-the-cli-route)
+    - [3) 🔌 Install the MCP route](#3--install-the-mcp-route)
+    - [4) 🔐 Restrict access](#4--restrict-access)
+    - [5) ✅ Verify the connection](#5--verify-the-connection)
+    - [6) 🧹 Remove or revoke access](#6--remove-or-revoke-access)
+  - [Verify](#verify)
 
 ## Why
 
-**MCP servers** load their full tool schema into every turn, which bloats the context window.
+**Capability fit** matters more than whether a CLI happens to exist.
 
-**CLI calls** cost a few tokens and return only what you ask for.
+**[Claude Code Tool Search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search)** defers full MCP tool schemas on supported models and providers; other clients and MCP capabilities may load differently.
 
-**Reach for MCP only when no CLI covers the service.**
+**Native configuration** uses the file, schema, scope, and installation flow documented by the selected client.
 
-**Audit what you install** before connecting any server.
+**Least privilege** limits the impact of write tools, broad OAuth access, and prompt injection.
 
-## Steps to choose and install the right integration
+## Steps to install the right integration
 
-#### 1) 🔎 Check for a CLI first
+### 1) 🔎 Choose by capability
 
-The CLI is usually cheaper because it does not inject a large tool schema into every turn.
+Choose the smallest interface that fully covers the workflow, authentication model, and data scope.
 
-1. Look for an official CLI before adding an MCP server.
-2. Install and authenticate the CLI when it covers the workflow.
-3. Keep MCP for services with no useful CLI alternative.
+1. Compare the exact operation you need against the table.
 
-| Service | Official MCP | CLI alternative | Recommended |
+| Need | Prefer a CLI | Prefer MCP |
+| --- | --- | --- |
+| Scriptable commands and raw API calls | The official CLI covers the operation and its output is manageable | The client needs typed discovery or structured results |
+| Live design or knowledge context | The CLI exposes the required operation and data | The server advertises the required tools, resources, or prompts |
+| Authentication | The CLI's login and credential storage fit the workflow | The server's authentication, requested scopes, and host credential storage fit the workflow |
+| Context cost | Output is requested only when the command runs | The client supports deferred loading such as [Claude Code Tool Search](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search) |
+
+The last column is a decision heuristic for this recipe, not a provider guarantee.
+
+| Service | CLI route | MCP route | Recipe heuristic |
 | --- | --- | --- | --- |
-| **GitHub** | [`api.githubcopilot.com/mcp/`](https://github.com/github/github-mcp-server) | [`gh`](https://cli.github.com/) | **CLI**: issues, PRs, releases, and API calls without the MCP schema cost |
-| **Atlassian** (Jira / Confluence) | [`mcp.atlassian.com/v1/mcp`](https://www.atlassian.com/platform/remote-mcp-server) | [`acli`](https://developer.atlassian.com/cloud/acli/guides/introduction/) for Jira | **CLI** for Jira, **MCP** for Confluence |
-| **Playwright** | [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) | [`npx playwright`](https://playwright.dev/docs/test-cli) | **CLI**: a real browser through `playwright open`, `codegen`, or `--headed` |
-| **Figma** | [`mcp.figma.com/mcp`](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | none for design data | **MCP** |
-| **Notion** | [`mcp.notion.com/mcp`](https://developers.notion.com/guides/mcp/get-started-with-mcp) | none official | **MCP** |
+| [GitHub](https://github.com/github/github-mcp-server) | [`gh`](https://cli.github.com/) | Remote toolsets, including read-only modes | CLI for routine API work; MCP for typed or remote-only capabilities |
+| [Atlassian](https://www.atlassian.com/platform/rovo-mcp) | [`acli`](https://developer.atlassian.com/cloud/acli/guides/introduction/) for Jira | The current Rovo MCP tool catalog; [OAuth 2.1 is recommended](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/configuring-oauth-2-1/), with API-token authentication only when an administrator enables it | Decide from the Atlassian product, operation, and permitted authentication |
+| [Playwright](https://github.com/microsoft/playwright-mcp) | [`@playwright/cli`](https://playwright.dev/agent-cli/installation) | `@playwright/mcp` | CLI for direct browser automation; MCP for live tool calls |
+| [Figma](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | The [`@figma/code-connect` CLI](https://developers.figma.com/docs/code-connect/cli-reference/) manages component mappings, not live design context or canvas operations | `https://mcp.figma.com/mcp` | CLI for Code Connect mappings; MCP for live design and canvas workflows |
+| [Notion](https://developers.notion.com/guides/mcp/get-started-with-mcp) | The official [`ntn` CLI](https://developers.notion.com/cli/get-started/overview) supports API, page, data-source, file, and Worker operations | `https://mcp.notion.com/mcp` | CLI for scripts and raw API work; MCP for agent workflows, with human confirmation |
+
+### 2) ⌨️ Install the CLI route
+
+The agent-oriented Playwright CLI is a direct browser alternative to Playwright MCP.
+
+1. Install `@playwright/cli` from the [official guide](https://playwright.dev/agent-cli/installation), then invoke its `playwright-cli` executable.
+
+```bash
+npm install -g @playwright/cli@latest
+playwright-cli open https://example.com --headed
+```
+
+Use `npx playwright test` for the test runner and `npx playwright codegen` for test generation; they are different command surfaces.
+
+### 3) 🔌 Install the MCP route
+
+Use a provider-supported client and distinguish the recommended plugin route from manual MCP configuration.
+
+1. Pick the [documented Figma route](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) for your client.
+
+| Client | Figma's recommended route | Manual alternative and scope |
+| --- | --- | --- |
+| Claude Code | `claude plugin install figma@claude-plugins-official` | `claude mcp add --transport http --scope project figma https://mcp.figma.com/mcp` writes project configuration to `.mcp.json` under `mcpServers` |
+| Codex | In the Codex app, open **Plugins**, select **+** next to Figma, then **Install Figma** | `codex mcp add figma --url https://mcp.figma.com/mcp` writes to [`~/.codex/config.toml`](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) under `mcp_servers`; trusted projects may instead use `.codex/config.toml` |
+| Cursor | Run `/add-plugin figma` | Manual project configuration uses `.cursor/mcp.json` under `mcpServers` |
+| GitHub Copilot in VS Code | Run **MCP: Open Workspace Folder MCP Configuration**, paste Figma's documented server object, then select **Start** | Workspace configuration uses `.vscode/mcp.json` under `servers` |
+
+```bash
+claude plugin install figma@claude-plugins-official
+```
 
-#### 2) 🔌 Add MCP only when it is the right integration
+[Figma accepts only clients in its MCP catalog](https://www.figma.com/mcp-catalog/); do not extrapolate these instructions to an unlisted host.
 
-An MCP config belongs in the assistant's MCP configuration file, and only for services where MCP is the best available interface.
+### 4) 🔐 Restrict access
 
-1. Read the provider docs and permission model.
-2. Add the server to `.mcp.json`.
-3. Restart the assistant so it picks up the new tools.
+Use the server's documented authentication, expose only required capabilities, and enforce confirmation for mutations.
+
+1. If the remote server uses OAuth, authorize it in the client and review the requested scopes; otherwise follow its documented authentication method.
+2. Prefer read-only endpoints, toolsets, or allowlists when the workflow only reads.
+3. Configure the host to require confirmation for mutating tools; if it cannot, disable write tools or use a provider-enforced read-only mode.
+
+[GitHub documents](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md#read-only-mode) this VS Code-format server-entry fragment; place it under `servers.github` in `.vscode/mcp.json`, or adapt the wrapper to the selected host:
 
 ```json
 {
-  "mcpServers": {
-    "figma": { "url": "https://mcp.figma.com/mcp" }
+  "type": "http",
+  "url": "https://api.githubcopilot.com/mcp/",
+  "headers": {
+    "X-MCP-Toolsets": "repos,issues",
+    "X-MCP-Readonly": "true"
   }
 }
 ```
 
-#### 3) ✅ Verify the integration
+[Notion MCP inherits the connected user's workspace access](https://developers.notion.com/guides/mcp/mcp-security-best-practices), so review every write and any data sent to another tool.
+
+### 5) ✅ Verify the connection
+
+Verify the configured server, authenticated identity, exposed tools, and one read-only operation before relying on it.
+
+1. Inspect the server through the client, then run a harmless read.
+
+```text
+Claude Code: /mcp
+Codex:       codex mcp list
+Cursor:      Settings > Cursor Settings > Tools & MCP
+VS Code:     MCP: List Servers
+```
+
+Figma's documented successful Claude Code flow ends with:
 
-Verification keeps a bad install out of later sessions.
+```text
+Authentication successful. Connected to figma
+```
+
+Use Figma's read-only [`whoami`](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/#whoami-remote-only) tool to confirm the authenticated email, plans, and seat type.
+
+### 6) 🧹 Remove or revoke access
+
+Clear stored authentication, remove local configuration, then revoke the provider grant when one exists.
 
-1. For MCP, confirm the tools appear in the assistant.
-2. For a CLI, run a read-only identity command.
+1. Clear authentication before removing the server entry.
+2. Remove the server or plugin from the client.
+3. For Figma, open [**Settings > Security > Connected apps**](https://help.figma.com/hc/en-us/articles/15021280611607-How-do-I-keep-my-account-secure) and select **Revoke access**.
+
+| Client | Clear authentication | Remove local configuration |
+| --- | --- | --- |
+| Claude Code | Run `/mcp`, select Figma, then **Clear authentication** | Plugin: `claude plugin uninstall figma@claude-plugins-official`; manual project server: `claude mcp remove --scope project figma` |
+| Codex | Manual server: `codex mcp logout figma` | Plugin: remove Figma in the Codex app's **Plugins** panel; manual server: `codex mcp remove figma` |
+| Cursor | Disconnect Figma under **Settings > Cursor Settings > Tools & MCP** | Remove the Figma plugin or its manual `.cursor/mcp.json` entry |
+| GitHub Copilot in VS Code | Select the server through **MCP: List Servers** | Uninstall the server or remove its `.vscode/mcp.json` entry |
 
 ```bash
-$ gh auth status
-github.com
-  ✓ Logged in to github.com account octocat
+codex mcp logout figma
+codex mcp remove figma
 ```
+
+Removing configuration alone does not prove that the OAuth grant was revoked.
+
+## Verify
+
+- The server appears in the chosen client's server list with the expected transport and scope.
+- Authentication uses the intended account and workspace.
+- Only the required tools are enabled; mutating calls require confirmation or are disabled.
+- Figma `whoami` returns the intended identity.
+- Authentication clearing, local removal, and provider revocation are separate and documented.