aem-eds-kit 0.4.48 → 0.4.57

package/README.md

@@ -12,13 +12,23 @@
 
 **Turn a design into an EDS block** - JS, CSS and a Universal Editor model - without leaving your terminal.
 
-`aem-eds-kit` gives you the `eds` command. Paste a design link - a Figma URL, or a Framer / Google Stitch page - and it hands the design to the AI agent you already use (Claude Code, Cursor or Codex), which writes production-ready code straight into your repo. Figma is read through MCP or the REST API; Framer and Stitch render real HTML, so they're **scraped with headless Chromium** (no token needed). It also scaffolds blocks, previews them in your browser, and keeps your project healthy with a few quick audits.
+`aem-eds-kit` gives you the `eds` command. Paste a design link (a Figma frame, a Framer or Google Stitch page, or any web page) and it hands the design to the AI agent you already use: Claude Code, Cursor or Codex, or a local model through Ollama / oMLX. The agent writes the block straight into your repo. Figma is read through its REST API or MCP; web pages are **scraped with headless Chromium**, no token needed.
 
-It lives next to `@adobe/aem-cli` (your local dev server) and handles everything around it.
+It lives next to `@adobe/aem-cli` (your `aem up` dev server) and handles everything around it: new projects, blocks, migration from AEM, previews, checks and publishing.
+
+```bash
+npm install -g aem-eds-kit
+eds new my-site && cd my-site                     # the latest Adobe boilerplate
+eds block from-design "<design link>" --name hero  # design → blocks/hero/
+eds block preview hero                            # see it in the browser
+```
+
+**Contents:** [What it does](#what-it-does) · [Install](#install) · [Try it](#try-it-in-30-seconds-no-figma-account-no-token) · [Interactive mode](#interactive-mode) · [Commands](#commands) · [Figma](#how-figma-integration-works) · [Local models](#local-models-ollama-omlx) · [Configuration](#configuration) · [Roadmap](#roadmap)
 
 ## What it does
 
-- **Blocks from a design.** A Figma frame (REST or MCP), a Framer / Google Stitch page (scraped with headless Chromium) or a local PNG / SVG export becomes `blocks/<name>/`: JS, CSS, a Universal Editor model and a preview mock. Works with Claude Code, Cursor and Codex. Content Fragment blocks (`--source cf` / `mixed`) get an async, fetching `decorate()`.
+- **A new project in one command.** `eds new` clones Adobe's latest boilerplate (Document Authoring, Universal Editor or Commerce) without a GitHub login, and `eds init` sets it up for your authoring model.
+- **Blocks from a design.** A Figma frame (REST or MCP), a Framer / Google Stitch page or any other web page (scraped with headless Chromium), or a local PNG / SVG export becomes `blocks/<name>/`: JS, CSS, a Universal Editor model and a preview mock. Works with Claude Code, Cursor and Codex, or a [local model](#local-models-ollama-omlx) through Ollama or oMLX. Content Fragment blocks (`--source cf` / `mixed`) get an async, fetching `decorate()`.
 - **Migration from AEM.** `eds migrate component` turns a classic component's dialog into a block and a UE model, with no agent involved. It handles AEM as a Cloud Service proxy components (via `sling:resourceSuperType`, e.g. onto Core Components) and AEM 6.5 Classic UI `dialog.xml` files.
 - **Within Figma's limits.** One REST or MCP call per block, then a cache. REST calls are paced per minute across parallel runs. A rate limit stops with the reset time; it never spends your MCP budget behind your back. [The limits](#how-figma-integration-works).
 - **QA before review.** `eds block test` does visual regression on the block itself, plus a design↔render diff. `eds block check` covers content and a11y, including preview mocks nested deeper than real EDS markup. There are also `doctor`, loading and security audits.
@@ -26,6 +36,17 @@ It lives next to `@adobe/aem-cli` (your local dev server) and handles everything
 
 Proof: the whole example screen (11 blocks) was generated from a scraped page and from Figma exports, screenshotted next to the design, and 163 + 22 real AEM components were migrated. See the [end-to-end test](https://piotrgodycki.github.io/aem-eds-kit/e2e-example.html).
 
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/design-vs-block.webp" alt="A Google Stitch hero design next to the EDS block eds generated from it: same layout, type scale, colours and buttons, with placeholder copy" width="100%"></p>
+
+<details>
+<summary><strong>The whole screen</strong>: design vs. the 11 generated blocks</summary>
+
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/design-vs-page.webp" alt="The full example page design next to the page built from 11 generated EDS blocks" width="100%"></p>
+
+Generated blocks ship with placeholder copy (and empty image slots) until authors fill them in; the layout, spacing, type and colours come from the design.
+
+</details>
+
 ## Install
 
 ```bash
@@ -70,7 +91,7 @@ eds block from-design "<figma-url>" --name hero
 
 ## Try it in 30 seconds (no Figma account, no token)
 
-From inside an EDS project (or spin a throwaway one up with `eds sandbox new demo`):
+From inside an EDS project (or clone a fresh one with `eds new demo && cd demo`):
 
 ```bash
 eds block from-design --sample --name hero --dry-run   # see the prompt - zero setup
@@ -78,19 +99,32 @@ eds block from-design --sample --name hero             # generate it with your A
 eds block preview hero                                  # see it live in the browser
 ```
 
-`--sample` uses a **bundled "Kiri Bloom" hero design**, read straight from disk - **no Figma token, no MCP call, no network**. (`--dry-run` needs no AI agent either - it just prints the prompt.)
+`--sample` uses the **hero of the project's example design**, bundled as an SVG and read straight from disk - **no Figma token, no MCP call, no network**. (`--dry-run` needs no AI agent either - it just prints the prompt.)
+
+A real run (Claude Code): the agent's live log, a verification pass over the files it wrote, then a menu to refine, preview or finish.
+
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/cli-fd.png" alt="Terminal: eds block from-design --sample (the example hero), showing the design source, the agent's live log, the files it wrote, a verification table and the refine / preview / finish menu" width="760"></p>
+
+`eds block preview` serves the block at the design's own widths, with live reload:
+
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/block-preview.webp" alt="Browser: the eds block preview harness showing the hero block at 1440 px with a breakpoint dropdown" width="100%"></p>
 
-Ready for the real thing? Point it at the official **Kiri Bloom AEM EDS Kit** training file in Figma:
+Ready for the real thing? The same example design exists as a page you can build every block from, and as a Figma file:
 
 ```bash
-eds block from-design \
-  "https://www.figma.com/design/vwlEKTFhcrlwuA8dRgN5SD/Kiri-Bloom-AEM-EDS-Kit-Example?node-id=0-1" \
-  --name hero
+# the example page (11 sections: hero, stats, cards, …) - read like a Framer / Stitch page
+eds block from-design "https://piotrgodycki.github.io/aem-eds-kit/example/" --name cards
 ```
 
+The Figma version is built by the plugin in [`examples/figma-kit`](https://github.com/piotrgodycki/aem-eds-kit/tree/main/examples/figma-kit) (run it once in Figma desktop); then pass any of its frame links.
+
 ## Interactive mode
 
-Run `eds` with no command and it opens an **interactive menu** that stays open between actions (arrows to move, Enter to run, **Esc** to go back - or to quit from the menu itself; Ctrl+C quits anywhere). It walks you through every feature (set up the project, generate a block from a design, migrate a classic AEM component, scaffold, create a block, add an integration, preview, Admin API, audits, Figma setup). Most commands are also interactive on their own when you omit arguments - e.g. `eds init`, `eds block from-design` (wizard), `eds migrate component`, `eds scaffold`, `eds integrate`, `eds preview`. Flags and subcommands still work for CI / power users.
+Run `eds` with no command and it opens an **interactive menu** that stays open between actions (arrows to move, Enter to run, **Esc** to go back - or to quit from the menu itself; Ctrl+C quits anywhere). It walks you through every feature: new project (clone the boilerplate), set up project, page template, sandbox repo, block from design, migrate component, scaffold UE, empty block, integration, model fields, analytics, structured data, Universal Editor, preview block, pages (preview / publish), audits and Figma MCP.
+
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/cli-menu.png" alt="Terminal: the eds interactive menu with Block from design selected" width="560"></p>
+
+ Most commands are also interactive on their own when you omit arguments - e.g. `eds init`, `eds block from-design` (wizard), `eds migrate component`, `eds scaffold`, `eds integrate`, `eds preview`. Flags and subcommands still work for CI / power users.
 
 A full A-Z reference of every command lives on the docs page: **https://piotrgodycki.github.io/aem-eds-kit/docs.html**
 
@@ -99,6 +133,9 @@ A full A-Z reference of every command lives on the docs page: **https://piotrgod
 ```bash
 eds                              # interactive menu
 
+# Start from the latest boilerplate (DA, Universal Editor or Commerce)
+eds new my-site
+
 # Just cloned an EDS boilerplate? Set it up for your authoring model
 eds init
 
@@ -131,7 +168,8 @@ The full path, command by command. This example targets **DA (da.live)** authori
 # 1. Install the CLI
 npm i -g aem-eds-kit
 
-# 2. Set up the project (pick DA, enter org + site). Writes fstab + CI + naming.
+# 2. Clone the latest boilerplate, then set it up (pick DA, enter org + site)
+eds new my-site && cd my-site
 eds init --authoring da --org my-org --site my-site
 
 # 3. Scaffold the Universal Editor config + helper functions
@@ -160,6 +198,32 @@ Every step is also interactive when you omit the flags - run `eds` for the menu.
 
 ## Commands
 
+### `eds new [dir]`
+
+Clone the **current EDS boilerplate** into a local folder. No GitHub auth needed, and nothing is created on GitHub (for a repo on GitHub, see [`eds sandbox`](#eds-sandbox)). Choose Document Authoring / DA (`adobe/aem-boilerplate`), Universal Editor / crosswalk (`adobe-rnd/aem-boilerplate-xwalk`), the Adobe Commerce storefront (`hlxsites/aem-boilerplate-commerce`), or any repo or git URL.
+
+By default the copy starts a **fresh git history**, with one initial commit naming the boilerplate commit it came from. `--keep-history` keeps the boilerplate's history with its remote named `upstream`, so `git pull upstream main` brings in later boilerplate changes. It refuses a folder that isn't empty, then offers `npm install` and `eds init`, with Universal Editor preselected for the crosswalk boilerplate.
+
+```bash
+eds new                                        # guided
+eds new my-site --yes                          # DA boilerplate, fresh history
+eds new my-site --ue --keep-history            # crosswalk, with an upstream remote
+eds new shop --boilerplate commerce --install
+eds new my-site --remote git@github.com:me/my-site.git
+```
+
+| Flag | Description |
+|---|---|
+| `--boilerplate <repo>` | `da` \| `ue` \| `commerce`, `owner/repo` on GitHub, or any git URL / path |
+| `--ue` | The crosswalk / Universal Editor boilerplate |
+| `--ref <ref>` | Branch or tag to clone |
+| `--keep-history` | Keep the boilerplate's history (remote renamed to `upstream`) |
+| `--remote <url>` | Set `origin` to your own repo |
+| `--install` | Run `npm install` after cloning |
+| `--yes` | Skip the guided prompts |
+
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/cli-new-picker.png" alt="Terminal: eds new asking for a folder and offering the DA, Universal Editor and Commerce boilerplates" width="660"></p>
+
 ### `eds init`
 
 Adapt a freshly cloned EDS boilerplate to your setup in one interactive wizard. Pick the authoring model - **Universal Editor (crosswalk), DA (da.live), Google Drive or SharePoint** - and `eds` sets the project name (`package.json` + boilerplate placeholders), writes `fstab.yaml` **only when the model needs it** (UE/crosswalk doesn't), scaffolds the crosswalk config + `paths.json` for UE, optionally adds the CI workflow, then walks the **external steps** (AEM Code Sync app, content-source share, Sidekick) as a clickable checklist.
@@ -171,15 +235,18 @@ By default it also writes, out of the box:
 
 Opt out with `--no-env` / `--no-xwalk`, or (re)generate either later with `eds scaffold env` / `eds scaffold xwalk`.
 
+**Non-interactive (`--yes`).** The project name defaults to the folder name (or `package.json`'s, unless that's still the boilerplate's own). The authoring model is detected from the `fstab.yaml` mountpoint (an AEM author → Universal Editor, `content.da.live` → DA, Google Drive, SharePoint) or a crosswalk `paths.json`, and preselected in the interactive picker. When it can't be told (the DA boilerplate ships no `fstab.yaml`), `--yes` stops with exit 1 and asks for `--authoring`.
+
 ```bash
 eds init                                           # interactive
+eds init --yes                                     # detect everything (e.g. right after `eds new --ue`)
 eds init --name my-site --authoring da --org my-org --site my-site --yes
 ```
 
 | Flag | Description |
 |---|---|
 | `--name <name>` | Project name (kebab-case) |
-| `--authoring <model>` | `ue` \| `da` \| `gdrive` \| `sharepoint` |
+| `--authoring <model>` | `ue` \| `da` \| `gdrive` \| `sharepoint` (else detected from `fstab.yaml` / `paths.json`) |
 | `--mountpoint <url>` | Content source URL (document models) |
 | `--org <org>` / `--site <site>` | DA org / site (`--authoring da`) |
 | `--no-ci` | Skip the GitHub Actions workflow |
@@ -216,18 +283,21 @@ Spin up and tear down **disposable EDS sandbox repos** on GitHub - a rapid, thro
 eds sandbox login                # authorize GitHub (device flow or token)
 eds sandbox new my-test          # guided: boilerplate, visibility, Code Sync, eds init
 eds sandbox new my-test --ue --private --yes
+eds sandbox new shop --boilerplate hlxsites/aem-boilerplate-commerce   # any template repo
 eds sandbox list                 # your sandboxes (tagged eds-sandbox) + preview URLs
 eds sandbox rm my-test           # delete it (with confirmation)
 ```
 
-`sandbox new` creates the repo from a boilerplate (Document Authoring `adobe/aem-boilerplate` or Universal Editor `adobe/aem-boilerplate-xwalk`) via the GitHub API, clones it, tags it `eds-sandbox`, then walks you through opening the AEM Code Sync install page and running `eds init`. The preview URL is `https://main--<repo>--<owner>.aem.page/`.
+`sandbox new` creates the repo from a boilerplate (Document Authoring `adobe/aem-boilerplate`, Universal Editor `adobe-rnd/aem-boilerplate-xwalk`, or any template repo with `--boilerplate <owner/repo>`) via the GitHub API, clones it, tags it `eds-sandbox`, then walks you through opening the AEM Code Sync install page and running `eds init`. The preview URL is `https://main--<repo>--<owner>.aem.page/`.
 
 Sandboxes are **throwaway test repos** - stand one up to debug or try an integration, then delete it; they work fine on a personal account. Two safety guarantees:
 
 - **Never overwrites an existing repo.** `sandbox new` checks first and refuses if `<owner>/<name>` already exists (and the GitHub template API never clobbers either way).
 - **Least privilege.** Scope the token to just your sandboxes - a fine-grained token limited to one repo, or a dedicated sandbox org used via `--org`. `eds sandbox login` links you straight to the token page with the minimal permissions. See the [Secure GitHub sandboxes guide](https://piotrgodycki.github.io/aem-eds-kit/secure-github-sandboxes.html).
 
-The token is stored owner-only (mode `0600`) in `~/.eds/github.json`; `eds sandbox logout` removes it. `list` only ever shows `eds-sandbox` repos and `rm` deletes only the named repo, with confirmation.
+The token is stored owner-only (mode `0600`) in `~/.eds/github.json`; `eds sandbox logout` removes it. `list` only ever shows `eds-sandbox` repos and `rm` deletes only the named repo (under `--org <org>` when it lives in an org), with confirmation.
+
+Just want the code on your machine, no GitHub repo? Use [`eds new`](#eds-new-dir).
 
 ### `eds migrate component [dir]`
 
@@ -244,6 +314,8 @@ eds migrate component ./ui.apps/.../apps/wknd/components/teaser \
   --super-root ../aem-core-wcm-components/content/src/content/jcr_root   # proxy → Core Component dialog
 ```
 
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/cli-mig.png" alt="Terminal: eds migrate component on the WKND teaser proxy component; the dialog is inherited from the Core Components teaser and its 13 fields are mapped to Universal Editor field types" width="760"></p>
+
 Dialogs map cleanly because Granite's `sling:resourceType` set is finite. The most faithful CSS actually comes from the **rendered page** (resolves LESS vars + cascade) - that capture lands in a later phase; for now the clientlib source gets you most of the way.
 
 ### `eds track block <name>`
@@ -306,9 +378,9 @@ The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definiti
 
 ### `eds block from-design [design-url]`
 
-Translates a design - **a Figma URL, a Framer / Google Stitch page, or a local SVG/PNG export** - into an EDS block. Run with **no URL** for a step-by-step wizard (design source, name, link, content source, UE model, screenshot, run mode). It builds a prompt with EDS conventions + your project's design tokens and hands it to your AI agent (Claude Code, Cursor, or Codex). *(This was `from-figma` before it went design-agnostic; Figma is the most battle-tested source and stays pixel-perfect.)*
+Translates a design - **a Figma URL, a Framer / Google Stitch page, or a local SVG/PNG export** - into an EDS block. Run with **no URL** for a step-by-step wizard (design source, name, link, content source, UE model, screenshot, run mode). It builds a prompt with EDS conventions + your project's design tokens and hands it to your AI agent (Claude Code, Cursor or Codex, or a [local model](#local-models-ollama-omlx)). *(This was `from-figma` before it went design-agnostic; Figma is the most battle-tested source and stays pixel-perfect.)*
 
-**Figma vs. web sources.** Figma paints to a WebGL canvas, so it's read through the **REST API** (with a token) or **MCP**. Framer and Google Stitch render **real HTML**, so `eds` **scrapes** them with headless Chromium — reading computed layout, typography, colours and geometry straight off the page (no token, no MCP). Canva and Sketch are canvas/image-based and aren't scrapeable — export a frame and pass it as a local SVG/PNG. The provider is detected from the URL host, or set with `--provider`.
+**Figma vs. web sources.** Figma paints to a WebGL canvas, so it's read through the **REST API** (with a token) or **MCP**. Framer, Google Stitch and **any other web page** (a live site you're rebuilding, an HTML mock-up) render **real HTML**, so `eds` **scrapes** them with headless Chromium — reading computed layout, typography, colours and geometry straight off the page (no token, no MCP). On a page with several sections, the block is built from the one matching `--name`: try `eds block from-design https://piotrgodycki.github.io/aem-eds-kit/example/ --name cards`. Canva and Sketch are canvas/image-based and aren't scrapeable — export a frame and pass it as a local SVG/PNG. The provider is detected from the URL (Figma, Framer, Stitch, else a web page), or set with `--provider`.
 
 **Gated sources (`--auth`).** A Google Stitch project (and a private Framer page) sits behind a login, so an anonymous scrape only sees the sign-in shell. Pass `--auth` and `eds` opens a **headed** browser once — you log in by hand, it saves the session, and every later scrape reuses it. The session (cookies/localStorage) is stored owner-only under `~/.eds/auth/<provider>.json`; re-login with `--auth-refresh`. (The saved session is a secret — it's never written to the repo.)
 
@@ -340,18 +412,20 @@ eds block from-design                               # interactive wizard
 eds block from-design "<figma-url>" --name hero     # non-interactive (REST if a token is set, else MCP)
 eds block from-design "<framer-url>" --name hero    # Framer/Stitch → scraped with headless Chromium
 eds block from-design "<stitch-url>" --name hero --auth   # gated source → log in once, reuse the session
+eds block from-design "https://piotrgodycki.github.io/aem-eds-kit/example/" --name cards   # any web page, one section
 eds block from-design ./hero.svg --name hero        # from a local export (no network)
-eds block from-design --sample --name hero          # bundled Kiri Bloom sample (no token, no MCP)
+eds block from-design --sample --name hero          # bundled example hero (no token, no MCP)
 eds block from-design "<figma-url>" --dry-run       # just build the prompt
 ```
 
 | Flag | Description |
 |---|---|
 | `--name <name>` | Override the inferred block name |
-| `--provider <type>` | Design source: `figma` \| `framer` \| `stitch` (else detected from the URL) |
+| `--provider <type>` | Design source: `figma` \| `framer` \| `stitch` \| `web` (else detected from the URL) |
 | `--source <type>` | Content source: `document` \| `ue` \| `cf` \| `mixed` (`cf` / `mixed` default to the `sonnet` model) |
 | `--widths <list>` | Design frame widths for preview breakpoints (e.g. `390,768,1440`) |
-| `--agent <type>` | Force `claude` \| `cursor` \| `codex` \| `none` (a prompt too large for one argument reaches Cursor / Codex as its file) |
+| `--agent <type>` | Force `claude` \| `cursor` \| `codex` \| `ollama` \| `omlx` \| `local` \| `none` (a prompt too large for one argument reaches Cursor / Codex as its file; see [Local models](#local-models-ollama-omlx)) |
+| `--model <name>` | Model to run: a Claude alias / id, or a local model such as `qwen2.5-coder:14b` |
 | `--dry-run` | Build the prompt only |
 | `--no-ue-model` | Skip the Universal Editor model |
 | `--screenshot` | Add a screenshot MCP call for a pixel check (opt-in — costs a call) |
@@ -359,7 +433,7 @@ eds block from-design "<figma-url>" --dry-run       # just build the prompt
 | `--auth` | Scrape with a logged-in session (Framer/Stitch): log in once, reuse it |
 | `--auth-refresh` | Force a fresh scrape login even if a session is saved |
 | `--refresh` | Ignore the cached snapshot and re-fetch |
-| `--sample` | Use the bundled Kiri Bloom sample design (no URL, token or MCP) |
+| `--sample` | Use the bundled sample design, the example file's hero (no URL, token or MCP) |
 | `--serve` | Auto-start the live preview (non-interactive runs only) |
 | `--yes` | Skip confirmation prompts |
 
@@ -376,7 +450,7 @@ The generated block records the **design's frame widths** in its `.eds-meta.json
 ### `eds figma setup`
 
 Interactive wizard that:
-1. Detects installed AI agents (Claude Code, Cursor, Codex)
+1. Detects installed AI agents (Claude Code, Cursor, Codex) and running local model servers (Ollama, oMLX)
 2. Checks if Figma MCP is configured for your agent
 3. Shows install commands if not
 4. Saves preferences to `~/.eds/config.json`
@@ -403,6 +477,13 @@ eds block preview hero --widths 375,768,1280   # custom breakpoints
 eds block preview hero --port 9000 --no-open
 ```
 
+- A dropdown switches the block between breakpoints inside an `<iframe>`, so the block's media queries fire against the chosen width - a **width-honest** comparison that isn't distorted by your monitor size.
+- Breakpoints come from the block's `.eds-meta.json` (`breakpoints`, marking which widths have a real Figma frame → pixel-perfect) and fall back to `375 / 768 / 1280` or `--widths`.
+- If the block has a `.eds-meta.json` with a Figma source, an **Open in Figma** link is shown.
+- Authored sample content is read from `blocks/<name>/_<name>.preview.html` if present; otherwise a placeholder is used (and the chrome tells you to add one).
+
+> Not to be confused with `eds preview [paths...]` (lower down), which previews **pages** via the AEM Admin API.
+
 ### `eds block test [name]` · `eds block check [name]`
 
 Two deterministic QA passes over a block's **rendered** DOM (no agent) - one block, or **all** of them when you omit the name. Both render the block in headless Chromium (Playwright), so install the browser once: `npx playwright install chromium`. Wire them into CI next to the audits - both exit non-zero on failure.
@@ -417,6 +498,11 @@ eds block test hero --design           # rendered block vs its Figma design imag
 eds block test --threshold 0.02        # allow 2% changed pixels
 ```
 
+A CSS change that moved the hero's buttons and text, caught at 1440 px, with the diff image it wrote:
+
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/cli-test.png" alt="Terminal: eds block test hero reporting 2.48% changed pixels at 1440px and the diff PNG path" width="760"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/visual-diff.webp" alt="Diff image: the changed pixels of the hero block highlighted in red and yellow" width="760"></p>
+
 | Flag | Description |
 |---|---|
 | `--update` | (Re)write baseline screenshots instead of comparing |
@@ -433,6 +519,8 @@ eds block check hero                   # one block
 eds block check --strict               # fail on warnings too
 ```
 
+<p align="center"><img src="https://raw.githubusercontent.com/piotrgodycki/aem-eds-kit/main/.github/assets/readme/cli-check.png" alt="Terminal: eds block check hero warning that the preview mock nests cell content one div deeper than EDS markup" width="760"></p>
+
 | Flag | Description |
 |---|---|
 | `--strict` | Fail on warnings too, not just errors |
@@ -473,28 +561,23 @@ eds integrate                  # interactive
 eds integrate gtm              # gtm · ga4 · chat · cookiebot · custom
 ```
 
-- A dropdown switches the block between breakpoints inside an `<iframe>`, so the block's media queries fire against the chosen width - a **width-honest** comparison that isn't distorted by your monitor size.
-- Breakpoints come from the block's `.eds-meta.json` (`breakpoints`, marking which widths have a real Figma frame → pixel-perfect) and fall back to `375 / 768 / 1280` or `--widths`.
-- If the block has a `.eds-meta.json` with a Figma source, an **Open in Figma** link is shown.
-- Authored sample content is read from `blocks/<name>/_<name>.preview.html` if present; otherwise a placeholder is used (and the chrome tells you to add one).
-
-> Not to be confused with `eds preview <paths...>` (lower down), which previews **pages** via the AEM Admin API.
+### `eds preview [paths...]`
 
-### `eds preview <path...>`
-
-Preview pages via the AEM Admin API (`admin.hlx.page`).
+Preview pages via the AEM Admin API (`admin.hlx.page`). Run it with no paths for a wizard (pick the action, the paths and the org / site / ref).
 
 ```bash
+eds preview                      # wizard
 eds preview /index
 eds preview /blog/my-post /about
 eds preview /index --org my-org --site my-repo --ref main
 ```
 
-### `eds publish <path...>`
+### `eds publish [paths...]`
 
-Publish pages to live via the AEM Admin API.
+Publish pages to live via the AEM Admin API (a wizard when run with no paths).
 
 ```bash
+eds publish                      # wizard
 eds publish /index
 eds publish /blog/my-post /about
 ```
@@ -571,7 +654,8 @@ The design is fetched **once** into a cached snapshot, then the agent generates
                     ┌─ local SVG/PNG ─┐
                     ├─ cache hit ──────┤      design.json      ┌─────────────┐   block files
  design reference ──┼─ Figma REST ─────┼───→  (cached) ───────→│ Claude Code │ ───────────────→ repo
-   (url / file)     └─ Figma MCP ──────┘      snapshot          │ /Cursor/Codex│
+   (url / file)     ├─ web scrape ─────┤      snapshot          │ Cursor/Codex│
+                    └─ Figma MCP ──────┘                        │ Ollama/oMLX │
                         (1 call, agent dumps to cache)          └─────────────┘
 ```
 
@@ -587,6 +671,35 @@ The prompt includes:
 - Lighthouse performance requirements + a single structural self-verification pass
 - Output file structure
 
+## Local models (Ollama, oMLX)
+
+Keep designs and code on your machine: `eds block from-design` can run a local model instead of Claude Code / Cursor / Codex.
+
+```bash
+ollama pull qwen2.5-coder:14b && ollama serve          # or: omlx start  (Apple Silicon)
+eds block from-design "<framer-url>" --name hero --agent ollama
+eds block from-design ./hero.png --name hero --agent ollama --model qwen2.5vl:7b   # PNG → vision model
+eds block from-design ./hero.svg --name hero --agent omlx
+```
+
+| Agent | Server (default) | API |
+|---|---|---|
+| `ollama` | `http://127.0.0.1:11434` | native `/api/chat` (so `num_ctx` can be raised) |
+| `omlx` | `http://127.0.0.1:8000/v1` | OpenAI-compatible `/v1/chat/completions` |
+| `local` | `local.baseUrl` | any OpenAI-compatible server (LM Studio, llama.cpp, vLLM…) |
+
+- **No tools, so the CLI does the I/O.** A local model can't read files or call MCP. `eds` sends the whole prompt - a scraped page or Figma REST spec embedded, an SVG export inlined, a PNG / JPG attached as an image - and asks for every file in a `=== FILE: … ===` format. It then writes those files itself, **only inside `blocks/<name>/`**. The raw reply is kept in `tmp/eds-cli/local-reply-*.md`.
+- **Figma needs REST or an export.** A Figma link without a token would need MCP, which a local model can't call: set `FIGMA_TOKEN`, or export the frame as PNG/SVG.
+- **Model.** `--model`, else `local.model`, else a coder model the server has (`*coder*`, Codestral/Devstral, Qwen, DeepSeek…). A PNG/JPG design needs a vision model.
+- **Context.** A design prompt is ~20-40k tokens. Ollama is asked for `local.contextTokens` (default **32768**, raised automatically when the prompt needs more); for other servers set the context length on the server. `eds` warns when the prompt won't fit.
+- **Auto-detect.** With no CLI agent installed, `eds` uses a running Ollama or oMLX server. Refine passes work too: the model gets the block's current files and returns the changed ones.
+
+```json
+{ "agent": "ollama", "local": { "model": "qwen2.5-coder:14b", "contextTokens": 49152 } }
+```
+
+`local.baseUrl` points at a different host or port, and `local.apiKey` is sent as a bearer token for servers that want one.
+
 ## Configuration
 
 Priority: CLI flags → env vars → `.edsrc.json` (project) → `~/.eds/config.json` (global)
@@ -596,10 +709,11 @@ Priority: CLI flags → env vars → `.edsrc.json` (project) → `~/.eds/config.
 {
   "agent": "claude",
   "model": "haiku",
-  "figma": { "token": "figd_…", "restPerMinute": 10 }
+  "figma": { "token": "figd_…", "restPerMinute": 10 },
+  "local": { "model": "qwen2.5-coder:14b", "contextTokens": 49152 }
 }
 ```
-`model` sets the block-generation model (default: fastest / Haiku). `figma.token` (or the `FIGMA_TOKEN` env var) enables the REST fetch path — a Personal Access Token with scope `file_content:read`. Tokens are secrets; keep them out of the repo.
+`agent` picks the agent (`claude`, `cursor`, `codex`, `ollama`, `omlx`, `local`); `model` sets the block-generation model (default: fastest / Haiku). `local.*` configures a [local model](#local-models-ollama-omlx). `figma.token` (or the `FIGMA_TOKEN` env var) enables the REST fetch path — a Personal Access Token with scope `file_content:read`. Tokens are secrets; keep them out of the repo.
 
 `figma.restPerMinute` paces Figma REST calls across every `eds` run in the project (they share `tmp/eds-cli/figma-rest-calls.json`), so a batch of blocks waits for a free slot instead of hitting a 429. Default **10** (Tier 1, Dev / Full seat on Professional); use 15 on Organization, 20 on Enterprise. On Starter or with a View / Collab seat the cap is monthly (20), so pacing can't help there.
 
@@ -620,13 +734,13 @@ Priority: CLI flags → env vars → `.edsrc.json` (project) → `~/.eds/config.
 |---|---|
 | `--verbose` | Debug-level output |
 | `--quiet` | Errors only |
-| `--json` | Machine-readable JSON output |
+| `--json` | Machine-readable JSON output (`doctor`, `audit loading`, `audit security`, `block list`) |
 | `--no-color` | Disable colors (also respects `NO_COLOR` env) |
 
 ## Development
 
 ```bash
-git clone <repo-url> && cd eds-cli
+git clone https://github.com/piotrgodycki/aem-eds-kit.git && cd aem-eds-kit
 npm install
 ```
 
@@ -698,11 +812,21 @@ Tests use fixtures in `tests/fixtures/` - a sample EDS project and recorded Figm
 
 ## Roadmap
 
-- **Design sources** - Figma (REST/MCP), Framer and Google Stitch (headless-Chromium scrape) are wired; next is deepening the scrape extractor (multi-breakpoint capture, component/variant detection), a generic `eds setup` in place of `eds figma setup`, and an end-to-end run against a real Figma file ([EDS-020](https://github.com/piotrgodycki/aem-eds-kit/issues/20)). Canva/Sketch stay on the local-export path (canvas/image — not scrapeable).
-- **Migration** - dialogs (Touch UI and Classic UI) map deterministically today; next is HTL → `decorate()` and capturing CSS from the rendered page.
-- **Screenshot-to-block** - build a block from a plain image (harder: no structured layout/measurements, so pixel-perfect is tougher).
-- **Tokens & sync** - design variables → CSS custom properties, and incremental re-sync of an existing block (`--update`).
-- **Headless & CI** - a direct MCP client (no agent needed) for CI/CD, plus `eds lighthouse`, `eds rum` and `eds migrate page`.
+**Next**
+- **Previews that look like the design.** The preview gets the design's real copy and images, so it matches 1:1; the block itself still reads authored content.
+- **A self-check against the design.** Render the block, compare it with the Figma frame or the page, and fix what differs in a second pass.
+- **Every breakpoint.** Read the design at mobile, tablet and desktop widths, not just one.
+
+**Then**
+- **Whole screens in one go.** Every section of a frame or page becomes a block, plus the page that puts them together.
+- **Blocks that follow the design.** When the design changes, update the existing block instead of regenerating it.
+- **Design tokens for the project.** Figma Variables become the CSS custom properties in `styles.css`.
+
+**Later**
+- **Deeper AEM migration.** HTL logic ported to `decorate()`, CSS taken from the rendered page, whole pages migrated.
+- **Performance in the loop.** Lighthouse and real-user data (RUM) checked for every block.
+
+Something missing? [Open an issue](https://github.com/piotrgodycki/aem-eds-kit/issues): the roadmap follows what people need.
 
 ## Trademarks & affiliation