raffina 0.2.0

package/skills/raffina-design-loop/references/cli-contract.md

@@ -0,0 +1,197 @@
+# Raffina CLI contract
+
+Use this reference to select commands and interpret their machine-readable output. Prefer `--json` in agent workflows.
+
+## Resolve the executable
+
+When working in a Raffina source checkout, prefer the source runner so an old build artifact cannot silently override current behavior:
+
+1. `bun packages/cli/src/index.ts` from a source checkout with installed dependencies.
+2. `raffina` when installed globally or exposed by the consuming project.
+3. `bunx raffina` after the package is published.
+4. `./dist/raffina` only after running `bun run build` in the current worktree.
+
+Do not install software or mutate global configuration unless the user requested it.
+
+Before extraction, probe the selected executable's actual capabilities:
+
+```sh
+raffina --help
+raffina inspect --help
+raffina iterate --help
+```
+
+Require the global `--json` option and both `inspect --summary` and `iterate --summary` described below. If any are absent, the executable is stale or incompatible: switch to the source runner, rebuild the current checkout, or ask the user to upgrade. Do not trust `--version` alone and do not silently downgrade the workflow contract.
+
+The command examples below use `raffina` for readability. Substitute the complete selected invocation, such as `bun packages/cli/src/index.ts`; do not place a multiword invocation in a scalar shell variable.
+
+## Commands
+
+### Extract
+
+```sh
+raffina extract <url> \
+  --output <brand.json> \
+  --provider local \
+  --viewport 1440x1000 \
+  --viewport 390x844 \
+  --screenshot '<reference-{viewport}.png>' \
+  --timeout 30000 \
+  --json
+```
+
+Providers:
+
+- `local`: rendered browser evidence; preferred for visual and responsive fidelity.
+- `firecrawl`: remote acquisition; use only with an authorized environment key.
+- `hybrid`: combine remote discovery with local rendered evidence when both are available.
+
+The default provider is `local`. Repeat `--viewport` to acquire multiple responsive states.
+
+`--screenshot` saves the exact stabilized reference frame used for visual and composition extraction. When requesting multiple viewports, the path must contain `{viewport}`; Raffina replaces it with values such as `1440x1000` and refuses an ambiguous shared path. Firecrawl-only extraction cannot write a rendered frame; use `local` or `hybrid`. Inspect each reference PNG before choosing asset or composition hypotheses.
+
+### Inspect
+
+```sh
+raffina inspect <brand.json> --json --summary
+```
+
+The summary is a bounded, versioned implementation digest with complete totals and representative samples. Use it for initial planning. Important surfaces include:
+
+- `colorScheme` and top/per-viewport `cssVariables`.
+- Colors, fonts, logos, image/icon assets, and asset roles.
+- Spacing, content widths, borders, radii, and shadows.
+- Motion, textures, component styles, and voice.
+- `layoutCaptures`, responsive `regions`, and `responsiveCaptures` for composition changes.
+- Coverage and evidence availability.
+
+CSS variables, palette, typography, assets, shape, and motion use `{ total, samples }` so truncation is explicit. Layout maps become compact density summaries, and responsive profiles retain per-viewport counts and content-width samples.
+
+Content-width samples combine meaningful declared `max-width` constraints with a conservative rendered fallback for large centered containers. The fallback helps with CSS such as `width: min(1300px, calc(100% - 40px))`, whose computed `max-width` is `none`; it excludes full-width roots, small centered controls, and leaf media. Interpret rendered values within their recorded viewport.
+
+Responsive `regions` retain up to 12 large, styled or positioned first-viewport regions. Each includes a selector, role, pixel bounds, CSS positioning/z-index, background, border, radius, shadow, and overflow. Use them to rebuild panel and overlay relationships that a density map cannot express, then validate against the exact source PNG. They are bounded structural evidence, not a full DOM snapshot.
+
+After selecting a repair category, request only its complete fields from the full inspection. For example:
+
+```sh
+raffina inspect <brand.json> --json | jq '{fonts, typographyScale}'
+raffina inspect <brand.json> --json | jq '{assetInventory, componentStyles}'
+```
+
+The full inspection can be large. Do not load it unfiltered when the digest or a focused projection is sufficient.
+
+Treat `typography.families[].sources` as declared candidates, not proof that every file was rendered. For exact font bytes, prefer digest `assets.fonts.samples` or full `assetInventory.fonts` entries with `loaded: true`/a loaded role and a fingerprint. Do not combine an unfingerprinted declared source ahead of the verified file in a new `@font-face`; preserve the source site's unicode-range rules when multiple subsets are genuinely needed. For non-font assets, consult the canonical brand artifact's `identity.logos` and `assets` inventories before performing separate discovery. Preserve licensing and provenance constraints.
+
+Rendered image roles include the capture viewport, a conservative semantic class such as `prominent-media`, and observed dimensions/position. Use these factual placement hints with the corresponding reference PNG; do not infer a hero treatment from natural image dimensions or inventory order alone. Responsive extraction can retain more than one placement for the same asset.
+
+### Apply
+
+```sh
+raffina apply <brand.json> <target-path> \
+  --adapter auto \
+  --json
+```
+
+Adapters are `auto`, `static-html`, and `tokens-only`. Apply is dry-run by default. Add `--write` only after reviewing the plan and confirming target edits are authorized. `--html` may be used where supported for a static HTML target.
+
+Apply can create a useful token foundation. It does not replace composition, component, asset, responsive, or motion implementation.
+
+### Verify
+
+```sh
+raffina verify <target-url-or-file> \
+  --brand <brand.json> \
+  --profile <brand|visual-system> \
+  --output <report.json> \
+  --screenshot <measured-frame.png> \
+  --viewport 1440x1000 \
+  --timeout 30000 \
+  --json
+```
+
+The `1.0.0` verification report contains:
+
+- `profile`: present as `visual-system` for scoped transfer reports; omitted for the default `brand` profile to preserve compatibility.
+- `score`: weighted score from 0 through 100.
+- `verdict`: `on-brand`, `needs-review`, or `off-brand`.
+- `coverage`: fraction of checks backed by measurable evidence.
+- `checks`: category results with score, status, evidence, and feedback.
+- `findings`: pass/warning/fail explanations.
+- `nextActions`: ordered instructions with category, priority, and evidence.
+- `caveats`: limits and unmeasured evidence.
+
+Asset actions name the failing classes and include only the first few compact reference representatives. Resolve their complete URLs, labels, fingerprints, and remaining classes from `checks.assets.details.references`; do not infer that an omitted representative is absent from the reference.
+
+Composition actions compare only differing component properties and include the worst region per dominant evidence type. The complete component samples and all spatial mismatches remain in `checks.composition.details`; use those fields after selecting composition as the active hypothesis.
+
+When the reference contains salient positioned, stacked, or shadowed regions, composition also reports `layoutRegionGrammar`, region counts, the selected one-to-one `layoutRegionAssignments`, and bounded `missingLayoutRegions`. The assignment maximizes total match quality across the viewport instead of taking pairs greedily. An unmatched entry includes the nearest `closestObserved` target geometry, match similarity, and whether that candidate is assigned to another reference region. Matching uses viewport-normalized geometry, role and layering features rather than selector identity; duplicate wrapper geometry is merged. This is supporting evidence with a bounded penalty, not a requirement to reproduce the source DOM hierarchy.
+
+Here `missing` means no observed target region cleared the match threshold, not that the target has no visible panel. Reshape an unclaimed `closestObserved` candidate; add or split only when the candidate already serves another reference region or no candidate exists. Inspect the exact frames before editing either way.
+
+`--screenshot` writes the exact stabilized PNG used to calculate screenshot and composition evidence; it does not trigger a second render. The path is command/workflow metadata rather than part of the frozen `VerificationReport` schema. The caller already owns that path, human output repeats it, and `iterate` records it with the run.
+
+Check status can be `measured`, `partial`, or `not-measured`. Never interpret an unmeasured category as a pass. Load-bearing gate failures can cap the overall result even when several cosmetic checks are strong.
+
+Profiles:
+
+- `brand` (default) scores every category and requires source asset identity where measurable.
+- `visual-system` scores and gates visual, composition, color, typography, motion, and shape. Asset identity and voice checks remain in `checks` for diagnosis but do not affect score, verdict, findings, or action ordering. Its `on-brand` verdict certifies only the scoped visual system.
+
+### Iterate
+
+```sh
+raffina iterate <target-url-or-file> \
+  --brand <brand.json> \
+  --profile <brand|visual-system> \
+  --history <iterations.json> \
+  --viewport 1440x1000 \
+  --target-score 85 \
+  --label <specific-change> \
+  --screenshot <iteration-frame.png> \
+  --report <iteration-report.json> \
+  --json --summary
+```
+
+`--summary` requires `--json`. The `1.0.0` summary contains `historyPath`, `brand`, `target`, `viewport`, `targetScore`, `bestRun`, `bestScore`, `totalRuns`, and the current `run`.
+
+The current run contains:
+
+- `score`, `delta`, `remaining`, `coverage`, and `verdict`.
+- `screenshot` when the run wrote its measured frame.
+- `report` when the run wrote its complete verification evidence.
+- `targetMet`, which requires the score target and an `on-brand` verdict.
+- Per-category `checks` and `checkDeltas`.
+- `regressions` for category drops greater than two points.
+- Ordered `nextActions`.
+
+An existing history is accepted only when its brand identity, observation, target, viewport, verification profile, and target score match. Use a new history file after changing any of those inputs. Histories from versions that did not record a viewport cannot be appended; choose a new path rather than risk mixing desktop and mobile measurements. Histories without a profile are treated as the legacy default `brand` profile.
+
+Use `--report` when later hypothesis selection needs full check details. It writes the complete `VerificationReport` produced by the same stabilized observation and stores its resolved path on the run; this preserves compact summaries without requiring a second render.
+
+Extraction and inspection motion totals count retained definitions/samples. Verification repair text can report rendered occurrence coverage by animation, transition, and keyframe kind. Compare counts within the same output surface; do not treat definition totals and occurrence totals as contradictory.
+
+## Errors and exit behavior
+
+Agent-facing failures use a structured JSON envelope when JSON output is requested:
+
+```json
+{
+  "error": {
+    "code": "INVALID_ARGUMENT",
+    "message": "Human-readable explanation",
+    "details": {}
+  }
+}
+```
+
+Treat non-zero exit status as failure even if partial output exists. Preserve error codes and messages in the report instead of guessing.
+
+## Evidence discipline
+
+- Render the target at the same viewport used for the reference capture.
+- Use browser evidence as the source of truth for visual verification.
+- Never claim a source-only check proves rendered adherence.
+- Do not compare unrelated pages or states and call the result conclusive.
+- Do not expose provider keys in terminal output, artifacts, histories, or commits.
+- Keep functional and accessibility tests alongside Raffina; the verifier is not a substitute for them.
+- Write milestone PNGs with `verify/iterate --screenshot`; these are the same stabilized frames used by the verifier. Use an available viewer for human judgment, and report human review as pending when no viewer exists.