@lotics/cli 0.205.2 → 0.206.0

package/AGENTS.md

@@ -14,6 +14,7 @@ conventions are, and where the traps are.
 | [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. |
 | [README.md](./README.md) | Install, auth, and worked examples. |
 
 ## Two surfaces, and the trap between them

package/README.md

@@ -34,6 +34,8 @@ package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
 - [`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.
+- [`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 on disk no longer matches what the CLI writes.
 - [`docs/knowledge_docs.md`](docs/knowledge_docs.md) — the AI's rulebook layer: authoring the
   workspace facts an agent can't guess, the access-vs-activation model, and the
   catalog-then-stage retrieval model agents use to pull only the lines they need.
@@ -90,6 +92,10 @@ lotics setup model.json --email you@company.com
 It creates no apps of its own: build one in the workspace afterwards
 (`lotics docs building_an_app`), or name a published package in the file's `apply` list and it is
 copied in — bound onto the tables the model just made — as part of the same run.
+For a model that declares apps, `lotics workspace build model.json` is the whole path in one
+command — check, apply where the workspace differs, then create or regenerate each app beside the
+model file and check it, deploying each under `--deploy`. An app that conflicts or checks red is
+named and the rest still run; `--dry-run` writes nothing anywhere.
 `setup` refuses a table name your workspace already has; `lotics scaffold apply model.json` is the
 additive verb — it adopts that table, adds what the model declares beyond it, and deletes nothing.
 Because it never renames, the file and the workspace drift: `lotics scaffold diff model.json`
@@ -375,6 +381,15 @@ 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
+# `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
+
 # 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
 # the code calls that nothing bound, undeclared capabilities, query drift. Exits 1 on what a deploy refuses, so CI can gate on it.
@@ -413,6 +428,14 @@ lotics app workflow set issueInvoice        # push the edited src/workflows/issu
 # authoritative, so the next `app deploy` re-syncs it — keep the manifest current.
 lotics app query set openInvoices           # push package.json#lotics.queries.openInvoices
 
+# 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
+# bound to its OWN row, and the source is unbound and undeclared here. No release
+# either side. Run it in the source project; refused while anything here still
+# calls the alias, unless you say --even-if-invoked.
+lotics app query move openInvoices --to ../ke-toan
+lotics app workflow move issueInvoice --to ../ke-toan
+
 # Run a bound app agent end-to-end (no deployed UI needed — app row + declaration
 # + member auth). Streams progress to stderr; reports the SETTLED run (structured
 # output / final text) to stdout; exits 0 only when the run completed.