# AGENTS.md — Model Apps Plugin This file provides guidance to AI Agents when working with the **model-apps** plugin. ## What This Plugin Is A plugin for building Power Apps for **model-driven apps**. Two **authoring** skills do the work (plus `/report-issue` and `/telemetry` — four user-invocable skills in total): - **`/genpage`** — build and deploy standalone **generative pages** (genux): React 17 + TypeScript + Fluent UI V9 single-file components, deployed via PAC CLI. Orchestrates specialist agents (planner, optional entity builder, parallel page builders). - **`/app-builder`** — build and edit a **whole model-driven app** (tables, columns, relationships, adaptive forms, views, charts, generative pages, app + sitemap, sample data, and admin-gated AI features) from a natural-language intent, via the vendored headless `cds-maker-sdk`. **The two authoring skills are independent entry points — neither requires the other.** Use `/genpage` to add pages to an app that already exists; use `/app-builder` to build or edit a whole app. `/app-builder` does *reuse* `genpage-page-builder` to generate its page `.tsx` (Phase 1.5), but that is an implementation detail of code generation, not a dependency: `/genpage` never invokes `/app-builder`, and `/app-builder` never invokes the `/genpage` skill. They install together (the marketplace copies the whole plugin directory), but **either can be invoked without the other, and neither leaves state the other depends on**. Keep it that way — shared **agents and libraries** are fine, a skill-to-skill call is not, and neither may write a file the other treats as authoritative (this is why `write-page-plan.js` emits `app-builder-page-plan.md`, not `genpage-plan.md`). Plus **`/report-issue`** to file bugs against this repo. Dataverse mutation flows through the shared, vendored SDK (`scripts/vendor/cds-maker-sdk.cjs`) — see `## Building & Testing` — except for the few surfaces it does not model, which use `dataverseRequest()` (see `## Dataverse Access From Scripts`). **Requirements:** - **PAC CLI > 2.10.0** — for app and generative-page deploy operations (incl. the genpage `upload` connector/Custom API flags) - **Azure CLI (`az`)** — Dataverse Web API auth (SDK + entity builder); must be logged in with the same identity as the active `pac` profile No Dataverse Skills plugin or Python dependency. ## Documentation Map Keep these in sync — **update the relevant doc(s) in the same PR as the change** (a reviewer should be able to tell what moved from the docs alone): | Doc | What it holds | Update when… | |-----|---------------|--------------| | `AGENTS.md` (this file — `CLAUDE.md` symlinks to it) | Per-component behavioral specs, the canonical file tree, conventions, build/test | You add/rename a script, change a component's behavior, or change how to build/test | | [`docs/architecture.md`](docs/architecture.md) | Wiring / flow **diagrams** for both skills (`/genpage` + `/app-builder`) | You change the orchestration, phase pipeline, or how the pieces connect | | [`docs/app-builder-capabilities.md`](docs/app-builder-capabilities.md) | `/app-builder` **capabilities** — what ships today, with the evidence for each | You ship an app-builder capability | | [`docs/app-builder-design.md`](docs/app-builder-design.md) | `/app-builder` **design record** — Part I staged-flow architecture (**cited from code by section number — never renumber**), Part II the `--changed-only` contract | You change the staged flow or the partial-apply contract | | [`CHANGELOG.md`](CHANGELOG.md) | Keep-a-Changelog — concise bullets (detail lives in PRs/docs) | Any user-visible change | | [`references/app-spec-schema.md`](references/app-spec-schema.md) | The App Spec contract (always-present fields) | You change the App Spec shape or validation | | [`references/app-spec-schema-advanced.md`](references/app-spec-schema-advanced.md) | The conditional App Spec fields (business rules, BPFs, commands, web resources, global choices, dashboards, roleGrants) — split out so the always-read contract stays small | You change one of those features | Don't duplicate content across these — **cross-link instead** (a second copy only drifts, as the file tree and teardown order both did before). **Issue references belong in history and in code, never in use-the-plugin reference material.** `references/*.md` and `skills/*/SKILL.md` are loaded verbatim into an agent's context so it can *author a spec*. A tracker link there costs tokens, cannot be dereferenced by the reader it is shown to, and goes stale while the doc lives on — so state the rule and the **why**, and stop. The test is simple: if deleting the link loses nothing operational, it was provenance, not explanation. Provenance is welcome in the *other* class of doc — the material that explains **why the code is the way it is** rather than how to use it: this file, `CHANGELOG.md`, and code comments, where the repo-root `AGENTS.md` actively asks for one. Its reader is a contributor who can open the link and act on it. Prefer the bare id (`AB#6686428`, `#537`) over a full URL even there: it carries the same provenance, costs less, and cannot rot. A corollary for **error messages**: an error must stand alone. `operator 'X' is not usable — see ` sends an author to a tracker to find out what they did wrong; say what is wrong instead. **This repo is public.** Before adding to any of these docs, re-read the repo-root `AGENTS.md` → *"This Repo Is PUBLIC"*. The docs here have already had to be scrubbed once for internal repo paths, a real Dataverse environment name, review provenance, and indexes into documents an outside reader cannot open. Record that kind of context in the PR conversation instead. ## app-builder — intent → model-driven app A second skill (`/app-builder`) builds a whole **model-driven app** (tables, columns, relationships, adaptive forms with sub-grids, views, Choice-column charts, app module + sitemap) from a natural-language intent — distinct from `/genpage`, which builds generative *pages*. The **whole flow runs in the main conversation loop, never a `Task` subagent** — subagents are headless, so `AskUserQuestion` and plan mode cannot reach the user. **This applies to `/genpage` too**: its agents are headless discovery/generation workers, and an agent that needs a decision returns a `needs_input` request for the main loop to ask (`references/agent-interaction-contract.md`). `scripts/validate-agent-interactivity.js` fails the build if any `plugins/model-apps/agents/*.md` declares an interactive tool — the frontmatter is prose to every other test, which is how `/genpage` Phase 1 specified an unreachable interactive flow for ~2.5 months. The same validator also fails a **one-sided tool declaration**: tool names are host-specific and every host silently ignores a name it does not recognize, so a capability named only in one scheme is absent on the other host and the agent launches without it. `TaskCreate`/`TaskUpdate`/`TaskList` are the live example — no published alias table lists them, so `todo` must be declared alongside. Both skills also support **unattended runs** (Copilot autopilot / Claude auto-accept) via `scripts/resolve-interaction-mode.js`; suppressing a prompt never authorizes destructive work. For the end-to-end flow, stage→phase mapping and page-identity model, see [`docs/architecture.md`](docs/architecture.md) → `## /app-builder — build pipeline`; that doc owns the pipeline and delegates each script's **behavioral spec** to the entries below. - **`references/authoring-flow.md`** — the Phase-1 authoring playbook the skill executes itself: validate prereqs, select the env via PAC (`pac auth list` / `pac org who`), detect existing tables/apps, author the **App Spec** in confirmed levels (**(a0) personas & jobs-to-be-done first** — they drive which tables and surfaces exist — then data model, then forms/views/charts + page-intents + sample data, then access), run the `spec-lint.js` guardrail, get plan-mode approval. Writes `app-spec.json` (the machine contract) + `model-app-plan.md` (rendered by `scripts/write-app-spec-doc.js`, never hand-written). **Artifact naming:** both skills derive their working directory from a slug off the user's request, so they can land on the SAME folder and file names are a namespace. A file written by BOTH is unprefixed (`workflow-log.md`); a file owned by ONE is prefixed with it (`genpage-plan.md`, `genpage-entity-creation-log.md`, `app-builder-page-plan.md`). A name chosen to prevent confusion must not *contain* the name it guards against — see `scripts/write-page-plan.js` for why the app-builder page plan is not `genpage-*`. - **`scripts/lib/spec-lint.js`** — pure App Spec guardrail (`lintAppSpec → { ok, errors, warnings }`): errors block the plan gate (e.g. the relationship-name-vs-lookup-name collision Dataverse rejects), warnings teach. - **`scripts/lib/app-source-path.js`** — shared resolver for page `codeFile` and web-resource `contentPath` reads/uploads and hashing. Validation/lint share its lexical rule; the resolver requires a relative, regular file inside the canonical app folder and refuses source symlinks and junctions. Source-file checks report rejected paths rather than silently skipping them. - **`scripts/lint-app-spec.js`** — the CLI surface for both gates, for a headless author or a CI job (#560). Runs `migrateAppSpec` → `validateAppSpec` (what the build runs on load) → `lintAppSpec` (guardrails the builder does **not** run), and exits non-zero on errors (`--strict` also fails on warnings). Prefer it over calling the library through `node -e`: linting the file **as written** rather than the migrated shape is what let a spec pass the lint and then fail the build (#545). `--profile` defaults to **`plan`**, not `deploy`, because the authoring flow runs this while pages are still intents — a deploy default rejects a normal work-in-progress spec. `plan` relaxes only that rule. Gate a final, deployable spec with `--profile deploy`. - **`scripts/build-model-app.js` → `scripts/lib/sdk-build.js`** — the deterministic, **idempotent** build engine, run after approval. Runs in two engine invocations (staged flow): (1) `--stage data --apply` materializes tables + columns + relationships (solution·data-model only; sample-data deferred) so `generate-types` can emit `RuntimeTypes.ts`; (2) a full `--apply` build (re-discovers the data model, then ui · app · publish) finalizes everything idempotently. `--stage ` selects phases by stage name; **apply-safe only for `data`** — the full build (run 2) is always a complete idempotent run. Discovers existing tables/columns/relationships via the SDK (`findTables`/`findColumns`/`fetchEntityMetadata`) and creates only what's missing (`createSolution`/`createTable`/`createColumn`/`createRelationship`), seeds sample data via `seedRecordGraph` (SDK-owned parent-bind + resolve-by-name idempotency), enriches default Active/Inactive views via `enrichDefaultViews`, then `createWebResource` for form JS, then builds each artifact through the SDK's **generic mutation surface** (`createArtifact`+`addElement`/`updateElement`/`removeElement`+`pushArtifact`) driven by the pure **`scripts/lib/artifact-intent.js`** compiler: a form is a minimal `createArtifact` plus a coarse `addElement` of each authored tab (sub-grids/quick-views are canonical control cells; form JS is the root-bag `/bag/c` `` region), a view is `updateElement('/columns')`, an app is `updateElement('/siteMap')`, a dashboard tile is `addElement('/components')`. Form reconcile adds the spec's fields and — for an author-controlled **explicit** layout — prunes fields it dropped (never the primary) via `findFieldCellPointer`+`removeElement`, keyed by a declared semantic identity so a rebuild never duplicates a control. A row that a pruned or moved cell leaves holding nothing is removed too (`strandedRows` in `lib/form-occupancy.js`, shared by the prune pass and both move paths). A row that a row-spanning cell above still reserves is kept, and so is a row that was already empty. Explicit layouts converge **tab/section order**, not existing-field order. Newly created listed fields and `fieldOptions[x].after` share a copied occupancy-checked plan, committed as one artifact edit so an interrupted split cannot persist duplicated cells. Anchors run in dependency order after new-field insertion; remaining unsatisfied requests are warned in `skipped.layout`. Existing fields are not list-reordered. Verify checks form-wide cell/control ID uniqueness, including auto forms, but not field order or anchor adjacency. See the [form-layout contract](references/app-spec-schema.md). **The Notes timeline** (#680, `lib/form-timeline.js` — one definition shared by the compiler, the build's repair and verify) is written in the shape Dynamics renders: the fixed control id `notescontrol` in a 23-row cell with `auto="false"` (its `auto`/spelled-out `showlabel`/`colspan`/ `rowspan` ride in the cell's bag), over the 22 empty spacer rows the cell spans. The old shape — a generated control id in a one-row cell — is published and never rendered. What platform forms share is the id, `showlabel="false"` and a cell of N rows followed by N−1 empty rows — N is 5, 20, 23 on different forms, `auto="false"` is on some and not others, `colspan` is 1 or 2 — so the helpers take ANY N of two or more as in shape: 23 and `auto` are what a NEW host is written with, never what an existing one is held to. A rebuild repairs the engine's own host (the `section_notes` section holding the timeline control) **in place** on every layout: one atomic rows write, same section, position and cell identity, and only what is missing — the id, a span of one row, rows under the span (to the span the maker chose; extra rows are never deleted); `auto` is written only with the conversion of an old cell, never alone. The repair (`repairTimelineHost`) runs **last** of the passes that touch a form's fields — after the prune and the `fieldOptions.after` moves — because it rewrites only the host's own rows and refuses a host that holds another control: run first, it would refuse an old host whose stray field the same build then prunes, and the form would stay old until a second build. The topology pass does not narrow that host below its timeline's `colspan` (a widened timeline is the maker's width). It never edits a maker's timeline elsewhere and never writes a second `notescontrol` — a form that already has a control by that id gets no new host (the explicit-layout topology pass and the auto-layout path share `timelineCreationBlocked`), and a host whose id cannot be renamed for that reason, or that still holds another control once the prune and moves are done, is left whole and reported in `skipped.layout`. That is one rule (`timelineRefusal`) applied to two different trees, not one decision that both reach alike: the build judges the form as its field passes have left it, `--verify` the form as published, BEFORE them. So verify predicts what the passes take out of the host (`notesHostInspector` in `verify-spec.js`: a field an explicit layout declares in another section; one a `fieldOptions.after` anchor places beside an anchor that is not in a section the build owns — an anchor that sits in the host but is itself anchored is moved out first, because anchored fields are placed in dependency order, and the field follows it; one an explicit layout with prune on does not list — `formRemovals`, the destructive gate's own function) and hands the rule those cells as `leaving`. What a pass does is predicted only for a field the form has ONE cell of. Each pass acts on a single cell of a field — the first it finds once the topology pass has reordered tabs and sections (`planOrderMoves`), and the prune removes one cell of a field per run — so for a field the form carries twice that a pass would act on (or one anchored, directly or down a chain of anchors, to a field it carries twice with a cell in a section the build owns; the reason names that field, not an anchor of one cell on the way to it) verify cannot know which cell a build acts on. It says so (`unsure`), in every shape of its advice — the taken-id one included, since freeing the id does not decide that cell: no promised repair (a full build repairs the timeline *unless* it leaves the cell, which verify cannot tell), no certain refusal, and no sending the maker off to do what the build may do itself. Only a pruned duplicate becomes predictable by itself (the prune removes one cell per run, so verify is exact once one is left); one a declaration or an anchor places can stay unpredictable build after build, since a build that acts on the cell already in place leaves the others — the maker moves them, as the advice says. A field that no pass touches stays whichever cell is acted on, one cell of it or several, so that is still said plainly. It is a prediction from the spec and the published form, not the build: it also cannot see a removal that was not authorized or that the build holds back, or a `fieldOptions` move skipped for a row-span or an overflowing row. Where it and a build differ the build's report is the authority — the cases in `form-timeline-real-bundle.test.js` run both on each shape, including forms whose published section order is not the build's, so a change to which fields a pass takes out is made in the pass and the prediction together. An `auto` form that asks for Notes and has no host gets one on rebuild (`addTimelineHost`, before the sub-grids: it has no topology pass to add it). Fields never go into an engine host: the no-section fallback skips hosts (`firstFieldSectionRowsPointer` — quick views use it too), a `fieldOptions.after` anchor inside one is refused, and the narrowing re-flow never runs on one (it would delete the spacer rows as "beyond the new count"). Verify's `form-timeline` check needs ONE timeline that renders (id `notescontrol`, a cell spanning more than one row) on any form the spec gives Notes — and, for the engine's own host, the N−1 rows under its span, since the build converges them; a maker's timeline is judged by id and span alone. So an old-shape form fails it until rebuilt — and its detail says what a build WILL do about that form (`timelineVerifyProblem`): "run a full build" where the build repairs or adds it, what the maker must do first where it declines (another control holds `notescontrol`; the host holds a control no pass of the build takes out — a maker's own control, or a field no rule of the spec moves or removes, which the maker moves out of the section; on an `auto` layout, which declares no section for a field and prunes none, that is any field already on the form that no `fieldOptions` anchor places). A field the build itself prunes or places elsewhere is not the maker's to move: the advice stays "run a full build" and names what the build takes out first, a removal with the `--allow-destructive` it needs. A field it cannot predict is neither: where a full build would repair the timeline the advice says it does so unless it leaves that field, which verify cannot tell; where the advice is something else first (a control that stays, a taken id) it says verify cannot tell whether the build takes the field out first — and, either way, what to do if the build's report says the timeline was left as it is. Always a FULL build: a `--changed-only` run of an unchanged spec is a no-op ("nothing to apply"), so a form an older version left — which no change to the spec reaches — is never repaired by it. Download does not reconstruct `forms[]` (see `hydrate-spec.js`), so `notes`/`hasNotes` are authored and there is no form read-back to adapt. **Where a sub-grid's section goes** (AB#6651699, `lib/form-subgrid-placement.js` — the pure rules the spec gate, build, verify and wireframe all read): `forms[].subgrids[]` takes `after`/`before` (a section of the declared layout), `tab`, `column`. An `after`/`before` grid sits in its anchor's tab and form-column DIRECTLY beside it (`columnSequence` builds the order — grids that share an anchor keep declared order, each directly beside the one declared before it — and `neighbourOf` names the token a grid must touch); a `tab`(+`column`) grid is a question of MEMBERSHIP, created at the end of that column and, once in it, left wherever it is within it. The names are what `formLayoutNames` (app-spec.js) derives — an auto layout is `tab_general` holding `section_general`, pinned to the compiler by a test — and `subgridPlacementProblems` is the one function behind both the spec gate and the lint (a key a sub-grid entry does not read is only a warning — `subgridUnknownKeys` — because entries written before the placement keys existed may carry extras the build never read). A form holds ONE grid per relationship, so `subgridDuplicateProblems` (gate and lint, one function) refuses a relationship listed twice when an entry places the grid — those keys are new, so no spec that built is turned away — and only warns for a repeat that places nothing (the build has always ignored the extra entry); verify fails the later entry rather than pass it. A grid with NO key takes the original path exactly (end of the first tab's first column, never moved): a test records its writes. The build (`addSubgrids` → `placeGridSection`) runs after the topology pass, using the tab/section matches that pass recorded (`reconcileFormTopology` returns `{ sectionTargets, tabIndexOf }`) — so an anchor matched by label under another name is still the anchor. Grids with no anchor are appended first, in declared order, as they always were; the anchored ones follow — `after` grids in declared order, `before` grids in reverse — each put directly beside the nearest token toward its anchor already on the form (`anchoredPosition`), which is where a NEW form puts it: a new grid is added there in one write, an existing one is MOVED (same section, one `moveElement`, within a column or across form-columns), and one already directly beside it writes nothing. ONLY THE GRID MOVES: `planOrderMoves`, the fewest-moves planner the topology pass uses, is deliberately not used here — it moves whichever section is cheapest, and on the layout every released build left behind (`notes: true` + a grid: the grid BEHIND the Notes section) that is an authored section or the timeline, leaving the Notes section mid-form; a section in between (the Notes section, a maker's own) is simply left behind the grid. Only the engine's own `section_grid_*` host is ever moved; a grid a maker put in a section of their own is reported in `skipped.layout` — unless it is already where the spec puts it, which is neither written nor reported — as is an anchor/tab the deployed form lacks (the grid is then added at the end of the first tab, never lost). Adding or moving a section shifts the indices of the sections behind it, so everything that holds a section across `addSubgrids` is kept by what it is, not where it is: `shiftSectionTargets` corrects the topology pass's recorded targets, and a field being ADDED is queued with its section's id and name (`queuedSectionPointer` finds it again through `findSectionById`, then by name and place) — an index goes stale when a grid section is inserted ahead of it or taken out of the column, and the field would land in the grid's section or halt the forms phase on a pointer that addresses nothing; a section gone altogether sends the field to the first field section, reported. Quick views go to the first FIELD section too, never a grid's. Verify's `form-subgrid` check judges each placed grid against the DEPLOYED form with the same `neighbourOf` — directly beside its neighbour, anything between them named — (`RelationshipName` is element text — `parseFormTopology` reads it), on explicit and auto layouts; a failing detail says to run a full build where the build moves the grid, and what the maker must do where it is in a maker's own section. The wireframe and the offline eval reader read a compiled column by PLACE (`columnItems`; `columnSequence` tokens carry `at`), never by name — a layout may declare a section named `section_notes` too. A grid is as wide as its form-column, so a full-width grid wants a one-column tab (documented, not engineered). Download does not reconstruct `forms[]`, so placement is authored too. **Which form a table opens with** (AB#6736948, `lib/form-order.js`) is decided by the table's Main Form Set order — each Main form's formxml `` — not by `systemform.isdefault` (measured: moving the flag reorders nothing, and a table's three new forms, all at the same order, were served with the `isdefault` form last). After every form exists, the forms phase promotes the default (an explicit `isDefault` or `entities[].mainFormOrder[0]` on any table; the first Main form only on a table the spec owns) and then writes Order 0..n-1 onto the spec's Main forms, the ones it does not list keeping their stored relative order. On a table it orders nothing on, a Main form it creates is created after the table's others: its order is written into the new form's own `` before the first push (`createInPlace`), so no interrupted run or later failure can leave it at the Order 0 every new form gets — a later build could not tell it is new. Only declared forms are written, order-only through `setFormSecurityRoles` so roles survive; a table ordered by hand (`securityRoles.order`) is left alone; the step is best-effort (✗ and a warning, never a halt). Verify checks the stored order (`form-order`) and what the public `RetrieveFilteredForms` serves the user running it (`form-order-served`). On `build --apply`, the destructive preflight writes `.maker-workspace/destructive-approval.json` when it refuses form-field or sitemap removals, and also when an approved destructive run starts so retries and later failures stay bound to that gate-time list — an empty list included, when the run includes the removal phases. A later `--allow-destructive` run may remove only that recorded set; the record is consumed only after a successful run that included both removal phases (`forms` and `app-shell`) and kept no field, and is otherwise kept on failure, partial runs, changed-only runs, or when the fence kept a field. An approved run consumes or rewrites only a record it found at its start or wrote itself (each record carries its run id, compared by content fingerprint), checked and changed under the workspace lease the apply snapshot uses, so two builds sharing a workspace cannot consume each other's record. A refusal still replaces the record with the list it just showed, because that is the list the maker is looking at, and a halt naming new removals refreshes it with the full current list (the halt shows only the new ones). An approved run halts before any write if the record changed after it was read, or if the lease stays held. The gate fails closed if the record is unreadable or if discovery fails while a record exists, because live removals cannot be compared with the approved list. If live state contains a new removal, the build halts, lists only that new removal, refreshes the record, and the engine keeps any field or sitemap target that appears during the run rather than pruning beyond the preflight-approved set. Every push routes through `requireSuccessfulPush` (a 412 version conflict halts the build for a fresh download instead of silently dropping the edit) — so new, existing, and mixed envs all work. The data model is **complete** (all column types, global choices, status reasons, alternate keys, N:N). It also builds **quick-create/quick-view forms** (`formType`) with **quick-view placement** (`forms[].quickViews[]` — embed a QuickView form via a lookup), **modern command-bar buttons** (`commands[]` — functional JS on-click + static hidden/disabled, incl. **flyout/split-button menus** via `type`+`children[]`), and **dashboards** (`dashboards[]` — chart/list/iframe/webresource tiles) with **sitemap placement** (a `dashboard` subarea auto-pins the dashboard as an app component). It also builds **business process flows** (`businessProcessFlows[]` — the staged process bar on a record): a `workflows` row of category 4 / type 1 / businessprocesstype 0 whose XAML the SDK compiles from ordered `stages[]`/`steps[]`, activated in the same push. The phase is additive discover-reconcile keyed on `(entity, name)` like `business-rules` — it creates what is missing and converges only Active/Draft **state**, never stage structure — and `bpfFilter` scopes every query in build/verify/teardown to the DEFINITION row, excluding both the platform's activated `type 2` copy and same-named TASK flows (also category 4). v1 is deliberately single-entity and linear: cross-entity stages, branching and stage actions are **rejected at the spec gate** rather than silently dropped, because the build cannot yet verify them. `securityRoles` was rejected alongside them and is now **supported** (`{ "personas": [...] }`): a BPF's role grants are `create/read/write/delete` privileges on the backing table that ACTIVATION creates, so they are applied in the **`security` phase**, after both the flow and the personas' roles exist — persona lookup there is **case-insensitive**, since a persona is a display name the author repeats by hand across two sections of the spec, and the target table is the flow's **deployed `uniquename` read back** from the workflow row rather than derived from its display name (a flow authored in Maker, or renamed later, keeps an unrelated unique name). There is no `everyone`/`fallbackForm`/`order`: those are `forms[].securityRoles` concepts written into formxml, and a privilege has no such equivalent. The rejection is an **allow-list at flow, stage AND step level**, because the SDK's normalizers copy a fixed key set and discard the rest — so a `branch` written on a stage (where the SDK actually models it), or the very plausible `fieldLogicalName` instead of `field` on a step, would otherwise validate clean and deploy as if it had never been written. Two further platform facts the validator encodes: a flow's **name must be unique across the whole spec**, because the SDK derives `uniquename` as `new_` — **ignoring the table** — and activation creates a backing table with that name; and a stage must carry **at least one step**, because the SDK substitutes a placeholder step named "New Step" for an empty one (its own `stage-needs-step` rule never fires, as the placeholder is injected before it looks). Following a **genpage-first policy**, overview/dashboard/analytics surfaces are authored as **generative pages** (`pages[]`) rather than classic dashboards — the build's `pages` phase uses a **three-authority model**: IDENTITY (durable `_pagemanifest`, outranked by a downloaded spec's `pages[].pageId`), EXISTENCE (env-wide `pac model genpage list` — crash-safe create-vs-reuse via `enumerateEnv`), and MEMBERSHIP (the app's sitemap `GenPageId` set, read fail-closed via `fetchSitemap` in `scripts/lib/sitemap-pages.js` — drives placement, download enumeration, and verify; a read failure HALTs). All page matching is by id. Every `pages[]` entry must be sitemap-placed (validation rejects headless pages) — because the sitemap is download's ONLY membership oracle, so a page reached only by `navigatesTo` is invisible to download and gets re-created as a duplicate on the next build. The corollary is that a detail page is reachable from the nav with **no input**, so a page declaring `pageInput` must also declare **`directEntry`** (`selector` | `emptyState`) saying what that renders; `page-plan` passes it to the generator and the page manifest carries it through download. Every `pageInput.data` key must also be produced by an incoming `navigatesTo[].data` edge. See `references/app-spec-schema.md` → *the input contract*. The build halts on safety violations (`pages-removed`, `pages-shared-across-apps`, identity conflicts, read failures) and, before any page is created or updated, on a page that would ship a Griffel shorthand (`pages-griffel-shorthand`: a page it creates, or one whose source changed since the last recorded apply — a page it sends again as it is gets a warning; see "Griffel shorthands"). The cross-app shared-page scan (`fetchAppsForPages`) enumerates every app via the vendored SDK's `@odata.nextLink` pagination (`queryRecords({ paginate:true })`), so it verifies EVERY app in the environment rather than one 5000-row page; a pagination fault (the SDK's repeated-nextLink guard) still fails **closed** rather than scanning a partial list. It reads each other app's PUBLISHED sitemap and also its SAVED (current, unpublished) one: a page another app has saved into its navigation but not published still halts the update (`pages-shared-across-apps`, naming the app `[saved, not published]`). The scan is a snapshot: another maker can take a page into another app's navigation while the build runs, and nothing reaches far enough to stop it — the lease is this workspace's, Dataverse offers no write conditional on another app's sitemap, and the update goes through `pac`, which takes no precondition. So a build that writes pages in place takes the scan twice more, over the pages it began with and now overwrites (one this run created, a navigation target included, was not there to share and is left out): right before the first of them is written, where a page that became shared halts the build before any page it began with is updated in place (`pages-shared-across-apps`, "became shared across apps while this build ran", `transient: false`); and after the last — or after the loop stops early, since what it wrote is written — where a page taken in while the uploads ran is reported as a warning naming the page and the app (one that only saved it shows the new content once that app is published; a scan that fails there is a warning too: nothing is left to refuse). Each scan reads every other app's navigation (three requests per other app, and three more), which is why it is not taken before every page. The saved layer of every other app is **one** extra request — the `sitemap` collection's `RetrieveUnpublishedMultiple`, joined to each app by the sitemap id its published read found, with the same current-row rule `navigationProof` uses — and it is fail-closed too: a read that fails as a whole halts as `pages-shared-check-failed`, and an app whose saved row is missing, ambiguous or malformed is listed unreadable. An app that was **never published** has no row in the published app list, so the scan lists those as well — one request, the `appmodule` collection's `RetrieveUnpublishedMultiple` (`draftOnlyApps`) — and joins each one's saved sitemap from the same saved-layer read, by the sitemap id its layer's sitemap component names (one more read per such app); it has no published layer, so whatever it holds is saved only. That list is fail-closed like the others: a read that fails halts as `pages-shared-check-failed`, and a never-published app whose layer, sitemap component or saved sitemap cannot be read is listed unreadable. A never-published app whose component read **succeeds** and finds **no sitemap component** is not yet shown to have no navigation: the vendored SDK links an app to its sitemap **by name** — it looks the sitemap up with `sitemapnameunique eq ''` and takes one for the app only while that column holds the app's name, and `ensureSitemapInSolution` (sdk-build.js) resolves it the same way — so such an app may hold a sitemap, and pages in it, that no component row links to it. The saved-layer read the scan makes anyway (it asks for `sitemapnameunique` too — no further request) shows whether it does: a sitemap of that name is joined like any draft app's (case-insensitively, as Dataverse compares names), several sitemaps of the name leave the app unreadable, and **none** means the app has no navigation at all and holds no page, so it is skipped — one draft app saved with only a name must not stop every page update in the environment (a read that *fails*, or a component that names no sitemap, proves nothing and is still unreadable; so is a *published* app with no sitemap component, which is not changed here). A single-app environment reads no other app's navigation: it pays the one small request for the list of never-published apps, and nothing more when there are none (one saved-layer read as well when a never-published app has no sitemap component, to rule out a sitemap linked by name). Classic `dashboards[]` are opt-in. **Every `pac model genpage` call is time-bounded** (`lib/genpage-cli.js` `runPac`): 3 minutes to list or download and 10 minutes to upload by default, or `POWER_PLATFORM_SKILLS_PAC_TIMEOUT_MS` (1 s to 60 min; one value sets all three). When the time is up the whole process tree is ended — a page upload once stalled for 17 minutes with no CPU and no network — and the call is reported as `timedOut`, which no exit code is. What happens next follows from what the call can have done. pac's upload writes the page, records the prompt and the agent message (two more requests), prints `Page ID`, then publishes, so a stopped upload has done anywhere from nothing to all but its last step. A timed-out list or download is read-only, so it is retried once. A timed-out **update** is **not** retried, though it names a page that exists: a re-send can record the prompt a second time (a call stalled in the publish has already written everything) and goes out minutes after the caller's own checks, so it can overwrite a change saved in between. It is reported as one that *may have landed*, and what it sends you to look at depends on the caller (`upload()`'s `caller`): the upload script's message names `genpage-base.js check` (the deployed page against the file and the base marker beside it), and a re-run goes back through the script's own guards. The **build** keeps no base marker, so that check could only answer "unknown", and every page's code file is a staging copy its cleanup deletes, so the command would fail on a missing file: the build's message tells you to read the deployed page with `pac model genpage download` (the call the build already uses, for that page id — and to open the `page.tsx` in the folder named for the id, which pac writes in its own letter case) and then run the build again, which sends the page once more to the same id — nothing new is created, but if the stalled send did land, the page's history now records its prompt a second time, and anything saved to the page in Maker since is replaced by the app folder's version. The error carries `transient: false`, so the build's own retry of transient halts never re-sends it. An **update** that **fails** — a non-zero exit, or an exit 0 with no `Page ID` — is handled the same way, for the same reason (pac can fail in the publish, after everything else is written): it is **not** retried, it is reported as one that *may have landed*, with what pac had printed (a `Page ID` means the page and its messages were written and the failure came in the publish) and the same caller-specific check, and it carries `transient: false`. Only a non-zero exit that pac reports for its own arguments or input files (`isDeterministic`) is an ordinary error, because pac checks those before it sends anything — and only when pac printed no `Page ID`: after the Page ID its one remaining step is the publish, whose error carries the server's own text, so a Page ID proves the page was written whatever the words. An update answered with another page's id also carries `transient: false`. That covers the halt an upload causes; a transient halt *later* in the same run (a 503 on a later read or write, say) still re-runs the whole build, which sends each page this run sent once more — as each rebuild does — so the page's history then records the prompt once more. A timed-out **create** is an uncertain create and is never run again, because a second create is how a duplicate is made. A `Page ID` pac had already printed names the page it created, whether the call then stalled or **failed** (exited non-zero): it is reported as *created as ``, stalled (or failed) before publish or placement*, the create is **not** sent again however the environment's listing looks (the page need not be in it yet), and the way on is to place it (`pac model genpage add`, or Maker) and then update it, or to delete it and re-run the create — never "update it" outright (refused: not in the app's navigation) and never a bare re-run. With no id printed, the env-wide id diff reports any page already visible — a create that failed and left a candidate gets the same way on, not "re-run it as an update with `--page-id`" — and a page that is not visible *yet* proves nothing: a create that stalled with nothing visible, or whose listing cannot be read, is reported as uncertain with the advice to wait and list `pac model genpage list --environment --include-unpublished` before anything is created again. **Every error that follows a create whose outcome is not known to be nothing carries `transient: false`** (`neverRetriedError`) — a stall, a printed Page ID, a candidate in the listing, a listing that cannot be read: the build re-runs a phase when a halt reads as transient (`isTransientHalt`, build-model-app.js), and it reads the halt's *text* — which quotes the page's name (a page called "SQL Timeouts" matched) and pac's own words ("… try again later") — so without the marker a re-run would be a second create and a duplicate page, with the run reporting success. The page that was created but whose local receipt could not be saved (`pages-creation-receipt-failed`) carries it too. A create that failed outright and left nothing in the listing, and a listing that fails *before* the create was sent, leave nothing to duplicate: both are still retried — by the upload (3 sends) and, when the error's text reads as transient, by the build — as in 2.13.0. (`pac connection list` and the auth probes have their own limits or none; this bound is the genpage calls'.) **All of the build's Dataverse access is via the SDK** (see "Dataverse Access From Scripts" for the sanctioned exceptions elsewhere), so metadata is persisted under `/.maker-workspace/` for reuse/edits. The 16 phases (`solution·data-model·sample-data·web-resources·views·charts·forms·business-rules·business-process-flows·commands·dashboards·app-shell·pages·ai-features·security·publish`) are unchanged; independent ops run with bounded parallelism. Off-sitemap ids require a local CREATE receipt for this app/key/id plus an exact decoded stored-name match, including when the spec and remote manifest agree. Otherwise `unproven-manifest-id` causes `pages-identity-conflict`, never a replacement CREATE. Names corroborate identity, never establish it. `scripts/lib/page-ownership-records.js` writes receipts immediately after an acknowledged create, before remote manifest persistence or sitemap placement. Version-2 records bind the target's normalized HTTPS origin with a SHA-256 fingerprint, never a stored environment URL. This is the only receipt format. Unknown versions, malformed data and unreadable files halt with the record's full path and recovery guidance, never an empty ownership set. Foreign fingerprints grant no authority and are never consumed for another target. Baselines, downloads and journals are not receipts. Business-rule reuse keeps additional same-name definitions; after a push every extra id not returned by the SDK is kept and reported as not attributable to this run. A rejected AI summary exposes no created-model id to this caller, so same-name AI models are reported and kept. Emits `[n/total]` events the orchestrator narrates + a `BuildHalt` it gates on. Dry-run by default; `--apply` writes, `--sample-data` / `--publish` opt-in (`--publish` gates the final *bulk* publish; without it the edit/finalize paths — reconciling an existing form/view, form events, quick-views, existing-app sitemap, page finalize — still publish their one artifact so the change takes effect, and with or without it the lookup-label repair publishes the tables whose columns it relabelled). The bulk publish is ONE `PublishXml` envelope (`publishArtifacts`) for every table and the app, and with `--publish` the default-view enrichment, the reconcile of an existing view or form, form-event wiring and quick-view placement all defer their own publish to it: an entity publish ships every pending customization on that table, so one per artifact only repeated it, at ~2-2.5 s each. The tables the reconcile, form-event and quick-view paths touched are also published together once, in one envelope at the start of the app step, before anything publishes the app (`publishReconciledTables`). Measured live: a `PublishXml` naming only the app, sent after an existing form's save and before its table's publish, leaves the form's label changes unpublished for good, while the structure saved with them goes live. The enrichment's default views (columns only) wait for the bulk publish. A table whose early publish the SDK refuses stops the build before the app is written (`reconciled-publish-failed`), since the app's publish would strand its labels; the halt carries what is owed, so the CLI's retry, or its settle once no retry follows, publishes the table without the app. A deferred publish is recorded as owed, and a build that halts before the publish phase hands what is still owed to the CLI, which keeps each attempt's debt across transient retries until a publish phase pays it, and settles the rest per target once no retry follows (`settleOwedPublishes`) — so a halted build leaves those views and forms live, as it did before the batching. The record also keeps the NAME of every view and form deferred onto a table (`view Open Tickets`, `form Ticket events`; the CLI unions them across attempts), and `default views of ` when that table's default-view enrichment saved its generated Active/Inactive pair — whether the enrichment makes the record or joins one an authored view's reconcile already made — because one artifact stands for its whole table in the envelope: when that publish fails or cannot be confirmed, the warning names what is saved but not live, as the per-artifact publish it replaced did, rather than the table's Main form. That warning also names the views, forms and charts the run created on the table (and a chart whose description it wrote), each name once: a first build creates them all and defers no publish for them, so its record would otherwise name only the default views and the line would read as if only the generated pair were not live. Those names are labels only and stay out of the owed record, which is what a halted build publishes, so the warning after a halt names what was deferred. Settling covers a halt the build THROWS. A process killed outright (Ctrl-C, a crash, a closed terminal) settles nothing, so what a reconcile had saved stays saved but unpublished until the next build, which publishes it (a clean workspace copy is still published, below): no marker outlives the process, the default-view enrichment has the same exposure, and the app-builder skill's recovery guidance says to re-run. A default-view push refused by a concurrent edit fails the enrichment step, as any refused push does. **An unchanged rebuild writes almost nothing, and no write is skipped on a guess.** An existing view or form is pushed only when the SDK reports that its workspace copy differs from its last-synced snapshot (`diffArtifact`, `lib/unsynced-edits.js`): an edit this run made, or one an interrupted run left in the workspace — which a plain fetch keeps while the server has not moved, so comparing what this run computed with what it fetched would call it unchanged and never push it. An SDK without the method, or a diff that fails, pushes as before. A clean copy is the UNPUBLISHED layer, so it says nothing about what is published: without `--publish` the reconcile still publishes its artifact even when it skipped the push, since an earlier run may have saved and stopped. The reconcile of a reused component also re-asserts its solution membership, and one read answers all of them (`lib/solution-membership.js`: a single paginated `solutioncomponent` query for the component types the build adds plus the solution's tables, made at first use, so a build that reuses nothing and deploys no pages never makes it). A component the read proves present is not added again — views, forms, charts, business rules, the process flow, the app, its sitemap, the page manifest and persona roles. There are two proofs: a row of the component's own, or, for a view, chart or form ONLY, its table being held by the solution with ALL its subcomponents (`rootcomponentbehavior` 0). A table the build creates is held that way, and the platform does not list such a table's views, forms and charts one by one — an explicit `AddSolutionComponent` for one leaves no row — so a rebuild that looked only for rows sent those adds every time (measured live: 10 of the 19 an unchanged rebuild sent). The table's MetadataId, which is the `objectid` of its row, is read once per table, only for a component without a row and only when the solution holds some table that way, through the raw client the build already uses for table metadata (`tableRefs`). A table held at 1 (its own metadata only) or 2 (shell only) proves nothing, and neither does a row with no behavior: those components need rows of their own, and are added without one. Anything the read does not prove (the read or the table lookup failed, the solution is a built-in one) is added exactly as before. A component this run creates is added directly, except the page manifest: it is persisted through the same check after every page create and once more at the end, so a first build that deploys pages makes the read too — and still adds the manifest, which the solution does not hold yet. What an unchanged rebuild still sends: the phase-8 envelope; the SDK's own default-view enrichment (it pushes both generated views of each table it enriches); the default-form promotion of a table the build owns (`isdefault`); the existing app's sitemap push with its component pins and publish; the AI-feature setting writes; and each persona role's privilege replace and app association. **The modern ("new look") shell is opt-in via `app.newLook`.** It is a per-app SETTING (`NewLookAlwaysOn`, written through the SDK's `saveSettingValue` scoped to app + solution), NOT an app-module column — `navigationtype` is Single/Multi *session* and unrelated, which is the reason this looked unavailable for a long time. Best-effort: the feature rolls out by tenant, so a failure warns and records `created.newLook: false` rather than failing an otherwise-good build or reporting a silent success. **`app.aiDescription` (the routing description) is written only when the spec sets it** — at create, and on an existing app when it differs from the fetched draft, riding that run's app push. The platform may author this text itself, so an omitted field is never written or blanked. A never-published app refuses the write (`APP_DRAFT_HEADER_NOT_WRITABLE`), which halts with `app-header-unpublished` — publish, then re-run — after resetting the workspace copy, which a plain re-fetch would otherwise refuse to replace (`LOCAL_EDITS_WOULD_BE_LOST`). An app with an UNPUBLISHED header change takes it: the vendored SDK conditions the header write on the appmodule's row token, so the push saves and keeps that change (live-verified). A 412 is a concurrent edit, on the appmodule row as on the sitemap, and is never re-explained as "publish first". Any other failed push that carried the change resets the copy too — except a concurrent edit (`VERSION_CONFLICT` / a code-less 412), where the unrecorded copy is what stops a blind re-run — and without the pages phase the change is applied only after the live-page gate, so a gate halt leaves nothing behind; a page-backed app's standalone header push refuses a copy still holding an earlier run's unpushed edits (`app-copy-unpushed-edits`) rather than replay them. **An existing app's sitemap is rewritten ONTO its live nodes (AB#6726727).** The App Spec describes a node's label/title, target and icons only, and the SDK serializes a node without its fetched `bag` from scratch (new `Id`, `ResourceId="SitemapDesigner.NewSubArea"`, broad `Client`/`Sku`, `AvailableOffline="true"`). Both existing-app writers (the app-shell write and the pages finalizer) therefore pass appDef's tree through `adoptLiveSitemap` (`scripts/lib/sitemap-merge.js`) first: a subarea corresponds by navigation target (a URL keeps the case of its path and query), an area or group by a label its level uses once, then by the navigation entries it holds, then by the id an earlier build gave it (a node none of these identifies is written as new rather than guessed); the live `id` and `bag` are kept, and only what the spec sets is overlaid — chrome it does not name is still removed, as before. Because the SDK only patches an existing `` on a node with a bag, and reads an empty title as "no edit", a title added to an entry that had none, or removed from one, is reconciled in the adopted bag at the SDK's language (other languages' titles are kept). Every dashboard entry carries exactly `Url="/workplace/home_dashboards.aspx"` — the designer writes it on every dashboard entry and recognizes one only by the whole Url, and the runtime keys the dashboard glyph on it with a case-sensitive match — and verify fails an entry without it (`subarea-dashboard-launcher`, which reads only real nav entries — a `SubArea` directly under `SiteMap/Area/Group`, never one in a comment or elsewhere — as the kept-icon check below does). With a **baseline** — `.maker-workspace/last-applied.json`, written atomically by a successful apply and by download, stamped with its environment and app (`scripts/lib/deployed-baseline.js`) — a nav entry's title/icon that the spec has not changed since, but the designer has, is kept and reported rather than reverted (`keepsLiveValue`); without one the spec wins and every change to an existing entry is reported. Baseline entries are lined up with live ones by the ids the baseline RECORDED for its environment (`__deployedIds`: what the apply resolved, or what the download read), never by the spec's own `dashboardId`/`pageId`, which may be another environment's. Verify accepts a kept icon by the same rule and identities, and only on a live entry that exists. A downloaded dashboard carries `dashboards[].dashboardId`, which build, verify and teardown resolve before the name (`findPinnedDashboard`) — when it resolves it is the only candidate, and teardown still requires solution membership — so a dashboard renamed in the designer is reused, with a warning since a build never renames one, instead of a second being created under the stale name. **DATA-MODEL Dataverse labels are stamped with the ORGANIZATION's base language, not a hardcoded 1033.** `resolveLanguageCode` (`scripts/lib/entity-provision.js`) reads `organization.languagecode` once per build and threads it into every label-emitting SDK call in that phase (tables, columns, customer columns, global choices, status reasons, alternate keys, relationships); precedence is `--language-code` → App Spec `languageCode` → the org's base language → 1033. Without this, an org that has not provisioned 1033 fails the data-model phase with `The language code 1033 is not a valid language for this organization` (#447) — and confusingly only on *some* column types, because (observed 2026-08) Dataverse tolerates an unprovisioned LCID on `EntityMetadata` and `PicklistAttributeMetadata` but rejects it on `DateTime`/`Memo`. Every fallback to 1033 warns, as does an explicitly supplied LCID that had to be discarded. An **explicitly supplied** LCID is additionally checked against `RetrieveProvisionedLanguages` (`readProvisionedLanguages`, `scripts/lib/dataverse-auth.js`, injected as `deps.provisionedLanguages`) and halts the data-model phase before any write if the org does not have it — because of the split behaviour above, the alternative is a table created with silently-wrong labels followed by a failure on the first `DateTime`/`Memo` column. Only *explicit* overrides are probed; the org's base language is provisioned by definition. The probe is best-effort — an unreachable or non-2xx `RetrieveProvisionedLanguages` resolves to `null` ("unknown") and the build proceeds unchanged, so the diagnostic can never itself break a build. Note `updateTable(logical, { quickCreateEnabled })` deliberately passes no language: it only builds a Label when a `displayName`/`pluralName`/`description` is supplied, and otherwise round-trips Dataverse's own labels under `MSCRM.MergeLabels`. **Scope — this now extends to the `forms`, `dashboards` and `app-shell` phases too.** Those go through the vendored SDK's artifact serializers, which used to hardcode `1033` into FormXML (`