similarbuild 0.1.0

package/templates/skills/sb-review-checks/scripts/tests/test-review-checks.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// test-review-checks.mjs — CLI integration tests for review-checks.mjs.
+// Covers: --help, arg validation, exit codes. Plus optional integration tests
+// that exercise the full end-to-end path against fixture HTML/Liquid (skipped
+// gracefully when cheerio isn't installed).
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve, join } from 'node:path'
+import { mkdir, writeFile, readFile, rm } from 'node:fs/promises'
+import { strict as assert } from 'node:assert'
+import { tmpdir } from 'node:os'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const SCRIPT = resolve(here, '..', 'review-checks.mjs')
+
+let passed = 0
+let failed = 0
+
+function test(name, fn) {
+  try {
+    const result = fn()
+    if (result && typeof result.then === 'function') {
+      return result.then(
+        () => { process.stdout.write(`ok - ${name}\n`); passed++ },
+        (err) => { process.stdout.write(`not ok - ${name}\n  ${err.message}\n`); failed++ },
+      )
+    }
+    process.stdout.write(`ok - ${name}\n`)
+    passed++
+  } catch (err) {
+    process.stdout.write(`not ok - ${name}\n  ${err.message}\n`)
+    failed++
+  }
+}
+
+function skip(name, reason) {
+  process.stdout.write(`ok - ${name} # SKIP ${reason}\n`)
+  passed++
+}
+
+function run(args) {
+  return spawnSync('node', [SCRIPT, ...args], { encoding: 'utf8' })
+}
+
+// ─── help + arg validation (no deps required) ──────────────────────────────
+
+test('--help exits 0 and prints usage', () => {
+  const r = run(['--help'])
+  assert.equal(r.status, 0, `exit code was ${r.status}\n${r.stderr}`)
+  assert.match(r.stdout, /review-checks\.mjs/)
+  assert.match(r.stdout, /--file/)
+  assert.match(r.stdout, /--preset/)
+  assert.match(r.stdout, /--output-dir/)
+  assert.match(r.stdout, /--compare-diffs/)
+})
+
+test('missing --file exits 2', () => {
+  const r = run(['--preset', 'wp-elementor', '--output-dir', '/tmp/x'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --file/)
+})
+
+test('missing --preset exits 2', () => {
+  const r = run(['--file', '/tmp/x.html', '--output-dir', '/tmp/x'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --preset/)
+})
+
+test('missing --output-dir exits 2', () => {
+  const r = run(['--file', '/tmp/x.html', '--preset', 'wp-elementor'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /missing --output-dir/)
+})
+
+test('invalid --preset value exits 2', () => {
+  const r = run([
+    '--file', '/tmp/x.html',
+    '--preset', 'wordpress',
+    '--output-dir', '/tmp/x',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /--preset must be one of/)
+})
+
+test('non-existent --file exits 2', () => {
+  const r = run([
+    '--file', '/tmp/sb-review-does-not-exist-xyz.html',
+    '--preset', 'wp-elementor',
+    '--output-dir', '/tmp/sb-review-test-out',
+  ])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /not found/)
+})
+
+test('stderr always carries the [sb-review-checks] prefix', () => {
+  const r = run(['--file', '/tmp/nope.html', '--preset', 'wp-elementor', '--output-dir', '/tmp/x'])
+  assert.equal(r.status, 2)
+  assert.match(r.stderr, /^\[sb-review-checks\]/)
+})
+
+// ─── integration: cheerio-gated ─────────────────────────────────────────────
+
+let cheerioAvailable = false
+try { await import('cheerio'); cheerioAvailable = true } catch {}
+
+const TMPROOT = join(tmpdir(), `sb-review-checks-test-${Date.now()}`)
+
+if (!cheerioAvailable) {
+  skip('integration: clean fragment exits 0 with passed=true', 'cheerio not installed')
+  skip('integration: dirty fragment exits 3 with violations', 'cheerio not installed')
+  skip('integration: writes report.json + emits stdout JSON', 'cheerio not installed')
+  skip('integration: cross-reference escalates correlated violations', 'cheerio not installed')
+  skip('integration: low-only violations still pass (exit 0)', 'cheerio not installed')
+} else {
+  await mkdir(TMPROOT, { recursive: true })
+
+  const cleanHtml = `<!-- clean fragment -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link rel="preload" as="image" href="hero.jpg">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter&display=swap">
+<style>
+  .scope { box-sizing: border-box; }
+  .scope .scope__title { font-size: 24px !important; }
+  .scope .scope__cta.scope__cta { background: #d8112a !important; color: #fff !important; }
+</style>
+<section class="scope">
+  <h1 class="scope__title">Hello</h1>
+  <img src="hero.jpg" alt="Hero" loading="eager">
+  <button type="button" class="scope__cta">Buy now</button>
+</section>`
+
+  const dirtyHtml = `<style>
+  .hero { height: 100vh; }
+  .title { font-size: 24px !important; }
+  .cta { background: red; color: white; }
+  .scope a { color: inherit; }
+  .x { opacity: 0.5; }
+</style>
+<section class="hero">
+  <h3>Bad first heading</h3>
+  <img src="hero.jpg">
+  <img src="other.jpg">
+  <button><svg></svg></button>
+  <div class="modal">x</div>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter">
+</section>`
+
+  await test('integration: clean fragment exits 0 with passed=true', async () => {
+    const dir = join(TMPROOT, 'clean')
+    await mkdir(dir, { recursive: true })
+    const file = join(dir, 'clean.html')
+    await writeFile(file, cleanHtml)
+    const out = join(dir, 'out')
+    const r = run(['--file', file, '--preset', 'wp-elementor', '--output-dir', out])
+    assert.equal(r.status, 0, `exit was ${r.status}\nstderr: ${r.stderr}\nstdout: ${r.stdout}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.passed, true)
+    assert.equal(json.violationCount.high, 0)
+    assert.equal(json.violationCount.medium, 0)
+  })
+
+  await test('integration: dirty fragment exits 3 with violations', async () => {
+    const dir = join(TMPROOT, 'dirty')
+    await mkdir(dir, { recursive: true })
+    const file = join(dir, 'dirty.html')
+    await writeFile(file, dirtyHtml)
+    const out = join(dir, 'out')
+    const r = run(['--file', file, '--preset', 'wp-elementor', '--output-dir', out])
+    assert.equal(r.status, 3, `exit was ${r.status}\nstderr: ${r.stderr}\nstdout: ${r.stdout.slice(0, 500)}`)
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.passed, false)
+    assert.ok(json.violationCount.high >= 2, `expected >=2 high, got ${json.violationCount.high}`)
+    // Each violation must have the contract fields and a non-trivial candidateFix
+    for (const v of json.violations) {
+      assert.ok(v.group, 'group required')
+      assert.ok(v.id, 'id required')
+      assert.ok(v.location, 'location required')
+      assert.ok(v.issue, 'issue required')
+      assert.ok(v.candidateFix && v.candidateFix.length > 10, `candidateFix must be specific: ${v.candidateFix}`)
+      assert.ok(['high', 'medium', 'low'].includes(v.severity))
+    }
+  })
+
+  await test('integration: writes report.json + emits stdout JSON', async () => {
+    const dir = join(TMPROOT, 'report')
+    await mkdir(dir, { recursive: true })
+    const file = join(dir, 'x.html')
+    await writeFile(file, dirtyHtml)
+    const out = join(dir, 'out')
+    const r = run(['--file', file, '--preset', 'wp-elementor', '--output-dir', out])
+    assert.ok([0, 3].includes(r.status))
+    const reportPath = join(out, 'report.json')
+    const fileJson = JSON.parse(await readFile(reportPath, 'utf8'))
+    const stdoutJson = JSON.parse(r.stdout.trim())
+    // The two should be deeply equivalent
+    assert.equal(fileJson.violationCount.high, stdoutJson.violationCount.high)
+    assert.equal(fileJson.violationCount.medium, stdoutJson.violationCount.medium)
+    assert.equal(fileJson.violations.length, stdoutJson.violations.length)
+  })
+
+  await test('integration: cross-reference escalates correlated violations', async () => {
+    const dir = join(TMPROOT, 'xref')
+    await mkdir(dir, { recursive: true })
+    const file = join(dir, 'x.html')
+    // Has a button-type violation (medium); diff has high-severity button issue
+    await writeFile(file, '<section class="scope"><button class="cta">Click</button></section>')
+    const diffsPath = join(dir, 'compare.json')
+    await writeFile(diffsPath, JSON.stringify({
+      structuredDiffs: [
+        { area: 'button', severity: 'high', issue: 'background-color drift', live: '#d8112a', build: '#d82a11' },
+      ],
+    }))
+    const out = join(dir, 'out')
+    const r = run([
+      '--file', file,
+      '--preset', 'wp-elementor',
+      '--output-dir', out,
+      '--compare-diffs', diffsPath,
+    ])
+    const json = JSON.parse(r.stdout.trim())
+    const correlated = json.violations.find((v) => v.correlatedDiff)
+    assert.ok(correlated, 'expected at least one correlated violation')
+    assert.equal(correlated.severity, 'high')
+  })
+
+  await test('integration: low-only violations still pass (exit 0)', async () => {
+    // Build a fragment whose only violations are `low` (e.g. just opacity 0.5)
+    const dir = join(TMPROOT, 'low-only')
+    await mkdir(dir, { recursive: true })
+    const file = join(dir, 'x.html')
+    const html = `<style>
+      .scope { box-sizing: border-box; }
+      .scope .scope__title { font-size: 24px !important; }
+      .scope .x { opacity: 0.5; }
+    </style>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter&display=swap">
+    <link rel="preload" as="image" href="hero.jpg">
+    <section class="scope">
+      <h1 class="scope__title">Hi</h1>
+      <img src="hero.jpg" alt="hero" loading="eager">
+      <button type="button">Buy</button>
+    </section>`
+    await writeFile(file, html)
+    const out = join(dir, 'out')
+    const r = run(['--file', file, '--preset', 'wp-elementor', '--output-dir', out])
+    const json = JSON.parse(r.stdout.trim())
+    assert.equal(json.violationCount.high, 0)
+    assert.equal(json.violationCount.medium, 0)
+    assert.ok(json.violationCount.low >= 1, `expected >=1 low, got ${json.violationCount.low}`)
+    assert.equal(r.status, 0)
+    assert.equal(json.passed, true)
+  })
+
+  // Cleanup
+  await rm(TMPROOT, { recursive: true, force: true }).catch(() => {})
+}
+
+if (failed > 0) {
+  process.stdout.write(`\n${failed} failed, ${passed} passed\n`)
+  process.exit(1)
+}
+process.stdout.write(`\n${passed} passed\n`)
+process.exit(0)

package/templates/skills/sb-tweak/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: sb-tweak
+description: Edits a built HTML/Liquid fragment in place from a natural-language request (PT/EN) — locates the targeted element, applies a precise change (text, attribute, CSS rule, or inline style), optionally re-validates the render, and emits a summarized diff. Use when the user asks to 'tweak', 'ajustar', 'aumentar/diminuir', 'mudar/trocar', 'adicionar/remover' something on a previously delivered file, or when the SimilarBuild orchestrator needs a post-delivery edit pass.
+---
+
+# sb-tweak
+
+## Overview
+
+Post-delivery editor for files produced by `sb-build-wp` / `sb-build-shopify`. Takes a natural-language request like *"aumenta o título do hero pra 32px"* or *"change the hero image alt to 'AlphaInfuse hero'"* and applies a single, surgical edit to the file — without re-cloning the page.
+
+Three parts work together:
+
+1. **`lib/intent-parser.mjs`** turns the request (PT or EN) into a structured `{action, target, property, value, confidence}` intent. Pure function, no I/O.
+2. **`lib/element-locator.mjs`** uses cheerio + heuristics to find the element(s) the intent points at, scores them, and picks the application scope (text, attribute, CSS rule, inline style). Pure function, no I/O.
+3. **`scripts/tweak.mjs`** is the CLI: file I/O, applies the edit, optionally invokes `sb-validate-render`, emits a summarized diff via `lib/diff-summarizer.mjs`.
+
+The split is deliberate (pattern #11): the script handles **mechanical** work (parse, locate, apply, validate, diff). The LLM handles **semantic** work (interpret ambiguous requests, pick between candidates when scores are close, decide if the result looks right). When the parser's confidence is low or the locator returns multiple plausible candidates, the script exits with **code 4 (disambiguation needed)** and surfaces machine-readable candidates — it never guesses.
+
+This skill is **standalone** and **invocable directly by the user** — it is not part of the `/build-page`, `/build-site`, or `/clip-section` flow. A future V2 may wrap it in a `/tweak` slash command following the same orchestrator pattern as the others.
+
+## Inputs
+
+| Argument            | Required | Default | Notes                                                                                                  |
+| ------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `--file`            | yes      | —       | Path to the HTML/Liquid file. Edited in place unless `--output-path` is given.                         |
+| `--request`         | yes      | —       | Natural-language request in PT or EN, e.g. `"aumenta o título do hero pra 32px"`.                       |
+| `--target-selector` | no       | —       | Bypass the locator and apply the edit to this exact CSS selector. Used after a disambiguation round.   |
+| `--output-path`     | no       | —       | Write the edited file to this path instead of editing in place. Parent dirs are created.               |
+| `--validate`        | no       | `true`  | After editing, invoke `sb-validate-render` to confirm the layout still renders. Pass `--no-validate` to skip. |
+| `--preset`          | cond.    | —       | `wp-elementor` or `shopify-section`. **Required when `--validate` is true.**                           |
+| `--output-dir`      | cond.    | —       | Directory for `tweak.json` and (when validating) the validation artifacts. Required.                   |
+| `--dry-run`         | no       | `false` | Show the proposed change without writing it. The diff is computed but the file is not modified.        |
+
+## Output
+
+A single JSON object printed to stdout AND saved to `{output-dir}/tweak.json`:
+
+```json
+{
+  "file": "/abs/path/build.html",
+  "request": "aumenta o título do hero pra 32px",
+  "intent": {
+    "action": "increase",
+    "target": { "type": "heading", "qualifier": "hero" },
+    "property": "font-size",
+    "value": { "kind": "pixels", "raw": "32px", "parsed": 32 },
+    "confidence": 0.9,
+    "language": "pt"
+  },
+  "selector": ".hero .hero__title",
+  "changes": [
+    { "selector": ".hero .hero__title", "property": "font-size", "before": "27px", "after": "32px", "scope": "css-rule", "line": 87 }
+  ],
+  "diff": "Changed `.hero .hero__title` font-size: 27px → 32px (line 87)",
+  "validation": { "screenshot": "{output-dir}/screenshot.png", "passed": true, "warnings": [] },
+  "needsClarification": false,
+  "outputPath": "/abs/path/build.html",
+  "dryRun": false
+}
+```
+
+When the parser is unsure or the locator returns multiple plausible candidates:
+
+```json
+{
+  "needsClarification": true,
+  "reason": "multiple-candidates",
+  "candidates": [
+    { "selector": ".hero .hero__title", "snippet": "<h1 class=\"hero__title\">Welcome</h1>", "score": 0.85, "line": 42 },
+    { "selector": ".pricing__title",    "snippet": "<h2 class=\"pricing__title\">Plans</h2>", "score": 0.62, "line": 118 }
+  ],
+  "hint": "re-invoke with --target-selector \"<chosen-selector>\""
+}
+```
+
+## Dependencies
+
+The host project must have `cheerio` installed (the SimilarBuild installer handles it). When `--validate` is true, `sb-validate-render` and its own deps must be available. Node ≥ 20.
+
+## On Activation
+
+1. **Resolve inputs.** Collect `--file`, `--request`, `--output-dir`. Optional: `--target-selector`, `--output-path`, `--validate` / `--no-validate`, `--preset`, `--dry-run`.
+
+2. **Run the script.** From the project root:
+
+   ```bash
+   node {skill-root}/scripts/tweak.mjs \
+     --file "{built-file}" \
+     --request "{natural-language-request}" \
+     --output-dir "{output-dir}" \
+     [--target-selector "{selector}"] \
+     [--output-path "{new-path}"] \
+     [--no-validate] [--preset wp-elementor] [--dry-run]
+   ```
+
+   The script handles: file read, intent parse, element location, edit application (text / attribute / CSS rule / inline style), optional validate-render invocation, diff summarization, and persistence.
+
+3. **Branch on exit code.**
+   - `0` — `needsClarification: false`, edit applied (or dry-run preview produced). Show the diff.
+   - `4` — `needsClarification: true`. **Not an error.** Either intent confidence was low, language was unrecognized, or multiple candidates tied. Read the JSON, ask the user to disambiguate (or pick the top candidate yourself if the snippet makes it obvious), then re-invoke with `--target-selector "<chosen>"`.
+   - `3` — validate-render ran after the edit and reported failure. The script reverts the file and returns the validate-render error. Treat as escalation: show the user what broke and ask whether to retry with a different approach.
+   - `2` — invalid args. Fix the call.
+   - `1` — script error (missing dep, malformed file). Surface stderr to the user and stop.
+
+4. **Forward the JSON unchanged** to the caller. Downstream consumers (an orchestrator that wraps `sb-tweak`, the user reading the diff) read every field directly.
+
+## Idempotence
+
+Running the same request twice on the same file produces the same file. The second run reports `changes: []` and `diff: "no changes (already applied)"` — the script reads the current value before applying and skips when it already matches.
+
+## Failure modes
+
+| Symptom                                                         | Likely cause                                            | What to surface                                                                                          |
+| --------------------------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Exit 4, `reason: "low-confidence"`                              | Request couldn't be parsed (vague, unsupported lang)    | Ask the user to rephrase. Show `intent` so they see what was understood.                                 |
+| Exit 4, `reason: "multiple-candidates"`                         | Locator found ≥2 elements with similar scores           | Show the snippets; ask which one. Re-invoke with `--target-selector`.                                    |
+| Exit 4, `reason: "no-candidates"`                               | Target type not present in the file                     | Tell the user. Suggest checking the file (maybe the section was already removed) or rephrasing.          |
+| Exit 4, `reason: "language-unsupported"`                        | Request was not PT or EN                                | Tell the user only PT and EN are supported.                                                              |
+| Exit 3, validation failed                                       | Edit broke the render                                   | The file was reverted automatically. Show the validation warnings.                                       |
+| Exit 1, stderr mentions `cheerio`                               | Dependency not installed                                | Pass stderr verbatim. Suggest `npm i cheerio`.                                                           |
+| `changes: []`, `diff: "no changes (already applied)"`           | Idempotent re-run                                       | This is success. Tell the user the file was already in the requested state.                             |
+
+## Conventions
+
+- Bare paths (e.g. `scripts/tweak.mjs`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}` resolves to the project working directory.
+- Stderr is prefixed `[sb-tweak]`.
+- The script edits a single file (pattern #15: `--output-path` for single-file artifacts).

package/templates/skills/sb-tweak/references/tweak-patterns.md

@@ -0,0 +1,157 @@
+---
+name: tweak-patterns
+description: Catalog of common natural-language tweak requests in PT/EN with expected parsed intent, locator behavior, and edit application. Used by sb-tweak's intent-parser as a calibration reference and by humans reading the skill to understand what's supported.
+---
+
+# Tweak Patterns
+
+This is the canonical catalog of supported natural-language requests. The intent parser does not need to recognize every variation listed here — it only needs to find the **action verb**, **target type**, optional **qualifier**, optional **property**, and **value**. The patterns below show what the parser produces for each shape, so future contributors can extend the parser with confidence.
+
+## Action verbs
+
+| Verb (PT)                                             | Verb (EN)                                  | Action      |
+| ----------------------------------------------------- | ------------------------------------------ | ----------- |
+| aumenta, aumentar, maior, cresce                      | increase, enlarge, grow, bigger, larger    | `increase`  |
+| diminui, diminuir, menor, encolhe, reduz, reduzir     | decrease, reduce, shrink, smaller          | `decrease`  |
+| muda, mudar, troca, trocar, altera, alterar, seta, define, define-se | set, change, replace, update, swap | `set`       |
+| adiciona, adicionar, coloca, colocar, põe, insere, insira | add, insert, put                       | `add`       |
+| remove, remover, tira, tirar, apaga, apagar, deleta   | remove, delete, drop                       | `remove`    |
+
+## Target types
+
+| Words (PT)                                | Words (EN)                          | `target.type`     | Default property guess |
+| ----------------------------------------- | ----------------------------------- | ----------------- | ---------------------- |
+| título, titulo, h1, h2, h3, headline      | title, heading, headline, h1/h2/h3  | `heading`         | `font-size` (size verbs); `text` (set with quoted value) |
+| subtítulo, subtitulo                      | subtitle, subheading                | `subheading`      | same                   |
+| imagem, foto, img                         | image, picture, photo, img          | `image`           | `src` (set + URL); `alt` (set + quoted text) |
+| botão, botao, cta                         | button, btn, cta                    | `button`          | `text` (set + quoted); `background-color` (color verbs) |
+| texto, parágrafo, paragrafo, descrição    | text, paragraph, copy, description  | `text`            | `text` (set + quoted); `font-size` (size verbs) |
+| link, âncora                              | link, anchor                        | `link`            | `href` (set + URL); `text` (set + quoted) |
+| ícone, icone                              | icon                                | `icon`            | `src`                  |
+| fundo, background                         | background                          | `background`      | `background-color` / `background-image` |
+| seção, secao, section                     | section                             | `section`         | (qualifier-driven)     |
+
+## Qualifiers
+
+| Words (PT)                          | Words (EN)             | `target.qualifier` | Locator behavior                                    |
+| ----------------------------------- | ---------------------- | ------------------ | --------------------------------------------------- |
+| hero, principal                     | hero, main             | `hero`             | element has class containing "hero"; or has ancestor with "hero" class |
+| footer, rodapé, rodape              | footer                 | `footer`           | element inside `<footer>` or class containing "footer" |
+| header, topo, cabeçalho, cabecalho  | header, top            | `header`           | inside `<header>` / class containing "header"       |
+| primeiro, primeira, 1º, 1°, 1a, 1o  | first, 1st             | `first`            | first match in document order                       |
+| segundo, segunda, 2º, 2°, 2a, 2o    | second, 2nd            | `second`           | second match                                        |
+| terceiro, terceira, 3º, 3°          | third, 3rd             | `third`            | third match                                         |
+| último, ultima, last                | last, final            | `last`             | last match                                          |
+
+When no qualifier is present and there's only one match for the target type, the locator picks it with high confidence. When there are multiple matches and no qualifier, the locator returns all candidates with `needsClarification: true`.
+
+## Property phrases
+
+| Phrase (PT)                                 | Phrase (EN)                          | `property`            |
+| ------------------------------------------- | ------------------------------------ | --------------------- |
+| tamanho, font-size                          | size, font size                      | `font-size`           |
+| cor (alone, on text/heading)                | color                                | `color`               |
+| cor de fundo, cor do fundo, background      | background color, bg color           | `background-color`    |
+| peso, font-weight                           | weight, font weight                  | `font-weight`         |
+| largura                                     | width                                | `width`               |
+| altura                                      | height                               | `height`              |
+| espaçamento, padding                        | padding, spacing                     | `padding`             |
+| margem, margin                              | margin                               | `margin`              |
+| alt, descrição alt                          | alt, alt text                        | `alt` (HTML attribute)|
+| src, fonte                                  | src, source                          | `src` (HTML attribute)|
+| href, link                                  | href, link                           | `href` (HTML attribute)|
+| texto                                       | text, content, copy                  | `text` (DOM text)     |
+
+## Value extraction
+
+| Pattern                                             | `value.kind`  | Example                                       |
+| --------------------------------------------------- | ------------- | --------------------------------------------- |
+| `\d+(\.\d+)?\s*px`                                  | `pixels`      | `32px`, `1.5px`                               |
+| `\d+(\.\d+)?\s*(rem\|em\|%\|vw\|vh)`                | `length`      | `2rem`, `100%`                                |
+| `\d+(\.\d+)?` (no unit, after size verb)            | `pixels`      | `32` → `32px` (when context implies size)     |
+| `#[0-9a-f]{3,8}`                                    | `color`       | `#fff`, `#1a2b3c`                             |
+| `rgb(...)`, `rgba(...)`, `hsl(...)`                 | `color`       | `rgb(255,0,0)`                                |
+| color names (red, blue, green, white, black, …)     | `color`       | `red`                                         |
+| `'...'` or `"..."`                                  | `text`        | `"AlphaInfuse hero"`                          |
+| `https?://...`                                      | `url`         | `https://cdn.example.com/img.png`             |
+| `\d+(\.\d+)?` bare                                  | `number`      | `32`, `0.85`                                  |
+
+## Examples
+
+Each row shows: request → produced intent (key fields) → locator behavior → edit applied.
+
+### Sizing (PT)
+
+> **"aumenta o título do hero pra 32px"**
+- intent: `{action: 'increase', target: {type: 'heading', qualifier: 'hero'}, property: 'font-size', value: {kind: 'pixels', parsed: 32}}`
+- locator: finds `h1.hero__title` (or whatever heading is inside the hero scope) → CSS rule scope.
+- edit: rewrites the `font-size` declaration of the matching CSS rule from `27px` (or whatever) to `32px`.
+
+> **"diminui o subtítulo para 14px"**
+- intent: `{action: 'decrease', target: {type: 'subheading'}, property: 'font-size', value: {kind: 'pixels', parsed: 14}}`
+- locator: looks for `h2`/`h3` or class containing `subtitle`/`subheading`.
+
+### Sizing (EN)
+
+> **"increase the hero title to 32px"** — same as the PT version above.
+
+> **"shrink the button text to 16px"**
+- intent: `{action: 'decrease', target: {type: 'button'}, property: 'font-size', value: {kind: 'pixels', parsed: 16}}`
+
+### Color (PT)
+
+> **"muda a cor do botão pra #fff"**
+- intent: `{action: 'set', target: {type: 'button'}, property: 'color', value: {kind: 'color', parsed: '#fff'}}`
+- Note: ambiguous between text color and background — defaults to `color`. User can say "cor de fundo" for the bg variant.
+
+> **"troca a cor de fundo do hero para #1a1a1a"**
+- intent: `{action: 'set', target: {type: 'section', qualifier: 'hero'}, property: 'background-color', value: {kind: 'color', parsed: '#1a1a1a'}}`
+
+### Text content (PT)
+
+> **'troca o título do hero para "Welcome back"'**
+- intent: `{action: 'set', target: {type: 'heading', qualifier: 'hero'}, property: 'text', value: {kind: 'text', parsed: 'Welcome back'}}`
+- edit: cheerio `.text("Welcome back")` on the located `<h1>`.
+
+### Attribute (EN)
+
+> **'set the hero image alt to "AlphaInfuse hero shot"'**
+- intent: `{action: 'set', target: {type: 'image', qualifier: 'hero'}, property: 'alt', value: {kind: 'text', parsed: 'AlphaInfuse hero shot'}}`
+- edit: `.attr('alt', 'AlphaInfuse hero shot')`.
+
+> **"change the hero image src to https://cdn.example.com/new.png"**
+- intent: `{action: 'set', target: {type: 'image', qualifier: 'hero'}, property: 'src', value: {kind: 'url', parsed: '...'}}`
+
+### Add / Remove
+
+> **'adiciona alt="Logo" na primeira imagem'**
+- intent: `{action: 'add', target: {type: 'image', qualifier: 'first'}, property: 'alt', value: {kind: 'text', parsed: 'Logo'}}`
+- edit: `.attr('alt', 'Logo')` (add and set are the same when the attr is missing).
+
+> **"remove the second button"**
+- intent: `{action: 'remove', target: {type: 'button', qualifier: 'second'}, value: null}`
+- edit: cheerio `.remove()` on the matched element.
+
+## Ambiguity rules
+
+The parser's confidence drops below `0.7` (which exits with code 4) when:
+
+- The action verb is not recognized (e.g. "tweak the hero" — no specific verb).
+- The target type is not recognized (e.g. "increase the thing").
+- A `set` action has no value, or a sizing verb has neither a number nor a unit.
+- The language is not PT or EN (no recognized words from either dictionary).
+
+The locator returns multiple candidates (also exit 4) when:
+
+- Two or more elements match the target type and have similar scores (top-2 within `0.15`).
+- There's no qualifier and there are ≥ 2 matches of the target type.
+
+In both cases, the script emits machine-readable candidates and the orchestrator/user picks one before re-invoking with `--target-selector`.
+
+## Out of scope (V1)
+
+- **Animations / transitions.** The parser does not recognize "anima isso" or "fade in".
+- **Multi-element edits in one request.** "muda o título e a imagem" is two separate tweaks.
+- **Layout restructuring.** "move the button below the title" is not an edit, it's a recompose. Re-run the build flow instead.
+- **Cross-file references.** "use the hero from page X" — the skill operates on a single file.
+- **CSS rules that don't exist yet.** If the property has no rule and no inline style, the script falls back to inline-style; it does not synthesize new CSS rules in the `<style>` block (V2 enhancement).