@wix/himalaya-cli 0.1038.0 → 0.1040.0

package/guides/designing-himi-screens.md

@@ -14,8 +14,9 @@ prescriptive layer that sits **above** the wiring guide: `himi docs tier-5-add-a
 > This is the *composition* layer: how to build a screen well out of the vocabulary. The *values*
 > layer — swapping a look-and-feel kit, editing token values — is a separate job; they compose.
 >
-> **Want a worked example?** `himi agent-init` writes `examples/stocks-dashboard.descriptor.json`
-> next to you — a fully-composed screen to study.
+> **Want a worked example?** `himi init` (and `himi agent-init`) write
+> `.agents/skills/himalaya/examples/stocks-dashboard.descriptor.json` into the app — a
+> fully-composed screen to study.
 
 ---
 

package/guides/getting-started.md

@@ -42,7 +42,6 @@ account, no corporate network. Append `/<topic>.md` for the raw markdown an agen
 # works from anywhere — no Wix network, no VPN.
 npm i -g @wix/himalaya-cli@latest
 himi --version                   # MUST print a version (>= 0.200). If it prints the help banner, your himi is ancient — re-run the install above.
-himi agent-init                  # seeds HIMALAYA.md + component-reference.md + examples/ here
 himi guide                       # this page + the headless dev loop
 himi docs                        # list the guides embedded in THIS CLI before naming a topic
 himi components                  # the native UI components you can use + their props
@@ -53,6 +52,8 @@ himi --help                      # capability preflight: verify the commands thi
 (On a Wix machine whose `~/.npmrc` points `@wix` at the internal registry this still works —
 that registry proxies npmjs.com.)
 
+**The agent files come with the app.** `himi init <app>` writes them **inside the new app**: `AGENTS.md` and `CLAUDE.md` (loaded by coding agents at every session start), the `himalaya` skill (`.agents/skills/himalaya/` with its `references/` and `examples/`, plus `.claude/skills/himalaya/`), the `HIMALAYA.md` primer and a Claude Code session-start hook that runs `himi progress --brief`. Start later sessions in that folder and they pick the work up by themselves. `himi agent-init`, run inside the app, refreshes them after a CLI upgrade (`himi doctor` says when they are stale); on an older CLI, run it there by hand.
+
 ### Installed-CLI capability gate
 
 Do not assume every published CLI contains every guide or verification verb named in this
@@ -194,7 +195,7 @@ is the entire value** of a prop — `text: "$service:home.total"`, never `text:
 (mid-string renders the raw token); put a label and its value in separate `Text`s. (A state string that
 itself starts with `$` collides with the binding sigil — don't prefix values with `$`.) Don't worry
 about the syntax yet:
-copy the `examples/counter.*` pair that `himi agent-init` writes (it shows the wiring), study
+copy the `examples/counter.*` pair (in `.agents/skills/himalaya/examples/`, which `himi init` and `himi agent-init` write; it shows the wiring), study
 `examples/stocks-dashboard.descriptor.json` to see a well-composed real screen; then start
 from the recipe that matches your screen — each ships as a doc + a runnable example pair:
 a data-backed list `examples/dynamic-list.*` (`himi docs recipe-dynamic-list`, incl.

package/guides/headless-loop.md

@@ -450,6 +450,7 @@ failure.
 
 ## Bootstrap your coding agent
 
-Run `himi agent-init` in your working directory to drop a `HIMALAYA.md` primer, the
-component reference, and the counter example so your own coding assistant discovers how to
-author Himi screens.
+`himi init <app>` writes the agent files into the new app — `AGENTS.md`, `CLAUDE.md`, a
+`HIMALAYA.md` primer and the `himalaya` skill with the component reference and the examples —
+so your own coding assistant discovers how to author Himi screens, and a later session picks the
+work back up. Run `himi agent-init` inside the app to refresh them after a CLI upgrade.

package/guides/himi-skill.md

@@ -0,0 +1,381 @@
+---
+name: himalaya-technical
+description: Technical implementation reference for Himalaya native iOS, Android, and web apps—CLI setup, screen authoring, Wix bindings, validation, preview, release, and QA distribution.
+---
+
+<!-- Himalaya technical reference — hosted at https://apps.wix.com/_api/himi-serve/himi-skill.md. Start customer work at https://apps.wix.com/_api/himi-serve/skill.md; it defines discovery, approval, and handoff behavior. -->
+
+> Fetching this page through a **summarizing** fetcher (some WebFetch tools paraphrase) drops the
+> exact commands. It is served as raw `text/markdown` — fetch the URL **verbatim** (e.g. `curl` it)
+> so the commands below arrive unaltered.
+
+> **Two other doors** reach the same authoring surface with **no install at all**, because the
+> server does the compiling: an **MCP server** whose tool list your client enumerates for you
+> (https://apps.wix.com/_api/himi-serve/skill-mcp.md), or the same loop in raw `curl`
+> (https://apps.wix.com/_api/himi-serve/skill-http.md). Both pages are public and worth reading, but
+> the endpoints they drive are reachable **only from the Wix network** (`bo.wix.com`), since
+> a server-side compile must not be internet-reachable. The CLI below is the one that works
+> from anywhere.
+
+> **Every guide referenced below is also fetchable**, with no install and from anywhere:
+> https://apps.wix.com/_api/himi-serve/docs is the index and `https://apps.wix.com/_api/himi-serve/docs/<id>.md` is one guide — the same set
+> `himi docs` ships, so use whichever door you already have open.
+>
+> **Two URLs, one guide.** `/docs/<id>.md` is YOUR url: the `.md` suffix is an unconditional
+> markdown override, so it stays markdown no matter what `Accept` you send. `/docs/<id>`,
+> with no suffix, is the one to hand a HUMAN: it negotiates on `Accept` and answers a browser
+> with a rendered page (and anything else with the same markdown). Do not paste a `.md` link
+> to a person — they will get raw markdown.
+
+# Start here
+
+With Himalaya you build **real native apps — iOS and Android first, plus the web, desktop
+(macOS), and the wrist (Apple Watch / Wear OS)** — that update **instantly over-the-air**:
+ship a new screen or a fix without an App Store / Play release. One project serves every
+surface it declares (`himi docs app-config` → Surfaces); start phone-first and add
+surfaces when you want them.
+
+You don't write Swift or Kotlin. A **screen is just data** — a layout of native UI components —
+plus, optionally, a little logic (a small JavaScript *worker* that holds state and handles taps).
+The `himi` CLI turns that into the live app. (In the deeper docs this "screen as data + worker"
+model is called a **Tier-5 screen** — but you don't need the jargon to start.)
+
+This is the technical starting point for a developer or coding agent building on Wix.
+For a business customer who begins with an app idea, start at https://apps.wix.com/_api/himi-serve/skill.md; it owns
+discovery, plan approval, consent, browser review, and the handoff to this technical loop.
+
+## Business-customer handoff
+
+Do not use the commands below to jump straight into a template when a customer has not yet
+approved their plan. The customer entry skill produces approved `SPEC.md` and `MOBILE-UX.md`,
+then sends you here to choose a template, implement, validate, and prepare an owner-private draft
+preview. For Wix Headless / Back Office work without a public site, use the approved plan's role/data
+matrix and read `himi docs headless-business-to-himi-app` **only if it appears in `himi docs`**;
+for a published site, read `himi docs wix-site-to-himi-app` only after permission to inspect live data
+and only if that topic is installed. A missing embedded guide is a tooling-version fact, never a reason
+to guess the customer's data model.
+
+## Two ways to begin
+
+**A. Read the guides in your browser** — https://apps.wix.com/_api/himi-serve/docs
+Every guide, the component reference and the importable SDKs, as readable pages. Public: no Wix
+account, no corporate network. Append `/<topic>.md` for the raw markdown an agent should fetch.
+
+**B. From your terminal / coding agent:**
+
+```sh
+# Step 0 — install the LATEST CLI and VERIFY it. Use @latest: a plain
+# `npm i -g @wix/himalaya-cli` is a no-op if an OLD himi is already on PATH, and an
+# out-of-date CLI reports authoring as "not available standalone" — a stale build, not
+# a platform limit. No registry flag: the CLI publishes to public npm, so the install
+# works from anywhere — no Wix network, no VPN.
+npm i -g @wix/himalaya-cli@latest
+himi --version                   # MUST print a version (>= 0.200). If it prints the help banner, your himi is ancient — re-run the install above.
+himi guide                       # this page + the headless dev loop
+himi docs                        # list the guides embedded in THIS CLI before naming a topic
+himi components                  # the native UI components you can use + their props
+himi sdk                         # importable @himalaya/* SDKs + their typed API
+himi --help                      # capability preflight: verify the commands this installed CLI actually has
+```
+
+(On a Wix machine whose `~/.npmrc` points `@wix` at the internal registry this still works —
+that registry proxies npmjs.com.)
+
+**The agent files come with the app.** `himi init <app>` writes them **inside the new app**: `AGENTS.md` and `CLAUDE.md` (loaded by coding agents at every session start), the `himalaya` skill (`.agents/skills/himalaya/` with its `references/` and `examples/`, plus `.claude/skills/himalaya/`), the `HIMALAYA.md` primer and a Claude Code session-start hook that runs `himi progress --brief`. Start later sessions in that folder and they pick the work up by themselves. `himi agent-init`, run inside the app, refreshes them after a CLI upgrade (`himi doctor` says when they are stale); on an older CLI, run it there by hand.
+
+### Installed-CLI capability gate
+
+Do not assume every published CLI contains every guide or verification verb named in this
+reference. In particular, check whether `himi --help` lists `test` and whether `himi docs`
+lists the topic you want **before** making either a required acceptance check. If either is absent
+after a fresh `@latest` install, record a tooling block and continue only with the supported
+local evidence (build, strict validate, and labelled state renders). That is not equivalent to a
+behavioral crawl: do not call the app fully validated or release-ready, and do not invent an
+unsupported command. The customer-facing skill owns the plan; its approved `MOBILE-UX.md` remains
+the UX source of truth even if that guide is absent from the installed CLI.
+
+## Author your first screen
+
+**Building a real app? Start from a full template**, not the blank scaffold:
+`himi init my-shop --template branded-lite` (a full consumer reference over a Wix
+site — store/bookings/events/blog/cart/CMS, wired to `@himalaya/wix-*` + a visitor session)
+or `--template owner-lite` (owner CRUD/management: lists, details, forms). That reference is
+**dozens of screens** in one megabytes-long `dev/index.ts` of raw descriptors. Keep its
+worker layer — trim it or mine it (`himi docs trim-a-template`): **trim** to the approved
+`SPEC.md` when most of its screens fit, or **mine** it when few do — keep the
+`tier5-src/_shared/` helpers and Wix worker chains and write your own screens. Do not delete
+`tier5-src/` + `dev/` and start from blank. 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
+to Wix — and `--remote` on `himi init` fetches one from there (the bundled copy is
+the offline fallback). Publish any app of your own as a template with `himi template publish` —
+see `himi docs templates`.
+
+**When the blank scaffold IS the right call.** It is a deliberate starting point, not only the
+thing you settle for when no template fits. Choose it when the app is **small and already
+understood** — a handful of screens you can name — because a dozens-of-screens reference is then
+more to delete than you would have written; when it **binds no Wix site or vertical**, so a
+template's identity, fixtures and boot-time worker calls would all have to be torn out anyway;
+when consent is **synthetic/local-only** and you need something that cannot auto-fetch (see the
+preflight below); or when you are **learning the wiring** and want one screen and one worker with
+nothing else in the file. The recipes below are written for exactly these cases. What blank is
+NOT good for is a real customer app whose shape a published template already has — trimming or
+mining that template (`himi docs trim-a-template`) beats rebuilding its Wix wiring from scratch.
+
+**A template is a SHOWCASE APP, so look at it before you pick it.** Each one is a real published
+release running on the plane: `GET /v1/templates.md` gives every row a `preview/a/<id>` URL that
+boots the actual app in a browser, and the public landing page shows the same catalog as live
+phones. Every row also carries a **start prompt** — the sentence a customer pastes to begin from
+that template — which is what a customer arriving with "starting from the … template" has already
+done. Print one yourself with `himi template prompt <name>`.
+
+**Consent preflight before a template preview.** `branded-lite` and `owner-lite` are Wix-integrated
+full apps; their workers can request Wix data when they boot. Do not start their worker or web
+host under a synthetic/local-only authorization unless you have first removed or mocked every such
+startup path and verified the network log is empty of Wix/external requests. Prefer a blank,
+local-only scaffold for that stage. A browser render that causes an unapproved request is a failed
+consent gate, not a harmless preview.
+
+**Preview boundary:** local `himi render` evidence is a rendered state artifact, not an interactive,
+authenticated owner preview. The interactive `himi preview` URLs exist for a **draft release** after
+`himi push --draft`; obtain the separate draft-publish approval first. Do not start an arbitrary local
+web host and call it owner-private, and do not let a template worker boot there until its startup
+network paths are authorized and preflighted.
+
+**Adopt, don't just rename, a template.** The approved `SPEC.md` and `MOBILE-UX.md` are the
+plan, and the plan wins over anything `himi init` seeds. `init` seeds placeholder copies of
+both and can overwrite plan files already in the package root, so keep a copy of the approved
+plan until `init` has run. After `init`, open both files:
+if either holds `init`'s boilerplate rather than the approved plan, put the approved plan back in
+its place — never the reverse — and finish it with the actual customer, data/auth assumptions,
+placeholder copy, flow/state matrix, and compact/phone/expanded + device evidence before calling
+the app ready. Keep scenario switches out of customer UI. A labelled preview fallback is acceptable
+only when the host cannot perform the task and it cannot write customer data.
+
+Before authoring a multi-screen mobile app, ensure the customer-approved `SPEC.md` and
+`MOBILE-UX.md` are in the content-package root. Use `himi docs <topic>` only after `himi docs`
+shows that topic for the installed CLI.
+The contract ships with a release when it contains public-safe material, so later agents can
+retrieve and extend the rationale.
+
+## From a Wix website (the usual real-app path)
+
+**No site yet?** `himi site create` provisions one, and what you pass decides what you get:
+
+```sh
+himi site create <name> --type headless \
+  --template <guid> --verticals stores,bookings \
+  --redirect-uri himalaya-<your-app>://oauth/callback --yes
+```
+
+`--type` defaults to `wix`, so pass `headless` for an app that binds a Headless client.
+**Without `--template` you get a BLANK project, not a usable site** — and `--verticals` is
+refused without it, because a blank project has no site for a vertical to attach to (the
+install reports success with `requiredActions: CREATE_SITE` while the vertical's API answers
+428 forever). **Pass `--redirect-uri` with your own app's scheme:** it defaults to
+`himalaya-demo-app://oauth/callback`, and a scaffolded template authenticates with
+`himalaya-<your-app>://oauth/callback` — mint a client that does not allowlist yours and
+sign-in fails at redirect-session with "no auth code".
+
+The minted client's id IS the `WIX_CLIENT_ID` below. The **`WIX_SITE_URL` half of the binding
+is not minted with it**: a just-created site is unpublished, so it has no public URL to read
+(`himi site list` reports `viewUrl` empty until you publish). `--site-url` is read **only
+during this one create call** — there is no rebind verb, and re-running `site create` bills you
+a second site — so if the site is not published yet, bind the URL **after** publishing by setting
+`WIX_SITE_URL` (the app resolves env first) or by editing `wix.siteUrl` in its
+`provisioning.json`. Otherwise the app keeps its placeholder URL and reads nothing.
+`--write-provisioning [path]` records the binding into an **existing** `provisioning.json` (it
+updates a manifest, it does not create one, and it refuses the committed branded-lite manifest).
+
+It creates a **real, billable** site on the signed-in Wix account and is not cleanly reversible,
+which is why `--yes` is mandatory: get the customer's explicit go-ahead first. Full procedure,
+including the Catalog-V3 and inherited-locale traps: `himi docs creating-wix-sites`.
+
+If the user has a **published Wix site** (URL + Headless `clientId`), **stop following the
+counter recipe.** Read `himi docs wix-site-to-himi-app` and follow it end to end: analyze
+(`himi site analyze`) → screen plan (words from `book.copy`, not stock phrases) →
+`himi init --template <overlay>` → bind
+`WIX_CLIENT_ID` / `WIX_SITE_URL` → rewrite verticals / CMS / Velo / forms / pages as
+**native mobile** screens (phone IA and UX, not a WebView or a shrunk desktop).
+`--apply` bakes name/colors/tabs — it is a start, not the product. It maps a handful of scraped
+CSS variables and picks the design kit from **installed verticals**, so it cannot tell a brand
+colour from a background wash and it has never seen the site. **Open `<out>/evidence/pages/*.png`
+and judge the look yourself**: pick the kit from the character you see there, take the accent from
+a colour actually present (a scraped theme value, or the logo in `<out>/media/`) rather than
+inventing one, treat a near-white/cream value as a surface, and verify BOTH colour schemes — the
+mapper writes the site's light colour into the dark arm too, so dark mode is where it fails first.
+To create/publish/invoke the site's Velo HTTP functions, `himi docs wix-site-http-functions`
+and `himi site function` (not analyze, and not `himi functions`).
+
+After `himi init … --template branded-lite` (or a vertical overlay), **point the app at your
+Wix site** before expecting live catalog data:
+
+```sh
+export WIX_CLIENT_ID="<headless-oauth-client-id>"
+export WIX_SITE_URL="https://your-site.wixsite.com/…"
+```
+
+The Headless `clientId` is the site binding (no separate MSID flag). Details:
+`himi docs branded-lite-site-binding`.
+
+A screen is a **layout** (a tree of native components) plus an optional **worker** —
+`defineService(name, { state, actions })` — wired together with bindings like `$service:<service>.<path>`,
+and a Button triggers an action via `tier5.<service>.<action>`. A binding is substituted **only when it
+is the entire value** of a prop — `text: "$service:home.total"`, never `text: "Total: $service:home.total"`
+(mid-string renders the raw token); put a label and its value in separate `Text`s. (A state string that
+itself starts with `$` collides with the binding sigil — don't prefix values with `$`.) Don't worry
+about the syntax yet:
+copy the `examples/counter.*` pair (in `.agents/skills/himalaya/examples/`, which `himi init` and `himi agent-init` write; it shows the wiring), study
+`examples/stocks-dashboard.descriptor.json` to see a well-composed real screen; then start
+from the recipe that matches your screen — each ships as a doc + a runnable example pair:
+a data-backed list `examples/dynamic-list.*` (`himi docs recipe-dynamic-list`, incl.
+pull-to-refresh + load-more), a create/edit form `examples/form-submit.*`
+(`himi docs recipe-form-submit`), a searchable list `examples/search-list.*`
+(`himi docs recipe-search`), a first-run onboarding card `examples/onboarding.*`
+(`himi docs recipe-onboarding`), and the loading/empty/error/ready idiom they all share
+(`himi docs recipe-four-state`). Then — **before you
+design** — read the UX guide (`himi docs designing-himi-screens`) and, for a multi-screen app,
+the mobile contract guide (`himi docs mobile-ux`), then follow
+*Author a Tier-5 screen*.
+
+Keep structural choices reviewable: use `FragmentSlot` when a finite set of shipped component
+trees is selected by worker state. Use the gated `WorkerSubtree` only when structure is genuinely
+unknowable at descriptor-authoring time; it requires explicit type/action/budget policy, a
+descriptor-shipped fallback, and `workerSubtreeScreens` allowlisting. The Tier-5 guide contains
+the complete decision order and examples.
+
+## What works off-repo — and what still needs VPN
+
+- ✅ **From `npm i -g @wix/himalaya-cli` alone:** the supported
+  author → check → iterate loop, with **nothing to check out and no simulator** — `guide`, `docs`,
+  `components`, `sdk`, `skills`, `agent-init`, `init`, and **`build` / `validate` / `render` /
+  `preview`**, plus `test` **only when the capability gate above lists it**. These compile a Tier-5
+  worker, lint a screen against schema/tokens/components/`$service` + a worker boot dry-run, and
+  headless-render it. When available, **`himi test` needs no test files** — it derives the checks from the actions your descriptors already
+  declare: it boots each screen's real worker, dispatches each action from a fresh boot, and reports
+  anything that threw, stayed stuck on `loading`, or leaked a `NaN`/`undefined`/`$service:` token into
+  visible text. It is the only local check that catches a WRONG REDUCER, and it runs the worker in a
+  device-parity sandbox (no `setTimeout`/`setInterval`, as on JSC/WebView) so a bundle that would only
+  die on the device fails locally instead. **`himi render --live` is
+  the sanctioned way to prove real-data binding with NO VPN and NO push** — it mints an anonymous
+  visitor token from the app's Wix `clientId` and **awaits the worker's real fetches** against live
+  Wix, so the render shows LIVE data (not just the empty initial state) and catches live-only binding
+  bugs locally. The CLI **ships its own `@wix/himalaya` runtime**, so it resolves `@himalaya/*`
+  on its own — `build` / `validate` / `render` work with **no per-app `node_modules` at all**. A
+  per-app `npm i @wix/himalaya` is **optional** (it only lets your editor / `tsc` resolve
+  `@himalaya/*` types locally) and is the one install still **VPN-gated** — that SDK package
+  publishes to the internal registry `npm.dev.wixpress.com`, which is unreachable off-VPN. The
+  CLI itself is not: it comes from public npm.
+- ⛔ **Needs a Wix sign-in:** `himi push` / `promote` publish and activate your release.
+  To change **part** of a release instead of republishing it, `push --only <selector>` publishes
+  just the named items — same build + lint gate, derived from the live release — and `himi patch`
+  does the same from a raw file on a machine with no content package. Both require an explicit
+  `--draft` or `--live`: a partial publish has no safe default, and neither carries an attestation
+  or refreshes the source archive (the output names both). Prefer `push` for anything you would
+  want restorable.
+  After a push, **`context` / `screens` / `diagnose` / `deeplinks` / `render --remote` /
+  `telemetry` / `logs`** read back from what you published (over `/v1/preview/…`,
+  `/v1/telemetry/events`, `/v1/telemetry/logs`), and so does **`himi dist`**
+  (a QA binary — see *Shipping* below), which you rarely need. Authenticate once with
+  **`himi login --browser`**: it signs you in with your own Wix account and stores a scoped
+  token, so nothing is ever hand-pasted. (`--wix` uses the machine's own Wix CLI credential
+  instead — the mode a CI container can satisfy. Wix employees can use `--dpx`.)
+  Everything up to the push runs locally.
+
+## Optional push notifications
+
+Interactive `himi init my-app` offers **Set up now / Later — continue building** after
+creating the project, with or without a template. Missing credentials or failed setup do not
+fail app creation. Use `--no-push-setup` to defer deliberately. Non-interactive runs,
+`--json`, and `init --yes` do not prompt or configure push unless `--push-setup` is
+explicitly supplied. Never combine `--push-setup` and `--no-push-setup`.
+
+Resume when the customer has a Wix site and the required keys:
+
+```sh
+himi login --browser --target wix
+wix login
+himi notify setup --content ./my-app --target wix
+himi notify status --content ./my-app --target wix --refresh --json
+```
+
+**Browser login alone is not sufficient for site authorization today.** Setup and status
+also use the Wix CLI account credential; use the same customer account for both logins.
+The CLI verifies app ownership and site access. A new app can be claimed as part of confirmed
+setup. Existing public bindings are reused and the prompts collect missing values.
+
+Supply the APNs key by local file path, its Key ID, Apple Team ID, bundle ID and environment;
+align the Android application ID with Firebase. The current wizard requires APNs input and
+has no separate Android-only mode. For automatic Apple signing, choose that option or use
+`--apple-signing` with a separate App Store Connect key file, Key ID and Issuer ID.
+Review the public plan before confirmation; agents use `--yes` only for authorized setup.
+Keys are transmitted to the authenticated backend for Branded/Ping custody, not copied into
+project settings or output. Enter Later to defer and continue building.
+
+`notify status` is read-only and needs no key files; `--refresh` checks providers live.
+Backend readiness does not prove notification delivery. This setup does not rewrite native
+configuration, select a Ping family, build a binary, register a device or send a notification.
+Continue building and publishing app content. Customer iOS push testing through `himi dist`
+is blocked until the hosted build service supports customer signing keys; the current Wix-managed QA
+binary cannot test the customer's saved push configuration. After an uncertain setup response, inspect status before
+retrying; the CLI does not automatically repeat provisioning.
+
+Full inputs, script flags and status meanings: `himi docs push-cli-onboarding`
+(https://apps.wix.com/_api/himi-serve/docs/push-cli-onboarding.md). The guide is bundled with the public npm package
+and is also served at that public URL. No repository access is required. This is notification setup; `himi push` publishes
+app content. Existing `notify send|tokens|doctor` commands use the local notification server.
+
+## Shipping — over the air by default, a binary only for a native delta
+
+`himi push` → `himi promote` ships screens, Tier-5 bundles, tokens and app-config in **seconds**,
+with no App Store / Play release. That is the normal path and it covers almost every change.
+
+You need an actual **binary** only for a *native* delta: a new SDUI component, a newly declared
+capability/entitlement, a new bundle id, or a `minBinaryVersion` floor bump. For that there is
+`himi dist` — Wix builds and signs a
+real IPA/APK for you and hands back an install link:
+
+```sh
+himi dist --app my-app --platform ios,android --target wix    # waits, prints the install link
+himi dist --app my-app --platform ios --no-wait --target wix  # returns a jobId instead
+himi dist status <jobId> --app my-app --target wix   # or: list --app my-app | cancel <jobId>
+```
+
+The binary is **offline-capable**: the pool bakes the serve release into it — every screen and
+Tier-5 bundle, plus tokens, app-config and the icon — so a fresh install paints with no network.
+iOS returns an **https install page** whose button carries the `itms-services:` URL (chat clients
+won't linkify that scheme, so the page is what you share); open it in Safari on the device.
+
+**Wix-managed QA signing needs no customer signing files.** The pool MINTS a provisioning profile for the app's own
+bundle id per job — there is no profile to pre-provision and nothing to borrow. `--borrow-ios-id
+<bundleId>` still exists as an escape hatch (the binary then installs under *that* id, which is
+fine for QA and wrong for anything else), but it is rarely what you want.
+For customer push credentials, the binary's Apple team, bundle ID and APNs environment must
+match the saved delivery configuration. The current self-serve `himi dist` path uses Wix's
+Apple team and a `com.wix.himi.<app>` bundle ID, so its QA binary cannot test customer iOS
+push. `--signing byo` is not supported. Testing through `himi dist` must wait for the hosted build service
+to support customer signing keys. Notification setup can verify backend configuration now,
+but does not make a matching customer-signed build available.
+
+**Android signing needs nothing either.** `--android-signing` defaults to `qa-keystore` — the
+repo's committed QA key, identical on every pool machine, so a new build installs *over* the last
+one. `--android-signing wix-keystore` signs with the Wix key the pool machine carries and fails
+loudly if it carries none; `debug` is the old per-machine key, where QA must uninstall first.
+
+`--release` is optional: omit it and the plane builds whatever is **live** for the app, recording
+the concrete id it chose. A build takes roughly **4 minutes** (iOS) or **3.5** (Android), and the
+pool parallelises, so dispatching many at once costs about the same as dispatching one.
+
+Full pipeline, signing constraints and how to read a failure: `himi docs qa-builds`.
+
+## Bootstrap a coding agent
+
+Paste this into your coding agent (Claude Code, Cursor, …):
+
+```
+I want to create a mobile app for my business. Follow this skill:
+https://apps.wix.com/_api/himi-serve/skill.md
+```
+
+## Native UX evidence gate
+
+Before declaring a multi-screen app ready, run `himi ux audit --content . --strict` and resolve its findings. After driving each available native shell, persist the actual checks with `himi ux record`; record an unavailable platform with its reason rather than claiming coverage.

package/guides/index.json

@@ -289,6 +289,10 @@
   ],
   "componentReferenceFile": "component-reference.json",
   "sdkReferenceFile": "sdk-reference.json",
+  "skills": {
+    "customer": "skill.md",
+    "technical": "himi-skill.md"
+  },
   "example": {
     "serviceFile": "counter.service.ts",
     "descriptorFile": "counter-t5.descriptor.json",

package/guides/recipe-dynamic-list.md

@@ -6,8 +6,8 @@ stitches together three pieces that are each documented separately but easy to m
 a unit: worker array state → `itemsPath` → an `$item.` row template.
 
 Mined from the in-repo reference apps: `apps/himi-owner-lite` (products/services/events/posts
-lists) and `apps/family-cart` (cart list). The `examples/dynamic-list.*` pair that
-`himi agent-init` writes is a distilled, runnable version of this recipe.
+lists) and `apps/family-cart` (cart list). The `examples/dynamic-list.*` pair in
+the app's `.agents/skills/himalaya/examples/` (written by `himi init` and `himi agent-init`) is a distilled, runnable version of this recipe.
 
 **Which components?** `LazyList` (vertical list, swipe actions, virtualized) or
 `Grid` with `columns: 1` (simple stacked rows; bump `columns`/`columnsMedium` for
@@ -251,4 +251,4 @@ Mechanics and the prod caveat in full: `himi docs tier-5-add-a-screen`.
 - `himi docs tier-5-add-a-screen` — the full worker/descriptor authoring loop.
 - `himi docs designing-himi-screens` — layout idioms + screen-state patterns.
 - `himi components LazyList` / `himi components Grid` — the full prop surface.
-- `examples/dynamic-list.*` (written by `himi agent-init`) — this recipe, runnable.
+- `.agents/skills/himalaya/examples/dynamic-list.*` (written into the app by `himi init` / `himi agent-init`) — this recipe, runnable.

package/guides/recipe-form-submit.md

@@ -7,8 +7,8 @@ half of CRUD (new product, edit post, contact form…). The load-bearing contrac
 per-keystroke state.
 
 Mined from `apps/himi-owner-lite` (product/post/service/event forms — `buildForm` +
-the `himi-owner-lite-*-form` workers). The `examples/form-submit.*` pair that
-`himi agent-init` writes is a distilled, runnable version.
+the `himi-owner-lite-*-form` workers). The `examples/form-submit.*` pair in
+the app's `.agents/skills/himalaya/examples/` (written by `himi init` and `himi agent-init`) is a distilled, runnable version.
 
 ## 1. The descriptor: `Form` + `FormField`s + a submit `Button`
 
@@ -171,4 +171,4 @@ shape (heading swap, `savedScreenId`, back-navigation).
 - `himi docs recipe-four-state` — the state-machine idiom this recipe leans on.
 - `himi docs recipe-dynamic-list` — the list the created entity lands in.
 - `himi components Form` / `FormField` / `TextField` / `Toggle` / `Picker`.
-- `examples/form-submit.*` (written by `himi agent-init`) — this recipe, runnable.
+- `.agents/skills/himalaya/examples/form-submit.*` (written into the app by `himi init` / `himi agent-init`) — this recipe, runnable.

package/guides/recipe-onboarding.md

@@ -8,8 +8,8 @@ separate onboarding screen to route around, works identically on iOS, Android
 and web.
 
 Mined from `apps/himi-branded-lite` (the home screen's first-run card). The
-`examples/onboarding.*` pair that `himi agent-init` writes is a distilled,
-runnable version.
+`examples/onboarding.*` pair in the app's `.agents/skills/himalaya/examples/` (written by `himi init` and `himi agent-init`)
+is a distilled, runnable version.
 
 ## 1. The worker: read the flag at boot, persist on dismiss
 
@@ -128,4 +128,4 @@ const svc = defineService<State, {
 
 - `himi docs recipe-four-state` — the same `hiddenWhen`/display-string idiom.
 - `himi docs designing-himi-screens` — copy + hierarchy guidance for the card.
-- `examples/onboarding.*` (written by `himi agent-init`) — this recipe, runnable.
+- `.agents/skills/himalaya/examples/onboarding.*` (written into the app by `himi init` / `himi agent-init`) — this recipe, runnable.

package/guides/recipe-search.md

@@ -6,8 +6,8 @@ network round-trip per keystroke, instant results, and the empty state can say
 *why* it's empty.
 
 Mined from the Himi Blog app's `himi-blog-feed` worker (search + category chips
-over posts). The `examples/search-list.*` pair that `himi agent-init` writes is a
-distilled, runnable version. Builds on `himi docs recipe-dynamic-list` — read that
+over posts). The `examples/search-list.*` pair in the app's `.agents/skills/himalaya/examples/` (written by `himi init`
+and `himi agent-init`) is a distilled, runnable version. Builds on `himi docs recipe-dynamic-list` — read that
 first; this recipe only adds the query layer.
 
 ## 1. The descriptor: `SearchField` → one debounced action
@@ -108,4 +108,4 @@ change — only the action's body.
 - `himi docs recipe-dynamic-list` — the list this recipe filters.
 - `himi docs recipe-four-state` — the emptyText/error/loading strings.
 - `himi components SearchField` / `FilterChips` / `Tabs`.
-- `examples/search-list.*` (written by `himi agent-init`) — this recipe, runnable.
+- `.agents/skills/himalaya/examples/search-list.*` (written into the app by `himi init` / `himi agent-init`) — this recipe, runnable.