@lotics/cli 0.234.0 → 0.235.0

package/AGENTS.md

@@ -7,14 +7,15 @@ conventions are, and where the traps are.
 |---|---|
 | `lotics --help` | The verb inventory (§ COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |
 | `lotics tools` · `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |
-| `lotics docs` · `lotics docs <area>[/<section>]` | Every reference the packages installed beside the project actually ship — `@lotics/app-sdk`, `@lotics/ui` and the document engines each carry their own, and this index only covers THIS package. Discovered by looking, not by a list, so it reports the installed VERSION of each: a doc always describes the code that is really there. Capped at a page: a doc that does not fit hands back its opening and the addresses into it, so the next call is smaller than the last. |
+| `lotics docs` · `lotics docs <area>[/<section>]` | Every reference the packages installed beside the project actually ship — `@lotics/app-runtime`, `@lotics/ui` and the document engines each carry their own, and this index only covers THIS package. Discovered by looking, not by a list, so it reports the installed VERSION of each: a doc always describes the code that is really there. Capped at a page: a doc that does not fit hands back its opening and the addresses into it, so the next call is smaller than the last. |
 | `lotics scaffold docs` | How to write a `model.json` — the file a workspace is built from. Two forms: `{"from": "<preset-slug>", "variants", "rename", "entities", "rows", "apply"}`, which names a preset by slug and carries only what this business differs by, and the full one, spelled out, for when no preset is the trade: every top-level key, every field type with the config it needs, the row format, the rules, and a worked example. Offline, and not part of `lotics docs`. It also covers the `apply` list — published packages copied in after the model's own tables, each with an optional `bind` onto them — and the `preset` block a published model carries. `lotics scaffold check` then proves the file — offline, except for the one read a `from` file's preset needs — including every branch of a preset merged onto its base; `lotics setup` applies it and refuses a table name the workspace already has, `lotics scaffold apply` adopts that table and adds what is missing, and the WORKSPACE remembers what each alias became, so every later run binds by id and a relabel on either side is a rename it reports rather than a second table it adds. `lotics scaffold export` goes the other way — a workspace printed as one of these files, to edit into another business's model; a starting point, never a source of truth. |
 | [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE — scaffold, model, types, queries, workflows, screens, ship — and the deploy-free inner loop. The other references describe contracts; this one is the order they go in and why. Read it once before starting an app. |
+| [docs/clauses.md](./docs/clauses.md) | Every clause a plan's app or screen can state, what it draws, and a plan fragment stating it — generated from the schema, so it lists no clause the schema lacks and misses none it has. |
 | [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas — the detail `--help` compresses. Read it before hand-building a `set_app_*` payload: several tools REPLACE rather than patch, and a CLI verb already owns the safe assembly. |
 | [docs/data_model.md](./docs/data_model.md) | How tables RELATE — one entity per table and the NAME-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 rather than a flag, a declared natural key so find-or-create never compares rendered text, and why derived DEPTH costs more than row count. Separate from building_an_app because every workspace starts with tables and many never get an app. The within-table half (one fact, one column) is stated at `create_table` / `update_table`, where you meet it while deciding. |
 | [docs/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates. |
 | [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the workspace facts an agent can't guess; access-vs-activation; catalog-then-stage retrieval. |
-| [docs/migration.md](./docs/migration.md) | What to DO when a release changes the shape of a project this CLI owns. Read once, when something already on disk no longer matches what the CLI writes — currently: an app built from a plan is `app.json` rendered by `@lotics/app-runtime`, not a tree of TSX. |
+| [docs/migration.md](./docs/migration.md) | What to DO when a release changes the shape of a project this CLI owns. Read once, when something already on disk no longer matches what the CLI writes — for one, an app built from a plan is `app.json` rendered by `@lotics/app-runtime`, not a tree of TSX. |
 | [README.md](./README.md) | Install, auth, and worked examples. |
 
 ## Two surfaces, and the trap between them

package/README.md

@@ -31,6 +31,8 @@ package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
 - [`docs/building_an_app.md`](docs/building_an_app.md) — building a custom-code app end to end:
   the sequence the steps go in (clarify → model → types → queries → workflows → screens → ship)
   and the deploy-free inner loop. Read it once before starting an app.
+- [`docs/clauses.md`](docs/clauses.md) — every clause a plan's app or screen can state, what it
+  draws, and a plan fragment stating it, generated from the schema.
 - [`docs/document_templates.md`](docs/document_templates.md) — generate finished documents
   (PDF, Excel, Word, email) by filling reusable templates: the five template types, the
   create → generate → chain lifecycle, and the marker capabilities.
@@ -350,10 +352,10 @@ lotics knowledge rm kdc_...                                   # archive
 # no app row, no table and no credential in the run — then the same headless walk
 # `app check --screens` takes, at the same two widths, measured by the same probes.
 # Exits 1 on any finding and prints what each phase cost. A model with no `rows` is
-# refused: a register over nothing measures clean. It renders from a cached scratch
-# project beside the model file (`<dir>/.lotics/preview/`), installed once from the
-# registry — the kit and the runtime are published packages — and rewritten from the
-# plan on every run.
+# refused: a register over nothing measures clean. It renders in the cached project
+# of its dependency set (`~/.lotics/render/`, shared with `app check --screens`),
+# installed once from the registry — the kit and the runtime are published packages
+# — and rewritten from the plan on every run.
 lotics app preview model.json#sales_desk
 lotics app preview model.json#sales_desk --shots ./shots --width 375
 
@@ -393,14 +395,16 @@ lotics app api unpublish                   # end the promise
 # use this after a rename, or when a pull ran offline.
 lotics app codegen                         # import { F, OPT } from "../.lotics/app_fields"
 
-# Install @lotics/ui or @lotics/app-sdk from your CHECKOUT, to prove a kit change
-# on a real app before it is published: build, pack into .lotics/kit/, install by
-# file specifier, then hash one built file on both sides — a repack under the same
-# name is otherwise served from the lockfile's first tarball. `app check` warns and
+# Install @lotics/app-runtime from your CHECKOUT, to prove a change on a real app
+# before it is published: build, pack into .lotics/kit/, install by file
+# specifier, then hash one built file on both sides — a repack under the same name
+# is otherwise served from the lockfile's first tarball. `app check` warns and
 # `app deploy` refuses (--allow-local-kit ships it anyway), because that tarball is
-# not in the source archive. --published puts the registry version back.
-lotics app kit ../lotics/packages/ui
-lotics app kit ../lotics/packages/ui --published
+# not in the source archive. --published puts back the range the app listed before
+# the first checkout (an app with none recorded moves to the registry's). Either
+# keeps @lotics/ui at the runtime's range and migrates an app on @lotics/app-sdk.
+lotics app kit ../lotics/packages/app-runtime
+lotics app kit --published
 
 # Every deploy pre-flight, WITHOUT the build or the version row: the app's own
 # typecheck over regenerated .lotics types, agent schemas vs the live app, aliases
@@ -410,9 +414,14 @@ lotics app check
 # --screens adds the rendered surface: each screen the app's navigation reaches,
 # and the first record each one opens onto a PAGE, headless in Chrome at 1280
 # and 375, measured against @lotics/ui docs/reviewing.md. --screen and --width
-# narrow it while you iterate on one screen.
+# narrow it while you iterate on one screen. It renders in the cached project of the
+# app's dependency set (~/.lotics/render/, shared with app preview) and prints what
+# each phase cost. --changed walks only when something the screens read has moved
+# since this checkout's last walk (.lotics/screens_check.json), and otherwise
+# reprints that walk's report.
 lotics app check --screens
 lotics app check --screens --screen "Đơn hàng" --width 375
+lotics app check --screens --changed
 
 # Running an app's alias is a TOOL call, like every other tool. Exits non-zero
 # when the RUN failed, not only when the call did.
@@ -439,6 +448,7 @@ lotics app workflow set issueInvoice        # push the edited src/workflows/issu
 # to apps.queries (server-validated like a deploy). apps.queries is manifest-
 # authoritative, so the next `app deploy` re-syncs it — keep the manifest current.
 lotics app query set openInvoices           # push package.json#lotics.queries.openInvoices
+lotics app query run openInvoices --params '{"customer":"rec_..."}'  # the bound query's rows, as a screen gets them
 
 # Move one alias out of this app and into another of the same workspace — the
 # declaration (and a workflow's body) land in the target project, the target is