@gobing-ai/knowledge-kit 0.0.13 → 0.0.15

package/plugins/generations/voice-gen/dist/index.js

@@ -21848,6 +21848,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];
@@ -22268,7 +22288,7 @@ function createVoiceboxClient(options = {}) {
         }
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        throw new Error(`Voicebox health check failed at ${url2}: ${reason}`);
+        throw new Error(`Voicebox health check failed at ${url2}: ${reason} \u2014 is Voicebox.app running with its REST server enabled? (restart the app or fix VOICEBOX_URL)`);
       }
     },
     async resolveProfile(nameOrId) {
@@ -22810,11 +22830,18 @@ async function processGeneratorIO(inputPath, outputPath, clientOverride, transco
     const scripts = docs.map((doc2) => parseDocToVoiceScript(doc2, envDefaultProfile));
     const combinedScript = mergeVoiceScripts(scripts, docs, envDefaultProfile);
     validateVoiceScript(combinedScript);
+    const renderStartedAt = Date.now();
+    const maxRunMs = process.env.VOICE_GEN_MAX_RUN_MS ? parseInt(process.env.VOICE_GEN_MAX_RUN_MS, 10) : 0;
+    echoError(`voice-gen: ${combinedScript.segments.length} segments queued for local render`);
     const segmentWavs = [];
     const segmentGaps = [];
     const segmentMetadata = [];
     let totalDuration = 0;
-    for (const segment of combinedScript.segments) {
+    for (const [segIndex, segment] of combinedScript.segments.entries()) {
+      if (maxRunMs > 0 && Date.now() - renderStartedAt > maxRunMs) {
+        throw new Error(`voice-gen: render budget ${maxRunMs}ms exceeded after ${segIndex}/${combinedScript.segments.length} segments \u2014 Voicebox may be wedged; raise VOICE_GEN_MAX_RUN_MS if the render is legitimately long`);
+      }
+      const segStartedAt = Date.now();
       const speakerConfig = segment.speaker ? combinedScript.speakers?.[segment.speaker] : undefined;
       const profileTarget = segment.profile_id ?? segment.profile ?? speakerConfig?.profile_id ?? speakerConfig?.profile ?? combinedScript.default_profile_id ?? combinedScript.default_profile ?? envDefaultProfile ?? (typeof docs[0]?.metadata?.voiceProfile === "string" ? docs[0].metadata.voiceProfile : undefined);
       if (!profileTarget) {
@@ -22930,6 +22957,7 @@ async function processGeneratorIO(inputPath, outputPath, clientOverride, transco
         transcription,
         loudnessDip
       });
+      echoError(`voice-gen: segment ${segIndex + 1}/${combinedScript.segments.length} done in ${((Date.now() - segStartedAt) / 1000).toFixed(1)}s${verifyRetries ? ` (${verifyRetries} verify ${verifyRetries === 1 ? "retry" : "retries"})` : ""}`);
     }
     const concatenatedWav = concatWavs(segmentWavs, segmentGaps);
     await fs.ensureDir(outDir);

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

@@ -83,6 +83,12 @@ export async function processGeneratorIO(
         // 3. Validate VoiceScript
         validateVoiceScript(combinedScript);
 
+        // Local render can take hours; per-segment progress + an optional total budget keep
+        // long renders observable and bounded (dogfood 2026-09-12: healthy 72-min render read as a hang).
+        const renderStartedAt = Date.now();
+        const maxRunMs = process.env.VOICE_GEN_MAX_RUN_MS ? parseInt(process.env.VOICE_GEN_MAX_RUN_MS, 10) : 0;
+        echoError(`voice-gen: ${combinedScript.segments.length} segments queued for local render`);
+
         // 4. Generate each segment
         const segmentWavs: Uint8Array[] = [];
         const segmentGaps: number[] = [];
@@ -98,7 +104,13 @@ export async function processGeneratorIO(
         }> = [];
         let totalDuration = 0;
 
-        for (const segment of combinedScript.segments) {
+        for (const [segIndex, segment] of combinedScript.segments.entries()) {
+            if (maxRunMs > 0 && Date.now() - renderStartedAt > maxRunMs) {
+                throw new Error(
+                    `voice-gen: render budget ${maxRunMs}ms exceeded after ${segIndex}/${combinedScript.segments.length} segments — Voicebox may be wedged; raise VOICE_GEN_MAX_RUN_MS if the render is legitimately long`,
+                );
+            }
+            const segStartedAt = Date.now();
             const speakerConfig = segment.speaker ? combinedScript.speakers?.[segment.speaker] : undefined;
             const profileTarget =
                 segment.profile_id ??
@@ -284,6 +296,9 @@ export async function processGeneratorIO(
                 transcription,
                 loudnessDip,
             });
+            echoError(
+                `voice-gen: segment ${segIndex + 1}/${combinedScript.segments.length} done in ${((Date.now() - segStartedAt) / 1000).toFixed(1)}s${verifyRetries ? ` (${verifyRetries} verify ${verifyRetries === 1 ? 'retry' : 'retries'})` : ''}`,
+            );
         }
 
         // 5. Concatenate audio

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

@@ -73,7 +73,9 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
                 }
             } catch (err: unknown) {
                 const reason = err instanceof Error ? err.message : String(err);
-                throw new Error(`Voicebox health check failed at ${url}: ${reason}`);
+                throw new Error(
+                    `Voicebox health check failed at ${url}: ${reason} — is Voicebox.app running with its REST server enabled? (restart the app or fix VOICEBOX_URL)`,
+                );
             }
         },
 

package/plugins/ingestions/aihot-ingest/dist/index.js

@@ -21848,6 +21848,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

package/plugins/ingestions/horizon-ingest/dist/index.js

@@ -21849,6 +21849,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

package/plugins/ingestions/last30days-ingest/dist/index.js

@@ -21850,6 +21850,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

package/plugins/ingestions/web-search/dist/index.js

@@ -21849,6 +21849,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

package/plugins/kk/commands/image-extract.md

@@ -0,0 +1,40 @@
+---
+name: image-extract
+description: Extract a reusable style preset (and optionally draft a format preset) from 1-5 reference images, saved to ~/.config/kk/image-presets/ after confirmation.
+argument-hint: "--name <style-name> --ref <img> [--ref <img>…] [--emit-format <name> --job free|cover|illustration]  (max 5 refs)"
+allowed-tools: ["Skill"]
+---
+
+# image-extract
+
+Thin wrapper for the `image-authoring` skill's `extract-style` operation — all vision
+analysis, schema-fill, merge, and validation logic lives in the skill. Forward
+`$ARGUMENTS` with one substitution: this command's `--name <style-name>` is the skill's
+`--extract-style <name>` (the flag doubles as the operation selector there — rewrite it,
+do not pass `--name` through). `--ref`, `--emit-format`, and `--job` pass through unchanged.
+
+```text
+Skill(skill="kk:image-authoring", args="$ARGUMENTS with --name rewritten to --extract-style")
+```
+
+## What it does
+
+- Reads 1–5 reference images (`--ref`, repeatable; more than 5 is refused), analyses
+  the look, and shows you the composed `StylePreset` YAML for `--name <style-name>`.
+- **Confirms with you before writing**, then saves to the user root
+  `~/.config/kk/image-presets/styles/<name>.yaml` — usable immediately via
+  `/kk:image-generate --style <name>`, shadowing any shipped preset of the same name.
+- With `--emit-format <name> --job <job>`, additionally **drafts** a format preset from
+  the same images: measured dimensions + declared job + visual defaults authored from
+  the analysis, skeleton (variables, template grammar) reused from the shipped format
+  of the same job. Shown for confirmation and fine-tuning, then written to
+  `~/.config/kk/image-presets/formats/<name>.yaml` with `defaultStyle` set to the
+  style just extracted.
+- Validates each new preset with a dry-run generation (`KK_IMAGE_DRY_RUN=1`).
+
+Examples:
+
+```text
+/kk:image-extract --name flat-retro --ref a.png --ref b.png
+/kk:image-extract --name flat-retro --ref a.png --emit-format retro-cover --job cover
+```

package/plugins/kk/commands/image-generate.md

@@ -1,7 +1,7 @@
 ---
 name: image-generate
 description: Generate images from a prompt or an article — covers, illustrations, or free-form — using named format and style presets.
-argument-hint: "[prompt] [--format <name>] [--style <name>] [--content <file>] [--ref <path>] [--var K=V] [--dry-run] [--list-presets]"
+argument-hint: "[prompt] [--format free|cover|illustration] [--style vibrant|minimalist|photorealistic|technical-diagram|editorial|fresh|warm|cute|sketch|clean-webapp-ui|<custom>] [--content <file>] [--ref <img>…] [--var K=V] [--dry-run] [--list-presets]"
 allowed-tools: ["Skill"]
 ---
 
@@ -13,3 +13,20 @@ confirmation and delegation logic lives in the skill. Forward `$ARGUMENTS` uncha
 ```text
 Skill(skill="kk:image-authoring", args="$ARGUMENTS")
 ```
+
+## Built-in presets (user presets under `~/.config/kk/image-presets/` shadow these)
+
+**Formats** (`--format`; default `free`):
+
+| Format | Job | Aspect | Default style |
+| ------ | --- | ------ | ------------- |
+| `free` | free-form image from the positional prompt | 1:1 | vibrant |
+| `cover` | article cover; requires `--content <file>` | 21:9 | vibrant |
+| `illustration` | auto-insert illustrations into `--content <file>` | 4:3 | technical-diagram |
+
+**Styles** (`--style`): `vibrant` · `minimalist` · `photorealistic` · `technical-diagram` ·
+`editorial` · `fresh` · `warm` · `cute` · `sketch` · `clean-webapp-ui` — or any custom style
+preset name. Omit to use the preference `image.style` or the format's default.
+
+Run `--list-presets` for the live list with origins and shadows. Create new presets from
+reference images with `/kk:image-extract`.

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

@@ -2,8 +2,8 @@
 name: workflow-run
 description: >-
   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;
+  Resolves the workflow YAML from the user override, KK_WORKFLOWS_SOURCE, bun/npm
+  global installs, the 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]"
@@ -13,8 +13,9 @@ Thin runner around the **storm-research**, **itc-generating** / **topic**, and *
 capabilities. Read `plugins/kk/skills/storm-research/SKILL.md` or
 `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
+workflow YAML resolution (user override → `$KK_WORKFLOWS_SOURCE` → **bun/npm global
+install** → **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.
@@ -30,12 +31,13 @@ Parse per the frozen rule:
   `kk-storm-research` (default), `kk-itc`, `kk-solo-podcast`. Any other name after successful copy → exit 1 listing
   `kk-storm-research`, `kk-itc`, `kk-solo-podcast`.
 - `--in <file>` → file mode. `--force` → overwrite an existing dest YAML / existing `brief.md`.
-- Profile `kk-storm-research`: `--fixture` → force `fixture: "true"`.
-- Profile `kk-itc`: `--dir <path>` (default `./<kebab>`), `--playbook generic|english|wechat` (default `generic`),
+- Profile `kk-storm-research`: `--dir <path>` (default `$works_dir/kk-storm-research/<topic-id>`),
+  `--fixture` → force `fixture: "true"`.
+- Profile `kk-itc`: `--dir <path>` (default `$works_dir/kk-itc/<kebab>`), `--playbook generic|english|wechat` (default `generic`),
   `--research` (`true`|`false`, default `false`), `--judge` (`true`|`false`, default `false`),
   `--outline <a|b|c>` (default empty), `--writer itc-generating|topic` (default `itc-generating`).
   `--fixture` passed with `kk-itc` or `kk-solo-podcast` → exit 1 (`fixture is storm-only`).
-- Profile `kk-solo-podcast`: `--dir <path>` (default `$works_dir/<kebab>`), `--outline <a|b|c>`
+- Profile `kk-solo-podcast`: `--dir <path>` (default `$works_dir/kk-solo-podcast/<date>`), `--outline <a|b|c>`
   (default empty), `--duration <min>` (default `8`), `--language <code>` (default `en`),
   `--script-approved` (sets `script_approved=true`; default off). `--fixture` is storm-only.
 - **XOR:** exactly one of `<topic>` / `--in <file>`. Both set or both empty → exit 1, stderr
@@ -90,6 +92,19 @@ while [ -L "$kbin" ]; do
   case "$link" in /*) kbin="$link";; *) kbin="$(dirname "$kbin")/$link";; esac
 done
 pkg=""; [ -n "$kbin" ] && pkg="$(cd "$(dirname "$kbin")/.." 2>/dev/null && pwd || true)"
+# Global-install roots — the common no-config case (package installed with `bun install -g`
+# or `npm i -g` and no `workflows_dir` written yet). Each probe is guarded, so a missing
+# package manager never breaks the chain.
+bun_global_workflows=""
+if command -v bun >/dev/null 2>&1; then
+  bg="$(dirname "$(bun pm bin -g 2>/dev/null)")/install/global/node_modules/@gobing-ai/knowledge-kit/plugins/kk/workflows"
+  [ -d "$bg" ] && bun_global_workflows="$bg"
+fi
+npm_global_workflows=""
+if command -v npm >/dev/null 2>&1; then
+  ng="$(dirname "$(npm root -g 2>/dev/null)")/node_modules/@gobing-ai/knowledge-kit/plugins/kk/workflows"
+  [ -d "$ng" ] && npm_global_workflows="$ng"
+fi
 ```
 
 Resolution order — first hit wins:
@@ -97,26 +112,31 @@ Resolution order — first hit wins:
 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)
+3. **bun global install** — `$(dirname $(bun pm bin -g))/install/global/node_modules/@gobing-ai/knowledge-kit/plugins/kk/workflows/$NAME.yaml`
+4. **npm global install** — `$(dirname $(npm root -g))/node_modules/@gobing-ai/knowledge-kit/plugins/kk/workflows/$NAME.yaml`
+5. `$pkg/plugins/kk/workflows/$NAME.yaml` — the installed package copy (resolved from the `kk` binary)
+6. `plugins/kk/workflows/$NAME.yaml` — repo checkout (development)
+
+A corrupt `config.yaml` already exited 1 in step 2; none of these probes runs before that check,
+so no fallback masks a config error.
 
 ```bash
 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
+  for d in "$KK_WORKFLOWS_SOURCE" "$bun_global_workflows" "$npm_global_workflows" ${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; }
+  [ -z "$dest" ] && { echo "no source workflow for $NAME (searched $workflows_dir, KK_WORKFLOWS_SOURCE, bun/npm global installs, kk package root, plugins/kk/workflows)" >&2; exit 1; }
 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
+  for d in "$KK_WORKFLOWS_SOURCE" "$bun_global_workflows" "$npm_global_workflows" ${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; }
+  [ -z "$src" ] && { echo "no source workflow for $NAME to force-install (searched KK_WORKFLOWS_SOURCE, bun/npm global installs, 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
@@ -126,9 +146,11 @@ fi
   `--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`.
+- Sidecars (`plugins/kk/scripts/kk-workflow-stages.ts`, plus the
+  `validate-voicescript.ts` / `wrap-voicescript-doc.ts` it delegates to) are **not copied** —
+  the workflow resolves the stage runner from the package root, and the runner resolves each
+  sidecar via the explicit var, `$KK_WORKFLOWS_DIR`, the package copy, then
+  `$HOME/.config/kk/workflows`.
 
 ## 4. Compute workspace
 
@@ -143,7 +165,7 @@ slug=$(printf '%s' "$normalized" | tr -cs 'a-z0-9' '-' | sed 's/^-*//; s/-*$//'
 [ -z "$slug" ] && slug="topic"
 hash=$(printf '%s' "$normalized" | shasum -a 256 | cut -c1-8)
 topic_id="${slug}-${hash}"
-work_dir="$works_dir/$topic_id"
+work_dir="${DIR:-$works_dir/kk-storm-research/$topic_id}"
 ```
 
 - `raw` derives empty (no H1 and empty basename) → exit 1 with the derived value.
@@ -157,15 +179,24 @@ mkdir -p "$work_dir"
 
 `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:-./$kebab}"`. Empty derived `kebab` → exit 1.
+`work_dir="${DIR:-$works_dir/kk-itc/$kebab}"`. Empty derived `kebab` → exit 1. An explicit
+`--dir` still wins, and the default never writes into the caller's cwd.
 
-### Profile `kk-solo-podcast` / `kk-daily-ai-voice`
+### Profile `kk-solo-podcast`
 
 `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/kk-solo-podcast/$date}"`.
 
+### Profile `kk-daily-ai-voice`
+
+Same `date` / `raw` / `kebab` derivation as `kk-solo-podcast`.
+`work_dir="${DIR:-$works_dir/kk-daily-ai-voice/$date}"`.
+
+Every profile's default puts its workspace in **its own** `$works_dir/<workflow-name>/` namespace;
+an explicit `--dir` overrides all four defaults.
+
 ## 5. Run the workflow
 
 All values are strings.
@@ -216,9 +247,10 @@ spur workflow run "$dest" --vars \
   and `$work_dir/content.json` (machine contract). Skim `content.md` citations against `docs.json`
   ids before presenting.
 - **`kk-itc`**: print resolved `work_dir`, then `$work_dir/brief.md`, `$work_dir/2-outline/outline-approved.md`,
-  and `$work_dir/3-draft/draft-article.md`. If `judge=true`, also print the verdict path.
-- **`kk-solo-podcast`**: print resolved `work_dir`, then `$work_dir/3-script/voicescript.yaml`,
-  `$work_dir/4-audio/content.json`, and `$work_dir/4-audio/content.wav`.
+  and `$work_dir/3-draft-draft-article.md`. If `judge=true`, also print the verdict path.
+- **`kk-solo-podcast`**: print resolved `work_dir`, then `$work_dir/1-briefing-briefing.md`,
+  `$work_dir/3-script-voicescript.yaml`, `$work_dir/4-audio/content.json`, and
+  `$work_dir/4-audio/content.wav`.
 
 If the run ended `failed`, show the failing state (`spur workflow trace <run-id> --json`) and the
 fail-loud recovery line.

package/plugins/kk/config.example.yaml

@@ -1,3 +1,8 @@
+# kk operator config. `works_dir` is the run-workspace root — each workflow run defaults
+# to <works_dir>/<workflow-name>/<run-id> unless --dir is given (existing `.works/`-era
+# trees are not migrated). `workflows_dir` is the user-override root for workflow YAMLs;
+# when a workflow is not found there, /workflow-run falls back to KK_WORKFLOWS_SOURCE,
+# bun/npm global installs, the kk package root, then the repo checkout.
 works_dir: "~/.config/kk/works"
 workflows_dir: "~/.config/kk/workflows"
 defaults:

package/plugins/kk/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "kk",
-    "version": "0.1.0",
+    "version": "0.0.15",
     "description": "knowledge-kit Claude Code plugin: skills, commands, subagents, hooks, and rules"
 }