From caf360a6ae422ea4899518370743e10e4b11ff7b Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 9 Jun 2026 16:17:51 -0400
Subject: [PATCH 01/17] feat(agents): add `agents` content type, built and
 served alongside skills

New content type for orchestrator agent prompts (the WHAT), parallel to skills. Source under transformation-config/agents/, built to dist/agents/ as raw markdown plus agent-menu.json, served by the dev server at /agents/<type>.md and /agent-menu.json.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 scripts/build.js               | 10 +++++
 scripts/dev-server.js          | 47 +++++++++++++++++++++--
 scripts/lib/agent-generator.js | 68 ++++++++++++++++++++++++++++++++++
 3 files changed, 121 insertions(+), 4 deletions(-)
 create mode 100644 scripts/lib/agent-generator.js

diff --git a/scripts/build.js b/scripts/build.js
index deaf6da0..13411917 100755
--- a/scripts/build.js
+++ b/scripts/build.js
@@ -12,6 +12,7 @@
 import fs from 'fs';
 import path from 'path';
 import { generateAllSkills, fetchDoc } from './lib/skill-generator.js';
+import { buildAgents } from './lib/agent-generator.js';
 import { generateMarketplace } from './lib/marketplace-generator.js';
 import {
     loadDocsConfig,
@@ -105,6 +106,15 @@ async function main() {
         const skillMenu = JSON.parse(fs.readFileSync(path.join(skillsDir, 'skill-menu.json'), 'utf8'));
         console.log(`  ✓ skill-menu.json (${Object.keys(skillMenu.categories).length} categories, ${skills.length} skills)`);
 
+        console.log('\nBuilding agent prompts...');
+        const agentsResult = buildAgents({
+            configDir,
+            distDir,
+            baseUrl: process.env.AGENTS_BASE_URL,
+            version: BUILD_VERSION,
+        });
+        console.log(`  ✓ ${agentsResult.count} agent prompt(s) → dist/agents/ + agent-menu.json`);
+
         const releaseAssetDocs = docEntries.filter(d => d.release_asset);
         if (releaseAssetDocs.length > 0) {
             console.log('\nWriting release-asset docs...');
diff --git a/scripts/dev-server.js b/scripts/dev-server.js
index 8c1754cb..c9ae6ca6 100644
--- a/scripts/dev-server.js
+++ b/scripts/dev-server.js
@@ -30,6 +30,7 @@ import { spawn } from 'child_process';
 import chokidar from 'chokidar';
 
 import { loadAndExpandSkills } from './lib/skill-generator.js';
+import { buildAgents } from './lib/agent-generator.js';
 import {
     partialRebuild,
     loadDocContentsFromManifest,
@@ -51,13 +52,18 @@ const distDir = path.join(repoRoot, 'dist');
 const skillsDir = path.join(distDir, 'skills');
 const promptsDir = path.join(repoRoot, 'llm-prompts');
 const skillsSourceDir = path.join(configDir, 'skills');
+const agentsSourceDir = path.join(configDir, 'agents');
+const agentsDir = path.join(distDir, 'agents');
 const basicsDir = path.join(repoRoot, 'basics');
 
 const localSkillsUrl = `http://localhost:${PORT}/skills`;
+const localAgentsUrl = `http://localhost:${PORT}/agents`;
 
-// `generateManifest` reads SKILLS_BASE_URL from process.env. Partial rebuilds
-// run in this process, so set it here too — the subprocess inherits it.
+// `generateManifest` reads SKILLS_BASE_URL from process.env, and the agent build
+// reads AGENTS_BASE_URL. Partial rebuilds run in this process, so set both here —
+// the build subprocess inherits them.
 process.env.SKILLS_BASE_URL = localSkillsUrl;
+process.env.AGENTS_BASE_URL = localAgentsUrl;
 
 // --- state ---
 
@@ -186,6 +192,25 @@ async function drainQueue() {
 // --- watcher ---
 
 function handleEvent(event, absPath) {
+    // Agent prompts are decoupled from the skill incremental machinery. A change
+    // under transformation-config/agents/ just re-copies them wholesale — cheap.
+    if (absPath.startsWith(agentsSourceDir)) {
+        try {
+            const { count } = buildAgents({
+                configDir,
+                distDir,
+                baseUrl: localAgentsUrl,
+                version: BUILD_VERSION,
+            });
+            console.log(
+                `📝 ${event}: ${path.relative(repoRoot, absPath)} → rebuilt ${count} agent prompt(s)`,
+            );
+        } catch (err) {
+            console.error(`❌ Agent rebuild failed: ${err.message}`);
+        }
+        return;
+    }
+
     const decision = routeChange({
         event,
         absPath,
@@ -211,7 +236,7 @@ function handleEvent(event, absPath) {
 
 function setupWatcher() {
     const sep = path.sep;
-    const watcher = chokidar.watch([skillsSourceDir, basicsDir], {
+    const watcher = chokidar.watch([skillsSourceDir, agentsSourceDir, basicsDir], {
         ignoreInitial: true,
         persistent: true,
         followSymlinks: false,
@@ -223,6 +248,7 @@ function setupWatcher() {
 
     console.log('\n👀 Watching:');
     console.log(`   📁 ${path.relative(repoRoot, skillsSourceDir)}`);
+    console.log(`   📁 ${path.relative(repoRoot, agentsSourceDir)}`);
     console.log(`   📁 ${path.relative(repoRoot, basicsDir)}`);
 
     return watcher;
@@ -270,6 +296,17 @@ function createServer() {
             return;
         }
 
+        const agentMatch = req.url?.match(/^\/agents\/([\w-]+\.md)$/);
+        if (agentMatch) {
+            serveFile(res, path.join(agentsDir, agentMatch[1]), 'text/markdown; charset=utf-8');
+            return;
+        }
+
+        if (req.url === '/agent-menu.json') {
+            serveFile(res, path.join(agentsDir, 'agent-menu.json'), 'application/json');
+            return;
+        }
+
         if (req.url === '/skills-mcp-resources.zip' || req.url === '/') {
             serveFile(
                 res,
@@ -281,7 +318,7 @@ function createServer() {
         }
 
         res.writeHead(404, { 'Content-Type': 'text/plain', ...NO_CACHE_HEADERS });
-        res.end('Not found. Available endpoints:\n  /skill-menu.json\n  /skills-mcp-resources.zip\n  /skills/{id}.zip');
+        res.end('Not found. Available endpoints:\n  /skill-menu.json\n  /skills-mcp-resources.zip\n  /skills/{id}.zip\n  /agent-menu.json\n  /agents/{type}.md');
     });
 
     server.listen(PORT, () => {
@@ -289,6 +326,8 @@ function createServer() {
         console.log(`\n📍 Skills bundle:   http://localhost:${PORT}/skills-mcp-resources.zip`);
         console.log(`📍 Individual skill: http://localhost:${PORT}/skills/{id}.zip`);
         console.log(`📋 Skills menu:      http://localhost:${PORT}/skill-menu.json`);
+        console.log(`🤖 Agent prompt:     http://localhost:${PORT}/agents/{type}.md`);
+        console.log(`📋 Agents menu:      http://localhost:${PORT}/agent-menu.json`);
     });
 
     return server;
diff --git a/scripts/lib/agent-generator.js b/scripts/lib/agent-generator.js
new file mode 100644
index 00000000..f84b912c
--- /dev/null
+++ b/scripts/lib/agent-generator.js
@@ -0,0 +1,68 @@
+/**
+ * Agent-prompt content type — the WHAT of the orchestrator runner.
+ *
+ * An agent prompt is one markdown file per task type. Its frontmatter carries
+ * the artifacts the executor configures the run with (model, skills, tools,
+ * dependsOn); its body is the instruction the task agent reads. Unlike skills,
+ * agent prompts are self-contained single files with no references/, so they are
+ * served as raw markdown rather than zipped. The wizard parses the frontmatter
+ * when it loads a task by type.
+ *
+ *   Source:  transformation-config/agents/<type>.md
+ *   Output:  dist/agents/<type>.md  +  dist/agents/agent-menu.json
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const DEFAULT_AGENTS_BASE_URL =
+    'https://github.com/PostHog/context-mill/releases/latest/download/agents';
+
+/** The agent ids available in source, derived from the `<type>.md` filenames. */
+export function loadAgentIds(agentsSourceDir) {
+    if (!fs.existsSync(agentsSourceDir)) return [];
+    return fs
+        .readdirSync(agentsSourceDir)
+        .filter(f => f.endsWith('.md'))
+        .map(f => f.slice(0, -'.md'.length))
+        .sort();
+}
+
+/**
+ * Copy every agent-prompt markdown file into dist/agents/ and write the menu the
+ * wizard fetches to discover available types. The menu carries a full
+ * downloadUrl per agent so the dev-server and the release host can differ
+ * without the wizard composing URLs. Returns { count, agentsDistDir }.
+ */
+export function buildAgents({ configDir, distDir, baseUrl, version = 'dev' }) {
+    const agentsSourceDir = path.join(configDir, 'agents');
+    const agentsDistDir = path.join(distDir, 'agents');
+    const resolvedBase = (baseUrl || DEFAULT_AGENTS_BASE_URL).replace(/\/+$/, '');
+
+    fs.mkdirSync(agentsDistDir, { recursive: true });
+
+    const ids = loadAgentIds(agentsSourceDir);
+    const agents = [];
+    for (const id of ids) {
+        fs.copyFileSync(
+            path.join(agentsSourceDir, `${id}.md`),
+            path.join(agentsDistDir, `${id}.md`),
+        );
+        agents.push({ id, downloadUrl: `${resolvedBase}/${id}.md` });
+    }
+
+    const menu = { version: '1.0', buildVersion: version, agents };
+    fs.writeFileSync(
+        path.join(agentsDistDir, 'agent-menu.json'),
+        JSON.stringify(menu, null, 2) + '\n',
+    );
+
+    // Reconcile: drop dist files whose source markdown was removed.
+    const keep = new Set(ids.map(id => `${id}.md`));
+    keep.add('agent-menu.json');
+    for (const file of fs.readdirSync(agentsDistDir)) {
+        if (!keep.has(file)) fs.rmSync(path.join(agentsDistDir, file));
+    }
+
+    return { count: agents.length, agentsDistDir };
+}

From e70da8b14fa825a95fd5a31fd2f43137c9101748 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 9 Jun 2026 16:18:02 -0400
Subject: [PATCH 02/17] feat(orchestrator): agent prompts + mini-skills for the
 integration flow

Agent prompts (agents/) and paired single-purpose mini-skills (skills/) for the task-queue orchestrator: install, init, identify, error-tracking, plan-capture, capture, build, dashboard, report, plus the integrate-posthog seed. Mini-skills are grounded in PostHog docs via docs_urls + {references}.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 transformation-config/agents/build.md         | 23 +++++++++++++++
 transformation-config/agents/capture.md       | 19 +++++++++++++
 transformation-config/agents/dashboard.md     | 19 +++++++++++++
 .../agents/error-tracking.md                  | 20 +++++++++++++
 transformation-config/agents/example.md       | 22 +++++++++++++++
 transformation-config/agents/identify.md      | 19 +++++++++++++
 transformation-config/agents/init.md          | 20 +++++++++++++
 transformation-config/agents/install.md       | 20 +++++++++++++
 .../agents/integrate-posthog.md               | 28 +++++++++++++++++++
 transformation-config/agents/plan-capture.md  | 21 ++++++++++++++
 transformation-config/agents/report.md        | 21 ++++++++++++++
 .../skills/build/config.yaml                  |  9 ++++++
 .../skills/build/description.md               | 24 ++++++++++++++++
 .../skills/capture/config.yaml                | 11 ++++++++
 .../skills/capture/description.md             | 15 ++++++++++
 .../skills/dashboard/config.yaml              |  9 ++++++
 .../skills/dashboard/description.md           | 11 ++++++++
 .../skills/error-tracking-step/config.yaml    | 11 ++++++++
 .../skills/error-tracking-step/description.md | 16 +++++++++++
 .../skills/identify/config.yaml               | 10 +++++++
 .../skills/identify/description.md            | 16 +++++++++++
 transformation-config/skills/init/config.yaml | 11 ++++++++
 .../skills/init/description.md                | 28 +++++++++++++++++++
 .../skills/install/config.yaml                | 11 ++++++++
 .../skills/install/description.md             | 19 +++++++++++++
 .../skills/plan-capture/config.yaml           | 10 +++++++
 .../skills/plan-capture/description.md        | 17 +++++++++++
 .../skills/report/config.yaml                 |  9 ++++++
 .../skills/report/description.md              | 19 +++++++++++++
 29 files changed, 488 insertions(+)
 create mode 100644 transformation-config/agents/build.md
 create mode 100644 transformation-config/agents/capture.md
 create mode 100644 transformation-config/agents/dashboard.md
 create mode 100644 transformation-config/agents/error-tracking.md
 create mode 100644 transformation-config/agents/example.md
 create mode 100644 transformation-config/agents/identify.md
 create mode 100644 transformation-config/agents/init.md
 create mode 100644 transformation-config/agents/install.md
 create mode 100644 transformation-config/agents/integrate-posthog.md
 create mode 100644 transformation-config/agents/plan-capture.md
 create mode 100644 transformation-config/agents/report.md
 create mode 100644 transformation-config/skills/build/config.yaml
 create mode 100644 transformation-config/skills/build/description.md
 create mode 100644 transformation-config/skills/capture/config.yaml
 create mode 100644 transformation-config/skills/capture/description.md
 create mode 100644 transformation-config/skills/dashboard/config.yaml
 create mode 100644 transformation-config/skills/dashboard/description.md
 create mode 100644 transformation-config/skills/error-tracking-step/config.yaml
 create mode 100644 transformation-config/skills/error-tracking-step/description.md
 create mode 100644 transformation-config/skills/identify/config.yaml
 create mode 100644 transformation-config/skills/identify/description.md
 create mode 100644 transformation-config/skills/init/config.yaml
 create mode 100644 transformation-config/skills/init/description.md
 create mode 100644 transformation-config/skills/install/config.yaml
 create mode 100644 transformation-config/skills/install/description.md
 create mode 100644 transformation-config/skills/plan-capture/config.yaml
 create mode 100644 transformation-config/skills/plan-capture/description.md
 create mode 100644 transformation-config/skills/report/config.yaml
 create mode 100644 transformation-config/skills/report/description.md

diff --git a/transformation-config/agents/build.md b/transformation-config/agents/build.md
new file mode 100644
index 00000000..fb028d68
--- /dev/null
+++ b/transformation-config/agents/build.md
@@ -0,0 +1,23 @@
+---
+type: build
+label: Install dependencies and build
+model: claude-sonnet-4-6
+skills: [build]
+allowedTools: [Read, Edit, Glob, Grep, Bash]
+disallowedTools: [enqueue_task]
+dependsOn: [install, init, identify, error-tracking, capture]
+---
+
+## Goal
+
+Bring the integration together: install the dependencies the earlier steps
+declared, then verify the project builds. Until now the steps only edited code and
+the manifest — this is where it actually installs and compiles.
+
+## How you know you succeeded
+
+The install completes and the build (or typecheck) passes. If you hit a conflict
+you cannot cleanly resolve — a dependency clash, a build error from the new code —
+fix what you safely can, then report it: put a one-line summary in your handoff's
+`conflict` field and the full detail in what you did. The user sees the one-liner
+in the outro and the detail in the report.
diff --git a/transformation-config/agents/capture.md b/transformation-config/agents/capture.md
new file mode 100644
index 00000000..b4317135
--- /dev/null
+++ b/transformation-config/agents/capture.md
@@ -0,0 +1,19 @@
+---
+type: capture
+label: Instrument the planned events
+model: claude-sonnet-4-6
+skills: [capture]
+allowedTools: [Read, Edit, Glob, Grep]
+disallowedTools: [enqueue_task]
+dependsOn: [plan-capture]
+---
+
+## Goal
+
+Instrument the events from the plan you were handed. Add a PostHog capture call at
+each one, on the real user action.
+
+## How you know you succeeded
+
+Each planned event has a capture call that fires on the user action, not on page
+load or render. If a planned event no longer fits the code, skip it and note why.
diff --git a/transformation-config/agents/dashboard.md b/transformation-config/agents/dashboard.md
new file mode 100644
index 00000000..3adb8b6d
--- /dev/null
+++ b/transformation-config/agents/dashboard.md
@@ -0,0 +1,19 @@
+---
+type: dashboard
+label: Create a starter dashboard
+model: claude-sonnet-4-6
+skills: [dashboard]
+allowedTools: [Read, Glob, Grep]
+disallowedTools: [Write, Edit, Bash, enqueue_task]
+dependsOn: [capture]
+---
+
+## Goal
+
+Create a starter PostHog dashboard with a few insights built on the events this
+integration instruments, using the PostHog MCP.
+
+## How you know you succeeded
+
+A dashboard exists with a handful of insights on the captured events, and you hand
+off its URL for the report to link.
diff --git a/transformation-config/agents/error-tracking.md b/transformation-config/agents/error-tracking.md
new file mode 100644
index 00000000..3d7ac2d6
--- /dev/null
+++ b/transformation-config/agents/error-tracking.md
@@ -0,0 +1,20 @@
+---
+type: error-tracking
+label: Add error tracking
+model: claude-sonnet-4-6
+skills: [error-tracking-step]
+allowedTools: [Read, Edit, Glob, Grep]
+disallowedTools: [enqueue_task]
+dependsOn: [install, init]
+---
+
+## Goal
+
+Add PostHog error tracking around the app's critical flows and boundaries, so
+failures that matter reach PostHog.
+
+## How you know you succeeded
+
+Exceptions in the important paths — the routes, actions, and boundaries where a
+failure hurts the user — are captured. If the app already reports errors
+elsewhere, add PostHog alongside it rather than replacing it.
diff --git a/transformation-config/agents/example.md b/transformation-config/agents/example.md
new file mode 100644
index 00000000..d028ee27
--- /dev/null
+++ b/transformation-config/agents/example.md
@@ -0,0 +1,22 @@
+---
+type: example
+model: claude-haiku-4-5-20251001
+skills: []
+allowedTools: [Read, Glob, Grep]
+disallowedTools: [enqueue_task]
+dependsOn: []
+---
+
+## Goal
+
+This is the canonical example of an agent prompt, the WHAT of an orchestrator
+task. The frontmatter carries the artifacts the executor configures the run
+with: the model, the mini-skills to load (the HOW), the tools the task may and
+may not use, and the tasks it depends on. The body is intent only — what to do
+and what done looks like. The client injects the basics (project context, how to
+report, how to surface progress), so a prompt never restates them.
+
+## How you know you succeeded
+
+Plain-text success criteria live here. State what done looks like, and what to do
+when the task cannot be completed.
diff --git a/transformation-config/agents/identify.md b/transformation-config/agents/identify.md
new file mode 100644
index 00000000..28ccad11
--- /dev/null
+++ b/transformation-config/agents/identify.md
@@ -0,0 +1,19 @@
+---
+type: identify
+label: Wire user identification
+model: claude-sonnet-4-6
+skills: [identify]
+allowedTools: [Read, Edit, Glob, Grep]
+disallowedTools: [enqueue_task]
+dependsOn: [install, init]
+---
+
+## Goal
+
+Wire user identification: call PostHog identify wherever the app establishes who
+the user is, typically at login and signup.
+
+## How you know you succeeded
+
+An identify call fires at the point the user becomes known, with a stable
+distinct id. If the app has no auth or user concept, say so and stop.
diff --git a/transformation-config/agents/init.md b/transformation-config/agents/init.md
new file mode 100644
index 00000000..b826089b
--- /dev/null
+++ b/transformation-config/agents/init.md
@@ -0,0 +1,20 @@
+---
+type: init
+label: Set up PostHog initialization
+model: claude-haiku-4-5-20251001
+skills: [init]
+allowedTools: [Read, Write, Edit, Glob, Grep]
+disallowedTools: [enqueue_task]
+dependsOn: []
+---
+
+## Goal
+
+Initialize PostHog: create the framework's init point so the SDK is configured
+once and available across the app, and set the PostHog environment variables
+through the wizard tools.
+
+## How you know you succeeded
+
+The init file exists and the PostHog env keys are present. Keys live in the env
+file, never hardcoded in source.
diff --git a/transformation-config/agents/install.md b/transformation-config/agents/install.md
new file mode 100644
index 00000000..1ca1636e
--- /dev/null
+++ b/transformation-config/agents/install.md
@@ -0,0 +1,20 @@
+---
+type: install
+label: Add the PostHog SDK to the manifest
+model: claude-haiku-4-5-20251001
+skills: [install]
+allowedTools: [Read, Edit, Glob, Grep]
+disallowedTools: [enqueue_task]
+dependsOn: []
+---
+
+## Goal
+
+Declare the PostHog SDK in the project's package manifest. Do not run the package
+manager and do not build — the build task installs and verifies everything at the
+end.
+
+## How you know you succeeded
+
+The SDK is listed in the manifest's dependencies at a sensible version. If it is
+already declared, leave it and say so.
diff --git a/transformation-config/agents/integrate-posthog.md b/transformation-config/agents/integrate-posthog.md
new file mode 100644
index 00000000..8564a81f
--- /dev/null
+++ b/transformation-config/agents/integrate-posthog.md
@@ -0,0 +1,28 @@
+---
+type: integrate-posthog
+model: claude-sonnet-4-6
+skills: []
+allowedTools: [Read, Glob, Grep]
+disallowedTools: [Write, Edit, Bash, complete_task]
+dependsOn: []
+---
+
+## Goal
+
+Plan a PostHog integration for this project and seed the task queue. Take a brief
+glance at the repo to confirm its shape — a quick look, not a deep analysis —
+then seed this graph:
+
+- `install` and `init`, independent of each other.
+- `identify`, `error-tracking`, and `plan-capture`, each after `install` and
+  `init`, independent of each other.
+- `capture`, after `plan-capture`.
+- `build`, after `install`, `init`, `identify`, `error-tracking`, and `capture` —
+  it installs the dependencies and verifies the project compiles.
+- `dashboard`, after `capture`.
+- `report`, after `build` and `dashboard` — it writes the setup report last.
+
+## How you know you succeeded
+
+The nine tasks are queued with that dependency shape, and the first is runnable.
+Keep them small and discrete so each finishes fast and shows visible progress.
diff --git a/transformation-config/agents/plan-capture.md b/transformation-config/agents/plan-capture.md
new file mode 100644
index 00000000..fc49c572
--- /dev/null
+++ b/transformation-config/agents/plan-capture.md
@@ -0,0 +1,21 @@
+---
+type: plan-capture
+label: Plan which events to capture
+model: claude-sonnet-4-6
+skills: [plan-capture]
+allowedTools: [Read, Glob, Grep]
+disallowedTools: [Write, Edit, Bash, enqueue_task]
+dependsOn: [install, init]
+---
+
+## Goal
+
+Decide which events are worth capturing in this app. Read the code to find the
+meaningful user actions — the things a product team would want to measure — and
+hand off that list. Do not edit code.
+
+## How you know you succeeded
+
+Your handoff is a short, concrete event plan: a handful of named events, each
+tied to a real user action and the file where it happens. Prefer a few
+high-signal events over an exhaustive list.
diff --git a/transformation-config/agents/report.md b/transformation-config/agents/report.md
new file mode 100644
index 00000000..fdac07d7
--- /dev/null
+++ b/transformation-config/agents/report.md
@@ -0,0 +1,21 @@
+---
+type: report
+label: Write the setup report
+model: claude-sonnet-4-6
+skills: [report]
+allowedTools: [Read, Write, Glob, Grep]
+disallowedTools: [enqueue_task]
+dependsOn: [build, dashboard]
+---
+
+## Goal
+
+Write the setup report summarizing what this integration did, drawing on the
+handoffs from the previous steps.
+
+## How you know you succeeded
+
+`posthog-setup-report.md` exists at the project root: what was installed and
+initialized, the events captured, whether identify was wired or skipped, error
+tracking added, the dashboard link, any build conflict in full, and the next
+steps for the user.
diff --git a/transformation-config/skills/build/config.yaml b/transformation-config/skills/build/config.yaml
new file mode 100644
index 00000000..82142d68
--- /dev/null
+++ b/transformation-config/skills/build/config.yaml
@@ -0,0 +1,9 @@
+type: docs-only
+template: description.md
+description: Install dependencies and verify the project builds
+tags: [orchestrator, build]
+variants:
+  - id: all
+    display_name: PostHog build step
+    tags: [orchestrator, build]
+    docs_urls: []
diff --git a/transformation-config/skills/build/description.md b/transformation-config/skills/build/description.md
new file mode 100644
index 00000000..dfeb018f
--- /dev/null
+++ b/transformation-config/skills/build/description.md
@@ -0,0 +1,24 @@
+# Install and build
+
+Bring the integration together: install the declared dependencies, then verify the
+project builds.
+
+## Install
+
+Detect the package manager from the lockfile — `pnpm-lock.yaml` → pnpm,
+`yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm — and run its install. The
+manifest already declares PostHog from the install step; you are realizing it now.
+
+## Build and verify
+
+Run the project's build or typecheck script if one exists (check the manifest's
+scripts for `build`, `typecheck`, `tsc`). Fix straightforward issues from the new
+PostHog code — a missing import, a wrong call shape.
+
+## Conflicts
+
+If install or build surfaces a conflict you cannot cleanly resolve — a peer
+dependency clash, a version conflict, a build error you should not paper over —
+stop forcing it. Summarize it in one line in your handoff `conflict` field, and
+put the full detail and what you tried in `did`. The user sees the one-liner in
+the outro and the detail in the report.
diff --git a/transformation-config/skills/capture/config.yaml b/transformation-config/skills/capture/config.yaml
new file mode 100644
index 00000000..8f973906
--- /dev/null
+++ b/transformation-config/skills/capture/config.yaml
@@ -0,0 +1,11 @@
+type: docs-only
+template: description.md
+description: Instrument the planned events with posthog.capture
+tags: [orchestrator, capture]
+variants:
+  - id: all
+    display_name: PostHog capture step
+    tags: [orchestrator, capture]
+    docs_urls:
+      - https://posthog.com/docs/libraries/js.md
+      - https://posthog.com/docs/product-analytics/best-practices.md
diff --git a/transformation-config/skills/capture/description.md b/transformation-config/skills/capture/description.md
new file mode 100644
index 00000000..d042de8b
--- /dev/null
+++ b/transformation-config/skills/capture/description.md
@@ -0,0 +1,15 @@
+# Capture events
+
+Instrument the planned events with `posthog.capture('event_name', { ...props })`.
+
+- Fire each capture on the real user action — the click or submit handler, the
+  server action — not on render or page load.
+- Add properties that make the event useful to analyze.
+- Read the file before editing, and check the event is not already captured, so a
+  re-run does not double-instrument.
+
+Use the event plan from the previous step for the names, files, and actions.
+
+## Reference
+
+{references}
diff --git a/transformation-config/skills/dashboard/config.yaml b/transformation-config/skills/dashboard/config.yaml
new file mode 100644
index 00000000..affa5328
--- /dev/null
+++ b/transformation-config/skills/dashboard/config.yaml
@@ -0,0 +1,9 @@
+type: docs-only
+template: description.md
+description: Create a starter PostHog dashboard from the captured events
+tags: [orchestrator, dashboard]
+variants:
+  - id: all
+    display_name: PostHog dashboard step
+    tags: [orchestrator, dashboard]
+    docs_urls: []
diff --git a/transformation-config/skills/dashboard/description.md b/transformation-config/skills/dashboard/description.md
new file mode 100644
index 00000000..71e580c5
--- /dev/null
+++ b/transformation-config/skills/dashboard/description.md
@@ -0,0 +1,11 @@
+# Create a starter dashboard
+
+Use the PostHog MCP tools to create a dashboard named "Analytics basics (wizard)"
+with a few high-signal insights built on the events this integration captures.
+
+- Read the capture step's handoff for the exact event names — use the real names,
+  do not invent events that were not instrumented.
+- Add up to five insights, favoring conversion funnels and the events that signal
+  activation or churn.
+
+Hand off the dashboard URL so the report can link to it.
diff --git a/transformation-config/skills/error-tracking-step/config.yaml b/transformation-config/skills/error-tracking-step/config.yaml
new file mode 100644
index 00000000..ec9aea97
--- /dev/null
+++ b/transformation-config/skills/error-tracking-step/config.yaml
@@ -0,0 +1,11 @@
+type: docs-only
+template: description.md
+description: Capture exceptions with PostHog around critical flows
+tags: [orchestrator, error-tracking]
+variants:
+  - id: all
+    display_name: PostHog error-tracking step
+    tags: [orchestrator, error-tracking]
+    docs_urls:
+      - https://posthog.com/docs/error-tracking/installation/web.md
+      - https://posthog.com/docs/error-tracking/installation/node.md
diff --git a/transformation-config/skills/error-tracking-step/description.md b/transformation-config/skills/error-tracking-step/description.md
new file mode 100644
index 00000000..ccc70121
--- /dev/null
+++ b/transformation-config/skills/error-tracking-step/description.md
@@ -0,0 +1,16 @@
+# Add error tracking
+
+Capture exceptions with PostHog at the points where failures matter.
+
+- Wrap the critical paths: server route handlers, server actions, payment,
+  webhook and auth endpoints, and client error boundaries.
+- Use `posthog.captureException(error, { ...context })` in the catch blocks,
+  with enough context to debug.
+- Do not swallow errors — capture, then handle or re-throw as the code already
+  does.
+- Read the file before editing, and add PostHog alongside any existing error
+  reporting rather than replacing it.
+
+## Reference
+
+{references}
diff --git a/transformation-config/skills/identify/config.yaml b/transformation-config/skills/identify/config.yaml
new file mode 100644
index 00000000..ed046697
--- /dev/null
+++ b/transformation-config/skills/identify/config.yaml
@@ -0,0 +1,10 @@
+type: docs-only
+template: description.md
+description: Identify users at login and signup
+tags: [orchestrator, identify]
+variants:
+  - id: all
+    display_name: PostHog identify step
+    tags: [orchestrator, identify]
+    docs_urls:
+      - https://posthog.com/docs/getting-started/identify-users.md
diff --git a/transformation-config/skills/identify/description.md b/transformation-config/skills/identify/description.md
new file mode 100644
index 00000000..8b4240c2
--- /dev/null
+++ b/transformation-config/skills/identify/description.md
@@ -0,0 +1,16 @@
+# Identify users
+
+Call `posthog.identify` at the moment the app learns who the user is — typically
+on login and signup success.
+
+- Use a stable unique id as the distinct id (the user id from your auth), not an
+  email or display name.
+- Pass useful person properties (email, name, plan) as the second argument.
+- Call `posthog.reset()` on logout so the next user starts clean.
+
+Find the auth flow first: login and signup handlers, session callbacks. If the
+app has no concept of a user, there is nothing to identify — report that and stop.
+
+## Reference
+
+{references}
diff --git a/transformation-config/skills/init/config.yaml b/transformation-config/skills/init/config.yaml
new file mode 100644
index 00000000..0317ac8e
--- /dev/null
+++ b/transformation-config/skills/init/config.yaml
@@ -0,0 +1,11 @@
+type: docs-only
+template: description.md
+description: Initialize PostHog and set its environment variables
+tags: [orchestrator, init]
+variants:
+  - id: all
+    display_name: PostHog init step
+    tags: [orchestrator, init]
+    docs_urls:
+      - https://posthog.com/docs/libraries/js.md
+      - https://posthog.com/docs/libraries/node.md
diff --git a/transformation-config/skills/init/description.md b/transformation-config/skills/init/description.md
new file mode 100644
index 00000000..7af55ea7
--- /dev/null
+++ b/transformation-config/skills/init/description.md
@@ -0,0 +1,28 @@
+# Initialize PostHog
+
+Set up PostHog so the SDK is configured once and available across the app.
+
+## Environment variables
+
+Set the PostHog keys through the wizard tools (`set_env_values`), never
+hardcoded. Use the framework's public env convention so the client can read them:
+`NEXT_PUBLIC_` for Next.js, `VITE_` for Vite, `PUBLIC_` for SvelteKit.
+
+- the public project token
+- the PostHog host
+
+## Init point
+
+Create the framework's single initialization point that runs once on the client:
+
+- **Next.js App Router**: a client `PostHogProvider` that calls `posthog.init`
+  with the env key and host, wrapping the app in the root layout.
+- **Other frameworks**: the equivalent provider or bootstrap that initializes
+  PostHog once.
+
+Read the existing provider or layout before editing, and add PostHog alongside
+what is already there rather than replacing it.
+
+## Reference
+
+{references}
diff --git a/transformation-config/skills/install/config.yaml b/transformation-config/skills/install/config.yaml
new file mode 100644
index 00000000..a442772b
--- /dev/null
+++ b/transformation-config/skills/install/config.yaml
@@ -0,0 +1,11 @@
+type: docs-only
+template: description.md
+description: Install the PostHog SDK with the project's package manager
+tags: [orchestrator, install]
+variants:
+  - id: all
+    display_name: PostHog install step
+    tags: [orchestrator, install]
+    docs_urls:
+      - https://posthog.com/docs/libraries/js.md
+      - https://posthog.com/docs/libraries/node.md
diff --git a/transformation-config/skills/install/description.md b/transformation-config/skills/install/description.md
new file mode 100644
index 00000000..624f4667
--- /dev/null
+++ b/transformation-config/skills/install/description.md
@@ -0,0 +1,19 @@
+# Add the PostHog SDK to the manifest
+
+Declare PostHog in the project's package manifest directly. Do not run the package
+manager, and do not build — the build task installs and verifies at the end.
+Adding it to the manifest now keeps this step fast and batches the real install
+into one place.
+
+- For a web or JavaScript framework app, add `posthog-js` to `dependencies`.
+- If the app has server-side code that should send events, also add
+  `posthog-node`.
+- Use a current, valid version range (e.g. `^1.x` for posthog-js). Match the
+  style of the other dependencies already in the manifest.
+
+Read the manifest first. If the dependency is already declared, leave it as is and
+say so. Edit only the manifest — no lockfile, no install command.
+
+## Reference
+
+{references}
diff --git a/transformation-config/skills/plan-capture/config.yaml b/transformation-config/skills/plan-capture/config.yaml
new file mode 100644
index 00000000..b8d28e59
--- /dev/null
+++ b/transformation-config/skills/plan-capture/config.yaml
@@ -0,0 +1,10 @@
+type: docs-only
+template: description.md
+description: Decide which custom events are worth capturing
+tags: [orchestrator, plan-capture]
+variants:
+  - id: all
+    display_name: PostHog capture-planning step
+    tags: [orchestrator, plan-capture]
+    docs_urls:
+      - https://posthog.com/docs/product-analytics/best-practices.md
diff --git a/transformation-config/skills/plan-capture/description.md b/transformation-config/skills/plan-capture/description.md
new file mode 100644
index 00000000..770f0957
--- /dev/null
+++ b/transformation-config/skills/plan-capture/description.md
@@ -0,0 +1,17 @@
+# Plan what to capture
+
+Read the app and decide which custom events are worth capturing. You are
+planning, not editing.
+
+Look for the actions that matter to a product team: signups, key feature use,
+content created, purchases, sharing, settings changed. Skip low-value noise and
+anything autocapture already covers (generic clicks, pageviews).
+
+For each event choose a clear, consistent name — `lower_snake_case`, named for
+the action — and note the file and the user action that should trigger it. A few
+high-signal events beat a long list. Hand off the plan so the capture step can
+instrument it.
+
+## Reference
+
+{references}
diff --git a/transformation-config/skills/report/config.yaml b/transformation-config/skills/report/config.yaml
new file mode 100644
index 00000000..1c454835
--- /dev/null
+++ b/transformation-config/skills/report/config.yaml
@@ -0,0 +1,9 @@
+type: docs-only
+template: description.md
+description: Write the PostHog setup report from the run's handoffs
+tags: [orchestrator, report]
+variants:
+  - id: all
+    display_name: PostHog report step
+    tags: [orchestrator, report]
+    docs_urls: []
diff --git a/transformation-config/skills/report/description.md b/transformation-config/skills/report/description.md
new file mode 100644
index 00000000..e25633a8
--- /dev/null
+++ b/transformation-config/skills/report/description.md
@@ -0,0 +1,19 @@
+# Write the setup report
+
+Write `posthog-setup-report.md` at the project root summarizing the integration.
+The handoffs from the previous steps are given to you as context — draw the
+details from them.
+
+Include:
+
+- A one-line summary of what was set up.
+- What was installed and how PostHog was initialized.
+- The events instrumented, as a table: event name, what it measures, the file.
+- Whether user identification was wired or skipped, and why.
+- The error tracking added.
+- The dashboard link.
+- Any build conflict, in full — the build step's handoff names it, and the user
+  needs the detail here.
+- Clear next steps for the user.
+
+Keep it skimmable. This is the artifact the user opens after the run.

From ba5146530afb6eac5369c692f871204db80cfdaa Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 9 Jun 2026 18:17:51 -0400
Subject: [PATCH 03/17] refine the orchestrator integration flow

Merges plan-capture into capture (one pass, writes .posthog-events.json for the event-plan view and the report); makes error-tracking a single global boundary; orders dashboard and report after build, which now also lints and tests; install stays manifest-only and build flags out-of-scope conflicts and moves on; report draws on the queue log and the events file; the docs-only skills drop framework specifics in favor of the bundled docs and examples.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 transformation-config/agents/build.md         |  7 ++--
 transformation-config/agents/capture.md       | 14 ++++----
 transformation-config/agents/dashboard.md     |  2 +-
 .../agents/error-tracking.md                  | 14 ++++----
 .../agents/integrate-posthog.md               | 19 ++++++-----
 transformation-config/agents/plan-capture.md  | 21 ------------
 transformation-config/agents/report.md        |  6 ++--
 .../skills/build/description.md               | 31 ++++++++++--------
 .../skills/capture/description.md             | 32 ++++++++++++++-----
 .../skills/error-tracking-step/description.md | 15 ++++-----
 .../skills/init/description.md                | 18 ++++-------
 .../skills/install/description.md             |  9 +++---
 .../skills/plan-capture/config.yaml           | 10 ------
 .../skills/plan-capture/description.md        | 17 ----------
 .../skills/report/description.md              | 14 +++++---
 15 files changed, 100 insertions(+), 129 deletions(-)
 delete mode 100644 transformation-config/agents/plan-capture.md
 delete mode 100644 transformation-config/skills/plan-capture/config.yaml
 delete mode 100644 transformation-config/skills/plan-capture/description.md

diff --git a/transformation-config/agents/build.md b/transformation-config/agents/build.md
index fb028d68..348bb5d3 100644
--- a/transformation-config/agents/build.md
+++ b/transformation-config/agents/build.md
@@ -11,12 +11,13 @@ dependsOn: [install, init, identify, error-tracking, capture]
 ## Goal
 
 Bring the integration together: install the dependencies the earlier steps
-declared, then verify the project builds. Until now the steps only edited code and
-the manifest — this is where it actually installs and compiles.
+declared, then verify the project builds, lints, and passes its tests. Until now
+the steps only edited code and the manifest — this is where it actually installs
+and is checked.
 
 ## How you know you succeeded
 
-The install completes and the build (or typecheck) passes. If you hit a conflict
+The install completes and the build, lint, and tests pass. If you hit a conflict
 you cannot cleanly resolve — a dependency clash, a build error from the new code —
 fix what you safely can, then report it: put a one-line summary in your handoff's
 `conflict` field and the full detail in what you did. The user sees the one-liner
diff --git a/transformation-config/agents/capture.md b/transformation-config/agents/capture.md
index b4317135..477c5d8b 100644
--- a/transformation-config/agents/capture.md
+++ b/transformation-config/agents/capture.md
@@ -1,19 +1,21 @@
 ---
 type: capture
-label: Instrument the planned events
+label: Capture events
 model: claude-sonnet-4-6
 skills: [capture]
 allowedTools: [Read, Edit, Glob, Grep]
 disallowedTools: [enqueue_task]
-dependsOn: [plan-capture]
+dependsOn: [install, init]
 ---
 
 ## Goal
 
-Instrument the events from the plan you were handed. Add a PostHog capture call at
-each one, on the real user action.
+Decide which events are worth capturing in this app, then instrument them in the
+same pass — read each file once, choose the events, and add the capture calls
+while the file is already open.
 
 ## How you know you succeeded
 
-Each planned event has a capture call that fires on the user action, not on page
-load or render. If a planned event no longer fits the code, skip it and note why.
+The meaningful user actions across the app have capture calls that fire on the
+real action, not on page load, and `.posthog-events.json` lists the events you
+instrumented.
diff --git a/transformation-config/agents/dashboard.md b/transformation-config/agents/dashboard.md
index 3adb8b6d..1cc2a887 100644
--- a/transformation-config/agents/dashboard.md
+++ b/transformation-config/agents/dashboard.md
@@ -5,7 +5,7 @@ model: claude-sonnet-4-6
 skills: [dashboard]
 allowedTools: [Read, Glob, Grep]
 disallowedTools: [Write, Edit, Bash, enqueue_task]
-dependsOn: [capture]
+dependsOn: [build]
 ---
 
 ## Goal
diff --git a/transformation-config/agents/error-tracking.md b/transformation-config/agents/error-tracking.md
index 3d7ac2d6..eae9d9ec 100644
--- a/transformation-config/agents/error-tracking.md
+++ b/transformation-config/agents/error-tracking.md
@@ -3,18 +3,18 @@ type: error-tracking
 label: Add error tracking
 model: claude-sonnet-4-6
 skills: [error-tracking-step]
-allowedTools: [Read, Edit, Glob, Grep]
+allowedTools: [Read, Write, Edit, Glob, Grep]
 disallowedTools: [enqueue_task]
-dependsOn: [install, init]
+dependsOn: [capture]
 ---
 
 ## Goal
 
-Add PostHog error tracking around the app's critical flows and boundaries, so
-failures that matter reach PostHog.
+Set up the framework's single global error boundary so uncaught errors reach
+PostHog. One place, following the docs and the reference example — not manual
+capture calls sprinkled across files.
 
 ## How you know you succeeded
 
-Exceptions in the important paths — the routes, actions, and boundaries where a
-failure hurts the user — are captured. If the app already reports errors
-elsewhere, add PostHog alongside it rather than replacing it.
+A global error handler forwards exceptions to PostHog. You did not read through the
+whole app or hand-wrap individual components or routes.
diff --git a/transformation-config/agents/integrate-posthog.md b/transformation-config/agents/integrate-posthog.md
index 8564a81f..35fa9aed 100644
--- a/transformation-config/agents/integrate-posthog.md
+++ b/transformation-config/agents/integrate-posthog.md
@@ -14,15 +14,18 @@ glance at the repo to confirm its shape — a quick look, not a deep analysis 
 then seed this graph:
 
 - `install` and `init`, independent of each other.
-- `identify`, `error-tracking`, and `plan-capture`, each after `install` and
-  `init`, independent of each other.
-- `capture`, after `plan-capture`.
-- `build`, after `install`, `init`, `identify`, `error-tracking`, and `capture` —
-  it installs the dependencies and verifies the project compiles.
-- `dashboard`, after `capture`.
-- `report`, after `build` and `dashboard` — it writes the setup report last.
+- `identify` and `capture`, each after `install` and `init`, independent of each
+  other. `capture` both decides the events and instruments them.
+- `error-tracking`, after `capture` — event tracking goes in first, then the
+  global error boundary.
+- `build`, after `install`, `init`, `identify`, `capture`, and `error-tracking` —
+  it installs the dependencies and verifies the project builds, lints, and passes
+  its tests.
+- `dashboard`, after `build` — only once the integration is confirmed building,
+  linting, and testing cleanly.
+- `report`, after `dashboard` — it writes the setup report last.
 
 ## How you know you succeeded
 
-The nine tasks are queued with that dependency shape, and the first is runnable.
+The tasks are queued with that dependency shape, and the first is runnable.
 Keep them small and discrete so each finishes fast and shows visible progress.
diff --git a/transformation-config/agents/plan-capture.md b/transformation-config/agents/plan-capture.md
deleted file mode 100644
index fc49c572..00000000
--- a/transformation-config/agents/plan-capture.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-type: plan-capture
-label: Plan which events to capture
-model: claude-sonnet-4-6
-skills: [plan-capture]
-allowedTools: [Read, Glob, Grep]
-disallowedTools: [Write, Edit, Bash, enqueue_task]
-dependsOn: [install, init]
----
-
-## Goal
-
-Decide which events are worth capturing in this app. Read the code to find the
-meaningful user actions — the things a product team would want to measure — and
-hand off that list. Do not edit code.
-
-## How you know you succeeded
-
-Your handoff is a short, concrete event plan: a handful of named events, each
-tied to a real user action and the file where it happens. Prefer a few
-high-signal events over an exhaustive list.
diff --git a/transformation-config/agents/report.md b/transformation-config/agents/report.md
index fdac07d7..8a49b13d 100644
--- a/transformation-config/agents/report.md
+++ b/transformation-config/agents/report.md
@@ -5,13 +5,13 @@ model: claude-sonnet-4-6
 skills: [report]
 allowedTools: [Read, Write, Glob, Grep]
 disallowedTools: [enqueue_task]
-dependsOn: [build, dashboard]
+dependsOn: [dashboard]
 ---
 
 ## Goal
 
-Write the setup report summarizing what this integration did, drawing on the
-handoffs from the previous steps.
+Write the setup report summarizing what this integration did, drawing only on the
+run's queue log (`.posthog-wizard/`) and the local `.posthog-events.json`.
 
 ## How you know you succeeded
 
diff --git a/transformation-config/skills/build/description.md b/transformation-config/skills/build/description.md
index dfeb018f..78f40899 100644
--- a/transformation-config/skills/build/description.md
+++ b/transformation-config/skills/build/description.md
@@ -1,24 +1,27 @@
 # Install and build
 
-Bring the integration together: install the declared dependencies, then verify the
-project builds.
+Install the declared dependencies, then verify the project builds. Be quick and
+decisive — this step must not spiral.
 
 ## Install
 
-Detect the package manager from the lockfile — `pnpm-lock.yaml` → pnpm,
-`yarn.lock` → yarn, `bun.lockb` → bun, otherwise npm — and run its install. The
-manifest already declares PostHog from the install step; you are realizing it now.
+Detect the package manager from the project's lockfile and run its install once,
+in this project directory. The manifest already declares PostHog.
 
 ## Build and verify
 
-Run the project's build or typecheck script if one exists (check the manifest's
-scripts for `build`, `typecheck`, `tsc`). Fix straightforward issues from the new
-PostHog code — a missing import, a wrong call shape.
+Run the project's build (or typecheck), lint, and test scripts if they exist
+(check the manifest's scripts). Fix only obvious issues from the new PostHog code —
+a missing import, a wrong call shape.
 
-## Conflicts
+## Flag out-of-scope conflicts and move on
 
-If install or build surfaces a conflict you cannot cleanly resolve — a peer
-dependency clash, a version conflict, a build error you should not paper over —
-stop forcing it. Summarize it in one line in your handoff `conflict` field, and
-put the full detail and what you tried in `did`. The user sees the one-liner in
-the outro and the detail in the report.
+Work only within this project's own directory; other repos and directories are not
+part of this task.
+
+If you hit a conflict that is excessively difficult and outside the scope of this
+integration — a dependency clash, a pre-existing build break, an environment issue
+that is not about the PostHog code — flag it and move on rather than spend time
+fighting it. Put a one-line summary in your handoff `conflict` field and the full
+detail in `did`, then complete the task. The user sees it in the outro and the
+report; flagging it is the right outcome.
diff --git a/transformation-config/skills/capture/description.md b/transformation-config/skills/capture/description.md
index d042de8b..43176247 100644
--- a/transformation-config/skills/capture/description.md
+++ b/transformation-config/skills/capture/description.md
@@ -1,14 +1,30 @@
-# Capture events
+# Plan and capture events
 
-Instrument the planned events with `posthog.capture('event_name', { ...props })`.
+Decide which custom events are worth capturing, then instrument them — in one
+pass, reading each file once.
 
-- Fire each capture on the real user action — the click or submit handler, the
-  server action — not on render or page load.
-- Add properties that make the event useful to analyze.
-- Read the file before editing, and check the event is not already captured, so a
-  re-run does not double-instrument.
+## Choose and record
 
-Use the event plan from the previous step for the names, files, and actions.
+From the project's files, select between 10 and 15 that might have business value
+for event tracking — especially conversion and churn events. Read them. Track
+actions, not pageviews (autocapture covers those). Don't duplicate events that
+already exist. Server-side events are required if there is instrumentable
+server-side code (API routes, server actions): payment/checkout completion,
+webhook handlers, and auth endpoints.
+
+Write the chosen events to `.posthog-events.json` at the project root — a JSON
+array of `{ event, description, file }`, one entry per event. Write it before you
+start editing: it drives the event-plan view, and it is the source the report
+reads later.
+
+## Instrument
+
+For each event add `posthog.capture('event_name', { ...props })` on the real user
+action — the click or submit handler, the server action — not on render or page
+load. Use clear `lower_snake_case` names and useful properties. Edit each file
+while it is already open.
+
+Leave `.posthog-events.json` in place for the report.
 
 ## Reference
 
diff --git a/transformation-config/skills/error-tracking-step/description.md b/transformation-config/skills/error-tracking-step/description.md
index ccc70121..2670a024 100644
--- a/transformation-config/skills/error-tracking-step/description.md
+++ b/transformation-config/skills/error-tracking-step/description.md
@@ -1,15 +1,12 @@
 # Add error tracking
 
-Capture exceptions with PostHog at the points where failures matter.
+Set up the framework's GLOBAL error boundary so uncaught errors and exceptions
+reach PostHog — one handler, not hand-wrapped across files.
 
-- Wrap the critical paths: server route handlers, server actions, payment,
-  webhook and auth endpoints, and client error boundaries.
-- Use `posthog.captureException(error, { ...context })` in the catch blocks,
-  with enough context to debug.
-- Do not swallow errors — capture, then handle or re-throw as the code already
-  does.
-- Read the file before editing, and add PostHog alongside any existing error
-  reporting rather than replacing it.
+Follow the framework's own mechanism for a global error handler, using the
+reference example and the docs for the exact pattern. Find the init or app entry,
+add the handler there, and you are done. One handler is enough — do not read
+through the whole app or wrap individual components or routes by hand.
 
 ## Reference
 
diff --git a/transformation-config/skills/init/description.md b/transformation-config/skills/init/description.md
index 7af55ea7..2440423e 100644
--- a/transformation-config/skills/init/description.md
+++ b/transformation-config/skills/init/description.md
@@ -4,24 +4,18 @@ Set up PostHog so the SDK is configured once and available across the app.
 
 ## Environment variables
 
-Set the PostHog keys through the wizard tools (`set_env_values`), never
-hardcoded. Use the framework's public env convention so the client can read them:
-`NEXT_PUBLIC_` for Next.js, `VITE_` for Vite, `PUBLIC_` for SvelteKit.
+Set the PostHog keys through the wizard tools (`set_env_values`), never hardcoded.
+Use the framework's public env-var convention so the client can read them.
 
 - the public project token
 - the PostHog host
 
 ## Init point
 
-Create the framework's single initialization point that runs once on the client:
-
-- **Next.js App Router**: a client `PostHogProvider` that calls `posthog.init`
-  with the env key and host, wrapping the app in the root layout.
-- **Other frameworks**: the equivalent provider or bootstrap that initializes
-  PostHog once.
-
-Read the existing provider or layout before editing, and add PostHog alongside
-what is already there rather than replacing it.
+Create the framework's single initialization point that runs once on the client,
+following the reference example and the docs for the right pattern. Read the
+existing provider or entry file before editing, and add PostHog alongside what is
+already there rather than replacing it.
 
 ## Reference
 
diff --git a/transformation-config/skills/install/description.md b/transformation-config/skills/install/description.md
index 624f4667..f914b263 100644
--- a/transformation-config/skills/install/description.md
+++ b/transformation-config/skills/install/description.md
@@ -5,11 +5,10 @@ manager, and do not build — the build task installs and verifies at the end.
 Adding it to the manifest now keeps this step fast and batches the real install
 into one place.
 
-- For a web or JavaScript framework app, add `posthog-js` to `dependencies`.
-- If the app has server-side code that should send events, also add
-  `posthog-node`.
-- Use a current, valid version range (e.g. `^1.x` for posthog-js). Match the
-  style of the other dependencies already in the manifest.
+Add the PostHog library appropriate for the app — the client library, plus the
+server library if the app has server-side code that should send events. Use the
+docs and the reference example to pick the right package and a current version
+range, and match the style of the dependencies already in the manifest.
 
 Read the manifest first. If the dependency is already declared, leave it as is and
 say so. Edit only the manifest — no lockfile, no install command.
diff --git a/transformation-config/skills/plan-capture/config.yaml b/transformation-config/skills/plan-capture/config.yaml
deleted file mode 100644
index b8d28e59..00000000
--- a/transformation-config/skills/plan-capture/config.yaml
+++ /dev/null
@@ -1,10 +0,0 @@
-type: docs-only
-template: description.md
-description: Decide which custom events are worth capturing
-tags: [orchestrator, plan-capture]
-variants:
-  - id: all
-    display_name: PostHog capture-planning step
-    tags: [orchestrator, plan-capture]
-    docs_urls:
-      - https://posthog.com/docs/product-analytics/best-practices.md
diff --git a/transformation-config/skills/plan-capture/description.md b/transformation-config/skills/plan-capture/description.md
deleted file mode 100644
index 770f0957..00000000
--- a/transformation-config/skills/plan-capture/description.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Plan what to capture
-
-Read the app and decide which custom events are worth capturing. You are
-planning, not editing.
-
-Look for the actions that matter to a product team: signups, key feature use,
-content created, purchases, sharing, settings changed. Skip low-value noise and
-anything autocapture already covers (generic clicks, pageviews).
-
-For each event choose a clear, consistent name — `lower_snake_case`, named for
-the action — and note the file and the user action that should trigger it. A few
-high-signal events beat a long list. Hand off the plan so the capture step can
-instrument it.
-
-## Reference
-
-{references}
diff --git a/transformation-config/skills/report/description.md b/transformation-config/skills/report/description.md
index e25633a8..b73d1258 100644
--- a/transformation-config/skills/report/description.md
+++ b/transformation-config/skills/report/description.md
@@ -1,19 +1,23 @@
 # Write the setup report
 
 Write `posthog-setup-report.md` at the project root summarizing the integration.
-The handoffs from the previous steps are given to you as context — draw the
-details from them.
+Draw on two sources only:
+
+- the run's queue log — `.posthog-wizard/queue.json` and the handoffs under
+  `.posthog-wizard/handoffs/` — for what each step did, whether identify was wired
+  or skipped, and any build conflict;
+- `.posthog-events.json` — the events that were instrumented.
 
 Include:
 
 - A one-line summary of what was set up.
 - What was installed and how PostHog was initialized.
-- The events instrumented, as a table: event name, what it measures, the file.
+- The events instrumented, as a table: event name, what it measures, and the file
+  (from `.posthog-events.json`).
 - Whether user identification was wired or skipped, and why.
 - The error tracking added.
 - The dashboard link.
-- Any build conflict, in full — the build step's handoff names it, and the user
-  needs the detail here.
+- Any build conflict, in full.
 - Clear next steps for the user.
 
 Keep it skimmable. This is the artifact the user opens after the run.

From b8e66ecc48d30d61ad8bd09b8f91c24e8a04451a Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Wed, 10 Jun 2026 15:24:26 -0400
Subject: [PATCH 04/17] =?UTF-8?q?feat(agents):=20per-flow=20registry=20mar?=
 =?UTF-8?q?kers=20=E2=80=94=20flow=20+=20seed=20frontmatter?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every agent names its flow (the program id) and each flow marks exactly one
prompt seed: true, the planner. The wizard's registry is scoped per flow, so
audit and migration flows can ship their own agent sets alongside these. The
canonical example moves to a README served to authors, not the menu — the
build skips it, so 'example' is no longer an installable agent.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 scripts/lib/agent-generator.js                |  3 +-
 transformation-config/agents/README.md        | 37 +++++++++++++++++++
 transformation-config/agents/build.md         |  1 +
 transformation-config/agents/capture.md       |  1 +
 transformation-config/agents/dashboard.md     |  1 +
 .../agents/error-tracking.md                  |  1 +
 transformation-config/agents/example.md       | 22 -----------
 transformation-config/agents/identify.md      |  1 +
 transformation-config/agents/init.md          |  1 +
 transformation-config/agents/install.md       |  1 +
 .../agents/integrate-posthog.md               |  2 +
 transformation-config/agents/report.md        |  1 +
 12 files changed, 49 insertions(+), 23 deletions(-)
 create mode 100644 transformation-config/agents/README.md
 delete mode 100644 transformation-config/agents/example.md

diff --git a/scripts/lib/agent-generator.js b/scripts/lib/agent-generator.js
index f84b912c..d404eeab 100644
--- a/scripts/lib/agent-generator.js
+++ b/scripts/lib/agent-generator.js
@@ -23,7 +23,8 @@ export function loadAgentIds(agentsSourceDir) {
     if (!fs.existsSync(agentsSourceDir)) return [];
     return fs
         .readdirSync(agentsSourceDir)
-        .filter(f => f.endsWith('.md'))
+        // README.md is documentation for authors, not a served prompt.
+        .filter(f => f.endsWith('.md') && f !== 'README.md')
         .map(f => f.slice(0, -'.md'.length))
         .sort();
 }
diff --git a/transformation-config/agents/README.md b/transformation-config/agents/README.md
new file mode 100644
index 00000000..0737511d
--- /dev/null
+++ b/transformation-config/agents/README.md
@@ -0,0 +1,37 @@
+# Agent prompts
+
+One `<type>.md` per orchestrator task — the WHAT of the task. The frontmatter
+carries the artifacts the executor configures the run with: the model, the
+mini-skills to load (the HOW), the tools the task may and may not use, and the
+tasks it depends on. `flow` names the program the agent belongs to — the
+wizard's registry is scoped per flow, so audit or migration agents live
+alongside these — and one prompt per flow is marked `seed: true`: the planner
+that seeds the queue, not an enqueueable task type.
+
+The body is intent only — what to do and what done looks like. The client
+injects the basics (project context, how to report, how to surface progress),
+so a prompt never restates them.
+
+This README is documentation, not data: the build serves every other `.md` in
+this folder as an agent prompt.
+
+```markdown
+---
+type: example
+flow: my-flow
+model: claude-haiku-4-5-20251001
+skills: []
+allowedTools: [Read, Glob, Grep]
+disallowedTools: [enqueue_task]
+dependsOn: []
+---
+
+## Goal
+
+What this task does, in plain prose.
+
+## How you know you succeeded
+
+Plain-text success criteria live here. State what done looks like, and what to
+do when the task cannot be completed.
+```
diff --git a/transformation-config/agents/build.md b/transformation-config/agents/build.md
index 348bb5d3..e4c97add 100644
--- a/transformation-config/agents/build.md
+++ b/transformation-config/agents/build.md
@@ -1,5 +1,6 @@
 ---
 type: build
+flow: posthog-integration
 label: Install dependencies and build
 model: claude-sonnet-4-6
 skills: [build]
diff --git a/transformation-config/agents/capture.md b/transformation-config/agents/capture.md
index 477c5d8b..08b0cfcf 100644
--- a/transformation-config/agents/capture.md
+++ b/transformation-config/agents/capture.md
@@ -1,5 +1,6 @@
 ---
 type: capture
+flow: posthog-integration
 label: Capture events
 model: claude-sonnet-4-6
 skills: [capture]
diff --git a/transformation-config/agents/dashboard.md b/transformation-config/agents/dashboard.md
index 1cc2a887..7dcb0745 100644
--- a/transformation-config/agents/dashboard.md
+++ b/transformation-config/agents/dashboard.md
@@ -1,5 +1,6 @@
 ---
 type: dashboard
+flow: posthog-integration
 label: Create a starter dashboard
 model: claude-sonnet-4-6
 skills: [dashboard]
diff --git a/transformation-config/agents/error-tracking.md b/transformation-config/agents/error-tracking.md
index eae9d9ec..4b859d63 100644
--- a/transformation-config/agents/error-tracking.md
+++ b/transformation-config/agents/error-tracking.md
@@ -1,5 +1,6 @@
 ---
 type: error-tracking
+flow: posthog-integration
 label: Add error tracking
 model: claude-sonnet-4-6
 skills: [error-tracking-step]
diff --git a/transformation-config/agents/example.md b/transformation-config/agents/example.md
deleted file mode 100644
index d028ee27..00000000
--- a/transformation-config/agents/example.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-type: example
-model: claude-haiku-4-5-20251001
-skills: []
-allowedTools: [Read, Glob, Grep]
-disallowedTools: [enqueue_task]
-dependsOn: []
----
-
-## Goal
-
-This is the canonical example of an agent prompt, the WHAT of an orchestrator
-task. The frontmatter carries the artifacts the executor configures the run
-with: the model, the mini-skills to load (the HOW), the tools the task may and
-may not use, and the tasks it depends on. The body is intent only — what to do
-and what done looks like. The client injects the basics (project context, how to
-report, how to surface progress), so a prompt never restates them.
-
-## How you know you succeeded
-
-Plain-text success criteria live here. State what done looks like, and what to do
-when the task cannot be completed.
diff --git a/transformation-config/agents/identify.md b/transformation-config/agents/identify.md
index 28ccad11..70f8ecad 100644
--- a/transformation-config/agents/identify.md
+++ b/transformation-config/agents/identify.md
@@ -1,5 +1,6 @@
 ---
 type: identify
+flow: posthog-integration
 label: Wire user identification
 model: claude-sonnet-4-6
 skills: [identify]
diff --git a/transformation-config/agents/init.md b/transformation-config/agents/init.md
index b826089b..052b87fc 100644
--- a/transformation-config/agents/init.md
+++ b/transformation-config/agents/init.md
@@ -1,5 +1,6 @@
 ---
 type: init
+flow: posthog-integration
 label: Set up PostHog initialization
 model: claude-haiku-4-5-20251001
 skills: [init]
diff --git a/transformation-config/agents/install.md b/transformation-config/agents/install.md
index 1ca1636e..e11fa69d 100644
--- a/transformation-config/agents/install.md
+++ b/transformation-config/agents/install.md
@@ -1,5 +1,6 @@
 ---
 type: install
+flow: posthog-integration
 label: Add the PostHog SDK to the manifest
 model: claude-haiku-4-5-20251001
 skills: [install]
diff --git a/transformation-config/agents/integrate-posthog.md b/transformation-config/agents/integrate-posthog.md
index 35fa9aed..03306fb1 100644
--- a/transformation-config/agents/integrate-posthog.md
+++ b/transformation-config/agents/integrate-posthog.md
@@ -1,5 +1,7 @@
 ---
 type: integrate-posthog
+flow: posthog-integration
+seed: true
 model: claude-sonnet-4-6
 skills: []
 allowedTools: [Read, Glob, Grep]
diff --git a/transformation-config/agents/report.md b/transformation-config/agents/report.md
index 8a49b13d..19a8cc62 100644
--- a/transformation-config/agents/report.md
+++ b/transformation-config/agents/report.md
@@ -1,5 +1,6 @@
 ---
 type: report
+flow: posthog-integration
 label: Write the setup report
 model: claude-sonnet-4-6
 skills: [report]

From 5ddce459b7ae9ddbbdcb65801c9dd0110ac863d9 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Wed, 10 Jun 2026 16:38:42 -0400
Subject: [PATCH 05/17] feat(skills): emit framework commandments as
 references/COMMANDMENTS.md

The orchestrator installs the framework's integration skill as the run
reference and points task agents at individual files, so the tag-matched
rules need to exist outside the SKILL.md body. The file also joins the
references listing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 scripts/lib/skill-generator.js | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/scripts/lib/skill-generator.js b/scripts/lib/skill-generator.js
index 3a7d3dca..ed98f472 100644
--- a/scripts/lib/skill-generator.js
+++ b/scripts/lib/skill-generator.js
@@ -581,15 +581,30 @@ async function generateSkill({
         }
     }
 
+    // Collect commandments for this skill's tags
+    const rules = collectCommandments(skill.tags || [], commandmentsConfig);
+    const commandmentsText = formatCommandments(rules);
+
+    // Also emit them as a reference file. The orchestrator installs this skill
+    // as the framework reference and points its task agents at individual
+    // files, so the rules must exist outside the SKILL.md body.
+    if (rules.length > 0) {
+        fs.writeFileSync(
+            path.join(referencesDir, 'COMMANDMENTS.md'),
+            `# Framework rules\n\nFollow these when integrating PostHog into this framework.\n\n${commandmentsText}\n`,
+            'utf8',
+        );
+        references.push({
+            filename: 'COMMANDMENTS.md',
+            description: 'Framework-specific rules the integration must follow',
+        });
+    }
+
     // Build references list for SKILL.md
     const referencesText = references
         .map(ref => `- \`references/${ref.filename}\` - ${ref.description}`)
         .join('\n');
 
-    // Collect commandments for this skill's tags
-    const rules = collectCommandments(skill.tags || [], commandmentsConfig);
-    const commandmentsText = formatCommandments(rules);
-
     // Format workflow steps
     const workflowText = formatWorkflowSteps(workflows);
 

From 0a62554ec4991cfa4c43dd015ad6b5cd833d6812 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Wed, 10 Jun 2026 17:00:55 -0400
Subject: [PATCH 06/17] feat(agents): dashboard is not a CI task
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ci: false in the dashboard frontmatter — CI runs must not create dashboards,
so the wizard's registry drops the type there. The seed plans around missing
types, rewiring dependents to the nearest upstream step.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 transformation-config/agents/dashboard.md         | 1 +
 transformation-config/agents/integrate-posthog.md | 4 ++++
 2 files changed, 5 insertions(+)

diff --git a/transformation-config/agents/dashboard.md b/transformation-config/agents/dashboard.md
index 7dcb0745..bb027687 100644
--- a/transformation-config/agents/dashboard.md
+++ b/transformation-config/agents/dashboard.md
@@ -1,6 +1,7 @@
 ---
 type: dashboard
 flow: posthog-integration
+ci: false
 label: Create a starter dashboard
 model: claude-sonnet-4-6
 skills: [dashboard]
diff --git a/transformation-config/agents/integrate-posthog.md b/transformation-config/agents/integrate-posthog.md
index 03306fb1..443e05fd 100644
--- a/transformation-config/agents/integrate-posthog.md
+++ b/transformation-config/agents/integrate-posthog.md
@@ -27,6 +27,10 @@ then seed this graph:
   linting, and testing cleanly.
 - `report`, after `dashboard` — it writes the setup report last.
 
+Some task types are not available in every run — `enqueue_task` only accepts
+the ones that are. Plan without the missing ones and rewire their dependents
+to the nearest upstream step (no `dashboard` means `report` follows `build`).
+
 ## How you know you succeeded
 
 The tasks are queued with that dependency shape, and the first is runnable.

From 464c6fd7928d155d494846864e419201152319f5 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Wed, 10 Jun 2026 17:17:59 -0400
Subject: [PATCH 07/17] =?UTF-8?q?revert=20ci=20awareness=20from=20agent=20?=
 =?UTF-8?q?content=20=E2=80=94=20the=20harness=20owns=20run-mode=20policy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 transformation-config/agents/dashboard.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/transformation-config/agents/dashboard.md b/transformation-config/agents/dashboard.md
index bb027687..7dcb0745 100644
--- a/transformation-config/agents/dashboard.md
+++ b/transformation-config/agents/dashboard.md
@@ -1,7 +1,6 @@
 ---
 type: dashboard
 flow: posthog-integration
-ci: false
 label: Create a starter dashboard
 model: claude-sonnet-4-6
 skills: [dashboard]

From 5a3d5e425d592fbccba2e340551833310edf2f0f Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 16 Jun 2026 20:24:16 -0400
Subject: [PATCH 08/17] feat(orchestrator): parallel error-tracking, seed full
 graph, cache paths

Seed wires error-tracking after install+init (parallel with identify/
capture) instead of after capture; error-tracking agent is instrument-only
(no install/build/test, stay in project). Seed prompt drops the
"plan without the missing ones" hedge so the full chain (through report)
is always queued. Report reads .posthog-wizard-cache/ (renamed cache dir).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../agents/error-tracking.md                  | 15 ++++++++++----
 .../agents/integrate-posthog.md               | 20 +++++++------------
 transformation-config/agents/report.md        |  2 +-
 .../skills/report/description.md              |  4 ++--
 4 files changed, 21 insertions(+), 20 deletions(-)

diff --git a/transformation-config/agents/error-tracking.md b/transformation-config/agents/error-tracking.md
index 4b859d63..c3489c07 100644
--- a/transformation-config/agents/error-tracking.md
+++ b/transformation-config/agents/error-tracking.md
@@ -6,16 +6,23 @@ model: claude-sonnet-4-6
 skills: [error-tracking-step]
 allowedTools: [Read, Write, Edit, Glob, Grep]
 disallowedTools: [enqueue_task]
-dependsOn: [capture]
+dependsOn: [install, init]
 ---
 
 ## Goal
 
 Set up the framework's single global error boundary so uncaught errors reach
-PostHog. One place, following the docs and the reference example — not manual
-capture calls sprinkled across files.
+PostHog. One place — the init or app entry — following the docs and the reference
+example, not manual capture calls sprinkled across files. The SDK is already
+installed and initialized (see the context from previous steps); build on that,
+do not re-check it.
+
+This is an instrument-only task. Do not install dependencies, run the build, run
+tests, or start the app — a later `build` step does all verification. Stay inside
+this project's directory and edit the one global handler; that is the whole job.
 
 ## How you know you succeeded
 
-A global error handler forwards exceptions to PostHog. You did not read through the
+A global error handler forwards exceptions to PostHog. You did not install
+anything, run a build or tests, search outside the project, or read through the
 whole app or hand-wrap individual components or routes.
diff --git a/transformation-config/agents/integrate-posthog.md b/transformation-config/agents/integrate-posthog.md
index 443e05fd..904ef74f 100644
--- a/transformation-config/agents/integrate-posthog.md
+++ b/transformation-config/agents/integrate-posthog.md
@@ -11,15 +11,13 @@ dependsOn: []
 
 ## Goal
 
-Plan a PostHog integration for this project and seed the task queue. Take a brief
-glance at the repo to confirm its shape — a quick look, not a deep analysis —
-then seed this graph:
+Plan a PostHog integration and seed the task queue with this graph:
 
 - `install` and `init`, independent of each other.
-- `identify` and `capture`, each after `install` and `init`, independent of each
-  other. `capture` both decides the events and instruments them.
-- `error-tracking`, after `capture` — event tracking goes in first, then the
-  global error boundary.
+- `identify`, `capture`, and `error-tracking`, each after `install` and `init`
+  and independent of one another, so they run in parallel. `capture` decides the
+  events and instruments them; `error-tracking` wires the single global error
+  boundary — it needs the SDK installed and initialized, not the events.
 - `build`, after `install`, `init`, `identify`, `capture`, and `error-tracking` —
   it installs the dependencies and verifies the project builds, lints, and passes
   its tests.
@@ -27,11 +25,7 @@ then seed this graph:
   linting, and testing cleanly.
 - `report`, after `dashboard` — it writes the setup report last.
 
-Some task types are not available in every run — `enqueue_task` only accepts
-the ones that are. Plan without the missing ones and rewire their dependents
-to the nearest upstream step (no `dashboard` means `report` follows `build`).
-
 ## How you know you succeeded
 
-The tasks are queued with that dependency shape, and the first is runnable.
-Keep them small and discrete so each finishes fast and shows visible progress.
+Every task in the graph is queued with that dependency shape, the report last,
+and the first task runnable. Keep labels short — the action in a few words.
diff --git a/transformation-config/agents/report.md b/transformation-config/agents/report.md
index 19a8cc62..ed0c6747 100644
--- a/transformation-config/agents/report.md
+++ b/transformation-config/agents/report.md
@@ -12,7 +12,7 @@ dependsOn: [dashboard]
 ## Goal
 
 Write the setup report summarizing what this integration did, drawing only on the
-run's queue log (`.posthog-wizard/`) and the local `.posthog-events.json`.
+run's queue log (`.posthog-wizard-cache/`) and the local `.posthog-events.json`.
 
 ## How you know you succeeded
 
diff --git a/transformation-config/skills/report/description.md b/transformation-config/skills/report/description.md
index b73d1258..4cc554ed 100644
--- a/transformation-config/skills/report/description.md
+++ b/transformation-config/skills/report/description.md
@@ -3,8 +3,8 @@
 Write `posthog-setup-report.md` at the project root summarizing the integration.
 Draw on two sources only:
 
-- the run's queue log — `.posthog-wizard/queue.json` and the handoffs under
-  `.posthog-wizard/handoffs/` — for what each step did, whether identify was wired
+- the run's queue log — `.posthog-wizard-cache/queue.json`, which holds each
+  task's handoff inline — for what each step did, whether identify was wired
   or skipped, and any build conflict;
 - `.posthog-events.json` — the events that were instrumented.
 

From 8092ddbf0d58548bf07886423ca888dd0fbd7096 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 16 Jun 2026 20:34:36 -0400
Subject: [PATCH 09/17] fix(skills): SDK error integration + personless anon
 events

error-tracking: use the framework's PostHog middleware / capture_exception(),
never a hand-rolled middleware that builds exception events via capture().
capture: use the authed user's id; for unauthenticated actions emit a
personless event instead of fabricating an 'anonymous' distinct id.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../skills/capture/description.md             |  5 +++++
 .../skills/error-tracking-step/description.md | 19 +++++++++++++------
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/transformation-config/skills/capture/description.md b/transformation-config/skills/capture/description.md
index 43176247..67a394d4 100644
--- a/transformation-config/skills/capture/description.md
+++ b/transformation-config/skills/capture/description.md
@@ -24,6 +24,11 @@ action — the click or submit handler, the server action — not on render or p
 load. Use clear `lower_snake_case` names and useful properties. Edit each file
 while it is already open.
 
+Server-side, use the authenticated user's id as the distinct id. For a genuinely
+unauthenticated action, emit a personless event — never fabricate a placeholder
+id like `'anonymous'`, which collapses every anonymous user into one person and
+corrupts the data.
+
 Leave `.posthog-events.json` in place for the report.
 
 ## Reference
diff --git a/transformation-config/skills/error-tracking-step/description.md b/transformation-config/skills/error-tracking-step/description.md
index 2670a024..1511c94f 100644
--- a/transformation-config/skills/error-tracking-step/description.md
+++ b/transformation-config/skills/error-tracking-step/description.md
@@ -1,12 +1,19 @@
 # Add error tracking
 
-Set up the framework's GLOBAL error boundary so uncaught errors and exceptions
-reach PostHog — one handler, not hand-wrapped across files.
+Wire the framework's single global path for uncaught errors and exceptions to
+PostHog — one handler, not hand-wrapped across files.
 
-Follow the framework's own mechanism for a global error handler, using the
-reference example and the docs for the exact pattern. Find the init or app entry,
-add the handler there, and you are done. One handler is enough — do not read
-through the whole app or wrap individual components or routes by hand.
+Use the SDK's own integration; do not hand-roll one. Where the framework ships a
+PostHog middleware or handler, add that — it captures exceptions and request
+context for you (e.g. Django:
+`posthog.integrations.django.PosthogContextMiddleware` in `MIDDLEWARE`). Where
+you must capture manually, call `posthog.capture_exception(e)` from the
+framework's central error handler — never hand-construct an exception event with
+`posthog.capture(...)`. Follow the framework rules (COMMANDMENTS) and the
+reference for the exact pattern.
+
+Find the init or app entry, wire it once, and you are done — don't read through
+the whole app or wrap individual components or routes by hand.
 
 ## Reference
 

From 3f7325e63d34d0360cad6b29ec93cb7ab9737027 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 16 Jun 2026 21:01:05 -0400
Subject: [PATCH 10/17] revert: drop hardcoded Django middleware prose from
 error-tracking-step

Framework specifics belong in docs/variants, not a step's prose. The fixed
reference (integration-<framework>) now carries the framework's EXAMPLE.md +
COMMANDMENTS (incl. PosthogContextMiddleware), so the step stays generic.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../skills/error-tracking-step/description.md | 19 ++++++-------------
 1 file changed, 6 insertions(+), 13 deletions(-)

diff --git a/transformation-config/skills/error-tracking-step/description.md b/transformation-config/skills/error-tracking-step/description.md
index 1511c94f..2670a024 100644
--- a/transformation-config/skills/error-tracking-step/description.md
+++ b/transformation-config/skills/error-tracking-step/description.md
@@ -1,19 +1,12 @@
 # Add error tracking
 
-Wire the framework's single global path for uncaught errors and exceptions to
-PostHog — one handler, not hand-wrapped across files.
+Set up the framework's GLOBAL error boundary so uncaught errors and exceptions
+reach PostHog — one handler, not hand-wrapped across files.
 
-Use the SDK's own integration; do not hand-roll one. Where the framework ships a
-PostHog middleware or handler, add that — it captures exceptions and request
-context for you (e.g. Django:
-`posthog.integrations.django.PosthogContextMiddleware` in `MIDDLEWARE`). Where
-you must capture manually, call `posthog.capture_exception(e)` from the
-framework's central error handler — never hand-construct an exception event with
-`posthog.capture(...)`. Follow the framework rules (COMMANDMENTS) and the
-reference for the exact pattern.
-
-Find the init or app entry, wire it once, and you are done — don't read through
-the whole app or wrap individual components or routes by hand.
+Follow the framework's own mechanism for a global error handler, using the
+reference example and the docs for the exact pattern. Find the init or app entry,
+add the handler there, and you are done. One handler is enough — do not read
+through the whole app or wrap individual components or routes by hand.
 
 ## Reference
 

From 3a9a57daa44b3b7e8b660ea9462c70375e41d6f5 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 16 Jun 2026 21:38:41 -0400
Subject: [PATCH 11/17] fix(build skill): don't fight install, report and move
 on
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Stop the build agent flailing when install is slow/erroring: no offline-flag
retries, no poking the package manager's global store/cache, nothing outside the
project dir. A build/install it can't cleanly finish is fine as long as it's
reported in the handoff conflict — reporting and moving on is the right outcome.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../skills/build/description.md               | 25 +++++++++++--------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/transformation-config/skills/build/description.md b/transformation-config/skills/build/description.md
index 78f40899..208f295b 100644
--- a/transformation-config/skills/build/description.md
+++ b/transformation-config/skills/build/description.md
@@ -6,7 +6,10 @@ decisive — this step must not spiral.
 ## Install
 
 Detect the package manager from the project's lockfile and run its install once,
-in this project directory. The manifest already declares PostHog.
+in this project directory. The manifest already declares PostHog. If install is
+slow, errors, or can't resolve a package, do not retry with offline flags and do
+not poke the package manager's global store or cache — a failed install is a
+conflict to report (below), not a problem to fight.
 
 ## Build and verify
 
@@ -16,12 +19,14 @@ a missing import, a wrong call shape.
 
 ## Flag out-of-scope conflicts and move on
 
-Work only within this project's own directory; other repos and directories are not
-part of this task.
-
-If you hit a conflict that is excessively difficult and outside the scope of this
-integration — a dependency clash, a pre-existing build break, an environment issue
-that is not about the PostHog code — flag it and move on rather than spend time
-fighting it. Put a one-line summary in your handoff `conflict` field and the full
-detail in `did`, then complete the task. The user sees it in the outro and the
-report; flagging it is the right outcome.
+Work only inside this project's own directory. Never read, search, or write
+anywhere outside it — not other repos, not the OS, not the package manager's
+global store or cache.
+
+A build or install you can't cleanly finish is a perfectly acceptable outcome —
+**as long as you report it.** If you hit a conflict that is excessively difficult
+or outside the scope of this integration — a dependency clash, a pre-existing
+build break, an install that won't resolve, an environment issue unrelated to the
+PostHog code — stop fighting it: put a one-line summary in your handoff `conflict`
+field and the full detail in `did`, then complete the task. The user sees it in
+the outro and the report; reporting it and moving on is the right outcome.

From 08a91caf9f5751539cb17861dc21a6bc3c165445 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 16 Jun 2026 21:47:55 -0400
Subject: [PATCH 12/17] feat(docs): reference identity-resolution.md everywhere
 identity is

Add https://posthog.com/docs/product-analytics/identity-resolution.md alongside
identify-users.md in every skill/doc that bundles the identity doc (identify,
integration, the omnibus instrument skills, the audit family, revenue-analytics,
best-practices, and the docs.yaml inline doc) so every identity-touching agent
gets the resolution guidance.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 transformation-config/docs.yaml                                  | 1 +
 transformation-config/skills/audit-3000/config.yaml              | 1 +
 transformation-config/skills/audit-identify/config.yaml          | 1 +
 transformation-config/skills/audit/config.yaml                   | 1 +
 transformation-config/skills/events-audit/config.yaml            | 1 +
 transformation-config/skills/identify/config.yaml                | 1 +
 transformation-config/skills/integration/config.yaml             | 1 +
 .../skills/omnibus/instrument-integration/config.yaml            | 1 +
 .../skills/omnibus/instrument-product-analytics/config.yaml      | 1 +
 transformation-config/skills/posthog-best-practices/config.yaml  | 1 +
 transformation-config/skills/revenue-analytics/config.yaml       | 1 +
 11 files changed, 11 insertions(+)

diff --git a/transformation-config/docs.yaml b/transformation-config/docs.yaml
index 1ca6752d..4e29e14e 100644
--- a/transformation-config/docs.yaml
+++ b/transformation-config/docs.yaml
@@ -8,6 +8,7 @@ docs:
     tags: [core, users, identity]
     urls:
       - https://posthog.com/docs/getting-started/identify-users.md
+      - https://posthog.com/docs/product-analytics/identity-resolution.md
 
   - id: cloudflare-workers
     display_name: Cloudflare Workers
diff --git a/transformation-config/skills/audit-3000/config.yaml b/transformation-config/skills/audit-3000/config.yaml
index 99252ec6..9ba87386 100644
--- a/transformation-config/skills/audit-3000/config.yaml
+++ b/transformation-config/skills/audit-3000/config.yaml
@@ -6,6 +6,7 @@ references:
   preamble: "**Read ONLY this file.** Do not read any other reference file until this one tells you to."
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
   - https://posthog.com/docs/product-analytics/best-practices.md
   - https://posthog.com/docs/session-replay/how-to-control-which-sessions-you-record.md
   - https://posthog.com/docs/session-replay/network-recording.md
diff --git a/transformation-config/skills/audit-identify/config.yaml b/transformation-config/skills/audit-identify/config.yaml
index 60ab37c3..56065f20 100644
--- a/transformation-config/skills/audit-identify/config.yaml
+++ b/transformation-config/skills/audit-identify/config.yaml
@@ -6,6 +6,7 @@ references:
   preamble: "**Read ONLY this file.** Do not read any other reference file until this one tells you to."
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
   - https://posthog.com/docs/product-analytics/cutting-costs.md
   - https://posthog.com/docs/libraries/js/config.md
 variants:
diff --git a/transformation-config/skills/audit/config.yaml b/transformation-config/skills/audit/config.yaml
index 0dd7276c..3d1dd7e9 100644
--- a/transformation-config/skills/audit/config.yaml
+++ b/transformation-config/skills/audit/config.yaml
@@ -6,6 +6,7 @@ references:
   preamble: "**Read ONLY this file.** Do not read any other reference file until this one tells you to."
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
   - https://posthog.com/docs/product-analytics/best-practices.md
 variants:
   - id: all
diff --git a/transformation-config/skills/events-audit/config.yaml b/transformation-config/skills/events-audit/config.yaml
index 12e462f8..78f2c0ad 100644
--- a/transformation-config/skills/events-audit/config.yaml
+++ b/transformation-config/skills/events-audit/config.yaml
@@ -7,6 +7,7 @@ references:
 shared_docs:
   - https://posthog.com/docs/product-analytics/best-practices.md
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: all
     display_name: PostHog events audit
diff --git a/transformation-config/skills/identify/config.yaml b/transformation-config/skills/identify/config.yaml
index ed046697..f257eeb4 100644
--- a/transformation-config/skills/identify/config.yaml
+++ b/transformation-config/skills/identify/config.yaml
@@ -8,3 +8,4 @@ variants:
     tags: [orchestrator, identify]
     docs_urls:
       - https://posthog.com/docs/getting-started/identify-users.md
+      - https://posthog.com/docs/product-analytics/identity-resolution.md
diff --git a/transformation-config/skills/integration/config.yaml b/transformation-config/skills/integration/config.yaml
index 56949f1a..3542ab9b 100644
--- a/transformation-config/skills/integration/config.yaml
+++ b/transformation-config/skills/integration/config.yaml
@@ -4,6 +4,7 @@ template: description.md
 description: PostHog integration for {display_name} applications
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: nextjs-app-router
     example_paths: basics/next-app-router
diff --git a/transformation-config/skills/omnibus/instrument-integration/config.yaml b/transformation-config/skills/omnibus/instrument-integration/config.yaml
index e7b2cf9b..a6fb38ea 100644
--- a/transformation-config/skills/omnibus/instrument-integration/config.yaml
+++ b/transformation-config/skills/omnibus/instrument-integration/config.yaml
@@ -5,6 +5,7 @@ description: Add PostHog SDK integration to your application. Use when setting u
 tags: []
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: all
     display_name: all supported frameworks
diff --git a/transformation-config/skills/omnibus/instrument-product-analytics/config.yaml b/transformation-config/skills/omnibus/instrument-product-analytics/config.yaml
index fd7efd27..0869ab73 100644
--- a/transformation-config/skills/omnibus/instrument-product-analytics/config.yaml
+++ b/transformation-config/skills/omnibus/instrument-product-analytics/config.yaml
@@ -6,6 +6,7 @@ description: Add PostHog product analytics events to track user behavior. Use af
 tags: []
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: all
     display_name: all supported frameworks
diff --git a/transformation-config/skills/posthog-best-practices/config.yaml b/transformation-config/skills/posthog-best-practices/config.yaml
index 8e5cb040..c3894c26 100644
--- a/transformation-config/skills/posthog-best-practices/config.yaml
+++ b/transformation-config/skills/posthog-best-practices/config.yaml
@@ -4,6 +4,7 @@ description: Framework-agnostic, distilled best practices for using PostHog
 tags: [best-practices]
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
   - https://posthog.com/docs/new-to-posthog/understand-posthog.md
   - https://posthog.com/docs/privacy/data-collection.md
   - https://posthog.com/docs/advanced/proxy.md
diff --git a/transformation-config/skills/revenue-analytics/config.yaml b/transformation-config/skills/revenue-analytics/config.yaml
index 212520a1..889e1fca 100644
--- a/transformation-config/skills/revenue-analytics/config.yaml
+++ b/transformation-config/skills/revenue-analytics/config.yaml
@@ -6,6 +6,7 @@ tags: [revenue-analytics, stripe]
 shared_docs:
   - https://posthog.com/docs/revenue-analytics/connect-to-customers.md
   - https://posthog.com/docs/getting-started/identify-users.md
+  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: setup
     display_name: Stripe Revenue Analytics

From 5d937f57592a18fda10093f57e3bde5d9e0bb783 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Tue, 16 Jun 2026 22:26:29 -0400
Subject: [PATCH 13/17] build skill: leave pre-existing errors in untouched
 files alone

The build agent was re-running typecheck/lint in a loop chasing a green it
could never reach, because the test app had pre-existing type errors in files
the integration never touched. Make ownership explicit: only fix errors in
files this integration changed; a failure in an untouched file is pre-existing,
note it and move on. Don't re-run hoping it clears.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 transformation-config/skills/build/description.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/transformation-config/skills/build/description.md b/transformation-config/skills/build/description.md
index 208f295b..aa9356cf 100644
--- a/transformation-config/skills/build/description.md
+++ b/transformation-config/skills/build/description.md
@@ -14,8 +14,11 @@ conflict to report (below), not a problem to fight.
 ## Build and verify
 
 Run the project's build (or typecheck), lint, and test scripts if they exist
-(check the manifest's scripts). Fix only obvious issues from the new PostHog code —
-a missing import, a wrong call shape.
+(check the manifest's scripts). Only errors in the files this integration changed
+are yours to fix — a missing import, a wrong call shape.
+An error in a file the integration never touched is pre-existing: note it and
+move on (below). Do not re-run build, typecheck, or lint hoping a pre-existing
+failure clears — it will not, and each re-run is slow.
 
 ## Flag out-of-scope conflicts and move on
 

From 46e04e7eb509c593b81e92481b03428e1d33703c Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Thu, 18 Jun 2026 09:15:22 -0400
Subject: [PATCH 14/17] fix: drop stale identity-resolution shared_doc to match
 main

The branch carried an identity-resolution shared_doc that main removed; the
merge kept the old version, adding the doc to ~43 built skills. Align the 8
configs with main so the build output drifts only where the agents content
type is added.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 context/skills/audit-identify/config.yaml                       | 1 -
 context/skills/audit/config.yaml                                | 1 -
 context/skills/events-audit/config.yaml                         | 1 -
 context/skills/integration/config.yaml                          | 1 -
 context/skills/omnibus/instrument-integration/config.yaml       | 1 -
 context/skills/omnibus/instrument-product-analytics/config.yaml | 1 -
 context/skills/posthog-best-practices/config.yaml               | 1 -
 context/skills/revenue-analytics/config.yaml                    | 1 -
 8 files changed, 8 deletions(-)

diff --git a/context/skills/audit-identify/config.yaml b/context/skills/audit-identify/config.yaml
index df4bcfd3..66c30f9d 100644
--- a/context/skills/audit-identify/config.yaml
+++ b/context/skills/audit-identify/config.yaml
@@ -10,7 +10,6 @@ references:
   preamble: "**Read ONLY this file.** Do not read any other reference file until this one tells you to."
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
-  - https://posthog.com/docs/product-analytics/identity-resolution.md
   - https://posthog.com/docs/product-analytics/cutting-costs.md
   - https://posthog.com/docs/libraries/js/config.md
 variants:
diff --git a/context/skills/audit/config.yaml b/context/skills/audit/config.yaml
index d378b9a9..45a7cb42 100644
--- a/context/skills/audit/config.yaml
+++ b/context/skills/audit/config.yaml
@@ -11,7 +11,6 @@ references:
   preamble: "**Read ONLY this file.** Do not read any other reference file until this one tells you to."
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
-  - https://posthog.com/docs/product-analytics/identity-resolution.md
   - https://posthog.com/docs/product-analytics/best-practices.md
 variants:
   - id: all
diff --git a/context/skills/events-audit/config.yaml b/context/skills/events-audit/config.yaml
index b8c494ca..e0a90291 100644
--- a/context/skills/events-audit/config.yaml
+++ b/context/skills/events-audit/config.yaml
@@ -7,7 +7,6 @@ references:
 shared_docs:
   - https://posthog.com/docs/product-analytics/best-practices.md
   - https://posthog.com/docs/getting-started/identify-users.md
-  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: all
     display_name: PostHog events audit
diff --git a/context/skills/integration/config.yaml b/context/skills/integration/config.yaml
index 932c4573..2fbc119d 100644
--- a/context/skills/integration/config.yaml
+++ b/context/skills/integration/config.yaml
@@ -4,7 +4,6 @@ template: description.md
 description: PostHog integration for {display_name} applications
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
-  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: nextjs-app-router
     example_paths: example-apps/next-app-router
diff --git a/context/skills/omnibus/instrument-integration/config.yaml b/context/skills/omnibus/instrument-integration/config.yaml
index 288cc811..b2d1ce82 100644
--- a/context/skills/omnibus/instrument-integration/config.yaml
+++ b/context/skills/omnibus/instrument-integration/config.yaml
@@ -5,7 +5,6 @@ description: Add PostHog SDK integration to your application. Use when setting u
 tags: []
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
-  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: all
     display_name: all supported frameworks
diff --git a/context/skills/omnibus/instrument-product-analytics/config.yaml b/context/skills/omnibus/instrument-product-analytics/config.yaml
index f46ce0bb..a998e9ce 100644
--- a/context/skills/omnibus/instrument-product-analytics/config.yaml
+++ b/context/skills/omnibus/instrument-product-analytics/config.yaml
@@ -6,7 +6,6 @@ description: Add PostHog product analytics events to track user behavior. Use af
 tags: []
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
-  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: all
     display_name: all supported frameworks
diff --git a/context/skills/posthog-best-practices/config.yaml b/context/skills/posthog-best-practices/config.yaml
index 3d8e4ba3..4fe8fa58 100644
--- a/context/skills/posthog-best-practices/config.yaml
+++ b/context/skills/posthog-best-practices/config.yaml
@@ -4,7 +4,6 @@ description: Framework-agnostic, distilled best practices for using PostHog
 tags: [best-practices]
 shared_docs:
   - https://posthog.com/docs/getting-started/identify-users.md
-  - https://posthog.com/docs/product-analytics/identity-resolution.md
   - https://posthog.com/docs/new-to-posthog/understand-posthog.md
   - https://posthog.com/docs/privacy/data-collection.md
   - https://posthog.com/docs/advanced/proxy.md
diff --git a/context/skills/revenue-analytics/config.yaml b/context/skills/revenue-analytics/config.yaml
index fd041804..1a595620 100644
--- a/context/skills/revenue-analytics/config.yaml
+++ b/context/skills/revenue-analytics/config.yaml
@@ -9,7 +9,6 @@ cli:
 shared_docs:
   - https://posthog.com/docs/revenue-analytics/connect-to-customers.md
   - https://posthog.com/docs/getting-started/identify-users.md
-  - https://posthog.com/docs/product-analytics/identity-resolution.md
 variants:
   - id: setup
     display_name: Stripe Revenue Analytics

From 1744e83ac5fdc15bb676f4f35e702d83bbc03a1c Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Thu, 18 Jun 2026 09:24:40 -0400
Subject: [PATCH 15/17] refactor: nest orchestrator step-skills under
 basic-integration/, drop stray file

- move the 8 per-task step skills (build, capture, dashboard,
  error-tracking-step, identify, init, install, report) under
  skills/basic-integration/ so they stop polluting the top-level skills
  namespace; IDs become basic-integration-<step> (path-based, like omnibus-*)
- update the agent prompts skills: refs to the new IDs
- delete the stray orchestrator-ci-plan.md committed by accident

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 context/agents/build.md                       |   2 +-
 context/agents/capture.md                     |   2 +-
 context/agents/dashboard.md                   |   2 +-
 context/agents/error-tracking.md              |   2 +-
 context/agents/identify.md                    |   2 +-
 context/agents/init.md                        |   2 +-
 context/agents/install.md                     |   2 +-
 context/agents/report.md                      |   2 +-
 .../{ => basic-integration}/build/config.yaml |   0
 .../build/description.md                      |   0
 .../capture/config.yaml                       |   0
 .../capture/description.md                    |   0
 .../dashboard/config.yaml                     |   0
 .../dashboard/description.md                  |   0
 .../error-tracking-step/config.yaml           |   0
 .../error-tracking-step/description.md        |   0
 .../identify/config.yaml                      |   0
 .../identify/description.md                   |   0
 .../{ => basic-integration}/init/config.yaml  |   0
 .../init/description.md                       |   0
 .../install/config.yaml                       |   0
 .../install/description.md                    |   0
 .../report/config.yaml                        |   0
 .../report/description.md                     |   0
 orchestrator-ci-plan.md                       | 210 ------------------
 25 files changed, 8 insertions(+), 218 deletions(-)
 rename context/skills/{ => basic-integration}/build/config.yaml (100%)
 rename context/skills/{ => basic-integration}/build/description.md (100%)
 rename context/skills/{ => basic-integration}/capture/config.yaml (100%)
 rename context/skills/{ => basic-integration}/capture/description.md (100%)
 rename context/skills/{ => basic-integration}/dashboard/config.yaml (100%)
 rename context/skills/{ => basic-integration}/dashboard/description.md (100%)
 rename context/skills/{ => basic-integration}/error-tracking-step/config.yaml (100%)
 rename context/skills/{ => basic-integration}/error-tracking-step/description.md (100%)
 rename context/skills/{ => basic-integration}/identify/config.yaml (100%)
 rename context/skills/{ => basic-integration}/identify/description.md (100%)
 rename context/skills/{ => basic-integration}/init/config.yaml (100%)
 rename context/skills/{ => basic-integration}/init/description.md (100%)
 rename context/skills/{ => basic-integration}/install/config.yaml (100%)
 rename context/skills/{ => basic-integration}/install/description.md (100%)
 rename context/skills/{ => basic-integration}/report/config.yaml (100%)
 rename context/skills/{ => basic-integration}/report/description.md (100%)
 delete mode 100644 orchestrator-ci-plan.md

diff --git a/context/agents/build.md b/context/agents/build.md
index e4c97add..77243bab 100644
--- a/context/agents/build.md
+++ b/context/agents/build.md
@@ -3,7 +3,7 @@ type: build
 flow: posthog-integration
 label: Install dependencies and build
 model: claude-sonnet-4-6
-skills: [build]
+skills: [basic-integration-build]
 allowedTools: [Read, Edit, Glob, Grep, Bash]
 disallowedTools: [enqueue_task]
 dependsOn: [install, init, identify, error-tracking, capture]
diff --git a/context/agents/capture.md b/context/agents/capture.md
index 08b0cfcf..c2501897 100644
--- a/context/agents/capture.md
+++ b/context/agents/capture.md
@@ -3,7 +3,7 @@ type: capture
 flow: posthog-integration
 label: Capture events
 model: claude-sonnet-4-6
-skills: [capture]
+skills: [basic-integration-capture]
 allowedTools: [Read, Edit, Glob, Grep]
 disallowedTools: [enqueue_task]
 dependsOn: [install, init]
diff --git a/context/agents/dashboard.md b/context/agents/dashboard.md
index 7dcb0745..54c336de 100644
--- a/context/agents/dashboard.md
+++ b/context/agents/dashboard.md
@@ -3,7 +3,7 @@ type: dashboard
 flow: posthog-integration
 label: Create a starter dashboard
 model: claude-sonnet-4-6
-skills: [dashboard]
+skills: [basic-integration-dashboard]
 allowedTools: [Read, Glob, Grep]
 disallowedTools: [Write, Edit, Bash, enqueue_task]
 dependsOn: [build]
diff --git a/context/agents/error-tracking.md b/context/agents/error-tracking.md
index c3489c07..c7e2aea3 100644
--- a/context/agents/error-tracking.md
+++ b/context/agents/error-tracking.md
@@ -3,7 +3,7 @@ type: error-tracking
 flow: posthog-integration
 label: Add error tracking
 model: claude-sonnet-4-6
-skills: [error-tracking-step]
+skills: [basic-integration-error-tracking-step]
 allowedTools: [Read, Write, Edit, Glob, Grep]
 disallowedTools: [enqueue_task]
 dependsOn: [install, init]
diff --git a/context/agents/identify.md b/context/agents/identify.md
index 70f8ecad..658afca9 100644
--- a/context/agents/identify.md
+++ b/context/agents/identify.md
@@ -3,7 +3,7 @@ type: identify
 flow: posthog-integration
 label: Wire user identification
 model: claude-sonnet-4-6
-skills: [identify]
+skills: [basic-integration-identify]
 allowedTools: [Read, Edit, Glob, Grep]
 disallowedTools: [enqueue_task]
 dependsOn: [install, init]
diff --git a/context/agents/init.md b/context/agents/init.md
index 052b87fc..ffc62c2d 100644
--- a/context/agents/init.md
+++ b/context/agents/init.md
@@ -3,7 +3,7 @@ type: init
 flow: posthog-integration
 label: Set up PostHog initialization
 model: claude-haiku-4-5-20251001
-skills: [init]
+skills: [basic-integration-init]
 allowedTools: [Read, Write, Edit, Glob, Grep]
 disallowedTools: [enqueue_task]
 dependsOn: []
diff --git a/context/agents/install.md b/context/agents/install.md
index e11fa69d..4ed83e18 100644
--- a/context/agents/install.md
+++ b/context/agents/install.md
@@ -3,7 +3,7 @@ type: install
 flow: posthog-integration
 label: Add the PostHog SDK to the manifest
 model: claude-haiku-4-5-20251001
-skills: [install]
+skills: [basic-integration-install]
 allowedTools: [Read, Edit, Glob, Grep]
 disallowedTools: [enqueue_task]
 dependsOn: []
diff --git a/context/agents/report.md b/context/agents/report.md
index ed0c6747..1e7f126e 100644
--- a/context/agents/report.md
+++ b/context/agents/report.md
@@ -3,7 +3,7 @@ type: report
 flow: posthog-integration
 label: Write the setup report
 model: claude-sonnet-4-6
-skills: [report]
+skills: [basic-integration-report]
 allowedTools: [Read, Write, Glob, Grep]
 disallowedTools: [enqueue_task]
 dependsOn: [dashboard]
diff --git a/context/skills/build/config.yaml b/context/skills/basic-integration/build/config.yaml
similarity index 100%
rename from context/skills/build/config.yaml
rename to context/skills/basic-integration/build/config.yaml
diff --git a/context/skills/build/description.md b/context/skills/basic-integration/build/description.md
similarity index 100%
rename from context/skills/build/description.md
rename to context/skills/basic-integration/build/description.md
diff --git a/context/skills/capture/config.yaml b/context/skills/basic-integration/capture/config.yaml
similarity index 100%
rename from context/skills/capture/config.yaml
rename to context/skills/basic-integration/capture/config.yaml
diff --git a/context/skills/capture/description.md b/context/skills/basic-integration/capture/description.md
similarity index 100%
rename from context/skills/capture/description.md
rename to context/skills/basic-integration/capture/description.md
diff --git a/context/skills/dashboard/config.yaml b/context/skills/basic-integration/dashboard/config.yaml
similarity index 100%
rename from context/skills/dashboard/config.yaml
rename to context/skills/basic-integration/dashboard/config.yaml
diff --git a/context/skills/dashboard/description.md b/context/skills/basic-integration/dashboard/description.md
similarity index 100%
rename from context/skills/dashboard/description.md
rename to context/skills/basic-integration/dashboard/description.md
diff --git a/context/skills/error-tracking-step/config.yaml b/context/skills/basic-integration/error-tracking-step/config.yaml
similarity index 100%
rename from context/skills/error-tracking-step/config.yaml
rename to context/skills/basic-integration/error-tracking-step/config.yaml
diff --git a/context/skills/error-tracking-step/description.md b/context/skills/basic-integration/error-tracking-step/description.md
similarity index 100%
rename from context/skills/error-tracking-step/description.md
rename to context/skills/basic-integration/error-tracking-step/description.md
diff --git a/context/skills/identify/config.yaml b/context/skills/basic-integration/identify/config.yaml
similarity index 100%
rename from context/skills/identify/config.yaml
rename to context/skills/basic-integration/identify/config.yaml
diff --git a/context/skills/identify/description.md b/context/skills/basic-integration/identify/description.md
similarity index 100%
rename from context/skills/identify/description.md
rename to context/skills/basic-integration/identify/description.md
diff --git a/context/skills/init/config.yaml b/context/skills/basic-integration/init/config.yaml
similarity index 100%
rename from context/skills/init/config.yaml
rename to context/skills/basic-integration/init/config.yaml
diff --git a/context/skills/init/description.md b/context/skills/basic-integration/init/description.md
similarity index 100%
rename from context/skills/init/description.md
rename to context/skills/basic-integration/init/description.md
diff --git a/context/skills/install/config.yaml b/context/skills/basic-integration/install/config.yaml
similarity index 100%
rename from context/skills/install/config.yaml
rename to context/skills/basic-integration/install/config.yaml
diff --git a/context/skills/install/description.md b/context/skills/basic-integration/install/description.md
similarity index 100%
rename from context/skills/install/description.md
rename to context/skills/basic-integration/install/description.md
diff --git a/context/skills/report/config.yaml b/context/skills/basic-integration/report/config.yaml
similarity index 100%
rename from context/skills/report/config.yaml
rename to context/skills/basic-integration/report/config.yaml
diff --git a/context/skills/report/description.md b/context/skills/basic-integration/report/description.md
similarity index 100%
rename from context/skills/report/description.md
rename to context/skills/basic-integration/report/description.md
diff --git a/orchestrator-ci-plan.md b/orchestrator-ci-plan.md
deleted file mode 100644
index f33f2069..00000000
--- a/orchestrator-ci-plan.md
+++ /dev/null
@@ -1,210 +0,0 @@
-# Running the orchestrator end-to-end in CI
-
-## 1. How Wizard CI works
-
-The trigger lives in the wizard repo:
-`wizard-orchestrator/.github/workflows/wizard-ci-trigger.yml`
-
-A PR comment `/wizard-ci <app>` fires `handle-command`, which calls
-`POST /repos/PostHog/wizard-workbench/dispatches` with event type
-`wizard-ci-trigger` and a `client_payload` containing:
-
-```
-app, wizard_ref, context_mill_ref, notify_pr: true, source_pr_number, ...
-```
-
-The workbench workflow `wizard-workbench/.github/workflows/wizard-ci.yml` picks
-that up, clones and builds wizard + context-mill + MCP in `setup-wizard-deps`,
-starts both servers in the background, then runs:
-
-```bash
-pnpm wizard-ci --app "$MATRIX_APP" --base "$INPUT_BASE_BRANCH" [--trigger-id ...] [--evaluate]
-```
-
-Inside `wizard-ci` (`services/wizard-ci/index.ts`), `runWizard` spawns:
-
-```bash
-node dist/bin.js --local-mcp --ci --region us --api-key <key> --install-dir <app>
-```
-
-`--local-mcp` tells the wizard to use `http://localhost:8765` (context-mill dev
-server) instead of the GitHub releases URL for both skills and agent prompts.
-
-Auth: `POSTHOG_PERSONAL_API_KEY` is the CI bot's PostHog API key (secret
-`GH_APP_POSTHOG_WIZARD_CI_BOT_POSTHOG_PERSONAL_KEY`); the wizard uses it for
-`--api-key` and the MCP server gets it the same way.
-
----
-
-## 2. The flag-override path end-to-end
-
-**Step 1 — CI build.**
-`setup-wizard-deps/action.yml` (line ~101) runs `pnpm build:ci`, which inlines
-`NODE_ENV=ci` into the bundle. That is the guard inside
-`applyCiFlagOverrides` (`src/utils/ci-flag-overrides.ts` line 25):
-
-```ts
-if (process.env.NODE_ENV === 'production') return flags;
-```
-
-Published packages inline `"production"` and the function becomes a no-op.
-CI builds do not, so the function is live.
-
-**Step 2 — env var.**
-`applyCiFlagOverrides` reads `runtimeEnv('WIZARD_CI_FLAG_OVERRIDES')` at
-runtime (registered in `src/env.ts` line 45). It expects a JSON object:
-`{"flag-key": value, ...}`. A malformed value throws and kills the run.
-
-**Step 3 — flag eval.**
-`getAllFlagsForWizard` in `src/utils/analytics.ts` (line 211) fetches live
-flags from PostHog, then unconditionally calls `applyCiFlagOverrides` over
-the result (line 241) and caches the merged map. The override wins because it
-runs after the network fetch.
-
-**Step 4 — orchestrator gate.**
-`isOrchestratorEnabled` in `src/lib/agent/agent-interface.ts` (line 262)
-reads `flags['wizard-orchestrator'] === 'true'`. When the override is in the
-map, the orchestrator branch fires in `runProgram` regardless of what the live
-flag says.
-
-**Does the current CI workflow expose WIZARD_CI_FLAG_OVERRIDES?**
-
-No. Neither `wizard-ci.yml` nor `setup-wizard-deps/action.yml` pass
-`WIZARD_CI_FLAG_OVERRIDES` into the `Execute wizard` step. The env block of
-that step (`wizard-ci.yml` lines 634–650) does not mention it.
-
----
-
-## 3. What runs (and doesn't) in CI for the orchestrator
-
-**CI-excluded task types.**
-`ciExcludedTaskTypes()` (`src/utils/ci-flag-overrides.ts` line 56) reads
-`WIZARD_CI_EXCLUDE_TASKS` (a comma-separated list). The orchestrator runner
-(`src/lib/programs/orchestrator/orchestrator-runner.ts` line 93) passes
-`{ exclude: ciExcludedTaskTypes() }` to `loadAgentRegistry`. The registry
-then drops those types so the seed agent cannot enqueue them.
-
-PR #639 / commit `0a62554` in context-mill says "dashboard is not a CI task".
-The `dashboard.md` agent (`transformation-config/agents/dashboard.md`) has no
-`ci: false` frontmatter — the exclusion is entirely harness-side via
-`WIZARD_CI_EXCLUDE_TASKS=dashboard`. That env var also needs to be set by the
-CI workflow (currently missing from the `Execute wizard` env block).
-
-**Agent prompts — the AGENTS_BASE_URL gap.**
-`setup-wizard-deps/action.yml` runs `npm run build` for context-mill (line 158)
-without setting `AGENTS_BASE_URL`. Inside `scripts/lib/agent-generator.js`
-(line 41), `buildAgents` falls back to `DEFAULT_AGENTS_BASE_URL`:
-
-```
-https://github.com/PostHog/context-mill/releases/latest/download/agents
-```
-
-That URL points to production releases, not to the local dev server. When
-context-mill then starts (`npm run dev`) it regenerates `agent-menu.json` with
-`http://localhost:8765/agents/…` URLs. But the action only runs `npm run build`
-then exports `CONTEXT_MILL_PATH`. The dev server is started later in the
-`Run Wizard CI` step via `npm run dev &`. At that point the dev server sets
-`AGENTS_BASE_URL = http://localhost:8765/agents` internally (dev-server.js
-lines 65–66) and rebuilds, so the in-memory menu is correct.
-
-In practice `--local-mcp` makes the wizard call `http://localhost:8765/agent-menu.json`,
-which the running dev server serves with correct localhost URLs — so the agents
-are fetched correctly as long as `npm run dev` is running. The skill-menu has
-the same pattern. The memory note "must set BOTH SKILLS_BASE_URL + AGENTS_BASE_URL"
-applies to manual standalone `npm run build` invocations; CI is fine because it
-always goes through the dev server.
-
-**What actually runs.**
-All task types in `dist/agents/` are eligible except those in
-`WIZARD_CI_EXCLUDE_TASKS`. Currently that env var is never set in CI, so the
-seed agent would try to enqueue `dashboard` — which requires MCP write access to
-create a PostHog dashboard. Whether that succeeds depends on the CI bot's
-PostHog permissions, but it is undesirable for a fast CI loop.
-
----
-
-## 4. The gap: no way to pass flag overrides via a PR comment
-
-The trigger command `wizard-ci-trigger.yml` accepts only:
-
-```
-/wizard-ci <app-or-category>
-```
-
-It dispatches a fixed `client_payload` with no `flag_overrides` or
-`ci_flag_overrides` field. The workbench `wizard-ci.yml` `resolve-inputs` step
-does not read any such field from `client_payload`. There is no path from a PR
-comment to `WIZARD_CI_FLAG_OVERRIDES` in the execute-wizard env.
-
----
-
-## 5. Concrete recommendation
-
-### Option A — add flag-override plumbing (recommended, ~1 day)
-
-Two files need changes.
-
-**wizard-workbench/.github/workflows/wizard-ci.yml**
-
-1. Add `flag_overrides` to `workflow_dispatch` inputs (type: string, default: '').
-2. In `resolve-inputs`: read `CP_FLAG_OVERRIDES` / `INPUT_FLAG_OVERRIDES` and
-   emit `flag_overrides` output (same pattern as the other inputs).
-3. Pass it as `input_flag_overrides` through `discover` outputs.
-4. In the `Execute wizard` env block (line 634), add:
-   ```yaml
-   WIZARD_CI_FLAG_OVERRIDES: ${{ needs.discover.outputs.input_flag_overrides }}
-   WIZARD_CI_EXCLUDE_TASKS: dashboard
-   ```
-
-**wizard-orchestrator/.github/workflows/wizard-ci-trigger.yml**
-
-In `handle-command`, add `flag_overrides` to the `client_payload`:
-```js
-const overridesMatch = comment.match(/--flags\s+(\S+)/);
-flag_overrides: overridesMatch ? overridesMatch[1] : ''
-```
-
-This lets a PR comment like:
-```
-/wizard-ci basic-integration/next-js/15-app-router-saas --flags {"wizard-orchestrator":true}
-```
-route `WIZARD_CI_FLAG_OVERRIDES={"wizard-orchestrator":true}` into the wizard binary.
-
-### Option B — trigger via workflow_dispatch now (no code change needed)
-
-Go to `wizard-workbench` → Actions → "Wizard CI" → Run workflow, and set:
-- `app`: e.g. `basic-integration/next-js/15-app-router-saas`
-- `wizard_ref`: `experiment/orchestrator-run-cache`
-- `context_mill_ref`: `experiment/orchestrator`
-
-Then add `WIZARD_CI_FLAG_OVERRIDES` and `WIZARD_CI_EXCLUDE_TASKS` as manual
-additions to the env block — but since the current workflow has no `flag_overrides`
-input, you can't pass it this way without editing the yaml first.
-
-**Short-term workaround (no workflow edits):** add a temporary `env:` override
-directly in the `Execute wizard` step of `wizard-ci.yml` on a branch:
-
-```yaml
-WIZARD_CI_FLAG_OVERRIDES: '{"wizard-orchestrator":true}'
-WIZARD_CI_EXCLUDE_TASKS: dashboard
-```
-
-Then trigger CI via workflow_dispatch with `wizard_ref: experiment/orchestrator-run-cache`
-and `context_mill_ref: experiment/orchestrator`. That is a single-line change, safe
-to push to a short-lived branch of wizard-workbench without merging.
-
----
-
-## Summary of env vars needed in the Execute wizard step
-
-| Var | Value | Status |
-|-----|-------|--------|
-| `WIZARD_CI_FLAG_OVERRIDES` | `{"wizard-orchestrator":true}` | **missing** |
-| `WIZARD_CI_EXCLUDE_TASKS` | `dashboard` | **missing** |
-| `POSTHOG_PERSONAL_API_KEY` | bot secret | already wired |
-| `WIZARD_PATH` | `~/wizard` | already wired |
-| `CONTEXT_MILL_PATH` | `~/context-mill` | already wired |
-| `MCP_PATH` | `~/posthog/services/mcp` | already wired |
-
-The two missing vars are the only change needed to make the orchestrator path
-run end-to-end in CI.

From a16ed9b3939fe75164eb4846a2f840dbc23ed402 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Thu, 18 Jun 2026 11:30:07 -0400
Subject: [PATCH 16/17] fix(orchestrator): keep basic-integration step-skills
 goal-oriented
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The step-skills baked JS/Node specifics into every framework's run. Strip the
JS-pinned docs_urls from the install, init, capture, and error-tracking configs,
and de-hardcode the identify and capture prose, so SDK specifics come from the
per-framework reference, not the step. lower_snake_case and the correlation
header names stay — stable conventions, not framework specifics.

Recover the universal monolith guidance the steps were missing: the analytics
contract and scan-first in capture, error capture at natural boundaries, and a
before-you-merge checklist in the report.

Move the event plan to .posthog-wizard-cache/.posthog-events.json so it is run
scaffolding, cleaned up with the rest, not left in the project.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 context/agents/capture.md                     |  4 +--
 context/agents/report.md                      |  3 +-
 .../basic-integration/capture/config.yaml     |  3 +-
 .../basic-integration/capture/description.md  | 34 +++++++++++--------
 .../error-tracking-step/config.yaml           |  3 --
 .../error-tracking-step/description.md        | 10 +++---
 .../basic-integration/identify/description.md | 14 +++++---
 .../skills/basic-integration/init/config.yaml |  3 --
 .../basic-integration/init/description.md     |  4 ---
 .../basic-integration/install/config.yaml     |  3 --
 .../basic-integration/install/description.md  |  4 ---
 .../basic-integration/report/description.md   | 14 ++++++--
 12 files changed, 52 insertions(+), 47 deletions(-)

diff --git a/context/agents/capture.md b/context/agents/capture.md
index c2501897..db5a77c4 100644
--- a/context/agents/capture.md
+++ b/context/agents/capture.md
@@ -18,5 +18,5 @@ while the file is already open.
 ## How you know you succeeded
 
 The meaningful user actions across the app have capture calls that fire on the
-real action, not on page load, and `.posthog-events.json` lists the events you
-instrumented.
+real action, not on page load, and `.posthog-wizard-cache/.posthog-events.json`
+lists the events you instrumented.
diff --git a/context/agents/report.md b/context/agents/report.md
index 1e7f126e..d9db8a69 100644
--- a/context/agents/report.md
+++ b/context/agents/report.md
@@ -12,7 +12,8 @@ dependsOn: [dashboard]
 ## Goal
 
 Write the setup report summarizing what this integration did, drawing only on the
-run's queue log (`.posthog-wizard-cache/`) and the local `.posthog-events.json`.
+run's queue log and event plan in `.posthog-wizard-cache/` (`queue.json` and
+`.posthog-events.json`).
 
 ## How you know you succeeded
 
diff --git a/context/skills/basic-integration/capture/config.yaml b/context/skills/basic-integration/capture/config.yaml
index 8f973906..98e99d55 100644
--- a/context/skills/basic-integration/capture/config.yaml
+++ b/context/skills/basic-integration/capture/config.yaml
@@ -1,11 +1,10 @@
 type: docs-only
 template: description.md
-description: Instrument the planned events with posthog.capture
+description: Instrument the planned events with PostHog capture calls
 tags: [orchestrator, capture]
 variants:
   - id: all
     display_name: PostHog capture step
     tags: [orchestrator, capture]
     docs_urls:
-      - https://posthog.com/docs/libraries/js.md
       - https://posthog.com/docs/product-analytics/best-practices.md
diff --git a/context/skills/basic-integration/capture/description.md b/context/skills/basic-integration/capture/description.md
index 67a394d4..b0a7d1b7 100644
--- a/context/skills/basic-integration/capture/description.md
+++ b/context/skills/basic-integration/capture/description.md
@@ -7,29 +7,35 @@ pass, reading each file once.
 
 From the project's files, select between 10 and 15 that might have business value
 for event tracking — especially conversion and churn events. Read them. Track
-actions, not pageviews (autocapture covers those). Don't duplicate events that
-already exist. Server-side events are required if there is instrumentable
-server-side code (API routes, server actions): payment/checkout completion,
-webhook handlers, and auth endpoints.
-
-Write the chosen events to `.posthog-events.json` at the project root — a JSON
-array of `{ event, description, file }`, one entry per event. Write it before you
-start editing: it drives the event-plan view, and it is the source the report
-reads later.
+actions, not pageviews (autocapture covers those). Server-side events are required
+if there is instrumentable server-side code (API routes, server actions):
+payment/checkout completion, webhook handlers, and auth endpoints.
+
+First scan for capture calls the project already makes, and note how their event
+names are formatted. Event names, property names, and feature flag keys are an
+analytics contract: reuse the existing names and follow the patterns already in
+the project rather than inventing parallel ones, and don't duplicate events that
+already exist.
+
+Write the chosen events to `.posthog-wizard-cache/.posthog-events.json` — a JSON
+array of `{ event, description, file }`, one entry per event. That cache directory
+is the wizard's, already created for the run; write the plan there, not at the
+project root. Write it before you start editing: it drives the event-plan view,
+and it is the source the report reads later.
 
 ## Instrument
 
-For each event add `posthog.capture('event_name', { ...props })` on the real user
-action — the click or submit handler, the server action — not on render or page
-load. Use clear `lower_snake_case` names and useful properties. Edit each file
-while it is already open.
+For each event call the SDK's capture method on the real user action — the click
+or submit handler, the server action — not on render or page load. Use clear
+`lower_snake_case` names and useful properties. Edit each file while it is already
+open.
 
 Server-side, use the authenticated user's id as the distinct id. For a genuinely
 unauthenticated action, emit a personless event — never fabricate a placeholder
 id like `'anonymous'`, which collapses every anonymous user into one person and
 corrupts the data.
 
-Leave `.posthog-events.json` in place for the report.
+Leave `.posthog-wizard-cache/.posthog-events.json` in place for the report.
 
 ## Reference
 
diff --git a/context/skills/basic-integration/error-tracking-step/config.yaml b/context/skills/basic-integration/error-tracking-step/config.yaml
index ec9aea97..0d050f96 100644
--- a/context/skills/basic-integration/error-tracking-step/config.yaml
+++ b/context/skills/basic-integration/error-tracking-step/config.yaml
@@ -6,6 +6,3 @@ variants:
   - id: all
     display_name: PostHog error-tracking step
     tags: [orchestrator, error-tracking]
-    docs_urls:
-      - https://posthog.com/docs/error-tracking/installation/web.md
-      - https://posthog.com/docs/error-tracking/installation/node.md
diff --git a/context/skills/basic-integration/error-tracking-step/description.md b/context/skills/basic-integration/error-tracking-step/description.md
index 2670a024..b2b5b91f 100644
--- a/context/skills/basic-integration/error-tracking-step/description.md
+++ b/context/skills/basic-integration/error-tracking-step/description.md
@@ -5,9 +5,9 @@ reach PostHog — one handler, not hand-wrapped across files.
 
 Follow the framework's own mechanism for a global error handler, using the
 reference example and the docs for the exact pattern. Find the init or app entry,
-add the handler there, and you are done. One handler is enough — do not read
-through the whole app or wrap individual components or routes by hand.
+add the handler there. Do not read through the whole app or wrap individual
+components or routes by hand.
 
-## Reference
-
-{references}
+If the app already has natural exception boundaries — a server-side API error
+handler, a critical flow with its own try/catch — capturing there too is worth a
+single edit. The global handler is the floor, not the only place errors matter.
diff --git a/context/skills/basic-integration/identify/description.md b/context/skills/basic-integration/identify/description.md
index 8b4240c2..c5a002bc 100644
--- a/context/skills/basic-integration/identify/description.md
+++ b/context/skills/basic-integration/identify/description.md
@@ -1,16 +1,22 @@
 # Identify users
 
-Call `posthog.identify` at the moment the app learns who the user is — typically
-on login and signup success.
+Call the SDK's identify method at the moment the app learns who the user is —
+typically on login and signup success.
 
 - Use a stable unique id as the distinct id (the user id from your auth), not an
   email or display name.
-- Pass useful person properties (email, name, plan) as the second argument.
-- Call `posthog.reset()` on logout so the next user starts clean.
+- Attach useful person properties (email, name, plan).
+- Reset the session on logout, where the SDK supports it, so the next user starts
+  clean.
 
 Find the auth flow first: login and signup handlers, session callbacks. If the
 app has no concept of a user, there is nothing to identify — report that and stop.
 
+If the app has both a client and a server, keep them on the same person: forward
+the client's distinct id and session id to the backend (the
+`X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` request headers are the usual
+carrier) so server-side events stitch to the same user rather than splitting off.
+
 ## Reference
 
 {references}
diff --git a/context/skills/basic-integration/init/config.yaml b/context/skills/basic-integration/init/config.yaml
index 0317ac8e..2100b785 100644
--- a/context/skills/basic-integration/init/config.yaml
+++ b/context/skills/basic-integration/init/config.yaml
@@ -6,6 +6,3 @@ variants:
   - id: all
     display_name: PostHog init step
     tags: [orchestrator, init]
-    docs_urls:
-      - https://posthog.com/docs/libraries/js.md
-      - https://posthog.com/docs/libraries/node.md
diff --git a/context/skills/basic-integration/init/description.md b/context/skills/basic-integration/init/description.md
index 2440423e..b550d169 100644
--- a/context/skills/basic-integration/init/description.md
+++ b/context/skills/basic-integration/init/description.md
@@ -16,7 +16,3 @@ Create the framework's single initialization point that runs once on the client,
 following the reference example and the docs for the right pattern. Read the
 existing provider or entry file before editing, and add PostHog alongside what is
 already there rather than replacing it.
-
-## Reference
-
-{references}
diff --git a/context/skills/basic-integration/install/config.yaml b/context/skills/basic-integration/install/config.yaml
index a442772b..0bb3fd1d 100644
--- a/context/skills/basic-integration/install/config.yaml
+++ b/context/skills/basic-integration/install/config.yaml
@@ -6,6 +6,3 @@ variants:
   - id: all
     display_name: PostHog install step
     tags: [orchestrator, install]
-    docs_urls:
-      - https://posthog.com/docs/libraries/js.md
-      - https://posthog.com/docs/libraries/node.md
diff --git a/context/skills/basic-integration/install/description.md b/context/skills/basic-integration/install/description.md
index f914b263..cb6bdb9b 100644
--- a/context/skills/basic-integration/install/description.md
+++ b/context/skills/basic-integration/install/description.md
@@ -12,7 +12,3 @@ range, and match the style of the dependencies already in the manifest.
 
 Read the manifest first. If the dependency is already declared, leave it as is and
 say so. Edit only the manifest — no lockfile, no install command.
-
-## Reference
-
-{references}
diff --git a/context/skills/basic-integration/report/description.md b/context/skills/basic-integration/report/description.md
index 4cc554ed..186303d7 100644
--- a/context/skills/basic-integration/report/description.md
+++ b/context/skills/basic-integration/report/description.md
@@ -6,18 +6,28 @@ Draw on two sources only:
 - the run's queue log — `.posthog-wizard-cache/queue.json`, which holds each
   task's handoff inline — for what each step did, whether identify was wired
   or skipped, and any build conflict;
-- `.posthog-events.json` — the events that were instrumented.
+- `.posthog-wizard-cache/.posthog-events.json` — the events that were instrumented.
 
 Include:
 
 - A one-line summary of what was set up.
 - What was installed and how PostHog was initialized.
 - The events instrumented, as a table: event name, what it measures, and the file
-  (from `.posthog-events.json`).
+  (from `.posthog-wizard-cache/.posthog-events.json`).
 - Whether user identification was wired or skipped, and why.
 - The error tracking added.
 - The dashboard link.
 - Any build conflict, in full.
 - Clear next steps for the user.
 
+End with a short "Before you merge" checklist, including only the items that
+apply to what was set up:
+
+- If the app ships minified browser bundles, source maps must be uploaded so
+  error stack traces are readable — call it out with the docs link.
+- The new env vars (the project token and host) are documented for other
+  developers and set in the deploy environments, not just locally.
+- Returning users are identified on load, not only at the login moment, so a
+  returning user's events do not fragment across anonymous and identified.
+
 Keep it skimmable. This is the artifact the user opens after the run.

From 4d4a682cd51f53a2da9568058557c577799c4cd5 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <gewenyu99@gmail.com>
Date: Thu, 18 Jun 2026 13:51:48 -0400
Subject: [PATCH 17/17] feat(orchestrator): per-framework variants for the
 SDK-divergent step-skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Install, init, capture, and error-tracking each carry framework-specific work,
so mirror the integration skill's 36 variants onto them: each variant packages
that framework's docs page (duplicated across steps for now). The step prose
stays generic; the variant supplies the framework HOW. Generic steps (identify,
report, dashboard, build) stay single-variant.

Reverses the docs_urls strip from the previous commit — the per-framework pages
return as variants rather than inline JS-only docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../basic-integration/capture/config.yaml     | 383 +++++++++++++++++-
 .../error-tracking-step/config.yaml           | 381 ++++++++++++++++-
 .../error-tracking-step/description.md        |   4 +
 .../skills/basic-integration/init/config.yaml | 381 ++++++++++++++++-
 .../basic-integration/init/description.md     |   4 +
 .../basic-integration/install/config.yaml     | 381 ++++++++++++++++-
 .../basic-integration/install/description.md  |   4 +
 7 files changed, 1521 insertions(+), 17 deletions(-)

diff --git a/context/skills/basic-integration/capture/config.yaml b/context/skills/basic-integration/capture/config.yaml
index 98e99d55..618bc884 100644
--- a/context/skills/basic-integration/capture/config.yaml
+++ b/context/skills/basic-integration/capture/config.yaml
@@ -1,10 +1,383 @@
 type: docs-only
 template: description.md
 description: Instrument the planned events with PostHog capture calls
-tags: [orchestrator, capture]
+tags:
+  - orchestrator
+  - capture
+shared_docs:
+  - https://posthog.com/docs/product-analytics/best-practices.md
 variants:
-  - id: all
-    display_name: PostHog capture step
-    tags: [orchestrator, capture]
+  - id: nextjs-app-router
+    display_name: Next.js App Router
+    tags:
+      - orchestrator
+      - capture
+      - nextjs
+      - react
+      - ssr
+      - app-router
+      - javascript
     docs_urls:
-      - https://posthog.com/docs/product-analytics/best-practices.md
+      - https://posthog.com/docs/libraries/next-js.md
+  - id: nextjs-pages-router
+    display_name: Next.js Pages Router
+    tags:
+      - orchestrator
+      - capture
+      - nextjs
+      - react
+      - ssr
+      - pages-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/next-js.md
+  - id: react-react-router-6
+    display_name: React Router v6
+    tags:
+      - orchestrator
+      - capture
+      - react
+      - react-router
+      - v6
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v6.md
+  - id: react-react-router-7-framework
+    display_name: React Router v7 - Framework mode
+    tags:
+      - orchestrator
+      - capture
+      - react
+      - react-router
+      - v7
+      - framework
+      - ssr
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-framework-mode.md
+  - id: react-react-router-7-data
+    display_name: React Router v7 - Data mode
+    tags:
+      - orchestrator
+      - capture
+      - react
+      - react-router
+      - v7
+      - data
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-data-mode.md
+  - id: react-react-router-7-declarative
+    display_name: React Router v7 - Declarative mode
+    tags:
+      - orchestrator
+      - capture
+      - react
+      - react-router
+      - v7
+      - declarative
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-declarative-mode.md
+  - id: react-vite
+    display_name: React (Vite)
+    tags:
+      - orchestrator
+      - capture
+      - react
+      - vite
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react.md
+  - id: nuxt-3-6
+    display_name: Nuxt 3.6
+    tags:
+      - orchestrator
+      - capture
+      - nuxt
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/nuxt-js-3-6.md
+  - id: nuxt-4
+    display_name: Nuxt 4
+    tags:
+      - orchestrator
+      - capture
+      - nuxt
+      - vue
+      - ssr
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/nuxt-js.md
+  - id: vue-3
+    display_name: Vue 3
+    tags:
+      - orchestrator
+      - capture
+      - vue
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/vue-js.md
+  - id: django
+    display_name: Django
+    tags:
+      - orchestrator
+      - capture
+      - django
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/django.md
+  - id: flask
+    display_name: Flask
+    tags:
+      - orchestrator
+      - capture
+      - flask
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/flask.md
+  - id: fastapi
+    display_name: FastAPI
+    tags:
+      - orchestrator
+      - capture
+      - fastapi
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/python.md
+  - id: react-tanstack-router-file-based
+    display_name: React with TanStack Router (file-based)
+    tags:
+      - orchestrator
+      - capture
+      - react
+      - tanstack-router
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: react-tanstack-router-code-based
+    display_name: React with TanStack Router (code-based)
+    tags:
+      - orchestrator
+      - capture
+      - react
+      - tanstack-router
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: tanstack-start
+    display_name: TanStack Start
+    tags:
+      - orchestrator
+      - capture
+      - react
+      - tanstack-start
+      - tanstack-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: laravel
+    display_name: Laravel
+    tags:
+      - orchestrator
+      - capture
+      - laravel
+      - php
+    docs_urls:
+      - https://posthog.com/docs/libraries/laravel.md
+  - id: php
+    display_name: PHP
+    tags:
+      - orchestrator
+      - capture
+      - php
+    docs_urls:
+      - https://posthog.com/docs/libraries/php.md
+  - id: ruby-on-rails
+    display_name: Ruby on Rails
+    tags:
+      - orchestrator
+      - capture
+      - ruby-on-rails
+      - ruby
+    docs_urls:
+      - https://posthog.com/docs/libraries/ruby-on-rails.md
+      - https://posthog.com/docs/libraries/ruby.md
+  - id: android
+    display_name: Android
+    tags:
+      - orchestrator
+      - capture
+      - android
+      - java
+      - kotlin
+    docs_urls:
+      - https://posthog.com/docs/libraries/android.md
+  - id: sveltekit
+    display_name: SvelteKit
+    tags:
+      - orchestrator
+      - capture
+      - sveltekit
+      - svelte
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/svelte.md
+  - id: python
+    display_name: Python
+    tags:
+      - orchestrator
+      - capture
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/python.md
+      - https://posthog.com/docs/references/posthog-python.md
+  - id: javascript_node
+    display_name: JavaScript Node
+    tags:
+      - orchestrator
+      - capture
+      - javascript_node
+    docs_urls:
+      - https://posthog.com/docs/libraries/node.md
+      - https://posthog.com/docs/references/posthog-node.md
+  - id: javascript_web
+    display_name: JavaScript Web
+    tags:
+      - orchestrator
+      - capture
+      - javascript_web
+    docs_urls:
+      - https://posthog.com/docs/libraries/js.md
+      - https://posthog.com/docs/references/posthog-js.md
+  - id: ruby
+    display_name: Ruby
+    tags:
+      - orchestrator
+      - capture
+      - ruby
+    docs_urls:
+      - https://posthog.com/docs/libraries/ruby.md
+  - id: elixir
+    display_name: Elixir
+    tags:
+      - orchestrator
+      - capture
+      - elixir
+      - phoenix
+      - plug
+    docs_urls:
+      - https://posthog.com/docs/libraries/elixir.md
+  - id: go
+    display_name: Go
+    tags:
+      - orchestrator
+      - capture
+      - go
+    docs_urls:
+      - https://posthog.com/docs/libraries/go.md
+  - id: swift
+    display_name: Swift (iOS/macOS)
+    tags:
+      - orchestrator
+      - capture
+      - swift
+      - ios
+      - macos
+      - swiftui
+    docs_urls:
+      - https://posthog.com/docs/libraries/ios.md
+      - https://posthog.com/docs/libraries/ios/usage.md
+      - https://posthog.com/docs/libraries/ios/configuration.md
+  - id: flutter
+    display_name: Flutter
+    tags:
+      - orchestrator
+      - capture
+      - flutter
+      - dart
+      - mobile
+    docs_urls:
+      - https://posthog.com/docs/libraries/flutter.md
+  - id: react-native
+    display_name: React Native
+    tags:
+      - orchestrator
+      - capture
+      - react-native
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-native.md
+  - id: expo
+    display_name: Expo
+    tags:
+      - orchestrator
+      - capture
+      - expo
+      - react-native
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-native.md
+  - id: astro-static
+    display_name: Astro (Static)
+    tags:
+      - orchestrator
+      - capture
+      - astro
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-view-transitions
+    display_name: Astro (View Transitions)
+    tags:
+      - orchestrator
+      - capture
+      - astro
+      - astro-view-transitions
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-ssr
+    display_name: Astro (SSR)
+    tags:
+      - orchestrator
+      - capture
+      - astro
+      - astro-ssr
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-hybrid
+    display_name: Astro (Hybrid)
+    tags:
+      - orchestrator
+      - capture
+      - astro
+      - astro-hybrid
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: angular
+    display_name: Angular
+    tags:
+      - orchestrator
+      - capture
+      - angular
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/angular.md
diff --git a/context/skills/basic-integration/error-tracking-step/config.yaml b/context/skills/basic-integration/error-tracking-step/config.yaml
index 0d050f96..9cb1076e 100644
--- a/context/skills/basic-integration/error-tracking-step/config.yaml
+++ b/context/skills/basic-integration/error-tracking-step/config.yaml
@@ -1,8 +1,381 @@
 type: docs-only
 template: description.md
 description: Capture exceptions with PostHog around critical flows
-tags: [orchestrator, error-tracking]
+tags:
+  - orchestrator
+  - error-tracking
 variants:
-  - id: all
-    display_name: PostHog error-tracking step
-    tags: [orchestrator, error-tracking]
+  - id: nextjs-app-router
+    display_name: Next.js App Router
+    tags:
+      - orchestrator
+      - error-tracking
+      - nextjs
+      - react
+      - ssr
+      - app-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/next-js.md
+  - id: nextjs-pages-router
+    display_name: Next.js Pages Router
+    tags:
+      - orchestrator
+      - error-tracking
+      - nextjs
+      - react
+      - ssr
+      - pages-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/next-js.md
+  - id: react-react-router-6
+    display_name: React Router v6
+    tags:
+      - orchestrator
+      - error-tracking
+      - react
+      - react-router
+      - v6
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v6.md
+  - id: react-react-router-7-framework
+    display_name: React Router v7 - Framework mode
+    tags:
+      - orchestrator
+      - error-tracking
+      - react
+      - react-router
+      - v7
+      - framework
+      - ssr
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-framework-mode.md
+  - id: react-react-router-7-data
+    display_name: React Router v7 - Data mode
+    tags:
+      - orchestrator
+      - error-tracking
+      - react
+      - react-router
+      - v7
+      - data
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-data-mode.md
+  - id: react-react-router-7-declarative
+    display_name: React Router v7 - Declarative mode
+    tags:
+      - orchestrator
+      - error-tracking
+      - react
+      - react-router
+      - v7
+      - declarative
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-declarative-mode.md
+  - id: react-vite
+    display_name: React (Vite)
+    tags:
+      - orchestrator
+      - error-tracking
+      - react
+      - vite
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react.md
+  - id: nuxt-3-6
+    display_name: Nuxt 3.6
+    tags:
+      - orchestrator
+      - error-tracking
+      - nuxt
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/nuxt-js-3-6.md
+  - id: nuxt-4
+    display_name: Nuxt 4
+    tags:
+      - orchestrator
+      - error-tracking
+      - nuxt
+      - vue
+      - ssr
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/nuxt-js.md
+  - id: vue-3
+    display_name: Vue 3
+    tags:
+      - orchestrator
+      - error-tracking
+      - vue
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/vue-js.md
+  - id: django
+    display_name: Django
+    tags:
+      - orchestrator
+      - error-tracking
+      - django
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/django.md
+  - id: flask
+    display_name: Flask
+    tags:
+      - orchestrator
+      - error-tracking
+      - flask
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/flask.md
+  - id: fastapi
+    display_name: FastAPI
+    tags:
+      - orchestrator
+      - error-tracking
+      - fastapi
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/python.md
+  - id: react-tanstack-router-file-based
+    display_name: React with TanStack Router (file-based)
+    tags:
+      - orchestrator
+      - error-tracking
+      - react
+      - tanstack-router
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: react-tanstack-router-code-based
+    display_name: React with TanStack Router (code-based)
+    tags:
+      - orchestrator
+      - error-tracking
+      - react
+      - tanstack-router
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: tanstack-start
+    display_name: TanStack Start
+    tags:
+      - orchestrator
+      - error-tracking
+      - react
+      - tanstack-start
+      - tanstack-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: laravel
+    display_name: Laravel
+    tags:
+      - orchestrator
+      - error-tracking
+      - laravel
+      - php
+    docs_urls:
+      - https://posthog.com/docs/libraries/laravel.md
+  - id: php
+    display_name: PHP
+    tags:
+      - orchestrator
+      - error-tracking
+      - php
+    docs_urls:
+      - https://posthog.com/docs/libraries/php.md
+  - id: ruby-on-rails
+    display_name: Ruby on Rails
+    tags:
+      - orchestrator
+      - error-tracking
+      - ruby-on-rails
+      - ruby
+    docs_urls:
+      - https://posthog.com/docs/libraries/ruby-on-rails.md
+      - https://posthog.com/docs/libraries/ruby.md
+  - id: android
+    display_name: Android
+    tags:
+      - orchestrator
+      - error-tracking
+      - android
+      - java
+      - kotlin
+    docs_urls:
+      - https://posthog.com/docs/libraries/android.md
+  - id: sveltekit
+    display_name: SvelteKit
+    tags:
+      - orchestrator
+      - error-tracking
+      - sveltekit
+      - svelte
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/svelte.md
+  - id: python
+    display_name: Python
+    tags:
+      - orchestrator
+      - error-tracking
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/python.md
+      - https://posthog.com/docs/references/posthog-python.md
+  - id: javascript_node
+    display_name: JavaScript Node
+    tags:
+      - orchestrator
+      - error-tracking
+      - javascript_node
+    docs_urls:
+      - https://posthog.com/docs/libraries/node.md
+      - https://posthog.com/docs/references/posthog-node.md
+  - id: javascript_web
+    display_name: JavaScript Web
+    tags:
+      - orchestrator
+      - error-tracking
+      - javascript_web
+    docs_urls:
+      - https://posthog.com/docs/libraries/js.md
+      - https://posthog.com/docs/references/posthog-js.md
+  - id: ruby
+    display_name: Ruby
+    tags:
+      - orchestrator
+      - error-tracking
+      - ruby
+    docs_urls:
+      - https://posthog.com/docs/libraries/ruby.md
+  - id: elixir
+    display_name: Elixir
+    tags:
+      - orchestrator
+      - error-tracking
+      - elixir
+      - phoenix
+      - plug
+    docs_urls:
+      - https://posthog.com/docs/libraries/elixir.md
+  - id: go
+    display_name: Go
+    tags:
+      - orchestrator
+      - error-tracking
+      - go
+    docs_urls:
+      - https://posthog.com/docs/libraries/go.md
+  - id: swift
+    display_name: Swift (iOS/macOS)
+    tags:
+      - orchestrator
+      - error-tracking
+      - swift
+      - ios
+      - macos
+      - swiftui
+    docs_urls:
+      - https://posthog.com/docs/libraries/ios.md
+      - https://posthog.com/docs/libraries/ios/usage.md
+      - https://posthog.com/docs/libraries/ios/configuration.md
+  - id: flutter
+    display_name: Flutter
+    tags:
+      - orchestrator
+      - error-tracking
+      - flutter
+      - dart
+      - mobile
+    docs_urls:
+      - https://posthog.com/docs/libraries/flutter.md
+  - id: react-native
+    display_name: React Native
+    tags:
+      - orchestrator
+      - error-tracking
+      - react-native
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-native.md
+  - id: expo
+    display_name: Expo
+    tags:
+      - orchestrator
+      - error-tracking
+      - expo
+      - react-native
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-native.md
+  - id: astro-static
+    display_name: Astro (Static)
+    tags:
+      - orchestrator
+      - error-tracking
+      - astro
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-view-transitions
+    display_name: Astro (View Transitions)
+    tags:
+      - orchestrator
+      - error-tracking
+      - astro
+      - astro-view-transitions
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-ssr
+    display_name: Astro (SSR)
+    tags:
+      - orchestrator
+      - error-tracking
+      - astro
+      - astro-ssr
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-hybrid
+    display_name: Astro (Hybrid)
+    tags:
+      - orchestrator
+      - error-tracking
+      - astro
+      - astro-hybrid
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: angular
+    display_name: Angular
+    tags:
+      - orchestrator
+      - error-tracking
+      - angular
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/angular.md
diff --git a/context/skills/basic-integration/error-tracking-step/description.md b/context/skills/basic-integration/error-tracking-step/description.md
index b2b5b91f..352bbea7 100644
--- a/context/skills/basic-integration/error-tracking-step/description.md
+++ b/context/skills/basic-integration/error-tracking-step/description.md
@@ -11,3 +11,7 @@ components or routes by hand.
 If the app already has natural exception boundaries — a server-side API error
 handler, a critical flow with its own try/catch — capturing there too is worth a
 single edit. The global handler is the floor, not the only place errors matter.
+
+## Reference
+
+{references}
diff --git a/context/skills/basic-integration/init/config.yaml b/context/skills/basic-integration/init/config.yaml
index 2100b785..f8683f88 100644
--- a/context/skills/basic-integration/init/config.yaml
+++ b/context/skills/basic-integration/init/config.yaml
@@ -1,8 +1,381 @@
 type: docs-only
 template: description.md
 description: Initialize PostHog and set its environment variables
-tags: [orchestrator, init]
+tags:
+  - orchestrator
+  - init
 variants:
-  - id: all
-    display_name: PostHog init step
-    tags: [orchestrator, init]
+  - id: nextjs-app-router
+    display_name: Next.js App Router
+    tags:
+      - orchestrator
+      - init
+      - nextjs
+      - react
+      - ssr
+      - app-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/next-js.md
+  - id: nextjs-pages-router
+    display_name: Next.js Pages Router
+    tags:
+      - orchestrator
+      - init
+      - nextjs
+      - react
+      - ssr
+      - pages-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/next-js.md
+  - id: react-react-router-6
+    display_name: React Router v6
+    tags:
+      - orchestrator
+      - init
+      - react
+      - react-router
+      - v6
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v6.md
+  - id: react-react-router-7-framework
+    display_name: React Router v7 - Framework mode
+    tags:
+      - orchestrator
+      - init
+      - react
+      - react-router
+      - v7
+      - framework
+      - ssr
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-framework-mode.md
+  - id: react-react-router-7-data
+    display_name: React Router v7 - Data mode
+    tags:
+      - orchestrator
+      - init
+      - react
+      - react-router
+      - v7
+      - data
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-data-mode.md
+  - id: react-react-router-7-declarative
+    display_name: React Router v7 - Declarative mode
+    tags:
+      - orchestrator
+      - init
+      - react
+      - react-router
+      - v7
+      - declarative
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-declarative-mode.md
+  - id: react-vite
+    display_name: React (Vite)
+    tags:
+      - orchestrator
+      - init
+      - react
+      - vite
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react.md
+  - id: nuxt-3-6
+    display_name: Nuxt 3.6
+    tags:
+      - orchestrator
+      - init
+      - nuxt
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/nuxt-js-3-6.md
+  - id: nuxt-4
+    display_name: Nuxt 4
+    tags:
+      - orchestrator
+      - init
+      - nuxt
+      - vue
+      - ssr
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/nuxt-js.md
+  - id: vue-3
+    display_name: Vue 3
+    tags:
+      - orchestrator
+      - init
+      - vue
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/vue-js.md
+  - id: django
+    display_name: Django
+    tags:
+      - orchestrator
+      - init
+      - django
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/django.md
+  - id: flask
+    display_name: Flask
+    tags:
+      - orchestrator
+      - init
+      - flask
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/flask.md
+  - id: fastapi
+    display_name: FastAPI
+    tags:
+      - orchestrator
+      - init
+      - fastapi
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/python.md
+  - id: react-tanstack-router-file-based
+    display_name: React with TanStack Router (file-based)
+    tags:
+      - orchestrator
+      - init
+      - react
+      - tanstack-router
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: react-tanstack-router-code-based
+    display_name: React with TanStack Router (code-based)
+    tags:
+      - orchestrator
+      - init
+      - react
+      - tanstack-router
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: tanstack-start
+    display_name: TanStack Start
+    tags:
+      - orchestrator
+      - init
+      - react
+      - tanstack-start
+      - tanstack-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: laravel
+    display_name: Laravel
+    tags:
+      - orchestrator
+      - init
+      - laravel
+      - php
+    docs_urls:
+      - https://posthog.com/docs/libraries/laravel.md
+  - id: php
+    display_name: PHP
+    tags:
+      - orchestrator
+      - init
+      - php
+    docs_urls:
+      - https://posthog.com/docs/libraries/php.md
+  - id: ruby-on-rails
+    display_name: Ruby on Rails
+    tags:
+      - orchestrator
+      - init
+      - ruby-on-rails
+      - ruby
+    docs_urls:
+      - https://posthog.com/docs/libraries/ruby-on-rails.md
+      - https://posthog.com/docs/libraries/ruby.md
+  - id: android
+    display_name: Android
+    tags:
+      - orchestrator
+      - init
+      - android
+      - java
+      - kotlin
+    docs_urls:
+      - https://posthog.com/docs/libraries/android.md
+  - id: sveltekit
+    display_name: SvelteKit
+    tags:
+      - orchestrator
+      - init
+      - sveltekit
+      - svelte
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/svelte.md
+  - id: python
+    display_name: Python
+    tags:
+      - orchestrator
+      - init
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/python.md
+      - https://posthog.com/docs/references/posthog-python.md
+  - id: javascript_node
+    display_name: JavaScript Node
+    tags:
+      - orchestrator
+      - init
+      - javascript_node
+    docs_urls:
+      - https://posthog.com/docs/libraries/node.md
+      - https://posthog.com/docs/references/posthog-node.md
+  - id: javascript_web
+    display_name: JavaScript Web
+    tags:
+      - orchestrator
+      - init
+      - javascript_web
+    docs_urls:
+      - https://posthog.com/docs/libraries/js.md
+      - https://posthog.com/docs/references/posthog-js.md
+  - id: ruby
+    display_name: Ruby
+    tags:
+      - orchestrator
+      - init
+      - ruby
+    docs_urls:
+      - https://posthog.com/docs/libraries/ruby.md
+  - id: elixir
+    display_name: Elixir
+    tags:
+      - orchestrator
+      - init
+      - elixir
+      - phoenix
+      - plug
+    docs_urls:
+      - https://posthog.com/docs/libraries/elixir.md
+  - id: go
+    display_name: Go
+    tags:
+      - orchestrator
+      - init
+      - go
+    docs_urls:
+      - https://posthog.com/docs/libraries/go.md
+  - id: swift
+    display_name: Swift (iOS/macOS)
+    tags:
+      - orchestrator
+      - init
+      - swift
+      - ios
+      - macos
+      - swiftui
+    docs_urls:
+      - https://posthog.com/docs/libraries/ios.md
+      - https://posthog.com/docs/libraries/ios/usage.md
+      - https://posthog.com/docs/libraries/ios/configuration.md
+  - id: flutter
+    display_name: Flutter
+    tags:
+      - orchestrator
+      - init
+      - flutter
+      - dart
+      - mobile
+    docs_urls:
+      - https://posthog.com/docs/libraries/flutter.md
+  - id: react-native
+    display_name: React Native
+    tags:
+      - orchestrator
+      - init
+      - react-native
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-native.md
+  - id: expo
+    display_name: Expo
+    tags:
+      - orchestrator
+      - init
+      - expo
+      - react-native
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-native.md
+  - id: astro-static
+    display_name: Astro (Static)
+    tags:
+      - orchestrator
+      - init
+      - astro
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-view-transitions
+    display_name: Astro (View Transitions)
+    tags:
+      - orchestrator
+      - init
+      - astro
+      - astro-view-transitions
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-ssr
+    display_name: Astro (SSR)
+    tags:
+      - orchestrator
+      - init
+      - astro
+      - astro-ssr
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-hybrid
+    display_name: Astro (Hybrid)
+    tags:
+      - orchestrator
+      - init
+      - astro
+      - astro-hybrid
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: angular
+    display_name: Angular
+    tags:
+      - orchestrator
+      - init
+      - angular
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/angular.md
diff --git a/context/skills/basic-integration/init/description.md b/context/skills/basic-integration/init/description.md
index b550d169..2440423e 100644
--- a/context/skills/basic-integration/init/description.md
+++ b/context/skills/basic-integration/init/description.md
@@ -16,3 +16,7 @@ Create the framework's single initialization point that runs once on the client,
 following the reference example and the docs for the right pattern. Read the
 existing provider or entry file before editing, and add PostHog alongside what is
 already there rather than replacing it.
+
+## Reference
+
+{references}
diff --git a/context/skills/basic-integration/install/config.yaml b/context/skills/basic-integration/install/config.yaml
index 0bb3fd1d..34c5a473 100644
--- a/context/skills/basic-integration/install/config.yaml
+++ b/context/skills/basic-integration/install/config.yaml
@@ -1,8 +1,381 @@
 type: docs-only
 template: description.md
 description: Install the PostHog SDK with the project's package manager
-tags: [orchestrator, install]
+tags:
+  - orchestrator
+  - install
 variants:
-  - id: all
-    display_name: PostHog install step
-    tags: [orchestrator, install]
+  - id: nextjs-app-router
+    display_name: Next.js App Router
+    tags:
+      - orchestrator
+      - install
+      - nextjs
+      - react
+      - ssr
+      - app-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/next-js.md
+  - id: nextjs-pages-router
+    display_name: Next.js Pages Router
+    tags:
+      - orchestrator
+      - install
+      - nextjs
+      - react
+      - ssr
+      - pages-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/next-js.md
+  - id: react-react-router-6
+    display_name: React Router v6
+    tags:
+      - orchestrator
+      - install
+      - react
+      - react-router
+      - v6
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v6.md
+  - id: react-react-router-7-framework
+    display_name: React Router v7 - Framework mode
+    tags:
+      - orchestrator
+      - install
+      - react
+      - react-router
+      - v7
+      - framework
+      - ssr
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-framework-mode.md
+  - id: react-react-router-7-data
+    display_name: React Router v7 - Data mode
+    tags:
+      - orchestrator
+      - install
+      - react
+      - react-router
+      - v7
+      - data
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-data-mode.md
+  - id: react-react-router-7-declarative
+    display_name: React Router v7 - Declarative mode
+    tags:
+      - orchestrator
+      - install
+      - react
+      - react-router
+      - v7
+      - declarative
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-router/react-router-v7-declarative-mode.md
+  - id: react-vite
+    display_name: React (Vite)
+    tags:
+      - orchestrator
+      - install
+      - react
+      - vite
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react.md
+  - id: nuxt-3-6
+    display_name: Nuxt 3.6
+    tags:
+      - orchestrator
+      - install
+      - nuxt
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/nuxt-js-3-6.md
+  - id: nuxt-4
+    display_name: Nuxt 4
+    tags:
+      - orchestrator
+      - install
+      - nuxt
+      - vue
+      - ssr
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/nuxt-js.md
+  - id: vue-3
+    display_name: Vue 3
+    tags:
+      - orchestrator
+      - install
+      - vue
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/vue-js.md
+  - id: django
+    display_name: Django
+    tags:
+      - orchestrator
+      - install
+      - django
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/django.md
+  - id: flask
+    display_name: Flask
+    tags:
+      - orchestrator
+      - install
+      - flask
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/flask.md
+  - id: fastapi
+    display_name: FastAPI
+    tags:
+      - orchestrator
+      - install
+      - fastapi
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/python.md
+  - id: react-tanstack-router-file-based
+    display_name: React with TanStack Router (file-based)
+    tags:
+      - orchestrator
+      - install
+      - react
+      - tanstack-router
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: react-tanstack-router-code-based
+    display_name: React with TanStack Router (code-based)
+    tags:
+      - orchestrator
+      - install
+      - react
+      - tanstack-router
+      - spa
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: tanstack-start
+    display_name: TanStack Start
+    tags:
+      - orchestrator
+      - install
+      - react
+      - tanstack-start
+      - tanstack-router
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/tanstack-start.md
+  - id: laravel
+    display_name: Laravel
+    tags:
+      - orchestrator
+      - install
+      - laravel
+      - php
+    docs_urls:
+      - https://posthog.com/docs/libraries/laravel.md
+  - id: php
+    display_name: PHP
+    tags:
+      - orchestrator
+      - install
+      - php
+    docs_urls:
+      - https://posthog.com/docs/libraries/php.md
+  - id: ruby-on-rails
+    display_name: Ruby on Rails
+    tags:
+      - orchestrator
+      - install
+      - ruby-on-rails
+      - ruby
+    docs_urls:
+      - https://posthog.com/docs/libraries/ruby-on-rails.md
+      - https://posthog.com/docs/libraries/ruby.md
+  - id: android
+    display_name: Android
+    tags:
+      - orchestrator
+      - install
+      - android
+      - java
+      - kotlin
+    docs_urls:
+      - https://posthog.com/docs/libraries/android.md
+  - id: sveltekit
+    display_name: SvelteKit
+    tags:
+      - orchestrator
+      - install
+      - sveltekit
+      - svelte
+      - javascript
+    docs_urls:
+      - https://posthog.com/docs/libraries/svelte.md
+  - id: python
+    display_name: Python
+    tags:
+      - orchestrator
+      - install
+      - python
+    docs_urls:
+      - https://posthog.com/docs/libraries/python.md
+      - https://posthog.com/docs/references/posthog-python.md
+  - id: javascript_node
+    display_name: JavaScript Node
+    tags:
+      - orchestrator
+      - install
+      - javascript_node
+    docs_urls:
+      - https://posthog.com/docs/libraries/node.md
+      - https://posthog.com/docs/references/posthog-node.md
+  - id: javascript_web
+    display_name: JavaScript Web
+    tags:
+      - orchestrator
+      - install
+      - javascript_web
+    docs_urls:
+      - https://posthog.com/docs/libraries/js.md
+      - https://posthog.com/docs/references/posthog-js.md
+  - id: ruby
+    display_name: Ruby
+    tags:
+      - orchestrator
+      - install
+      - ruby
+    docs_urls:
+      - https://posthog.com/docs/libraries/ruby.md
+  - id: elixir
+    display_name: Elixir
+    tags:
+      - orchestrator
+      - install
+      - elixir
+      - phoenix
+      - plug
+    docs_urls:
+      - https://posthog.com/docs/libraries/elixir.md
+  - id: go
+    display_name: Go
+    tags:
+      - orchestrator
+      - install
+      - go
+    docs_urls:
+      - https://posthog.com/docs/libraries/go.md
+  - id: swift
+    display_name: Swift (iOS/macOS)
+    tags:
+      - orchestrator
+      - install
+      - swift
+      - ios
+      - macos
+      - swiftui
+    docs_urls:
+      - https://posthog.com/docs/libraries/ios.md
+      - https://posthog.com/docs/libraries/ios/usage.md
+      - https://posthog.com/docs/libraries/ios/configuration.md
+  - id: flutter
+    display_name: Flutter
+    tags:
+      - orchestrator
+      - install
+      - flutter
+      - dart
+      - mobile
+    docs_urls:
+      - https://posthog.com/docs/libraries/flutter.md
+  - id: react-native
+    display_name: React Native
+    tags:
+      - orchestrator
+      - install
+      - react-native
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-native.md
+  - id: expo
+    display_name: Expo
+    tags:
+      - orchestrator
+      - install
+      - expo
+      - react-native
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/react-native.md
+  - id: astro-static
+    display_name: Astro (Static)
+    tags:
+      - orchestrator
+      - install
+      - astro
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-view-transitions
+    display_name: Astro (View Transitions)
+    tags:
+      - orchestrator
+      - install
+      - astro
+      - astro-view-transitions
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-ssr
+    display_name: Astro (SSR)
+    tags:
+      - orchestrator
+      - install
+      - astro
+      - astro-ssr
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: astro-hybrid
+    display_name: Astro (Hybrid)
+    tags:
+      - orchestrator
+      - install
+      - astro
+      - astro-hybrid
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/astro.md
+  - id: angular
+    display_name: Angular
+    tags:
+      - orchestrator
+      - install
+      - angular
+      - javascript
+      - typescript
+    docs_urls:
+      - https://posthog.com/docs/libraries/angular.md
diff --git a/context/skills/basic-integration/install/description.md b/context/skills/basic-integration/install/description.md
index cb6bdb9b..f914b263 100644
--- a/context/skills/basic-integration/install/description.md
+++ b/context/skills/basic-integration/install/description.md
@@ -12,3 +12,7 @@ range, and match the style of the dependencies already in the manifest.
 
 Read the manifest first. If the dependency is already declared, leave it as is and
 say so. Edit only the manifest — no lockfile, no install command.
+
+## Reference
+
+{references}