markilo 1.0.0 → 1.1.2

package/plugin/skills/design/references/design-principles.md

@@ -1,163 +1,170 @@
-# Designing marks that last
-
-This is the craft standard Markilo holds itself to. Use it when exploring directions, drawing SVGs and
-critiquing.
-
-## Start from an idea, not a shape
-
-A strong mark compresses one true, specific idea about the brand into a form simple enough to remember
-after one look. Before drawing, write the idea in one sentence: _"Two arches that share one stem — research and
-verification meeting in an m."_ If you cannot write that sentence, you do not have a concept yet.
-
-Good sources of ideas, in order of strength:
-1. **What the product uniquely does** (its mechanism, its transformation, its promise).
-2. **The name** — its letters, its meaning, its sound, its etymology. Monograms work when the letter is
-   transformed by the idea, not just set in a font.
-3. **The audience's world** — a tool, gesture or artifact they recognise, used unexpectedly.
-4. **Abstract character** — rhythm, tension, motion, balance — when the product is too broad for literal
-   imagery (holding companies, platforms, families).
-
-Avoid category clichés unless you subvert them knowingly: lightbulbs for ideas, globes for "global",
-speech bubbles for chat, shields for security, rockets for growth, generic leaves for "green", swooshes,
-brain/circuit hybrids for AI, interlocking rings, abstract "connected dots" networks, and default
-gradient blobs. Markilo's genericity check flags marks that collapse to a stock primitive.
-
-**The product's own object is a cliché too.** The first idea everyone has — and the icon most competitors already
-use — is the thing the product handles: a page, a folded corner or a sticky note for documents and invoices; bars,
-charts, tally marks or coins for finance; a moon, stars, clouds or a bed for sleep; a padlock, a key or a shield for
-privacy; a check mark for tasks; a speech bubble for messaging. Draw it only when a transformation is the first thing
-a stranger notices; otherwise it reads as a UI icon next to the competitors. The same goes for the literal noun in
-the name (a tally for "Tally…", a fold for "…fold").
-
-**So is the name's initial with a cut.** Once objects are ruled out, the next default is the first letter split,
-sliced, offset, stepped or nested inside a copy of itself — an S with a seam, an L cut by a diagonal, two Ls, a T with
-a bent arm. Independent judges call it "a common monogram device" every time. A letter-led mark works only when the
-letter becomes something else at first sight (the reading is the idea, not "the letter T"), or when the letterform
-itself is drawn with a character no font has.
-
-## Ideas before directions
-
-Write ideas as what a stranger would see, not as what they mean: "a lamp seen from above, its shade cut into the
-initial" is a hook; "reliability" or "a round trip from audit to fix" is a meaning still looking for a picture. Rules
-for the longlist (`markilo ideas`):
-
-- At least 12 hooks from at least three sources: the product's mechanism, the audience's world (a tool, a gesture, a
-  material they know), the name (its letters, sound, meaning, the parts of a compound name), type (a face and a
-  treatment that carry the brand across the whole word) and abstract character.
-- **Mechanism metaphors drawn with primitives become UI glyphs.** On three real developer products every such
-  direction — a round trip, a crossing point, a threshold, a keystone, an undertrace, a hinge — was drawn as brackets,
-  crosses, arches, gauges or loops, and read as a D, a return key, a headstone, a speedometer. Keep one only if the
-  hook names a specific, unusual form, not the concept.
-- **Compound and meaningful names are the strongest source when they exist**: both identities that passed in the
-  benchmark drew the name's meaning inside its own letters (a q holding a dot like an egg in a nest; an n sheltering a
-  seed for a name that means a held pine). Coined names (no meaning to draw) lean on type: a distinctive face and one
-  treatment that runs through every letter, not one gimmick letter with a coloured accent ("a letter-plus-dot of the
-  generic kind").
-- A coloured block, dot or tab added to one letter is the default move of every wordmark board; critics read it as
-  a cursor, a flag or a full stop. It needs a reason a stranger can see.
-
-## Form language follows the brief's character
-
-The same idea drawn with the wrong form language fails on brand fit. Decide the form language from the brief's
-adjectives before sketching, and keep it across the mark and the wordmark:
-
-| The brief says               | Construction choices                                                                                                                  |
-| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| warm, handmade, human, craft | organic curves (`line` with `smooth`), slightly irregular rhythm, soft but unequal radii, one hand-cut detail; avoid UI-icon geometry |
-| precise, technical, reliable | one grid and unit, constant weights, crisp corners or one radius family, exact alignments                                             |
-| calm, quiet, trustworthy     | few parts, generous negative space, low internal contrast, no sharp diagonals                                                         |
-| bold, energetic, young       | heavy weights, confident asymmetry, one strong diagonal or cut, saturated accent                                                      |
-| premium, editorial           | contrast between thick and thin, restraint, a serif or a refined grotesque in the wordmark                                            |
-
-A mark that reads as a tech or UI icon for a handmade brief, or as a playful sticker for an enterprise brief, is the
-wrong form language even when the idea is right.
-
-## Directions must be genuinely different
-
-Three to five directions, each a different _idea_ and form language — e.g. a letterform-led monogram, a
-pictorial metaphor, an abstract geometric system, a typographic-only wordmark, an emblem. Two
-directions that share the same idea are one direction. `markilo diversity` must report `low` risk between
-directions at the explore stage.
-
-**One direction is usually wordmark-led** (`concept new --lead wordmark`). A symbol has to be invented from nothing,
-and in categories full of pictograms (developer tools, SaaS, analytics) an invented symbol is most often read as a
-UI icon — a camera, a download arrow, a toggle. A wordmark starts from letters a type designer already drew well;
-the identity is the word with one or two letters changed so they carry the idea (a ligature that joins two letters
-the way the product joins two things, a counter that holds the product's object, a terminal that points), and the
-icon is that changed letter or pair cut from the same drawing. It is judged as a word first: on the wordmark sheet
-at 12–64 px, then the icon at 16 px. The change must be more than a slice or offset of a letter — that is the
-initial-with-a-cut cliché again.
-
-## Form
-
-- **Simplicity**: as few elements as the idea allows. Aim for something a child could redraw from memory.
-  Under ~40 path commands for a symbol is a healthy target; complexity needs a reason.
-- **Silhouette first**: the mark must work as a solid black shape. Color is added after the form works.
-- **Construction**: build on a grid (e.g. 24 or 48 units) with a consistent set of radii and stroke
-  weights. Repeat measurements. Build with `markilo construct` so the recipe is saved as `construction.json`
-  (see `construction.md`).
-- **Optical corrections** (what separates professional marks):
-  - Round and pointed forms overshoot flat ones by ~1–3% to look the same size.
-  - Horizontal strokes are drawn slightly thinner than vertical ones to look equal.
-  - The optical center sits slightly above the geometric center; the verify balance check reports a
-    small upward offset as intentional.
-  - Where strokes meet at acute angles, open the joint (ink traps) or thin the stroke to avoid dark blobs
-    at small sizes.
-  - Circles next to squares need to be slightly larger.
-- **Negative space**: use it on purpose; counters must stay open at 16 px (verify reports closed
-  counter-spaces). Gaps under 1.2 px at 16 px disappear.
-- **Small sizes**: the symbol must survive at 16 px. If a detail matters only at large sizes, it is
-  decoration; drop it or create a deliberately simplified small-size variant.
-- **Balance**: visual weight near the optical center, with breathing room in the artboard (80–98% of the
-  artboard; verify reports it).
-- **Monochrome**: the mark must read in one color with no internal color-only boundaries. Separate parts
-  with real gaps (knockouts), not just different shades.
-
-## Color
-
-- One dominant brand color, one optional supporting color, plus ink and paper. More colors need a system
-  reason (a product family, a data palette).
-- Check meaning across markets: red (luck in China, danger/discount elsewhere), green (finance, health,
-  Islam), white (mourning in parts of East Asia), purple (mourning in parts of Latin America and
-  Thailand). Note any risk in the brief.
-- Contrast: the mark needs ≥ 3:1 against its background (WCAG 1.4.11); provide reversed variants for dark
-  grounds. The palette command reports WCAG pairs and semantic clashes (brand color too close to error red
-  or success green).
-- Prefer colors that still work in grayscale (vary lightness, not only hue) for color-vision deficiencies.
-
-## Typography
-
-- The wordmark is drawn from a typeface, then _edited_: tracking, specific letter adjustments, joined or
-  cut strokes when the idea calls for it. Always outlined (`markilo wordmark`), never live text.
-- Match the symbol's construction: geometric symbols pair with geometric sans; humanist forms with
-  humanist sans; editorial or heritage positioning can use a serif (fraunces, ibm-plex-serif).
-- Lowercase reads friendlier and more modern; uppercase reads institutional and stable; title case is
-  neutral.
-- Check every letter of the name for awkward pairs (rn → m, cl → d, Il1) and for diacritics in target
-  markets (Turkish İ/ı, ş, ğ; German ß; Nordic å/ø). Use `--locale tr` for Turkish casing.
-- Licenses: bundled fonts are SIL OFL 1.1 (commercial use allowed; outlined logos carry no font
-  obligations). Record any user-supplied font and its license.
+# Designing identities worth choosing
+
+This is how Markilo designs. It describes what good work looks like, not a recipe: use judgment, and break a
+recommendation when the work is better for it. Only the technical rules (SVG validity, legibility, safety, originality)
+are fixed — see `svg-authoring.md` and `originality.md`.
+
+## What Markilo 1.0 got wrong, so you don't repeat it
+
+An independent panel looked at 81 concepts from Markilo 1.0 and would present none. They were not sloppy; they were
+mechanical. The process asked designers to assemble marks from primitives (rings, bars, cuts), to start from what a
+stranger sees in a 32 px favicon, to change "one or two letters" of a stock typeface, and to avoid a long list of
+rejected patterns. The results were what those instructions produce:
+
+- **UI icons** — a metaphor (a round trip, a keystone, a gauge) drawn with uniform strokes on an icon grid reads as a
+  button, not a brand.
+- **Primitive geometry** — a circle, a bar and a gap, however clean, is a shape, not a drawing.
+- **Weak monograms** — the initial with a slice, offset or step.
+- **Stock wordmarks** — a neutral grotesque with one letter tweaked or a coloured dot added.
+- **Literal metaphors** — the product's mechanism drawn as a diagram.
+
+The fix is not more rules. It is designing the way identity designers do: a point of view first, then drawing with
+intent, then craft.
+
+## Start from a point of view
+
+Before drawing, decide what the identity should _feel_ like to the people who will see it every day — and what it must
+not feel like. Write it as a stance, not a metaphor: "quiet authority — a tool that is sure of itself and never
+shouts", "editorial precision, like a well-set technical book", "warm, hand-made confidence". The stance chooses the
+typeface, the weight, the proportions, the colour and the kind of form; the metaphor, if there is one, comes second.
+
+A strong identity usually has **one distinctive idea, executed with consistency**: a particular letter construction
+carried through the word, a contour that is unmistakably drawn, a rhythm, a proportion. It does not need to explain
+the product. Most identities people remember say almost nothing literal.
+
+## Wordmark first, especially for coined names
+
+For a coined or distinctive name (most software products), the word itself is usually the strongest identity: it says
+the name every time, it cannot be mistaken for a UI icon, and type is where character is easiest to make ownable.
+Default to a wordmark-led proposal unless the brief calls for a symbol above all; a separate symbol is never mandatory.
+The compact icon (favicon, app icon, avatar) is then derived from the word — a letter, a pair, a ligature or a detail of
+the drawing — not invented separately.
+
+**A wordmark is designed, not typeset.** Typing the name in a font is the starting point. Then make it yours:
+
+- **Choose the face for character, not neutrality.** Inter, Manrope and DM Sans are excellent for interfaces and
+  forgettable as logos. Look for a face whose construction already says the stance (`markilo fonts` lists traits);
+  then push it.
+- **Work the whole word, not one letter.** A treatment that runs through every letter reads as intent; a single
+  modified letter on a stock word reads as a gimmick. Examples of whole-word decisions: one terminal shape repeated on
+  every stroke ending; a consistent cut angle; stroke contrast (thick verticals, thin joins); a unified x-height and
+  counter shape; a width (condensed, extended) that gives the word a silhouette.
+- **Find the word's own opportunities.** Look at the actual letters: which pairs could share a stroke or form a
+  ligature (rl, li, va, ar, ex), which counters could be reshaped consistently, where an ascender or descender could
+  extend, where the word's rhythm (stems and rounds) creates a pattern worth emphasising. These moves are specific to
+  this name, which is what makes them ownable.
+- **Draw custom letters when the face cannot say it.** Build letters from the font's outlines and your own Bézier
+  paths (`construct` with `glyph` and `path`, booleans to join or cut), or draw them fully custom. A custom `R`, `a` or
+  `x` with a distinctive construction, repeated logic in the other letters, beats any off-the-shelf face.
+- **Space it by eye.** Tight, even colour across the word; open the pairs that clump (rn, ri), close the ones that gap
+  (Va, ro). Optical kerning is the difference between "set in a font" and "a logo".
+- **Case is a decision.** Lowercase is approachable and modern; capitals are institutional; mixed case keeps a coined
+  name readable.
+- **Stay readable.** Every letter must still be the letter it is — at 12 px and in a header. A wordmark that has to be
+  explained has failed.
+
+## Symbols: drawn, not assembled
+
+When a proposal is symbol-led, draw a form, not a diagram:
+
+- **Use freeform paths and Bézier curves.** Write the `d` attribute directly in a 1024-unit square, or construct parts
+  and then redraw the contour. Curves with deliberate tension — a contour that speeds up and slows down — read as
+  drawn; arcs of one radius joined to straight bars read as an icon set.
+- **Prefer solid, filled silhouettes** with a distinctive outline and purposeful negative space over outlined line
+  icons. Uniform strokes with round caps on a square grid are the visual language of interface icons; avoid it unless
+  the stance demands it.
+- **Abstract is allowed.** An abstract form with the right energy (balanced, tense, organic, asymmetric, heavy, light)
+  can carry an identity better than a literal picture. It must still be specific: a form you could recognise again,
+  not a generic blob or swoosh.
+- **Asymmetry and organic geometry are tools**, not mistakes. Perfect symmetry and primitive geometry are tools too —
+  choose them on purpose.
+- **If there is a metaphor, transform it.** The product's own object (a document, a chart, a check mark, a shield, a
+  magnifying glass, a funnel) drawn plainly is what every competitor already uses. Use an idea only when the drawing
+  adds something the obvious version does not have.
+
+## Three proposals that are genuinely different
+
+A round is three proposals that differ in kind, not three variations of one shape. Vary at least two of: what leads
+(word or symbol), the stance, the typeface family (grotesque, humanist, geometric, serif, custom), the form language
+(geometric, organic, calligraphic, engineered), and colour. A useful default mix:
+
+1. **A wordmark-led identity** with a fully worked word and an icon derived from it.
+2. **A symbol + wordmark** where the symbol is a drawn, ownable form and the word is set with care to match it.
+3. **A bolder or unexpected route** — a typographic emblem, an abstract system, an editorial serif, a monogram so well
+   drawn it becomes a mark — something the user might not have asked for and might love.
+
+Adapt the mix to the brief. If the user's references point somewhere, at least one proposal should go there. Let one
+proposal be warmer or more human than the category expects: on a release-engineering tool whose brief said
+"rigorous, calm", the owner chose a hand-tooled humanist word and a cairn of stones over two engineered routes.
+
+## What an accepted identity teaches (the bar for "good enough")
+
+In Markilo 1.1's validation the owner of a real release-engineering tool accepted this identity after one round of
+proposals, a development pass and a choice between icon options:
+
+- **The word had a hand.** A humanist face (Alegreya Sans) softened and tooled across every letter, with a pebble for
+  the i-dot: typeset likeness 0.77 — visibly not the font, still effortless to read.
+- **The icon was an object with character plus one product truth.** Stones at rest (a trail marker: someone checked
+  this way), the top stone drawn only as an outline — the product's "unverified is a state, never a silent pass" made visible. Letter icons
+  (an r, an R, an "r.") were all read as generic; stacked bars read as a menu.
+- **The user combined.** The outline came from an earlier, otherwise rejected proposal. Ideas that lose as a whole
+  often carry the detail that wins — keep them visible in the gallery.
+- **Development keeps the choice.** Two development passes lost what was chosen (a narrowed word, stones flattened into
+  pills); the version the owner accepted refined the chosen drawing and offered icon options instead.
+
+## Craft
+
+- **Optical corrections.** Round forms overshoot flat ones by 1–3 %; horizontals are slightly thinner than verticals;
+  the optical centre sits a little above the geometric one; acute joins need opening (ink traps) at small sizes.
+- **Consistency.** One stroke-contrast logic, one corner logic, one terminal logic across word and icon.
+- **Small sizes are a check, not the starting point.** Design at display size; then confirm the icon still reads at
+  16–32 px. If a detail matters only large, make a simplified small version rather than coarsening the main mark.
+- **Monochrome first.** The identity must work in one colour; colour is added to a form that already works.
+- **Restraint.** Every element earns its place. Decoration is not character.
+
+## Colour
+
+One confident primary, an optional supporting colour, ink and paper. Pick colour from the stance and the product's
+existing interface (an existing UI palette is equity), check contrast (≥ 3:1 for the mark, `markilo palette` reports
+WCAG pairs) and cultural meaning in the target markets. Prefer a palette that still works in greyscale.
+
+## User references
+
+When the user shares logos, screenshots, mood boards, sketches or identities they like or dislike
+(`markilo reference add --category inspiration|dislike|existing`), read them for **characteristics**: proportion,
+weight, contrast, typeface classification, case, spacing, corner and terminal shapes, density, energy, colour
+temperature. Write those down and design from them. Never reproduce a referenced mark or its distinctive device;
+references are compared in the originality check like any competitor mark. A sketch from the user is an idea to
+develop, credited to them. Without references, design from the brief — references help, they are never required.
+
+## Avoid (short list)
+
+The category's clichés named in the brief; the product's object drawn plainly; outlined line icons; a stock face
+untouched; one tweaked letter or a coloured dot on an otherwise stock word; the initial with a slice or offset as the
+whole idea; gradient blobs, swooshes, connected dots, generic arrows and check marks.
+
+## Typography notes
+
+- Bundled faces are SIL OFL 1.1 (commercial use allowed; outlined logos carry no font obligations). `markilo fonts`
+  lists them with traits; with network approval `markilo fonts search` / `fonts add` reach ~1,800 open-licensed
+  families. Record any user-supplied font and its license.
+- Check every letter pair for confusion (rn → m, cl → d, Il1) and diacritics in target markets (Turkish İ/ı, ş, ğ;
+  German ß; Nordic å/ø). Use `--locale tr` for Turkish casing.
+- Wordmarks are always outlined (no live `<text>`).
 
 ## Refresh vs. redesign
 
-Keep equity that exists. Before changing a working identity, list what people already recognise (shape,
-color, letter, sound). A **refresh** keeps the core idea and improves craft (geometry, small sizes,
-contrast, a modern wordmark). A **redesign** is justified when the current mark fails measurably
-(legibility, originality conflict, scalability), contradicts the positioning, or the business changed.
-State which one you recommend and why, with evidence.
+Keep equity that exists: list what people already recognise (shape, colour, letter, sound) before changing it. A
+refresh keeps the idea and improves craft; a redesign is justified when the current mark fails measurably, contradicts
+the positioning, or the business changed. Recommend one with evidence.
 
-## Families (multi-product brands)
+## Families
 
-- Define the shared system first: grid, corner radii, stroke weight, color logic, type, and a shared
-  structural motif. Write it to `brand/shared/system.json` (tokens) and the brief notes.
-- Each product gets its own idea expressed in the shared language. Family members should be clearly
-  related at a glance and clearly distinguishable at 16 px. Check both with `markilo diversity` per brand
-  and by comparing members with `markilo compare`.
-- Architecture: decide master brand vs. endorsed vs. independent per product, and record it (`--role`,
-  `--parent`).
-- Preserved (locked) members are inputs to the system, not things to change.
+Define the shared system first (type, stroke and corner logic, colour logic, one structural motif), then give each
+product its own expression inside it. Members must be related at a glance and distinct at 16 px.
 
-## Judgment criteria (scored 0–10 by the critic, with one-line reasons)
+## Judgment criteria (used in the final review)
 
-brand-fit, semantic-relevance, distinctiveness, memorability, simplicity, balance, craft (geometry and
-optical alignment), typography, color, cultural-fit, timelessness, premium-perception, versatility.
+brand-fit, semantic-relevance, distinctiveness, memorability, simplicity, balance, craft (geometry and optical
+alignment), typography, color, cultural-fit, timelessness, premium-perception, versatility. Scores inform; the user
+decides.

package/plugin/skills/design/references/svg-authoring.md

@@ -1,8 +1,8 @@
 # SVG authoring rules for Markilo masters
 
-`markilo svg lint --master` and `markilo verify` enforce these. Build symbols with `markilo construct`
-(see `construction.md`): it produces masters that already follow these rules. Write SVG by hand only for parts no
-construction shape can express.
+`markilo svg lint --master` and `markilo verify` enforce these. Write SVG by hand — freeform paths and Bézier curves
+are first-class — or build it with `markilo construct` (`construction.md`), which produces masters that already follow
+these rules. Either way, the rules below are fixed: they keep masters valid, safe, legible and exportable.
 
 ## Required
 
@@ -23,9 +23,10 @@ construction shape can express.
 - Snap coordinates to the construction grid; use integers or one decimal where possible.
 - Keep the mark inside the artboard with a small margin: ink should span 80–98% of the viewBox.
 - Use `fill-rule="evenodd"` for counters (holes) inside one path when it keeps the path simple.
-- Prefer arcs (`a`) and straight segments over many tiny curve segments; prefer a few precise cubic
-  Béziers over auto-traced noise. Keep total path commands low (verify reports complexity).
-- Round corners with arcs of consistent radius across the mark.
+- Draw curves with a few precise cubic Béziers: place points at extremes (top, bottom, left, right of a curve) with
+  horizontal or vertical handles where the curve turns; that is how type designers draw smooth contours. Avoid
+  auto-traced noise; verify reports complexity.
+- Keep one logic for corners (sharp, one radius family, or soft) across the mark and its word.
 - For overlaps that should read as separate parts in one color, cut a real gap: ≥ 1/13 of the artboard (≥ 80 units
   on 1024), which is 1.2 px at 16 px — the verify threshold. Under 1/23 (~45 units) fails.
 
@@ -41,8 +42,10 @@ construction shape can express.
 
 ## Wordmarks and lockups
 
-- Generate with `markilo wordmark --text … --font … --weight … -o wordmark.svg`; it embeds cap-height and
-  baseline metadata used by `markilo lockup` and `finalize`.
+- Start from `markilo wordmark --text … --font … --weight … -o wordmark.svg` or a construct spec with
+  `"role": "wordmark"`; both embed `data-baseline`, `data-cap-height` and `data-x-height` used by `markilo lockup` and
+  `finalize`. A wordmark drawn fully by hand needs `data-markilo-role="wordmark"`, `data-baseline` and
+  `data-cap-height` on its root (in its own viewBox units) so lockups align it.
 - Tune tracking in thousandths of an em (`--tracking=-15` tight display, `0` default, `+40` airy caps).
 - Manual letter edits are allowed after generation: edit individual `<path data-char="…">` elements and
   keep the root attributes.

package/plugin/skills/design/references/workflow.md

@@ -2,18 +2,18 @@
 
 ## Stage gates
 
-| Stage    | Done when                                                                            | Saved in                          |
-| -------- | ------------------------------------------------------------------------------------ | --------------------------------- |
-| Discover | Sources scanned, existing identity seen, mode chosen (new/refresh/redesign/evaluate) | profile.json, brief.json `mode`   |
-| Research | Each topic covered or listed as a gap; references collected                          | profile.json, research/references |
-| Brief    | Brief validates; user confirmed the key trade-offs                                   | brief.json, answers.json          |
-| Explore  | 3–5 directions, each with idea sentence, form language, type, color, risk            | decisions.md                      |
-| Design   | Each direction has symbol.svg (+ wordmark.svg) and concept.json                      | concepts/<id>/                    |
-| Verify   | No `fail` checks, originality not `redesign`, diversity low, critic scores recorded  | reports/, concept.json `judgment` |
-| Review   | User has seen the gallery and chosen                                                 | answers.json, concept status      |
-| Refine   | Chosen concept re-verified after every change; finalized                             | final/                            |
-| Export   | Export ran without skipped groups the user needs                                     | exports/                          |
-| Deliver  | User has paths, guidelines, quality + originality summary, limitations               | —                                 |
+| Stage      | Done when                                                                                        | Saved in                          |
+| ---------- | ------------------------------------------------------------------------------------------------ | --------------------------------- |
+| Understand | Sources read, existing identity seen, concise brief, essential questions answered, references in | profile.json, brief.json, answers |
+| Explore    | Three proposals in the round: word, icon, idea, strengths, weaknesses, rendered board            | concepts/<id>/, proposals/round-N |
+| Choose     | The user selected, asked for changes, combined, or rejected the round with a note                | feedback/, concept status         |
+| Develop    | The chosen concept refined: letterforms, spacing, icon, small version, lockups, colour           | concepts/<id>/                    |
+| Verify     | No `fail` checks, originality not `redesign`, one independent critique applied, user approved    | reports/, final/                  |
+| Export     | Export ran without skipped groups the user needs                                                 | exports/                          |
+
+Rounds: at most two rounds of three proposals on Markilo's own initiative; a third needs the user's direction
+(`concept new --round 3 --directed "<their words>"`). Track cost per phase with `markilo cost`; the default budget is
+$12 per brand (`markilo cost --brand <slug> --budget <usd>` to change it).
 
 Append one dated line per significant decision to `brand/brands/<slug>/decisions.md` (Edit the file):
 what was decided, why, and the evidence.
@@ -32,7 +32,8 @@ Recommend a mode with evidence (measurements of the current mark + findings) and
 
 - "Research X": Discover + Research + Brief, then stop with a summary of the profile.
 - "Check this logo": evaluate mode (`score`, `analyze`, `compare` against references, `name check`).
-- "Make variations of concept A": Refine.
+- "Make variations of concept A": Develop (develop mode on that concept).
+- "Show me three directions": Understand (briefly) + Explore, then stop for the user's choice.
 - "Export / give me favicons": Export (+ `install-assets` dry run).
 - "Show me": `markilo gallery`.
 
@@ -60,14 +61,12 @@ Recommend a mode with evidence (measurements of the current mark + findings) and
    (`--role product --parent <master>`). Locked members: `brand add "<Name>" --locked` then
    `markilo lock --brand <slug> --symbol … --primary …`.
 2. Research the family once (master brand), then product-specific facts per product.
-3. Sketch the family as one system, not the master alone: every sketch spec of a family direction has a `members`
-   block (one parameter set, and colours if they differ, per product — construction.md → Families). `markilo
-   sketches` draws master and members together on `sketches/family.png` and marks a sketch not ready when two members
-   read as the same mark (same shape and close colours); members told apart only by colour get a note. The sketch
-   review judges the system: do the members belong together, and can each be told apart at 16 px?
-4. When the master passes the gate, build each product from the same spec: `markilo concept new --brand <product> …`,
+3. Propose the family as one system, not the master alone: each proposal shows the master and two or three members.
+   With construction specs, a `members` block draws them from one parameter set (construction.md → Families;
+   `markilo sketches` renders `sketches/family.png` and flags members that read as the same mark).
+4. When the user has chosen the master, build each product from the same system: `markilo concept new --brand <product> …`,
    then `markilo construct <spec> --brand <product> --concept <id> --member <name>` (its parameters and colours),
-   `markilo verify`, and a critique per product. Record the system (construction, colour logic) in
+   `markilo verify`, and show the family together. Record the system (construction, colour logic) in
    `shared/system.json`.
 5. Products that need their own idea (an acquired brand, a different audience) are designed separately with the
    concept-designer agent, inside the shared system.

package/plugin/skills/export/SKILL.md

@@ -33,6 +33,7 @@ Toolchain: `node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command>` (written `m
    the plan), and `--force` only if they want existing icons replaced — those are backed up to `.markilo-backup/`.
    Applying is all-or-nothing; `markilo install-assets --undo [--project <dir>]` previews reversing it, `--apply`
    does it (files the user edited since are kept). Do not edit their source files; give them the snippet instead.
-7. Tell the user where everything is (`exports/`, `asset-manifest.json`, `guidelines/index.html`), that more groups
+7. Tell the user where everything is: open `exports/index.html` first (every file previewed on its own background,
+   with links); `exports/README.md` lists the files most people need; `guidelines/index.html` explains usage. Say that more groups
    can be added any time (`markilo deliverables --add ios` then `markilo export`), and mention that
    X (Twitter) header sizes could not be verified against x.com documentation.

package/plugin/skills/gallery/SKILL.md

@@ -17,14 +17,17 @@ Toolchain: `node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command>` (written `m
    on this computer, needs the token, serves only the gallery and exported artwork, and stops by itself when idle.
    Without a background shell, run `markilo gallery` instead: it writes `brand/gallery/index.html`, a self-contained
    file that works offline; give the user its `file://` URL.
-2. Explain the review flow in two lines: at the sketch stage, pick one sketch per direction to develop (or "None of
-   these"); on each developed concept choose Keep / Refine / Drop, add revision tags or a note, click on the big mark
-   to pin what should change at that spot, tick "Compare" on two or more concepts to see them side by side and mark
-   one "Prefer this". Then press **Send to your agent** (served) or **Download decisions** (file) and tell you when
-   done.
+2. Explain the review flow in two lines: the round's three proposals (A, B, C) are side by side; **Select** one,
+   **Request changes** on one (add tags or a note, or click on the big mark to pin what should change at that spot),
+   tick **combine with another** on two to mix them, or **Reject all three** with a note on what is missing. **Add to
+   comparison** on two or more, then **Compare** shows them side by side. Then press **Send to your agent** (served)
+   or **Download decisions** (file) and tell you when done. The choice is theirs; no critic score decides it. The page
+   has EN/TR and light/dark/system switches at the top; if the user writes in Turkish, mention the TR switch.
 3. Read the decisions: `markilo feedback --brand <slug>` (after a download: `markilo feedback --import <file>`). It
    returns each decision with tags, notes and pinned spots (e.g. "at top-right: thicker stem"), the preferred concept
    and ready-to-act requests. Repeat them back to the user in one short summary.
-4. Act: `markilo feedback --brand <slug> --apply` records sketch picks (the user's pick wins over the critic's) and
-   marks dropped concepts rejected and kept ones shortlisted (only after the user confirmed the summary). Log what was decided (`markilo answers`) and continue with the refine skill for
-   each "refine" request — pinned spots tell you where on the mark the change belongs.
+4. Act, after the user confirmed your summary: `markilo feedback --brand <slug> --apply` marks selected concepts
+   shortlisted and dropped or round-rejected ones rejected. Log what was decided (`markilo answers`). Then: a selection
+   or change request → the refine skill (develop the chosen concept; pinned spots tell you where the change belongs);
+   a combination → a new concept developed from the named parts; a rejected round → the concepts skill for the next
+   round, with the user's note.

package/plugin/skills/refine/SKILL.md

@@ -1,25 +1,30 @@
 ---
 
 name: refine
-description: Markilo refinement — iterate on a chosen logo concept (geometry, optical corrections, wordmark spacing, palette, small-size version) with verification after every change, then finalize it as the approved identity. Use when the user picks a concept or asks for changes to one.
+description: Markilo development — turn the concept the user chose (or a combination of two) into a professional identity (letterforms, spacing, optical balance, icon, small version, lockups, colour), verify it, get one independent critique, and finalize it on the user's approval. Use when the user picks a concept or asks for changes to one.
 argument-hint: "[brand slug, concept id and the feedback]"
 allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep
 ---
 
-# Markilo · Refine and finalize
+# Markilo · Develop, verify and finalize
 
 Request: $ARGUMENTS
 
 Toolchain: `node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command>` (written `markilo`). Run every toolchain command as its own Bash call, written out in full (`node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command> …`). Do not wrap it in shell variables, `cd`, `&&` chains or pipes: the plugin pre-approves exactly that form, so anything else triggers permission prompts. Craft rules: `${CLAUDE_PLUGIN_ROOT}/skills/design/references/design-principles.md`, `${CLAUDE_PLUGIN_ROOT}/skills/design/references/svg-authoring.md`.
 
-1. Read the concept (`concepts/<id>/concept.json`, `symbol.svg`, `wordmark.svg`) and its reports. Collect the user's
-   feedback (gallery notes may be pasted in) and log it with `markilo answers`.
-2. Decide whether the change is a refinement (edit in place) or a new variant (copy to a new concept id, e.g. `<id>-b`,
-   with `markilo concept new`). Keep the original for comparison.
-3. Apply professional refinements: snap to the grid, unify radii and stroke weights, optical overshoot, ink traps,
-   open counters for 16 px, real gaps instead of color-only separation, balanced artboard fit. Regenerate the
-   wordmark with adjusted tracking or weight if needed; hand-edit individual letters when the idea calls for it.
-4. After every change: `markilo verify --brand <slug> --concept <id>` and `Read` the review sheet. Stop when there are
-   no fails and the warnings are understood.
-5. When the user approves: `markilo finalize --brand <slug> --concept <id> --tagline "<tagline>"`, append the decision to
-   `decisions.md`, then offer the export.
+1. Collect the user's decision (`markilo feedback --brand <slug>`, or their words) and log it with `markilo answers`.
+   Never develop a concept the user dropped. `markilo cost --brand <slug>` before spending.
+2. If the user selected without changes and `markilo proposals --brand <slug> --concepts <id>` lists nothing missing
+   and `verify` has no failing check, ask whether to finish as chosen; on yes, skip to step 5 without a designer or
+   critic. A small, precise change they describe is done directly with the toolchain (`construct`, `lockup`,
+   `verify`). Otherwise: one `markilo:concept-designer` agent in `develop <concept id>` mode with the user's changes, pinned spots, or the
+   combination (it creates a new concept for a combination). Record `--phase refine` with its usage.
+3. `markilo verify --brand <slug> --concept <id>` until nothing fails; `Read` the review, wordmark and context sheets.
+4. After a development pass only, one `markilo:design-critic` agent in `final <concept id>` mode. Apply the fixes that improve the work without
+   changing what the user chose — once, then verify again; do not critique an unchanged image twice. Record
+   `--phase verify`.
+5. Show the user the refined identity (`markilo proposals --brand <slug> --concepts <id>`, the gallery), the measured
+   checks, the originality verdict and the critic's notes labelled as judgment. Further changes go back to step 2.
+6. When the user approves: `markilo finalize --brand <slug> --concept <id> --user-choice "<their words>" --tagline "<tagline>"`
+   (`--accept-risk` only on their explicit yes to an `insufficient-evidence` or `needs-review` verdict), append the
+   decision to `decisions.md`, then offer the export.

package/plugin/skills/research/SKILL.md

@@ -20,8 +20,9 @@ Toolchain: `node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command>` (written `m
    (one call researches every package). Single project → `markilo research repo <path> --brand <slug>`. Read the design
    docs and icon sets the scan reports. `Read` the existing logo files it lists.
 4. Website: ask the user before fetching. Then `markilo research site <url> --brand <slug> --allow-network`.
-5. Market research: delegate to the `markilo:brand-researcher` agent with the brand slug, what is known, and which
-   topics are missing. For a small brand, do it yourself following the playbook.
+5. Market research, proportionate and once: about five category or competitor brands is enough to differentiate.
+   Delegate to the `markilo:brand-researcher` agent only for a broad brief; for most products do it yourself following
+   the playbook. Research that will not change a design decision is not worth its cost.
 6. Write the brief: `markilo brief update --brand <slug> --file <patch.json>` (write the patch to a temp file first).
 7. Ask the user only the open questions that change the design (batched, each with your suggested answer), and log them.
 8. Finish with a short summary: what the brand is, who it is for, the competitive landscape and category codes,