@pancake-pos/app-cli 2026.1.4 → 2026.1.6

package/README.md

@@ -4,10 +4,13 @@ The `pos-app` command for Pancake POS apps: `login`, `dev`, `check`, `build`, `d
 
 ```bash
 npx @pancake-pos/app-cli login --shop 123 --token <token>   # from POS › Settings › Advanced › Custom apps › Connect CLI
-npx pos-app dev
-npx pos-app deploy
+npm run dev      # in an app created by create-pos-app (scripts call pos-app)
+npm run deploy
+npx @pancake-pos/app-cli versions   # any command, from anywhere
 ```
 
+Do not run `npx pos-app`: the `pos-app` package on npm is not published by Pancake, and npx downloads it outside an installed project.
+
 Docs: https://pos.pages.fm/developers/apps/en (English), https://pos.pages.fm/developers/apps (Tiếng Việt). For AI tools: https://pos.pages.fm/developers/apps/llms-full.txt.
 
 Part of Pancake POS Apps. Use is limited to building apps for Pancake POS.

package/dist/cli.js

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 
 // src/api.ts
 async function apiRequest(credentials, method, path, body) {
-  if (!credentials.token) throw new ApiError(401, "Ch\u01B0a \u0111\u0103ng nh\u1EADp: ch\u1EA1y `pos-app login` tr\u01B0\u1EDBc");
+  if (!credentials.token) throw new ApiError(401, 'Ch\u01B0a \u0111\u0103ng nh\u1EADp: ch\u1EA1y l\u1EC7nh \u1EDF n\xFAt "K\u1EBFt n\u1ED1i CLI" tr\xEAn trang \u1EE8ng d\u1EE5ng tu\u1EF3 bi\u1EBFn c\u1EE7a POS (npx @pancake-pos/app-cli login \u2026)');
   const headers = { Authorization: `Bearer ${credentials.token}`, Accept: "application/json" };
   let payload;
   if (body instanceof FormData) payload = body;
@@ -73,7 +73,7 @@ function targets(apiVersion) {
     "app.page",
     ...RESOURCES.flatMap((r) => [...locations, "index.column"].map((l) => `${r}.${l}`)),
     ...PRINT_RESOURCES.map((r) => `${r}.print-action`),
-    "customer.details.block"
+    ...CUSTOMER_LOCATIONS.map((l) => `customer.${l}`)
   ];
 }
 function validateManifest(manifest, files) {
@@ -181,7 +181,7 @@ function validateManifest(manifest, files) {
     } else if (target.endsWith(".print-action") && PRINT_RESOURCES.includes(target.slice(0, -".print-action".length))) {
       requiredString(e, "label", 40, path);
       file("module", true);
-    } else if (target.endsWith(".index.column") && RESOURCES.includes(target.slice(0, -".index.column".length))) {
+    } else if (target.endsWith(".index.column") && [...RESOURCES, "customer"].includes(target.slice(0, -".index.column".length))) {
       requiredString(e, "title", 30, path);
       file("module", true);
       if (e.format !== void 0 && !COLUMN_FORMATS.includes(e.format)) add("invalid_field", `${path}.format`, `format ph\u1EA3i l\xE0 ${COLUMN_FORMATS.join(", ")}`);
@@ -192,7 +192,8 @@ function validateManifest(manifest, files) {
       const dot = target.indexOf(".");
       const resource = target.slice(0, dot);
       const location = target.slice(dot + 1);
-      if (!RESOURCES.includes(resource)) return add("unknown_target", `${path}.target`, `Target ${target} kh\xF4ng t\u1ED3n t\u1EA1i`);
+      const customer = resource === "customer" && CUSTOMER_LOCATIONS.includes(location);
+      if (!RESOURCES.includes(resource) && !customer) return add("unknown_target", `${path}.target`, `Target ${target} kh\xF4ng t\u1ED3n t\u1EA1i`);
       if (ACTION_LOCATIONS.includes(location)) {
         requiredString(e, "label", 40, path);
         optionalString(e, "title", 60, path);
@@ -229,7 +230,7 @@ function validOrigin(origin) {
     return false;
   }
 }
-var API_VERSIONS, RESERVED_DOMAINS, RESOURCES, ACTION_LOCATIONS, DETAIL_LOCATIONS, PRESENTATIONS, METHODS, ACCESS_FIELDS, CONDITION_RESOURCES, UUID, PRINT_RESOURCES, COLUMN_FORMATS, COLUMN_ALIGNS, isString, isObject;
+var API_VERSIONS, RESERVED_DOMAINS, RESOURCES, ACTION_LOCATIONS, DETAIL_LOCATIONS, PRESENTATIONS, METHODS, ACCESS_FIELDS, CONDITION_RESOURCES, UUID, CUSTOMER_LOCATIONS, PRINT_RESOURCES, COLUMN_FORMATS, COLUMN_ALIGNS, isString, isObject;
 var init_manifest = __esm({
   "src/manifest.ts"() {
     "use strict";
@@ -252,6 +253,7 @@ var init_manifest = __esm({
       has_customer: ["order"]
     };
     UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    CUSTOMER_LOCATIONS = ["details.block", ...ACTION_LOCATIONS, "index.column"];
     PRINT_RESOURCES = ["order", "purchase", "export", "warehouse_transfer"];
     COLUMN_FORMATS = ["text", "number", "money", "date", "datetime"];
     COLUMN_ALIGNS = ["left", "center", "right"];
@@ -643,7 +645,7 @@ function createSiteHandler(options) {
     if (req.method !== "GET" && req.method !== "HEAD") return send(req, res, 405, { ...textHeaders, Allow: "GET, HEAD" }, "Method not allowed");
     const url = new URL(req.url ?? "/", "http://sandbox");
     const path = url.pathname;
-    if (path === "/_pos/health") return send(req, res, 200, textHeaders, "ok");
+    if (path === "/_pos/health") return send(req, res, 200, options.runtime.version ? { ...textHeaders, "X-Pos-Runtime": options.runtime.version } : textHeaders, "ok");
     if (options.rejectTopLevel && req.headers["sec-fetch-dest"] === "document") {
       return send(req, res, 403, textHeaders, "This app only runs inside Pancake POS");
     }
@@ -1145,7 +1147,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = true ? "2026.1.4" : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    CLI_VERSION = true ? "2026.1.6" : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
   }
 });
 
@@ -1246,6 +1248,8 @@ function isSaved(resource, record) {
 }
 function recordRef(resource, record) {
   switch (resource) {
+    case "customer":
+      return customerRef(record);
     case "order": {
       const systemId = orderSystemId(record) ?? 0;
       return { id: str(record.custom_id) ?? systemId, system_id: systemId, status: num(record.status), updated_at: str(record.updated_at) };
@@ -1374,11 +1378,12 @@ function hideOrderFields(data, hidden) {
   for (const field of hidden) delete draft[field];
   return { ...data, draft };
 }
-var RESOURCES2, MAX_SELECTION, num, str, idOf, ids, list, orderPrice, orderSystemId;
+var RESOURCES2, LIST_RESOURCES, MAX_SELECTION, num, str, idOf, ids, list, orderPrice, orderSystemId;
 var init_records = __esm({
   "../app-host/src/records.ts"() {
     "use strict";
     RESOURCES2 = ["order", "product", "purchase", "export", "warehouse_transfer"];
+    LIST_RESOURCES = [...RESOURCES2, "customer"];
     MAX_SELECTION = 500;
     num = (value, fallback = 0) => typeof value === "number" && Number.isFinite(value) ? value : Number(value) || fallback;
     str = (value) => value === void 0 || value === null || value === "" ? null : String(value);
@@ -1514,17 +1519,18 @@ function describeTarget(target, all = sections()) {
   const [resource, ...rest] = target.split(".");
   const location = target === "nav.item" || target === "app.page" ? target : rest.join(".");
   const plain = target === "nav.item" || target === "app.page";
-  const docHeading = plain ? target : target === "customer.details.block" ? `\`${target}\`` : `\`*.${location}\``;
-  const docs = all.filter((section) => section.page === "targets" && (section.heading === docHeading || section.heading.startsWith(`${docHeading} `)));
+  const customer = resource === "customer";
+  const headings = plain ? [target] : customer ? ["`customer.*`", ...location === "details.block" ? [] : [`\`*.${location}\``]] : [`\`*.${location}\``];
+  const docs = all.filter((section) => section.page === "targets" && headings.some((heading) => section.heading === heading || section.heading.startsWith(`${heading} `)));
   const listData = location === "print-action" || location === "index.column";
-  const data = target === "customer.details.block" ? "CustomerData ({ resource: 'customer', record: CustomerRef })" : DATA[location] ? `${DATA[location]}<'${resource}'>` : target === "app.page" ? "PageData ({ path, query })" : "none (no code)";
+  const data = customer && location.startsWith("details.") ? "CustomerData ({ resource: 'customer', record: CustomerRef })" : DATA[location] ? `${DATA[location]}<'${resource}'>` : target === "app.page" ? "PageData ({ path, query })" : "none (no code)";
   const result = location === "before_submit" ? "BeforeSubmitResult: `{ ok: true, changes?: { note?, add_tags? } }` or `{ ok: false, message }`" : location === "print-action" ? "PrintResult: `{ html, title? }` (POS strips scripts, then prints)" : location === "index.column" ? `ColumnResult: \`{ values: { [${resource === "order" ? "system_id" : "id"}]: string | number | null } }\`` : location.endsWith("action") ? "headless: `{ message?, refresh? }` or nothing; modal/fullscreen: render, call pos.close()" : "nothing (blocks and pages render themselves)";
-  const types = target === "customer.details.block" ? [typeBlock("CustomerRef", all)].filter(Boolean) : DATA[location] ? [typeBlock(`${pascal(resource)}Ref`, all), location === "index.action" || location.endsWith("selection-action") || location === "after_save" || listData ? null : typeBlock(`${pascal(resource)}Draft`, all)].filter(Boolean) : [];
+  const types = customer ? [typeBlock("CustomerRef", all)].filter(Boolean) : DATA[location] ? [typeBlock(`${pascal(resource)}Ref`, all), location === "index.action" || location.endsWith("selection-action") || location === "after_save" || listData ? null : typeBlock(`${pascal(resource)}Draft`, all)].filter(Boolean) : [];
   return [
     `# ${target}`,
     `- Context data (\`pos.data\` and the module argument): \`${data}\``,
     `- Returns: ${result}`,
-    `- Manifest fields: ${target === "customer.details.block" ? "`module` (required), `should_render`. No `conditions`." : MANIFEST[location] ?? ""}`,
+    `- Manifest fields: ${target === "customer.details.block" ? "`module` (required), `should_render`. No `conditions`." : `${MANIFEST[location] ?? ""}${customer ? " No `conditions` for customer targets." : ""}`}`,
     ...types.length ? ["", "```ts", ...types, "```"] : [],
     "",
     "## Example",
@@ -1583,7 +1589,7 @@ function createTools(ctx) {
   let dev = null;
   const devLog = [];
   const shop = () => {
-    if (!ctx.shop) throw new Error("Missing shop: start the server with --shop <shop_id> or run pos-app login --shop <shop_id>");
+    if (!ctx.shop) throw new Error("Missing shop: start the server with --shop <shop_id> or run npx @pancake-pos/app-cli login --shop <shop_id>");
     return ctx.shop;
   };
   const get = (path) => apiRequest(ctx.credentials, "GET", `/shops/${shop()}/${path}`);
@@ -1684,20 +1690,12 @@ ${hit.text.slice(0, 4e3)}`).join("\n\n---\n\n") };
       async run(args) {
         const target = String(args.target ?? "");
         if (target === "app.page") return ok({ target, data: { path: "/", query: {} } });
-        if (target === "customer.details.block") {
-          const id = args.record_id === void 0 ? void 0 : String(args.record_id);
-          const response = id ? await get(`customers/${encodeURIComponent(id)}`) : await get(`customers?page_size=1&page_number=1`);
-          const record2 = id ? response.data ?? response : itemsOf(response)[0];
-          if (!record2 || typeof record2 !== "object") return fail("The shop has no customers the signed-in user can read");
-          return ok({ target, data: customerData(record2) });
-        }
         const [resource, ...rest] = target.split(".");
         const location = rest.join(".");
-        if (!RESOURCES2.includes(resource) || !targets(API_VERSION2).includes(target)) return fail(`Unknown target ${target}`);
+        if (!LIST_RESOURCES.includes(resource) || !targets(API_VERSION2).includes(target)) return fail(`Unknown target ${target}`);
         const record = await sampleRecord(resource, args.record_id === void 0 ? void 0 : String(args.record_id));
         if (!record) return fail(`The shop has no ${resource} records the signed-in user can read`);
-        const r = resource;
-        const data = location === "index.action" ? indexData(r, record) : location === "index.selection-action" || location === "print-action" || location === "index.column" ? selectionData(r, [record]) : location === "after_save" ? afterSaveInput(r, record, "edit") : detailsData(r, record);
+        const data = location === "index.action" ? indexData(resource, record) : location === "index.selection-action" || location === "print-action" || location === "index.column" ? selectionData(resource, [record]) : resource === "customer" ? customerData(record) : location === "after_save" ? afterSaveInput(resource, record, "edit") : detailsData(resource, record);
         const hidden = readManifest(ctx.root).access?.hidden_order_fields;
         return ok({ target, data: "draft" in data ? hideOrderFields(data, hidden) : data });
       }
@@ -1883,7 +1881,8 @@ var init_tools = __esm({
       product: "products",
       purchase: "purchases",
       export: "export",
-      warehouse_transfer: "transfers"
+      warehouse_transfer: "transfers",
+      customer: "customers"
     };
     META_PATHS = {
       order: { warehouses: "warehouses", tags: "orders/tags", order_sources: "order_source" },
@@ -1968,7 +1967,7 @@ async function run(argv, io = defaultIo) {
     const credentials = readCredentials();
     const shopOf = () => {
       const shop = str2(flags.shop) ?? credentials.shop;
-      if (!shop) throw new Error("Thi\u1EBFu --shop <shop_id> (ho\u1EB7c l\u01B0u b\u1EB1ng `pos-app login --shop`)");
+      if (!shop) throw new Error("Thi\u1EBFu --shop <shop_id> (ho\u1EB7c l\u01B0u b\u1EB1ng `npx @pancake-pos/app-cli login --shop`)");
       return shop;
     };
     switch (command) {

package/docs/llms-full.txt

@@ -171,7 +171,7 @@ Details: [Data access](/developers/apps/en/data-access).
 |---|---|
 | PoC | Sandbox, app tokens, order detail block, order action menu item, iframe page, a sample app written by AI |
 | Phase 1 | Upload, versions, rollback, visibility permissions, audit, rate limits, component catalog v1, SDK, CLI |
-| Phase 2 | Available: `before_submit` hook (block saves, set the note and tags), Worker UI pages (`render: "worker"`), app print templates (orders, purchases, exports, transfers), list columns, customer blocks. Not yet: per-app webhooks and service keys, app storage |
+| Phase 2 | Available: `before_submit` hook (block saves, set the note and tags), Worker UI pages (`render: "worker"`), app print templates (orders, purchases, exports, transfers), list columns, customer boxes, actions and columns. Not yet: per-app webhooks and service keys, app storage |
 | Phase 3 | Consider the mobile app, install one app across shops of the same owner |
 
 ---
@@ -259,21 +259,21 @@ npx @pancake-pos/app-cli login --shop 123 --token <token>
 Then run:
 
 ```bash
-npx pos-app dev              # watch and build, serve at http://localhost:5174
+npm run dev                  # watch and build, serve at http://localhost:5174
 ```
 
 On the same management page, click **Development mode** and enter `http://localhost:5174` (see [Manage apps › Development mode](/developers/apps/en/manage-apps#development-mode)). While it is on, POS loads the app from `localhost` **in your browser only**; everyone else in the shop keeps using the active version. When you edit code, POS reloads the extensions without reloading the page. Use Chrome or Edge: Safari may block an `https` page from loading `http://localhost`.
 
-In development mode, `pos.api` can call the Open API only after the app has been uploaded at least once (`npx pos-app deploy`, no activation needed), and it uses the `access` of the latest uploaded version. Deploy again after changing `access`. After each such deploy, reload the POS page so POS gets a new token.
+In development mode, `pos.api` can call the Open API only after the app has been uploaded at least once (`npm run deploy`, no activation needed), and it uses the `access` of the latest uploaded version. Deploy again after changing `access`. After each such deploy, reload the POS page so POS gets a new token.
 
 Development mode runs against the real data of the open shop, so try a test shop first. To see the app as a staff member with narrow permissions, deploy and activate it on a test shop and sign in with that account.
 
-While you write code, an editor with the ESLint extension shows problems as you type. Run `npx pos-app check` to validate the manifest as well.
+While you write code, an editor with the ESLint extension shows problems as you type. Run `npm run check` to validate the manifest as well.
 
 ## 4. Build and upload
 
 ```bash
-npx pos-app deploy
+npm run deploy
 ```
 
 This command:
@@ -420,7 +420,7 @@ The `pos-app` command (and the MCP server) needs a token to upload apps to the s
 
 Development mode lets you try the code you are writing inside real POS without affecting anyone else.
 
-1. On your machine, run `npx pos-app dev` in the app folder (served at `http://localhost:5174` by default).
+1. On your machine, run `npm run dev` in the app folder (served at `http://localhost:5174` by default).
 2. Click **Development mode**, enter the **Dev server address** and click **Enable development mode**.
 
 ![The Development mode dialog](/static/developers/apps/manage/en/dev-mode.webp)
@@ -651,8 +651,8 @@ and a "Send reminder" button that calls https://crm.example.com/api/remind. Read
 - [ ] Modules in `extensions/` use no real DOM, UI libraries or CSS.
 - [ ] No tokens, API keys or secrets in code.
 - [ ] Errors and loading states are handled.
-- [ ] `npx pos-app check` reports no errors.
-- [ ] Tested with `npx pos-app dev` (an account with the Settings permission), then deployed to a test shop and tried with a narrow-permission staff account.
+- [ ] `npm run check` reports no errors.
+- [ ] Tested with `npm run dev` (an account with the Settings permission), then deployed to a test shop and tried with a narrow-permission staff account.
 
 ## Sample AGENTS.md
 
@@ -677,10 +677,11 @@ Docs: https://pos.pages.fm/developers/apps/llms-full.txt (read before changing c
 - Catch errors on every API call; handle 403 and 429.
 
 ## Commands
-- npx pos-app dev: try in POS (turn on Development mode on the custom apps management page); POS reloads when code changes.
+- Run the CLI through the npm scripts below, or as `npx @pancake-pos/app-cli <command>` (login, versions, mcp). Never run `npx pos-app`: the `pos-app` package on npm is not Pancake's, and npx downloads it when the project is not installed.
+- npm run dev: try in POS (turn on Development mode on the custom apps management page); POS reloads when code changes.
 - npx eslint .: check the code after every change; do not add eslint-disable to silence rules.
-- npx pos-app check: validate the manifest and code; fix every error before deploying.
-- npx pos-app deploy: build, validate the manifest, upload a new version.
+- npm run check: validate the manifest and code; fix every error before deploying.
+- npm run deploy: build, validate the manifest, upload a new version (options after --, for example npm run deploy -- --message "...").
 - With the pos-app MCP server: get_target/list_shop_meta/sample_context before writing code, check_app after every change, get_errors after testing in POS, deploy when done (uploads an inactive version; an admin activates it). For a platform bug or a missing feature: draft a report, show it to the user, and call send_feedback only after they agree.
 ````
 
@@ -1158,6 +1159,8 @@ Apply to `*.details.block`.
 | Target | Field | Description |
 |---|---|---|
 | `customer.details.block` | `module` (required), `should_render` | As for blocks; no `conditions`. |
+| `customer.details.action`, `customer.index.action`, `customer.index.selection-action` | As for actions | No `conditions`. |
+| `customer.index.column` | As for `<resource>.index.column` | `values` is keyed by the customer's `id`. |
 | `<resource>.print-action` | `label` (required) | Template name in the "Print template" picker, up to 40 characters. |
 | `<resource>.print-action` | `module` (required) | Module returning `{ html, title? }`. |
 | `<resource>.index.column` | `title` (required) | Column title, up to 30 characters. |
@@ -1166,7 +1169,7 @@ Apply to `*.details.block`.
 | `<resource>.index.column` | `align` | `left`, `center`, `right`. |
 | `<resource>.index.column` | `width` | Column width in px, 60–400, default 140. |
 
-See [Extension points](/developers/apps/en/targets#customer-details-block) for the context data and return values.
+See [Extension points](/developers/apps/en/targets#customer) for the context data and return values.
 
 ### Hook fields
 
@@ -1261,7 +1264,7 @@ Targets attached to a POS record are named `<resource>.<location>`, for example
 | `<resource>.after_save` | After a record is created/updated on the detail form | hook, headless |
 | `<resource>.index.column` | A column in the list | hook, headless |
 | `<resource>.print-action` | A print template in the "Print template" picker (except `product`) | headless, returns HTML |
-| `customer.details.block` | A box in the customer profile | Worker UI |
+| `customer.<location>` | Customer profile and list: `details.block`, `details.action`, `index.action`, `index.selection-action`, `index.column` | See [`customer.*`](#customer) |
 
 `<resource>` is one of `order`, `product`, `purchase`, `export`, `warehouse_transfer`. Products have no `print-action` because they only print barcodes.
 
@@ -1345,6 +1348,7 @@ Example `pos.data` in `purchase.details.action`:
 | `purchase` | `record.id` | `purchase_id`, `purchase_ids` |
 | `export` | `record.id` | `export_id`, `export_ids` |
 | `warehouse_transfer` | `record.id` | `warehouse_transfer_id`, `warehouse_transfer_ids` |
+| `customer` | `record.id` | `customer_id`, `customer_ids` |
 
 ### Types per resource
 
@@ -1663,9 +1667,19 @@ export default defineExtension('order.before_submit', async (data) => {
 
 `*.before_submit` and `*.after_save` only run when the user saves on the detail form in POS web. They do **not** run for changes made elsewhere: the status menu on list rows, bulk updates, Excel import, the Open API, the mobile app or marketplace sync. Rules that must always hold belong on the server.
 
-## `customer.details.block`
+## `customer.*`
 
-A box in the customer profile, in the right column below Notes and Addresses. The profile has this box wherever it opens: the Customers page, the order form and other screens.
+Customers have boxes, actions and columns like the other resources, but **no** `before_submit`, `after_save` (the profile saves each field as soon as it changes; there is no shared Save button) and no print templates.
+
+| Target | Location | Context data |
+|---|---|---|
+| `customer.details.block` | A box in the customer profile, right column below Notes and Addresses | `CustomerData` |
+| `customer.details.action` | An "Apps" button at the top of the customer profile, shown only when an app adds an action here | `CustomerData` |
+| `customer.index.action` | The "⋯" menu at the end of each customer list row, shown only when an app adds an action here | `IndexData<'customer'>` |
+| `customer.index.selection-action` | An "Apps" button on the action bar when several customers are selected | `SelectionData<'customer'>` |
+| `customer.index.column` | A column in the customer list; `values` is keyed by the customer's `id` | `ColumnData<'customer'>` |
+
+The profile has the box and the actions wherever it opens: the Customers page, the order form and other screens. When the customer list is filtered to deleted customers, app actions and columns are hidden.
 
 ```ts
 type CustomerRef = {
@@ -1678,12 +1692,14 @@ type CustomerRef = {
   updated_at: string | null;
 };
 
-type CustomerData = { resource: 'customer'; record: CustomerRef };
+type CustomerData = { resource: 'customer'; record: CustomerRef };   // same shape as IndexData<'customer'>
 ```
 
-- Manifest: `module` (required), `should_render`. No `conditions`.
-- When the customer is edited in the profile, POS emits `data-change` with the new data.
-- As with `*.details.block`, the worker starts when the box scrolls into view; POS shows a placeholder meanwhile.
+- Manifest: the same fields as the target at the same location for other resources (`*.details.action`, `*.details.block`, `*.index.column`…). Customer targets have **no** `conditions`; use `should_render` to hide by data.
+- `refresh` of a headless action and `pos.refresh()` reload the customer list page being viewed; a profile opened from the list gets the new data. A profile opened from the order form or other screens does not reload yet.
+- `navigate` adds `customer_id` or `customer_ids` to the query.
+- When the customer is edited in the profile, the box receives `data-change` with the new data.
+- As with `*.details.block`, the box's worker starts when the box scrolls into view; POS shows a placeholder meanwhile.
 
 ## `*.print-action`
 
@@ -2647,7 +2663,13 @@ const pos = await connect({ timeout: 10_000 });
 
 Every command accepts `--json` for machine-readable output (CI, scripts, the MCP server).
 
-The `pos-app` command is available once `@pancake-pos/app-cli` is installed, so `npx pos-app …` works inside the project folder. Outside a project, call it by package name: `npx @pancake-pos/app-cli <command>`. The `pos-app` package on npm is not published by Pancake.
+How to run the CLI:
+
+- **In a project** created by `create-pos-app`: `npm run dev`, `npm run check`, `npm run build`, `npm run deploy`. Put options after `--`, for example `npm run deploy -- --message "Fix the debt box"`.
+- **Other commands, or from anywhere:** `npx @pancake-pos/app-cli <command>`, for example `npx @pancake-pos/app-cli versions`. In an installed project this uses the project's own version.
+- **Short command everywhere:** install globally with `npm i -g @pancake-pos/app-cli`, then run `pos-app <command>`.
+
+Do not run `npx pos-app`: the `pos-app` package on npm is not published by Pancake. Outside an installed project, npx downloads and runs that package.
 
 Activation and rollback happen on the [custom apps page](/developers/apps/en/manage-apps) in POS, so an admin always approves permissions before an app runs.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pancake-pos/app-cli",
-  "version": "2026.1.4",
+  "version": "2026.1.6",
   "description": "pos-app command for Pancake POS apps: login, dev, check, build, deploy, versions and an MCP server for AI tools",
   "license": "UNLICENSED",
   "type": "module",
@@ -24,6 +24,6 @@
     "esbuild": "^0.28.2",
     "eslint": "^10.12.0",
     "fflate": "^0.8.3",
-    "@pancake-pos/eslint-plugin": "2026.1.4"
+    "@pancake-pos/eslint-plugin": "2026.1.6"
   }
 }

package/runtime/frame.js

@@ -37,5 +37,5 @@ window.addEventListener("message", (event) => {
     else if (data?.t === "kill") kill(data.instance);
   };
 });
-window.parent.postMessage({ t: "frame-ready", protocol: PROTOCOL_VERSION, runtime: "2026.1.4" }, "*");
+window.parent.postMessage({ t: "frame-ready", protocol: PROTOCOL_VERSION, runtime: "2026.1.6" }, "*");
 //# sourceMappingURL=frame.js.map