@wix/himalaya-cli 0.1573.0 → 0.1574.0

package/guides/himi-json-output.md

@@ -6,7 +6,7 @@ repurposed when human wording changes. New codes may be added; consumers must
 handle an unknown code as a failure, without parsing prose.
 
 **Rollout:** this contract is enforced for **`himi push`**, including `--only`,
-first, for **`himi store iap connect`**, for **`himi site member-app`**, for **`himi fidelity`**, and for the **`himi base44`** entity and function verbs. Other subcommands still have legacy failures without codes and are a
+first, for **`himi store iap connect`**, for **`himi site member-app`**, for **`himi fidelity`**, for the **`himi base44`** entity and function verbs, and for **`himi l10n import`**. Other subcommands still have legacy failures without codes and are a
 follow-up migration. This is an additive change: existing `error`, `errors`,
 `message`, `hint`, status, body, and gate-specific fields stay as they were.
 Some legacy envelopes have no singular `error` or `hint`; consumers must not
@@ -114,6 +114,34 @@ prints neither.
 
 This is not a whole-command migration: the command's other refusals still have no code.
 
+## `himi l10n import` codes
+
+Every refusal from `himi l10n import` carries one of these. Usage-grammar refusals exit 2;
+operational refusals exit 1. A successful import (exit 0) reports `unsupported`,
+`missingInSource`, `converted`, `duplicateSources`, `keyConflicts`, `staleKeys`, `invalidKeys` and `warnings` inside
+its `ok: true` envelope — those are findings, not failures.
+
+| Code | Meaning |
+|---|---|
+| `invalid_usage` | The subcommand, `<dir>` positional, app selector (`--app`/`--content`) or `--locales`/`--source` value is missing or malformed (a bare `--locales` is refused, not read as "all"). Nothing was read or written. Exit 2. |
+| `unsupported_format` | `--format` is missing or names a format other than `oneapp`; `formats` lists what exists. Exit 2. |
+| `app_not_found` | `--app <slug>` is not a slug, or `apps/<slug>/config.ts` does not exist under the current directory. Exit 2. |
+| `messages_dir_not_found` | `<dir>` does not exist or is not a directory. Exit 1. |
+| `no_messages_found` | `<dir>` holds no `messages_<locale>.json` file. Exit 1. |
+| `source_locale_missing` | There is no `messages_<source>.json` — the source locale supplies every row's `source` string, so nothing can be converted without it. `found` lists the tags that do exist. Exit 1. |
+| `locale_file_missing` | A `--locales` tag has no `messages_<tag>.json`; `missing` and `found` name them. Exit 1. |
+| `messages_not_utf8` | A messages file is not valid UTF-8, has a UTF-16 byte-order mark, or contains NUL bytes (a UTF-16 export, even an ASCII-only one, is the usual cause). A UTF-8 BOM is tolerated and stripped. Exit 1. |
+| `messages_unreadable` | The messages directory cannot be listed, or a messages file cannot be read (a directory or a FIFO in its place is refused up front, so the import never blocks on one), is not JSON, is not an object, or has non-string values (`keys` names up to five offenders). Exit 1. |
+| `catalog_unreadable` | An existing `apps/<app>/l10n/<tag>.json` cannot be parsed, or holds a message that is not an object. The import refuses rather than overwrite translations it could not read; the file is left untouched. Exit 1. |
+| `unsafe_path` | A `messages_<locale>.json` inside the messages directory, the app's `l10n` directory, or one of its catalogs is a symbolic link. The import never follows one: it would read a file the translation directory points at into the generated catalog, or write outside the app. Nothing was written. (The directory named on the command line may itself be a link — that is the caller's choice.) Exit 1. |
+| `catalog_write_failed` | Writing a catalog failed, or the app's `l10n` path cannot be inspected or created (for example `l10n` is a regular file); `written` lists what landed before the failure. Exit 1. |
+| `import_failed` | The conversion itself threw on input the earlier checks accepted. Nothing was written. Exit 1. |
+| `invalid_flag_value` | The CLI's global flag grammar refused a flag before the command ran (for example `--overwrite=false`: a switch takes no value). `problems` lists each one. Exit 2. |
+
+This is not a whole-command-group migration: only `l10n import` exists today, and all of
+its refusals are coded — including the global flag-grammar refusal, which carries a `code`
+for `l10n` only.
+
 ## `himi store iap status` codes
 
 Status adds these stable codes to incomplete JSON results. Existing result fields and exit
@@ -143,7 +171,7 @@ existing `problems` list.
 | Code | Meaning |
 |---|---|
 | `screenshots_incomplete` | At least one selected item has no screenshot. Each one in `items` carries a `skipped` reason: no purchase screen, no Apple price yet, an existing screenshot kept without `--force`, a screen that did not show the Apple price, or a failed read of the item. The screenshots that were made are saved and named in the manifest. Exit 1. |
-| `browser_unavailable` | The headless Chromium the screenshots are taken in is not installed. Run `npx playwright install chromium` once. Nothing was rendered or written. Exit 2. |
+| `browser_unavailable` | The headless Chromium the screenshots are taken in is not installed. Run the install command the error names once (it uses the CLI's own Playwright, so it installs the Chromium revision the CLI launches). Nothing was rendered or written. Exit 2. |
 
 An invalid manifest fails with `manifest_invalid`, like the other `store iap` commands.
 
@@ -217,6 +245,17 @@ whole body gzip-encoded because it is over the plain 8 MB cap:
 |---|---|
 | `compressed_publish_unsupported` | The publish body went out gzipped and the publishing service did not accept it compressed. It either read the bytes as malformed JSON, or measured the decompressed body against the 8 MB uncompressed limit (HTTP 413). Either the service does not accept compressed bodies yet, or the credential is a self-serve one, which keeps the 8 MB uncompressed limit. Nothing was written. |
 
+## `himi template screens --upsert` codes
+
+`--upsert` writes many generated screens at once. Its refusals carry a code; nothing is written
+on any of them (a failed batch restores every file). Other `template screens` paths stay legacy.
+
+| Code | Meaning |
+|---|---|
+| `invalid_usage` | `--upsert` was given without `--from <file>`. Exit 2. |
+| `invalid_input` | The `--from` file cannot be read or is not JSON. Exit 2. |
+| `upsert_refused` | The JSON is not `{ "<screenId>": <ScreenDescriptor> }`, an id or `screenId` does not match, the result would not parse as plain SCREENS entries, or a target file is a symlink. `error` names which. Exit 2. |
+
 ## `himi site member-app` codes
 
 `himi site member-app set|clear|show <site>` prints one envelope. A refusal from the publishing service

package/guides/himi-mcp.md

@@ -112,7 +112,7 @@ runs a session with it.
 | `himi_build` | Compile the app's worker bundles. |
 | `himi_validate` | Lint the app without publishing anything. |
 | `himi_test` | The behavioral crawl — every action each screen declares, against the app's mocked network. Never reaches live data. |
-| `himi_render` | Render one screen and return the PNG to the agent (needs Playwright's Chromium: `npx playwright install chromium`). |
+| `himi_render` | Render one screen and return the PNG to the agent (needs Playwright's Chromium: run the install command `himi render --png` prints). |
 | `himi_progress` | Read or add to the build journal the owner follows. |
 | `himi_preview_start` / `_status` / `_stop` | The live preview — see below. |
 | `himi_whoami` | Which account the stored sign-in belongs to. |

package/guides/himi-test.md

@@ -492,8 +492,9 @@ behavior. This instruction does not add an automatic suppression or retry gate t
 
 **Screenshots** are on by default when a headless browser is installed: one PNG per screen
 to `.himi/shots/`, showing the settled state at phone width. Absent browser ⇒ the report
-carries `shots.unavailable` and the ledger names the one-time `npx playwright install
-chromium`. Fully hermetic; `--no-shots` opts out.
+carries `shots.unavailable` and the ledger names the one-time install command for the
+CLI's own Playwright (`node '<CLI>/node_modules/playwright/cli.js' install chromium`; a bare
+`npx playwright install chromium` can install another revision). Fully hermetic; `--no-shots` opts out.
 
 ### Exit codes
 

package/guides/iap-products.md

@@ -411,7 +411,7 @@ product's review screenshot from the app's own purchase screen, so nobody has to
 
 **One-time setup.** The screenshots are taken in a headless Chromium on your machine, so no phone,
 simulator or Xcode is needed. The Playwright library comes with himi; the browser is a separate
-download (~170MB) that you run once: `npx playwright install chromium`. Without it the command stops
+download (~170MB) that you run once, with the install command the CLI prints (`node '<CLI>/node_modules/playwright/cli.js' install chromium`). Without it the command stops
 before rendering anything and says so (`browser_unavailable`). A `--dry-run` doesn't need it.
 
 1. **It renders the screen.** For each item it opens that Wix item's detail screen: `himi_product_<id>`,

package/guides/importing-oneapp-translations.md

@@ -0,0 +1,115 @@
+# Importing OneApp translations
+
+An app moving to Himi from the OneApp engine already has its copy translated: one flat
+JSON file per locale, `messages_<locale>.json`, mapping an engine key to an ICU
+MessageFormat string (`{ "DOWNLOAD_BTN": "Download", … }`). Himi's per-app catalog
+(`l10n/<tag>.json` in the app's content directory) is a different shape, and re-keying
+thousands of strings by hand is error-prone. `himi l10n import` does the conversion:
+
+```bash
+himi l10n import --format oneapp ./strings --app my-app --locales en,he --json
+```
+
+reads `./strings/messages_en.json` + `./strings/messages_he.json` and writes the app's
+`l10n/en.json` + `l10n/he.json` (`--app <slug>` names an app in a checkout; off-repo,
+point `--content` at the app's directory). After the import, a descriptor (or a worker,
+via `t()`) references each message by its OneApp key: `$t:DOWNLOAD_BTN`.
+
+## What it does
+
+- **One catalog per locale**, in the existing shape: rows keyed by the extractor's
+  content hash of the **source-locale** string, each carrying `source` (the `--source`
+  locale's text, default `en`), `key` (the OneApp key — what `$t:<KEY>` resolves) and
+  `translation` (that locale's text; empty in the source locale's own catalog).
+- **Default locales: every `messages_<tag>.json` found** in the directory. `--locales`
+  narrows the list; a requested tag with no file is a refusal, not a silent skip.
+- **Placeholders**: OneApp's legacy `{{name}}` spelling (spaces and hyphens allowed:
+  `{{ name }}`, `{{user-name}}`) becomes ICU `{name}` and is listed under `converted`. A
+  double brace that is not a plain name (`{{first name}}`) is kept verbatim and listed under
+  `unsupported`, because the runtime would paint it literally; so is a `{{name}}` inside an
+  ICU quoted span (`'{{name}}'`), whose braces ICU makes literal. The rewrite walks the
+  pattern with the runtime's own ICU tokenizer and edits the original text in place, so branch
+  order and spacing are preserved (the row id is a hash of that text) and a genuine ICU double brace (`one {{count}} other {{count} files}` — branch brace plus
+  argument brace) is never corrupted.
+- **ICU subset**: each message is parsed with the subset the runtime formats — simple
+  arguments, `plural` with `=N`/`#` (the Hebrew dual included) and `select`. Anything
+  outside it — `selectordinal`, number/date skeletons, plural `offset:`, a plural nested
+  in another plural, a quoted `'#'` inside a plural branch, branch text the tokenizer cannot
+  parse (a stray comma between branches, a quoted brace), a branch selector the runtime can
+  never select (`one {a};other {b}` — the `;other` is part of the key — or a non-canonical
+  `=01`/`=1.0`, which never equals the number), a plural or select
+  with no `other` branch, HTML tags — is kept **verbatim**
+  (the runtime degrades to visible text by contract) and listed under `unsupported` with key
+  and locale.
+- **Merging**: an existing catalog's manual translations and keys survive a re-import
+  unless `--overwrite`; provenance fields and rows the import does not touch survive the
+  import. An existing catalog that cannot be parsed is refused, never clobbered.
+- **Changed source text**: row ids are content hashes, so editing a source string moves its
+  key to a new row. The old row keeps its text (for the source-string swap) but loses the
+  key, so exactly one row answers each `$t:` key; the dropped keys are listed under
+  `staleKeys`. This happens with or without `--overwrite`, and in a target locale whose file
+  has no entry for the key yet. When only the row id moved (the text did not change), the
+  manual translation moves with the key.
+- **The source-string extractor** keeps a prior row only while a descriptor still contains
+  its text or references its key as `$t:`. A key used only from a worker through `t()`
+  therefore needs the import re-run after an extract.
+- **Keys a descriptor cannot reference**: a `$t:` binding accepts letters, digits, `_`, `.`
+  and `-`. A OneApp key outside that (`settings:title`, `Home Header`) is still written —
+  a worker's `t()` takes any string — but listed under `invalidKeys`, since no `$t:<key>`
+  can reach it.
+- **Native rows**: when the app lives inside the Himalaya source checkout, its English
+  catalog also receives the native login-gate rows (the same rows the extractor adds), so
+  the derived-output check stays green; other locales hold translations only.
+- **Symbolic links are never followed**: a `messages_<locale>.json` that is a link, a linked
+  `l10n` directory, or a linked catalog is refused (`unsafe_path`) before anything is read
+  or written, so an untrusted translation package cannot pull another local file into a
+  catalog or redirect a write outside the app. Catalogs are written through a temporary
+  file and a rename, never in place.
+- **Deterministic output**: ids sorted, no timestamp — re-running over the same inputs
+  produces no diff.
+- **Edge cases reported, never silent**: a key present in a target locale but missing in
+  the source is skipped and listed under `missingInSource`; OneApp keys sharing one source
+  string all survive, each on its own row id, and the group is listed under
+  `duplicateSources` (no key keeps the plain id, so a key added later cannot take an id
+  from one already imported).
+
+## The report
+
+`--json` prints one envelope:
+
+```json
+{
+  "ok": true,
+  "written": [{ "tag": "he", "path": "my-app/l10n/he.json", "count": 412 }],
+  "unsupported": [{ "key": "UPDATED_AT", "locale": "he", "construct": "date argument \"when\" (short)" }],
+  "missingInSource": [{ "key": "ONLY_IN_HE", "locales": ["he"] }]
+}
+```
+
+plus `converted`, `duplicateSources`, `keyConflicts`, `staleKeys`, `invalidKeys` and
+`warnings` when non-empty.
+Failures carry a stable `code` — see
+[the JSON failure contract](himi-json-output.md#himi-l10n-import-codes).
+
+## Declare the locales
+
+A catalog only bakes and serves for a locale the app declares, and only `en`, `he` and
+`es` can be declared. The import checks each imported tag against the app's `locale`
+config and warns with the line to add to its `locale` block:
+
+```ts
+translations: ["es", "he"]
+```
+
+A tag outside those three (`fr`, or a region tag like `es-MX`) still gets its catalog
+written, but is warned about separately and is never offered as config — declaring it would
+make the config fail.
+
+`--source` should be the app's default locale: the runtime falls back to a row's source text
+only for the default locale, so importing another locale as the source warns.
+
+## Scope
+
+The importer is generic for any OneApp-format catalog (flat key → ICU string). Fetching
+messages from a translation service, exporting back, and other source formats are out of
+scope — adapters can be added behind `--format` later.

package/guides/index.json

@@ -74,6 +74,12 @@
       "category": "CLI & Loop",
       "file": "himi-json-output.md"
     },
+    {
+      "id": "importing-oneapp-translations",
+      "title": "Importing OneApp translations",
+      "category": "CLI & Loop",
+      "file": "importing-oneapp-translations.md"
+    },
     {
       "id": "himi-mcp",
       "title": "himi in your coding agent (MCP)",

package/guides/one-app-section-mappings.md

@@ -110,8 +110,8 @@ The **Himalaya implementation** cell is blank for every unassigned row. Notes on
 
 | Source sectionDefinitionId | Source viewer component | Himalaya implementation | Placement / reuse | Class | Settings, actions and gaps |
 | --- | --- | --- | --- | --- | --- |
-| `referrals_refer_section` | `referrals.components.ReferWidget` |  |  | Empty | No consumer referral-code/link sharing and referral-status feature was found. Do not map to Loyalty or generic sharing without a user decision. |
-| `referrals_description_section` | `referrals.components.DescriptionWidget` |  |  | Empty | No referral-program description/data implementation was found. Text primitives alone do not resolve the business-bound referral content. |
+| `referrals_refer_section` | `referrals.components.ReferWidget` |  |  | Empty | No consumer referral-code/link sharing and referral-status feature was found. Do not map to Loyalty or generic sharing without a user decision. **Probe first:** `GET /_api/referral-programs/v1/program` answered the One App visitor identity in a 2026-11 migration, and the program copy was built live in an app-local section. The member's own referral link/code was not generated; resolve it before you mark the Refer action supported. |
+| `referrals_description_section` | `referrals.components.DescriptionWidget` |  |  | Empty | No referral-program description/data implementation was found. Text primitives alone do not resolve the business-bound referral content. **Probe first:** `GET /_api/referral-programs/v1/program` answered the One App visitor identity in a 2026-11 migration, and the program copy was built live in an app-local section. The member's own referral link/code was not generated; resolve it before you mark the Refer action supported. |
 
 ### 9. member-list-section-definitions.json
 
@@ -330,8 +330,8 @@ These are the exact definitions whose target cells above remain empty. “Not fo
 | `events-section-definitions.json` | `events_guests_section` | The Events detail has only a best-effort attendee summary/avatar strip using an owner-scoped guest query. It is not a full consumer guest-list section; leave the mapping unassigned. |
 | `groups-section-definitions.json` | `single_group_feed_section` | A feed exists, but it selects a relevant/home group internally and does not accept the configured fixed-group selector. No verified single-group feed adapter exists; keep this target empty until a policy/implementation is chosen. |
 | `loyalty-section-definitions.json` | `loyalty_status_section` | The existing Loyalty worker lists the program and rewards but does not load this member's points balance/tier/status. A rewards catalog is not a loyalty-status widget. |
-| `referrals-section-definitions.json` | `referrals_refer_section` | No consumer referral-code/link sharing and referral-status feature was found. Do not map to Loyalty or generic sharing without a user decision. |
-| `referrals-section-definitions.json` | `referrals_description_section` | No referral-program description/data implementation was found. Text primitives alone do not resolve the business-bound referral content. |
+| `referrals-section-definitions.json` | `referrals_refer_section` | No consumer referral-code/link sharing and referral-status feature was found. Do not map to Loyalty or generic sharing without a user decision. A visitor-readable program read exists; see the row above. |
+| `referrals-section-definitions.json` | `referrals_description_section` | No referral-program description/data implementation was found. Text primitives alone do not resolve the business-bound referral content. A visitor-readable program read exists; see the row above. |
 | `pages-section-definitions.json` | `pages_section` | No matching Wix Pages content fetch/render adapter was found. Generic CMS or RichContent renderers do not identify the original page entity or its data contract. |
 | `photoalbum-section-definitions.json` | `photoAlbums_list_section` | Existing Photo Albums code is an empty-state placeholder with no album API wired. Pro Gallery uses a different data source and is not a substitute; choose an implementation explicitly. |
 | `photoalbum-section-definitions.json` | `photoAlbums_photos_list` | Existing Photo Albums code is an empty-state placeholder with no album API wired. Pro Gallery uses a different data source and is not a substitute; choose an implementation explicitly. |
@@ -377,3 +377,15 @@ These rows have reusable code, but their remaining requirements must not disappe
 ## GitHub implementation references
 
 The linked sources are in private Wix repositories. The inventory and gap decisions above are usable as historical capability evidence without local filesystem references. Links identify implementation code, not production deployment or exact feature parity.
+
+## Definitions outside the pinned inventory
+
+Migrated apps contain section definitions that the pinned inventory above does not list. They are
+outside its 77 definitions and have no verified mapping. Resolve each one with the workflow's probe
+procedure (`himi docs one-app-to-himi-app`, "Probe an unmapped section") and record the result.
+
+| Source sectionDefinitionId | Seen in | Status and leads |
+| --- | --- | --- |
+| `forum_post_list_section` | A 2026-11 Branded migration | Unmapped. A single-section page can point at the Forum template screen; an inline post list needs an app-local section over the Forum posts read. |
+| `shared_gallery_list_section` | A 2026-11 Branded migration | Unmapped and left unresolved in that migration. Do not substitute Pro Gallery or Photo Albums without verifying the source data contract. |
+| `woa_member_restaurants_reservation` | A 2026-11 Branded migration | Unmapped. That migration adapted it to a "Reserve a Table" button that opens the template reservation screen; record it as an adaptation, not as the source section. |

package/guides/one-app-to-himi-app.md

@@ -259,6 +259,16 @@ Apply these interpretation rules:
   a feature to account for; they do not alone prove visibility or access for every
   visitor or member. Resolve those rules separately. This check is specific to this
   migration workflow; it does not change the behavior of `himi validate`.
+  The check maps a source screen to its target **only** through that screen's `route`
+  row (`source: "/screens/<id>"`) in `ONE-APP-COVERAGE.json`, through `target.screenId`;
+  a row of any other kind does not map a screen, and an unmapped source screen is checked
+  under its own id. A control counts only as an entry of `actions`; a matching `topBar.items`
+  entry (a leading profile avatar, for example) does not, because iOS draws no toolbar items
+  yet and web/Android draw only some trailing ones. A `branded-lite` screen
+  that declares its own `topBar` replaces `topBarDefault`, so the shared controls are
+  missing on it: `himi_account`, `himi_shop`, `himi_services`, `himi_agenda`, `himi_events`,
+  `himi_blog` and the CMS collection screens do. Delete that `topBar` so the screen inherits
+  the default, or add every source control to its `actions`.
 - Apply the collected app theme before the first build: run
   `himi one-app validate-design --evidence-dir .himi/one-app --content . --fix`,
   resolve any remaining mismatches/unresolved values, then rebuild. The source is
@@ -486,7 +496,7 @@ reference's top-tabs row in R04 and its top-tabs acceptance case:
 - `missing_icon`: choose an icon that matches the page content and record it as a
   target adaptation. `missing_label`: use a label from the page content and record it.
 - `tab_overflow`: more than five tabs need the explicit overflow arrangement of
-  viewer rule R05. Do not drop tabs to fit the bar.
+  viewer rule R05. Do not drop tabs to fit the bar. See [Large top-tab apps](#large-top-tab-apps).
 - `free_instance_converted`: the source editor offers bottom tabs to Branded apps
   only. Record the converted navigation as a target adaptation in the report.
 - `nested_top_tabs`: a bottom entry holds a `TOP_TABS` screen. It is out of this
@@ -495,12 +505,53 @@ reference's top-tabs row in R04 and its top-tabs acceptance case:
 With `--top-tabs keep`, the plan has `reason: "policy-keep"` and the viewer
 reference's top-tabs rules apply.
 
+#### Large top-tab apps
+
+A source with many top-tab pages (33 in one migration) converts to this arrangement:
+
+- The first four pages in source order are tabs; a fifth **More** tab lists every other
+  visible page in source order, and each row pushes its page. Hidden pages get no row.
+- `appEditor.outline.*` icons with no Himi name (lightning, rocket, light bulb, megaphone,
+  brochure, content card) need a fallback icon from `himi icons`, such as `star`,
+  `bell` or `doc`. Record each fallback as an adaptation.
+- A source `goToScreen` to a page that is now a **tab** must select that tab. A descriptor
+  `himi.open` pushes a second copy of the page instead, so give static pages a small nav
+  worker whose action calls `navigate(s, { tab: "<tabId>" })`. A `goToScreen` to a page
+  in More can use `himi.open`.
+- A `goToScreen` whose layout item does not exist does nothing in the source. Keep it a
+  no-op (a worker action that returns the state unchanged) and list it as an unresolved
+  route.
+- A page whose only section is one vertical (Pricing, Groups, Forum, Events, Programs,
+  Loyalty, Galleries, Shop, Services, Forms) can point at that vertical's template screen
+  instead of a copy. Record its route row against the template screen id.
+- Only the first tab keeps the source header; the others take the compact default bar.
+
 The current [viewer reference](https://apps.wix.com/_api/himi-serve/docs/one-app-viewer.md)
 supersedes simplified historical ordering, routing and layout examples. Pinned
 mapping rows are research leads: inspect the current CLI's component, SDK and
 template contracts before using them. A previously empty row does not prove the
 feature is impossible today.
 
+### Probe an unmapped section
+
+A section whose catalogue row is "Empty", or whose definition is not in the catalogue at
+all, is not unresolved until you probe it:
+
+1. Find the section's data contract: its `sectionDefinitionId`, the source viewer component
+   in the catalogue, and the Wix REST API of that domain (Wix docs or `@himalaya/wix-*`).
+2. Choose a read-only call. Confirm in the service contract that it does not write on read
+   (see the announcement getter above).
+3. Send it through the target transport with the app's One App visitor identity
+   (`himi render --live`, or the hosted preview), not with an owner credential.
+4. A 2xx with the source content means you can build the section app-locally. Record the
+   call, the response shape and the identity in the migration report, and mark the row
+   `supported` or `adapted`. A 401/403/428 for the visitor is an access result: keep the
+   row `unresolved` and record the status.
+
+For example, `GET /_api/referral-programs/v1/program` answers the visitor identity, so
+the referral program copy can be built live. The member's own referral link is a
+separate, member-scoped contract.
+
 ### Standalone launch tab
 
 When the reconstructed navigation has a tab bar, preserve the app's actual tab
@@ -708,6 +759,22 @@ For a marked One App migration, `himi validate --strict` fails when the icon is
 missing, still byte-identical to a bundled template, or its pixel checks cannot run. A passing mechanical check
 cannot establish ownership of arbitrary custom artwork; compare the real mark too.
 
+Expect a large ledger: a 33-page app had 796 rows, 396 of them top-bar controls. Map it
+in batches with the executable ledger mapping recipe above, not by hand. Each row's
+`source` is a JSON pointer into `raw-structure.json`, and the shape says what to set:
+
+| `source` shape | `target` |
+| --- | --- |
+| `/screens/<id>` (`route`) | `{ "screenId": "<target>" }`. `validate-topbar` maps screens only through these rows. |
+| `/screens/<id>/layout/items/<i>` | the target screen of that layout item (a top-tab page). |
+| `…/layout/items/<i>/elements/<j>` | that page's screen; an `interaction` row also names the `control` (the section's element id). |
+| `/screens/<id>/topBar/…` | the screen, and the `control` id of the matching top-bar action (`cart`, `notifications`, `chat`, `profile`). |
+| `/sections/<id>` | the screen of the page that holds that section. |
+| `/businessProfile…` | the business-profile screen. |
+
+Decide per row, and let the recipe list every row it could not map or decide. Never
+invent a status for an undecided row. Run `coverage check` after each run.
+
 Map each row to a target screen and, for interactions or top-bar controls, a
 target control. A `design` row is app-wide, so it needs no screen or control: it is
 satisfied by the design check instead. Set its `status` to `supported`, `adapted`, `conditional`, or
@@ -843,6 +910,31 @@ not share mutable filters accidentally. Keep static authored content in the app,
 and products, services, availability, posts and member records live on the same site.
 Refresh data after operations without reconnecting layout to the One App editor.
 
+### Write generated screens as static SCREENS entries
+
+`himi template trim`, `himi template screens --show/--write` and
+`himi one-app validate-topbar` read `dev/index.ts` statically. They see only plain
+`"<screenId>": { "screenId": "<screenId>", … },` entries inside the `SCREENS` literal.
+A screen merged in at runtime (`Object.assign`, an imported module), a spread, or a
+function call in the literal makes them fail with "expected a `"<screenId>": {` entry",
+"homeScreenId … is not a screen in the SCREENS map" or "no target screen mapping to an
+authored descriptor". Blank lines and whole-line `//` comments between entries are
+accepted.
+
+So generate descriptors as data and write them with the CLI:
+
+```sh
+himi template screens --upsert --from .himi/one-app/gen/screens.json
+```
+
+The file is one JSON object, `{ "<screenId>": <ScreenDescriptor>, … }`. Each existing
+id is replaced in place; each new id is added and registered in
+`navigation.linkableScreens`. One invalid entry refuses the batch and restores every
+file. A builder call such as `detailedHeader(...)` written inline in `dev/index.ts`
+cannot be inspected: call the builder in your generator and serialize the value it
+returns. Run the generator inside the app (after `npm install`), so
+`@wix/himalaya/screens` resolves to the app's own dependency.
+
 ### Screen-content contract
 
 Use the current [screen design guide](https://apps.wix.com/_api/himi-serve/docs/designing-himi-screens.md) and the app's
@@ -942,7 +1034,12 @@ a new destination to read the site's current data; never invent or retain a temp
 Use `siteUrl` from the successful collection's manifest for the auth binding. It is
 the first usable value from `website.publicUrl`, then legacy `website.url`: an HTTPS
 origin and optional base path, with no credentials, custom port, query or fragment.
-`site client ensure` does not return it. Keep visitor/member gates from the reconstruction plan. Verify that the
+`site client ensure` does not return it.
+With the One App binding, `himi push` bakes the current product and service detail
+screens through the site's One App visitor instance. A `dev/index.ts` scaffolded by an
+older CLI reads only `clientId` for this, so it bakes no detail screens; the preview
+still resolves them live.
+Keep visitor/member gates from the reconstruction plan. Verify that the
 built app reads the intended site (and, with a client, uses the exact registered
 redirect). The MetaSite and a public client ID are app configuration; the collection
 credential is not.
@@ -987,8 +1084,15 @@ as unverified in the migration report.
 
 The UX audit requires app-specific network fixtures. `himi test --record` records
 only boot-time reads with the app's visitor identity, then crawls hermetically.
-Review its recorded/refused requests; do not run a source getter known to mutate
-on read (such as the legacy announcement default getter). Keep actual recordings
+Before you run it, run `himi template inspect` and read `.himi/adopt.json`
+`bootRequests[]`: every entry is a screen that can request when it appears. An entry
+with `trigger: "module-load"` is a worker that calls an action while its module
+evaluates (`svc.load();` at the bottom of the file — the pattern every migration
+worker uses); the screen descriptor names nothing, but the read runs as soon as the
+screen boots the worker. Each boot path must be a catalogue or directory read.
+Stop if one submits, orders, books, pays, or calls a getter known to mutate on read
+(such as the legacy announcement default getter). Then review the recorded and
+refused requests. Keep actual recordings
 under `.himi/one-app/fixtures/net-mocks.json`. For local test/render discovery,
 make `dev/net-mocks.json` a relative symlink to that private file: the source
 archiver skips symlinks as well as `.himi/`. Verify the archive excludes both
@@ -996,19 +1100,56 @@ before publishing. Portable fixtures committed as regular files must instead be
 synthetic test data; do not publish source catalogs, member records or credentials
 as test evidence. Re-run affected checks after changing fixtures.
 
+`himi push` refuses with `headless_run_failed` while `himi test` has an error finding,
+including one on an inherited template screen. Boot-only fixtures cannot cover a read
+that a tap starts (for example, choosing a category on `himi_shop`), so the hermetic
+crawl reports it stuck on loading although it works live. Reproduce it live first
+(`himi run` or the hosted preview). If it works, add a fixture for that read, or add a
+`himi-test.json` `skip[]` entry with the `screen`, `action`, `invariant` and a `reason`
+that states the live evidence (date, data shown). If it fails live, fix it. Never push
+with `--force` to pass this gate.
+
+In `SPEC.md` `## Data access`, name an inherited template write the way `himi test`
+reads it: its action (`selectCategory` or `tier5.himiBrandedShop.selectCategory`), its
+endpoint (`POST /stores/v3/products/query`, with `*` for one path segment), or its
+capability or kind (`payment`, `signup`). Prose approves nothing.
+
 Render and inspect actual reconstructed screens at compact and wider widths,
 including loading, empty, error and denied states. Compare the source's resolved
 design and composition; when source visual evidence is available compare matched
 locale, platform and data state. Record actual visual evidence and any native
 platform not exercised; never infer native parity from a web screenshot.
 
+Known web limits:
+
+- A short screen paints its root background only as tall as its content; below it the
+  web host shows its own (light) background. On a dark source, check a short page and
+  record the difference; native fills the screen.
+- `himi render --png` needs the Chromium of the Playwright that `himi` bundles. Run the
+  install command the render hint prints. A bare `npx playwright install chromium`
+  from the app directory can install another revision.
+- A Detailed header (`CollapsingHeader`) scrolls with the page in current releases. An
+  older CLI drew it in a 640px scroll box, so the page scrolled inside it and
+  `himi render --png` showed only the first viewport; update the CLI before you compare.
+- The One App editor preview shows demo data for member widgets ("This is a demo image
+  and won't appear live") and draws some vertical pages blank. It is not a live baseline:
+  compare against the published app or the source evidence instead.
+
+Fonts follow the typography rules of the design check in step 1: a source family Himi
+does not ship is replaced only with the owner's explicit instruction, recorded as an
+`adapted` design row. Also resolve every other pointer the report lists under
+`notCompared` (button `uppercase`, for example); a passing design check does not cover them.
+
 Record actual mobile UX checks for the current release, then audit them. For each
 platform driven, use `himi ux record --platform ios --status passed --checks <actual-checks>`
 (or `android`, and `failed` for a real failure). An unavailable platform requires
 `himi ux record --platform android --status unavailable --reason "<actual limitation>"`
 and no fabricated checks. Resolve failures, run `himi ux audit --strict`, and keep
 these records bound to the final content immediately before push. An edit changes
-the release; repeat the affected checks and record that content. Never bypass this
+the release; repeat the affected checks and record that content. Any content change
+(a fixture, a trimmed screen, a recompressed icon) makes a new release hash, so redo
+`himi ux record` and `himi one-app validate-design --record --release-hash <new>` as
+the last step before `himi push`, after every size or test fix. Never bypass this
 gate with `--force` or claim an unavailable native platform passed.
 
 Once the implemented app passes its available checks, publish only a draft:
@@ -1017,11 +1158,27 @@ Once the implemented app passes its available checks, publish only a draft:
 himi push --draft --target bo
 ```
 
-Keep the editable source archive included. If publication returns
-`publish_body_too_large`, remove unused generated definitions or apply lossless
-asset compression, then repeat affected validation. Prove emitted screens or
-decoded pixels are unchanged. Do not use `--no-source` or remove authored features
-to fit the upload limit; report a remaining size blocker instead.
+Keep the editable source archive included. The publish body is limited to 8,388,608
+bytes. It is about base64(source archive + worker bundles + assets + icons) plus the
+descriptor JSON, so a large app can exceed it: one 33-page migration measured
+11,259,935 bytes. Measure early, not at the end: after `himi build`, add up
+`dist/bundles/*`, the icons and a zip of the content directory without the excluded
+paths below. `himi push` refuses an oversized body locally, before it sends anything,
+with `publish_body_too_large`; its `breakdown`
+gives each part's bytes (`appSource`, `screens`, `bundles`, `assets`, `icon`, `other`)
+and the largest entries by name. Reduce it in this order, and repeat affected
+validation after each step:
+
+1. Trim the template screens the plan does not use, and the ones a reconstructed page
+   replaced (`himi template trim --keep …`). Their descriptors and workers ride the body.
+2. Recompress images losslessly (the 1024 icon is in the body and in the archive). Prove
+   the decoded pixels are unchanged.
+3. Remove unused generated definitions.
+
+The archive already leaves out `.himi/`, `.claude/`, `.agents/`, `HIMALAYA.md`,
+`node_modules/`, `dist/` and symlinks. Do not use `--no-source` or remove authored
+features to fit the upload limit; report a remaining size blocker with the breakdown
+instead.
 
 Use the target's existing authentication flow when needed. Capture the returned
 release and hosted preview URL, then open that exact URL in the browser and verify

package/guides/qa-builds.md

@@ -1193,7 +1193,8 @@ himi dist --app <app> --platform android --aab --wait --target bo
   activates a draft release: `GET /v1/admin/site/store-build-check?app=&site=[&shell=]` answers
   `200 { ok: true, android: { packageName } }` or the same refusals, through `CheckIfBuildIsAllowed`,
   so it locks nothing. It names no release, so it cannot give
-  `409 release_predates_store_builds`; a draft the editor just built is on a current commit. It never
+  `409 release_predates_store_builds`; a draft the editor just built is on a current commit. It is
+  not sent the App name and icon either, so it cannot give their refusals (below). It never
   falls back to the locking call.
 - **A Containers app's TestFlight build is an App Store build.** For an app bound to a Wix site,
   `--platform ios --destination testflight --version <x.y.z>` with no `--signing` builds the app for
@@ -1226,6 +1227,25 @@ himi dist --app <app> --platform android --aab --wait --target bo
   502 (the prepared files failed Himalaya's checks, the check's code in `reason`: a fix on Wix's
   side, not a retry), `store_builds_unavailable` 503. A named `--signing byo` keeps the
   customer-signed path above, from the site's legacy BuildSecrets.
+- **A store build ships under the owner's App name and icon.** Both store builds above (a Containers
+  app's `--aab` and its TestFlight build) need `appName` and `appIconUrl` on `POST /v1/admin/dist`
+  (`himi dist --app-name <name> --app-icon-url <url>`): the App name and App icon the owner set in
+  the Containers editor, which the Containers server reads off the project and sends. They win over
+  the release's app-config `name` and icon, which the generation agent picked. Any other build
+  takes them too when they are sent, and keeps the release's when they aren't. The name is trimmed,
+  1 to 200 characters, with no control characters and no `$` (Xcode would expand `$(NAME)` from the
+  pool's environment into the binary), and can't start with `@` or `?` (Android would read it as a
+  resource reference). The icon must be a Wix Media file, exactly
+  `https://static.wixstatic.com/media/<file>`. Its 1024x1024 PNG rendition
+  (`<url>/v1/fill/w_1024,h_1024,al_c,q_100/icon.png`) is fetched and checked last before the store
+  id is locked, and again when the pool reads its contract (`GET /v1/dist/contract`), twice at most.
+  If it can't be read then, the contract answers `503 app_icon_unavailable` and the build fails,
+  rather than baking the release's or the shell's icon. iOS gets the icon re-encoded with no alpha
+  channel, which App Store Connect refuses. The job records `appInfo`, and
+  `GET /v1/owner/rebuild-reasons` reports `app_name` and `app_icon` as `unknown` for such a build.
+  Refusals, each with `code` equal to `error`: `store_build_app_info_missing`, `app_info_incomplete`
+  (one without the other), `invalid_app_name`, `invalid_app_icon_url` and `app_icon_invalid` (not a
+  1024x1024 PNG a platform can use) 400, `app_icon_unavailable` 503 (Wix Media couldn't be read).
 
 **Why the Wix production key, and only for the bundle.** There are two Android keys: the committed
 QA keystore and the Wix production key (WixOne). WixOne is the Play **upload** key every Branded

package/guides/templates.md

@@ -106,8 +106,9 @@ details beside the app:
 | `.himi/himi-test.stub.json` | a typed-journey skeleton per form (every field, then its submit) with `<FILL>` slots |
 
 `bootsOffline` is the consent preflight: it is `false` when any screen's `onAppear` dispatches into
-a worker that can reach Wix or the network, and `bootRequests` names each one. It is static and errs
-on the safe side ("may request"). The commands behind it:
+a worker that can reach Wix or the network, or when a screen boots such a worker that calls an
+action while its module evaluates (`svc.load();` at the top level). `bootRequests` names each one,
+with `trigger: "onAppear"` or `"module-load"`. It is static and errs on the safe side ("may request"). The commands behind it:
 
 ```sh
 himi template recommend --text "a salon where clients book and buy products"   # rank the catalog (or --verticals / --book)

package/guides/testing-himi-apps.md

@@ -267,7 +267,7 @@ render, local browser, zero network. `--no-shots` opts out (sweeps should).
 
 Absence is said, never silent: without the browser the report carries
 `shots.unavailable` and the ledger names the one-time remedy —
-`npx playwright install chromium`. Web fidelity, honestly named: these are the web
+the install command `himi render --png` prints. Web fidelity, honestly named: these are the web
 renderer's pixels; native truth still comes from a device (`himi push` a preview).
 
 Hygiene: a **full** run owns `.himi/shots/` and clears it first, so a deleted screen

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1573.0",
+  "version": "0.1574.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
-    "@rive-app/canvas": "^2.21.0",
+    "@rive-app/canvas": "2.38.3",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "cheerio": "^1.0.0",
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "39a44e1a057f7d34899d550863397025bfdec7b4f241a6e45b677246"
+  "falconPackageHash": "3931950af337466648e08fa667462e52b854969f6441f512f82b9241"
 }