dr-claw 1.1.2

package/server/taskmaster-templates/ai-research-method-model.json

@@ -0,0 +1,230 @@
+{
+  "id": "ai-research-method-model",
+  "name": "AI Research - Method/Model",
+  "description": "For algorithmic, architectural, and model innovation projects",
+  "domain": "ai-research",
+  "category": "ai-research",
+  "format": "research-brief-json",
+  "fileName": "research_brief.json",
+  "metaFields": [
+    { "key": "title", "label": "Paper Title", "path": "meta.title", "placeholder": "Optional project title" },
+    { "key": "lead_author", "label": "Lead Author", "path": "meta.lead_author", "placeholder": "Optional lead author" },
+    { "key": "target_venue", "label": "Target Venue", "path": "meta.target_venue", "placeholder": "Optional venue" }
+  ],
+  "sectionFields": {
+    "survey": [
+      { "key": "literature_scope", "label": "Literature Scope", "path": "sections.survey.literature_scope", "placeholder": "Search boundary, keywords, and covered subtopics" },
+      { "key": "key_references", "label": "Key References", "path": "sections.survey.key_references", "type": "array", "placeholder": "One reference or paper family per line" },
+      { "key": "synthesis_summary", "label": "Synthesis Summary", "path": "sections.survey.synthesis_summary", "placeholder": "Main trends, dominant baselines, unresolved tensions" },
+      { "key": "open_gaps", "label": "Open Gaps", "path": "sections.survey.open_gaps", "type": "array", "placeholder": "One gap per line" }
+    ],
+    "ideation": [
+      { "key": "research_goal", "label": "Research Goal", "path": "sections.ideation.research_goal", "placeholder": "Main hypothesis and expected gains" },
+      { "key": "problem_framing", "label": "Problem Framing", "path": "sections.ideation.problem_framing", "placeholder": "Novelty boundary vs prior work" },
+      { "key": "evidence_plan", "label": "Evidence Plan", "path": "sections.ideation.evidence_plan", "placeholder": "Related work and intended comparisons" },
+      { "key": "success_criteria", "label": "Success Criteria", "path": "sections.ideation.success_criteria", "type": "array", "placeholder": "One criterion per line" }
+    ],
+    "experiment": [
+      { "key": "hypothesis_or_validation_goal", "label": "Validation Goal", "path": "sections.experiment.hypothesis_or_validation_goal", "placeholder": "What should ablations prove?" },
+      { "key": "dataset_or_data_source", "label": "Dataset Plan", "path": "sections.experiment.dataset_or_data_source", "placeholder": "Datasets and splits" },
+      { "key": "method_or_protocol", "label": "Method Protocol", "path": "sections.experiment.method_or_protocol", "placeholder": "Architecture/training/inference plan" },
+      { "key": "evaluation_plan", "label": "Evaluation Plan", "path": "sections.experiment.evaluation_plan", "placeholder": "Metrics, robustness, significance tests" }
+    ],
+    "publication": [
+      { "key": "paper_outline", "label": "Paper Outline", "path": "sections.publication.paper_outline", "placeholder": "Contribution narrative and sections" },
+      { "key": "figures_tables_plan", "label": "Figures/Tables Plan", "path": "sections.publication.figures_tables_plan", "placeholder": "Ablation and benchmark tables" },
+      { "key": "artifact_plan", "label": "Artifact Plan", "path": "sections.publication.artifact_plan", "placeholder": "Code/config/repro script release" },
+      { "key": "submission_checklist", "label": "Submission Checklist", "path": "sections.publication.submission_checklist", "type": "array", "placeholder": "One item per line" }
+    ],
+    "promotion": [
+      { "key": "slide_outline", "label": "Slide Outline", "path": "sections.promotion.slide_outline", "placeholder": "One slide or scene per line" },
+      { "key": "deck_style", "label": "Deck Style", "path": "sections.promotion.deck_style", "placeholder": "Visual style, color, layout, and pacing guidance" },
+      { "key": "homepage_plan", "label": "Homepage Plan", "path": "sections.promotion.homepage_plan", "placeholder": "Sections, assets, links, and CTA for the project page" },
+      { "key": "tts_config", "label": "TTS Config", "path": "sections.promotion.tts_config", "placeholder": "Voice, engine, pacing, and narration constraints" },
+      { "key": "video_assembly_plan", "label": "Video Assembly Plan", "path": "sections.promotion.video_assembly_plan", "placeholder": "How slides, audio, captions, and demo clips should be assembled" }
+    ]
+  },
+  "pipeline": {
+    "version": "1.1",
+    "mode": "idea",
+    "stages": {
+      "survey": {
+        "required_elements": [
+          "sections.survey.literature_scope",
+          "sections.survey.synthesis_summary"
+        ],
+        "optional_elements": [
+          "sections.survey.key_references",
+          "sections.survey.open_gaps"
+        ],
+        "quality_gate": [
+          "Method families and strongest baselines are mapped",
+          "Open gaps connect directly to the proposed method direction"
+        ],
+        "task_blueprints": [
+          {
+            "id": "method_literature_landscape",
+            "title": "Map literature landscape and dominant baseline families",
+            "description": "Survey recent methods, identify dominant design patterns, and cluster representative baselines.",
+            "taskType": "exploration",
+            "recommended_skills": ["inno-deep-research", "academic-researcher"]
+          },
+          {
+            "id": "method_gap_synthesis",
+            "title": "Synthesize unresolved gaps for method innovation",
+            "description": "Summarize what current methods miss and where a new method can create measurable value.",
+            "taskType": "analysis",
+            "recommended_skills": ["inno-deep-research", "academic-researcher"]
+          }
+        ],
+        "recommended_skills": [
+          "inno-deep-research",
+          "academic-researcher"
+        ]
+      },
+      "ideation": {
+        "required_elements": [
+          "sections.ideation.research_goal",
+          "sections.ideation.problem_framing"
+        ],
+        "optional_elements": [
+          "sections.ideation.evidence_plan",
+          "sections.ideation.success_criteria"
+        ],
+        "quality_gate": [
+          "Novel method contribution over baselines is explicit",
+          "Claim boundaries and target setting are concrete"
+        ],
+        "task_blueprints": [
+          {
+            "id": "method_novelty_and_claim_definition",
+            "title": "Define novelty claim and theoretical motivation",
+            "description": "Clarify what is new, why it should work, and expected tradeoffs.",
+            "taskType": "analysis",
+            "recommended_skills": ["inno-idea-generation", "academic-researcher"]
+          },
+          {
+            "id": "method_design_space_and_baselines",
+            "title": "Map design space and baseline comparison plan",
+            "description": "Identify main design alternatives and strong baseline families.",
+            "taskType": "exploration",
+            "recommended_skills": ["inno-idea-generation", "inno-code-survey"]
+          }
+        ],
+        "recommended_skills": [
+          "inno-pipeline-planner",
+          "inno-idea-generation"
+        ]
+      },
+      "experiment": {
+        "required_elements": [
+          "sections.experiment.hypothesis_or_validation_goal",
+          "sections.experiment.method_or_protocol",
+          "sections.experiment.evaluation_plan"
+        ],
+        "optional_elements": [
+          "sections.experiment.dataset_or_data_source"
+        ],
+        "quality_gate": [
+          "Ablation matrix and training protocol are executable",
+          "Evaluation includes robustness and significance checks"
+        ],
+        "task_blueprints": [
+          {
+            "id": "method_implementation_and_repro_setup",
+            "title": "Implement method and reproducible training setup",
+            "description": "Prepare code path, hyperparameter defaults, seeds, and run manifests.",
+            "taskType": "implementation",
+            "recommended_skills": ["inno-experiment-dev"]
+          },
+          {
+            "id": "method_ablation_and_robustness_evaluation",
+            "title": "Run ablations, robustness checks, and statistical validation",
+            "description": "Execute core benchmarks, ablations, and reliability analysis.",
+            "taskType": "analysis",
+            "recommended_skills": ["inno-experiment-analysis"]
+          }
+        ],
+        "recommended_skills": [
+          "inno-experiment-dev",
+          "inno-experiment-analysis"
+        ]
+      },
+      "publication": {
+        "required_elements": [
+          "sections.publication.paper_outline",
+          "sections.publication.submission_checklist"
+        ],
+        "optional_elements": [
+          "sections.publication.figures_tables_plan",
+          "sections.publication.artifact_plan"
+        ],
+        "quality_gate": [
+          "Claims are aligned with empirical evidence",
+          "Figures/tables communicate ablations and comparisons clearly"
+        ],
+        "task_blueprints": [
+          {
+            "id": "method_results_narrative_and_figures",
+            "title": "Draft results narrative and key comparison figures",
+            "description": "Turn experiment outcomes into coherent claim-evidence storytelling.",
+            "taskType": "writing",
+            "recommended_skills": ["inno-paper-writing", "inno-reference-audit"]
+          },
+          {
+            "id": "method_repro_appendix_and_submission_polish",
+            "title": "Finalize reproducibility appendix and submission-ready manuscript",
+            "description": "Complete appendix/checklists and final manuscript polish for submission.",
+            "taskType": "writing",
+            "recommended_skills": ["inno-paper-writing"]
+          }
+        ],
+        "recommended_skills": [
+          "inno-paper-writing",
+          "inno-reference-audit"
+        ]
+      },
+      "promotion": {
+        "required_elements": [
+          "sections.promotion.slide_outline"
+        ],
+        "optional_elements": [
+          "sections.promotion.deck_style",
+          "sections.promotion.tts_config",
+          "sections.promotion.video_assembly_plan",
+          "sections.promotion.homepage_plan"
+        ],
+        "quality_gate": [
+          "Slide flow reflects the method contribution and strongest results",
+          "Homepage and narration plans are specific enough to produce assets"
+        ],
+        "task_blueprints": [
+          {
+            "id": "method_promotion_outline_and_script",
+            "title": "Draft slide outline, speaking track, and homepage structure",
+            "description": "Turn the paper narrative into a promotion-ready deck outline, narration plan, and homepage information architecture.",
+            "taskType": "scripting",
+            "recommended_skills": ["making-academic-presentations"]
+          },
+          {
+            "id": "method_promotion_visual_assets",
+            "title": "Generate slide visuals and supporting homepage assets",
+            "description": "Prepare presentation visuals and homepage-ready figures from paper assets.",
+            "taskType": "rendering",
+            "recommended_skills": ["making-academic-presentations"]
+          },
+          {
+            "id": "method_promotion_audio_video_delivery",
+            "title": "Produce narration audio and assemble delivery outputs",
+            "description": "Generate TTS narration and package slide, homepage, and demo-video deliverables.",
+            "taskType": "delivery",
+            "recommended_skills": ["making-academic-presentations"]
+          }
+        ],
+        "recommended_skills": [
+          "making-academic-presentations"
+        ]
+      }
+    }
+  }
+}

package/server/taskmaster-templates/ai-research-position-paper.json

@@ -0,0 +1,230 @@
+{
+  "id": "ai-research-position-paper",
+  "name": "AI Research - Position Paper",
+  "description": "For argument-driven papers: framing, taxonomy, agenda, and critical synthesis",
+  "domain": "ai-research",
+  "category": "ai-research",
+  "format": "research-brief-json",
+  "fileName": "research_brief.json",
+  "metaFields": [
+    { "key": "title", "label": "Paper Title", "path": "meta.title", "placeholder": "Optional project title" },
+    { "key": "lead_author", "label": "Lead Author", "path": "meta.lead_author", "placeholder": "Optional lead author" },
+    { "key": "target_venue", "label": "Target Venue", "path": "meta.target_venue", "placeholder": "Optional venue" }
+  ],
+  "sectionFields": {
+    "survey": [
+      { "key": "literature_scope", "label": "Literature Scope", "path": "sections.survey.literature_scope", "placeholder": "Communities, debates, and time window to cover" },
+      { "key": "key_references", "label": "Key References", "path": "sections.survey.key_references", "type": "array", "placeholder": "One foundational or contradictory source per line" },
+      { "key": "synthesis_summary", "label": "Synthesis Summary", "path": "sections.survey.synthesis_summary", "placeholder": "What positions exist, where they agree, and where they clash" },
+      { "key": "open_gaps", "label": "Open Gaps", "path": "sections.survey.open_gaps", "type": "array", "placeholder": "One unresolved debate or synthesis gap per line" }
+    ],
+    "ideation": [
+      { "key": "research_goal", "label": "Core Thesis", "path": "sections.ideation.research_goal", "placeholder": "State your central claim" },
+      { "key": "problem_framing", "label": "Problem Framing", "path": "sections.ideation.problem_framing", "placeholder": "Why now and for whom" },
+      { "key": "evidence_plan", "label": "Evidence Plan", "path": "sections.ideation.evidence_plan", "placeholder": "Canonical + contradictory evidence" },
+      { "key": "success_criteria", "label": "Success Criteria", "path": "sections.ideation.success_criteria", "type": "array", "placeholder": "One criterion per line" }
+    ],
+    "experiment": [
+      { "key": "hypothesis_or_validation_goal", "label": "Validation Goal", "path": "sections.experiment.hypothesis_or_validation_goal", "placeholder": "What should empirical support validate?" },
+      { "key": "dataset_or_data_source", "label": "Data/Case Source", "path": "sections.experiment.dataset_or_data_source", "placeholder": "Case studies or datasets if needed" },
+      { "key": "method_or_protocol", "label": "Validation Protocol", "path": "sections.experiment.method_or_protocol", "placeholder": "Audit/survey/small-scale protocol" },
+      { "key": "evaluation_plan", "label": "Evaluation Plan", "path": "sections.experiment.evaluation_plan", "placeholder": "Internal/external validity checks" }
+    ],
+    "publication": [
+      { "key": "paper_outline", "label": "Paper Outline", "path": "sections.publication.paper_outline", "placeholder": "Argument structure and sections" },
+      { "key": "figures_tables_plan", "label": "Figures/Tables Plan", "path": "sections.publication.figures_tables_plan", "placeholder": "Taxonomy/checklist/evidence tables" },
+      { "key": "artifact_plan", "label": "Artifact Plan", "path": "sections.publication.artifact_plan", "placeholder": "Appendix and reproducibility artifacts" },
+      { "key": "submission_checklist", "label": "Submission Checklist", "path": "sections.publication.submission_checklist", "type": "array", "placeholder": "One item per line" }
+    ],
+    "promotion": [
+      { "key": "slide_outline", "label": "Slide Outline", "path": "sections.promotion.slide_outline", "placeholder": "Talk track or slide-by-slide outline" },
+      { "key": "deck_style", "label": "Deck Style", "path": "sections.promotion.deck_style", "placeholder": "Visual tone, pace, and audience framing" },
+      { "key": "homepage_plan", "label": "Homepage Plan", "path": "sections.promotion.homepage_plan", "placeholder": "Landing page structure, visuals, and references" },
+      { "key": "tts_config", "label": "TTS Config", "path": "sections.promotion.tts_config", "placeholder": "Voice, pacing, and narration constraints" },
+      { "key": "video_assembly_plan", "label": "Video Assembly Plan", "path": "sections.promotion.video_assembly_plan", "placeholder": "How to combine slides, narration, and optional demo footage" }
+    ]
+  },
+  "pipeline": {
+    "version": "1.1",
+    "mode": "idea",
+    "stages": {
+      "survey": {
+        "required_elements": [
+          "sections.survey.literature_scope",
+          "sections.survey.synthesis_summary"
+        ],
+        "optional_elements": [
+          "sections.survey.key_references",
+          "sections.survey.open_gaps"
+        ],
+        "quality_gate": [
+          "The surveyed debate space is explicit and balanced",
+          "Contradictions and synthesis gaps are documented clearly"
+        ],
+        "task_blueprints": [
+          {
+            "id": "position_debate_landscape",
+            "title": "Map the debate landscape and canonical positions",
+            "description": "Survey major viewpoints, representative sources, and the assumptions behind each position.",
+            "taskType": "exploration",
+            "recommended_skills": ["inno-deep-research", "academic-researcher"]
+          },
+          {
+            "id": "position_tension_synthesis",
+            "title": "Synthesize unresolved tensions and framing gaps",
+            "description": "Summarize where the literature disagrees and what conceptual gap the position paper should address.",
+            "taskType": "analysis",
+            "recommended_skills": ["inno-deep-research", "academic-researcher"]
+          }
+        ],
+        "recommended_skills": [
+          "inno-deep-research",
+          "academic-researcher"
+        ]
+      },
+      "ideation": {
+        "required_elements": [
+          "sections.ideation.research_goal",
+          "sections.ideation.problem_framing"
+        ],
+        "optional_elements": [
+          "sections.ideation.evidence_plan",
+          "sections.ideation.success_criteria"
+        ],
+        "quality_gate": [
+          "Core thesis and scope boundaries are testable and explicit",
+          "Counterarguments and alternative framings are acknowledged"
+        ],
+        "task_blueprints": [
+          {
+            "id": "position_thesis_and_scope_definition",
+            "title": "Formulate central thesis and argument scope",
+            "description": "Define the core position, audience, and limits of the argument.",
+            "taskType": "analysis",
+            "recommended_skills": ["inno-idea-generation", "academic-researcher"]
+          },
+          {
+            "id": "position_evidence_map_and_counterpoints",
+            "title": "Build evidence map with supporting and opposing views",
+            "description": "Collect canonical support and strongest counter-evidence for balance.",
+            "taskType": "exploration",
+            "recommended_skills": ["inno-idea-generation", "academic-researcher"]
+          }
+        ],
+        "recommended_skills": [
+          "inno-pipeline-planner",
+          "inno-idea-generation"
+        ]
+      },
+      "experiment": {
+        "required_elements": [
+          "sections.experiment.hypothesis_or_validation_goal",
+          "sections.experiment.method_or_protocol",
+          "sections.experiment.evaluation_plan"
+        ],
+        "optional_elements": [
+          "sections.experiment.dataset_or_data_source"
+        ],
+        "quality_gate": [
+          "Validation protocol is appropriate for argument claims",
+          "Evidence synthesis addresses internal and external validity"
+        ],
+        "task_blueprints": [
+          {
+            "id": "position_validation_protocol_design",
+            "title": "Design argument-validation protocol",
+            "description": "Specify survey/audit/case-study protocol to stress-test key claims.",
+            "taskType": "implementation",
+            "recommended_skills": ["inno-experiment-dev"]
+          },
+          {
+            "id": "position_synthesis_and_conflict_resolution",
+            "title": "Synthesize evidence and resolve claim conflicts",
+            "description": "Aggregate findings, reconcile contradictions, and refine claim strength.",
+            "taskType": "analysis",
+            "recommended_skills": ["inno-experiment-analysis"]
+          }
+        ],
+        "recommended_skills": [
+          "inno-experiment-dev",
+          "inno-experiment-analysis"
+        ]
+      },
+      "publication": {
+        "required_elements": [
+          "sections.publication.paper_outline",
+          "sections.publication.submission_checklist"
+        ],
+        "optional_elements": [
+          "sections.publication.figures_tables_plan",
+          "sections.publication.artifact_plan"
+        ],
+        "quality_gate": [
+          "Argument flow is coherent end-to-end",
+          "Taxonomy/checklists and evidence tables are publication-ready"
+        ],
+        "task_blueprints": [
+          {
+            "id": "position_taxonomy_and_argument_structure",
+            "title": "Draft taxonomy and argument structure",
+            "description": "Translate thesis into sectioned narrative with clear argumentative progression.",
+            "taskType": "writing",
+            "recommended_skills": ["inno-paper-writing", "inno-reference-audit"]
+          },
+          {
+            "id": "position_manuscript_finalization",
+            "title": "Finalize position manuscript and submission package",
+            "description": "Complete final revisions, checklist, and supplementary rationale artifacts.",
+            "taskType": "writing",
+            "recommended_skills": ["inno-paper-writing"]
+          }
+        ],
+        "recommended_skills": [
+          "inno-paper-writing",
+          "inno-reference-audit"
+        ]
+      },
+      "promotion": {
+        "required_elements": [
+          "sections.promotion.slide_outline"
+        ],
+        "optional_elements": [
+          "sections.promotion.deck_style",
+          "sections.promotion.tts_config",
+          "sections.promotion.video_assembly_plan",
+          "sections.promotion.homepage_plan"
+        ],
+        "quality_gate": [
+          "Deck and homepage communicate the thesis clearly to the target audience",
+          "Narration and delivery plan are specific enough to produce final assets"
+        ],
+        "task_blueprints": [
+          {
+            "id": "position_promotion_storyboard",
+            "title": "Storyboard the talk and homepage narrative",
+            "description": "Translate the position argument into a concise slide sequence, talk track, and homepage summary.",
+            "taskType": "scripting",
+            "recommended_skills": ["making-academic-presentations"]
+          },
+          {
+            "id": "position_promotion_visual_packaging",
+            "title": "Package visual assets for slides and homepage",
+            "description": "Prepare diagrams, highlight boxes, and supporting visuals for public-facing communication.",
+            "taskType": "rendering",
+            "recommended_skills": ["making-academic-presentations"]
+          },
+          {
+            "id": "position_promotion_delivery_outputs",
+            "title": "Generate narration and assemble promotion outputs",
+            "description": "Produce TTS or narration guidance and assemble shareable slide, homepage, and video deliverables.",
+            "taskType": "delivery",
+            "recommended_skills": ["making-academic-presentations"]
+          }
+        ],
+        "recommended_skills": [
+          "making-academic-presentations"
+        ]
+      }
+    }
+  }
+}

package/server/telemetry.js

@@ -0,0 +1,121 @@
+import fetch from 'node-fetch';
+
+const DEFAULT_TELEMETRY_ENDPOINT =
+  'https://vibe-telemetry-collector-1002374823539.us-central1.run.app/events';
+const DEFAULT_TELEMETRY_AUTH_TOKEN =
+  'a02ba6627d6515a1b59521772f074c6bd9bfc2734c333760bd0b83acf28e1f71';
+
+const TELEMETRY_ENDPOINT = (process.env.TELEMETRY_ENDPOINT ?? DEFAULT_TELEMETRY_ENDPOINT).trim();
+const TELEMETRY_AUTH_TOKEN = (process.env.TELEMETRY_AUTH_TOKEN ?? DEFAULT_TELEMETRY_AUTH_TOKEN).trim();
+const TELEMETRY_FORCE_DISABLE = process.env.TELEMETRY_FORCE_DISABLE === 'true';
+const TELEMETRY_BATCH_SIZE = Math.max(1, Number.parseInt(process.env.TELEMETRY_BATCH_SIZE || '20', 10));
+const TELEMETRY_FLUSH_INTERVAL_MS = Math.max(
+  200,
+  Number.parseInt(process.env.TELEMETRY_FLUSH_INTERVAL_MS || '1500', 10),
+);
+const TELEMETRY_MAX_QUEUE = Math.max(100, Number.parseInt(process.env.TELEMETRY_MAX_QUEUE || '2000', 10));
+
+let queue = [];
+let flushTimer = null;
+let isFlushing = false;
+
+export function isTelemetryEnabled() {
+  return !TELEMETRY_FORCE_DISABLE && Boolean(TELEMETRY_ENDPOINT);
+}
+
+function scheduleFlush() {
+  if (flushTimer) {
+    return;
+  }
+  flushTimer = setTimeout(() => {
+    flushTimer = null;
+    flushTelemetryQueue().catch((error) => {
+      console.error('[telemetry] flush timer failed:', error);
+    });
+  }, TELEMETRY_FLUSH_INTERVAL_MS);
+}
+
+async function postEvents(events) {
+  const headers = {
+    'Content-Type': 'application/json',
+  };
+  if (TELEMETRY_AUTH_TOKEN) {
+    headers.Authorization = `Bearer ${TELEMETRY_AUTH_TOKEN}`;
+  }
+
+  const response = await fetch(TELEMETRY_ENDPOINT, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      source: 'dr-claw',
+      sentAt: new Date().toISOString(),
+      events,
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => '');
+    throw new Error(`HTTP ${response.status}${body ? `: ${body.slice(0, 300)}` : ''}`);
+  }
+}
+
+export async function flushTelemetryQueue() {
+  if (!isTelemetryEnabled() || isFlushing || queue.length === 0) {
+    return;
+  }
+
+  isFlushing = true;
+  const batch = queue.splice(0, TELEMETRY_BATCH_SIZE);
+
+  try {
+    await postEvents(batch);
+  } catch (error) {
+    // Requeue at front on transient failures, bounded to max queue size.
+    queue = [...batch, ...queue].slice(0, TELEMETRY_MAX_QUEUE);
+    console.error('[telemetry] failed to send events:', error.message || error);
+  } finally {
+    isFlushing = false;
+    if (queue.length > 0) {
+      scheduleFlush();
+    }
+  }
+}
+
+export function enqueueTelemetryEvent(event) {
+  if (!isTelemetryEnabled() || !event || typeof event !== 'object') {
+    return false;
+  }
+
+  queue.push({
+    ...event,
+    receivedAt: event.receivedAt || new Date().toISOString(),
+  });
+
+  if (queue.length > TELEMETRY_MAX_QUEUE) {
+    queue = queue.slice(queue.length - TELEMETRY_MAX_QUEUE);
+  }
+
+  if (queue.length >= TELEMETRY_BATCH_SIZE) {
+    flushTelemetryQueue().catch((error) => {
+      console.error('[telemetry] immediate flush failed:', error);
+    });
+  } else {
+    scheduleFlush();
+  }
+
+  return true;
+}
+
+export function enqueueTelemetryEvents(events) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return 0;
+  }
+
+  let accepted = 0;
+  for (const event of events) {
+    if (enqueueTelemetryEvent(event)) {
+      accepted += 1;
+    }
+  }
+  return accepted;
+}