trykeyline 0.0.0-stage → 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "keyline",
+  "owner": {
+    "name": "Mihir Modi",
+    "url": "https://github.com/Mihirmodi27"
+  },
+  "metadata": {
+    "description": "Keyline: interface design laws for coding agents, applied in your project's own tokens.",
+    "version": "0.1.1"
+  },
+  "plugins": [
+    {
+      "name": "keyline",
+      "source": "./plugins/keyline",
+      "description": "One skill with eleven commands — init, sync, critique, audit, type, color, layout, depth, motion, patterns, polish — that applies one set of interface laws through a DESIGN.md written in your project's own names."
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihir Modi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# Keyline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interface design laws for coding agents.
+
+Keyline reads your codebase once and writes a `DESIGN.md` that maps your own token names onto its roles and picks a preset for your reader. From then on your agent critiques, audits and fixes type, colour, layout, depth, motion and product patterns through that file: the same laws on every project, your values on yours.
+
+```sh
+npx trykeyline install
+```
+
+The npm package is `trykeyline`, because npm holds `keyline` too close to an older package's name. Everything else, the skill and the commands in your agent, is `keyline`.
+
+Then, in your agent:
+
+```
+/keyline init
+```
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `/keyline init` | Scans the codebase, maps its tokens onto roles, picks a preset, writes `DESIGN.md` with the open issues it found |
+| `/keyline sync` | Reconciles `DESIGN.md` with code that has moved since |
+| `/keyline critique` | A designer's read of one screen: what the reader feels first, what's working, the few changes that matter |
+| `/keyline audit` | Every law checked with evidence, per domain, scored 0–4 |
+| `/keyline type` | Type scale, weights, leading, tracking, emphasis, numerals, font loading |
+| `/keyline color` | Tokens by intent, text tiers by measured contrast, status colours, themes |
+| `/keyline layout` | Measure, spacing that groups, radii, line weights, z-index, breakpoints, empty states |
+| `/keyline depth` | Elevation, shadows, edges, scrims, translucent surfaces and their fallbacks |
+| `/keyline motion` | Durations, curves, springs, open and close, reduced motion, scroll |
+| `/keyline patterns` | Labels, buttons, destructive actions, forms, agent UIs, dashboards |
+| `/keyline polish` | All six domains in order, one reviewable pass each |
+
+You don't have to name a command: ask for "tighter spacing" or "a review of the settings page" and the agent picks one.
+
+`critique`, `audit`, `init` and `sync` change no code. The refining commands change only what their domain owns, in your token names, and write decisions back to `DESIGN.md` so the next session starts from them.
+
+## The detector
+
+Twenty-four of the laws can be checked from source alone, with no model and no API key:
+
+```sh
+npx trykeyline check            # human report; exits 1 on errors
+npx trykeyline check --json     # every finding, for CI or an agent
+npx trykeyline check --strict   # warnings fail the run too
+```
+
+It reads CSS, Tailwind classes, inline styles, `<style>` blocks and CSS-in-JS, in React, Vue, Svelte, Astro and plain HTML, and it reads `DESIGN.md` so the verdicts follow your preset and your motion and z-index ladders. A few of the things it catches: `transition: all`; animation with no reduced-motion branch; an outline removed with nothing in its place; `100vh`; `z-index: 9999`; colours typed inline instead of tokens; translucency with no `@supports` fallback; pinch-zoom disabled; uppercase labels and Title Case buttons where the preset says sentence case. `npx trykeyline check --rules` lists all of them, each with the law it comes from.
+
+`/keyline audit` runs it first and spends its own reading on what a detector can't see — hierarchy, grouping, whether a box should exist at all.
+
+Silence a line with a `keyline-ignore` comment on it or the line above, naming the rule if you like (`/* keyline-ignore type/uppercase */`); a whole file with `keyline-ignore-file`. Leave out paths with `--ignore src/content`.
+
+In CI:
+
+```yaml
+- run: npx trykeyline check
+```
+
+## Presets
+
+The laws hold everywhere. A preset sets the dials — how far the type scale climbs, how much colour is spent, how long motion runs — for what your reader is doing:
+
+| Preset | For a reader who is |
+|---|---|
+| `editorial` | Reading: articles, docs, portfolios, changelogs |
+| `product` | Working: dashboards, tools, anything used daily |
+| `expressive` | Being persuaded: landing pages, launches, campaigns |
+| `glass` | Getting [modimihir.com](https://modimihir.com)'s exact system, with drop-in tokens and components |
+
+Mixed projects are normal: `product`, with the marketing routes on `expressive`. Any dial can be moved, and the move is recorded in `DESIGN.md` with its reason.
+
+## Installing
+
+`npx trykeyline install` asks which agent you use and copies the skill into that agent's folder. Flags answer up front:
+
+```sh
+npx trykeyline install --tool codex,cursor     # several agents
+npx trykeyline install --tool claude-code --user   # every project on this machine
+npx trykeyline update                          # refresh every copy already installed
+```
+
+| Agent | `--tool` | This project | Every project (`--user`) |
+|---|---|---|---|
+| Claude Code | `claude-code` | `.claude/skills` | `~/.claude/skills` |
+| Codex | `codex` | `.agents/skills` | `~/.codex/skills` |
+| Cursor | `cursor` | `.agents/skills` | `~/.cursor/skills` |
+| Gemini CLI | `gemini-cli` | `.agents/skills` | `~/.gemini/skills` |
+| GitHub Copilot | `github-copilot` | `.agents/skills` | `~/.copilot/skills` |
+| OpenCode | `opencode` | `.agents/skills` | `~/.config/opencode/skills` |
+| Windsurf | `windsurf` | `.windsurf/skills` | `~/.codeium/windsurf/skills` |
+| Any agent that reads `.agents/skills` | `agents` | `.agents/skills` | `~/.agents/skills` |
+
+**Claude Code plugin:**
+
+```
+/plugin marketplace add Mihirmodi27/keyline
+/plugin install keyline@keyline
+```
+
+Claude Code names a plugin's skills after the plugin, so installed this way the command is `/keyline:keyline init`, `/keyline:keyline critique` and so on. Installed with `npx trykeyline install`, it's `/keyline`.
+
+**With the [`skills` CLI](https://github.com/vercel-labs/skills):** `npx skills add Mihirmodi27/keyline --agent claude-code`.
+
+Or run the installer straight from GitHub: `npx github:Mihirmodi27/keyline install`.
+
+### Coming from interface-skills
+
+Keyline replaces both interface-skills packages: the adaptable set became the commands, and the Glass package became the `glass` preset. `npx trykeyline install` finds the old skills and offers to remove them, since their descriptions would compete with Keyline's for the same requests. A `DESIGN.md` written by the old setup skill works as it is.
+
+## Requirements
+
+Node 18 or later, for the installer and for the three scripts the skill runs: the detector, a token inventory and a contrast checker. None of them needs a dependency, a model or an API key.
+
+## Licence
+
+MIT © Mihir Modi

package/bin/keyline.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/**
+ * Keyline's command line.
+ *
+ *   npx trykeyline install                      asks which coding agent
+ *   npx trykeyline install --tool codex,cursor  answers up front
+ *   npx trykeyline install --user               for every project on this machine
+ *   npx trykeyline update                       refresh every copy already installed
+ *
+ * Keyline is one skill folder. Each coding agent reads skills from its own
+ * folder: Claude Code and Windsurf have their own; Codex, Cursor, Gemini CLI,
+ * GitHub Copilot, OpenCode and most others share `.agents/skills` in a project.
+ * The folder is always copied, never symlinked, so an agent reads real files,
+ * and agents that share a folder share one copy.
+ *
+ * The skill ships inside this package, so installing copies rather than
+ * downloads: it works offline and installs exactly the version npx resolved.
+ */
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+const SOURCE = fileURLToPath(new URL("../plugins/keyline/skills/keyline/", import.meta.url));
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const NAME = "keyline";
+
+/**
+ * Where each agent reads skills from — in a project, and for the whole machine.
+ * The ids and folders match the `skills` CLI (vercel-labs/skills), so a skill
+ * installed either way lands in the same place.
+ */
+const home = homedir();
+const configHome = process.env.XDG_CONFIG_HOME?.trim() || join(home, ".config");
+const TOOLS = {
+  "claude-code": {
+    title: "Claude Code",
+    project: ".claude/skills",
+    global: join(process.env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"), "skills"),
+  },
+  codex: {
+    title: "Codex",
+    project: ".agents/skills",
+    global: join(process.env.CODEX_HOME?.trim() || join(home, ".codex"), "skills"),
+  },
+  cursor: { title: "Cursor", project: ".agents/skills", global: join(home, ".cursor", "skills") },
+  "gemini-cli": { title: "Gemini CLI", project: ".agents/skills", global: join(home, ".gemini", "skills") },
+  "github-copilot": { title: "GitHub Copilot", project: ".agents/skills", global: join(home, ".copilot", "skills") },
+  opencode: { title: "OpenCode", project: ".agents/skills", global: join(configHome, "opencode", "skills") },
+  windsurf: { title: "Windsurf", project: ".windsurf/skills", global: join(home, ".codeium", "windsurf", "skills") },
+  agents: {
+    title: "Any other agent that reads .agents/skills",
+    project: ".agents/skills",
+    global: join(home, ".agents", "skills"),
+  },
+};
+const ALIASES = { claude: "claude-code", gemini: "gemini-cli", copilot: "github-copilot", other: "agents" };
+const TOOL_IDS = Object.keys(TOOLS);
+
+/**
+ * Keyline replaces the interface-skills packages. Left installed beside it,
+ * their descriptions compete with Keyline's for the same requests, so install
+ * offers to remove them.
+ */
+const SUPERSEDED = [
+  "design-system-setup",
+  "typographic-system",
+  "color-and-theming",
+  "layout-and-hierarchy",
+  "surfaces-and-depth",
+  "interface-motion",
+  "product-patterns",
+  "glass-typography",
+  "glass-color",
+  "glass-layout",
+  "glass-and-depth",
+  "glass-motion",
+];
+
+const USAGE = `Keyline ${version} — interface design laws for coding agents.
+
+  npx trykeyline install [options]   install the skill
+  npx trykeyline update  [options]   refresh every copy already installed
+  npx trykeyline check  [paths…]     the laws that can be checked without a model
+                                     (--json, --strict; see npx trykeyline check --help)
+  npx trykeyline tools               list the agents it installs for
+
+Options:
+  -t, --tool <tool[,tool…]>   which agent — asked for when not given, Claude Code
+                              when there's no terminal to ask on. One of:
+                              ${TOOL_IDS.join(", ")}
+  --user                      for every project on this machine, not just this one
+  --dir <path>                into <path>, whatever the agent
+  -f, --force                 overwrite a copy that's already there
+  -h, --help                  this
+  -v, --version               the version
+
+Then, in your agent: /keyline init`;
+
+function die(message) {
+  console.error(`keyline: ${message}`);
+  process.exit(1);
+}
+
+function toolId(name) {
+  const id = ALIASES[name] ?? name;
+  if (!TOOLS[id]) die(`no agent called '${name}' — use one of: ${TOOL_IDS.join(", ")}`);
+  return id;
+}
+
+/* ── Arguments ──────────────────────────────────────────────────────────── */
+
+const argv = process.argv.slice(2);
+
+// `check` is the detector, which lives in the skill so an agent can run it without this CLI.
+if (argv[0] === "check") {
+  const { run } = await import(new URL("../plugins/keyline/skills/keyline/scripts/check.mjs", import.meta.url));
+  process.exit(run(argv.slice(1)));
+}
+const command = argv[0] && !argv[0].startsWith("-") ? argv.shift() : null;
+let dir = null;
+let user = false;
+let force = false;
+const tools = [];
+
+for (let i = 0; i < argv.length; i++) {
+  const arg = argv[i];
+  const value = () => (arg.includes("=") ? arg.slice(arg.indexOf("=") + 1) : argv[++i]);
+  if (arg === "--user") user = true;
+  else if (arg === "--dir" || arg.startsWith("--dir=")) {
+    const path = value();
+    if (!path) die("--dir needs a path");
+    dir = resolve(path);
+  } else if (["-t", "--tool", "--agent"].includes(arg) || arg.startsWith("--tool=") || arg.startsWith("--agent=")) {
+    const v = value();
+    if (!v) die("--tool needs an agent name");
+    for (const name of v.split(",").map((s) => s.trim()).filter(Boolean)) tools.push(toolId(name));
+  } else if (arg === "-f" || arg === "--force") force = true;
+  else if (arg === "-h" || arg === "--help") {
+    console.log(USAGE);
+    process.exit(0);
+  } else if (arg === "-v" || arg === "--version") {
+    console.log(version);
+    process.exit(0);
+  } else die(`unknown option: ${arg} (try --help)`);
+}
+
+if (!command) {
+  console.log(USAGE);
+  process.exit(0);
+}
+if (command === "tools") {
+  for (const id of TOOL_IDS) console.log(`${id.padEnd(16)} ${TOOLS[id].title}`);
+  process.exit(0);
+}
+if (command !== "install" && command !== "update") die(`no command called '${command}' (try --help)`);
+
+/* ── Helpers ────────────────────────────────────────────────────────────── */
+
+const interactive = process.stdin.isTTY && process.stdout.isTTY;
+
+async function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } catch {
+    // Ctrl+C or Ctrl+D at a question: stop quietly, having written nothing yet for this question.
+    console.log("\nCancelled.");
+    process.exit(130);
+  } finally {
+    rl.close();
+  }
+}
+
+async function askTools() {
+  if (!interactive) {
+    console.log("No terminal to ask on, so installing for Claude Code. Pass --tool to choose (try `keyline tools`).\n");
+    return ["claude-code"];
+  }
+  console.log("Which agent?\n");
+  TOOL_IDS.forEach((id, i) => console.log(`  ${i + 1}) ${TOOLS[id].title}`));
+  console.log();
+  for (;;) {
+    const answer = (await prompt("Choose one or more, like 1 or 1,2 [1]: ")) || "1";
+    const picks = answer.split(/[\s,]+/).filter(Boolean).map(Number);
+    if (picks.length && picks.every((n) => Number.isInteger(n) && n >= 1 && n <= TOOL_IDS.length)) {
+      console.log();
+      return [...new Set(picks.map((n) => TOOL_IDS[n - 1]))];
+    }
+    console.log(`  Type numbers from 1 to ${TOOL_IDS.length}, separated by commas.`);
+  }
+}
+
+const shown = (path) => (path.startsWith(process.cwd()) ? `./${relative(process.cwd(), path)}` : path.replace(home, "~"));
+
+/** The folders to install into, each with the agents that read it. */
+function destinations(ids, global) {
+  const byPath = new Map();
+  for (const id of ids) {
+    const path = global ? TOOLS[id].global : resolve(TOOLS[id].project);
+    byPath.set(path, [...(byPath.get(path) ?? []), TOOLS[id].title]);
+  }
+  // More than two readers only happens on an update sweep of the shared
+  // .agents/skills folder, where naming all six says less than naming the folder.
+  return [...byPath].map(([path, readers]) => ({
+    path,
+    label: readers.length > 2 ? `Every agent that reads ${shown(path)}` : readers.join(", "),
+  }));
+}
+
+const installedAt = (path) => existsSync(join(path, NAME, "SKILL.md"));
+const supersededAt = (path) => SUPERSEDED.filter((s) => existsSync(join(path, s)));
+
+function copyTo(path) {
+  const target = join(path, NAME);
+  mkdirSync(path, { recursive: true });
+  rmSync(target, { recursive: true, force: true });
+  cpSync(SOURCE, target, { recursive: true });
+}
+
+async function retire(path) {
+  const old = supersededAt(path);
+  if (old.length === 0) return;
+  console.log(`  Found interface-skills here, which Keyline replaces: ${old.join(", ")}.`);
+  const links = old.filter((s) => lstatSync(join(path, s)).isSymbolicLink());
+  if (links.length) console.log(`  (${links.join(", ")} ${links.length === 1 ? "is a link" : "are links"}; removing ${links.length === 1 ? "it" : "them"} leaves the target alone.)`);
+  if (!interactive) {
+    console.log("  Left in place — remove them by hand, or rerun in a terminal, so they don't compete with Keyline.");
+    return;
+  }
+  const answer = ((await prompt("  Remove them? [Y/n]: ")) || "y").toLowerCase();
+  if (!answer.startsWith("y")) return;
+  for (const s of old) rmSync(join(path, s), { recursive: true, force: true });
+  console.log(`  ✓ removed ${old.length}`);
+}
+
+if (!existsSync(join(SOURCE, "SKILL.md"))) die("the package is missing its SKILL.md — reinstall it");
+
+/* ── update ─────────────────────────────────────────────────────────────── */
+
+if (command === "update") {
+  // Every place Keyline is already installed — in this project and on this machine.
+  const scopes = dir ? [{ path: dir, label: shown(dir) }] : [...destinations(TOOL_IDS, false), ...destinations(TOOL_IDS, true)];
+  const found = scopes.filter((d) => installedAt(d.path));
+  if (found.length === 0) {
+    console.log("Keyline isn't installed here or for this user — run `npx trykeyline install`.");
+    process.exit(0);
+  }
+  for (const d of found) {
+    copyTo(d.path);
+    console.log(`✓ ${d.label} → ${shown(join(d.path, NAME))}`);
+  }
+  console.log(`\nKeyline ${version}, ${found.length} ${found.length === 1 ? "copy" : "copies"} updated.`);
+  process.exit(0);
+}
+
+/* ── install ────────────────────────────────────────────────────────────── */
+
+const dests = dir ? [{ path: dir, label: shown(dir) }] : destinations(tools.length ? tools : await askTools(), user);
+let installed = 0;
+
+for (const d of dests) {
+  console.log(`${d.label} → ${shown(join(d.path, NAME))}`);
+  if (installedAt(d.path) && !force) {
+    console.log("  · already installed — `npx trykeyline update` refreshes it, --force overwrites it");
+  } else {
+    copyTo(d.path);
+    console.log(`  ✓ keyline ${version}`);
+    installed++;
+  }
+  await retire(d.path);
+  console.log();
+}
+
+if (installed > 0) {
+  console.log("Next, in your agent:");
+  console.log("  /keyline init       scan this project and write DESIGN.md");
+  console.log("  /keyline critique   then a designer's read of any screen");
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "trykeyline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Interface design laws for coding agents: one skill that reads your codebase, writes a DESIGN.md in your own token names, then critiques, audits and fixes type, colour, layout, depth, motion and product patterns through it.",
+  "keywords": [
+    "design",
+    "design-system",
+    "ui",
+    "typography",
+    "accessibility",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "cursor",
+    "skills"
+  ],
+  "homepage": "https://github.com/Mihirmodi27/keyline#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mihirmodi27/keyline.git"
+  },
+  "license": "MIT",
+  "author": "Mihir Modi (https://modimihir.com)",
+  "type": "module",
+  "bin": {
+    "keyline": "bin/keyline.mjs",
+    "trykeyline": "bin/keyline.mjs"
+  },
+  "files": [
+    "bin",
+    "plugins",
+    ".claude-plugin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\""
+  }
+}

package/plugins/keyline/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "keyline",
+  "displayName": "Keyline",
+  "version": "0.1.1",
+  "description": "Interface design laws for coding agents. /keyline init reads your codebase and writes a DESIGN.md in your own token names; critique, audit, type, color, layout, depth, motion, patterns and polish work through it, with dials set by a preset (editorial, product, expressive or glass).",
+  "author": {
+    "name": "Mihir Modi",
+    "url": "https://modimihir.com"
+  },
+  "homepage": "https://github.com/Mihirmodi27/keyline#readme",
+  "repository": "https://github.com/Mihirmodi27/keyline",
+  "license": "MIT",
+  "keywords": ["design-system", "design-tokens", "typography", "motion", "colour", "layout", "accessibility"]
+}

package/plugins/keyline/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "keyline",
+  "version": "0.1.1",
+  "description": "Interface design laws for coding agents. /keyline init reads your codebase and writes a DESIGN.md in your own token names; critique, audit, type, color, layout, depth, motion, patterns and polish work through it, with dials set by a preset (editorial, product, expressive or glass).",
+  "author": {
+    "name": "Mihir Modi",
+    "url": "https://modimihir.com"
+  },
+  "homepage": "https://github.com/Mihirmodi27/keyline#readme",
+  "repository": "https://github.com/Mihirmodi27/keyline",
+  "license": "MIT",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "typography",
+    "motion",
+    "colour",
+    "layout",
+    "accessibility"
+  ]
+}

package/plugins/keyline/skills/keyline/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: keyline
+description: "Design, review and fix interfaces with one set of laws, applied in the project's own tokens and names. Commands: init (write DESIGN.md), sync, critique, audit, type, color, layout, depth, motion, patterns, polish. Use to set up or document a design system, critique or audit a UI, or improve typography, colour, contrast, dark mode, spacing, layout, hierarchy, cards, shadows, glass and translucent surfaces, animation, hover and focus states, UI copy, forms, dashboards, and agent and AI chat interfaces. Also for screens that feel generic, boxy, cluttered or template-made, and for building new UI. Not for backend-only work."
+---
+
+# Keyline
+
+Keyline gives an agent the judgement of a careful interface designer, as laws it can apply and check. **The laws are the same for every project; the values never are.** A setup pass reads the codebase once and writes `DESIGN.md`, which maps the project's own token names onto Keyline's roles and picks a preset for its reader. Every other command works through that file, in the project's names.
+
+Paths in these files are relative to this skill's folder. In shell commands it is written `<keyline>` — substitute the folder this file is in.
+
+## Running it
+
+`/keyline <command> [target]` — the target is a route, file, directory or component; without one, the command takes the whole project, or the screen the conversation is about.
+
+| Command | Does |
+|---|---|
+| `init` | Scans the codebase and writes `DESIGN.md` |
+| `sync` | Reconciles `DESIGN.md` with code that has moved |
+| `critique` | A designer's ranked read of one screen |
+| `audit` | Every law checked with evidence, scored per domain |
+| `type` | Scale, weights, leading, tracking, numerals, fonts |
+| `color` | Tokens, contrast, status colours, themes |
+| `layout` | Measure, spacing, radii, lines, z-index, breakpoints |
+| `depth` | Elevation, shadows, scrims, translucent surfaces |
+| `motion` | Durations, curves, springs, reduced motion |
+| `patterns` | Labels, buttons, forms, dialogs, agent UIs, dashboards |
+| `polish` | All six domains in order, one pass each |
+
+**No command named?** Pick the one the request is about, say which, and go: "set up", "document", "extract" → `init`; "review", "what's wrong", "feedback" → `critique`; "check everything", "lint", "score" → `audit`; "font", "headings", "typography" → `type`; "colour", "contrast", "dark mode" → `color`; "spacing", "padding", "alignment", "cramped" → `layout`; "shadow", "card", "glass", "modal" → `depth`; "animate", "transition", "feels janky" → `motion`; "copy", "labels", "form", "dialog" → `patterns`; "make it better", "clean this up", "finish" → `polish`. Building something new runs the relevant domains' `## Building it for a project` sections, in polish order (patterns has none; its nearest is `## Iterating on feedback`). `colour`, `typography`, `spacing`, `animate` and `copy` work as aliases.
+
+## Before any command
+
+1. **Read `DESIGN.md`** at the project root. `## Profile` gives the preset and any areas on another preset; each domain has its own section; `## Decisions` overrides the preset's defaults and must be respected; `## Open issues` is what's already known.
+2. **No `DESIGN.md`:** for `init`, that's the job. For anything else, run `init` for the domains this command touches — `## Profile` and those domains' sections — do the task, then recommend a full `/keyline init`. Don't refuse.
+3. **Load the command's file**, `commands/<command>.md`. It says which guides to read, and which sections; read them, don't work from memory of them.
+4. **Preset `glass`:** the exact system from modimihir.com. Beside each domain guide, read `glass/<domain>/guide.md` for the exact recipes behind the values in `DESIGN.md`; from its `assets/`, take only the files its `## Assets` list names for what you're changing. There is no `glass/patterns/`: patterns take the dials of the preset nearest the reader.
+
+## What every command holds to
+
+- **The project's names, always.** Reason in roles (`text.secondary`, `duration.small`), write code in whatever the project calls them. Never rename a project's tokens; never add a second token system beside the first. Where a role you need has no row, reuse a value already doing that job; otherwise add one in the project's naming style, marked `proposed`.
+- **Measure, don't estimate.** Mechanical laws are checked by `<keyline>/scripts/check.mjs`; contrast comes from `<keyline>/scripts/contrast.mjs`; inventories from `<keyline>/scripts/scan.mjs`; counts from the code. A finding carries its evidence: a ratio, a count, a `file:line`.
+- **Laws hold under every preset; dials move between them.** A change that would break a law, or move a dial off the preset, is said out loud and asked about first. When the user agrees, it goes under `## Decisions` with its date and reason.
+- **Keep what the design already chose.** An existing interface keeps its brand colour and gradients wherever they do a job, and its corners stay at least as round. Only a law removes something, and the report names that law: a pass that leaves the screen greyer or boxier than it found it has to say why.
+- **Findings are not fixes.** `init`, `sync`, `critique` and `audit` change no code. The refining commands change only what their domain owns, and name the owning domain for anything else they notice.
+- **Write back.** A decision that changes the system — a new role, a moved dial, a law knowingly broken, a change a law forced that a later session might undo (marked *law*) — goes into `DESIGN.md`, so the next session starts from it: roles and values in the domain's section, decisions under `## Decisions` (format: `system/design-md.md`). Open issues are one line each with evidence; fixed ones come off.
+- **Look at the result.** When the project can be rendered, render it before and after a change and look at both themes, a narrow width, and reduced motion where they apply. Code that reads right can still look wrong.

package/plugins/keyline/skills/keyline/commands/audit.md

@@ -0,0 +1,30 @@
+# `/keyline audit`
+
+Every law, checked with evidence, per domain — the full inspection `critique` is the summary of. Findings go into `DESIGN.md` so later sessions start from them.
+
+**Read:** `DESIGN.md`, then from every `domains/<domain>/guide.md` (all six unless the user narrows it):
+
+- **The checklist** — each law's `### N.` heading and its bold first sentence: `awk 'FNR==1{p=0; print "== " FILENAME} /^## /{p = /^## Laws/} p' <keyline>/domains/*/guide.md | grep -oE '^(== |### ).*|^\*\*([^*]|\*[^*])+\*\*'`
+- **`## Auditing existing code`**, and `## Checklist` where a guide still has one: `awk 'FNR==1{p=0; print "== " FILENAME} /^## /{p = /^## (Auditing|Checklist)/} p' <keyline>/domains/*/guide.md`
+
+Read a law's full text where a finding needs it. Under preset `glass`, also each `glass/<domain>/guide.md` checklist (there is no `glass/patterns/`): `awk 'FNR==1{p=0; print "== " FILENAME} /^## /{p = /^## Checklist/} p' <keyline>/glass/*/guide.md`
+
+**Steps:**
+
+1. **Detector:** `node <keyline>/scripts/check.mjs --root <project root> --json --ignore <prose and example dirs>`. Every finding it returns is evidence already — file, line, law — so start each domain from its findings and spend your reading on what it can't see: hierarchy, grouping, whether a box should exist. Treat a finding as a lead, not a verdict; one you judge wrong goes in the report as such, and gets a `keyline-ignore` comment only if the user agrees.
+2. **Inventory:** `node <keyline>/scripts/scan.mjs . --ignore <prose and example dirs>`.
+3. **Contrast:** every text tier, the focus ring (`--min 3`) and status colours, per theme, with `<keyline>/scripts/contrast.mjs`.
+4. **Per domain, in polish order** — type, colour, layout, depth, motion, patterns — run that guide's audit: its searches, then its evidence per law. Render where the guide asks you to look (widths, themes, reduced motion, keyboard).
+5. **Score each domain** from what you found, the detector's findings and yours together:
+
+| Score | Means |
+|---|---|
+| 4 | Every law holds; nothing to report |
+| 3 | Small strays — a handful of one-off values, nothing a reader would notice |
+| 2 | A law broken in a way a reader feels — a hierarchy inversion, a failed contrast tier, a box around everything |
+| 1 | Several laws broken across templates; the domain isn't working as a system |
+| 0 | No system: values typed inline, nothing on a ladder |
+
+**Report:** a table of the six domains with score and finding count, then findings grouped by domain, worst first, one line each with evidence — `file:line`, a ratio, a count — and the law, with its UX-law name where one explains it (`commands/ux-laws.md`). Close with the order to fix in: usually the lowest score first, unless a law in another domain blocks it.
+
+**Write back:** every finding under `## Open issues` in `DESIGN.md`, replacing entries now fixed.

package/plugins/keyline/skills/keyline/commands/color.md

@@ -0,0 +1,7 @@
+# `/keyline color`
+
+**Guide:** `domains/color/guide.md` · **`DESIGN.md` section:** `## Colour` · **Procedure:** `commands/refine.md` · **Alias:** `colour`
+
+Makes colour mean something: tokens named for the job they do rather than their lightness, text tiers chosen by measured contrast and kept strictly descending, a focus colour that's never lost, status colours as foreground and background pairs, colour spent on what needs a person rather than on decoration, and themes that switch without a flash.
+
+Typical finds: one grey doing duty as both a border and a caption; a tier that passes 4.5:1 but is indistinguishable from its neighbour; a second accent hue; success green on steps the reader has simply passed (outside an expressive brand's counted exceptions); a gradient that wasn't re-picked for dark. Every ratio comes from `<keyline>/scripts/contrast.mjs`. Deeper references: `deriving-a-ramp.md`, `status-and-exceptions.md`, `theming-mechanics.md`.

package/plugins/keyline/skills/keyline/commands/critique.md

@@ -0,0 +1,20 @@
+# `/keyline critique`
+
+A designer's read of one screen, flow or component: what a reader notices first, what's working, and the few changes that would matter most. Judgement, ranked — not a checklist. For every law checked with evidence, use `/keyline audit`.
+
+**Read:** `DESIGN.md`. Then the law headings (the `### N.` lines) of all six domain guides — enough to know which laws exist and cite them by number: `grep -n '^### [0-9]' <keyline>/domains/*/guide.md`. Read a law's full text only for the two or three domains where the screen's biggest problems sit, after step 3 has found them: `awk '/^## /{p = /^## Laws/} p' <keyline>/domains/<domain>/guide.md`. A critique ranks a few changes; it doesn't need every law in full, which is what `/keyline audit` is for.
+
+**Steps:**
+
+1. **Look at it.** Render it if you can — the running app, a preview, a screenshot through whatever browser tool you have — at a desktop and a phone width, in each theme. Read the code too, for what rendering hides (states, focus, reduced motion). If nothing can be rendered, say the critique is from code alone. With a headless Chrome and no other tool, `--screenshot --window-size=1440,900` shoots a page; dark mode needs the page's own theme switch (its `data-theme` or class) set in the URL or DOM, because Chrome's `--blink-settings` flag only gives light reliably.
+2. **Name what the screen is for and who reads it**, in one sentence. Everything below is measured against it.
+3. **Read it as its reader would, in order:** what the eye lands on first, second, third — and whether that order matches what matters. Then how it groups, what competes, what's missing, what's noise.
+4. **Tie each problem to a law**, by domain and number (`layout law 3`), so the fix is a rule rather than a taste. Where a named UX law explains *why* the reader feels it, name that too (`layout law 13, Fitts's law`) — it tells the owner the problem is about people, not preference. The names, and where Keyline holds each, are in `commands/ux-laws.md`.
+
+**Report:**
+
+- **The read** — two or three sentences: what the screen gets right, and the one thing that most undercuts it.
+- **Changes, most important first** — at most five. Each: what's wrong, as the reader feels it; the law; the fix in a sentence, in the project's names; and the command that makes it (`/keyline layout`).
+- **Keep** — what's working and shouldn't be touched by the fixes.
+
+Don't pad to five. Don't list what's fine as a problem to fix.

package/plugins/keyline/skills/keyline/commands/depth.md

@@ -0,0 +1,7 @@
+# `/keyline depth`
+
+**Guide:** `domains/depth/guide.md` · **`DESIGN.md` section:** `## Surfaces` · **Procedure:** `commands/refine.md`
+
+Makes every surface say where it sits — flat, raised, floating or modal — with each level one bundle of surface, edge, shadow and layer. Shadows from one light, dark themes that lift by lightening, scrims, gradient strokes, and translucency only where it earns its place, legible from its tint alone, with every fallback.
+
+Typical finds: a card that should be a section; four shadow recipes for two levels; dark-mode cards that vanish because the shadow was the only cue; blur stacked on blur; text over glass that fails contrast against its worst backdrop; no `@supports` or reduced-transparency fallback. Deeper references: `elevation-recipes.md`, `translucent-materials.md`, `fallbacks-and-performance.md`.