@onexeor/lumo 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viktor Savchik
+
+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

@@ -0,0 +1,47 @@
+# lumo — installer
+
+One-command installer for [Lumo](https://github.com/OneXeor/lumo): mobile
+UI/UX design intelligence for AI coding assistants.
+
+```bash
+npx @onexeor/lumo init                    # interactive — picks your AI client
+npx @onexeor/lumo init --ai claude        # explicit target
+npx @onexeor/lumo init --all              # install everywhere supported
+npx @onexeor/lumo init --ai claude --dev  # install from a local git clone (contributors)
+npx @onexeor/lumo init --no-mcp           # skill only, skip MCP server registration
+
+# After install the binary is `lumo` (the scoped package name is only
+# needed to disambiguate during install):
+lumo doctor                               # verify every Lumo piece is in place
+lumo uninstall --ai claude                # remove the skill (Python tools stay)
+```
+
+Supported AI clients in v0.1:
+
+- **Claude Code** — copies the skill into `~/.claude/skills/lumo/` and
+  registers the MCP server in `claude_desktop_config.json`
+- **Cursor** — installs to `~/.cursor/rules/lumo/` and registers MCP in
+  `~/.cursor/mcp.json`
+- **OpenAI Codex CLI** — installs to `~/.codex/skills/lumo/` and
+  registers MCP in `~/.codex/mcp.json`
+- **generic** — prints install paths so you can wire it into anything
+  not listed above
+
+Under the hood the installer:
+
+1. Locates a Python 3.10+ interpreter and creates a Lumo-owned venv at
+   `~/.lumo/venv` so your system Python stays clean.
+2. `pip install`s [`lumo-tools`](https://pypi.org/project/lumo-tools/) into
+   that venv. The CLIs (`lumo-wcag`, `lumo-theory`, `lumo-parity`,
+   `lumo-mcp`) become available at absolute paths the MCP configs point to.
+3. Copies the `SKILL.md` bundle into the chosen client's skill directory.
+4. Merges a `{ "mcpServers": { "lumo": { "command": "..." } } }` block
+   into the client's MCP config — non-destructive, backs up the file once
+   before the first write.
+
+The installer never modifies anything outside `~/.lumo`, the chosen
+client's skill directory, and the chosen client's MCP config file.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@onexeor/lumo",
+  "version": "0.0.1",
+  "description": "Install Lumo — mobile UI/UX design intelligence for AI coding assistants (Claude Code, Cursor, Codex, MCP clients).",
+  "type": "module",
+  "bin": {
+    "lumo": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "prepack": "node scripts/bundle-skill.js"
+  },
+  "keywords": [
+    "mobile",
+    "design",
+    "ui",
+    "ux",
+    "wcag",
+    "claude",
+    "cursor",
+    "codex",
+    "mcp",
+    "jetpack-compose",
+    "swiftui",
+    "ai-skill"
+  ],
+  "author": "OneXeor",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OneXeor/lumo.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: lumo
+description: "Mobile UI/UX design intelligence grounded in cognitive science (Fitts, Hick, Gestalt, Nielsen) and platform guidelines (Apple HIG, Material Design). Specialised for Jetpack Compose, Android XML, SwiftUI, and UIKit. Use when: \"WCAG\", \"contrast\", \"accessibility\", \"colour pair\", \"design audit\", \"mobile UI review\", \"Compose vs SwiftUI\", \"Fitts's law\", \"Hick's law\", \"touch target\", \"safe area\"."
+---
+
+# Lumo
+
+Mobile design intelligence for Claude Code. Lumo combines a curated rule set
+with a small toolkit of deterministic Python tools — so checks that need real
+math (WCAG luminance, OKLCH correction, AST diff, cross-platform parity)
+return facts, not LLM guesses.
+
+## When to Use
+
+Use Lumo when the user request touches any of:
+
+- Accessibility / WCAG contrast questions on a colour pair or palette
+- Reviewing or auditing mobile UI code (Jetpack Compose, Android XML,
+  SwiftUI, UIKit)
+- Comparing the same screen across iOS and Android for visual / behavioural
+  parity (padding, animation timing, touch target, typography scale)
+- Applying cognitive-science rules to a layout: Fitts (target size × distance),
+  Hick (choice count → decision time), Gestalt grouping, Nielsen heuristics
+- Choosing or validating colour tokens for a mobile design system
+- Detecting platform-specific anti-patterns (e.g. emoji as system icons,
+  hardcoded hex in components, missing safe-area handling)
+
+## When NOT to Use
+
+Skip Lumo entirely for:
+
+- Pure backend / API / database tasks
+- Non-mobile web design (use a web-focused skill instead)
+- Build / CI / dependency / version-bump tasks
+- Performance work that doesn't touch UI rendering
+- Tasks where the user has explicitly opted out of design feedback
+
+Do not invoke Lumo "just in case" the request might be design-adjacent.
+If the request doesn't match a trigger above and the user hasn't named a
+mobile UI concern, stay out.
+
+## Tools
+
+Lumo ships with Python tools. Each tool has a single CLI entry-point with
+deterministic output. Invoke via Bash. Tools live in `tools/lumo/<area>/cli.py`
+and are exposed as console scripts after `pip install -e tools/`.
+
+### `lumo-wcag` — WCAG contrast validator + OKLCH auto-correct
+
+When to invoke:
+
+- The user provides a foreground/background colour pair and asks whether it
+  is accessible.
+- The user pastes a palette (multiple pairs) and asks to validate it.
+- A design audit needs to check colour tokens against WCAG.
+
+Commands:
+
+```bash
+# Check a single pair against WCAG (default: AA / normal text)
+lumo-wcag check --fg "<hex>" --bg "<hex>" [--level AA|AAA] [--size normal|large]
+
+# Auto-correct a failing pair by adjusting the foreground in OKLCH
+# (preserves chroma + hue, so brand identity stays intact)
+lumo-wcag fix   --fg "<hex>" --bg "<hex>" [--level AA|AAA] [--size normal|large]
+
+# Add --json to either command for machine-readable output
+```
+
+Worked example — checking a Tailwind blue-500 button on white:
+
+```bash
+$ lumo-wcag check --fg "#3B82F6" --bg "#FFFFFF" --level AA --size normal
+FAIL  #3B82F6 on #FFFFFF  ratio=3.678:1  required=4.5:1  (AA, normal text)
+```
+
+Worked example — auto-correcting a sky-300 label on white:
+
+```bash
+$ lumo-wcag fix --fg "#7DD3FC" --bg "#FFFFFF" --level AA --size normal
+FIXED  #7DD3FC → #1B7BA1  on #FFFFFF
+       ratio 1.667:1 → 4.779:1  (required 4.5:1)
+       strategy=darken_fg  iterations=14
+```
+
+Exit codes: `0` pass / unchanged, `1` check failed, `2` correction unreachable.
+
+### `lumo-theory` — cognitive-science layout checks
+
+When to invoke:
+
+- The user provides a screen layout (as coordinates, as code, or as a
+  screenshot you've described) and asks for a design review.
+- An audit needs to check Fitts (target difficulty), Hick (choice overload),
+  Gestalt proximity, or thumb-reachability of primary actions.
+
+What this tool **does not** do:
+
+- It does not produce absolute Fitts MT or Hick RT in milliseconds.
+  Those depend on device-specific constants (a, b) with ±40 % variance
+  between studies. We return relative comparisons and discrete flags.
+- It does not check Nielsen heuristics — those aren't reliably numeric.
+  See "Inline Rules → Nielsen heuristics" below for manual-review guidance.
+- It does not invoke any LLM. If the layout JSON was estimated by a model,
+  declare that with `"source": "description-estimated"` so findings carry
+  the right confidence label.
+
+Command:
+
+```bash
+lumo-theory check --layout path/to/layout.json [--json]
+```
+
+Layout JSON schema:
+
+```json
+{
+  "screen":  { "width": 411, "height": 891, "unit": "dp" },
+  "source":  "measured | code-estimated | description-estimated",
+  "elements": [
+    {
+      "id": "btn_continue",
+      "role": "primary_action",
+      "x": 24, "y": 800, "w": 363, "h": 56,
+      "group": "form_actions",
+      "weight": "primary"
+    }
+  ]
+}
+```
+
+- `role` ∈ `primary_action | secondary_action | nav_item | tab |
+  list_item | input | icon_button | text | image | decorative`
+- `weight` ∈ `primary | secondary | equal` (default `equal`)
+- `group` is a free-form string used by Hick (equal-weight overload) and
+  Gestalt proximity.
+- `source` reports honesty: `measured` means the coordinates came from a
+  real device (Espresso, XCUITest, Compose `onGloballyPositioned`,
+  SwiftUI `GeometryReader`); `code-estimated` from static code parsing;
+  `description-estimated` from a description or screenshot. The tool
+  propagates this value to every finding so the user can weigh confidence.
+
+When you (the model) construct a layout from a screenshot or from Compose
+/ SwiftUI source code, set `source` to the matching honest label. Do not
+default to `measured` — that would falsely inflate confidence.
+
+Worked example — a deliberately bad screen:
+
+```bash
+$ lumo-theory check --layout examples/bad.json
+FOUND  3 findings (2 high, 1 medium)
+       source: measured
+
+  1. [HIGH    ] fitts_undersized_target
+     elements: close
+     Element 'close' is 32dp on its shorter side, below the minimum tap
+     target (48dp).
+     → Increase the touchable area to at least 48dp, either by growing
+     the element or by extending the hit area (Compose:
+     Modifier.minimumInteractiveComponentSize; SwiftUI: .contentShape;
+     UIKit: hitTest override).
+     metric: smaller_side=32.00, minimum=48.00
+  ...
+```
+
+Exit codes: `0` no findings, `1` findings reported.
+
+### `lumo-parity` — cross-platform parity diff
+
+When to invoke:
+
+- The user has the same screen built on Android (Compose / XML) and iOS
+  (SwiftUI / UIKit) and wants to know where the two diverge.
+- The user has a design system (tokens) and wants to verify both platforms
+  match it.
+
+What this tool does:
+
+- Compares two layout JSONs (same schema as `lumo-theory`), one per platform.
+- Flags numeric mismatches in size and presence of named elements.
+- Whitelists known legitimate platform divergences (Material 48dp vs Apple
+  HIG 44pt touch targets, Material bottom nav 80dp vs iOS Tab Bar 49pt) and
+  reports them as `info`, not as mismatches.
+- Optionally validates both layouts against a shared `lumo.config.json` so
+  divergence from the design system is reported as a separate, higher-
+  severity finding.
+
+What this tool **does not** do:
+
+- It does not flag position (x, y) mismatches. Different screen widths and
+  safe-area insets legitimately shift coordinates; flagging those would be
+  noise. Size, presence, and design-system tokens are what matter for parity.
+- It does not parse Compose or SwiftUI source code in v1. The model is
+  expected to translate code into layout JSON as preprocessing, then call
+  the tool. Set `source` to `code-estimated` in that case.
+
+Common bug pattern this tool catches:
+
+A junior dev writes `Modifier.padding(16.dp)` on Android but `.padding(48)`
+on SwiftUI, believing iOS uses "3× because Retina". Both `dp` and `pt` are
+density-independent and **equal in physical size on screen**. 16 ≠ 48.
+`lumo-parity` will flag this immediately.
+
+Command:
+
+```bash
+lumo-parity diff \
+  --android path/to/android.json \
+  --ios     path/to/ios.json \
+  [--config path/to/lumo.config.json] \
+  [--json]
+```
+
+Optional `lumo.config.json` schema:
+
+```json
+{
+  "spacing": { "sm": 8, "md": 16, "lg": 24 },
+  "sizing":  { "primary_button_height": 56 },
+  "colors":  { "primary": "brand.primary", "surface": "brand.surface" }
+}
+```
+
+Worked example — Android card with `padding(16.dp)` paired with SwiftUI
+`.padding(48)`:
+
+```bash
+$ lumo-parity diff --android examples/parity_android.json --ios examples/parity_ios.json
+FOUND  6 parity findings (1 high, 3 medium, 2 info)
+  ...
+  2. [MEDIUM] height_mismatch
+     element: card_offer
+     android: 16.0    ios: 48.0
+     'card_offer' height differs between platforms: Android 16.0dp vs iOS 48.0pt.
+     dp and pt are both density-independent and should match.
+  ...
+  5. [INFO  ] platform_specific_default
+     element: nav_back
+     android: 48.0    ios: 44.0
+     'nav_back' width differs by design: 48.0dp / 44.0pt.
+     Minimum touch target: Material 48dp vs Apple HIG 44pt.
+```
+
+Exit codes: `0` parity, `1` mismatches present.
+
+## Decision Tree
+
+| User request shape | Action |
+|---|---|
+| "Is `#ABC123` on `#FFFFFF` accessible?" | `lumo-wcag check` with that pair. |
+| "Fix this colour pair." | `lumo-wcag fix`. Report both the corrected hex and the strategy. |
+| "Audit this palette." | Run `lumo-wcag check` for every pair in the palette. Summarise as a table. |
+| "Review this Compose / SwiftUI screen." | Build a layout JSON (set `source` honestly), then run `lumo-theory check`. Combine with inline rules below for things the tool doesn't cover (typography, animation, anti-patterns). |
+| "Is this primary action reachable?" | `lumo-theory check` — the `reach_*` checks cover this. |
+| "Are there too many choices on this screen?" | `lumo-theory check` — the `hick_overload` check covers this. |
+| "Compare this iOS screen to its Android version." | Build layout JSONs for both platforms (set `source` honestly), then run `lumo-parity diff`. Pass `--config lumo.config.json` when the user has a shared design system. |
+| "Does my SwiftUI match the design tokens?" | `lumo-parity diff` with `--config`. Even a single-platform check benefits from design-system validation. |
+
+## Output Format Contract
+
+When a tool returns results, format the final answer for the user as:
+
+1. **One-line verdict** — `PASS`, `FAIL: <count> issues`, or `FIXED: <change>`.
+2. **Issues table** when there are multiple findings, with these columns and
+   nothing else:
+
+   | # | Where | Issue | Severity | Fix |
+   |---|---|---|---|---|
+
+3. **Tool output** as a fenced block, verbatim. Do not paraphrase ratios or
+   hex values — they are facts and must round-trip exactly.
+4. **Suggested next step** in one sentence, if and only if there is one.
+
+Do not add closing summaries, emojis, or restatements of the user's request.
+
+## Inline Rules (apply when no tool covers the case)
+
+These are stable rules that the model is expected to apply directly. They
+duplicate what `lumo-wcag` and the Phase 2 tools will eventually automate —
+keep them here until the tool exists.
+
+### Touch targets
+
+- iOS minimum tap target: **44 × 44 pt**. (Apple HIG, *Designing for iOS*.)
+- Android minimum tap target: **48 × 48 dp**. (Material Design *Accessibility*.)
+- Minimum gap between adjacent tap targets: **8 dp / 8 pt**.
+- Below-minimum icons must extend their hit area (Compose `Modifier.minimumInteractiveComponentSize()`, SwiftUI `.contentShape(Rectangle())` with padding, UIKit `hitTest` override).
+
+### Typography baseline
+
+- Mobile body text: **≥ 16 sp / 16 pt**. Smaller triggers iOS auto-zoom and is below WCAG-recommended legibility.
+- Line height for body: **1.4 – 1.6**.
+- Always honour the system text-scale (Compose: `TextUnit.sp` not `dp`; SwiftUI: dynamic type styles, not fixed point sizes).
+
+### Animation timing
+
+- Micro-interactions: **150 – 300 ms**.
+- Complex transitions: **≤ 400 ms**.
+- Exits roughly 60–70 % of enter duration.
+- Animate `transform` / `opacity` only — never `width`, `height`, `top`, `left`.
+
+### Safe areas
+
+- Compose: `Modifier.safeDrawingPadding()` / `WindowInsets.safeDrawing`.
+- SwiftUI: `.safeAreaInset(edge:)` / `.ignoresSafeArea()` deliberately.
+- UIKit: `safeAreaLayoutGuide`, not view bounds.
+- XML: `android:fitsSystemWindows="true"` + insets handling, not hardcoded padding.
+
+### Common anti-patterns
+
+| Avoid | Prefer | Why |
+|---|---|---|
+| Emoji as system icons (`🏠`, `⚙️`) | SVG / vector icon sets (Lucide, Material Symbols, SF Symbols) | Emoji rendering is font-dependent, inconsistent across platforms, untokenisable. |
+| Hardcoded hex inside components | Semantic tokens (`MaterialTheme.colorScheme.primary`, `Color("AccentColor")`) | Tokens survive theme switches and dark-mode auditing. |
+| Placeholder-only labels | Visible `Text` / `Label` above the field | Placeholder disappears on focus and breaks accessibility. |
+| Same components dressed differently per screen | Single styled component reused | Drift kills perceived polish. |
+| `if Platform.isIOS` style branching scattered across UI code | Platform-specific files / extensions at the boundary | Prevents accidental "iOS-only" features creeping into Android. |
+| Animating `width` / `height` to expand a card | Animate `scale` / `transform`, layout with `AnimatedContent` (Compose) or `matchedGeometryEffect` (SwiftUI) | The former triggers layout reflow each frame — janky on mid-range Android. |
+| Hardcoded `padding(16.dp)` everywhere | A `Spacing` token scale (4 / 8 / 12 / 16 / 24 / 32) | Scale rhythm is a baseline polish signal. |
+
+## Self-correction Loops
+
+Apply these in order before answering:
+
+1. **No tool needed?** If the request is conversational ("what's WCAG?"),
+   answer directly. Don't invoke `lumo-wcag` for theory questions.
+2. **Tool error?** If `lumo-wcag` returns a non-zero exit beyond the
+   documented `1` (failed check) or `2` (correction unreachable), surface
+   the stderr verbatim and stop. Do not retry blindly.
+3. **Zero findings?** Say "no WCAG issues at AA / normal for the pairs you
+   provided" — do not invent a finding to look useful.
+4. **Many findings (> 10)?** Show the top issues by severity (CRITICAL →
+   HIGH → MEDIUM → LOW), then a one-line "+N more" pointer. Do not dump.
+5. **Ambiguity?** If the user provided a single colour without saying which
+   is foreground and which is background, ask once. Do not guess.
+
+## What Lumo Does NOT Do
+
+- Lumo does not generate screens, mockups, or boilerplate.
+- Lumo does not replace a designer's judgement on hierarchy, brand, or copy.
+- Lumo does not call any network service. All tools run locally.
+- Lumo does not store data anywhere outside the user's working directory.
+
+If the user asks Lumo to do something on this list, say so and stop.

package/src/commands/doctor.js

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+
+import kleur from "kleur";
+
+import { CLIENTS } from "../lib/clients.js";
+import { LUMO_HOME, listInstalledBinaries, venvBinary } from "../lib/python.js";
+
+function row(ok, label, detail = "") {
+  const icon = ok ? kleur.green("✓") : kleur.red("✗");
+  const text = ok ? kleur.white(label) : kleur.yellow(label);
+  console.log(`  ${icon} ${text}${detail ? kleur.dim("  " + detail) : ""}`);
+}
+
+export async function doctorCommand() {
+  console.log(kleur.bold().cyan("\n• lumo doctor\n"));
+
+  console.log(kleur.bold("Python tools"));
+  row(fs.existsSync(LUMO_HOME), `Lumo home`, LUMO_HOME);
+  row(fs.existsSync(venvBinary("python")), `venv Python`, venvBinary("python"));
+  for (const bin of listInstalledBinaries()) {
+    row(bin.exists, bin.name, bin.path);
+  }
+
+  console.log("");
+  console.log(kleur.bold("Client integrations"));
+  for (const client of CLIENTS) {
+    if (!client.skillDir) continue;
+    const skillPresent = fs.existsSync(client.skillDir);
+    row(skillPresent, `${client.label} skill`, client.skillDir);
+
+    if (client.mcpConfigPath) {
+      if (!fs.existsSync(client.mcpConfigPath)) {
+        row(false, `${client.label} MCP config`, `not found at ${client.mcpConfigPath}`);
+        continue;
+      }
+      try {
+        const raw = fs.readFileSync(client.mcpConfigPath, "utf8");
+        const data = JSON.parse(raw);
+        const hasLumo = Boolean(data[client.mcpConfigKey]?.lumo);
+        row(hasLumo, `${client.label} MCP registered`, client.mcpConfigPath);
+      } catch (err) {
+        row(false, `${client.label} MCP config unparseable`, err.message);
+      }
+    }
+  }
+
+  console.log("");
+  console.log(kleur.dim("Run `lumo init` to install or repair any missing pieces."));
+  console.log("");
+}

package/src/commands/init.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import kleur from "kleur";
+import prompts from "prompts";
+
+import { CLIENTS, getClient } from "../lib/clients.js";
+import { installLumoTools, listInstalledBinaries } from "../lib/python.js";
+import { findSkillSource, installSkill } from "../lib/skill.js";
+import { registerMcp } from "../lib/mcp.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Resolve --dev source: the repo root above installer/. */
+function devSource() {
+  return path.resolve(__dirname, "..", "..", "..", "tools");
+}
+
+async function pickClient(supplied, allFlag) {
+  if (allFlag) return CLIENTS.filter((c) => c.id !== "generic");
+  if (supplied) return [getClient(supplied)];
+
+  const { ai } = await prompts({
+    type: "select",
+    name: "ai",
+    message: "Which AI client are you installing Lumo for?",
+    choices: CLIENTS.map((c) => ({ title: c.label, value: c.id })),
+    initial: 0,
+  });
+  if (!ai) {
+    throw new Error("No client selected.");
+  }
+  return [getClient(ai)];
+}
+
+export async function initCommand(opts) {
+  console.log(kleur.bold().cyan("\n• Lumo installer\n"));
+
+  const targets = await pickClient(opts.ai, opts.all);
+
+  console.log(kleur.dim("→ installing Python tools (lumo-tools) into ~/.lumo/venv ..."));
+  try {
+    if (opts.dev) {
+      const dev = devSource();
+      console.log(kleur.dim(`  using --dev source ${dev}`));
+      await installLumoTools({ source: dev });
+    } else {
+      await installLumoTools();
+    }
+  } catch (err) {
+    throw new Error(`pip install failed: ${err.stderr || err.message || err}`);
+  }
+
+  const bins = listInstalledBinaries();
+  const missing = bins.filter((b) => !b.exists);
+  if (missing.length > 0) {
+    throw new Error(
+      "Some Lumo CLIs did not install:\n  " +
+        missing.map((b) => `${b.name} (expected at ${b.path})`).join("\n  ")
+    );
+  }
+  console.log(kleur.green(`✓ Python tools installed`));
+  bins.forEach((b) => console.log(kleur.dim(`  ${b.name}  ${b.path}`)));
+
+  const skillSource = findSkillSource();
+
+  for (const client of targets) {
+    console.log(kleur.bold(`\n→ ${client.label}`));
+    if (!client.skillDir) {
+      console.log(kleur.dim("  generic mode — nothing to copy automatically."));
+      console.log(kleur.dim("  Skill bundle is at: ") + skillSource);
+      console.log(kleur.dim("  MCP server command: ") + listInstalledBinaries()[3].path);
+      continue;
+    }
+
+    installSkill(client.skillDir);
+    console.log(kleur.green(`  ✓ skill copied to ${client.skillDir}`));
+
+    if (opts.mcp !== false && client.mcpConfigPath && client.mcpConfigKey) {
+      try {
+        const { configPath, command } = registerMcp(client.mcpConfigPath, client.mcpConfigKey);
+        console.log(kleur.green(`  ✓ MCP registered in ${configPath}`));
+        console.log(kleur.dim(`    command: ${command}`));
+      } catch (err) {
+        console.log(
+          kleur.yellow(`  ! MCP registration skipped: ${err.message}`)
+        );
+      }
+    } else if (opts.mcp === false) {
+      console.log(kleur.dim("  MCP registration skipped (--no-mcp)."));
+    }
+  }
+
+  console.log(kleur.bold().green("\n✓ Lumo installation complete.\n"));
+  console.log(kleur.dim("Next: open your AI client and ask it to use the Lumo skill."));
+  console.log(kleur.dim("Verify any time with: lumo doctor\n"));
+}

package/src/commands/uninstall.js

@@ -0,0 +1,51 @@
+import kleur from "kleur";
+import prompts from "prompts";
+
+import { CLIENTS, getClient } from "../lib/clients.js";
+import { unregisterMcp } from "../lib/mcp.js";
+import { removeSkill } from "../lib/skill.js";
+
+async function pickClient(supplied, allFlag) {
+  if (allFlag) return CLIENTS.filter((c) => c.id !== "generic");
+  if (supplied) return [getClient(supplied)];
+
+  const { ai } = await prompts({
+    type: "select",
+    name: "ai",
+    message: "Remove Lumo from which client?",
+    choices: CLIENTS.filter((c) => c.skillDir).map((c) => ({ title: c.label, value: c.id })),
+    initial: 0,
+  });
+  if (!ai) throw new Error("No client selected.");
+  return [getClient(ai)];
+}
+
+export async function uninstallCommand(opts) {
+  console.log(kleur.bold().cyan("\n• Lumo uninstaller\n"));
+
+  const targets = await pickClient(opts.ai, opts.all);
+
+  for (const client of targets) {
+    if (!client.skillDir) continue;
+    console.log(kleur.bold(`\n→ ${client.label}`));
+
+    const removed = removeSkill(client.skillDir);
+    if (removed) {
+      console.log(kleur.green(`  ✓ skill removed from ${client.skillDir}`));
+    } else {
+      console.log(kleur.dim(`  skill not present (${client.skillDir})`));
+    }
+
+    if (client.mcpConfigPath && client.mcpConfigKey) {
+      const unreg = unregisterMcp(client.mcpConfigPath, client.mcpConfigKey);
+      if (unreg) {
+        console.log(kleur.green(`  ✓ MCP entry removed from ${client.mcpConfigPath}`));
+      } else {
+        console.log(kleur.dim(`  no MCP entry to remove`));
+      }
+    }
+  }
+
+  console.log(kleur.dim("\nPython tools (~/.lumo/venv) left intact."));
+  console.log(kleur.dim("Remove them manually with: rm -rf ~/.lumo\n"));
+}

package/src/index.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * lumo — mobile UI/UX design intelligence installer.
+ *
+ * Subcommands:
+ *   init [--ai <client>] [--all]   Install the Lumo skill (+ optional MCP) into an AI client.
+ *   doctor                         Verify Python tools + skill installation.
+ *   uninstall [--ai <client>]      Remove the Lumo skill (Python tools left intact).
+ *
+ * Supported AI clients in v0.1: claude, cursor, codex, generic.
+ * Other clients can still consume Lumo via `npx skills add OneXeor/lumo`
+ * or by pointing their MCP config at `lumo-mcp`.
+ */
+
+import { Command } from "commander";
+import kleur from "kleur";
+
+import { initCommand } from "./commands/init.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { uninstallCommand } from "./commands/uninstall.js";
+
+const program = new Command();
+
+program
+  .name("lumo")
+  .description(
+    "Mobile UI/UX design intelligence — WCAG / parity / cognitive-science checks " +
+      "for Jetpack Compose, Android XML, SwiftUI, UIKit."
+  )
+  .version("0.0.1");
+
+program
+  .command("init")
+  .description("Install the Lumo skill into an AI coding assistant.")
+  .option(
+    "-a, --ai <client>",
+    "Target client: claude | cursor | codex | generic (asks interactively if omitted)"
+  )
+  .option("--all", "Install into every supported client at once.")
+  .option("--no-mcp", "Skip registering the MCP server (skill-only install).")
+  .option("--dev", "Install from the current git clone instead of pip (for contributors).")
+  .action(initCommand);
+
+program
+  .command("doctor")
+  .description("Verify Python tools, MCP server, and skill installation paths.")
+  .action(doctorCommand);
+
+program
+  .command("uninstall")
+  .description("Remove the Lumo skill from an AI client (Python tools left intact).")
+  .option("-a, --ai <client>", "Which client to remove from (asks interactively if omitted)")
+  .option("--all", "Remove from every supported client at once.")
+  .action(uninstallCommand);
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(kleur.red(`\n✗ ${err.message ?? err}`));
+  process.exit(1);
+});

package/src/lib/clients.js

@@ -0,0 +1,81 @@
+/**
+ * Supported AI client registry.
+ *
+ * Each entry tells the installer:
+ *   - where to copy the SKILL.md (skillDir, optional)
+ *   - where to register the MCP server (mcpConfigPath + mcpConfigKey, optional)
+ *   - how to detect whether the client is installed (detectPaths)
+ *
+ * Adding a new client = adding one entry here. The init / uninstall / doctor
+ * commands all read from this registry.
+ */
+
+import os from "node:os";
+import path from "node:path";
+
+const HOME = os.homedir();
+
+/** @typedef {{
+ *   id: string,
+ *   label: string,
+ *   skillDir?: string,
+ *   mcpConfigPath?: string,
+ *   mcpConfigKey?: string,
+ *   detectPaths: string[],
+ * }} ClientSpec
+ */
+
+/** @type {ClientSpec[]} */
+export const CLIENTS = [
+  {
+    id: "claude",
+    label: "Claude Code",
+    // Claude Code reads skills from ~/.claude/skills/<name>/SKILL.md
+    skillDir: path.join(HOME, ".claude", "skills", "lumo"),
+    // Claude Desktop / Claude Code share a config file for MCP servers.
+    // On macOS the canonical path is ~/Library/Application Support/Claude/claude_desktop_config.json
+    // We fall back to ~/.claude/claude_desktop_config.json if the Library path doesn't exist.
+    mcpConfigPath:
+      process.platform === "darwin"
+        ? path.join(HOME, "Library", "Application Support", "Claude", "claude_desktop_config.json")
+        : path.join(HOME, ".claude", "claude_desktop_config.json"),
+    mcpConfigKey: "mcpServers",
+    detectPaths: [path.join(HOME, ".claude"), path.join(HOME, "Library", "Application Support", "Claude")],
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    // Cursor reads project rules from .cursorrules and global rules from
+    // ~/.cursor/rules/. For now Lumo writes a small pointer rule that
+    // delegates the heavy lifting to the MCP server.
+    skillDir: path.join(HOME, ".cursor", "rules", "lumo"),
+    mcpConfigPath: path.join(HOME, ".cursor", "mcp.json"),
+    mcpConfigKey: "mcpServers",
+    detectPaths: [path.join(HOME, ".cursor")],
+  },
+  {
+    id: "codex",
+    label: "OpenAI Codex CLI",
+    // Codex CLI looks for skills in ~/.codex/skills/ when present.
+    skillDir: path.join(HOME, ".codex", "skills", "lumo"),
+    mcpConfigPath: path.join(HOME, ".codex", "mcp.json"),
+    mcpConfigKey: "mcpServers",
+    detectPaths: [path.join(HOME, ".codex")],
+  },
+  {
+    id: "generic",
+    label: "Generic / manual (just print install paths)",
+    // No skillDir or mcpConfigPath — generic mode only prints guidance.
+    detectPaths: [],
+  },
+];
+
+export function getClient(id) {
+  const client = CLIENTS.find((c) => c.id === id);
+  if (!client) {
+    throw new Error(
+      `Unknown client: ${id}. Supported: ${CLIENTS.map((c) => c.id).join(", ")}`
+    );
+  }
+  return client;
+}

package/src/lib/mcp.js

@@ -0,0 +1,72 @@
+/**
+ * MCP server registration in a client's JSON config.
+ *
+ * All supported MCP clients (Claude, Cursor, Codex, etc) use roughly the
+ * same shape:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "lumo": { "command": "/abs/path/to/lumo-mcp", "args": [] }
+ *     }
+ *   }
+ *
+ * We:
+ *   - create the file if missing
+ *   - merge into an existing object without clobbering other servers
+ *   - keep a backup copy as <file>.lumo.bak the first time we write
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { venvBinary } from "./python.js";
+
+const SERVER_KEY = "lumo";
+
+function loadJsonOrEmpty(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (err) {
+    throw new Error(
+      `${filePath} exists but is not valid JSON. Fix it manually before re-running lumo init.\n  parse error: ${err.message}`
+    );
+  }
+}
+
+function backupOnce(filePath) {
+  const backup = `${filePath}.lumo.bak`;
+  if (fs.existsSync(filePath) && !fs.existsSync(backup)) {
+    fs.copyFileSync(filePath, backup);
+  }
+}
+
+/** Register lumo-mcp under the client's mcpServers key. */
+export function registerMcp(configPath, mcpKey) {
+  const lumoMcp = venvBinary("lumo-mcp");
+
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  backupOnce(configPath);
+
+  const config = loadJsonOrEmpty(configPath);
+  config[mcpKey] = config[mcpKey] || {};
+  config[mcpKey][SERVER_KEY] = {
+    command: lumoMcp,
+    args: [],
+  };
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return { configPath, command: lumoMcp };
+}
+
+/** Remove the `lumo` entry from the client's mcpServers, if present. */
+export function unregisterMcp(configPath, mcpKey) {
+  if (!fs.existsSync(configPath)) return false;
+  const config = loadJsonOrEmpty(configPath);
+  if (!config[mcpKey] || !config[mcpKey][SERVER_KEY]) return false;
+  delete config[mcpKey][SERVER_KEY];
+  // Drop the mcp key entirely if it's now empty.
+  if (Object.keys(config[mcpKey]).length === 0) delete config[mcpKey];
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return true;
+}

package/src/lib/python.js

@@ -0,0 +1,94 @@
+/**
+ * Python detection and lumo-tools install helpers.
+ *
+ * Strategy:
+ *   - Locate a Python ≥3.10 interpreter (python3, python, py -3 on Windows).
+ *   - Maintain a Lumo-owned venv at ~/.lumo/venv so user system Python stays clean.
+ *   - Install lumo-tools into that venv via pip — from PyPI by default,
+ *     from a local git path when --dev was passed.
+ *   - Expose absolute paths to each console script so SKILL.md and MCP configs
+ *     can reference them without depending on PATH.
+ */
+
+import { execFile, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+export const LUMO_HOME = path.join(os.homedir(), ".lumo");
+export const VENV_DIR = path.join(LUMO_HOME, "venv");
+const BIN_DIR = process.platform === "win32" ? "Scripts" : "bin";
+
+export function venvBinary(name) {
+  const ext = process.platform === "win32" ? ".exe" : "";
+  return path.join(VENV_DIR, BIN_DIR, `${name}${ext}`);
+}
+
+/** Returns the first usable Python interpreter or throws with install hint. */
+export function findPython() {
+  const candidates =
+    process.platform === "win32"
+      ? [["py", "-3"], ["python3"], ["python"]]
+      : [["python3"], ["python"]];
+
+  for (const [cmd, ...args] of candidates) {
+    const result = spawnSync(cmd, [...args, "--version"], { encoding: "utf8" });
+    if (result.status !== 0) continue;
+    const out = (result.stdout || result.stderr || "").trim();
+    const match = out.match(/Python (\d+)\.(\d+)/);
+    if (!match) continue;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    if (major < 3 || (major === 3 && minor < 10)) continue;
+    return { cmd, args, version: `${major}.${minor}` };
+  }
+
+  throw new Error(
+    "Python 3.10+ not found.\n" +
+      "  macOS:     brew install python@3.12\n" +
+      "  Ubuntu:    sudo apt install python3.12 python3.12-venv\n" +
+      "  Windows:   winget install Python.Python.3.12"
+  );
+}
+
+/** Create ~/.lumo/venv if it doesn't already exist. */
+export async function ensureVenv() {
+  fs.mkdirSync(LUMO_HOME, { recursive: true });
+  if (fs.existsSync(VENV_DIR) && fs.existsSync(venvBinary("python"))) {
+    return; // already there
+  }
+  const py = findPython();
+  await execFileP(py.cmd, [...py.args, "-m", "venv", VENV_DIR]);
+}
+
+/**
+ * Install lumo-tools into the Lumo-owned venv.
+ *
+ * @param {object} opts
+ * @param {string} [opts.source]  Local path to install from (used with --dev).
+ *                                When omitted, installs `lumo-tools` from PyPI.
+ */
+export async function installLumoTools(opts = {}) {
+  await ensureVenv();
+  const pip = venvBinary("pip");
+  const args = ["install", "--upgrade"];
+  if (opts.source) {
+    args.push("-e", opts.source);
+  } else {
+    args.push("lumo-tools");
+  }
+  await execFileP(pip, args, { maxBuffer: 20 * 1024 * 1024 });
+}
+
+/** Sanity check: each registered CLI binary actually exists in the venv. */
+export function listInstalledBinaries() {
+  const names = ["lumo-wcag", "lumo-theory", "lumo-parity", "lumo-mcp"];
+  return names.map((name) => ({
+    name,
+    path: venvBinary(name),
+    exists: fs.existsSync(venvBinary(name)),
+  }));
+}

package/src/lib/skill.js

@@ -0,0 +1,64 @@
+/**
+ * Skill file deployment.
+ *
+ * Copies the SKILL.md (and any references/) from the Lumo repo into the
+ * target client's skills directory. We resolve the source skill bundle
+ * relative to this installer file so it works in three modes:
+ *
+ *   1. `npm install -g lumo` — npm copied the installer next to the
+ *      bundled skill/ directory.
+ *   2. `npx lumo init` — same as above but transient.
+ *   3. `node installer/src/index.js init --dev` from a fresh git clone —
+ *      the skill/ directory is one level up from installer/.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/** Find the repo's skill/ directory regardless of install mode. */
+export function findSkillSource() {
+  const candidates = [
+    path.resolve(__dirname, "..", "..", "..", "skill"), // installer/src/lib → repo/skill
+    path.resolve(__dirname, "..", "..", "skill"),       // bundled-with-npm layout
+    path.resolve(__dirname, "skill"),                   // any other co-located case
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(candidate, "SKILL.md"))) return candidate;
+  }
+  throw new Error(
+    "Could not find the Lumo skill/ directory next to the installer. " +
+      "If you're running from a custom checkout, pass --dev with the repo root."
+  );
+}
+
+/** Recursive copy. Overwrites existing files; never deletes the destination root. */
+export function copyDirectory(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectory(from, to);
+    } else {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+/** Install the skill into a client's skill directory. Returns the dest path. */
+export function installSkill(targetDir) {
+  const source = findSkillSource();
+  copyDirectory(source, targetDir);
+  return targetDir;
+}
+
+/** Remove a previously-installed skill directory (no-op if not present). */
+export function removeSkill(targetDir) {
+  if (!fs.existsSync(targetDir)) return false;
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  return true;
+}