basiclines · basiclines · Mar 17, 2026 · Mar 16, 2026 · Mar 16, 2026 · Mar 16, 2026
diff --git a/.github/skills/update-docs/SKILL.md b/.github/skills/update-docs/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: update-docs
+description: Audit and update all rampa project documentation after code changes. Use when adding features, changing defaults, modifying APIs, or before a release.
+metadata:
+  author: ismael.fyi
+  version: "1.0.0"
+---
+
+# Update Documentation
+
+Audit and update all project documentation to reflect current code.
+
+## Doc Files to Update
+
+| File | Purpose |
+|------|---------|
+| `sdk/README.md` | SDK user-facing docs — transforms, palette API, value ranges, type exports |
+| `cli/README.md` | CLI user-facing docs — all subcommand flag tables, examples, defaults |
+| `cli/src/palette.ts` | CLI palette `showHelp()` function and `parseArgs()` defaults |
+| `cli/src/index.ts` | Main `rampa --help` text — subcommand list, IMAGE PALETTE section |
+| `cli/src/color.ts` | CLI color subcommand help text and transform flags |
+| `AGENTS.md` | Architecture guide — build commands, file map, conventions |
+
+## Source Files to Read
+
+| File | What to check |
+|------|---------------|
+| `sdk/src/index.ts` | All SDK exports — types and classes |
+| `sdk/src/palette.ts` | PaletteResult API surface, options interfaces, defaults |
+| `sdk/src/types.ts` | All public type definitions |
+| `sdk/src/color-result.ts` | Color transform methods, value ranges |
+| `src/engine/PaletteEngine.ts` | Engine defaults — sampleSize, tolerance, bucket counts |
+| `cli/src/palette.ts` | CLI palette `parseArgs()` defaults, flag list |
+| `cli/src/color.ts` | CLI color transform flags |
+
+## Audit Process
+
+1. **Read source files** to understand current API surface and defaults
+2. **Read doc files** to see what's documented
+3. **Diff** — find stale defaults, missing features, removed APIs
+4. **Update** — make surgical edits to fix gaps
+5. **Verify** — CLI help text defaults must match `parseArgs()` defaults in the same file
+
+## Defaults to Track
+
+These change occasionally and must be consistent across all docs:
+
+| Setting | Source of truth | Also appears in |
+|---------|----------------|-----------------|
+| Sample size | `PaletteEngine.ts` `samplePixels` default | `sdk/palette.ts`, `cli/palette.ts` parseArgs, SDK README, CLI README, CLI help |
+| K-means tolerance | `PaletteEngine.ts` `kMeansClustering` default | `sdk/palette.ts` DominantOptions JSDoc, `cli/palette.ts` parseArgs, SDK README, CLI README, CLI help |
+| Raw tolerance | `PaletteEngine.ts` `buildRawPalette` default | `cli/palette.ts` parseArgs, CLI README, CLI help |
+| Dominant count | `cli/palette.ts` parseArgs default | CLI README, CLI help |
+| ANSI count | `PaletteEngine.ts` `buildAnsiPalette` default | SDK README |
+| L bucket count | `PaletteEngine.ts` `DEFAULT_L_BUCKETS` array length | `cli/palette.ts` parseArgs `lBuckets`, CLI README, CLI help |
+| C bucket count | `PaletteEngine.ts` `DEFAULT_C_BUCKETS` array length | `cli/palette.ts` parseArgs `cBuckets`, CLI README, CLI help |
+| H bucket count | `PaletteEngine.ts` `DEFAULT_H_BUCKETS` array length | `cli/palette.ts` parseArgs `hBuckets`, CLI README, CLI help |
+| Contrast mode | `sdk/src/contrast.ts` default mode | SDK README, CLI README |
+
+## SDK README Sections to Verify
+
+- Color transforms (lighten, darken, saturate, desaturate, rotate, set, mix, blend)
+- Value ranges (HSL s/l and OKLCH l use 0-1 scale, NOT 0-100)
+- Ramp introspection (.at(), .colors() on Linear/Plane/CubeColorSpace)
+- Palette extraction (palette(), dominant(), raw(), ansi(), group(), sortBy())
+- Output formats (json, css, text)
+- Type exports (all public types from `sdk/src/index.ts` should be mentioned)
+
+## CLI README Sections to Verify
+
+- `rampa color` flags table (transform flags: --lighten, --darken, etc.)
+- `rampa palette` flags table (all flags with correct defaults)
+- `rampa palette` usage examples
+- `rampa lint` flags
+- `rampa colorspace` flags
+
+## Rules
+
+- **Release notes**: Only include SDK/CLI changes. Never include site/editor/landing page changes.
+- **Site demos**: Only update `site/` if SDK API changes break existing demos.
+- **Value ranges**: 0-1 scale for HSL s/l and OKLCH l. Format string output is unchanged.
+- **Help text**: CLI `showHelp()` defaults must exactly match `parseArgs()` defaults in the same file.
diff --git a/AGENTS.md b/AGENTS.md
@@ -32,17 +32,21 @@ src/engine/          ← Core math (color mixing, interpolation, ramps)
   ├── ColorSpaceEngine.ts  Linear/Plane/Cube color space generation
   ├── OklchEngine.ts       Color mixing and perceptual uniformity
   ├── HarmonyEngine.ts     Complementary, triadic, analogous, etc.
-  └── BlendingEngine.ts    16 blend modes for tinting
+  ├── BlendingEngine.ts    16 blend modes for tinting
+  ├── PaletteEngine.ts     Image palette extraction (k-means, ANSI classification)
+  └── ImageDecoder.ts      PNG/JPEG decoding (fast-png + jpeg-js)
 
 sdk/src/             ← npm package (@basiclines/rampa-sdk)
   ├── builder.ts           rampa('#hex').size(10).lightness(10,90) → callable palette
+  ├── palette.ts           palette('image.jpg') → dominant, raw, ansi, average
   ├── linear-color-space.ts
   ├── plane-color-space.ts
   └── cube-color-space.ts
 
 cli/src/             ← npm package (@basiclines/rampa)
   ├── index.ts             Main CLI entry (citty framework)
-  └── colorspace.ts        `rampa colorspace` subcommand
+  ├── colorspace.ts        `rampa colorspace` subcommand
+  └── palette.ts           `rampa palette` subcommand
 
 src/                 ← React web app (rampa.studio)
   ├── components/          shadcn/ui + @react-three/fiber for 3D viewer
@@ -70,6 +74,24 @@ Do NOT use `.hex` property — use template literals or `.valueOf()`.
 - **CubeColorSpace** — 3D cube (8 corner colors: k, r, g, b, y, m, c, w)
 
 All support chainable `.interpolation()`, `.format()`, `.size()`.
+All support `.at()` for 0-based Color access and `.colors()` for Color[] arrays.
+
+### Color Transforms
+All transforms on `color()` operate in **OKLCH space** and return a new immutable `Color`:
+- `lighten(n)`, `darken(n)` — absolute L delta (0-1 scale)
+- `saturate(n)`, `desaturate(n)` — absolute chroma delta
+- `rotate(n)` — hue rotation in degrees
+- `set({ lightness?, chroma?, hue? })` — absolute OKLCH values
+- `mix(color, ratio, space?)` — color space interpolation (oklch/lab/srgb)
+- `blend(color, opacity, mode)` — compositing modes (multiply/screen/overlay etc.)
+
+### Value Ranges
+All structured property values use **0-1 normalized ranges** (CSS-spec aligned):
+- `hsl.s`, `hsl.l` — 0 to 1 (not 0-100)
+- `oklch.l` — 0 to 1 (not 0-100)
+- `oklch.c` — 0 to ~0.4 (native OKLCH)
+- Hue values are always 0-360 degrees
+- `.format()` string output uses CSS conventions (percentages where appropriate)
 
 ### SDK Type Declarations
 When adding new types, interfaces, or classes to the SDK:
@@ -107,3 +129,9 @@ CLI uses manual argument parsing (not a framework for `colorspace` subcommand).
 **Always include release notes** when creating a GitHub release. Summarize new features, fixes, and breaking changes. Use the PR descriptions and commit messages as source material.
 
 **Always ask the user before committing and pushing.**
+
+## Development Skills
+
+Internal skills for rampa development live in `.github/skills/`:
+
+- **`update-docs`** — Audit and update all documentation after code changes. Lists every doc file, source file, and default value that must stay in sync. Use after adding features or changing defaults.
diff --git a/bun.lockb b/bun.lockb
diff --git a/cli/README.md b/cli/README.md
@@ -267,7 +267,7 @@ rampa lint --fg '#fff' --bg '#000' --output json
 
 ### Color
 
-Inspect a color in all supported formats (hex, hsl, rgb, oklch).
+Inspect, transform, mix, and export a single color. All transforms operate in OKLCH space.
 
 ```bash
 rampa color '#ff6600'
@@ -277,9 +277,31 @@ rampa color '#1e1e2e' -O css --prefix brand
 
 | Flag | Alias | Description |
 |------|-------|-------------|
-| `<color>` | `-c` | Color to inspect (positional or flag) |
+| `<color>` | `-c` | Color to inspect/transform (positional or flag) |
 | `--output <text\|json\|css>` | `-O` | Output format (default: text) |
 | `--prefix <name>` | | Prefix for CSS variable names (default: color) |
+| `--lighten <n>` | | Increase OKLCH lightness by n (0-1 scale) |
+| `--darken <n>` | | Decrease OKLCH lightness by n |
+| `--saturate <n>` | | Increase OKLCH chroma by n |
+| `--desaturate <n>` | | Decrease OKLCH chroma by n |
+| `--rotate <n>` | | Rotate hue by n degrees |
+| `--set-lightness <n>` | | Set OKLCH lightness to n |
+| `--set-chroma <n>` | | Set OKLCH chroma to n |
+| `--set-hue <n>` | | Set hue to n degrees |
+| `--mix <color>` | | Mix with target color (use --ratio, --space) |
+| `--blend <color>` | | Blend with target color (use --ratio, --mode) |
+| `--ratio <n>` | | Mix/blend ratio 0-1 (default: 0.5) |
+| `--space <oklch\|lab\|srgb>` | | Color space for --mix (default: oklch) |
+| `--mode <name>` | | Blend mode for --blend (multiply, screen, overlay, etc.) |
+
+Transforms are applied left-to-right, matching SDK chaining order:
+
+```bash
+rampa color '#66b172' --lighten 0.1 --desaturate 0.05
+rampa color '#ff0000' --mix '#0000ff' --ratio 0.5 --space lab
+rampa color '#ff8800' --blend '#0088ff' --ratio 0.5 --mode multiply
+rampa color '#66b172' --lighten 0.1 --desaturate 0.05 -O css --prefix brand
+```
 
 ### Other
 
@@ -288,6 +310,38 @@ rampa color '#1e1e2e' -O css --prefix brand
 | `--help` | `-h` | Show help |
 | `--version` | `-v` | Show version |
 
+### Image Palette
+
+Extract color palettes from PNG and JPEG images.
+
+```bash
+rampa palette photo.jpg
+rampa palette photo.jpg --count 5
+rampa palette photo.jpg --ansi --count 3
+rampa palette photo.jpg --group C --sort L
+rampa palette photo.jpg --output json
+```
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `<file>` | | Image file path (PNG or JPEG) |
+| `--count <n>` | | Number of dominant colors (default: 10) |
+| `--tolerance <n>` | | DeltaE clustering radius (default: 4) |
+| `--raw` | | Show all unique colors |
+| `--raw-tolerance <n>` | | DeltaE threshold for raw dedup (default: 2) |
+| `--max-colors <n>` | | Max colors for raw output (default: 1000) |
+| `--ansi` | | Classify into ANSI color categories |
+| `--group <L\|C\|H>` | | Group by lightness, chroma, or hue |
+| `--l-buckets <n>` | | Number of lightness buckets (default: 5) |
+| `--c-buckets <n>` | | Number of chroma buckets (default: 4) |
+| `--h-buckets <n>` | | Number of hue buckets (default: 8) |
+| `--sort <frequency\|L\|C\|H>` | | Sort order (default: frequency) |
+| `--average` | | Show average color only |
+| `--temperature` | | Show color temperature only |
+| `--sample-size <n>` | | Pixels to sample (default: 50000) |
+| `--output <text\|json\|css>` | `-O` | Output format (default: text) |
+| `--prefix <name>` | | CSS variable prefix (default: palette) |
+
 ## Examples
 
 ### Basic Palette
@@ -454,13 +508,63 @@ rampa lint --fg '#fff' --bg '#000' -O css
 
 ```bash
 # View all formats
-rampa inspect -c '#ff6600'
+rampa color '#ff6600'
 
 # JSON output
-rampa inspect -c 'rgb(100, 200, 50)' --output json
+rampa color 'rgb(100, 200, 50)' --output json
 
 # CSS custom properties
-rampa inspect -c '#1e1e2e' -O css
+rampa color '#1e1e2e' -O css
+
+# Transform: lighten and desaturate
+rampa color '#66b172' --lighten 0.1 --desaturate 0.05
+
+# Derive bright variant
+rampa color '#06ef48' --lighten 0.1 --desaturate 0.05
+
+# Mix two colors in lab space
+rampa color '#ff0000' --mix '#0000ff' --ratio 0.5 --space lab
+
+# Blend with multiply mode
+rampa color '#ff8800' --blend '#0088ff' --ratio 0.5 --mode multiply
+
+# Set absolute OKLCH values
+rampa color '#f85149' --set-lightness 0.48 --set-chroma 0.15
+```
+
+### Image Palette
+
+```bash
+# Dominant colors from a photo
+rampa palette photo.jpg
+
+# Top 5 with ANSI swatches
+rampa palette photo.jpg --count 5
+
+# ANSI-classified palette
+rampa palette photo.jpg --ansi --count 3
+
+# Group by chroma, sorted by lightness (accent discovery)
+rampa palette photo.jpg --group C --sort L
+
+# Group by lightness with 3 buckets
+rampa palette photo.jpg --group L --l-buckets 3
+
+# Group by hue, sorted dark→light
+rampa palette photo.jpg --group H --sort L
+
+# Raw unique colors
+rampa palette photo.jpg --raw --tolerance 5
+
+# JSON output for tooling
+rampa palette photo.jpg --output json
+
+# CSS variables
+rampa palette photo.jpg --output css --prefix photo
+
+# Average color and temperature
+rampa palette photo.jpg --average
+rampa palette photo.jpg --temperature
 ```
 
 ## Contextual Help

diff --git a/cli/bun.lock b/cli/bun.lock
diff --git a/cli/package.json b/cli/package.json
@@ -45,7 +45,9 @@
   },
   "dependencies": {
     "chroma-js": "^3.1.2",
-    "citty": "^0.1.6"
+    "citty": "^0.1.6",
+    "fast-png": "^8.0.0",
+    "jpeg-js": "^0.4.4"
   },
   "devDependencies": {
     "@github/copilot-sdk": "^0.1.23",