@gobing-ai/knowledge-kit 0.0.9 → 0.0.10

package/plugins/kk/workflows/kk-solo-podcast.yaml

@@ -3,7 +3,8 @@
 name: kk-solo-podcast
 kind: state-machine
 description: >-
-  Solo podcast authoring pipeline using VoiceScript authoring, Spur HITL gates, and voice-gen audio generation
+  Solo podcast authoring pipeline over the kk:audio-authoring skill, Spur HITL gates,
+  and voice-gen audio generation
 initialState: prepare
 terminalStates:
   - done
@@ -26,7 +27,7 @@ vars:
   plugins_path: ""
   validate_script: ""
   agent: ""
-  __runId: "solo"
+  wrap_script: ""
   __hitlAnswer: ""
   __hitlInput: ""
 
@@ -36,32 +37,33 @@ states:
     onEnter:
       - kind: shell
         options:
-          command: >-
-            set -e;
-            if [ -z "${vars.work_dir}" ]; then
-              echo "missing work_dir" >&2; exit 1;
-            fi;
-            mkdir -p "${vars.work_dir}" "${vars.work_dir}/1-briefing" "${vars.work_dir}/2-outline" "${vars.work_dir}/3-script" "${vars.work_dir}/4-audio";
-            if [ -n "${vars.topic}" ] && [ -n "${vars.input_file}" ]; then
-              echo "XOR violation: both topic and input_file set" >&2; exit 1;
-            fi;
-            if [ -z "${vars.topic}" ] && [ -z "${vars.input_file}" ]; then
-              echo "XOR violation: neither topic nor input_file set" >&2; exit 1;
-            fi;
-            if [ -z "${vars.voice_profile}" ] && [ -z "$VOICEBOX_DEFAULT_PROFILE" ]; then
-              echo "missing voice_profile (set vars.voice_profile or VOICEBOX_DEFAULT_PROFILE)" >&2; exit 1;
-            fi;
-            if [ -f "${vars.work_dir}/brief.md" ] && [ "${vars.force}" != "true" ]; then
-              echo "initialization target already exists at ${vars.work_dir}/brief.md; pass force=true to replace" >&2; exit 1;
-            fi;
-            if [ -n "${vars.topic}" ]; then
-              printf '%s\n' "${vars.topic}" > "${vars.work_dir}/brief.md";
-            else
-              if [ ! -f "${vars.input_file}" ]; then
-                echo "input file not found: ${vars.input_file}" >&2; exit 1;
-              fi;
-              cp "${vars.input_file}" "${vars.work_dir}/brief.md";
+        command: >-
+          set -e;
+          if [ -z "${vars.work_dir}" ]; then
+            echo "missing work_dir" >&2; exit 1;
+          fi;
+          mkdir -p "${vars.work_dir}" "${vars.work_dir}/1-briefing" "${vars.work_dir}/2-outline" "${vars.work_dir}/3-script" "${vars.work_dir}/4-audio";
+          if [ -n "${vars.topic}" ] && [ -n "${vars.input_file}" ]; then
+            echo "XOR violation: both topic and input_file set" >&2; exit 1;
+          fi;
+          if [ -z "${vars.topic}" ] && [ -z "${vars.input_file}" ]; then
+            echo "XOR violation: neither topic nor input_file set" >&2; exit 1;
+          fi;
+          if [ -z "${vars.voice_profile}" ] && [ -z "$VOICEBOX_DEFAULT_PROFILE" ]; then
+            echo "missing voice_profile (set vars.voice_profile or VOICEBOX_DEFAULT_PROFILE)" >&2; exit 1;
+          fi;
+          if [ -f "${vars.work_dir}/brief.md" ] && [ "${vars.force}" != "true" ]; then
+            echo "initialization target already exists at ${vars.work_dir}/brief.md; pass force=true to replace" >&2; exit 1;
+          fi;
+          if [ -n "${vars.topic}" ]; then
+            printf '%s\n' "${vars.topic}" > "${vars.work_dir}/brief.md";
+          else
+            if [ ! -f "${vars.input_file}" ]; then
+              echo "input file not found: ${vars.input_file}" >&2; exit 1;
             fi;
+            cp "${vars.input_file}" "${vars.work_dir}/brief.md";
+          fi;
+          echo 0 > "${vars.work_dir}/.revise-count";
 
   - id: understand
     description: "Analyze brief and generate podcast briefing (agent.run)"
@@ -71,9 +73,11 @@ states:
           role: scribe
           agent: ${vars.agent}
           input: |
+            Invoke the kk:audio-authoring skill: operation `briefing`, mode `solo`.
             Read the source brief at ${vars.work_dir}/brief.md.
             Write a concise podcast briefing at ${vars.work_dir}/1-briefing/briefing.md.
             Identify core thesis, key listener takeaways, audience profile, target spoken duration (${vars.target_duration_min} minutes), tone, and what material from the brief to emphasize or cut.
+            Flags: --dir ${vars.work_dir} --duration ${vars.target_duration_min}
           expectFile: ${vars.work_dir}/1-briefing/briefing.md
 
   - id: outline-write
@@ -84,6 +88,7 @@ states:
           role: scribe
           agent: ${vars.agent}
           input: |
+            Invoke the kk:audio-authoring skill: operation `outline`, mode `solo`.
             Read the briefing at ${vars.work_dir}/1-briefing/briefing.md and brief at ${vars.work_dir}/brief.md.
             Generate spoken podcast outline options in ${vars.work_dir}/2-outline/:
             - outline-option-a.md (e.g. narrative / storytelling arc)
@@ -91,11 +96,12 @@ states:
             - optional outline-option-c.md
             Target total episode spoken duration is ${vars.target_duration_min} minutes.
             Do not wait for operator selection; write the option files.
+            Flags: --dir ${vars.work_dir} --duration ${vars.target_duration_min}
           expectFile: ${vars.work_dir}/2-outline/outline-option-a.md
       - kind: shell
         options:
-          command: >-
-            test -f "${vars.work_dir}/2-outline/outline-option-b.md" || { echo "missing required outline-option-b.md" >&2; exit 1; }
+        command: >-
+          test -f "${vars.work_dir}/2-outline/outline-option-b.md" || { echo "missing required outline-option-b.md" >&2; exit 1; }
 
   - id: outline-select
     description: "Operator selects preferred outline option"
@@ -115,15 +121,15 @@ states:
     onEnter:
       - kind: shell
         options:
-          command: >-
-            sel="${vars.outline}";
-            if [ -z "$sel" ]; then sel="${vars.__hitlAnswer}"; fi;
-            if [ -z "$sel" ]; then sel="a"; fi;
-            src="${vars.work_dir}/2-outline/outline-option-$sel.md";
-            if [ ! -f "$src" ]; then
-              echo "selected outline file not found: $src" >&2; exit 1;
-            fi;
-            cp "$src" "${vars.work_dir}/2-outline/outline-approved.md";
+        command: >-
+          sel="${vars.outline}";
+          if [ -z "$sel" ]; then sel="${vars.__hitlAnswer}"; fi;
+          if [ -z "$sel" ]; then sel="a"; fi;
+          src="${vars.work_dir}/2-outline/outline-option-$sel.md";
+          if [ ! -f "$src" ]; then
+            echo "selected outline file not found: $src" >&2; exit 1;
+          fi;
+          cp "$src" "${vars.work_dir}/2-outline/outline-approved.md";
 
   - id: script-write
     description: "Author complete VoiceScript YAML from approved outline (agent.run)"
@@ -133,6 +139,7 @@ states:
           role: scribe
           agent: ${vars.agent}
           input: |
+            Invoke the kk:audio-authoring skill: operation `script`, mode `solo`.
             Read the approved outline at ${vars.work_dir}/2-outline/outline-approved.md and briefing at ${vars.work_dir}/1-briefing/briefing.md.
             Target duration is ${vars.target_duration_min} minutes.
             Spoken budget: if language (${vars.language}) is zh, ja, or ko, target characters = ${vars.target_duration_min} * ${vars.cjk_chars_per_min}; otherwise target words = ${vars.target_duration_min} * ${vars.words_per_min}. Land inside ±20%, spoken prose, one speaker.
@@ -147,6 +154,8 @@ states:
                 gap_ms: 400               # optional, >= 0, silence before next clip
                 instruct: "warm"          # optional, <= 500 characters
             Do not invent fields. Revision feedback: ${vars.__hitlInput}
+            Duration retries: if ${vars.work_dir}/.duration-feedback exists, invoke with `--force` (authorized rewrite) and treat its contents as the revision feedback.
+            Flags: --dir ${vars.work_dir} --duration ${vars.target_duration_min} --language ${vars.language} --profile ${vars.voice_profile} --revise "${vars.__hitlInput}"
           expectFile: ${vars.work_dir}/3-script/voicescript.yaml
 
   - id: script-validate
@@ -154,18 +163,26 @@ states:
     onEnter:
       - kind: shell
         options:
-          command: >-
-            set -e;
-            vs="${vars.validate_script}";
-            if [ -z "$vs" ]; then
-              if [ -n "$KK_WORKFLOWS_DIR" ]; then vs="$KK_WORKFLOWS_DIR/validate-voicescript.ts";
-              else vs="$HOME/.config/kk/workflows/validate-voicescript.ts"; fi;
-            fi;
-            if [ ! -f "$vs" ]; then
-              echo "validate_script not found: $vs (install with /workflow-run kk-solo-podcast into $HOME/.config/kk/workflows)" >&2;
-              exit 1;
-            fi;
-            bun "$vs" --in "${vars.work_dir}/3-script/voicescript.yaml"
+        command: >-
+          set -e;
+          vs="${vars.validate_script}";
+          if [ ! -f "$vs" ]; then
+            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)";
+            vs="";
+            if [ -n "$KK_WORKFLOWS_DIR" ] && [ -f "$KK_WORKFLOWS_DIR/validate-voicescript.ts" ]; then vs="$KK_WORKFLOWS_DIR/validate-voicescript.ts";
+            elif [ -n "$pkg" ] && [ -f "$pkg/plugins/kk/workflows/validate-voicescript.ts" ]; then vs="$pkg/plugins/kk/workflows/validate-voicescript.ts";
+            elif [ -f "$HOME/.config/kk/workflows/validate-voicescript.ts" ]; then vs="$HOME/.config/kk/workflows/validate-voicescript.ts"; fi;
+          fi;
+          if [ -z "$vs" ]; then
+            echo "validate_script not found (searched: \$KK_WORKFLOWS_DIR, kk package root via \`command -v kk\`, \$HOME/.config/kk/workflows) — install the kk package or place an override with /workflow-run kk-solo-podcast --force" >&2;
+            exit 1;
+          fi;
+          bun "$vs" --in "${vars.work_dir}/3-script/voicescript.yaml"
 
   - id: script-review
     description: "Operator reviews and approves VoiceScript before live TTS generation"
@@ -182,13 +199,10 @@ states:
     onEnter:
       - kind: shell
         options:
-          command: >-
-            mkdir -p .spur/run;
-            run_id="${vars.__runId}";
-            if [ -z "$run_id" ]; then run_id="solo"; fi;
-            count_file=".spur/run/$run_id-solo-revise-count";
-            curr=$(cat "$count_file" 2>/dev/null || echo 0);
-            echo $((curr + 1)) > "$count_file";
+        command: >-
+          rm -f "${vars.work_dir}/.duration-feedback";
+          n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
+          echo $((n + 1)) > "${vars.work_dir}/.revise-count";
       - kind: hitl.input
         options:
           prompt: "Provide specific revision feedback for ${vars.work_dir}/3-script/voicescript.yaml:"
@@ -199,41 +213,65 @@ states:
     onEnter:
       - kind: shell
         options:
-          command: >-
-            bun -e '
-            import { readFileSync, writeFileSync } from "node:fs";
-            import { createHash } from "node:crypto";
-            import { resolve } from "node:path";
-            const scriptPath = resolve(process.argv[1]);
-            const outPath = resolve(process.argv[2]);
-            const voiceProfile = process.argv[3] || process.env.VOICEBOX_DEFAULT_PROFILE || "";
-            const body = readFileSync(scriptPath, "utf-8");
-            const sourceUri = "file://" + scriptPath;
-            const id = createHash("sha256").update(sourceUri).digest("hex").slice(0, 16);
-            const doc = {
-              id,
-              title: "Podcast VoiceScript",
-              sourceUri,
-              body,
-              mediaType: "application/yaml",
-              metadata: voiceProfile ? { voiceProfile } : {},
-            };
-            writeFileSync(outPath, JSON.stringify([doc], null, 2));
-            ' "${vars.work_dir}/3-script/voicescript.yaml" "${vars.work_dir}/4-audio/docs.json" "${vars.voice_profile}"
+        command: >-
+          set -e;
+          ws="${vars.wrap_script}";
+          if [ ! -f "$ws" ]; then
+            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)";
+            ws="";
+            if [ -n "$KK_WORKFLOWS_DIR" ] && [ -f "$KK_WORKFLOWS_DIR/wrap-voicescript-doc.ts" ]; then ws="$KK_WORKFLOWS_DIR/wrap-voicescript-doc.ts";
+            elif [ -n "$pkg" ] && [ -f "$pkg/plugins/kk/workflows/wrap-voicescript-doc.ts" ]; then ws="$pkg/plugins/kk/workflows/wrap-voicescript-doc.ts";
+            elif [ -f "$HOME/.config/kk/workflows/wrap-voicescript-doc.ts" ]; then ws="$HOME/.config/kk/workflows/wrap-voicescript-doc.ts"; fi;
+          fi;
+          if [ -z "$ws" ]; then
+            echo "wrap_script not found (searched: \$KK_WORKFLOWS_DIR, kk package root via \`command -v kk\`, \$HOME/.config/kk/workflows) — install the kk package or place an override with /workflow-run kk-solo-podcast --force" >&2;
+            exit 1;
+          fi;
+          bun "$ws" "${vars.work_dir}/3-script/voicescript.yaml" "${vars.work_dir}/4-audio/docs.json" "${vars.voice_profile}"
 
   - id: generate
     description: "Invoke voice-gen generator plugin to generate audio"
     onEnter:
       - kind: shell
         options:
-          command: >-
-            set -e;
-            extra="";
-            if [ -n "${vars.plugins_path}" ]; then extra="--plugins-path ${vars.plugins_path}"; fi;
-            kk executor run voice-gen --in "${vars.work_dir}/4-audio/docs.json" --out "${vars.work_dir}/4-audio/content.json" $extra
+        command: >-
+          set -e;
+          extra="";
+          if [ -n "${vars.plugins_path}" ]; then extra="--plugins-path ${vars.plugins_path}"; fi;
+          kk executor run voice-gen --in "${vars.work_dir}/4-audio/docs.json" --out "${vars.work_dir}/4-audio/content.json" $extra
 
   - id: duration-check
-    description: "Validate generated audio duration against target budget"
+    description: "Validate generated audio duration against target budget; miss writes .duration-feedback for the retry edge"
+    onEnter:
+      - kind: shell
+        options:
+        command: >-
+          rm -f "${vars.work_dir}/4-audio/.duration-ok";
+          if [ ! -f "${vars.work_dir}/4-audio/content.json" ]; then
+            exit 0;
+          fi;
+          dur=$(jq -r '.metadata.duration // empty' "${vars.work_dir}/4-audio/content.json" 2>/dev/null);
+          if [ -z "$dur" ]; then
+            printf 'Regenerate: audio metadata.duration missing or not a number.\n' > "${vars.work_dir}/.duration-feedback";
+            n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
+            echo $((n+1)) > "${vars.work_dir}/.revise-count";
+            exit 0;
+          fi;
+          target_s=$((${vars.target_duration_min} * 60));
+          min_s=$(awk -v t="$target_s" 'BEGIN {print t * 0.5}');
+          max_s=$(awk -v t="$target_s" 'BEGIN {print t * 2.0}');
+          if awk -v d="$dur" -v min="$min_s" -v max="$max_s" 'BEGIN { exit !(d >= min && d <= max) }'; then
+            touch "${vars.work_dir}/4-audio/.duration-ok";
+          else
+            printf 'Regenerate: last audio duration %ss outside 0.5x–2x of %ss; adjust segment lengths toward the target.\n' "$dur" "$target_s" > "${vars.work_dir}/.duration-feedback";
+            n=$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0);
+            echo $((n+1)) > "${vars.work_dir}/.revise-count";
+          fi
 
   - id: done
     description: "Terminal — Solo podcast VoiceScript and audio generated successfully"
@@ -314,7 +352,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "${vars.__hitlAnswer}" = "no" && { run_id="${vars.__runId}"; if [ -z "$run_id" ]; then run_id="solo"; fi; test "$(cat .spur/run/$run_id-solo-revise-count 2>/dev/null || echo 0)" -lt 3; }'
+        command: 'test "${vars.__hitlAnswer}" = "no" && test "$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)" -lt 3'
 
   - from: script-review
     to: failed
@@ -322,7 +360,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "${vars.__hitlAnswer}" = "no" && { run_id="${vars.__runId}"; if [ -z "$run_id" ]; then run_id="solo"; fi; test "$(cat .spur/run/$run_id-solo-revise-count 2>/dev/null || echo 0)" -ge 3; }'
+        command: 'test "${vars.__hitlAnswer}" = "no" && test "$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)" -ge 3'
 
   - from: script-revise
     to: script-write
@@ -348,27 +386,20 @@ transitions:
     guard:
       kind: shell
       options:
-        command: >-
-          test ! -f "${vars.work_dir}/4-audio/content.json" || {
-            dur=$(jq -r '.metadata.duration // empty' "${vars.work_dir}/4-audio/content.json" 2>/dev/null);
-            test -n "$dur" && target_s=$((${vars.target_duration_min} * 60)) && min_s=$(awk -v t="$target_s" 'BEGIN {print t * 0.5}') && max_s=$(awk -v t="$target_s" 'BEGIN {print t * 2.0}') && awk -v d="$dur" -v min="$min_s" -v max="$max_s" 'BEGIN { if (d >= min && d <= max) exit 0; else exit 1 }';
-          }
+        command: 'test ! -f "${vars.work_dir}/4-audio/content.json" || test -f "${vars.work_dir}/4-audio/.duration-ok"'
+
+  - from: duration-check
+    to: script-write
+    description: "Audio duration outside band with revision budget remaining -> regenerate script from feedback"
+    guard:
+      kind: shell
+      options:
+        command: 'test -f "${vars.work_dir}/4-audio/content.json" && test ! -f "${vars.work_dir}/4-audio/.duration-ok" && test "$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)" -lt 3'
 
   - from: duration-check
     to: failed
-    description: "Audio duration missing or outside [0.5x, 2.0x] target range -> fail"
+    description: "Audio duration outside band with revision budget exhausted -> fail"
     guard:
       kind: shell
       options:
-        command: >-
-          test -f "${vars.work_dir}/4-audio/content.json" && {
-            dur=$(jq -r '.metadata.duration // empty' "${vars.work_dir}/4-audio/content.json" 2>/dev/null);
-            if [ -z "$dur" ]; then
-              echo "duration-check failed: metadata.duration missing or not a number" >&2;
-              exit 0;
-            fi;
-            target_s=$((${vars.target_duration_min} * 60));
-            min_s=$(awk -v t="$target_s" 'BEGIN {print t * 0.5}');
-            max_s=$(awk -v t="$target_s" 'BEGIN {print t * 2.0}');
-            awk -v d="$dur" -v min="$min_s" -v max="$max_s" -v ts="$target_s" 'BEGIN { if (d < min || d > max) { printf "duration-check failed: duration %ss outside 0.5x–2x of %ss\n", d, ts > "/dev/stderr"; exit 0 } else exit 1 }';
-          }
+        command: 'test -f "${vars.work_dir}/4-audio/content.json" && test ! -f "${vars.work_dir}/4-audio/.duration-ok" && test "$(cat "${vars.work_dir}/.revise-count" 2>/dev/null || echo 0)" -ge 3'

package/plugins/kk/workflows/kk-storm-research.yaml

@@ -37,10 +37,10 @@ vars:
   maxResults: "8" # written into topic.json as int (0054 maxResults)
   fixture: "false" # "true" selects the stub; CI/dry-run must pass "true"
   work_dir: "./work" # RESOLVED topic dir ($works_root/<topic-id>)
-  plugins_path: "./plugins" # --plugins-path for kk executor run
+  plugins_path: "" # empty -> ADR-012 default discovery (package-shipped built-ins); set for checkout dev
   ingestion_plugin: "web-search"
   generator_plugin: "content-gen"
-  render_script: "plugins/kk/scripts/render-md.ts" # 0058 shipped runner
+  render_script: "" # empty -> fallback chain: kk package root -> checkout plugins/kk/scripts/render-md.ts
 
 states:
   - id: prepare
@@ -103,9 +103,11 @@ states:
       - kind: shell
         options:
           command: >-
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             kk executor run "${vars.ingestion_plugin}" --in
             "${vars.work_dir}/topic.json" --out "${vars.work_dir}/docs.json"
-            --plugins-path "${vars.plugins_path}"
+            "$@"
 
   - id: generate
     description: >-
@@ -123,9 +125,11 @@ states:
       - kind: shell
         options:
           command: >-
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             kk executor run "${vars.generator_plugin}" --in
             "${vars.work_dir}/docs.json" --out "${vars.work_dir}/content.json"
-            --plugins-path "${vars.plugins_path}"
+            "$@"
 
   - id: render
     description: >-
@@ -135,7 +139,24 @@ states:
       - kind: shell
         options:
           command: >-
-            bun "${vars.render_script}" --in "${vars.work_dir}/content.json"
+            set -e;
+            rs="${vars.render_script}";
+            if [ ! -f "$rs" ]; then
+              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)";
+              rs="";
+              if [ -n "$pkg" ] && [ -f "$pkg/plugins/kk/scripts/render-md.ts" ]; then rs="$pkg/plugins/kk/scripts/render-md.ts";
+              elif [ -f "plugins/kk/scripts/render-md.ts" ]; then rs="plugins/kk/scripts/render-md.ts"; fi;
+            fi;
+            if [ -z "$rs" ]; then
+              echo "render_script not found (searched: var, kk package root via \`command -v kk\`, ./plugins/kk/scripts)" >&2;
+              exit 1;
+            fi;
+            bun "$rs" --in "${vars.work_dir}/content.json"
             --out "${vars.work_dir}/content.md"
 
   - id: done

package/plugins/kk/workflows/wrap-voicescript-doc.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+/**
+ * Runtime VoiceScript→Doc[] wrapper for kk-solo-podcast.
+ *
+ * Copied with the workflow YAML into $KK_WORKFLOWS_DIR (default
+ * ~/.config/kk/workflows). Node/Bun builtins only — no @gobing-ai/* and no
+ * relative imports (those paths do not exist next to the runtime copy).
+ *
+ * SYNC: plugins/kk/workflows/kk-solo-podcast.yaml (wrap-docs state shells this
+ * script with scriptPath, outPath, voiceProfile argv). The wrap shape must stay
+ * a single-Doc array with sha256(file://scriptPath)[0:16] id — voice-gen and
+ * tests depend on it.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const [scriptPathArg, outPathArg, voiceProfileArg] = process.argv.slice(2);
+
+if (!scriptPathArg || !outPathArg) {
+    console.error('usage: wrap-voicescript-doc.ts <scriptPath> <outPath> [voiceProfile]');
+    process.exit(1);
+}
+
+const scriptPath = resolve(scriptPathArg);
+const outPath = resolve(outPathArg);
+const voiceProfile = voiceProfileArg || process.env.VOICEBOX_DEFAULT_PROFILE || '';
+const body = readFileSync(scriptPath, 'utf-8');
+const sourceUri = `file://${scriptPath}`;
+const id = createHash('sha256').update(sourceUri).digest('hex').slice(0, 16);
+const doc = {
+    id,
+    title: 'Podcast VoiceScript',
+    sourceUri,
+    body,
+    mediaType: 'application/yaml',
+    metadata: voiceProfile ? { voiceProfile } : {},
+};
+
+writeFileSync(outPath, JSON.stringify([doc], null, 2));