@lotics/cli 0.284.2 → 0.285.0

package/docs/building_an_app.md

@@ -6,8 +6,7 @@ reach for the area doc (`lotics docs`) whenever you need the detail.
 
 **The live app is the only edit surface.** Every change to an app — applying a model, deploying a
 build, setting one query or workflow — mints a new version of it, and rolling back to an earlier
-version is the undo. Nothing about an app lives in a local directory the platform reads back, so
-there is no project to keep in sync and no deploy to find out whether something works.
+version is the undo. Nothing about an app lives in a local directory the platform reads back.
 
 **Rolling back restores the app, not the data.** A table change the model made, and every row a
 workflow wrote while you tried it, stay where they are. Try a write on a throwaway record.
@@ -115,6 +114,7 @@ cd <dir>
 # edit src/App.tsx — node_modules/@lotics/app-sdk/AGENTS.md is the reference
 npm run typecheck && npm run lint && npm test
 lotics app deploy -m "<what changed>"   # build, upload, a new version live
+lotics app pull <app_id>                # the live version's source, on a machine without the project or after another deploy
 ```
 
 What the app reads and writes is bound on the app, never in the project: `lotics run

package/docs/cli_reference.md

@@ -43,7 +43,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** — the Library's list, `list_knowledge`, and the corpus `grep_knowledge` searches — while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as "everything". |
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
 | `lotics setup <model.json> [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then applies the model to its workspace, then prints the one-time sign-in link. **When that email already has an account it hands over to the `lotics auth login` flow** — it prints the sign-in page to open and the code it must show, and **exits 1 having created nothing**; the person presses Confirm and runs the same command again, which collects the key and carries on into the model. (`--wait` holds the terminal through the Confirm instead, finishing in one command.) The re-run is not refused for naming an `--email` it is now signed in as — that address IS the account it holds, not a second one. The file is a workspace MODEL, and it is read and checked before an account is created — the design decisions an apply would refuse it for too (`lotics docs design`), since a new workspace holds no rows to change them — because a file with a typo in it must not leave an organization behind. Then it is `lotics model apply` run on the new workspace: its tables, rows and apps; the sign-in link lands on its app when it has one, else on the workspace's app list. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently writes into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` applies the model to the account you already have. A path positional after the file is accepted and IGNORED with a warning — `setup` writes nothing to disk — so a prompt that passes one still runs. **`--json` prints one object on stdout and nothing else** — what `lotics model apply --json` does (`tables`; `apps`, each with `alias`, `app_id`, `version_id`, `origin`, `address` and `findings`; and `findings`) plus `organization_id`, `workspace_id` and `signin_url`, and a `warnings` array carrying everything the prose form would have said out of band, such as a sign-in link that could not be minted. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. Reachable with no install: `npx -y @lotics/cli setup …`. |
-| `lotics model apply <model.json> [--app <alias> ...] [--plan] [--json]` | **The model, applied to this workspace, through the `apply_model` tool.** The file is read and checked against the model's own rules with the validator the server runs, every problem in one run, before anything is uploaded. **The apply refuses an app leaving out a treatment its rows call for** (`lotics docs design`) — judged by the server beside the workspace's rows, before it writes anything — until the app adopts it or states why not under the `declines` key the refusal names; the refusal carries each refused app's patch adopting its decisions, to merge in the order printed. Documents a row attaches by a path beside the file are uploaded first and the rows sent with their `fil_` ids; a path this workspace already recorded keeps its id, so a re-apply uploads nothing twice. **Where the file was pulled (`-o`) or applied in this workspace before, only what it changed since is sent**, as a `patch`: what changed in the workspace since and the file does not touch stays. What the file takes out is sent as a removal: it goes where an apply rebuilds it (an app's acts and columns, a write rule) and is refused, naming the tool that deletes it, where an apply never deletes it (a table, a field, an option, an app). A file that reorders items named by their `alias` sends the whole model, said on stderr. The copy each change is read against is kept per workspace and file under `~/.lotics/model_bases`: an apply narrowed by `--app` leaves in it the other apps as they were, so the next apply sends their edits again, and an apply that fails — refused, or cut off — leaves none, so the next sends the whole model. Then the tool adopts or creates every table (the table this workspace bound the entity to, else an existing table of the same label, is ADOPTED and given the fields, options and views it lacks; no stored value changes), writes first rows only where every bound table is empty, and mints a new version of each app the model declares — `--app` (repeatable, comma-separated) narrows which apps, while the tables are applied whole. Prints one line per app — alias, `app_id`, `created`/`updated` with the version minted or `unchanged`, and the address it is served at — then the model's notes once, as the server states them. **`--plan` writes nothing and uploads nothing**: it prints what the apply would do to the tables (what it would create, what it leaves as the workspace has it, what the two disagree about), which apps it would create or update, and what it would refuse an app for — the decisions among its findings, read beside the workspace's rows, with each refused app's patch — exiting 1 when it would refuse one; workflow bodies are checked only at apply, since they name fields a plan has not created. **A rollback restores an app's earlier version** (`lotics run rollback_app`); table changes and data writes stay. Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, tables, apps, findings}` on stdout (with `--plan`, each table and app is what the apply would do, an app the patches change carrying its body as they leave it as `draft`, and `designs` each refused app's patch in merge order), or `{ok: false, findings}` when the file does not check. |
+| `lotics model apply <model.json> [--app <alias> ...] [--plan] [--json]` | **The model, applied to this workspace, through the `apply_model` tool.** The file is read and checked against the model's own rules with the validator the server runs, every problem in one run, before anything is uploaded. **The apply refuses an app leaving out a treatment its rows call for** (`lotics docs design`) — judged by the server beside the workspace's rows, before it writes anything — until the app adopts it or states why not under the `declines` key the refusal names; the refusal carries each refused app's patch adopting its decisions, to merge in the order printed. Documents a row attaches by a path beside the file are uploaded first and the rows sent with their `fil_` ids; a path this workspace already recorded keeps its id, so a re-apply uploads nothing twice. **Where the file was pulled (`-o`) or applied in this workspace before, only what it changed since is sent**, as a `patch`: what changed in the workspace since and the file does not touch stays. What the file takes out is sent as a removal: it goes where an apply rebuilds it (an app's acts and columns, a write rule) and is refused, naming the tool that deletes it, where an apply never deletes it (a table, a field, an option, an app). A file that reorders items named by their `alias`, or states a `null` a patch would read as a removal, sends the whole model, said on stderr. The copy each change is read against is kept per workspace and file under `~/.lotics/model_bases`: an apply narrowed by `--app` leaves in it the other apps as they were, so the next apply sends their edits again, and an apply that fails — refused, or cut off — leaves none, so the next sends the whole model. Then the tool adopts or creates every table (the table this workspace bound the entity to, else an existing table of the same label, is ADOPTED and given the fields, options and views it lacks; no stored value changes), writes first rows only where every bound table is empty, and mints a new version of each app the model declares — `--app` (repeatable, comma-separated) narrows which apps, while the tables are applied whole. Prints one line per app — alias, `app_id`, `created`/`updated` with the version minted or `unchanged`, and the address it is served at — then the model's notes once, as the server states them. **`--plan` writes nothing and uploads nothing**: it prints what the apply would do to the tables (what it would create, what it leaves as the workspace has it, what the two disagree about), which apps it would create or update, and what it would refuse an app for — the decisions among its findings, read beside the workspace's rows, with each refused app's patch — exiting 1 when it would refuse one; workflow bodies are checked only at apply, since they name fields a plan has not created. **A rollback restores an app's earlier version** (`lotics run rollback_app`); table changes and data writes stay. Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, tables, apps, findings}` on stdout (with `--plan`, each table and app is what the apply would do, an app the patches change carrying its body as they leave it as `draft`, and `designs` each refused app's patch in merge order), or `{ok: false, findings}` when the file does not check. |
 | `lotics model pull [-o <model.json>]` | **This workspace's model, rebuilt from what owns each part** — the tables, fields, options, templates and roles the workspace holds, how rows are recognised, and each app's body from its current version — through the `get_model` tool, as the file `model apply` reads: to stdout, or to the file `-o` names. What the workspace holds that a model cannot state is printed on stderr, never written into the file. Applying what it wrote changes nothing. With `-o`, what it wrote is the copy the next `model apply` of that file reads its changes against. |
 | `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`), scaffolds a Vite + React + TypeScript project into `[path]` (default `./<name>`, refused when not empty — before the app row exists) that depends on `@lotics/app-sdk` alone and draws with plain React, and installs it (`npm install --ignore-scripts`), then writes the declarations of the app's live bindings (`get_app_types`) into `.lotics/`, which the project's `tsconfig.json` includes. `package.json#lotics` names the app and its workspace, which is how `app deploy` in that directory finds both. The app has no version until the first `lotics app deploy`. `--custom` is required: an app the runtime draws from a model is made by `lotics model apply`. The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the project. |
 | `lotics app pull [app_id] [path]` | **A custom-code app's live source, as a project ready to deploy on it.** The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** — but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`get_app_types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). A JSON app has no source tree: the server's refusal names `get_model`, and `lotics model pull` is its pull. |

package/docs/design.md

@@ -64,6 +64,7 @@ then check again. A note refuses nothing.
 | Papers to read | an act's `intake` with `fills` | `model/acts` |
 | Calls and visits | an act's `record` | `model/acts` |
 | Documents covering lines | a rows block with `under` | `model/blocks` |
+| Rows on file a record takes in | a rows block with `pick` | `model/blocks` |
 | One owner's question across jobs | a dashboard app | `model/dashboards` |
 
 ### Faces and pictures
@@ -167,7 +168,9 @@ default record: every field a person writes.
 
 Rows that each belong to one row of another entity (a one-row link to it) are drawn under that row: a `rows` block on
 its record, a `timeline` where they are a log, an `agenda` where they are planned on a day and within it, a roster of
-them, or lanes of them by that link. Which children a record lists is the author's — one of them at least.
+them, or lanes of them by that link. Which children a record lists is the author's — one of them at least. Rows on
+file before the row they come to belong to — a job's cost lines before the supplier bill over them — are picked into
+it: a rows block with `pick`, often with `create: false` and `remove: false`.
 
 ### Papers
 
@@ -188,12 +191,16 @@ placeholder, the reader ticking which to make. A template no act names is made b
 
 A paper the business is brought and reads is an act's `intake`: the press takes the papers, an agent reads
 them, and each is filed as the line of its kind in the child the record `expect`s, while `fills` writes what
-they state into the record's fields — shown before it is saved. Worked: `examples/case`.
+they state into the record's fields — a single link as a row the agent finds among those the app reads of its
+entity — shown before it is saved. Worked: `examples/case`.
 
 #### Under
 
 A rows block with `under`: the documents that cover lines (an invoice over its fee lines) stand as headings
-over the lines they cover, and a line no document covers offers to make one.
+over the lines they cover, and a line no document covers offers to make one. A document entered as it arrives,
+over lines already on file (a supplier bill), picks them from its own record instead: a rows block with `pick`.
+Choose one per document: a document a make covers lines by is never also picked into, since a pick does not check
+what the make does.
 
 ### Calls
 

package/docs/document_templates.md

@@ -130,7 +130,7 @@ lotics download <file_id> -o ./out/
   `table`/`list`/loop variables. `filename` excludes the extension (the type sets it).
 - `generate_document` renders the template's own type and returns a generated file object; take
   its `file_id` onward.
-- In a workflow, a **generate step** calls the same tools and hands the `file_id` to the next
+- In a workflow, a **generate step** calls the same tool and hands the `file_id` to the next
   step (attach to a record, send as an attachment, etc.).
 
 ## Discovering and managing templates

package/docs/field_values.md

@@ -27,6 +27,8 @@ one value.
 - A single-select is a ONE-element array; a bare `"opt_…"` is accepted and wrapped. A single
   `select_member` takes a bare `"mbr_…"` the same way.
 - `select_record_link` and `files` take an array only.
+- A `files` id the write adds must name a live file of this workspace, or the whole write is refused;
+  an id that cell already holds stays, though its file was archived since.
 - Two options on a single-select, or two members on a single `select_member`, are refused.
 - `update_records`' `add_to`, `remove_from` and `replace` take arrays of the same items: `opt_` keys
   for a select, member ids for a `select_member`, record ids for a `select_record_link`, file ids for

package/docs/migration.md

@@ -20,7 +20,7 @@ templates and roles are the workspace's own.
 | `lotics app regenerate` | change the model file, then `lotics model apply` |
 | `lotics scaffold diff` | `lotics model apply <model.json> --plan` — what the apply would change, writing nothing |
 | `lotics scaffold export` | `lotics model pull [-o <model.json>]` — the workspace's model, rebuilt from what owns each part |
-| `lotics app pull`, `app codegen`, `app check`, `app dev`, `app preview` | nothing local: read an app with `lotics run get_app`, and change it through its tools |
+| `lotics app codegen`, `app check`, `app dev`, `app preview` | nothing local: read an app with `lotics run get_app`, and change it through its tools |
 | `lotics app workflow set` / `app query set` / `app agent set` | `lotics run set_app_workflow` / `set_app_queries` / `set_app_agent` — each mints a version |
 | `lotics app versions` + a redeploy of an old tree | `lotics run query_app_versions`, then `lotics run rollback_app` — restores the app's earlier version; table changes and data writes stay |
 | `lotics app rename`, `app subdomain`, `package.json#lotics.capabilities` | `lotics run update_app` (`name`, `public_subdomain`, `capabilities`) |

package/package.json

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