@gobing-ai/knowledge-kit 0.0.9 → 0.0.10

package/plugins/generations/voice-gen/src/qc.ts

@@ -0,0 +1,157 @@
+import type { VoiceboxClient } from './voicebox-client';
+import type { VoiceScript, VoiceSegment } from './voicescript';
+
+export interface SegmentQualityAudit {
+    segmentIndex: number;
+    text: string;
+    duration: number;
+    expectedDurationRange: [number, number];
+    speechRateCharsPerSec: number;
+    transcription?: string;
+    repetitionDetected: boolean;
+    durationAnomaly: boolean;
+    issues: string[];
+    passed: boolean;
+}
+
+export interface VoiceQualityReport {
+    passed: boolean;
+    totalDuration: number;
+    overallScore: number; // 0 to 100
+    segmentAudits: SegmentQualityAudit[];
+    criticalIssues: string[];
+}
+
+/**
+ * Detects stuttering, repetitive loops, or mode collapse in text.
+ * E.g., "酒酒酒酒酒", "这种这种这种这种", "我会帮您收拾到最新的节目我会帮您收拾到最新的节目"
+ */
+export function detectRepetitions(text: string): boolean {
+    const trimmed = text.trim();
+    if (trimmed.length < 4) {
+        return false;
+    }
+
+    // 1. Single character repeated 3+ times (e.g. "酒酒酒" or "诶诶诶")
+    if (/(.)\1{2,}/u.test(trimmed)) {
+        return true;
+    }
+
+    // 2. 2-to-3 character word repeated 3+ times (e.g. "这种这种这种")
+    if (/(.{2,3}?)\1{2,}/u.test(trimmed)) {
+        return true;
+    }
+
+    // 3. 4-to-30 character phrase repeated 2+ times consecutively
+    if (/(.{4,30}?)\1{1,}/u.test(trimmed)) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * Compute expected speech duration range given text and language.
+ */
+export function computeExpectedDurationRange(text: string, language = 'zh'): [number, number] {
+    const cleanText = text.replace(/\[[^\]]+\]/g, '').trim(); // ignore [laugh] tags
+    const isZh = language.toLowerCase().startsWith('zh');
+
+    if (isZh) {
+        const charCount = cleanText.replace(/\s+/g, '').length;
+        const minSec = Math.max(1.0, charCount / 7.0);
+        const maxSec = Math.max(2.5, charCount / 2.2 + 2.5);
+        return [Number(minSec.toFixed(2)), Number(maxSec.toFixed(2))];
+    }
+
+    const wordCount = cleanText.split(/\s+/).filter(Boolean).length;
+    const minSec = Math.max(1.0, wordCount / 5.0);
+    const maxSec = Math.max(2.5, wordCount / 1.5 + 2.5);
+    return [Number(minSec.toFixed(2)), Number(maxSec.toFixed(2))];
+}
+
+/**
+ * Audit the quality of synthesized voice segments.
+ */
+export async function auditVoiceSegments(
+    script: VoiceScript,
+    segmentWavs: Uint8Array[],
+    segmentMetadata: Array<{ generationId: string; profile: string; duration: number }>,
+    client?: VoiceboxClient,
+): Promise<VoiceQualityReport> {
+    const audits: SegmentQualityAudit[] = [];
+    const criticalIssues: string[] = [];
+    let totalDuration = 0;
+
+    for (let i = 0; i < script.segments.length; i++) {
+        const segment = script.segments[i] as VoiceSegment;
+        const meta = segmentMetadata[i];
+        const wavBytes = segmentWavs[i];
+        const duration = meta?.duration ?? 0;
+        totalDuration += duration;
+
+        const lang = segment.language ?? script.language ?? 'zh';
+        const [minExpected, maxExpected] = computeExpectedDurationRange(segment.text, lang);
+        const cleanLen = segment.text.replace(/\s+/g, '').length;
+        const speechRate = duration > 0 ? cleanLen / duration : 0;
+
+        const issues: string[] = [];
+        let durationAnomaly = false;
+
+        // Check duration anomaly: duration exceeds 1.5x max expected or rate < 1.8 chars/sec on >= 8 chars
+        if (cleanLen >= 8 && (duration > maxExpected * 1.5 || speechRate < 1.8)) {
+            durationAnomaly = true;
+            issues.push(
+                `Duration anomaly: ${duration.toFixed(2)}s is unusually long for ${cleanLen} chars (expected ${minExpected}-${maxExpected}s, rate ${speechRate.toFixed(1)} chars/s)`,
+            );
+        }
+
+        let transcriptionText: string | undefined;
+        let repetitionDetected = false;
+
+        if (client && wavBytes && typeof client.transcribe === 'function') {
+            try {
+                const trans = await client.transcribe(wavBytes, lang);
+                transcriptionText = trans.text;
+                if (detectRepetitions(transcriptionText)) {
+                    repetitionDetected = true;
+                    issues.push(
+                        `Repetition hallucination detected in audio transcription: "${transcriptionText.slice(0, 80)}..."`,
+                    );
+                }
+            } catch {
+                // Transcription service unavailable or optional
+            }
+        }
+
+        const passed = !durationAnomaly && !repetitionDetected;
+        if (!passed) {
+            criticalIssues.push(`Segment ${i + 1} (${meta?.profile || 'Unknown'}): ${issues.join('; ')}`);
+        }
+
+        audits.push({
+            segmentIndex: i,
+            text: segment.text,
+            duration,
+            expectedDurationRange: [minExpected, maxExpected],
+            speechRateCharsPerSec: Number(speechRate.toFixed(2)),
+            transcription: transcriptionText,
+            repetitionDetected,
+            durationAnomaly,
+            issues,
+            passed,
+        });
+    }
+
+    const passedCount = audits.filter((a) => a.passed).length;
+    const overallScore = audits.length > 0 ? Math.round((passedCount / audits.length) * 100) : 100;
+    const allPassed = criticalIssues.length === 0;
+
+    return {
+        passed: allPassed,
+        totalDuration: Number(totalDuration.toFixed(2)),
+        overallScore,
+        segmentAudits: audits,
+        criticalIssues,
+    };
+}

package/plugins/generations/voice-gen/src/voicebox-client.ts

@@ -1,3 +1,9 @@
+export interface EffectConfig {
+    type: string;
+    enabled?: boolean;
+    params?: Record<string, number>;
+}
+
 export interface VoiceboxGenerateBody {
     profile_id: string;
     text: string;
@@ -6,8 +12,10 @@ export interface VoiceboxGenerateBody {
     instruct?: string;
     max_chunk_chars: number;
     crossfade_ms: number;
-    personality: false;
-    normalize: true;
+    personality?: boolean;
+    normalize?: boolean;
+    seed?: number | null;
+    effects_chain?: EffectConfig[] | null;
 }
 
 export interface VoiceboxProfile {
@@ -36,6 +44,7 @@ export interface VoiceboxClient {
         pollMs?: number,
     ): Promise<{ status: 'completed' | 'failed'; duration?: number; error?: string }>;
     downloadAudio(id: string): Promise<Uint8Array>;
+    transcribe(audio: Uint8Array, language?: string): Promise<{ text: string; duration?: number }>;
 }
 
 export interface VoiceboxClientOptions {
@@ -219,5 +228,34 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
                 throw new Error(`Voicebox /audio/${id} failed to read audio stream at ${url}: ${reason}`);
             }
         },
+
+        async transcribe(audio: Uint8Array, language = 'zh'): Promise<{ text: string; duration?: number }> {
+            const formData = new FormData();
+            const blob = new Blob([audio], { type: 'audio/wav' });
+            formData.append('file', blob, 'audio.wav');
+            formData.append('language', language);
+
+            let res: Response;
+            try {
+                res = await customFetch(`${url}/transcribe`, {
+                    method: 'POST',
+                    body: formData,
+                });
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /transcribe request failed at ${url}: ${reason}`);
+            }
+
+            if (!res.ok) {
+                throw new Error(`Voicebox /transcribe failed at ${url}: HTTP ${res.status} ${res.statusText}`);
+            }
+
+            try {
+                return (await res.json()) as { text: string; duration?: number };
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /transcribe returned invalid JSON at ${url}: ${reason}`);
+            }
+        },
     };
 }

package/plugins/generations/voice-gen/src/voicescript.ts

@@ -1,4 +1,5 @@
 import type { Doc } from '@gobing-ai/kk-core';
+import type { EffectConfig } from './voicebox-client';
 
 export const VOICEBOX_TEXT_MAX = 50_000;
 export const VOICEBOX_INSTRUCT_MAX = 500;
@@ -45,6 +46,43 @@ export const VOICEBOX_LANGUAGES = [
     'tr',
 ] as const;
 
+export const BUILTIN_EFFECT_PRESETS: Record<string, EffectConfig[]> = {
+    robotic: [
+        {
+            type: 'chorus',
+            enabled: true,
+            params: { rate_hz: 0.2, depth: 1.0, feedback: 0.35, centre_delay_ms: 7.0, mix: 0.5 },
+        },
+    ],
+    radio: [
+        { type: 'highpass', enabled: true, params: { cutoff_frequency_hz: 300.0 } },
+        { type: 'lowpass', enabled: true, params: { cutoff_frequency_hz: 3500.0 } },
+        {
+            type: 'compressor',
+            enabled: true,
+            params: { threshold_db: -15.0, ratio: 6.0, attack_ms: 5.0, release_ms: 50.0 },
+        },
+        { type: 'gain', enabled: true, params: { gain_db: 6.0 } },
+    ],
+    'echo chamber': [
+        {
+            type: 'reverb',
+            enabled: true,
+            params: { room_size: 0.85, damping: 0.3, wet_level: 0.45, dry_level: 0.55, width: 1.0 },
+        },
+        { type: 'delay', enabled: true, params: { delay_seconds: 0.25, feedback: 0.3, mix: 0.2 } },
+    ],
+    'deep voice': [
+        { type: 'pitch_shift', enabled: true, params: { semitones: -3.0 } },
+        { type: 'lowpass', enabled: true, params: { cutoff_frequency_hz: 6000.0 } },
+        {
+            type: 'compressor',
+            enabled: true,
+            params: { threshold_db: -18.0, ratio: 3.0, attack_ms: 10.0, release_ms: 150.0 },
+        },
+    ],
+};
+
 const ENGINE_SET = new Set<string>(VOICEBOX_ENGINES);
 const LANGUAGE_SET = new Set<string>(VOICEBOX_LANGUAGES);
 
@@ -60,23 +98,67 @@ function assertLanguage(value: string | undefined, label: string): void {
     }
 }
 
+export function resolveEffectsChain(customChain?: EffectConfig[], presetName?: string): EffectConfig[] | undefined {
+    if (customChain && customChain.length > 0) {
+        return customChain;
+    }
+    if (presetName) {
+        const normalized = presetName.trim().toLowerCase();
+        const preset = BUILTIN_EFFECT_PRESETS[normalized];
+        if (preset) {
+            return preset;
+        }
+    }
+    return undefined;
+}
+
+export function resolveInstruct(instruct?: string, emotion?: string): string | undefined {
+    if (instruct && emotion) {
+        const lower = instruct.toLowerCase();
+        if (lower.includes(emotion.toLowerCase())) {
+            return instruct;
+        }
+        return `${instruct}. Emotion: ${emotion}`;
+    }
+    if (instruct) {
+        return instruct;
+    }
+    if (emotion) {
+        return `Speak in a ${emotion} tone.`;
+    }
+    return undefined;
+}
+
 export interface VoiceSpeaker {
-    profile: string;
+    profile?: string;
+    profile_id?: string;
+    name?: string;
+    role?: string;
     engine?: string;
     language?: string;
+    emotion?: string;
     instruct?: string;
+    effects_chain?: EffectConfig[];
+    effect_preset?: string;
+    personality?: boolean;
 }
 
 export interface VoiceSegment {
     speaker?: string;
     profile?: string;
+    profile_id?: string;
     text: string;
+    emotion?: string;
     instruct?: string;
     engine?: string;
     language?: string;
     gap_ms?: number;
     max_chunk_chars?: number;
     crossfade_ms?: number;
+    personality?: boolean;
+    seed?: number;
+    effects_chain?: EffectConfig[];
+    effect_preset?: string;
 }
 
 export interface VoiceScript {
@@ -84,13 +166,26 @@ export interface VoiceScript {
     language?: string;
     default_engine?: string;
     default_profile?: string;
+    default_profile_id?: string;
+    default_emotion?: string;
+    default_effects_chain?: EffectConfig[];
+    default_effect_preset?: string;
     max_chunk_chars?: number;
     crossfade_ms?: number;
     speakers?: Record<string, VoiceSpeaker>;
     segments: VoiceSegment[];
 }
 
-const VOICESCRIPT_KEYS = new Set(['segments', 'speakers', 'default_profile', 'default_engine']);
+const VOICESCRIPT_KEYS = new Set([
+    'segments',
+    'speakers',
+    'default_profile',
+    'default_profile_id',
+    'default_engine',
+    'default_emotion',
+    'default_effects_chain',
+    'default_effect_preset',
+]);
 
 /**
  * Parse a Doc into a VoiceScript structure.
@@ -107,7 +202,11 @@ export function parseDocToVoiceScript(doc: Doc, envDefaultProfile?: string): Voi
         try {
             parsed = JSON.parse(trimmed);
         } catch {
-            throw new Error('Invalid VoiceScript JSON structure: failed to parse JSON object');
+            try {
+                parsed = Bun.YAML.parse(trimmed);
+            } catch {
+                throw new Error('Invalid VoiceScript JSON structure: failed to parse JSON object');
+            }
         }
         if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
             throw new Error('Invalid VoiceScript JSON structure: root must be a JSON object');
@@ -115,13 +214,17 @@ export function parseDocToVoiceScript(doc: Doc, envDefaultProfile?: string): Voi
         return parsed as VoiceScript;
     }
 
-    if (trimmed.startsWith('[')) {
-        return {
-            segments: [{ text: trimmed }],
-            default_profile:
-                envDefaultProfile ??
-                (typeof doc.metadata?.voiceProfile === 'string' ? doc.metadata.voiceProfile : undefined),
-        };
+    if (trimmed.startsWith('[') && !trimmed.startsWith('[-')) {
+        // Plain text starting with paralinguistic tag e.g. [laugh] or [sigh]
+        const hasYamlStructure = trimmed.includes('segments:') || trimmed.includes('speakers:');
+        if (!hasYamlStructure) {
+            return {
+                segments: [{ text: trimmed }],
+                default_profile:
+                    envDefaultProfile ??
+                    (typeof doc.metadata?.voiceProfile === 'string' ? doc.metadata.voiceProfile : undefined),
+            };
+        }
     }
 
     try {
@@ -161,7 +264,11 @@ export function mergeVoiceScripts(scripts: VoiceScript[], docs: Doc[], envDefaul
 
     let title: string | undefined;
     let defaultProfile: string | undefined = envDefaultProfile;
+    let defaultProfileId: string | undefined;
     let defaultEngine: string | undefined;
+    let defaultEmotion: string | undefined;
+    let defaultEffectsChain: EffectConfig[] | undefined;
+    let defaultEffectPreset: string | undefined;
     let language: string | undefined;
     let maxChunkChars: number | undefined;
     let crossfadeMs: number | undefined;
@@ -179,12 +286,24 @@ export function mergeVoiceScripts(scripts: VoiceScript[], docs: Doc[], envDefaul
         if (script.default_profile && defaultProfile === envDefaultProfile) {
             defaultProfile = script.default_profile;
         }
+        if (script.default_profile_id && !defaultProfileId) {
+            defaultProfileId = script.default_profile_id;
+        }
         if (!defaultProfile && typeof doc?.metadata?.voiceProfile === 'string') {
             defaultProfile = doc.metadata.voiceProfile;
         }
         if (!defaultEngine && script.default_engine) {
             defaultEngine = script.default_engine;
         }
+        if (!defaultEmotion && script.default_emotion) {
+            defaultEmotion = script.default_emotion;
+        }
+        if (!defaultEffectsChain && script.default_effects_chain) {
+            defaultEffectsChain = script.default_effects_chain;
+        }
+        if (!defaultEffectPreset && script.default_effect_preset) {
+            defaultEffectPreset = script.default_effect_preset;
+        }
         if (!language && script.language) {
             language = script.language;
         }
@@ -220,9 +339,21 @@ export function mergeVoiceScripts(scripts: VoiceScript[], docs: Doc[], envDefaul
     if (defaultProfile) {
         result.default_profile = defaultProfile;
     }
+    if (defaultProfileId) {
+        result.default_profile_id = defaultProfileId;
+    }
     if (defaultEngine) {
         result.default_engine = defaultEngine;
     }
+    if (defaultEmotion) {
+        result.default_emotion = defaultEmotion;
+    }
+    if (defaultEffectsChain) {
+        result.default_effects_chain = defaultEffectsChain;
+    }
+    if (defaultEffectPreset) {
+        result.default_effect_preset = defaultEffectPreset;
+    }
     if (language) {
         result.language = language;
     }
@@ -282,8 +413,8 @@ export function validateVoiceScript(script: VoiceScript): void {
             if (!speaker || typeof speaker !== 'object') {
                 throw new Error(`Speaker "${name}" definition must be an object`);
             }
-            if (!speaker.profile || typeof speaker.profile !== 'string') {
-                throw new Error(`Speaker "${name}" must have a profile specified`);
+            if (!speaker.profile && !speaker.profile_id) {
+                throw new Error(`Speaker "${name}" must have a profile or profile_id specified`);
             }
             if (
                 speaker.instruct &&
@@ -359,6 +490,12 @@ export function validateVoiceScript(script: VoiceScript): void {
             }
         }
 
+        if (segment.seed !== undefined) {
+            if (typeof segment.seed !== 'number' || !Number.isInteger(segment.seed) || segment.seed < 0) {
+                throw new Error('seed must be a non-negative integer');
+            }
+        }
+
         assertEngine(segment.engine, `Segment at index ${idx}`);
         assertLanguage(segment.language, `Segment at index ${idx}`);
     }

package/plugins/kk/commands/workflow-run.md

@@ -1,18 +1,21 @@
 ---
 name: workflow-run
 description: >-
-  Run STORM daily research or IT content authoring end to end. Installs the workflow
-  YAML on first run (two-root copy rule), creates the config with defaults if missing,
-  computes the workspace, and shells spur workflow run against the installed workflow.
+  Run STORM daily research, IT content authoring, or solo-podcast end to end.
+  Resolves the workflow YAML from the user override, KK_WORKFLOWS_SOURCE, the
+  installed kk package root, or a repo checkout — runs in place from any cwd;
+  creates the config with defaults if missing; computes the workspace; shells
+  spur workflow run against the resolved YAML.
 argument-hint: "[name] <topic|--in file> [--dir <path>] [--playbook generic|english|wechat] [--research] [--judge] [--outline <a|b|c>] [--writer itc-generating|topic] [--duration <min>] [--language <code>] [--script-approved] [--fixture] [--force]"
 ---
 
 Thin runner around the **storm-research**, **itc-generating** / **topic**, and **kk-solo-podcast**
 capabilities. Read `plugins/kk/skills/storm-research/SKILL.md` or
-`plugins/kk/skills/itc-generating/SKILL.md` for craft; solo-podcast craft is inlined in the
-workflow `agent.run` prompt (no fat skill). This command owns the run procedure: config create,
-YAML install (two-root copy rule) into `$HOME/.config/kk/workflows`, workspace computation, and
-the `spur workflow run` of that **runtime** dest. Design-time SSOT remains
+`plugins/kk/skills/itc-generating/SKILL.md` for craft; solo-podcast craft lives in the
+`audio-authoring` skill. This command owns the run procedure: config create,
+workflow YAML resolution (user override → `$KK_WORKFLOWS_SOURCE` → **installed package
+root** → repo checkout, runs in place from any cwd), workspace computation, and the
+`spur workflow run` of the resolved YAML. Design-time SSOT remains
 `plugins/kk/workflows/` in the package/repo. No new `kk` CLI noun (ADR-011) — everything here
 is shell + the workflow.
 
@@ -75,46 +78,58 @@ EOF
 `--fixture` sets `fixture=true` regardless of the file. `FIRECRAWL_API_KEY` is **never** read
 from config — env-only.
 
-## 3. Install the workflow YAML
+## 3. Resolve the workflow YAML (run anywhere)
 
-`dest="$workflows_dir/$NAME.yaml"`. Copy from the **first hit** of, in order:
+The workflow YAML runs **in place** — no copy on the happy path. Resolve the `kk`
+package root from the binary itself (works under bun/npm/nvm/homebrew prefixes):
 
-1. `$KK_WORKFLOWS_SOURCE/$NAME.yaml`
-2. `plugins/kk/workflows/$NAME.yaml`
+```bash
+kbin="$(command -v kk 2>/dev/null || true)"
+while [ -L "$kbin" ]; do
+  link="$(readlink "$kbin")"
+  case "$link" in /*) kbin="$link";; *) kbin="$(dirname "$kbin")/$link";; esac
+done
+pkg=""; [ -n "$kbin" ] && pkg="$(cd "$(dirname "$kbin")/.." 2>/dev/null && pwd || true)"
+```
+
+Resolution order — first hit wins:
 
-- `dest` missing → copy from the first hit. Source missing from both roots → exit 1, stderr
-  lists the roots searched: `no source workflow for $NAME (searched KK_WORKFLOWS_SOURCE, plugins/kk/workflows)`.
-- `dest` exists + `--force` → overwrite from source.
-- `dest` exists + identical bytes → no-op.
-- `dest` exists + different bytes → **warn and leave** (run proceeds with the user's copy).
+1. **User override** `$workflows_dir/$NAME.yaml` (default `~/.config/kk/workflows/`) —
+   when it exists it always wins, and nothing is copied.
+2. `$KK_WORKFLOWS_SOURCE/$NAME.yaml`
+3. `$pkg/plugins/kk/workflows/$NAME.yaml` — the installed package copy
+4. `plugins/kk/workflows/$NAME.yaml` — repo checkout (development)
 
 ```bash
-src=""
-for d in "$KK_WORKFLOWS_SOURCE" "plugins/kk/workflows"; do
-  [ -n "$d" ] && [ -f "$d/$NAME.yaml" ] && { src="$d/$NAME.yaml"; break; }
-done
-[ -z "$src" ] && { echo "no source workflow for $NAME (searched KK_WORKFLOWS_SOURCE, plugins/kk/workflows)" >&2; exit 1; }
-if [ ! -f "$dest" ] || [ "$FORCE" = true ]; then
-  install -d "$(dirname "$dest")" && cp "$src" "$dest"
-elif ! cmp -s "$src" "$dest"; then
-  echo "warning: $dest differs from install source; leaving user copy (pass --force to replace)" >&2
+dest=""
+if [ -f "$workflows_dir/$NAME.yaml" ]; then
+  dest="$workflows_dir/$NAME.yaml"
+else
+  for d in "$KK_WORKFLOWS_SOURCE" ${pkg:+"$pkg/plugins/kk/workflows"} "plugins/kk/workflows"; do
+    [ -n "$d" ] && [ -f "$d/$NAME.yaml" ] && { dest="$d/$NAME.yaml"; break; }
+  done
+  [ -z "$dest" ] && { echo "no source workflow for $NAME (searched $workflows_dir, KK_WORKFLOWS_SOURCE, kk package root, plugins/kk/workflows)" >&2; exit 1; }
 fi
-# Runtime dest is $workflows_dir (default ~/.config/kk/workflows). Copy YAML sidecars
-# that the machine shells (kk-solo-podcast: validate-voicescript.ts).
-if [ "$NAME" = "kk-solo-podcast" ] && [ -n "$src" ]; then
-  side="validate-voicescript.ts"
-  sdir=$(dirname "$src")
-  ddir=$(dirname "$dest")
-  if [ -f "$sdir/$side" ]; then
-    if [ ! -f "$ddir/$side" ] || [ "$FORCE" = true ]; then
-      cp "$sdir/$side" "$ddir/$side"
-    elif ! cmp -s "$sdir/$side" "$ddir/$side"; then
-      echo "warning: $ddir/$side differs from install source; leaving user copy (pass --force to replace)" >&2
-    fi
-  fi
+# --force: refresh the user override from the best available source, then run the override.
+if [ "$FORCE" = true ]; then
+  src=""
+  for d in "$KK_WORKFLOWS_SOURCE" ${pkg:+"$pkg/plugins/kk/workflows"} "plugins/kk/workflows"; do
+    [ -n "$d" ] && [ -f "$d/$NAME.yaml" ] && { src="$d/$NAME.yaml"; break; }
+  done
+  [ -z "$src" ] && { echo "no source workflow for $NAME to force-install (searched KK_WORKFLOWS_SOURCE, kk package root, plugins/kk/workflows)" >&2; exit 1; }
+  install -d "$workflows_dir" && cp "$src" "$workflows_dir/$NAME.yaml"
+  dest="$workflows_dir/$NAME.yaml"
 fi
 ```
 
+- To customize a workflow, copy it to `$workflows_dir/$NAME.yaml` yourself (or use
+  `--force` to place a fresh copy there) — that override wins on every later run.
+- No auto-copy, no drift warnings: the package copy is versioned with the CLI and
+  never goes stale; overrides are explicit.
+- Sidecars (`validate-voicescript.ts`, `wrap-voicescript-doc.ts`) are **not copied** —
+  the workflow's own fallback chain resolves them via `$KK_WORKFLOWS_DIR`, the package
+  root, then `$HOME/.config/kk/workflows`.
+
 ## 4. Compute workspace
 
 ### Profile `kk-storm-research` (0056 `topicId`)
@@ -144,11 +159,12 @@ mkdir -p "$work_dir"
 `kebab` = lower-case, `[^a-z0-9]+` → `-`, trimmed dashes (no length cap, no sha256 hash).
 `work_dir="${DIR:-./$kebab}"`. Empty derived `kebab` → exit 1.
 
-### Profile `kk-solo-podcast`
+### Profile `kk-solo-podcast` / `kk-daily-ai-voice`
 
+`date` = today's date in `YYYY-MM-DD` (`$(date +%Y-%m-%d)`).
 `raw` = `TOPIC` or file-mode first ATX H1 else basename without extension.
 `kebab` = lower-case, `[^a-z0-9]+` → `-`, trimmed dashes (no length cap, no sha256 hash).
-`work_dir="${DIR:-$works_dir/$kebab}"`. Empty derived `kebab` → exit 1.
+`work_dir="${DIR:-$works_dir/kk-solo-podcast/$date}"`.
 
 ## 5. Run the workflow
 
@@ -157,8 +173,9 @@ All values are strings.
 ### Profile `kk-storm-research`
 
 Bind vars: `maxResults` and `fixture` from step 2; `plugins_path` defaults to `./plugins`
-in a checkout, else installed package `plugins/` or `KK_PLUGIN_PATH`; `render_script` is
-`plugins/kk/scripts/render-md.ts`.
+in a checkout, else `$pkg/plugins` (package root from step 3) or `KK_PLUGIN_PATH`;
+`render_script` is `plugins/kk/scripts/render-md.ts` in a checkout, else
+`$pkg/plugins/kk/scripts/render-md.ts`.
 
 ```bash
 spur workflow run "$dest" --vars \
@@ -168,24 +185,29 @@ spur workflow run "$dest" --vars \
 ### Profile `kk-itc`
 
 Bind vars: `topic`, `input_file`, `work_dir`, `writer`, `playbook`, `research`, `judge`, `outline`,
-`force`, `rubric` (`tech-accuracy`), `verdictFile` (`.spur/run/${vars.__runId}-itc-verdict.json`), `agent`.
+`force`, `rubric` (`tech-accuracy`), `agent`. The judge verdict lands at `$work_dir/.itc-verdict.json`
+(fixed path inside the workflow).
 
 ```bash
 spur workflow run "$dest" --vars \
-  "{\"topic\":\"$TOPIC\",\"input_file\":\"$INPUT_FILE\",\"work_dir\":\"$work_dir\",\"writer\":\"$WRITER\",\"playbook\":\"$PLAYBOOK\",\"research\":\"$RESEARCH\",\"judge\":\"$JUDGE\",\"outline\":\"$OUTLINE\",\"force\":\"$FORCE\",\"rubric\":\"tech-accuracy\",\"verdictFile\":\".spur/run/\${vars.__runId}-itc-verdict.json\",\"agent\":\"$AGENT\"}"
+  "{\"topic\":\"$TOPIC\",\"input_file\":\"$INPUT_FILE\",\"work_dir\":\"$work_dir\",\"writer\":\"$WRITER\",\"playbook\":\"$PLAYBOOK\",\"research\":\"$RESEARCH\",\"judge\":\"$JUDGE\",\"outline\":\"$OUTLINE\",\"force\":\"$FORCE\",\"rubric\":\"tech-accuracy\",\"agent\":\"$AGENT\"}"
 ```
 
 ### Profile `kk-solo-podcast`
 
 Bind vars: `topic`, `input_file`, `work_dir`, `outline`, `script_approved`, `force`,
 `target_duration_min`, `language`, `voice_profile` (from `VOICEBOX_DEFAULT_PROFILE` or empty),
-`validate_script` (`$workflows_dir/validate-voicescript.ts`), `plugins_path` (empty → ADR-012
-default discovery), `agent`. **Always** `spur workflow run "$dest"` — `$dest` is
-`$workflows_dir/kk-solo-podcast.yaml`, never the design-time `plugins/kk/workflows/` path.
+`validate_script` (`$workflows_dir/validate-voicescript.ts` when that override exists, else
+empty), `wrap_script` (`$workflows_dir/wrap-voicescript-doc.ts` when that override exists,
+else empty) — empty binds let the workflow's fallback chain resolve via the package root.
+`plugins_path` (empty → ADR-012 default discovery), `agent`. `$dest` is the user override
+when present, else the package/checkout YAML resolved in step 3 — never a hardcoded path.
 
 ```bash
+vs_arg=""; [ -f "$workflows_dir/validate-voicescript.ts" ] && vs_arg="$workflows_dir/validate-voicescript.ts"
+ws_arg=""; [ -f "$workflows_dir/wrap-voicescript-doc.ts" ] && ws_arg="$workflows_dir/wrap-voicescript-doc.ts"
 spur workflow run "$dest" --vars \
-  "{\"topic\":\"$TOPIC\",\"input_file\":\"$INPUT_FILE\",\"work_dir\":\"$work_dir\",\"outline\":\"$OUTLINE\",\"script_approved\":\"$SCRIPT_APPROVED\",\"force\":\"$FORCE\",\"target_duration_min\":\"$DURATION\",\"language\":\"$LANGUAGE\",\"voice_profile\":\"$VOICE_PROFILE\",\"validate_script\":\"$workflows_dir/validate-voicescript.ts\",\"plugins_path\":\"\",\"agent\":\"$AGENT\"}"
+  "{\"topic\":\"$TOPIC\",\"input_file\":\"$INPUT_FILE\",\"work_dir\":\"$work_dir\",\"outline\":\"$OUTLINE\",\"script_approved\":\"$SCRIPT_APPROVED\",\"force\":\"$FORCE\",\"target_duration_min\":\"$DURATION\",\"language\":\"$LANGUAGE\",\"voice_profile\":\"$VOICE_PROFILE\",\"validate_script\":\"$vs_arg\",\"wrap_script\":\"$ws_arg\",\"plugins_path\":\"\",\"agent\":\"$AGENT\"}"
 ```
 
 ## 6. Report