@gobing-ai/knowledge-kit 0.0.14 → 0.0.16

package/plugins/kk/workflows/kk-itc.yaml

@@ -29,34 +29,17 @@ vars:
 
 states:
   - id: prepare
-    description: "mkdir work_dir, 2-outline, 3-draft; validate XOR topic/input_file; write brief.md"
+    description: "mkdir work_dir, 2-outline; validate XOR topic/input_file; write brief.md"
     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}/2-outline" "${vars.work_dir}/3-draft";
-            echo 0 > "${vars.work_dir}/.revise-count";
-            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 [ -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;
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" prepare-itc "${vars.work_dir}" "${vars.topic}" "${vars.input_file}" "${vars.force}"
 
   - id: research
     description: "Conduct preliminary topic research via storm-research (agent.run)"
@@ -123,9 +106,9 @@ states:
           agent: ${vars.agent}
           input: |
             Invoke the kk:${vars.writer} skill.
-            Author the technical draft at ${vars.work_dir}/3-draft/draft-article.md based on approved outline ${vars.work_dir}/2-outline/outline-approved.md and brief ${vars.work_dir}/brief.md using playbook ${vars.playbook}.
+            Author the technical draft at ${vars.work_dir}/3-draft-draft-article.md based on approved outline ${vars.work_dir}/2-outline/outline-approved.md and brief ${vars.work_dir}/brief.md using playbook ${vars.playbook}.
             Revision feedback: ${vars.__hitlInput}
-          expectFile: ${vars.work_dir}/3-draft/draft-article.md
+          expectFile: ${vars.work_dir}/3-draft-draft-article.md
 
   - id: draft-review
     description: "Operator reviews and approves or requests revision on draft-article.md"
@@ -133,7 +116,7 @@ states:
     onEnter:
       - kind: hitl.confirm
         options:
-          prompt: "Review draft at ${vars.work_dir}/3-draft/draft-article.md. Approve?"
+          prompt: "Review draft at ${vars.work_dir}/3-draft-draft-article.md. Approve?"
           var: __hitlAnswer
 
   - id: draft-revise
@@ -147,7 +130,7 @@ states:
             echo $((n + 1)) > "${vars.work_dir}/.revise-count";
       - kind: hitl.input
         options:
-          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-draft/draft-article.md:"
+          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-draft-draft-article.md:"
           var: __hitlInput
 
   - id: judge
@@ -159,7 +142,7 @@ states:
           agent: ${vars.agent}
           input: |
             Invoke the kk:content-judge skill.
-            Evaluate the draft at ${vars.work_dir}/3-draft/draft-article.md against the ${vars.rubric} rubric.
+            Evaluate the draft at ${vars.work_dir}/3-draft-draft-article.md against the ${vars.rubric} rubric.
             Write the verdict JSON to ${vars.work_dir}/.itc-verdict.json per the skill's verdict contract.
             Print the verdict path as the last line of stdout.
           expectFile: ${vars.work_dir}/.itc-verdict.json

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

@@ -37,33 +37,16 @@ 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";
-          fi;
-          echo 0 > "${vars.work_dir}/.revise-count";
+          # ADR-115: the XOR / voice_profile / overwrite / brief logic lives in the
+          # solo-podcast stage runner; this action only resolves the package root and
+          # delegates (one logical call).
+          command: >-
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" prepare-solo "${vars.work_dir}" "${vars.topic}" "${vars.input_file}" "${vars.voice_profile}" "${vars.force}"
 
   - id: understand
     description: "Analyze brief and generate podcast briefing (agent.run)"
@@ -75,10 +58,10 @@ states:
           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.
+            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
+          expectFile: ${vars.work_dir}/1-briefing-briefing.md
 
   - id: outline-write
     description: "Generate spoken podcast outline options (agent.run)"
@@ -89,7 +72,7 @@ states:
           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.
+            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)
             - outline-option-b.md (e.g. analytical / explainer breakdown)
@@ -100,8 +83,8 @@ states:
           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"
@@ -121,15 +104,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)"
@@ -138,51 +121,32 @@ states:
         options:
           role: scribe
           agent: ${vars.agent}
+          # ADR-115 (R3): the VoiceScript field contract is the skill's own
+          # templates/voicescript.solo.yaml (task 0081) — not duplicated here. The prompt
+          # stays a bounded skill invocation: operation + inputs + output path + budget.
           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.
-            Author the complete solo-podcast VoiceScript YAML at ${vars.work_dir}/3-script/voicescript.yaml.
-            Emit ONLY valid YAML (no markdown fences, no repo/docs paths). Contract:
-            title: string
-            language: "${vars.language}"
-            default_profile: "${vars.voice_profile}"
-            default_engine: qwen|qwen_custom_voice|luxtts|chatterbox|chatterbox_turbo|tada|kokoro  # optional
-            segments:
-              - text: "spoken sentence"   # required, 1..50000 characters
-                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
+            Inputs: briefing ${vars.work_dir}/1-briefing-briefing.md; approved outline ${vars.work_dir}/2-outline/outline-approved.md; revision feedback ${vars.__hitlInput}.
+            Contract: the skill's templates/voicescript.solo.yaml — `language: "${vars.language}"`, `segments` of spoken text; no `default_profile`, no `title`, no invented fields.
+            Budget: ${vars.target_duration_min} min — zh/ja/ko ${vars.cjk_chars_per_min} chars/min, else ${vars.words_per_min} words/min; within ±20%, one speaker.
+            Write ONLY the YAML (no fences, no repo paths) to ${vars.work_dir}/3-script-voicescript.yaml.
+            Flags: --dir ${vars.work_dir} --duration ${vars.target_duration_min} --language ${vars.language} --profile ${vars.voice_profile} --revise "${vars.__hitlInput}"; add --force when ${vars.work_dir}/.duration-feedback exists (its contents are the revision feedback).
+          expectFile: ${vars.work_dir}/3-script-voicescript.yaml
 
   - id: script-validate
     description: "Validate authored VoiceScript YAML structure and constraints"
     onEnter:
       - kind: shell
         options:
-        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"
+          # ADR-115: package-root resolution + delegation to validate-voicescript.ts
+          # (override chain preserved inside the stage runner).
+          command: >-
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" validate "${vars.validate_script}" --in "${vars.work_dir}/3-script-voicescript.yaml"
 
   - id: script-review
     description: "Operator reviews and approves VoiceScript before live TTS generation"
@@ -190,7 +154,7 @@ states:
     onEnter:
       - kind: hitl.confirm
         options:
-          prompt: "Review VoiceScript at ${vars.work_dir}/3-script/voicescript.yaml. Approve for voice generation?"
+          prompt: "Review VoiceScript at ${vars.work_dir}/3-script-voicescript.yaml. Approve for voice generation?"
           var: __hitlAnswer
 
   - id: script-revise
@@ -199,13 +163,13 @@ states:
     onEnter:
       - kind: shell
         options:
-        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";
+          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:"
+          prompt: "Provide specific revision feedback for ${vars.work_dir}/3-script-voicescript.yaml:"
           var: __hitlInput
 
   - id: wrap-docs
@@ -213,65 +177,42 @@ states:
     onEnter:
       - kind: shell
         options:
-        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}"
+          # ADR-115: package-root resolution + delegation to wrap-voicescript-doc.ts
+          # (override chain preserved inside the stage runner).
+          command: >-
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" wrap "${vars.wrap_script}" --in "${vars.work_dir}/3-script-voicescript.yaml" --out "${vars.work_dir}/4-audio/docs.json" --profile "${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; 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
+          # ADR-115: the band math, .duration-feedback, and .revise-count bump live in
+          # the solo-podcast stage runner; the transition guards below still branch on
+          # .duration-ok.
+          command: >-
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" duration "${vars.work_dir}" "${vars.target_duration_min}"
 
   - id: done
     description: "Terminal — Solo podcast VoiceScript and audio generated successfully"

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

@@ -52,49 +52,12 @@ states:
       - kind: shell
         options:
           command: >-
-            set -e;
-            mkdir -p "${vars.work_dir}";
-            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 [ -n "${vars.topic}" ]; then
-            jq -n --arg topic "${vars.topic}" --arg maxResults
-            "${vars.maxResults}" --arg fixture "${vars.fixture}"
-            '{topic: $topic, maxResults: ($maxResults | tonumber),
-            fixture: ($fixture == "true")}' > "${vars.work_dir}/topic.json";
-            exit 0;
-            fi;
-            if [ -f "${vars.input_file}" ]; then
-            cp "${vars.input_file}" "${vars.work_dir}/input.md";
-            ABS=$(cd "$(dirname "${vars.input_file}")" && pwd)/$(basename
-            "${vars.input_file}");
-            QUERY=$(grep -m1 '^# ' "${vars.input_file}" | sed 's/^# *//'
-            || true);
-            if [ -z "$QUERY" ]; then
-            QUERY=$(basename "${vars.input_file}" | sed 's/\.[^.]*$//');
-            fi;
-            if [ -z "$QUERY" ]; then
-            echo "no query derivable (no H1 and empty basename)" >&2;
-            exit 1;
-            fi;
-            ID=$(printf 'file://%s' "$ABS" | shasum -a 256 | cut -c1-16);
-            jq -n --arg id "$ID" --arg body "$(cat "${vars.input_file}")"
-            --arg title "$QUERY" --arg sourceUri "file://$ABS" --arg query
-            "$QUERY" '{id: $id, body: $body, title: $title, sourceUri:
-            $sourceUri, mediaType: "text/markdown",
-            metadata: {query: $query, rank: -1, position: 0}}'
-            > "${vars.work_dir}/local-doc.json";
-            jq -n --arg topic "$QUERY" --arg maxResults
-            "${vars.maxResults}" --arg fixture "${vars.fixture}"
-            '{topic: $topic, maxResults: ($maxResults | tonumber),
-            fixture: ($fixture == "true")}' > "${vars.work_dir}/topic.json";
-            else
-            echo "input_file not readable: ${vars.input_file}" >&2; exit 1;
-            fi
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" prepare-storm "${vars.work_dir}" "${vars.topic}" "${vars.input_file}" "${vars.maxResults}" "${vars.fixture}"
 
   - id: ingest
     description: >-
@@ -139,25 +102,12 @@ states:
       - kind: shell
         options:
           command: >-
-            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"
+            kbin="$(command -v kk 2>/dev/null)";
+            pkg="$(dirname "$(dirname "$(realpath "$kbin" 2>/dev/null)")")";
+            st="$pkg/plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || st="plugins/kk/scripts/kk-workflow-stages.ts";
+            [ -f "$st" ] || echo "kk-workflow-stages.ts not found at $st — install or refresh the kk package (bun link in a checkout)" >&2;
+            bun "$st" render-storm "${vars.render_script}" --in "${vars.work_dir}/content.json" --out "${vars.work_dir}/content.md"
 
   - id: done
     description: >-