markilo 0.4.0 → 1.0.0

package/plugin/fonts/young-serif/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2023 The Young Serif Project Authors (https://github.com/noirblancrouge/YoungSerif)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/plugin/fonts/zilla-slab/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2017, The Mozilla Foundation ZillaSlab-LightItalic.ttf: Copyright 2017, The Mozilla Foundation ZillaSlab-Regular.ttf: Copyright 2017, The Mozilla Foundation ZillaSlab-Italic.ttf: Copyright 2017, The Mozilla Foundation ZillaSlab-Medium.ttf: Copyright 2017, The Mozilla Foundation ZillaSlab-MediumItalic.ttf: Copyright 2017, The Mozilla Foundation ZillaSlab-SemiBold.ttf: Copyright 2017, The Mozilla Foundation ZillaSlab-SemiBoldItalic.ttf: Copyright 2017, The Mozilla Foundation ZillaSlab-Bold.ttf: Copyright 2017, The Mozilla Foundation ZillaSlab-BoldItalic.ttf: Copyright 2017, The Mozilla Foundation
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/plugin/skills/concepts/SKILL.md

@@ -27,9 +27,9 @@ Toolchain: `node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command>` (written `m
 4. After the agents finish: `markilo diversity --brand <slug>`. Merge or replace directions that are too similar.
 5. Ask the `markilo:design-critic` agent to review all concepts (it reads the review sheets and records judgment).
    Apply the quality gate: the critic's blind brand-fit, distinctiveness and memorability each ≥ 6 and its "would a
-   senior designer present this?" is yes (`markilo concept list` shows `gate` per concept); else back to a
-   concept-designer with the critique and a request for a different move (max 2 rounds; a `nearMiss` first gets one
-   targeted round on its lowest criteria). What still misses is set to `rejected` so the gallery hides it; if fewer than
-   two pass, tell the user plainly and propose new directions instead of showing weak work.
+   senior designer present this?" is yes (`markilo concept list` shows `gate` per concept). A failed concept's `next`
+   decides: `fix` goes back to a concept-designer once with exactly what the critic named; `reject` is set to `rejected`
+   so the gallery hides it — reworking a failed idea almost never works (1 of 34 in the benchmark). If fewer than two
+   pass, tell the user plainly and propose new directions instead of showing weak work.
 6. `markilo gallery` and present: per concept, two lines (idea + measured strengths/risks) and the gallery path.
    Ask the user which to refine.

package/plugin/skills/design/SKILL.md

@@ -67,12 +67,25 @@ Work through these stages. Tell the user which stage you are in. If they asked f
 3. **Brief** — synthesize `markilo profile show --brand <slug>` into the brief
    (`markilo brief update --brand <slug> --file …`). Ask only what you truly cannot infer — usually 2–5
    questions, asked together, each with your suggested answer.
-4. **Explore** — propose 3–5 genuinely different creative directions (idea, metaphor, form language,
+4. **Ideas, then directions.** Before any direction, write the idea longlist: at least 12 one-line visual hooks with
+   `markilo ideas --brand <slug> --add "<what a stranger sees at 32 px>" --means "<what it says>" --source
+   product|audience|name|type|abstract`, from at least three sources (see "Ideas before directions" in
+   `references/design-principles.md`). Then one `markilo:design-critic` agent in `ideas` mode strikes or keeps each one
+   from the words alone and ranks the kept ones — words are the cheapest place to lose a weak idea. In real-project runs
+   every direction drawn from a mechanism metaphor (a round trip, a crossing, a threshold, a keystone) became a bracket,
+   a cross, an arch or a gauge, and was read as a UI glyph. Build directions from the kept ideas, strongest first, and
+   record which idea each concept comes from (`markilo ideas --brand <slug> --idea <id> --concept <concept id>`). When
+   the user is here, show them the kept ideas before sketching; they often know which one is theirs.
+   **Explore** — propose 3–5 genuinely different creative directions (idea, metaphor, form language,
    type, color, why it fits, risks). Different ideas, not variations of one idea. For each, write the visual hook —
    the one thing the eye catches at 32 px — and what a stranger would see first; at most one direction may draw the product's own object or the name's literal noun (a page for
    documents, a chart for finance, a moon for sleep — see "The product's own object is a cliché too" in
    `references/design-principles.md`), and only with a named transformation; at most one may be built on the name's
    initial; at least one must come from what the product does or the audience's world, with no letter and no object.
+   Unless the user wants a symbol above all, one direction is **wordmark-led** (`concept new … --lead wordmark`): the
+   name drawn from a good typeface with one or two letters changed so the word carries the idea, and a symbol cut from
+   that same drawing for icons. Where a category is full of pictograms (developer tools, SaaS), symbols drift into UI
+   icons; a crafted word starts from professionally drawn letters and is often the stronger identity.
    Name each direction's form language from the brief's adjectives ("Form language follows the brief's character").
    Let the user steer.
 5. **Design**, in two passes so weak ideas die cheap:
@@ -81,9 +94,13 @@ Work through these stages. Tell the user which stage you are in. If they asked f
    Before the review, every sketch must be `ready` in `markilo sketches` (no hairline gaps or failing checks); send
    boards that are not back to their designer with the `fix` lines.
    b. **Sketch review** — one `markilo:design-critic` agent reviews every board and records a pick or `none` per
-   concept (`--sketch-pick`). For `none`, send the direction back for one more sketch pass with the critic's
-   suggested move and a second sketch review, or drop it (`--status rejected`). The pick is the critic's: never
-   override a `none` with your own pick.
+   concept (`--sketch-pick`). When the user is here, show them the boards before anything is developed — a sketch is
+   cheap, a developed mark that fails the gate is not: open the gallery (`markilo gallery --serve`; it shows every
+   board with the critic's reading and pick), ask them to pick a sketch per direction or accept the critic's picks,
+   then `markilo feedback --brand <slug> --apply` records their picks (a user's pick wins over the critic's, `none`
+   included). For `none`, send the direction back for one more sketch pass with the suggested move and a second
+   review, or drop it (`--status rejected`). Never override the critic with your own pick; with nobody to ask
+   (unattended), the critic's pick stands.
    c. **Develop** — for each picked sketch, a concept-designer in `develop <sketch id>` mode finishes the mark:
    measured variants, `symbol.svg`, `construction.json` and a wordmark that carries the idea in one or two letters.
 6. **Verify** — `markilo verify --brand <slug> --concept <id>` for every concept, then
@@ -92,17 +109,23 @@ Work through these stages. Tell the user which stage you are in. If they asked f
    to "would a senior designer present this as is?" (`--present`) and adds informed scores as feedback (`--judgment`).
    **Quality gate:** a concept goes to the user only if the critic's blind brand-fit, distinctiveness and memorability
    are each ≥ 6 and its answer is yes — read the result
-   from `markilo concept list --brand <slug>` (`gate: passed|failed`); `finalize` refuses a failed concept unless the
-   user chose it anyway (`--user-choice "<their reason>"`). A `nearMiss` (only the average is short, every required
-   criterion ≥ 6 and the critic said yes) gets one targeted round on its lowest-scored criteria before anything else,
-   then a fresh critique; the bar does not move. Otherwise send it
-   back to a concept-designer with the critique (up to 2 rounds), asking for a different move, not a polish. A concept
-   that still misses is set to `rejected` (`markilo concept update --status rejected`) so the gallery hides it.
+   from `markilo concept list --brand <slug>` (`gate: passed|failed|undecided`); `finalize` refuses any concept that has
+   not passed unless the user chose it anyway (`--user-choice "<their reason>"`). `undecided` (`next: second-look`)
+   means the first cold look landed on the edge of the bar: start two fresh `markilo:design-critic` agents in parallel,
+   each told only `second-look <concept id>`, the brand slug and whether the concept is wordmark-led (never the
+   direction, the rationale or the first critic's notes), then read the gate
+   again — the majority of the three looks decides. The gate's `next` says what to do with a concept that
+   failed: `fix` (the cold scores clear the bar and only the critic's no, for a reason it named, stands in the way) gets
+   one round on exactly that, then a fresh critique; `reject` is set to `rejected`
+   (`markilo concept update --status rejected`) so the gallery hides it. Do not rework a rejected idea: in Markilo's
+   benchmark 1 of 34 concepts sent back after a failed gate passed later (after three rounds); every other pass came
+   from a first look. Spend the budget on new directions instead.
    If fewer than two concepts pass, say so plainly, show what passed, and propose new directions — do not fill the
    gallery with weak work. Two strong concepts beat four mediocre ones.
 7. **Review** — open the gallery as the gallery skill describes (`markilo gallery --serve` in the background, or the
-   offline file), summarize each concept in two lines with its measured strengths and risks, and ask the user to
-   decide there: Keep / Refine / Drop, pins on the mark, side-by-side comparison, then "Send to Claude". Read the
+   offline file), summarize each concept in two lines with its measured strengths and risks (a concept that passed on
+   second looks passed at the edge: say so — in Markilo's 1.0 validation an independent panel rejected such passes), and ask the user to
+   decide there: Keep / Refine / Drop, pins on the mark, side-by-side comparison, then "Send to your agent". Read the
    decisions with `markilo feedback --brand <slug>` instead of asking the user to retype them.
 8. **Refine** — iterate on the chosen concept (optical corrections, construction, wordmark spacing,
    palette), re-verifying each round. Then `markilo finalize --brand <slug> --concept <id> --tagline …`.

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

@@ -48,48 +48,49 @@ Topics: product, audience, market, competitor, visual-identity, typography, colo
 
 ## Design
 
-| Command                                                                                                                                                                                                                                                                                                              | Purpose                                                                                                                                                                                                                                                           |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `concept new --brand s --id ID --title T --direction D --rationale R --semantics a,b --primary '#hex' [--secondary --accent --ink --paper] [--font id --weight n]`                                                                                                                                                   | Create `concepts/ID/`; then write `symbol.svg` there.                                                                                                                                                                                                             |
-| `concept list --brand s`                                                                                                                                                                                                                                                                                             | Concepts with status, files, palette and `gate` (`passed`, `failed`, `not-reviewed`) with the critic average.                                                                                                                                                     |
-| `concept show --brand s --concept ID`                                                                                                                                                                                                                                                                                | One concept with its files, palette, typography, critique and `gate`.                                                                                                                                                                                             |
-| `wordmarks --brand s --concept ID [--fonts a,b] [--weights 500,700] [--tracking -20,0,20] \| --pick wN`                                                                                                                                                                                                              | The name in several faces next to the symbol on `review/wordmarks.png`, measured; `--pick` commits one as `wordmark.svg` with its typography.                                                                                                                     |
-| `sketches --brand s --concept ID`                                                                                                                                                                                                                                                                                    | Build `sketches/*.json` in the concept palette into `sketches/board.png` for the critic's sketch review; says which are `ready` (with `fix` lines). Specs with `members` also get `sketches/family.png`.                                                          |
-| `construct spec.json -o out.svg [--guides c.png] [--set k=v,…]`                                                                                                                                                                                                                                                      | Build a mark from a construction spec (see construction.md).                                                                                                                                                                                                      |
-| `construct spec.json --brand s --concept ID [--vary [--max 24]] [--set k=v,…] [--member name] [--role small]`                                                                                                                                                                                                        | Into the concept: `symbol.svg`, `construction.json`, `review/construction.png`; `--vary` ranks variants in `sketches/variants/`.                                                                                                                                  |
-| `wordmark --text T --font id --weight n -o out.svg [--tracking=-10] [--case lower] [--color '#hex'] [--locale tr]`                                                                                                                                                                                                   | Outlined wordmark with real kerning. Negative tracking needs `=`.                                                                                                                                                                                                 |
-| `lockup --symbol a.svg --wordmark b.svg --layout horizontal\|stacked -o out.svg`                                                                                                                                                                                                                                     | Cap-height aligned lockup.                                                                                                                                                                                                                                        |
-| `concept update --brand s --concept ID [--wordmark wordmark.svg] [--status shortlisted\|rejected] [--judgment memorability=8:"reason"] [--present yes\|no:"reason"] [--blind distinctiveness=n,memorability=n,brand-fit=n,craft=n,versatility=n] [--reads-as "a; b; c"] [--sketch-pick s3\|none --sketch-notes "…"]` | Update files/status/judgment. Criteria: brand-fit, semantic-relevance, distinctiveness, memorability, simplicity, balance, craft, typography, color, cultural-fit, timelessness, premium-perception, versatility. Prints the `gate` (blind scores when recorded). |
-| `color compare #a #b [#c…]`                                                                                                                                                                                                                                                                                          | ΔE00 and WCAG contrast between colors (e.g. an accent vs a well-known brand color).                                                                                                                                                                               |
-| `palette '#primary' [--secondary '#…'] [--accent '#…']`                                                                                                                                                                                                                                                              | OKLCH scales, neutrals, semantic colors, WCAG pairs.                                                                                                                                                                                                              |
-| `fonts`                                                                                                                                                                                                                                                                                                              | Bundled OFL fonts (inter, manrope, space-grotesk, sora, dm-sans, outfit, plus-jakarta-sans, fraunces, ibm-plex-serif, jetbrains-mono).                                                                                                                            |
+| Command                                                                                                                                                                                                                                                                                                                                                                                          | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `concept new --brand s --id ID --title T --direction D --rationale R --semantics a,b --primary '#hex' [--secondary --accent --ink --paper] [--font id --weight n] [--lead wordmark]`                                                                                                                                                                                                             | Create `concepts/ID/`; then write `symbol.svg` there.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `concept list --brand s`                                                                                                                                                                                                                                                                                                                                                                         | Concepts with status, files, palette and `gate` (`passed`, `failed`, `not-reviewed`) with the critic average.                                                                                                                                                                                                                                                                                                                                                            |
+| `concept show --brand s --concept ID`                                                                                                                                                                                                                                                                                                                                                            | One concept with its files, palette, typography, critique and `gate`.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `wordmarks --brand s --concept ID [--fonts a,b] [--weights 500,700] [--tracking -20,0,20] \| --pick wN`                                                                                                                                                                                                                                                                                          | The name in several faces next to the symbol on `review/wordmarks.png`, measured; `--pick` commits one as `wordmark.svg` with its typography.                                                                                                                                                                                                                                                                                                                            |
+| `sketches --brand s --concept ID`                                                                                                                                                                                                                                                                                                                                                                | Build `sketches/*.json` in the concept palette into `sketches/board.png` for the critic's sketch review; says which are `ready` (with `fix` lines). Specs with `members` also get `sketches/family.png`.                                                                                                                                                                                                                                                                 |
+| `construct spec.json -o out.svg [--guides c.png] [--set k=v,…]`                                                                                                                                                                                                                                                                                                                                  | Build a mark from a construction spec (see construction.md).                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `construct spec.json --brand s --concept ID [--vary [--max 24]] [--set k=v,…] [--member name] [--role small]`                                                                                                                                                                                                                                                                                    | Into the concept: `symbol.svg`, `construction.json`, `review/construction.png`; `--vary` ranks variants in `sketches/variants/`.                                                                                                                                                                                                                                                                                                                                         |
+| `wordmark --text T --font id --weight n -o out.svg [--tracking=-10] [--case lower] [--color '#hex'] [--locale tr]`                                                                                                                                                                                                                                                                               | Outlined wordmark with real kerning. Negative tracking needs `=`.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `lockup --symbol a.svg --wordmark b.svg --layout horizontal\|stacked -o out.svg`                                                                                                                                                                                                                                                                                                                 | Cap-height aligned lockup.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `ideas --brand s [--add "<hook>" --means "<why>" --source product\|audience\|name\|type\|abstract] [--idea iN (--keep "<reading>" [--rank n] \| --strike "<reading>") \| --concept ID]`                                                                                                                                                                                                          | The idea longlist before directions: designer adds hooks, critic keeps/strikes from the words and ranks; `next` says what follows.                                                                                                                                                                                                                                                                                                                                       |
+| `concept update --brand s --concept ID [--wordmark wordmark.svg] [--status shortlisted\|rejected] [--judgment memorability=8:"reason"] [--present yes\|no:"reason"] [--blind distinctiveness=n,memorability=n,brand-fit=n,craft=n,versatility=n] [--reviewer <model>] [--reads-as "a; b; c"] [--sketch-pick s3\|none --sketch-notes "…"] [--look <five scores> --look-present yes\|no:"reason"]` | Update files/status/judgment; `--look` records a fresh critic's second look when the gate says `second-look`. Criteria: brand-fit, semantic-relevance, distinctiveness, memorability, simplicity, balance, craft, typography, color, cultural-fit, timelessness, premium-perception, versatility. Prints the `gate` (blind scores when recorded) with `next` (`present`, `fix` once, `reject`, `second-look`), the `reviewer` and whether the gate was calibrated on it. |
+| `color compare #a #b [#c…]`                                                                                                                                                                                                                                                                                                                                                                      | ΔE00 and WCAG contrast between colors (e.g. an accent vs a well-known brand color).                                                                                                                                                                                                                                                                                                                                                                                      |
+| `palette '#primary' [--secondary '#…'] [--accent '#…']`                                                                                                                                                                                                                                                                                                                                          | OKLCH scales, neutrals, semantic colors, WCAG pairs.                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `fonts`                                                                                                                                                                                                                                                                                                                                                                                          | Bundled OFL fonts (inter, manrope, space-grotesk, sora, dm-sans, outfit, plus-jakarta-sans, fraunces, ibm-plex-serif, jetbrains-mono).                                                                                                                                                                                                                                                                                                                                   |
 
 ## Verify
 
-| Command                                                                             | Purpose                                                                               |
-| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `verify --brand s --concept ID`                                                     | All checks; writes reports + `concepts/ID/review/symbol-sheet.png`. **Read the PNG.** |
-| `diversity --brand s`                                                               | Pairwise similarity of active concepts.                                               |
-| `originality --brand s --concept ID [--names a,b]`                                  | Originality & Similarity Report only.                                                 |
-| `score file.svg [--role symbol\|wordmark\|lockup]` / `analyze file` / `compare a b` | Standalone measurements.                                                              |
-| `svg lint file.svg [--master]`                                                      | Master-file rules.                                                                    |
-| `name check "Name" --against a,b,c` / `name trademark "Name" --describe "…"`        | Name confusion and registry pre-screen plan.                                          |
-| `render file.svg -o out.png [--sheet]`                                              | PNG or review contact sheet.                                                          |
+| Command                                                                             | Purpose                                                                                                           |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `verify --brand s --concept ID`                                                     | All checks; writes reports + `concepts/ID/review/symbol-sheet.png` (and `wordmark-sheet.png`). **Read the PNGs.** |
+| `diversity --brand s`                                                               | Pairwise similarity of active concepts.                                                                           |
+| `originality --brand s --concept ID [--names a,b]`                                  | Originality & Similarity Report only.                                                                             |
+| `score file.svg [--role symbol\|wordmark\|lockup]` / `analyze file` / `compare a b` | Standalone measurements.                                                                                          |
+| `svg lint file.svg [--master]`                                                      | Master-file rules.                                                                                                |
+| `name check "Name" --against a,b,c` / `name trademark "Name" --describe "…"`        | Name confusion and registry pre-screen plan.                                                                      |
+| `render file.svg -o out.png [--sheet]`                                              | PNG or review contact sheet.                                                                                      |
 
 ## Deliver
 
-| Command                                                                                                                  | Purpose                                                                                                                                                     |
-| ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `finalize --brand s --concept ID [--tagline T] [--note "usage rule"]... [--accept-risk] [--user-choice "why"] [--force]` | Freeze masters, build lockups (horizontal/stacked/compact), write `final/brand.json`. Refuses a concept that failed the critic gate unless `--user-choice`. |
-| `lock --brand s --primary '#hex' [--symbol f] [--wordmark f] [--lockup f]`                                               | Register an existing identity to preserve byte-for-byte.                                                                                                    |
-| `deliverables --brand s [--set g,…] [--add g,…] [--remove g,…]`                                                          | Which groups this brand needs; suggests from product type and platforms.                                                                                    |
-| `export --brand s [--only logos,web,ios,macos,android,windows,social,marketing,tokens,guidelines] [--all] [--clean]`     | Chosen groups (deliverables) + `asset-manifest.json`.                                                                                                       |
-| `gallery [--brand s] [--serve [--port N]]`                                                                               | `brand/gallery/index.html`; `--serve` serves it on 127.0.0.1 (token, read-only, stops when idle) so "Send to Claude" saves decisions.                       |
-| `feedback [--brand s] [--import file] [--apply]`                                                                         | Decisions from the gallery: keep/refine/drop, tags, notes, pinned spots, preferred concept, ready-to-act requests; `--apply` sets concept status.           |
-| `install-assets --brand s --framework auto\|next\|laravel\|flutter\|static [--project <dir>] [--apply] [--force]`        | Files where the framework expects them (plan unless `--apply`; replaced files backed up). Without `--framework`: `--group web --into public`.               |
-| `agent-setup --target codex\|cursor\|generic [--apply]`                                                                  | Instruction file so another coding agent can run Markilo's workflow with this CLI.                                                                          |
-| `shortcut install\|uninstall\|status [--yes]`                                                                            | Optional personal `/markilo` skill.                                                                                                                         |
-| `doctor`                                                                                                                 | Environment check.                                                                                                                                          |
+| Command                                                                                                                               | Purpose                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `finalize --brand s --concept ID [--tagline T] [--note "usage rule"]... [--accept-risk] [--user-choice "why"] [--force]`              | Freeze masters, build lockups (horizontal/stacked/compact), write `final/brand.json`. Refuses a concept that failed the critic gate unless `--user-choice`.                                                                                                       |
+| `lock --brand s --primary '#hex' [--symbol f] [--wordmark f] [--lockup f]`                                                            | Register an existing identity to preserve byte-for-byte.                                                                                                                                                                                                          |
+| `deliverables --brand s [--set g,…] [--add g,…] [--remove g,…]`                                                                       | Which groups this brand needs; suggests from product type and platforms.                                                                                                                                                                                          |
+| `export --brand s [--only logos,web,ios,macos,android,windows,social,marketing,tokens,guidelines] [--all] [--clean]`                  | Chosen groups (deliverables) + `asset-manifest.json`.                                                                                                                                                                                                             |
+| `gallery [--brand s] [--serve [--port N]]`                                                                                            | `brand/gallery/index.html`; `--serve` serves it on 127.0.0.1 (token, read-only, stops when idle) so "Send to your agent" saves decisions.                                                                                                                         |
+| `feedback [--brand s] [--import file] [--apply]`                                                                                      | Decisions from the gallery: keep/refine/drop, tags, notes, pinned spots, preferred concept, ready-to-act requests; `--apply` sets concept status.                                                                                                                 |
+| `install-assets --brand s --framework auto\|next\|laravel\|flutter\|static [--project <dir>] [--apply [--expect <planId>]] [--force]` | Files where the framework expects them (plan unless `--apply`; one transaction, replaced files backed up; `--expect` refuses a stale plan). Without `--framework`: `--group web --into public`. `install-assets --undo [--apply]` reverses the last installation. |
+| `agent-setup --target codex\|cursor\|vscode\|generic [--model critic=<id>]... [--apply]`                                              | The workflow for another coding agent, and the researcher, designer and critic as its sub-agents (`.codex/agents`, `.cursor/agents`, `.github/agents`) on the models named with `--model`. Dry run unless `--apply`.                                              |
+| `shortcut install\|uninstall\|status [--yes]`                                                                                         | Optional personal `/markilo` skill.                                                                                                                                                                                                                               |
+| `doctor`                                                                                                                              | Environment check.                                                                                                                                                                                                                                                |
 
 Error codes: USAGE, NOT_FOUND, EXISTS, UNSAFE_PATH, INVALID_INPUT, INVALID_SVG, NETWORK_DISABLED, NETWORK,
 ROBOTS_DISALLOWED, LOCKED, NO_WORKSPACE, INTERNAL.

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

@@ -58,7 +58,7 @@ With `--brand/--concept`, palette roles come from the concept, the result is wri
 | `ring`     | `c`, `r` (outer), `width`                                                                                                                                                                             |
 | `arc`      | `c`, `r` (centre line), `from`, `to`, `width`, `cap` `butt`/`round`/`square` — a stroked arc as a filled shape                                                                                        |
 | `sector`   | `c`, `r`, `from`, `to`, `inner` (0 = pie slice)                                                                                                                                                       |
-| `polygon`  | `points`                                                                                                                                                                                              |
+| `polygon`  | `points`; `smooth: true` draws one curved, filled outline through them (`tension`, and `sharp: [i…]` keeps those points as corners — the tip of a drop, the point of a leaf)                          |
 | `regular`  | `c`, `r`, `sides`, `rotate`                                                                                                                                                                           |
 | `star`     | `c`, `r`, `inner`, `points`, `rotate`                                                                                                                                                                 |
 | `line`     | `points`, `width`, `cap`, `join`, `smooth` (curve through the points), `closed`                                                                                                                       |
@@ -162,6 +162,10 @@ Each is a construction technique, not a shape to copy. Combine at most two.
 - **Cut and shift**: `subtract` a thin band (`rect` rotated) through a solid, then `move` one side — motion,
   precision, a "slice" of something.
 - **Truncation**: `intersect` a form with a frame so it is cropped by the edge — tension, scale beyond the frame.
+- **One silhouette**: the object as a single filled outline — a `polygon` with `smooth: true` through 6–12 points,
+  sharp only where the object has a point — instead of a stack of circles, bars and triangles. An object assembled
+  from separate primitives reads as a pictogram (a plumb bob built from a ring, a bar, a trapezoid and a triangle read
+  as a download arrow); one drawn outline with a particular proportion reads as a drawing.
 - **Single gesture**: one `line` with `smooth: true`, consistent `width`, round caps, that draws the idea in one
   movement. Avoid the generic swoosh; the path must describe something specific.
 - **Modular system**: one unit (`defs`) repeated with `repeat` along a grid, where the arrangement itself is the
@@ -193,6 +197,35 @@ a terminal), on top of a calm, well-spaced typeface. Rebuilding every letter fro
 harder to read, and it reads as a display face rather than a brand. Every letter must still be readable on its own:
 check `e`, `a`, `w`, `m` and other complex forms at 1200 px and at 64 px wide.
 
+A treatment can also run through the whole word instead of living in one letter — the usual way a coined name gets
+character. Transforms on a `glyph` apply to every letter at once: `"round": 18` softens every corner and terminal,
+`"grow": 6` adds weight evenly, and a `subtract` of one repeated `rect` (`repeat` with `step`) cuts every stem at the
+same angle. Pick one treatment from the brief's form language, check it at 12 px, and keep the letters themselves
+untouched.
+
+### Wordmark-led concepts (`--lead wordmark`)
+
+The word is the identity, so it is built, not typeset:
+
+1. Choose the face on the wordmark board: `markilo wordmarks --brand <slug> --concept <id>` (the bundled faces,
+   weights and spacing, measured), and commit one with `--pick`.
+2. Build the word as one spec with `glyph` and `"role": "wordmark"`, then change one or two letters with booleans so
+   they carry the idea — join two letters into a ligature, reshape a counter, extend or cut a terminal, share a stroke
+   between neighbours. Aim the change by the printed `glyphs` boxes (stem, bowl, x-height), not by eye.
+3. Cut the icon from the same drawing: a second spec with the same `glyph` and the same change, keeping only the
+   changed letter or pair (`"letters": [i]`), fitted to the square — `construct … --role symbol`. Add a small version
+   when the change disappears at 16 px.
+4. `markilo verify` writes `review/wordmark-sheet.png` (the word at 12–64 px on light, dark, black and white). Read it
+   as a stranger: the word must stay readable at 12 px, and the change must be visible at 24 px.
+
+`construct` and `sketches` measure every changed letter against the font's own alphabet. A letter that now looks more
+like another letter ("o" cut open on the right is a "c": the word reads "necn") makes the sketch not `ready`; a letter
+that lost its counter (an e without its eye) or two letters merged into one shape is a note the critic weighs. Most
+misread wordmarks in Markilo's benchmark came from exactly these: "portwise" read as "partwise", an "ll" as a "4" or
+an "n", a "pinehold" whose e lost its eye. Change a terminal, a join or a counter's shape; keep the stroke that names
+the letter. A separate element dropped into the word is read as punctuation: between letters a hyphen ("searve-x"),
+over a letter an accent ("jourílo"), after the word a full stop. Put it inside a counter or attach it to a letter.
+
 ## Craft checklist
 
 - One unit `u` and a few multiples of it for all widths, radii and gaps; a single corner radius family.

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

@@ -35,6 +35,27 @@ a bent arm. Independent judges call it "a common monogram device" every time. A
 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
@@ -58,6 +79,15 @@ pictorial metaphor, an abstract geometric system, a typographic-only wordmark, a
 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.