@gobing-ai/knowledge-kit 0.0.11 → 0.0.13

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

@@ -0,0 +1,134 @@
+# Style extraction from reference images
+
+Loaded by the image-authoring skill when the operator hands over one or more
+reference images and wants the look captured as a reusable style preset.
+Extraction is a **skill operation** — the running agent reads the image(s) with
+its own vision and writes a YAML file. No plugin code, no vision API call, no
+provider credential is involved.
+
+There are two mechanisms for using a reference image, and this file owns the
+boundary between them:
+
+| baoyu usage | kk mechanism | What happens |
+| --- | --- | --- |
+| `direct` | pass-through | The file rides `ImageJobSpec.referenceImages` (0104) to a provider whose `supportsReferenceImages(model)` is true (0103). Highest fidelity; produces one image, nothing reusable. |
+| `style` | extraction (this file) | The look is analysed and written as a `styles/<name>.yaml`. Works with every provider; reusable and editable. |
+| `palette` | extraction, partial | Same procedure, but only `palette`, `name` and `description` are filled; `modifiers` stays a one-line summary. |
+
+## Where the preset goes
+
+Write to the **user root**: `~/.config/kk/image-presets/styles/<name>.yaml`. A cloned
+look is usually the operator's, not the repository's. An operator who wants the
+preset shared with a team writes to the project root
+(`<KNOWLEDGE_KIT_PROJECT_ROOT>/.kk/image-presets/styles/`) instead — it ranks
+higher in the loader chain. No registration step exists or is needed: the
+loader discovers presets by scanning these directories (0102). If the chosen
+name matches a shipped preset, the new file **shadows** it whole-file and the
+loader emits a `shadowed` diagnostic naming both paths — that is the intended
+way to adjust a shipped style, not an accident.
+
+## Input rules
+
+- **One to five reference images.** Count them before reading anything.
+- **Cap refusal (exact wording):** if the operator supplies more than 5, refuse
+  before reading any of them:
+  `Refusing extraction: <N> reference images requested; the cap is 5. Split the set into coherent groups, or drop the least representative references and re-run.`
+  The cap is a constant, not a design commitment; changing it means changing
+  this number and this message only.
+
+## Output rules — the schema is frozen
+
+Emit **YAML only** — no prose, no code fence. The document fills **exactly**
+the `StylePreset` fields of `plugins/generations/image-gen/src/presets.ts` and
+nothing else. **Inventing a field outside this list is a defect, not an
+enhancement.** Field-by-field:
+
+| Field | Required | Rule |
+| --- | --- | --- |
+| `name` | yes | kebab-case, derived from the look, never from the filename. |
+| `description` | yes | One or two sentences naming the look and where it works. |
+| `modifiers` | yes | A comma-separated prompt fragment in the same voice as the shipped styles under `plugins/generations/image-gen/presets/styles/` — `composePrompt` concatenates it as segment 3 of a comma-joined prompt. Read two shipped styles before writing one; a style in the wrong voice produces a prompt in two voices. |
+| `palette` | no | 3–6 entries of `{role, name, hex}`. `role` from `{primary, secondary, accent, background, text}`. `hex` uppercase `#RRGGBB`, sampled from the image, never invented. (A merged set may legitimately keep fewer than 3 — only colours common to every reference survive; see merge rules.) |
+| `typography` | no | Only when the image evidences it. Omit rather than guess. |
+| `visualElements` | no | Array of strings naming recurring visual devices (borders, banding, grain, iconography). Only what the image shows. |
+| `bestFor` | no | The content types this look suits. Inferred from the image's own subject matter. |
+| `negative` | no | What this look must avoid — inferred from what is conspicuously absent. |
+| `source` | yes for extraction | `kind: extracted`, `refImages` = the absolute input paths **in the order given**, `extractedAt` = ISO-8601 timestamp, `confidence` = the judgement below. |
+
+### The `confidence` decision rule (human-judged, not computed)
+
+- `high` — a single clean image with an obvious, consistent look.
+- `medium` — mixed or noisy references, or a merged set where the references
+  disagree on any of the four fidelity axes.
+- `low` — the look is ambiguous, or the image is photographic content rather
+  than a designed style (a photo *of* something is not a style).
+
+## Multi-image merge rules
+
+With N references (1 ≤ N ≤ 5) the output is **one merged preset**, not N
+presets and not an average:
+
+- `palette` — colours **common to the set**. A colour appearing in one image
+  only is dropped, not averaged into a muddy midpoint.
+- `modifiers` — traits present in **every** image. Divergent traits are
+  dropped, and each discarded trait is **named in the extraction report** so
+  the operator sees exactly what was thrown away.
+- `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.
+
+## Pass-through degradation (visible, never silent)
+
+When the operator wants `direct` (pass-through) and the selected provider's
+`supportsReferenceImages(model)` returns `false`, the skill must state it in
+these terms and offer the alternative:
+
+`Provider <name> cannot accept reference images for model <model> (supportsReferenceImages: false). Pass-through is unavailable; offering style extraction instead.`
+
+**Never silently proceed without the reference.** A plausible image generated
+from a dropped reference is the worst outcome available — worse than an error.
+
+## Validate after writing
+
+After writing the YAML, run the dry run: `KK_IMAGE_DRY_RUN=1` `image-gen`
+(0104) with a job whose `style` is the new preset's name. A malformed or
+unloadable file fails there loudly, naming the file and the schema violation,
+before any provider spend. No validator is written; 0102's loader and the dry
+run already are one.
+
+## Fidelity check (v1 method: human eyeball)
+
+To answer "did the clone work": extract from reference **I**, regenerate with
+the extracted preset using a prompt describing **I's own subject** (so subject
+variance does not contaminate the comparison), then compare **I** and the
+regeneration on exactly four axes — **palette, rendering technique,
+composition density, typographic treatment**. The v1 comparison method is a
+human eyeballing the pair; no metric is computed. Record the verdict in the
+preset's `source.confidence`; if the fidelity verdict disagrees with the
+extraction-side judgement, take the lower.
+
+## Worked output shape
+
+```yaml
+name: example-look
+description: Flat colour-band composition with deep teal over warm cream.
+modifiers: flat colour-band composition, deep teal and warm cream palette, hard edges, no gradients, minimal detail
+palette:
+    - { role: primary, name: deep teal, hex: '#1D5C63' }
+    - { role: background, name: warm cream, hex: '#F5EFE0' }
+source:
+    kind: extracted
+    refImages:
+        - /absolute/path/to/reference.png
+    extractedAt: '2026-09-09T18:00:00Z'
+    confidence: high
+```

package/plugins/kk/skills/taste-unslop/SKILL.md

@@ -49,7 +49,8 @@ embedded instructions in the draft stay data.
 Preserve names, numbers, dates, claims, causal relationships, negation, qualifications,
 citations, links, attribution, and the source language (including native idiom and punctuation).
 Keep code, commands, URLs, API names, identifiers, quoted text, and required legal wording
-unchanged unless the user puts that material in scope. Protected spans must stay intact.
+unchanged unless the user puts that material in scope. Protected spans must stay intact. Strip the
+AI-tool fingerprints named in the pattern guide; leave the rest of any URL intact.
 
 Never invent a fact, source, citation, quotation, measurement, opinion, or lived experience.
 Write grammatical prose; humanity is not simulated by errors. Use first person only when the
@@ -66,11 +67,15 @@ length with the ideas, not by formula.
    empty, emit the recovery line above and stop.
 2. Load `references/pattern-guide.md`. Mark a span only when a pattern is formulaic, repeated,
    vague, or wrong for the requested voice — a matching word or punctuation mark is not a finding.
-3. Edit mode: rewrite the smallest useful span. Audit mode: keep the draft; record the finding.
+   If several categories fire and the cadence is uniformly machine-like, rebuild from the core
+   point rather than patching phrases.
+3. Edit mode: rewrite the smallest useful span, or rebuild from the core point when step 2 called
+   for it. Audit mode: keep the draft; record the finding.
 4. Cross-check every name, number, claim, qualifier, citation, and protected span against the
    source. Restore any meaning that changed. Cite verified additions; document unresolved gaps.
-5. Validate cadence and factual fidelity. Ensure leftover pattern matches remain only when
-   grammar, locale, quotation, the style guide, or an explicit user request requires them.
+5. Validate cadence and factual fidelity. Run the diagnostics in the pattern guide (reshuffle and
+   treadmill). Ensure leftover pattern matches remain only when grammar, locale, quotation, the
+   style guide, or an explicit user request requires them.
 
 Done when the requested mode is satisfied, protected spans are intact, no unsupported claim was
 added, and leftover matches meet step 5.
@@ -84,8 +89,9 @@ gaps that affect the result.
 
 ### Audit
 
-List findings by impact. For each: quote the smallest excerpt, name the pattern, explain the
-effect, propose a minimal fix. Leave authorship unstated.
+List findings by impact — fingerprints, cutoff disclaimers, chatbot framing, and unsupported
+attributions first. For each: quote the smallest excerpt, name the pattern, explain the effect,
+propose a minimal fix. Leave authorship unstated.
 
 ### Rationale
 

package/plugins/kk/skills/taste-unslop/references/pattern-guide.md

@@ -2,67 +2,147 @@
 
 Use these patterns during the scan in `SKILL.md`. A matching word or punctuation mark is not enough
 to justify an edit. Change it only when the usage is formulaic, repeated, vague, or wrong for the
-requested voice.
+requested voice. Wordiness is a clarity edit. Clustered stock diction is a stronger signal than a
+single hit.
 
 ## Content and evidence
 
-1. **Puffery and promotion.** Cut phrases such as "pivotal moment", "testament to", "evolving
-   landscape", "breathtaking", and "groundbreaking" when facts carry the point better.
-2. **Vague authority.** Replace "experts believe" or "reports suggest" with a supplied source. If no
-   source exists, preserve the uncertainty and flag or remove the unsupported claim.
-3. **Context-free name-dropping.** Keep a person, company, or publication only when the text explains
-   what it contributes.
-4. **Decorative participial tails.** Delete or expand "highlighting", "showcasing", "ensuring", and
-   similar endings when they add no supported fact.
-5. **Formulaic concessions.** Replace "despite challenges, it continues to thrive" with the actual
-   limitation and result supplied by the source.
+1. **Puffery and promotion.** Cut phrases such as "pivotal moment", "watershed moment", "testament
+   to", "evolving landscape", "breathtaking", "nestled", "vibrant", "thriving", and "groundbreaking"
+   when facts carry the point better. If the sentence still works after the inflation clause is
+   deleted, delete the clause.
+2. **Vague authority.** Replace "experts believe", "reports suggest", "studies show", "analysts
+   agree", or "independent testing confirms" with a supplied source. If no source exists, preserve
+   the uncertainty and flag or remove the unsupported claim. Named, checkable citations stay.
+3. **Context-free name-dropping.** Keep a person, company, or publication only when the text
+   explains what it contributes. A stack of prestige names ("cited in NYT, BBC, and Wired") is
+   weaker than one specific reference. Cut historical-analogy montages ("like the printing press,
+   the telegraph, and the internet") unless one parallel does analytical work.
+4. **Decorative participial tails.** Delete or expand "highlighting", "showcasing", "ensuring",
+   "symbolizing", and "reflecting" endings when they add no supported fact.
+5. **Formulaic concessions.** Replace "despite challenges, it continues to thrive" and "while X has
+   limitations, it's still remarkable" with the actual limitation and result supplied by the source.
+   Vague balance is not a tradeoff.
 6. **Generic openings and conclusions.** Cut scene-setting and endings such as "the future looks
-   bright" unless they state a concrete claim, decision, or next action.
+   bright", "only time will tell", or "may become one of the most important narratives of the next
+   cycle" unless they state a concrete, preferably falsifiable, claim, decision, or next action.
+7. **Novelty inflation.** Do not treat an established idea as a coinage ("he introduced a term I
+   hadn't heard", "the failure mode nobody's naming"). Describe what the source did with the idea.
+   Cut invented labels that are never defined.
 
 ## Language
 
-7. **Stock AI diction.** Words such as "delve", "pivotal", "tapestry", "underscore", "vibrant",
+8. **Stock AI diction.** Words such as "delve", "pivotal", "tapestry", "underscore", "vibrant",
    "intricate", and abstract "landscape" are signals only when generic or clustered. Keep the word
-   when it is the precise one.
-8. **Inflated linking verbs.** Replace "serves as", "stands as", or promotional "boasts" with "is"
-   or "has" when precision survives.
-9. **Stock frames.** Rewrite repeated "not just X but Y", forced groups of three, and false "from X
-   to Y" ranges when a direct statement is clearer.
-10. **Synonym cycling.** Pick the precise noun and repeat it instead of rotating through near-synonyms.
-11. **Vague metaphor and borrowed jargon.** Replace metaphorical "substrate", "vector", "north star",
-    "flywheel", or "scaffolding" with the actual mechanism. Preserve established domain terms such as
-    vector embeddings, API surface, language primitive, and test harness.
-12. **Filler and stacked hedges.** Shorten "in order to", "due to the fact that", and redundant
-    qualifier chains. Preserve qualifiers that encode real uncertainty; never turn "may" into "will".
-13. **Fancy plain words.** Prefer "use", "help", "many", and "if" over "utilize", "facilitate",
-    "numerous", and "in the event that" when meaning is unchanged.
+   when it is the precise one. Repeated multi-word boilerplate ("the integration of",
+   "community-driven", "long-term sustainability") stacked across a piece is the same class: replace
+   with a specific claim, or vary genuinely.
+9. **Inflated linking verbs.** Replace "serves as", "stands as", "features", "presents", or
+   promotional "boasts" with "is" or "has" when precision survives.
+10. **Stock frames.** Rewrite repeated "not just X but Y" (including the split form "It isn't X.
+    The real story is Y"), forced groups of three, false "from X to Y" ranges, and slot-fill
+    templates ("a [adj] step towards [adj] infrastructure", "whether you're X or Y") when a direct
+    statement is clearer.
+11. **Synonym cycling.** Pick the precise noun and repeat it instead of rotating through
+    near-synonyms ("developers… engineers… practitioners… builders").
+12. **Vague metaphor and borrowed jargon.** Replace metaphorical "substrate", "vector", "north
+    star", "flywheel", or "scaffolding" with the actual mechanism. Preserve established domain terms
+    such as vector embeddings, API surface, language primitive, and test harness.
+13. **Filler, stacked hedges, and empty intensifiers.** Shorten "in order to", "due to the fact
+    that", "moreover", "furthermore", and "in today's X". Collapse hedge stacks ("could potentially",
+    "may eventually") to one real qualifier. Drop empty "real" / "actual" / "genuine" on abstract
+    nouns unless the sentence names the contrast ("real settlement, not bridged IOUs"). Preserve
+    qualifiers that encode real uncertainty; never turn "may" into "will".
+14. **Fancy plain words.** Prefer "use", "help", "many", and "if" over "utilize", "facilitate",
+    "numerous", and "in the event that" when meaning is unchanged. These are clarity edits, not
+    evidence of who wrote the sentence.
 
 ## Structure and style
 
-14. **Mechanical rhythm.** Break repeated sentence openings, equal-length paragraphs, and serial
-    summaries. Do not force variation into text whose form is intentionally regular.
-15. **Punctuation monotony.** Reduce repeated em dashes, colons, or parenthetical asides. Keep
+15. **Mechanical rhythm.** Break repeated sentence openings, equal-length paragraphs, and serial
+    summaries. Mix short and long sentences with the ideas, not by formula. In longer general prose,
+    a narrow looping vocabulary is a cue to name specific things, not to reach for synonyms;
+    technical reference that compresses vocabulary on purpose is exempt. Do not force variation
+    into text whose form is intentionally regular, and do not sand away deliberate disfluency,
+    fragments, or uneven pacing to make the prose "cleaner".
+16. **Punctuation monotony.** Reduce repeated em dashes, colons, or parenthetical asides. Keep
     punctuation required by grammar, locale, quoted material, or the style guide; no mark is banned.
-16. **Formatting as decoration.** Remove excessive boldface, title-case headings, emoji, and inline
-    labels that merely repeat the sentence. Preserve formatting that improves navigation or meets the
-    publication format.
-17. **Dense syntax.** Split a sentence when its dependencies make the reader backtrack. Keep clauses
-    together when separating them would hide the relationship.
-18. **Unhelpful passive voice.** Name the actor when the actor matters. Keep passive voice when the
+17. **Formatting as decoration.** Remove excessive boldface, title-case headings, emoji headers,
+    and inline labels that merely repeat the sentence ("**Speed:** Speed improved…"). Convert
+    numbered-list inflation ("here are 7 reasons") to the two or three points that matter. On a
+    list label, prefer a colon to a period ("**Intros:** …", not "**Intros.** …"). Cut trailing
+    hashtag blocks of six or more tags; keep two or three specific tags, or none — and do not treat
+    issue refs, hex colors, preprocessor directives, or in-code `#` as tags. Convert a run of five
+    or more bare adjective-noun bullets with no verb into prose or into claims that can be checked.
+    Preserve formatting that improves navigation or meets the publication format, including genuine
+    lists (changelogs, parameters, ingredients).
+18. **Dense syntax.** Split a sentence when its dependencies make the reader backtrack. Keep
+    clauses together when separating them would hide the relationship.
+19. **Unhelpful passive voice.** Name the actor when the actor matters. Keep passive voice when the
     actor is unknown, obvious, or deliberately de-emphasized.
-19. **Adverbs propping up weak claims.** Use a stronger verb or a supplied measurement. Do not invent a
-    number to replace "significantly" or "quickly".
-20. **Typographic inconsistency.** Follow the source language and house style for quotation marks,
+20. **Adverbs propping up weak claims.** Use a stronger verb or a supplied measurement. Do not
+    invent a number to replace "significantly" or "quickly".
+21. **Typographic inconsistency.** Follow the source language and house style for quotation marks,
     dashes, spacing, capitalization, and headings instead of forcing English ASCII conventions.
+    Unweld needless hyphens in open compounds ("research-impact" → "research impact", "in real-time"
+    → "in real time") when house style agrees; keep legitimate modifiers ("real-time analytics") and
+    do not treat a hyphen fix as authorship evidence.
+22. **Rhetorical stalls and engagement hooks.** Lead with the claim instead of "what if there were
+    a better way", "so why should you care", "the catch?", "the kicker?", or "here's the thing."
+    Delete the hook; state the thing.
+23. **Excessive scaffolding.** Merge short text that is over-headed (several headers in a few
+    hundred words, or stock "Overview" / "Key Points" / "Conclusion" labels). Cut the one-line
+    warm-up that restates the heading. Keep structure that a reader would actually use to navigate.
+24. **Modifier stacking.** Cut stacked hyphenated praise ("a high-quality, well-architected,
+    future-proof solution") to the modifier that matters. Individual hyphens may be correct.
 
-## Chat and meta language
+## Chat, register, and meta
 
-21. **Stock assistant framing.** Remove empty openings and closings such as "Of course", "Great
-    question", "I hope this helps", and "Let me know if". Keep a direct next step when one exists.
-22. **Sycophancy.** Replace automatic agreement with the answer or evidence.
-23. **Cutoff disclaimers.** State the exact missing evidence or omit the unsupported passage. Never
-    disguise a guess as "details are limited".
-24. **Writing about the writing.** Cut "this article will delve into" and similar road signs when the
-    text can make the point directly.
-25. **Feeling without mechanism.** Replace reusable mood claims such as "SQL you can read" with a
-    source-backed behavior, example, or number. If none exists, cut the claim.
+25. **Stock assistant framing.** Remove empty openings and closings such as "Of course", "Great
+    question", "Certainly", "I hope this helps", and "Let me know if". Cut "let's explore" /
+    "let's break this down" when they only delay the point. Skip acknowledgment loops ("you're
+    asking about", "to answer your question"). Keep a direct next step when one exists.
+26. **Sycophancy and recap-flattery.** Replace automatic agreement with the answer or evidence. Do
+    not open a reply by summarizing the other person's own work back at them as praise; substance
+    first, and a short thanks only if it is warranted.
+27. **Cutoff disclaimers.** State the exact missing evidence or omit the unsupported passage. Never
+    disguise a guess as "details are limited" or "as of my last update".
+28. **Speculative gap-filling.** Cut hedged invention that hides a missing fact ("maintains a low
+    profile", "likely began his career", "appears to have studied"). Unlike a cutoff disclaimer,
+    this does not admit the gap. Replace only with a sourced fact from the draft or an
+    authoritative lookup; otherwise flag the gap.
+29. **Writing about the writing.** Cut "this article will delve into" and similar road signs when
+    the text can make the point directly.
+30. **Feeling, significance, and candor without mechanism.** Replace reusable mood claims
+    ("what surprised me most", "I was fascinated to discover", "SQL you can read") with a
+    source-backed behavior, example, or number — or cut. Cut lingering-attention frames ("the line
+    I keep coming back to", "I can't stop thinking about this") unless a reason follows. Cut
+    self-labeling after a list ("that last move is the contrarian one") and reader-steering cues
+    ("it's worth noting", "interestingly", "this is the interesting part") when the fact can stand
+    alone. Cut narrated candor ("I want to be upfront", "two caveats I would rather flag than let
+    you discover later"); keep the disclosure itself, including real conflict-of-interest wording.
+31. **Reasoning-chain artifacts.** Remove "let me think step by step", "breaking this down", and
+    numbered internal monologue. State the conclusion, then the evidence.
+32. **Wall-of-text replies.** In conversational registers (issue/PR comments, chat, DMs), break a
+    dense reply-length block at thought boundaries. Do not apply this to long-form prose, docs, or
+    a deliberately tight paragraph.
+33. **Tool fingerprints.** Fill or delete shipped placeholders (`[Your Name]`, `[INSERT SOURCE]`,
+    `2025-XX-XX`). Strip leaked chat citation tokens (`citeturn0search0`, `oai_citation`,
+    `contentReference[oaicite:…]`). Strip `utm_source` values that name an AI product; leave the
+    rest of the URL intact.
+
+## Diagnostics
+
+These are writer-side tests, not findings by themselves.
+
+- **Reshuffle.** If two body paragraphs can swap places without breaking the piece, the draft is a
+  list of points, not a building argument. Add the missing through-line, or make the list explicit.
+- **Treadmill.** For each paragraph, name the one fact, claim, or turn it adds. If there isn't one,
+  cut it. If there is, lead with it.
+
+## Provenance
+
+Pattern classes adapted from the Pattern reference in
+[avoid-ai-writing](https://github.com/conorbronsdon/avoid-ai-writing) (MIT), rewritten here as
+editing signals. That catalog's replace-on-sight word lists, em-dash bans, numeric type-token
+thresholds, and detector scoring are not part of this skill.