@gobing-ai/knowledge-kit 0.0.8 → 0.0.10

package/plugins/ingestions/aihot-ingest/src/client.ts

@@ -0,0 +1,185 @@
+import { echoError } from '@gobing-ai/ts-utils';
+import { z } from 'zod';
+
+export const AIHOT_BASE_URL = 'https://aihot.virxact.com';
+export const DEFAULT_AIHOT_USER_AGENT = 'aihot-ingest/1.0.0';
+
+export const AihotItemSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    originalTitle: z.string().nullable(),
+    summary: z.string().nullable(),
+    source: z.object({ name: z.string() }),
+    links: z.object({
+        aihot: z.url(),
+        original: z.url(),
+    }),
+    publishedAt: z.iso.datetime().nullable(),
+    discoveredAt: z.iso.datetime(),
+    category: z.string().nullable(),
+    score: z.number().min(0).max(100).nullable(),
+    selected: z.boolean(),
+    reason: z.string().nullable().optional(),
+    attribution: z
+        .object({
+            name: z.string(),
+            url: z.url(),
+        })
+        .optional(),
+});
+
+export type AihotItem = z.infer<typeof AihotItemSchema>;
+
+export const AihotSnapshotResponseSchema = z.object({
+    schemaVersion: z.literal(1),
+    asOf: z.iso.datetime(),
+    fields: z.literal('default'),
+    cursor: z.string(),
+    count: z.number().int().nonnegative(),
+    hasMore: z.boolean(),
+    nextPage: z.string().nullable(),
+    items: z.array(AihotItemSchema),
+});
+
+export type AihotSnapshotResponse = z.infer<typeof AihotSnapshotResponseSchema>;
+
+const AihotSnapshotEnvelopeSchema = AihotSnapshotResponseSchema.extend({
+    items: z.array(z.unknown()),
+});
+
+export const AihotChangeSchema = z.discriminatedUnion('op', [
+    z.object({
+        op: z.literal('upsert'),
+        item: AihotItemSchema,
+        changedAt: z.iso.datetime(),
+    }),
+    z.object({
+        op: z.literal('remove'),
+        id: z.string(),
+        changedAt: z.iso.datetime(),
+    }),
+]);
+
+export const AihotChangesResponseSchema = z.object({
+    schemaVersion: z.literal(1),
+    fields: z.literal('default'),
+    cursor: z.string(),
+    count: z.number().int().nonnegative(),
+    hasMore: z.boolean(),
+    changes: z.array(AihotChangeSchema),
+});
+
+export type AihotChangesResponse = z.infer<typeof AihotChangesResponseSchema>;
+
+const AihotChangesEnvelopeSchema = AihotChangesResponseSchema.extend({
+    changes: z.array(z.unknown()),
+});
+
+export type FetchLike = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export interface AihotDeps {
+    fetch: FetchLike;
+    baseUrl?: string;
+    userAgent?: string;
+    warn?: (message: string) => void;
+}
+
+export interface FetchSnapshotOptions {
+    limit?: number;
+    page?: string;
+}
+
+export interface FetchChangesOptions {
+    cursor: string;
+    limit?: number;
+}
+
+export class AihotClient {
+    private readonly fetch: FetchLike;
+    private readonly baseUrl: string;
+    private readonly userAgent: string;
+    private readonly warn: (message: string) => void;
+
+    constructor(deps?: Partial<AihotDeps>) {
+        this.fetch = deps?.fetch ?? globalThis.fetch;
+        this.baseUrl = (deps?.baseUrl ?? AIHOT_BASE_URL).replace(/\/+$/, '');
+        this.userAgent = deps?.userAgent ?? DEFAULT_AIHOT_USER_AGENT;
+        this.warn = deps?.warn ?? echoError;
+    }
+
+    public async fetchSnapshot(options?: FetchSnapshotOptions): Promise<AihotSnapshotResponse> {
+        const url = new URL(`${this.baseUrl}/api/v1/selected/snapshot`);
+        if (options?.limit !== undefined) {
+            url.searchParams.set('limit', String(options.limit));
+        }
+        if (options?.page) {
+            url.searchParams.set('page', options.page);
+        }
+        url.searchParams.set('fields', 'default');
+
+        const res = await this.fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': this.userAgent,
+            },
+        });
+
+        if (!res.ok) {
+            const errBody = (await res.text()).slice(0, 1000);
+            throw new Error(
+                `aihot snapshot request failed (HTTP ${res.status} ${res.statusText}): ${errBody || 'Unknown error'}`,
+            );
+        }
+
+        const response = AihotSnapshotEnvelopeSchema.parse(await res.json());
+        return {
+            ...response,
+            items: this.parseRecords(response.items, AihotItemSchema, 'snapshot item'),
+        };
+    }
+
+    public async fetchChanges(options: FetchChangesOptions): Promise<AihotChangesResponse> {
+        const url = new URL(`${this.baseUrl}/api/v1/selected/changes`);
+        url.searchParams.set('cursor', options.cursor);
+        if (options.limit !== undefined) {
+            url.searchParams.set('limit', String(options.limit));
+        }
+
+        const res = await this.fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': this.userAgent,
+            },
+        });
+
+        if (!res.ok) {
+            const errBody = (await res.text()).slice(0, 1000);
+            throw new Error(
+                `aihot changes request failed (HTTP ${res.status} ${res.statusText}): ${errBody || 'Unknown error'}`,
+            );
+        }
+
+        const response = AihotChangesEnvelopeSchema.parse(await res.json());
+        return {
+            ...response,
+            changes: this.parseRecords(response.changes, AihotChangeSchema, 'change record'),
+        };
+    }
+
+    private parseRecords<T>(records: unknown[], schema: z.ZodType<T>, label: string): T[] {
+        return records.flatMap((record, index) => {
+            const result = schema.safeParse(record);
+            if (result.success) return [result.data];
+
+            const details = result.error.issues.map((issue) => `${issue.path.join('.') || '<root>'}: ${issue.message}`);
+            this.warn(`aihot: skipping invalid ${label} at index ${index} (${details.join('; ')})`);
+            return [];
+        });
+    }
+}
+
+export function createAihotClient(deps?: Partial<AihotDeps>): AihotClient {
+    return new AihotClient(deps);
+}

package/plugins/ingestions/aihot-ingest/src/index.ts

@@ -0,0 +1,137 @@
+import { dirname } from 'node:path';
+import { parseArgs } from 'node:util';
+import { type Doc, DocListSchema } from '@gobing-ai/kk-core';
+import { atomicWriteJson, createNodeFileSystem, readJsonFile } from '@gobing-ai/ts-runtime';
+import { echoError } from '@gobing-ai/ts-utils';
+import { z } from 'zod';
+import { type AihotDeps, createAihotClient } from './client';
+import { mapAihotItemsToDocs } from './mapper';
+
+export * from './client';
+export * from './mapper';
+
+export interface IngestionOptions {
+    out: string;
+    limit?: number;
+    cursor?: string;
+    stateFile?: string;
+}
+
+export interface IngestionResult {
+    docs: Doc[];
+    cursor: string;
+    asOf?: string;
+}
+
+const IngestionInputSchema = z.object({
+    limit: z.number().int().min(1).max(100).optional(),
+    cursor: z.string().trim().min(1).optional(),
+    stateFile: z.string().trim().min(1).optional(),
+});
+
+const CursorStateSchema = z.object({ cursor: z.string().trim().min(1) });
+
+function parseLimit(value: string): number {
+    return z.coerce.number().int().min(1).max(100).parse(value);
+}
+
+export async function processIngestionIO(
+    options: IngestionOptions,
+    depsOverride?: Partial<AihotDeps>,
+): Promise<IngestionResult> {
+    const fs = createNodeFileSystem();
+    const client = createAihotClient(depsOverride);
+
+    let effectiveCursor = options.cursor?.trim();
+    if (!effectiveCursor && options.stateFile && (await fs.exists(options.stateFile))) {
+        effectiveCursor = CursorStateSchema.parse(await readJsonFile(options.stateFile, fs)).cursor;
+    }
+
+    let items: import('./client').AihotItem[];
+    let cursor: string;
+    let asOf: string | undefined;
+
+    if (effectiveCursor) {
+        const changes = await client.fetchChanges({
+            cursor: effectiveCursor,
+            limit: options.limit,
+        });
+        items = changes.changes.flatMap((change) => (change.op === 'upsert' ? [change.item] : []));
+        cursor = changes.cursor;
+    } else {
+        const snapshot = await client.fetchSnapshot({
+            limit: options.limit,
+        });
+        items = snapshot.items;
+        cursor = snapshot.cursor;
+        asOf = snapshot.asOf;
+    }
+
+    const docs = DocListSchema.parse(mapAihotItemsToDocs(items));
+
+    const outDir = dirname(options.out);
+    if (outDir && outDir !== '.') {
+        await fs.ensureDir(outDir);
+    }
+    await atomicWriteJson(options.out, docs, fs);
+
+    if (options.stateFile) {
+        const stateDir = dirname(options.stateFile);
+        if (stateDir && stateDir !== '.') {
+            await fs.ensureDir(stateDir);
+        }
+        const statePayload = {
+            cursor,
+            asOf,
+            lastSyncAt: new Date().toISOString(),
+            itemCount: docs.length,
+        };
+        await atomicWriteJson(options.stateFile, statePayload, fs);
+    }
+
+    return { docs, cursor, asOf };
+}
+
+export async function main(depsOverride?: Partial<AihotDeps>): Promise<number> {
+    let values: { in?: string; out?: string; limit?: string; cursor?: string; 'state-file'?: string };
+    try {
+        ({ values } = parseArgs({
+            options: {
+                in: { type: 'string' },
+                out: { type: 'string' },
+                limit: { type: 'string' },
+                cursor: { type: 'string' },
+                'state-file': { type: 'string' },
+            },
+        }));
+    } catch (err: unknown) {
+        echoError(`aihot-ingest failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+
+    if (!values.out) {
+        echoError('aihot-ingest failed: Missing required argument: --out');
+        return 1;
+    }
+
+    try {
+        const input = values.in ? IngestionInputSchema.parse(await readJsonFile(values.in)) : {};
+        await processIngestionIO(
+            {
+                out: values.out,
+                limit: values.limit ? parseLimit(values.limit) : (input.limit ?? 10),
+                cursor: values.cursor ?? input.cursor,
+                stateFile: values['state-file'] ?? input.stateFile,
+            },
+            depsOverride,
+        );
+        return 0;
+    } catch (err: unknown) {
+        echoError(`aihot-ingest failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exit(await main());
+}

package/plugins/ingestions/aihot-ingest/src/mapper.ts

@@ -0,0 +1,42 @@
+import { createHash } from 'node:crypto';
+import type { Doc } from '@gobing-ai/kk-core';
+import type { AihotItem } from './client';
+
+export function computeDocId(seed: string): string {
+    return createHash('sha256').update(seed).digest('hex').slice(0, 16);
+}
+
+export function mapAihotItemToDoc(item: AihotItem): Doc {
+    const rawId = item.id.trim();
+    const canonicalSource = item.links.original || item.links.aihot || item.title || 'untitled';
+    const id = rawId.length > 0 ? rawId : computeDocId(canonicalSource);
+
+    const sourceUri = item.links?.original || item.links?.aihot || `https://aihot.virxact.com/items/${id}`;
+    const title = item.title.trim() || 'Untitled AI News';
+    const body = `${item.summary?.trim() || item.title.trim()}\n`;
+
+    const metadata: Record<string, unknown> = {
+        sourceName: item.source.name,
+        publishedAt: item.publishedAt,
+        discoveredAt: item.discoveredAt,
+        category: item.category ?? undefined,
+        score: item.score ?? undefined,
+        aihotUrl: item.links.aihot,
+        originalUrl: item.links.original,
+        attribution: item.attribution,
+        reason: item.reason ?? undefined,
+    };
+
+    return {
+        id,
+        title,
+        sourceUri,
+        body,
+        mediaType: 'text/markdown',
+        metadata,
+    };
+}
+
+export function mapAihotItemsToDocs(items: AihotItem[]): Doc[] {
+    return items.map(mapAihotItemToDoc);
+}

package/plugins/ingestions/aihot-ingest/tsconfig.json

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

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

@@ -356,7 +356,7 @@ export function parseInput(raw: string): InInput {
     return { topic: input.topic, maxResults, fixture: input.fixture === true };
 }
 
-export async function main(): Promise<number> {
+export async function main(depsOverride?: Partial<SearchDeps>): Promise<number> {
     const fs = createNodeFileSystem();
     const { values } = parseArgs({
         options: {
@@ -385,6 +385,7 @@ export async function main(): Promise<number> {
                 fetch: globalThis.fetch,
                 env: process.env,
                 now: () => new Date(),
+                ...depsOverride,
             };
             // Bun.which with an explicit PATH — without the option it can ignore runtime
             // process.env.PATH changes (observed on Bun 1.3.14).

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

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