@gobing-ai/knowledge-kit 0.0.12 → 0.0.14

package/plugins/kk/skills/image-authoring/references/providers.md

@@ -0,0 +1,52 @@
+# Provider facts for image generation
+
+The operator-facing digest of 0103's provider inventory. Source of truth:
+`plugins/generations/image-gen/src/providers/types.ts` (the frozen registry) —
+if this file and the registry ever disagree, the registry wins and this file
+gets fixed. Credential *values* live only in
+`plugins.generations.image-gen.env` (`plugins/kk/config.example.yaml`); they
+are read by `invoke.ts` at spawn, never by this skill.
+
+## The rules
+
+- **Readiness is env presence.** A provider is available when its env var(s)
+  are non-empty. A stale key still passes readiness and surfaces as the
+  adapter's own auth error at generate time.
+- **Auto-selection** walks `AUTO_ORDER` — google, openai, replicate,
+  openrouter, dashscope, seedream, zai, minimax, jimeng, azure, agnes — and
+  takes the first available. `IMAGE_GEN_PROVIDER` names a provider explicitly;
+  `--provider` outranks it.
+- **`codex-cli` is never auto-selected.** Its readiness (the `codex` CLI on
+  PATH with an active login) is not env-expressible; pin it explicitly.
+- **Reference images** ride `--ref` only when `supportsReferenceImages(model)`
+  is true for the resolved model — a substring test over the registry's
+  `refModels` fragments (no `refModels` = every model; empty list = none).
+  When it is false, say so and offer `extract-style`; never drop the
+  reference silently.
+
+## The inventory
+
+| Provider | Env var(s) that enable it | Default model | Reference images |
+| --- | --- | --- | --- |
+| agnes | `AGNES_API_KEY` | `agnes-image-2.1-flash` | yes |
+| azure | `AZURE_OPENAI_API_KEY` (+ `AZURE_OPENAI_BASE_URL`, `AZURE_OPENAI_DEPLOYMENT` to run) | `gpt-image-2` | yes (no `refModels` declared → every model passes `supportsReferenceImages`) |
+| codex-cli | not env-expressible — `codex` CLI + login | `codex-image-gen` | never auto-selected |
+| dashscope | `DASHSCOPE_API_KEY` | `qwen-image-2.0-pro` | only `wan2.7` models |
+| google | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `gemini-3-pro-image` | the gemini image models (`gemini-3-pro-image`, `*-flash-image`, previews) |
+| jimeng | `JIMENG_ACCESS_KEY_ID` **and** `JIMENG_SECRET_ACCESS_KEY` (both halves) | `jimeng_t2i_v40` | yes |
+| minimax | `MINIMAX_API_KEY` | `image-01` | yes (jpg/png <10MB, subject reference) |
+| openai | `OPENAI_API_KEY` | `gpt-image-2` | `gpt-image` models |
+| openrouter | `OPENROUTER_API_KEY` | `google/gemini-3.1-flash-image` | yes (no `refModels` declared → treated as supporting; real capability depends on the routed model) |
+| replicate | `REPLICATE_API_TOKEN` | `google/nano-banana-2` | yes |
+| seedream | `ARK_API_KEY` (not `SEEDREAM_*`) | `doubao-seedream-5-0-260128` | `doubao-seedream-5-0` / `4-5-` / `4-0-` models |
+| zai | `ZAI_API_KEY` or `BIGMODEL_API_KEY` | `glm-image` | **none** |
+
+## Deciding with references in hand
+
+1. Resolve the provider per Preference chain (argument → `IMAGE_GEN_PROVIDER`
+   → config → `AUTO_ORDER`).
+2. Check `supportsReferenceImages` for the resolved model. False → the
+   pass-through path is unavailable: state it and offer style extraction
+   (0105), which works with every provider.
+3. Name the chosen provider and model in the spend preview — the operator
+   approves the pair, not just the prompt.

package/plugins/kk/skills/image-authoring/references/style-extraction.md

@@ -0,0 +1,139 @@
+# Style extraction from reference images
+
+Loaded by the image-authoring skill when the operator hands over one or more
+reference images and wants the look captured as a reusable style preset.
+Extraction is a **skill operation** — the running agent reads the image(s) with
+its own vision and writes a YAML file. No plugin code, no vision API call, no
+provider credential is involved.
+
+There are two mechanisms for using a reference image, and this file owns the
+boundary between them:
+
+| baoyu usage | kk mechanism | What happens |
+| --- | --- | --- |
+| `direct` | pass-through | The file rides `ImageJobSpec.referenceImages` (0104) to a provider whose `supportsReferenceImages(model)` is true (0103). Highest fidelity; produces one image, nothing reusable. |
+| `style` | extraction (this file) | The look is analysed and written as a `styles/<name>.yaml`. Works with every provider; reusable and editable. |
+| `palette` | extraction, partial | Same procedure, but only `palette`, `name` and `description` are filled; `modifiers` stays a one-line summary. |
+
+## Where the preset goes
+
+Write to the **user root**: `~/.config/kk/image-presets/styles/<name>.yaml`. A cloned
+look is usually the operator's, not the repository's. An operator who wants the
+preset shared with a team writes to the project root
+(`<KNOWLEDGE_KIT_PROJECT_ROOT>/.kk/image-presets/styles/`) instead — it ranks
+higher in the loader chain. No registration step exists or is needed: the
+loader discovers presets by scanning these directories (0102). If the chosen
+name matches a shipped preset, the new file **shadows** it whole-file and the
+loader emits a `shadowed` diagnostic naming both paths — that is the intended
+way to adjust a shipped style, not an accident.
+
+## Input rules
+
+- **One to five reference images.** Count them before reading anything.
+- **Cap refusal (exact wording):** if the operator supplies more than 5, refuse
+  before reading any of them:
+  `Refusing extraction: <N> reference images requested; the cap is 5. Split the set into coherent groups, or drop the least representative references and re-run.`
+  The cap is a constant, not a design commitment; changing it means changing
+  this number and this message only.
+
+## Output rules — the schema is frozen
+
+Emit **YAML only** — no prose, no code fence. The document fills **exactly**
+the `StylePreset` fields of `plugins/generations/image-gen/src/presets.ts` and
+nothing else. **Inventing a field outside this list is a defect, not an
+enhancement.** Field-by-field:
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `name` | yes | kebab-case, derived from the look, never from the filename. |
+| `description` | yes | One or two sentences naming the look and where it works. |
+| `modifiers` | yes | A comma-separated prompt fragment in the same voice as the shipped styles under `plugins/generations/image-gen/presets/styles/` — `composePrompt` concatenates it as segment 3 of a comma-joined prompt. Read two shipped styles before writing one; a style in the wrong voice produces a prompt in two voices. |
+| `palette` | no | 3–6 entries of `{role, name, hex}`. `role` from `{primary, secondary, accent, background, text}`. `hex` uppercase `#RRGGBB`, sampled from the image, never invented. (A merged set may legitimately keep fewer than 3 — only colours common to every reference survive; see merge rules.) |
+| `typography` | no | Only when the image evidences it. Omit rather than guess. |
+| `visualElements` | no | Array of strings naming recurring visual devices (borders, banding, grain, iconography). Only what the image shows. |
+| `bestFor` | no | The content types this look suits. Inferred from the image's own subject matter. |
+| `negative` | no | What this look must avoid — inferred from what is conspicuously absent. |
+| `source` | yes for extraction | `kind: extracted`, `refImages` = the absolute input paths **in the order given**, `extractedAt` = ISO-8601 timestamp, `confidence` = the judgement below. |
+
+### The `confidence` decision rule (human-judged, not computed)
+
+- `high` — a single clean image with an obvious, consistent look.
+- `medium` — mixed or noisy references, or a merged set where the references
+  disagree on any of the four fidelity axes.
+- `low` — the look is ambiguous, or the image is photographic content rather
+  than a designed style (a photo *of* something is not a style).
+
+## Multi-image merge rules
+
+With N references (1 ≤ N ≤ 5) the output is **one merged preset**, not N
+presets and not an average:
+
+- `palette` — colours **common to the set**. A colour appearing in one image
+  only is dropped, not averaged into a muddy midpoint.
+- `modifiers` — traits present in **every** image. Divergent traits are
+  dropped, and each discarded trait is **named in the extraction report** so
+  the operator sees exactly what was thrown away.
+- `confidence` — capped at `medium` when the set disagrees on any fidelity axis.
+- `source.refImages` — all N absolute paths, in the order given.
+
+## What extraction writes
+
+**Style by default; format drafting is opt-in.** A `FormatPreset` carries `template`,
+`variables`, `keywords`, `defaultStyle`, `outputFilename` — none of which is
+*recoverable* from a picture, so extraction alone never writes a `formats/*.yaml`.
+What an image *does* yield is arithmetic: the extraction report **states the observed
+pixel dimensions and the nearest named aspect ratio** of each reference, chosen from
+`21:9`, `4:3`, `1:1`, `16:9`, `3:4`, `9:16`.
+
+When the operator passes `--emit-format <name> --job <job>` alongside `--extract-style`,
+that arithmetic plus the same visual analysis feeds a **draft** format preset — measured
+fields taken, visual defaults authored, structural fields reused from the shipped
+skeleton, operator fine-tuning expected. That procedure lives in
+[format-drafting.md](format-drafting.md); this file stays style-only.
+
+## Pass-through degradation (visible, never silent)
+
+When the operator wants `direct` (pass-through) and the selected provider's
+`supportsReferenceImages(model)` returns `false`, the skill must state it in
+these terms and offer the alternative:
+
+`Provider <name> cannot accept reference images for model <model> (supportsReferenceImages: false). Pass-through is unavailable; offering style extraction instead.`
+
+**Never silently proceed without the reference.** A plausible image generated
+from a dropped reference is the worst outcome available — worse than an error.
+
+## Validate after writing
+
+After writing the YAML, run the dry run: `KK_IMAGE_DRY_RUN=1` `image-gen`
+(0104) with a job whose `style` is the new preset's name. A malformed or
+unloadable file fails there loudly, naming the file and the schema violation,
+before any provider spend. No validator is written; 0102's loader and the dry
+run already are one.
+
+## Fidelity check (v1 method: human eyeball)
+
+To answer "did the clone work": extract from reference **I**, regenerate with
+the extracted preset using a prompt describing **I's own subject** (so subject
+variance does not contaminate the comparison), then compare **I** and the
+regeneration on exactly four axes — **palette, rendering technique,
+composition density, typographic treatment**. The v1 comparison method is a
+human eyeballing the pair; no metric is computed. Record the verdict in the
+preset's `source.confidence`; if the fidelity verdict disagrees with the
+extraction-side judgement, take the lower.
+
+## Worked output shape
+
+```yaml
+name: example-look
+description: Flat colour-band composition with deep teal over warm cream.
+modifiers: flat colour-band composition, deep teal and warm cream palette, hard edges, no gradients, minimal detail
+palette:
+    - { role: primary, name: deep teal, hex: '#1D5C63' }
+    - { role: background, name: warm cream, hex: '#F5EFE0' }
+source:
+    kind: extracted
+    refImages:
+        - /absolute/path/to/reference.png
+    extractedAt: '2026-09-09T18:00:00Z'
+    confidence: high
+```

package/plugins/kk/workflows/kk-daily-ai-voice.yaml

@@ -19,6 +19,7 @@ vars:
   limit: "10"
   language: "zh"
   voice_profile: "robin-news"
+  voice_generator: "voice-gen"
   title: ""
   cursor: ""
   state_file: ""
@@ -54,6 +55,7 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"prepare\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             test -n "${vars.work_dir}" || { echo "missing required variable: work_dir" >&2 && exit 1; };
             mkdir -p "${vars.work_dir}/1-ingest" "${vars.work_dir}/2-facts" "${vars.work_dir}/2-plan" "${vars.work_dir}/2-article" "${vars.work_dir}/2-cover" "${vars.work_dir}/2-script" "${vars.work_dir}/3-audio" "${vars.work_dir}/3-publish";
             date +%Y%m%d > "${vars.work_dir}/run-date.txt" &&
@@ -75,11 +77,13 @@ states:
           # fan-in 30m per-source default and making empty episodes stochastic — horizon gets a
           # 45m leash; aihot/last30days keep the default.
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"collect\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             if [ -f "${vars.work_dir}/1-ingest/blended.json" ]; then echo "collect cached: ${vars.work_dir}/1-ingest/blended.json"; exit 0; fi;
             kk executor fan-in --source "aihot-ingest:${vars.work_dir}/1-ingest/source.json" --source "last30days-ingest:${vars.work_dir}/1-ingest/last30days.json" --source "horizon-ingest:${vars.work_dir}/1-ingest/horizon.json" --source-timeout-override "horizon-ingest:2700000" --out "${vars.work_dir}/1-ingest/blended.json"
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"collect\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             set --;
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             if [ -f "${vars.work_dir}/2-facts/content.json" ] && [ -f "${vars.work_dir}/2-facts/core-facts.md" ]; then echo "core facts cached: ${vars.work_dir}/2-facts/core-facts.md"; exit 0; fi;
@@ -92,6 +96,7 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"plan\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             set --;
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             PLAN_CONTENT="${vars.work_dir}/2-plan/content.json"; PLAN_DOCS="${vars.work_dir}/2-plan/plan.json";
@@ -106,6 +111,7 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"quality-control-content\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             set --;
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             if [ -f "${vars.work_dir}/2-plan/candidates.json" ]; then echo "candidates cached: ${vars.work_dir}/2-plan/candidates.json"; exit 0; fi;
@@ -136,23 +142,30 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"article\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             set --;
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             CONTENT_OUT="${vars.work_dir}/2-article/content-${vars.run_date}.json"; ARTICLE_MD="${vars.work_dir}/2-article/article-${vars.run_date}.md";
             if [ -f "$ARTICLE_MD" ]; then echo "article cached: $ARTICLE_MD"; else PLAN_IN="${vars.work_dir}/2-plan/plan.json"; PLAN_OK=1; bun -e 'try { JSON.parse(await Bun.file(process.argv[1]).text()); process.exit(0); } catch (e) { console.warn("article: plan.json invalid JSON — replacing with untranslated plan (downstream states read this file): " + e.message); const docs = JSON.parse(await Bun.file(process.argv[2]).text()).metadata?.docs; if (!Array.isArray(docs) || docs.length === 0) { console.error("article: candidates.json metadata.docs missing"); process.exit(2); } await Bun.write(process.argv[1], JSON.stringify(docs, null, 2)); process.exit(1); }' "$PLAN_IN" "${vars.work_dir}/2-plan/candidates.json"; case $? in 0|1) PLAN_OK=0;; esac; test "$PLAN_OK" -eq 0 || { echo "article: no usable plan input"; exit 1; }; ARTICLE_DATE="${vars.run_date}" kk executor run daily-article-gen --in "$PLAN_IN" --out "$CONTENT_OUT" "$@" && bun -e 'await Bun.write(process.argv[2], (await Bun.file(process.argv[1]).json()).body)' "$CONTENT_OUT" "$ARTICLE_MD"; fi
 
   - id: cover
-    description: "Generate the article cover image via the wt-image-cover skill (agent.run)"
+    description: "Generate the article cover image via the kk:image-authoring skill (agent.run)"
     onEnter:
       - kind: agent.run
         options:
           role: scribe
           agent: ${vars.agent}
           input: |
-            Invoke the wt-image-cover skill.
-            Generate a 21:9 cover image for the article at ${vars.work_dir}/2-article/article-${vars.run_date}.md and save it to ${vars.work_dir}/2-cover/cover-${vars.run_date}.png.
-            Use style "news". If no image-generation backend is available, a procedurally rendered cover (e.g. PIL: news palette, headline typography) is an acceptable, expected deliverable — not a fake; generate it and write the file. Do not wait for operator confirmation.
-          expectFile: ${vars.work_dir}/2-cover/cover-${vars.run_date}.png
+            Invoke the kk:image-authoring skill (generate operation).
+            This node is a non-interactive workflow step: run every image command with KK_NONINTERACTIVE=1 and KK_IMAGE_AUTO_CONFIRM=1 in the environment (this workflow approves the image spend via cover_enabled) — never prompt, never open a question.
+            Command: --format cover --content ${vars.work_dir}/2-article/article-${vars.run_date}.md --out ${vars.work_dir}/2-cover
+            Derive the cover template variables (title, subtitle, topics) from the article as the skill owns; style is the format's default — do not pass --style.
+            The plugin writes ${vars.work_dir}/2-cover/content.json plus the artifact ${vars.work_dir}/2-cover/content-cover-01.<ext>, where <ext> follows the elected provider's native output (payload honesty: minimax returns JPEG, google/ark return PNG). If generation fails, report the error verbatim and stop — no procedural fallback.
+            Run 20260911 context: only MINIMAX_API_KEY is credentialed (ARK out of token, google key unset), so the elected provider is minimax and the artifact lands as content-cover-01.jpg.
+          expectFile: ${vars.work_dir}/2-cover/content-cover-01.jpg
+      - kind: shell
+        options:
+          command: 'cd "${vars.work_dir}/2-cover" && src="content-cover-01.png"; test -f "$src" || src="content-cover-01.jpg"; test -f "$src" || { echo "cover normalize: no content-cover-01.{png,jpg} artifact" >&2; exit 1; }; case "$src" in *.jpg) command -v sips >/dev/null 2>&1 || { echo "cover normalize: sips not found; cannot transcode jpg -> png" >&2; exit 1; }; sips -s format png "$src" --out "cover-${vars.run_date}.png" >/dev/null;; *) mv "$src" "cover-${vars.run_date}.png";; esac; rm -f content-cover-01.jpg content-cover-01.png; echo "cover normalized: cover-${vars.run_date}.png"'
 
   - id: script
     description: "Compile the episode plan Doc[] into structured broadcast VoiceScript YAML Content"
@@ -160,6 +173,7 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"script\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             set --;
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             SCRIPT_CONTENT_OUT="${vars.work_dir}/2-script/content-${vars.run_date}.json"; VOICESCRIPT_YAML="${vars.work_dir}/2-script/voicescript-${vars.run_date}.yaml";
@@ -180,18 +194,20 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"wrap-docs\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             bun -e 'const scriptUrl = new URL(process.argv[1], "file://" + process.cwd() + "/"); const scriptPath = decodeURIComponent(scriptUrl.pathname); const doc = { id: new Bun.CryptoHasher("sha256").update(scriptUrl.href).digest("hex").slice(0, 16), title: "Daily AI News VoiceScript", sourceUri: scriptUrl.href, body: await Bun.file(scriptPath).text(), mediaType: "application/yaml", metadata: { voiceProfile: process.argv[3] || process.env.VOICEBOX_DEFAULT_PROFILE || "robin-news" } }; await Bun.write(process.argv[2], JSON.stringify([doc], null, 2))' "${vars.work_dir}/2-script/voicescript-${vars.run_date}.yaml" "${vars.work_dir}/3-audio/docs.json" "${vars.voice_profile}"
 
   - id: generate
-    description: "Invoke voice-gen generator plugin to generate audio"
+    description: "Invoke voice generator plugin (voice_generator var) to generate audio"
     onEnter:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"generate\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             set --;
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             if [ -f "${vars.work_dir}/3-audio/content.json" ] && jq -e '.metadata.qc.passed == true' "${vars.work_dir}/3-audio/content.json" > /dev/null 2>&1; then echo "audio cached: ${vars.work_dir}/3-audio/content.json (QC passed)"; exit 0; fi;
-            VOICE_GEN_MP3="${vars.transcode_mp3}" kk executor run voice-gen --in "${vars.work_dir}/3-audio/docs.json" --out "${vars.work_dir}/3-audio/content.json" "$@"
+            VOICE_GEN_MP3="${vars.transcode_mp3}" kk executor run ${vars.voice_generator} --in "${vars.work_dir}/3-audio/docs.json" --out "${vars.work_dir}/3-audio/content.json" "$@"
 
   - id: quality-control
     description: "Verify audio quality, speech rate, and silence/repetition QC metrics"
@@ -199,63 +215,117 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"quality-control\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             bun -e 'const content = JSON.parse(await Bun.file(process.argv[1]).text()); const qc = content.metadata?.qc; console.log("=== Voice Quality Control Report ==="); console.log("Overall Score: " + (qc ? qc.overallScore : 100) + "/100 | Passed: " + (qc ? qc.passed : true)); if (qc && qc.criticalIssues && qc.criticalIssues.length) { console.warn("QC Issues:\n" + qc.criticalIssues.map(function(i) { return "  - " + i; }).join("\n")); } else { console.log("All audio segments passed quality control checks cleanly."); }' "${vars.work_dir}/3-audio/content.json"
 
+  - id: publish-prep
+    description: "Merge article Content with audio (podcast assembly facts ride the content options channel for podcast-pub's absorbed assembly; runDate kept for surfdash slug)"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"publish-prep\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
+            bun -e 'const article = JSON.parse(await Bun.file(process.argv[1]).text()); const audio = JSON.parse(await Bun.file(process.argv[2]).text()); const audioMeta = audio.metadata ?? {}; const rawFile = audioMeta.mp3Path ?? audioMeta.audioPath; if (!rawFile) { console.error("publish-prep: voice content carries no mp3Path/audioPath"); process.exit(1); } const { resolve } = await import("node:path"); const { existsSync } = await import("node:fs"); const audioFile = resolve(rawFile); const coverPath = resolve(process.argv[4]); const merged = { ...article, metadata: { ...(article.metadata ?? {}), audioFile, runDate: process.argv[5] }, options: { audioFile, durationSec: audioMeta.duration, coverPath: existsSync(coverPath) ? coverPath : undefined } }; await Bun.write(process.argv[3], JSON.stringify(merged, null, 2))' "${vars.work_dir}/2-article/content-${vars.run_date}.json" "${vars.work_dir}/3-audio/content.json" "${vars.work_dir}/3-publish/content.json" "${vars.work_dir}/2-cover/cover-${vars.run_date}.png" "${vars.run_date}"
+
+  - id: publish-surfdash
+    description: "Publish the merged Content to surfdash (single target); result lands in result.json — surfdash publishes first so show-notes can link the article (task 0118 seam reorder)"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"publish-surfdash\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            RESULT="${vars.work_dir}/3-publish/result-surfdash.json";
+            if jq -e '.targets[]? | select(.target == "surfdash-pub" and .ok == true and .status == "published")' "$RESULT" > /dev/null 2>&1; then echo "publish-surfdash cached: surfdash target ok in $RESULT"; exit 0; fi;
+            env -u SPUR_WORKFLOW_RUN_ACTIVE kk executor fan-out --content "${vars.work_dir}/3-publish/content.json" --target surfdash-pub --out "$RESULT" "$@" || true;
+            echo "publish-surfdash: surfdash target dispatched; classification happens after podcast publish"
+
   - id: show-notes
-    description: "Render uniform show notes from the episode plan (podcast-pub show-notes operation; PODCAST_PUB_TITLE carries the effective title vars.title || article.title)"
+    description: "Render timeline show notes from the episode plan (podcast-pub show-notes op, briefMode; article URL from the surfdash result postPath — surfdash failure degrades to legacy full-body layout)"
     onEnter:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"show-notes\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             set --;
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
             TITLE_ARG="${vars.title}";
             EFFECTIVE_TITLE="$(jq -r '.title // ""' "${vars.work_dir}/2-article/content-${vars.run_date}.json")";
             if [ -z "$TITLE_ARG" ]; then TITLE_ARG="$EFFECTIVE_TITLE"; fi;
-            PODCAST_PUB_TITLE="$TITLE_ARG" PODCAST_PUB_RUN_DATE="${vars.run_date}" kk executor run podcast-pub --in "${vars.work_dir}/2-plan/plan.json" --out "${vars.work_dir}/3-publish/show-notes.md" "$@"
+            RESULT="${vars.work_dir}/3-publish/result.json";
+            POST_PATH="$(jq -r '[(.targets // [])[] | select(.target == "surfdash-pub" and .ok == true) | .metadata.postPath // empty] | first // ""' "$RESULT" 2>/dev/null || true)";
+            PODCAST_PUB_TITLE="$TITLE_ARG" PODCAST_PUB_RUN_DATE="${vars.run_date}" PODCAST_PUB_BRIEF_MODE=true PODCAST_PUB_ARTICLE_POST_PATH="$POST_PATH" kk executor run podcast-pub --in "${vars.work_dir}/2-plan/plan.json" --out "${vars.work_dir}/3-publish/show-notes.md" "$@"
 
-  - id: publish-prep
-    description: "Merge article Content with audio (podcast assembly facts ride the content options channel for podcast-pub's absorbed assembly; runDate kept for surfdash slug)"
+  - id: publish-podcast
+    description: "Publish the episode to podcast-pub with the rendered show notes (metadata.showNotes carries the brief/timeline markdown; map.ts falls back to content.body when absent — task 0118 R3)"
     onEnter:
       - kind: shell
         options:
           command: >-
-            bun -e 'const article = JSON.parse(await Bun.file(process.argv[1]).text()); const audio = JSON.parse(await Bun.file(process.argv[2]).text()); const audioMeta = audio.metadata ?? {}; const rawFile = audioMeta.mp3Path ?? audioMeta.audioPath; if (!rawFile) { console.error("publish-prep: voice content carries no mp3Path/audioPath"); process.exit(1); } const { resolve } = await import("node:path"); const { existsSync } = await import("node:fs"); const audioFile = resolve(rawFile); const coverPath = resolve(process.argv[4]); const merged = { ...article, metadata: { ...(article.metadata ?? {}), audioFile, runDate: process.argv[5] }, options: { audioFile, durationSec: audioMeta.duration, coverPath: existsSync(coverPath) ? coverPath : undefined } }; await Bun.write(process.argv[3], JSON.stringify(merged, null, 2))' "${vars.work_dir}/2-article/content-${vars.run_date}.json" "${vars.work_dir}/3-audio/content.json" "${vars.work_dir}/3-publish/content.json" "${vars.work_dir}/2-cover/cover-${vars.run_date}.png" "${vars.run_date}"
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"publish-podcast\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            RESULT="${vars.work_dir}/3-publish/result-podcast.json";
+            if jq -e '.targets[]? | select(.target == "podcast-pub" and .ok == true and .status == "published")' "$RESULT" > /dev/null 2>&1; then echo "publish-podcast cached: podcast target ok in $RESULT"; exit 0; fi;
+            bun -e 'const content = JSON.parse(await Bun.file(process.argv[1]).text()); const notes = await Bun.file(process.argv[2]).text(); content.metadata = { ...(content.metadata ?? {}), showNotes: notes }; await Bun.write(process.argv[1], JSON.stringify(content, null, 2))' "${vars.work_dir}/3-publish/content.json" "${vars.work_dir}/3-publish/show-notes.md" &&
+            env -u SPUR_WORKFLOW_RUN_ACTIVE kk executor fan-out --content "${vars.work_dir}/3-publish/content.json" --target podcast-pub --out "$RESULT" "$@" || true;
+            echo "publish-podcast: podcast target dispatched"
 
   - id: publish
-    description: "Fan out the merged Content to surfdash-pub and podcast-pub; classify the outcome full|partial|none into publish-status.txt (exit 0 in all three — routing is transition-owned)"
+    description: "Classify the sequenced surfdash → podcast outcomes full|partial|none into publish-status.txt (exit 0 in all three — routing is transition-owned; task 0118: per-target classification over the merged result.json)"
     onEnter:
       - kind: shell
         options:
           command: >-
-            set --;
-            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"publish\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             RESULT="${vars.work_dir}/3-publish/result.json"; STATUS_FILE="${vars.work_dir}/3-publish/publish-status.txt";
-            if jq -e '.ok == true and ([.targets[]? | select(.ok == true and .status == "published")] | length) == 2' "$RESULT" > /dev/null 2>&1; then echo "publish cached: $RESULT (2 targets ok)"; printf 'full' > "$STATUS_FILE"; exit 0; fi;
-            OK_COUNT=0; TOTAL=0; STATUS="none";
-            env -u SPUR_WORKFLOW_RUN_ACTIVE kk executor fan-out --content "${vars.work_dir}/3-publish/content.json" --target surfdash-pub --target podcast-pub --out "$RESULT" "$@" || true;
-            if [ -f "$RESULT" ]; then OK_COUNT="$(jq '[.targets[]? | select(.ok == true and .status == "published")] | length' "$RESULT")"; TOTAL="$(jq '[.targets[]?] | length' "$RESULT")"; if [ "$OK_COUNT" -gt 0 ] && [ "$OK_COUNT" -eq "$TOTAL" ]; then STATUS="full"; elif [ "$OK_COUNT" -gt 0 ]; then STATUS="partial"; fi; else echo "publish: fan-out wrote no result.json — routing to none" >&2; fi;
+            TARGETS="$(jq -s '[(.[0].targets // []), (.[1].targets // [])] | add' "${vars.work_dir}/3-publish/result-surfdash.json" "${vars.work_dir}/3-publish/result-podcast.json" 2>/dev/null || echo '[]')";
+            OK_COUNT="$(printf '%s' "$TARGETS" | jq '[.[]? | select(.ok == true and .status == "published")] | length')";
+            TOTAL="$(printf '%s' "$TARGETS" | jq 'length')";
+            if [ "$OK_COUNT" -gt 0 ] && [ "$OK_COUNT" -eq "$TOTAL" ]; then STATUS="full"; elif [ "$OK_COUNT" -gt 0 ]; then STATUS="partial"; else STATUS="none"; fi;
+            jq -n --argjson targets "$TARGETS" --argjson ok "$OK_COUNT" --argjson total "$TOTAL" '{ok: ($ok == $total and $total > 0), targets: $targets}' > "$RESULT";
             printf '%s' "$STATUS" > "$STATUS_FILE";
             echo "publish: status=$STATUS ($OK_COUNT/$TOTAL targets published); routing is transition-owned"
 
   - id: publish-partial
-    description: "Partial publish — at least one target published, at least one failed; echo warning, write a .spur/run marker, preserve result.json for --retry-from, continue to done"
+    description: "Partial publish — at least one target published, at least one failed; echo warning, write a .spur/run marker, preserve result.json for --retry-from, continue to done (task 0118: surfdash failure = no-URL fallback notes; podcast failure = its own partial)"
     onEnter:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"publish-partial\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             FAILED="$(jq -r '[.targets[]? | select(.ok != true or .status != "published") | .target] | join(",")' "${vars.work_dir}/3-publish/result.json")";
             if [ -z "$FAILED" ]; then FAILED="(unparsed)"; fi;
             echo "WARNING: partial publish — failed targets: $FAILED" >&2;
             mkdir -p .spur/run &&
             printf '%s partial publish: failed targets: %s (result.json preserved for kk executor fan-out --retry-from)\n' "${vars.run_date}" "$FAILED" > ".spur/run/publish-partial-${vars.run_date}.txt"
 
+  - id: run-report
+    description: "Assemble the per-run report (scores+aggregates+rejected counts+step timing) from existing artifacts — news-report-gen; output-only, never throws; 0117"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"run-report\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
+            REPORT_MD="${vars.work_dir}/run-report-${vars.run_date}.md";
+            if [ -f "$REPORT_MD" ]; then echo "run report cached: $REPORT_MD"; exit 0; fi;
+            CANDS="${vars.work_dir}/2-plan/episode-plan.json";
+            test -f "${vars.work_dir}/2-plan/candidates.json" || { echo "run-report: no candidates.json (run ended below plan step) — skip"; exit 0; };
+            jq '.metadata.docs // []' "${vars.work_dir}/2-plan/candidates.json" > "$CANDS";
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            QC_MIN_QUALITY="${vars.qc_min_quality}" QC_MIN_IMPORTANCE="${vars.qc_min_importance}" QC_MIN_URGENCY="${vars.qc_min_urgency}" QC_MIN_IMPACT="${vars.qc_min_impact}" NEWS_REPORT_REJECTED_FILE="${vars.work_dir}/2-plan/candidates.rejected.json" NEWS_REPORT_TIMING_FILE="${vars.work_dir}/step-timing.json" NEWS_REPORT_DATE="${vars.run_date}" kk executor run news-report-gen --in "$CANDS" --out "${vars.work_dir}/run-report.json" "$@" &&
+            bun -e 'await Bun.write(process.argv[2], (await Bun.file(process.argv[1]).json()).body)' "${vars.work_dir}/run-report.json" "$REPORT_MD" &&
+            echo "run report written: $REPORT_MD"
+
   - id: translate-en
     description: "Scaffold en draft from the zh article via surfdash-pub scaffold-locale (postPath from publish result; done-no-content/none-publish runs carry no zh path and skip)"
     onEnter:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"translate-en\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             RESULT="${vars.work_dir}/3-publish/result.json";
             ZH="$(jq -r '[(.targets // [])[] | select(.target == "surfdash-pub" and .ok == true) | .metadata.postPath // empty] | first // ""' "$RESULT")";
             case "$ZH" in *index.md) ;; *) ZH="";; esac;
@@ -298,6 +368,7 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"translate-ja\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             ZH="$(cat "${vars.work_dir}/3-publish/zh-post-path.txt" 2>/dev/null || printf '')";
             JA="$(printf '%s' "$ZH" | sed 's|/zh/|/ja/|')";
             printf '%s' "$JA" > "${vars.work_dir}/3-publish/ja-post-path.txt";
@@ -334,6 +405,7 @@ states:
       - kind: shell
         options:
           command: >-
+            __STAMP_T0="$(date -u +%FT%TZ)"; trap '[ -n "${vars.work_dir}" ] && printf "{\"step\":\"translate-sync\",\"startedAt\":\"%s\",\"endedAt\":\"%s\"}\n" "$__STAMP_T0" "$(date -u +%FT%TZ)" >> "${vars.work_dir}/step-timing.json"' EXIT;
             test -n "${vars.surfdash_post_path}" || { echo "no zh post path — skip translate-sync"; exit 0; };
             set --;
             if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
@@ -461,8 +533,8 @@ transitions:
       kind: always
 
   - from: quality-control
-    to: show-notes
-    description: "publish enabled AND QC passed -> render show notes, then publish"
+    to: publish-prep
+    description: "publish enabled AND QC passed -> merge article + audio for the publish seam"
     guard:
       kind: shell
       options:
@@ -482,21 +554,33 @@ transitions:
     guard:
       kind: always
 
+  - from: publish-prep
+    to: publish-surfdash
+    description: "Merged content ready -> surfdash publishes first (task 0118 seam reorder: article URLs must exist before show-notes render)"
+    guard:
+      kind: always
+
+  - from: publish-surfdash
+    to: show-notes
+    description: "Surfdash dispatched (ok or failed — failure degrades to no-URL notes) -> render timeline show notes"
+    guard:
+      kind: always
+
   - from: show-notes
-    to: publish-prep
-    description: "Show notes rendered -> merge article + audio for the publish seam"
+    to: publish-podcast
+    description: "Show notes rendered (briefMode timeline or legacy fallback) -> podcast publish carries them via metadata.showNotes"
     guard:
       kind: always
 
-  - from: publish-prep
+  - from: publish-podcast
     to: publish
-    description: "Merged content ready -> fan out to surfdash-pub + podcast-pub"
+    description: "Podcast dispatched -> classify the per-target outcomes full|partial|none"
     guard:
       kind: always
 
   - from: publish
-    to: translate-en
-    description: "Publish full (all targets published) -> scaffold + translate en locale"
+    to: run-report
+    description: "Publish full (all targets published) -> assemble run report first"
     guard:
       kind: shell
       options:
@@ -519,11 +603,27 @@ transitions:
         command: 'test "$(cat "${vars.work_dir}/3-publish/publish-status.txt")" = "none"'
 
   - from: publish-partial
-    to: done
-    description: "Partial publish recorded (warning + .spur/run marker) -> done; retry failed targets later via kk executor fan-out --retry-from"
+    to: run-report
+    description: "Partial publish recorded (warning + .spur/run marker) -> still assemble the run report"
     guard:
       kind: always
 
+  - from: run-report
+    to: translate-en
+    description: "Run report assembled after full publish -> scaffold + translate en locale"
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat "${vars.work_dir}/3-publish/publish-status.txt")" = "full"'
+
+  - from: run-report
+    to: done
+    description: "Run report assembled after partial publish -> done; retry failed targets later via kk executor fan-out --retry-from"
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat "${vars.work_dir}/3-publish/publish-status.txt")" = "partial"'
+
   - from: translate-en
     to: translate-en-agent
     description: "zh post published and en draft scaffolded -> agent translates en draft in place"