@lotics/cli 0.315.18 → 0.316.0

package/docs/app_bindings.md

@@ -1,22 +1,21 @@
-# App bindings — the queries, workflows and agents an app calls
+# App bindings — the queries and workflows an app calls
 
-A custom-code app reaches workspace data through three kinds of binding, each declared on the app
+A custom-code app reaches workspace data through two kinds of binding, each declared on the app
 under an alias — a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):
 
 | Binding | Declared with | The app calls it with | An agent calls it with |
 |---|---|---|---|
 | Query | `set_app_queries` (CLI, chat) | `useQuery("<alias>", params?)` | `run_app_query` |
 | Workflow | `set_app_workflow` | `useWorkflow("<alias>")({ ...inputs })` | `run_app_workflow` |
-| Agent | `set_app_agent` (CLI, chat) | `useAgentRun("<alias>")({ ...inputs })` | — |
 
 Each runs under the app's authority (`{ type: "app", app_id }`), the app owner's reach — never the
 calling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next
-call uses it. `get_app_capabilities` lists an app's aliases with their params and inputs.
+call uses it. `get_app` lists an app's aliases with their params and inputs.
 
 Each reader returns a fingerprint of what it read — `get_app_workflow`'s `body_sha`, and on the CLI and in chat
-`get_app_query`'s `sha` and `get_app_agent`'s `instructions_sha` — and a write built on that read passes it back:
+`get_app_query`'s `sha` — and a write built on that read passes it back:
 `set_app_queries`' `expected_shas` (alias → `sha`), `set_app_workflow`'s `expected_body_sha`,
-`set_app_agent`'s `expected_instructions_sha`, `remove_app_binding`'s `expected_sha`. The write is
+`remove_app_binding`'s `expected_sha`. The write is
 refused, and writes nothing, when the binding changed since; omit it for an unconditional write.
 
 ## Queries
@@ -66,9 +65,15 @@ Filters (`from_table.filter`, `filter.predicate`, an aggregate's `filter`) are t
 `filters` reference — over the input's columns, taking `{{params.x}}` as values. `search` matches
 every text-bearing field of the row, accent- and case-insensitive.
 
-A `project` column is a field key as a bare string (output name and type come from the field), or
+A query names a table's fields by the alias its document states, wherever a node reads the table directly (a
+`from_table`'s filter and sort, the `project`, `filter`, `group`, `window`, `unnest` or `unpivot` over it) and a select
+condition's values by the option's alias. A column a `project` writes answers under the alias it was written with; every
+name past a `project` or an aggregate is that column's own. A `union` whose arms read one alias from different tables
+projects each arm's columns under one name first. The query is stored by key and read back by alias.
+
+A `project` column is a field's alias as a bare string (output name and type come from the field), or
 `{ output?, type?, source, writable_target?, limit? }` to rename, compute or bound one. A computed
-`source` is a field key, `{ literal }`, `{ eq: [a, b] }`, `{ neq: [a, b] }`, `{ isEmpty }`,
+`source` is a field's alias, `{ literal }`, `{ eq: [a, b] }`, `{ neq: [a, b] }`, `{ isEmpty }`,
 `{ isNotEmpty }`, `{ coalesce: [...] }`, `{ concat: [...] }`, `{ record_id: true }`,
 `{ link: { source, field } }` (a field of the first linked record),
 `{ link_agg: { source, field, operation } }` (`sum`, `avg`, `min`, `max`, `count`, `string_agg`
@@ -92,7 +97,7 @@ name → `{ type, required?, description?, …per type }`. An entry is required
 |---|---|
 | `text`, `number`, `boolean`, `date`, `datetime`, `email` | — |
 | `record_link` | `table_id`; `multi?`; `max?` (with `multi`, the most ids one call carries) |
-| `select` | exactly one of `options: [{ label, value }]` or `field: "fld_…"` (a select field whose CURRENT options back it); `multi?` |
+| `select` | exactly one of `options: [{ label, value }]` or `field: "<table id>.<alias>"` (a select field whose CURRENT options back it); `multi?` |
 | `date_range` | `include_time?` |
 | `member` | `multi?`; `group?` (a member group the value must belong to) |
 | `file` | `multi?` — an uploaded `fil_…` id, for a files field |
@@ -113,7 +118,7 @@ name → `{ type, required?, description?, …per type }`, every entry present u
 |---|---|
 | `text`, `number`, `boolean`, `date`, `datetime`, `email`, `json` | — |
 | `record_link` | `table_id`, `multi?` |
-| `select` | exactly one of `options: [{ label, value }]` or `field: "fld_…"`; `multi?` |
+| `select` | exactly one of `options: [{ label, value }]` or `field: "<table id>.<alias>"`; `multi?` |
 | `object` | `fields` |
 | `array` | `items` |
 
@@ -124,12 +129,13 @@ keeps the type tracking the live field.
 ## Workflows
 
 `set_app_workflow` binds a workflow body to an alias: `{ app_id, alias, source, inputs?, outputs?,
-name?, description? }`. On an app built from a model, the alias is one the model names — an act's own
-`workflow`, or an entry of the app's `workflows`, which states `inputs`, `outputs` and `description`:
-a call stating any of them for it is refused, and outputs the entry leaves out are derived from the
-body. An alias the model names nowhere is archived by the next apply. An entry of `workflows` runs
-only for someone who holds the app: on an app shared by a public link, a visitor's call of it is
-refused as an alias the app does not have.
+name?, description? }`. On an app written as a tree the alias is one the tree names — a Workflow node's
+`key` or an Act's `workflow` — and the node states `inputs`, `outputs` and `description`
+(`model/workflow-node`, whose value shapes differ from the **Inputs** below): a call stating any of
+them for it is refused, and outputs the node leaves out are derived from the body. An alias the tree
+names nowhere is archived by the next `set_app`. A Workflow node runs only for someone who holds the
+app: on an app shared by a public link, a visitor's call of it is refused as an alias the app does
+not have. This page's `inputs` and `outputs` are for a custom-code app.
 
 - `source` is the body with no `on({...})` trigger — the app is the trigger. It reads each declared
   input as `trigger.app_workflow.inputs.<name>`; no record is in scope, so it reads each one by id
@@ -145,50 +151,6 @@ refused as an alias the app does not have.
   and writes nothing. A call naming a live alias replaces its body in place, keeping its run history.
 - A call whose payload does not match `inputs` is refused before the body runs.
 
-`get_app_workflow` reads the body back; `dry_run_workflow` with `trigger_type: "app_workflow"`
-runs it against sample inputs before binding; on the CLI and in chat, `remove_app_binding` with
+`get_app_workflow` reads the body back; `set_app_workflow` with `verify_only` and `record_id` or `preview_inputs`
+rehearses a draft before binding; on the CLI and in chat, `remove_app_binding` with
 `kind: "workflow"` unbinds it.
-
-## Agents
-
-On the CLI and in chat, `set_app_agent` binds a streaming tool-loop agent to an alias. A run streams its work to the app,
-returns a typed result and keeps a run history per session.
-
-The declaration:
-
-- `instructions` — the task, every run. A new alias needs it.
-- `tool_names` — the tools it may call, from these and no other: `analyze_pdf_template`,
-  `code_edit_file`, `code_exec`, `code_read_file`, `code_write_file`, `excel_create_file`,
-  `excel_find_cells`, `excel_format_range`, `excel_get_range`, `excel_update_range`,
-  `generate_bank_qr_code`, `generate_document`, `generate_image`, `generate_qr_code`, `get_template`,
-  `grep_knowledge`, `list_banks`, `list_knowledge`, `lookup_business`, `query_templates`,
-  `read_knowledge`, `run_app_query`, `run_app_workflow`, `validate_excel_template`,
-  `vietcombank_convert_currency`, `view_files`, `word_create_document`, `word_find_text`,
-  `word_get_content`, `word_get_table_data`, `word_insert_conditional`, `word_insert_loop`,
-  `word_replace_text`. `[]` is a reasoning-only agent. A few fields of a document read well through
-  the `excel_*` / `word_*` tools; a cross-check, reconciliation or transform a decision rests on
-  belongs in the code tools.
-- `query_aliases` / `workflow_aliases` — the app's own queries and workflows it may call through
-  `run_app_query` / `run_app_workflow`. They are its whole reach over records: no agent tool takes a
-  `table_id`, so a read is bounded by the query's tables, rows and columns, and a write goes through
-  the app's own workflow.
-- `knowledge_doc_ids` — knowledge docs it may read with `grep_knowledge` / `read_knowledge`
-  (declare them in `tool_names`). Each must be one the app owner and you can use. Nothing is
-  inlined and size does not matter. The list is the agent's whole reach — `list_knowledge` finds no
-  doc outside it — so name a doc's id in `instructions` to point it there. `code_exec` computes
-  across a corpus (counting, cross-referencing); reading needs only the knowledge tools.
-- `model_tier` — `haiku`, `sonnet` or `opus`. Omitted, the run follows the platform's default tier
-  and moves with new models; pin one only as a tested choice, and never `haiku`, a utility tier.
-- `effort_level` — `low`, `medium`, `high`, `xhigh` or `max`, one the pinned tier supports; it
-  needs `model_tier`.
-- `prefix_cache_ttl` — `5m` (the default) or `1h`. `1h` doubles the cache write price and pays only
-  when runs land 5 to 60 minutes apart, as a scheduled sweep does.
-- `inputs` — the per-run payload (see **Inputs**); omitted, the payload is untyped.
-- `outputs` — the structured result (see **Outputs**), checked before the run is saved and typed
-  as `run.output` in the app; omitted, the result is the final message.
-- `writes` — where the outputs land: `{ table_id, row, fields }`, `row` naming a single
-  `record_link` input to `table_id` and `fields` mapping each output name to a field key of that
-  table. A result that validates is written to that row under the app's authority.
-
-Send only what you change: an omitted field keeps its stored value, `null` clears an optional one.
-On the CLI and in chat, `get_app_agent` reads one back; `remove_app_binding` with `kind: "agent"` deletes it.

package/docs/building_an_app.md

@@ -1,33 +1,34 @@
 # Building an app, end to end
 
-The other references here describe **contracts** — what a model may state, what a tool takes. This
+The other references here describe **grammars** — what a table document or an app tree may state, what a tool takes. This
 one describes the **sequence**: the order the steps go in, and why. Read it once for the shape, then
 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.
+**The live app is the only edit surface.** Every change to an app — applying a tree, deploying a
+build, setting one query or workflow — mints a new version of it. To go back, apply the earlier tree
+again (or deploy the earlier source). 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.
+**Going back restores the app, not the data.** A table change, and every row a workflow wrote while
+you tried it, stay where they are. Try a write on a throwaway record.
 
 ---
 
 ## 1 — Two kinds of app
 
-- **An app stated in a model** — the default, and the right one for almost every job. `model.json`
-  says how a row of each entity is recognised (`records`) and, in `apps`, one working register over
-  one entity and the record its rows open, with the logs that stand beside it (`logs`, read by the organization's own members alone): its columns and filters, its sections in the order its work
-  reaches them, its acts and the checks that guard them (`lotics docs model/register`,
-  `model/record-page`, `model/acts`, `model/checks`). The platform
+- **An app stated as a tree** — the default, and the right one for almost every job. The tree (a
+  JSON file, one per app) is a List of one table, whose rows are recognised by the
+  table's own `records`, and the Record its rows open, with the logs that stand beside it (further Lists at the root, which a change may add at any time, read by the organization's own members alone): its columns and filters, its Sections in the order its work
+  reaches them, its Acts and the Checks that guard them (`lotics docs model/app-tree`,
+  `model/list-node`, `model/section-node`, `model/act-node`, `model/check-node`). The platform
   compiles each app and draws it with the runtime every such app shares, so how each piece looks is
-  the platform's, one way per concept, and no key changes it. Every write the app makes is a
-  generated workflow that re-checks on the server what the model states.
-- **A custom-code app** — React you write, for a surface the model's vocabulary cannot state. It
+  the platform's, one way per concept, and no prop changes it. Every write the app makes is a
+  generated workflow that re-checks on the server what the tables state.
+- **A custom-code app** — React you write, for a surface the tree's components cannot state. It
   reads and writes through `@lotics/app-sdk` (queries, workflows, files, AI) and draws with whatever
   React you choose.
 
-## 2 — Clarify what is being asked, before modelling it
+## 2 — Clarify what is being asked, before designing it
 
 **A metric name is not a definition.** "Revenue", "in stock", "active", "overdue" — each is a
 business rule the person asking owns, and the cost of guessing is a screen that is confidently
@@ -46,76 +47,93 @@ invisible in review: every later artifact is correct with respect to the wrong d
 
 ## 3 — The data model, before any app
 
-Get this wrong and nothing above it can be precise. Each entity is its own table with links into
+Get this wrong and nothing above it can be precise. Each kind of thing is its own table with links into
 the spine; attributes and evidence are fields on their owner. A single table with a `type` column
-standing in for three entities collapses the distinctions every later query needs.
+standing in for three kinds of thing collapses the distinctions every later query needs.
 
 **Verify real VALUES, never just that a field exists.** `lotics run query_records` a sample and
 look at fill rates — a field that is present and empty on 90% of rows will not support the screen
 you are about to design.
 
-**That includes imagery.** If the entity has a likeness — a product, a property, a vehicle, a
+**That includes imagery.** If the thing has a likeness — a product, a property, a vehicle, a
 person — its picture is the strongest identifier a register row can carry, and an empty image field
 is a data gap to fill before you design around it: `lotics file upload`, then `update_records`.
 
-**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 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. Prefer the link, the
-select, or the formula, and compose the text when you READ.
-
-**Match on ids and option keys, never on rendered text.** Resolve a name to its `rec_…` or `opt_…`
+**Match on ids and option aliases, never on rendered text.** Resolve a name to its `rec_…` or its option alias
 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`** — read it before designing a schema; those
-decisions outlive any one app.
+**How the tables RELATE, and one fact in one column, is `lotics docs data_model`** — read it before designing a
+schema; those decisions outlive any one app.
 
-**Empty is not the same as redundant.** A field nothing fills may still be the only home for a real
-distinction. Read what a field MEANS before you remove it.
+## 4 — An app stated as a tree
 
-## 4 — An app stated in a model
+Tables first, then apps. `set_tables` takes a list of table documents, one or many, and writes them all or
+none; `set_app` takes one app per call. Each creates when it is given no id and edits when it is given one.
 
 ```
-lotics docs model                       # how to write model.json, with a worked example
-lotics docs design                      # how to design each app: the method, a treatment per kind of row
-lotics model apply model.json           # check it, apply the tables, mint a version of every app
-lotics model apply model.json --app orders   # only the apps named; the tables are applied whole
-lotics model check model.json           # what the apply would change, writing nothing
-lotics model pull -o model.json         # the workspace's model, as the file apply reads
+lotics docs model                       # the keys of a table document and the app tree's components, with a worked example
+lotics docs design                      # the treatment per kind of row
+lotics run set_tables @tables.json      # one call, every table: {"tables": [...]}
+lotics run set_app @orders.call.json    # one app: {"body": <the App tree>} to create (add "dry_run": true to check)
+lotics app apply orders.app.json --check   # the same tool from a bare tree file: what would refuse it, writing nothing
+lotics app apply orders.app.json        # no app known: creates it; known: edits it to the file
+lotics app pull <app_id>                # the app's tree, as ./<name>.app.json
 ```
 
-`model apply` checks the whole file first — every problem in one run, before anything is uploaded
-or written. It then adopts or creates each table (the table this workspace bound it to, else one of the same
-label, is adopted and given what it lacks; no stored value changes), writes the first rows only where every bound
-table is empty, and mints one version per app, printing each app's id, the version minted
-(`unchanged` when there was nothing to mint) and its address. Applying the same file again mints nothing.
-A table change is not undone by rolling an app back, so `lotics model check` first says what the apply would
-create or change in the tables and which apps it would create, update or refuse — writing nothing.
-
-**An app leaving out a treatment its rows call for is refused** — readings over its rows, a record's
-sections, an act per status move, a picture where its rows hold photos (`lotics docs design`). Each
-refusal names the rule, and beside them comes each refused app's patch adopting its decisions: merge
-the patches into the file in the order given, or state why the app stays as it is under the
-`declines` key the refusal names (`lotics docs model/declines`), then apply again. `lotics model check` reads the
-decisions beside the workspace's rows, and with `--json` gives each app as the patches leave it, its
-`draft`.
-
-**The model changes after the app exists, and applying it again is how it lands.** Edit the file,
-apply it. An act whose write the model cannot say names its own `workflow`; that workflow's body is
+A new workspace is built in one order: one `set_tables` call with the tables, then every `set_app`
+call, then fixes. One call carries at most 50 tables, 200 first rows a table, and 2000 rows and 2000
+documents in all; a workspace of more tables is built in further calls, each naming the tables already made by
+their ids. The example files at `https://lotics.ai/presets/index.json` are read and their tables passed to
+`set_tables`.
+
+A table is a document: its `fields` are keyed by alias, and a link field names the table it
+points at by id, or by the `ref` of another table of the same call, and states `multi`. A
+two-way link states `pair` on one table, as `true` or as a free alias, and the partner is made on the other; a many-to-many link states both sides. A table is edited by an RFC 7396 merge patch of its document:
+what the patch leaves alone is left alone and `null` deletes. `dry_run` checks the call and writes
+nothing; a refusal lists everything wrong in it at once.
+
+The App node is the app: its `name`, `description`, `icon` and `color` are props of it, and no other input of
+`set_app` states them. It names the tables and templates it uses by their aliases (an entity is a table's alias, a `template` a template's alias);
+`set_app` fills the `tables` and `templates` maps by id from them and `get_app` shows aliases (`lotics docs model/app-node`). A call that creates
+is `{"body": <the App tree>}`; one that changes a part is `{"app_id": "app_…", "nodes": {"<address>": <patch>}}`,
+each address a node's path of keys (`get_app` prints every one), a patch a JSON merge patch of that node's props
+and `null` removing the node; the App's own props change through `body`. A call stating `base_version_id` — the
+version you read — is refused when the app has moved on. The old body grammar (`register`, `record`, `acts`,
+`edits`) is refused with a sentence pointing here.
+
+A tree states what it means once: a statement equal to what the runtime draws anyway (a column the row already shows) is kept,
+drawn once and noted, while a statement that conflicts is refused. A register List's `label` is the register's heading in the app's lists; its rows are named by the table's own label and singular.
+`type` may be omitted, and a Section, Side or Page
+without a `key` is keyed by its title's slug, written once and kept.
+
+`app apply` with no app known creates one from the file, named by the tree's `name`, and records its id and
+version in `<file>.lotics.json` (`app pull` writes the same file), so the next apply of that file edits that
+app; `--app <app_id>` names it instead, and is refused for a file whose record names another app. A known app
+is read first and only what the file changes is sent, as a JSON merge patch (RFC 7396): a key the file drops
+is removed, a list is replaced whole, and what the file leaves alone is left alone. A file pulled at a
+version the app has since left is refused, naming the version: pull the current tree into another path and
+carry your edits over. Applying a tree the app already has mints nothing.
+`--check` sends the same change as `dry_run`: what would refuse the tree, the notes on it, and the permissions the
+write would grant and remove, writing nothing. Every write's answer states those permissions: the saves, adds,
+Deletes and act writes the new tree grants and removes, from the previous tree to the new one.
+
+**Nothing is written into the tree for you.** The answer notes a treatment the rows call for that the tree leaves out —
+Readings over its rows, a record's Sections, an Act per status move, a picture where its rows hold photos
+(`lotics docs design`) — and the tree states the ones the job needs.
+
+**The tree changes after the app exists, and applying it again is how it lands.** Pull the tree, edit
+the file, apply it; or send `nodes` for one part. An Act whose write the tree cannot say names its own `workflow`; that workflow's code is
 the live one, and `lotics run set_app_workflow` changes it. A job no press starts — an agent or a
-service handing the app a file or a list of rows — is a workflow the app declares in `workflows`
-(`lotics docs model/workflows`): the model states what it takes and hands back, `lotics run
-set_app_workflow` sets its body with `inputs` and `outputs` left out, and every apply keeps that
-body. A workflow set on the app that its model declares nowhere is archived by the next apply; a query set on it that its model declares nowhere (`queries`) is removed by the next apply, which says so in its plan and its answer. An act that reads papers runs an agent
-apply owns: made, replaced and removed with the act, and an agent of that alias apply did not make
-is refused, never rewritten.
-
-**What a person reads and does in the app, an agent reads and does through it.** The apply generates a
-query for every list, record, child block and figure the screen reads, and a workflow for every add, edit,
-removal and act — `lotics run get_app_capabilities` lists them, and `lotics docs agent_surface` names each
-family and how it is called. A question the screen never asks is a query the app declares in `queries`
-(`lotics docs model/queries`), beside its `workflows`. Both are part of the design: step 5 of
-`lotics docs design`.
+service handing the app a file or a list of rows — is a Workflow node the app declares
+(`lotics docs model/workflow-node`): the node states what it takes and hands back, and `lotics run
+set_app_workflow` sets its code with `inputs` and `outputs` left out.
+
+**What a person reads and does in the app, an agent reads and does through it.** Writing the tree generates a
+query for every List, record, child List and figure the screen reads, and a workflow for every add, edit,
+removal and act — `lotics run get_app` lists them, and `lotics docs agent_surface` names each
+family and how it is called. A question the screen never asks is a Query node the app declares
+(`lotics docs model/query-node`), beside its Workflow nodes. Both are part of the design: `lotics docs
+agent_surface`, § Declaring more.
 
 ## 5 — A custom-code app
 
@@ -134,7 +152,7 @@ version. `useQuery("<alias>")` and `useWorkflow("<alias>")` call them. A deploy
 and carries every binding forward unchanged.
 
 **Named queries.** Author them as `kind: "project"` with a `filter`, naming each projected column
-(`{ "source": "fld_…", "output": "total" }`), so a row reads as `r.total`. Scope per-user reads with
+(`{ "source": "amount", "output": "total" }`), so a row reads as `r.total`. Scope per-user reads with
 `is_current_member` **inside the query** — a member id passed from the client is chosen by the
 caller. Write one `description` per alias: it is the line a chat or MCP caller chooses by.
 
@@ -147,12 +165,12 @@ that caller.
 Static checks prove parse, types and names — they evaluate nothing. Rehearse a write first:
 
 ```
-lotics run dry_run_workflow '{"trigger_type":"app_workflow","trigger_payload":{…},"live_reads":true}'
+lotics run set_app_workflow '{"app_id":"app_…","alias":"…","source":"…","verify_only":true,"record_id":"rec_…"}'
 ```
 
-It walks the real step tree and returns the resolved plan plus expression and tool-input errors,
-dispatching no write. **`live_reads: true` matters whenever the body reads anything**: without it
-every read returns a stub, and every data-gated branch takes the empty path.
+It walks the draft through the same engine an Act's preview uses, under the app's authority: reads are real,
+writes and sends are said and not made, and it returns what the run would answer plus the calls it would make.
+Pass `preview_inputs` for the values of a workflow that takes inputs and no row.
 
 Then run it end to end, on a throwaway record:
 
@@ -184,17 +202,15 @@ where a table left columns off at that width, `shed` names them.
 
 The app is drawn live, as you, read-only: a screen that writes when it opens shows that write
 refused, and `errors` lists what failed on the page. A version that looks wrong is one
-`lotics run rollback_app` away from the one before.
+`lotics app apply` away from the one before: apply the earlier tree again.
 
-For an app a model applied, `verdict` comes beside the images: what a check of the workspace's
-model finds of that app now, beside its rows — what the next apply would refuse it for and the notes
-on it, the `patch` adopting the decisions among them, and the app's body as the patch
-leaves it (`draft`). `verdict_unread` says why none was read.
+For an app stated as a tree, `verdict` comes beside the images: what a check of that app finds now,
+beside its rows — what the next write would refuse it for and the notes
+on it. `verdict_unread` says why none was read.
 
-The app's `name`, `icon`, `theme` and `description` are keys of the app in the model, and each apply
-writes them onto the app; an `icon` or `description` the model leaves out is cleared, and an app
-stating no `theme` is refused (`app.theme`). `lotics run update_app` changes them on
-the app, and `lotics model pull` reads them back as the app holds them. The
+The app's `name`, `icon`, `color` and `description` are props of the App node; an app
+stating no `color` gets the platform's grey tile. `lotics run set_app` with the app's id and a `body` patch changes them
+on the app, and `lotics app pull` reads the tree back as the app holds it. The
 `description` heads the capability listing the member's chat agent reads on **every** turn, so a
 standing process the app expects that agent to carry out belongs there and nowhere else.