thumbgate 1.21.2 → 1.23.0

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "thumbgate-marketplace",
-  "version": "1.21.2",
+  "version": "1.23.0",
   "owner": {
     "name": "Igor Ganapolsky",
     "email": "ig5973700@gmail.com"
@@ -14,7 +14,7 @@
         "source": "npm",
         "package": "thumbgate"
       },
-      "version": "1.21.2",
+      "version": "1.23.0",
       "author": {
         "name": "Igor Ganapolsky",
         "email": "ig5973700@gmail.com",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "thumbgate",
   "description": "One 👎 becomes a hard rule the agent cannot bypass. Captures thumbs-down feedback, distills it into PreToolUse Pre-Action Checks, enforced across every future Claude Code session.",
-  "version": "1.21.2",
+  "version": "1.23.0",
   "author": {
     "name": "Igor Ganapolsky",
     "email": "ig5973700@gmail.com",

package/.well-known/mcp/server-card.json

@@ -1,6 +1,6 @@
 {
   "name": "thumbgate",
-  "version": "1.21.2",
+  "version": "1.23.0",
   "description": "ThumbGate — 👍👎 feedback that teaches your AI agent. Thumbs down a mistake, it never happens again.",
   "homepage": "https://thumbgate-production.up.railway.app",
   "transport": "stdio",

package/README.md

@@ -474,6 +474,7 @@ Pro ($19/mo or $149/yr) removes the rule cap and adds history-aware lesson recal
 - [Agent Workflow Contract](WORKFLOW.md) — the agent-run contract for all ThumbGate operations
 - [Ready for Agent Intake](https://github.com/IgorGanapolsky/ThumbGate/issues/new?template=ready-for-agent.yml) — ready-for-agent intake template
 - [SEO Guide: Claude Code Guardrails](docs/learn/claude-code-guardrails.md)
+- [Unsupervised Learning Signals](docs/UL.md) — silent-failure clustering (experimental, behind `THUMBGATE_SILENT_FAILURE_CLUSTERING=1`; only useful on workspaces with ≥ 50 tool calls/day)
 - [ThumbGate-Core](https://github.com/IgorGanapolsky/ThumbGate-Core) — private core for hosted overlays, ranking, policy synthesis, billing intelligence, and org/team workflows
 
 ---

package/adapters/chatgpt/openapi.yaml

@@ -72,6 +72,11 @@ components:
           description: Optional domain tags. If omitted, ThumbGate infers one from the feedback text before promotion.
         skill:
           type: string
+        source:
+          type: string
+          enum: [chatgpt_gpt]
+          default: chatgpt_gpt
+          description: Attribution marker for ThumbGate analytics. The published ThumbGate GPT should send `chatgpt_gpt` so owner dashboards can distinguish GPT Action calls from local API calls.
     IntentPlanRequest:
       type: object
       required: [intentId]
@@ -880,6 +885,11 @@ paths:
                 toolName:
                   type: string
                   description: Tool name is optional when provider-native tool call payload is supplied.
+                source:
+                  type: string
+                  enum: [chatgpt_gpt]
+                  default: chatgpt_gpt
+                  description: Attribution marker for ThumbGate analytics. The published ThumbGate GPT should send `chatgpt_gpt` so owner dashboards can distinguish GPT Action calls from local API calls.
                 provider:
                   type: string
                 model:

package/adapters/claude/.mcp.json

@@ -2,13 +2,13 @@
   "mcpServers": {
     "thumbgate": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.21.2", "thumbgate", "serve"]
+      "args": ["--yes", "--package", "thumbgate@1.23.0", "thumbgate", "serve"]
     }
   },
   "hooks": {
     "preToolUse": {
       "command": "npx",
-      "args": ["--yes", "--package", "thumbgate@1.21.2", "thumbgate", "gate-check"]
+      "args": ["--yes", "--package", "thumbgate@1.23.0", "thumbgate", "gate-check"]
     }
   }
 }

package/adapters/mcp/server-stdio.js

@@ -216,7 +216,7 @@ const {
   finalizeSession: finalizeFeedbackSession,
 } = require('../../scripts/feedback-session');
 
-const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.21.2' };
+const SERVER_INFO = { name: 'thumbgate-mcp', version: '1.23.0' };
 const COMMERCE_CATEGORIES = [
   'product_recommendation',
   'brand_compliance',
@@ -368,6 +368,111 @@ function buildRecallResponse(args = {}) {
   return toTextResult(text);
 }
 
+function buildSuggestFixResponse(args = {}) {
+  const context = String(args.context || '').trim();
+  const rawLimit = Number(args.limit);
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, 5) : 3;
+
+  // If no context provided, return generic suggestion
+  if (!context) {
+    return toTextResult({
+      suggestions: [
+        {
+          action: 'Capture feedback about what went wrong so ThumbGate can learn and prevent recurrence.',
+          source: 'generic',
+        },
+      ],
+      query: '',
+      totalFound: 0,
+    });
+  }
+
+  // Search lessons via lesson-search module
+  const lessonModule = loadPrivateMcpModule('lessonSearch');
+  let lessonActions = [];
+  if (lessonModule) {
+    try {
+      const searchResult = lessonModule.searchLessons(context, { limit: 10 });
+      const results = Array.isArray(searchResult && searchResult.results) ? searchResult.results : [];
+      for (const result of results) {
+        const correctiveActions = (result.systemResponse && Array.isArray(result.systemResponse.correctiveActions))
+          ? result.systemResponse.correctiveActions
+          : [];
+        for (const action of correctiveActions) {
+          const text = String(action.text || '').trim();
+          if (text) {
+            lessonActions.push({
+              action: text,
+              source: action.source || `lesson:${result.id || 'unknown'}`,
+              score: result.score || 0,
+            });
+          }
+        }
+        // Also pick up lesson-level howToAvoid / actionNeeded when no explicit correctiveActions
+        if (correctiveActions.length === 0 && result.lesson) {
+          const text = result.lesson.howToAvoid || result.lesson.actionNeeded || '';
+          if (text) {
+            lessonActions.push({
+              action: String(text).trim(),
+              source: `lesson:${result.id || 'unknown'}`,
+              score: result.score || 0,
+            });
+          }
+        }
+      }
+    } catch {
+      // lesson search failure is non-fatal
+    }
+  }
+
+  // Search prevention rules directly via lesson-search module's helper
+  let ruleActions = [];
+  try {
+    const { readPreventionRuleMatches } = require('../../scripts/lesson-search');
+    const ruleMatches = readPreventionRuleMatches(context, limit);
+    for (const rule of ruleMatches) {
+      const text = rule.summary || rule.title || '';
+      if (text) {
+        ruleActions.push({
+          action: String(text).trim(),
+          source: `rule:${String(rule.title || 'prevention_rules').trim()}`,
+          score: rule.score || 0,
+        });
+      }
+    }
+  } catch {
+    // rule search failure is non-fatal
+  }
+
+  // Merge, deduplicate, sort by score, and take top `limit`
+  const seen = new Set();
+  const all = [...lessonActions, ...ruleActions]
+    .filter((item) => {
+      if (!item.action) return false;
+      const key = item.action.toLowerCase();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) => (b.score || 0) - (a.score || 0))
+    .slice(0, limit)
+    .map(({ action, source }) => ({ action, source }));
+
+  // If nothing matched, add generic fallback
+  if (all.length === 0) {
+    all.push({
+      action: 'No matching lessons or rules found. Capture feedback via capture_feedback so ThumbGate can learn from this failure.',
+      source: 'generic',
+    });
+  }
+
+  return toTextResult({
+    suggestions: all,
+    query: context,
+    totalFound: all.length,
+  });
+}
+
 function buildDiagnoseFailureResponse(args = {}) {
   let intentPlan = null;
   const requestedProfile = args.mcpProfile || getActiveMcpProfile();
@@ -579,6 +684,8 @@ async function callToolInner(name, args) {
         tags: Array.isArray(args.tags) ? args.tags : [],
       }));
     }
+    case 'suggest_fix':
+      return buildSuggestFixResponse(args);
     case 'retrieve_lessons': {
       // Cross-encoder reranking: retrieve more candidates, then rerank for precision
       const { retrieveWithRerankingSync } = loadOptionalModule(path.join(__dirname, '../../scripts/cross-encoder-reranker'), () => ({
@@ -1330,6 +1437,7 @@ module.exports = {
   acquireLock,
   toCaptureFeedbackTextResult,
   formatCorrectiveActionsReminder,
+  buildSuggestFixResponse,
   __test__: {
     PRIVATE_MCP_MODULES,
     loadPrivateMcpModule,

package/adapters/opencode/opencode.json

@@ -7,7 +7,7 @@
         "npx",
         "--yes",
         "--package",
-        "thumbgate@1.21.2",
+        "thumbgate@1.23.0",
         "thumbgate",
         "serve"
       ],

package/bin/cli.js

@@ -52,6 +52,25 @@ const PKG_ROOT = path.join(__dirname, '..');
 
 const PRO_URL = 'https://thumbgate-production.up.railway.app';
 const PRO_CHECKOUT_URL = PRO_MONTHLY_PAYMENT_LINK;
+const TRIAL_DAYS = 14;
+
+function checkoutUrlFor(source, content) {
+  try {
+    const url = new URL(PRO_CHECKOUT_URL);
+    url.searchParams.set('utm_source', source || 'cli');
+    url.searchParams.set('utm_medium', 'cli');
+    url.searchParams.set('utm_campaign', 'pro_conversion');
+    if (content) url.searchParams.set('utm_content', content);
+    return url.toString();
+  } catch (_) {
+    return PRO_CHECKOUT_URL;
+  }
+}
+
+function trialDeadlineLabel(now = new Date()) {
+  const deadline = new Date(now.getTime() + (TRIAL_DAYS * 24 * 60 * 60 * 1000));
+  return deadline.toISOString().slice(0, 10);
+}
 
 function upgradeNudge() {
   if (process.env.THUMBGATE_NO_NUDGE === '1') return;
@@ -139,25 +158,46 @@ function proNudge(context) {
     const { isProTier } = require(path.join(PKG_ROOT, 'scripts', 'rate-limiter'));
     if (isProTier()) return;
   } catch (_) { /* if rate-limiter is unavailable, fall through and nudge */ }
+  const checkoutUrl = checkoutUrlFor('cli_nudge', context || COMMAND || 'general');
   const messages = [
-    `\n  💡 Unlock Pro (${PRO_PRICE_LABEL}): searchable dashboard, DPO export, multi-repo sync\n     ${PRO_CHECKOUT_URL}\n`,
-    `\n  💡 Pro tip: export your feedback as DPO training pairs to improve your models.\n     Get Pro: ${PRO_CHECKOUT_URL}\n`,
-    `\n  💡 ThumbGate Pro: search, edit, and sync lessons across repos. ${PRO_PRICE_LABEL}.\n     ${PRO_CHECKOUT_URL}\n`,
+    `\n  💡 Unlock Pro (${PRO_PRICE_LABEL}): searchable dashboard, DPO export, multi-repo sync\n     ${checkoutUrl}\n`,
+    `\n  💡 Pro tip: export your feedback as DPO training pairs to improve your models.\n     Get Pro: ${checkoutUrl}\n`,
+    `\n  💡 ThumbGate Pro: search, edit, and sync lessons across repos. ${PRO_PRICE_LABEL}.\n     ${checkoutUrl}\n`,
   ];
   // Rotate message daily — no Math.random (security policy)
   const msg = messages[Math.floor(Date.now() / 86400000) % messages.length];
   process.stderr.write(msg);
 }
 
-function limitNudge(action) {
+function limitNudge(action, limitResult = {}) {
   if (process.env.THUMBGATE_NO_NUDGE === '1') return;
+  const checkoutUrl = checkoutUrlFor('cli_limit', action);
+  const usageLine = Number.isFinite(limitResult.used) && Number.isFinite(limitResult.limit)
+    ? `     Usage: ${limitResult.used}/${limitResult.limit} (${limitResult.limitType || 'limit'}).\n`
+    : '';
+  const reason = limitResult.message
+    ? String(limitResult.message).split('\n')[0]
+    : 'Free tier limit reached.';
   process.stderr.write(
-    `\n  ⚠️  Free tier limit reached. Upgrade to Pro for unlimited: https://thumbgate-production.up.railway.app/pro\n` +
-    `     ${action} daily limit reached. Upgrade to Pro for unlimited usage — ${PRO_PRICE_LABEL}:\n` +
-    `     ${PRO_CHECKOUT_URL}\n\n`
+    `\n  🔒 ${reason}\n` +
+    usageLine +
+    `     Upgrade to Pro (${PRO_PRICE_LABEL}) to continue ${action.replace(/_/g, ' ')}:\n` +
+    `     ${checkoutUrl}\n\n`
   );
 }
 
+function printInitConversionPrompt(email) {
+  if (process.env.THUMBGATE_NO_NUDGE === '1') return;
+  const checkoutUrl = checkoutUrlFor('cli_init', email ? 'init_email' : 'init_no_email');
+  console.log('');
+  console.log('  ┌──────────────────────────────────────────────────────────┐');
+  console.log(`  │  14-day Pro trial active through ${trialDeadlineLabel()}.              │`);
+  console.log('  │  Pro unlocks lesson search, recall, dashboard, exports. │');
+  console.log('  │  Add onboarding: npx thumbgate init --email you@company.com │');
+  console.log(`  │  Upgrade: ${checkoutUrl}`);
+  console.log('  └──────────────────────────────────────────────────────────┘');
+}
+
 function parseArgs(argv) {
   const args = {};
   argv.forEach((arg, index) => {
@@ -613,6 +653,18 @@ function quickStart() {
 
 function init(cliArgs = parseArgs(process.argv.slice(3))) {
   const args = { ...cliArgs };
+  if (args.help || args.h) {
+    console.log('Usage: npx thumbgate init [--agent <name>] [--wire-hooks] [--email you@company.com]');
+    console.log('');
+    console.log('Scaffold ThumbGate in the current project and wire detected agent integrations.');
+    console.log('');
+    console.log('Options:');
+    console.log('  --agent <name>           Wire a specific agent: claude-code, codex, gemini, amp, cursor, cline');
+    console.log('  --wire-hooks             Wire hooks only; do not scaffold project files');
+    console.log('  --email <email>          Subscribe installer to the setup guide and trial reminders');
+    console.log('  --dry-run                Show hook changes without writing them');
+    return;
+  }
 
   // --wire-hooks only mode: skip scaffolding, just wire hooks
   if (args['wire-hooks']) {
@@ -746,16 +798,48 @@ function init(cliArgs = parseArgs(process.argv.slice(3))) {
   }
 
   console.log('');
-  console.log(`thumbgate v${pkgVersion()} initialized.`);
-  console.log('Run: npx thumbgate help');
+  console.log(`✅ thumbgate v${pkgVersion()} initialized.`);
+  const onboardingEmail = typeof args.email === 'string'
+    ? args.email.trim()
+    : (typeof args['onboarding-email'] === 'string' ? args['onboarding-email'].trim() : '');
+  if (onboardingEmail) {
+    try {
+      execFileSync(process.execPath, [__filename, 'subscribe', onboardingEmail], {
+        cwd: CWD,
+        env: process.env,
+        stdio: 'inherit',
+      });
+      trackEvent('cli_init_email_subscribed', { command: 'init', source: 'init_email' });
+    } catch (_) {
+      console.log(`  Retry onboarding email: npx thumbgate subscribe ${onboardingEmail}`);
+    }
+  }
   trackEvent('cli_init', { command: 'init' });
-  proNudge();
+
+  // ---------------------------------------------------------------------------
+  // Activation guide: the ONE thing the user should do next.
+  // 98.5% of init users never promote their first prevention rule.
+  // This is the funnel break — not conversion, not nudges — activation.
+  // ---------------------------------------------------------------------------
   console.log('');
-  console.log('  ┌──────────────────────────────────────────────────────────┐');
-  console.log('  │  Teams: shared enforcement, CI gates, audit trails      │');
-  console.log('  │  One correction protects every agent on your team.      │');
-  console.log('  │  https://thumbgate-production.up.railway.app/pro        │');
-  console.log('  └──────────────────────────────────────────────────────────┘');
+  console.log('  ╭──────────────────────────────────────────────────────────╮');
+  console.log('  │  NEXT: Create your first prevention rule (30 seconds)   │');
+  console.log('  │                                                         │');
+  console.log('  │  When your AI agent makes a mistake, capture it:        │');
+  console.log('  │                                                         │');
+  console.log('  │  npx thumbgate capture --feedback=down \\               │');
+  console.log('  │    --context="agent deleted prod config" \\              │');
+  console.log('  │    --what-went-wrong="ran rm on .env" \\                 │');
+  console.log('  │    --what-to-change="never delete .env files"           │');
+  console.log('  │                                                         │');
+  console.log('  │  ThumbGate auto-promotes this to a prevention rule      │');
+  console.log('  │  that blocks the mistake from happening again.          │');
+  console.log('  ╰──────────────────────────────────────────────────────────╯');
+  console.log('');
+  printInitConversionPrompt(onboardingEmail);
+  if (!onboardingEmail) {
+    console.log('  Get trial reminders: npx thumbgate init --email you@company.com');
+  }
 
   try {
     const { appendFunnelEvent } = require(path.join(PKG_ROOT, 'scripts', 'billing'));
@@ -785,7 +869,7 @@ function capture() {
   const { getUsage } = require(path.join(PKG_ROOT, 'scripts', 'rate-limiter'));
   const capLimit = checkLimit('capture_feedback');
   if (!capLimit.allowed) {
-    limitNudge('capture_feedback');
+    limitNudge('capture_feedback', capLimit);
     process.exit(1);
   }
   trackEvent('cli_capture', { command: 'capture' });
@@ -878,7 +962,14 @@ function stats() {
   const { analyzeFeedback } = require(path.join(PKG_ROOT, 'scripts', 'feedback-loop'));
   const data = analyzeFeedback();
 
+  // Gate enforcement stats — runtime intercepts + configured gates
+  let gateData = { blocked: 0, warned: 0, passed: 0, byGate: {} };
+  try { gateData = require(path.join(PKG_ROOT, 'scripts', 'gates-engine')).loadStats(); } catch {}
+  let gateConfigData = { totalGates: 0, autoPromotedGates: 0, estimatedHoursSaved: '0.0', topBlocked: null, firstTimeFixRate: null };
+  try { gateConfigData = require(path.join(PKG_ROOT, 'scripts', 'gate-stats')).calculateStats(); } catch {}
+
   const avgCostOfMistake = 2.50;
+  const totalInterceptions = gateData.blocked + gateData.warned;
   const payload = {
     total: data.total,
     positives: data.totalPositive,
@@ -888,6 +979,13 @@ function stats() {
     revenueAtRisk: Number((data.totalNegative * avgCostOfMistake).toFixed(2)),
     topTags: data.topTags || [],
     recentActivity: data.recentActivity || [],
+    gatesBlocked: gateData.blocked,
+    gatesWarned: gateData.warned,
+    totalGates: gateConfigData.totalGates,
+    autoPromotedGates: gateConfigData.autoPromotedGates,
+    estimatedHoursSaved: gateConfigData.estimatedHoursSaved,
+    topBlockedGate: gateConfigData.topBlocked ? gateConfigData.topBlocked.id : null,
+    firstTimeFixRate: gateConfigData.firstTimeFixRate,
   };
 
   if (args.json) {
@@ -901,6 +999,18 @@ function stats() {
   console.log(`  Approval Rate   : ${payload.approvalRate}%`);
   console.log(`  Recent Trend    : ${payload.recentTrend}%`);
 
+  // Gate enforcement — the high-ROI section
+  if (totalInterceptions > 0 || payload.totalGates > 0) {
+    console.log('\n🛡️  PRE-ACTION GATE ENFORCEMENT');
+    console.log(`  Actions blocked : ${payload.gatesBlocked}`);
+    console.log(`  Actions warned  : ${payload.gatesWarned}`);
+    console.log(`  Active gates    : ${payload.totalGates} (${payload.autoPromotedGates} auto-promoted)`);
+    if (payload.topBlockedGate) console.log(`  Top blocker     : ${payload.topBlockedGate}`);
+    console.log(`  Est. time saved : ~${payload.estimatedHoursSaved} hours`);
+    const { formatFirstTimeFixRate } = require(path.join(PKG_ROOT, 'scripts', 'gate-stats'));
+    console.log(`  First-time fix  : ${formatFirstTimeFixRate(payload.firstTimeFixRate)}`);
+  }
+
   if (payload.negatives > 0) {
     console.log('\n⚠️  REVENUE-AT-RISK ANALYSIS');
     console.log(`  Repeated Failures detected: ${payload.negatives}`);
@@ -1161,6 +1271,13 @@ function lessons() {
   const tags = String(args.tags || '').split(',').map((t) => t.trim()).filter(Boolean);
   const query = args.query || process.argv.slice(3).find((a) => !a.startsWith('--')) || '';
   const limit = Number(args.limit || 10);
+  const { checkLimit } = require(path.join(PKG_ROOT, 'scripts', 'rate-limiter'));
+  const searchLimit = checkLimit('search_lessons');
+  if (!searchLimit.allowed) {
+    trackEvent('cli_upgrade_prompt', { command: 'lessons', action: 'search_lessons', limitType: searchLimit.limitType || null });
+    limitNudge('search_lessons', searchLimit);
+    process.exit(1);
+  }
 
   // --remote: fetch from hosted Railway instance
   if (args.remote) {
@@ -1427,13 +1544,10 @@ function risk() {
 }
 
 function exportDpo() {
-  const { isProTier } = require(path.join(PKG_ROOT, 'scripts', 'rate-limiter'));
-  if (!isProTier(null)) {
-    process.stderr.write(
-      `\n  🔒 DPO Export requires Pro (${PRO_PRICE_LABEL}).\n` +
-      `     Your feedback would generate valuable training pairs.\n` +
-      `     Upgrade: ${PRO_CHECKOUT_URL}\n\n`
-    );
+  const { checkLimit } = require(path.join(PKG_ROOT, 'scripts', 'rate-limiter'));
+  const exportLimit = checkLimit('export_dpo');
+  if (!exportLimit.allowed) {
+    limitNudge('export_dpo', exportLimit);
     process.exit(1);
   }
   const extraArgs = process.argv.slice(3).join(' ');
@@ -1450,13 +1564,10 @@ function exportDpo() {
 }
 
 function exportDatabricks() {
-  const { isProTier } = require(path.join(PKG_ROOT, 'scripts', 'rate-limiter'));
-  if (!isProTier(null)) {
-    process.stderr.write(
-      `\n  🔒 Databricks Export requires Pro (${PRO_PRICE_LABEL}).\n` +
-      `     Export feedback logs + proof artifacts for analytics.\n` +
-      `     Upgrade: ${PRO_CHECKOUT_URL}\n\n`
-    );
+  const { checkLimit } = require(path.join(PKG_ROOT, 'scripts', 'rate-limiter'));
+  const exportLimit = checkLimit('export_databricks');
+  if (!exportLimit.allowed) {
+    limitNudge('export_databricks', exportLimit);
     process.exit(1);
   }
   const extraArgs = process.argv.slice(3).join(' ');
@@ -1684,6 +1795,25 @@ function gateStats() {
   console.log('\n' + formatStats(stats) + '\n');
 }
 
+function contextPacks() {
+  const args = parseArgs(process.argv.slice(3));
+  const { generateAutoContextPacks } = require(path.join(PKG_ROOT, 'scripts', 'auto-context-packs'));
+  const result = generateAutoContextPacks();
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`\nGenerated ${result.packCount} context pack(s):`);
+  for (const p of result.packs) {
+    console.log(`  [${p.type}] ${p.name}`);
+    console.log(`    -> ${p.filePath}`);
+  }
+  if (result.packCount === 0) {
+    console.log('  (No failure patterns found yet — capture some feedback first.)');
+  }
+  console.log('');
+}
+
 function harnessAudit() {
   const args = parseArgs(process.argv.slice(3));
   const {
@@ -2416,6 +2546,39 @@ if (COMMAND === 'daemon' || COMMAND === 'serve-daemon') {
   process.exit(0);
 }
 
+// ---------------------------------------------------------------------------
+// Global --help interceptor: `thumbgate <cmd> --help` shows per-command help
+// instead of running the command. Commands with their own --help guard (init)
+// handle it internally; everything else falls through here.
+// ---------------------------------------------------------------------------
+const _cliSubArgs = process.argv.slice(3);
+const _wantsHelp = _cliSubArgs.includes('--help') || _cliSubArgs.includes('-h');
+
+const SUBCOMMAND_HELP = {
+  capture:       'Usage: npx thumbgate capture --feedback=up|down --context="..." [--what-worked="..."] [--what-went-wrong="..."] [--what-to-change="..."] [--tags=a,b]',
+  feedback:      'Usage: npx thumbgate feedback --feedback=up|down --context="..." [--what-worked="..."] [--what-went-wrong="..."] [--what-to-change="..."] [--tags=a,b]',
+  stats:         'Usage: npx thumbgate stats\n\nShow gate enforcement statistics: blocked/warned counts, active gates, time saved.',
+  trial:         'Usage: npx thumbgate trial\n\nShow Pro trial status, remaining days, and upgrade path.',
+  pro:           'Usage: npx thumbgate pro [--activate <key>]\n\nLaunch the local Pro dashboard or activate a Pro license key.',
+  subscribe:     'Usage: npx thumbgate subscribe <email>\n\nSubscribe to the 5-minute setup guide + trial reminders.',
+  lessons:       'Usage: npx thumbgate lessons [--query="..."] [--limit=N]\n\nSearch the lesson database (Pro feature).',
+  search:        'Usage: npx thumbgate search <query>\n\nSearch ThumbGate knowledge base (Pro feature).',
+  'gate-check':  'Usage: npx thumbgate gate-check\n\nPreToolUse hook interface: reads tool call JSON from stdin, outputs gate verdict.',
+  'export-dpo':  'Usage: npx thumbgate export-dpo [--format=jsonl|csv]\n\nExport feedback as DPO training pairs (Pro feature).',
+  status:        'Usage: npx thumbgate status\n\nShow ThumbGate system health and active configuration.',
+  watch:         'Usage: npx thumbgate watch\n\nWatch for feedback changes and auto-regenerate prevention rules.',
+  compact:       'Usage: npx thumbgate compact\n\nCompact the lesson database and reclaim disk space.',
+  'context-packs': 'Usage: npx thumbgate context-packs\n\nGenerate context packs from top failure patterns.',
+  suggest:       'Usage: npx thumbgate suggest <gate-id>\n\nSuggest fixes for a specific gate based on lesson history.',
+  cost:          'Usage: npx thumbgate cost [--json] [--stats <path>] [--mix \'{"claude-sonnet-4-5":0.8,...}\']\n\nShow cumulative $ and tokens saved by PreToolUse gate blocks. Reads ~/.thumbgate/gate-stats.json.',
+  savings:       'Usage: npx thumbgate savings [--json] [--stats <path>] [--mix \'{"claude-sonnet-4-5":0.8,...}\']\n\nAlias for `thumbgate cost`.',
+};
+
+if (_wantsHelp && COMMAND && SUBCOMMAND_HELP[COMMAND]) {
+  console.log(SUBCOMMAND_HELP[COMMAND]);
+  process.exit(0);
+}
+
 switch (COMMAND) {
   case '--version':
   case '-v':
@@ -2470,6 +2633,17 @@ switch (COMMAND) {
   case 'revenue':
     cfo();
     break;
+  case 'cost':
+  case 'savings':
+  case 'costs': {
+    const { main: costMain } = require(path.join(PKG_ROOT, 'scripts', 'cost-cli'));
+    process.exit(costMain(process.argv.slice(3)));
+    // process.exit doesn't return, but keep an explicit break so the switch
+    // cannot accidentally fall through to case 'billing:setup' if a future
+    // refactor wraps costMain in try/finally that intercepts the exit, or
+    // a test runner stubs process.exit (flagged by gitar-bot on PR #2281).
+    break;
+  }
   case 'billing:setup':
     require(path.join(PKG_ROOT, 'scripts', 'billing-setup'));
     break;
@@ -2486,6 +2660,11 @@ switch (COMMAND) {
   case 'search-lessons':
     lessons();
     break;
+  case 'notes': {
+    const { cli: notesCli } = require(path.join(PKG_ROOT, 'scripts', 'implementation-notes'));
+    notesCli(process.argv.slice(3));
+    break;
+  }
   case 'lesson-health':
   case 'stale': {
     const { initDB } = require(path.join(PKG_ROOT, 'scripts', 'lesson-db'));
@@ -2627,6 +2806,9 @@ switch (COMMAND) {
   case 'rules':
     rules();
     break;
+  case 'context-packs':
+    contextPacks();
+    break;
   case 'harness-audit':
   case 'harness':
     harnessAudit();
@@ -2720,6 +2902,41 @@ switch (COMMAND) {
   case 'self-heal':
     selfHeal();
     break;
+  case 'trial': {
+    // Show trial status — connects the 4K monthly npm installers to checkout
+    const { isProTier, isInTrialPeriod, trialDaysRemaining, getInstallAgeDays } = require(path.join(PKG_ROOT, 'scripts', 'rate-limiter'));
+    const ageDays = getInstallAgeDays();
+    const inTrial = isInTrialPeriod();
+    const remaining = trialDaysRemaining();
+    const isPro = isProTier();
+    console.log('');
+    console.log('  ThumbGate Pro Trial');
+    console.log('  ──────────────────');
+    if (isPro && !inTrial) {
+      console.log('  Status: ✅ Pro (active license or API key)');
+    } else if (inTrial) {
+      const expiryDate = new Date(Date.now() + remaining * 86400000).toLocaleDateString('en-US', { month: 'long', day: 'numeric', year: 'numeric' });
+      console.log(`  Status: 🎁 Active (${remaining} day${remaining === 1 ? '' : 's'} remaining)`);
+      console.log(`  Expires: ${expiryDate}`);
+      console.log('');
+      console.log('  All Pro features unlocked:');
+      console.log('    • Unlimited prevention rules (free tier: 5)');
+      console.log('    • Recall, lesson search, DPO export');
+      console.log('    • Cross-machine sync via API key');
+    } else {
+      console.log('  Status: ⏰ Expired');
+      if (ageDays !== null) {
+        console.log(`  Installed: ${Math.floor(ageDays)} days ago`);
+      }
+      console.log('');
+      console.log('  Free tier: 5 active rules, no recall/search/export');
+    }
+    console.log('');
+    console.log(`  Keep Pro: ${PRO_CHECKOUT_URL}`);
+    console.log(`  Or set: THUMBGATE_API_KEY=<your-key>`);
+    console.log('');
+    break;
+  }
   case 'pro':
     pro();
     break;