@wix/himalaya-cli 0.1432.0 → 0.1434.0

package/guides/base44-app-context.md

@@ -55,7 +55,7 @@ listed in `gaps[]`.
 
 | Mode | How | Stored where |
 |---|---|---|
-| Interactive | `himi base44 login` runs Base44's device sign-in. You approve a code in the browser, and only read access (`apps:read`) is asked for | `~/.himi/base44/session.json`, mode 0600 |
+| Interactive | `himi base44 login` runs Base44's device sign-in. You approve a code in the browser, and only read access (`apps:read`) is asked for. `--write` also asks for `apps:write`, which only the provisioning verbs need ([base44-entities](base44-entities.md#provisioning-create-seed-deploy)) | `~/.himi/base44/session.json`, mode 0600 |
 | Reuse the Base44 CLI's session | `himi base44 login --from-base44-cli` imports what `npx base44 login` stored | the same file |
 | CI | `BASE44_ACCESS_TOKEN=<token>` in the environment | nowhere, it is read from the environment |
 

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

@@ -61,8 +61,8 @@ whose `Task` entity anyone may read and write:
 
 | Tab | Screen | Worker | Pattern it shows |
 |---|---|---|---|
-| Tasks | `b44_tasks` | `tasks` | list, create, bulk-create, update, delete; loading / empty / error / ready; pull to refresh |
-| (pushed) | `b44_task` | `task` | read one row by its id (a nav param), edit, delete then go back |
+| Tasks | `b44_tasks` | `b44-task-list` | **generated** by `himi base44 screens`: list, create, delete; loading / empty / error / ready; pull to refresh |
+| (pushed) | `b44_task` | `b44-task` | **generated**: read one row by its id (a nav param), edit, delete then go back |
 | Functions | `b44_functions` | `functions` | `functions.invoke(name, payload)` with the reply and the error painted |
 | Account | `b44_account` | `account` | Native Google sign-in (requires tenant app-link associations), email + password and emailed-code sign-in, register, reset, profile, sign out |
 
@@ -89,10 +89,14 @@ Turn the book's entities and functions into an adopted declaration, then wire it
 himi base44 adopt --content . --book ../.himi/base44-book --write   # the book step 1 wrote, one level up → base44-entities.ts (never overwrites)
 ```
 
+The starter's `config.ts` declares the sample `Task` as a local `const base44Entities = [...]`.
+Delete that declaration, then import yours in its place (keeping both fails with "Identifier
+'base44Entities' has already been declared"):
+
 ```ts
 import { base44Entities, base44Functions } from "./base44-entities.js";
 // …
-base44: { appId: "<id>", entities: base44Entities, functions: base44Functions },
+base44: { appId: base44AppId, entities: base44Entities, functions: base44Functions },
 ```
 
 `himi validate` then lints the declaration (`pass: "base44"`), and `himi base44 entities query`
@@ -112,15 +116,21 @@ until you do. See [`base44-sdk`](base44-sdk.md#typed-rows).
 
 ## 3. Plan the screens from the book
 
+`himi base44 screens` (step 4) applies the rules below for you, so this step is about choosing
+**what to declare**: which entities, in what order (with up to three entities each gets a tab; with
+four or more, the first two get tabs and the rest go under More), which fields and which `rls`. The rules describe what the generator emits. Read them to predict the result, and to
+know what to customise afterwards.
+
 Write `.himi/screen-plan.md` before editing code. For each entity in `book.entities`:
 
 1. **Decide whether it gets a tab.** An entity that a top-level route reads (`routes[].entities`)
    and that a user browses gets a tab. A child entity (one whose rows only make sense under a
    parent, such as `OrderItem` under `Order`) gets a section on the parent's detail screen
    instead. Keep to 3–5 tabs. Account always takes one when the app is not public (step 5).
-2. **Pick the list row.** The title is the first `required` string field, preferring one named
-   `title`, `name` or `label`. The subtitle is one or two short fields (a status `enum`, a date, a
-   number). Never put a long text field in a row.
+2. **Pick the list row.** The title is the entity's `displayField` if it declares one, else the
+   first `required` string field, preferring one named `title`, `name` or `label`. The subtitle is
+   one or two short fields (a status `enum`, a date, a number). Never put a long text field in a
+   row.
 3. **Pick the detail and form fields** from each field's JSON Schema type:
 
 | Field (`type` / `format` / `enum`) | Detail shows | Form control |
@@ -129,20 +139,28 @@ Write `.himi/screen-plan.md` before editing code. For each entity in `book.entit
 | `string` + long text (`description`, `notes`, `body`, …) | `Text` with `maxLines` | `TextField` with `multilineMaxLines` |
 | `string` + `enum` | `Badge` / `Text` | `SegmentedControl` (≤ 4 values) or `Picker` |
 | `string` + `format: date` / `date-time` | formatted `Text` | `DatePicker` |
-| `string` + `format: email` / `uri` | `Text`, tap opens mail / URL | `TextField` with `keyboard: "email"` / `"url"` |
+| `string` + `format: email` / `uri` | `Text` (the generator does not make it tappable yet) | `TextField` with `keyboard: "email"` / `"url"` |
 | `string` holding an image URL (`image`, `photo`, `avatar`, `*_url`) | `Image` | read-only, see [file upload](#what-the-sdk-cannot-do) |
 | `number` / `integer` | `Text` (with unit) | `Stepper` (small ranges) or numeric `TextField` |
 | `boolean` | `Badge` or `Text` | `Toggle` |
-| `array` of strings | `FilterChips` / `ChipsInput` (read-only) | `ChipsInput` |
-| `object` / nested `array` of objects | a sub-section of rows | none at first. Edit it on the web app |
+| `array` of strings | comma-joined `Text` | `ChipsInput` |
+| `object` / nested `array` of objects | its JSON as `Text` (a sub-section of rows is yours to build) | none. Edit it on the web app |
 | built-ins `id`, `created_date`, `updated_date`, `created_by` | "Created …" metadata row | never editable |
 
 4. **Respect the entity's rules.** `rls` (and field-level `rls`) decide what the signed-in user
-   may do. Offer only the writes `BOOK.md` lists for the entity. An operation whose rule is
-   `false` gets no button. A rule that is a condition (`{ "created_by": "{{user.email}}" }`)
-   means the write only works for a signed-in user, on their own rows, so it belongs behind
-   sign-in (step 5). A denied call still fails with Base44's message, and every screen must paint
-   that error rather than swallow it.
+   may do. Declare the `rls` `BOOK.md` lists for the entity. The generator gates each write
+   control on its operation's rule (falling back to the entity-level `write` rule):
+
+   | Rule | Control |
+   |---|---|
+   | `false`, or absent | not emitted at all |
+   | `true` | always shown |
+   | exactly `{ "created_by": "{{user.email}}" }` or `{ "created_by_id": "{{user.id}}" }` | shown only on the signed-in user's own rows |
+   | any other condition | shown only when signed in |
+
+   A field whose field-level `rls.write` is not `true` is read-only in the form. The gate is
+   advisory: a denied call still fails with Base44's message, and every screen paints that error
+   rather than swallowing it.
 5. **Use the sample rows** (`sampleRows`, already redacted) to size rows and choose the subtitle,
    never as data the app ships.
 
@@ -151,22 +169,48 @@ Compose each screen with [`designing-himi-screens`](designing-himi-screens.md)
 
 ## 4. Build one list + detail per entity
 
-Copy the Task pair and rename it. For an entity `Project`:
+Declare the entity, then generate its screens:
+
+```bash
+himi base44 adopt --content . --book ../.himi/base44-book --write   # or declare by hand (step 2)
+himi base44 screens --content . --json
+```
+
+For each entity in `config.ts` `base44.entities`, `himi base44 screens` writes a list screen
+(`b44_<plural>`, e.g. `b44_projects`) and a detail screen (`b44_<name>`, e.g. `b44_project`):
+
+- `tier5-src/_shared/b44-<entity>-plan.ts`: the plan (row title and subtitle, facts, form
+  controls, write gates) the rules in step 3 produce. The list, the detail and the descriptors all
+  read it, so this is the file to customise.
+- `tier5-src/b44-<entity>-list/index.ts` and `tier5-src/b44-<entity>/index.ts`: one-line worker
+  entries over the template's shared engine (`_shared/entity-list.ts`, `_shared/entity-detail.ts`).
+  Each entity gets its own bundle and service, so two entity tabs never share state.
+- `dev/entities.generated.ts` and `config.entities.generated.ts`: the screen registrations and the
+  `linkableScreens` / `tabBar` items. `dev/index.ts` and `config.ts` already import them.
+
+The first three entities in config order get a tab, in front of Functions and Account. With more,
+the last entity slot becomes a generated `b44_more` screen listing the rest, so the bar never has
+more than five items. Ids pluralise naively (`Category` → `b44_categories`, `Person` →
+`b44_persons`); give the entity a `title` for the visible name. Two entities that would share an id
+are refused with `code: "entity_id_collision"`.
+
+Re-running is safe. Each generated file starts with
+`// @generated by himi base44 screens — sha256:<hash>`:
+
+- an unchanged config reports every file `unchanged` and writes nothing;
+- a generated file you edited by hand (its body no longer matches the hash) is reported
+  `skipped-edited` and left alone, and the command still exits 0. Pass `--force` to overwrite it;
+- files for an entity you removed from `config.ts` are reported in `orphaned[]` and never deleted.
+
+`--dry-run` reports the same outcomes without writing. Failures carry a top-level `code`
+(`no_entities_block`, `entity_id_collision`, `content_dir_not_base44_starter`), per
+[`himi-json-output`](himi-json-output.md). The generator never calls Base44.
 
-- `tier5-src/projects/index.ts` from `tier5-src/tasks/index.ts`. Set `ENTITY = "Project"`, the
-  service name (`b44Projects`), and `toRow()` for the fields you chose. Keep the structure:
-  module-eval `load()`, the `latestList` sequence that drops stale replies, the `pendingWrites`
-  guard, and `derive()` producing the `hide*` flags.
-- `tier5-src/project/index.ts` from `tier5-src/task/index.ts`. `inputId()` reads the row id from
-  the nav param, `get(id)` loads it, and `remove` returns `navigate(…, { presentation: "back" })`
-  from the action the host dispatched.
-- In `dev/index.ts`, a `projects()` and a `project()` builder (copy `tasks()` and `task()`), each
-  bound with `bundle: "<worker dir>"` and `declaredCapabilities: ["base44"]`. Register both in
-  `screens.exact` and the tab root in `seed.screens`.
-- In `config.ts`, a `linkableScreens` entry for each (the detail with `paramKeys: ["id"]` and its
-  list as `parentScreenId`) and a `tabBar` item for the list.
+To change a screen beyond what the plan expresses (a filtered list, a child section, a custom
+action), edit its generated entry or plan. The edit makes the file `skipped-edited`, so the
+generator leaves it alone from then on.
 
-The calls a worker makes, all on `entities("<Name>")`:
+The calls the engine makes (and a customised worker can make), all on `entities("<Name>")`:
 
 | Need | Call |
 |---|---|
@@ -187,7 +231,9 @@ Rules that keep it correct:
   `$item.openLabel`. `himi validate` flags this as an error.
 - **Every write re-lists**, and a failed write keeps the list on screen with the error above it.
   Only a failed *first* list is the error state.
-- Remove `tasks` / `task` once your own entities replace them, and change `homeScreenId`.
+- Replace the sample `Task` declaration with your own entities and re-run `himi base44 screens`.
+  The home screen is the first entity's list. The generator reports the sample's files as
+  `orphaned`; delete them by hand.
 
 ## 5. Auth: the Account tab
 

package/guides/base44-entities.md

@@ -1,4 +1,4 @@
-# Base44 entities and functions (declare, lint, adopt, query)
+# Base44 entities and functions (declare, lint, adopt, query, provision)
 
 A Himi app on [Base44](https://base44.com) names the entities and backend functions it depends on
 in `config.ts`. With that declaration, `himi validate` lints it, `himi base44 adopt` writes it from
@@ -8,8 +8,9 @@ This is the Base44 sibling of [`cms-collections`](cms-collections.md) (`himi doc
 It reuses the same ideas (owned versus adopted, an offline lint, a read-only drift report) but not
 the same block: Base44 field types, access rules and naming differ from Wix Data.
 
-> **Read-only in this release.** Nothing here writes to a Base44 app. Creating schemas, seeding
-> rows and deploying functions come next (see [Coming next](#coming-next)).
+> **Writes are separate and deliberate.** `adopt`, `query` and the lint never write to a Base44
+> app. Creating schemas, seeding rows and deploying functions are their own verbs. Each one prints
+> a plan and writes only with `--yes` (see [Provisioning](#provisioning-create-seed-deploy)).
 
 ## The block
 
@@ -35,7 +36,7 @@ Each entity is one of two kinds:
 
 | Kind | Declared by | Physical entity | himi may |
 |---|---|---|---|
-| **Owned** | `name: "Note"` (alphanumeric) | `Himi<AppPascal>Note`. For app `todo` that is `HimiTodoNote`, and for `video-courses` it is `HimiVideoCoursesNote` | create, seed (coming next) |
+| **Owned** | `name: "Note"` (alphanumeric) | `Himi<AppPascal>Note`. For app `todo` that is `HimiTodoNote`, and for `video-courses` it is `HimiVideoCoursesNote` | create, seed |
 | **Adopted** | `base44Name: "Customer"` | `Customer`, verbatim | read only |
 
 Base44 entity names are alphanumeric only, so the CMS `himi_<app>_` prefix cannot be used. The
@@ -140,11 +141,119 @@ makes is a `GET`.
 
 Failure codes are listed in [`himi-json-output`](himi-json-output.md#himi-base44-entities-codes).
 
+## Provisioning: create, seed, deploy
+
+```bash
+himi base44 login --write                     # once: a session with apps:read apps:write
+himi base44 entities create --app todo        # the plan: create / update / unchanged / refused per entity
+himi base44 entities create --app todo --yes  # send it
+himi base44 entities seed --app todo --yes    # fill EMPTY owned entities
+himi base44 functions deploy --app todo --yes # ship owned functions
+```
+
+`--app <slug>` resolves to `apps/<slug>/`, and `--content <dir>` points anywhere. Without `--yes`
+each verb makes only reads and sends no write.
+
+**Base44's schema write is a destructive full-set sync.** `PUT /api/apps/<id>/entity-schemas`
+with `{ entityNameToSchema }` **deletes every entity the body leaves out**, along with its rows.
+Base44 has no read for schemas. So `entities create` downloads the live project (the same eject
+read as `query`) and builds the body from every entity in it:
+
+- Owned entities are built from `config.ts`.
+- Every other entity is passed through as the exact schema object the download holds. It is never
+  rebuilt, renamed, changed or dropped.
+
+A **live** entity counts as owned only if `base44-provisioned.json`, beside `config.ts`, records
+that this app provisioned it. `entities create` keeps that file up to date. **Commit it** like a
+lockfile, so every machine and CI agrees on what the app owns. A bare prefix is not enough on its
+own. If app `todo` (`HimiTodo…`) declares `ListNote`, that names the entity app `todo-list` owns
+as `Note` (`HimiTodoListNote`). So:
+
+- A declared entity that already exists but is not in the file is refused with
+  `owned_entity_unclaimed`. If it really is this app's, record it in the file; otherwise rename the
+  declaration.
+- An undeclared entity in the namespace that the file does not list is left untouched and listed
+  in `warnings`.
+- When a sync's outcome is uncertain (a lost reply, a 5xx, a reply with no `deleted[]`),
+  `entities create` re-reads the app and records only the creates that are live, and keeps every
+  name the file already held. If that re-read fails too, nothing new is recorded, and the next run
+  refuses the entity with `owned_entity_unclaimed`, which you fix by recording it by hand.
+- `entities seed` only writes entities the file lists.
+
+If any entity file in the download fails to parse, or the source walk drops it (a symlink, a
+denied name), the snapshot counts as unreadable. A sync without that file would delete the
+entity.
+
+```mermaid
+flowchart TD
+  A[entities create] --> Y{--yes?}
+  Y -- yes --> S{token has apps:write?}
+  S -- no --> R1[write_scope_missing<br/>no request]
+  S -- yes --> C
+  Y -- no --> C["GET …/eject → every live entity, verbatim"]
+  C -- failed --> R2[schema_snapshot_unavailable]
+  C -- no entities, no --empty-app-ok --> R3[schema_snapshot_empty]
+  C --> P["plan: foreign as-is + owned from config"]
+  P -- a foreign entity missing or altered --> R4[would_delete_foreign_entity]
+  P -- owned entity / field dropped, no --allow-destructive --> R5[owned_*_removal_needs_flag]
+  P -- no --yes --> D[print the plan, exit 0]
+  P -- --yes --> H[re-read the eject, re-plan]
+  H -- plan differs --> R6[snapshot_changed]
+  H -- same --> I["one PUT …/entity-schemas"]
+  I -- deleted[] names an entity the plan kept --> R7[foreign_entity_deleted]
+  I --> K[created / updated / unchanged]
+```
+
+Every refusal except the last one happens before the `PUT`.
+
+- `--allow-destructive` lets an **owned** entity or field be removed. It only reaches entities this
+  app provisioned, never another app's.
+- `--apply-permissions` writes a changed owned `rls` (entity- or field-level). Without it the live
+  rules are kept and the difference is reported as `permissions` drift. A rule the declaration
+  does not state never clears a live one.
+- `--empty-app-ok` accepts a download with no entities. An empty app cannot be told apart from a
+  failed read, so this has to be opted into.
+
+Because this is a full-set sync, an entity added in the Base44 builder between the plan and the
+`PUT` is caught by the re-read (`snapshot_changed`). Whether the eject download always reflects
+builder edits that were never exported is not yet proven against a live app. Before the first
+live `--yes`, check it on a throwaway app: add an entity in the builder and confirm `entities
+create` lists it.
+
+**`entities seed`** checks each owned entity with `GET …/entities/<E>?limit=1`:
+
+- An empty entity gets one `POST …/entities/<E>/bulk` with its rows.
+- An entity that already has rows is skipped with `skipped: "not-empty"`.
+- An adopted entity is never read or written.
+
+Rows from `base44-seed.json` take precedence over `config.ts` `seed`. Only declared keys are sent,
+so a row cannot set `id` or `created_by`. `--ai` writes placeholder rows to `base44-seed.json`
+offline and returns an `agentPrompt` for the agent to rewrite them, exactly like `himi cms seed
+--ai`.
+
+**`functions deploy`** reads each owned function from `base44/functions/<name>/`. The entry file is
+`entry.ts` or `entry.js`, or the one `function.jsonc`'s `entry` names. The folder is read with
+`himi push`'s own walk: symlinks are never followed, the deny-list applies, and the secret scan
+runs. Anything those flag refuses the deploy with `function_source_unsafe`. Each function is sent
+with
+one `PUT …/backend-functions/<name>` and body `{ entry, files, automations? }`. It never uses the
+bulk `PUT …/backend-functions`, which deletes the functions it omits, and never sends `DELETE`.
+
+Owned functions keep their plain `name`, so every deploy adds a `.himi-owned` marker file naming
+the app. A deployed function with a declared name that lacks this app's marker is refused with
+`function_name_taken` and nothing is deployed. That covers a function built in the builder,
+another himi app's function, or a listing that returns no files. A listing with no `functions`
+array is refused outright and is never read as "nothing deployed".
+
+**Scope.** The default `himi base44 login` stays `apps:read`, so the analyzer and `query` keep
+least privilege. `--yes` on any of these verbs needs a token whose `scope` claim includes
+`apps:write`. A token whose claims cannot be read (an opaque `BASE44_ACCESS_TOKEN`) is refused
+rather than guessed.
+
+Failure codes are listed in
+[`himi-json-output`](himi-json-output.md#himi-base44-entities--functions-provisioning-codes).
+
 ## Coming next
 
-- **Provisioning**: `create`, `seed` and `functions deploy` for owned entities and functions. It
-  consumes `diffEntityFields` and the `Base44QueryReport`. Base44's schema write is a destructive
-  full-set sync, which is why it is a separate, deliberate step.
 - **Typed clients and hermetic test data**: `entities<"X">()` typed from the declaration, with
   `seed` rows as mocks.
-- **Generated screens**: list and detail screens per declared entity.

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`**, and for **`himi site member-app`**. Other subcommands still have legacy failures without codes and are a
+first, for **`himi store iap connect`**, for **`himi site member-app`**, and for the **`himi base44`** entity and function verbs. 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
@@ -234,7 +234,7 @@ Covers `himi base44 adopt` and `himi base44 entities query` (#4557,
   carries each `ruleCode`. Adopt only emits what the lint accepts, so this means a bug in
   `adopt` (exit 1).
 - `unknown_subcommand`: `himi base44 entities` was given no subcommand, or one other than
-  `query` (exit 2).
+  `query`, `create` or `seed` (exit 2).
 - `config_unloadable`: `entities query` could not load `config.ts` (exit 1).
 - `invalid_config`: the `base44` block has lint errors; `issues[]` carries each one's
   `ruleCode` (exit 1). `himi validate` reports the same findings with `pass: "base44"`.
@@ -249,6 +249,88 @@ branch on them without parsing prose:
 - `source_unavailable`: the project download (the eject read) failed, so no drift was
   computed. Row counts still ran; `sourceRead` is `"unavailable"` and `sourceError` says why.
 
+## `himi base44 entities | functions` provisioning codes
+
+Covers `himi base44 entities create`, `himi base44 entities seed` and `himi base44 functions
+deploy` (#4558, [base44-entities](base44-entities.md#provisioning-create-seed-deploy)). Failures
+print `ok: false` and `code` on stderr. Every code below that refuses a write does so **before**
+the write request is sent.
+
+- `invalid_usage`: an unknown `functions` subcommand, a bare `--only`, `--only` on `entities
+  create` (always a full-set sync), an `--app` with no `apps/<slug>/config.ts`, or nothing to
+  deploy (no owned function, or `--only` matched none) (exit 2).
+- `unknown_subcommand`: `himi base44 entities` was given no subcommand, or one other than `query`,
+  `create` or `seed` (exit 2).
+- `config_unloadable`: `config.ts` could not be loaded (exit 1).
+- `invalid_config`: the `base44` block has lint errors; `issues[]` carries each `ruleCode` (exit 1).
+- `no_app_id`: the config has no `base44` block, or no `base44.appId` (exit 1).
+- `not_signed_in`: there is no session and no `BASE44_ACCESS_TOKEN`. Run `himi base44 login
+  --write` (exit 2).
+- `write_scope_missing`: `--yes` was given, but the token's `scope` claim lacks `apps:write` or
+  cannot be read. Nothing is sent, not even a read. Run `himi base44 login --write` (exit 2).
+- `schema_snapshot_unavailable`: the project download (`GET …/eject`) failed, or one of its entity
+  files does not parse or was dropped by the source walk. The current entity set is unknown, and
+  a sync without that file would delete the entity (exit 1).
+- `schema_snapshot_empty`: the download has no entity schemas. That cannot be told apart from a
+  failed read, so the run refuses unless `--empty-app-ok` is passed (exit 1).
+- `would_delete_foreign_entity`: the sync body would omit or alter an entity himi does not own.
+  The guard, which should never trip (exit 1).
+- `owned_entity_removal_needs_flag`: an entity this app provisioned (recorded in
+  `base44-provisioned.json`) is no longer declared. Dropping it deletes its rows; pass
+  `--allow-destructive`. An entity in the namespace that this app never provisioned is left
+  untouched and only warned about (exit 1).
+- `owned_field_removal_needs_flag`: an owned entity lost a declared field. Pass
+  `--allow-destructive` (exit 1).
+- `owned_entity_unclaimed`: a declared owned entity already exists on the app, but
+  `base44-provisioned.json` does not record this app provisioning it, so it may belong to another
+  himi app whose slug shares the prefix. If it is this app's, record it in that file; otherwise
+  rename the declaration (exit 1).
+- `snapshot_changed`: the entities changed between the plan and the re-read just before the
+  `PUT`. Nothing was sent; re-run (exit 1).
+- `ledger_unreadable`: `base44-provisioned.json` exists but is not a JSON object (a merge
+  conflict, say). himi will not rewrite it from scratch, because that would drop other app ids'
+  records, so fix the file. The same code means the sync was sent but the file could not be
+  written afterwards; `error` names the entities to record by hand (exit 1).
+- `foreign_entity_deleted`: after the `PUT`, Base44's `deleted[]` named an entity the plan did not
+  drop on purpose; `foreignDeleted` lists them. Defence in depth: the guard should make this
+  unreachable (exit 1).
+- `nothing_to_seed`: `seed` found no owned entity (adopted ones are never seeded), or `--ai`
+  had none to write (exit 1).
+- `seed_incomplete`: one or more owned entities were not seeded because they are missing from
+  the app, unrecorded in `base44-provisioned.json` (`skipped: "unclaimed"`), or their rows could
+  not be read; `skipped[]` names each one. Not-empty entities are
+  skipped (`skipped: "not-empty"`) without failing (exit 1).
+- `seed_file_invalid`: `base44-seed.json` is not a JSON object keyed by entity name, one of
+  its entries is not an array of row objects, or a row has no declared field left once undeclared
+  keys are dropped (a blank record would make the entity non-empty for good) (exit 1).
+- `function_name_taken`: a declared function name is already deployed and does not carry this
+  app's `.himi-owned` marker. Nothing was deployed (exit 1).
+- `function_source_missing`: an owned function has no `base44/functions/<name>/` folder or no
+  entry file (exit 1).
+- `function_source_unsafe`: the function folder contains a symlink or a denied path, the secret
+  scan flags a file, or the folder is over the file or byte cap. Nothing is uploaded (exit 1).
+- `request_failed`: any other refused request, or a reply himi cannot read. That includes a sync
+  response with no `deleted[]` and a function listing with no `functions` array. `status` and
+  `serverError` are included when the server answered (exit 1).
+
+## `himi base44 screens` codes
+
+`himi base44 screens` (#4560, [base44-app-to-himi-app](base44-app-to-himi-app.md)) generates one
+list + detail screen per declared `base44.entities` entity. Failures print `ok: false` and `code`
+on stderr (exit 1):
+
+- `content_dir_not_base44_starter`: the directory lacks the shared engine the generated files
+  import (`missing[]` names the files). Scaffold with `himi init --template base44-starter`.
+- `no_entities_block`: `config.ts` declares no `base44.entities`, so there is nothing to generate.
+- `entity_id_collision`: two entities would generate the same screen id (or one would shadow
+  `b44_functions` / `b44_account` / `b44_more`); `entity`, `screenId` and `with` name the clash.
+- `config_unloadable` / `invalid_config`: as for `himi base44 entities` above.
+
+On success (`ok: true`, stdout, exit 0) `files[]` gives every generated path with its `outcome`:
+`written`, `unchanged`, or `skipped-edited` (the file was edited by hand and was left alone; pass
+`--force` to overwrite it). A skipped file is not a failure. `orphaned[]`, when present, lists
+generated files for entities no longer declared. They are never deleted.
+
 ## Follow-ups
 
 - Migrate failure envelopes in subcommands other than `push`, keeping this contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1432.0",
+  "version": "0.1434.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": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "796dbf6642a176106f5ab3335bbab9788c281db7f264524e0c7fb8e3"
+  "falconPackageHash": "cb5b7712df9ddebe73b144d2897a1f0c22f171a5e4e2f908546c7509"
 }