@gobing-ai/knowledge-kit 0.0.7 → 0.0.8

package/plugins/ingestions/karakeep-local/src/index.ts

@@ -1,8 +1,12 @@
 import { createHash } from 'node:crypto';
-import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
-import { dirname, join, relative } from 'node:path';
+import { dirname, relative } from 'node:path';
 import { parseArgs } from 'node:util';
 import type { Doc } from '@gobing-ai/kk-core';
+import { getLogger, initializeLogger } from '@gobing-ai/ts-infra';
+import { createNodeFileSystem, walkDir } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+
+const log = getLogger('kk.ingestion.karakeep-local');
 
 interface ParsedMeta {
     title?: string;
@@ -17,27 +21,26 @@ function computeHash(str: string): string {
 }
 
 async function collectFiles(dir: string): Promise<string[]> {
-    const entries = await readdir(dir, { recursive: true });
-    const files: string[] = [];
-    for (const entry of entries) {
-        const fullPath = join(dir, entry);
-        const st = await stat(fullPath);
-        if (st.isFile()) {
-            files.push(fullPath);
-        }
-    }
-    return files.sort();
+    // walkDir is cycle-safe and root-confined: a directory symlink pointing back at
+    // an ancestor is walked at most once, and one escaping `dir` is skipped.
+    return (await walkDir(dir, createNodeFileSystem())).sort();
 }
 
 export async function processKarakeepFolder(inDir: string): Promise<Doc[]> {
+    const fs = createNodeFileSystem();
     try {
-        const inStat = await stat(inDir);
+        // The FileSystem seam returns null for a missing path where node's stat throws;
+        // both cases must still surface as "Inaccessible source path" below.
+        const inStat = await fs.stat(inDir);
+        if (inStat === null) {
+            throw new Error(`Source path does not exist: ${inDir}`);
+        }
         if (!inStat.isDirectory()) {
             throw new Error(`Source path is not a directory: ${inDir}`);
         }
     } catch (err: unknown) {
         const msg = `Inaccessible source path: ${inDir}`;
-        console.error(`Error: ${msg}`, err);
+        echoError(`Error: ${msg}`);
         throw new Error(msg, { cause: err });
     }
 
@@ -62,14 +65,14 @@ export async function processKarakeepFolder(inDir: string): Promise<Doc[]> {
 
         if (contentMd) {
             processedFiles.add(contentMd);
-            const mdText = await readFile(contentMd, 'utf-8');
+            const mdText = await fs.readFile(contentMd);
             let metaObj: ParsedMeta = {};
             if (metaJson) {
                 processedFiles.add(metaJson);
                 try {
-                    metaObj = JSON.parse(await readFile(metaJson, 'utf-8')) as ParsedMeta;
+                    metaObj = JSON.parse(await fs.readFile(metaJson)) as ParsedMeta;
                 } catch (err: unknown) {
-                    console.error(`Warning: corrupt/unparsable meta file at ${metaJson}`, err);
+                    log.warn(`Warning: corrupt/unparsable meta file at ${metaJson}`, { error: err });
                 }
             }
 
@@ -99,7 +102,7 @@ export async function processKarakeepFolder(inDir: string): Promise<Doc[]> {
 
         if (f.endsWith('.json')) {
             try {
-                const jsonText = await readFile(f, 'utf-8');
+                const jsonText = await fs.readFile(f);
                 const jsonObj = JSON.parse(jsonText) as ParsedMeta;
                 const { title, sourceUri, mediaType, body, ...extraMeta } = jsonObj;
                 if (typeof body === 'string') {
@@ -112,13 +115,13 @@ export async function processKarakeepFolder(inDir: string): Promise<Doc[]> {
                         metadata: Object.keys(extraMeta).length > 0 ? extraMeta : undefined,
                     });
                 } else {
-                    console.error(`Warning: JSON entry missing string body at ${f}`);
+                    log.warn(`Warning: JSON entry missing string body at ${f}`);
                 }
             } catch (err: unknown) {
-                console.error(`Warning: corrupt/unparsable JSON file at ${f}`, err);
+                log.warn(`Warning: corrupt/unparsable JSON file at ${f}`, { error: err });
             }
         } else if (f.endsWith('.md')) {
-            const mdText = await readFile(f, 'utf-8');
+            const mdText = await fs.readFile(f);
             docs.push({
                 id,
                 body: mdText,
@@ -140,31 +143,33 @@ export async function main() {
     });
 
     if (!values.in || !values.out) {
-        console.error('Error: Missing required arguments --in or --out');
+        echoError('Error: Missing required arguments --in or --out');
         process.exit(1);
     }
 
+    const fs = createNodeFileSystem();
     try {
         const candidateFiles = await collectFiles(values.in);
         const docs = await processKarakeepFolder(values.in);
 
         if (docs.length === 0 && candidateFiles.length > 0) {
-            console.error(`Fatal: source yielded zero ingestible documents at ${values.in}`);
+            echoError(`Fatal: source yielded zero ingestible documents at ${values.in}`);
             process.exit(1);
         }
 
         const outDir = dirname(values.out);
         if (outDir && outDir !== '.') {
-            await mkdir(outDir, { recursive: true });
+            await fs.ensureDir(outDir);
         }
 
-        await writeFile(values.out, JSON.stringify(docs, null, 2), 'utf-8');
+        await fs.writeFile(values.out, JSON.stringify(docs, null, 2));
     } catch (err: unknown) {
-        console.error('Fatal error during karakeep-local ingestion:', err);
+        echoError(`Fatal error during karakeep-local ingestion: ${err instanceof Error ? err.message : String(err)}`);
         process.exit(1);
     }
 }
 
 if (import.meta.main) {
+    await initializeLogger({ console: process.env.NODE_ENV !== 'test', json: true, level: 'warn' });
     main();
 }

package/plugins/ingestions/karakeep-local/tsconfig.json

@@ -0,0 +1,4 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "include": ["src", "tests"]
+}

package/plugins/ingestions/web-search/package.json

@@ -6,7 +6,10 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "@gobing-ai/kk-core": "workspace:*"
+        "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-infra": "catalog:",
+        "@gobing-ai/ts-runtime": "catalog:",
+        "@gobing-ai/ts-utils": "catalog:"
     },
     "devDependencies": {
         "@types/bun": "1.3.14"

package/plugins/ingestions/web-search/src/index.ts

@@ -1,8 +1,12 @@
 import { createHash } from 'node:crypto';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { dirname, join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { getLogger, initializeLogger } from '@gobing-ai/ts-infra';
+import { createNodeFileSystem } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+
+const log = getLogger('kk.ingestion.web-search');
 
 /** Validated `--in` input per the 0054 contract (`topic` required; `maxResults`/`fixture` optional). */
 interface InInput {
@@ -49,13 +53,49 @@ export function computeId(uri: string): string {
 /** Fetch signature the live path accepts, so tests can inject a fake (CI never hits the network). */
 export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 
-/** Live-path dependencies — fetch, env, and clock are all injectable for tests. */
+/** markitdown normalizer — HTML in, markdown out (ADR-013 D3). Throws on non-zero exit or
+ * empty output; callers treat a throw as unusable content (per-URL fallback, D5). */
+export type MarkitdownRunner = (html: string) => Promise<string>;
+
+/** Live-path dependencies — fetch, env, clock, scrape, and markitdown are all injectable for tests. */
 export interface SearchDeps {
     fetch: FetchLike;
     env: Record<string, string | undefined>;
     now: () => Date;
+    /** Scrape transport; defaults to `deps.fetch` so tests can route both Firecrawl calls separately. */
+    scrape?: FetchLike;
+    /** markitdown runner; when absent in live mode, `main` probes PATH and fails loud (R6). */
+    markitdown?: MarkitdownRunner;
 }
 
+/** Real markitdown runner: `markitdown -x .html`, HTML on stdin, markdown on stdout. The
+ * `-x .html` extension hint is required — bare stdin passes HTML through unconverted.
+ * Spawns the absolute path resolved via Bun.which (with an explicit PATH option — plain
+ * argv[0] lookup can resolve against a startup PATH snapshot, missing runtime edits). */
+export const realMarkitdown: MarkitdownRunner = async (html: string): Promise<string> => {
+    const bin = Bun.which('markitdown', { PATH: process.env.PATH });
+    if (!bin) {
+        throw new Error('markitdown is not on PATH');
+    }
+    const proc = Bun.spawn([bin, '-x', '.html'], { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' });
+    proc.stdin.write(html);
+    await proc.stdin.end();
+    const [stdout, stderrText, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    if (exitCode !== 0) {
+        const detail = stderrText.trim();
+        throw new Error(`markitdown exited ${exitCode}${detail ? `: ${detail}` : ''}`);
+    }
+    const markdown = stdout.trim();
+    if (markdown.length === 0) {
+        throw new Error('markitdown produced empty output');
+    }
+    return markdown;
+};
+
 /** One Firecrawl `data.web[]` item — the subset of fields 0054 Block 3/4 consume. */
 interface FirecrawlWebItem {
     url?: unknown;
@@ -70,6 +110,12 @@ interface FirecrawlSearchResponse {
     data?: { web?: FirecrawlWebItem[] | null } | null;
 }
 
+/** One Firecrawl `/v2/scrape` body — the subset the cache pass consumes. */
+interface FirecrawlScrapeResponse {
+    success?: unknown;
+    data?: { html?: unknown; markdown?: unknown } | null;
+}
+
 /**
  * Live Firecrawl search → Doc[] (0054 Blocks 2–5). Throws an Error whose message is the
  * fail-loud diagnostic; `main` prefixes it with `web-search failed: ` and returns 1.
@@ -152,7 +198,7 @@ export async function searchFirecrawl(input: InInput, deps: SearchDeps): Promise
         if (!url || body.length === 0) {
             // Row 7 — partial item failure: skip + stderr warn, continue.
             skipped += 1;
-            console.warn(`web-search: skipping result without usable markdown (url=${url ?? 'missing'})`);
+            log.warn(`web-search: skipping result without usable markdown (url=${url ?? 'missing'})`);
             continue;
         }
         docs.push({
@@ -195,6 +241,72 @@ function extractError(bodyText: string): string {
     return '';
 }
 
+/** Scrape + normalize + cache pass over the search results (ADR-013 D1–D6). Sequential
+ * per Doc — deliberate, no parallel fan-out (rate-limit friendly, deterministic). Cache hit
+ * (`references/<doc-id>.md` exists) reuses the file with no new /v2/scrape call (R3/R4);
+ * otherwise scrape → normalize (html via markitdown, markdown as-is) → write cache → body
+ * swap. Per-URL failure or unusable content warns and keeps the snippet body (R5/R11) — never
+ * fatal. Returns a new Doc[]; input order and non-body fields are untouched. */
+export async function scrapeAndCacheDocs(docs: Doc[], deps: SearchDeps, outPath: string): Promise<Doc[]> {
+    const fs = createNodeFileSystem();
+    const cacheDir = join(dirname(outPath), 'references');
+    const scrapeFetch = deps.scrape ?? deps.fetch;
+    const out: Doc[] = [];
+    for (const doc of docs) {
+        const uri = doc.sourceUri;
+        if (!uri) {
+            out.push(doc);
+            continue;
+        }
+        const cacheFile = join(cacheDir, `${doc.id}.md`);
+        try {
+            const cached = await fs.readFile(cacheFile);
+            if (cached.trim().length > 0) {
+                out.push({ ...doc, body: cached });
+                continue;
+            }
+        } catch {
+            // Cache miss — fall through to the live scrape.
+        }
+        try {
+            const key = deps.env.FIRECRAWL_API_KEY;
+            if (!key) throw new Error('FIRECRAWL_API_KEY is unset');
+            const res = await scrapeFetch('https://api.firecrawl.dev/v2/scrape', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${key}`,
+                },
+                body: JSON.stringify({ url: uri, formats: ['html', 'markdown'] }),
+            });
+            if (!res.ok || res.status !== 200) {
+                throw new Error(`Firecrawl HTTP ${res.status}`);
+            }
+            const parsed = JSON.parse(await res.text()) as FirecrawlScrapeResponse;
+            if (parsed.success !== true || parsed.data === null || parsed.data === undefined) {
+                throw new Error('Firecrawl malformed scrape response');
+            }
+            const html = typeof parsed.data.html === 'string' ? parsed.data.html : undefined;
+            const markdown = typeof parsed.data.markdown === 'string' ? parsed.data.markdown : undefined;
+            let normalized: string;
+            if (html && html.trim().length > 0) {
+                normalized = await (deps.markitdown ?? realMarkitdown)(html);
+            } else if (markdown && markdown.trim().length > 0) {
+                normalized = markdown.trim();
+            } else {
+                throw new Error('scrape returned no usable content');
+            }
+            await fs.ensureDir(cacheDir);
+            await fs.writeFile(cacheFile, normalized);
+            out.push({ ...doc, body: normalized });
+        } catch (err: unknown) {
+            log.warn(`web-search: scrape failed (url=${uri}): ${err instanceof Error ? err.message : String(err)}`);
+            out.push(doc);
+        }
+    }
+    return out;
+}
+
 /**
  * Build the fixture `Doc[]` for a topic (0054 Block 4 mapping). Always emits
  * canned docs — the v1 plugin has no live Firecrawl path.
@@ -245,6 +357,7 @@ export function parseInput(raw: string): InInput {
 }
 
 export async function main(): Promise<number> {
+    const fs = createNodeFileSystem();
     const { values } = parseArgs({
         options: {
             in: { type: 'string' },
@@ -253,34 +366,42 @@ export async function main(): Promise<number> {
     });
 
     if (!values.in || !values.out) {
-        console.error('Error: Missing required arguments --in and --out');
+        echoError('Error: Missing required arguments --in and --out');
         return 1;
     }
 
     let input: InInput;
     try {
-        input = parseInput(await readFile(values.in, 'utf-8'));
+        input = parseInput(await fs.readFile(values.in));
     } catch (err: unknown) {
-        console.error(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
+        echoError(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
         return 1;
     }
 
     if (!input.fixture) {
         // 0054 Block 1/Block 8: `fixture` absent/false = LIVE Firecrawl path.
         try {
-            const docs = await searchFirecrawl(input, {
+            const deps: SearchDeps = {
                 fetch: globalThis.fetch,
                 env: process.env,
                 now: () => new Date(),
-            });
+            };
+            // Bun.which with an explicit PATH — without the option it can ignore runtime
+            // process.env.PATH changes (observed on Bun 1.3.14).
+            if (!deps.markitdown && !Bun.which('markitdown', { PATH: deps.env.PATH })) {
+                // R6 — live mode requires the normalizer; fail before any network call.
+                throw new Error('markitdown is not on PATH');
+            }
+            const docs = await searchFirecrawl(input, deps);
+            const cached = await scrapeAndCacheDocs(docs, deps, values.out);
             const outDir = dirname(values.out);
             if (outDir && outDir !== '.') {
-                await mkdir(outDir, { recursive: true });
+                await fs.ensureDir(outDir);
             }
-            await writeFile(values.out, JSON.stringify(DocListSchema.parse(docs), null, 2), 'utf-8');
+            await fs.writeFile(values.out, JSON.stringify(DocListSchema.parse(cached), null, 2));
             return 0;
         } catch (err: unknown) {
-            console.error(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
+            echoError(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
             return 1;
         }
     }
@@ -289,16 +410,17 @@ export async function main(): Promise<number> {
         const docs = DocListSchema.parse(buildFixtureDocs(input.topic, input.maxResults));
         const outDir = dirname(values.out);
         if (outDir && outDir !== '.') {
-            await mkdir(outDir, { recursive: true });
+            await fs.ensureDir(outDir);
         }
-        await writeFile(values.out, JSON.stringify(docs, null, 2), 'utf-8');
+        await fs.writeFile(values.out, JSON.stringify(docs, null, 2));
         return 0;
     } catch (err: unknown) {
-        console.error(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
+        echoError(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
         return 1;
     }
 }
 
 if (import.meta.main) {
+    await initializeLogger({ console: process.env.NODE_ENV !== 'test', json: true, level: 'warn' });
     process.exit(await main());
 }

package/plugins/kk/README.md

@@ -7,9 +7,15 @@ It is a Claude Code / Superskill plugin, **not** a kk-core product plugin.
 |------|--------|
 | `skills/` | Fat skills (`SKILL.md`) |
 | `commands/` | Thin slash-command wrappers |
-| `agents/` | Thin subagent wrappers |
+| `agents/` | Thin subagent wrappers (currently empty — see below) |
 | `hooks/` | Hook definitions |
 | `rules/` | Agent rules |
+| `workflows/` | Design-time product YAML SSOT (ADR-009). Runtime dest is `$HOME/.config/kk/workflows` via `/workflow-run` |
+
+`agents/` is reserved for thin wrappers of fat skills. It is empty: `judge-tech` /
+`judge-tone` / `judge-compliance` were retired (2026-08-19). Rubric selection lives on
+`content-judge` (`agent.run` prompt or `--judge` on `itc-generating`). Do not re-add a
+persona wrapper unless a new skill owns a distinct run procedure.
 
 `discoverPlugins` skips this directory. Product plugins (`ingestion` / `generator` /
 `publish`) live under `plugins/ingestions|generations|publishings/<name>/`.
@@ -17,6 +23,6 @@ It is a Claude Code / Superskill plugin, **not** a kk-core product plugin.
 Install: `superskill install kk`.
 
 Capability files **omit a leading `kk-`**. `superskill install` prefixes the plugin name, so
-`skills/judge` installs as `kk:judge` (not `kk:kk-judge`). Same for `topic`, `storm-research`,
-`/workflow-run`, and the `judge-*` subagents. Product workflow YAML (`kk-storm-research.yaml`)
+`skills/content-judge` installs as `kk:content-judge` (not `kk:kk-content-judge`). Same for `topic`,
+`storm-research`, `itc-generating`, and `/workflow-run`. Product workflow YAML (`kk-storm-research.yaml`)
 keeps its existing name — that is a workflow stem, not an installable agent capability.

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

@@ -1,18 +1,20 @@
 ---
 name: workflow-run
 description: >-
-  Run STORM daily research end to end — a topic sentence XOR a markdown file becomes a
-  grounded content.md report. Installs the workflow YAML on first run (0056 copy rule),
-  creates the config with defaults if missing, computes the topic workspace, and shells
-  spur workflow run against the installed workflow.
-argument-hint: "[name] <topic|--in file> [--fixture] [--force]"
+  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.
+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 wrapper around the **storm-research** skill. Read
-`plugins/kk/skills/storm-research/SKILL.md` first — it is the craft SSOT (query framing,
-evidence verification, better-report practices, fail-loud rows). This command owns the run
-procedure: config create, YAML install, topic-id computation, and the `spur workflow run`.
-No new `kk` CLI noun (ADR-011) — everything here is shell + the workflow.
+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/workflows/` in the package/repo. No new `kk` CLI noun (ADR-011) — everything here
+is shell + the workflow.
 
 **Args:** `$ARGUMENTS`
 
@@ -21,14 +23,25 @@ No new `kk` CLI noun (ADR-011) — everything here is shell + the workflow.
 Parse per the frozen rule:
 
 - First token is the workflow **name** when it matches `^[a-z0-9][a-z0-9-]*$` and is not `--in`;
-  otherwise `name=kk-storm-research` and that token is the topic.
-- `--in <file>` → file mode. `--fixture` → force `fixture: "true"`. `--force` → overwrite an
-  existing dest YAML.
+  otherwise `name=kk-storm-research` and that token is the topic. Supported profile names:
+  `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`),
+  `--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>`
+  (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
   states the XOR rule, no writes.
 
 Resolve these before step 2: `NAME`, `TOPIC`, `INPUT_FILE` (empty in sentence mode), `FIXTURE`
-(`true`|`false`), `FORCE`.
+(`true`|`false`), `FORCE` (`true`|`false`), `DIR`, `PLAYBOOK`, `RESEARCH`, `JUDGE`, `OUTLINE`,
+`WRITER`, `DURATION` (`8`), `LANGUAGE` (`en`), `SCRIPT_APPROVED` (`true`|`false`),
+`VOICE_PROFILE` (from `VOICEBOX_DEFAULT_PROFILE`, default empty).
 
 ## 2. Resolve the config
 
@@ -68,28 +81,43 @@ from config — env-only.
 
 1. `$KK_WORKFLOWS_SOURCE/$NAME.yaml`
 2. `plugins/kk/workflows/$NAME.yaml`
-3. `.spur/workflows/$NAME.yaml`
 
-- `dest` missing → copy from the first hit. Source missing from all three → exit 1, stderr
-  lists the roots searched.
+- `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).
 
 ```bash
 src=""
-for d in "$KK_WORKFLOWS_SOURCE" "plugins/kk/workflows" ".spur/workflows"; do
+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, .spur/workflows)" >&2; exit 1; }
+[ -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
 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
+fi
 ```
 
-## 4. Compute the topic workspace (0056 `topicId`)
+## 4. Compute workspace
+
+### Profile `kk-storm-research` (0056 `topicId`)
 
 `raw` = `TOPIC` (sentence mode) or the first ATX H1 (`/^#\s+(.+)$/m`) else basename without
 extension (`--in` mode). Then:
@@ -110,21 +138,65 @@ work_dir="$works_dir/$topic_id"
 mkdir -p "$work_dir"
 ```
 
+### Profile `kk-itc` (authoring workspace)
+
+`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.
+
+### Profile `kk-solo-podcast`
+
+`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.
+
 ## 5. Run the workflow
 
-All values are strings. Bind the vars first: `maxResults` and `fixture` from step 2;
-`plugins_path` defaults to `./plugins` in a checkout, else the installed package `plugins/`
-path or `KK_PLUGIN_PATH`; `render_script` stays `plugins/kk/scripts/render-md.ts`.
+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`.
 
 ```bash
 spur workflow run "$dest" --vars \
   "{\"topic\":\"$TOPIC\",\"input_file\":\"$INPUT_FILE\",\"maxResults\":\"$maxResults\",\"fixture\":\"$FIXTURE\",\"work_dir\":\"$work_dir\",\"plugins_path\":\"$plugins_path\",\"render_script\":\"$render_script\"}"
 ```
 
+### 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`.
+
+```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\"}"
+```
+
+### 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.
+
+```bash
+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\"}"
+```
+
 ## 6. Report
 
-Print the resolved `work_dir`, then the two artifacts to hand the operator:
-`$work_dir/content.md` (report sidecar) and `$work_dir/content.json` (machine contract).
-Per the skill's better-report practice (d), skim `content.md` citations against `docs.json`
-ids before presenting. If the run ended `failed`, show the failing state
-(`spur workflow trace <run-id> --json`) and the skill's fail-loud recovery row.
+- **`kk-storm-research`**: print resolved `work_dir`, then `$work_dir/content.md` (report sidecar)
+  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`.
+
+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

@@ -0,0 +1,34 @@
+works_dir: "~/.config/kk/works"
+workflows_dir: "~/.config/kk/workflows"
+defaults:
+  maxResults: 8
+  fixture: false
+
+# Plugin credentials — paste values between the quotes.
+# Path: plugins/<collection>/<name>/env — each entry is injected into that plugin's
+# process environment at exec time. A real environment variable always wins
+# over a value here (flag > env > config > compiled default).
+plugins:
+  ingestions:
+    web-search:
+      env:
+        FIRECRAWL_API_KEY: ""   # firecrawl.dev — required for live research
+  generations:
+    voice-gen:
+      env:
+        VOICEBOX_URL: "http://127.0.0.1:17493"     # local Voicebox REST origin
+        VOICEBOX_DEFAULT_PROFILE: "Robin"          # GET /profiles name or id — required for plain-text Docs
+        VOICEBOX_TIMEOUT_MS: "600000"              # per-generation poll budget (ms)
+        VOICEBOX_POLL_MS: "1000"                   # GET /history/{id} interval
+        VOICEBOX_MAX_CHUNK_CHARS: "800"            # Voicebox auto-chunk size (100–5000)
+        VOICEBOX_CROSSFADE_MS: "50"                # Voicebox chunk crossfade (0–500)
+  publishings:
+    qiita-pub:
+      env:
+        QIITA_TOKEN: ""         # Qiita API v2 token (read_qiita/write_qiita) — required
+    zenn-pub:
+      env:
+        ZENN_REPO: ""           # GitHub repo for Zenn CLI deploy — used by zenn-pub
+    surfdash-pub:
+      env:
+        POSTSURFING_BIN: ""    # optional — delete if unused; defaults to `postsurfing` on PATH