@lotics/cli 0.262.0 → 0.264.0

package/dist/src/invocation.d.ts

@@ -1,7 +1,7 @@
 /** Enabled by an explicit `LOTICS_TELEMETRY=1`. Anything else, including unset, is off. */
 export declare function telemetryEnabled(env?: NodeJS.ProcessEnv): boolean;
 /**
- * The verb path of an invocation — `app.workflow.set`, `run.query_records` —
+ * The verb path of an invocation — `model.apply`, `run.query_records` —
  * from the raw argv positionals.
  *
  * Positionals stop at the first token that is a flag, a JSON blob, an `@file`,

package/docs/building_an_app.md

@@ -1,113 +1,31 @@
 # Building an app, end to end
 
-The other references here describe **contracts** — what a query may express, what a workflow body
-may say, which props a component takes. This one describes the **sequence**: the order the steps go
-in, and why that order and not another. Read it once for the shape, then reach for the area doc
-(`lotics docs`) whenever you need the detail.
+The other references here describe **contracts** — what a model may state, what a tool takes. This
+one describes the **sequence**: the order the steps go in, and why. Read it once for the shape, then
+reach for the area doc (`lotics docs`) whenever you need the detail.
 
-Everything below is deploy-free until the last step. That is the point: a deploy is a release, and
-using one to find out whether something works is the slowest possible way to learn it.
+**The live app is the only edit surface.** Every change to an app — applying a model, deploying a
+build, setting one query or workflow — mints a new version of it, and rolling back to an earlier
+version is the undo. Nothing about an app lives in a local directory the platform reads back, so
+there is no project to keep in sync and no deploy to find out whether something works.
 
----
+**Rolling back restores the app, not the data.** A table change the model made, and every row a
+workflow wrote while you tried it, stay where they are. Try a write on a throwaway record.
 
-## 1 — Scaffold, or pull what exists
+---
 
-```
-lotics app preview model.json#<app> --shots shots/   # the model's app rendered: no workspace
-lotics app create "<name>"          # new: a real Vite + React + TS project, deps installed
-lotics app create "<name>" --from model.json#<app>   # new, from a checked model: app.json, rendered
-lotics app create "<name>" --api    # new, no screens: its declarations are the whole surface
-cd <dir> && lotics app regenerate   # existing + generated: recompile it from the model
-cd <dir> && lotics app pull <app_id>   # existing: refresh to the latest first, then read its README
-lotics workspace build model.json      # the whole model: check, apply, then every app in it
-```
+## 1 — Two kinds of app
 
-`lotics workspace build` is the create and regenerate lines above in one, for a model that
-declares several apps: `scaffold check`, `scaffold apply` where this workspace differs from the
-model, then per app `create --from` into `<dir-of-model>/<alias-with-dashes>` when that directory
-does not exist and `regenerate` there when it does, then `app check` — and `app deploy` under
-`--deploy`. An app that conflicts or checks red is named and the rest still run, because the one
-you are going to fix is not a reason to leave the others in a state nobody knows. `--dry-run`
-writes nothing and says which apps it would create and which it would regenerate.
-
-**An app is stated, not drawn.** In `model.json`, `records` says how a row of each entity is
-recognised — its title, the line under it, its picture, its status, its figure, its deadlines, what it is about — and
-each entry of `apps` is one register over one entity and the record its rows open: the register's
-columns and filters, the record's sections in the order its work reaches them, the acts and the checks that guard them.
-That is the whole vocabulary (`lotics docs model/apps`). How each piece looks is the runtime's, one
-way per concept, and no key changes it. `lotics scaffold check` prints each app as its reader will
-see it, with every value a default supplied marked `(default)` — review the app there, before
-anything exists.
-
-**Work people are assigned is a task list, stated like any other.** Give the child entity a stored
-status select with `closed` options, a member field, and a deadline under `due`, and state
-`"task": true` in its `records`. Every table of its rows — a rows block of the record it belongs to,
-its own register, the rows filed under one of them (its steps) — then draws each row as a task: its
-ring ticks it done by the act of that entity setting a closed option — stamping and recording what
-that act does — else by its own save, unticks it by the act moving it back, and its status moves in
-place. State a second act `of` the child with `on: "rows"` to complete several at once.
-`starts: { "<member>": "me" }` fills the assignee from whoever adds the row. `opens: { "<member>":
-"me" }` opens a register on the reader's own rows, and a reading's `where` takes `"me"` the same
-way — both narrowed on the server. A register over that child — "My tasks" — rings its rows by
-its own acts the same way. `scaffold check` prints each ring's write — a ring no write reaches is
-drawn disabled, and the check notes it.
-
-**Look at it before anything exists.** `lotics app preview <model.json>#<app>` compiles the app
-against the model's own ids, answers every read from the model's `rows` (a few synthesized for an
-entity that states none), renders the register, the record in its door and the add dialog at 1280
-and 375, and runs the probes `app check --screens` runs — no workspace, no credential, nothing
-created. `--shots <dir>` writes what it measured as PNGs.
-
-`--from` takes the model file `lotics scaffold check` approved and the app in it, and writes
-**`app.json`** — the app compiled against the live `tbl_`/`fld_`/`opt_` ids its entities became —
-beside a `src/main.tsx` that mounts `@lotics/app-runtime` over it, one `src/workflows/<alias>.ts`
-per write and an empty `src/components/index.ts`. Every write — a create, an edit, a remove, each
-act — is a generated workflow that re-checks on the server what the model states: required fields,
-`write_rules`, an act's `when` and `requires`, and the checks that block it. The runtime draws the
-spec; there is no screen source to edit (`node_modules/@lotics/app-runtime/AGENTS.md`). The tables
-have to exist (`lotics scaffold apply` first); a table or field the workspace lacks is refused by
-name. The app is recorded against its model alias, so a second `--from` for the same alias is
-refused. The project's `README.md` is the app in prose: its register, its record and the tables
-behind them.
-
-`--api` scaffolds the app something OUTSIDE Lotics calls (§ 9): the manifest, `src/workflows/`, a
-CI job and the two briefs, with no `index.html`, no `src/App.tsx`, no Vite config and no kit. Its
-one devDependency is `typescript`, because `app workflow check` runs the project's own compiler.
-Nothing is built and nothing is deployed, so `current_version_id` stays null and the surface goes
-live through `app query set` / `app workflow set` instead. It cannot be combined with `--from`,
-which describes screens; `app dev` and `app check --screens` refuse a project with no Vite
-config, `app deploy` one with no `build` script, and `app pull` rebuilds its project from the app row,
-since there is no archive. Steps 7 and 8 below do not apply to
-it, and step 9 ships it without a build: `npm run typecheck` (it declares no `lint` and no `test`
-script), `lotics app check` on its own, then `lotics app api publish` where a screens app deploys.
-Every other step applies unchanged.
-
-A pull writes more than source: one `src/workflows/<alias>.ts` per bound workflow, one
-`src/agents/<alias>.md` per bound agent, and the `.lotics/` type companions — so an existing app
-arrives fully editable rather than as an archive you have to reconstruct.
-
-**The model changes after the app is built, and `lotics app regenerate` is how it lands.** Run it
-inside the app; the model is the one `package.json#lotics.plan` remembers, unless `--from` names
-another. The generator owns what it emits: `app.json` is compiled from the model and rewritten
-whole, and a generated workflow body is rewritten too, with the text it replaced parked in
-`.lotics/regenerate-dropped.patch`. Two things are yours and survive every regeneration:
-`src/components/` (seeded where it is absent, never rewritten), and the body of an act's own
-`workflow` — only the guard region at its top, between the `<lotics:guards>` markers, is the
-generator's. The manifest is reconciled by ownership — the generator's aliases replaced, the ones
-it retired removed, the ones you added kept — then codegen and `app check` run. A generated
-workflow is declared with the inputs it reads and the `outputs` its return hands back, so a
-contract an earlier generation bound is replaced at the next deploy; your own act's `workflow`
-keeps the outputs the server derived from your body. That body follows the guard region, which
-already declares `i` and, on one record, reads it into `row` by `i.record_id`: reuse them, never
-declare them again.
-
-**Nothing is pushed.** What the live app RUNS changes at `lotics app deploy` and nowhere else: the
-bundle production serves was built against the bindings it has, so a regeneration that replaced a
-live workflow body left a deployed dialog posting inputs that workflow no longer declared. The
-summary names what a deploy will add, change and leave bound instead. `--bind-new` binds the
-aliases the app does not have YET — `lotics app dev` forwards queries to production, so a new alias
-cannot be tried before something binds it — and refuses, naming them, to touch one that already
-exists. `--dry-run` prints the whole run and writes nothing.
+- **An app stated in a model** — the default, and the right one for almost every job. `model.json`
+  says how a row of each entity is recognised (`records`) and, in `apps`, one register over one
+  entity and the record its rows open: its columns and filters, its sections in the order its work
+  reaches them, its acts and the checks that guard them (`lotics docs model/apps`). The platform
+  compiles each app and draws it with the runtime every such app shares, so how each piece looks is
+  the platform's, one way per concept, and no key changes it. Every write the app makes is a
+  generated workflow that re-checks on the server what the model states.
+- **A custom-code app** — React you write, for a surface the model's vocabulary cannot state. It
+  reads and writes through `@lotics/app-sdk` (queries, workflows, files, AI) and draws with whatever
+  React you choose.
 
 ## 2 — Clarify what is being asked, before modelling it
 
@@ -126,12 +44,11 @@ wrong. Ask until there is no ambiguity left:
 This is the step that gets skipped under time pressure, and it is the only one whose mistakes are
 invisible in review: every later artifact is correct with respect to the wrong definition.
 
-## 3 — The data model, before any code
+## 3 — The data model, before any app
 
-Get this wrong and nothing above it can be precise. Each entity is its own table with
-`record_link`s into the spine; attributes and evidence are fields on their owner. A single table
-with a `type` column standing in for three entities collapses the distinctions every later query
-needs.
+Get this wrong and nothing above it can be precise. Each entity is its own table with links into
+the spine; attributes and evidence are fields on their owner. A single table with a `type` column
+standing in for three entities collapses the distinctions every later query needs.
 
 **Verify real VALUES, never just that a field exists.** `lotics run query_records` a sample and
 look at fill rates — a field that is present and empty on 90% of rows will not support the screen
@@ -139,339 +56,101 @@ you are about to design.
 
 **That includes imagery.** If the entity has a likeness — a product, a property, a vehicle, a
 person — its picture is the strongest identifier a register row can carry, and an empty image field
-is a data gap to fill before you design around it (see `lotics docs composition`, §Character comes
-from the DATA). Fill it the same way you fill any other field: put the file on the record. Where the
-images do not exist yet, generate them out of band and `lotics file upload` + `update_records` them
-on — and keep one style across the whole set, because a catalogue whose shots disagree about
-lighting and background reads worse than one with no pictures at all.
+is a data gap to fill before you design around it: `lotics file upload`, then `update_records`.
 
 **One fact, one column — and check before you add one.** Read the table's existing fields before
 adding any, because the fact is often already there in another shape: a place written as text
-beside a `select_record_link` to the place record, a status word beside the select that decides it,
-a total beside the formula that computes it. Two columns for one fact never stay equal — some
-writer sets only one of them, and nothing reports the divergence because both rows look correct
-alone. Prefer the link, the select, or the formula, and compose the text when you READ. Renaming or
-re-pointing the existing field beats adding a second one; a field is addressed by key, so a rename
-breaks nothing. Superseding a field means deleting it, not leaving it beside its replacement.
-
-**Match on ids and option keys, never on rendered text.** A reader that compares display strings
-treats "Acme" and "Acme Ltd" as different records, and a value spelled `Net 30` as different from
-the option labelled `Net 30 days` — so an import creates a duplicate every time it runs, silently,
-because each row looks right on its own. Resolve a name to its `rec_…` or `opt_…` once, at the boundary, and
-compare those. Treat an unresolved name as UNKNOWN, never as a wildcard.
-
-**How the tables RELATE is `lotics docs data_model`** — one entity per table and the overlap probe
-that says when a split has broken, one vocabulary wherever values are copied between tables, a copy
-boundary that accounts for every source field, provenance as a link, a declared natural key, and why
-derived depth costs more than row count. Read it before designing a schema; those decisions outlive
-any one app, and most of them are unfixable once a second screen depends on the copy.
-
-**Empty is not the same as redundant.** A field nothing fills may still be the only home for a real
-distinction, and a column whose values are all `1` may be the volume band nobody has needed yet.
-Read what a field MEANS before you remove it; "unused in this data" is not evidence it is wrong.
-
-## 4 — Typed field access
+beside a link to the place record, a status word beside the select that decides it, a total beside
+the formula that computes it. Two columns for one fact never stay equal. Prefer the link, the
+select, or the formula, and compose the text when you READ.
 
-```
-lotics app codegen        # no deploy, no version bump
-```
-
-Regenerates `.lotics/`: the three `.d.ts` companions that type `useQuery` / `useWorkflow` /
-`useAgentRun`, and — when credentials resolve — `app_fields.ts`, exporting four maps keyed by
-display-name aliases: `F` (table → field → `"fld_…"`), `OPT` (table → select field → option →
-`"opt_…"`), `TBL` (table → `"tbl_…"`) and `GRP` (member group → `"grp_…"`).
-
-Address every id by alias, never by a pasted one — a table id and a member group included:
-
-```tsx
-row.opt(r[F.SHIPMENT.direction]) === OPT.SHIPMENT.direction.export
-useCommentCounts({ table_id: TBL.SHIPMENT });
-useMembers({ group: GRP.sale });
-```
+**Match on ids and option keys, never on rendered text.** Resolve a name to its `rec_…` or `opt_…`
+once, at the boundary, and compare those. Treat an unresolved name as UNKNOWN, never as a wildcard.
 
-An alias is slugified from the display name, so a rename on the platform MOVES it: re-run `codegen`
-and every call site on the old alias fails `tsc` until it names the new one. **Re-run after any
-schema change** — local typecheck is only honest if the generated ids are current, and you never
-deploy to refresh types.
+**How the tables RELATE is `lotics docs data_model`** — read it before designing a schema; those
+decisions outlive any one app.
 
-## 5 — Named queries
-
-Author them as `kind: "project"` with a `filter`. A bare `from_table` over-exposes columns and
-degrades at scale. Scope per-user reads with `is_current_member` **inside the template** — a
-`member_id` passed from the client is an IDOR, since the caller chooses it.
-
-Name each projected column — `{ "source": "fld_…", "output": "total" }` — and the row is then read
-as `r.total`, with no field map on the read path; `lotics app create --from` emits exactly that.
-Write one `description` per alias too: it is the line a chat or MCP caller chooses between them by,
-and `lotics app check` exits 1 naming any alias that has none.
-
-Decode cells with the `row.*` helpers (`row.text`, `row.opt`, `readSelect`, `readLinks`), never by
-reaching into the raw shape: a select cell is `[{key,label}]`, and a hand-rolled reader silently
-returns the wrong half.
+**Empty is not the same as redundant.** A field nothing fills may still be the only home for a real
+distinction. Read what a field MEANS before you remove it.
 
-Iterating a query needs no deploy either:
+## 4 — An app stated in a model
 
 ```
-lotics app query set <alias>     # pushes package.json#lotics.queries.<alias>, server-validated
+lotics docs model                       # how to write model.json, with a worked example
+lotics model apply model.json           # check it, apply the tables, mint a version of every app
+lotics model apply model.json --app orders   # only the apps named; the tables are applied whole
+lotics model pull -o model.json         # the workspace's model, as the file apply reads
 ```
 
-Details: `lotics docs queries`.
-
-## 6 — Workflows, the only way an app writes
-
-**A workflow binding is SOURCE, and it deploys with the app.** Its two halves are
-`package.json#lotics.workflows.<alias>` and `src/workflows/<alias>.ts`; `lotics app pull` writes
-both, and `lotics app deploy` pushes whatever differs from what it last saw live — through
-`set_app_workflow`, before the bundle ships, so a version that shipped always reproduces what runs.
-Nothing is bound by hand after a deploy, and nothing needs to be: an alias whose body and
-declaration are in the repo is an alias the next clone can build. Three consequences worth knowing
-before you write one:
-
-- **A push refuses when the live body moved past the copy you edited.** The baseline rides as a
-  precondition, so two people editing one alias is a refusal naming it, never a silent clobber.
-- **An unchanged alias is not pushed.** An update is a diff, so a deploy that changes one screen
-  does not re-push nine workflows.
-- **Deleting the declaration and the file does not unbind it.** The binding keeps serving, and
-  keeps being published to chat and to MCP. `lotics app deploy --prune` unbinds what the project no
-  longer names, and it is opt-in because an alias can be invoked from outside the bundle. An alias
-  `lotics app regenerate` retired is the exception: the next deploy unbinds it unasked.
-
-A workflow body is a file you open and edit. The new-alias path is typed from the first line:
-
-1. Declare it in `package.json#lotics.workflows.<alias>` — its `inputs`, and `outputs` only to
-   narrow beyond what the body infers.
-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 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`
-writes the schema back into the manifest and refreshes that alias's types in place.
-
-The alias's `description` rides along from the manifest. It is the one line an agent reads when
-choosing between your workflows, so write it rather than leaving the generated placeholder — and
-keep it inside 300 characters, the cap a push holds both a workflow's and a query's `description`
-to, because both ride the capability catalog into the agent's prompt on every run. `app check`
-names every alias over it and exits 1, and `workflow set` / `query set` refuse before sending
-anything, so a long line costs one edit rather than a failed push per alias.
-
-**Every workflow you declare is also the chat agent's write surface.** So the alias's *shape* is an
-agent-facing decision, not only a screen-facing one — take a list where one job covers many
-records; say in an optional input's own `description` what omitting it means, since the agent
-cannot see the default your body applies; make the write survive running twice on the same input;
-and gate anything irreversible with `wait_for_approval` inside the body. `lotics docs ai` and
-`lotics docs workflows` carry each of those.
-
-**Static green is not a run.** `check` and `set` prove parse, types, name resolution and lint —
-they evaluate nothing. Rehearse before the first live run:
-
-```
-lotics run dry_run_workflow '{"trigger_type":"app_workflow","trigger_payload":{…},"live_reads":true}'
-```
+`model apply` checks the whole file first — every problem in one run, before anything is uploaded
+or written. It then adopts or creates each table (an existing table of the same label is adopted
+and given what it lacks; no stored value changes), writes the first rows only where every bound
+table is empty, and mints one version per app, printing each app's id and the version minted
+(`unchanged` when there was nothing to mint). Applying the same file again mints nothing.
 
-It walks the real step tree and returns the resolved plan plus expression and tool-input errors,
-dispatching no write. Pass the raw body — the file carries a wrapper that `set` strips and this
-tool does not. **`live_reads: true` matters whenever the body reads anything**: without it every
-read returns a stub, so a duplicate check finds no duplicate and every data-gated branch takes the
-empty path — green, and proving nothing about the branch you care about.
+**The model changes after the app exists, and applying it again is how it lands.** Edit the file,
+apply it. An act whose write the model cannot say names its own `workflow`; that workflow's body is
+the live one, and `lotics run set_app_workflow` changes it.
 
-Then prove it end to end without a screen:
+## 5 — A custom-code app
 
 ```
-lotics run run_app_workflow '{"app_id":"app_…","alias":"…","inputs":{…}}'
-# exits non-zero on error, so it is assertable
+lotics app create "<name>" --custom     # the app, plus a Vite + React + TS project using @lotics/app-sdk
+cd <dir>
+# edit src/App.tsx — node_modules/@lotics/app-sdk/AGENTS.md is the reference
+npm run typecheck && npm run lint && npm test
+lotics app deploy -m "<what changed>"   # build, upload, a new version live
 ```
 
-A workflow is also how an app **produces a document** — an invoice, a debit note, a shipping
-label. The `generate_*_from_template` tools fill a template you registered once, and the file
-comes back to the app on `result.files[]`, **not** through `return({ data })`; that channel
-carries values, never files. Registering the template is a CLI job, not an app one:
-`lotics docs document_templates`.
-
-Authoring rules for the body itself: `lotics docs workflows`.
+What the app reads and writes is bound on the app, never in the project: `lotics run
+set_app_query` binds a named query, `lotics run set_app_workflow` a workflow body, and each mints a
+version. `useQuery("<alias>")` and `useWorkflow("<alias>")` call them. A deploy uploads the build
+and carries every binding forward unchanged.
 
-## 7 — Screens
+**Named queries.** Author them as `kind: "project"` with a `filter`, naming each projected column
+(`{ "source": "fld_…", "output": "total" }`), so a row reads as `r.total`. Scope per-user reads with
+`is_current_member` **inside the query** — a member id passed from the client is chosen by the
+caller. Write one `description` per alias: it is the line a chat or MCP caller chooses by.
 
-**A model-built app's screens are its `app.json`, and `@lotics/app-runtime` draws them.** The
-register, the record each row opens, its sections, the acts and the checks are all stated by
-the model, so a correction is a change to the MODEL followed by `lotics app regenerate` — or, where
-the ruling is about how every app draws, a change to the runtime or the kit that reaches every app
-on its next install.
+**Workflows are the only way an app writes.** Every workflow bound to an app is also the chat
+agent's write surface, so its shape is an agent-facing decision: take a list where one job covers
+many records, say in an optional input's `description` what omitting it means, make the write
+survive running twice, and gate anything irreversible with `wait_for_approval`.
 
-**Where the vocabulary has no word for what a record needs,** a `component` block names one of the
-app's own components (`lotics docs components`), and an act whose write `set` cannot say names its
-own `workflow`, which runs after the generated guards. A component the kit lacks is built into the
-kit, never hand-rolled in one app.
+## 6 — Prove it, without a screen
 
-**A hand-written app composes the kit itself.** Before any JSX, read `lotics docs ui` — the catalog
-and the composition grammar; the pieces the runtime draws a record with (`RecordFrame`,
-`RecordHeader`, `ChecksCallout`, `ActGroup`, `ActAsksDialog`) and the register's (`Table` with a `Row`
-subject, `FilterBand` with `StatusChips` and `GroupByMenu`) are there to compose rather than rebuild.
-
-Two rules for any code the app writes itself — a component or a hand-written screen:
-
-- **Never copy server data into `useState`.** Derive from `useQuery` / `useWorkflow` with
-  `useMemo`; a copy goes stale the moment anything else writes.
-- **Design the loading, empty and error states.** Reserve their space so the layout does not jump.
-
-**The kit is a strong recommendation, not a requirement.** `@lotics/app-runtime/sdk` is data and
-RPC only — its peers are `react`, `react-dom` and `react-router` — so an app can be plain DOM React
-with your own CSS and still use every hook, deploy the same way, and run the same server-side.
-What the scaffold buys you is the part that is hard to get right by hand: a screen that looks
-deliberate, states that are already designed, and behaviour that matches the rest of the product.
-Building without it means owning all of that, so reach for it unless you have a specific reason not
-to — and if you do, the ONLY thing you give up is the components.
-
-## 8 — Run it locally, and prove it
+Static checks prove parse, types and names — they evaluate nothing. Rehearse a write first:
 
 ```
-lotics app dev
+lotics run dry_run_workflow '{"trigger_type":"app_workflow","trigger_payload":{…},"live_reads":true}'
 ```
 
-Vite plus an RPC-forwarding server, in a sandboxed iframe matching production, with real data and
-auth and HMR. File flows work too — the dev server relays the bytes, so upload, preview and
-download are all exercisable locally.
-
-**Navigate with `waitUntil: "domcontentloaded"`.** A dev app never goes network-quiet — the Vite
-client and the app's own cross-origin frame each keep a connection open — so a driver that opts
-into `networkidle` waits out its timeout on an app that rendered fine, and the timeout reads as the
-app being broken. Any in-app path opens directly (`http://localhost:<port>/lo/rec_…`); the wrapper
-serves every path that is not one of its own `/_…` routes.
-
-**Drive it with a browser, in this order** — each step's failure means something different:
-
-1. **Does it render at all?** A blank iframe is almost always a bundling problem, not your code.
-2. **Read the console before the DOM.** A React error boundary shows a blank region; the reason is
-   only in the console.
-3. **Does the data arrive?** Check the query result before blaming the layout — an empty list and a
-   broken list look identical.
-4. **Then interact.** Click the real control rather than calling the handler: an element that is
-   covered, disabled, or outside the viewport fails only under a real click.
-
-**Everything inside the app is a separate frame.** The app renders in a sandboxed iframe served
-from a different port, so it is cross-origin to the wrapper: parent-page JavaScript cannot reach
-`contentDocument`, and a selector run against the page finds nothing. Address it through the frame
-— `page.frameLocator("iframe")`, or the frame refs an accessibility snapshot gives you — and run
-any injected script in the frame's own context, or its `window` and coordinates are the wrong ones.
-
-Three kit anatomies then need driving deliberately rather than clicked: a pressable row's named
-button always intercepts pointer events, overlays portal to the top of the DOM, and custom pointer
-drag ignores `dragTo`. All three are by design and all three read as bugs — `lotics docs testing`.
-
-Read a failure by what it *cannot* be. A control that takes its value while its list never appears
-is not a wiring bug — the list is rendered somewhere the harness cannot see. Assert what the DOM
-actually carries, not what the source says it should.
+It walks the real step tree and returns the resolved plan plus expression and tool-input errors,
+dispatching no write. **`live_reads: true` matters whenever the body reads anything**: without it
+every read returns a stub, and every data-gated branch takes the empty path.
 
-## 9 — Verify, then ship
+Then run it end to end, on a throwaway record:
 
 ```
-npm run typecheck && npm run lint && npm test
-lotics app check --screens --shots shots/
-                                     # every pre-flight a deploy runs, without building or shipping,
-                                     # plus the portability gate a library publish applies, plus
-                                     # every screen rendered at 1280 and 375, measured, and written
-                                     # to shots/ as a PNG per screen and per record it opened
-lotics app deploy -m "<what changed + why>"
+lotics run run_app_query '{"app_id":"app_…","alias":"…","params":{…}}'
+lotics run run_app_workflow '{"app_id":"app_…","alias":"…","inputs":{…}}'
+# exits non-zero when the run failed, so it is assertable
 ```
 
-**A green suite says nothing about how the screen LOOKS**, and that half starts with
-`--screens`: it renders the app over its real data (Chrome needed), walks every tab at both
-widths, and refuses what a review would; what it measures is in `lotics docs cli_reference`. It
-is a READ, enforced at the network rather than by what the walk presses — the CLI serves the app
-an allowlist of read ops and refuses everything else before the call leaves your machine, and a
-refused call heads the report and fails the run. What
-it cannot measure is in `lotics docs reviewing` — which is why `--shots <dir>` is on the same
-line: it photographs the frame each probe read, so LOOKING at the app is the same run rather than
-a dev server and a browser pass per screen. Open the 375 shots first. Both before the deploy, not
-as an audit someone schedules after a complaint.
-
-Every check above reads the SOURCE; none of them renders it. So the entire class of defect that
-lives in the pixels — wrong form for the subject, a treatment that contradicts what an element
-means, a surface that measures clean and still tells the reader nothing — passes all of them
-silently, and arrives later as "it looks bad", which is a report about a cause the reporter cannot
-name. That is what the review is for, and why it belongs here rather than in whoever remembers to
-ask for it.
-
-`-m` is optional; the deploy derives a message from what it pushed. Write one when the *why* is
-worth keeping.
-
-Then set the icon, the colour and the app's own `description` — the most-forgotten step, which is
-why `deploy` and `check` both warn while any of them is unset:
+A workflow is also how an app **produces a document** — the `generate_*_from_template` tools fill a
+template you registered once (`lotics docs document_templates`).
 
-```
-lotics app rename "<the app's name>" --icon <lucide-name> --theme blue \
-  --description "<what the app is for, and the standing job it does>"
-```
+## 7 — Look at it, then name it
 
-The name is repeated because it is the same act: `app rename` is the one verb that sets an app's
-display metadata, and it also folds the new name into `package.json#name`, which nothing else
-does. Renaming to the name it already has changes nothing on the server.
+Open the app and look at it at a desktop width and at a phone's — every check above reads the
+definition, none of them the pixels. A version that looks wrong is one `lotics run rollback_app`
+away from the one before.
 
-The `description` is not a label. It heads the capability listing the member's chat agent reads on
-**every** turn, so a standing process the app expects that agent to carry out belongs there and
-nowhere else — not in workspace instructions and not in a knowledge doc, both of which apply to
-every app at once (`lotics docs ai`).
+Then set the icon, the colour and the app's own `description` through `lotics run update_app`. The
+`description` heads the capability listing the member's chat agent reads on **every** turn, so a
+standing process the app expects that agent to carry out belongs there and nowhere else.
 
 **A caller outside the team gets its own app.** Sharing an app publicly, or giving an API key
-*Only selected ones* → that app, reaches every alias the app declares; no alias can be held back.
-So whatever outsiders may call is a SECOND app over the same tables: only the queries they may
-read, each projecting only the columns they may see, and only the workflows they may run — a form
-anyone can reach is workflows and no queries at all. It needs no screens, so scaffold it with
-`lotics app create "<name>" --api` (§ 1): push its aliases with `app query set` /
-`app workflow set`, share it or give a key to it, and `app api publish` once a caller depends on
-it — there is no deploy anywhere in that loop. The desk the team works in stays a separate,
-private app.
-
-Finally, update the app's own `README.md` on any model or behaviour change and redeploy, so the
-brief travels with the app rather than living in whoever built it.
-
----
-
-## The inner loop
-
-Once scaffolded, everything below happens locally:
-
-```
-edit src/workflows/<alias>.ts        # or a component, or a query
-lotics app preview model.json#<app> --shots shots/   # when the MODEL moved: see it before a table does
-lotics app regenerate --dry-run      # then: what the new generation would do to this app
-lotics app codegen                   # after any schema change
-npm run typecheck                    # honest, because codegen is current
-lotics run run_app_workflow '{"app_id":…,"alias":…}'   # prove the mutation path
-lotics app dev                       # prove the screen
-lotics app check --screens --shots shots/   # measure it AND photograph it, before anyone looks
-…
-lotics app workflow set <alias>      # push the body; the server verifies
-lotics app deploy -m "…"             # pushes pending bindings, then ships
-```
-
-**An app lists `@lotics/app-runtime` and nothing else of ours** — its SDK is every app's data
-layer, and it depends on the kit it draws with. Where the app's own code imports the kit, it lists
-`@lotics/ui` at **the runtime's range**, never its own; `lotics app kit` keeps the two in step.
-**Proving a change to the runtime before it is published** is
-`lotics app kit <path-to-packages/app-runtime>`: it builds the runtime, packs it into this app's
-`.lotics/kit/`, installs it by file specifier and hashes one built file on both sides to prove the
-install took — a repack under the same name is otherwise served from the lockfile's first tarball,
-and every other signal reads as success. `app check` then says the app depends on a build that
-exists on one machine, and `app deploy` refuses it (the tarball is not in the source archive, so a
-clone could not install) unless you pass `--allow-local-kit`. `lotics app kit --published` puts
-back the range the app listed before the first checkout — an app with none recorded moves to the
-registry version — and migrates an app still on `@lotics/app-sdk`, the package the SDK was before
-it moved into the runtime (`lotics docs migration`). A kit change reaches an app through the runtime that depends on
-it; `LOTICS_UI_SRC` links the kit's source into `lotics app dev`.
-
-A deploy pushes any workflow body, agent prose or query that is ahead of the app **before** it
-ships the bundle, so a forgotten `set` cannot ship a bundle typed against a binding that does not
-exist. It asks the server about every query and body first and pushes none when one would be
-refused, so a release never stops half way with the app reading a mix of new and old bindings. It then regenerates the `.lotics` types and runs `npm run typecheck` before building — Vite
-strips types, so that run is what makes them a gate. `lotics app check` reports the same set, holds every
-query to the server's own gate, and runs the same typecheck, without pushing.
-
-Keep the CLI current: an old one silently drops manifest fields it does not model.
+access to it, reaches every alias the app declares; no alias can be held back. So whatever
+outsiders may call is a SECOND app over the same tables: only the queries they may read and the
+workflows they may run. The desk the team works in stays a separate, private app.