@lotics/cli 0.239.0 → 0.240.0

package/docs/building_an_app.md

@@ -289,7 +289,7 @@ is where it is looked at.
 **Where the plan has no word for a screen, a section or an act,** the spec names one of the app's
 own components — `lotics app eject` writes it from exactly what the runtime was drawing, one part at
 a time, and `lotics docs components` says what it is handed. A screen no shape fits is declared in
-the plan as `"shape": "custom"` with its slots as roles (`lotics scaffold docs` § Apps and screens)
+the plan as `"shape": "custom"` with its slots as roles (`lotics docs model/apps-and-screens`)
 — never a shape bent to fit — and then `lotics report` with `wanted` opening `shape <name>`: a custom
 slot set that recurs becomes a shape, and the report is how the next build gets it. A component
 the kit lacks is built into the kit, never hand-rolled in one app.

package/docs/clauses.md

@@ -2,7 +2,7 @@
 
 Every clause an app in a model's `apps` can state, what it draws, and an example
 value. `[]` is every element of a list or a map; `as` is one form a key takes.
-Each clause's rules are `lotics scaffold docs` § Apps and screens.
+Each clause's rules are `lotics docs model/apps-and-screens`.
 
 `lotics app preview <model.json>#<app> --shots <dir>` renders an app stating any
 of them, over the rows of your own model, before a table exists.

package/docs/cli_reference.md

@@ -6,7 +6,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 |---|---|
 | `lotics` / `lotics --help` | Show full help with capabilities, tool categories, workflow |
 | `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |
-| `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>`, also mailed — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `library list`/`show`, `scaffold docs`/`check`, `app codegen`, `app workflow check` — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
+| `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>`, also mailed — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `library list`/`show`, `docs`, `scaffold check`, `app codegen`, `app workflow check` — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
 | `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
 | `lotics auth web` | Send a magic link email to access the web app (requires auth) |
 | `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key — read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |
@@ -55,19 +55,19 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app codegen [path]` | Regenerate `.lotics/*` from the manifest + workspace schema **without a deploy**. The three `.d.ts` companions (`app_{workflows,queries,agents}.d.ts`) are always rewritten (synchronous, no network). When credentials resolve, also rewrites the **runtime** `.lotics/app_fields.ts` — a real `.ts` exporting `F` (table→field→`"fld_…"`), `OPT` (table→select-field→option→`"opt_…"`), `TBL` (table→`"tbl_…"`) and `GRP` (member group→`"grp_…"`) keyed by display-name aliases, for every table the app's queries READ plus every table its bound workflows WRITE (each binding's recorded `table_ids`, so a table no screen reads is still addressable by alias and a rename fails `tsc` instead of the body), plus every member group in the organization — which one a screen names is not knowable from the manifest, and a `GRP` narrowed by a failed read is a map that is wrong rather than absent, so a failure writes nothing. **There is one form, and that is what makes a starter's source portable**: the keys are slugified DISPLAY NAMES and a starter carries its labels verbatim, so running codegen in a copy's own workspace emits the same keys pointing at that workspace's ids — no binding fetched at load, no prebuilt bundle to keep in step. Beside it, `.lotics/app_siblings.ts` exports `APP` — every app the workspace's model declares, by the plan's alias for it (`APP.<alias>` → `"app_…"`), read off the workspace's model binding — so a hand-written app opens a sibling as `openApp(APP.<alias>, route)` and holds no `app_` id; an app archived here is absent, so a call naming it fails `tsc`. The binding is an admin's read: a key that cannot read it keeps the file on disk and says so. Also refreshes each bound workflow's `.lotics/workflows/<alias>.globals.d.ts` + re-wraps its EXISTING `src/workflows/<alias>.ts` body in the current envelope (strips + re-wraps; never re-fetches the body, so local edits survive). **`.lotics/` is reconciled to the manifest, not merely added to** — a `<alias>.globals.d.ts` whose alias the manifest no longer declares is DELETED. Only that exact filename shape is removed; anything else in the directory is left alone. The reconcile runs before the credential branch, so it happens offline too. The authored counterpart is never deleted — a `src/workflows/<alias>.ts` the manifest does not declare is NAMED instead (`check` and `set` both take their alias set from the manifest, so editing an undeclared body is a silent no-op). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). **Re-silvers `package.json#lotics.agents`** from the live app row whenever its `inputs`/`outputs` disagree, then rewrites the agent `.d.ts` from the refreshed block: that block is a mirror AND the offline seed for `useAgentRun` typings, so a stale copy types the app against an agent that does not exist. The write is surgical and order-preserving, so it changes only the fields that actually differ. A hand edit to that block is therefore reverted — it never changed the agent anyway; to change one, `set_app_agent`. **Types are written for every DECLARED alias, body file or not** — the dts is rendered from the declaration, which is the whole point of the declare → codegen → write → check loop — and codegen NAMES each alias it wrote types for without a body, with the next step. It used to return early on a missing or blank `src/workflows/<alias>.ts` and say nothing, which left `workflow check` pointing at `app workflow pull` (which writes nothing for an alias the server has never bound) on one path and at `app codegen` — the command that had just declined to write them — on the other. **A body whose helper sits ABOVE the `__workflow` wrapper is refused by name and line** rather than wrapped a second time: the strip peels a wrapper only when it is the first line after the header, so a top-level declaration between the two used to leave the whole file read as the body and the re-wrap nested an envelope per run. Move the helper inside the wrapper — the body is one expression sequence. |
 | `lotics app kit <path-to-packages/app-runtime>` \| `lotics app kit --published` | **The app's ONE range, `@lotics/app-runtime`, from a CHECKOUT, or back to the range it listed before**, so a runtime change is proven on a real app before it is published. Run inside the app directory; the path names `packages/app-runtime` in your clone (a kit change reaches an app through the runtime that depends on it — `LOTICS_UI_SRC` links the kit's source into `app dev`). It runs the runtime's own `npm run build`, `npm pack`s it into the app's `.lotics/kit/` (replacing any earlier pack, so the directory holds one tarball), removes the installed copy and the lockfile's entry for it, installs by file specifier, and then **proves the install**: the first non-dot file of the directory the package's own `package.json#files` publishes is hashed on both sides, and a mismatch — or an absence — is a refusal naming the file. That proof is the point. A repack under the SAME name is the normal case (a working copy's version does not move between builds) and the lockfile pins the first tarball's integrity, so on some npm versions the install is a no-op that reports success while the app keeps building against an hour-old kit; nothing else in the loop can tell. **Either way the rest of the manifest follows the runtime**: `@lotics/ui`, where the app lists it, moves to the range the runtime depends on — two ranges are two copies of the kit — and an app still on `@lotics/app-sdk` (the package the SDK was before it moved into the runtime) is MIGRATED: every `@lotics/app-sdk` and `@lotics/app-sdk/router` specifier under `src/` and in the Vite config becomes `@lotics/app-runtime/sdk` and `@lotics/app-runtime/router`, the dependency is dropped, and the summary names each file rewritten. **Refusals, all before anything is written**: a directory that is not a Lotics app (no `package.json#lotics.workspace_id`); a path that is not `@lotics/app-runtime`; a runtime that declares no `@lotics/ui` range while the app lists the kit; `--published` given a path; a build that failed, named with npm's own output tail. **It records what it did in `package.json#lotics.kit.@lotics/app-runtime`** (`version`, `tarball`, the `source` checkout, `packed_at`), which is what `lotics app check` warns about and what `lotics app deploy` REFUSES on unless you pass `--allow-local-kit` — `.lotics/` is excluded from the source archive a deploy uploads, so an app whose manifest names `file:.lotics/kit/…` ships a bundle that runs and a source tree the next clone cannot install. The record also keeps what the app listed before the FIRST checkout went in (`replaced` — a repack keeps it), and `--published` undoes the trial: the runtime and the kit go back to exactly those specs, so a kit trial never moves an app to another line on its way out; an app with no such record (never given a checkout, or given one by a CLI that recorded none, which the run says) moves to `^<latest>` from the registry and the kit to the range that published version depends on. Either way the tarball and the record are deleted, the lock entry and the installed copy are cleared, and a plain install resolves the published package. Needs no credential — npm, the filesystem and (for `--published` with no prior range) the registry. |
 | `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 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. 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 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 docs model/presets`), 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. |
+| `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 docs model` is where that goes. |
 | `lotics library show <slug\|apg_id> [--json]` | **The argument says which shelf**, and both forms are allowlists rather than a fallback: an `apg_` id is a package, anything else is a preset slug (`^[a-z0-9_]+$`, refused before any request — a slug reaches a URL). **A SLUG** reads the preset's own file off the website with no credential and no account, which is the whole timing argument for serving it as a file: it prints the preset's name and sentence, the questions it may ask (at most two), every table as `alias · label` with each field as `alias:type`, and every branch as `slug · when` followed by the tables and fields taking it ADDS — a slug picked off its `when` alone cannot say whether the branch brings the column the person was asked about. It closes with the `{"from": …}` file to write. The file is proven as a MODEL on the way through (the same `readPresetModel` this repo's own test runs over these files), so a preset that would fail in the workspace of whoever takes a branch is refused here, named in the preset's own keys — ours to fix, not the reader's. **An `apg_` id** prints the package: name, description, current version, shelf tile and trust standing (`official` — reviewed by Lotics; `your organization's own`; otherwise `not copyable from this organization`), plus the date it was unpublished once it has been, then the same COMPACT table listing — each table as `alias · label`, each field as `alias:type` — which is exactly what a `--bind` is typed from. Read it before copying a package you did not publish. **Works with no account for anything Lotics publishes**, falling to `GET /v1/starters/official/{id}` the way `list` falls to the public shelf; signed in, the prose form is admin-only and readable by id from any org, but an unpublished package 404s for every org except the one that published it. `--json` prints the preset FILE for a slug, and the published contract read whole — views, labels and all — for a package: ONE shape whichever credentials the caller holds, because the reader of that object is a program writing a model from it. |
 | `lotics library init <apg_id> [--bind <entity>=<Label> ...] [--connection <alias>=<cac_id> ...]` | **Copy a package into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates every app the package carries and materializes each one's queries, workflows and agents onto it — then deploys each app from the dist the package was published with, rewriting the publisher's sentinel field keys to this workspace's. No build runs anywhere, nothing is written to this machine, and nothing here needs node: the apps are live when the command returns. **What you get is yours outright**: ordinary apps plus ordinary tables, with no link back to what it came from and nothing pinned. It does STAMP what delivered it (`apps.origin`), which nothing resolves through and only `lotics app upgrade <app_id>` reads. Edit any of it — `lotics app pull <app_id>` is how an app's code is edited afterwards. **The publisher's code runs in your workspace as you** — its apps, workflows and agents — which is why provenance is the gate: **copyable only if the package is Lotics-reviewed or your own organization published it**, enforced server-side; the disclosure is printed (and carried in `--json`'s `warnings`) whenever the package is not your own. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a package declaring `Contacts` would bind to yours. An app whose deploy failed is reported by name with its reason and the exit is non-zero, but the copy is complete around it — the tables, the records and the app row exist — so it must not be run again; the publisher fixes the package and it is copied into a fresh workspace. The sign-in link lands on the app when there is one, else on the workspace's app list. `--json` prints one object on stdout instead of progress (the shape is under `lotics setup`). `--no-sample-data` skips the sample records, and a copy that ADOPTS an existing table writes none either — that table already holds real rows, and the fixture set links to itself, so it is all-or-nothing; with them, how many landed is reported. They are ordinary records, delete them whenever. **`--bind <entity>=<Label>` says which of YOUR tables the package's entities are, and `--bind <entity>.<field>=<Label>` which of your fields** — repeatable, and split on the FIRST `=` so a label may contain one. Scaffold adopts by DISPLAY LABEL, so a bind renames the contract to what you already call things and the copy lands on your tables instead of creating a second set beside them: this is how a package of apps lands on a workspace that already has its tables. Only naming moves — a bound field must be the TYPE the package declares, or the copy is refused (409). A bound entity needs no `--adopt`. The same target named twice is refused rather than overwritten, because the caller then believes one of the two took. `lotics library show <apg_id>` lists the aliases to bind. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`opctl library publish/unpublish`) stays operator-only. **`--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 library fixtures capture [--entity <alias> ...] [--limit <n>]` | **(authoring)** Write this app's live records into the project as `fixtures/<entity-alias>.json` — the sample data a package carries, so a copy lands with something in it. Run from an app project; the app id comes from its manifest. The alias-keyed shape is produced server-side, because the aliases are minted when the starter is extracted and exist nowhere a project can read them. `--entity` is repeatable and comma-separated; omitted, every table the app declares is captured. **Capture a linked set in ONE call** — a link between two rows only resolves within a single capture, so taking companies and contacts separately drops the edge between them (it says so when it happens). `--limit` bounds rows per table (default 10, max 200 — a higher one is clamped, not refused). **A captured row is written into a copy exactly as it reads here**: a cell the origin left empty stays empty, because the copy's inserts do not apply field defaults. **READ WHAT IT WROTE before committing**: these rows are created verbatim in every workspace that copies the starter, so a real customer name, price or address captured here is published. Files, formulas, rollups, lookups and autonumbers are never captured — the platform writes those. Admin-only; writes nothing to the workspace. |
 | `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 docs` \| `lotics docs <area>[/<section>]` | The index of the reference docs, **resolved out of the packages installed beside this project** — the model reference alone is carried by this CLI (`lotics docs model`). **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, a path of sections (`model/field/select`) finds each inside the one before, 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 docs model` \| `lotics docs model/<section>[/…]` | **The model reference, from inside the binary** — the one doc this CLI carries rather than resolves, because it describes this CLI's own plan checker; listed first by `lotics docs`, at this CLI's version. Its first page is what a model composes with, the working order (jobs → entities and fields → roles → one app per job → `scaffold check` → `app preview` → `workspace build`) and the section addresses; every page of it is whole. 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.** |
 | `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, 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.239.0",
+  "version": "0.240.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
     "build": "tsgo -p tsconfig.build.json && node scripts/build_cli.mjs",
     "build:binaries": "node scripts/build_binaries.mjs",
     "publish:binaries": "node scripts/build_binaries.mjs && node scripts/publish_binaries.mjs",
-    "generate:results": "node --import tsx --import ./dev/markdown_text.ts dev/results_app.ts",
+    "generate:results": "node --import tsx dev/results_app.ts",
     "generate:model-reference": "node --import tsx dev/model_reference_gen.ts",
     "typecheck": "tsgo --noEmit",
     "lint": "oxlint",