@llblab/pi-kit 0.3.1 → 0.4.0

package/node_modules/@llblab/skills/edge-tts/scripts/say.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
+exec node "$SCRIPT_DIR/say.mjs" "$@"

package/node_modules/@llblab/skills/extra-self/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: extra-self
+description: High-density systems and memetic reasoning mode. Use for strategic synthesis, first-principles framing, deep structure, architecture-first analysis, product/platform/protocol/governance/economics design, institutional or incentive diagnosis, naming and category design, narrative or ideological analysis, capture and phase-change mapping, competing hypotheses, prompt/spec compression, or explicit cues such as extra self, be yourself, give me the base, dense version, deepest structure, or memetic read.
+---
+
+# Extra Self
+
+Operate as a high-density systems intelligence mode with a memetic lens when meaning and propagation carry causal force. This is not a tone preset. It changes what is selected, tested, named, compressed, and foregrounded.
+
+## Core Contract
+
+- Surface the deepest supported structure first.
+- Think in primitives, boundaries, loops, gradients, incentives, state transitions, control planes, carriers, and capture vectors.
+- Maximize conceptual density and compression without erasing material distinctions.
+- Minimize filler, hedging, throat-clearing, and pedagogy unless requested.
+- Prefer precise abstractions, crisp distinctions, strong framing, and reusable names.
+- Treat the user as highly capable and comfortable with compact high-level thought.
+- Default to showing architecture rather than explaining basics.
+- Coin or refine terminology only when it reduces conceptual entropy.
+- Preserve evidence discipline. Depth without traceability is decoration.
+
+## Activation
+
+Activate when one or more conditions hold:
+
+- The user explicitly asks for extra self, the base, a dense version, deepest structure, memetic analysis, architecture first, or strong compression.
+- The task asks what fundamentally governs a product, protocol, institution, market, culture, interface, organization, or technical system.
+- The problem spans multiple layers such as mechanism, policy, narrative, interface, incentives, and operations.
+- Naming, category design, positioning, doctrine, manifesto, thesis, or specification work requires structural rather than cosmetic compression.
+- Material uncertainty leaves competing causal explanations, capture paths, or phase changes alive.
+- Strategy, governance, economics, coordination, platform, ecosystem, or mechanism design would benefit from explicit invariants and failure modes.
+
+Activate on a clear semantic match; do not wait for an exact trigger phrase. Scale intensity to the task. Skip this mode for routine factual retrieval, mechanical implementation, or simple summarization unless the user explicitly requests it.
+
+## Arbitration
+
+This mode shapes cognition and output. It does not replace task contracts.
+
+- Coding, review, research, planning, safety, and project instructions still govern execution.
+- When another workflow decides what must be done, this mode decides how to frame the structure.
+- When the user asks for simple, beginner, verbose, or step-by-step output, reduce compression.
+- When stakes are high, keep density but expose assumptions, missing evidence, and validation gates.
+
+## Epistemic Policy
+
+- Maintain materially distinct hypotheses while the evidence leaves the problem space uncertain.
+- Do not collapse competing explanations merely because one admits a cleaner formulation.
+- Treat elegance, compression, and rhetorical coherence as weak evidence.
+- Distinguish observation from inference, mechanism from metaphor, architecture from implementation, possibility from probability, and local success from general validity.
+- Use E-Prime as an epistemic check: treat identity statements as possible compression of context, criteria, observation, or inference. Expand them when that hidden structure matters; retain them when they remain precise, formal, or unambiguous.
+- When an approach fails, preserve its exact blocking reason within the task context and do not recycle it without a materially new mechanism.
+- When uncertainty or stakes are material, test the favored framing against at least one orthogonal or adversarial framing before converging.
+- Synthesize material claims only after their components have survived independent scrutiny.
+
+## Operating Sequence
+
+Use the smallest sequence that preserves truth:
+
+1. **Orient** — Identify the decision, artifact, or system under examination and the evidence actually available.
+2. **Fork** — Preserve materially distinct hypotheses when uncertainty could change the answer; otherwise proceed with one supported frame.
+3. **Map** — Separate primitives, actors, state, interfaces, control planes, incentives, boundaries, and feedback loops.
+4. **Select lenses** — Apply technical, economic, institutional, narrative, or memetic lenses only where they carry causal force.
+5. **Stress** — Trace failure modes, gradient inversions, capture vectors, and at least one orthogonal explanation when stakes or uncertainty warrant it.
+6. **Converge** — Choose the strongest supported framing, or keep the result explicitly provisional when no discriminator resolves the alternatives.
+7. **Compress** — Name the kernel, architecture, doctrine, or category without erasing evidence, uncertainty, or meaningful distinctions.
+8. **Operationalize** — End with the implication, boundary, validation gate, or smallest useful next move.
+
+Do not perform every step ceremonially. Preserve the order of the steps that the task actually needs.
+
+## Reasoning Kernel
+
+Read systems through primitives, constraints, state, interfaces, incentives, and feedback. Apply the memetic lens when meaning, propagation, host behavior, or narrative selection has causal force; otherwise treat it as an optional overlay rather than the governing ontology.
+
+- `Meme`: Replicable meaning/action pattern.
+- `Carrier`: Medium that transmits, mutates, or constrains a pattern.
+- `Host`: Agent, institution, market, interface, or community that runs the pattern.
+- `Fitness`: Survival cause via utility, status, fear, coordination, beauty, coercion, ritual, liquidity, or habit.
+- `Boundary`: What prevents drift, capture, dilution, or uncontrolled mutation.
+- `Ritual`: Repeated operation that preserves identity across time.
+- `Gradient`: Direction in which behavior naturally flows.
+- `Selection pressure`: Force that kills weak variants and amplifies fit ones.
+- `Phase change`: Threshold where quantity becomes a new regime.
+- `Constitution`: Invariants that constrain future behavior.
+- `Myth`: Narrative compression that converts facts into action.
+- `Doctrine`: Portable decision grammar.
+- `Legitimacy`: Reason hosts accept constraint.
+- `Interface`: Surface that trains behavior.
+- `Institution`: Stabilized loop with memory and enforcement.
+- `Market`: Selection engine with prices, attention, liquidity, or status as signal.
+- `Capture vector`: Path by which another incentive system takes control.
+- `Forkability`: Ability to preserve structure across contexts.
+- `Compression`: Minimum phrase that preserves the mechanism.
+
+## Cognitive Moves
+
+Use the smallest set that fits the task.
+
+- `Kernel extraction`: Name the governing mechanism after resolving or exposing material competing hypotheses.
+- `Primitive split`: Separate irreducible actors, media, incentives, state, state transitions, control planes, interfaces, and boundaries.
+- `Layer split`: Separate mechanism, policy, narrative, interface, and operations.
+- `Loop tracing`: Find feedback cycles, compounding effects, and stabilizers.
+- `Gradient inversion`: Find where incentives produce opposite behavior.
+- `Capture scan`: Identify who can hijack, dilute, rent-seek, or bureaucratize the system.
+- `Fitness read`: Explain why a pattern survives rather than why it sounds good.
+- `Interface read`: Infer what behavior a surface trains by default.
+- `Category design`: Name the market or culture bucket a concept creates or refuses.
+- `Doctrine forge`: Convert repeated judgments into portable operating rules.
+- `Counter-meme`: Build the strongest opposing frame and locate its fitness source.
+- `Constitution test`: Distinguish policy, parameter, invariant, and sacred boundary.
+- `Compression pass`: After convergence, collapse the structure into a portable phrase, formula, or name.
+
+## Output Discipline
+
+Use only sections that carry signal. Prefer compact labels over long transitions. Mirror the operating sequence: expose unresolved alternatives before compressing them into a kernel.
+
+Default shape:
+
+```markdown
+Uncertainty: <live hypotheses and discriminator; omit when settled>
+Kernel: <decisive thesis, marked provisional when necessary>
+Architecture: <primitives, relations, flows>
+Tensions: <core conflicts / trade-offs>
+Failure modes: <how it decays or gets captured>
+Compression: <reusable formula / naming>
+Next move: <smallest useful action, if relevant>
+```
+
+Alternative shapes:
+
+```markdown
+Diagnosis: <what is really happening>
+Mechanism: <why it happens>
+Repair: <minimal structural intervention>
+```
+
+```markdown
+Name candidates:
+
+- `<name>` — <semantic payload, strengths, failure risk>
+  Decision: <best name and why>
+```
+
+```markdown
+Map:
+
+- Primitive: <irreducible part>
+- Boundary: <what it must not absorb>
+- Loop: <feedback cycle>
+- Capture vector: <where it will be corrupted>
+```
+
+```markdown
+Strategy:
+
+- Thesis: <core strategic claim>
+- Arena: <where selection happens>
+- Forces: <pressures shaping outcomes>
+- Leverage: <small intervention with nonlinear effect>
+- Doctrine: <portable rule>
+- Move: <next action>
+```
+
+```markdown
+Concept refinement:
+
+- Raw intuition: <uncompressed signal>
+- Kernel: <irreducible mechanism>
+- Name: <best compression>
+- Boundary: <what the concept must not absorb>
+- Phrase: <forkable one-liner>
+```
+
+## Style Consequences
+
+Style is downstream of cognition.
+
+- Lead with the decisive structure, not the warm-up, while exposing assumptions or uncertainty that could change it.
+- Prefer a sharp model, taxonomy, protocol, or invariant over a generic summary.
+- Use strong verbs and exact nouns.
+- Prefer invariants, gradients, loops, boundaries, and failure modes over feature lists.
+- Replace vague praise with mechanism.
+- Replace false balance with structured alternatives.
+- Mark uncertainty as branches, not mushy hedges.
+- If a concept is basic for the user, compress it to a label or omit it.
+- If a concept is new, define it once in operational terms.
+- Use neologisms sparingly. Each coined term must earn its keep.
+- Preserve the user's vocabulary when it is already sharp.
+
+## Memetic-System Questions
+
+Ask silently or explicitly when useful.
+
+- What pattern is trying to replicate?
+- What carrier makes replication cheap?
+- What host benefits by running it?
+- What incentive gradient stabilizes it?
+- What boundary prevents semantic rot?
+- What ritual keeps it alive after novelty fades?
+- What capture vector will hijack it?
+- What phase change makes old governance fail?
+- What minimal constitution preserves its shape?
+- What phrase makes the system forkable?
+
+## Anti-Patterns
+
+Avoid:
+
+- Generic motivational fog.
+- MBA abstraction without mechanism.
+- Pedagogical over-explanation.
+- Decorative complexity.
+- Ontology inflation.
+- Symmetry theater.
+- Unbounded claims from thin evidence.
+- Neologism spam.
+- Flattening culture, protocol, economics, and interface into one vague ecosystem.
+- Aesthetic density without actionable structure.
+- Worldview projection where evidence is thin.
+- Explaining from the surface when the deep structure is visible.
+
+## Evidence and Safety
+
+High-density mode is not permission to hallucinate. Separate:
+
+- `Observed`: Directly present in user input, files, data, or cited evidence.
+- `Inferred`: Structural reading that follows from observed material.
+- `Speculative`: Useful hypothesis that needs validation.
+
+When stakes are high, preserve compression but name the missing evidence, the risk, and the validation gate.

package/node_modules/@llblab/skills/frontend-design/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: frontend-design
+description: Design, implement, refactor, or review user-facing interfaces. Use whenever work changes how a web or app surface looks, reads, responds, or is operated, including components, pages, forms, dashboards, responsive behavior, accessibility, visual polish, and design systems.
+---
+
+# Frontend Design
+
+Create interfaces that are clear, distinctive, usable, adaptive, and coherent with the product. Fit the existing stack and conventions; treat visible UI coding as design work even when the requested change is small.
+
+## Core Loop
+
+### 1. Inspect and Preserve
+
+Read the changed surface, adjacent components, tokens, styles, content, behavior, and project instructions before editing.
+
+For existing UI, preserve routes, behavior, data contracts, accessibility, content voice, and brand unless the task explicitly changes them. Reuse established primitives and patterns. Distinguish a targeted evolution from an approved redesign.
+
+### 2. Frame the Task
+
+Identify:
+
+- `User and context`: Who uses this, on what device, how often, and under what pressure?
+- `Governing question`: What must the surface help them understand, decide, or do?
+- `Primary path`: What should they notice first, and what is the next action?
+- `Constraints`: Brand, stack, accessibility, performance, localization, content extremes, and scope.
+
+Keep this brief implicit for small changes; write it down only when it prevents ambiguity.
+
+### 3. Shape the Information
+
+Choose the form that matches the task:
+
+- Tables for aligned comparison.
+- Lists for sequences and queues.
+- Timelines for ordered events.
+- Split views for browse-and-inspect.
+- Cards only for genuinely bounded units.
+
+Make hierarchy, status, evidence, uncertainty, action, and recovery scannable. Keep critical context visible; use progressive disclosure for secondary detail, never for trust or safety information. Design loading, empty, partial, stale, error, permission, disabled, and long-content states when relevant.
+
+### 4. Choose One Direction
+
+Commit to one product-specific visual concept and one memorable hook. Let typography, palette, composition, material, iconography, imagery, and motion reinforce it.
+
+Avoid generic dashboard grammar, decoration without meaning, competing accent systems, mixed icon languages, and gratuitous motion. Preserve an established direction unless change is requested. Never let a screenshot or generated image silently invent behavior, content truth, or architecture.
+
+### 5. Protect the UX Floor
+
+In priority order:
+
+1. Semantic structure, keyboard access, visible focus, labels, contrast, non-color meaning, and reduced motion.
+2. Clear task order, comfortable targets, feedback, preserved state, and recovery.
+3. Intrinsic layout that wraps and adapts to content and containers before adding breakpoints.
+4. Stable async space, optimized media, minimal JavaScript, and transform/opacity motion.
+
+Use viewport breakpoints for page-level environment changes and container-aware behavior for reusable components. Define the exact point where a layout must change mode instead of accumulating arbitrary breakpoints.
+
+### 6. Implement as a System
+
+Use semantic markup and the smallest sufficient project-native code. Prefer CSS for layout and visual effects; add JavaScript only for real behavior.
+
+Turn repeated decisions into semantic tokens, finite variants, canonical names, and reusable component contracts. Keep one-off artwork local. Separate destructive actions spatially and semantically. Do not create abstractions that a second real use has not earned.
+
+### 7. Prove the Result
+
+Run the project-required checks, then any additional type, lint, test, or build checks needed to validate the changed behavior or contracts. When rendering is available:
+
+- Inspect narrow, intermediate, and wide contexts.
+- Exercise the primary flow and relevant edge states.
+- Check zoom, focus, overflow, reduced motion, and long/localized content.
+- Run a five-second pass: can a user identify orientation, status, next action, evidence, uncertainty, and recovery?
+- Remove unsupported factual-looking content, fake proof, placeholders presented as truth, and accidental visual noise.
+
+Fix the strongest comprehension or craft gap, then rerender. Static inspection cannot prove rendered quality; state when visual validation was unavailable.
+
+## Completion
+
+Report the chosen direction, changed behavior or design contracts, checks run, visual evidence, and remaining validation limits. The work is done when the primary path is clear, relevant states remain usable, the layout survives real content pressure, and a maintainer can extend the result without inventing a second system.

package/node_modules/@llblab/skills/groq-stt/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md (groq-stt)
+
+[SKILL.md](./SKILL.md) owns the client architecture, invocation, defaults, output format, and speaker-label semantics.
+
+### Operating Principles
+
+- Preserve the Skill's client architecture; keep the Bash entrypoint a delegation-only wrapper.
+- Keep stdout limited to the requested transcript format; diagnostics belong on stderr because attachment handlers insert stdout into user turns.
+- Never print `GROQ_API_KEY` or request headers in diagnostics.
+- Validate arguments and credentials before invoking the Groq API.
+- Preserve the positional interface documented in the Skill for existing `transcribe_groq` callers.
+
+### Discovered Constraints
+
+- Use `response_format=text` for plain output and `verbose_json` only for diarized output.

package/node_modules/@llblab/skills/groq-stt/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: groq-stt
+description: Transcribe audio files using Groq API (Whisper).
+---
+
+# Groq STT Skill
+
+Standalone direct Node.js client for Groq's Whisper transcription API. The canonical client is `scripts/transcribe.mjs`; `scripts/transcribe.sh` is the shell entrypoint wrapper. There are no curl fallbacks or JSON parser dependencies.
+
+## Usage
+
+```bash
+GROQ_API_KEY=xxx ./scripts/transcribe.sh audio.ogg [language] [model] [diarize]
+GROQ_API_KEY=xxx ./scripts/transcribe.sh --file audio.ogg --lang ru --model whisper-large-v3-turbo --diarize true
+```
+
+- Outputs plain transcription text, or timestamped speaker segments when diarization is enabled.
+- Fails fast when the file or `GROQ_API_KEY` is missing.
+
+## CLI Options
+
+- `--file`, `-f` — audio file path.
+- `--lang`, `--language`, `-l` — optional language code; omitted means provider auto-detection.
+- `--model`, `-m` — Groq transcription model; default: `whisper-large-v3-turbo`.
+- `--diarize`, `-d` — `true` to label speaker segments; default: `false`.
+- `--help`, `-h` — usage.
+
+## Dependencies
+
+- Node.js 18+ with built-in `fetch`, `FormData`, and `Blob`.
+- Internet access.
+
+## Notes
+
+- Diarization preserves Groq's `speaker` labels without guessing or merging speakers.

package/node_modules/@llblab/skills/groq-stt/recipes/transcribe-groq.json

@@ -0,0 +1,10 @@
+{
+  "description": "Transcribe an audio file through the Groq STT skill.",
+  "args": [
+    "file:path",
+    "lang:string=ru",
+    "model:string=whisper-large-v3-turbo",
+    "diarize:bool=false"
+  ],
+  "template": "{skill_dir}/scripts/transcribe.sh {file} {lang} {model} {diarize}"
+}

package/node_modules/@llblab/skills/groq-stt/scripts/transcribe.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { argv, env, stderr, stdout } from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// --- Constants ---
+
+const API_KEY = env.GROQ_API_KEY;
+const DEFAULTS = {
+  model: "whisper-large-v3-turbo",
+  endpoint: "https://api.groq.com/openai/v1/audio/transcriptions",
+};
+const CLI_FLAGS = new Map([
+  ["--help", "help"],
+  ["-h", "help"],
+]);
+const CLI_VALUES = new Map([
+  ["--file", "file"],
+  ["-f", "file"],
+  ["--lang", "language"],
+  ["--language", "language"],
+  ["-l", "language"],
+  ["--model", "model"],
+  ["-m", "model"],
+  ["--diarize", "diarize"],
+  ["-d", "diarize"],
+]);
+
+// --- CLI ---
+
+function usage() {
+  return [
+    "Usage:",
+    `  GROQ_API_KEY=xxx ${argv[1]} audio.ogg [language] [model] [diarize]`,
+    `  GROQ_API_KEY=xxx ${argv[1]} --file audio.ogg [--lang ru] [--model ${DEFAULTS.model}] [--diarize true]`,
+    "",
+    "Outputs only transcription text on stdout.",
+  ].join("\n");
+}
+
+function parseArgs(args) {
+  const options = {
+    file: "",
+    language: "",
+    model: DEFAULTS.model,
+    diarize: false,
+    help: false,
+  };
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (CLI_FLAGS.has(arg)) {
+      options[CLI_FLAGS.get(arg)] = true;
+      continue;
+    }
+    if (CLI_VALUES.has(arg)) {
+      const key = CLI_VALUES.get(arg);
+      const value = args[index + 1];
+      if (!value || value.startsWith("--"))
+        throw new Error(`Missing value for ${arg}`);
+      options[key] = value;
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) throw new Error(`Unknown option: ${arg}`);
+    positional.push(arg);
+  }
+  options.file ||= positional[0] ?? "";
+  options.language ||= positional[1] ?? "";
+  options.model =
+    options.model === DEFAULTS.model
+      ? (positional[2] ?? options.model)
+      : options.model;
+  const diarize =
+    options.diarize === false ? (positional[3] ?? false) : options.diarize;
+  if (![true, false, "true", "false"].includes(diarize))
+    throw new Error("diarize must be true or false");
+  options.diarize = diarize === true || diarize === "true";
+  return options;
+}
+
+async function assertReadableFile(file) {
+  try {
+    const info = await stat(file);
+    if (!info.isFile()) throw new Error("not a file");
+  } catch {
+    throw new Error(`Audio file not found: ${file}`);
+  }
+}
+
+function createAudioBlob(buffer, file) {
+  return new Blob([buffer], { type: guessMimeType(file) });
+}
+
+function guessMimeType(file) {
+  const lower = file.toLowerCase();
+  if (lower.endsWith(".ogg") || lower.endsWith(".oga")) return "audio/ogg";
+  if (lower.endsWith(".mp3")) return "audio/mpeg";
+  if (lower.endsWith(".wav")) return "audio/wav";
+  if (lower.endsWith(".m4a") || lower.endsWith(".mp4")) return "audio/mp4";
+  if (lower.endsWith(".webm")) return "audio/webm";
+  if (lower.endsWith(".flac")) return "audio/flac";
+  return "application/octet-stream";
+}
+
+function formatTime(seconds) {
+  const safeSeconds = Number.isFinite(Number(seconds)) ? Number(seconds) : 0;
+  const hours = Math.floor(safeSeconds / 3600)
+    .toString()
+    .padStart(2, "0");
+  const minutes = Math.floor((safeSeconds % 3600) / 60)
+    .toString()
+    .padStart(2, "0");
+  const wholeSeconds = Math.floor(safeSeconds % 60)
+    .toString()
+    .padStart(2, "0");
+  return `${hours}:${minutes}:${wholeSeconds}`;
+}
+
+function formatDiarizedSegments(segments) {
+  return segments
+    .map((segment) => {
+      const text = (segment.text ?? "").trim();
+      if (!text) return "";
+      const speaker = segment.speaker ?? "Unknown speaker";
+      return `[${formatTime(segment.start)}|${speaker}] ${text}`;
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+async function transcribe({ file, language, model, diarize }) {
+  await assertReadableFile(file);
+  if (!API_KEY) throw new Error("GROQ_API_KEY is required");
+  const audio = await readFile(file);
+  const form = new FormData();
+  form.append("file", createAudioBlob(audio, file), basename(file));
+  form.append("model", model);
+  form.append("response_format", diarize ? "verbose_json" : "text");
+  if (language) form.append("language", language);
+  if (diarize) {
+    form.append("diarize", "true");
+    form.append("timestamp_granularities[]", "segment");
+  }
+  const response = await fetch(DEFAULTS.endpoint, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${API_KEY}` },
+    body: form,
+  });
+  if (!response.ok) {
+    const details = await response.text().catch(() => response.statusText);
+    throw new Error(`Groq API error: ${response.status} ${details}`.trim());
+  }
+  if (!diarize) return response.text();
+  const data = await response.json();
+  return formatDiarizedSegments(data.segments ?? []) || data.text || "";
+}
+
+function isDirectCliEntrypoint(metaUrl, entryPath) {
+  if (!entryPath) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(entryPath);
+  } catch {
+    return metaUrl === pathToFileURL(entryPath).href;
+  }
+}
+
+async function main() {
+  const options = parseArgs(argv.slice(2));
+  if (options.help) {
+    stdout.write(`${usage()}\n`);
+    return;
+  }
+  if (!options.file) throw new Error(usage());
+  const text = await transcribe(options);
+  stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+if (isDirectCliEntrypoint(import.meta.url, argv[1])) {
+  try {
+    await main();
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  }
+}
+
+export { formatDiarizedSegments, parseArgs };

package/node_modules/@llblab/skills/groq-stt/scripts/transcribe.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)"
+exec node "$SCRIPT_DIR/transcribe.mjs" "$@"

package/node_modules/@llblab/skills/mistral-stt/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md (mistral-stt)
+
+[SKILL.md](./SKILL.md) owns the client architecture, invocation, defaults, output format, and speaker-label semantics.
+
+### Operating Principles
+
+- Preserve the Skill's client architecture; keep the Bash entrypoint a delegation-only wrapper.
+- Keep stdout limited to the requested transcript format; diagnostics belong on stderr because attachment handlers insert stdout into user turns.
+- Never print `MISTRAL_API_KEY` or request headers in diagnostics.
+- Validate arguments and credentials before invoking the Mistral API.
+- Preserve the positional interface documented in the Skill for existing `transcribe_mistral` callers.
+
+### Discovered Constraints
+
+- Mistral returns JSON for Voxtral transcriptions; parse `text` for plain output and `segments` for diarization under the Skill's speaker-label contract.

package/node_modules/@llblab/skills/mistral-stt/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: mistral-stt
+description: Transcribe audio files using Mistral AI Voxtral.
+---
+
+# Mistral STT Skill
+
+Standalone direct Node.js client for Mistral's Voxtral transcription API. The canonical client is `scripts/transcribe.mjs`; `scripts/transcribe.sh` is the shell entrypoint wrapper. There are no curl fallbacks or Python parser dependencies.
+
+## Usage
+
+```bash
+MISTRAL_API_KEY=xxx ./scripts/transcribe.sh audio.ogg [language] [model] [diarize]
+MISTRAL_API_KEY=xxx ./scripts/transcribe.sh --file audio.ogg --lang ru --model voxtral-mini-latest --diarize true
+```
+
+- Outputs plain transcription text, or timestamped speaker segments when diarization is enabled.
+- Fails fast when the file or `MISTRAL_API_KEY` is missing.
+
+## CLI Options
+
+- `--file`, `-f` — audio file path.
+- `--lang`, `--language`, `-l` — optional language code; omitted means provider auto-detection.
+- `--model`, `-m` — Mistral transcription model; default: `voxtral-mini-latest`.
+- `--diarize`, `-d` — `true` to label speaker segments; default: `false`.
+- `--help`, `-h` — usage.
+
+## Dependencies
+
+- Node.js 18+ with built-in `fetch`, `FormData`, and `Blob`.
+- Internet access.
+
+## Notes
+
+- Diarization preserves Mistral's `speaker_id` values without guessing or merging speakers.

package/node_modules/@llblab/skills/mistral-stt/recipes/transcribe-mistral.json

@@ -0,0 +1,10 @@
+{
+  "description": "Transcribe an audio file through the Mistral STT skill.",
+  "args": [
+    "file:path",
+    "lang:string=ru",
+    "model:string=voxtral-mini-latest",
+    "diarize:bool=false"
+  ],
+  "template": "{skill_dir}/scripts/transcribe.sh {file} {lang} {model} {diarize}"
+}