@gobing-ai/knowledge-kit 0.0.12 → 0.0.13

package/plugins/ingestions/web-search/plugin.json

@@ -1,7 +1,7 @@
 {
     "name": "web-search",
     "kind": "ingestion",
-    "entry": "./src/index.ts",
+    "entry": "./dist/index.js",
     "version": "1.0.0",
     "description": "Ingests web search results for a topic into Doc objects (fixture stub — no live Firecrawl in v1)"
 }

package/plugins/kk/commands/image-generate.md

@@ -0,0 +1,15 @@
+---
+name: image-generate
+description: Generate images from a prompt or an article — covers, illustrations, or free-form — using named format and style presets.
+argument-hint: "[prompt] [--format <name>] [--style <name>] [--content <file>] [--ref <path>] [--var K=V] [--dry-run] [--list-presets]"
+allowed-tools: ["Skill"]
+---
+
+# image-generate
+
+Thin wrapper for the `image-authoring` skill — all preset resolution, preference precedence,
+confirmation and delegation logic lives in the skill. Forward `$ARGUMENTS` unchanged.
+
+```text
+Skill(skill="kk:image-authoring", args="$ARGUMENTS")
+```

package/plugins/kk/config.example.yaml

@@ -22,6 +22,73 @@ plugins:
         VOICEBOX_POLL_MS: "1000"                   # GET /history/{id} interval
         VOICEBOX_MAX_CHUNK_CHARS: "800"            # Voicebox auto-chunk size (100–5000)
         VOICEBOX_CROSSFADE_MS: "50"                # Voicebox chunk crossfade (0–500)
+
+    # image-gen (task 0103/0104): full credential inventory, placeholder values only —
+    # source of truth: plugins/generations/image-gen/config.example.yaml
+    image-gen:
+      env:
+        # -- google (Gemini multimodal + Imagen; GOOGLE_* and GEMINI_* are fallback pairs) --
+        GOOGLE_API_KEY: ""                 # or GEMINI_API_KEY — either one enables google
+        GEMINI_API_KEY: ""
+        GOOGLE_IMAGE_MODEL: ""             # optional — default gemini-3-pro-image
+        GOOGLE_BASE_URL: ""                # optional — default https://generativelanguage.googleapis.com
+        # -- openai (gpt-image generations/edits; OPENAI_IMAGE_USE_CHAT is a debug escape hatch) --
+        OPENAI_API_KEY: ""                 # platform.openai.com — required for openai
+        OPENAI_IMAGE_MODEL: ""             # optional — default gpt-image-2
+        OPENAI_BASE_URL: ""                # optional — default https://api.openai.com/v1
+        OPENAI_IMAGE_USE_CHAT: ""          # optional — "true" routes through chat completions
+        # -- openrouter (multi-host gateway) --
+        OPENROUTER_API_KEY: ""             # openrouter.ai/settings/keys — required for openrouter
+        OPENROUTER_IMAGE_MODEL: ""         # optional — default google/gemini-3.1-flash-image
+        OPENROUTER_BASE_URL: ""            # optional — default https://openrouter.ai/api/v1
+        OPENROUTER_HTTP_REFERER: ""        # optional — attribution header
+        OPENROUTER_TITLE: ""               # optional — attribution header
+        # -- dashscope (Alibaba; refs only on wan2.7 models) --
+        DASHSCOPE_API_KEY: ""              # required for dashscope
+        DASHSCOPE_IMAGE_MODEL: ""          # optional — default qwen-image-2.0-pro
+        DASHSCOPE_BASE_URL: ""             # optional — default https://dashscope.aliyuncs.com
+        # -- zai (Z.AI / bigmodel.cn; refs unsupported) --
+        ZAI_API_KEY: ""                    # or BIGMODEL_API_KEY — either one enables zai
+        BIGMODEL_API_KEY: ""
+        ZAI_IMAGE_MODEL: ""                # optional — default glm-image
+        BIGMODEL_IMAGE_MODEL: ""
+        ZAI_BASE_URL: ""                   # optional — default https://api.z.ai/api/paas/v4
+        BIGMODEL_BASE_URL: ""
+        # -- minimax (image-01; refs via subject_reference, jpg/png <10MB) --
+        MINIMAX_API_KEY: ""                # required for minimax
+        MINIMAX_IMAGE_MODEL: ""            # optional — default image-01
+        MINIMAX_BASE_URL: ""               # optional — default https://api.minimaxi.com
+        # -- replicate (hosted model surface; prediction polling) --
+        REPLICATE_API_TOKEN: ""            # replicate.com/account/api-tokens — required for replicate
+        REPLICATE_IMAGE_MODEL: ""          # optional — default google/nano-banana-2
+        REPLICATE_BASE_URL: ""             # optional — default https://api.replicate.com
+        # -- jimeng (Volcengine; BOTH key halves required, HMAC-signed) --
+        JIMENG_ACCESS_KEY_ID: ""           # required for jimeng (with the secret key)
+        JIMENG_SECRET_ACCESS_KEY: ""       # required for jimeng (with the access key)
+        JIMENG_IMAGE_MODEL: ""             # optional — default jimeng_t2i_v40
+        JIMENG_REGION: ""                  # optional — default cn-north-1
+        JIMENG_BASE_URL: ""                # optional — default https://visual.volcengineapi.com
+        # -- seedream (ByteDance Ark; key is ARK_API_KEY, not SEEDREAM_*) --
+        ARK_API_KEY: ""                    # required for seedream
+        SEEDREAM_IMAGE_MODEL: ""           # optional — default doubao-seedream-5-0-260128
+        SEEDREAM_BASE_URL: ""              # optional — default https://ark.cn-beijing.volces.com/api/v3
+        # -- azure (Azure OpenAI; model is addressed by deployment name) --
+        AZURE_OPENAI_API_KEY: ""           # required for azure
+        AZURE_OPENAI_BASE_URL: ""          # required resource endpoint, e.g. https://<res>.openai.azure.com
+        AZURE_OPENAI_DEPLOYMENT: ""        # deployment hosting a gpt-image model
+        AZURE_OPENAI_IMAGE_MODEL: ""       # optional — default gpt-image-2
+        AZURE_API_VERSION: ""              # optional — default 2025-04-01-preview
+        # -- agnes (OpenAI-compatible images endpoint) --
+        AGNES_API_KEY: ""                  # required for agnes
+        AGNES_IMAGE_MODEL: ""              # optional — default agnes-image-2.1-flash
+        AGNES_BASE_URL: ""                 # optional — default https://apihub.agnes-ai.com/v1
+        # -- codex-cli (subprocess; NEVER auto-selected — pin explicitly) --
+        BAOYU_CODEX_IMAGEGEN_BIN: ""           # optional — wrapper entrypoint override
+        BAOYU_CODEX_IMAGEGEN_TIMEOUT_MS: ""    # optional — per-call timeout (ms)
+        BAOYU_CODEX_IMAGEGEN_RETRIES: ""       # optional — retry count
+        # -- 0104 R6 runtime seams (behavior, not credentials; placeholder values only) --
+        KK_IMAGE_MAX_IMAGES: ""                # optional — per-run budget cap; default 4 (OPEN for the operator to set)
+        KK_IMAGE_DRY_RUN: ""                   # optional — "1" composes every prompt, selects the provider, spends nothing
   publishings:
     qiita-pub:
       env:
@@ -32,3 +99,16 @@ plugins:
     surfdash-pub:
       env:
         POSTSURFING_BIN: ""    # optional — delete if unused; defaults to `postsurfing` on PATH
+
+# Image-authoring preferences (task 0106) — read by the kk:image-authoring skill,
+# not by the plugin; the plugin sees only the resolved winners in its --in envelope.
+# Precedence: arguments > environment (KK_IMAGE_*) > this block > compiled defaults.
+# Credentials never live here — see plugins.generations.image-gen.env above.
+image:
+  format: free            # default --format
+  style: ~                # ~ = use the format's defaultStyle
+  provider: ~             # ~ = auto (0103 AUTO_ORDER)
+  model: ~
+  auto_confirm: false     # baoyu's quick_mode, renamed to say what it does
+  max_images: 4           # mirrors KK_IMAGE_MAX_IMAGES (0104)
+  preset_path: ~          # extra roots, ':'-separated → KK_IMAGE_PRESET_PATH

package/plugins/kk/skills/image-authoring/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: image-authoring
+description: >-
+  Use the image-authoring skill to generate images — "generate an image",
+  "create a cover for this article", "illustrate this article", "make a hero
+  image", "extract a style from this reference image", "clone this look",
+  "list the image formats and styles". Three operations — generate,
+  extract-style, list-presets — over named format and style presets, with a
+  confirmation gate before any paid generation.
+---
+
+# image-authoring — image generation agent surface (generate | extract-style | list-presets)
+
+## Purpose
+
+Turn an operator request into **generated or derived image artefacts** by driving the
+deterministic `kk:image-gen` generator plugin. One fat skill with three operations —
+`generate` (default), `extract-style`, `list-presets` — sharing one invocation contract,
+`--in` envelope, preference chain and confirmation policy. The job is not an operation:
+it is **data** — each format preset declares its own `job` field
+(0102), and `--format` selects the work. This is the `audio-authoring` shape applied to
+a job axis that lives in YAML.
+
+**The judgment line — the plugin executes a decided plan; this skill decides it.** The
+plugin (`plugins/generations/image-gen/`) is deterministic: preset resolution and
+shadowing, prompt composition, provider selection and the API call, artefact naming and
+writing, and markdown insertion at a given anchor. Everything needing reading, taste or
+ambiguity resolution is **this skill's**: deriving `--var` values from an article (title,
+subtitle, topics), style auto-detection, illustration **position detection**, caption and
+alt-text authoring, style extraction from reference images, preference precedence
+resolution, and spend approval. The skill's single output to the engine is the `--in`
+envelope; nothing model-shaped ever crosses it.
+
+## When to use
+
+- A user asks for an image: a free-form picture from a prompt, a cover for an article,
+  or illustrations inserted into an article body.
+- A user hands over reference images wanting the look captured as a reusable style
+  preset, or asks what formats and styles exist.
+- A workflow `agent.run` step needs one image job non-interactively (Confirmation
+  policy — the node must set `KK_NONINTERACTIVE=1`).
+
+## Do not use this skill for
+
+- Speech or spoken-audio authoring (that is `kk:audio-authoring`).
+- Hand-written programmatic generation: call `kk executor run image-gen` directly with
+  your own `--in` envelope — this skill's value is the deciding, not the spawn.
+- Editing an existing image (image-to-image): regenerate with a tweaked prompt instead.
+- A coordinator subagent over this skill: none is wanted; `/kk:image-generate` is the
+  whole entry surface.
+
+## Operations
+
+### generate (default)
+
+Sequence: **resolve preferences** (Preference chain) → **resolve the format** →
+**validate arguments** → **decide the work** → **confirm** (Confirmation policy) →
+**preview** (`KK_IMAGE_DRY_RUN=1`) → **paid run** → **report**.
+
+1. Resolve the format preset from `--format` and read its `job` field — that is the
+   branch. Never hardcode format names: an operator-authored format must work with
+   zero edits here (its `job` field is the only fact the skill needs).
+2. If the `job` value is one of the branches below, proceed. Anything else: **stop,
+   name the unimplemented branch and the format**, and never fall back to `free`.
+   - `free` — the positional prompt is the subject; no `--content` needed.
+   - `cover` — read `--content` and derive the format's template variables from the
+     article (title, subtitle, topics) — model work, this skill's — into `vars`.
+   - `illustration` — detect insertion positions and author captions per
+     [references/illustration-positions.md](references/illustration-positions.md);
+     the chosen anchors cross as `metadata.positions`, one image per anchor.
+3. Resolve the style: `--style`, else the preference `image.style`, else the format's
+   `defaultStyle`. Without an explicit choice the skill may propose an auto-detected
+   style — taste, this skill's — shown in the preview for approval.
+4. Resolve the provider and model per Preference chain; the credential and
+   reference-image facts per provider live in
+   [references/providers.md](references/providers.md).
+5. Write the `--in` envelope (Artifact contract), then follow the Confirmation policy.
+6. Report the `--out` path, every artefact, and for illustration the captions.
+   `--dry-run` stops after the preview and reports the composed prompt.
+
+### extract-style
+
+Requires `--ref` (one to five images). **Authoritative procedure:
+[references/style-extraction.md](references/style-extraction.md)** — read it first; it
+owns the schema-fill rules, the multi-image merge rules, the cap-5 refusal wording,
+where the preset is written (user root, shadowing by design), and the validation step:
+read the images with your own vision, write `~/.config/kk/image-presets/styles/<name>.yaml`
+filling exactly the `StylePreset` fields, then validate with a `KK_IMAGE_DRY_RUN=1` run
+whose `style` is the new preset's name. Extraction never writes a `formats/*.yaml` —
+a format is not recoverable from a picture.
+
+### list-presets
+
+Enumerate the **real** preset roots the 0102 loader scans — builtin
+(`plugins/generations/image-gen/presets/`), then `~/.config/kk/image-presets/`, then
+`$KNOWLEDGE_KIT_PROJECT_ROOT/.kk/image-presets/`, then each `:`-separated
+`KK_IMAGE_PRESET_PATH` entry — printing every format and style with its **origin
+root**, plus (formats) `job`, `aspectRatio`, `defaultStyle`. Surface the loader's
+diagnostics verbatim: `shadowed` names **both** paths (losing shipped file, winning
+user file); `invalid` names the file and the schema violation. **Never read a shipped
+markdown gallery** — no gallery exists; the roots are the one source of truth. This
+output is also the text an unknown `--format`/`--style` refusal quotes.
+
+## Invocation contract
+
+`$ARGUMENTS` (or the Skill call args) parse as:
+
+```
+[prompt] [--format <name>] [--style <name>] [--var KEY=VALUE]... [--content <file>]
+         [--ref <path>]... [--count <n>] [--provider <name>] [--model <id>]
+         [--out <dir|file>] [--dry-run] [--list-presets] [--extract-style <name>]
+```
+
+| Token | Meaning | Default |
+| --- | --- | --- |
+| `prompt` | free-form subject text | required for `free`; optional otherwise |
+| `--format <name>` | format preset; its `job` field selects the branch | `image.format`, else `free` |
+| `--style <name>` | style preset | format's `defaultStyle` |
+| `--var KEY=VALUE` | template variable (repeatable) | preset `variables` defaults |
+| `--content <file>` | markdown source for `cover` / `illustration` | none |
+| `--ref <path>` | reference image (repeatable, **max 5**) | none |
+| `--count <n>` | images to produce — **`illustration` job only** | number of `positions` anchors, else 1 |
+| `--provider <name>` | 0103 provider name | auto (`AUTO_ORDER`) |
+| `--model <id>` | provider model id | provider default |
+| `--out <dir\|file>` | the plugin's `--out`; see Artifact contract | temp dir under the works dir |
+| `--dry-run` | compose and price, generate nothing | off |
+| `--list-presets` | → the `list-presets` operation | — |
+| `--extract-style <name>` | → the `extract-style` operation; **requires `--ref`** | — |
+
+**Validation is this skill's, before any plugin spawn**, each refusal naming the
+offending argument: unknown `--format` or `--style` (quote what `list-presets` would
+show); `--count` on a non-`illustration` job; more than five `--ref` paths;
+`--extract-style` without `--ref`; a `--content` file that does not exist. Flags the
+wt plugin retired are **answered, not ignored** — state the replacement and stop; the
+table lives in
+[references/migrating-from-wt.md](references/migrating-from-wt.md)
+(`--template` → `--format`, `--resolution WxH` → the format's `aspectRatio`,
+`--backend` → `--provider`, `--list-templates` → `--list-presets`).
+
+## Artifact contract
+
+The skill writes exactly one input file — the `--in` JSON: a `Doc[]` whose **first
+element** carries the whole job spec at `metadata.imageGen` (strict schema; a typo'd
+key fails loud), plus `metadata.positions` for the illustration job:
+
+```json
+[{
+  "id": "doc-1", "title": "Article title", "body": "<article text>",
+  "metadata": {
+    "imageGen": {
+      "job": "cover", "format": "cover", "style": "vibrant",
+      "provider": "seedream", "model": "doubao-seedream-5-0-260128",
+      "vars": { "title": "Article title", "subtitle": "Derived subtitle" },
+      "maxImages": 4, "outputStem": "article-title"
+    },
+    "positions": ["## A heading that occurs exactly once in the body"]
+  }
+}]
+```
+
+| Path | Rule |
+| --- | --- |
+| `--out` ending `.json` | used verbatim as the plugin's `--out` |
+| `--out` anything else | treated as a directory; the plugin's `--out` becomes `<dir>/content.json` |
+| generated images | **siblings** of `--out` (0104), named from the format's `outputFilename` |
+| output `metadata.images[]` | one entry per image: absolute `path`, `format`, `style`, `provider`, `model`, the exact `prompt`, `bytes` |
+| output `metadata.captions[]` | illustration only: `{index, path, caption, altText, anchor}` |
+
+`metadata.imageGen` accepts only: `job`, `format`, `style`, `vars`, `extra`, `provider`,
+`model`, `referenceImages`, `count`, `maxImages`, `seed`, `outputStem`. **No credential
+is ever written into this file** — see Preference chain.
+
+## Preference chain
+
+Every preference resolves through the repo's frozen order — **arguments >
+environment > `$KK_CONFIG` > compiled defaults** — and the winners are written into
+`metadata.imageGen`:
+
+| Key | 1. argument | 2. environment | 3. `$KK_CONFIG` `image:` | 4. compiled default |
+| --- | --- | --- | --- | --- |
+| format | `--format` | — | `image.format` | `free` |
+| style | `--style` | — | `image.style` | the format's `defaultStyle` |
+| provider | `--provider` | `IMAGE_GEN_PROVIDER` | `image.provider` | auto (`AUTO_ORDER`) |
+| model | `--model` | — | `image.model` | provider default |
+| auto-confirm | — | `KK_IMAGE_AUTO_CONFIRM=1` | `image.auto_confirm` | `false` |
+| max images | — | `KK_IMAGE_MAX_IMAGES` | `image.max_images` | `4` |
+| preset roots | — | `KK_IMAGE_PRESET_PATH` | `image.preset_path` | none |
+
+- `$KK_CONFIG` defaults to `~/.config/kk/config.yaml`. The environment **wins over the
+  config file**: an exported `KK_IMAGE_MAX_IMAGES` beats `image.max_images`.
+- Loading is **non-blocking**: a missing or malformed `image:` block earns **one
+  notice line naming the block**, then the compiled defaults. Every key has a working
+  default; refusing to draw over a missing optional config is a worse failure than
+  drawing with defaults. (A malformed *preset* is a different matter and fails loud.)
+- **No `EXTEND.md`** — do not read, create, or mention one: baoyu's ranks file above
+  environment, the opposite of this chain, and one product gets one precedence rule.
+- **Credentials are not in this chain.** `plugins.generations.image-gen.env` values
+  reach the plugin only through `invoke.ts`'s process environment at spawn. They never
+  enter this skill's context, the `--in` file, or any report.
+
+## Confirmation policy
+
+The skill is in exactly one of two contexts, signalled **explicitly**:
+`KK_NONINTERACTIVE=1` means non-interactive. Never infer from a TTY probe — a wrong
+guess is either a hang or an unapproved spend.
+
+**Interactive** (default). Before any paid run: execute once with `KK_IMAGE_DRY_RUN=1`,
+then present the **spend preview** — resolved format and style, provider and model,
+image count, and the **composed prompt taken from that run's `Content.body`** (the real
+string the provider will receive, not a reconstruction) — and ask **once** for
+confirmation (`AskUserQuestion` where available). `--dry-run` stops here and reports.
+Declining ends the run with no plugin spawn beyond the dry run. A modification request
+re-runs the preview; the loop is bounded at **3 revision rounds**, after which state
+the bound and ask the operator to restate the request — never a paid round.
+
+**Non-interactive** (`KK_NONINTERACTIVE=1`, e.g. a `spur workflow` `agent.run` step).
+**Never prompt — never emit a question.** Proceed only if `image.auto_confirm: true`
+or `KK_IMAGE_AUTO_CONFIRM=1`; otherwise **fail immediately, naming both switches**.
+Hanging is unrecoverable, and spending unapproved money is worse than a failed node.
+A workflow node invoking this skill **must set `KK_NONINTERACTIVE=1`** (and choose its
+auto-confirm switch) — that is the caller's contract.
+
+The cap is the backstop under both paths: `maxImages` rides the envelope and the
+plugin refuses before the first provider call (0104 R6). Confirmation is a courtesy;
+the cap is the control.
+
+## Failure and recovery
+
+- **Unknown format/style** — refuse, listing what `list-presets` shows.
+- **Unimplemented `job` branch** — stop, naming the branch and format; never fall back
+  to `free`.
+- **Malformed preset** — the 0102 loader's `invalid` diagnostic names the file and the
+  schema violation; the dry run fails loud before any spend. Fix or delete the file.
+- **Provider cannot accept `--ref`** — when `supportsReferenceImages(model)` is false,
+  say so and offer `extract-style`; never silently drop a reference.
+- **Declined confirmation** — end cleanly; only the dry run ran, nothing was spent.
+- **Failed run** — the plugin deletes `--out` and every artefact of that run before
+  rethrowing; report the error verbatim and stop.
+- **No credential anywhere** — name the provider and the env var it needs
+  (references/providers.md); never solicit a secret in chat.
+
+## References
+
+- [references/style-extraction.md](references/style-extraction.md) — `extract-style` (0105): schema-fill rules, merge rules, cap, fidelity check.
+- [references/illustration-positions.md](references/illustration-positions.md) —
+  position detection and caption authoring for `illustration`, with the wt example.
+- [references/providers.md](references/providers.md) — the operator digest of 0103's
+  provider inventory: env vars, default models, reference capability, auto order.
+- [references/migrating-from-wt.md](references/migrating-from-wt.md) — the retired wt
+  flags and their frozen replacements.

package/plugins/kk/skills/image-authoring/references/illustration-positions.md

@@ -0,0 +1,87 @@
+# Illustration positions and captions
+
+Loaded by the image-authoring skill when the resolved format's `job` is
+`illustration`. Position detection, concept prompts and caption authoring are
+**model work** — this file's — while the plugin does the deterministic half:
+composing one prompt per anchor (the anchor rides the format's `concept`
+template variable), generating, and inserting the markdown at the anchor. The
+skill's entire output across this boundary is `metadata.positions` in the
+`--in` envelope.
+
+## The anchor contract
+
+- `metadata.positions` is an **array of anchor strings**, one per illustration.
+- Each anchor must occur **exactly once** in the doc `body` — the plugin
+  inserts at that occurrence and fails loud if it is absent or ambiguous.
+  Headings and distinctive sentences are safe anchors; short common phrases
+  are not.
+- The array length is the image count: `--count` must equal it, and each
+  anchor is fed as image *i*'s `concept` var (`plugins/generations/image-gen/src/index.ts`
+  composes one prompt per anchor in array order).
+- The budget still applies: the default cap is 4 images (`maxImages`); a
+  longer article does not silently spend past it.
+
+## Detection procedure
+
+Read the article once, end to end, then list **candidate** positions before
+selecting. For each candidate record: line/section, **type**, a 0–12 **score**,
+and a one-line rationale. The wt taxonomy, kept because it works:
+
+| Type | Looks like | Typical score driver |
+| --- | --- | --- |
+| abstract concept | jargon-dense section with no visual ("microservices architecture", "service discovery") | technical-jargon density |
+| information dense | wide tables, long parameter lists | structure that a diagram would organise |
+| emotional transition | major section break, shift in narrative register | flow improvement |
+
+Selection rules (the wt defaults, kept): prefer higher score; keep at least
+~20 lines between chosen positions; respect the operator's `--count` as the
+maximum; spread across types rather than clustering on one. Fewer, better
+placements beat filling the quota.
+
+For each **selected** position, author in the same pass:
+
+1. **Anchor** — the exactly-once string from the body.
+2. **Concept** — a one-sentence visual brief; the plugin feeds it to the
+   format's `concept` variable, so write it as an image subject, not prose
+   about the article.
+3. **Caption and alt text** — the caption states what the image adds; the alt
+   text describes the image for a screen reader (complete sentence, no "image
+   of"). These are reported to the operator against each artefact path.
+4. **Style** — default to the resolved style; `technical-diagram` suits
+   concepts and dense reference content, `sketch` suits data relationships,
+   `minimalist` suits transitions. A proposal, shown in the preview — the
+   operator confirms the whole spend once.
+
+## Worked example (from the wt plugin, the prior art)
+
+Input: `article-before.md`, a 1,850-word microservices guide with no images.
+Detection found **8 candidates, selected 5** (two dropped for sitting too
+close to a higher-scoring neighbour, one for low score):
+
+| # | Line | Type | Score | Selected |
+| --- | --- | --- | --- | --- |
+| 1 | 23 | abstract concept ("What Are Microservices?") | 12 | yes |
+| 2 | 45 | abstract concept (service discovery) | 11 | yes |
+| 3 | 62 | information dense (7-column API table) | 10 | yes |
+| 4 | 79 | abstract concept (communication patterns) | 10 | no — too close to #3 |
+| 5 | 92 | information dense (configuration list) | 11 | yes |
+| 6 | 112 | emotional transition ("Best Practices") | 7 | yes |
+| 7 | 128 | abstract concept | 8 | no — below the line |
+
+The chosen anchors became `metadata.positions`; image *i*'s anchor was fed as
+its `concept` — e.g. position 1's concept, "Microservices architecture pattern
+with API gateway", produced a technical-diagram prompt, and the caption
+reported back as alt text: "Diagram showing microservices architecture with
+API gateway, independent services with databases, and message queue
+communication". The output side is `article-after.md` — the same article with
+`![alt](path)` references at the anchors — plus the captions payload the
+plugin emits at `metadata.captions[]` (`{index, path, caption, altText,
+anchor}`), which is what the skill reports to the operator.
+
+## What this file never does
+
+- No detection inside the plugin — the plugin never reads for meaning; it
+  only inserts where told.
+- No image selection after the fact — positions are decided **before** the
+  confirmation preview, so the operator approves the whole spend knowingly.
+- No caption writing inside the plugin — captions are the skill's voice.

package/plugins/kk/skills/image-authoring/references/migrating-from-wt.md

@@ -0,0 +1,31 @@
+# Migrating from the wt image commands
+
+For operators arriving from the `wt` plugin (`/wt:image-generate` and its
+three skills). The kk surface is **one command** (`/kk:image-generate`)
+driving **one skill** (`kk:image-authoring`). Flag by flag:
+
+| wt flag | kk replacement | Why |
+| --- | --- | --- |
+| `--template <name>` | `--format <name>` | Templates are formats now — data presets (0102). wt's `default` → `free`; `cover` → `cover`; `illustrator` → `illustration`. A custom template like `cover-xhs` becomes a YAML file in `~/.config/kk/image-presets/formats/` — no skill or plugin edit needed. |
+| `--resolution WxH` | *(dropped)* | The format's `aspectRatio` owns dimensions (0102 R1) — a portable ratio beats per-call pixels across twelve providers. A different shape means a different or overridden format. |
+| `--backend <name>` | `--provider <name>` | 0103's inventory replaces wt's three backends: `gemini` → `google`; `nano_banana` → `replicate`; `huggingface` has no kk equivalent. Omitting `--provider` auto-selects (see providers.md). |
+| `--list-templates` | `--list-presets` | Lists formats **and** styles from the real preset roots, with origin and shadowing diagnostics. |
+| `--output <path>` | `--out <dir\|file>` | A path ending `.json` is used verbatim; anything else is a directory, and generated images land as its siblings. |
+
+Kept, unchanged in meaning: the positional prompt, `--style`,
+`--var KEY=VALUE`, `--content <file>`.
+
+Also different, by design:
+
+- The command validates nothing — the skill does. Thinner command, same
+  refusals, one place that knows the rules.
+- The three wt skills' model work (content analysis, style auto-detection,
+  position detection) lives inside this one skill as named capabilities, not
+  three skills.
+- The `wt:image-generator` coordinator subagent is deliberately **not
+  ported** — a forwarder over a single skill is an indirection with nothing
+  in it.
+- Spend control: kk previews the real prompt via a `KK_IMAGE_DRY_RUN=1` run
+  and asks once before the paid run; workflow nodes must set
+  `KK_NONINTERACTIVE=1`. The wt `--resolution`-style per-call budget has no
+  equivalent — `maxImages` (env/config) is the cap.

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.