devlyn-cli 2.5.6 → 2.6.0

package/README.md

@@ -27,7 +27,7 @@ If devlyn-cli saved you time, [give it a star](https://github.com/fysoul17/devly
 npx devlyn-cli
 ```
 
-That's it. The interactive installer handles everything. Claude Code config is installed by default; optional AI CLI instructions can be selected during install. Choose **Codex CLI (OpenAI)** to install `AGENTS.md` and the `devlyn:resolve`, `devlyn:ideate`, and `devlyn:design-ui` skills into `~/.codex/skills/`. In Codex, invoke them as skills with `$devlyn:resolve`, `$devlyn:ideate`, or `$devlyn:design-ui` rather than Claude Code slash commands. Run it again anytime to update.
+That's it. The installer opens with a single **agent selector** — pick any combination of **Claude Code**, **Codex CLI**, **oh-my-pi (omp)**, **Pi**, Gemini, Cursor, Copilot, or Windsurf, and devlyn installs into every one you choose in a single pass. Claude Code and any agent already present on your machine are pre-checked, so the common case is just Enter. Skill-capable agents receive the `devlyn:resolve`, `devlyn:ideate`, and `devlyn:design-ui` skills in the directory each one loads from: Codex → `~/.codex/skills/`, while **omp and Pi share `~/.agents/skills/`** — the cross-agent standard both read — so the bundle is written there once, not duplicated per agent. In Codex / omp / Pi, invoke them as skills (`$devlyn:resolve`, `$devlyn:ideate`, `$devlyn:design-ui`); in Claude Code they're slash commands (`/devlyn:resolve`). Run it again anytime to update. (`npx devlyn-cli -y` installs the Claude core non-interactively; `npx devlyn-cli agents <cli>` adds one agent later.)
 
 ---
 
@@ -39,7 +39,7 @@ devlyn-cli turns Claude Code into a hands-free development pipeline. The pipelin
 ideate (optional)  →  resolve  →  ship
 ```
 
-Codex note: when the optional Codex install is selected, these workflows are installed as Codex skills. Use `$devlyn:ideate`, `$devlyn:resolve`, or `$devlyn:design-ui` in Codex; the `/devlyn:*` slash-command form is for Claude Code.
+Non-Claude agents (Codex / omp / Pi): when one of these is selected, the workflows install as that agent's skills. Use `$devlyn:ideate`, `$devlyn:resolve`, or `$devlyn:design-ui`; the `/devlyn:*` slash-command form is for Claude Code.
 
 ### Step 1 (optional) — Plan with `/devlyn:ideate`
 

package/bin/devlyn.js

@@ -11,6 +11,19 @@ const AGENTS_SOURCE = path.join(__dirname, '..', 'agents-config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
 const PKG = require('../package.json');
 
+// The devlyn skill bundle installed into every skill-capable agent's loader
+// directory. Single source of truth so codex/omp/pi stay in lockstep — adding a
+// skill here installs it everywhere. Standards skills (code-*, root-cause-*,
+// ui-*) stay Claude-core-only, matching the pre-existing Codex bundle.
+const DEVLYN_CORE_SKILLS = ['devlyn:resolve', 'devlyn:ideate', 'devlyn:design-ui', '_shared'];
+
+// Cross-agent shared skills directory read by BOTH oh-my-pi and Pi. Verified
+// from the omp binary's skill-provider strings ("skills from .agents/skills —
+// project walk-up + user home") and Pi's docs ("~/.agents/skills/"). Installing
+// the bundle here once covers both agents — the de-dup driver writes it a single
+// time even when both are selected.
+const SHARED_AGENTS_SKILLS_DIR = path.join(os.homedir(), '.agents', 'skills');
+
 // Cross-CLI agent installation targets
 // Each entry maps a CLI tool to where its agent instructions should be placed
 const CLI_TARGETS = {
@@ -22,9 +35,32 @@ const CLI_TARGETS = {
     // Codex auto-loads skills from ~/.codex/skills/ (user-global). Same
     // SKILL.md format as Claude Code; descriptions must stay ≤1024 chars.
     skillsDir: path.join(os.homedir(), '.codex', 'skills'),
-    skillsToInstall: ['devlyn:resolve', 'devlyn:ideate', 'devlyn:design-ui', '_shared'],
+    skillsToInstall: DEVLYN_CORE_SKILLS,
     detect: () => fs.existsSync(path.join(process.cwd(), 'AGENTS.md')) || fs.existsSync(path.join(process.cwd(), '.codex')),
   },
+  omp: {
+    name: 'oh-my-pi (omp)',
+    instructionsFile: 'AGENTS.md',
+    baseInstructionsFile: 'AGENTS.md',
+    configDir: null, // omp discovers AGENTS.md at project root + user home
+    // omp loads skills from ~/.agents/skills (user home) — shared with Pi.
+    skillsDir: SHARED_AGENTS_SKILLS_DIR,
+    skillsToInstall: DEVLYN_CORE_SKILLS,
+    // Project-scoped only: machine-level ~/.omp must not auto-trigger a project
+    // AGENTS.md write via `npx devlyn-cli agents` in an unrelated repo.
+    detect: () => fs.existsSync(path.join(process.cwd(), '.omp')) || fs.existsSync(path.join(process.cwd(), '.agents')),
+  },
+  pi: {
+    name: 'Pi (earendil-works)',
+    instructionsFile: 'AGENTS.md',
+    baseInstructionsFile: 'AGENTS.md',
+    configDir: null, // Pi reads AGENTS.md / CLAUDE.md walking up from cwd
+    // Pi loads skills from ~/.agents/skills — shared with oh-my-pi.
+    skillsDir: SHARED_AGENTS_SKILLS_DIR,
+    skillsToInstall: DEVLYN_CORE_SKILLS,
+    // Project-scoped only (see omp): machine-level ~/.pi must not auto-trigger.
+    detect: () => fs.existsSync(path.join(process.cwd(), '.pi')) || fs.existsSync(path.join(process.cwd(), '.agents')),
+  },
   gemini: {
     name: 'Gemini CLI (Google)',
     instructionsFile: 'GEMINI.md',
@@ -180,6 +216,7 @@ const OPTIONAL_ADDONS = [
   { name: 'generate-skill', desc: 'Create well-structured Claude Code skills following Anthropic best practices', type: 'local' },
   { name: 'prompt-engineering', desc: 'Claude 4 prompt optimization using Anthropic best practices', type: 'local' },
   { name: 'better-auth-setup', desc: 'Production-ready Better Auth + Hono + Drizzle + PostgreSQL auth setup', type: 'local' },
+  { name: 'polar-billing-setup', desc: 'Polar usage-based / metered billing — correct setup + diagnose silent $0-billing failures', type: 'local' },
   { name: 'pyx-scan', desc: 'Check whether an AI agent skill is safe before installing', type: 'local' },
   { name: 'dokkit', desc: 'Document template filling for DOCX/HWPX — ingest, fill, review, export', type: 'local' },
   { name: 'devlyn:pencil-pull', desc: 'Pull Pencil designs into code with exact visual fidelity', type: 'local' },
@@ -362,9 +399,9 @@ function cleanManagedSkillDirs(sourceSkillsDir, targetSkillsDir) {
   return cleaned;
 }
 
-function multiSelect(items) {
+function multiSelect(items, preselectedIndices = []) {
   return new Promise((resolve) => {
-    const selected = new Set();
+    const selected = new Set(preselectedIndices.filter((i) => i >= 0 && i < items.length));
     let cursor = 0;
     let firstRender = true;
 
@@ -469,11 +506,15 @@ function installLocalSkill(skillName) {
   copyRecursive(src, dest, targetDir);
 
   // Mirror to every CLI skill-loader directory that already exists so optional
-  // skills are picked up by Codex (and any future CLI with a skillsDir) the
-  // same way required skills are. Existing dir, not new dir — we don't create
-  // a Codex install just because someone opted into a Claude-side skill.
+  // skills are picked up by Codex/omp/Pi (and any future CLI with a skillsDir)
+  // the same way required skills are. Existing dir, not new dir — we don't
+  // create an agent install just because someone opted into a Claude-side skill.
+  // De-dup by directory: omp and Pi share ~/.agents/skills, so the mirror runs
+  // once per unique destination.
+  const mirrored = new Set();
   for (const cli of Object.values(CLI_TARGETS)) {
-    if (!cli.skillsDir || !fs.existsSync(cli.skillsDir)) continue;
+    if (!cli.skillsDir || mirrored.has(cli.skillsDir) || !fs.existsSync(cli.skillsDir)) continue;
+    mirrored.add(cli.skillsDir);
     const cliDest = path.join(cli.skillsDir, skillName);
     if (fs.existsSync(cliDest)) fs.rmSync(cliDest, { recursive: true, force: true });
     copyRecursive(src, cliDest, cli.skillsDir);
@@ -555,94 +596,136 @@ function installSkillsForCLI(cliKey) {
   return copied;
 }
 
-function installAgentsForCLI(cliKey) {
+// Strip devlyn's previously-appended "# Devlyn Agent Instructions" block from an
+// instruction file (or the packaged base) before re-appending, so installs stay
+// idempotent and never duplicate the block. Anchors on the LAST marker, not the
+// first: the packaged AGENTS.md ships its own "# Devlyn Agent Instructions"
+// section, so indexOf would truncate that real content — lastIndexOf targets the
+// devlyn-appended block (always last) and preserves everything above it.
+function stripManagedBlock(content) {
+  const marker = '# Devlyn Agent Instructions';
+  const markerIdx = content.lastIndexOf(marker);
+  if (markerIdx > 0) {
+    const sepIdx = content.lastIndexOf('\n---', markerIdx);
+    return content.slice(0, sepIdx > 0 ? sepIdx : markerIdx).trimEnd();
+  }
+  return content.trimEnd();
+}
+
+// One-line description of exactly what selecting a CLI target installs, so the
+// unified selector stays honest — "Gemini" (instructions only) must not look
+// identical to "Codex" (instructions + skills).
+function targetDesc(cli) {
+  if (cli.skillsDir) {
+    return `${cli.instructionsFile} + devlyn skills → ${cli.skillsDir.replace(os.homedir(), '~')}`;
+  }
+  if (cli.configDir) return `Agent instructions → ${cli.configDir}/`;
+  return `${cli.instructionsFile} instructions only`;
+}
+
+// Install only the instruction file(s) for a CLI (no skills). Returns true when
+// instruction content was written. Split from skills so the de-dup driver can
+// write a shared destination (e.g. project AGENTS.md for codex/omp/pi) once.
+function installInstructionsForCLI(cliKey) {
   const cli = CLI_TARGETS[cliKey];
   if (!cli) return false;
 
   const agents = fs.existsSync(AGENTS_SOURCE)
     ? fs.readdirSync(AGENTS_SOURCE).filter((f) => f.endsWith('.md'))
     : [];
+  if (agents.length === 0) return false;
 
-  if (agents.length > 0) {
-    log(`\n🤖 Installing agents for ${cli.name}...`, 'cyan');
+  log(`\n🤖 Installing agent instructions for ${cli.name}...`, 'cyan');
 
-    if (cli.configDir) {
-      // CLI supports an agents directory — copy agent files there
-      const destDir = path.join(process.cwd(), cli.configDir);
-      if (!fs.existsSync(destDir)) {
-        fs.mkdirSync(destDir, { recursive: true });
-      }
-      for (const file of agents) {
-        const src = path.join(AGENTS_SOURCE, file);
-        const dest = path.join(destDir, file);
-        fs.copyFileSync(src, dest);
-        log(`  → ${cli.configDir}/${file}`, 'dim');
-      }
-    } else {
-      // CLI uses a single instructions file — append agent content
-      const destFile = path.join(process.cwd(), cli.instructionsFile);
-      const separator = '\n\n---\n\n# Devlyn Agent Instructions\n\n';
-      const agentContent = agents.map((file) => {
-        return fs.readFileSync(path.join(AGENTS_SOURCE, file), 'utf8');
-      }).join('\n\n---\n\n');
-
-      let existing = '';
-      if (fs.existsSync(destFile)) {
-        existing = fs.readFileSync(destFile, 'utf8');
-        // Remove previous devlyn agent section if present
-        const devlynMarker = '# Devlyn Agent Instructions';
-        const markerIdx = existing.indexOf(devlynMarker);
-        if (markerIdx > 0) {
-          // Find the separator before the marker (---\n\n)
-          const sepIdx = existing.lastIndexOf('---', markerIdx);
-          existing = existing.slice(0, sepIdx > 0 ? sepIdx : markerIdx).trimEnd();
-        }
-      } else if (cli.baseInstructionsFile) {
-        const baseInstructionsSrc = path.join(__dirname, '..', cli.baseInstructionsFile);
-        if (fs.existsSync(baseInstructionsSrc)) {
-          existing = fs.readFileSync(baseInstructionsSrc, 'utf8').trimEnd();
-        }
+  if (cli.configDir) {
+    // CLI supports an agents directory — copy agent files there
+    const destDir = path.join(process.cwd(), cli.configDir);
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+    for (const file of agents) {
+      const src = path.join(AGENTS_SOURCE, file);
+      const dest = path.join(destDir, file);
+      fs.copyFileSync(src, dest);
+      log(`  → ${cli.configDir}/${file}`, 'dim');
+    }
+  } else {
+    // CLI uses a single instructions file — append agent content
+    const destFile = path.join(process.cwd(), cli.instructionsFile);
+    const separator = '\n\n---\n\n# Devlyn Agent Instructions\n\n';
+    const agentContent = agents.map((file) => {
+      return fs.readFileSync(path.join(AGENTS_SOURCE, file), 'utf8');
+    }).join('\n\n---\n\n');
+
+    let existing = '';
+    if (fs.existsSync(destFile)) {
+      existing = stripManagedBlock(fs.readFileSync(destFile, 'utf8'));
+    } else if (cli.baseInstructionsFile) {
+      const baseInstructionsSrc = path.join(__dirname, '..', cli.baseInstructionsFile);
+      if (fs.existsSync(baseInstructionsSrc)) {
+        existing = stripManagedBlock(fs.readFileSync(baseInstructionsSrc, 'utf8'));
       }
-
-      fs.writeFileSync(destFile, existing + separator + agentContent + '\n');
-      log(`  → ${cli.instructionsFile} (agent instructions appended)`, 'dim');
     }
+
+    fs.writeFileSync(destFile, existing + separator + agentContent + '\n');
+    log(`  → ${cli.instructionsFile} (agent instructions appended)`, 'dim');
   }
+  return true;
+}
 
-  // Always install global skills (Codex-style skill loader) regardless of
-  // whether agent files were present. Agent install and skill install are
-  // independent capabilities.
+// Install both instructions and skills for a single CLI. Used by the
+// `agents <cli>` command; multi-target paths use installSelectedCLITargets.
+function installAgentsForCLI(cliKey) {
+  const instr = installInstructionsForCLI(cliKey);
   const skillsCopied = installSkillsForCLI(cliKey);
   if (skillsCopied > 0) {
     log(`  → ${skillsCopied} skill${skillsCopied > 1 ? 's' : ''} installed (devlyn:resolve / devlyn:ideate / devlyn:design-ui / _shared)`, 'dim');
   }
+  return instr || skillsCopied > 0;
+}
 
-  return agents.length > 0 || skillsCopied > 0;
+// Install instructions + skills for a set of selected CLI targets, writing each
+// unique destination exactly once. omp and Pi share project AGENTS.md and the
+// ~/.agents/skills dir, so selecting both does not duplicate writes — this is
+// the researched "group the common" model: targets are the user's selection,
+// destinations are the unit of work.
+function installSelectedCLITargets(cliKeys) {
+  const instrDone = new Set();
+  const skillsDone = new Set();
+  let count = 0;
+  for (const cliKey of cliKeys) {
+    const cli = CLI_TARGETS[cliKey];
+    if (!cli) continue;
+    const instrKey = cli.configDir ? `dir:${cli.configDir}` : `file:${cli.instructionsFile}`;
+    if (!instrDone.has(instrKey)) {
+      installInstructionsForCLI(cliKey);
+      instrDone.add(instrKey);
+    }
+    if (cli.skillsDir && !skillsDone.has(cli.skillsDir)) {
+      const copied = installSkillsForCLI(cliKey);
+      if (copied > 0) {
+        log(`  → ${copied} skill${copied > 1 ? 's' : ''} → ${cli.skillsDir.replace(os.homedir(), '~')}`, 'dim');
+      }
+      skillsDone.add(cli.skillsDir);
+    }
+    count++;
+  }
+  return count;
 }
 
 function installAgentsForAllDetected() {
   const detected = detectOtherCLIs();
   if (detected.length === 0) return 0;
-
-  let installed = 0;
-  for (const cliKey of detected) {
-    if (installAgentsForCLI(cliKey)) installed++;
-  }
-  return installed;
+  return installSelectedCLITargets(detected);
 }
 
-async function init(skipPrompts = false) {
-  showLogo();
-  log('─'.repeat(44), 'dim');
-
-  if (!fs.existsSync(CONFIG_SOURCE)) {
-    log('❌ Config source not found', 'yellow');
-    process.exit(1);
-  }
-
-  // Install core config
+// Install the Claude Code core config: project .claude/ (skills, templates,
+// settings, CLAUDE.md, .gitignore) plus global ~/.claude/settings.json tweaks.
+// Extracted so the unified target selector installs it only when "Claude Code"
+// is chosen. Behavior is unchanged from the previous unconditional core install.
+function installClaudeCore() {
   const targetDir = getTargetDir();
-  log('\n📁 Installing core config to .claude/', 'green');
+  log('\n📁 Installing Claude Code config to .claude/', 'green');
   const refreshed = cleanManagedSkillDirs(
     path.join(CONFIG_SOURCE, 'skills'),
     path.join(targetDir, 'skills'),
@@ -746,40 +829,55 @@ async function init(skipPrompts = false) {
     log('  → ~/.claude/settings.json (disabled adaptive thinking, enabled 1h prompt caching)', 'dim');
   }
 
-  log('\n✅ Core config installed!', 'green');
+  log('\n✅ Claude Code config installed!', 'green');
+}
+
+async function init(skipPrompts = false) {
+  showLogo();
+  log('─'.repeat(44), 'dim');
 
-  // Skip prompts if -y flag or non-interactive
+  if (!fs.existsSync(CONFIG_SOURCE)) {
+    log('❌ Config source not found', 'yellow');
+    process.exit(1);
+  }
+
+  // Non-interactive / -y: preserve historical behavior — install Claude core
+  // only. Multi-target selection needs a TTY; scripted runs add other agents
+  // via `npx devlyn-cli agents <cli>`.
   if (skipPrompts || !process.stdin.isTTY) {
+    installClaudeCore();
     log('\n💡 Add optional addons later: run `npx devlyn-cli` without -y', 'dim');
-    log('   Add Codex instructions + skills later: run `npx devlyn-cli agents codex`', 'dim');
+    log('   Add another agent (Codex / omp / Pi / …) later: `npx devlyn-cli agents <cli>`', 'dim');
     log(`\n${COLORS.dim}   Enjoying devlyn? Star it on GitHub — it helps others find it:${COLORS.reset}`);
     log(`   ${COLORS.purple}→ https://github.com/fysoul17/devlyn-cli${COLORS.reset}\n`);
     return;
   }
 
-  // Ask which non-Claude CLIs should receive instruction files.
-  log('\n🤖 Optional AI CLI instructions:\n', 'blue');
-  const cliOptions = Object.entries(CLI_TARGETS).map(([key, cli]) => {
-    let desc;
-    if (cli.configDir) {
-      desc = `Install agents into ${cli.configDir}/`;
-    } else if (cli.skillsDir) {
-      desc = `Install ${cli.instructionsFile} + devlyn:resolve/devlyn:ideate/devlyn:design-ui skills (~/.codex/skills/; use $devlyn:* in Codex)`;
-    } else {
-      desc = `Install ${cli.instructionsFile}`;
-    }
-    return { key, name: cli.name, desc, type: 'cli' };
-  });
-  const selectedClis = await multiSelect(cliOptions);
-  if (selectedClis.length > 0) {
-    let agentsInstalled = 0;
-    for (const selectedCli of selectedClis) {
-      if (installAgentsForCLI(selectedCli.key)) agentsInstalled++;
-    }
-    log(`  ✅ Agent instructions installed for ${agentsInstalled} CLI${agentsInstalled !== 1 ? 's' : ''}`, 'green');
-  } else {
-    log('💡 No additional CLI instructions selected', 'dim');
-    log('   Run `npx devlyn-cli agents codex` later to install Codex AGENTS.md + devlyn skills', 'dim');
+  // Pick every agent to install devlyn into, up front. Claude Code is
+  // pre-checked (the happy path); every other agent is an explicit opt-in so a
+  // bare Enter never mutates a project's AGENTS.md or a shared skills dir for an
+  // agent the user didn't choose.
+  log('\n🎯 Select the agents to install devlyn into:\n', 'blue');
+  const targetOptions = [
+    { key: 'claude', name: 'Claude Code', desc: '.claude/ config — skills, templates, settings, CLAUDE.md', type: 'cli' },
+    ...Object.entries(CLI_TARGETS).map(([key, cli]) => ({ key, name: cli.name, desc: targetDesc(cli), type: 'cli' })),
+  ];
+  const preselected = [targetOptions.findIndex((o) => o.key === 'claude')];
+  const selectedKeys = (await multiSelect(targetOptions, preselected)).map((t) => t.key);
+
+  if (selectedKeys.length === 0) {
+    log('\n💡 No agents selected — nothing installed.', 'yellow');
+    log('   Run `npx devlyn-cli` again and pick at least one agent.\n', 'dim');
+    return;
+  }
+
+  if (selectedKeys.includes('claude')) {
+    installClaudeCore();
+  }
+  const cliKeys = selectedKeys.filter((k) => k !== 'claude');
+  if (cliKeys.length > 0) {
+    const installed = installSelectedCLITargets(cliKeys);
+    log(`\n  ✅ Installed devlyn into ${installed} agent${installed !== 1 ? 's' : ''}`, 'green');
   }
 
   // Ask about optional addons (local skills + external packs)
@@ -805,9 +903,9 @@ async function init(skipPrompts = false) {
 function showHelp() {
   showLogo();
   log('Usage:', 'green');
-  log('  npx devlyn-cli              Install/update .claude config');
+  log('  npx devlyn-cli              Install/update devlyn (pick agents: Claude / Codex / omp / Pi / …)');
   log('  npx devlyn-cli list         List available skills & templates');
-  log('  npx devlyn-cli -y           Install without prompts');
+  log('  npx devlyn-cli -y           Install Claude core without prompts');
   log('  npx devlyn-cli agents       Install agents for detected CLIs');
   log('  npx devlyn-cli agents all   Install agents for all supported CLIs');
   log('  npx devlyn-cli benchmark    Run the resolve benchmark suite');
@@ -1064,12 +1162,10 @@ switch (command) {
     log('─'.repeat(44), 'dim');
     const subArg = args[1];
     if (subArg === 'all') {
-      // Install for all supported CLIs regardless of detection
+      // Install for all supported CLIs regardless of detection. De-duped so the
+      // shared ~/.agents/skills dir (omp + Pi) and shared AGENTS.md write once.
       log('\n🤖 Installing agents for all supported CLIs...', 'blue');
-      let count = 0;
-      for (const cliKey of Object.keys(CLI_TARGETS)) {
-        if (installAgentsForCLI(cliKey)) count++;
-      }
+      const count = installSelectedCLITargets(Object.keys(CLI_TARGETS));
       log(`\n✅ Agents installed for ${count} CLI${count !== 1 ? 's' : ''}`, 'green');
     } else if (subArg && CLI_TARGETS[subArg]) {
       // Install for a specific CLI

package/optional-skills/polar-billing-setup/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: polar-billing-setup
+description: Set up, integrate, and DEBUG Polar (polar.sh) usage-based / metered billing the right way — events ingestion, meters, metered prices, checkout, webhooks, and free-credit reconciliation. Use this whenever the user mentions Polar billing, usage-based or metered billing, "ingest events to Polar", a Polar meter, a metered price, or — critically — when billing looks broken: "Polar isn't charging", "my invoice is $0", "usage events aren't billing", "consumed_units is 0", "metering not working", or "why are customers not being charged". This skill encodes the silent-failure traps that make Polar metering quietly bill $0, and ships a diagnostic script that tells you exactly where the chain is broken. Prefer it over guessing whenever Polar metered billing is involved, even if the user doesn't name the specific failure.
+allowed-tools: Read, Write, Edit, Bash
+argument-hint: [setup | verify | diagnose --customer <id>]
+---
+
+# Polar usage-based billing — setup & verification
+
+Polar metered billing is a **chain**, and any single broken link silently bills **$0** with no error. Events still return `inserted: 1`, the dashboard still shows the subscription as active, orders still get created — they're just all `$0`. The failure is invisible unless you check the one number that matters: the meter's `consumed_units`.
+
+This skill exists because that chain is easy to misconfigure and the failures are silent. Read this top section always; pull in `references/` and run `scripts/diagnose.mjs` as the task dictates.
+
+## The billing chain (every link must hold)
+
+```
+app emits event  ─►  meter FILTER matches it  ─►  meter AGGREGATION sums a property
+   (name +              (by event name)            that EXISTS on the event
+    metadata)                                              │
+                                                           ▼
+customer is linked  ◄─  metered PRICE is attached  ◄─  consumed_units > 0
+to a subscription       to the meter (not flat/free)
+        │
+        ▼
+   invoice charges at cycle end
+```
+
+Break any arrow and the invoice is `$0`. The most common break — and the one that burns hours — is the **aggregation property name not matching the emitted metadata key** (a `cost_cent` vs `cost_cents` typo, a casing/spacing mismatch). The filter still matches by event name, so events flow in and look fine, but the sum targets a property that doesn't exist, so `consumed_units` stays 0.
+
+## Golden rules (the why behind each)
+
+1. **The aggregation property must byte-match the emitted metadata key.** Polar sums `metadata.<property>`; if the emitter sends `cost_cents` and the meter sums `cost_cent`, the sum is over a missing field → 0. Decide the exact key ONCE and assert it on both ends. Singular/plural/camelCase/snake_case are different keys.
+
+2. **A meter's aggregation is immutable once it has aggregated events.** `PATCH /v1/meters/{id}` on `aggregation` returns `422 "can't be updated because the meter is already aggregating events"`. So you cannot fix a property typo on the meter after go-live. Either get it right at creation, or — the cheaper fix — **change the emitter to match the meter's existing (even misspelled) property**, because that fixes existing subscriptions without re-pointing prices. Recreating the meter means creating a new price and migrating every existing subscription. Document any locked-in misspelling at the emitter so nobody "corrects" it and re-breaks billing.
+
+3. **`inserted: 1` is NOT proof of billing.** It means the event was accepted, not metered. The only proof is `consumed_units > 0` on the customer's meter (`GET /v1/customers/{id}/state` or `GET /v1/meters/{id}/quantities`). Always verify after a change.
+
+4. **Polar does not backfill.** Events ingested before the meter/aggregation/price was correct are NOT retro-counted when you fix the config. Only events after the fix aggregate. Plan a manual order/credit adjustment if past usage must be recovered.
+
+5. **The price must be a metered price bound to the meter.** A product can have a `free`/`fixed` price AND a `metered_unit` price; only the `metered_unit` one with the right `meter_id` produces usage charges. Verify `amount_type: "metered_unit"` and `meter_id` match.
+
+6. **Usage attributes to a linked customer.** Events carry `customer_id` (Polar's id) or `external_customer_id` (your id, set at checkout). If the customer isn't created/linked, the usage is orphaned and never billed. Confirm the customer exists and its `external_id` maps back to your tenant.
+
+7. **Sandbox ≠ production.** Token, API base (`sandbox-api.polar.sh` vs `api.polar.sh`), and product/meter IDs all differ per environment. A sandbox token in prod means no real money moves — and it fails silently. Drive the base + IDs off one env switch.
+
+8. **Token scopes are split.** Ingestion needs `events:write`; reading meters/orders for diagnosis needs `meters:read` / `orders:read`. The minimal ingestion token usually CANNOT read meters, so diagnosis returns `insufficient_scope` — provision a separate read-scoped token for debugging (never widen the production ingestion token just to debug).
+
+9. **Reconcile local free credit with Polar.** If you grant local "first $X free" credit, the emitter must send Polar only the **billable overflow** (`max(0, cost − remainingCredit)`), or Polar will bill the free tier too. Conversely, if Polar grants the credit (a credit benefit), don't also withhold locally. Pick one source of truth and net consistently.
+
+10. **Webhooks must fail loud, not 200-ack.** Returning `200` when customer resolution fails makes Polar treat delivery as successful and never retry — the link is lost forever. Return non-2xx on unresolved linkage; keep handlers idempotent (dedupe by event id).
+
+## Workflow
+
+**Setup a new integration** → read `references/setup.md` and follow it in order (meter → product+metered price → checkout → webhook → ingestion). Get the property name and aggregation right the first time (rule 2).
+
+**Add metering to an existing integration** → confirm the meter's exact `aggregation.property`, then make the emitter send that exact key. Don't invent a "nicer" key.
+
+**Debug "$0 invoice" / "not charging" / "consumed_units is 0"** → run the diagnostic FIRST, before theorizing:
+
+```bash
+POLAR_ACCESS_TOKEN=<read-scoped token> POLAR_SERVER=production \
+  node scripts/diagnose.mjs --customer <polar_customer_id> --event-name <name>
+```
+
+It reports, link by link, where the chain breaks: token scope, meter filter+aggregation, whether recent events' metadata keys actually match the aggregation property, `consumed_units`, the product's price type, and recent order totals. Read its verdict, then fix the one broken link. See `references/gotchas.md` for the full failure catalog mapped to symptoms.
+
+**After ANY fix** → verify with rule 3: emit one real (or synthetic `cost:1`) event and confirm `consumed_units` increments. A passing unit test on the emitter is necessary but not sufficient — the meter config lives in the Polar dashboard, outside your repo.
+
+## Reference files
+
+- `references/setup.md` — step-by-step correct setup (meter, product, metered price, checkout, webhook, ingestion), with the exact API shapes.
+- `references/gotchas.md` — the full silent-failure catalog: symptom → cause → fix, including everything that produced a real $0-billing incident.
+
+## Diagnostic script
+
+`scripts/diagnose.mjs` — Node 18+ (global `fetch`). Read-only. Walks the whole chain for one customer and prints a per-link PASS/FAIL verdict. This is the fastest path from "billing seems broken" to "here is the exact broken link." Requires a token with `meters:read` + `orders:read` (see rule 8).

package/optional-skills/polar-billing-setup/references/gotchas.md

@@ -0,0 +1,111 @@
+# Polar metering failure catalog — symptom → cause → fix
+
+Every entry here has produced a real silent-$0-billing incident or is a near-miss the diagnostic checks for. Match the symptom, confirm the cause with `scripts/diagnose.mjs`, apply the fix. Ordered by how often it's the culprit.
+
+---
+
+## 1. Invoice is $0 but events show `inserted:1` — aggregation property typo
+
+**Symptom:** Events ingest fine (`{"inserted":1}`), the subscription is active, orders are created — all `$0`. `consumed_units` is 0.
+
+**Cause:** The meter's `aggregation.property` doesn't byte-match the emitted `metadata` key. Classic: meter sums `cost_cent` (singular) while the app emits `cost_cents` (plural). The filter still matches by event **name**, so events flow and look healthy, but `sum` targets a non-existent property → 0. Casing (`costCents` vs `cost_cents`) and spaces do the same.
+
+**Confirm:** diagnostic link "emitted metadata key matches meter aggregation property" → FAIL. Or by hand: `GET /v1/meters/{id}` `aggregation.property` vs `GET /v1/events/?customer_id=...` metadata keys.
+
+**Fix:** The aggregation is **immutable once aggregating** (`PATCH` → `422`), so you usually fix the **emitter** to send the meter's existing property name — even if it's the misspelled one — because that fixes all existing subscriptions without re-pointing prices. Add a comment at the emitter so nobody "corrects" the spelling and re-breaks billing. Then re-emit and confirm `consumed_units` increments. Past events do NOT backfill.
+
+---
+
+## 2. `PATCH /v1/meters/{id}` returns 422 — meter aggregation is locked
+
+**Symptom:** Trying to fix the property on the meter returns `422 "This field can't be updated because the meter is already aggregating events."`
+
+**Cause:** Polar freezes a meter's aggregation once it has counted any event. By design.
+
+**Fix:** Don't fight it. Match the emitter to the meter (entry 1). Creating a *new* meter is a last resort — it forces a new metered price and a migration of every existing subscription to it; the old meter and its subscriptions keep producing $0.
+
+---
+
+## 3. `consumed_units` is 0 but everything else looks right
+
+**Symptom:** Filter matches, events exist, but the customer meter shows `consumed: 0`.
+
+**Causes (check in order):** (a) aggregation property mismatch (entry 1) — most likely; (b) events ingested *before* the meter/aggregation existed and you're expecting backfill — there is none; (c) the events carry the property but as a **string** when `sum` expects a number — send numbers, not `"1"`; (d) you're reading a different environment than the events landed in (entry 6).
+
+**Fix:** Run the diagnostic; it isolates a–d. Remember: only events ingested *after* the config is correct will count.
+
+---
+
+## 4. "It's billing, just small" — actually it's $0
+
+**Symptom:** Assuming tiny charges when the real number is exactly 0.
+
+**Cause:** Conflating local usage counters / dashboards with the Polar invoice. Your app's "total usage" can be accurate while Polar bills $0 because the meter isn't aggregating.
+
+**Fix:** Trust `consumed_units` and `GET /v1/orders` `total_amount`, not your own dashboard, as the billing source of truth. The diagnostic reads both.
+
+---
+
+## 5. New users charged for their "free" credit — local credit not reconciled
+
+**Symptom:** Once metering works, users are billed for usage that local logic treated as free signup credit.
+
+**Cause:** The emitter sends the **full** cost to Polar while local code separately decrements a free-credit balance. The two ledgers don't talk, so the free tier is billed by Polar anyway.
+
+**Fix:** Send Polar only the billable overflow: `billable = max(0, cost − remainingCreditBefore)`, computed atomically (read credit under a row lock in the same transaction as the decrement). Forward `billable` to ingestion; skip ingestion when it's 0. Alternatively configure a matching credit benefit on the Polar product and don't withhold locally — but pick exactly one source of truth.
+
+---
+
+## 6. Works in sandbox, $0 in production (or vice-versa)
+
+**Symptom:** Behaves differently across environments, or prod moves no money.
+
+**Cause:** A sandbox token / sandbox API base / sandbox product+meter IDs leaked into production (or the inverse). Sandbox and production are separate Polar orgs. A sandbox token in prod silently bills nothing.
+
+**Fix:** One env switch driving base URL + token + product/meter IDs. Sandbox tokens commonly look like `polar_oat_…` on `sandbox-api.polar.sh`; verify with `GET /v1/customers/{id}` that the customer/org is the one you expect. The diagnostic takes `POLAR_SERVER=sandbox|production` — run it against both if unsure.
+
+---
+
+## 7. Diagnosis returns `insufficient_scope`
+
+**Symptom:** `GET /v1/meters` or `/v1/orders` → `{"error":"insufficient_scope"}`.
+
+**Cause:** The production **ingestion** token only needs `events:write`, so it's usually scoped down and can't read meters/orders.
+
+**Fix:** Create a separate token with `meters:read` + `orders:read` (+ `customers:read`, `events:read`) just for diagnosis. Don't widen the production ingestion token. Keep the diagnostic token in a local file, never echo it into logs or chat, never commit it.
+
+---
+
+## 8. Customer linked but usage orphaned
+
+**Symptom:** Subscription exists, events ingest, but a specific customer's usage never bills.
+
+**Cause:** Events sent with a `customer_id`/`external_customer_id` that doesn't resolve to a linked Polar customer, or the customer was never created. Orphaned events aren't billed.
+
+**Fix:** Ensure the Polar customer exists and its `external_id` maps to your tenant (set `external_customer_id` at checkout; store the returned `customer_id`). Only emit usage for customers you've confirmed are linked.
+
+---
+
+## 9. Webhook 200-ack on failure loses the link forever
+
+**Symptom:** A subscription exists in Polar but your DB never recorded the `customer_id`; usage for that org silently drops.
+
+**Cause:** The webhook handler caught a resolution failure and still returned `200`. Polar marks delivery successful and never retries, so the one chance to link the customer is gone.
+
+**Fix:** Return non-2xx whenever customer/org resolution fails so Polar retries. Keep the handler idempotent (dedupe by `webhook-id`) so retries are safe. Verify the HMAC signature.
+
+---
+
+## 10. Ingestion failures vanish
+
+**Symptom:** Occasional gaps in metered usage with no error surfaced.
+
+**Cause:** Fire-and-forget ingestion — failures are logged and swallowed, never retried. A Polar API blip drops events permanently.
+
+**Fix:** At minimum, log+alert on ingestion failure. If usage is high-value, put ingestion behind a durable queue with retry. Accept the tradeoff explicitly rather than discovering it as missing revenue.
+
+---
+
+## The one-line rule
+
+After **any** billing change, emit one event and confirm `consumed_units` went up. Unit tests on the emitter are necessary but not sufficient — the meter config lives in the Polar dashboard, outside your repo, and is the half that silently breaks.

package/optional-skills/polar-billing-setup/references/setup.md

@@ -0,0 +1,101 @@
+# Correct setup order — Polar usage-based billing
+
+Set these up in order. The ordering matters because the price binds to the meter, and the emitter must match the meter's aggregation property (which is immutable after the first event — see rule 2 in SKILL.md).
+
+## 0. Decide the contract first (on paper)
+
+Before clicking anything, fix three strings and never deviate:
+
+- **event name** — e.g. `compute-usage`
+- **metadata property** to aggregate — e.g. `cost_cents` (pick the spelling now; you cannot change it on the meter later)
+- **unit semantics** — what one unit costs. If the meter sums `cost_cents` (integer cents of cost) and the price is `unit_amount = 1` (1 cent/unit), then charge = cents-of-cost = the dollar cost. Keep the math trivially invertible.
+
+## 1. Meter (dashboard or API)
+
+A meter has a **filter** (which events it counts) and an **aggregation** (what number it produces).
+
+```
+POST /v1/meters
+{
+  "name": "compute-usage",
+  "filter": { "conjunction": "and", "clauses": [
+    { "conjunction": "or", "clauses": [
+      { "property": "name", "operator": "eq", "value": "compute-usage" }
+    ]}
+  ]},
+  "aggregation": { "func": "sum", "property": "cost_cents" }   // ← property MUST equal the emitted metadata key
+}
+```
+
+- `func` is `count` | `sum` | `avg` | `min` | `max`. For `count`, `property` is irrelevant. For the rest, `property` must be a metadata key present on the events.
+- **This `aggregation` cannot be edited once events have been counted** (`422`). Triple-check the property spelling here.
+
+## 2. Product + metered price
+
+```
+POST /v1/products
+{ "name": "Pay-as-you-go", "recurring_interval": "month",
+  "prices": [
+    { "amount_type": "free" },                                 // $0/mo base
+    { "amount_type": "metered_unit", "unit_amount": 1,         // 1 cent per unit
+      "meter_id": "<meter id from step 1>" }                   // ← binds price to the meter
+  ]
+}
+```
+
+- Without a `metered_unit` price bound to the meter, usage never turns into money.
+- `unit_amount` is per unit in the smallest currency unit (supports fractional via decimal string).
+
+## 3. Checkout (links a customer to the subscription)
+
+```
+POST /v1/checkouts/
+{ "products": ["<product id>"],
+  "customer_email": "<email>",
+  "external_customer_id": "<your tenant/org id>",   // ← so webhooks + events map back to you
+  "success_url": "https://app.example.com/success" }
+```
+
+- `external_customer_id` is the bridge: later you read it back from the Polar customer (`external_id`) to link the Polar `customer_id` to your tenant. Set it, always.
+
+## 4. Webhook (subscription lifecycle → your DB)
+
+Handle `subscription.created` / `.updated` / `.canceled` / `.revoked`. On `created`/`updated`, resolve your org from `customer_id` (DB lookup, then `GET /v1/customers/{id}` → `external_id` fallback) and store the Polar `customer_id` on your org.
+
+- **Fail loud.** If you can't resolve the org, return non-2xx so Polar retries. A `200` ack on failure loses the link permanently.
+- Verify the `webhook-signature` HMAC; dedupe by `webhook-id` for idempotency.
+
+## 5. Ingestion (emit usage)
+
+```
+POST /v1/events/ingest
+{ "events": [{
+    "name": "compute-usage",                 // ← must match the meter filter
+    "customer_id": "<polar customer id>",     // (or external_customer_id)
+    "metadata": { "cost_cents": <amount> }    // ← key MUST match meter aggregation.property
+}]}
+```
+
+- Emit only the **billable** amount. If you grant local free credit, send `max(0, cost − remainingCredit)` so the free tier isn't billed (rule 9).
+- Ingestion is fire-and-forget on most integrations; failures are logged, not retried. Monitor for `ingestion failed` and decide if you need a retry/queue.
+
+## 6. Verify (do NOT skip)
+
+```
+node scripts/diagnose.mjs --customer <id> --event-name compute-usage
+```
+
+Emit one event, then confirm `consumed_units > 0`. `inserted:1` is not enough. There is no backfill, so verify before you assume past usage will be captured.
+
+## Environment switch
+
+Drive everything off one flag:
+
+```
+const PROD = process.env.NODE_ENV === "production";
+const BASE = PROD ? "https://api.polar.sh" : "https://sandbox-api.polar.sh";
+const PRODUCT_ID = PROD ? "<prod product>" : "<sandbox product>";
+// token + webhook secret come from env per environment
+```
+
+Sandbox and production are separate orgs with separate tokens, products, and meters. A sandbox token in prod moves no real money and fails silently.

package/optional-skills/polar-billing-setup/scripts/diagnose.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// Polar usage-based billing diagnostic — walks the metering chain for one
+// customer and reports, link by link, where billing breaks. Read-only.
+//
+// Usage:
+//   POLAR_ACCESS_TOKEN=<token with meters:read + orders:read> \
+//   POLAR_SERVER=production|sandbox \
+//     node diagnose.mjs --customer <polar_customer_id> [--event-name <name>] [--meter <meter_id>]
+//
+// Why this exists: Polar metered billing fails silently. Events return
+// `inserted:1`, subscriptions look active, orders get created — all at $0 —
+// when a single link in the chain is misconfigured. This script checks each
+// link and names the broken one instead of leaving you to guess.
+
+const args = Object.fromEntries(
+  process.argv.slice(2).reduce((acc, a, i, arr) => {
+    if (a.startsWith("--")) acc.push([a.slice(2), arr[i + 1]?.startsWith("--") ? true : arr[i + 1]]);
+    return acc;
+  }, []),
+);
+
+const TOKEN = process.env.POLAR_ACCESS_TOKEN;
+const SERVER = (process.env.POLAR_SERVER || "production").toLowerCase();
+const BASE = SERVER === "sandbox" ? "https://sandbox-api.polar.sh" : "https://api.polar.sh";
+const CUSTOMER = args.customer;
+const EVENT_NAME = args["event-name"];
+const METER_ARG = args.meter;
+
+const C = { g: "\x1b[32m", r: "\x1b[31m", y: "\x1b[33m", d: "\x1b[2m", x: "\x1b[0m" };
+const PASS = `${C.g}✓ PASS${C.x}`;
+const FAIL = `${C.r}✗ FAIL${C.x}`;
+const WARN = `${C.y}? UNKNOWN${C.x}`;
+
+if (!TOKEN || !CUSTOMER) {
+  console.error("Required: POLAR_ACCESS_TOKEN env + --customer <id>.");
+  console.error("Optional: POLAR_SERVER=sandbox|production, --event-name <name>, --meter <id>.");
+  process.exit(2);
+}
+
+const findings = [];
+const note = (link, status, detail) => {
+  findings.push({ link, status });
+  const tag = status === "pass" ? PASS : status === "fail" ? FAIL : WARN;
+  console.log(`${tag}  ${link}`);
+  if (detail) console.log(`        ${C.d}${detail}${C.x}`);
+};
+
+async function get(path) {
+  try {
+    const res = await fetch(`${BASE}${path}`, { headers: { Authorization: `Bearer ${TOKEN}` } });
+    let json = null;
+    try { json = await res.json(); } catch { /* non-JSON */ }
+    return { status: res.status, json };
+  } catch (err) {
+    return { status: 0, json: { error: String(err) } };
+  }
+}
+
+console.log(`\nPolar billing diagnostic — ${SERVER} — customer ${CUSTOMER}\n`);
+
+// ── Link 0: token scope ───────────────────────────────────────────────
+const meterScopeProbe = await get(`/v1/meters/?limit=1`);
+const canReadMeters = meterScopeProbe.status === 200;
+if (canReadMeters) {
+  note("token scope: meters:read", "pass");
+} else if (meterScopeProbe.json?.error === "insufficient_scope") {
+  note("token scope: meters:read", "fail",
+    "Token lacks meters:read — meter/price checks below will be skipped. Create a read-scoped token (rule 8).");
+} else {
+  note("token scope: meters:read", "warn", `Unexpected status ${meterScopeProbe.status}.`);
+}
+
+// ── Link 1: customer state (consumed_units — the number that matters) ──
+const state = await get(`/v1/customers/${CUSTOMER}/state`);
+if (state.status !== 200) {
+  note("customer state", "fail", `GET /v1/customers/${CUSTOMER}/state → ${state.status}. Wrong id, env, or customer:read scope.`);
+  summarize();
+  process.exit(0);
+}
+const activeMeters = state.json.active_meters || [];
+const activeSubs = state.json.active_subscriptions || [];
+const totalConsumed = activeMeters.reduce((s, m) => s + (m.consumed_units || 0), 0);
+if (activeMeters.length === 0) {
+  note("customer has an active meter", "fail", "No active_meters on the customer — no metered subscription, or meter not bound to the product price.");
+} else if (totalConsumed > 0) {
+  note("consumed_units > 0 (billing IS flowing)", "pass",
+    activeMeters.map((m) => `meter ${m.meter_id}: consumed=${m.consumed_units}, balance=${m.balance}`).join("; "));
+} else {
+  note("consumed_units > 0", "fail",
+    `consumed_units is 0 across ${activeMeters.length} meter(s) — usage is NOT being counted. Continue below to find why.`);
+}
+
+// ── Link 2: meter filter + aggregation ────────────────────────────────
+const meterIds = METER_ARG ? [METER_ARG] : activeMeters.map((m) => m.meter_id).filter(Boolean);
+let aggProperty = null;
+let filterEventNames = [];
+if (!canReadMeters) {
+  note("meter filter + aggregation", "warn", "Skipped — no meters:read scope.");
+} else if (meterIds.length === 0) {
+  note("meter filter + aggregation", "warn", "No meter id resolved (pass --meter <id>).");
+} else {
+  for (const mid of meterIds) {
+    const m = await get(`/v1/meters/${mid}`);
+    if (m.status !== 200) { note(`meter ${mid}`, "warn", `→ ${m.status}`); continue; }
+    aggProperty = m.json.aggregation?.property ?? null;
+    const func = m.json.aggregation?.func;
+    const clauses = JSON.stringify(m.json.filter);
+    filterEventNames = [...clauses.matchAll(/"value"\s*:\s*"([^"]+)"/g)].map((x) => x[1]);
+    note(`meter "${m.json.name}" config`, "pass",
+      `aggregation: ${func}${aggProperty ? `(metadata.${aggProperty})` : "()"} · filter matches event name(s): ${filterEventNames.join(", ") || "?"}`);
+  }
+}
+
+// ── Link 3: do real events carry the aggregated property? (the typo trap) ──
+const evName = EVENT_NAME || filterEventNames[0];
+const evResp = await get(`/v1/events/?customer_id=${CUSTOMER}&limit=25`);
+if (evResp.status !== 200) {
+  note("events carry the aggregated property", "warn", `Cannot read events → ${evResp.status} (needs events:read).`);
+} else {
+  const items = (evResp.json.items || []).filter((e) => !evName || e.name === evName);
+  if (items.length === 0) {
+    note("recent events exist for this customer", "fail",
+      `No events${evName ? ` named "${evName}"` : ""} found. The app isn't emitting (or wrong name).`);
+  } else {
+    const keys = new Set();
+    items.forEach((e) => Object.keys(e.metadata || {}).forEach((k) => keys.add(k)));
+    const userEvents = items.filter((e) => e.source !== "system");
+    console.log(`        ${C.d}recent "${evName}" event metadata keys: ${[...keys].join(", ")}${C.x}`);
+    if (aggProperty) {
+      const withProp = userEvents.filter((e) => e.metadata && aggProperty in e.metadata).length;
+      if (userEvents.length > 0 && withProp === 0) {
+        note("emitted metadata key matches meter aggregation property", "fail",
+          `Meter sums metadata.${aggProperty} but NONE of the recent events carry that key. THIS is the silent $0 bug (rule 1). Emit "${aggProperty}", or note the locked-in spelling and match it.`);
+      } else if (withProp < userEvents.length) {
+        note("emitted metadata key matches meter aggregation property", "warn",
+          `Only ${withProp}/${userEvents.length} events carry metadata.${aggProperty}. Mixed keys — likely mid-migration.`);
+      } else {
+        note("emitted metadata key matches meter aggregation property", "pass",
+          `All ${userEvents.length} recent events carry metadata.${aggProperty}.`);
+      }
+    } else {
+      note("recent events exist", "pass", `${items.length} event(s); aggregation property unknown (no meters:read) — verify key by hand.`);
+    }
+  }
+}
+
+// ── Link 4: product has a metered price bound to the meter ─────────────
+const productId = activeSubs[0]?.product_id;
+if (!canReadMeters) {
+  note("metered price attached to meter", "warn", "Skipped — no scope to read product.");
+} else if (!productId) {
+  note("metered price attached to meter", "warn", "No active subscription product_id in customer state.");
+} else {
+  const p = await get(`/v1/products/${productId}`);
+  if (p.status !== 200) {
+    note("metered price attached to meter", "warn", `GET product → ${p.status}.`);
+  } else {
+    const prices = p.json.prices || [];
+    const metered = prices.find((pr) => pr.amount_type === "metered_unit");
+    if (!metered) {
+      note("metered price attached to meter", "fail",
+        `Product has prices [${prices.map((pr) => pr.amount_type).join(", ")}] but NO metered_unit price — usage can't bill.`);
+    } else if (meterIds.length && !meterIds.includes(metered.meter_id)) {
+      note("metered price attached to meter", "fail",
+        `Metered price points at meter ${metered.meter_id}, not the customer's active meter(s) ${meterIds.join(",")}.`);
+    } else {
+      note("metered price attached to meter", "pass",
+        `metered_unit price, unit_amount=${metered.unit_amount}, meter_id=${metered.meter_id}.`);
+    }
+  }
+}
+
+// ── Link 5: orders (are invoices actually non-zero?) ──────────────────
+const orders = await get(`/v1/orders/?customer_id=${CUSTOMER}&limit=5`);
+if (orders.status !== 200) {
+  note("orders show non-zero billing", "warn", `Cannot read orders → ${orders.status} (needs orders:read).`);
+} else {
+  const items = orders.json.items || [];
+  const nonZero = items.filter((o) => (o.total_amount ?? 0) > 0).length;
+  if (items.length === 0) {
+    note("orders exist", "warn", "No orders yet (new subscription or pre-first-cycle).");
+  } else if (nonZero > 0) {
+    note("orders show non-zero billing", "pass", `${nonZero}/${items.length} recent orders are non-zero.`);
+  } else if (totalConsumed > 0) {
+    // Usage is accruing now, but these orders are $0 — they predate the fix or
+    // the current cycle hasn't closed. Not a broken link; the next invoice bills.
+    note("orders show non-zero billing", "warn",
+      `All ${items.length} recent orders total $0, but consumed_units=${totalConsumed} now — these orders predate the fix / current cycle hasn't closed. The next invoice will bill the accrued usage.`);
+  } else {
+    note("orders show non-zero billing", "fail",
+      `All ${items.length} recent orders total $0 and consumed_units is 0 — corroborates broken metering above.`);
+  }
+}
+
+summarize();
+
+function summarize() {
+  const fails = findings.filter((f) => f.status === "fail");
+  console.log("");
+  if (fails.length === 0) {
+    console.log(`${C.g}Billing chain looks intact.${C.x} If invoices are still $0, check sandbox-vs-production (rule 7) and that you're inspecting the right environment.`);
+  } else {
+    console.log(`${C.r}Broken link(s):${C.x} ${fails.map((f) => f.link).join("  |  ")}`);
+    console.log(`${C.d}Fix the first broken link, re-emit one event, and re-run this to confirm consumed_units increments (no backfill — rule 4).${C.x}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "2.5.6",
+  "version": "2.6.0",
   "description": "AI development toolkit for Claude Code — ideate, resolve, and ship with context engineering and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {

package/scripts/lint-skills.sh

@@ -242,10 +242,11 @@ if [ ! -e "optional-skills/devlyn:design-ui" ]; then
 else
   bad "devlyn:design-ui must not be installed as an optional addon"
 fi
-if grep -Fq "skillsToInstall: ['devlyn:resolve', 'devlyn:ideate', 'devlyn:design-ui', '_shared']" bin/devlyn.js; then
-  ok "Codex install includes devlyn:design-ui"
+if grep -Fq "const DEVLYN_CORE_SKILLS = ['devlyn:resolve', 'devlyn:ideate', 'devlyn:design-ui', '_shared'];" bin/devlyn.js \
+   && grep -Fq "skillsToInstall: DEVLYN_CORE_SKILLS" bin/devlyn.js; then
+  ok "Codex install includes devlyn:design-ui (via shared DEVLYN_CORE_SKILLS bundle)"
 else
-  bad "Codex skillsToInstall must include devlyn:design-ui"
+  bad "Codex skillsToInstall must include devlyn:design-ui (shared DEVLYN_CORE_SKILLS bundle)"
 fi
 if ! grep -F "name: 'devlyn:design-ui'" bin/devlyn.js >/dev/null 2>&1; then
   ok "devlyn:design-ui is absent from OPTIONAL_ADDONS"