app-builder

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

# app-builder — intent → model-driven app

> ⚠️ **Preview.** This skill is in preview — its App Spec shape, flags, and build behavior may change
> between versions. Review the plan-mode summary before applying, and prefer a non-production
> environment while it stabilizes.

Turn a natural-language intent into a deployed model-driven app. You author a reviewable **App Spec**
(JSON) with the user across confirmed turns, then a deterministic engine (`cds-maker-sdk`, vendored)
builds it — tables/columns/relationships, sample data, views, Choice-column charts, adaptive forms
with sub-grids, **generative pages** for overview/dashboard surfaces, and the app module + sitemap.
The **same spec drives create and edit**: download a deployed app back into a spec, change it, and
re-run the build (it's idempotent).

## CRITICAL — run the interactive flow in THIS conversation (the main loop)

> **You MUST run the authoring questions and the build narration yourself, in the main
> conversation. Do NOT dispatch a subagent (`Task`) for the interactive steps.**
>
> A subagent is headless — `AskUserQuestion` and plan mode do not reach the user from inside one
> (its only output is its final message). The whole point of this skill is the multi-turn,
> propose-then-confirm experience, so every `AskUserQuestion`, `EnterPlanMode`, and live build
> status line must originate here, in the main loop.

## CRITICAL — the user sees your chat message, NOT tool output

> **Shell/tool output — the result of running `preview-app.js`, a dry-run plan, or a lint —
> is COLLAPSED BY DEFAULT in the UI. The user does NOT see it unless they manually expand the
> tool panel.** Running the command is therefore NOT the same as showing the user. Every artifact
> the user must **read, review, or approve** — the whole-app **preview wireframes**, the
> **dry-run build plan**, and blocking **lint findings** — MUST be reproduced **verbatim in your
> chat reply**, inside a fenced ` ``` ` code block. Never say "the preview looks right" and leave
> the content buried in a collapsed panel: **paste it into your message.** This is the #1 cause of
> "the wireframes aren't visible" — the preview ran, but its output stayed hidden.

## Capabilities — the full toolbox (pick best-fit per requirement)

You are a **complete** model-driven app builder, not a single-surface tool. Everything below ships in
one App Spec and one build — choose what best serves the user's requirement to make a **useful,
prod-ready** app; don't under-build (a bare table list) or over-build (surfaces nobody asked for):

- **Data model** — tables (give each custom table a **meaningful Fluent-style SVG table icon by default**; propose what the glyph will **depict** in words — never a Fluent token name — and record it as `iconDescription` before drawing the SVG — see [`references/authoring-flow.md`](../../references/authoring-flow.md) → *Table icons*), columns (all types), relationships (1:N / N:N + junctions), sample data
- **Record UI** — forms (sub-grids, quick-create / quick-view), views (with enriched default columns), charts
- **Custom grid rendering** (preview) — `entities[].columns[].visualization`: render a column as a
  `RadialDial`, `LineChart`, `HeatMap` or `StarRating` in **every** grid and view that shows it,
  instead of plain text. Reach for it when a column is a *magnitude a user scans* (a score, a
  utilization %, a rating, a priority) rather than a value they read exactly — it makes a list
  scannable at a glance for one line of spec. It is per-*column*, so set it once on the column, not
  on each view. **Preview:** on an environment where it is not provisioned the build skips it and
  everything else still deploys, so it is always safe to include.
- **Actions** — modern command-bar buttons (incl. flyout / split menus), web resources (form JS / HTML / CSS).
  Two rules when writing that JS, both learned from buttons that deployed perfectly and then did
  nothing: a command handler is handed the record (`function doThing(primaryControl)`) — the build
  supplies the parameter, so write that signature; and **never hardcode Choice values** like
  `100000003`, because they are assigned per publisher. Resolve by label via `getOptions()`
  (see `references/app-spec-schema.md` → webResources). Note also that command and web-resource
  **edits do not redeploy on rebuild** — the phases reuse what exists, so changing a button or a
  script means deleting it first.
- **Form logic without code** — `businessRules[]`: show/hide, lock/unlock, set-required and
  set-value, driven by a condition on the record. **Reach for a business rule before form JS** when
  the requirement is field-level and declarative — it is visible in the maker, survives solution
  export, and needs no web resource. Use form JS when the logic needs a real API call, cross-record
  work, or anything beyond the four supported actions.
- **Surfaces** — **generative pages** (modern dashboards / overviews / analytics / landing — the default),
  classic dashboards (opt-in), external URLs
- **App shell** — the app module + sitemap, with per-subarea icons. Turn on the **modern shell** with
  `app.newLook: true` unless the user asks for the classic one; it is opt-in and best-effort, so a
  tenant without the setting still gets a working app. `app.headerNavigationRefresh` controls the
  **Wave 2 header/navigation refresh** — a *separate, independent* setting whose platform default is
  **ON**, so set it to `false` only when the user explicitly wants the classic header.
- **Security & access** — one **security role per persona**, sized from that persona's jobs-to-be-done
  (the entity access each job needs, unioned into the role), so the app **opens for non-admins**.
- **AI-first features** (admin-gated) — form-fill assist, natural-language grid/view search, NL chart
  / AI da