@wix/himalaya-cli 0.1610.0 → 0.1611.0

package/dist/quickjs-worker-entry.js

@@ -134,6 +134,10 @@ async function boot(msg) {
       let sweepError = null;
       try {
         actions = drain(ctx, runtime, msg.skipLoad ? "himi.quickjs.actions" : "himi.quickjs.loads");
+        if (msg.settleAuthoredActions) {
+          drainDetachedJobs(ctx, runtime);
+          actions = readbackJson(ctx, actionsReadback);
+        }
       } catch (e) {
         sweepError = String(e?.message ?? e);
       }

package/guides/getting-started.md

@@ -166,7 +166,9 @@ worker layer — trim it or mine it (`himi docs trim-a-template`): **trim** to t
 lists its screens (size, workers, `onAppear`), `--show <id>` prints one entry, and
 `--write <id> --from <file>` puts an edited entry back (refused if it breaks the file), and
 `--add <id> --from <file>` appends a NEW screen and registers it as linkable — the authoring half
-of mining a template. Not sure
+of mining a template. To add a screen, clone the closest one: `--show <closest>`, change the id
+and content, then `--add <new> --from <file> --display-name "<New title>"` (view names must be unique). `--from` takes that entry, a ScreenDescriptor
+JSON object, or `{ "<id>": <ScreenDescriptor> }`; never edit `dev/index.ts` by hand. Not sure
 which template fits? `himi template recommend --text "<the business>"` (or `--book <site analyze
 dir>` for a site's verticals) ranks the catalog with reasons. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
 list --remote` shows the full catalog (title/description/tags) — including templates published

package/guides/himi-json-output.md

@@ -40,6 +40,17 @@ keeps its existing fields and adds the code:
 }
 ```
 
+## `himi test` authored journey failures
+
+| Code | Meaning |
+| --- | --- |
+| `test_journey_failed` | At least one unsuppressed authored journey failed: its destination is absent, initialization/action failed, or the expected rendered values were missing. The existing `failures`, `journeys`, counts and exit 1 remain. This includes cold-entry journeys with `steps: []`. |
+| `test_input_evidence_requires_json` | `--input-evidence` was requested without explicit `--json`. Exit 2 before build or worker execution. |
+| `test_input_evidence_unsupported_mode` | `--input-evidence` was combined with `--browser`, or the content is a functions package rather than an app worker crawl. Exit 2 before execution. |
+| `test_input_evidence_unavailable` | The isolated input crawl cannot establish all contained realms, cannot read a stable source archive before/after the crawl, or fails to return one complete JSON report (including interruption, process timeout or output limit). Exit 1; no host-realm fallback or positive input acceptance. |
+
+This is a scoped migration. Other legacy `himi test` failure paths retain their existing envelopes.
+
 ## `himi icon from-one-app` codes
 
 | Code | Meaning |
@@ -300,15 +311,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
+## `himi template screens --upsert | --add | --write` 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.
+`--upsert` writes many generated screens at once; `--add <id>` and `--write <id>` write one. Their
+`--from` refusals carry a code; nothing is written on any of them (a failed batch restores every
+file). Other `template screens` paths, and `--add`/`--write` refusals about the package itself
+(an existing id, a symlink, a result that would not parse), 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. |
+| `invalid_usage` | `--upsert`, `--add` or `--write` was given without `--from <file>`. Exit 2. |
+| `invalid_input` | The `--from` file is missing, unreadable or not JSON. For `--add`/`--write` also: it is not a ScreenDescriptor object, `{ "<id>": <ScreenDescriptor> }` or the entry `--show` prints, or its key or `screenId` is not the `<id>` given; a templated route (`{ pattern, display, template }`) takes back only the text `--show` prints for it. `error` names the file. 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

package/guides/himi-skill.md

@@ -189,7 +189,9 @@ worker layer — trim it or mine it (`himi docs trim-a-template`): **trim** to t
 lists its screens (size, workers, `onAppear`), `--show <id>` prints one entry, and
 `--write <id> --from <file>` puts an edited entry back (refused if it breaks the file), and
 `--add <id> --from <file>` appends a NEW screen and registers it as linkable — the authoring half
-of mining a template. Not sure
+of mining a template. To add a screen, clone the closest one: `--show <closest>`, change the id
+and content, then `--add <new> --from <file> --display-name "<New title>"` (view names must be unique). `--from` takes that entry, a ScreenDescriptor
+JSON object, or `{ "<id>": <ScreenDescriptor> }`; never edit `dev/index.ts` by hand. Not sure
 which template fits? `himi template recommend --text "<the business>"` (or `--book <site analyze
 dir>` for a site's verticals) ranks the catalog with reasons. For a small **non-Wix** pattern, `himi init --template chat-bot --remote`. `himi template
 list --remote` shows the full catalog (title/description/tags) — including templates published

package/guides/himi-test.md

@@ -74,6 +74,80 @@ Each stage runs on hermetic data with zero network:
 Engine: `core/dev-server/src/screen-crawl.ts`.
 CLI orchestration: `tools/himi-cli/src/test.ts`.
 
+## Machine input evidence
+
+`himi test --content <dir> --input-evidence --json` opts into additive
+`inputEvidence.version: 1` output. The local evaluator records actual dispatches; it
+does not interpret a Plan or decide whether a warning is benign. The flag requires
+explicit `--json`; browser-loop and functions-package modes refuse it with typed
+failure codes. An older CLI may omit the field: treat that as capability missing,
+never as a passing scan.
+
+The CLI runs this opt-in crawl in a separate process, enables the existing compiler
+import confinement, and establishes QuickJS/WASM realms for generated dev modules,
+config, worker boot and worker actions before loading generated modules. Explicit
+host-realm overrides or unavailable isolation refuse with
+`test_input_evidence_unavailable`; there is no host fallback. Packages containing
+symlinks are refused. The compiler accepts package-owned files and CLI-owned
+source/staged SDK roots; it does not expand arbitrary app or ancestor dependency
+links into trusted roots. A separate editor SDK install cannot substitute for the
+pinned CLI's runtime in this mode. The trusted caller must keep the generated
+source and its environment quiescent during capture and bind the final subject. The local
+receipt CLI projects only the caller-owned public `WIX_CLIENT_ID` and `WIX_SITE_URL`
+into contained config/dev compilation, preserving their supplied values. Other
+host environment keys (including secrets) are omitted; tokenless/default contained
+callers still receive an empty environment. Capture those public bindings with
+the run environment; the CLI does not choose an identity or provision a site.
+Packages requiring host filesystem/network work during config or descriptor construction must report
+that limitation instead of issuing contained evidence. The isolated crawl has a
+three-minute process limit; interruption forwards SIGTERM/SIGINT to its child.
+
+The receipt has these fields:
+
+| Field | Evidence |
+| --- | --- |
+| `subject` | Actual app, tested release ID and payload hash, test run ID, source diff/untracked hashes, and SHA256 of the exact `himi-test.json` bytes parsed for the run (`absent` when missing). `sourceArchiveHash` is SHA256 of the base64 deterministic ZIP from the publish source collector, including authored `himi-test.json`. It is captured before loading generated modules and rechecked after the crawl; unreadable or changed source refuses with `test_input_evidence_unavailable`. Generated `.himi` outputs are excluded by the shared archive rules. Git hashes may explicitly be `unavailable`. |
+| `execution` | CLI-established `devModule`, `appConfig`, `workerBoot` and `workerAction` modes, each `quickjs-wasm`. A v1 report missing these fields predates the contained CLI path; do not accept it as contained execution. This marker is meaningful only when captured from the trusted pinned producer. |
+| `probes` | Each synthesized typed dispatch's screen/component/action/hook, contract control and injected field/value, actual argument list, precondition input/current value/state hash, post-state hash, and observed state/navigation/request/host-call/throw results. Zero probes is not proof that required controls ran. |
+| `journeys` | Actual screen/input, each attempted step's scope, raw `declaredPayload`, effective row-resolved `descriptorPayload`, exact `testOverrides`, final merged `payload`, pre/post state hashes, executed/threw/not-dispatched status, final visible observations and evaluator-computed assertions. Unavailable actions remain not-dispatched, never successful steps. |
+| `unavailableScreens`, `unavailableJourneys` | Requested coverage for which the evaluator did not supply v1 evidence, including older engines, invalid/collapsed screens and unavailable journeys. With positional screen IDs, these lists contain only requested roots; requested unknown IDs remain unavailable. Unrelated configured journeys do not run or fail a scoped run. These gaps are not accepted behavior. |
+
+State hashes fingerprint the exact serialized worker snapshot captured at the dispatch
+boundary. `currentValuePresent` distinguishes an absent current value from null.
+Input records include the implicit screen ID, then baked descriptor input and route
+overrides with the same precedence the worker receives.
+Requests and host calls are attempted hermetic effects, not live-service success.
+Journey assertion kind `observation-substring` states the existing operator exactly:
+substring inclusion in joined visible `nodeId.field=value` lines. It does not prove
+exact text equality, complete result sets, absence of extra rows, or that an
+agent-authored expected value is an independently approved oracle.
+
+Journey parameters are synthetic overrides. A journey that replaces a descriptor's
+literal service-reference ID with a real ID tests that synthetic dispatch, not the
+actual UI tap. Inspect `testOverrides` alongside `descriptorPayload`; a passing
+assertion cannot waive a failing descriptor-driven flow. Worker (`tier5.*`) actions
+keep authored params/args literal by the existing action contract; reducers read
+their selected record from state/input rather than expecting nested service binding
+evaluation. This evidence does not change that contract.
+The origin fields are always present: unavailable declared/effective payloads and
+absent test parameters are explicit `null`; an explicitly empty override is `{}`.
+An omitted origin field is unknown, not evidence that no override occurred.
+
+This output leaves `ok`, finding severities and suppressions unchanged. In particular,
+`typed-value-ignored` remains a warning and can coexist with `ok: true`. Use the
+structured finding invariant/screen/trigger/field/axis to apply a separate trusted
+acceptance policy; do not parse message prose or reject every warning. Finding IDs
+are stable grouping identities, not unique case/dispatch IDs. Inspect suppressed,
+skipped and absent coverage explicitly. A different successful input cannot excuse
+an untested or failed required input.
+
+Attestation v2 still binds only aggregate report/coverage values alongside its
+existing source/release/descriptor/screenshot hashes; it does not acquire new
+acceptance semantics. A trusted host must capture the actual pinned CLI process
+exit/stdout, bind the full report to its own run and immutable final source/release,
+and supply independent required-control/case policy. Neither a negative-clear scan
+nor an unkeyed receipt is whole-product acceptance or trusted agent prose.
+
 ## Typed form journeys
 
 The crawl types into a control **only when it can read a legal value off the app itself** — an id
@@ -115,6 +189,19 @@ edge would hand it — so the journey boots the way a real tap into it would. Ke
 navigation in the ordinary edge pass, which boots the destination with real source
 parameters. Pair dynamic journeys with app-specific `dev/net-mocks.json` fixtures.
 
+Journeys run only the initialization the bundle and descriptor actually declare: module-scope
+calls and the root `onAppear`. Unlike the discovery crawl's convenience `load()` sweep, they do
+not call an otherwise uncalled loader. A declaration of `actions.load` alone does not initialize
+a cold screen on device.
+
+Use `"steps": []` to assert the result of entering a detail screen, without adding a synthetic
+load tap that could conceal missing initialization. Add separate journeys with different `input`
+IDs and requirement-derived `expectText` (title, notes, metadata and numeric values). Include
+missing/stale IDs and a not-found expectation. These are independent cold entries, not proof of
+back/return, state carry-over or the source row's emitted navigation params; verify those with
+real interactions as well. A green derived crawl without such expectations does not establish
+that a detail shows the selected record.
+
 ## What it checks
 
 Only **unambiguous** defects, so a green run stays worth trusting:
@@ -483,6 +570,7 @@ behavior. This instruction does not add an automatic suppression or retry gate t
 | `--offline` | Strip every data layer — see the failure UI head-on. (Excludes `--net`.) |
 | `--no-hostile` | Skip the empty-list / all-500 passes. |
 | `--no-shots` | Skip the per-screen PNGs written to `.himi/shots/`. |
+| `--input-evidence` | Requires `--json`; capture actual typed probes and authored-journey receipts in contained local worker mode (see the receipt contract above). |
 | `--net <file>` | Use an explicit net-mocks file instead of the app's own. |
 | `--budget <ms>` | Per-action settle budget (default 2000). |
 | `--native` | Also decode every baked descriptor, and the release's `tokens.json`, with the real native decoders; bare `--native` runs whichever toolchains are present and names each one it could NOT check in a top-level `skippedPlatforms: [{ platform, reason }]` (never a pass), while `--native ios` or `--native android` selects one and exits 2 when it is unavailable. The Android SDK is found from `ANDROID_HOME`, then `ANDROID_SDK_ROOT`, then `sdk.dir` in the source checkout's Android test harness `local.properties`, then the default install path (`~/Library/Android/sdk` on macOS, `~/Android/Sdk` on Linux). **Source-checkout only** — the decoder oracles are that tree's own HimalayaCore Swift package and Gradle harness, which a published install does not ship, so it cannot run this at all (and its coverage ledger stays silent about native decoding rather than suggesting it). |

package/guides/qa-builds.md

@@ -636,6 +636,14 @@ gradle read the tree. The shell supplies the project; it no longer supplies the
 | `apps/<app>/ios/project.yml`, then its `build.gradle.kts` | the content app has source in this checkout — it already declared a version, so nothing new has to be declared |
 | the SHELL's own declared version | an off-repo app that declares nothing anywhere. Deliberate: `CFBundleShortVersionString` is **also** the OTA rollout floor (`HimalayaApp.swift` passes it as `binaryVersion`; serve-control's `resolveRelease` skips any ring whose `minBinaryVersion` it fails, and returns nothing when none qualifies), and the shell's version is the truth about what the binary can render |
 
+Branded Lite keeps the two apart, so the store version never moves its rollout floor. Its Android
+app reports `BuildConfig.SHELL_VERSION` as the OTA `binaryVersion`, and its iOS app the Info.plist
+key `HimalayaShellVersion`. Each is pinned equal to the shell's committed version. So a
+Containers app's App Store build, which stamps the owner's version into `CFBundleShortVersionString`
+through `APP_VERSION`, still reports the shell's version to update checks, and the build log says so.
+A shell commit older than the key reports `CFBundleShortVersionString`, as before. Force update
+(`minVersion`) compares the store version on both.
+
 The **build number** (`CFBundleVersion` / `versionCode`) is seconds since 2020-01-01Z, so it is
 monotonic and unique per app per second — App Store Connect rejects a duplicate version/build pair,
 and Play requires `versionCode` to increase.

package/guides/release-notes.md

@@ -14,6 +14,18 @@ areas, always in the same order, so you can skim for the one you care about.
 
 ---
 
+## 2026-11-08
+
+### Getting started & the CLI
+
+- **`himi template screens --add` and `--write` now take the screen as JSON.** `--from` accepts a
+  plain ScreenDescriptor (the id comes from `--add <id>` / `--write <id>`), `{ "<id>": <ScreenDescriptor> }`,
+  or the entry `--show` prints. Before, only that `--show` entry worked, and a JSON file failed with an
+  error pointing at a line of `dev/index.ts`. A file that is not one of these shapes, has a different
+  id or cannot be read is refused with `code: "invalid_input"`, and the error names your file. To add
+  a screen, clone the closest one: `--show <closest>`, edit it, then
+  `--add <new> --from <file> --display-name "<title>"`. (#5422)
+
 ## 2026-11-04
 
 ### Branded Lite & Owner Lite

package/guides/templates.md

@@ -117,6 +117,8 @@ himi template screens                        # list the screens and their worker
 himi template screens --show himi_saved > saved.txt    # ONE screen's entry
 himi template screens --write himi_saved --from saved.txt   # put it back — re-parsed, refused if it breaks the file
 himi template screens --add himi_sellers --from sellers.txt --parent himi_branded_home   # a NEW screen, registered as linkable
+# --add/--write --from takes a ScreenDescriptor JSON object, { "<id>": <ScreenDescriptor> }, or the --show entry.
+# To add a screen, clone the closest one: --show it, change the id and content, then --add it.
 himi template sweep --set "Sample content=>Our latest" --dry-run   # copy inside string literals only
 himi template trim --from-spec --links drop --dry-run   # keep SPEC.md's Screen catalogue ids — read fromSpec.droppedPrimary first
 ```

package/guides/tier-5-add-a-screen.md

@@ -779,6 +779,20 @@ This works identically on web, iOS, and Android. (Regression-guarded by
 detail bundles for BOTH the primary `input.id` param and the back-compat
 `input.screenId` recovery.)
 
+**Prove the selected record, not just a successful build.** Each screen has its own worker,
+even when several screens name the same bundle and service. Setting a selected id in the list's
+service does not set the detail's state. Trace the tapped row id → navigation params →
+`himalaya.input` → the detail's initialized state. Route input is not automatically a loader
+argument, and `$input.id` is not a descriptor binding; read input in the worker as above.
+
+Add cold-entry journeys (`steps: []`) in `himi-test.json` for at least two distinct records per
+detail, asserting their requirement-derived title, metadata, notes and numeric values. Also
+assert missing/stale ids. See [cold-entry assertions](himi-test.md#typed-form-journeys). Do not
+manually dispatch `load` in these checks: that can make an uninitialized generated screen look
+correct. Then drive the actual row taps and back/return on each required surface, confirming
+that the second selection and a missing id show none of the first record's fields. Keep the
+source-nav and return evidence separate from the screen-local cold-entry assertions.
+
 **Alternative — a templated route that bakes a static `input`.** When the id space is
 enumerable, a `screens.templated` route can bake the id straight into the descriptor's
 **static `input`** instead of relying on a nav param — the `property_<id>` pattern. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1610.0",
+  "version": "0.1611.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": [
@@ -72,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "fd34bb941dc2b1092069d5876a747cc0048164fc1b1ce148a32257b2"
+  "falconPackageHash": "5919de535cfa33dabfeb372e350f3934dc2b5ccd610a7c9acdea0c51"
 }