@gobing-ai/knowledge-kit 0.0.5 → 0.0.7

package/dist/index.js

@@ -16682,6 +16682,8 @@ function isDirectory(path2) {
 function getByName(result, name) {
   return result.plugins.find((p) => p.name === name);
 }
+// ../../packages/kk-core/src/render-md.ts
+if (false) {}
 // src/fanin.ts
 var EXIT_USAGE = 2;
 var EXIT_INPUT = 1;
@@ -17438,7 +17440,7 @@ function createProgram() {
 }
 
 // src/main.ts
-async function main(argv = process.argv, options = {}) {
+async function main2(argv = process.argv, options = {}) {
   const program2 = createProgram();
   program2.exitOverride();
   program2.configureOutput({
@@ -17468,5 +17470,5 @@ async function main(argv = process.argv, options = {}) {
 
 // src/index.ts
 if (import.meta.main) {
-  process.exit(await main());
+  process.exit(await main2());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/knowledge-kit",
-    "version": "0.0.5",
+    "version": "0.0.7",
     "description": "An ingest → create → publish content pipeline CLI (Bun).",
     "repository": {
         "type": "git",

package/plugins/generations/content-gen/package.json

@@ -7,7 +7,8 @@
     },
     "dependencies": {
         "@gobing-ai/kk-core": "workspace:*",
-        "@gobing-ai/utils": "workspace:*"
+        "@gobing-ai/utils": "workspace:*",
+        "zod": "4.4.3"
     },
     "devDependencies": {
         "@types/bun": "1.3.14"

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

@@ -40,11 +40,161 @@ const FIXTURE_ENTRIES: FixtureEntry[] = [
     },
 ];
 
-/** Deterministic Doc id: sha256(sourceUri) hex prefix, same idea as karakeep-local (0054 Block 4). */
-function computeId(uri: string): string {
+/** Deterministic Doc id: sha256(sourceUri) hex prefix, same idea as karakeep-local (0054 Block 4).
+ * Exported so 0059's local-Doc mapping can stay consistent if a later helper imports it (R3). */
+export function computeId(uri: string): string {
     return createHash('sha256').update(uri).digest('hex').slice(0, 16);
 }
 
+/** 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. */
+export interface SearchDeps {
+    fetch: FetchLike;
+    env: Record<string, string | undefined>;
+    now: () => Date;
+}
+
+/** One Firecrawl `data.web[]` item — the subset of fields 0054 Block 3/4 consume. */
+interface FirecrawlWebItem {
+    url?: unknown;
+    title?: unknown;
+    markdown?: unknown;
+    position?: unknown;
+}
+
+interface FirecrawlSearchResponse {
+    success?: unknown;
+    error?: unknown;
+    data?: { web?: FirecrawlWebItem[] | null } | 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.
+ * Never writes `--out` on a thrown path (no DocListSchema.parse, no file write here).
+ */
+export async function searchFirecrawl(input: InInput, deps: SearchDeps): Promise<Doc[]> {
+    const key = deps.env.FIRECRAWL_API_KEY;
+    if (!key) {
+        // 0054 Block 5 row 2 — key required by this plugin's contract, not by Firecrawl.
+        throw new Error('FIRECRAWL_API_KEY is unset');
+    }
+
+    let res: Response;
+    try {
+        res = await deps.fetch('https://api.firecrawl.dev/v2/search', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${key}`,
+            },
+            body: JSON.stringify({
+                query: input.topic,
+                limit: input.maxResults,
+                sources: ['web'],
+                scrapeOptions: { formats: ['markdown'] },
+            }),
+        });
+    } catch (err: unknown) {
+        // 0054 Block 5 row 3 — transport error (DNS, refused, TLS, fetch throws).
+        throw new Error(`Firecrawl network error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    let bodyText: string;
+    try {
+        bodyText = await res.text();
+    } catch {
+        throw new Error(`Firecrawl HTTP ${res.status}: empty response body`);
+    }
+
+    if (!res.ok || res.status !== 200) {
+        // 0054 Block 5 rows 4–5 — 401/402/400/404/408/429/5xx. No silent retry in v1.
+        throw new Error(`Firecrawl HTTP ${res.status}: ${extractError(bodyText)}`);
+    }
+
+    let parsed: FirecrawlSearchResponse;
+    try {
+        parsed = JSON.parse(bodyText) as FirecrawlSearchResponse;
+    } catch {
+        // 200 but not JSON → malformed response (row 5).
+        throw new Error('Firecrawl malformed response: invalid JSON');
+    }
+
+    if (parsed.success === false) {
+        // 0054 Block 5 row 5 — `success:false` in a 200 body.
+        throw new Error(`Firecrawl HTTP 200: ${extractError(bodyText)}`);
+    }
+
+    if (parsed.success !== true) {
+        throw new Error('Firecrawl malformed response: success missing');
+    }
+
+    // Row 5 (P4): a 200 `success:true` with `data` absent/null is malformed, not zero hits.
+    if (parsed.data === null || parsed.data === undefined) {
+        throw new Error('Firecrawl malformed response: data missing');
+    }
+
+    const web = parsed.data.web ?? [];
+
+    // Row 6 — true zero hits: write `[]`, exit 0.
+    if (web.length === 0) {
+        return [];
+    }
+
+    const docs: Doc[] = [];
+    let skipped = 0;
+    for (const [rank, item] of web.entries()) {
+        const url = typeof item.url === 'string' ? item.url : undefined;
+        const markdown = typeof item.markdown === 'string' ? item.markdown : undefined;
+        const body = markdown?.trim() ?? '';
+        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'})`);
+            continue;
+        }
+        docs.push({
+            id: computeId(url),
+            body,
+            title: typeof item.title === 'string' ? item.title : undefined,
+            sourceUri: url,
+            mediaType: 'text/markdown',
+            metadata: {
+                query: input.topic,
+                rank,
+                position: typeof item.position === 'number' ? item.position : undefined,
+                scraped_at: deps.now().toISOString(),
+            },
+        });
+    }
+
+    // Row 8 — hits > 0 but every item skipped: deliberate departure from C1 (0054 Block 6b).
+    if (docs.length === 0 && skipped > 0) {
+        throw new Error('Firecrawl returned hits but no usable markdown bodies');
+    }
+
+    return docs;
+}
+
+/** Best-effort `error` message from a Firecrawl error body; empty when unavailable. */
+function extractError(bodyText: string): string {
+    try {
+        const parsed = JSON.parse(bodyText) as { error?: unknown };
+        const error = parsed.error;
+        if (typeof error === 'string' && error.length > 0) {
+            return error;
+        }
+        if (error !== undefined && error !== null) {
+            return JSON.stringify(error);
+        }
+    } catch {
+        // Non-JSON error body — fall through to empty.
+    }
+    return '';
+}
+
 /**
  * Build the fixture `Doc[]` for a topic (0054 Block 4 mapping). Always emits
  * canned docs — the v1 plugin has no live Firecrawl path.
@@ -116,13 +266,23 @@ export async function main(): Promise<number> {
     }
 
     if (!input.fixture) {
-        // 0054 Block 1/Block 8: `fixture` absent or false selects the LIVE Firecrawl path; v1 has no
-        // live client. Fail loud (Block 5 row-2 semantics: exit 1, no --out) instead of silently
-        // fabricating research docs — an obvious failure beats a surprising recovery.
-        console.error(
-            'web-search failed: live Firecrawl not implemented in v1 (pass "fixture": true to use the fixture stub)',
-        );
-        return 1;
+        // 0054 Block 1/Block 8: `fixture` absent/false = LIVE Firecrawl path.
+        try {
+            const docs = await searchFirecrawl(input, {
+                fetch: globalThis.fetch,
+                env: process.env,
+                now: () => new Date(),
+            });
+            const outDir = dirname(values.out);
+            if (outDir && outDir !== '.') {
+                await mkdir(outDir, { recursive: true });
+            }
+            await writeFile(values.out, JSON.stringify(DocListSchema.parse(docs), null, 2), 'utf-8');
+            return 0;
+        } catch (err: unknown) {
+            console.error(`web-search failed: ${err instanceof Error ? err.message : String(err)}`);
+            return 1;
+        }
     }
 
     try {

package/plugins/kk/README.md

@@ -15,3 +15,8 @@ It is a Claude Code / Superskill plugin, **not** a kk-core product plugin.
 `publish`) live under `plugins/ingestions|generations|publishings/<name>/`.
 
 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`)
+keeps its existing name — that is a workflow stem, not an installable agent capability.

package/plugins/kk/agents/{kk-judge-compliance.md → judge-compliance.md}

@@ -1,18 +1,18 @@
 ---
-name: kk-judge-compliance
-description: This specialized judge agent should be used when evaluating generated content for regulatory, legal, or safety compliance — prohibited claims, required disclosures, jurisdictional rules, and PII/sensitive-data leakage. Triggers on "compliance check", "legal review of content", "check prohibited claims", "verify disclosures", "regulatory gate", or when a spur workflow needs a compliance evaluation gate before publishing. Delegates all evaluation logic to the kk-judge fat skill with the compliance rubric pre-selected.
+name: judge-compliance
+description: This specialized judge agent should be used when evaluating generated content for regulatory, legal, or safety compliance — prohibited claims, required disclosures, jurisdictional rules, and PII/sensitive-data leakage. Triggers on "compliance check", "legal review of content", "check prohibited claims", "verify disclosures", "regulatory gate", or when a spur workflow needs a compliance evaluation gate before publishing. Delegates all evaluation logic to the judge fat skill with the compliance rubric pre-selected.
 tools: Read, Grep, Glob
 ---
 
-# kk-judge-compliance — compliance judge persona
+# judge-compliance — compliance judge persona
 
-Thin wrapper around the **kk-judge** fat skill. Fixes the rubric to `compliance` and forwards
+Thin wrapper around the **judge** fat skill. Fixes the rubric to `compliance` and forwards
 evaluation. Do not duplicate evaluation logic here — the skill owns it.
 
 ## Behavior
 
 1. Receive the content path and the jurisdiction/policy config from the caller or workflow step.
-2. Invoke the `kk-judge` skill procedure with `rubric: compliance`.
+2. Invoke the `judge` skill procedure with `rubric: compliance`.
 3. Return the verdict JSON path; the skill writes the verdict file.
 
 ## Invocation contract
@@ -20,10 +20,10 @@ evaluation. Do not duplicate evaluation logic here — the skill owns it.
 When invoked by an `agent.run` workflow step:
 
 ```
-You are the kk-judge-compliance persona.
-Load the kk-judge skill from plugins/kk/skills/kk-judge/SKILL.md.
+You are the judge-compliance persona.
+Load the judge skill from plugins/kk/skills/judge/SKILL.md.
 Evaluate the content at {{content_path}} against the compliance rubric
-  (plugins/kk/skills/kk-judge/references/rubrics.md, section "compliance").
+  (plugins/kk/skills/judge/references/rubrics.md, section "compliance").
 Jurisdiction/policy: {{jurisdiction}}      # e.g. US-SEC, EU-GDPR, CN-CAC; or "unspecified"
 Write the verdict JSON to {{verdict_path}} per the contract in SKILL.md.
 Print the verdict path as the last line of stdout.

package/plugins/kk/agents/{kk-judge-tech.md → judge-tech.md}

@@ -1,18 +1,18 @@
 ---
-name: kk-judge-tech
-description: This specialized judge agent should be used when evaluating generated technical content for factual accuracy, citation integrity, and code correctness. Triggers on "check technical accuracy", "verify tech content", "fact-check technical", "review code samples in content", or when a spur workflow needs a technical-accuracy evaluation gate. Delegates all evaluation logic to the kk-judge fat skill with the tech-accuracy rubric pre-selected.
+name: judge-tech
+description: This specialized judge agent should be used when evaluating generated technical content for factual accuracy, citation integrity, and code correctness. Triggers on "check technical accuracy", "verify tech content", "fact-check technical", "review code samples in content", or when a spur workflow needs a technical-accuracy evaluation gate. Delegates all evaluation logic to the judge fat skill with the tech-accuracy rubric pre-selected.
 tools: Read, Grep, Glob
 ---
 
-# kk-judge-tech — technical-accuracy judge persona
+# judge-tech — technical-accuracy judge persona
 
-Thin wrapper around the **kk-judge** fat skill. Fixes the rubric to `tech-accuracy` and forwards
+Thin wrapper around the **judge** fat skill. Fixes the rubric to `tech-accuracy` and forwards
 evaluation. Do not duplicate evaluation logic here — the skill owns it.
 
 ## Behavior
 
 1. Receive the content path (and optional verdict output path) from the caller or workflow step.
-2. Invoke the `kk-judge` skill procedure with `rubric: tech-accuracy`.
+2. Invoke the `judge` skill procedure with `rubric: tech-accuracy`.
 3. Return the verdict JSON path; the skill writes the verdict file.
 
 ## Invocation contract
@@ -20,10 +20,10 @@ evaluation. Do not duplicate evaluation logic here — the skill owns it.
 When invoked by an `agent.run` workflow step:
 
 ```
-You are the kk-judge-tech persona.
-Load the kk-judge skill from plugins/kk/skills/kk-judge/SKILL.md.
+You are the judge-tech persona.
+Load the judge skill from plugins/kk/skills/judge/SKILL.md.
 Evaluate the content at {{content_path}} against the tech-accuracy rubric
-  (plugins/kk/skills/kk-judge/references/rubrics.md, section "tech-accuracy").
+  (plugins/kk/skills/judge/references/rubrics.md, section "tech-accuracy").
 Write the verdict JSON to {{verdict_path}} per the contract in SKILL.md.
 Print the verdict path as the last line of stdout.
 ```

package/plugins/kk/agents/{kk-judge-tone.md → judge-tone.md}

@@ -1,19 +1,19 @@
 ---
-name: kk-judge-tone
-description: This specialized judge agent should be used when evaluating generated content for brand voice and tone consistency, banned-phrase compliance, and audience fit. Triggers on "check brand tone", "review voice consistency", "tone audit", "style guide check", or when a spur workflow needs a brand-tone evaluation gate before publishing. Delegates all evaluation logic to the kk-judge fat skill with the brand-tone rubric pre-selected.
+name: judge-tone
+description: This specialized judge agent should be used when evaluating generated content for brand voice and tone consistency, banned-phrase compliance, and audience fit. Triggers on "check brand tone", "review voice consistency", "tone audit", "style guide check", or when a spur workflow needs a brand-tone evaluation gate before publishing. Delegates all evaluation logic to the judge fat skill with the brand-tone rubric pre-selected.
 tools: Read, Grep, Glob
 ---
 
-# kk-judge-tone — brand-tone judge persona
+# judge-tone — brand-tone judge persona
 
-Thin wrapper around the **kk-judge** fat skill. Fixes the rubric to `brand-tone` and forwards
+Thin wrapper around the **judge** fat skill. Fixes the rubric to `brand-tone` and forwards
 evaluation. Do not duplicate evaluation logic here — the skill owns it.
 
 ## Behavior
 
 1. Receive the content path and the brand config (tone profile + banned-phrase list) from the
    caller or workflow step.
-2. Invoke the `kk-judge` skill procedure with `rubric: brand-tone`.
+2. Invoke the `judge` skill procedure with `rubric: brand-tone`.
 3. Return the verdict JSON path; the skill writes the verdict file.
 
 ## Invocation contract
@@ -21,10 +21,10 @@ evaluation. Do not duplicate evaluation logic here — the skill owns it.
 When invoked by an `agent.run` workflow step:
 
 ```
-You are the kk-judge-tone persona.
-Load the kk-judge skill from plugins/kk/skills/kk-judge/SKILL.md.
+You are the judge-tone persona.
+Load the judge skill from plugins/kk/skills/judge/SKILL.md.
 Evaluate the content at {{content_path}} against the brand-tone rubric
-  (plugins/kk/skills/kk-judge/references/rubrics.md, section "brand-tone").
+  (plugins/kk/skills/judge/references/rubrics.md, section "brand-tone").
 Brand config (tone profile + banned phrases): {{brand_config}}
 Write the verdict JSON to {{verdict_path}} per the contract in SKILL.md.
 Print the verdict path as the last line of stdout.

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

@@ -0,0 +1,130 @@
+---
+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]"
+---
+
+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.
+
+**Args:** `$ARGUMENTS`
+
+## 1. Parse `$ARGUMENTS`
+
+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.
+- **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`.
+
+## 2. Resolve the config
+
+`config_path="${KK_CONFIG:-$HOME/.config/kk/config.yaml}"`.
+
+- **Missing file → create-on-first-run** with compiled defaults (never overwrite an existing
+  file — no merge, no rewrite):
+
+```bash
+install -d "$(dirname "$config_path")"
+cat > "$config_path" <<'EOF'
+works_dir: "$HOME/.config/kk/works"
+workflows_dir: "$HOME/.config/kk/workflows"
+defaults:
+  maxResults: 8
+  fixture: false
+EOF
+```
+
+- **Unreadable / unparseable / invalid types** (e.g. `maxResults: "eight"`) → exit 1, stderr
+  names the key and expected vs actual type; touch nothing.
+- Read the four values with precedence **command flag > env > file > compiled default**:
+
+| Value | Env override | Compiled default |
+| --- | --- | --- |
+| `works_dir` | `KK_WORKS_DIR` | `$HOME/.config/kk/works` |
+| `workflows_dir` | `KK_WORKFLOWS_DIR` | `$HOME/.config/kk/workflows` |
+| `defaults.maxResults` | — | `8` |
+| `defaults.fixture` | — | `false` |
+
+`--fixture` sets `fixture=true` regardless of the file. `FIRECRAWL_API_KEY` is **never** read
+from config — env-only.
+
+## 3. Install the workflow YAML
+
+`dest="$workflows_dir/$NAME.yaml"`. Copy from the **first hit** of, in order:
+
+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` 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
+  [ -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; }
+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
+```
+
+## 4. Compute the topic workspace (0056 `topicId`)
+
+`raw` = `TOPIC` (sentence mode) or the first ATX H1 (`/^#\s+(.+)$/m`) else basename without
+extension (`--in` mode). Then:
+
+```bash
+normalized=$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | tr -s '[:space:]' ' ' | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+slug=$(printf '%s' "$normalized" | tr -cs 'a-z0-9' '-' | sed 's/^-*//; s/-*$//' | cut -c1-48 | sed '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"
+```
+
+- `raw` derives empty (no H1 and empty basename) → exit 1 with the derived value.
+- Same `raw` → same workspace; **last write wins**; never fail on an existing works dir.
+
+```bash
+mkdir -p "$work_dir"
+```
+
+## 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`.
+
+```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\"}"
+```
+
+## 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.

package/plugins/kk/scripts/render-md.ts

@@ -0,0 +1,145 @@
+/**
+ * Shipped no-checkout runner for the Content→markdown research-report helper.
+ * 0059's `render` state shells: `bun <this script> --in <content.json> --out <content.md>`.
+ *
+ * Self-contained by design: end users install the published `kk` package and cannot
+ * resolve `@gobing-ai/kk-core` (private). The render logic below is a COPY of
+ * `packages/kk-core/src/render-md.ts`; keep them byte-identical for the same Content.
+ *
+ * SYNC: packages/kk-core/src/render-md.ts (renderContentMarkdown + helpers)
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+
+interface Ref {
+    url?: string;
+    title?: string;
+    cite?: string;
+}
+
+interface ContentInput {
+    body: string;
+    title?: string;
+    outline?: string;
+    references?: Ref[];
+}
+
+/** Mirror of `ContentSchema` structural requirements for the fields this render touches. */
+function parseContent(raw: string): ContentInput {
+    const value: unknown = JSON.parse(raw);
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('content must be an object');
+    }
+    const c = value as Record<string, unknown>;
+    if (typeof c.body !== 'string') {
+        throw new Error('body is required and must be a string');
+    }
+    const out: ContentInput = { body: c.body };
+    if (c.title !== undefined) {
+        if (typeof c.title !== 'string') {
+            throw new Error('title must be a string');
+        }
+        out.title = c.title;
+    }
+    if (c.outline !== undefined) {
+        if (typeof c.outline !== 'string') {
+            throw new Error('outline must be a string');
+        }
+        out.outline = c.outline;
+    }
+    if (c.references !== undefined) {
+        if (!Array.isArray(c.references)) {
+            throw new Error('references must be an array');
+        }
+        out.references = c.references.map((r, i) => {
+            if (r === null || typeof r !== 'object' || Array.isArray(r)) {
+                throw new Error(`references[${i}] must be an object`);
+            }
+            const rr = r as Record<string, unknown>;
+            for (const key of ['url', 'title', 'cite'] as const) {
+                if (rr[key] !== undefined && typeof rr[key] !== 'string') {
+                    throw new Error(`references[${i}].${key} must be a string`);
+                }
+            }
+            return { url: rr.url, title: rr.title, cite: rr.cite } as Ref;
+        });
+    }
+    return out;
+}
+
+export function renderContentMarkdown(content: ContentInput): string {
+    const heading = content.title?.trim() || 'Untitled';
+    const startsWithHeading = content.body.startsWith(`# ${heading}`);
+    const lead = startsWithHeading ? '' : `# ${heading}\n\n`;
+    const outlineBlock =
+        content.outline && content.outline.trim().length > 0 ? `\n\n## Outline\n\n${content.outline.trim()}` : '';
+    const refsBlock = renderReferences(content.references);
+    return `${lead}${content.body}${outlineBlock}${refsBlock}\n`;
+}
+
+function renderReferences(references: ContentInput['references']): string {
+    if (!references || references.length === 0) {
+        return '';
+    }
+    const lines: string[] = [];
+    for (const ref of references) {
+        const label = renderReferenceLabel(ref);
+        if (label === '') {
+            continue;
+        }
+        lines.push(`- ${label}`);
+    }
+    if (lines.length === 0) {
+        return '';
+    }
+    return `\n\n## References\n\n${lines.join('\n')}`;
+}
+
+function renderReferenceLabel(ref: Ref): string {
+    const { url, title, cite } = ref;
+    const titleT = title?.trim() ?? '';
+    const urlT = url?.trim() ?? '';
+    const citeT = cite?.trim() ?? '';
+    let label: string;
+    if (titleT !== '' && urlT !== '') {
+        label = `[${titleT}](${urlT})`;
+    } else if (titleT !== '') {
+        label = titleT;
+    } else if (urlT !== '') {
+        label = urlT;
+    } else if (citeT !== '') {
+        label = `\`${citeT}\``;
+    } else {
+        return '';
+    }
+    if (citeT !== '' && label !== `\`${citeT}\``) {
+        label = `${label} (${citeT})`;
+    }
+    return label;
+}
+
+async function main(): Promise<number> {
+    const { values } = parseArgs({
+        options: {
+            in: { type: 'string' },
+            out: { type: 'string' },
+        },
+    });
+    if (!values.in || !values.out) {
+        console.error('Error: Missing required arguments --in and --out');
+        return 1;
+    }
+    try {
+        const content = parseContent(await readFile(values.in, 'utf-8'));
+        await writeFile(values.out, renderContentMarkdown(content), 'utf-8');
+        return 0;
+    } catch (err: unknown) {
+        console.error(`render-md failed: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+
+if (import.meta.main) {
+    process.exitCode = await main();
+}

package/plugins/kk/skills/{kk-judge → judge}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: kk-judge
-description: This skill should be used when an LLM evaluation gate is needed in a knowledge-kit pipeline — "judge this content", "evaluate against rubric", "quality gate before publish", "check technical accuracy", "review brand tone", "compliance check", or when a spur workflow step of type `agent.run` targets the kk-judge skill to emit a PASS/FAIL/NEEDS_REVISION verdict. Centralizes evaluation rubrics, prompt templates, and structured verdict emission for generated Content.
+name: judge
+description: This skill should be used when an LLM evaluation gate is needed in a knowledge-kit pipeline — "judge this content", "evaluate against rubric", "quality gate before publish", "check technical accuracy", "review brand tone", "compliance check", or when a spur workflow step of type `agent.run` targets the judge skill to emit a PASS/FAIL/NEEDS_REVISION verdict. Centralizes evaluation rubrics, prompt templates, and structured verdict emission for generated Content.
 version: 0.1.0
 ---
 
-# kk-judge — LLM-as-judge evaluation skill
+# judge — LLM-as-judge evaluation skill
 
 ## Purpose
 
@@ -107,7 +107,7 @@ Content to evaluate: {{content_path}}
 Rubric: {{rubric}}              # general | tech-accuracy | brand-tone | compliance
 Output verdict to: {{verdict_path}}
 
-Load the rubric definition from plugins/kk/skills/kk-judge/references/rubrics.md (section: {{rubric}}).
+Load the rubric definition from plugins/kk/skills/judge/references/rubrics.md (section: {{rubric}}).
 Evaluate the content against every criterion in that rubric.
 For each criterion, quote the specific passage and assign pass | fail | warn.
 Decide the verdict: any must-pass fail → FAIL; else score < threshold → NEEDS_REVISION; else PASS.

package/plugins/kk/skills/{kk-judge → judge}/references/rubrics.md

@@ -1,6 +1,6 @@
-# Rubrics — kk-judge evaluation criteria
+# Rubrics — judge evaluation criteria
 
-Loaded by the kk-judge skill at evaluation time. Each rubric defines criteria, weights,
+Loaded by the judge skill at evaluation time. Each rubric defines criteria, weights,
 must-pass flags, and the score thresholds that map to verdicts.
 
 ## Scoring model

package/plugins/kk/skills/{kk-judge → judge}/references/workflow-integration.md

@@ -1,4 +1,4 @@
-# Workflow integration — kk-judge in a spur workflow
+# Workflow integration — judge in a spur workflow
 
 Spur's workflow engine executes one node at a time (`type: parallel` is an inert schema field —
 see `docs/03_ARCHITECTURE.md`). The judge step is therefore a single `agent.run` node followed
@@ -13,10 +13,10 @@ by a `shell` node that guards the transition to `publish`.
     Evaluate the generated content against the {{rubric}} rubric.
     Content: {{content_path}}
     Write the verdict to {{verdict_path}}.
-  skill: kk-judge
+  skill: judge
 ```
 
-- `agent.run` spawns an agent that loads the `kk-judge` skill, performs the evaluation, and writes
+- `agent.run` spawns an agent that loads the `judge` skill, performs the evaluation, and writes
   the verdict JSON to `{{verdict_path}}` (typically `.spur/run/verdict-judge.json`).
 - The verdict file is the only durable artifact. The agent's prose output is not the contract.
 
@@ -28,22 +28,22 @@ The guard runs as a `shell` step after `judge`. It reads the verdict and gates t
 #!/usr/bin/env sh
 verdict_path="{{verdict_path}}"
 if [ ! -f "$verdict_path" ]; then
-  echo "kk-judge: verdict file not found at $verdict_path"
+  echo "judge: verdict file not found at $verdict_path"
   exit 1
 fi
 verdict=$(jq -r '.verdict' "$verdict_path")
 case "$verdict" in
   PASS)
-    echo "kk-judge: PASS"
+    echo "judge: PASS"
     exit 0
     ;;
   FAIL|NEEDS_REVISION)
-    echo "kk-judge: $verdict — see $verdict_path for findings"
+    echo "judge: $verdict — see $verdict_path for findings"
     jq -r '.findings[]? | select(.status=="fail") | "  FAIL: \(.criterion): \(.detail)"' "$verdict_path"
     exit 1
     ;;
   *)
-    echo "kk-judge: unrecognized verdict '$verdict' in $verdict_path"
+    echo "judge: unrecognized verdict '$verdict' in $verdict_path"
     exit 1
     ;;
 esac
@@ -60,7 +60,7 @@ esac
 
 For a bounded regenerate-retry loop, wire the workflow so that a `NEEDS_REVISION` verdict routes
 back to the `generate` step with the verdict's `feedback` as additional input. Cap retries (the
-example workflow uses 2). This is workflow-level orchestration — `kk-judge` itself is stateless
+example workflow uses 2). This is workflow-level orchestration — `judge` itself is stateless
 and re-runnable.
 
 ```

package/plugins/kk/skills/storm-research/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: storm-research
+description: >-
+  Use the storm-research skill to run daily STORM research — turn a research topic
+  sentence or a markdown source file into a grounded STORM Content report with a content.md
+  sidecar ("research X", "produce a research report on X", "run today's STORM research",
+  "turn this brief into a researched report"). The machine is the 0059 workflow
+  (prepare → ingest → generate → render) over the 0056 works layout. Research is separate from
+  authoring: topic owns init→outline→draft and this skill never merges into topic.
+version: 0.1.0
+---
+
+# storm-research — STORM daily research (topic sentence XOR markdown file → content.md)
+
+## Purpose
+
+Turn one research topic (a sentence) or one markdown source file into a **grounded STORM
+`Content` report** plus a `content.md` sidecar by composing the `web-search` ingestion plugin,
+the `content-gen` generator, and the `render-md` helper. The machine is the 0059 workflow
+(`prepare → ingest → generate → render → done|failed`); this skill owns the **craft** — framing
+the query, deciding when to re-run ingest, and verifying the report against the evidence.
+
+Research is **not** authoring. `topic` owns `init → outline → draft` from an approved
+outline; this skill owns evidence gathering. **Do not merge this into `topic`.**
+
+## When to use / not to use
+
+Use when:
+
+- A user asks to research a topic: "research X", "produce a research report on X", "run today's
+  STORM research", "what does the evidence say about X".
+- A user supplies a markdown source (brief, notes, outline) that should ground the report —
+  pass it with `--in <file>`.
+
+Do **not** use for:
+
+- Authoring an article from a topic with no research need — that is `topic`.
+- Quality gating / judging generated content — that is `judge`.
+- Publishing, platform adaptation, or illustration — out of C4 scope.
+- Anything requiring a raw `kk executor run` chain when the workflow already composes it.
+
+## Invocation contract
+
+Same arguments as `/workflow-run` (the thin command delegates here for craft):
+
+```
+[workflow-name] <topic | --in <file>> [--fixture] [--force]
+```
+
+| Token | Meaning | Default |
+| --- | --- | --- |
+| `workflow-name` | installed workflow YAML name; must match `^[a-z0-9][a-z0-9-]*$` and not be `--in` | `kk-storm-research` |
+| `<topic>` | a **specific research question** (better-report a — prefer a question over a noun phrase) | required unless `--in` |
+| `--in <file>` | markdown file mode (XOR with `<topic>`) | — |
+| `--fixture` | force `fixture: "true"` (offline stub ingest) | config default (`false` for real runs) |
+| `--force` | overwrite an existing dest workflow YAML | off |
+
+**XOR rule:** exactly one of `<topic>` / `--in <file>` must be set. Both set or both empty →
+fail loud, no writes. `--in` and a bare topic token are mutually exclusive.
+
+The operator invocation in practice is `/workflow-run <topic>` or `/workflow-run --in <file>`; the
+skill is also callable directly as `Skill(skill="storm-research", args="<topic|--in file> ...")`.
+
+## How to run
+
+1. **Frame the query** (better-report a): prefer a specific question over a noun phrase.
+   "What are the known failure modes of vector databases at 1B rows?" beats "vector databases".
+   A question constrains the search and the report; a noun phrase invites scope creep.
+2. **Choose input**: topic sentence, or a markdown file via `--in` (XOR). File mode derives the
+   query from the first ATX H1 (`/^#\s+(.+)$/m`), else the basename without extension.
+3. **`work_dir` is the resolved topic directory** `$works_dir/<topic-id>`, computed by the
+   invoker (the command or the operator) via the 0056 `topicId()` algorithm — never by the
+   workflow. `prepare` only `mkdir` + materializes files into `${vars.work_dir}`.
+4. **Pick fixture vs live** (see below). Default is live (`fixture: "false"`); pass
+   `fixture: "true"` for offline/dry-run/CI.
+5. **Run** the workflow and collect the outputs: `content.md` (report sidecar), `content.json`
+   (machine contract), `docs.json` (evidence). Read the report against the evidence before
+   presenting it (better-report d).
+
+## topicId algorithm (0056, frozen)
+
+`topicId(raw: string)` — computed by the **invoker**, never by the workflow YAML:
+
+1. `normalized` = trim, collapse whitespace, lowercase.
+2. `slug` = replace `[^a-z0-9]+` with `-`, squeeze dashes, trim dashes, slice to **48 chars**,
+   trim dashes again. If empty → `topic`.
+3. `hash` = `sha256(normalized).digest('hex').slice(0, 8)`.
+4. Return `slug + '-' + hash`.
+
+- Sentence mode: `raw` = the topic string. File mode: `raw` = first ATX H1 else basename
+  without extension.
+- Same `raw` → same id → same workspace. **Last write wins**; do not fail on an existing
+  works dir (re-running a topic is legal — no `--force` needed).
+- If `raw` derives empty (no H1 and an empty basename, e.g. a file named `.md`) → fail loud.
+
+## Works layout (0056, frozen)
+
+Per-topic workspace at `$works_dir/<topic-id>/`:
+
+| File | Written by | Contents |
+| --- | --- | --- |
+| `topic.json` | prepare | ingest `--in` (`topic`, `maxResults`, `fixture`) |
+| `input.md` | prepare (file mode only) | verbatim copy of the operator file |
+| `local-doc.json` | prepare (file mode only) | one-element `Doc[]` (id = `sha256('file://'+absPath).hex.slice(0,16)`, rank `-1`, position `0`) |
+| `docs.json` | ingest | `web-search` output `Doc[]` |
+| `content.json` | generate | STORM `Content` (machine contract) |
+| `content.md` | render | markdown sidecar report |
+
+Contrast: `topic`'s authoring workspace is `./<kebab-case(topic)>` with `brief.md` /
+`2-outline/` / `3-draft/` and explicitly excludes research. C4 works live under `$works_dir`,
+outside any repo.
+
+## Live vs fixture
+
+| Mode | `fixture` | Behavior | Requires |
+| --- | --- | --- | --- |
+| Live | `"false"` (default) | `web-search` calls the Firecrawl search API (`POST https://api.firecrawl.dev/v2/search`, `scrapeOptions.formats: ["markdown"]`), maps `data.web[]` to `Doc[]` | `FIRECRAWL_API_KEY` env var; unset → the ingest exits 1 ("FIRECRAWL_API_KEY is unset") |
+| Fixture | `"true"` | `web-search` emits canned `Doc[]` (stable `sha256(sourceUri)` ids); no network, no key | none — offline/dry-run/CI |
+
+- `FIRECRAWL_API_KEY` is **env-only** — never a config key, never a workflow var, never in the
+  report.
+- Real daily research defaults to live. **`fixture: true` is not research** (better-report b) —
+  the canned docs are for machine checks, not for evidence a reader should trust.
+
+## Fail-loud table (0056 rows the agent must execute)
+
+| Condition | Behavior | Recovery |
+| --- | --- | --- |
+| Both `<topic>` and `--in` set, or neither | exit 1, stderr states the XOR rule; no writes | pass exactly one of `topic` / `--in` |
+| `--in` file unreadable (missing / I/O) | exit 1, stderr names the path | fix the path / permissions |
+| Derived query / topic-id empty (no H1 and empty basename) | exit 1, stderr shows the derived value | add an H1 or give the file a real name |
+| Dest `$workflows_dir/<name>.yaml` exists with different bytes | warning, **no overwrite**; run proceeds with the user's copy | re-run with `--force` to replace from the install source |
+| Workflow YAML cannot be resolved from any install source | exit 1, stderr lists the roots searched | reinstall the package / set `KK_WORKFLOWS_SOURCE` |
+| `KK_CONFIG` set but unreadable, or config unparseable / invalid types | exit 1, stderr names the key + expected vs actual type | fix the file, or delete it (recreated with defaults next run) |
+| Missing config at `KK_CONFIG` | **not a failure** — create-on-first-run with compiled defaults; an existing file is never overwritten | — |
+
+Every failure names the exact path and the exact next command. Never silently skip, never
+auto-replace, never hash topic-id in the YAML.
+
+## Better-report practices (R1)
+
+1. **(a) Prefer a specific question over a noun phrase.** A question ("How does X behave under
+   Y?") pins the search and the report's thesis; a noun ("X") leaves scope open.
+2. **(b) Do not treat `fixture: true` as research.** Fixture output is canned — fine for
+   pipeline checks, never a source of claims to present to a reader.
+3. **(c) Re-run ingest only when the query or sources must change.** If the question is
+   unchanged and the sources are the same, **reuse `docs.json`** — do not re-fetch. Only a new
+   query, new sources, or stale evidence justifies a fresh ingest.
+4. **(d) Read `content.md` citations against `docs.json` ids.** Every citation in the report
+   must resolve to a Doc id present in `docs.json`; verify the claim against that Doc's body
+   before trusting it. A citation to a missing id is a defect — fix the report, not the id list.
+5. **Cap `maxResults` before widening.** Start at the default (`8`); only widen when the first
+   pass demonstrably misses coverage. More results is not better grounding — it is more noise.
+6. **Prefer primary sources in the markdown input file.** When a source file is supplied via
+   `--in`, favor the primary material in it (first-party specs, owned notes, authoritative
+   extracts) as the spine of the report; web results fill gaps, not the reverse.
+
+## Invariants
+
+- The invoker computes `topicId` and passes `work_dir` resolved; the workflow never hashes.
+- XOR input always — exactly one of `topic` / `input_file`.
+- Never promise a judge gate or query expansion in this skill (C4 scope: neither exists).
+- No new `kk` first-layer noun (ADR-011) — this skill runs through the workflow, not through a
+  `kk` CLI verb.
+- `FIRECRAWL_API_KEY` stays env-only.
+- Works layout file names are frozen (0056) — do not rename or add sidecars in this skill.

package/plugins/kk/skills/{kk-topic → topic}/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: kk-topic
+name: topic
 description: >-
-  Use the kk-topic skill to author technical content from a topic or Markdown
+  Use the topic skill to author technical content from a topic or Markdown
   brief — "create an article from this topic", "turn this brief into a draft",
   "generate outline options", "initialize a topic workspace", "resume my draft".
   Runs the topic-core authoring loop (init → outline → draft) through four
@@ -9,7 +9,7 @@ description: >-
   cohesive topic-authoring core, harvested from the WT 7-stage wrappers.
 ---
 
-# kk-topic — topic-core authoring (create | init | outline | draft)
+# topic — topic-core authoring (create | init | outline | draft)
 
 ## Purpose
 
@@ -159,7 +159,7 @@ silently skip, never auto-replace, never delete.
 ## Prompt template (Skill() / agent.run)
 
 ```
-Skill(skill="kk-topic",
+Skill(skill="topic",
   args="<operation> <topic-or-brief> [--dir <target>] [--outline <a|b|c>] [--revise <feedback>] [--force]")
 ```
 

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

@@ -0,0 +1,184 @@
+---
+# STORM topic-research daily workflow (C4):
+#   prepare -> ingest -> generate -> render -> done|failed.
+#
+# State-machine extension of the C3 dry-run prototype. Adds the 0056 XOR
+# prepare + works layout, the generate local-doc merge, and the 0058 render
+# sidecar state. No publish, no judge — by design (C4 scope).
+#
+# 0056 contract (docs/tasks/0056 ... Solution blocks 1-8): `work_dir` is the
+# RESOLVED topic dir (`$works_root/<topic-id>`), computed by the invoker
+# (0060/operator) and passed as `--vars`. prepare only `mkdir` + materializes
+# files into `${vars.work_dir}`; it never hashes the topic-id in YAML. XOR:
+# exactly one of `topic`/`input_file` must be non-empty.
+#
+# 0058 contract (docs/tasks/0058 ... Solution): render shells
+#   bun plugins/kk/scripts/render-md.ts --in <work_dir>/content.json \
+#     --out <work_dir>/content.md
+#
+# Success edges use `guard: { kind: always }` (repo convention — see the C3
+# file and task-pipeline.yaml): a real-run action failure short-circuits at
+# the state under the default onError=fail policy; `always` lets `--dry-run`
+# walk to `done` (actions don't execute in dry-run, so `action-ok` would
+# always deny and fall to `failed`).
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+name: kk-storm-research
+kind: state-machine
+description: >-
+  STORM daily topic research — XOR prepare into 0056 works layout, chain
+  ingest + generate, render content.md sidecar
+initialState: prepare
+terminalStates:
+  - done
+  - failed
+vars:
+  topic: "" # sentence-mode query; ignored when input_file set (XOR)
+  input_file: "" # file-mode markdown path when non-empty (XOR)
+  maxResults: "8" # written into topic.json as int (0054 maxResults)
+  fixture: "false" # "true" selects the stub; CI/dry-run must pass "true"
+  work_dir: "./work" # RESOLVED topic dir ($works_root/<topic-id>)
+  plugins_path: "./plugins" # --plugins-path for kk executor run
+  ingestion_plugin: "web-search"
+  generator_plugin: "content-gen"
+  render_script: "plugins/kk/scripts/render-md.ts" # 0058 shipped runner
+
+states:
+  - id: prepare
+    description: >-
+      mkdir work_dir; XOR guard; sentence mode writes topic.json; file mode
+      copies input.md, writes local-doc.json and topic.json with a derived
+      query
+    onEnter:
+      - 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
+
+  - id: ingest
+    description: >-
+      Run web-search ingestion plugin to produce document list (docs.json)
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            kk executor run "${vars.ingestion_plugin}" --in
+            "${vars.work_dir}/topic.json" --out "${vars.work_dir}/docs.json"
+            --plugins-path "${vars.plugins_path}"
+
+  - id: generate
+    description: >-
+      Prepend local-doc (when present) onto docs.json, then run content
+      generator to produce content.json
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            if [ -f "${vars.work_dir}/local-doc.json" ]; then
+            jq -s '[.[0]] + .[1]' "${vars.work_dir}/local-doc.json"
+            "${vars.work_dir}/docs.json" > "${vars.work_dir}/docs.json.tmp"
+            && mv "${vars.work_dir}/docs.json.tmp" "${vars.work_dir}/docs.json";
+            fi
+      - kind: shell
+        options:
+          command: >-
+            kk executor run "${vars.generator_plugin}" --in
+            "${vars.work_dir}/docs.json" --out "${vars.work_dir}/content.json"
+            --plugins-path "${vars.plugins_path}"
+
+  - id: render
+    description: >-
+      Render content.json to the markdown sidecar content.md via the 0058
+      shipped script
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            bun "${vars.render_script}" --in "${vars.work_dir}/content.json"
+            --out "${vars.work_dir}/content.md"
+
+  - id: done
+    description: >-
+      Terminal — topic materialized, ingested, generated, and rendered to
+      content.md. No publish/judge by design (C4).
+  - id: failed
+    description: Terminal — one of the steps failed
+
+transitions:
+  - from: prepare
+    to: ingest
+    description: Works materialized — proceed to web-search ingestion
+    guard:
+      kind: always
+  - from: prepare
+    to: failed
+    description: >-
+      prepare failed (XOR violation / unreadable input) — terminate workflow
+
+  - from: ingest
+    to: generate
+    description: Ingestion succeeded — proceed to content generation
+    guard:
+      kind: always
+  - from: ingest
+    to: failed
+    description: Ingestion failed — terminate workflow
+
+  - from: generate
+    to: render
+    description: Content generated — render the markdown sidecar
+    guard:
+      kind: always
+  - from: generate
+    to: failed
+    description: Generation failed — terminate workflow
+
+  - from: render
+    to: done
+    description: content.md rendered — workflow complete
+    guard:
+      kind: always
+  - from: render
+    to: failed
+    description: Render failed — terminate workflow