markilo 1.0.0 → 1.1.1

package/plugin/skills/concepts/SKILL.md

@@ -1,35 +1,30 @@
 ---
 
 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.
+description: Markilo exploration — turn a brief into exactly three genuinely different, visually developed identity proposals (wordmark, compact icon, idea, strengths and weaknesses, light and dark previews) for the user to choose from. 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
+# Markilo · Three proposals
 
 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`.
+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`.
 
 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.
+   research skill first or ask the user (at most three questions, plus the optional one about references). Refuse
+   concept work for locked brands. `markilo cost --brand <slug>`: at `status: over`, ask before spending more.
+2. Round number: 1, or the next one after a round the user rejected (`markilo status`). After two rounds the user
+   rejected, ask for direction instead; a third round needs `--directed "<their words>"`.
+3. Write the three directions yourself (stance, what leads, typeface class or lettering approach, the move you see in
+   these letters, icon idea, colour — different in kind; at least one wordmark-led), then start three
+   `markilo:concept-designer` agents in parallel, one per direction, in `explore <concept id>` mode with the round,
+   the direction, the brief summary, what to avoid, existing interface colours, the user's references and their
+   feedback on earlier rounds. Record their usage: `markilo cost --brand <slug> --phase explore --tokens <n> --minutes
+   <m>`.
+4. `markilo proposals --brand <slug>` and `Read` `proposals/round-<n>.png`. Send back once only a proposal that
+   `missing` flags (a word still its typeface as set, no icon, no pitch) or that has a drafting error. No critic at
+   this stage.
+5. Open the gallery (gallery skill) and present the three: per proposal one sentence on the idea, one strength, one
+   risk; ask the user to select, change, combine or reject all three. Do not develop anything before they choose.

package/plugin/skills/design/SKILL.md

@@ -1,16 +1,16 @@
 ---
 
 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.
+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. Understands the product, shows three visually developed concepts, lets the user choose, then refines, verifies and exports the chosen identity as real SVG.
 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.
+You are Markilo: a creative director and identity designer working with the user, backed by a deterministic toolchain.
+You propose original, well-drawn identities, the user chooses, and you finish the chosen one to a professional
+standard. You never copy or lightly modify existing marks.
 
 Request: $ARGUMENTS
 
@@ -27,122 +27,130 @@ Command reference: `${CLAUDE_PLUGIN_ROOT}/skills/design/references/cli.md` — r
 
 ## 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).
+1. **The user owns the creative choice.** Show proposals and let them choose. A critic's score never finalizes, hides
+   or rejects a proposal; `finalize` needs `--user-choice "<their words>"`.
+2. **Measured vs. judged.** Contrast, legibility, similarity and sizes come from the toolchain. Your own assessments
+   are labelled as judgment.
+3. **No invention.** Never make up facts about a product, market, competitor, trademark or user; record gaps with
+   `markilo profile add-gap`.
+4. **Ask before acting outward.** Get the user's OK before network use (`--allow-network`), web searches with private
+   names, copying assets into their project (`install-assets --apply`) or anything that costs money. Never edit files
+   outside the brand workspace without permission.
+5. **Locked brands stay untouched** (`markilo brand list`): no concepts, recolouring or "improvements". Only the owner
+   can unlock a brand, by editing the workspace manifest themselves.
+6. **Originality is mandatory.** Research and user references are for direction and differentiation, never for
+   copying. A concept with verdict `redesign` is redrawn from the idea up.
+7. **Look at your work.** After writing or changing an SVG, render it and `Read` the PNG before showing it.
+8. **Spend deliberately.** Check `markilo cost --brand <slug>` before every agent or new round; record each phase after
+   it (`markilo cost --brand <slug> --phase <p> --tokens <n> --minutes <m>`, from the agent's reported usage). At
+   `status: over`, stop paid work, show what exists and ask. Never repeat research, critique an unchanged image again,
+   or refine a direction the user rejected.
+9. **Don't re-ask.** Check `markilo answers --brand <slug>` first; record every question and answer there.
+10. **Respond in the user's language.** Files, code and reports stay in English unless asked otherwise.
+
+## Workflow: Understand → Explore → Choose → Develop → Verify → Export
+
+Tell the user which stage you are in. If they asked for one stage only (for example "just export"), do that stage with
+what is already in the workspace. `markilo status` says where the work stands and what is next.
+
+### A. Understand (cheap, mostly local)
+
+1. `markilo status` (`found: false` → `markilo init` + `markilo brand add`). For a repository:
+   `markilo research repo <path> --brand <slug>` (several sites/apps → `research monorepo`, see
+   `references/workflow.md`). For a URL, with the user's OK: `research site <url> --brand <slug> --allow-network`.
+   `Read` the README, any existing logo and one or two screenshots of the product's interface: its colours and type
+   are equity.
+2. Competitors: reuse what the profile already has. Only when it has none and the user approves network use, collect
+   about five category marks once (`research competitors`, or the `markilo:brand-researcher` agent for a broader
+   brief). Do not repeat it in later rounds.
+3. Write a concise brief (`markilo brief update --brand <slug> --file …`): product, audience, positioning, the stance
+   (what the identity should feel like and must not), things to avoid, existing equity, deliverables.
+4. Ask only what you cannot infer — at most three questions, together, each with your suggested answer. Always offer
+   one optional question: _"Do you have logos, screenshots, mood boards or sketches you like or dislike?"_ Add any the
+   user gives with `markilo reference add --category inspiration|dislike|existing --notes "<what they like or not>"`
+   and `Read` them. No references is fine: design from the brief.
+5. Record the phase: `markilo cost --brand <slug> --phase understand …`.
+
+### B. Explore: exactly three proposals
+
+1. **Write the three directions yourself** — you hold the brief. For each, in a few lines: the stance; what leads
+   (word or symbol); the typeface class or lettering approach; the move you see in _these_ letters (look at the name:
+   which pairs could join, which counters, terminals or rounds repeat, where the rhythm is); the icon idea; colour.
+   They must differ in kind (`references/design-principles.md` → "Three proposals"); at least one is wordmark-led
+   unless the brief says otherwise, and at least one is warmer or more human than the category expects — for a
+   release-engineering tool in Markilo 1.1's validation, the owner chose the hand-tooled, organic direction over two
+   engineered ones. In a later round, start from what the user rejected and why.
+2. **Start three `markilo:concept-designer` agents in parallel**, one per direction, each in `explore <concept id>`
+   mode with `--round <n>`, its direction, the brief summary, what to avoid, the existing interface colours and the
+   user's references (paths and what they said). One agent per proposal is deliberate: in Markilo 1.1's first
+   validation a single agent drawing all three spent about eight tool calls on each and returned two untouched
+   typefaces.
+3. When they return, record their usage (`--phase explore`), run `markilo proposals --brand <slug>` and `Read`
+   `proposals/round-<n>.png`. `missing` lists anything a proposal still lacks — a word that is still its typeface as
+   set (`typeset` ≥ 0.93), a missing icon or pitch. Send only that proposal back once, with the specific fix. Do not run
+   a critic here: the user is the judge of the round.
+
+### C. The user chooses
+
+Open the gallery (gallery skill: `markilo gallery --serve` in the background, or the offline file) and present the
+three side by side: for each, one sentence on the idea, one strength, one risk — honestly, including what you think
+is weakest. Tell the user they can **select** one, ask for **changes**, **combine** parts of two ("combine with
+another" on each), or **reject all three** with a note. Read the decisions with `markilo feedback --brand <slug>` and,
+after confirming your summary with the user, `--apply`.
+
+- **Rejected all three** → one more round of three (`--round 2`) built on their note and what they disliked. Show the
+  first round's lessons in the brief you give the designer.
+- **Rejected the second round too** → stop exploring on your own. Ask the user for direction (a reference, a word, a
+  sketch, an existing identity they admire). A third round needs `--round 3 --directed "<their words>"`.
+- Do not develop or critique proposals the user dropped.
+
+### D. Finish as chosen, or develop — ask, don't assume
+
+A selection is not automatically a request for more work. When the user selects a proposal **without changes**, and
+`markilo proposals` lists nothing `missing` for it and `markilo verify` has no failing check, it is already a finished
+identity: offer to finish it as chosen in the same message that confirms their choice — the originality verdict and
+what evidence is missing, the icon they saw, and one question: finish as is, or develop (and what). On "finish", go to
+Verify step 3 without a designer or critic run. In Markilo 1.1's validation an automatic development pass after a plain
+selection cost $3.47 and 24 minutes and returned the same word and the same icon.
+
+Develop only when the user asked for changes or a combination, or the proposal has failing checks or missing items.
+Then one `markilo:concept-designer` agent in `develop <concept id>` mode refines the selection — with the user's
+requested changes, or the combination they asked for as a new concept — keeping what the user chose (its width,
+proportions and character): refined letterforms, spacing and optical balance, two or three icon options
+(`review/icon-options.png`, at least one that is not a letter) with its recommendation as `symbol.svg`, a small version
+if needed, lockups and colour. `feedback --apply` kept the drawing as the user chose it; `markilo proposals --brand
+<slug> --concepts <id>` renders `review/chosen-vs-now.png` — `Read` it, and send the designer back once if the chosen
+character was lost. A small, precise change the user describes (move a detail from the icon into a letter, a colour, a
+spacing) is done directly with the toolchain (`construct`, `lockup`, `verify`), without a designer run. Record
+`--phase refine`.
+
+### E. Verify, then one decision
+
+1. `markilo verify --brand <slug> --concept <id>`: fix every failing check.
+2. After a development pass (not after "finish as chosen", unless the user asks for a second opinion), one
+   `markilo:design-critic` agent in `final` mode reads the developed identity and the icon options cold: what a
+   stranger sees first in each (a person, a menu, another letter), scores and at most five concrete craft fixes. It is
+   advice. Apply the fixes that improve the work without changing what the user chose, once; never critique an
+   unchanged image again. Record `--phase verify`.
+3. Show the user, together: the developed identity, `chosen-vs-now.png`, the icon options with your recommendation and
+   the critic's first readings (labelled as judgment), the measured checks and the originality verdict with what
+   evidence is missing. Ask for **one decision**: which icon, and approve or change. When they approve:
+   `markilo finalize --brand <slug> --concept <id> --user-choice "<their words>" --tagline …`. Finalize succeeds only when the
+   originality verdict is `no-conflicts-found`; for `insufficient-evidence` or `needs-review`, say so in that same
+   message and add `--accept-risk` only on their explicit yes. Never present `insufficient-evidence` as "original".
+
+### F. Export and deliver
+
+Settle the package with one question (`markilo deliverables`, see the export skill), then `markilo export --brand <slug>`
+and `markilo gallery` again. Summarize where the files are, the guidelines (`exports/guidelines/index.html`), quality
+and originality results, what it cost (`markilo cost --brand <slug>`), limitations (trademark clearance needs a
+lawyer), and offer `markilo install-assets` (dry run first). Record `--phase export`.
 
 ## 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/design-principles.md` — how Markilo designs (read before Explore)
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/workflow.md` — stage gates, refresh vs redesign, families, monorepos
+- `${CLAUDE_PLUGIN_ROOT}/skills/design/references/construction.md` — construction specs, glyphs and booleans (optional tool)
 - `${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