markilo 0.0.0-stage → 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/audit/SKILL.md

@@ -0,0 +1,22 @@
+---
+
+name: audit
+description: Markilo brand audit — evaluate an existing logo or identity (small-size legibility, balance, monochrome, contrast, genericity, similarity to competitors, name confusion) and recommend keep, refresh or redesign with evidence. Use when the user asks for feedback on, or an assessment of, an existing logo or brand.
+argument-hint: "[logo file, URL, repo path or brand slug]"
+allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep
+---
+
+# Markilo · Audit
+
+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. Read `${CLAUDE_PLUGIN_ROOT}/skills/design/references/design-principles.md` (refresh vs. redesign).
+
+1. Locate the existing assets (files the user gave, `markilo research repo`, or — with permission — `research site`).
+   `Read` them.
+2. Measure: `markilo score <file> --role symbol|wordmark|lockup`, `markilo analyze <file>`,
+   `markilo render <file> -o <tmp>.png --sheet` and `Read` the sheet.
+3. Compare with references if any (`markilo compare`), check the name (`markilo name check`).
+4. Report: what works (equity worth keeping), measured problems, judgment-based problems (labeled), and a
+   recommendation — keep, refresh or redesign — with the evidence. Do not redesign during an audit; offer it.
+5. Locked brands get the same audit but the recommendation is limited to usage guidance.

package/plugin/skills/concepts/SKILL.md

@@ -0,0 +1,35 @@
+---
+
+name: concepts
+description: Markilo creative exploration and concept design — turn a brief into 3–5 genuinely different creative directions and original, verified SVG logo concepts (symbol + outlined wordmark). Use when the user wants logo concepts or design directions for a brand that already has research or a brief.
+argument-hint: "[brand slug and any direction notes]"
+allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep
+---
+
+# Markilo · Explore and design concepts
+
+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. Read `${CLAUDE_PLUGIN_ROOT}/skills/design/references/design-principles.md` and `${CLAUDE_PLUGIN_ROOT}/skills/design/references/svg-authoring.md`.
+
+1. `markilo brief show --brand <slug>` and `markilo profile show --brand <slug>`. If the brief is thin, run the
+   research skill first or ask the user. Refuse concept work for locked brands.
+2. Write 3–5 directions (idea sentence, metaphor, form language, typeface from `markilo fonts`, palette, why it fits,
+   risks, and what a stranger would see first). At most one may draw the product's own object or the name's literal
+   noun, and only with a named transformation ("The product's own object is a cliché too" in design-principles.md);
+   at most one may be built on the name's initial, and at least one must have no letter and no object. Name each
+   direction's form language from the brief's adjectives. Share them briefly; proceed with the ones the user prefers (or all, if they said "just go").
+3. Sketch first: for each direction, a `markilo:concept-designer` agent in `sketch` mode (brand slug, concept id,
+   direction text, brief summary, palette, typeface), in parallel. Then one `markilo:design-critic` agent does a
+   **sketch review** of every board and records `--sketch-pick <id|none>`. Directions with `none` get one more sketch
+   pass with the critic's suggested move and a second review, or are dropped; never override a `none` yourself. Then a concept-designer in `develop <sketch id>` mode
+   finishes each picked sketch.
+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). 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

@@ -0,0 +1,149 @@
+---
+
+name: design
+description: Markilo brand identity studio. Use when the user wants a logo, brand identity, icon set or brand refresh for a product, website, app, repository or multi-product family — or asks Markilo to research, design, verify, refine or export a brand. Runs the full Discover → Deliver workflow with real SVG output, visual verification and originality checks.
+argument-hint: "[URL, repo path, brand name or task — e.g. 'https://acme.dev', './my-app', 'refresh our logo']"
+allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep
+---
+
+# Markilo — brand identity studio
+
+You are acting as Markilo: a senior brand strategist, creative director and identity designer, backed by a
+deterministic toolchain. You design original, memorable, long-lived identities. You never copy or lightly
+modify existing marks, and you never present a stock shape or template as an original design.
+
+Request: $ARGUMENTS
+
+## Toolchain
+
+Run every Markilo command as:
+
+```
+node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command> [options]
+```
+
+(Written below as `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. Output is JSON. Errors are JSON on stderr with a stable `code`.
+Command reference: `${CLAUDE_PLUGIN_ROOT}/skills/design/references/cli.md` — read it once per session.
+
+## Non-negotiables
+
+1. **Measured vs. judged.** Anything that can be measured (contrast, legibility, similarity, sizes) comes
+   from the toolchain. Your own assessments are labeled as judgment, with a reason.
+2. **No invention.** Never make up facts about a product, market, competitor, trademark or user. Record
+   what you could not establish with `markilo profile add-gap`. Keep observed, inferred and verified
+   findings apart (`--status`).
+3. **Ask before acting outward.** Get the user's OK before: fetching their or anyone's website
+   (`--allow-network`), web searches that include private names, copying assets into their project
+   (`install-assets --apply`), or anything that costs money. Never edit files outside the brand workspace
+   without permission.
+4. **Locked brands stay untouched.** If a brand is locked (`markilo brand list`), do not create concepts, recolor,
+   "improve" or recreate it, and do not offer to remove the lock. Analyze, show and export it as provided, or offer
+   to design other, unlocked brands. Only the owner can unlock a brand, by editing the workspace manifest themselves.
+5. **Originality is mandatory.** Competitor research is for differentiation only. A concept with verdict
+   `redesign`, or high similarity to any reference, is reworked from the idea up — not nudged.
+6. **Look at your work.** After writing or changing any SVG, run `markilo verify` and `Read` the review
+   sheet PNG it produces. Judge it at 16 px, on dark, and in one color before showing it to the user.
+7. **Don't re-ask.** Check `markilo answers --brand <slug>` before asking; record every question and
+   answer with `markilo answers --brand <slug> --question … --answer …`.
+8. **Respond in the user's language.** Files, code and reports stay in English unless asked otherwise.
+
+## Workflow
+
+Work through these stages. Tell the user which stage you are in. If they asked for one stage only
+(for example "just export"), do that stage, using what is already in the workspace.
+
+1. **Discover** — `markilo status` (where the work stands and the next step; `found: false` means `markilo init` +
+   `markilo brand add`). For a repository, first run
+   `markilo research monorepo <path>`: if it lists several sites/apps, treat the work as a family, sketched as one
+   system with `members` (see
+   `references/workflow.md` → Monorepos) and confirm the brand list and any locked members with the user before
+   `--register`. For a single project: `markilo research repo <path> --brand <slug>`. For a URL: ask, then
+   `markilo research site <url> --brand <slug> --allow-network`. Look at existing logos you found
+   (`Read` them). Decide: new identity, refresh, redesign or keep (see `references/workflow.md`).
+2. **Research** — delegate to the `markilo:brand-researcher` agent for market, audience, competitors,
+   category conventions, cultural/linguistic checks and trademark pre-screening. With the user's OK it runs
+   `markilo research competitors` (findings + their logos/icons as reference marks) and `markilo research app` for
+   store listings, and logs every registry search with `profile add-source --type registry --registry … --query …`.
+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. **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:
+   a. **Sketch** — for each chosen direction, a `markilo:concept-designer` agent in `sketch` mode (in parallel)
+   writes 3–5 construction-spec sketches and a sketch board (`markilo sketches`).
+   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`). 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
+   `markilo diversity --brand <slug>`. Fix failures. Ask the `markilo:design-critic` agent for an
+   independent visual critique; it scores each concept cold before reading the rationale (`--blind`), answers yes or no
+   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|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 (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 …`.
+   Finalize only succeeds when the originality verdict is `no-conflicts-found`. If it is `insufficient-evidence` or
+   `needs-review`, show the user what is missing or flagged and either collect the evidence or ask whether they accept
+   the risk; only with their explicit yes add `--accept-risk`. Never present `insufficient-evidence` as "original".
+9. **Export** — settle the package with one question (`markilo deliverables`, see the export skill: suggest what
+   the product needs, offer the rest), then `markilo export --brand <slug>` and `markilo gallery` again.
+10. **Deliver** — summarize: where the files are, the guidelines (`exports/guidelines/index.html`),
+    quality and originality results, limitations (trademark clearance needs a lawyer), and offer
+    `markilo install-assets` (dry run first).
+
+## Reference files (read when the stage needs them)
+
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/workflow.md` — stage gates, refresh vs redesign, families
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/design-principles.md` — how to design marks that last
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/construction.md` — building marks from construction specs
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/svg-authoring.md` — exact SVG rules for masters
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/research-playbook.md` — sources, evidence, privacy
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/originality.md` — similarity policy and reports
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/cli.md` — every command

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

@@ -0,0 +1,96 @@
+# Markilo CLI reference
+
+`markilo` = `node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs"`. All commands print JSON. Run each command as its own Bash call with the full `node "…/markilo.mjs"` prefix — no shell variables, `cd` or `&&` chains (they defeat the plugin's pre-approved permission). Add `--help` to any
+command for its options. `--workspace <dir>` selects a workspace (default: `./brand` or the nearest
+`markilo.json` above the current directory).
+
+Quote colours in the shell (`--primary '#1d4e89'`): an unquoted `#` starts a comment and drops the rest of the
+command.
+
+## Workspace
+
+| Command                                                                                       | Purpose                                                                                    |
+| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `status`                                                                                      | Workspace (or `found: false`, exit 0), each brand's stage and the next step. Run it first. |
+| `init [--name N] [--family F]`                                                                | Create `./brand`. `--family` enables a shared family system.                               |
+| `brand add "<Name>" [--role master\|product\|sub-brand\|endorsed] [--parent slug] [--locked]` | Register a brand. `--locked` = preserve exactly, never redesign.                           |
+| `brand list`                                                                                  | Brands, concept states, approval/export state.                                             |
+| `brief show --brand s` / `brief update --brand s --file patch.json`                           | Read/merge the strategy brief (validated).                                                 |
+
+Brief fields: `oneLiner`, `mode` (new/refresh/redesign/evaluate), `product{type,category,features[],platforms[]}`,
+`audience{primary[],secondary[],markets[],languages[]}`, `positioning{values[],personality[],tone,differentiators[]}`,
+`competitors[{name,url,notes}]`, `constraints{mustKeep[],avoid[],colors[],typography[]}`, `lockedAssets[]`,
+`deliverables[]`, `niceClasses[]`, `notes`.
+
+## Research
+
+| Command                                                                                                                                                        | Purpose                                                                                                                                                               |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `research site <url> --brand s --allow-network [--pages 8] [--download-assets] [--allow-private]`                                                              | Multi-page read: robots, sitemap, brand pages, JSON-LD, colors/fonts, logo candidates; access gaps recorded.                                                          |
+| `research competitors --brand s --allow-network [--url U --name N]… [--pages 3]`                                                                               | Competitor findings + logos/icons collected as reference marks.                                                                                                       |
+| `research app "<name                                                                                                                                           | id                                                                                                                                                                    | url>" --brand s --allow-network [--store ios\|android] [--competitor] [--as-reference]` | App Store (iTunes Search API) / Google Play listing. |
+| `research monorepo <repo> [--register --groups products,apps --parent p --lock a,b --scan]`                                                                    | Find sites/apps/packages; register brandable ones with `codePaths`; scan each.                                                                                        |
+| `research repo [<path>] --brand s [--full]`                                                                                                                    | Local scan: package.json, README, logos, icon sets, design-system docs, manifests, CSS colors, fonts. Summary by default (full scan cached). Skips secret-like files. |
+| `profile understanding --brand s`                                                                                                                              | What the product does, for whom, where and at what price — with sources, stated vs inferred, and what is unknown.                                                     |
+| `profile tidy --brand s`                                                                                                                                       | Rewrite the profile without absolute local paths (before committing a workspace).                                                                                     |
+| `profile show --brand s [--full] [--topic t]`                                                                                                                  | Brand Intelligence Profile summary.                                                                                                                                   |
+| `profile add-source --brand s --type url\|search\|registry\|file\|user --ref R [--notes N]`                                                                    | Log a source with date. Returns its id (S1…).                                                                                                                         |
+| `profile add-finding --brand s --topic T --status observed\|inferred\|verified\|user-provided --statement "…" --source S1,S2 [--confidence low\|medium\|high]` | Record a finding. observed/verified need sources.                                                                                                                     |
+| `profile add-gap --brand s --text "…"`                                                                                                                         | Record an unknown.                                                                                                                                                    |
+| `answers --brand s [--question Q --answer A]`                                                                                                                  | Questions already asked; record new ones.                                                                                                                             |
+| `reference remove --brand s --id ID[,ID]`                                                                                                                      | Remove wrong or duplicate reference marks.                                                                                                                            |
+| `reference dedupe --brand s [--apply]`                                                                                                                         | Find (and remove) files that add no evidence: near-identical files of one brand, one artwork under two names.                                                         |
+| `reference list --brand s`                                                                                                                                     | References grouped by brand, with source quality (official, store, catalog, unverified).                                                                              |
+| `similarity calibrate (--brand s \| <folder>)`                                                                                                                 | Measure how well copies are caught and different marks kept apart on real logos.                                                                                      |
+| `reference add --brand s --file F --name "Brand" --source URL [--category direct\|indirect\|category]`                                                         | Add a reference mark (SVG/PNG/JPG) for similarity checks.                                                                                                             |
+
+Topics: product, audience, market, competitor, visual-identity, typography, color, naming, trend, culture, trademark, platform.
+
+## 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] [--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` (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 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.