@lotics/cli 0.246.0 → 0.247.0

package/AGENTS.md

@@ -8,14 +8,13 @@ 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-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 docs model` · `lotics docs model/<section>` | How to write a `model.json` — the file a workspace is built from, and the apps planned over it. Carried inside this CLI at its own version, since it describes this CLI's plan checker, and paged like every doc: the first page is the working order and the section addresses. 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. 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. |
+| `lotics docs model` · `lotics docs model/<section>` | How to write a `model.json` — the file a workspace is built from: its tables, how a row of each is recognised (`records`), and the apps stated over them. Carried inside this CLI at its own version, since it describes this CLI's model checker, and paged like every doc: the first page is the working order and the section addresses. 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. 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; who can read a doc; 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 — for one, 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 model is `app.json` version 2, rendered by `@lotics/app-runtime`. |
 | [README.md](./README.md) | Install, auth, and worked examples. |
 
 ## Two surfaces, and the trap between them

package/README.md

@@ -31,8 +31,6 @@ 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.
@@ -70,8 +68,8 @@ selects each.
 
 ## Or describe your own workspace
 
-A `model.json` names the tables, fields, options, links, views, roles and first rows, and
-`lotics setup` builds them. **Start from a preset when one is your trade** — name it instead of
+A `model.json` names the tables, fields, options, links, views, roles and first rows, how a row
+of each table is recognised, and the apps over them; `lotics setup` builds the tables. **Start from a preset when one is your trade** — name it instead of
 restating it:
 
 ```json
@@ -347,20 +345,21 @@ lotics knowledge rm kdc_...                                   # archive
 ## Custom-code apps
 
 ```bash
-# SEE THE APP BEFORE IT EXISTS. The plan is bound against the workspace the model
-# WOULD become and every read is answered from the model's own `rows`, so there is
-# 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 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.
+# SEE THE APP BEFORE IT EXISTS. The model's app is compiled against the workspace the
+# model WOULD become and every read is answered from the model's own `rows` (a few
+# synthesized for an entity that states none), so there is 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: the register, the record in
+# its door, the add. Exits 1 on any finding and prints what each phase cost. 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 model on every run.
 lotics app preview model.json#sales_desk
 lotics app preview model.json#sales_desk --shots ./shots --width 375
 
 # Scaffold / pull / deploy a Vite+React+TS app project
 lotics app create "Sales Desk"            # scaffold + deploy v1
+lotics app create "Sales Desk" --from model.json#sales_desk   # the model's app, as app.json
 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/*)