@lotics/cli 0.205.1 → 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
@@ -95,12 +96,15 @@ response there is *not* evidence the subcommand is absent. To find out whether s
   findings. An unrecognized status exits 0 — the list is an allowlist of failure, so a status added
   later never turns a working script red — and a parked run (`awaiting_input`) is not a failure.
 - **An app that PUBLISHES an API turns every later manifest write into a release.** `lotics app api
-  publish` snapshots what the app's queries and workflows promise to callers outside it — a
+  publish` snapshots what the app's queries, workflows and agents promise to callers outside it — a
   customer's own site or server, which nobody here can redeploy. From then on an additive change
   re-snapshots silently and a breaking one is REFUSED, naming each change;
-  `--acknowledge-breaking-api` (on `app deploy`, `app query set`, `app workflow set`, `app upgrade`)
-  is the answer that carries it out and snapshots the break as a new contract version. An app that
-  publishes nothing is untouched by any of it.
+  `--acknowledge-breaking-api` (on `app deploy`, `app query set`, `app workflow set`,
+  `app agent set`, `app upgrade`) is the answer that carries it out and snapshots the break as a new
+  contract version. An app that publishes nothing is untouched by any of it.
+- **Exposure is per app, all or nothing** — a public share or a key reaches every alias an app
+  declares, so what outsiders may call is a second app over the same tables, scaffolded with
+  `lotics app create "<name>" --api` ([docs/building_an_app.md](./docs/building_an_app.md) § 9).
 - **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the
   records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs
   those deletes (records only — never files, integrations or notifications). Neither is a rollback.

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`
@@ -341,6 +347,8 @@ lotics knowledge rm kdc_...                                   # archive
 ```bash
 # Scaffold / pull / deploy a Vite+React+TS app project
 lotics app create "Sales Desk"            # scaffold + deploy v1
+lotics app create "Orders API" --api       # no screens: its declarations are the whole surface,
+                                           # so nothing is built and nothing is deployed
 lotics app pull app_...                    # bootstrap an existing app locally (incl. .lotics/*)
 lotics app deploy -m "Add quote drawer"    # typecheck + build + upload a new version
 lotics app versions                        # deploy history: version, when, who, -m message (* = live)
@@ -353,13 +361,14 @@ lotics app versions app_...                # ...for any app, without pulling it
 lotics app upgrade                         # the app this directory's manifest names
 lotics app upgrade app_...                 # ...for any app, without pulling it first
 
-# The app's API: what its declared queries and workflows promise to a caller
-# OUTSIDE the app — a customer's own site or server. Publishing snapshots that
-# promise as a numbered contract; from then on a manifest write that would break
-# it is refused and every breaking change is named, unless the write carries
+# The app's API: what its declared queries, workflows and agents promise to a
+# caller OUTSIDE the app — a customer's own site or server. Publishing snapshots
+# that promise as a numbered contract; from then on a manifest write that would
+# break it is refused and every breaking change is named, unless the write carries
 # --acknowledge-breaking-api (app deploy / app query set / app workflow set /
-# app upgrade). A query that does not name the columns it returns is refused at
-# publish: those field names are the table's, not the app's to promise.
+# app agent set / app upgrade). A query that does not name the columns it returns
+# is refused at publish: those field names are the table's, not the app's to
+# promise.
 lotics app api publish                     # snapshot the contract; prints the version + warnings
 lotics app api status                      # is one published, and which version callers hold
 lotics app api spec -o api.openapi.json    # the OpenAPI 3.1 document, for the consumer's generator
@@ -372,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.
@@ -410,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.