feat(context): simplify service setup and connection checks

README.md

@@ -236,7 +236,7 @@ Start with a functional need or User Story, then track it as an issue or ticket
 before planning. Shipping follows the project's own delivery process. Capture a
 learning only when it is durable enough to improve the next feature.
 
-> 🍳 **More flows** → bundled recipes: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), and [installing AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md).
+> 🍳 **More flows** → bundled recipes: [Connect your services](plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), and [installing AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md).
 
 ## 🧩 Plugins
 
@@ -338,7 +338,7 @@ Full catalog → [`CATALOG.md`](docs/CATALOG.md).
 
 | | |
 | --- | --- |
-| 🍳 **Recipes** | Bundled how-to sheets: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), [install AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). Project recipes created by cook live in `aidd_docs/recipes/`. |
+| 🍳 **Recipes** | Bundled how-to sheets: [Connect your services](plugins/aidd-context/skills/12-cook/assets/recipes/connect-services.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), [install AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). Project recipes created by cook live in `aidd_docs/recipes/`. |
 | 🏛️ **[Architecture](docs/ARCHITECTURE.md)** | How the framework composes: plugins, skills, hooks, agents. |
 | 🧩 **[Create a plugin](docs/CREATE_PLUGIN.md)** | Build and publish your own. |
 | 🛒 **[Marketplace](docs/MARKETPLACE.md)** | Install scopes and versioning. |

aidd_docs/tasks/2026_10/2026_10_14_connect-services/challenge.md

@@ -0,0 +1,21 @@
+**Verdict:** READY
+**Scope:** Final connect-services recipe against the agreed concise service-setup guide.
+**Evidence limits:** Static documentation review; provider authentication and reads were not exercised. Sources checked 2026-10-14.
+
+## Verified
+
+- **Choice:** Four options compare use cases, advantages and limits; category tables retain CLI and MCP/native alternatives.
+- **Accuracy:** Context savings are conditional, matching [Playwright](https://playwright.dev/agent-cli/introduction#playwright-cli-vs-mcp) and [Claude Code's deferred tools](https://code.claude.com/docs/en/mcp#scale-with-mcp-tool-search). No universal speed or freshness claim remains.
+- **Setup:** Commands are labeled examples. The Figma command matches its [official setup guide](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/). Reusable API access points to Generate Skill. Its cross-skill link uses the source URL so installation does not break it.
+- **Verification:** Existing action maps relevant memory, performs target-specific reads and fills the category report without changing services.
+- **Checks:** Architecture rules pass; local Markdown links have no broken target; all three bundled recipes validate; diff whitespace check passes.
+
+## Blockers
+
+None.
+
+## Suggestions
+
+| Finding | Evidence | Minimal improvement |
+| --- | --- | --- |
+| API and SDK are different layers, though both are useful choices for this guide | [Octokit wraps GitHub APIs](https://github.com/octokit/octokit.js), checked 2026-10-14 | Optionally say “An SDK can wrap an API”; current use-case distinction is sufficient |

aidd_docs/tasks/2026_10/2026_10_14_connect-services/review.md

@@ -0,0 +1,49 @@
+# Review: Connect services
+
+- **Verdict**: approve
+- **Diff**: `origin/next...HEAD` plus tracked working edits to the recipe, verification action and report
+- **Axes run**: code, functional, relevancy
+- **Date**: 2026-10-14
+- **Findings**: 0 critical, 0 warning, 0 minor; formal findings limited to concrete P0/P1 risks
+
+## Phases
+
+### Phase 1: Recipe and setup
+
+- [x] Rename recipe and update its references: `README.md:239`, `token-optimization.md:452`, new `connect-services.md` replaces `mcp-installation.md`.
+- [x] Eight actual H4 category headings with emojis: `connect-services.md:49–113`.
+- [x] Service tables expose linked CLI, MCP/native and API/SDK alternatives; unsupported Google CLI labeled: `connect-services.md:53–122`.
+- [x] Explain memory mapping and link category memory templates: `connect-services.md:5`, `connect-services.md:47–115`.
+- [x] Three actionable steps; installation checks existing access, follows documentation, then authenticates; code examples belong to bullets: `connect-services.md:43`, `connect-services.md:125–165`.
+- [x] Bold introductory labels use a colon; ordinary bullets avoid unnecessary labels: `connect-services.md:131`, `connect-services.md:138`, `connect-services.md:147`.
+
+### Phase 2: Verification
+
+- [x] Public `verify` entry routes to `verify-connection`: `02-project-memory/SKILL.md:4`, `02-project-memory/SKILL.md:14–15`, `02-project-memory/SKILL.md:29`.
+- [x] Resolve the local recipe and read it by relative path; relevant memory is not a fixed filename list: `05-verify-connection.md:7`, `05-verify-connection.md:15–17`.
+- [x] Simple map, read and report process; rules replace a terminal Test section; unavailable context never means not needed: `05-verify-connection.md:15–26`.
+- [x] Read-only operation excludes writes, installs, login, memory changes and secret output; successful reads must match account and target: `05-verify-connection.md:25–26`.
+- [x] One category per four-column report; aggregate status preserves failed or unverified required access: `connection-report.md:4–24`.
+
+### Phase 3: Validator support
+
+- [x] CLI validation permits H4 subsections only below a direct numbered H3 step; malformed numbered headings still fail; unit cases cover valid subsections, orphans, changed parents and malformed headings: `recipe-validation.ts:397–439`, `recipe-validation.unit.test.ts:120–155`.
+
+## Findings
+
+None.
+
+## Verification
+
+| Metric | Value |
+| --- | --- |
+| Verified | 100% (12/12) static acceptance criteria reviewed |
+| Files checked | All 10 changed PR files: README, recipe validator, validator unit tests, context CATALOG, project-memory router, verification action, connection report, new connect-services recipe, deleted mcp-installation recipe, token-optimization recipe; three current tracked doc edits included |
+| Static check | `git diff --check origin/next` exited 0; scoped README/plugins/CLI search found no old `mcp-installation` reference |
+| Unchecked | Provider execution and runtime test results: not-applicable to this read-only static review; provider documentation contents and link availability not independently rechecked |
+| Unplanned | None; validator relaxation directly supports requested H4 category structure |
+| Completion score | 100: every supplied criterion examined |
+| Quality score | 92: criteria statically fulfilled; small duplication and local catalogue resolution indirection remain; runtime/provider behavior is not established by this review |
+| Non-blocking simplification | `connect-services.md:9–39`: graph shows a decision sequence, table shows tradeoffs; their functions differ, but graph repeats CLI preference and API fallback. Retaining just the comparison table and a short selection sentence would reduce page length without losing useful choice information |
+| Non-blocking clarity | `05-verify-connection.md:15`: local recipe resolution has an existing authoritative location policy at `../../12-cook/references/recipe-locations.md`; linking that policy would remove ambiguity without duplicating it |
+| Non-blocking router consistency | `02-project-memory/SKILL.md:36`: “report of what changed” predates the read-only verify entry; scoping it to setup/refresh/rewire would align it with verify's observed-results report |

cli/src/contexts/framework/domain/recipes/recipe-validation.ts

@@ -394,8 +394,10 @@ function checkSteps(
   );
   const steps: RecipeStep[] = [];
   const categories: Heading[] = [];
+  let directStep: RecipeStep | undefined;
 
   for (const heading of scopedHeadings) {
+    if (heading.depth === 3) directStep = undefined;
     const source = `${"#".repeat(heading.depth)} ${heading.text}`;
     const match = source.match(STEP_PATTERN);
     if (match) {
@@ -409,7 +411,9 @@ function checkSteps(
           "Add one meaningful emoji between the step number and title."
         );
       }
-      steps.push({ ...heading, number: Number.parseInt(match[2], 10), icon, title: match[4] });
+      const step = { ...heading, number: Number.parseInt(match[2], 10), icon, title: match[4] };
+      steps.push(step);
+      if (heading.depth === 3) directStep = step;
       continue;
     }
 
@@ -423,13 +427,13 @@ function checkSteps(
       );
     } else if (heading.depth === 3) {
       categories.push(heading);
-    } else {
+    } else if (!directStep) {
       addFinding(
         findings,
         file,
         heading.line,
         "category-depth",
-        "Use level 3 for a category and level 4 only for its numbered steps."
+        "Use level 4 for numbered category steps or subsections of a direct numbered step."
       );
     }
   }

cli/tests/contexts/framework/domain/recipes/recipe-validation.unit.test.ts

@@ -104,7 +104,7 @@ test("categories require level-four steps and cannot parent earlier steps", () =
     recipe(command, "### Beginner\n\n#### Unnumbered step"),
     "category-depth",
     9,
-    "Use level 3 for a category and level 4 only for its numbered steps."
+    "Use level 4 for numbered category steps or subsections of a direct numbered step."
   );
 });
 
@@ -117,6 +117,41 @@ test("direct steps stay at level three", () => {
   );
 });
 
+test("direct numbered steps allow unnumbered level-four subsections", () => {
+  const content = recipe(
+    `#### Version control\n\n${command}\n\n#### Database\n\n${command}\n\n### 2) 🔌 Connect\n\n#### Authentication\n\n${command}`
+  );
+  assert.deepEqual(inspectRecipe(file, content).findings, []);
+});
+
+test("unnumbered level-four subsections require a direct numbered parent", () => {
+  for (const heading of [
+    "#### Orphan subsection",
+    "### 1. ✅ Check readiness\n\n#### Subsection",
+    "### 1) ✅ Check readiness\n\n### Beginner\n\n#### Subsection",
+    "### Beginner\n\n#### 1) ✅ Check readiness\n\n#### Subsection",
+  ]) {
+    assert.equal(
+      inspectRecipe(file, recipe(command, heading)).findings.some(
+        (item) => item.rule === "category-depth"
+      ),
+      true
+    );
+  }
+});
+
+test.each(["#### 2. 🔌 Connect", "#### 2 🔌 Connect"])(
+  "subsections do not hide malformed numbered step heading %s",
+  (heading) => {
+    finding(
+      recipe(`${heading}\n\n${command}`),
+      "step-heading",
+      9,
+      "Use `### N) <emoji> Title`, or `#### N) <emoji> Title` below a category."
+    );
+  }
+);
+
 test("step numbering continues across categories instead of restarting", () => {
   const content = recipe(
     `${command}\n\n### Advanced\n\n#### 1) 🔬 Inspect output\n\n${command}`,

plugins/aidd-context/CATALOG.md

@@ -75,6 +75,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [02-write.md](skills/02-project-memory/actions/02-write.md) | - |
 | `actions` | [03-check.md](skills/02-project-memory/actions/03-check.md) | - |
 | `actions` | [04-sync.md](skills/02-project-memory/actions/04-sync.md) | - |
+| `actions` | [05-verify-connection.md](skills/02-project-memory/actions/05-verify-connection.md) | - |
+| `assets` | [connection-report.md](skills/02-project-memory/assets/connection-report.md) | - |
 | `assets` | [report.md](skills/02-project-memory/assets/report.md) | - |
 | `assets` | [scan-summary.md](skills/02-project-memory/assets/scan-summary.md) | - |
 | `references` | [capability-signals.md](skills/02-project-memory/references/capability-signals.md) | - |
@@ -85,7 +87,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `references` | [review-protocol.md](skills/02-project-memory/references/review-protocol.md) | - |
 | `references` | [structure.md](skills/02-project-memory/references/structure.md) | - |
 | `references` | [tools.md](skills/02-project-memory/references/tools.md) | - |
-| `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Build the project's memory of its architecture, conventions, and decisions, and wire it into your AI tools. Use when the user wants to set up or refresh project memory, or rewire it into a tool. Not for editing one existing memory file.` |
+| `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Build project memory and wire it into AI tools. Use when the user wants to set up or refresh memory, rewire it, or verify the assistant's service connections. Not for editing one existing memory file.` |
 
 #### `skills/03-context-generate`
 

plugins/aidd-context/skills/02-project-memory/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: 02-project-memory
-description: Build the project's memory of its architecture, conventions, and decisions, and wire it into your AI tools. Use when the user wants to set up or refresh project memory, or rewire it into a tool. Not for editing one existing memory file.
-argument-hint: setup | refresh | rewire
+description: Build project memory and wire it into AI tools. Use when the user wants to set up or refresh memory, rewire it, or verify the assistant's service connections. Not for editing one existing memory file.
+argument-hint: setup | refresh | rewire | verify
 ---
 
 # Project Memory
@@ -11,6 +11,8 @@ flowchart LR
   new([no argument, or setup]) --> scan --> write --> sync --> wired([memory wired])
   update([refresh]) --> scan --> check --> write
   rewire([rewire]) --> sync
+  verify([verify]) --> verify-connection
+  verify-connection --> reported([connection report])
   scan -.-> empty([nothing to remember])
 ```
 
@@ -24,10 +26,11 @@ Run the flow above, reading only the next action file.
 | write  | write the memory                |
 | check  | show what drifted, change nothing |
 | sync   | pick the tools, wire it in      |
+| verify-connection | verify the assistant's service access |
 
 ## Transversal rules
 
-- If a referenced file cannot be read, stop and say so. Never invent its content.
+- Never invent unreadable content; setup, refresh and rewire stop when a referenced file cannot be read.
 - Ask before anything ambiguous. Never default silently.
 - A bank that already exists changes only through what the user approved, file by file and line by line.
 - End with a short report of what changed.

plugins/aidd-context/skills/02-project-memory/actions/05-verify-connection.md

@@ -0,0 +1,26 @@
+# 05 - Verify Connection
+
+Check project access and fill the report.
+
+## Input
+
+The project's bank in `aidd_docs/memory/` and the local `connect-services.md` recipe.
+
+## Output
+
+A printed report using [connection-report.md](../assets/connection-report.md).
+
+## Process
+
+1. **Map**: Resolve `connect-services.md` from the local recipe catalogue, then read it by its relative path and read the relevant project memory to identify required services, accounts and targets.
+   - Include any other relevant memory files or services.
+   - Mark missing context as unverified, never as not needed.
+2. **Check**: Inspect available CLI, MCP, native or API access and perform one read against each required account and target.
+   - Continue checking the other services when one fails.
+3. **Report**: Fill `connection-report.md` from observed results, with one row per category.
+
+## Rules
+
+- Check the assistant access the project requires; the catalogue is not an installation checklist.
+- No writes, installs, login flows, configuration or memory changes, or secret output.
+- A configured tool alone never proves access; report success only after a read matches the intended account and target.

plugins/aidd-context/skills/02-project-memory/assets/connection-report.md

@@ -0,0 +1,24 @@
+# Connection Report
+
+<!--
+- Keep every category and group its services.
+- Name each tool, account and target.
+- Keep results short; name one corrective action for each problem.
+- Use the worst required result: failed, not configured, unverified.
+- Pass only when every required read succeeds.
+- Mark not needed only when no access is required.
+- Remove this comment from the report.
+-->
+
+| Category | Tool / target | Status | Evidence / next step |
+| --- | --- | --- | --- |
+| Version control | | | |
+| Ticketing | | | |
+| Documentation and workspace | | | |
+| Browser | | | |
+| Design | | | |
+| Monitoring | | | |
+| Deployment | | | |
+| Database | | | |
+
+✅ All required reads passed · ❌ Read failed · 🔌 Not configured · ⚠️ Unverified · ⏭️ Not needed