@wix/himalaya-cli 0.1609.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

@@ -199,7 +199,20 @@ by this job, and its temporary files. It preserves the agent's keychain; it does
 certificate or delete the original profile in Apple/Branded. A matching identity already in the
 keychain is refused before import so cleanup cannot delete a pre-existing identity.
 
-Outside that runner mode, Himi creates a temporary keychain and deletes it during cleanup. A
+A job that is killed before its cleanup runs (SIGKILL) leaves the customer's material behind, so
+each job records what it places before placing it: its signing folder (which holds the private key
+until it is imported), the identity it imports into the agent keychain, and every copy of the App
+Store Connect key (`~/.private_keys/AuthKey_<id>.p8`, also when it replaces a file already there,
+and the temporary copy `altool` reads). The records live in `~/.himalaya/customer-secret-claims` in the account home.
+At the start of the next customer build on that Mac, before the pre-existing check, Himi removes
+what a job whose process has ended recorded, and leaves alone what a running job recorded, since a
+Mac may run more than one job at once. A matching identity that a running job owns, or that no
+record names, is still refused. SIGTERM and process exit remove the key copies directly, as they do
+the signing directory.
+
+Outside that runner mode, Himi creates a temporary keychain and deletes it during cleanup. That
+keychain is recorded the same way before it is created, and the next customer build deletes one an
+ended job left (`security delete-keychain`, which also drops it from the search list). A
 missing password or keychain in agent-keychain mode fails the build instead of silently switching
 modes. Private key material does not enter job parameters or the public job record. The runner
 source SHA must advertise support for this protocol and be reachable from the pool before BYO
@@ -623,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.1609.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": "fa0e34282ffa10a702049aac3eee4901f37a114adb15ad682acd5013"
+  "falconPackageHash": "5919de535cfa33dabfeb372e350f3934dc2b5ccd610a7c9acdea0c51"
 }