@lotics/cli 0.238.0 → 0.239.0

package/dist/src/client.d.ts

@@ -424,16 +424,34 @@ export interface ScaffoldWorkspaceResult {
      */
     carried_rules?: string[];
     /**
-     * Every table automation the model declares, with the table workflow it is:
-     * created by this run, or rewritten in place — found through the binding
-     * (`id`) or by its label on its table. Absent from an instance too old to
-     * provision one, which also refuses a model that declares any.
+     * Every table automation the model declares that this run wrote, with the
+     * table workflow it is: created by this run, or rewritten in place — found
+     * through the binding (`id`) or by its label on its table — or `restored`
+     * from archived. `enabled` is whether it fires — a rewrite keeps the owner's
+     * switch — and is absent from an instance too old to say. Absent from an
+     * instance too old to provision one, which also refuses a model that declares
+     * any.
      */
     automations?: Array<{
         alias: string;
         entity: string;
         table_workflow_id: string;
-        bound_by: "created" | "id" | "label";
+        bound_by: "created" | "id" | "label" | "restored";
+        enabled?: boolean;
+    }>;
+    /**
+     * Automations this run neither created nor rewrote: deployed app workflows
+     * write the table each keeps (`keeps`, an entity alias) themselves, and both
+     * writing it would land every row twice. `live` is the table workflow already
+     * writing it beside them — twice NOW — else null. Absent from an instance too
+     * old to hold one back.
+     */
+    held_automations?: Array<{
+        alias: string;
+        entity: string;
+        keeps: string;
+        writers: AppTableWriter[];
+        live: string | null;
     }>;
     /**
      * The account each connection the model declares pushes through: named by the
@@ -496,11 +514,22 @@ export interface BoundTarget {
 export interface BoundField extends BoundTarget {
     options: Record<string, BoundTarget>;
 }
+/** One app workflow alias whose deployed body writes a table's rows. */
+export interface AppTableWriter {
+    app_id: string;
+    app_name: string;
+    workflow_alias: string;
+}
 /** One entity of the model, as this workspace holds it. */
 export interface BoundEntity {
     table: string;
     live_label: string | null;
     fields: Record<string, BoundField>;
+    /**
+     * The deployed app workflows that write this table — only on an entity the
+     * read named in `app_writers`, and absent from an instance too old to say.
+     */
+    app_writers?: AppTableWriter[];
 }
 /**
  * WHAT EACH ALIAS OF A WORKSPACE MODEL BECAME IN ONE WORKSPACE.
@@ -855,7 +884,9 @@ export declare class LoticsClient {
      * additive verb creates a second table over. Admin-only, like the scaffold it
      * is the memory of.
      */
-    getModelBinding(): Promise<ModelBinding>;
+    getModelBinding(opts?: {
+        app_writers?: readonly string[];
+    }): Promise<ModelBinding>;
     /**
      * Forget what one alias is bound to here — the escape from a binding whose
      * target has been deleted. Forgets everything addressed under it too: an
@@ -1466,6 +1497,8 @@ export declare class LoticsClient {
         /** Carry out this write even though it breaks what the app's published API
          *  promises, snapshotting the broken contract as a new version. */
         acknowledge_breaking_api_change?: boolean;
+        /** Run every check the write makes and answer its issues, writing nothing. */
+        verify_only?: boolean;
     }): Promise<ToolExecuteResult>;
     /**
      * Bind (create or replace) an app query by alias via the `set_app_query` tool

package/dist/src/client.js

@@ -396,8 +396,10 @@ var LoticsClient = class {
    * additive verb creates a second table over. Admin-only, like the scaffold it
    * is the memory of.
    */
-  async getModelBinding() {
-    return this.request("GET", "/v1/workspaces/model/binding");
+  async getModelBinding(opts = {}) {
+    const writers = opts.app_writers ?? [];
+    const qs = writers.length === 0 ? "" : `?${new URLSearchParams({ app_writers: writers.join(",") }).toString()}`;
+    return this.request("GET", `/v1/workspaces/model/binding${qs}`);
   }
   /**
    * Forget what one alias is bound to here — the escape from a binding whose
@@ -929,7 +931,10 @@ var LoticsClient = class {
       ...body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {},
       // Sent only when the caller asked for it: absent means "refuse a break",
       // which is the answer a caller who said nothing gave.
-      ...body.acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {}
+      ...body.acknowledge_breaking_api_change ? { acknowledge_breaking_api_change: true } : {},
+      // Sent only when asked: a server that predates it refuses the parameter
+      // rather than performing the write.
+      ...body.verify_only ? { verify_only: true } : {}
     });
   }
   /**

package/docs/building_an_app.md

@@ -219,11 +219,13 @@ A workflow body is a file you open and edit. The new-alias path is typed from th
 2. Write `src/workflows/<alias>.ts`.
 3. `lotics app codegen` — the dts is generated **from your declaration**, so the body gets real
    types (`trigger.app_workflow.inputs.*`, the tool globals) before the alias is bound at all.
-4. `lotics app workflow check` — runs the server's own parse and typecheck locally. It catches the
-   JS-subset rejections that read as ordinary TypeScript: a `function` declaration, a typed
-   parameter, `push` on a const. Those otherwise cost a full push round trip.
-5. `lotics app workflow set <alias>` — the server re-verifies (parse → typecheck → resolve names →
-   lint → structural validate).
+4. `lotics app workflow check` — runs the server's parse and typecheck locally, which catch the
+   JS-subset rejections that read as ordinary TypeScript (an `async` function declaration, a typed
+   parameter). A body clean there is then sent to the server, which answers what `set` would
+   (resolve names → lint → structural validate, table reach, the draft and API guards) and writes
+   nothing; its issues print at `file:line`. With no credentials or network it warns and exits on
+   the local verdict.
+5. `lotics app workflow set <alias>` — the server verifies again and saves.
 
 `outputs` are declared, else **derived** from `return({ status, message, data })` — so a workflow
 that returns an id must keep its `data` clause or the app receives nothing. When derived, `set`

package/docs/cli_reference.md

@@ -22,7 +22,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics workspace settings [--name <n>] [--currency <ISO>] [--timezone <Area/City>]` | Change the CURRENT workspace's name, default currency or timezone — `PATCH /v1/workspace`, admin only. Only what you name changes; the endpoint takes the whole triple, so the CLI carries the two you did not. `rename` is this verb with the name alone, which is why it can never forget the other two. Both values are invisible once they are wrong: the currency decides how every money field RENDERS and the zone decides how every date BUCKETS, on a workspace whose whole purpose may be to look like the customer's own. `--json` prints the updated workspace. |
 | `lotics workspace delete <id> --yes` | Delete a workspace by id (admin only). **Soft delete** — `archived_at` is set, so it drops out of listings, can no longer be selected, and its tables/records go dark, while the data is retained and recoverable. Its **apps are cascade-archived** too — every app entry point (embedded, public link, standalone subdomain, incl. anonymous public links) stops serving. Refuses the org's **only** active workspace (400) and any workspace outside the caller's org (404). Requires `--yes` to confirm (destructive; the CLI is used non-interactively). |
 | `lotics workspace doctor` | Report workspace-wide dangling schema references via `GET /v1/workspaces/dangling-references` — every active app/workflow artifact whose prefixed schema id no longer resolves, printed as `<referent.kind> "<name>" (<id>) → <namespace> <id> (missing)`; healthy prints a one-line all-clear. **Exits non-zero (exit 1) on findings** so scripts can gate on it. Resolves the first workspace like every data command (runs before the global workspace resolution). Admin-only. |
-| `lotics workspace build <model.json> [--dry-run] [--deploy]` | **A plan to live apps in one command**, composed out of the verbs that already own each step — it authors nothing, so every refusal a reader sees is the refusal the underlying command writes. In order: `scaffold check` (a model that does not check stops the run with its findings and nothing is written); the `scaffold diff` join against this workspace, printed; `scaffold apply` **only when that diff found something, or when the model declares a table automation** — a body is not in the export, so it cannot be proven unchanged — because the apply is additive and idempotent but costs a round trip per table and the common case is a model that has not moved; then, per app the plan declares — each after every sibling it names that this run creates, and the first of two apps that name each other built again once the other exists, so a hand-off binds on the first run — `app create --from <model.json>#<alias>` into `<dir-of-model>/<alias-with-dashes>` when that directory does not exist, else `app regenerate` there — which also sets the icon and colour the plan states where the live tile shows otherwise — then `app check`, then `app deploy` under `--deploy` — which unbinds every alias the regeneration retired (see `app deploy`). **One app's failure is not the run's.** A refusal or a red check is recorded and the next app still runs — the author is going to fix that one and run this again, and an app that never ran is an app whose state nobody knows — so the summary at the end carries a line per app (created/regenerated, files rewritten, the check verdict, the version deployed) and the exit code is 1 if any line is bad. **`--dry-run` writes nothing, locally or remotely** — it checks the model, prints the diff and names which apps it would create and which it would regenerate. A regenerated app's bindings ride its own deploy, so the check between the two is told as much rather than refusing the state the regeneration was asked to leave, and a run without `--deploy` ends by naming how many bindings still await one. Admin-only, like the apply it runs. |
+| `lotics workspace build <model.json> [--dry-run] [--deploy]` | **A plan to live apps in one command**, composed out of the verbs that already own each step — it authors nothing, so every refusal a reader sees is the refusal the underlying command writes. In order: `scaffold check` (a model that does not check stops the run with its findings and nothing is written); the `scaffold diff` join against this workspace, printed; `scaffold apply` **only when that diff found something, or when the model declares a table automation** — a body is not in the export, so it cannot be proven unchanged — because the apply is additive and idempotent but costs a round trip per table and the common case is a model that has not moved; then, per app the plan declares — each after every sibling it names that this run creates, and the first of two apps that name each other built again once the other exists, so a hand-off binds on the first run — `app create --from <model.json>#<alias>` into `<dir-of-model>/<alias-with-dashes>` when that directory does not exist, else `app regenerate` there — which also sets the icon and colour the plan states where the live tile shows otherwise — then `app check`, then `app deploy` under `--deploy` — which unbinds every alias the regeneration retired (see `app deploy`). **One app's failure is not the run's.** A refusal or a red check is recorded and the next app still runs — the author is going to fix that one and run this again, and an app that never ran is an app whose state nobody knows — so the summary at the end carries a line per app (created/regenerated, files rewritten, the check verdict, the version deployed) and the exit code is 1 if any line is bad. An automation the apply HELD because an app's deployed bodies still write its table is applied again after the deploys under `--deploy`, since the regenerated apps no longer write it; one still held is a `Held:` line in the summary and exits 1. **`--dry-run` writes nothing, locally or remotely** — it checks the model, prints the diff and names which apps it would create and which it would regenerate. A regenerated app's bindings ride its own deploy, so the check between the two is told as much rather than refusing the state the regeneration was asked to leave, and a run without `--deploy` ends by naming how many bindings still await one. Admin-only, like the apply it runs. |
 | `lotics field rename <table> <field> "<new label>" [--model <file>] [--apps <dir>]` | **One field renamed everywhere it is addressed.** `<table>` and `<field>` each take a name or an id/key. ONE `update_table` call, then the places that call the old name: the label inside a `--model` file (rewritten as JSON, addressed by the entity and field the rename names, so a namesake label elsewhere is left alone), and every `--apps` project (repeatable) whose `src/**/*.{ts,tsx}` addresses `T.<field>`, `F.<TABLE>.<field>` or `OPT.<TABLE>.<field>.*` — each rewritten and then re-codegened, in that order, so no project is left holding new source against the old map. `T.` is rewritten only in a file that binds `const T = F.<TABLE>;` for THIS table: unscoped it would rename a namesake field on whatever table that file is about, which still compiles and reads the wrong column. **The old→new alias pair is read off the table's schema BEFORE and AFTER the write**, never off slugifying the new label alone: an alias is deduped against its neighbours (`ngay`, `ngay_2`), so a rename that frees a slug moves a field nobody touched — and computing it in isolation would leave that one addressed by a key the map no longer has. Everything after the one write reads its result, so a refused rename leaves the file and every project as they were. Admin-only. |
 | `lotics tools` | List tools by category with descriptions |
 | `lotics tools <name>` | Full description + JSON Schema for one tool |
@@ -57,9 +57,9 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics setup <apg_id \| model.json> [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then fills its workspace, then prints the one-time sign-in link. **When that email already has an account it hands over to the `lotics auth login` flow** — it prints the sign-in page to open and the code it must show, and **exits 1 having created nothing**; the person presses Confirm and runs the same command again, which collects the key and carries on into the copy or the model. (`--wait` holds the terminal through the Confirm instead, finishing in one command.) The re-run is not refused for naming an `--email` it is now signed in as — that address IS the account it holds, not a second one. **The argument decides which of the two forms this is, by SHAPE**: a `*.json` file is a workspace MODEL — in either of ITS two forms, spelled out or `{"from": "<preset-slug>", …}` — and anything else is a package id copied through `library init`. The suffix decides it alone — asking the filesystem would answer a long library id with `ENAMETOOLONG` instead of with a verdict — and a model is checked OFFLINE before an account is created, because a file with a typo in it must not leave an organization behind. The model form creates no apps, so its sign-in link lands on the first table it made. It sends no `adopt`: an entity whose `label` already names a table in the workspace is REFUSED with every collision named, and the refusal adds the line the server cannot — `lotics scaffold apply <model.json>`, the verb that adds to the workspace you already have. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently copies a package into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` copies into the account you already have and is a pure alias for `library init`. A path positional is accepted and IGNORED with a warning — `setup` writes nothing to disk — so a prompt that passes one still runs. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_ids` (alias → id), `apps` (each app's `version_number`, or its `error`), `signin_url`, and `created` — which NAMES what landed (`tables`, `templates` and `knowledge_docs` are alias arrays; `sample_records` is a row count, since rows are not named things). Aliases rather than counts because the next question is about a particular artifact: a copied template carries the publisher's wording and a copied knowledge doc describes how they work, so "which of these should be mine?" is the conversation a copy starts, and a count cannot begin it. **The model form emits `entities`, `roles`, `record_ids` and `rows_skipped`** in place of `app_ids` / `apps` / `created` — a model creates no apps and nothing named for a copier to review. **The model form also runs the file's `apply` list** — each named package copied in after the tables exist, with that entry's `bind`, in order, stopping at a refusal with everything before it kept — and emits `applied: [{package, apps}]` beside them; **the sign-in link then lands on the FIRST app any applied package created**, falling back to the first table when the model applied none. Plus a `warnings` array carrying everything the prose form would have said out of band — an unbindable knowledge doc, a sign-in link that could not be minted, the publisher's-code disclosure, an app that landed without a version. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. Reachable with no install: `npx -y @lotics/cli setup …`. |
 | `lotics scaffold docs` | **The model reference, from inside the binary.** Every top-level key of a `model.json`, every field `type` the contract admits with the config each one needs, the option / view / role / inline-template shapes, the row format (relative dates `@today` / `@month-start` with whole-day offsets; links as `"<entity-alias>:<ref>"`), the rules, the `apply` list (packages copied in after the model's own tables, each with an optional `bind` onto them), the `preset` block (a published model's branches and its at-most-two questions), the **`from` form** — `{from, variants, rename, entities, rows, field_roles, apps, apply}`, which names a preset by SLUG instead of restating it — and one complete worked example. **Offline, no account**, and not part of `lotics docs`. |
 | `lotics scaffold check <model.json> [--json]` | **Prove a model before anyone sees it — no network, no credential**, unless the file names a preset. ONE parse of the whole file against the model schema (strict, so `tabels` or `row` is an error rather than a silently dropped key, and a model cannot express what only a starter bundle carries: `fixtures`, `knowledge`, `knowledge_expects`, a file-backed `excel`/`word`/`pdf-form` template; its `apps` are a PLAN of screens, never built code), then `validateWorkspaceModel` — the caps, every cross-reference, and the first rows themselves (a field the entity does not declare, an unknown option alias, a link naming no row in the file, a duplicate `ref`, a date that is not one, a value on a platform-computed field, a files cell that is not a relative path beside the model or a `fil_` id, a document path with no file beside the model), then `field_roles` — every role on a field its type can answer — and the screen plan, every shape's slots bound from those roles, a required slot nothing fills refused. **Reports EVERY problem in one run**, each as `<path>: <message>` in the file's own keys (`entities.0.fields.1.type`, `rows.order.so_1.customer`), so fixing a model is not a round trip per mistake. Exits 1 when there is one; exits 0 with the counts (`N tables, N fields, N links, N views, N roles, N rows`, plus `N apps, N screens` when the file plans any and `N custom` when a screen has no shape), then the plan — one line per screen with the field in each slot — then what the first rows would show, all on stdout. `--json` replaces both with one object and nothing else: `{ok: true, tables, fields, links, views, roles, rows, apps, screens, custom, plan, coverage}` or `{ok: false, findings: [{path, message}]}`. **A `preset` is checked as N models, not one** — every variant merged onto the base (its added entities, and its added fields keyed by entity) and put through the same rules, each finding addressed `preset.variants.<slug>.<path>`, so a preset ships with every branch proven: the branch nobody took is the one that fails in the workspace of whoever takes it, who is the one reader who cannot fix it. A variant's `fields` key naming no declared entity is a finding too — the merge keys on the entity, so a typo'd alias adds those fields to nothing. Same verdict the server reaches, because it runs the server's own functions out of `@lotics/shared` rather than a second implementation of them. **A file written as `{"from": "<preset-slug>", …}` is resolved first** — one GET of that preset's file on the website — and that read is the one step on this path that needs the network; it says so when it cannot make it, and a slug nothing serves is answered with the slugs there ARE, read from the listing, rather than with a 404 the author cannot spell their way out of. Resolution is pure (`resolveModelFrom` in `@lotics/shared`): the named variants merged onto the preset's base in order, then `rename` through the same `applyBinding` a `--bind` goes through, then the file's own `entities` appended. What comes out is the full form and goes through everything above unchanged, so a `from` file cannot reach a workspace by a route the full form does not. A variant slug the preset does not declare, an alias `rename` names that it does not declare, and a renamed label that is already another table's are each a finding rather than a silent drop — a branch quietly ignored scaffolds the base and looks like it worked. **It also prints WHO WRITES WHAT across the plan's apps** — one line per record surface left operable, naming the apps whose screens open it, and saying so when two desks write the same record: that is the shape behind an app changing a column its catalogue gives to another desk, and the plan is where it is visible before either app is built. A model cannot state a sanctioned split, so this is a reading rather than a refusal — the statement belongs in each built app's `package.json#lotics.writes`, where `shared_with` names the other desk and `app check` holds every body to it. On stdout with the plan and the coverage — the reference states that `check` prints it, which makes it part of the verdict rather than a diagnostic beside it — and in `--json` as `writers` (entity alias → app aliases). |
-| `lotics scaffold apply <model.json> [--connection <alias>=<cac_id> ...] [--json]` | **Create the model in this workspace**: its tables, fields, select options, links, views, roles and first rows, through `POST /v1/workspaces/scaffold`. Runs `check` first, so a bad file never reaches the network, then resolves and ANNOUNCES its workspace (`lotics → <org> / <workspace>` on stderr) before writing — it is a destructive path. **Additive and re-runnable**: it is the verb that sends `adopt`, so an entity whose `label` already names a table here BINDS to that table and gains the fields, options and views it is missing, while `setup` refuses that same label. Nothing is ever modified or deleted, so applying the same model twice creates nothing the second time — and a declared PAIRING (`sync_both_ways` / `paired_field_alias`) over a link this workspace already has one-way is REFUSED before the first write, naming the alias and `update_fields sync_both_ways`, because a pairing is only ever created with the link and adoption would otherwise finish clean over a half-paired link. **After the first run the WORKSPACE remembers what each alias became**, so every later run binds entity, field, select option, template and role BY ID and a relabel on either side is a RENAME rather than a second table: the run reports each moved name with the command that reconciles it (`lotics field rename` moves the platform, the file and every bound app together; `update_table` moves a table's name), and applies anyway — which of the two names is right is the author's to decide, and the run bound the thing the model has always meant either way. A bound target the workspace no longer holds is refused by name, with `restore_table` and `lotics scaffold unbind` as the two ways out. **Rows land only where every bound table is empty**: one bound table already holding records and none are written anywhere, because sample rows landing among a customer's real ones cannot be told apart from them — it says so and reports `rows_skipped`. Prints `created`/`adopted` per entity with its table id **and the delta that landed on it** (`+8 fields, +2 options, +1 view`, and nothing where the run added nothing) — `adopted` alone cannot report the columns, options and views a later version of a model puts on a table that is already the owner's, and the only other proof was a full re-export and a diff — marking `(bound by name)` the one case where a NAME decided which table the model points at; the same `created`/`adopted` per ROLE with its group id — an adopted role binds a group that already exists, which is how one silently inherits another workspace's members — and rows written per entity. It also provisions the model's table automations (`table_workflows`, the two a lifecycle's `history` derives included) on their tables, after the tables and before the first rows, and rewrites a bound one in place on every later apply — printed `created` or `rewrote` with its `tbw_` id, marked `(bound by name)` as a table is. An automation body names the account it pushes through as `@@connection:<alias>@@`, declared in `connections` with its provider: the first apply binds the alias to the ONE account of that provider you can use here, or to the one `--connection` names, and every later apply keeps it; none — or two or more with none named — is refused before the first table is written, naming the provider, the alias and each candidate. **The binding is the workspace's, not the file's**: a model file is never committed, so memory kept beside it is one author's disk — absent for a teammate, on a second machine or after a delete, and each of those falls silently back to the label join that grows the twin. It holds what each entity, field, option, role and template alias became (`tbl_`/`fld_`/`opt_`/`grp_`/`tpl_`), plus one entry per first ROW under its own `<entity>:<ref>` and `documents` (path → `fil_`), and is read by `diff`, `--documents`, `app create --from`, `app regenerate --from` and `workspace build` before any of them reads a label. **Then it copies in every package the file's `apply` list names, in order** — each one a `library init` with that entry's `bind` and `no_sample_data`, and each sending `adopt`, because by then the workspace holds exactly the tables this same run just created. Order is load-bearing: a later entry may bind onto a table an earlier one made. **A refused entry stops the run and the entries before it stay** — they are separate copies, committed as they land — so the refusal carries the server's own message plus what already landed and the one-package command to retry with. `--json` prints one object and nothing else (`entities`, each with `bound_by`: `created` by this run, `id` through the binding, or `label` for an alias nothing had bound; `roles`, `record_ids`, `rows_skipped`, `drift`, `applied: [{package, apps}]` — always present, empty included, so a reader cannot mistake "applied nothing" for "too old to say" — plus `organization_id`/`workspace_id` and a `warnings` array). Admin-only. A model PLANS its apps as shapes over entities and builds none of them — `apply` creates no app; build one in the workspace and publish it as a package, or name a published package in `apply`. **`--connection <alias>=<cac_id>`** (repeatable) names the account a connection pushes through, where you can use more than one account of its provider — two accounts of one service are two sets of books, so the refusal that asks for it names each and nothing is ever picked for you; the account must be this workspace's, of the provider the model declares, and one you can use. |
+| `lotics scaffold apply <model.json> [--connection <alias>=<cac_id> ...] [--json]` | **Create the model in this workspace**: its tables, fields, select options, links, views, roles and first rows, through `POST /v1/workspaces/scaffold`. Runs `check` first, so a bad file never reaches the network, then resolves and ANNOUNCES its workspace (`lotics → <org> / <workspace>` on stderr) before writing — it is a destructive path. **Additive and re-runnable**: it is the verb that sends `adopt`, so an entity whose `label` already names a table here BINDS to that table and gains the fields, options and views it is missing, while `setup` refuses that same label. Nothing is ever modified or deleted, so applying the same model twice creates nothing the second time — and a declared PAIRING (`sync_both_ways` / `paired_field_alias`) over a link this workspace already has one-way is REFUSED before the first write, naming the alias and `update_fields sync_both_ways`, because a pairing is only ever created with the link and adoption would otherwise finish clean over a half-paired link. **After the first run the WORKSPACE remembers what each alias became**, so every later run binds entity, field, select option, template and role BY ID and a relabel on either side is a RENAME rather than a second table: the run reports each moved name with the command that reconciles it (`lotics field rename` moves the platform, the file and every bound app together; `update_table` moves a table's name), and applies anyway — which of the two names is right is the author's to decide, and the run bound the thing the model has always meant either way. A bound target the workspace no longer holds is refused by name, with `restore_table` and `lotics scaffold unbind` as the two ways out. **Rows land only where every bound table is empty**: one bound table already holding records and none are written anywhere, because sample rows landing among a customer's real ones cannot be told apart from them — it says so and reports `rows_skipped`. Prints `created`/`adopted` per entity with its table id **and the delta that landed on it** (`+8 fields, +2 options, +1 view`, and nothing where the run added nothing) — `adopted` alone cannot report the columns, options and views a later version of a model puts on a table that is already the owner's, and the only other proof was a full re-export and a diff — marking `(bound by name)` the one case where a NAME decided which table the model points at; the same `created`/`adopted` per ROLE with its group id — an adopted role binds a group that already exists, which is how one silently inherits another workspace's members — and rows written per entity. It also provisions the model's table automations (`table_workflows`, the two a lifecycle's `history` derives included) on their tables, after the tables and before the first rows, and rewrites a bound one in place on every later apply — printed `created` or `rewrote` with its `tbw_` id, marked `(bound by name)` as a table is. **An automation that writes a `writes: false` table (a `history`'s two among them) is HELD while a deployed app workflow writes that table itself** — both would land every row twice — so the run neither creates nor rewrites it, prints `held` with each app's name, `app_` id and workflow alias, applies everything else, and exits 1: run `lotics app regenerate` then `lotics app deploy` in each app named, then apply again. A held one already live is named as doubling NOW, with the `tbw_` id to archive until the apps are redeployed. One of those found archived — through the binding, or by its label where nothing binds it — is restored (`restored`) rather than added beside it, unless schema its archived body names was deleted since, which adds a fresh one. A rewrite keeps the owner's on/off switch: one switched off prints `(off)`, and one that is its table's only writer warns `off` with the `update_table_workflow` call that turns it on. An automation body names the account it pushes through as `@@connection:<alias>@@`, declared in `connections` with its provider: the first apply binds the alias to the ONE account of that provider you can use here, or to the one `--connection` names, and every later apply keeps it; none — or two or more with none named — is refused before the first table is written, naming the provider, the alias and each candidate. **The binding is the workspace's, not the file's**: a model file is never committed, so memory kept beside it is one author's disk — absent for a teammate, on a second machine or after a delete, and each of those falls silently back to the label join that grows the twin. It holds what each entity, field, option, role and template alias became (`tbl_`/`fld_`/`opt_`/`grp_`/`tpl_`), plus one entry per first ROW under its own `<entity>:<ref>` and `documents` (path → `fil_`), and is read by `diff`, `--documents`, `app create --from`, `app regenerate --from` and `workspace build` before any of them reads a label. **Then it copies in every package the file's `apply` list names, in order** — each one a `library init` with that entry's `bind` and `no_sample_data`, and each sending `adopt`, because by then the workspace holds exactly the tables this same run just created. Order is load-bearing: a later entry may bind onto a table an earlier one made. **A refused entry stops the run and the entries before it stay** — they are separate copies, committed as they land — so the refusal carries the server's own message plus what already landed and the one-package command to retry with. `--json` prints one object and nothing else (`entities`, each with `bound_by`: `created` by this run, `id` through the binding, or `label` for an alias nothing had bound; `roles`, `record_ids`, `rows_skipped`, `drift`, `automations` (each `{alias, entity, table_workflow_id, bound_by, enabled}`, `bound_by` one of `created`/`id`/`label`/`restored`), `held_automations` (each `{alias, entity, keeps, writers: [{app_id, app_name, workflow_alias}], live}`, `live` the `tbw_` id already writing beside the apps or null), `applied: [{package, apps}]` — always present, empty included, so a reader cannot mistake "applied nothing" for "too old to say" — plus `organization_id`/`workspace_id` and a `warnings` array). Admin-only. A model PLANS its apps as shapes over entities and builds none of them — `apply` creates no app; build one in the workspace and publish it as a package, or name a published package in `apply`. **`--connection <alias>=<cac_id>`** (repeatable) names the account a connection pushes through, where you can use more than one account of its provider — two accounts of one service are two sets of books, so the refusal that asks for it names each and nothing is ever picked for you; the account must be this workspace's, of the provider the model declares, and one you can use. |
 | `lotics scaffold apply <model.json> --documents` | **The `files` cells of `rows`, and nothing else** — no table, no field, no row. The half a re-apply cannot redo: rows land only into empty tables, so a model whose binaries were missed the first time has no other way back, and a starter that binds a `mark` or a file section ships with empty wells until this runs. Each distinct path is uploaded once, recorded against the file it became, and attached with `update_records add_to` onto the record the binding names — joined by the row's own REF (`<entity>:<ref>`), so a row added to or removed from the file since the apply changes nothing about the rest. **A ref this workspace holds no record for is a refusal**, naming it: the alternative is filing its document under whichever row happened to sit at that position. **Idempotent by construction**: an uploaded path is reused from the binding's `documents` map and `add_to` is a set union, so running it twice leaves one id in the cell. The field is bound by the id the binding recorded, and by LABEL only for a field added since — a label that has moved with nothing bound to it is refused, pointing at `lotics scaffold diff`. Admin-only. |
-| `lotics scaffold diff <model.json>` | **Where the file and this workspace have come apart.** Runs `scaffold export` against the selected workspace and prints what the model has and the workspace lacks, the reverse, and every field the two disagree about — a type, the option labels one carries and the other does not, or a PAIRING the model declares over a link that is one-way here, which `apply` refuses and nothing else named — and each `unique` set one side declares and the other lacks, compared as an unordered set of the workspace's fields. **Joined on the ids this workspace remembers**, entity then field then select option, and on LABEL only for an alias nothing has bound — a new entity, or a workspace this model has never been applied to, which is the join the first apply itself makes. A relabel on either side therefore prints as one rename under the alias (`order.state: label: model "Stage" · workspace "Giai đoạn"`) rather than as one thing the workspace lacks and one the model lacks, which is what made an additive apply add a second one. A bound id this workspace no longer serves is named with the command that puts it back, never silently re-bound by label. **Exits 1 on any difference**, so it is a gate: a starter published from a model that has drifted would ship the FILE's labels while the workspace uses others, and nothing else compares them. Checks the file offline first. Admin-only (the export is). |
+| `lotics scaffold diff <model.json>` | **Where the file and this workspace have come apart.** Runs `scaffold export` against the selected workspace and prints what the model has and the workspace lacks, the reverse, and every field the two disagree about — a type, the option labels one carries and the other does not, or a PAIRING the model declares over a link that is one-way here, which `apply` refuses and nothing else named — and each `unique` set one side declares and the other lacks, compared as an unordered set of the workspace's fields. **Joined on the ids this workspace remembers**, entity then field then select option, and on LABEL only for an alias nothing has bound — a new entity, or a workspace this model has never been applied to, which is the join the first apply itself makes. A relabel on either side therefore prints as one rename under the alias (`order.state: label: model "Stage" · workspace "Giai đoạn"`) rather than as one thing the workspace lacks and one the model lacks, which is what made an additive apply add a second one. A bound id this workspace no longer serves is named with the command that puts it back, never silently re-bound by label. Each table automation is named without being compared (the export carries no body), and one the next apply would HOLD — its `writes: false` table is still written by a deployed app workflow — is named with each app and workflow alias. **Exits 1 on any difference or held automation**, so it is a gate: a starter published from a model that has drifted would ship the FILE's labels while the workspace uses others, and nothing else compares them. Checks the file offline first. Admin-only (the export is). |
 | `lotics scaffold export [--tables <tbl_id,…>]` | **This workspace, read back as a model file** — `GET /v1/workspaces/model`. Prints the tables it has (or only the ids `--tables` names) with their fields, options and views, plus its roles and its html/email templates when it has any (a file-backed template is named on stderr and left out), as pretty JSON on **stdout**: exactly the file `lotics scaffold check` reads, so `lotics scaffold export > model.json && lotics scaffold check model.json` is the round trip. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr), like every other verb that reads one. **Findings go to stderr, each led by its severity** (`• <severity>  <area>: <message>`, and one line counting the errors underneath) — a workspace holds things a model cannot express, and a file that dropped them silently would read as the whole workspace; the model is printed either way, and the exit is 1 when any finding is an `error`, because a file with a hole in it is still worth having on disk. **`--tables` names the closure it returned**, on stderr above the findings: the walk takes the transitive closure over links, so one seed in a connected workspace comes back with nearly all of it, and this file is what a preset is written from — a pull-in nobody stated is a preset nobody chose. **What comes out is a STARTING POINT, never a source of truth**: it carries one business's labels and stops describing that workspace the moment either changes. Edit the labels into the trade's words, add the `preset` block with its questions and variants (`lotics scaffold docs`), and prove every branch with `lotics scaffold check` before it is published. Admin-only. |
 | `lotics scaffold unbind <kind> <alias>` | **Make this workspace forget what one of a model's aliases is bound to** — `DELETE /v1/workspaces/model/binding`. `kind` is `entity`, `field`, `option`, `template`, `role`, `automation`, `row`, `document`, `app` or `connection`; `alias` is spelled in that kind's own grammar (`order`, `order.state`, `order.state:open`, `order:first`, a document's relative path, or an app's alias in the plan). **`scaffold unbind app <alias>`** forgets which app `app create --from` made for that plan alias: the next `app create --from <model.json>#<alias>` then binds the app it makes, and until it does, a sibling regenerated in between draws its `sibling` act naming the alias disabled. **`scaffold unbind connection <alias>`** forgets which connected account a connection alias pushes through: the next apply binds the one account of its provider you can use. **The escape from a binding whose target was deleted**: every verb refuses that alias by name rather than quietly creating a second thing beside it, and this is where somebody who is sure says so. Deliberately a command of its own and never a flag on `apply` — forgetting means the next apply CREATES a new one, and nothing afterwards joins it to whatever was there. An alias is a namespace, so forgetting an entity forgets its fields, its options and its rows with it, and the count of what went is what it prints. 404 when nothing was bound. Admin-only. |
 | `lotics library list` | **Works with no account**, and that is the point: whether to start from a preset, copy a package or build from scratch is decided before one exists, so requiring a key would mean signing up to learn the answer was no. **Two shelves, printed under their own headings and never merged**, because they are different kinds of thing and end in different commands. **Presets** are a trade's MODEL, served as static files on the website (`GET <site>/presets/index.json`, no credential, no server that knows what a preset is): each row is `slug · name`, the sentence, how many tables the base carries, and every branch as `slug · when`. The `when` rides the listing rather than waiting for a `show`, because it is what an answer is matched against — two trades whose names sound alike are told apart by which one has a branch describing the business in front of the reader. A preset is READ and turned into a `model.json`; nothing is copied. **Packages** are apps plus the tables they stand on, COPIED in whole. Unauthenticated it lists what Lotics publishes (`GET /v1/starters/official`, public); authenticated it lists the org shelf — the packages this organization can copy, Lotics-reviewed ones plus its own, each with at least one released version, deliberately NOT a catalogue of everything published: the server returns exactly what a copy would be allowed to take, so the list can never offer something that then refuses (admin-only). Both render through one function, and each row names WHAT IS INSIDE it — its apps and how many tables — because that is the fact the choice turns on: a name and a sentence leave a chooser guessing, and an agent matching what someone said they manage has nothing else to match against. Nothing fitting on either shelf is a real answer: `lotics scaffold docs` is where that goes. |
@@ -69,7 +69,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script — the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe — a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |
 | `lotics docs` \| `lotics docs <area>[/<section>]` | The index of the reference docs, **resolved out of the packages installed beside this project** — never carried by this CLI. **Both levels are discovered by looking**: every `@lotics/*` package carrying an `AGENTS.md` or a `docs/` in any `node_modules/@lotics` from the current directory UPWARD (nearest wins, so a hoisted root copy never shadows the one a project's own imports resolve to), and within each, every area it actually ships. Titles come from each file's own `# heading` and the version from the installed `package.json`, so a doc OR a whole package added upstream appears with no change to this CLI, and a skewed install is visible rather than reassuring. A package's index is named after the package (`lotics docs ui`), never `index`. `@lotics/app-runtime`, `@lotics/ui` and `@lotics/cli` sort first as a reading ORDER, not a filter. **Output is ONE PAGE, 16 KB, navigation included**: a doc that does not fit prints its opening and the addresses that reach into it — its sections with their sizes, or, for a reference that is one table (this file, the kit's catalog), the name of every row. `lotics docs <area>/<section>` prints that section and `lotics docs ui/catalog/Button` that one row; a unique prefix is enough, and an address matching two parts is refused with both. Both levels print to **stdout** — the index is the payload of a bare `lotics docs`, so `lotics docs | grep -i excel` works — with only the provenance line on stderr; a name two packages share is refused with both qualified forms (`lotics docs ui/templates`) rather than resolved silently. Needs no auth. Outside a project only `@lotics/cli`'s own resolve, and it says so. |
 | `lotics report '<json>'` \| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** — `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` — invoking it IS the consent that passive collection needs an opt-in for — but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. **Prints the id of each frame filed** — a filing nobody can cite cannot be answered about. The ids come from the server, so an instance that only logs the frames prints the count alone; the CLI never mints one of its own, which would hand back a token that resolves to nothing. |
-| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping. **First, whether this project is even based on the served version** — the one thing a deploy REFUSES outright rather than pushing (the server 409s a stale `prev_version_id`), and the one finding that invalidates every other: a stale tree and the live app are two different apps, so comparing them reports nothing trustworthy. Stale exits 1 naming both versions and stops before the rest; a project with no stamp at all — or an app with no version yet — is a first deploy, not a conflict. `deploy` runs the SAME assertion, so a stale tree fails before it pushes or builds. Then: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings this bundle stopped calling (the same transition — and the same baseline — `deploy` reports, so the two cannot disagree), capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a missing app `description` (it heads the capability catalog the chat agent reads every turn, and its absence has no other symptom), a `vite.config.ts` that never defines `global`/`__DEV__` **in a project that still ships react-native** (read off its own `package.json` — an app on the React DOM kit bundles none of it and the check would be advice to define two globals nothing reads), and a `window.open` in the app's own source (each fails ONLY in the deployed app: dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green), an agent whose capability and its reach disagree, in EITHER direction, over any of the five declaration-bound tools (`run_app_query`/`run_app_workflow` against `query_aliases`/`workflow_aliases`; `grep_knowledge`/`read_knowledge`/`list_knowledge` against `knowledge_doc_ids`) — the tool is the capability, the list is the reach, and a tool with no reach means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb, and a notice for any alias the source computes at runtime (invisible to every check here and to `--prune`'s unbind guard). **And whether the runtime this app builds against has fallen behind what is published** — `@lotics/app-runtime` alone, since the kit an app lists sits at the runtime's range, read from `node_modules` rather than the range because a caret is minor-locked below 1.0 (`^0.13.x` can never resolve `0.14`, and `npm update` does nothing). A release LINE behind is loud and names `lotics app kit --published` and `@lotics/ui`'s `MIGRATION.md`; anything smaller is one quiet `npm update` line, because a warning that fires on every deploy is one the reader stops seeing. An app still listing `@lotics/app-sdk` is told it moved into the runtime and which verb migrates it. The lookup is bounded and every failure is silence: a version check must never become a new way for a deploy to fail. Every deploy finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **And the PORTABILITY gate, the second of two rules `check` runs that a deploy does not** (the first is the undeclared call site below) — the ids an app cannot carry into another workspace, over the working tree, with the same exclusions the deploy tar applies. Two rules. **An id this workspace MINTED**, written into `src/`, a `.md` or the app's own docs — it resolves to nothing in a copy, and in prose it is an instruction the copier's agent follows; this is the one a `library publish` also refuses, on the uploaded archive. **And an id-shaped STAND-IN** too short for the generator that mints its prefix (`"opt_X"`, `"fld_a"` — quoted or in a code span, so a bare `opt_in` stays legal, and never in a test file), which only `check` runs, and which additionally reads a workflow body and the manifest: those two are exempt from the first rule because a publish INVERTS a real id there and cannot invert a fake. **And an `app_` id in `app.json` anywhere but the `app_id` a hand-off's binder writes**: a sibling app is named by its plan alias and the app it became is read off the workspace's binding at every regeneration, so a pasted one is re-pointed by nothing. Each is reported as `<file>:<line> — <id>` with the one edit that fixes it. This gate reads only the files, but the command around it still needs a resolvable credential and the live app row, so it is not an offline check. **And every bound workflow body, type-checked locally** — the same isolated per-alias program `app workflow check` builds, against the pulled `.lotics/workflows/<alias>.globals.d.ts`. The server verifies a body once, at the save that wrote it, so a body whose declared types have since moved stays stored, matching what is live, and is refused by the next writer — a starter copy, in somebody else's workspace. The verdict is as fresh as those types, which `pull`, `workflow pull` and `codegen` refresh. **And the app's own `npm run typecheck`**, after regenerating the `.lotics/*.d.ts` companions from the manifest — the same run a deploy makes before building, so a filter or sort key the query does not project fails here rather than at the first member's request. **Exits 1 on that, on a body the types refuse, on a failing typecheck, and on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query), and a query or workflow `description` over the 300-character capability cap, which is a binding no `set` and no deploy will take (the rule is `@lotics/shared`'s, the same one the server refuses with, and `workflow set` / `query set` ask it before sending anything — so a long line costs one edit rather than a failed push per alias). **And every manifest query declared with NO description**, named in one line: that sentence is what a chat or MCP caller chooses between aliases by, and an alias is a JS identifier. `app create --from` deliberately writes none — a template over a shape's own English reads like a line about the business while saying nothing — so a generated app is told once, here, which lines are the author's to write. Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. **`--screens` adds the rendered surface, and is its own entry below.** It runs after the typecheck and only when it passed — a type error renders nothing to measure — and its findings, and any write it refused, fold into this command's exit code. **It also refuses a call site the manifest no longer declares.** `useQuery`/`useWorkflow` keep a bare-string overload for a computed alias, so deleting or renaming an alias leaves every call site compiling and failing only when the screen renders — the one edit most likely to orphan a call site is the one the generated types cannot catch. The alias literals in `src/` are matched against `package.json#lotics.queries`/`.workflows` (the manifest, not the live row: the server still SERVES an alias whose declaration was just deleted, because a deploy never unbinds), and an undeclared one exits 1. `app codegen` prints the same finding as a warning, since it is the command an author runs right after editing the manifest. **A failing body that is byte-identical to the one the server is running is labelled as such**: its `lotics.synced.workflows.<alias>.content` baseline proves the file has not been edited since it was pushed or pulled, so the failure is a grammar migration the stored body is owed rather than a stale checkout — a link field reads as an id array, so drop `.id` or descend with `linked(…)`. Until the body is edited and `set`, the stored one keeps running as it always has. **And a query that reads past a table's ROW RULE.** A table's `private_filters` bind the CALLER, and an app query's caller is the app's OWNER — the viewer needs no table access, `app:use` is the grant — so the rule passes and every row is served. For each table a declared query reads (`GET /v1/tables/{id}`, the one surface that serves the rule), the viewer predicate — `current_member in_any_group`, or a member field's `is_current_member` / `is_not_current_member` — is attributed to the SCAN it guards: a `from_table`'s own `filter`, or an enclosing `filter` node's predicate, whose rows are the ones that scan produced. So a clause written over one table never silences the finding for the ruled table joined beside it, and every scan no clause covers is named with its table. A table this credential may not read (403, or 404 for one that is gone) is dropped — a rule that cannot be read is not evidence of one — while any other failure of that read fails the command, since "I could not ask" must never render as "there is no rule". Advisory, never part of the exit code: an app that deliberately serves the whole table to a desk of people who may all read it is legitimate, and nothing here can tell the two apart. **And it names the workflows a chat or MCP caller is offered with no description** (one `get_app_capabilities` read, the reader's own view of the app): that text is what those callers choose between aliases by, and without it they choose by the alias. It cannot be counted from the manifest — a workflow bound out of band is not declared there at all. Advisory, never part of the exit code. **It regenerates `.lotics/app_fields.ts` from the live schema before typechecking**, as a deploy does — a gitignored map from a moved schema otherwise passes. **And three claims the app makes**: a bound body's writes against `package.json#lotics.writes`, read as the step tree the server would store, exit 1 on a field no entry covers, and declaring none only warns; a description carrying `<placeholder>` syntax exits 1, since the catalogue escapes angle brackets — state the format as an example; so does one naming a desk `query_apps` does not list. |
+| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping. **First, whether this project is even based on the served version** — the one thing a deploy REFUSES outright rather than pushing (the server 409s a stale `prev_version_id`), and the one finding that invalidates every other: a stale tree and the live app are two different apps, so comparing them reports nothing trustworthy. Stale exits 1 naming both versions and stops before the rest; a project with no stamp at all — or an app with no version yet — is a first deploy, not a conflict. `deploy` runs the SAME assertion, so a stale tree fails before it pushes or builds. Then: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings this bundle stopped calling (the same transition — and the same baseline — `deploy` reports, so the two cannot disagree), capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a missing app `description` (it heads the capability catalog the chat agent reads every turn, and its absence has no other symptom), a `vite.config.ts` that never defines `global`/`__DEV__` **in a project that still ships react-native** (read off its own `package.json` — an app on the React DOM kit bundles none of it and the check would be advice to define two globals nothing reads), and a `window.open` in the app's own source (each fails ONLY in the deployed app: dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green), an agent whose capability and its reach disagree, in EITHER direction, over any of the five declaration-bound tools (`run_app_query`/`run_app_workflow` against `query_aliases`/`workflow_aliases`; `grep_knowledge`/`read_knowledge`/`list_knowledge` against `knowledge_doc_ids`) — the tool is the capability, the list is the reach, and a tool with no reach means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb, and a notice for any alias the source computes at runtime (invisible to every check here and to `--prune`'s unbind guard). **And whether the runtime this app builds against has fallen behind what is published** — `@lotics/app-runtime` alone, since the kit an app lists sits at the runtime's range, read from `node_modules` rather than the range because a caret is minor-locked below 1.0 (`^0.13.x` can never resolve `0.14`, and `npm update` does nothing). A release LINE behind is loud and names `lotics app kit --published` and `@lotics/ui`'s `MIGRATION.md`; anything smaller is one quiet `npm update` line, because a warning that fires on every deploy is one the reader stops seeing. An app still listing `@lotics/app-sdk` is told it moved into the runtime and which verb migrates it. The lookup is bounded and every failure is silence: a version check must never become a new way for a deploy to fail. Every deploy finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **And the PORTABILITY gate, the second of two rules `check` runs that a deploy does not** (the first is the undeclared call site below) — the ids an app cannot carry into another workspace, over the working tree, with the same exclusions the deploy tar applies. Two rules. **An id this workspace MINTED**, written into `src/`, a `.md` or the app's own docs — it resolves to nothing in a copy, and in prose it is an instruction the copier's agent follows; this is the one a `library publish` also refuses, on the uploaded archive. **And an id-shaped STAND-IN** too short for the generator that mints its prefix (`"opt_X"`, `"fld_a"` — quoted or in a code span, so a bare `opt_in` stays legal, and never in a test file), which only `check` runs, and which additionally reads a workflow body and the manifest: those two are exempt from the first rule because a publish INVERTS a real id there and cannot invert a fake. **And an `app_` id in `app.json` anywhere but the `app_id` a hand-off's binder writes**: a sibling app is named by its plan alias and the app it became is read off the workspace's binding at every regeneration, so a pasted one is re-pointed by nothing. Each is reported as `<file>:<line> — <id>` with the one edit that fixes it. This gate reads only the files, but the command around it still needs a resolvable credential and the live app row, so it is not an offline check. **And every bound workflow body, checked as `app workflow check` checks it** — the same isolated per-alias program against the pulled `.lotics/workflows/<alias>.globals.d.ts`, then the server's `verify_only` verdict on each body that passed, which exits 1 on any issue and warns when the server is not reached. The server verifies a body once, at the save that wrote it, so a body whose declared types have since moved stays stored, matching what is live, and is refused by the next writer — a starter copy, in somebody else's workspace. The verdict is as fresh as those types, which `pull`, `workflow pull` and `codegen` refresh. **And the app's own `npm run typecheck`**, after regenerating the `.lotics/*.d.ts` companions from the manifest — the same run a deploy makes before building, so a filter or sort key the query does not project fails here rather than at the first member's request. **Exits 1 on that, on a body the types refuse, on a failing typecheck, and on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query), and a query or workflow `description` over the 300-character capability cap, which is a binding no `set` and no deploy will take (the rule is `@lotics/shared`'s, the same one the server refuses with, and `workflow set` / `query set` ask it before sending anything — so a long line costs one edit rather than a failed push per alias). **And every manifest query declared with NO description**, named in one line: that sentence is what a chat or MCP caller chooses between aliases by, and an alias is a JS identifier. `app create --from` deliberately writes none — a template over a shape's own English reads like a line about the business while saying nothing — so a generated app is told once, here, which lines are the author's to write. Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. **`--screens` adds the rendered surface, and is its own entry below.** It runs after the typecheck and only when it passed — a type error renders nothing to measure — and its findings, and any write it refused, fold into this command's exit code. **It also refuses a call site the manifest no longer declares.** `useQuery`/`useWorkflow` keep a bare-string overload for a computed alias, so deleting or renaming an alias leaves every call site compiling and failing only when the screen renders — the one edit most likely to orphan a call site is the one the generated types cannot catch. The alias literals in `src/` are matched against `package.json#lotics.queries`/`.workflows` (the manifest, not the live row: the server still SERVES an alias whose declaration was just deleted, because a deploy never unbinds), and an undeclared one exits 1. `app codegen` prints the same finding as a warning, since it is the command an author runs right after editing the manifest. **A failing body that is byte-identical to the one the server is running is labelled as such**: its `lotics.synced.workflows.<alias>.content` baseline proves the file has not been edited since it was pushed or pulled, so the failure is a grammar migration the stored body is owed rather than a stale checkout — a link field reads as an id array, so drop `.id` or descend with `linked(…)`. Until the body is edited and `set`, the stored one keeps running as it always has. **And a query that reads past a table's ROW RULE.** A table's `private_filters` bind the CALLER, and an app query's caller is the app's OWNER — the viewer needs no table access, `app:use` is the grant — so the rule passes and every row is served. For each table a declared query reads (`GET /v1/tables/{id}`, the one surface that serves the rule), the viewer predicate — `current_member in_any_group`, or a member field's `is_current_member` / `is_not_current_member` — is attributed to the SCAN it guards: a `from_table`'s own `filter`, or an enclosing `filter` node's predicate, whose rows are the ones that scan produced. So a clause written over one table never silences the finding for the ruled table joined beside it, and every scan no clause covers is named with its table. A table this credential may not read (403, or 404 for one that is gone) is dropped — a rule that cannot be read is not evidence of one — while any other failure of that read fails the command, since "I could not ask" must never render as "there is no rule". Advisory, never part of the exit code: an app that deliberately serves the whole table to a desk of people who may all read it is legitimate, and nothing here can tell the two apart. **And it names the workflows a chat or MCP caller is offered with no description** (one `get_app_capabilities` read, the reader's own view of the app): that text is what those callers choose between aliases by, and without it they choose by the alias. It cannot be counted from the manifest — a workflow bound out of band is not declared there at all. Advisory, never part of the exit code. **It regenerates `.lotics/app_fields.ts` from the live schema before typechecking**, as a deploy does — a gitignored map from a moved schema otherwise passes. **And three claims the app makes**: a bound body's writes against `package.json#lotics.writes`, read as the step tree the server would store, exit 1 on a field no entry covers, and declaring none only warns; a description carrying `<placeholder>` syntax exits 1, since the catalogue escapes angle brackets — state the format as an example; so does one naming a desk `query_apps` does not list. |
 | `lotics app check --screens [--screen <label>] [--width <n>] [--shots <dir>] [--changed]` | **`--screens` adds the rendered surface**: the app is served the way `app dev` serves it (its real data, this key), rendered headless in Chrome (`CHROME_PATH`/`LOTICS_CHROME`, then Playwright's, then system) at 1280 and 375. **The screens are its navigation's destinations** — a `nav` landmark's `a[href]` or `role="link"` (an app's route lives in its router, so the kit's shell renders each screen as a button carrying the link role and no `href`), else the first tab strip, else the root — in that order, because a screen's own lifecycle desk draws a tablist too, and reaching for one first walks a screen's STAGES as if they were the app's. **Each screen is then WALKED THROUGH ITS OWN DOORS**, nothing configured per app: every door is named by something the document states. A record: a row stamped `data-opens="page"`, a real `a[href]`, or an EMPTY DOOR — a named control with no text and no child element, the only legal whole-row press target, which reaches a drawer register, a Schedule row and a hand-written row alike. On a record: the acts menu (`aria-haspopup`), the first child row, the facts behind the fold (`aria-expanded="false"`). On any surface: every dialog a visible primary or secondary act raises — nothing announces one, so a press is kept only where an overlay appeared. **THE RUN IS A READ, AND THE NETWORK IS WHERE THAT IS ENFORCED — never a rule about what the page may draw.** The app frame holds no credential and Chrome runs on a throwaway profile, so every call the app makes reaches the workspace through this CLI and nowhere else, and this CLI serves an ALLOWLIST of reads. Everything outside it is refused before the call leaves the machine — a workflow run, a record write, an upload, an agent run, a comment, and any op this CLI does not know, which is refused because it is not on the list rather than because anyone listed it. A refused call HEADS the report, naming the surface, the control the app had focused and the RPC by its alias (never a payload value), and fails the run on its own: a walk that provoked a write left the app in a state no reader could have put it in, so nothing measured under it means anything. What the walk does is bounded on the page as well: nothing inside an open overlay, nothing typed, no submit and nothing in a form, no act the kit marks costly (`data-tone` danger/warning) and none whose own name is the write, in either language — and nothing is FOCUSED, because focus cannot be taken from one field without leaving another, and a field that saves itself when the reader leaves it saves on exactly that. Where a reading needs the focused state, as the focus-ring rule does, Chrome is asked to PAINT `:focus-visible` and release it again: the cascade answers, focus never moves and no event is dispatched. Each overlay closes with Escape, confirmed closed; a record is descended at most twice; the walk stops at twelve surfaces per screen and NAMES each door it left. Each surface is measured once no request is in flight, and the measurable probes of `@lotics/ui` docs/reviewing.md run over the DOM, each finding printing the rule it IS — its law, its section and the one edit that answers it — so the numbers need no key. What they exempt is what the screen itself declares: a register's ordinal gutter (a column counting to the row count is the shape's numbering, which no app can treat), a strip whose list carries `data-order="sequence"` (a lifecycle rail, which composition.md permits under a screen's tabs), a hairline or `clip-path`-clipped leaf (the visually-hidden node a control plants for a screen reader), and a leaf whose own computed line clamp states a count over a sentence. **A meter counts as an encoding only where it draws a POSITION** — `aria-valuenow` inside a range with room left. A bar pinned at its own maximum — what a meter alarmed AT its maximum draws on every alarmed row — reads the same as every value above it, and one with no maximum states none; both are counted in the census's `devices` and out of its `encoded`, so "nothing drawn" and "drawn and saying nothing" never read alike. The bare values that remain are grouped into columns, each named by the heading over it, so a finding says WHICH slot draws its figures as words. **Two finding classes read what geometry cannot.** `clutter` (docs/hierarchy.md): a second primary act, a value in two places on a record, an unstated fact open beside its fold, a box reserving more lines than it holds, markers on over half a form's fields, a second accent. `right_form` (docs/templates.md's device index): a boolean as a two-option select, a day run as a repeated date column where the kit ships `Schedule`, a fold hiding a record's section, two reading columns from 1016px. Each prints a line per rule fired, with three offenders. A census line per screen (text runs, money strings, bare values against the devices reading, tab strips) prints first, so a clean verdict over a screen that rendered nothing cannot pass; a screen that renders no text is itself a finding, and one still changing after fifteen seconds is measured as it is. **A cold dependency optimisation is waited out, not measured**: the first paint has its own bound, far longer than settle's, since an app's modules load after its document completes and Vite holds them; only a MOUNTED, idle, textless frame is blank at once, and the finding names the wait and its blocker. It also RELOADS the page under the probe, so a width is measured again once; a second reload is a page that keeps moving and fails. **`--screen <label>` and `--width <n>` narrow a run** (repeatable, comma-separated; the label matches case-insensitively as a substring), for the author iterating on one screen who would otherwise pay a typecheck, a Vite boot and every screen at both widths on every edit; the clean verdict then names only the widths covered, and a `--screen` matching nothing is refused. **`--shots <dir>` writes what the run measured** — a `<surface>@<width>.png` and a `<surface>@<width>.json` per surface, off the SAME settled frame the probes read, so a shot and a finding can never describe different pixels. The PNG is the WHOLE surface: an app scrolls inside a box of its own, so the window is grown to the height the probe measured and put back, and an overlay a resize dismissed is shot as the viewport, the sidecar saying so (`app dev`'s header band is in it — the band the app was laid out under). The JSON is the half a picture cannot carry: the nav's first item's left edge, the title and first section heading, the primary acts by name, label/value pairs against what the folds state, values drawn twice, money that wraps, text the layout cut, and the console errors and uncaught exceptions the frame raised. Named `<nn>-<slug>` plus one `__<step>` per door taken (`__record`, `__menu`, `__child`, `__fold`, `__dialog-<n>`); `<nn>` is the walk's index, which lists the directory in reading order and keeps two labels that fold to one ASCII slug apart. The row a record surface opened from is the sidecar's `opened_from` and that screen's census line, never a file name — it is a person's data. The directory is created if missing, and refused before the dev server boots when it cannot be; `--shots` without `--screens` is refused. Findings exit 1 like the rest. **Where it renders**: the app's files are copied into the render project of its DEPENDENCY SET — `~/.lotics/render/<key>/`, keyed by the manifest's `dependencies` and `devDependencies` as written, a `file:` tarball by its bytes — the one `app preview` renders in, so the install and Vite's dependency optimisation are paid once per set rather than per app; one render holds a project at a time (`<key>.lock` — a second run waits, naming the app and pid, and takes over a dead hold). Where that install resolved another runtime or kit than the app's own, the run says which, since a deploy builds the app's own. The run ends with what each phase cost: `preflight · install|reuse · walk`. **`--changed`** walks only when something the screens READ has moved since this checkout's last walk — each part of `app.json` (every record apart), each declared query, each bundled source file, the field map, the ranges and the kit the render resolved — read against `.lotics/screens_check.json`, which every walk writes; with nothing moved, that walk's report is printed again under its timestamp and still fails the run. An app's screens all read its one spec, so a move walks the app whole. It walks, saying why, with no earlier walk, a different `--screen`/`--width`, or `LOTICS_UI_SRC` set (a linked working copy has no fingerprint); the workspace's rows are not an input. `--changed` without `--screens`, or beside `--shots`, is refused. |
 | `lotics app preview <model.json>#<app> [--shots <dir>] [--width <n>] [--screen <label>] [--kit <path>]` | **The app a plan describes, RENDERED — before a table exists, and with no credential in the process.** The model is checked offline, the named app's register is bound against the workspace the model WOULD become (synthetic `tbl_`/`fld_`/`opt_`/`grp_`/`dtl_` ids, minted positionally off the file), and every read the app makes is answered from the model's own `rows` — projected under the columns the query names, narrowed by the params it declares and sorted the way it states, so a child list under a record holds that record's rows and not every parent's. Then the SAME headless walk `app check --screens` takes: every screen, the record each row opens, its acts menu, its children, the facts behind its fold, the party a row names, and each dialog a tone-neutral act raises, at 1280 and 375, measured by the same probes. `--shots` writes a PNG and a sidecar per surface. **Exits 1 on any finding**, exactly as the check does, and prints what each phase cost — bind, install-or-reuse, walk. **A model with no `rows` is refused by name**: a register over nothing draws its empty state at both widths and measures clean, which reads as an app that is finished. **Nothing is created and nothing is reached** — no app row, no table, no workspace; the only network it needs is the npm registry, and only when the kit has moved. It renders in the cached render project of its dependency set (`~/.lotics/render/<key>/`, shared with `app check --screens` and with every model whose app lists the same set, and held by one render at a time — a second run waits, naming the app and pid holding it, and takes over a hold whose process is gone): the runtime and its kit are PUBLISHED packages, so a project is what a preview needs to install them into — the CLI has no renderer of its own. **It installs the runtime this CLI was built for**, and the kit through it, never `latest`: the spec this binary's generator writes is the one that runtime reads, and a version that published mid-session is a runtime nobody checked the plan against. A version the registry does not serve yet is refused before npm runs, naming `--kit`. **`--kit <checkout>`** (repeatable) — a checkout's ROOT, which names the app-runtime and the ui it holds, or one of those two packages — renders against that checkout instead — built, packed and proven the way `lotics app kit` installs one into an app — and the run prints that it rendered against a LOCAL CHECKOUT, first and last, so the render is never read as the published one. The project is a CACHE and never a source: `npm install` runs on the first render of a set and again only when a checkout's tarball did, and every file in it is rewritten from the plan on each run. **A document a row names by path is served** from the project's own static root, as the named file a workspace would hold, so a files section, a verdict over the pile and a required set read what the model states; a `fil_` id is carried by name. **An app read inside one subject (`scope`) is walked with the first row its switcher lists picked**, and the run names it. **`--record <ref>`** opens that row's record — a row of the entity the app's screen lists, by the ref the model gives it — where the walk otherwise opens the first; a ref naming no such row is refused with the refs there are. **Every read is answered at the BRIDGE**, not inside the page. The app SDK's design-time fixture (`registerMockFixture` + `?__mock=1`) is the wrong half of this: the flag lives in the app's own url, and the first record page is a navigation the app's router performs — so from that surface onwards the flag is gone and every read falls through anyway. The bridge is the one place every call arrives whatever the url says, so `query`, `field_options`, `members` and `context` are answered there from one reading of the rows, and the generated entry ships EXACTLY as `app create --from` writes it. **A preview writes nothing**: a workflow, an upload or an agent run meets the same read gate `app check --screens` uses, so the app draws its own refusal path rather than reporting a save nothing moved for, and the call is reported above the census the way the check reports one. **What came out empty, it names**: a `formula`, `rollup`, `lookup` or `autonumber` is computed here rather than stated in the model, and the census lists each computed column that stayed empty on EVERY row of a table that has rows — named by outcome, since a total drawn blank is either the app's own answer or a hole and only the run can say which. The census reads the CELLS and not the field types, so nothing is exempt by kind. **A computed column that came out `#ERROR:` is named too, and the run refuses it** before anything is installed: a wall of red measures clean, and a run that drew it and exited 0 would tell its author the app is fine. **It computes in UTC**, because a model states no timezone — a row's `@today`, an autonumber's `{YEAR}` and a record's own clock all land on the run's own date at UTC midnight, so two runs of one model draw the same register wherever they are made. |
 | `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` **and the `description`** from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). The `description` is the one line an agent reads when choosing between the app's aliases (the workflow counterpart to a query's) — authored in the manifest so it lives beside the body in version control and rides every push; omit it and the workflow keeps whatever description it already has, so a push can never blank one set elsewhere. When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. A deploy runs this same verb for every alias whose declaration or body is ahead of the app, so this command is the one-alias spelling of what a release does, not a step a release leaves to a person. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. A push also prints any non-blocking verify warnings, including an input the alias declares that the body never reads. A first bind MINTS the workflow row, and the id it echoes is written back into `package.json#lotics.workflows.<alias>.workflow_id` — the same surgical write the derived `outputs` gets. Without it a hand-declared alias ended up shaped unlike its siblings, so anything reading the manifest (an audit, a port to another workspace, a person comparing two blocks) had to treat a missing id as normal, which is exactly how a genuinely missing one stops being visible. **`--acknowledge-breaking-api`** carries this write out even though it breaks what the app's published API promises, snapshotting the broken contract as a new version; without it such a write is refused and every breaking change is named (see `app api`). |
@@ -79,7 +79,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app query move <alias> --to <dir|app_id>` \| `lotics app workflow move <alias> --to <dir|app_id>` | **One alias, out of this app and into another of the same workspace — both halves, no release either side.** Run it in the SOURCE project. In order, and the order is the safety: the alias is refused while anything here still reaches it (a `useQuery`/`useWorkflow` call site in `src/`, or an alias this app computes at run time — the same scan `deploy --prune` defers on), and that gate runs before the first write; then the target gains the binding; then the source loses it. A failure anywhere leaves the alias bound SOMEWHERE, where the other order would leave a capability that exists nowhere. `--to` is an ALLOWLIST of two shapes: a DIRECTORY holding the target's `package.json` (the declaration lands in its manifest, a workflow's `src/workflows/<alias>.ts` lands beside it, its `.lotics/*.d.ts` are regenerated, and its baseline is recorded — so its next deploy ships exactly what is live; all of it AFTER the push, because declared-and-unbound is a state a deploy would BIND, so a manifest written ahead of a refused push would have the target take the alias while the source still owns it), or an `app_…` id with no checkout here (only the live binding moves, and the command names the `lotics app pull <app_id>` that project owes). Anything else is refused by name. **A workflow's target binding is a NEW workflow row**: `workflow_id` is the SOURCE app's and is dropped on the way in, which is the mistake a hand-copied declaration makes — the second app then edits the first app's workflow. The source unbind is `remove_app_query` / `remove_app_workflow`, the same tools `deploy --prune` calls, so it needs no version; the declaration is parked under `.lotics/pruned/<kind>/<alias>.json` and removed from the manifest, because leaving it declared is how the next plain deploy re-creates the binding just retired. If the unbind is REFUSED (the server's guard on an alias the workspace has RUN, say) the target half and the manifest half still stand and the command names the one thing the source still owes: `lotics app deploy --prune [--prune-invoked <alias>] -m "…"`. `--even-if-invoked` lifts both guards — the call-site scan here and, for a workflow, the server's recorded-run refusal. Refused with nothing written: an alias this project does not declare, a workflow whose body was never pulled, a target that already declares the alias or already has that body file (a move never overwrites either), a target in another workspace, and `--to` naming this same app. |
 | `lotics app workflow pull` | Rewrite every `src/workflows/<alias>.ts` from the server (faithful body per bound alias via `get_app_workflow`) **+ its `.lotics/workflows/<alias>.globals.d.ts`** (via `getAppWorkflowDts`, so the body is locally typecheckable via `lotics app workflow check`) without a full `app pull` (no source archive, no npm install). A legacy alias with no rendered source warns and is skipped; a dts-fetch failure is non-fatal (body still written with the fallback wrapper, typecheck degraded). Each alias's `description` is folded back into `package.json#lotics.workflows.<alias>` from the same read — the alias binding the manifest is otherwise stamped from carries `inputs`/`outputs` but not the description, which lives on the workflow ROW, so without this a pull would erase an authored one. The server's GENERATED default is skipped, so an app that never described its workflows gains no manifest noise. Also idempotently patches the main `tsconfig.json` `exclude` to cover `src/workflows` + `.lotics/workflows` so a pre-existing app's `npm run typecheck` never loads the bodies or the colliding per-alias globals. **A body the app's row has not moved on is left exactly as it is**, and the aliases skipped are named. A pull writes the server's RE-RENDER of a stored step tree, which is not the text that made it — a comment inside an object literal does not survive the round trip — and the local hash cannot catch that, because `workflow set` recorded this checkout's own text (comments included) as `synced.workflows.<alias>.content`, so nothing reads as unpushed. The fact that can is the server's own fingerprint: when `synced.workflows.<alias>.live` still equals the `body_sha` the read returns, there is nothing to deliver and the baseline is left where it is. `--force` takes the app's rendering anyway. |
 | `lotics app workflow diff [alias...]` | Print how `src/workflows/<alias>.ts` differs from the body the SERVER is running, line by line (`-` is live, `+` is the file, three lines of context, the unchanged middle elided). Name the aliases to diff them whether or not they read as drifted; name none and it diffs every alias the baseline says has moved. Exits 1 when anything differs, so a script can gate on it. It is the companion the drift signal never had: `workflow set` pushes the file and `workflow pull --force` takes the server's, but nothing could say what the difference WAS short of pulling into a throwaway directory. **The two hashes under `package.json#lotics.synced` are not a comparison**: `content` hashes the local text and `live` is the server's own fingerprint of a body stored as steps, so they can never be equal and nothing compares them — reading `content != live` as drift is a misreading the block's shape invites. |
-| `lotics app workflow check [alias...]` | Check the editable workflow bodies locally — **every alias you name**, or all of them when you name none; an alias that is not bound is refused BEFORE any body is checked, so a green ✓ never sits under an exit 1 — no auth / no network, in the **server's own order** — parse, then type-check. **Parse** runs `parseWorkflowJs` from `@lotics/shared` (the SAME module `verifyWorkflow` calls, never a second implementation) over the stripped body `set` would upload, with `toolNames: undefined` (the CLI ships no tool registry, so tool-name resolution stays a server check while every shape/scope rule runs here). A body the subset rejects reports **that error alone** and skips the compiler — it never reaches the server's compiler either, so tsc's opinion of it is noise. **Type-check** then builds an **isolated** `ts.Program` per alias from exactly that alias's `{body, globals}` pair — mirroring the server, which verifies one body at a time — so the per-alias ambient `trigger` never collides and `trigger.app_workflow.inputs` is checked against the right alias. All aliases run in ONE node process (N programs, not N `tsc` spawns), with the SAME compile options the server uses at set-time verify (lib `es2022` with no DOM, target ES2022, strict, NodeNext, `types:[]`, skipLibCheck) and the app's OWN `typescript` (resolved from its `node_modules`, never bundled into the CLI). What the compiler sees is the **checked source**, not the file: `rewriteAccumulatorAppends` from `@lotics/shared` — the SAME transform the server applies before its set-time compile — is applied in memory, so a pulled body's canonical `out = concat(out, [item])` accumulator checks green here exactly as it saves there, and the body on disk is never rewritten. Reports `<file>:<line>:<col> - <TS####\|subset>` at the **physical** line in `src/workflows/<alias>.ts`, so an editor jump lands on the offending code (these are deliberately NOT `set`'s body-relative numbers — `set` prints no file path, so there is no format to agree with); exits non-zero if any alias fails. Green is honest but not total: `set` additionally resolves names, lints and structurally validates against the live workspace — passes that need its tables and tool schemas, so they cannot run offline, and the success line says so. A bound alias with no body file yet warns + skips; a body with no globals errors (naming `lotics app codegen`, which refreshes types WITHOUT touching the body — a pull would overwrite it). **It also keeps the types honest.** Each alias's `.lotics/workflows/<alias>.globals.d.ts` carries a `// lotics:declaration <hash>` stamp of the manifest declaration it was rendered from; `check` compares it to `package.json#lotics.workflows.<alias>` and, when they differ, re-renders that alias's dts from the LOCAL declaration before compiling. Without it the verdict was confidently wrong in the exact case an author needs it — declare an input, run `check`, and get `TS2339: Property 'x' does not exist` pointing at your body for a schema the types have never been told about. The server renders a dts from a SUPPLIED declaration, so this works before the manifest has ever been deployed, which is when it matters (the order is edit → check → set). This is the ONE thing `check` uses the API for: it is skipped entirely when the stamps match (the common case, so `check` stays instant and offline), and with no credentials or a failed fetch it WARNS and checks against the older types rather than blocking. A file written before the stamp existed reads as unknown, never as matching, so a pre-existing checkout heals on its first run. |
+| `lotics app workflow check [alias...]` | Check the editable workflow bodies locally — **every alias you name**, or all of them when you name none; an alias that is not bound is refused BEFORE any body is checked, so a green ✓ never sits under an exit 1 — locally first, in the **server's own order** — parse, then type-check — then on the server. **Parse** runs `parseWorkflowJs` from `@lotics/shared` (the SAME module `verifyWorkflow` calls, never a second implementation) over the stripped body `set` would upload, with `toolNames: undefined` (the CLI ships no tool registry, so tool-name resolution stays a server check while every shape/scope rule runs here). A body the subset rejects reports **that error alone** and skips the compiler — it never reaches the server's compiler either, so tsc's opinion of it is noise. **Type-check** then builds an **isolated** `ts.Program` per alias from exactly that alias's `{body, globals}` pair — mirroring the server, which verifies one body at a time — so the per-alias ambient `trigger` never collides and `trigger.app_workflow.inputs` is checked against the right alias. All aliases run in ONE node process (N programs, not N `tsc` spawns), with the SAME compile options the server uses at set-time verify (lib `es2022` with no DOM, target ES2022, strict, NodeNext, `types:[]`, skipLibCheck) and the app's OWN `typescript` (resolved from its `node_modules`, never bundled into the CLI). What the compiler sees is the **checked source**, not the file: `rewriteAccumulatorAppends` from `@lotics/shared` — the SAME transform the server applies before its set-time compile — is applied in memory, so a pulled body's canonical `out = concat(out, [item])` accumulator checks green here exactly as it saves there, and the body on disk is never rewritten. Reports `<file>:<line>:<col> - <TS####\|subset>` at the **physical** line in `src/workflows/<alias>.ts`, so an editor jump lands on the offending code (these are deliberately NOT `set`'s body-relative numbers — `set` prints no file path, so there is no format to agree with); exits non-zero if any alias fails. **Then every body the local passes found clean goes to the server**: `set_app_workflow` with `verify_only: true`, sent exactly what `set` sends (the manifest's `inputs`/`outputs`/`description` and the synced `expected_body_sha`), which runs every check a save runs — names, lint, structural validation, table reach, the published-API guard — and writes nothing. Its issues print in the same `<file>:<line>:<col> - <source>/<code>` form at the physical line; one tied to a step rather than a position prints against the file, naming the step; a refusal (a stale baseline, a draft, a break) prints as `server/<code>`. All of them exit 1. A server it cannot reach — no credentials, the network, a server that predates `verify_only` — is a warning naming each alias and why, and the exit is then the local verdict's, so a green run says which of the two it is. A bound alias with no body file yet warns + skips; a body with no globals errors (naming `lotics app codegen`, which refreshes types WITHOUT touching the body — a pull would overwrite it). **It also keeps the types honest.** Each alias's `.lotics/workflows/<alias>.globals.d.ts` carries a `// lotics:declaration <hash>` stamp of the manifest declaration it was rendered from; `check` compares it to `package.json#lotics.workflows.<alias>` and, when they differ, re-renders that alias's dts from the LOCAL declaration before compiling. Without it the verdict was confidently wrong in the exact case an author needs it — declare an input, run `check`, and get `TS2339: Property 'x' does not exist` pointing at your body for a schema the types have never been told about. The server renders a dts from a SUPPLIED declaration, so this works before the manifest has ever been deployed, which is when it matters (the order is edit → check → set). That refresh is skipped when the stamps match, and with no credentials or a failed fetch it WARNS and checks against the older types rather than blocking. A file written before the stamp existed reads as unknown, never as matching, so a pre-existing checkout heals on its first run. |
 | `lotics app subdomain <new-subdomain>` | Rename the app's public address under the instance's apps domain via `PUT /v1/apps/{id}/subdomain`. app_id comes from the local `package.json` manifest; the chosen slug must be a valid DNS label and free; the old address stops resolving. |
 | `lotics app rename "<new name>" [--description <d>] [--icon <lucide-name>] [--theme <color>]` | **The app's display metadata, live and on disk, in one verb** — via the `update_app` tool (the single setter for name/description/icon/theme). app_id comes from the local `package.json` manifest; the public address (`subdomain`) and the code (`deploy`) are unchanged. **It also writes `package.json#name`**, folded from the new display name by the scaffold's own rule (`starter_template.ts` — diacritics are FOLDED, never dropped, so `Điều xe` is `dieu-xe` and not `i-u`). Nothing else folds it, so a rename that skipped it left every `npm` line, every CI log and every reader of the project calling the app by its old name. Written only after the server took the rename, and surgically: no other manifest key moves. The three flags set the branding `app check` warns about — a missing icon or colour draws a generic tile, a missing description gives the app's chat agent a roster of aliases and no brief — through the same call, so setting them is never a second `lotics run update_app` that forgets the manifest write. `--theme` takes the COLOUR (`theme.color` is the whole of what the launcher reads), not a JSON object. A flag you omit changes nothing: `update_app` merges, and absent means unchanged. CLEARING one is still `lotics run update_app` with an explicit `null` — a CLI flag has no spelling for that a shell cannot produce by accident. |
 | `lotics app dev [path] [--port <n>] [--vite-port <n>] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. **Refused in one sentence on a project with no `vite.config.*`** — an app created with `--api` serves no bundle, and without the config Vite fails on a missing entry document in a bundler's words about a file the author never expected to have. `app check --screens` is refused on the same project for the same reason, rather than reporting "nothing blocking" for a pass it never ran; plain `app check` runs everything else. **`--port` is the wrapper you open and `--vite-port` is the module server, each as `--port <n>` or `--port=<n>`; pin both to run several apps at once.** A value that is not a port number is refused. With no `--vite-port`, `vite.config`'s own `server.port` is used when it states a literal one — the CLI passes `--port … --strictPort` to Vite, and a CLI flag beats the config in Vite's precedence, so the config's value could otherwise never win. `--vite-port` still outranks it and says so. **The wrapper serves every path that is not one of its own `/_…` routes**, so `http://localhost:PORT/lo/rec_…` opens that screen directly; `?_loc=<url-encoded path>` still works and wins. With `LOTICS_UI_SRC` set, Vite is started with `--force`: its optimizer cache survives a restart, so a NEW file added to the linked kit tree otherwise left the browser running the previous build of the module that imported it, silently. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage: dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-runtime/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the app's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. **Every forwarded op logs one line naming its ALIAS** — `[rpc] query applicants 231ms` — and `query applicants (count)` for a count request, which is a SECOND full execution of the same query rather than a cheap lookup. When requests overlap the line carries `· N in flight`. That number is the one to watch: the server bounds how many app queries run at once, so requests past the bound wait and the wait lands inside each request's own duration — a burst reads as "every query got slower", which looks like a slow database and is not one. A screen firing its list plus three facet counts on one keystroke shows up here as eight lines over one or two aliases; see `@lotics/app-runtime` `docs/data_fetching.md` (`useCount`, and handing `usePaginatedQuery` a `total`) and `docs/queries.md` §10 for collapsing them. **Holds no realtime connection** — push belongs to the product frontend, so an app previewed here never updates on an external write (a CLI run, another tab, an agent): reload to see it. Deliberate rather than missing, since the alternative is a second implementation of the channel in the wrapper page, and a blanket poll here would hide an app whose queries do not declare their tables — the one mistake the real host punishes. The startup banner says `realtime: off` so this is visible without reading this table. The scaffold's `vite.config.ts` states `optimizeDeps: loticsOptimizeDeps()` — every published kit subpath, DERIVED from the kit's own `exports` rather than copied, and empty under `LOTICS_UI_SRC`. Vite's scanner reaches a subpath the moment something imports it, and meeting one mid-session re-optimizes, reloads, and inside this sandboxed iframe leaves two Reacts ("Invalid hook call") until a cold restart. `dev` and `codegen` heal that line, and the `server.fs.allow` one beside it, into a config scaffolded before them. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.238.0",
+  "version": "0.239.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {