@lotics/cli 0.181.0 → 0.181.1

package/AGENTS.md

@@ -10,6 +10,7 @@ conventions are, and where the traps are.
 | `lotics docs` · `lotics docs <area>` | 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. |
 | [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/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. |
 | [README.md](./README.md) | Install, auth, and worked examples. |

package/dist/src/cli.js

@@ -45711,7 +45711,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.181.0";
+var VERSION = "0.181.1";
 
 // src/timezone.ts
 function machineTimezone() {

package/docs/building_an_app.md

@@ -57,6 +57,31 @@ images do not exist yet, generate them out of band and `lotics file upload` + `u
 on — and keep one style across the whole set, because a catalogue whose shots disagree about
 lighting and background reads worse than one with no pictures at all.
 
+**One fact, one column — and check before you add one.** Read the table's existing fields before
+adding any, because the fact is often already there in another shape: a place written as text
+beside a `select_record_link` to the place record, a status word beside the select that decides it,
+a total beside the formula that computes it. Two columns for one fact never stay equal — some
+writer sets only one of them, and nothing reports the divergence because both rows look correct
+alone. Prefer the link, the select, or the formula, and compose the text when you READ. Renaming or
+re-pointing the existing field beats adding a second one; a field is addressed by key, so a rename
+breaks nothing. Superseding a field means deleting it, not leaving it beside its replacement.
+
+**Match on ids and option keys, never on rendered text.** A reader that compares display strings
+treats "Acme" and "Acme Ltd" as different records, and a value spelled `Net 30` as different from
+the option labelled `Net 30 days` — so an import creates a duplicate every time it runs, silently,
+because each row looks right on its own. Resolve a name to its `rec_…` or `opt_…` once, at the boundary, and
+compare those. Treat an unresolved name as UNKNOWN, never as a wildcard.
+
+**How the tables RELATE is `lotics docs data_model`** — one entity per table and the 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, a declared natural key, and why
+derived depth costs more than row count. Read it before designing a schema; those decisions outlive
+any one app, and most of them are unfixable once a second screen depends on the copy.
+
+**Empty is not the same as redundant.** A field nothing fills may still be the only home for a real
+distinction, and a column whose values are all `1` may be the volume band nobody has needed yet.
+Read what a field MEANS before you remove it; "unused in this data" is not evidence it is wrong.
+
 ## 4 — Typed field access
 
 ```

package/docs/data_model.md

@@ -0,0 +1,92 @@
+# The data model — how tables relate
+
+The decisions here outlive any one app, and most become expensive the moment a second screen depends
+on them. They are separate from `lotics docs building_an_app` on purpose: **every workspace starts
+with tables and many never get a custom app**, so schema design is not a chapter of app building.
+
+`ONE FACT, ONE COLUMN` — the rules governing a single table's own columns — is stated at the tools
+that add a field, `create_table` and `update_table`, where you meet it while deciding. This doc is
+the other half: how tables relate to each other.
+
+Everything below shares one signature. **Both sides read correctly on their own**, so nothing reports
+the problem — no error, no empty column, no failing query. Each is found by looking for it.
+
+## One entity, one table — and the test is measurable
+
+Variation belongs in a column — a multi-select role, a kind, a stage — not in a second table. Two
+tables for one kind of thing give the same real-world entity two rows, two ids and two halves of its
+history, and each screen shows whichever half it happens to link to.
+
+Split tables are often right. A supplier book beside a customer book is a normal shape, and merging
+on suspicion is a large repoint bought for nothing. So do not argue it in the abstract:
+
+> **List both tables' names and look for one that appears in both.**
+
+None means the split is holding. One means it has broken — the usual cause is a party you begin to
+invoice as well as buy from — and the fix is to merge before a second screen depends on the copy.
+
+Worth writing as a test rather than a note, because a note about a condition nobody re-checks goes
+stale in silence.
+
+## One vocabulary wherever values are COPIED between tables
+
+Two `select` fields for one concept carry DIFFERENT option keys even when their labels match — keys
+are minted per field. So anything moving a value between them needs a hand-written key map.
+
+That map is code. Put it in one named module with a test; written inline at the copy it is invisible,
+untested, and silently wrong the first time somebody renames an option, because a rename leaves the
+key intact and the map still compiling. Prefer a link to a shared reference table where the set is
+open or growing; keep a map only for a small closed set.
+
+Where one side genuinely holds MORE values than the other, that is not drift — it is the model
+telling the truth. The wider side must **refuse** what the narrower one cannot express rather than
+quietly picking the nearest value.
+
+## A copy boundary accounts for EVERY source field
+
+Each field on the source gets a column on the destination, a deliberate drop with the reason written
+down, or a refusal.
+
+A field with nowhere to land is data destroyed at the boundary, and it is invisible afterwards: the
+destination is not empty and not obviously wrong — just a number that no longer agrees with where it
+came from.
+
+## Provenance is a LINK, not a flag and not a copy
+
+A row created BY another row carries a link to it.
+
+That link is what makes "is this the estimate or the actual", "where did this come from" and "have we
+already imported this" answerable at all. A boolean records that something was true once; a link
+stays true, survives a rename, and lets the next write UPDATE the original instead of adding a second
+row beside it.
+
+## Say what makes two rows the SAME row
+
+Declare the natural key in the table's description.
+
+Anything that imports, reconciles or de-duplicates has to decide identity, and with no declared key
+it falls back to comparing displayed text — which is how one company arrives three times under three
+spellings. Name the key: a reference number, a tax id, a link plus a period. Then match on `rec_…`
+and `opt_…`, never on rendered labels.
+
+## Keep derived chains shallow
+
+Formulas and rollups are computed and STORED when a row is written, and one that reads another
+recomputes with it. A rollup over a formula over a formula is paid three times on every touch, and
+again for every row upstream of it.
+
+**Depth costs more than row count.** This is the optimisation lever that actually exists here; row
+scanning is the platform's problem, chain depth is yours.
+
+## Changing a money formula on a live table
+
+Formula edits recompute every row, so the only honest proof that one changed nothing it should not is
+the numbers themselves:
+
+1. Snapshot the affected totals to a file.
+2. Make the change.
+3. Diff. Identical is the pass.
+
+And when a formula gains a new field, **test that the value IS the one you want, never that it
+differs from it** — an empty cell reads as `""`, which differs from every option key, so the inverted
+spelling silently zeroes every row written before the field existed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.181.0",
+  "version": "0.181.1",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {