@gobing-ai/knowledge-kit 0.0.7 → 0.0.9

package/plugins/kk/skills/itc-generating/references/platform-english.md

@@ -0,0 +1,72 @@
+# English-platform playbook (X / Medium / Substack)
+
+Distilled from the STORM study "How to Write and Distribute IT Technical Documents on English
+Platforms" (works dir `how-to-write-it-technical-documents-for-english-a6a76477`, provenance only).
+Load this reference when `--playbook english`; it shapes platform choice, format, and distribution
+for the draft — never reimplements publishing.
+
+## Choose the platform before you write
+
+- The writer's-first-question fallacy: pick a platform *after* deciding what you actually want as
+  a writer. Technical content is expensive to produce; making it for the wrong audience on the
+  wrong surface wastes your scarcest resource.
+- Compare platforms on three axes:
+  - **Growth/discoverability** — Medium: internal distribution, but the algorithm decides reach.
+    X: reach with high volatility. Substack: slow to start, compounds (Notes, recommendations,
+    direct email) into an asset you keep.
+  - **Audience/culture** — X is fast and combative; Medium skews essay readers; Substack readers
+    opt in deliberately (roughly 85% email / 10% app on a typical post).
+  - **Business model** — Medium pays per member read; X monetization is thin for most; Substack is
+    free, you own your subscriber list, paid subs optional (10% cut only when someone pays).
+- For IT writers the email list is the difference between building equity and renting attention.
+  Cross-posting to Medium is a fine low-effort hedge — just understand its mechanics first.
+
+## Launch and grow (Substack)
+
+- Substack is three layers: email newsletter, publication (archive/about/navigation), and
+  social/discovery (Notes, recommendations, search). Most writers only use layer one — that is why
+  they struggle to grow.
+- Setup order: name the publication (clear topic promise or memorable brand — not your personal
+  name unless known); write an attention-grabbing bio (what you write, who it's for, credentials);
+  import any existing subscriber list; publish a first post before promoting.
+- Cadence: a sustainable frequency — one good post per week beats one "perfect" post per month;
+  shipping gets you feedback to iterate. Open each issue with a clear thesis and keep it readable
+  in an email client.
+- **Growth levers combine**: from zero, Notes daily + connecting with writers gets the first
+  50–100 subs; 100–500 layers in guest posts, collaborations, and recommendations (one publication
+  gained ~7,000 subs through recommendations alone).
+- **Notes** is the "new Twitter for writers": short valuable insights, questions, daily presence,
+  genuine engagement (comments, restacks). Not random hot takes or growth-hacking. A 3-2-1 weekly
+  rhythm: three value notes, two engagement posts, one soft promotion.
+- **Own the channel, rent the algorithm**: the email list is the asset that survives platform
+  changes; Notes/X/LinkedIn are top-of-funnel discovery — valuable, volatile, never the foundation.
+
+## Position and voice
+
+- **Author-first** (the newsletter builds an audience for *you*; topics range widely) vs
+  **topic-first** (the publication is the draw; the niche is the promise — "production Kubernetes
+  war stories"). IT content tends to capture niche intent faster topic-first; author-first builds a
+  brand that travels.
+- **Voice is the durable moat**: people want the person behind the publication. When automation
+  repurposes content, preserve conversational voice and framework thinking — never "AI rewrites my
+  stuff," which yields generic output.
+
+## Repurposing (one long-form → many assets)
+
+- One newsletter becomes 5 LinkedIn posts + 10 Substack Notes + 3 X threads via a webhook →
+  extract → generate → deliver pipeline (Make.com + Firecrawl + OpenAI + Google Docs), cutting
+  hours of manual reformatting to ~30 minutes of polish.
+- **Adapt per platform, never copy-paste**: LinkedIn wants declarative hooks + strategic line
+  breaks; Substack Notes wants ~200-character insights with bold + mic-drop endings; X threads
+  need conversational hooks with curiosity gaps between tweets.
+- Dense IT material (architecture tradeoffs, debugging walkthroughs, benchmarks) must be re-cut
+  per surface. Long-form Substack/Medium carries the full technical depth and is the canonical
+  source everything links back to.
+- **The 10–20% human polish pass is mandatory and non-delegable** — for technical material this
+  is where accuracy lives: verify every code snippet, command, flag, and version-specific claim.
+
+## Applying this in `create`
+
+Load this reference when `--playbook english`. It informs the draft's framing (audience, voice,
+platform-native format) and the distribution plan, but the deliverable stays `topic`'s
+`3-draft/draft-article.md` — this playbook never publishes and never writes a parallel artifact.

package/plugins/kk/skills/itc-generating/references/platform-wechat.md

@@ -0,0 +1,60 @@
+# WeChat Official Account playbook (specific-platform study)
+
+Distilled from the STORM study "How to Write and Publish Technical Documents on WeChat Official
+Accounts" (works dir `how-to-write-it-technical-documents-for-specific-d158f7c2`, provenance only).
+Load this reference when `--playbook wechat`; it shapes the draft for WeChat's reading context and
+compliance constraints — never reimplements registration, publishing, or the API.
+
+## Why WeChat
+
+- For Chinese academics, engineers, and technical decision-makers, WeChat Official Accounts
+  (微信公众号) are the primary delivery channel — researchers check it almost every waking hour.
+- Authority bar: an expert should be able to name at least five public accounts on the topic they
+  follow. If your account would not make that list, you are not reaching the expert audience.
+
+## Account type and constraints (the drafting context)
+
+- **Subscription account (订阅号)**: up to 1 push/day, but folded into a "Subscriptions" folder —
+  best for high-cadence technical publishing. **Service account (服务号)**: 4 messages/month but
+  appears in the main chat list with push — best for low-cadence, high-importance announcements.
+- **Enterprise accounts (企业号)** are for internal newsletters (mutual approval, no public reach).
+- **Hard limits that shape content**: each message carries up to 8 articles; **published articles
+  cannot be deleted** — only modified with a correction notice. Errors are permanent, so
+  review-before-publish is mandatory.
+- Registration is a Chinese-identity-bound process (QR-scan binding, Chinese ID/phone for admins,
+  ICP / Mini Program filings for hosted infrastructure). Foreign entities must work through a
+  Chinese partner. API access needs AppID/AppSecret (QR-verified) and an IP whitelist.
+
+## Authoring for the WeChat reader
+
+- **Markdown-first pipeline**: WeChat's rich-text editor cannot interpret Markdown. Write in
+  Markdown, convert to WeChat-compatible rich text (MD2WeChat / `lyricat/wechat-format`, or the
+  Obsidian `wechat-public-platform` plugin for one-command draft upload), then paste/upload.
+  Converters turn external links into footnotes (external links are not allowed in articles).
+- **Format for mobile consumption** (articles are read on phones — commuting, mid-meeting):
+  short paragraphs, images/GIFs/audio/video (text-only underperforms), text-light images, abstract
+  (摘要) under 120 characters, 900×500px cover, Simplified Chinese, short self-explanatory titles
+  (truncated after ~26 Chinese characters), h2–h4 headings (leave h1 for larger embedding), 15px
+  body text, PingFang on iOS.
+- **Language**: Chinese-language articles outperform English even for Chinese academics who read
+  English; some international accounts publish multilingual content.
+- **What engages**: novelty (new findings/new resources), originality and authenticity, and
+  structural rigor — this audience is trained to be critical of a WeChat post.
+
+## Editorial standards for authority
+
+- **Bilingual/translated material**: the CAICT model — long-form Chinese analyses of international
+  technical reports, crediting Chinese-institution contributors — is the reference pattern.
+- **Worth a "top five" slot**: recurring high-signal formats (standards announcements, seminar
+  notices, joint research, translated analyses) plus originality, authenticity, and rigor.
+- **Review-before-publish checklist** (forced by the no-deletion rule): preview to your own WeChat
+  first; verify title length, abstract, cover, and footnote-converted links; confirm originality
+  declaration, tags, and comment settings manually in the draft box; route the broadcast through
+  the admin QR-code verification step.
+
+## Applying this in `create`
+
+Load this reference when `--playbook wechat`. It informs the draft's structure (mobile-first
+formatting, Chinese-language expectations, title/abstract limits, review rigor) but the deliverable
+stays `topic`'s `3-draft/draft-article.md` — this playbook never registers an account, never
+publishes, and never touches the WeChat API.

package/plugins/kk/skills/itc-generating/references/skill-authoring.md

@@ -0,0 +1,62 @@
+# Skill-authoring self-discipline (why this skill stays lean)
+
+Distilled from the STORM study "How to Write the Best Technical Documentation with Agent Skills"
+(works dir `how-to-write-the-best-technical-document-with-ex-2c52b35c`, provenance only). This
+reference is the meta-discipline for *this skill*: it exists so `itc-generating` stays a thin
+method+orchestration layer instead of re-vendoring craft or reimplementing sibling skills.
+
+## The SKILL.md contract (hard limits)
+
+- **Frontmatter**: `name` ≤64 chars, lowercase letters/numbers/hyphens only, no XML tags or
+  reserved words, and must exactly match the parent directory name. `description` is non-empty,
+  ≤1,024 chars, no XML tags.
+- **Body budget**: keep SKILL.md under ~500 lines / ~5,000 tokens — just the core instructions the
+  agent needs every run; split the rest into `references/`.
+- **Context economics**: only `name` + `description` are pre-loaded; the rest enters context only
+  when needed. The description is the *only* routing signal — write it as a third-person capability
+  statement with explicit negative triggers so near-miss tasks are excluded.
+- **Folder grammar**: SKILL.md + `references/` + `scripts/` + `assets/`, kept **exactly one level
+  deep** (`references/schema.md`, not `references/db/v1/schema.md`). Avoid nested reference chains —
+  when references point at references, the agent previews instead of reading fully.
+
+## Progressive disclosure (the load-on-demand rule)
+
+- Keep the always-loaded core minimal; push detail into `references/` with **just-in-time
+  pointers**: "Read `references/api-errors.md` if the API returns a non-200" beats "see
+  references/ for details".
+- Three patterns: high-level guide + references; domain-specific organization; conditional details
+  (branch to a section only when a condition holds).
+- Prefer **deterministic scripts** for fragile/repetitive operations (link checks, format
+  validation) — not for judgment-heavy authoring. Design their failure modes deliberately.
+
+## Instruction design
+
+- **Degree of freedom**: prescriptive exact-sequence instructions for fragile operations; goal-plus-
+  philosophy for judgment-heavy work (authoring). Vague skills fail — "handle errors appropriately"
+  carries no information.
+- **Defaults, not menus**: pick one default and a one-line escape hatch, rather than listing
+  options and hoping the agent chooses well.
+- **Add what the agent lacks; omit what it knows**: the filter is "would the agent get this wrong
+  without this instruction?" If no, cut it.
+- Highest-value blocks: gotchas sections (environment facts that defy assumptions), output-format
+  templates, checklists and self-check loops.
+
+## Evaluation and review (how to keep improving the skill)
+
+- Four validation passes: discovery (description in isolation — does it route correctly?),
+  logic (deterministic steps, no hallucinated gaps), adversarial edge-case QA ("try to break this
+  skill"), architecture refinement (enforce progressive disclosure).
+- **Execute-then-refine** beats endless pre-polish: run the skill on real tasks and iterate;
+  read execution traces, not just outputs (instructions retried many times, instructions followed
+  that don't apply, too many options without a default).
+- Add a **self-reflection step**: after a run, examine the friction log and improve the skill so
+  the next run does not struggle the same way.
+
+## How this skill applies it
+
+`itc-generating` is one-level-deep by construction: SKILL.md points at the four `references/*.md`
+files below it and loads them on demand (generic-craft always; playbook only when `--playbook` is
+not `generic`). It reuses `topic`'s artifact contract rather than inventing a parallel workspace
+(D5), delegates research/judging to `storm-research`/`content-judge` rather than reimplementing them (D6),
+and stays under the body budget because the four STORM reports live in the works dirs as
+provenance — never vendored here (D4).

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

@@ -35,7 +35,7 @@ Use when:
 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`.
+- Quality gating / judging generated content — that is `content-judge`.
 - Publishing, platform adaptation, or illustration — out of C4 scope.
 - Anything requiring a raw `kk executor run` chain when the workflow already composes it.
 
@@ -93,7 +93,7 @@ skill is also callable directly as `Skill(skill="storm-research", args="<topic|-
   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)
+## Works layout (0056, frozen; ADR-013 adds `references/`)
 
 Per-topic workspace at `$works_dir/<topic-id>/`:
 
@@ -105,6 +105,7 @@ Per-topic workspace at `$works_dir/<topic-id>/`:
 | `docs.json` | ingest | `web-search` output `Doc[]` |
 | `content.json` | generate | STORM `Content` (machine contract) |
 | `content.md` | render | markdown sidecar report |
+| `references/<doc-id>.md` | ingest (live path only) | normalized full content per source (`/v2/scrape` → markitdown); file name = Doc id; audit trail and the citation-resolution target for the report tail (ADR-013) |
 
 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`,
@@ -130,9 +131,10 @@ outside any repo.
 | `--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` |
+| Workflow YAML cannot be resolved from any install source | exit 1, stderr lists the roots searched (`KK_WORKFLOWS_SOURCE`, `plugins/kk/workflows`) | 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 | — |
+| `markitdown` missing from `PATH` (live mode) | ingest exit 1, stderr `web-search failed: markitdown is not on PATH`; probed before any network call, so no `docs.json` write | install markitdown / put it on `PATH`, re-run ingest |
 
 Every failure names the exact path and the exact next command. Never silently skip, never
 auto-replace, never hash topic-id in the YAML.
@@ -154,6 +156,10 @@ auto-replace, never hash topic-id in the YAML.
 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.
+7. **Digest, don't index.** References are evidence, not the deliverable: the report synthesizes
+   findings across the supplied documents, compares them, and states conclusions — it never
+   lists sources one per line. The render drops the `## Outline` replay (ADR-013 D7); the
+   references tail plus `references/<doc-id>.md` files are the audit trail behind each cite id.
 
 ## Invariants
 
@@ -164,3 +170,4 @@ auto-replace, never hash topic-id in the YAML.
   `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.
+  ADR-013 exception: the ingest live path writes `references/<doc-id>.md` per cached source.

package/plugins/kk/workflows/judge-gated-publish-example.yaml

@@ -0,0 +1,101 @@
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: judge-gated-publish
+description: "Example workflow where an LLM-as-judge agent.run step gates a publish transition"
+initialState: generate
+terminalStates:
+  - done
+  - failed
+failureStates:
+  - failed
+vars:
+  contentFile: ".spur/run/content.json"
+  verdictFile: ".spur/run/verdict.json"
+  rubric: "general"
+  maxRetries: "2"
+  # attempt is mutated by the revise loop; initialize to 0.
+  attempt: "0"
+  spurBin: "spur"
+states:
+  - id: generate
+    description: "Generate content from brief or docs (kk invoke <generator>)"
+    onEnter:
+      - kind: shell
+        options:
+          # Seed the verdict so the judge gate guards can be evaluated in --dry-run
+          # (dry-run skips actions but still evaluates shell guards). A real run's
+          # judge step overwrites this file before the gate is read.
+          command: "echo '{\"verdict\":\"PASS\",\"score\":0.0}' > ${vars.verdictFile} && echo 'generating content...'"
+  - id: judge
+    description: "Evaluate generated content via the judge skill (agent.run)"
+    onEnter:
+      # `agent.run` is registered by the kk workflow host: it spawns an agent that loads the
+      # content-judge skill, evaluates the content against ${vars.rubric}, and writes the verdict
+      # JSON to ${vars.verdictFile}. Under `spur workflow run` (dry-run), this action is
+      # skipped — the seeded verdict above keeps the gate evaluable. See
+      # plugins/kk/skills/content-judge/SKILL.md and references/workflow-integration.md.
+      - kind: agent.run
+        options:
+          role: reviewer
+          input: |
+            Evaluate the content at ${vars.contentFile} against the ${vars.rubric} rubric.
+            Load plugins/kk/skills/content-judge/SKILL.md and its references/rubrics.md.
+            Write the verdict JSON to ${vars.verdictFile} per the contract in SKILL.md.
+            Print the verdict path as the last line of stdout.
+          expectFile: ${vars.verdictFile}
+  - id: publish
+    description: "Publish content after clearing judge gate (kk fanout)"
+    onEnter:
+      - kind: shell
+        options:
+          command: "echo 'publishing content...'"
+  - id: done
+    description: "Publish completed successfully"
+  - id: failed
+    description: "Judge rejected content (FAIL) or retries exhausted (NEEDS_REVISION)"
+
+transitions:
+  - from: generate
+    to: judge
+    description: "Content generated -> proceed to evaluation"
+    guard:
+      kind: always
+
+  # PASS -> publish.
+  - from: judge
+    to: publish
+    description: "Judge verdict is PASS (or file absent under --dry-run) -> proceed to publish"
+    guard:
+      kind: shell
+      options:
+        # Fail-closed on an explicit non-PASS verdict; fail-open only when the file is
+        # absent, which happens under --dry-run (actions are skipped, so the judge
+        # never writes its verdict). A real run always has the file.
+        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test -z "$v" -o "$v" = PASS'
+
+  # NEEDS_REVISION -> back to generate with a bounded retry budget.
+  - from: judge
+    to: generate
+    description: "Judge verdict is NEEDS_REVISION and retry budget remains -> regenerate with feedback"
+    guard:
+      kind: shell
+      options:
+        # Allow the revise loop only while the attempt counter is below maxRetries.
+        # The shell kind cannot mutate vars, so the host (or a sidecar note action) is
+        # responsible for incrementing attempt on each loop in a real run.
+        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test "$v" = NEEDS_REVISION -a "$attempt" -lt "$maxRetries"'
+
+  # FAIL, or NEEDS_REVISION with no retries left -> failed.
+  - from: judge
+    to: failed
+    description: "Judge verdict is FAIL, or NEEDS_REVISION with retries exhausted -> block publish"
+    guard:
+      kind: shell
+      options:
+        command: 'v="$(jq -r .verdict ${vars.verdictFile} 2>/dev/null)"; test -n "$v" && { test "$v" = FAIL || test "$v" = NEEDS_REVISION -a "$attempt" -ge "$maxRetries"; }'
+
+  - from: publish
+    to: done
+    description: "Publish done"
+    guard:
+      kind: always

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

@@ -0,0 +1,144 @@
+---
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+name: kk-daily-ai-voice
+kind: state-machine
+description: >-
+  Daily AI news broadcast pipeline orchestrating aihot-ingest, dailynews-gen, and voice-gen
+initialState: prepare
+terminalStates:
+  - done
+  - failed
+failureStates:
+  - failed
+
+vars:
+  work_dir: ""
+  limit: "10"
+  language: "zh"
+  voice_profile: "Robin"
+  title: ""
+  cursor: ""
+  state_file: ""
+  skip_review: "false"
+  transcode_mp3: "false"
+  plugins_path: ""
+  __hitlAnswer: ""
+
+states:
+  - id: prepare
+    description: "Create workspace subdirectories and validate parameters"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            test -n "${vars.work_dir}" || { echo "missing required variable: work_dir" >&2 && exit 1; };
+            mkdir -p "${vars.work_dir}" "${vars.work_dir}/1-ingest" "${vars.work_dir}/2-script" "${vars.work_dir}/3-audio";
+            bun -e 'await Bun.write(process.argv[1], JSON.stringify({ limit: Number(process.argv[2]), cursor: process.argv[3] || undefined, stateFile: process.argv[4] || undefined }, null, 2))' "${vars.work_dir}/1-ingest/source.json" "${vars.limit}" "${vars.cursor}" "${vars.state_file}"
+
+  - id: fetch
+    description: "Ingest latest curated AI news from aihot.virxact.com"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            kk executor run aihot-ingest --in "${vars.work_dir}/1-ingest/source.json" --out "${vars.work_dir}/1-ingest/docs.json" "$@"
+
+  - id: script
+    description: "Compile news Doc[] into structured broadcast VoiceScript YAML Content"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; fi;
+            DAILYNEWS_LANGUAGE="${vars.language}" DAILYNEWS_TITLE="${vars.title}" VOICEBOX_DEFAULT_PROFILE="${vars.voice_profile}" kk executor run dailynews-gen --in "${vars.work_dir}/1-ingest/docs.json" --out "${vars.work_dir}/2-script/content.json" "$@" &&
+            bun -e 'await Bun.write(process.argv[2], (await Bun.file(process.argv[1]).json()).body)' "${vars.work_dir}/2-script/content.json" "${vars.work_dir}/2-script/voicescript.yaml"
+
+  - id: review
+    description: "Operator reviews the generated news script before speech synthesis"
+    pause: true
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Review daily AI news VoiceScript at ${vars.work_dir}/2-script/voicescript.yaml. Proceed to voice generation?"
+          var: __hitlAnswer
+
+  - id: wrap-docs
+    description: "Wrap VoiceScript into Doc[] input for voice-gen"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            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" } }; await Bun.write(process.argv[2], JSON.stringify([doc], null, 2))' "${vars.work_dir}/2-script/voicescript.yaml" "${vars.work_dir}/3-audio/docs.json" "${vars.voice_profile}"
+
+  - id: generate
+    description: "Invoke voice-gen generator plugin to generate audio"
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            set --;
+            if [ -n "${vars.plugins_path}" ]; then set -- --plugins-path "${vars.plugins_path}"; 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" "$@"
+
+  - id: done
+    description: "Terminal — Daily AI news voice broadcast generated successfully"
+  - id: failed
+    description: "Terminal — Pipeline failed"
+
+transitions:
+  - from: prepare
+    to: fetch
+    description: "Workspace prepared -> fetch news items"
+    guard:
+      kind: always
+
+  - from: fetch
+    to: script
+    description: "News ingested -> build broadcast script"
+    guard:
+      kind: always
+
+  - from: script
+    to: wrap-docs
+    description: "skip_review enabled -> bypass HITL review"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.skip_review}" = "true"'
+
+  - from: script
+    to: review
+    description: "skip_review disabled -> pause for operator review"
+    guard:
+      kind: always
+
+  - from: review
+    to: wrap-docs
+    description: "VoiceScript approved -> wrap for audio generation"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.__hitlAnswer}" = "yes"'
+
+  - from: review
+    to: failed
+    description: "VoiceScript rejected -> abort"
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.__hitlAnswer}" = "no"'
+
+  - from: wrap-docs
+    to: generate
+    description: "Doc[] wrapped -> synthesize audio"
+    guard:
+      kind: always
+
+  - from: generate
+    to: done
+    description: "Audio generated successfully -> complete"
+    guard:
+      kind: always

package/plugins/kk/workflows/kk-ingest-generate-publish.yaml

@@ -0,0 +1,72 @@
+# Linear state-machine workflow template for knowledge-kit plugin platform:
+# ingest -> generate -> publish -> done.
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+name: kk-ingest-generate-publish
+kind: state-machine
+description: Chained ingestion, generator, and publish plugins via kk executor run
+initialState: ingest
+terminalStates:
+  - done
+  - failed
+vars:
+  ingestion_plugin: "karakeep-local"
+  generator_plugin: "content-gen"
+  publish_plugin: "surfdash-pub"
+  source: "./source"
+  work_dir: "./work"
+  plugins_path: "./plugins"
+
+states:
+  - id: ingest
+    description: Run ingestion plugin to produce document list (docs.json)
+    onEnter:
+      - kind: shell
+        options:
+          command: kk executor run ${vars.ingestion_plugin} --in ${vars.source} --out ${vars.work_dir}/docs.json --plugins-path ${vars.plugins_path}
+
+  - id: generate
+    description: Run content generator plugin to produce markdown content (content.json)
+    onEnter:
+      - 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: publish
+    description: Run publish plugin to deploy content and receive result (result.json)
+    onEnter:
+      - kind: shell
+        options:
+          command: kk executor run ${vars.publish_plugin} --in ${vars.work_dir}/content.json --out ${vars.work_dir}/result.json --plugins-path ${vars.plugins_path}
+
+  - id: done
+    description: Terminal — all three plugin steps succeeded
+  - id: failed
+    description: Terminal — one of the plugin run steps failed
+
+transitions:
+  - from: ingest
+    to: generate
+    description: Ingest succeeded — proceed to content generation
+    guard:
+      kind: action-ok
+  - from: ingest
+    to: failed
+    description: Ingest failed — terminate workflow
+
+  - from: generate
+    to: publish
+    description: Content generation succeeded — proceed to publish
+    guard:
+      kind: action-ok
+  - from: generate
+    to: failed
+    description: Generator failed — terminate workflow
+
+  - from: publish
+    to: done
+    description: Publish succeeded — workflow complete
+    guard:
+      kind: action-ok
+  - from: publish
+    to: failed
+    description: Publish failed — terminate workflow