@gobing-ai/knowledge-kit 0.0.7 → 0.0.8

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

@@ -6,6 +6,13 @@
  * 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.
  *
+ * NODE-BUILTIN-ONLY — no workspace or `@gobing-ai/*` imports, and therefore raw
+ * `console.error` rather than the ts-utils output seam. This script ships to arbitrary
+ * user projects and is shelled as `bun <this script>`; an `@gobing-ai/*` import resolves
+ * there only because bun auto-installs it from the network, so it fails under
+ * `bun --no-install`, offline, or in an air-gapped environment. Enforced by
+ * `shipped-script-isolation` in `.spur/rules/boundary/`.
+ *
  * SYNC: packages/kk-core/src/render-md.ts (renderContentMarkdown + helpers)
  */
 
@@ -72,10 +79,8 @@ 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`;
+    return `${lead}${content.body}${refsBlock}\n`;
 }
 
 function renderReferences(references: ContentInput['references']): string {

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

@@ -1,17 +1,17 @@
 ---
-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.
+name: content-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 content-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
 ---
 
-# judge — LLM-as-judge evaluation skill
+# content-judge — LLM-as-judge evaluation skill
 
 ## Purpose
 
 Evaluate generated `Content` against a rubric and emit a structured **verdict** that a spur
 workflow gate can consume. This is the fat skill — the single source of truth for evaluation
-logic, prompt templates, and verdict formatting. Thin wrappers (tech-accuracy, brand-tone,
-compliance) delegate here with a pre-selected rubric.
+logic, prompt templates, and verdict formatting. The `agent.run` prompt (or `--judge` flag on
+`itc-generating`) selects the rubric; there are no persona subagents.
 
 LLM-as-judge is **not** a knowledge-kit plugin kind (ADR-007 amdt 2026-08-07). It runs as an
 `agent.run` step in a spur workflow; the verdict is a skill output, not a plugin-kind contract.
@@ -20,7 +20,7 @@ LLM-as-judge is **not** a knowledge-kit plugin kind (ADR-007 amdt 2026-08-07). I
 
 - A spur workflow needs a quality gate between `generate` and `publish`.
 - A user asks to "judge", "evaluate", "quality-check", or "gate" generated content.
-- A thin wrapper (tech-accuracy / brand-tone / compliance) delegates evaluation.
+- A workflow or skill names a rubric (`tech-accuracy` / `brand-tone` / `compliance` / `general`).
 
 ## Verdict output contract
 
@@ -61,8 +61,8 @@ Every evaluation writes a JSON verdict file. The default path is
 
 1. **Read the Content** from the path given in the evaluation request (the `content.json` written
    by the preceding `kk executor run <generator>` step).
-2. **Select the rubric** — either named in the request (`tech-accuracy`, `brand-tone`,
-   `compliance`, `general`) or loaded by a thin wrapper. Default: `general`.
+2. **Select the rubric** — named in the request (`tech-accuracy`, `brand-tone`,
+   `compliance`, `general`). Default: `general`.
 3. **Evaluate each criterion** in the rubric. For each, produce a `pass` / `fail` / `warn` status
    backed by a specific, quotable evidence reference (quote, section, claim).
 4. **Score** — weighted aggregate per the rubric's scoring rules. `score` is 0.0–1.0.
@@ -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/judge/references/rubrics.md (section: {{rubric}}).
+Load the rubric definition from plugins/kk/skills/content-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.
@@ -119,13 +119,12 @@ Print the verdict path to stdout as the last line.
 
 See `references/workflow-integration.md` for the `agent.run` step shape and the shell/`jq` guard
 that reads the verdict. The example workflow is at
-`.spur/workflows/judge-gated-publish-example.yaml`.
+`plugins/kk/workflows/judge-gated-publish-example.yaml`.
 
-## Thin wrappers
+## Rubric selection
 
-The wrappers in `plugins/kk/agents/` (tech-accuracy, brand-tone, compliance) are thin: they fix
-the `rubric` field and forward to this skill. They do not duplicate evaluation logic. To create a
-new persona, add a wrapper that sets the rubric and reuses this skill's procedure verbatim.
+The `agent.run` prompt (or the calling skill) sets `{{rubric}}`. To add a persona, add a rubric
+section in `references/rubrics.md` and name it from the prompt — do not add a subagent wrapper.
 
 ## Additional resources
 

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

@@ -1,4 +1,4 @@
-# Workflow integration — judge in a spur workflow
+# Workflow integration — content-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
@@ -7,16 +7,18 @@ by a `shell` node that guards the transition to `publish`.
 ## Step shape
 
 ```yaml
-- name: judge
-  type: agent.run
-  run: |
-    Evaluate the generated content against the {{rubric}} rubric.
-    Content: {{content_path}}
-    Write the verdict to {{verdict_path}}.
-  skill: judge
+- kind: agent.run
+  options:
+    role: reviewer
+    input: |
+      Evaluate the generated content against the {{rubric}} rubric.
+      Content: {{content_path}}
+      Write the verdict to {{verdict_path}}.
+      Load plugins/kk/skills/content-judge/SKILL.md.
+    expectFile: "{{verdict_path}}"
 ```
 
-- `agent.run` spawns an agent that loads the `judge` skill, performs the evaluation, and writes
+- `agent.run` spawns an agent that loads the `content-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.
 
@@ -60,7 +62,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 — `judge` itself is stateless
+example workflow uses 2). This is workflow-level orchestration — `content-judge` itself is stateless
 and re-runnable.
 
 ```
@@ -73,5 +75,5 @@ generate ──▶ judge ──PASS──▶ publish
 
 ## Workflow YAML location
 
-The runnable example lives at `.spur/workflows/judge-gated-publish-example.yaml`. It demonstrates
+The runnable example lives at `plugins/kk/workflows/judge-gated-publish-example.yaml`. It demonstrates
 `generate → judge → guard → publish` with a 2-retry NEEDS_REVISION loop.

package/plugins/kk/skills/itc-generating/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: itc-generating
+description: >-
+  Use the itc-generating skill to produce an approved IT technical draft from a
+  topic or Markdown brief, applying the distilled generic IT-writing method and
+  an optional platform playbook — "write an article about X applying the IT
+  writing method", "generate an IT technical draft on X", "create a technical
+  article for WeChat/English platforms". Orchestrates topic (outline + draft),
+  optional storm-research, and optional content-judge without enlarging those skills.
+---
+
+# itc-generating — IT technical draft generation (method + orchestration)
+
+## Purpose
+
+Turn a topic or Markdown brief into an **approved IT technical draft** by applying the distilled
+IT-writing craft and orchestrating the existing `kk` skills — `topic` (outline + draft), optional
+`storm-research` (evidence), optional `content-judge` (technical-accuracy gate). One fat skill with one
+operation, `create`, whose default is the distilled generic-craft method; it delegates outline
+selection and draft review to `topic` and writes the **same topic artifact paths**. This skill owns
+*which* method and *when* to research/judge — it never reimplements topic-core, research, or
+evaluation (D6).
+
+## When to use
+
+- A user asks to write an IT technical article from a topic or brief and wants the distilled
+  IT-writing method applied ("write an IT article about X", "produce a technical draft on X").
+- A user wants a specific platform playbook applied to the draft (`--playbook english` / `wechat`).
+- A user wants the same topic artifact contract but with the writing method and optional
+  research/judging orchestrated around it.
+
+Do **not** use this skill for: a single topic-core step without the method (call `topic` directly);
+research alone (call `storm-research`); evaluating content alone (call `content-judge`); publishing,
+platform adaptation, or image generation (all out of scope); anything requiring a runtime plugin
+(`kk executor run`, `plugin.json`, `GeneratorInput → Content`).
+
+## Invocation contract
+
+`$ARGUMENTS` (or the Skill call args) parse as:
+
+```
+[create] <topic-or-brief> [--dir <target>] [--brief <path>]
+         [--playbook generic|english|wechat]
+         [--research] [--judge]
+         [--outline <a|b|c>] [--revise <feedback>] [--force]
+```
+
+| Token | Meaning | Default |
+| --- | --- | --- |
+| `create` | the only operation; may be omitted | `create` |
+| `<topic-or-brief>` | quoted topic phrase, or `--brief <path>` naming a Markdown brief file | required — empty fails loud |
+| `--dir <target>` | workspace directory | `./<kebab-case(topic)>` (same default as `topic`) |
+| `--playbook <p>` | which reference to load as the writing method | `generic` |
+| `--research` | if the workspace has no evidence, run `storm-research` first | off |
+| `--judge` | after an approved draft, run `content-judge` with the `tech-accuracy` rubric | off |
+| `--outline <a\|b\|c>` | explicit outline selection (passed through to `topic`) | operator selects at the gate |
+| `--revise <feedback>` | revision feedback for the draft review gate (passed through to `topic`) | none (approve path) |
+| `--force` | explicit operator approval to replace an existing artifact (passed through to `topic`) | off — never overwrite without it |
+
+Flags may appear in any order; the first bare positional token is the topic phrase. An unknown
+operation (anything other than `create`) fails loud and lists `create` as the only valid operation.
+
+## References (loaded on demand, R2)
+
+| File | When to load |
+| --- | --- |
+| `references/generic-craft.md` | **always** on every `create` run — the five IT-writing disciplines |
+| `references/platform-english.md` | `--playbook english` — X / Medium / Substack playbook |
+| `references/platform-wechat.md` | `--playbook wechat` — WeChat Official Account playbook |
+| `references/skill-authoring.md` | when reviewing or editing this skill — why it stays lean |
+
+The four STORM studies remain in the works dirs (`~/.config/kk/works/`) as provenance; the skill
+body and references do **not** vendor the full reports (D4).
+
+## Artifact contract (reuses topic, D5)
+
+All paths are relative to the workspace `--dir`. This skill does **not** invent a parallel
+workspace — it delegates to `topic`, which writes exactly these paths:
+
+| Artifact | Path | Written by |
+| --- | --- | --- |
+| Brief | `brief.md` | `topic` `init` |
+| Outline options | `2-outline/outline-option-{a,b,c}.md` | `topic` `outline` |
+| Approved outline | `2-outline/outline-approved.md` | `topic` `outline` (after selection gate) |
+| Draft | `3-draft/draft-article.md` | `topic` `draft` (from approved outline, review gate) |
+
+## create sequence
+
+1. **Input check** (fail loud, R5): empty topic and no `--brief` → stop with recovery. A `--brief`
+   path that does not exist → stop with recovery.
+2. **Target check** (fail loud, R5): if `--dir` exists with a `brief.md` and no `--force` → stop
+   with recovery ("initialization target already exists at `<dir>`; pass `--force` after explicit
+   operator confirmation to replace, or choose a new `--dir`"). Never overwrite without `--force`.
+3. **Load the method** — read `references/generic-craft.md` (always) plus the selected playbook if
+   `--playbook` is not `generic` (R2). If `--research` and the workspace has no reusable evidence,
+   invoke `storm-research` on the topic (XOR: a topic phrase or `--in <file>`); re-run research
+   only when the query or sources must change — reuse existing `docs.json` otherwise.
+4. **Delegate to `topic`** — run `topic create` against `--dir` with the same artifact contract and
+   gates: outline options → explicit selection gate (`--outline <a|b|c>` or interactive) → approved
+   outline → draft → review gate (approve or bounded `--revise`). This skill never reimplements
+   those gates (R1, R3).
+5. **Apply the method while drafting** — using the loaded references, apply the five disciplines
+   (one goal per document, value proposition as scope firewall, explicit prerequisites and POLA,
+   show-don't-tell with diagrams/examples, accessibility) plus the platform playbook's constraints
+   (e.g. WeChat mobile formatting or English-platform framing). The draft is written by `topic`
+   from the approved outline; the method shapes it.
+6. **Optional judge gate** — if `--judge` and `3-draft/draft-article.md` is approved, invoke
+   `content-judge` with the `tech-accuracy` rubric. A non-`PASS` verdict is reported to the operator; it
+   does **not** auto-publish and does not auto-revise past `topic`'s 3-round bound.
+7. **Print** the final artifact paths and stop.
+
+## Fail-loud table (R5)
+
+| Condition | Behavior | Recovery instruction |
+| --- | --- | --- |
+| Empty topic and no `--brief` | Stop; no files created | Provide a topic phrase or `--brief <path>` |
+| `--brief` path does not exist | Stop; no files created | Check the path; supply a real Markdown brief |
+| `--research` with neither topic nor `--in` | Stop; nothing written | Pass exactly one of the topic / `--in <file>` to `storm-research` |
+| Missing prerequisite artifact (e.g. outline before draft) | Stop; nothing written | The recovery comes from `topic` — run the prerequisite step first (see `topic` fail-loud table) |
+| Existing initialization target without `--force` | Stop; no overwrite | Confirm with the operator and pass `--force`, or choose a new `--dir` |
+| Unknown operation | Stop; nothing written | Use `create` (the only operation) or call `topic` / `storm-research` / `content-judge` directly |
+
+Every stop names the exact missing or existing path and the exact next command. Never silently
+skip, never auto-replace, never delete.
+
+## Invariants
+
+- `create` is the **only** operation. Research, illustration, adaptation, and publish operations
+  are **not** added to `topic` — this skill delegates to `storm-research` / `content-judge` (R3).
+- Reuse `topic` artifact paths; never invent a parallel workspace (D5).
+- `topic` / `storm-research` / `content-judge` contracts are unchanged (D6) — this skill only orchestrates.
+- No `plugins/kk/commands/itc*.md`, no `kk` CLI noun/verb, no generator `plugin.json` (R4).
+- Never overwrite an existing artifact without `--force`; bound draft revision at `topic`'s 3
+  rounds.
+- No live publish, no external side effects beyond the delegated research call, no image generation.
+
+## Prompt template (Skill() / agent.run)
+
+```
+Skill(skill="itc-generating",
+  args="<topic-or-brief> [--dir <target>] [--brief <path>] [--playbook generic|english|wechat] [--research] [--judge] [--outline <a|b|c>] [--revise <feedback>] [--force]")
+```
+
+When invoked, follow the `create` sequence above. Load the references the flags select, delegate
+outline selection and draft review to `topic`, and pause for the operator at `topic`'s gates. On
+any stop, output the fail-loud recovery line. The artifact paths under the workspace `--dir` are
+the handoff.

package/plugins/kk/skills/itc-generating/references/generic-craft.md

@@ -0,0 +1,80 @@
+# Generic IT-writing craft — five disciplines
+
+Distilled from the STORM study "How to Write the Best Generic IT Technical Documentation"
+(works dir `how-to-write-the-best-generic-it-technical-docum-0a71c5a7`, provenance only — this
+reference replaces vendoring the full report). Load this reference on every `create` run; apply
+all five disciplines while authoring the draft.
+
+## 1. Structure and scope (the document architect)
+
+- Pick the document types you actually need — and **stop**. There is no universal list; add a
+  document only when no existing one's goal absorbs the content.
+- **One document, one goal**, enforced at review: reread after writing and remove or move
+  anything that does not serve that goal. Write everything first, then cut.
+- **Write the Value Proposition (VP) first**: a one-page list of what the doc will do for its
+  reader (save time, reduce errors, cut training…). It says nothing about format or fonts. Use it
+  as a scope-creep firewall — keep content that supports a VP item, remove the rest.
+- **Plan before writing**: research first (history → latest literature → what existing docs
+  already cover), then a documentation plan (scope, objectives, estimates, workflows, resources).
+  Do not over-invest in placement up front — move a document after it exists.
+- **One goal per section** too: link out to other documents for prerequisites and detail instead
+  of inlining everything.
+
+## 2. Write for the reader (the reader advocate)
+
+- **Profile the readership** enough to structure and customize for them. Do not assume background,
+  environment, context, or that they have read your other docs — link prerequisites instead of
+  inlining them.
+- **Show, don't tell**: lead with diagrams (process flows, C4 views), then explain in prose.
+  Text-based diagrams (Mermaid, PlantUML) stay easy to update. Use at least one concrete example
+  early — a simple example beats an abstract description.
+- **Principle of Least Astonishment (POLA)**: cover the gotchas and non-typical usage up front —
+  undocumented prerequisites, surprising defaults, implicit ordering. Name assumptions, defaults,
+  and prerequisites explicitly.
+- **Long-form craft**: a succinct, jargon-free title; structure against the five Ws + H; write the
+  introduction last, once the content has settled.
+- **Accessibility and inclusive writing** are concrete requirements: follow accessibility
+  guidelines for structure/language; use inclusive example names and bias-free language.
+
+## 3. Make it a team discipline (the engineering manager)
+
+- **Budget for docs time**: measure how long SME review of writer output takes and factor it into
+  each release. Good docs are written once, read hundreds of times.
+- **Close the specialized-skill gap**: technical writing is its own discipline (audience
+  understanding + logical presentation); bring in a technical writer or build review processes
+  that treat writing with the same rigor as code.
+- **Embed docs in the engineering workflow**: docs reviews inside normal PR review, preview builds
+  on each check-in, docs as part of shipping every release — not a post-release afterthought.
+- **Docs are coordination infrastructure** at team scale: they improve knowledge retention and
+  underpin quality, consistency, and compliance.
+- **Build documentation mindshare**: state the problem, start in engineering, gather input
+  broadly, build a taxonomy, make contribution easy, meet regularly.
+
+## 4. Keep it fresh (the maintenance owner)
+
+- **Docs go stale by default**; the countermeasure is procedural — assess doc impact of changes
+  each sprint and allocate update time in the release.
+- **Make updates cheap**: prefer simple human-readable formats (Markdown — diffable in Git) and
+  text-based diagrams so edits stay cheap.
+- **Institutionalize the lifecycle**: plan → write → review → publish, with research up front and
+  maintenance at the end; take occasional content inventories and use reader feedback to fill gaps.
+
+## 5. Tooling and publishing (the pipeline engineer)
+
+- **Match tools to doc types and languages**; when in doubt, defer to Markdown and tooling with
+  simple human-readable formats. A convenient editor matters — you won't write docs you hate
+  editing.
+- **Bake publishing into CI/CD**: build docs from sources and publish on every release; generate
+  docs from code artifacts where possible (OpenAPI is the canonical example).
+- **Plan reuse**: write content once and reuse it (CCMS for cross-product scale); audit for
+  overlap before duplication spreads.
+- **Adopt (or author) style guides**: shared style guides keep output consistent — don't write
+  them from scratch (Write the Docs maintains a living one). During review, get the right experts
+  on the right documents and use preview runs to catch errors before publication.
+
+## Applying this in `create`
+
+While drafting `3-draft/draft-article.md` (after `topic`'s outline gate), apply: one goal per
+document enforced at the draft-review gate; the Value Proposition as a scope firewall; explicit
+prerequisites and POLA; show-don't-tell with diagrams/examples; and accessibility. The `--judge`
+gate then verifies technical accuracy against the rubric.

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.