raffina 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raffina contributors
+
+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,129 @@
+# Raffina
+
+**Make AI-built interfaces feel intentional.**
+
+Raffina is an evidence-backed design extraction and verification CLI for humans and coding agents. Give it a public website and it builds a reusable brand system from the rendered page—logos, fonts, colors, spacing, layout, assets, motion, shape, and voice. Use that system to guide an implementation, measure the rendered result, and iterate toward the reference.
+
+Raffina is in early beta. Its artifacts are runtime-validated and versioned, but commands and scoring details may still evolve before 1.0.
+
+Raffina is a design compiler and linter, not an official brand guide or a substitute for human review.
+
+## Install
+
+Run without installing:
+
+```bash
+bunx raffina --help
+```
+
+Or install globally:
+
+```bash
+bun add --global raffina
+raffina --version
+```
+
+The package is one bundled Bun CLI. It requires Bun 1.3 or newer and Chrome or Chromium for webpage extraction and verification. Set `CHROME_PATH` when the browser is installed in a non-standard location.
+
+## Quick start
+
+Extract a responsive reference:
+
+```bash
+bunx raffina extract https://cursor.com \
+  --viewport 1440x1000 \
+  --viewport 390x844 \
+  --screenshot 'reference-{viewport}.png' \
+  --output cursor.brand.json
+```
+
+Inspect the useful system:
+
+```bash
+bunx raffina inspect cursor.brand.json
+bunx raffina inspect cursor.brand.json --json --summary
+```
+
+Start the target application, then verify its rendered result:
+
+```bash
+bunx raffina verify http://localhost:3000 \
+  --brand cursor.brand.json \
+  --viewport 1440x1000 \
+  --screenshot target.png \
+  --output report.json
+```
+
+Iterate with category deltas, regressions, and ranked next fixes:
+
+```bash
+bunx raffina iterate http://localhost:3000 \
+  --brand cursor.brand.json \
+  --history .raffina/iterations.json \
+  --report .raffina/latest.report.json \
+  --screenshot .raffina/latest.png \
+  --label hero-layout \
+  --json --summary
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `raffina extract <url>` | Render a website and build a typed, evidence-backed brand system. |
+| `raffina inspect <brand>` | Read the system as a human summary or bounded agent digest. |
+| `raffina apply <brand> <target>` | Preview or write portable tokens and a conservative codebase adapter. |
+| `raffina verify <target>` | Score one rendered target and produce actionable evidence. |
+| `raffina iterate <target>` | Append an attempt, deltas, regressions, and next fixes. |
+| `raffina skill install` | Install the bundled agent design-loop skill into Codex. |
+
+Run `raffina <command> --help` for every option. Every command supports machine-readable output through `--json`.
+
+## What verification checks
+
+Raffina measures screenshot structure, spatial composition, rendered colors, typography and loaded font bytes, asset identity, motion grammar, shape, and representative voice signals.
+
+The default `brand` profile checks exact identity and voice. Use `--profile visual-system` to transfer composition, color, typography, motion, and shape while preserving the target product's logo and copy.
+
+An `on-brand` verdict requires an overall score of at least 85, at least 80% evidence coverage, and the load-bearing category gates. Missing evidence becomes `not-measured`; it never silently receives a perfect score. Verification is specific to the captured viewport and state.
+
+The installed package includes the exact formulas, evidence requirements, category ceilings, gate logic, and repair ordering in `docs/verification.md`.
+
+## Agent workflow
+
+The package includes the `raffina-design-loop` skill:
+
+```bash
+bunx raffina skill install
+```
+
+It guides an agent through:
+
+```text
+extract → inspect → understand the target → render a baseline
+       → implement one focused change → verify → keep or revert → repeat
+```
+
+The CLI remains the deterministic measurement engine. The skill provides implementation strategy, bounded context, responsive iteration rules, and regression guardrails.
+
+## Providers
+
+- `local` is the default and requires no paid service.
+- `firecrawl` uses Firecrawl's hosted branding response.
+- `hybrid` keeps rendered local evidence as the baseline and uses Firecrawl as an independent semantic vote.
+
+```bash
+FIRECRAWL_API_KEY=... bunx raffina extract https://example.com \
+  --provider hybrid \
+  --output example.brand.json
+```
+
+Provider conflicts remain visible rather than being silently overwritten. Never commit provider keys.
+
+## Important limits
+
+Raffina does not grant rights to public assets, infer uncaptured routes or states, or replace human judgment for originality, accessibility, licensing, and brand-owner intent. It records asset URLs and fingerprints but does not redistribute logos, imagery, or fonts.
+
+Source, architecture, benchmark evidence, and release instructions live in the [Raffina repository](https://github.com/zvadaadam/raffina).
+
+MIT licensed.