@wix/himalaya-cli 0.1181.0 → 0.1183.0

package/dist/cli.mjs

@@ -1391,6 +1391,21 @@ function defaultWorkerTsconfig() {
 function offRepoImports(body) {
   return body.replace(/(["'])@himalaya\/([^"']+)\1/g, "$1@wix/himalaya/$2$1");
 }
+function templateTakesBase44AppId(template) {
+  if (!availableTemplates().includes(template)) return void 0;
+  const config = join3(templateSourceDir(template), "config.ts");
+  return existsSync2(config) && readFileSync3(config, "utf8").includes(`"${BASE44_APP_ID_PLACEHOLDER}"`);
+}
+function applyBase44AppId(dir, appId2) {
+  if (!BASE44_APP_ID_RE.test(appId2)) throw new Error(`"${appId2}" is not a Base44 app id (8\u201364 letters and digits)`);
+  const config = join3(dir, "config.ts");
+  if (!existsSync2(config)) return false;
+  const body = readFileSync3(config, "utf8");
+  const literal = `"${BASE44_APP_ID_PLACEHOLDER}"`;
+  if (!body.includes(literal)) return false;
+  writeFileSync3(config, body.replaceAll(literal, `"${appId2}"`));
+  return true;
+}
 function templateIconPath(name) {
   if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) return null;
   const p = join3(TEMPLATE_ICONS_DIR, `${name}.png`);
@@ -1785,7 +1800,7 @@ A per-app \`npm i @wix/himalaya\` is optional and only buys your editor local ty
   );
   return finishScaffold({ dir, files, ...kept.length ? { kept: kept.sort() } : {} });
 }
-var PLAN_FILES, PACKAGE_GITIGNORE, MODULE_SOURCE_FILE, TEMPLATES_DIR, SHOWCASE_TEMPLATES_DIR, SHOWCASE_TEMPLATE_NAMES, TEMPLATE_META_FILE, TEMPLATE_ICONS_DIR, HEX_COLOR, PALETTE_KEYS, IDENTITY_SENTINELS, SENTINEL_RE, escapeRe, NAME_FIELDS, IDENTITY_FILES, DOTID_RE, BINARY_EXTENSIONS, extOf;
+var PLAN_FILES, PACKAGE_GITIGNORE, MODULE_SOURCE_FILE, TEMPLATES_DIR, SHOWCASE_TEMPLATES_DIR, SHOWCASE_TEMPLATE_NAMES, BASE44_APP_ID_PLACEHOLDER, BASE44_APP_ID_RE, TEMPLATE_META_FILE, TEMPLATE_ICONS_DIR, HEX_COLOR, PALETTE_KEYS, IDENTITY_SENTINELS, SENTINEL_RE, escapeRe, NAME_FIELDS, IDENTITY_FILES, DOTID_RE, BINARY_EXTENSIONS, extOf;
 var init_scaffold = __esm({
   "src/scaffold.ts"() {
     init_source_deny();
@@ -1796,7 +1811,9 @@ var init_scaffold = __esm({
     MODULE_SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/i;
     TEMPLATES_DIR = resolve2(dirname2(fileURLToPath(import.meta.url)), "../templates");
     SHOWCASE_TEMPLATES_DIR = resolve2(dirname2(fileURLToPath(import.meta.url)), "../showcase-apps");
-    SHOWCASE_TEMPLATE_NAMES = ["video-courses"];
+    SHOWCASE_TEMPLATE_NAMES = ["video-courses", "base44-starter"];
+    BASE44_APP_ID_PLACEHOLDER = "ReplaceWithYourBase44AppId";
+    BASE44_APP_ID_RE = /^[A-Za-z0-9]{8,64}$/;
     TEMPLATE_META_FILE = "himalaya.template.json";
     TEMPLATE_ICONS_DIR = resolve2(dirname2(fileURLToPath(import.meta.url)), "../template-icons");
     HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
@@ -6790,7 +6807,6 @@ function walk(node, registry, path2, out2) {
 var SYSTEM_FONT_FAMILY, TONAL_ELEVATION_ALPHA, COLOR_TOKEN_PROPS, TYPOGRAPHY_TOKEN_PROPS;
 var init_tokens = __esm({
   "../../core/ts/src/tokens.ts"() {
-    "use strict";
     SYSTEM_FONT_FAMILY = "$system";
     TONAL_ELEVATION_ALPHA = [0, 0.05, 0.08, 0.11, 0.12, 0.14];
     COLOR_TOKEN_PROPS = {
@@ -24526,7 +24542,6 @@ function shouldRevealError(args) {
 var EMAIL_RE, URL_HOST_RE, INTEGER_RE, NUMBER_RE;
 var init_validation = __esm({
   "../../core/ts/src/validation.ts"() {
-    "use strict";
     EMAIL_RE = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}$/;
     URL_HOST_RE = /^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*(:[0-9]+)?$/;
     INTEGER_RE = /^[+-]?[0-9]+$/;
@@ -25186,7 +25201,6 @@ function validateWorkerSubtree(raw, slotId, policy, actionCatalog) {
 var WORKER_SUBTREE_CEILINGS, ID_PART, ACTION_ID;
 var init_worker_subtree = __esm({
   "../../core/ts/src/worker-subtree.ts"() {
-    "use strict";
     init_worker_subtree_safe_types_generated();
     WORKER_SUBTREE_CEILINGS = Object.freeze({
       maxEncodedBytes: 65536,
@@ -78140,9 +78154,11 @@ var USAGE = `himi \u2014 the Himalaya authoring CLI (remote dev loop)
                                            create/store or inspect CAPTCHA keys (not login tokens).
                                            Setup needs final --ios-bundle-id / --android-package-name.
 
-  himi init <name> [--dir <parent>] [--template <t>] [--remote] [--push-setup | --no-push-setup] [--no-agent] [--no-first-look]
+  himi init <name> [--dir <parent>] [--template <t>] [--remote] [--base44-app-id <id>] [--push-setup | --no-push-setup] [--no-agent] [--no-first-look]
                                            scaffold a starter content package (--template <t> starts
-                                           from a reference app; --remote fetches it off the serve plane),
+                                           from a reference app; --remote fetches it off the serve plane;
+                                           --base44-app-id writes a Base44 app id into a Base44 template
+                                           such as base44-starter \u2014 himi docs base44-app-to-himi-app),
                                            with the agent files inside it (AGENTS.md, CLAUDE.md, the himalaya
                                            skill, a session-start hook); --no-agent skips them. Also makes
                                            the build board (no browser is opened) and the first picture of
@@ -78873,7 +78889,7 @@ WHAT A PATCH DOES NOT CARRY \u2014 all reported in the output, never silent
   himi docs releasing-with-himi-serve`;
 var COMMANDS2 = [
   { name: "captcha", summary: "create and store native CAPTCHA keys in Serve, or inspect setup status; customer setup verifies Wix site ownership; does not enable member CAPTCHA SDKs", required: "setup|status --app <app> [--content <dir>] [--site <msid>] [--ios-bundle-id <id>] [--android-package-name <id>] [--target <t>]" },
-  { name: "init", summary: "scaffold a starter content package (OTA-only; no native shells). --template <t> starts from a full reference app (branded-lite = consumer storefront over a Wix site; owner-lite = owner CRUD/management) instead of the minimal counter; --templates lists bundled ones; --remote fetches the template off the serve plane (falls back to the bundled copy offline). The new app also gets its agent files (the same set `himi agent-init` writes: AGENTS.md, CLAUDE.md, the himalaya skill, HIMALAYA.md, a SessionStart hook) so the next session started inside it picks the work up; --no-agent skips them. It also makes the build board (.himi/studio/, exactly as `himi studio --no-open` does \u2014 it never opens a browser), so every later render, test, validate, push and progress entry refreshes it; and, for a template bundled with this CLI, it makes the FIRST PICTURE itself (never for a --remote one: that is its publisher's code, and a render runs it on this machine, so next[] leaves the render to the agent after it has read the code): exactly `himi render <homeScreenId> --png --mocks --device iphone` (offline \u2014 no request; never --live; --mocks loads the app's recorded data when it has any), run as a child it kills after a time budget, writing .himi/shots/<home>.png and journaling it (by: himi) as the STARTING POINT (\"Starting point: the <template> template, before any of your changes\") so the board and the journal hold a picture when init returns. init also records the source it wrote (.himi/init-source.json: a content fingerprint, Markdown left out), and the first home PNG render after the source diverges from it is journaled once as \"First look at your app\" \u2014 reported as `firstLook: {image}` or `{skipped: <reason>}`, never a failed init; `--no-first-look` skips it (for scripts and CI that render themselves). For a bundled template (never a --remote one \u2014 the preview would build and serve its publisher's code) init also STARTS the live preview itself: `himi run --watch --content <dir> --port <p> --no-open --idle-exit 30`, detached in its own process group with its output in .himi/watch.log, never waited for (the url is chosen before it builds), recorded in .himi/watch.json, and reported as `watch: {started, pid, url, board, log}` \u2014 or `{skipped: <reason>}` for a `CI` environment, a test runner, a watch already running, or a start that failed (never a failed init). Nothing else skips it: outside CI it is started, and `watch.note` says an opt-out was ignored. The envelope LEADS with `doNow`: three lines to run now (the consent preflight, the live preview \u2014 its url and board when init started it, else `himi run --watch --content <dir> &` with the board's path \u2014 and the postcard line), and ENDS with the same lines as `doNowAgain`, so an agent that reads only the head or only the tail (`| tail`) gets them; at a terminal they are also printed as plain text on stderr, before the JSON and again after it. Its `next[]` LEADS with the steps for THIS session, in this order for every app \u2014 the offline first render and that picture's `himi progress` postcard (only when init could not make the picture), the skill's consent preflight (authorize or mock any Wix or external startup request; with none, go straight on), and only then the live preview (the running one's url, or `himi run --watch &` when init did not start it) \u2014 ahead of the next-session guidance", required: "<name> [--dir] [--template <t>] [--remote] [--no-agent] [--no-first-look] | --templates" },
+  { name: "init", summary: "scaffold a starter content package (OTA-only; no native shells). --template <t> starts from a full reference app (branded-lite = consumer storefront over a Wix site; owner-lite = owner CRUD/management) instead of the minimal counter; --templates lists bundled ones; --remote fetches the template off the serve plane (falls back to the bundled copy offline). The new app also gets its agent files (the same set `himi agent-init` writes: AGENTS.md, CLAUDE.md, the himalaya skill, HIMALAYA.md, a SessionStart hook) so the next session started inside it picks the work up; --no-agent skips them. It also makes the build board (.himi/studio/, exactly as `himi studio --no-open` does \u2014 it never opens a browser), so every later render, test, validate, push and progress entry refreshes it; and, for a template bundled with this CLI, it makes the FIRST PICTURE itself (never for a --remote one: that is its publisher's code, and a render runs it on this machine, so next[] leaves the render to the agent after it has read the code): exactly `himi render <homeScreenId> --png --mocks --device iphone` (offline \u2014 no request; never --live; --mocks loads the app's recorded data when it has any), run as a child it kills after a time budget, writing .himi/shots/<home>.png and journaling it (by: himi) as the STARTING POINT (\"Starting point: the <template> template, before any of your changes\") so the board and the journal hold a picture when init returns. init also records the source it wrote (.himi/init-source.json: a content fingerprint, Markdown left out), and the first home PNG render after the source diverges from it is journaled once as \"First look at your app\" \u2014 reported as `firstLook: {image}` or `{skipped: <reason>}`, never a failed init; `--no-first-look` skips it (for scripts and CI that render themselves). For a bundled template (never a --remote one \u2014 the preview would build and serve its publisher's code) init also STARTS the live preview itself: `himi run --watch --content <dir> --port <p> --no-open --idle-exit 30`, detached in its own process group with its output in .himi/watch.log, never waited for (the url is chosen before it builds), recorded in .himi/watch.json, and reported as `watch: {started, pid, url, board, log}` \u2014 or `{skipped: <reason>}` for a `CI` environment, a test runner, a watch already running, or a start that failed (never a failed init). Nothing else skips it: outside CI it is started, and `watch.note` says an opt-out was ignored. The envelope LEADS with `doNow`: three lines to run now (the consent preflight, the live preview \u2014 its url and board when init started it, else `himi run --watch --content <dir> &` with the board's path \u2014 and the postcard line), and ENDS with the same lines as `doNowAgain`, so an agent that reads only the head or only the tail (`| tail`) gets them; at a terminal they are also printed as plain text on stderr, before the JSON and again after it. Its `next[]` LEADS with the steps for THIS session, in this order for every app \u2014 the offline first render and that picture's `himi progress` postcard (only when init could not make the picture), the skill's consent preflight (authorize or mock any Wix or external startup request; with none, go straight on), and only then the live preview (the running one's url, or `himi run --watch &` when init did not start it) \u2014 ahead of the next-session guidance", required: "<name> [--dir] [--template <t>] [--remote] [--base44-app-id <id>] [--no-agent] [--no-first-look] | --templates" },
   { name: "template", summary: "starter-template catalog + publishing. Every template is a SHOWCASE APP \u2014 a real published release you can open running before you start from it. `list` prints available templates with metadata (title/description/tags) plus each one's start prompt \u2014 pass --remote to include the serve-plane catalog so an agent can pick one; `prompt <name>` prints just that sentence for one template (the skill URL is the public door, or the plane named by --target/--serve-url); `publish` publishes an app AS a `himi init --template` (needs a himalaya.template.json; builds a previewable release + attaches the scaffold source; --source-dir overrides which tree becomes the source, --name sets the template name; bakes a launcher icon \u2014 --icon <png>, or the committed template-icons/<name>.png \u2014 and extracts accent/palette gallery meta from the scaffold's tokens.json; --visibility unlisted keeps it out of the /v1/templates catalog \u2014 templates default to public); `trim --keep <ids>` cuts an app scaffolded from a template down to those screens (the home, and any screen the navigation pins such as a drawer body, always stays) \u2014 it deletes the other SCREENS/TEMPLATED entries whole, prunes navigation (linkableScreens, tabBar, drawer, deep links, surfaces) and drops tier5-src workers no kept screen uses, then runs validate --strict and rolls everything back if it fails (--force keeps it, --dry-run writes nothing). A kept screen that links to a removed one is refused unless --links follow (keep those too) or --links drop (remove the taps). Adopting one: `inspect` writes the adoption inventory (.himi/adopt.json: screens, workers, which screens can call Wix/network on appear \u2014 bootsOffline \u2014 placeholder and sample copy, proposed Data access rows, typed-journey stubs); `screens` lists, shows, rewrites or adds ONE dev/index.ts entry; `sweep` replaces sample identity/copy inside string literals; `recommend` ranks the catalog for a business description or a site's verticals; `trim --from-spec` takes the kept screens from SPEC.md's Screen catalogue", required: "list [--remote] | prompt <name> | publish [--dir <app>] [--source-dir <dir>] [--name <n>] [--icon <png>] [--visibility public|unlisted] [--target <t>] | trim --keep <id,id,\u2026>|--from-spec [SPEC.md] [--content <dir>] [--links follow|drop] [--dry-run] [--force] | inspect [--content <dir>] [--dry-run] | screens [--show <id>] [--write <id> --from <file>] [--add <id> --from <file>] | sweep --set 'Old=>New' | --map <file> [--dry-run] | recommend [--text <t>] [--verticals a,b] [--book <dir>] [--remote]" },
   { name: "build", summary: "compile tier5-src/<name>/index.ts -> dist/bundles/<name>.bundle.js with esbuild (--binary = resolve published @himalaya/*); semantic TypeScript checking belongs to himi validate", required: "[--content <dir>] [--binary]" },
   { name: "functions", summary: "inspect/invoke server functions and operate durable jobs or schedules", required: "list|describe|openapi|invoke | jobs list|get|cancel|retry|dlq | schedule describe|invoke [--app <a>] [--environment preview|production] [--release <id>]" },
@@ -80030,7 +80046,9 @@ function keptPlan(kept) {
   const note = keptPlanNote(kept);
   return note ? { kept, note } : {};
 }
-async function initFromRemoteTemplate(name, parentDir, template, c) {
+var NoBase44SlotError = class extends Error {
+};
+async function initFromRemoteTemplate(name, parentDir, template, c, opts = {}) {
   const dir = resolve56(parentDir, name);
   if (existsSync73(join74(dir, "himalaya.content.json"))) {
     throw new Error(`content package already exists at ${dir}`);
@@ -80041,6 +80059,9 @@ async function initFromRemoteTemplate(name, parentDir, template, c) {
   if (!archive?.files || typeof archive.files !== "object") {
     throw new Error(`template "${template}" returned no source files`);
   }
+  if (opts.requireBase44Slot && !String(archive.files["config.ts"] ?? "").includes(`"${BASE44_APP_ID_PLACEHOLDER}"`)) {
+    throw new NoBase44SlotError(`template "${template}" has no Base44 app id to fill`);
+  }
   return finishScaffold(materializeSource(archive.files, name, dir), template);
 }
 function contentDir(flags) {
@@ -80955,6 +80976,26 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
         }
         const template = str9(flags.template);
         const parentDir = resolve56(str9(flags.dir) ?? process.cwd());
+        const base44AppId = flags["base44-app-id"] === void 0 ? void 0 : String(flags["base44-app-id"]);
+        if (base44AppId !== void 0) {
+          if (!BASE44_APP_ID_RE.test(base44AppId)) {
+            io.error(JSON.stringify({ error: `--base44-app-id "${base44AppId}" is not a Base44 app id (8\u201364 letters and digits)`, hint: "it is the id in your app's URL: https://app.base44.com/apps/<id>" }));
+            return 2;
+          }
+          if (!template) {
+            io.error(JSON.stringify({ error: "--base44-app-id needs --template (e.g. --template base44-starter)" }));
+            return 2;
+          }
+          if (flags.remote !== true && templateTakesBase44AppId(template) === false) {
+            io.error(JSON.stringify({ error: `template "${template}" has no Base44 app id to fill`, hint: "use --template base44-starter" }));
+            return 2;
+          }
+        }
+        const base44Applied = (dir) => {
+          if (base44AppId === void 0) return {};
+          if (!applyBase44AppId(dir, base44AppId)) throw new Error(`--base44-app-id: ${dir}/config.ts lost its Base44 app id placeholder`);
+          return { base44: { appId: base44AppId } };
+        };
         const withAgentFiles = async (dir) => {
           const seeded = await seedAgentFilesFor(dir, flags);
           if (!seeded.agent || "error" in seeded.agent) return seeded;
@@ -80999,8 +81040,12 @@ ${doNow.map((l) => `  ${l}`).join("\n")}`);
         if (template && flags.remote === true) {
           let fetched;
           try {
-            fetched = await initFromRemoteTemplate(name, parentDir, template, client2());
+            fetched = await initFromRemoteTemplate(name, parentDir, template, client2(), { requireBase44Slot: base44AppId !== void 0 });
           } catch (e) {
+            if (e instanceof NoBase44SlotError) {
+              io.error(JSON.stringify({ error: e.message, hint: "use --template base44-starter" }));
+              return 2;
+            }
             if (!availableTemplates().includes(template)) {
               io.error(JSON.stringify({ error: `remote template "${template}" unavailable: ${e.message}`, hint: "check the template name with `himi template list --remote`, or drop --remote to use a bundled template" }));
               return 1;
@@ -81008,17 +81053,23 @@ ${doNow.map((l) => `  ${l}`).join("\n")}`);
             io.error(JSON.stringify({ warning: `remote template fetch failed (${e.message}); falling back to the bundled "${template}"` }));
           }
           if (fetched) {
+            const b442 = base44Applied(fetched.dir);
             const agent2 = await startSession(fetched.dir, await withAgentFiles(fetched.dir), "remote");
             const pushSetup2 = await offerPushSetup2({ contentDir: fetched.dir, flags, io, deps: { validate: createTrimValidator(deps) } });
-            print({ ok: true, doNow: agent2.doNow, app: name, dir: fetched.dir, template, source: "remote", files: fetched.files, ...keptPlan(fetched.kept), ...agent2, ...await adoptAtInit(fetched.dir), pushSetup: pushSetup2, doNowAgain: agent2.doNow });
+            print({ ok: true, doNow: agent2.doNow, app: name, dir: fetched.dir, template, source: "remote", files: fetched.files, ...b442, ...keptPlan(fetched.kept), ...agent2, ...await adoptAtInit(fetched.dir), pushSetup: pushSetup2, doNowAgain: agent2.doNow });
             sayDoNow(agent2.doNow, true);
             return 0;
           }
         }
+        if (base44AppId !== void 0 && template && templateTakesBase44AppId(template) === false) {
+          io.error(JSON.stringify({ error: `template "${template}" has no Base44 app id to fill`, hint: "use --template base44-starter" }));
+          return 2;
+        }
         const res = scaffoldContentPackage(name, parentDir, template);
+        const b44 = base44Applied(res.dir);
         const agent = await startSession(res.dir, await withAgentFiles(res.dir), "bundled");
         const pushSetup = await offerPushSetup2({ contentDir: res.dir, flags, io, deps: { validate: createTrimValidator(deps) } });
-        print({ ok: true, doNow: agent.doNow, app: name, dir: res.dir, ...template ? { template, source: "embedded" } : {}, files: res.files, ...keptPlan(res.kept), ...agent, ...template ? await adoptAtInit(res.dir) : {}, pushSetup, doNowAgain: agent.doNow });
+        print({ ok: true, doNow: agent.doNow, app: name, dir: res.dir, ...template ? { template, source: "embedded" } : {}, files: res.files, ...b44, ...keptPlan(res.kept), ...agent, ...template ? await adoptAtInit(res.dir) : {}, pushSetup, doNowAgain: agent.doNow });
         sayDoNow(agent.doNow, true);
         return 0;
       }

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

@@ -0,0 +1,241 @@
+# From a Base44 app → a native Himi app
+
+This page takes an agent from a [Base44](https://base44.com) app to a running Himi app that
+uses that app's backend, with the himi CLI alone:
+
+```
+himi base44 analyze  →  himi init --template base44-starter  →  one list + detail per entity  →  himi test  →  himi run / Himi Player
+```
+
+The Base44 app keeps its data, its users and its backend functions. The Himi app is a native UI
+over them: every screen is a Tier-5 worker that calls the app through the `base44` capability
+(`@wix/himalaya/base44` off-repo, `@himalaya/base44` in this repo). Nothing is copied out of
+Base44 and nothing is written back to it except through the same API calls the web app makes.
+
+> Read [`base44-app-context`](base44-app-context.md) (`himi docs base44-app-context`) for what the
+> book contains and what it never collects. This page is what to *do* with the book.
+
+## 0. What you need
+
+- The Base44 **app id**: the id in the app's editor URL, `https://app.base44.com/apps/<id>`. It
+  is a public id, not a secret.
+- For the full book (entities, functions, auth), a Base44 session as the app's owner or an
+  editor: `himi base44 login` (or `BASE44_ACCESS_TOKEN`). Without one, `--url` reads only what
+  any visitor sees, which has no entity schemas.
+
+## 1. Read the app into a book
+
+```bash
+himi base44 analyze --app-id <id>            # owner pass → .himi/base44-book/
+```
+
+Read `.himi/base44-book/BOOK.md` first, then `book.json` for detail. Check `gaps[]` before you
+plan: a missing `entities` chapter means you have no schemas to build from, so sign in and run it
+again instead of guessing fields.
+
+The parts of the book this procedure uses:
+
+| Book field | Drives |
+|---|---|
+| `identity.name`, `identity.colors`, `look` | the app name, `tokens.json` accent and surfaces |
+| `entities[]` (`name`, `fields[]`, `required`, `rls`, `sampleRows`) | one list + detail (+ form) per entity |
+| `routes[]` (`path`, `component`, `entities`) | which entities the web app treats as primary, so which get a tab |
+| `auth.visibility`, `auth.providers` | whether the app needs the Account tab, and which sign-in it offers |
+| `functions[]` (`name`, `kind`, `invoke`) | actions on the screens that need them |
+| `agents[]`, `connectors[]`, `secrets.names` | nothing on the device. See [What the SDK cannot do](#what-the-sdk-cannot-do) |
+
+## 2. Scaffold from the starter
+
+```bash
+himi init my-app --template base44-starter --base44-app-id <id>
+cd my-app
+```
+
+`base44-starter` is a complete, working app over any Base44 app with a `Task` entity. To try it
+before pointing it at yours, pass the public sample app (`--base44-app-id 69725232345f461f64ad1623`),
+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 |
+| Functions | `b44_functions` | `functions` | `functions.invoke(name, payload)` with the reply and the error painted |
+| Account | `b44_account` | `account` | Base44 email + password and emailed-code sign-in, register, reset, profile, sign out |
+
+`config.ts` declares `capabilities: ["base44"]` and `base44: { appId }`. `--base44-app-id` writes
+the id there, and that line is the only place it is read from. Without the flag the id is the
+placeholder `ReplaceWithYourBase44AppId`, which talks to no app, so every screen shows its error
+state until you edit it in. A malformed id (anything but 8–64 letters and digits) is refused before
+anything is written.
+
+Run it once before you change anything, so you know the starter works against your app:
+
+```bash
+himi run --content .                         # web preview — the Tasks tab lists your Task rows
+```
+
+If your app has no `Task` entity, the Tasks tab shows its error state with Base44's own message.
+That is expected: you are about to replace it.
+
+## 3. Plan the screens from the book
+
+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.
+3. **Pick the detail and form fields** from each field's JSON Schema type:
+
+| Field (`type` / `format` / `enum`) | Detail shows | Form control |
+|---|---|---|
+| `string` | `Text` | `TextField` |
+| `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` 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 |
+| 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.
+5. **Use the sample rows** (`sampleRows`, already redacted) to size rows and choose the subtitle,
+   never as data the app ships.
+
+Compose each screen with [`designing-himi-screens`](designing-himi-screens.md)
+(`himi docs designing-himi-screens`): hierarchy, spacing, and the four states.
+
+## 4. Build one list + detail per entity
+
+Copy the Task pair and rename it. For an entity `Project`:
+
+- `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.
+
+The calls a worker makes, all on `entities("<Name>")`:
+
+| Need | Call |
+|---|---|
+| newest first, one page | `.list({ sort: "-created_date", limit: 20, fields: [...] })` |
+| next page | `.list({ sort, limit, skip })` |
+| filtered list (a tab per status, the signed-in user's rows) | `.filter({ status: "open" }, { sort, limit })` |
+| one row | `.get(id)` |
+| create / update / delete | `.create(data)` / `.update(id, patch)` / `.delete(id)` |
+| several rows at once | `.bulkCreate(rows)` |
+
+Rules that keep it correct:
+
+- **The detail is an exact screen fed its id as a nav param**, opened with
+  `himi.open { screenId: "<detail>", id: "$item.id" }`. It is not a templated route, because
+  Base44 row ids exist only at runtime and a release can bake only the ids it knows.
+- **Bindings substitute whole values only.** `"Open $item.title"` renders literally on device.
+  Compute the whole string in the worker (`openLabel: \`Open ${title}\``) and bind
+  `$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`.
+
+## 5. Auth: the Account tab
+
+| `book.auth.visibility` | Do |
+|---|---|
+| `public` | Keep Account only if writes need a user (an `rls` condition on `user`). Otherwise remove it. |
+| `private` / `workspace` | Keep Account, and make it the first thing a signed-out user sees: gate each list's write controls (and, for `private`, the lists themselves) on the account state. |
+
+Offer only the providers in `book.auth.providers` that the SDK supports: `email-password` (with
+the emailed-code form the starter already has). **Do not offer Google, Microsoft, Facebook, Apple
+or SSO sign-in**: the Base44 capability has no social sign-in yet, so those buttons would be dead.
+
+The token never reaches the worker. Native code keeps it (Keychain / encrypted prefs), so the
+session survives a relaunch, and `auth.status()` reports it on the next boot.
+
+An app that lets users sign up must let them delete their account in the app (App Store
+5.1.1(v)). A regular Base44 user cannot delete their own record, so write a backend function that
+does it with the service role. Name it in `config.ts`
+(`base44DeleteAccountFunction = "deleteMyAccount"`) and the Account tab shows the Delete row.
+
+## 6. Functions as actions
+
+Each `book.functions[]` entry with `kind: "invoke"` is callable from a worker as
+`functions.invoke("<name>", payload)`. Put it where the user needs it, not on a debug screen:
+
+- a function that acts on one row (send an invoice, recalculate a total) → a button on that
+  entity's detail screen, passing the row id in the payload, then re-`get` the row;
+- a function that acts on the user (export, invite) → a row on the Account tab;
+- a scheduled or entity-triggered function (`automations`) → nothing on the device. It runs on
+  Base44 by itself.
+
+A `kind: "http"` function serves its own HTTP requests (`Deno.serve`). Call it with
+`functions.invoke` only if it also handles an invoke payload. Otherwise leave it on the web.
+
+Paint the reply and paint the failure: a function that is missing, not deployed or that throws
+must read as an error, never as an empty reply. The Functions tab of the starter is a developer
+tool for trying functions by name. Remove it from the shipped app once each function you need
+has its own button.
+
+## 7. Look
+
+Take `identity.colors` and the `look` chapter into `tokens.json`: `accentPrimary` from the
+brand colour (check that it reaches 4.5:1 on `surfacePrimary` and `surfaceTertiary`, since
+`himi validate` warns when it does not), the app name from `identity.name` into
+`himalaya.content.json`, and the icon with `himi icon set` or `himi icon generate`. Keep the web
+app's words: screen titles, tab labels and empty states come from its pages, not invented copy.
+
+## 8. Test, run, ship
+
+```bash
+himi validate --content . --strict           # zero errors
+himi test --content . --json                 # derived crawl: failures and warnings must be 0
+himi run --content .                         # web preview against the live Base44 app
+```
+
+`himi test` crawls every action against the real workers with hermetic transport, so it proves
+the wiring, not your data. Its gap ledger names what the hermetic crawl could not reach (rows that
+only exist on the live app, for instance). Close a gap with the remedy it names, or accept it.
+Then drive the real flow in `himi run`: list, create, edit, delete a row of each entity, and
+sign in when the app is not public.
+
+**Where it runs.** The web preview and the web Himi Player serve `base44` themselves. A native
+shell has to link the Base44 SDK. The native Himi Player does not link it yet, so it lists a Base44
+release as not supported on that device. A branded native binary of the `himi-base44` shell is
+#3674.
+
+Publish with `himi push` like any other content package.
+
+## What the SDK cannot do
+
+The `base44` capability is `auth.*`, `entities(name).*` and `functions.invoke`. It has no:
+
+- **realtime** subscriptions. Re-list on `onAppear` and on pull-to-refresh instead;
+- **`integrations.*`** (LLM, email, image generation, file storage). Call them from a backend
+  function and invoke that;
+- **file upload**. Upload from a backend function (pass the file's URL or base64 in the payload),
+  or keep the upload on the web app;
+- **agents**, **connectors** or **secrets**. They stay on Base44, and a function that needs one
+  uses it server-side;
+- **service-role** access. A shipped client never holds an admin credential, so anything that
+  needs one is a backend function.
+
+Route each of these through `functions.invoke`. Never put a token, key or secret in a worker or
+in `config.ts`.

package/guides/index.json

@@ -220,6 +220,12 @@
       "category": "CLI & Loop",
       "file": "base44-app-context.md"
     },
+    {
+      "id": "base44-app-to-himi-app",
+      "title": "From a Base44 app → a native Himi app",
+      "category": "CLI & Loop",
+      "file": "base44-app-to-himi-app.md"
+    },
     {
       "id": "headless-business-to-himi-app",
       "title": "From Wix Headless / Back Office → a native Himi app",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1181.0",
+  "version": "0.1183.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": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "b9567648a0cc9010de85880423e53d9ef97a10fb139c7074a2d1cd78"
+  "falconPackageHash": "7ca344d0a8415adec66c315d8b104421a94353b9f7fc240429171467"
 }