thumbgate 1.37.2 → 1.37.3

package/scripts/typesafe-typed-questions.js

@@ -16,20 +16,27 @@
  *   3. Code owns route() (pass | review | block) — the model does not emit the verdict
  *   4. Confidence is a second axis; low confidence on high-stakes fails closed
  *
- * Does NOT install typesafe-sdk, call api.typesafe.ai, clone Jev, or wire
- * an LLM adjudicator (#3690 / #3687, ECI pause). Deterministic matchers
- * answer the battery; existing PreToolUse / gate-check remains the enforcer.
+ * Does NOT install typesafe-sdk, clone Jev, or wire an LLM adjudicator
+ * (#3690 / #3687, ECI pause) as the PreToolUse gate. Deterministic matchers
+ * own route(). Optional `--live` shadows the same battery against
+ * POST /v1/systemone (Jev) for calibration — never as the verdict.
  */
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 
 const SOURCE_URLS = Object.freeze([
   'https://console.typesafe.ai/hook',
+  'https://docs.typesafe.ai/api',
   'https://docs.typesafe.ai/cookbooks/llm_guardrails.md',
   'https://docs.typesafe.ai/patterns/confidence-routing.md',
 ]);
 
+const SYSTEMONE_URL = 'https://api.typesafe.ai/v1/systemone';
+const PARALLEL_QUESTIONS_COOKBOOK = 'https://docs.typesafe.ai/cookbooks/parallel_questions';
+const SHADOW_NOUL_DELTA = 0.4;
+
 const TYPED_KINDS = Object.freeze(['noul', 'choice', 'score']);
 const ROUTE_PRECEDENCE = Object.freeze(['block', 'review', 'pass']);
 const ROUTE_ACTIONS = Object.freeze(['block', 'review', 'pass']);
@@ -132,6 +139,7 @@ const DEFAULT_BATTERY = Object.freeze({
 });
 
 const RAIL_MAP = Object.freeze([
+  { typesafe: 'one POST with all N questions (parallel_questions cookbook)', thumbgate: '--live sends the whole battery once; --fan-out-questions is refused' },
   { typesafe: 'noul (one hazard each)', thumbgate: 'existing secret / destructive / outbound / tamper matchers' },
   { typesafe: 'choice over a closed set', thumbgate: 'hazard_family composed in code from which noul fired' },
   { typesafe: 'score rubric', thumbgate: 'severity 0–3 from the same matchers' },
@@ -441,11 +449,299 @@ function normalizeOptions(raw = {}) {
     useTypesafeApi: normalizeBoolean(raw['use-typesafe-api'] || raw.useTypesafeApi),
     llmAdjudicate: normalizeBoolean(raw['llm-adjudicate'] || raw.llmAdjudicate),
     modelEmittedVerdict: raw['model-emitted-verdict'] || raw.modelEmittedVerdict || null,
+    live: normalizeBoolean(raw.live),
+    fanOutQuestions: normalizeBoolean(raw['fan-out-questions'] || raw.fanOutQuestions),
+    apiKey: Object.prototype.hasOwnProperty.call(raw, 'apiKey')
+      ? raw.apiKey
+      : (raw['api-key'] || undefined),
+    fetchImpl: typeof raw.fetchImpl === 'function' ? raw.fetchImpl : undefined,
     strict: normalizeBoolean(raw.strict),
     json: normalizeBoolean(raw.json),
   };
 }
 
+function loadTypesafeApiKey() {
+  const env = process.env.TYPESAFE_API_KEY;
+  if (env && String(env).trim()) return String(env).trim();
+  const fallback = path.join(os.homedir(), '.resume_secrets', 'TYPESAFE_API_KEY');
+  if (!fs.existsSync(fallback)) return null;
+  const text = fs.readFileSync(fallback, 'utf8').trim();
+  return text || null;
+}
+
+function parallelReceipt(questions, usage) {
+  const questionCount = Object.keys(questions || {}).length;
+  const inputTokens = usage && usage.input_tokens != null ? Number(usage.input_tokens) : null;
+  const estimatedFanoutInputTokens = inputTokens != null && questionCount > 0
+    ? inputTokens * questionCount
+    : null;
+  return {
+    cookbook: PARALLEL_QUESTIONS_COOKBOOK,
+    batchedCalls: 1,
+    questionCount,
+    estimatedFanoutCalls: questionCount,
+    inputTokens,
+    estimatedFanoutInputTokens,
+    estimatedTokenFactor: questionCount || null,
+    note: 'Estimated fan-out cost is N× this call\'s input tokens (document-dominated). Not a measured 12.2× cookbook number.',
+  };
+}
+
+function questionsForApi(battery) {
+  const out = {};
+  for (const [id, question] of Object.entries(battery || {})) {
+    if (!question || typeof question !== 'object') continue;
+    const type = String(question.type || '').toLowerCase();
+    if (!TYPED_KINDS.includes(type) || !question.instructions) continue;
+    const entry = { type, instructions: question.instructions };
+    if (question.criteria != null) entry.criteria = question.criteria;
+    out[id] = entry;
+  }
+  return out;
+}
+
+async function callSystemOne({
+  state,
+  questions,
+  apiKey,
+  model = 'jev-latest',
+  fetchImpl,
+} = {}) {
+  if (!apiKey) {
+    const err = new Error('missing_api_key');
+    err.code = 'missing_api_key';
+    throw err;
+  }
+  const fetchFn = typeof fetchImpl === 'function' ? fetchImpl : globalThis.fetch;
+  if (typeof fetchFn !== 'function') {
+    const err = new Error('fetch_unavailable');
+    err.code = 'fetch_unavailable';
+    throw err;
+  }
+  const res = await fetchFn(SYSTEMONE_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ state, model, questions }),
+  });
+  const text = await res.text();
+  let body = null;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = null;
+  }
+  if (!res.ok) {
+    const err = new Error(`systemone_http_${res.status}`);
+    err.code = res.status === 401 ? 'live_unauthorized' : 'live_http_error';
+    err.status = res.status;
+    throw err;
+  }
+  return body;
+}
+
+function compareShadow(detAnswers, jevAnswers) {
+  const divergences = [];
+  const jev = jevAnswers && typeof jevAnswers === 'object' ? jevAnswers : {};
+  for (const [id, det] of Object.entries(detAnswers || {})) {
+    const live = jev[id];
+    if (!live || !det) continue;
+    if (det.type === 'noul' && live.type === 'noul' && det.noul != null && live.noul != null) {
+      const delta = Math.abs(Number(live.noul) - Number(det.noul));
+      if (delta >= SHADOW_NOUL_DELTA) {
+        divergences.push({
+          id,
+          type: 'noul',
+          deterministic: Number(det.noul),
+          jev: Number(live.noul),
+          delta,
+        });
+      }
+    }
+    if (det.type === 'choice' && live.type === 'choice' && det.choice && live.choice && det.choice !== live.choice) {
+      divergences.push({
+        id,
+        type: 'choice',
+        deterministic: det.choice,
+        jev: live.choice,
+      });
+    }
+    if (det.type === 'score' && live.type === 'score' && det.score != null && live.score != null) {
+      const delta = Math.abs(Number(live.score) - Number(det.score));
+      if (delta >= 1) {
+        divergences.push({
+          id,
+          type: 'score',
+          deterministic: Number(det.score),
+          jev: Number(live.score),
+          delta,
+        });
+      }
+    }
+  }
+  return divergences;
+}
+
+function normalizeMetric(answer, question = {}) {
+  if (!answer || typeof answer !== 'object') return null;
+  const type = String(answer.type || (question && question.type) || '').toLowerCase();
+  if (type === 'noul') {
+    return answer.noul != null ? Number(answer.noul) : null;
+  }
+  if (type === 'choice') {
+    if (answer.probabilities && typeof answer.probabilities === 'object') {
+      const probs = Object.values(answer.probabilities).map(Number).filter((n) => !Number.isNaN(n));
+      if (probs.length) return Math.max(...probs);
+    }
+    return answer.confidence != null ? Number(answer.confidence) : 1.0;
+  }
+  if (type === 'score') {
+    const raw = answer.score != null ? Number(answer.score) : 0;
+    const criteria = question && Array.isArray(question.criteria) ? question.criteria : null;
+    const maxLevel = criteria && criteria.length > 1 ? criteria.length - 1 : 3;
+    return maxLevel > 0 ? Number((raw / maxLevel).toFixed(4)) : raw;
+  }
+  return null;
+}
+
+function computeVariance(runs) {
+  if (!Array.isArray(runs) || runs.length < 2) return {};
+  const stats = {};
+  const keys = Object.keys(runs[0] || {});
+  for (const key of keys) {
+    const values = runs.map((r) => Number(r[key])).filter((v) => !Number.isNaN(v));
+    if (values.length < 2) continue;
+    const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+    const variance = values.reduce((sum, v) => sum + Math.pow(v - mean, 2), 0) / (values.length - 1);
+    const stdDev = Math.sqrt(variance);
+    stats[key] = {
+      mean: Number(mean.toFixed(4)),
+      stdDev: Number(stdDev.toFixed(4)),
+      runs: values.length,
+      zeroVariance: stdDev === 0,
+    };
+  }
+  return stats;
+}
+
+async function attachLiveShadow(report, options = {}) {
+  if (options.fanOutQuestions) {
+    report.findings.push({
+      id: 'parallel_fanout_refused',
+      severity: 'fail',
+      gateId: 'require-typed-pretool-questions',
+      message: 'Refused --fan-out-questions. Parallel-questions cookbook: one POST with all N questions, not N calls. Do not re-pay the document N times.',
+    });
+    report.status = 'fail';
+    report.ok = false;
+    report.parallel = {
+      cookbook: PARALLEL_QUESTIONS_COOKBOOK,
+      batchedCalls: 0,
+      refusedFanOut: true,
+    };
+    return report;
+  }
+  if (!options.live || options.mapOnly || options.useTypesafeApi) return report;
+  const apiKey = options.apiKey !== undefined ? options.apiKey : loadTypesafeApiKey();
+  if (!apiKey) {
+    report.findings.push({
+      id: 'live_key_missing',
+      severity: 'fail',
+      gateId: 'require-code-owned-route',
+      message: '--live needs TYPESAFE_API_KEY (env or ~/.resume_secrets/TYPESAFE_API_KEY). Key is never printed.',
+    });
+    report.status = 'fail';
+    report.ok = false;
+    report.shadow = { used: false, reason: 'missing_api_key' };
+    return report;
+  }
+
+  const battery = parseBattery(options.batteryText || '').battery || DEFAULT_BATTERY;
+  const questions = questionsForApi(battery);
+  try {
+    const body = await callSystemOne({
+      state: options.payloadText
+        ? parsePayload(options.payloadText).payload
+        : {
+          tool_name: options.toolName,
+          tool_input: { command: options.command },
+        },
+      questions,
+      apiKey,
+      fetchImpl: options.fetchImpl,
+    });
+    const jevAnswers = (body && body.answers) || {};
+    const divergences = compareShadow(report.answers, jevAnswers);
+    report.parallel = parallelReceipt(questions, body && body.usage);
+    report.shadow = {
+      used: true,
+      ownsRoute: false,
+      model: body && body.model,
+      usage: body && body.usage,
+      answers: jevAnswers,
+      divergences,
+    };
+    for (const d of divergences) {
+      report.findings.push({
+        id: 'shadow_divergence',
+        severity: 'warn',
+        gateId: 'require-typed-pretool-questions',
+        questionId: d.id,
+        message: `Jev shadow disagrees with deterministic ${d.type} on ${d.id} (code still owns route=${report.route}).`,
+      });
+    }
+    if (divergences.length && report.status === 'ready') report.status = 'actionable';
+  } catch (err) {
+    const id = err && err.code === 'live_unauthorized' ? 'live_unauthorized' : 'live_http_error';
+    const status = err && err.status ? Number(err.status) : null;
+    const raw = String((err && err.message) || '');
+    const safeMsg = /apikey_|bearer\s/i.test(raw) ? 'redacted' : raw.slice(0, 160);
+    const errorCode = err && (err.code || (err.cause && err.cause.code));
+    report.findings.push({
+      id,
+      severity: 'fail',
+      gateId: 'require-code-owned-route',
+      message: `Live System One call failed (HTTP ${status || 'unknown'}${safeMsg ? `: ${safeMsg}` : ''}). Route stays deterministic. Secret is not logged.`,
+    });
+    report.status = 'fail';
+    report.ok = false;
+    report.shadow = {
+      used: false,
+      reason: id,
+      status,
+      errorName: err && err.name,
+      errorCode: errorCode || null,
+    };
+  }
+  return report;
+}
+
+async function buildTypesafeTypedQuestionsReportAsync(rawOptions = {}) {
+  const report = buildTypesafeTypedQuestionsReport(rawOptions);
+  const options = normalizeOptions(rawOptions);
+  if (options.fanOutQuestions) return report;
+  if (!options.live || options.mapOnly) return report;
+  const payloadText = options.payloadText || JSON.stringify({
+    tool_name: options.toolName,
+    tool_input: { command: options.command },
+  });
+  await attachLiveShadow(report, {
+    live: true,
+    mapOnly: false,
+    useTypesafeApi: options.useTypesafeApi,
+    fanOutQuestions: options.fanOutQuestions,
+    apiKey: options.apiKey,
+    fetchImpl: options.fetchImpl,
+    batteryText: options.batteryText,
+    payloadText,
+    toolName: options.toolName,
+    command: options.command,
+  });
+  return report;
+}
+
 function buildFindings({
   batteryParse,
   payloadParse,
@@ -506,6 +802,14 @@ function buildFindings({
       message: 'Refused --use-typesafe-api. Do not call api.typesafe.ai from PreToolUse (ECI; LLM adjudicator parked).',
     });
   }
+  if (flags.fanOutQuestions) {
+    findings.push({
+      id: 'parallel_fanout_refused',
+      severity: 'fail',
+      gateId: 'require-typed-pretool-questions',
+      message: 'Refused --fan-out-questions. Parallel-questions cookbook: one POST with all N questions, not N calls.',
+    });
+  }
   if (flags.llmAdjudicate) {
     findings.push({
       id: 'llm_adjudicator_parked',
@@ -587,6 +891,7 @@ function buildTypesafeTypedQuestionsReport(rawOptions = {}) {
     useTypesafeApi: options.useTypesafeApi,
     llmAdjudicate: options.llmAdjudicate,
     modelEmittedVerdict: options.modelEmittedVerdict,
+    fanOutQuestions: options.fanOutQuestions,
   };
 
   const evaluated = options.mapOnly
@@ -745,6 +1050,8 @@ function parseCliArgs(argv) {
     if (arg === '--clone-jev') { options['clone-jev'] = true; continue; }
     if (arg === '--use-typesafe-api') { options['use-typesafe-api'] = true; continue; }
     if (arg === '--llm-adjudicate') { options['llm-adjudicate'] = true; continue; }
+    if (arg === '--live') { options.live = true; continue; }
+    if (arg === '--fan-out-questions') { options['fan-out-questions'] = true; continue; }
     if (arg === '--help' || arg === '-h') { options.help = true; continue; }
     const m = /^--([^=]+)(?:=(.*))?$/.exec(arg);
     if (!m) continue;
@@ -765,7 +1072,9 @@ Flags:
   --map-only               Print TypeSafe → ThumbGate rail map
   --claim-ready            Fail unless code owns the route
   --clone-jev              Always fail (SKU clone)
-  --use-typesafe-api       Always fail (do not call Jev)
+  --use-typesafe-api       Always fail (Jev as the PreToolUse gate)
+  --live                   Shadow the battery against api.typesafe.ai; one POST, all questions
+  --fan-out-questions      Always fail (cookbook: do not pay the document N times)
   --llm-adjudicate         Always fail (#3690/#3687 parked)
   --model-emitted-verdict=V  Always fail (code must own route)
   --root=DIR               Repo root for relative paths
@@ -776,13 +1085,13 @@ Sources: ${SOURCE_URLS.join(' ')}
 `);
 }
 
-function runCli(argv = process.argv.slice(2)) {
+async function runCli(argv = process.argv.slice(2)) {
   const args = parseCliArgs(argv);
   if (args.help) {
     printHelp();
     return 0;
   }
-  const report = buildTypesafeTypedQuestionsReport(args);
+  const report = await buildTypesafeTypedQuestionsReportAsync(args);
   if (args.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
   else process.stdout.write(formatTypesafeTypedQuestionsReport(report));
   if (args.strict && report.status !== 'ready') return 1;
@@ -803,11 +1112,27 @@ module.exports = {
   composeHazardFamily,
   composeSeverity,
   route,
+  SYSTEMONE_URL,
+  loadTypesafeApiKey,
+  questionsForApi,
+  callSystemOne,
+  compareShadow,
+  attachLiveShadow,
+  parallelReceipt,
+  PARALLEL_QUESTIONS_COOKBOOK,
+  normalizeMetric,
+  computeVariance,
   buildTypesafeTypedQuestionsReport,
+  buildTypesafeTypedQuestionsReportAsync,
   formatTypesafeTypedQuestionsReport,
   runCli,
 };
 
 if (path.resolve(process.argv[1] || '') === path.resolve(__filename)) {
-  process.exitCode = runCli();
+  runCli().then((code) => {
+    process.exitCode = code;
+  }).catch((err) => {
+    process.stderr.write(`${err && err.message ? err.message : err}\n`);
+    process.exitCode = 1;
+  });
 }

package/server.json

@@ -8,13 +8,13 @@
     "source": "github",
     "url": "https://github.com/IgorGanapolsky/ThumbGate"
   },
-  "version": "1.37.2",
+  "version": "1.37.3",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "thumbgate",
-      "version": "1.37.2",
+      "version": "1.37.3",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {

package/skills/article-syndication-pipeline/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: article-syndication-pipeline
+description: Technical article syndication pipeline for cross-posting Dev.to articles to CoderLegion and other developer platforms with canonical URL preservation, UTM parameter attribution, and contributor onboarding compliance.
+---
+
+# ✍️ Article Syndication & Contributor Pipeline
+
+This skill guides the autonomous syndication of ThumbGate technical discoveries, security postmortems, and engineering deep dives across developer platforms (Dev.to, CoderLegion, Hashnode, Medium).
+
+---
+
+## 🎯 Architecture & Operating Directives
+
+1. **Canonical SEO Integrity:**
+   - Always preserve the primary origin as the canonical URL (e.g. `https://dev.to/igorganapolsky/...`).
+   - Syndicated copies on CoderLegion or elsewhere must link back to avoid search engine duplicate-content penalties.
+2. **First-Party Revenue Attribution:**
+   - All inbound links to `thumbgate.ai` must include UTM campaign tags (`utm_source=coderlegion`, `utm_medium=community`, `utm_campaign=guest-post`).
+   - Conversion links (Pro license checkout) must route through `/go/pro` (`https://thumbgate.ai/go/pro?utm_source=...`) to ensure server-side redirect logging.
+3. **CoderLegion Contributor Compliance:**
+   - URL import endpoint: `https://coderlegion.com/import-post`.
+   - Supports 2 imported Dev.to articles with full attribution.
+   - Contributor checklist: `https://coderlegion.com/guest-blog-checklists`.
+   - All imported posts undergo editorial review before appearing on the main feed.
+
+---
+
+## 🛠️ Step-by-Step Workflow
+
+1. **Verify Original Article:**
+   Verify original URL exists, returns HTTP 200, and has correct canonical tags.
+2. **Fetch via Platform Parser:**
+   Submit `import_url` to `https://coderlegion.com/import-post`.
+3. **Review & Confirm Metadata:**
+   Confirm title, tags (`ai`, `security`, `architecture`, `opensource`), and backlink to canonical source.
+4. **Publish & Track:**
+   Submit publication step and record post URL in session log and Comet browser tab.

package/skills/comet-session-logger/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: comet-session-logger
+description: Live session logger and observability dashboard driver for Comet browser. Ensures every PR, deployment status check, CoderLegion/Dev.to publication, and Railway production health metric is actively logged and visualized in Comet tabs.
+---
+
+# ☄️ Comet Session Logger & Visual HUD
+
+This skill governs the automated logging, tab orchestration, and visual tracking of all ThumbGate agentic tasks inside the **Comet** browser on macOS.
+
+---
+
+## 🎯 Purpose & Directives
+
+1. **CEO Visual Observability:** The CEO monitors agent progress via open tabs in Comet. Every major milestone must be reflected in Comet tabs without disrupting existing work.
+2. **Deterministic Tab Management:** Uses macOS AppleScript (`osascript`) to inspect, activate, create, or update Comet tabs.
+3. **Fail-Safe & Non-Destructive:** Never closes existing tabs; always reuses matching URLs or opens clean dedicated monitoring tabs.
+
+---
+
+## 🧭 Standard Tab Targets
+
+| Surface | Target URL | Trigger Milestone |
+|---------|------------|-------------------|
+| **Pull Requests** | `https://github.com/IgorGanapolsky/ThumbGate/pull/<NUM>` | After creating or advancing a PR |
+| **CI / Checks** | `https://github.com/IgorGanapolsky/ThumbGate/actions` | During workflow verification |
+| **Production Health** | `https://thumbgate-production.up.railway.app/health` | After deployment gate verification |
+| **Railway Console** | `https://railway.com/project/thumbgate-production` | When inspecting infrastructure |
+| **CoderLegion** | `https://coderlegion.com/import-post` | When onboarding or syndicating articles |
+| **Dev.to Dashboard** | `https://dev.to/dashboard` | When tracking article reach & analytics |
+
+---
+
+## 🛠️ AppleScript Orchestration Helpers
+
+```bash
+# Check existing Comet tabs
+osascript -e '
+tell application "Comet"
+    set outList to ""
+    repeat with w in windows
+        repeat with t in tabs of w
+            set outList to outList & (URL of t) & " | " & (title of t) & linefeed
+        end repeat
+    end repeat
+    return outList
+end tell'
+
+# Open or focus a specific URL in Comet
+open_comet_url() {
+  local target_url="$1"
+  osascript -e "
+  tell application \"Comet\"
+      activate
+      tell front window
+          make new tab with properties {URL:\"${target_url}\"}
+      end tell
+  end tell"
+}
+```

package/skills/thumbgate-daily-discoveries/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: thumbgate-daily-discoveries
+description: Autonomous daily publishing engine and monitoring skill for ThumbGate news and technical discoveries. Generates high-density engineering posts with full UTM attribution, synchronizes to Obsidian, schedules dual cron/launchd runs at 9:00 AM EST, and tracks publication ledgers.
+---
+
+# 📰 ThumbGate Daily Technical Discoveries & News Engine
+
+This skill automates the daily harvesting, synthesis, UTM attribution, and multi-channel publication of ThumbGate engineering discoveries and release news.
+
+---
+
+## 🎯 Architecture & Operating Principles
+
+1. **Daily Cadence (9:00 AM EST):** Runs once per calendar day. Avoids spam while establishing consistent technical authority.
+2. **Dual Scheduling Redundancy:**
+   - Primary: macOS crontab (`0 9 * * * /bin/bash scripts/thumbgate-daily-discoveries-publish.sh ...`)
+   - Fallback: macOS LaunchAgent (`~/Library/LaunchAgents/com.thumbgate.daily-publish.plist`)
+   - Note: GitHub Actions `schedule:` is strictly limited to `codeql.yml` per repo hygiene tests.
+3. **Full UTM Attribution & Tracked Redirects:**
+   - All outbound links to `thumbgate.ai` must use `buildUTMLink` from `scripts/social-analytics/utm.js`.
+   - Outbound pro/checkout links must route through `/go/pro` (`serveTrackedLinkRedirect` in `src/api/server.js`) to capture first-party funnel telemetry.
+4. **Multi-Surface Staging & Sync:**
+   - Staged locally at `docs/marketing/daily-discoveries/YYYY-MM-DD-<slug>.md`.
+   - Synchronized to the CEO's Obsidian Vault at `~/Documents/Igor/Research/Daily-Discoveries/`.
+   - Logged idempotently to `.thumbgate/daily-discoveries-ledger.jsonl`.
+   - Dispatches to Dev.to / Zernio if API keys are configured.
+
+---
+
+## 🛠️ CLI Commands & Usage
+
+```bash
+# Preview today's technical discovery without making mutations or network calls
+node scripts/thumbgate-daily-discoveries-publish.js --dry-run
+
+# Output structured JSON report
+node scripts/thumbgate-daily-discoveries-publish.js --json
+
+# Force publish/restage today's discovery even if already logged in ledger
+node scripts/thumbgate-daily-discoveries-publish.js --force
+
+# Shell wrapper (used by crontab / launchd)
+./scripts/thumbgate-daily-discoveries-publish.sh
+
+# Run test suite
+node --test tests/thumbgate-daily-discoveries-publish.test.js
+```
+
+---
+
+## 📋 Pre-Flight Verification Checklist
+
+- [ ] Verify `node --test tests/thumbgate-daily-discoveries-publish.test.js` passes.
+- [ ] Verify outbound links contain valid UTM parameters (`utm_source=daily_discoveries`, `utm_campaign=daily_technical_discoveries`).
+- [ ] Verify `launchctl list | grep thumbgate` reports exit code 0.
+- [ ] Verify `crontab -l | grep thumbgate` contains the 9:00 AM daily trigger.
+- [ ] Check `.thumbgate/daily-discoveries-ledger.jsonl` for recent execution receipts.

package/src/index.js

@@ -12,6 +12,12 @@ const {
   isNamedIdentity,
 } = require('./hermes-platform-protocol');
 const { HermesSyncPlane } = require('./hermes-sync-plane');
+const {
+  IdeaBrowserConnector,
+  ToolTier,
+  DEFAULT_READ_ONLY_TOOLS,
+  DEFAULT_MUTATING_TOOLS,
+} = require('./integrations/ideabrowser-connector');
 
 // The package entry point is the production surface for `thumbgate`.
 // The hosted-Hermes identity/lifecycle/approval gates are exported here so
@@ -29,4 +35,8 @@ module.exports = Object.assign({}, feedbackLoop, {
   THREAD_MODES,
   FORBIDDEN_IDENTITIES,
   isNamedIdentity,
+  IdeaBrowserConnector,
+  ToolTier,
+  DEFAULT_READ_ONLY_TOOLS,
+  DEFAULT_MUTATING_TOOLS,
 });