SKILL.md- the skill, written out in plain English

raw text → Gemini-3-Flash (tag enhancer) → ElevenLabs eleven_v3 → audio/mpeg

POST http://127.0.0.1:3147/voice/speak
Body: {
  "text": "raw text",
  "voiceId"?: "cgSgspJ2msm6clMCkdW9",   // default: Jessica (warm British)
  "modelId"?: "eleven_v3",              // default: eleven_v3 (tags work)
  "tone"?: "professional",              // professional|sultry|hype|calm
  "length"?: "normal",                  // minimal|short|normal|verbose
  "enhance"?: true,                     // default true; false bypasses Gemini
  "voiceSettings"?: { ... }             // overrides tone preset if given
}
Response: audio/mpeg
Headers: x-snappy-voice-enhanced: 0|1, x-snappy-voice-tone, x-snappy-voice-id

ELEVENLABS_API_KEY=sk_...
OPENROUTER_API_KEY=sk-or-v1-...   # for the enhancement step

curl -sS -X POST http://127.0.0.1:3147/voice/speak \
  -H "Content-Type: application/json" \
  -d '{"text":"the build is green","tone":"professional","length":"short"}' \
  -o /tmp/out.mp3 && afplay /tmp/out.mp3

{
  "ts": "2026-04-25T22:57:24Z",
  "voiceId": "cgSgspJ2msm6clMCkdW9",
  "modelId": "eleven_v3",
  "tone": "professional",
  "length": "short",
  "enhanced": true,
  "raw_chars": 41,
  "chars": 65,
  "durationMs": 3564,
  "bytes": 88233,
  "ok": true
}

echo "[$(date -u +%FT%TZ)] voice: <what was missing>" >> state/log/loader-feedback.log

AGENTS.md- what the AI loads when this skill comes up

echo "[$(date -u +%FT%TZ)] voice: <what was missing>" >> state/log/loader-feedback.log

echo "[$(date -u +%FT%TZ)] voice: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * state/lib/voice.ts -- Tone gate and citation gate for snappy-os.
 *
 * Ported from snappy-positioning/api.ts (kernel). Frozen snapshot —
 * reconcile manually at end-of-port comparison, not mid-week.
 *
 * checkTone(text) — banned phrases + rhythm-slop regex + em-dash gate.
 * requireCitations(draft) — forces mining pods to stitch verbatim with
 *   [source: mtg ~mm:ss] tags and wrap connective tissue in
 *   <connective>...</connective>. ≤35% connective ratio.
 *
 * This is the eval source for content-polish and any mining skill.
 * If this file drifts from the kernel copy, evals drift — do not edit
 * casually. See program.md §Voice.
 */

const BANNED_PHRASES: string[] = [
  "10x faster",
  "10x developer",
  "100x speed",
  "in minutes",
  "the operating system for",
  "the X for Y",
  "without the Z",
  "before you Q",
  "at the intersection of",
  "one-stop shop",
  "revolutionize",
  "revolutionary",
  "transform",
  "unleash",
  "unlock",
  "unlock the power of",
  "supercharge",
  "empower",
  "empowering",
  "leverage",
  "synergy",
  "game changer",
  "game-changing",
  "ultimate",
  "cutting edge",
  "bleeding edge",
  "next-gen",
  "next generation",
  "seamless",
  "seamlessly",
  "effortless",
  "effortlessly",
  "AI-powered",
  "AI-native",
  "agentic-first",
  "founder-led",
  "ship-ready",
  "vibe coding",
  "Snappy is",
  "feel confident",
  "feel in control",
  "feel unstuck",
  "my stack is opinionated",
  "i dog-food everything",
  "clear boxes, not black boxes",
  "delve",
  "showcase",
  "noteworthy",
  "multifaceted",
  "tapestry",
  "beacon",
  "meticulous",
  "intricate",
  "commendable",
  "paramount",
  "commence",
  "utilize",
  "robust",
  "streamline",
  "harness",
  "illuminate",
  "facilitate",
  "bolster",
  "underscore",
  "pivotal",
  "realm",
  "foster",
  "landscape",
  "paradigm",
  "ecosystem",
  "spearhead",
  "groundbreaking",
  "transformative",
  "game-changer",
  "elevate",
  "deep dive",
  "unpack",
  "in today's fast-paced",
  "it's worth noting",
  "here's where it gets interesting",
  "here's the kicker",
  "let's break this down",
  "let's unpack",
  "the truth is simple",
  "think of it as",
  "imagine a world where",
  "in conclusion",
  "to sum up",
  "studies show",
  "experts say",
  "it goes without saying",
  "importantly,",
  "interestingly,",
  "notably,",
  "furthermore,",
  "moreover,",
  "additionally,",
  "despite its challenges",
  "i'm excited to announce",
  "without further ado",
  "agree?",
  "thoughts?",
  "at its core",
  "whether you're a",
  "whether you're an",
  "the catch?",
  "your ideas, ai's polish",
];

const RHYTHM_PATTERNS: Array<[RegExp, string]> = [
  [/\bnot\s+\w+,\s+not\s+\w+\s*[—-]/i, "Not X, not Y — Z (rhetorical negation trifecta)"],
  [
    /\bif\s+you're\s+(?:a|an)\s+\w+\s+(?:founder|dev|team|builder|engineer)[^.]*stuck\s+between\b/i,
    "'If you're a [X] stuck between' (AI sales opener)",
  ],
  [
    /\bon\s+your\s+repo,\s+on\s+your\s+\w+\s+problem\b/i,
    "'on your repo, on your real problem' (parallel-clause slop)",
  ],
  [/—\s+that's\s+how\s+you\b/i, "'— that's how you' (AI didactic dash)"],
  [/\bnever\s+\w+[,.].{0,40}\balways\b/i, "Never X, always Y (false-symmetry rule)"],
  [
    /\bthe\s+real\s+\w+\s+is\s+(?:simple|that|this)\b/i,
    "'The real [X] is [reveal]' (AI reveal framing)",
  ],
  [/\bhere's\s+the\s+thing\b/i, "'Here's the thing' (AI pivot)"],
  [/\bat\s+the\s+end\s+of\s+the\s+day\b/i, "'At the end of the day' (filler)"],
  [/—/, "em dash — dead AI tell (voice: use commas/periods or restructure)"],
  [/–/, "en dash — dead AI tell (voice: use commas/periods or restructure)"],
  [
    /\b(agree|thoughts|right\?|make sense)\?\s*$/im,
    "engagement-bait closer ('Agree?' / 'Thoughts?') — LinkedIn slop tell",
  ],
  [
    /\bwhether you're (?:a|an)\s+\w+[,\s]+(?:a|an)?\s*\w+[,\s]+or\s+(?:a|an)?\s*\w+/i,
    "'Whether you're X, Y, or Z' template opener",
  ],
  [
    /\b\d{2,}\+?(?:\s+[\w-]+){0,3}\s+(endpoints|tools|clients|projects|integrations|playbooks|skills|apis|deploys|agents|workflows|automations)\b/i,
    "author-scoreboard count — numbers-about-author are decoys",
  ],
  [
    /(?:^|\n)\s*(?:the catch|the twist|the kicker|the surprise|the result|the reality)\?\s*\n/i,
    "mini-question intro fragment",
  ],
  [
    /(?:^|\n)\s*(?:I was |I noticed |Last (?:week|month|year) I |I had a session |I caught an? |I watched an? |I spent |I realized )/i,
    "personal story opener — lead with insight, not diary",
  ],
];

export function getBannedPhrases(): string[] {
  return [...BANNED_PHRASES];
}

export function checkTone(text: string): { pass: boolean; violations: string[] } {
  const cleaned = text
    .replace(/\[source:[^\]]*\]/gi, "")
    .replace(/<connective>[\s\S]*?<\/connective>/gi, "");
  const lower = cleaned.toLowerCase();
  const violations: string[] = [];

  for (const phrase of BANNED_PHRASES) {
    if (lower.includes(phrase.toLowerCase())) violations.push(phrase);
  }

  const nxMatch = text.match(/\b\d+x\b/gi);
  if (nxMatch) {
    for (const m of nxMatch) {
      if (!violations.includes(m)) violations.push(`${m} (Nx claim)`);
    }
  }

  for (const [re, label] of RHYTHM_PATTERNS) {
    if (re.test(text)) violations.push(label);
  }

  return { pass: violations.length === 0, violations };
}

export function getToneGuide(): {
  oneLiner: string;
  shortTagline: string;
  longTagline: string;
  tuningFork: string[];
  principles: string[];
  doRules: string[];
  dontRules: string[];
} {
  return {
    oneLiner: "Snappy helps developers build and control agents that ship real systems.",
    shortTagline: "We build businesses, not demos.",
    longTagline:
      "Faster than vibe coding. Private AI tools to ship real systems while others prompt. We build businesses, not demos.",
    tuningFork: [
      "You built it. You're stuck. Let's fix that, live on your screen.",
      "We open your codebase together, map the architecture, and start fixing what's blocking you.",
      "I burn the hours so you don't.",
      "Build and control agents to get huge results.",
    ],
    principles: [
      "Lead with what happens, not what Snappy is.",
      "First person. 'I' by default. 'We' only when literally true.",
      "Builder-to-builder. Assume the reader has shipped real software.",
      "Earn every adjective. If you can't defend it on a call, delete it.",
      "The four reference sentences are the tuning fork.",
    ],
    doRules: [
      "Write first person. 'I', 'you', 'we built'. Never marketing third person.",
      "Be direct. State the problem, state the fix, stop talking.",
      "Builder-to-builder. Assume the reader has shipped real software.",
      "Lead with the work. Screens, repos, agents running, commits landing.",
      "Short sentences beat clever sentences.",
      "Name the tool when it matters -- but the tool is never the hero. The outcome is.",
      "Earn every adjective. If you can't defend it on a call, delete it.",
    ],
    dontRules: [
      "No hype. No adjective stacking.",
      "No vibe coding language as our own. We build and control.",
      "No false novelty.",
      "No fake urgency.",
      "No third-person hero narration about Robert.",
      "No personification of Snappy.",
      "No 'MCP integration' or 'Xano MCP' as the headline.",
    ],
  };
}

export type FlowProfile = {
  name: string;
  source: string;
  stdev: number;
  rolling5: number;
  lowVarianceCeiling: number;
  shortFloor: number;
  longFloor: number;
};

export const FLOW_PROFILES: Record<string, FlowProfile> = {
  balanced: {
    name: "balanced",
    source:
      "writer-agnostic telegram detector; loose floors that catch metronome rhythm without prescribing any one stylist",
    stdev: 6.0,
    rolling5: 5.5,
    lowVarianceCeiling: 0.4,
    shortFloor: 0.08,
    longFloor: 0.15,
  },
  pg: {
    name: "pg",
    source:
      "Paul Graham corpus, 30377 sentences across 215 essays (HuggingFace sgoel9/paul_graham_essays, April 2026). Measured: stdev 9.79, rolling5 8.42, lowvar 18%, short 15.1%, long 27.9%",
    stdev: 7.5,
    rolling5: 7.0,
    lowVarianceCeiling: 0.3,
    shortFloor: 0.1,
    longFloor: 0.18,
  },
};

export function checkFlow(
  text: string,
  opts: { minSentences?: number; profile?: string } = {},
): {
  pass: boolean;
  profile: string;
  violations: string[];
  stats: {
    sentences: number;
    meanLength: number;
    medianLength: number;
    stdev: number;
    rolling5Stdev: number;
    lowVarianceWindowRatio: number;
    shortRatio: number;
    longRatio: number;
  };
} {
  const minSentences = opts.minSentences ?? 10;
  const profileName = opts.profile ?? "balanced";
  const profile = FLOW_PROFILES[profileName];
  if (!profile) {
    throw new Error(
      `[checkFlow] unknown profile '${profileName}'. Available: ${Object.keys(FLOW_PROFILES).join(", ")}`,
    );
  }

  const stripped = text
    .replace(/```[\s\S]*?```/g, "")
    .replace(/^#.*$/gm, "")
    .replace(/^---[\s\S]*?---/m, "")
    .replace(/<\/?connective>/gi, "")
    .replace(/\[source:[^\]]*\]/gi, "");

  const sentences = splitSentences(stripped);
  const lengths = sentences.map((s) => s.split(/\s+/).filter(Boolean).length);

  const zeroStats = {
    sentences: lengths.length,
    meanLength: 0,
    medianLength: 0,
    stdev: 0,
    rolling5Stdev: 0,
    lowVarianceWindowRatio: 0,
    shortRatio: 0,
    longRatio: 0,
  };

  if (lengths.length < minSentences) {
    return { pass: true, profile: profileName, violations: [], stats: zeroStats };
  }

  const mean = lengths.reduce((a, b) => a + b, 0) / lengths.length;
  const sorted = [...lengths].sort((a, b) => a - b);
  const median = sorted[Math.floor(sorted.length / 2)];
  const variance = lengths.reduce((a, b) => a + (b - mean) ** 2, 0) / lengths.length;
  const stdev = Math.sqrt(variance);

  const windowStdevs: number[] = [];
  for (let i = 0; i + 5 <= lengths.length; i++) {
    const w = lengths.slice(i, i + 5);
    const wMean = w.reduce((a, b) => a + b, 0) / 5;
    const wVar = w.reduce((a, b) => a + (b - wMean) ** 2, 0) / 5;
    windowStdevs.push(Math.sqrt(wVar));
  }
  const rolling5Stdev =
    windowStdevs.length === 0
      ? stdev
      : windowStdevs.reduce((a, b) => a + b, 0) / windowStdevs.length;
  const lowVarianceWindows = windowStdevs.filter((s) => s < 5).length;
  const lowVarianceWindowRatio =
    windowStdevs.length === 0 ? 0 : lowVarianceWindows / windowStdevs.length;

  const shortRatio = lengths.filter((l) => l < 8).length / lengths.length;
  const longRatio = lengths.filter((l) => l > 20).length / lengths.length;

  const violations: string[] = [];

  if (stdev < profile.stdev) {
    violations.push(
      `stdev ${stdev.toFixed(1)} < ${profile.stdev} floor (profile: ${profile.name}). Vary sentence length more.`,
    );
  }
  if (rolling5Stdev < profile.rolling5) {
    violations.push(
      `rolling-5 window stdev ${rolling5Stdev.toFixed(1)} < ${profile.rolling5} floor (profile: ${profile.name}). Metronome rhythm; break it up.`,
    );
  }
  if (lowVarianceWindowRatio > profile.lowVarianceCeiling) {
    violations.push(
      `${(lowVarianceWindowRatio * 100).toFixed(0)}% of 5-sentence windows have stdev<5, ceiling ${(profile.lowVarianceCeiling * 100).toFixed(0)}% (profile: ${profile.name}). Too many flat runs.`,
    );
  }
  if (shortRatio < profile.shortFloor) {
    violations.push(
      `only ${(shortRatio * 100).toFixed(0)}% of sentences are under 8 words, floor ${(profile.shortFloor * 100).toFixed(0)}% (profile: ${profile.name}). Add short punches for emphasis.`,
    );
  }
  if (longRatio < profile.longFloor) {
    violations.push(
      `only ${(longRatio * 100).toFixed(0)}% of sentences are over 20 words, floor ${(profile.longFloor * 100).toFixed(0)}% (profile: ${profile.name}). Add flowing clause-joined sentences.`,
    );
  }

  return {
    pass: violations.length === 0,
    profile: profileName,
    violations,
    stats: {
      sentences: lengths.length,
      meanLength: Math.round(mean * 10) / 10,
      medianLength: median,
      stdev: Math.round(stdev * 100) / 100,
      rolling5Stdev: Math.round(rolling5Stdev * 100) / 100,
      lowVarianceWindowRatio: Math.round(lowVarianceWindowRatio * 100) / 100,
      shortRatio: Math.round(shortRatio * 100) / 100,
      longRatio: Math.round(longRatio * 100) / 100,
    },
  };
}

function splitSentences(text: string): string[] {
  return text
    .split(/(?<=[.!?])\s+/)
    .map((s) => s.trim())
    .filter((s) => s.length > 0 && /[A-Za-z]/.test(s));
}

export function requireCitations(draft: string): {
  pass: boolean;
  totalSentences: number;
  citedSentences: number;
  connectiveSentences: number;
  uncitedSentences: string[];
  connectiveRatio: number;
  reasons: string[];
} {
  const stripped = draft
    .replace(/```[\s\S]*?```/g, "")
    .replace(/^#.*$/gm, "")
    .replace(/^---.*$/gm, "");

  const connectiveMatches = stripped.match(/<connective>[\s\S]*?<\/connective>/gi) || [];
  const connectiveSentences = connectiveMatches.reduce((n, chunk) => {
    const inner = chunk.replace(/<\/?connective>/gi, "");
    return n + splitSentences(inner).length;
  }, 0);
  const withoutConnective = stripped.replace(/<connective>[\s\S]*?<\/connective>/gi, "");

  const sentences = splitSentences(withoutConnective);
  const citeRe = /\[source:\s*[^\]]+?~\s*\d{1,3}:\d{2}[^\]]*\]/i;

  const cited: string[] = [];
  const uncited: string[] = [];
  for (const s of sentences) {
    if (citeRe.test(s)) cited.push(s);
    else uncited.push(s);
  }

  const totalSentences = sentences.length + connectiveSentences;
  const citedSentences = cited.length;
  const connectiveRatio = totalSentences === 0 ? 0 : connectiveSentences / totalSentences;

  const reasons: string[] = [];
  if (uncited.length > 0) {
    reasons.push(
      `${uncited.length} prose sentence(s) lack [source: ...~mm:ss] citation and are not wrapped in <connective>...`,
    );
  }
  if (connectiveRatio > 0.35) {
    reasons.push(
      `connective tissue ratio ${(connectiveRatio * 100).toFixed(0)}% exceeds 35% budget`,
    );
  }

  return {
    pass: reasons.length === 0,
    totalSentences,
    citedSentences,
    connectiveSentences,
    uncitedSentences: uncited,
    connectiveRatio,
    reasons,
  };
}

scripts- helper scripts it can run

prose-only skill - 6 inline code blocks live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 9 runs