<div align="center">

# ⚡ LUMINA
### The Generative Frontend Engine & Automated MCP for AI Developers
**Linear · Apple · Vercel · Stripe · Teenage Engineering Tier Standards**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-cyan.svg?style=flat-square)](https://python.org)
[![MCP Compatible](https://img.shields.io/badge/MCP-Model_Context_Protocol-purple.svg?style=flat-square)](https://modelcontextprotocol.io)
[![Zero Trace](https://img.shields.io/badge/Zero--Trace-Uninstaller-emerald.svg?style=flat-square)](#-zero-trace-uninstallation)
[![Design Standard](https://img.shields.io/badge/Standard-Tier_S_Luxury-orange.svg?style=flat-square)](#-9-luxury-design-archetypes)

<br/>

> **Lumina** is an autonomous generative frontend engine and Model Context Protocol (MCP) server for **Google Antigravity (AGY)** and **Claude Code**.  
> It eradicates repetitive **"AI Slop"** (generic purple gradients, unchamfered flat cards, raw untracked fonts, and dead buttons) and empowers LLMs with **bespoke, tactile, and living design systems**.

---

</div>

## ⚡ Global Installation (One-Liner)

Install Lumina globally in seconds. The installer configures the CLI binary, sets up your system PATH, and **automatically registers the Lumina MCP server** into your AI environment without touching existing tools.

### 🪟 Windows (PowerShell - Recommended)
```powershell
irm https://raw.githubusercontent.com/Farukes/lumina/main/install.ps1 | iex
```

### 🐍 Python (Windows / macOS / Linux)
```bash
python -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/Farukes/lumina/main/install.py').read())"
```

### 📦 Alternative: Clone & Install Locally
```bash
git clone https://github.com/Farukes/lumina.git
cd lumina
python install.py
```

> **What Does Installation Do?**
> 1. Syncs the engine to `~/.lumina/engine`.
> 2. Registers the global `lumina` executable into your User `PATH`.
> 3. Automatically configures the Lumina MCP server in **Antigravity** (`~/.gemini/config/mcp_config.json`) and **Claude Desktop** without touching other servers (your existing MCP servers remain 100% intact).

---

## 🎮 Core Commands (Intuitive & Minimal)

Lumina replaces complex subcommands with **4 primary actions**:

| Command | Action | Description |
| :--- | :---: | :--- |
| **`lumina`** | 🎮 | **Interactive HUD**: Visual terminal dashboard to inspect themes, audit code, and toggle features. |
| **`lumina on`** | 🚀 | **Activate in Workspace**: Injects the Lumina Constitution (`GEMINI.md`, `.agents/rules`) and CSS tokens. |
| **`lumina fix`** | ✨ | **Codebase Polisher**: Scans and automatically refactors AI-slop into Apple/Linear-grade patterns. |
| **`lumina check`** | 🔍 | **Design Quality Linter**: Audits code for 12+ anti-patterns and outputs a 0–100 design score. |
| **`lumina off`** | 🧹 | **Eject from Project**: Cleans all Lumina rules and tokens from the current project cleanly. |

### 🛠️ Quick Utilities
* `lumina theme` $\rightarrow$ Explore and switch between 9 handcrafted luxury archetypes.
* `lumina view` $\rightarrow$ Launch the interactive HTML5 live showcase directly in your default browser.
* `lumina add <block>` $\rightarrow$ Add battle-tested AAA blocks (`bento-grid`, `command-bar`, `floating-dock`, `glow-hero`, etc.).
* `lumina mcp` $\rightarrow$ Launch the Model Context Protocol stdio server (or `lumina mcp -i` to re-register).

---

## 🧠 Smart AI Assistant Detection (Zero Clutter)

Lumina automatically inspects your machine to avoid generating clutter:
* **Antigravity (AGY) detected:** Injects only `GEMINI.md` and `.agents/rules`. If Claude Code is not on your PC, **no unnecessary `CLAUDE.md` or `.claude/` files are generated.**
* **Claude Code detected:** Injects Claude Code directives and skills.
* **Manual Override:**
  ```bash
  lumina on --ai agy      # Target Antigravity exclusively
  lumina on --ai claude   # Target Claude Code exclusively
  lumina on --ai both     # Target both environments
  ```

---

## 🎨 9 Luxury Design Archetypes

Lumina features 9 original, copyright-clean design archetypes to guide generative AI models:

1. **`obsidian-craft` (Linear Tier):** Deep obsidian (`#09090b`), 1px inner metallic specular chamfer (`border-white/[0.08] shadow-[inset_0_1px_0_0_rgba(255,255,255,0.06)]`), emerald accents.
2. **`industrial-machina` (Teenage Engineering):** Matte aluminum (`#18181b`), dot-matrix typography, tactile Safety Orange (`#ff4400`) switches.
3. **`liquid-spatial` (visionOS):** Liquid refraction, multi-tier backdrop blur (`backdrop-blur-2xl`), specular top rim reflection (`border-t-white/40`), viscous spring physics.
4. **`parchment-editorial` (Stripe Press):** Warm unbleached paper tone (`#fbf9f5`), editorial serif typography (Newsreader), 0.5px razor dividers.
5. **`stark-monolith` (Vercel Discipline):** Pure monochrome contrast, Geist font pairing, razor 0.5px structural grids.
6. **`fintech-horizon` (Stripe SaaS):** Midnight deep slate, ambient mesh auroras, soft dimensional elevation.
7. **`amber-terminal` (Raycast Cyber):** Phosphor amber glow (`#f59e0b`), monospace telemetry, keyboard-first navigation (<kbd>⌘K</kbd>).
8. **`pure-cupertino` (Apple Clean):** Multi-layer squircle geometry, generous negative space, translucent glass morphology.
9. **`refined-brutalism`:** Crisp 2px ink borders, 3px zero-blur hard offset drop shadows (`shadow-[3px_3px_0_0_#000]`), electric acid accents.

---

## 🤖 Model Context Protocol (MCP) Suite

Lumina exposes 5 generative AI tools via Model Context Protocol:

* **`synthesize_design_tokens`**: Generates OKLCH color palettes, chamfer highlights, and spring physics tailored to archetype, data density, and materiality.
* **`get_composition_grammar`**: Teaches AI structural layout laws, visual hierarchy balances, and ASCII wireframes without enforcing rigid cookie-cutter templates.
* **`get_visual_primitive`**: Returns mathematical formulas and micro-interaction primitives (Border Beam, Spotlight Follow, 3D Perspective Tilt, Text Scramble, Web Audio).
* **`get_component_blueprint`**: Provides reference architecture for complex living blocks (Living Bento Grid, Command Bar, Dynamic Island Dock).
* **`critique_ui_design`**: Audits submitted JSX/TSX/HTML code through the lens of a Senior Design Director.

---

## 🗑️ Zero-Trace Uninstallation

Lumina is strictly isolated. It never creates Windows Registry entries, runs background daemons, or leaves orphaned files.

To remove Lumina from your entire computer:
```bash
lumina uninstall
```

**Clean Removal Guarantee:**
* Purges the global engine directory (`~/.lumina`).
* Removes `~/.lumina/bin` from your user `PATH` environment variable.
* Safely removes `"lumina"` from `mcp_config.json` (**all other MCP servers remain completely untouched**).
* Removes workspace-level constitutions and CSS tokens.
* Leaves exactly **0 bytes and 0 traces** behind.

---

## 📦 Repository Structure

```
lumina/
├── install.py             # Global cross-platform Python installer
├── install.ps1            # Windows single-line PowerShell installer
├── lumina/
│   ├── cli.py             # Click & Rich CLI master entrypoint
│   └── core/
│       ├── installer.py   # Global installation, PATH & MCP configuration engine
│       ├── auditor.py     # 12+ AI-slop pattern scanner and scoring engine
│       ├── polisher.py    # Automated code refactoring and chamfer injector
│       ├── themes.py      # 9 luxury design archetypes with OKLCH tokens
│       ├── registry.py    # AAA component blueprints
│       └── rules_generator.py # Smart environment-aware AI rule injector
├── mcp/
│   └── server.py          # Model Context Protocol (MCP) stdio server
├── components/blocks/     # React & Tailwind living UI blocks
└── showcase/              # Interactive live browser showcase
```

---

## 📄 License

This project is licensed under the [MIT License](LICENSE). Open-source, free for personal and commercial use.