@gobing-ai/knowledge-kit 0.1.11 → 0.1.12

package/plugins/generations/image-gen/scripts/gen-samples.ts

@@ -0,0 +1,208 @@
+/**
+ * Preset sample gallery (task 0340): render one sample per shipped format × style
+ * pair into assets/sample/ and regenerate README.md as the index over them.
+ *
+ * Usage (run from the repo root so `kk` resolves this checkout's plugin):
+ *   bun plugins/generations/image-gen/scripts/gen-samples.ts                 # render missing pairs + README
+ *   bun plugins/generations/image-gen/scripts/gen-samples.ts --force         # re-render every pair
+ *   bun plugins/generations/image-gen/scripts/gen-samples.ts --readme-only   # README from samples on disk
+ *   bun plugins/generations/image-gen/scripts/gen-samples.ts --provider gemini --model <m>
+ *
+ * Only the builtin presets/ root is read — user/project preset roots never leak
+ * into the shipped index. A finished sample is never overwritten without --force,
+ * so a run that dies on pair 37 resumes from pair 37. Failed pairs are named and
+ * the script exits 1.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { type FormatPreset, FormatPresetSchema, type StylePreset, StylePresetSchema } from '../src/presets';
+
+const PLUGIN_DIR = join(import.meta.dir, '..');
+const SAMPLE_DIR = join(PLUGIN_DIR, 'assets', 'sample');
+const README = join(PLUGIN_DIR, 'README.md');
+const WORK_DIR = join(process.cwd(), '.works', 'tmp', 'test-samples');
+const THUMB_PX = 640;
+const CONCURRENCY = 3;
+
+/** Fixed per-job inputs so every style is compared on the same subject. */
+const SAMPLE_SUBJECT = 'a request flowing through an API gateway to three microservices';
+const COVER_VARS = {
+    title: 'Building Reliable AI Agents',
+    subtitle: 'Patterns for production',
+    topics: 'AI agents',
+};
+
+const args = process.argv.slice(2);
+const flag = (name: string): boolean => args.includes(name);
+const option = (name: string, fallback: string): string => {
+    const index = args.indexOf(name);
+    return index >= 0 && args[index + 1] !== undefined ? args[index + 1] : fallback;
+};
+const provider = option('--provider', 'minimax');
+const model = option('--model', 'image-01');
+
+function loadBuiltin<T>(axis: string, schema: { parse(value: unknown): T }): T[] {
+    const dir = join(PLUGIN_DIR, 'presets', axis);
+    return readdirSync(dir)
+        .filter((entry) => entry.endsWith('.yaml'))
+        .sort()
+        .map((entry) => schema.parse(Bun.YAML.parse(readFileSync(join(dir, entry), 'utf8'))));
+}
+
+const formats = loadBuiltin<FormatPreset>('formats', FormatPresetSchema);
+const styles = loadBuiltin<StylePreset>('styles', StylePresetSchema);
+const sampleName = (format: string, style: string): string => `${format}__${style}.jpg`;
+
+/** The Doc envelope that drives one pair through the real executor. */
+function envelope(format: FormatPreset, style: StylePreset): unknown[] {
+    const imageGen: Record<string, unknown> = {
+        job: format.job,
+        format: format.name,
+        style: style.name,
+        provider,
+        model,
+    };
+    const doc: Record<string, unknown> = { id: `${format.name}__${style.name}`, title: COVER_VARS.title, body: '' };
+    if (format.job === 'cover') {
+        imageGen.vars = COVER_VARS;
+    } else if (format.job === 'illustration') {
+        // The anchor must occur exactly once in the body (index.ts assertAnchorPlan).
+        doc.body = `Every call enters at the edge: ${SAMPLE_SUBJECT}.`;
+        doc.metadata = { positions: [SAMPLE_SUBJECT] };
+    } else if (format.compose !== undefined) {
+        imageGen.vars = { subject: SAMPLE_SUBJECT, headline: 'API 网关', points: '统一入口\n鉴权限流\n路由转发' };
+    } else {
+        imageGen.vars = { subject: SAMPLE_SUBJECT };
+    }
+    doc.metadata = { ...((doc.metadata as object) ?? {}), imageGen: { ...imageGen, maxImages: 1 } };
+    return [doc];
+}
+
+async function render(format: FormatPreset, style: StylePreset): Promise<void> {
+    const stem = `${format.name}__${style.name}`;
+    const dir = join(WORK_DIR, stem);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(dir, { recursive: true });
+    const input = join(dir, 'in.json');
+    const output = join(dir, 'out.json');
+    await Bun.write(input, JSON.stringify(envelope(format, style)));
+    const run = Bun.spawn(['kk', 'executor', 'run', 'image-gen', '--in', input, '--out', output], {
+        stdout: 'pipe',
+        stderr: 'pipe',
+    });
+    const [code, stderr] = await Promise.all([run.exited, new Response(run.stderr).text()]);
+    if (code !== 0) {
+        throw new Error(`kk exited ${code}: ${stderr.trim().split('\n').slice(-3).join(' | ')}`);
+    }
+    const image = (await Bun.file(output).json())?.metadata?.images?.[0]?.path as string | undefined;
+    if (image === undefined) {
+        throw new Error('executor output carries no metadata.images[0].path');
+    }
+    const source = image.startsWith('/') ? image : join(dir, image);
+    // ponytail: macOS sips does the downscale (no image dep in the repo); add sharp if this must run on Linux.
+    const sips = Bun.spawnSync([
+        'sips',
+        '-Z',
+        String(THUMB_PX),
+        '-s',
+        'format',
+        'jpeg',
+        '-s',
+        'formatOptions',
+        '80',
+        source,
+        '--out',
+        join(SAMPLE_DIR, sampleName(format.name, style.name)),
+    ]);
+    if (sips.exitCode !== 0) {
+        throw new Error(`sips failed: ${sips.stderr.toString().trim()}`);
+    }
+}
+
+async function renderAll(): Promise<string[]> {
+    mkdirSync(SAMPLE_DIR, { recursive: true });
+    const queue = formats.flatMap((format) =>
+        styles
+            .filter((style) => flag('--force') || !existsSync(join(SAMPLE_DIR, sampleName(format.name, style.name))))
+            .map((style) => ({ format, style })),
+    );
+    console.log(`${queue.length} of ${formats.length * styles.length} pairs to render via ${provider}/${model}`);
+    const failed: string[] = [];
+    const worker = async (): Promise<void> => {
+        for (let pair = queue.shift(); pair !== undefined; pair = queue.shift()) {
+            const name = `${pair.format.name} × ${pair.style.name}`;
+            try {
+                await render(pair.format, pair.style);
+                console.log(`ok   ${name}`);
+            } catch (error) {
+                failed.push(name);
+                console.error(`FAIL ${name}: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: CONCURRENCY }, worker));
+    return failed;
+}
+
+const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim().replace(/\|/g, '\\|');
+
+function readme(): string {
+    const lines = [
+        '# image-gen',
+        '',
+        'Image generation plugin (`kind: generator`): `free`, `cover` and `illustration` jobs over the',
+        '`Doc[] → Content` contract. Every image is one **format** (canvas, template, job) composed with one',
+        '**style** (visual modifiers); any format pairs with any style.',
+        '',
+        'This page is the preset index: one sample per shipped format × style pair, so you can pick a',
+        'combination by eye. Pass the pair as `metadata.imageGen.format` / `metadata.imageGen.style`, or',
+        "`--format` / `--style` to the `kk:image-generate` skill. Omitting the style uses the format's",
+        'default (★ below).',
+        '',
+        `Samples: provider \`${provider}\`, model \`${model}\`, downscaled to ${THUMB_PX}px JPEG. Inputs are fixed per`,
+        `job — subject “${SAMPLE_SUBJECT}”; cover title “${COVER_VARS.title}”. Regenerate with`,
+        '`bun plugins/generations/image-gen/scripts/gen-samples.ts` (see its header for flags).',
+        '',
+        '## Formats',
+        '',
+        '| Format | Job | Aspect | Size | Default style | Description |',
+        '| --- | --- | --- | --- | --- | --- |',
+        ...formats.map(
+            (f) =>
+                `| [\`${f.name}\`](#format-${f.name}) | ${f.job} | ${f.aspectRatio} | ${f.width ?? '?'}×${f.height ?? '?'} | ${f.defaultStyle} | ${oneLine(f.description)} |`,
+        ),
+        '',
+        '## Styles',
+        '',
+        '| Style | Description | Best for |',
+        '| --- | --- | --- |',
+        ...styles.map((s) => `| \`${s.name}\` | ${oneLine(s.description)} | ${oneLine(s.bestFor ?? '')} |`),
+        '',
+        '## Gallery',
+    ];
+    const columns = 3;
+    for (const format of formats) {
+        lines.push('', `<a id="format-${format.name}"></a>`, '', `### ${format.name}`, '');
+        lines.push(`${format.job} job · ${format.aspectRatio} · default style \`${format.defaultStyle}\``, '');
+        lines.push(`|${' |'.repeat(columns)}`, `|${' --- |'.repeat(columns)}`);
+        for (let i = 0; i < styles.length; i += columns) {
+            const cells = styles.slice(i, i + columns).map((style) => {
+                const file = sampleName(format.name, style.name);
+                const label = `\`${style.name}\`${style.name === format.defaultStyle ? ' ★' : ''}`;
+                return existsSync(join(SAMPLE_DIR, file))
+                    ? `<img src="assets/sample/${file}" alt="${format.name} × ${style.name}" width="260"><br>${label}`
+                    : `_not rendered_<br>${label}`;
+            });
+            lines.push(`| ${cells.join(' | ')} |`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+
+const failed = flag('--readme-only') ? [] : await renderAll();
+await Bun.write(README, readme());
+console.log(`wrote ${README}`);
+if (failed.length > 0) {
+    console.error(`${failed.length} pair(s) failed — rerun to retry only those:\n  ${failed.join('\n  ')}`);
+    process.exit(1);
+}

package/plugins/generations/image-gen/src/compose/chromium.ts

@@ -11,9 +11,8 @@
  * Playwright's pipe under Bun 1.3.14 stalls intermittently (fulfill never
  * returns, `document.fonts.ready` never settles — 0212 dogfood, ~1 in 3 runs).
  *
- * The E2E test still skips under `bun test` (Playwright's launch blocks that
- * runner's event loop); the evidence script runs each variant pair in its own
- * subprocess. `compose` carries a deadline as the backstop for any other stall.
+ * The E2E test runs inside `bun test` on Bun 1.4.3 (the 1.3.14 launch block is
+ * gone). `compose` carries a deadline as the backstop for any other stall.
  *
  * Missing Playwright or Chromium surfaces as an actionable error naming the
  * install command.

package/plugins/generations/image-gen/src/presets.ts

@@ -187,7 +187,9 @@ function matchPlaceholder(template: string, start: number): { expr: string; end:
 
 /**
  * Resolve one expression against the merged vars. An empty value (including
- * a caller-passed '') resolves to the fallback; an unknown placeholder with
+ * a caller-passed '') resolves to the fallback, except a wrapper fallback
+ * (one embedding its own `{{name}}`), which drops out entirely so its literal
+ * slot never reaches the provider; an unknown placeholder with
  * no fallback throws, naming the placeholder and the format — wt silently
  * left it in place, and a literal `{{title}}` must not reach a paid provider.
  * Leading trim on the fallback skips the `| ` separator; its trailing space
@@ -200,13 +202,14 @@ function resolvePlaceholder(expr: string, vars: Record<string, string>, formatNa
         const name = expr.slice(0, pipe).trim();
         const fallback = expr.slice(pipe + 1).trimStart();
         const value = vars[name];
+        const slot = `{{${name}}}`;
         if (!value) {
-            return fallback;
+            return fallback.includes(slot) ? '' : fallback;
         }
         // A fallback that embeds its own '{{name}}' slot is a mini-template
         // wrapping the value (the R6 golden's ', subtitled "…"' form); a
         // plain-text fallback is just the default, so the value wins.
-        return fallback.includes(`{{${name}}}`) ? fallback.split(`{{${name}}}`).join(value) : value;
+        return fallback.includes(slot) ? fallback.split(slot).join(value) : value;
     }
     const name = expr.trim();
     const value = vars[name];

package/plugins/generations/image-gen/src/providers/errors.ts

@@ -24,6 +24,16 @@
 /** The retry decision classes the D6 fallback loop (0166) acts on. */
 export type ProviderErrorClass = 'auth' | 'quota' | 'transient' | 'policy' | 'unknown';
 
+/** MiniMax business codes are not HTTP statuses; messages may be only "system error". */
+export function minimaxErrorClass(code: number): ProviderErrorClass {
+    // https://platform.minimax.io/docs/api-reference/errorcode
+    if ([1026, 1027, 1040, 1046].includes(code)) return 'policy';
+    if ([1004, 2049].includes(code)) return 'auth';
+    if ([1002, 1008, 1039, 1045, 2056].includes(code)) return 'quota';
+    if ([1000, 1001, 1024, 1033].includes(code)) return 'transient';
+    return 'unknown';
+}
+
 /** Content-policy / safety / moderation rejections — checked first, they often arrive as 400/403. */
 const POLICY_RE = /content[_ -]?policy|moderation|safety|sensitive|inappropriate|violat|blocked/i;
 /** Credential wording; 401/403 statuses are checked separately. */
@@ -69,7 +79,12 @@ function partsOf(err: unknown): { readonly name: string; readonly message: strin
 export function classifyProviderError(err: unknown): ProviderErrorClass {
     const parts = partsOf(err);
     const statuses = statusesIn(parts.message);
-    if (POLICY_RE.test(parts.message)) return 'policy';
+    const miniCode = /^MiniMax API error \(status_code=(\d+)\):/.exec(parts.message)?.[1];
+    const miniClass = miniCode === undefined ? 'unknown' : minimaxErrorClass(Number(miniCode));
+    if (miniClass === 'policy' || POLICY_RE.test(parts.message)) return 'policy';
+    // An explicit business code owns retry semantics; e.g. invalid params (2013) must not
+    // become transient merely because its description contains the word "timeout".
+    if (miniCode !== undefined) return miniClass;
     if (statuses.some((status) => status === 401 || status === 403) || AUTH_RE.test(parts.message)) return 'auth';
     if (statuses.some((status) => status === 402 || status === 429) || QUOTA_RE.test(parts.message)) return 'quota';
     if (

package/plugins/generations/image-gen/src/providers/minimax.ts

@@ -1,5 +1,8 @@
 import { Buffer } from 'node:buffer';
+import { setTimeout as delay } from 'node:timers/promises';
+import { echoError } from '@gobing-ai/ts-utils';
 import { readBytes } from '../bytes';
+import { classifyProviderError } from './errors';
 import { mimeForPath } from './refs';
 import { PROVIDER_REQUEST_TIMEOUT_MS } from './timeouts';
 import type { ImageProvider, ImageRequest, ImageResult, ProviderFactory, ProviderOptions } from './types';
@@ -41,6 +44,13 @@ interface MinimaxResponse {
     };
 }
 
+function responseError(result: MinimaxResponse): Error | null {
+    const code = result?.base_resp?.status_code;
+    return code !== undefined && code !== 0
+        ? new Error(`MiniMax API error (status_code=${code}): ${result.base_resp?.status_msg ?? 'unknown error'}`)
+        : null;
+}
+
 export function parsePixelSize(size: string): { width: number; height: number } | null {
     const match = size.trim().match(/^(\d+)\s*[xX*]\s*(\d+)$/);
     if (match === null) return null;
@@ -126,10 +136,8 @@ export async function extractImageFromResponse(
     fetchFn: typeof fetch = fetch,
     timeoutMs: number = PROVIDER_REQUEST_TIMEOUT_MS,
 ): Promise<Uint8Array> {
-    const baseResp = result.base_resp;
-    if (baseResp?.status_code !== undefined && baseResp.status_code !== 0) {
-        throw new Error(baseResp.status_msg ?? `MiniMax API returned status_code=${baseResp.status_code}`);
-    }
+    const error = responseError(result);
+    if (error !== null) throw error;
     const base64Image = result.data?.image_base64?.[0];
     if (base64Image !== undefined) return Uint8Array.from(Buffer.from(base64Image, 'base64'));
     const url = result.data?.image_urls?.[0];
@@ -167,20 +175,41 @@ export const createMinimax: ProviderFactory = (options?: ProviderOptions): Image
 
             const base = (readEnv('MINIMAX_BASE_URL') || 'https://api.minimaxi.com').replace(/\/+$/g, '');
             const url = base.endsWith('/v1') ? `${base}/image_generation` : `${base}/v1/image_generation`;
-            const response = await fetchFn(url, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
-                body: JSON.stringify(body),
-                signal: AbortSignal.timeout(timeoutMs),
-            });
-            if (!response.ok) {
-                throw new Error(`MiniMax API error (${response.status}): ${await response.text()}`);
+            // One deadline covers all attempts and backoff. Retry only explicit failed responses:
+            // transport errors leave generation outcome ambiguous and must not silently rebill it.
+            const signal = AbortSignal.timeout(timeoutMs);
+            let result: MinimaxResponse;
+            for (let attempt = 1; ; attempt += 1) {
+                signal.throwIfAborted();
+                const response = await fetchFn(url, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+                    body: JSON.stringify(body),
+                    signal,
+                });
+                let error: Error | null;
+                if (response.ok) {
+                    result = (await response.json()) as MinimaxResponse;
+                    error = responseError(result);
+                    if (error === null) break;
+                } else {
+                    const detail = await response.text();
+                    let businessError: Error | null = null;
+                    try {
+                        businessError = responseError(JSON.parse(detail) as MinimaxResponse);
+                    } catch {
+                        // A non-JSON gateway response still carries its HTTP failure class.
+                    }
+                    // Business codes own policy/auth semantics even on a generic HTTP 5xx.
+                    error = businessError ?? new Error(`MiniMax API error (${response.status}): ${detail}`);
+                }
+                if (attempt >= 3 || classifyProviderError(error) !== 'transient') throw error;
+                const delayMs = attempt * 1000;
+                echoError(`WARN image-gen: ${error.message}; retrying MiniMax (${attempt + 1}/3) after ${delayMs}ms`);
+                await delay(delayMs, undefined, { signal });
             }
-            const bytes = await extractImageFromResponse(
-                (await response.json()) as MinimaxResponse,
-                fetchFn,
-                timeoutMs,
-            );
+            // Download errors are outside the POST retry loop: the image already exists.
+            const bytes = await extractImageFromResponse(result, fetchFn, timeoutMs);
             return { bytes, extension: 'jpg', provider: 'minimax', model: req.model };
         },
     };

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

@@ -392,7 +392,7 @@ export async function main(depsOverride?: Partial<SearchDeps>): Promise<number>
                 ...depsOverride,
             };
             // Bun.which with an explicit PATH — without the option it can ignore runtime
-            // process.env.PATH changes (observed on Bun 1.3.14).
+            // process.env.PATH changes (observed on Bun 1.3.14, still true on 1.4.3).
             if (!deps.markitdown && !Bun.which('markitdown', { PATH: deps.env.PATH })) {
                 // R6 — live mode requires the normalizer; fail before any network call.
                 throw new Error('markitdown is not on PATH');

package/plugins/kk/README.md

@@ -28,6 +28,17 @@ Capability files **omit a leading `kk-`**. `superskill install` prefixes the plu
 `storm-research`, `itc-generating`, `explain-things` (via `/tell-me`), and `/workflow-run`. Product workflow YAML (`kk-storm-research.yaml`)
 keeps its existing name — that is a workflow stem, not an installable agent capability.
 
+### Grok Bot
+
+Install: `superskill install kk --targets grok-bot --bot-provides cli:kk --bot-provides local-fs`.
+Add `--bot-provides cli:spur` when the Bot ran the spur bootstrap.
+
+Each skill and command declares a `requires:` list (`hooks`, `subagents`, `local-fs`, `cli:<name>`)
+so the install ships only entries the Bot can run; the guard test is
+`plugins/kk/tests/runtime-requires.test.ts`. Which kk work may actually run in the cloud is decided
+by ADR-044 (`docs/00_ADR.md`): cloud Grok Bot routines are store-free and browser-free —
+anything touching `kk.db` or a browser profile stays Mac-side.
+
 ## Schedule
 
 `spur serve` **hosts the scheduler**: the `.spur/config.yaml` `bootstrap.scheduler` jobs (the daily
@@ -59,6 +70,13 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.gobing.kk-collect.pli
 crontab -l > /tmp/kk-collect.cron 2>/dev/null || :
 kk schedule render kk-collect --platform cron --repo "$PWD" >> /tmp/kk-collect.cron
 crontab /tmp/kk-collect.cron
+
+# Grok Bot cloud routine (ADR-044): prints a routine definition for the store-free kk-collect
+# prefix — the Bot owns preparation, the Mac owns the kk store. Paste the printed text into the
+# Bot's routine editor (creating the routine there is the operator action; kk never calls an API).
+# kk-serve and the publish3 windows are refused on grok-bot: they are store- or browser-bound.
+kk schedule render kk-collect --platform grok-bot --bot kk-cloud --tz "$TZ" \
+  | pbcopy   # then paste into the Bot's routine editor
 ```
 
 Both rendered artifacts set `PATH` themselves (`{{home}}/.bun/bin`, `/opt/homebrew/bin`,

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

@@ -3,6 +3,7 @@ name: image-extract
 description: Extract a reusable style preset (and optionally draft a format preset) from 1-5 reference images, saved to ~/.config/kk/image-presets/ after confirmation.
 argument-hint: "--name <style-name> --ref <img> [--ref <img>…] [--emit-format <name> --job free|cover|illustration]  (max 5 refs)"
 allowed-tools: ["Skill"]
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # image-extract

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

@@ -3,6 +3,7 @@ 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 free|cover|illustration] [--style vibrant|minimalist|photorealistic|technical-diagram|editorial|fresh|warm|cute|sketch|clean-webapp-ui|<custom>] [--content <file>] [--ref <img>…] [--var K=V] [--dry-run] [--list-presets]"
 allowed-tools: ["Skill"]
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 # image-generate

package/plugins/kk/commands/tell-me.md

@@ -3,6 +3,7 @@ name: tell-me
 description: Explain the supplied or current topic with the smallest useful view; use ELI5 only when requested.
 argument-hint: "[topic] [--eli5]"
 allowed-tools: ["Skill"]
+requires: [local-fs]
 ---
 
 # tell-me

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

@@ -7,6 +7,7 @@ description: >-
   creates the config with defaults if missing; computes the workspace; shells
   spur workflow run against the resolved YAML.
 argument-hint: "[name] <topic|--in file> [--dir <path>] [--playbook generic|english|wechat] [--research] [--judge] [--outline <a|b|c>] [--writer itc-generating|topic] [--duration <min>] [--language <code>] [--script-approved] [--fixture] [--force]"
+requires: [cli:kk, cli:spur, local-fs]
 ---
 
 Thin runner around the **storm-research**, **itc-generating** / **topic**, and **kk-solo-podcast**
@@ -223,12 +224,17 @@ stays `false` unless `--live` is passed explicitly (ADR-022). `--playbook wechat
 `cover_enabled` / `inline_images` (`false` unless passed); `--max-revisions` binds
 `max_revisions` (default `2`). Each lands in `itc-options.json` under its camelCase key.
 
+Two var-only child options skip the options snapshot: `outline_bullets_only=true` keeps the
+outline stage to heading-plus-bullets options (no prose paragraphs), and `plan_only=true`
+stops the parent DAG after the confirmed publish plan (no `send-confirm` pause, no fanout-send,
+no recovery, no settle) — a plan preview, not a send.
+
 **Collected topic (`--from-collect <profile>`, 0299).** `itc-prepare` without `--chosen` returns
 an *intake* snapshot (`status: intake`, `workDir: null`). Choose the topic in a run-scoped intake
 dir, then finalize:
 
 1. `kk stage run itc-topic-extract --request` `{parentRunId, intakeDir, topicProfile}` → the pool.
-2. The agent writes `$intakeDir/topic-candidates.json` (≤3 candidates `a|b|c` with
+2. The agent (or `kk itc candidates`) writes `$intakeDir/topic-candidates.json` (≤5 candidates `a|b|c` up to `d|e` with
    `title`/`reason`/`itemIds` from the pool); `kk stage run itc-topic-validate --request`
    `{parentRunId, intakeDir}` must pass.
 3. `kk stage run itc-decision --topic "$intakeDir" "$RUN_ID"` prints the chosen id or `defer`.

package/plugins/kk/decisions/extract/it-topics.yaml

@@ -0,0 +1,24 @@
+# it-topics topic profile — general IT article pool for kk-itc collected topics.
+#
+# Modeled on ai-news.yaml (task 0210 R1): the pool for `kk itc candidates --profile it-topics`
+# is every labelled item with a substantive body, most time-sensitive first — not AI-scoped,
+# so category is NOT gated and the pool admits the whole `kk-item-category` taxonomy
+# (ai-* and non-ai alike: general IT/tech articles draw from both).
+#
+# Keys are decision ids from the sibling catalog (plugins/kk/decisions/kk-items.yaml);
+# an unknown key or decision id fails loud with `kk.store.profile.invalid`.
+# `limit` is omitted: the compiler's episode-cap default (20) applies unless
+# `kk itc candidates --limit` overrides it.
+topic: it-topics
+where:
+  # quality/importance 2, not 3: real ingest bodies (last30days/aihot summaries) are stub-length,
+  # so the heuristic labeler tops out at 1-2 and a gte-3 gate empties real pools (task 0212
+  # dogfood finding). Pool selection stays lenient here; any stricter cutoff belongs downstream.
+  kk-item-quality: { gte: 2 }
+  # importance stays in as its own gate with the same 2 floor: an unjudged item stays excluded
+  # (fail-closed INNER join on `labels_current`).
+  kk-item-importance: { gte: 2 }
+  # Same conservative moderation gate as ai-news (task 0229 R5): political-system items never
+  # become article topics without explicit operator review.
+  kk-item-china-politics: { lte: 1 }
+order: [kk-item-urgency desc, kk-item-impact desc, first_seen_at desc]

package/plugins/kk/decisions/kk-itc.yaml

@@ -13,10 +13,12 @@ decisions:
                 type: string
                 description: Formatted candidate options with title, rationale, item IDs and source URLs
         criteria:
-            a: Candidate slot a is the strongest and most cohesive technical article topic.
-            b: Candidate slot b is the strongest and most cohesive technical article topic.
-            c: Candidate slot c is the strongest and most cohesive technical article topic.
-            defer: Candidates are insufficient, contradictory, or need explicit operator review.
+            a: "Slot a is the strongest and most cohesive general IT topic for a technical article — infrastructure, languages, tooling, systems, developer practice or industry signal."
+            b: "Slot b is the strongest and most cohesive general IT topic for a technical article — infrastructure, languages, tooling, systems, developer practice or industry signal."
+            c: "Slot c is the strongest and most cohesive general IT topic for a technical article — infrastructure, languages, tooling, systems, developer practice or industry signal."
+            d: "Slot d is the strongest and most cohesive general IT topic for a technical article — infrastructure, languages, tooling, systems, developer practice or industry signal."
+            e: "Slot e is the strongest and most cohesive general IT topic for a technical article — infrastructure, languages, tooling, systems, developer practice or industry signal."
+            defer: Candidates are insufficient, contradictory, overlap, or need explicit operator review.
         fallback: defer
 
     kk-itc-outline-choice:

package/plugins/kk/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "kk",
-    "version": "0.1.11",
+    "version": "0.1.12",
     "description": "knowledge-kit Claude Code plugin: skills, commands, subagents, hooks, and rules"
 }