aem-eds-kit 0.4.33 → 0.4.54

package/README.md

@@ -5,15 +5,38 @@
 [![npm version](https://img.shields.io/npm/v/aem-eds-kit.svg)](https://www.npmjs.com/package/aem-eds-kit)
 [![npm downloads](https://img.shields.io/npm/dm/aem-eds-kit.svg)](https://www.npmjs.com/package/aem-eds-kit)
 [![CI](https://github.com/piotrgodycki/aem-eds-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/piotrgodycki/aem-eds-kit/actions/workflows/ci.yml)
-[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/piotrgodycki/aem-eds-kit/blob/main/LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
 
+**[Docs](https://piotrgodycki.github.io/aem-eds-kit/docs.html)** · **[Changelog](https://piotrgodycki.github.io/aem-eds-kit/changelog.html)** · **[End-to-end test](https://piotrgodycki.github.io/aem-eds-kit/e2e-example.html)** · **[GitHub](https://github.com/piotrgodycki/aem-eds-kit)** · **[Issues](https://github.com/piotrgodycki/aem-eds-kit/issues)**
+
 **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 URL, or a Framer / Google Stitch 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), 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.
 
 It lives next to `@adobe/aem-cli` (your local dev server) and handles everything around it.
 
+## 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, 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.
+- **An interactive menu that stays open.** Run `eds`, then use the arrows, Enter, and Esc to go back. Every command also runs non-interactively for CI.
+
+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
@@ -58,7 +81,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
@@ -68,6 +91,14 @@ eds block preview hero                                  # see it live in the bro
 
 `--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.)
 
+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 --name promo, 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:
 
 ```bash
@@ -78,7 +109,11 @@ eds block from-design \
 
 ## Interactive mode
 
-Run `eds` with no command and it opens an **interactive menu** that 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**
 
@@ -87,6 +122,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
 
@@ -119,7 +157,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
@@ -148,6 +187,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.
@@ -159,15 +224,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 |
@@ -204,18 +272,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]`
 
@@ -223,11 +294,17 @@ Start migrating a **classic AEM component** to EDS. Phase 1 is deterministic (no
 
 It also pulls the component's **clientlib CSS** off disk into the block's CSS when it can find one (auto-detected, or `--clientlib <dir>`): it honours `css.txt` ordering (and `#base=`), concatenates the `.css`, and flags any LESS/SCSS that needs a build. Treat it as a starting point - review the selectors and scope them under `.<block>`.
 
+**AEM as a Cloud Service and AEM 6.5.** A *proxy component* (the usual AEMaaCS setup: no dialog of its own, just `sling:resourceSuperType` pointing at a Core Component) inherits its parent's dialog. The parent is looked up in the component's own `jcr_root`, and in any folder passed with `--super-root` (e.g. a checkout of `adobe/aem-core-wcm-components`, `content/src/content/jcr_root`). Granite `include`s are resolved from disk the same way. A component with only a **Classic UI** dialog (`dialog.xml`, still found on AEM 6.5) is read from its ExtJS `xtype`s: `textfield`, `textarea`, `richtext`, `pathfield`, `numberfield`, `selection`, `smartimage`, `multifield` (incl. ACS `multifieldpanel`), `tabpanel` and `cqinclude`.
+
 ```bash
 eds migrate component /path/to/apps/myproject/components/hero
 eds migrate component ./components/hero --name hero --clientlib ./ui.apps/.../hero/clientlib --yes
+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>`
@@ -275,7 +352,7 @@ eds ue open / --org my-org --ref dev
 eds ue open /blog --url main--site--owner.aem.page --no-open
 ```
 
-Full workflow (proxy, `.env`, `xwalk.json`, editor deep link): [`docs/local-development.md`](docs/local-development.md).
+Full workflow (proxy, `.env`, `xwalk.json`, editor deep link): [`docs/local-development.md`](https://github.com/piotrgodycki/aem-eds-kit/blob/main/docs/local-development.md).
 
 ### `eds block create <name>`
 
@@ -286,11 +363,11 @@ eds block create hero-banner             # js + css + _hero-banner.json (UE mode
 eds block create hero-banner --no-ue-model   # skip the UE model
 ```
 
-The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definitions` / `models` / `filters`) with starter fields (title + heading-level select + rich text). Extend it from the **full catalog of all 17 Universal Editor field types** - see [`docs/universal-editor-fields.md`](docs/universal-editor-fields.md). `eds block from-design` picks the right field type per Figma layer automatically.
+The generated `_<name>.json` uses the EDS block-plugin (xwalk) format (`definitions` / `models` / `filters`) with starter fields (title + heading-level select + rich text). Extend it from the **full catalog of all 17 Universal Editor field types** - see [`docs/universal-editor-fields.md`](https://github.com/piotrgodycki/aem-eds-kit/blob/main/docs/universal-editor-fields.md). `eds block from-design` picks the right field type per Figma layer automatically.
 
 ### `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`.
 
@@ -301,12 +378,23 @@ Translates a design - **a Figma URL, a Framer / Google Stitch page, or a local S
 1. **Local file** — pass a path to an SVG/PNG export (`eds block from-design ./hero.svg`) → read from disk, no network.
 2. **Cache** — a snapshot already fetched for this design (`tmp/eds-cli/design-cache/`) is reused.
 3. **Web scrape (Framer / Stitch)** — the live page is rendered in headless Chromium and its computed layout/styles are extracted. Needs Playwright + a browser: `npx playwright install chromium`.
-4. **Figma REST** — if a Figma token is set, `eds` fetches the node itself and embeds a compact design spec. Separate, generous quota; **does not touch the MCP limit**.
+4. **Figma REST** — if a Figma token is set, `eds` fetches the node itself and embeds a compact design spec. Its own budget, separate from MCP (see the limits below); **does not spend MCP calls**.
 5. **Figma MCP** — fallback: the agent makes **one** `get_design_context` call and caches it.
 
 The agent then generates pixel-perfect code (JS + CSS) **and its Universal Editor model** by default, with lightweight **placeholders** for not-yet-authored content. You see a **live, colour-coded log** with per-phase timings. On success you get a **menu** — refine the block with another pass, open the live preview, or finish (preview is **opt-in**, never auto-launched).
 
-> **Figma MCP limits:** the Dev Mode MCP server is metered per plan (Starter / View / Collab seats: ~6–20 **tool calls a month**). `eds` uses **one** MCP call per block and caches it; set a Figma token to skip MCP entirely via REST. See [How Figma integration works](#how-figma-integration-works).
+> **Figma limits.** Figma meters both paths, and the limit follows the **plan that owns the file** (a Full seat elsewhere doesn't help a file in a Starter team).
+>
+> | | Starter | Professional | Organization | Enterprise |
+> |---|---|---|---|---|
+> | **REST** (Tier 1: file, nodes, image), Dev / Full seat | 20 / month | 10 / min | 15 / min | 20 / min |
+> | **REST**, View / Collab seat | 20 / month | 20 / month | 20 / month | 20 / month |
+> | **MCP**, Dev / Full seat | 20 / month | 200 / day, 10 / min | 200 / day, 15 / min | 600 / day, 20 / min |
+> | **MCP**, View / Collab seat | 20 / month | 20 / month | 20 / month | 20 / month |
+>
+> `eds` spends **one** call per block (REST `file nodes`, or MCP `get_design_context`) and caches it; `--design` adds one REST `image` call, `--screenshot` one MCP call. A REST 429 with a short `Retry-After` is waited out; a plan cap stops instead of spending MCP calls. A local PNG/SVG export uses no quota. Figma can change these numbers - see its [REST](https://developers.figma.com/docs/rest-api/rate-limits/) and [MCP](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/) pages.
+>
+> See [How Figma integration works](#how-figma-integration-works).
 
 ```bash
 eds block from-design                               # interactive wizard
@@ -322,9 +410,10 @@ eds block from-design "<figma-url>" --dry-run       # just build the prompt
 |---|---|
 | `--name <name>` | Override the inferred block name |
 | `--provider <type>` | Design source: `figma` \| `framer` \| `stitch` (else detected from the URL) |
-| `--source <type>` | Content source: `document` \| `ue` \| `cf` \| `mixed` |
+| `--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` |
+| `--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) |
@@ -349,7 +438,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`
@@ -376,11 +465,18 @@ 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.
 
-**`eds block test`** - **visual regression.** Screenshots each block at every breakpoint and diffs it (pixelmatch) against a committed baseline in `blocks/<name>/__snapshots__/`; it fails when the changed-pixel ratio crosses the threshold (default 1%) and writes the diff image to `tmp/eds-cli/visual-diff/`. `--update` (re)writes the baselines after an intended change. `--design` does a **design↔render** diff instead - the rendered block against its Figma design image (needs a Figma token and a Figma source in the block's `.eds-meta.json`).
+**`eds block test`** - **visual regression.** Screenshots each block (the block element only, not the empty viewport) at every breakpoint and diffs it (pixelmatch) against a committed baseline in `blocks/<name>/__snapshots__/`; it fails when the changed-pixel ratio crosses the threshold (default 1%) and writes the diff image to `tmp/eds-cli/visual-diff/`. `--update` (re)writes the baselines after an intended change. `--design` does a **design↔render** diff instead - the rendered block against its Figma design image (needs a Figma token and a Figma source in the block's `.eds-meta.json`).
 
 ```bash
 eds block test                         # all blocks vs committed baselines
@@ -390,6 +486,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 |
@@ -398,7 +499,7 @@ eds block test --threshold 0.02        # allow 2% changed pixels
 | `--widths <list>` | Breakpoint widths (e.g. `375,768,1280`) |
 | `--port <port>` | Port for the internal preview server (default `8788`) |
 
-**`eds block check`** - **content, link & a11y.** Renders each block (after `decorate()`) and flags missing image `alt`, missing image dimensions (CLS risk), links/buttons with no accessible name, empty `href`s and inline event handlers. Checks run at the widest breakpoint; it exits non-zero on any error, or on any warning with `--strict`.
+**`eds block check`** - **content, link & a11y.** Renders each block (after `decorate()`) and flags missing image `alt`, missing image dimensions (CLS risk), links/buttons with no accessible name, empty `href`s and inline event handlers. It also warns when the preview mock (`_<name>.preview.html`) nests cell content one `<div>` deeper than real EDS markup (row > cell > content), which leaves `decorate()` written against the mock misreading real content. Checks run at the widest breakpoint; it exits non-zero on any error, or on any warning with `--strict`.
 
 ```bash
 eds block check                        # all blocks
@@ -406,6 +507,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 |
@@ -446,28 +549,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).
+### `eds preview [paths...]`
 
-> Not to be confused with `eds preview <paths...>` (lower down), which previews **pages** via the AEM Admin API.
-
-### `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
 ```
@@ -544,12 +642,13 @@ 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)          └─────────────┘
 ```
 
 - **No token needed** for the MCP path — the agent uses its own Figma MCP connection and makes **one** `get_design_context` call per block (then caches it).
-- **Set a Figma token** (`FIGMA_TOKEN` or `figma.token`) to use the **REST** path instead: `eds` fetches the node over HTTPS and embeds a compact spec — a **separate, far larger quota** than the MCP limit, so it works comfortably on Starter / Collab seats.
+- **Set a Figma token** (`FIGMA_TOKEN` or `figma.token`) to use the **REST** path instead: `eds` fetches the node over HTTPS and embeds a compact spec, on REST's own budget instead of MCP's. With a Dev / Full seat on a paid plan that's a per-minute limit (10–20 / min) instead of MCP's daily cap; on Starter, or with a View / Collab seat, both are 20 calls a month.
 - **Local export** (`./file.svg|png`) reads straight from disk — zero network, best for vector/text-heavy frames.
 
 The prompt includes:
@@ -560,6 +659,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)
@@ -569,10 +697,13 @@ Priority: CLI flags → env vars → `.edsrc.json` (project) → `~/.eds/config.
 {
   "agent": "claude",
   "model": "haiku",
-  "figma": { "token": "figd_…" }
+  "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.
 
 **`.edsrc.json`** (project root, optional):
 ```json
@@ -591,13 +722,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
 ```
 
@@ -669,8 +800,9 @@ 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) and a generic `eds setup` in place of `eds figma setup`. Canva/Sketch stay on the local-export path (canvas/image — not scrapeable).
-- **Screenshot-to-block** - build a block from a plain image (harder: no structured layout/measurements, so pixel-perfect is tougher).
+- **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.
+- **Image-only designs** - a plain PNG/JPG already works (`from-design ./hero.png`, or a vision model with `--agent ollama --model qwen2.5vl:7b`); next is measuring it (no structured layout in a bitmap, so pixel-perfect is harder than from Figma or a scraped page).
 - **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`.
 
@@ -682,4 +814,4 @@ Adobe, AEM, Edge Delivery Services and Universal Editor are trademarks of Adobe
 
 ## License
 
-MIT - see [LICENSE](LICENSE).
+MIT - see [LICENSE](https://github.com/piotrgodycki/aem-eds-kit/blob/main/LICENSE).