markilo 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,50 @@
+# SVG authoring rules for Markilo masters
+
+`markilo svg lint --master` and `markilo verify` enforce these. Build symbols with `markilo construct`
+(see `construction.md`): it produces masters that already follow these rules. Write SVG by hand only for parts no
+construction shape can express.
+
+## Required
+
+- Root: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 W H" data-markilo-role="symbol">`.
+  Symbols use a **square** viewBox (e.g. `0 0 120 120` or `0 0 48 48`). No `width`/`height` needed.
+- Include `<title>Brand — symbol</title>` for accessibility.
+- **Filled shapes only** in masters. If you sketch with strokes, convert them to filled outlines before
+  delivery (rect/path geometry). Strokes are allowed in drafts but scale with the viewBox and can vanish
+  at small sizes.
+- Solid colors as `fill="#rrggbb"`. Every color must come from the concept palette.
+- Pure vector: no `<image>`, no embedded PNG/JPEG/base64, no external references, no `<script>`,
+  no `<foreignObject>`, no event handlers, no web fonts, no live `<text>` (use `markilo wordmark`).
+- No filters (blur, drop shadow) and no opacity in masters. Gradients only if a flat version also works.
+- Unique, meaningful ids only when referenced (masks, clip paths).
+
+## Geometry
+
+- Snap coordinates to the construction grid; use integers or one decimal where possible.
+- Keep the mark inside the artboard with a small margin: ink should span 80–98% of the viewBox.
+- Use `fill-rule="evenodd"` for counters (holes) inside one path when it keeps the path simple.
+- Prefer arcs (`a`) and straight segments over many tiny curve segments; prefer a few precise cubic
+  Béziers over auto-traced noise. Keep total path commands low (verify reports complexity).
+- Round corners with arcs of consistent radius across the mark.
+- For overlaps that should read as separate parts in one color, cut a real gap: ≥ 1/13 of the artboard (≥ 80 units
+  on 1024), which is 1.2 px at 16 px — the verify threshold. Under 1/23 (~45 units) fails.
+
+## Example (structure only — do not reuse the shape)
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" data-markilo-role="symbol">
+  <title>Example — symbol</title>
+  <path fill="#2f4bd8" d="M22 24a6 6 0 0 1 6-6h16v84H28a6 6 0 0 1-6-6z"/>
+  <path fill="#2f4bd8" fill-rule="evenodd" d="M60 30a30 30 0 1 1 0 60a30 30 0 1 1 0-60zm0 14a16 16 0 1 0 0 32a16 16 0 1 0 0-32z"/>
+</svg>
+```
+
+## Wordmarks and lockups
+
+- Generate with `markilo wordmark --text … --font … --weight … -o wordmark.svg`; it embeds cap-height and
+  baseline metadata used by `markilo lockup` and `finalize`.
+- Tune tracking in thousandths of an em (`--tracking=-15` tight display, `0` default, `+40` airy caps).
+- Manual letter edits are allowed after generation: edit individual `<path data-char="…">` elements and
+  keep the root attributes.
+- Hand-made lockups are optional; `finalize` builds horizontal, stacked and compact lockups aligned to
+  cap height with clear space = 1 cap height.

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

@@ -0,0 +1,79 @@
+# Workflow details
+
+## Stage gates
+
+| Stage    | Done when                                                                            | Saved in                          |
+| -------- | ------------------------------------------------------------------------------------ | --------------------------------- |
+| Discover | Sources scanned, existing identity seen, mode chosen (new/refresh/redesign/evaluate) | profile.json, brief.json `mode`   |
+| Research | Each topic covered or listed as a gap; references collected                          | profile.json, research/references |
+| Brief    | Brief validates; user confirmed the key trade-offs                                   | brief.json, answers.json          |
+| Explore  | 3–5 directions, each with idea sentence, form language, type, color, risk            | decisions.md                      |
+| Design   | Each direction has symbol.svg (+ wordmark.svg) and concept.json                      | concepts/<id>/                    |
+| Verify   | No `fail` checks, originality not `redesign`, diversity low, critic scores recorded  | reports/, concept.json `judgment` |
+| Review   | User has seen the gallery and chosen                                                 | answers.json, concept status      |
+| Refine   | Chosen concept re-verified after every change; finalized                             | final/                            |
+| Export   | Export ran without skipped groups the user needs                                     | exports/                          |
+| Deliver  | User has paths, guidelines, quality + originality summary, limitations               | —                                 |
+
+Append one dated line per significant decision to `brand/brands/<slug>/decisions.md` (Edit the file):
+what was decided, why, and the evidence.
+
+## Choosing the mode
+
+- **evaluate**: the user wants an opinion or the brand is locked. Run `markilo score` / `analyze` /
+  `compare` on existing files, then report strengths, risks and recommendations without designing.
+- **refresh**: equity is strong but craft is weak → keep the idea, rebuild geometry, wordmark, palette.
+- **redesign**: the mark fails measurably or contradicts the strategy → new directions.
+- **new**: no identity exists.
+
+Recommend a mode with evidence (measurements of the current mark + findings) and let the user decide.
+
+## Partial requests
+
+- "Research X": Discover + Research + Brief, then stop with a summary of the profile.
+- "Check this logo": evaluate mode (`score`, `analyze`, `compare` against references, `name check`).
+- "Make variations of concept A": Refine.
+- "Export / give me favicons": Export (+ `install-assets` dry run).
+- "Show me": `markilo gallery`.
+
+## Monorepos
+
+1. `markilo research monorepo <repo>` lists packages with `kind` (site, app, client, library, service) and whether they
+   are `brandable` (user-facing). Libraries and services are not brands.
+2. Agree with the user on: the master brand, which packages get their own identity, which are locked (preserved), and
+   the parent of each (e.g. apps living inside a platform product).
+3. `markilo research monorepo <repo> --register --groups products,apps --parent <master> --lock <slugs> --scan` creates the
+   brands, stores each package folder in the brief's `codePaths`, and scans each one into its own profile. Run it once
+   per parent if different groups have different parents.
+4. Read the design-system docs and icon sets the scans report before proposing anything — an existing system is
+   equity.
+5. Scale the work: master + family system first; sites one at a time; many apps (10+) are usually best served by a
+   shared **app icon system** (one grid, one container shape, one color logic, a distinct glyph per app) rather than
+   separate identities. Do apps in batches of 4–6 concept-designer agents.
+6. To place exports back into the repo from a separate brand folder:
+   `markilo install-assets --brand <slug> --group web --into public --project <repo>/<package>` (dry run, then `--apply`
+   after the user agrees).
+
+## Multi-product families
+
+1. `markilo init --family "<Family>"`, then `brand add` for the master brand and each product
+   (`--role product --parent <master>`). Locked members: `brand add "<Name>" --locked` then
+   `markilo lock --brand <slug> --symbol … --primary …`.
+2. Research the family once (master brand), then product-specific facts per product.
+3. Sketch the family as one system, not the master alone: every sketch spec of a family direction has a `members`
+   block (one parameter set, and colours if they differ, per product — construction.md → Families). `markilo
+   sketches` draws master and members together on `sketches/family.png` and marks a sketch not ready when two members
+   read as the same mark (same shape and close colours); members told apart only by colour get a note. The sketch
+   review judges the system: do the members belong together, and can each be told apart at 16 px?
+4. When the master passes the gate, build each product from the same spec: `markilo concept new --brand <product> …`,
+   then `markilo construct <spec> --brand <product> --concept <id> --member <name>` (its parameters and colours),
+   `markilo verify`, and a critique per product. Record the system (construction, colour logic) in
+   `shared/system.json`.
+5. Products that need their own idea (an acquired brand, a different audience) are designed separately with the
+   concept-designer agent, inside the shared system.
+
+## Using Markilo from another project
+
+The workspace lives in the user's project at `./brand` (add it to their VCS or not — their choice; raw
+research captures are git-ignored automatically). Nothing outside `./brand` changes unless the user
+approves `install-assets --apply`.

package/plugin/skills/export/SKILL.md

@@ -0,0 +1,36 @@
+---
+
+name: export
+description: Markilo asset export — generate the complete brand asset kit from the approved identity (logo variants, favicons, PWA, iOS, Android, macOS, Windows icons, social and marketing images, tokens, guidelines) and optionally install web assets into the project. Use when the user wants logo files, favicons, app icons or a brand kit.
+argument-hint: "[brand slug] [groups, e.g. web,ios]"
+allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep
+---
+
+# Markilo · Export
+
+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.
+
+1. `markilo status`. If the brand has no approved kit: for a designed concept run `markilo finalize`; for an existing
+   identity the user wants to keep as-is, use `markilo lock --brand <slug> --symbol … --primary …` (exact copy).
+2. **Choose the package once.** Run `markilo deliverables --brand <slug>`. If `source` is `brief`, the user already
+   chose; go on. If it is `suggested`, tell the user in one short message what you will prepare, in plain words, and
+   offer the left-out groups in the same message as one question, for example: "For a web app I'll prepare the logo
+   files, web icons, link-preview images, color/type tokens and the guidelines. Should I add mobile app icons, desktop
+   app icons or print items (business card, email signature)?" Save the answer with
+   `markilo deliverables --brand <slug> --set …` (or `--add` / `--remove`) and record it with `markilo answers`.
+   If the user already said "everything" or "just do it", keep the suggestion and don't ask.
+3. `markilo export --brand <slug>` (it exports the chosen groups; `--only web,ios,…` or `--all` override). Read the
+   summary: files per group, `notIncluded`, skipped groups, warnings.
+4. Spot-check a few outputs visually with `Read` (e.g. `exports/web/icon-maskable-512.png`,
+   `exports/ios/AppIcon.appiconset/AppIcon-1024.png`, `exports/social/og-image.png`).
+5. `markilo gallery` to refresh the preview.
+6. To place assets in the user's project, plan first: `markilo install-assets --brand <slug> --framework auto
+   [--project <dir>]`. It detects Next.js, Laravel, Flutter or a static site and lists where each file goes and what
+   (if anything) the user must add by hand (a head snippet). Show the plan; only with the user's OK re-run with
+   `--apply` (and `--force` only if they want existing icons replaced — those are backed up to `.markilo-backup/`).
+   Do not edit their source files; give them the snippet instead.
+7. Tell the user where everything is (`exports/`, `asset-manifest.json`, `guidelines/index.html`), that more groups
+   can be added any time (`markilo deliverables --add ios` then `markilo export`), and mention that
+   X (Twitter) header sizes could not be verified against x.com documentation.

package/plugin/skills/gallery/SKILL.md

@@ -0,0 +1,29 @@
+---
+
+name: gallery
+description: Markilo Brand Preview Gallery — build and open the local HTML gallery that compares concepts and shows every variant on realistic surfaces (browser tab, app icons, dock, store listing, social preview, business card) with quality and originality results. Use when the user wants to see, compare or review designs.
+argument-hint: "[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 · Gallery
+
+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.
+
+1. Preferred: start `markilo gallery --serve` as a **background** Bash command (it keeps running). Its first output
+   line has `serving`: a `http://127.0.0.1:<port>/…?t=<token>` URL. Give the user that URL. The server only listens
+   on this computer, needs the token, serves only the gallery and exported artwork, and stops by itself when idle.
+   Without a background shell, run `markilo gallery` instead: it writes `brand/gallery/index.html`, a self-contained
+   file that works offline; give the user its `file://` URL.
+2. Explain the review flow in two lines: on each concept choose Keep / Refine / Drop, add revision tags or a note, click
+   on the big mark to pin what should change at that spot, tick "Compare" on two or more concepts to see them side by
+   side and mark one "Prefer this". Then press **Send to Claude** (served) or **Download decisions** (file) and tell
+   you when done.
+3. Read the decisions: `markilo feedback --brand <slug>` (after a download: `markilo feedback --import <file>`). It
+   returns each decision with tags, notes and pinned spots (e.g. "at top-right: thicker stem"), the preferred concept
+   and ready-to-act requests. Repeat them back to the user in one short summary.
+4. Act: `markilo feedback --brand <slug> --apply` marks dropped concepts rejected and kept ones shortlisted (only after
+   the user confirmed the summary). Log what was decided (`markilo answers`) and continue with the refine skill for
+   each "refine" request — pinned spots tell you where on the mark the change belongs.

package/plugin/skills/markilo/SKILL.md

@@ -0,0 +1,12 @@
+---
+
+name: markilo
+description: Markilo entry point (same as markilo:design). Use when the user types /markilo or asks Markilo for anything brand-related.
+argument-hint: "[URL, repo path, brand name or task]"
+allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep Skill
+---
+
+Request: $ARGUMENTS
+
+Load the `markilo:design` skill (Skill tool) and follow it for this request. If you only need a quick toolchain
+command, run it as `node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command>` — never as a bare `markilo` command, and never through shell variables, `cd` or `&&` chains (the plugin pre-approves exactly that form).

package/plugin/skills/originality/SKILL.md

@@ -0,0 +1,25 @@
+---
+
+name: originality
+description: Markilo market intelligence and originality check — compare a logo concept or existing mark against competitor and category marks (silhouette, perceptual hash, structure, color), check name confusion and plan trademark pre-screening, and write an Originality & Similarity Report. Use when the user asks whether a logo or name is original, similar to others, or safe to use.
+argument-hint: "[brand slug, concept id, or path to a logo file]"
+allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep WebSearch WebFetch
+---
+
+# Markilo · Originality
+
+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. Policy: `${CLAUDE_PLUGIN_ROOT}/skills/design/references/originality.md`.
+
+- **A concept in the workspace**: make sure references exist (`markilo reference list --brand <slug>`); if fewer than ~5,
+  collect more (competitors, category leaders, famous marks with a similar form) and add them with `markilo reference add`
+  — ask before web searches that reveal unreleased names. Then `markilo originality --brand <slug> --concept <id>` and
+  `markilo diversity --brand <slug>`.
+- **A loose file** (any SVG/PNG): `markilo analyze <file>` and `markilo compare <file> <reference>` for each reference.
+- **A name**: `markilo name check "<Name>" --against <competitors>` and `markilo name trademark "<Name>" --describe "<product>"`.
+  If the user agrees, run registry searches via the links and log each with `markilo profile add-source --type registry`.
+
+Report in plain language: the verdict, the top matches with their numbers and reasons, what was and was not compared,
+and the limits (not legal advice; no results ≠ unique). Recommend redesign for high risk instead of small tweaks.
+Open the report file path for the user: `brand/brands/<slug>/reports/originality-<id>.md`.

package/plugin/skills/refine/SKILL.md

@@ -0,0 +1,25 @@
+---
+
+name: refine
+description: Markilo refinement — iterate on a chosen logo concept (geometry, optical corrections, wordmark spacing, palette, small-size version) with verification after every change, then finalize it as the approved identity. Use when the user picks a concept or asks for changes to one.
+argument-hint: "[brand slug, concept id and the feedback]"
+allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep
+---
+
+# Markilo · Refine and finalize
+
+Request: $ARGUMENTS
+
+Toolchain: `node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command>` (written `markilo`). Run every toolchain command as its own Bash call, written out in full (`node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" <command> …`). Do not wrap it in shell variables, `cd`, `&&` chains or pipes: the plugin pre-approves exactly that form, so anything else triggers permission prompts. Craft rules: `${CLAUDE_PLUGIN_ROOT}/skills/design/references/design-principles.md`, `${CLAUDE_PLUGIN_ROOT}/skills/design/references/svg-authoring.md`.
+
+1. Read the concept (`concepts/<id>/concept.json`, `symbol.svg`, `wordmark.svg`) and its reports. Collect the user's
+   feedback (gallery notes may be pasted in) and log it with `markilo answers`.
+2. Decide whether the change is a refinement (edit in place) or a new variant (copy to a new concept id, e.g. `<id>-b`,
+   with `markilo concept new`). Keep the original for comparison.
+3. Apply professional refinements: snap to the grid, unify radii and stroke weights, optical overshoot, ink traps,
+   open counters for 16 px, real gaps instead of color-only separation, balanced artboard fit. Regenerate the
+   wordmark with adjusted tracking or weight if needed; hand-edit individual letters when the idea calls for it.
+4. After every change: `markilo verify --brand <slug> --concept <id>` and `Read` the review sheet. Stop when there are
+   no fails and the warnings are understood.
+5. When the user approves: `markilo finalize --brand <slug> --concept <id> --tagline "<tagline>"`, append the decision to
+   `decisions.md`, then offer the export.

package/plugin/skills/research/SKILL.md

@@ -0,0 +1,28 @@
+---
+
+name: research
+description: Markilo brand research only — scan a repository or website, research the market, audience, competitors, category conventions, culture and trademarks, and build a sourced Brand Intelligence Profile and brief. Use when the user asks to research or analyze a brand before any design.
+argument-hint: "[URL, repo path or brand name]"
+allowed-tools: Bash(node "${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs" *) Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/markilo.mjs *) Read Write Edit Glob Grep WebSearch WebFetch
+---
+
+# Markilo · Research
+
+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/research-playbook.md` and `${CLAUDE_PLUGIN_ROOT}/skills/design/references/cli.md` first.
+
+1. Find or create the workspace: `markilo status` — with `found: false`, `markilo init` and `markilo brand add "<Name>"`.
+2. Check what is already known: `markilo profile show --brand <slug>` and `markilo answers --brand <slug>`.
+   Do not repeat finished research; extend it.
+3. Local sources: for repositories run `markilo research monorepo <path>` first. Several sites/apps → confirm the list and
+   locked members with the user, then `markilo research monorepo <path> --register --groups … --parent <master> --lock … --scan`
+   (one call researches every package). Single project → `markilo research repo <path> --brand <slug>`. Read the design
+   docs and icon sets the scan reports. `Read` the existing logo files it lists.
+4. Website: ask the user before fetching. Then `markilo research site <url> --brand <slug> --allow-network`.
+5. Market research: delegate to the `markilo:brand-researcher` agent with the brand slug, what is known, and which
+   topics are missing. For a small brand, do it yourself following the playbook.
+6. Write the brief: `markilo brief update --brand <slug> --file <patch.json>` (write the patch to a temp file first).
+7. Ask the user only the open questions that change the design (batched, each with your suggested answer), and log them.
+8. Finish with a short summary: what the brand is, who it is for, the competitive landscape and category codes,
+   opportunities for distinctiveness, risks, and open gaps. Mark inferences as inferences.