@gobing-ai/knowledge-kit 0.0.13 → 0.0.14

package/plugins/generations/voice-gen/dist/index.js

@@ -21848,6 +21848,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];
@@ -22268,7 +22288,7 @@ function createVoiceboxClient(options = {}) {
         }
       } catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        throw new Error(`Voicebox health check failed at ${url2}: ${reason}`);
+        throw new Error(`Voicebox health check failed at ${url2}: ${reason} \u2014 is Voicebox.app running with its REST server enabled? (restart the app or fix VOICEBOX_URL)`);
       }
     },
     async resolveProfile(nameOrId) {
@@ -22810,11 +22830,18 @@ async function processGeneratorIO(inputPath, outputPath, clientOverride, transco
     const scripts = docs.map((doc2) => parseDocToVoiceScript(doc2, envDefaultProfile));
     const combinedScript = mergeVoiceScripts(scripts, docs, envDefaultProfile);
     validateVoiceScript(combinedScript);
+    const renderStartedAt = Date.now();
+    const maxRunMs = process.env.VOICE_GEN_MAX_RUN_MS ? parseInt(process.env.VOICE_GEN_MAX_RUN_MS, 10) : 0;
+    echoError(`voice-gen: ${combinedScript.segments.length} segments queued for local render`);
     const segmentWavs = [];
     const segmentGaps = [];
     const segmentMetadata = [];
     let totalDuration = 0;
-    for (const segment of combinedScript.segments) {
+    for (const [segIndex, segment] of combinedScript.segments.entries()) {
+      if (maxRunMs > 0 && Date.now() - renderStartedAt > maxRunMs) {
+        throw new Error(`voice-gen: render budget ${maxRunMs}ms exceeded after ${segIndex}/${combinedScript.segments.length} segments \u2014 Voicebox may be wedged; raise VOICE_GEN_MAX_RUN_MS if the render is legitimately long`);
+      }
+      const segStartedAt = Date.now();
       const speakerConfig = segment.speaker ? combinedScript.speakers?.[segment.speaker] : undefined;
       const profileTarget = segment.profile_id ?? segment.profile ?? speakerConfig?.profile_id ?? speakerConfig?.profile ?? combinedScript.default_profile_id ?? combinedScript.default_profile ?? envDefaultProfile ?? (typeof docs[0]?.metadata?.voiceProfile === "string" ? docs[0].metadata.voiceProfile : undefined);
       if (!profileTarget) {
@@ -22930,6 +22957,7 @@ async function processGeneratorIO(inputPath, outputPath, clientOverride, transco
         transcription,
         loudnessDip
       });
+      echoError(`voice-gen: segment ${segIndex + 1}/${combinedScript.segments.length} done in ${((Date.now() - segStartedAt) / 1000).toFixed(1)}s${verifyRetries ? ` (${verifyRetries} verify ${verifyRetries === 1 ? "retry" : "retries"})` : ""}`);
     }
     const concatenatedWav = concatWavs(segmentWavs, segmentGaps);
     await fs.ensureDir(outDir);

package/plugins/generations/voice-gen/src/index.ts

@@ -83,6 +83,12 @@ export async function processGeneratorIO(
         // 3. Validate VoiceScript
         validateVoiceScript(combinedScript);
 
+        // Local render can take hours; per-segment progress + an optional total budget keep
+        // long renders observable and bounded (dogfood 2026-09-12: healthy 72-min render read as a hang).
+        const renderStartedAt = Date.now();
+        const maxRunMs = process.env.VOICE_GEN_MAX_RUN_MS ? parseInt(process.env.VOICE_GEN_MAX_RUN_MS, 10) : 0;
+        echoError(`voice-gen: ${combinedScript.segments.length} segments queued for local render`);
+
         // 4. Generate each segment
         const segmentWavs: Uint8Array[] = [];
         const segmentGaps: number[] = [];
@@ -98,7 +104,13 @@ export async function processGeneratorIO(
         }> = [];
         let totalDuration = 0;
 
-        for (const segment of combinedScript.segments) {
+        for (const [segIndex, segment] of combinedScript.segments.entries()) {
+            if (maxRunMs > 0 && Date.now() - renderStartedAt > maxRunMs) {
+                throw new Error(
+                    `voice-gen: render budget ${maxRunMs}ms exceeded after ${segIndex}/${combinedScript.segments.length} segments — Voicebox may be wedged; raise VOICE_GEN_MAX_RUN_MS if the render is legitimately long`,
+                );
+            }
+            const segStartedAt = Date.now();
             const speakerConfig = segment.speaker ? combinedScript.speakers?.[segment.speaker] : undefined;
             const profileTarget =
                 segment.profile_id ??
@@ -284,6 +296,9 @@ export async function processGeneratorIO(
                 transcription,
                 loudnessDip,
             });
+            echoError(
+                `voice-gen: segment ${segIndex + 1}/${combinedScript.segments.length} done in ${((Date.now() - segStartedAt) / 1000).toFixed(1)}s${verifyRetries ? ` (${verifyRetries} verify ${verifyRetries === 1 ? 'retry' : 'retries'})` : ''}`,
+            );
         }
 
         // 5. Concatenate audio

package/plugins/generations/voice-gen/src/voicebox-client.ts

@@ -73,7 +73,9 @@ export function createVoiceboxClient(options: VoiceboxClientOptions = {}): Voice
                 }
             } catch (err: unknown) {
                 const reason = err instanceof Error ? err.message : String(err);
-                throw new Error(`Voicebox health check failed at ${url}: ${reason}`);
+                throw new Error(
+                    `Voicebox health check failed at ${url}: ${reason} — is Voicebox.app running with its REST server enabled? (restart the app or fix VOICEBOX_URL)`,
+                );
             }
         },
 

package/plugins/ingestions/aihot-ingest/dist/index.js

@@ -21848,6 +21848,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

package/plugins/ingestions/horizon-ingest/dist/index.js

@@ -21849,6 +21849,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

package/plugins/ingestions/last30days-ingest/dist/index.js

@@ -21850,6 +21850,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

package/plugins/ingestions/web-search/dist/index.js

@@ -21849,6 +21849,26 @@ var ResultSchema = exports_external.object({
   metadata: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
 });
 var DocListSchema = exports_external.array(DocSchema);
+var omniVoiceGenContentSchema = ContentSchema.extend({
+  format: exports_external.literal("audio"),
+  metadata: exports_external.looseObject({
+    generator: exports_external.literal("kk:omni-voice-gen"),
+    audioPath: exports_external.string(),
+    duration: exports_external.number(),
+    segments: exports_external.array(exports_external.looseObject({
+      generationId: exports_external.string(),
+      profile: exports_external.string(),
+      speaker: exports_external.string().optional(),
+      emotion: exports_external.string().optional(),
+      duration: exports_external.number(),
+      verifyRetries: exports_external.number(),
+      transcription: exports_external.string().optional(),
+      loudnessDip: exports_external.boolean().optional()
+    })),
+    mp3Path: exports_external.string().optional(),
+    qc: exports_external.record(exports_external.string(), exports_external.unknown()).optional()
+  })
+});
 
 // ../../packages/kk-core/src/kinds.ts
 var PLUGIN_KINDS = ["ingestion", "generator", "publish"];

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

@@ -0,0 +1,40 @@
+---
+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"]
+---
+
+# image-extract
+
+Thin wrapper for the `image-authoring` skill's `extract-style` operation — all vision
+analysis, schema-fill, merge, and validation logic lives in the skill. Forward
+`$ARGUMENTS` with one substitution: this command's `--name <style-name>` is the skill's
+`--extract-style <name>` (the flag doubles as the operation selector there — rewrite it,
+do not pass `--name` through). `--ref`, `--emit-format`, and `--job` pass through unchanged.
+
+```text
+Skill(skill="kk:image-authoring", args="$ARGUMENTS with --name rewritten to --extract-style")
+```
+
+## What it does
+
+- Reads 1–5 reference images (`--ref`, repeatable; more than 5 is refused), analyses
+  the look, and shows you the composed `StylePreset` YAML for `--name <style-name>`.
+- **Confirms with you before writing**, then saves to the user root
+  `~/.config/kk/image-presets/styles/<name>.yaml` — usable immediately via
+  `/kk:image-generate --style <name>`, shadowing any shipped preset of the same name.
+- With `--emit-format <name> --job <job>`, additionally **drafts** a format preset from
+  the same images: measured dimensions + declared job + visual defaults authored from
+  the analysis, skeleton (variables, template grammar) reused from the shipped format
+  of the same job. Shown for confirmation and fine-tuning, then written to
+  `~/.config/kk/image-presets/formats/<name>.yaml` with `defaultStyle` set to the
+  style just extracted.
+- Validates each new preset with a dry-run generation (`KK_IMAGE_DRY_RUN=1`).
+
+Examples:
+
+```text
+/kk:image-extract --name flat-retro --ref a.png --ref b.png
+/kk:image-extract --name flat-retro --ref a.png --emit-format retro-cover --job cover
+```

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

@@ -1,7 +1,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 <name>] [--style <name>] [--content <file>] [--ref <path>] [--var K=V] [--dry-run] [--list-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"]
 ---
 
@@ -13,3 +13,20 @@ confirmation and delegation logic lives in the skill. Forward `$ARGUMENTS` uncha
 ```text
 Skill(skill="kk:image-authoring", args="$ARGUMENTS")
 ```
+
+## Built-in presets (user presets under `~/.config/kk/image-presets/` shadow these)
+
+**Formats** (`--format`; default `free`):
+
+| Format | Job | Aspect | Default style |
+| ------ | --- | ------ | ------------- |
+| `free` | free-form image from the positional prompt | 1:1 | vibrant |
+| `cover` | article cover; requires `--content <file>` | 21:9 | vibrant |
+| `illustration` | auto-insert illustrations into `--content <file>` | 4:3 | technical-diagram |
+
+**Styles** (`--style`): `vibrant` · `minimalist` · `photorealistic` · `technical-diagram` ·
+`editorial` · `fresh` · `warm` · `cute` · `sketch` · `clean-webapp-ui` — or any custom style
+preset name. Omit to use the preference `image.style` or the format's default.
+
+Run `--list-presets` for the live list with origins and shadows. Create new presets from
+reference images with `/kk:image-extract`.

package/plugins/kk/plugin.json

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

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

@@ -86,8 +86,10 @@ owns the schema-fill rules, the multi-image merge rules, the cap-5 refusal wordi
 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.
+whose `style` is the new preset's name. Extraction writes `styles/*.yaml`; with
+`--emit-format <name> --job <job>` it additionally **drafts** a `formats/*.yaml` from
+the same references — a different act with its own authoritative procedure:
+[references/format-drafting.md](references/format-drafting.md).
 
 ### list-presets
 
@@ -109,6 +111,7 @@ output is also the text an unknown `--format`/`--style` refusal quotes.
 [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>]
+         [--emit-format <name> --job <job>]
 ```
 
 | Token | Meaning | Default |
@@ -126,11 +129,15 @@ output is also the text an unknown `--format`/`--style` refusal quotes.
 | `--dry-run` | compose and price, generate nothing | off |
 | `--list-presets` | → the `list-presets` operation | — |
 | `--extract-style <name>` | → the `extract-style` operation; **requires `--ref`** | — |
+| `--emit-format <name>` | with `--extract-style`: also draft a format preset from the same refs; **requires `--job`** | — |
+| `--job free\|cover\|illustration` | declared job for the drafted format — never inferred from pixels | — |
 
 **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
+`--extract-style` without `--ref`; `--emit-format` without `--extract-style` or
+without `--job`, or a `--job` outside `free|cover|illustration`; 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)

package/plugins/kk/skills/image-authoring/references/format-drafting.md

@@ -0,0 +1,57 @@
+# Format drafting from reference images
+
+Loaded by the image-authoring skill when `extract-style` runs with
+`--emit-format <name> --job <job>`. Produces a **draft** `FormatPreset` from the same
+reference images, for the operator to confirm and fine-tune. This is drafting, not
+extraction: a picture supplies measurements and visual defaults, never job semantics
+or variable contracts — those are **declared** or **reused**, and the report must say
+which is which.
+
+## Field provenance — three tiers, never blurred
+
+| Tier | Fields | Source |
+| ---- | ------ | ------ |
+| **Measured** | `aspectRatio`, `width`, `height` | Observed pixel dimensions of the largest reference; `aspectRatio` is the nearest named ratio from `21:9`, `4:3`, `1:1`, `16:9`, `3:4`, `9:16`. No taste involved. |
+| **Declared** | `name`, `job` | The operator's `--emit-format <name>` and `--job <job>`. `job` is never inferred from pixels — a picture does not know whether it is a cover. |
+| **Drafted** | `description`, `keywords`, visual `variables` defaults, `template` | Agent vision over the same references the style came from. Fine-tuning expected. |
+| **Reused** | `defaultStyle`, `outputFilename`, variable names, template grammar | See skeleton rule below. `defaultStyle` is the `--extract-style <name>` of this same run — the pairing is the point of doing both in one pass. |
+
+## The skeleton rule
+
+Start from the shipped format of the **same job** —
+`plugins/generations/image-gen/presets/formats/<job>.yaml` — read it first, then:
+
+- **Keep** its variable names, `outputFilename` grammar, and template placeholder
+  structure. The variable-to-article mapping (`{{title}}`, `{{topics}}`, …) is a
+  contract with the skill's `cover`/`illustration` branches; renaming variables
+  silently breaks `--content` derivation.
+- **Re-author** the visual defaults from the image analysis: `description`,
+  `keywords`, and the default values of the visual variables (`visual_style`,
+  `composition`, `color_palette`, `atmosphere`, `mood`, or their skeleton
+  equivalents) so the drafted prompt would reproduce the reference look.
+- A `free` job needs no `--content` variables; keep the skeleton minimal.
+
+## Output rules
+
+Emit **YAML only**, filling **exactly** the `FormatPreset` fields of
+`plugins/generations/image-gen/src/presets.ts` (`name`, `description`, `job`,
+`aspectRatio`, optional `width`/`height`, `defaultStyle`, `keywords`,
+`outputFilename`, `variables`, `template`) — inventing a field is a defect, same rule
+as style extraction. Multi-image merge follows the style-extraction rule: visual
+defaults reflect traits present in **every** reference; discarded divergent traits are
+named in the report.
+
+## Where the preset goes
+
+Write to the **user root**: `~/.config/kk/image-presets/formats/<name>.yaml`, after
+showing the composed YAML and getting confirmation (interactive; the Confirmation
+policy governs). Same-name shipped formats are shadowed whole-file — intended, as
+with styles. No registration step; the 0102 loader scans the roots.
+
+## Validation
+
+Before reporting done, run one `KK_IMAGE_DRY_RUN=1` generation whose `format` is the
+new preset's name (and whose `style` is the run's extracted style), then report the
+composed prompt from that run's `Content.body`. The report must list each field's
+tier — measured / declared / drafted / reused — so the operator knows exactly what to
+fine-tune.

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

@@ -76,15 +76,20 @@ presets and not an average:
 - `confidence` — capped at `medium` when the set disagrees on any fidelity axis.
 - `source.refImages` — all N absolute paths, in the order given.
 
-## What extraction never writes
-
-**Style only — no format extraction in v1.** A `FormatPreset` carries
-`template`, `variables`, `keywords`, `defaultStyle`, `outputFilename` — none of
-which is recoverable from a picture. Never write a `formats/*.yaml` file. What
-an image *does* yield is arithmetic, not extraction: the extraction report
-**states the observed pixel dimensions and the nearest named aspect ratio** of
-each reference, chosen from `21:9`, `4:3`, `1:1`, `16:9`, `3:4`, `9:16`, as a
-suggestion for which existing format to pair the style with.
+## What extraction writes
+
+**Style by default; format drafting is opt-in.** A `FormatPreset` carries `template`,
+`variables`, `keywords`, `defaultStyle`, `outputFilename` — none of which is
+*recoverable* from a picture, so extraction alone never writes a `formats/*.yaml`.
+What an image *does* yield is arithmetic: the extraction report **states the observed
+pixel dimensions and the nearest named aspect ratio** of each reference, chosen from
+`21:9`, `4:3`, `1:1`, `16:9`, `3:4`, `9:16`.
+
+When the operator passes `--emit-format <name> --job <job>` alongside `--extract-style`,
+that arithmetic plus the same visual analysis feeds a **draft** format preset — measured
+fields taken, visual defaults authored, structural fields reused from the shipped
+skeleton, operator fine-tuning expected. That procedure lives in
+[format-drafting.md](format-drafting.md); this file stays style-only.
 
 ## Pass-through degradation (visible, never silent)