@lotics/cli 0.315.18 → 0.316.0

package/docs/knowledge_docs.md

@@ -1,228 +1,109 @@
 # Knowledge Docs
 
-Knowledge docs are the AI's **rulebook layer** — the workspace-specific facts and rules an
-agent can't know on its own: your price list, your product codes, your SOPs, your shipping
-tariffs, your glossary of in-house terms. You write them once; the agent **searches and reads
-them on demand** while it works, pulling in only the lines it needs.
+Knowledge docs are the workspace's **rulebook layer** — the facts and rules an agent can't know on its own: a
+procedure, a policy, a glossary of in-house terms, a tariff book. You write them once; the agent **searches and reads
+them on demand** while it works, pulling in only the lines it needs. They are not injected wholesale, so a 10,000-line
+tariff costs nothing until a question touches it.
 
-They are deliberately **not** injected into the agent wholesale. Instead the agent retrieves
-from them line by line — grep, then read — so a 10,000-line tariff book costs nothing until a
-question actually touches it, and a 10MB one is no different.
-
-This is a **capability + usage** guide. For the exact input schema of any tool named here, run
-`lotics tools <tool_name>`.
+A menu with its prices, the customer list and the open orders are not knowledge: they are rows of tables, so apps, queries and documents
+can use them.
 
 ## Rulebook, not methodology
 
-Put in a knowledge doc the things the model **cannot guess**: your specific numbers, codes,
-names, exceptions, and policies. Do **not** put in it general skills the model already has
-("how to write a polite email", "how to summarize"). If the agent would get it right without
-the doc, the doc is noise.
-
-## Creating a doc — `lotics knowledge create`
+Put in a knowledge doc the things the model **cannot guess**: your specific numbers, codes, names, exceptions and
+policies. Do **not** put in it general skills the model already has ("how to write a polite email"). If the agent would
+get it right without the doc, the doc is noise.
 
-```bash
-lotics knowledge create --name "Shipping tariffs" \
-  --description "HS-coded rates; searchable by lane and code" \
-  --tags "HS,nhập khẩu" \        # file it as you make it — see Classifying, below
-  --from ./tariffs.md            # the body is a Markdown file; or --content '<inline>'
-```
+## Writing a doc — `set_knowledge`
 
-This reads the body from your filesystem and creates the doc through `create_knowledge`
-(prints the new id). A raw `lotics run create_knowledge @doc.json` works too — read a large
-`content` from a file or stdin. `create_knowledge` takes five fields, three of them required:
+`set_knowledge` creates a doc when it is given no `knowledge_doc_id` and changes the named one when it is given one:
 
-- `name` — what it is. Just the name: **grouping belongs in `tags`, not in a prefix baked into
-  every title.**
-- `description` — what the doc is **and what to grep it for**: its vocabulary and the synonyms
-  an ambiguous query would use. Surfaced in the tree before any body is read, and truncated at
-  200 characters. See *Write for grep* below.
+- `name` — what it is. Just the name: **grouping belongs in `tags`, not in a prefix baked into every title.**
+- `description` — what the doc is **and what to grep it for**: its vocabulary and the synonyms an ambiguous query would
+  use. Surfaced in the listing before any body is read, and truncated at 200 characters.
 - `content` — Markdown.
-- `tags` *(optional)* — the labels someone would filter by, e.g. `["Hồ sơ NOXH", "Khoản 13"]`.
-  Give **every** one that is true of the doc, not just the main one — a corpus is narrowed by
-  intersecting tags, so a doc carrying one label can only ever be found down one path. On
-  `update_knowledge` the array **replaces** what is stored, so resend the labels it should keep.
-- `files` *(optional)* — file ids of the source `.docx`/`.pdf`/`.xlsx` the doc was built from,
-  stored alongside it so a reader can open the original. The body stays the searchable text.
-
-A new doc is created **owned by you, active in your own agent context, and private** — no one
-else can see it yet. Changing a doc's default-active state is done through the web app / REST
-surface, not this tool.
-
-## Access
+- `tags` *(optional)* — the labels someone would filter by, e.g. `["Hồ sơ NOXH", "Khoản 13"]`. Give **every** one that is
+  true of the doc: a corpus is narrowed by intersecting tags, so a doc carrying one label is found down one path only.
+  On a change the array **replaces** what is stored, so resend the labels it should keep.
+- `files` *(optional)* — file ids of the source `.docx`/`.pdf`/`.xlsx`, stored alongside so a reader can open the original.
 
-A knowledge doc reaches an agent only when the member can `use` the doc. New docs are private
-to the owner; share them with other members or groups using the IAM tool `share_resource` on the CLI or in chat
-(category **Admin**; `unshare_resource` to revoke). An organization admin who is a person is no
-exception: they read a doc only once it is shared with them, or once they share it with
-themselves, which the audit log records. An API key acting as itself keeps the access set on the
-key.
+A change sends only the fields it changes. `edits` (anchored replace, insert, append) makes a surgical change to the
+body. Refine structure as you learn what users ask: add the synonym that failed to match, split a line that was too
+coarse, restate a term the heading was carrying.
 
-## How an agent uses a doc — ls, grep, cat
+A new doc is **owned by you and private**. `set_access` shares it: `resources[]` with `resource_type` `knowledge_doc`, and `principals[]` (a
+member, a member group, or `organization` for everyone), each with a `role` of `user` or `manager`; a principal without a `role` has
+its access taken away. A doc reaches an agent only when the member can `use` it, an organization admin included.
 
-Docs are not injected wholesale. The agent works the corpus like a filesystem, and all three
-verbs respect access, so only docs the caller may use ever surface.
+## How an agent uses a doc
 
-1. **`list_knowledge`** — `ls`. The corpus as a flat list: id, name, tags, and a truncated
-   description; `tag` narrows it. No bodies.
-2. **`grep_knowledge`** — `grep -rn`. Match across every readable doc (or one doc, or one
-   tag), returning **doc, line number, and the matching line**. It runs inside Postgres,
-   so only matching lines cross the wire.
-3. **`read_knowledge`** — `cat` / `sed -n 'X,Yp'`. Read a doc whole or by line range, to see
-   the context around a hit.
+Retrieval works like a filesystem, and respects access: only docs the caller may use ever surface.
 
-Matching is **not ranked** — there is no index and no tokenizer, which is why a corpus in any
-script works and why nothing goes stale. The consequence is that the *agent* does the
-narrowing: a distinctive phrase is sharply selective, a whole question matches everything.
-`grep_knowledge` always reports `total_matches`, so "too broad" is visible and cheap to fix.
+1. **List and search** — `get_workspace` kind `knowledge` lists the corpus (id, name, tags, a truncated
+   description); a search term matches a doc's name, description and tags. `get_workspace` with `search` finds where something is said: it
+   matches across every readable doc and returns the **doc, line number and matching line**;
+   `knowledge_doc_id` or `tag` confines the lines to one doc or to the docs carrying that tag.
+2. **Read** — `read_knowledge`, a doc whole or by line range, to see the context around a hit.
 
-### Literal by default, expression on request
+Matching is **not ranked**: the *agent* does the narrowing. A distinctive phrase is sharply selective, a whole question
+matches everything. A search always reports `total_matches`, so "too broad" is visible and cheap to fix.
 
-`pattern` is **literal text** — every character matches itself. Set `regex: true` to read it as
-a POSIX regular expression instead.
+The `search` is **literal text** — every character matches itself. Set `regex: true` to read it as a POSIX regular
+expression (a word boundary is `\y`, not `\b`):
 
 ```
-grep_knowledge({ pattern: "C/O (Form E)" })
-grep_knowledge({ pattern: "\\yNK\\y", regex: true, case_sensitive: true })
+{ "search": "C/O (Form E)", "kind": "knowledge" }
+{ "search": "\\yNK\\y", "kind": "knowledge", "regex": true, "case_sensitive": true }
 ```
 
-The default is the safe one rather than the conventional one, and the asymmetry is worth
-knowing. As an expression, `C/O (Form E)` searches for `C/O Form E` — not in the document — and
-returns a confident zero; `[CŨ]` becomes a one-character class and matches every `C` in the
-corpus. Both look like ordinary answers. A literal search has no such failure: the worst case
-is an expression sent without the flag, which finds nothing and says so, naming the search that
-ran and what to pass instead. That last part is **measured, not guessed** — an empty result tells
-you whether reading the pattern as an expression would have matched, so an alternation sent without
-the flag (`phrase A|phrase B`) comes back naming `regex: true` rather than advising you to shorten a
-pattern that was never too broad.
-
-### Matching options
-
-- **Tone marks match exactly by default.** `diacritic_insensitive: true` folds them, so `ca phe`
-  matches `cà phê` — reach for it when the pattern was typed without them, not by habit: folding
-  strips the pattern to ASCII, where a short Vietnamese word matches inside unrelated words
-  (`mã` finds `manifest`). An empty result tells you when folding would have matched.
-- **Case folds by default**, independently of diacritics. `case_sensitive: true` matches case
-  exactly — useful for an acronym (`NK` vs `nk`) that a folded search would blur.
-- **Whitespace is normalized on both sides.** A body converted from PDF, Word or Excel carries
-  non-breaking spaces, soft hyphens, zero-width marks and padded runs that nobody types into a
-  query; those fold to ordinary single spaces before matching, so a correct search does not return
-  a silent zero on text that is present. A literal pattern is normalized the same way; an
-  expression is left byte-exact, since collapsing its whitespace would rewrite it.
-- **What `regex: true` supports**: quantifiers, character classes, alternation, anchors,
-  backreferences, non-greedy forms, `(?i)`, and both lookahead and lookbehind. A word boundary
-  is **`\y`**, not `\b` — Postgres spells it differently, and `\b` is rewritten for you rather
-  than silently matching nothing. Named groups and `\p{…}` are likewise rewritten to their POSIX
-  equivalents. A `\p{…}` with no POSIX equivalent, and a malformed expression, are both refused
-  with the reason.
-
-Where an expression cannot express the question at all — a value that must be computed, a
-layout matching cannot address — stage the doc into a code run instead (`code_exec`, in chat or an app agent, with
-`knowledge_doc_ids` puts it at `inputs/knowledge/<id>.md` as a real file).
-
-### What a result is bounded by
-
-A result carries at most 40.000 characters. Matched lines are admitted first and context fills
-what remains, so an answer is never dropped to make room for a neighbouring line. Anything the
-budget cut is REPORTED — `chars_elided_matches` (an answer was dropped) and
-`context_omitted_matches` (an answer was kept without the context you asked for) mean different
-things and call for different fixes: narrow the pattern, or ask for fewer `context_lines`.
-Individual lines longer than 600 characters are clipped and marked, with `read_knowledge` giving
-the rest.
-
-`total_matches` is always the true total, even when fewer are shown.
-
-## Write for grep — the rules that decide whether an answer is findable
-
-Retrieval addresses **lines**. Every rule below follows from that one fact.
-
-- **One self-contained fact per line.** A grep hit returns *that line*. For dense or tabular
-  data — a price row, a tariff code, a charge entry — put the whole record on one line.
-- **Repeat the searchable terms on every line; headings do not carry down.** A line reading
-  `Rate: 15%` under a heading `Roasted coffee` will never match a search for `coffee`. Restate
-  the identifying terms inline, even when it reads redundantly to a human. This is the single
-  rule most often got wrong.
-- **Keep a line under ~600 characters.** Past that the line is truncated in the agent's view
-  and marked as cut; the agent can still `read_knowledge` for the rest, but it costs a round
-  trip. Put the identifying terms early and the long tail late.
-- **Put synonyms and translations on the line itself.** A bilingual row (`Cà phê, đã rang /
-  Coffee, roasted`) matches queries in either language for free. The same trick carries
-  colloquial terms next to official ones.
-- **For prose, keep a rule and its exception close.** A hit returns one line, so a rule on line
-  40 and its exception on line 90 can be retrieved apart. Use `context_lines` when reading, and
-  keep related clauses adjacent when writing.
-
-Markdown headings are ordinary text — useful for a human (a doc's `##` headings outside its
-blocks, two or more, are listed on its page as its sections) and for orienting a
-`read_knowledge`, but they carry no retrieval weight of their own.
-
-**The description is the discovery hint.** It is what the agent sees in the tree before it has
-read a byte of the body, so it is the only clue for *what term to grep for*. Write it to name
-the doc's vocabulary — the words that actually appear inside it. Keep it to a sentence: it is
-truncated at 200 characters, and a keyword-stuffed description is cut, not rewarded.
-
-## Updating a doc — `lotics knowledge update`
-
-```bash
-lotics knowledge update kdc_... --from ./tariffs.md   # replace the body (--name / --description too)
-```
+As an expression `C/O (Form E)` would search for `C/O Form E`, which is not in the document, and return a confident
+zero; the literal default has no such failure. With `regex` omitted, a literal search that finds nothing while the
+pattern, read as an expression, matches (`a|b`, the commonest) returns those lines under a note saying how they were
+read. `regex: false` keeps the literal zero; a search that finds nothing either
+way says so.
 
-Send only the fields you're changing. `--from` / `--content` replaces the body; `--name` /
-`--description` / `--tags` change metadata. `update_knowledge` resolves concurrency **internally** — it
-re-reads the current content pointer and version-chains the new body — so there is no version
-token to pass from the CLI. (The chat agent may instead send an `edits` array — anchored
-replace / insert / append — for a surgical change; see `lotics tools update_knowledge`.) Refine
-structure as you learn what users actually ask: add the synonym that failed to match, split a
-line that was too coarse, restate a term the heading was carrying.
+- **Tone marks match exactly by default.** `diacritic_insensitive: true` folds them (`ca phe` matches `cà phê`); use it
+  when the pattern was typed without them, since folding lets a short word match inside unrelated ones.
+- **Case folds by default.** `case_sensitive: true` matches exactly, for an acronym (`NK` vs `nk`).
+- **Whitespace is normalized on both sides.** Non-breaking spaces, soft hyphens and padded runs from PDF, Word or Excel
+  bodies fold to single spaces before matching.
 
-## Classifying a corpus — tags
+A search shows at most 16,000 characters, shared by what it finds in knowledge, in structure and in records. Matched
+lines are admitted first and context fills what remains; anything cut is reported, with the true number of matching
+lines. Lines longer than 600 characters are clipped and marked; `read_knowledge` gives the rest.
 
-A doc carries a SET of labels, not a folder. Order does not matter, a doc can wear several, and
-the vocabulary is whatever the docs themselves use — a tag stops existing the moment nothing
-carries it.
+## Write for grep
 
-```bash
-lotics knowledge update kdc_... --tags "HS,nhập khẩu"    # ONE doc: state its complete set
-lotics knowledge tag kdc_a kdc_b --add HS --remove draft # MANY docs: a diff applied to each
-```
+Retrieval addresses **lines**. Every rule follows from that one fact.
 
-The split is deliberate. Looking at one doc you know what it should carry, so `--tags` replaces.
-Across a set you do not — the docs carry different labels — so `tag` adds and removes against
-each doc's own set, and never states one classification for all of them. Removal ignores case;
-adding a label a doc already carries changes nothing.
+- **One self-contained fact per line.** A hit returns *that line*. For dense or tabular data — a price row, a tariff
+  code — put the whole record on one line.
+- **Repeat the searchable terms on every line; headings do not carry down.** A line reading `Rate: 15%` under a heading
+  `Roasted coffee` will never match a search for `coffee`. Restate the identifying terms inline, even when it reads
+  redundantly to a human. This is the rule most often got wrong.
+- **Keep a line under ~600 characters,** the identifying terms early and the long tail late.
+- **Put synonyms and translations on the line itself.** A bilingual row (`Cà phê, đã rang / Coffee, roasted`) matches
+  queries in either language.
+- **For prose, keep a rule and its exception close.** A rule on line 40 and its exception on line 90 can be retrieved apart.
 
-An agent narrows by tag rather than reading the whole corpus:
+Markdown headings carry no retrieval weight of their own; a doc's `##` headings outside its blocks, two or more, are
+listed on its page as its sections.
 
-```bash
-lotics tools list_knowledge   # takes an optional tag
-lotics tools grep_knowledge   # same
-```
+The **description is the discovery hint**: it is the only clue for *what term to grep for* before a body is read. Name
+the doc's vocabulary in a sentence.
 
-## Taking a doc out of circulation — `hide`
-
-```bash
-lotics knowledge hide kdc_...              # superseded, draft, source material
-lotics knowledge list --include-hidden     # find it again
-lotics knowledge unhide kdc_...            # put it back
-```
-
-A hidden doc is out of every **listing**: it is gone from the Library's list, from
-`list_knowledge`, and from the corpus `grep_knowledge` searches, so nothing finds it by browsing.
-It is not deleted, not unshared, and still **reads when addressed by id** — `read_knowledge` with
-its id, a code run staging it, an app agent that declares it. That is the point: hiding is a
-statement about discovery, so it cannot silently break an app that depends on a doc by name.
+## Classifying a corpus — tags
 
-Reach for it instead of `rm` whenever the material still matters: last year's tariff schedule, a
-handbook a newer one replaced, the raw source a curated doc was written from.
+A doc carries a SET of labels, not a folder. Order does not matter, a doc can wear several, and the vocabulary is
+whatever the docs themselves use. `tags` on `set_knowledge` states one doc's complete set.
 
 ## Deleting and restoring
 
-`lotics knowledge rm <id...>` deletes docs: they leave every listing, search and read. **Their sharing
-and version history are kept**, so a deleted doc is recoverable. `lotics knowledge list --deleted`
-shows the deleted docs you manage, and `lotics knowledge restore <id...>` brings them back with the
-access they had (`restore_knowledge` in chat). A restore is all or none: every id must be a deleted
-doc you manage, or nothing changes. A doc with no owner is restored only by an admin, who becomes its
-owner. A doc that an app or workflow still names cannot be deleted.
+`delete_knowledge` deletes docs: they leave every listing, search and read. **Their sharing and version history are
+kept**, so a deleted doc is recoverable. `get_workspace` kind `knowledge` with `include_archived: true` lists the deleted
+docs you manage, and `restore_knowledge` brings them back with the access they had. Both take many ids and are all or
+none: every id must be a doc you manage, or nothing changes. A doc with no owner is restored only by an admin, who
+becomes its owner. A doc that an app or workflow still names cannot be deleted.
 
 ## Formatting — what a doc draws
 
@@ -242,20 +123,3 @@ A doc is markdown with GFM tables. Beyond that it draws a few blocks, each in sy
 Each tag stands on a line of its own, and a tag line inside a fenced code block is code. Attributes are text in double quotes or a number in braces; nothing in a tag runs. A write that adds a tag that does not close, nests wrongly, carries an attribute the tag does not take, or names a component this list lacks (`<Frame>`, `<CodeGroup>`) is refused with the lines to fix; lowercase HTML (`<br>`) stays text.
 
 A chart's numbers live in its mermaid source, which agents read and grep like any text: write them there once, not again in a table.
-
-## Reaching the tools
-
-```bash
-lotics knowledge list                   # catalog: id, name, tags, description
-lotics knowledge get kdc_... -o doc.md  # read a body to a file (omit -o for stdout)
-lotics tools update_knowledge           # full input schema for any knowledge tool
-```
-
-The Knowledge category covers `list_knowledge`, `create_knowledge`, `update_knowledge`,
-`delete_knowledge` and `restore_knowledge` — fronted by the `lotics knowledge list | create | get |
-update | tag | hide | unhide | rm | restore` commands, and all but `delete_knowledge` and
-`restore_knowledge` reachable over MCP as well, so a corpus can be
-authored from whichever surface you already work in. `list` (without `--deleted`), `tag`, `hide` and `unhide` go over REST rather than a tool, because
-they are a person's view of the corpus: the tools answer what the ASSISTANT may browse, and a
-hidden doc is out of that set by definition. Sharing a doc to other members is `share_resource` / `unshare_resource` on the
-CLI or in chat (category **Admin**).

package/docs/migration.md

@@ -6,54 +6,50 @@ already on disk no longer matches what the CLI does.
 
 ## Local app projects are gone
 
-An app built from a model no longer lives in a directory. The live app is the only edit surface:
-each change mints a new version of it, and rolling back to an earlier version is the undo. What
+An app stated as a tree no longer lives in a directory. The live app is the only edit surface:
+each change mints a new version of it, and applying the earlier tree again is the undo. What
 the app is — its screens (`app.json`), its queries, workflows, agents and capabilities, and the
-model body it was compiled from — is held by that version, and the model's tables, fields, options,
-templates and roles are the workspace's own.
+tree it was compiled from — is held by that version, and the tables, fields, options, templates and
+roles are the workspace's own.
 
 | What you ran | What replaces it |
 |---|---|
-| `lotics scaffold check` + `scaffold apply` | `lotics model apply <model.json>` — checks the file, applies the tables and rows, then mints a version of every app it declares |
-| `lotics workspace build <model.json>` | `lotics model apply <model.json>` |
-| `lotics app create --from <model.json>#<app>` | `lotics model apply <model.json> --app <app>` |
-| `lotics app regenerate` | change the model file, then `lotics model apply` |
-| `lotics scaffold diff` | `lotics model check <model.json>` — 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 scaffold check` + `scaffold apply`, `lotics workspace build <model.json>`, `lotics setup <file>` | `lotics run set_tables` with the tables of the workspace in one list (at most 50 a call), then `set_app` for each app (`lotics app apply <file>`); `dry_run` checks and writes nothing |
+| `lotics app create --from <model.json>#<app>` | `lotics app apply <file>` — `set_app` creates the app from its tree |
+| `lotics app regenerate` | change the tree, then `lotics app apply <file>` |
+| `lotics scaffold diff` | `lotics app apply <file> --check` — what would refuse the tree, writing nothing |
+| `lotics scaffold export` | `lotics app pull <app_id> [path]` — the app's tree as JSON, one app at a time |
 | `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`) |
+| `lotics app workflow set` / `app query set` | `lotics run set_app_workflow` / `set_app_queries` — each mints a version |
+| `lotics app versions` + a redeploy of an old tree | apply the earlier tree again (`lotics app apply <file>`), or deploy the earlier source; table changes and data writes stay |
+| `lotics app rename`, `app subdomain`, `package.json#lotics.capabilities` | `lotics run set_app` with the app's id (`public_subdomain`, `capabilities`; its name is the tree's `name`) |
 | `lotics app api publish` / `unpublish` | `lotics run publish_app_api` / `unpublish_app_api` |
-| `lotics field rename` | `lotics run update_table`, then the same label in the model file |
+| `lotics field rename` | `lotics run set_tables` with a merge patch of the table's document |
 | `lotics app kit` | nothing: a custom-code app depends on `@lotics/app-sdk` (below) |
 | `@lotics/xlsx` / `@lotics/docx` to build a template's file | any `.xlsx` / `.docx` library, then `lotics upload` (`lotics docs document_templates`) |
 | `lotics file preview` | `lotics file download <fil_id>`, then open it |
-| `model.json#apply` (`[{package, bind}]`) | state the tables under `entities` — a model carrying `apply` is refused |
-| `lotics library list` / `library show <slug>`, `lotics preset list` / `preset show <slug>` | the example models at `https://lotics.ai/presets/index.json`, each a complete `model.json` to adapt |
-| `model.json#from` (with `variants`, `rename`) | state every table under `entities` — a model carrying `from` is refused |
-| `lotics library init <apg_id>`, `lotics setup <apg_id>`, `lotics app upgrade`, `lotics library fixtures` | nothing copies a package any more: write a `model.json` (`lotics docs model`), then `lotics setup model.json` or `lotics model apply model.json` |
+| `lotics library list` / `library show <slug>`, `lotics preset list` / `preset show <slug>` | the example files at `https://lotics.ai/presets/index.json`, each read and its tables passed to `set_tables` |
+| `lotics library init <apg_id>`, `lotics app upgrade`, `lotics library fixtures` | nothing copies a package any more: state the tables (`lotics docs model`) and pass them to `set_tables` |
 
 `lotics tools` lists every tool, and `lotics tools <name>` prints its input.
 
-**An existing JSON app moves on the first `lotics model apply`** of the model it came from: that
-apply binds each app alias to the app it already became and mints its next version from the file.
-A directory an earlier CLI wrote (`app.json`, `src/workflows/`, `.lotics/`, `package.json#lotics`
-with `plan`, `queries` or `workflows`) is no longer read by anything; keep the model file, delete the
+**An existing JSON app moves with `lotics app pull <app_id>`**: it writes the app's tree, and
+`lotics app apply` of that file edits the app and mints its next version. A directory an earlier CLI wrote (`app.json`, `src/workflows/`, `.lotics/`, `package.json#lotics`
+with `plan`, `queries` or `workflows`) is no longer read by anything; keep the pulled tree, delete the
 rest.
 
 **Authored workflow bodies** an act names (`workflow` on an act) are the live workflow's own body:
-the apply keeps it, and `lotics run set_app_workflow` changes it.
+`lotics run set_app_workflow` changes it.
 
-**A model written before `party`** draws its people and organisations as things — a row with no
-picture shows no initials: state `party` (`person` or `organization`) on those entities' `records`.
+**A table written before `party`** draws its people and organisations as things — a row with no
+picture shows no initials: state `party` (`person` or `organization`) in that table's `records`.
 
 ## Custom-code apps use `@lotics/app-sdk`
 
 A hand-written app depends on `@lotics/app-sdk` alone — the hooks (`useQuery`, `useWorkflow`, …),
 `mount`, and `AppRouter` from `@lotics/app-sdk/router` — and draws with its own React.
 `@lotics/app-runtime` and `@lotics/ui` are no longer published: the runtime is what the platform
-draws a model's app with, and it ships with the platform.
+draws an app with, and it ships with the platform.
 
 An app that listed `@lotics/app-runtime`: