@lotics/cli 0.315.17 → 0.316.0

package/AGENTS.md

@@ -8,18 +8,22 @@ 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>]` · `lotics docs [<area>] --grep <text>` | This CLI's references, carried inside it so each describes the binary answering. 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. A page the copy lacks — one the server added since this binary was built, which a refusal can cite — is read from the server's `docs` tool with this machine's credential, and so is every `--grep`, over the references the server serves. A custom-code app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the app. |
-| `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. Every top-level key, every field type with the config it needs, the row format, the rules, and a worked example; complete example models of several trades are listed at `https://lotics.ai/presets/index.json`. `lotics model apply` checks the file (every problem in one run), applies its tables and mints a version of each app; the WORKSPACE remembers what each alias became, so every later apply binds by id and a relabel on either side is a rename it reports rather than a second table it adds. `lotics model pull` goes the other way — the workspace's model, rebuilt from what owns each part. |
-| `lotics docs design` · `lotics docs design/<section>` | Designing an app — where an app starts: the method, the treatment each kind of row takes with the `model` page stating its keys, the visual bar, and looking at what an apply built. A finding of the apply names its section. |
-| `lotics docs examples` · `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete model: the job, the keys to read, where it is the wrong one, and the excerpt. |
-| [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE — clarify, model, apply or build, prove, look — for an app stated in a model and for a custom-code app. Read it once before starting an app. Looking is `lotics run screenshot_app '<json>' -o <dir>`, which saves each PNG and its text snapshot there. |
+| `lotics docs model` · `lotics docs model/<section>` | The keys of a table document and the components of an app tree: a table's fields keyed by alias, how a row of each table is recognised (`records`), and the apps stated over them. Every key, every field type with the config it needs, the rules, and a worked example; example files of several trades are listed at `https://lotics.ai/presets/index.json` — read one and pass its tables to `set_tables`. |
+| `lotics docs design` · `lotics docs design/<section>` | Designing an app — the treatment each kind of row takes with the `model` page stating its keys, the visual bar, and looking at what a write built. Opens on the common treatments; a finding names its section. |
+| `lotics docs examples` · `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete workspace: the job, the props to read, where it is the wrong one, and the excerpt. |
+| [docs/getting_started.md](./docs/getting_started.md) | What a workspace holds, and the one page to open for each job: building a workspace, changing an app, a rule on a table, a document, data and questions, a connected service, sharing. The first page an agent outside the product reads. |
+| [docs/first_build.md](./docs/first_build.md) | A whole workspace built call by call — understand the work, tables with a check, the paper, the app (which apps, a treatment per kind of row, what the check refuses, who gets it), the owner's rows, pressing it — in one worked example. |
+| [docs/app_architecture.md](./docs/app_architecture.md) | One factory's split into apps: each app's job sentence, person, register and what sits inside it. The questions that split a business are in first_build. |
+| [docs/working_in_a_workspace.md](./docs/working_in_a_workspace.md) | The right means for each job once the apps exist: an app's act for a business operation, a record write for data entry, a query for a figure the business defines, a count for the rest. |
+| [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE — clarify, tables, apps, prove, look — for an app stated as a tree and for a custom-code app. Read it once before starting an app. Looking is `lotics run screenshot_app '<json>' -o <dir>`, which saves each PNG and its text snapshot there. |
 | [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas — the detail `--help` compresses. |
-| [docs/data_model.md](./docs/data_model.md) | Tables, their fields, and how they relate — one fact per column, one entity per table and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied, a copy boundary that accounts for every source field, provenance as a link, a declared natural key, history as rows, and why derived DEPTH costs more than row count; then every field type, its properties, computed fields, and what `update_fields` takes. Separate from building_an_app because every workspace starts with tables and many never get an app. |
+| [docs/data_model.md](./docs/data_model.md) | Tables, their fields, and how they relate — one fact per column, one table per kind of thing and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied, a copy boundary that accounts for every source field, provenance as a link, a declared natural key, history as rows, and why derived DEPTH costs more than row count; then the choices around a field's type, and how a field is changed (a list replaces whole, what refuses a deletion, what `force` consents to). Separate from building_an_app because every workspace starts with tables and many never get an app. |
 | [docs/filters.md](./docs/filters.md) | The one filter grammar every filter-taking tool, view and rollup reads — conditions, groups, and the operators per field type. |
 | [docs/field_values.md](./docs/field_values.md) | The value each field type takes in a write. |
 | [docs/workflows.md](./docs/workflows.md) | Writing a workflow body — triggers, steps, what an expression reads, the helpers, approvals and agent steps, and table checks. |
 | [docs/app_bindings.md](./docs/app_bindings.md) | The queries, workflows and agents an app binds — the query tree, typed inputs and outputs, and an agent's declaration. |
-| [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/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates, and what a template an app's Act makes is handed. |
+| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the procedures, policies and glossary an agent can't guess with `set_knowledge`; who can read a doc; searching and reading it line by line. |
 | [docs/migration.md](./docs/migration.md) | What to DO when something an earlier CLI wrote to disk no longer matches what it does — local app projects are gone, and each verb that read one has a replacement. |
 | [README.md](./README.md) | Install, auth, and worked examples. |
 
@@ -30,14 +34,14 @@ conventions are, and where the traps are.
 - **Tools** (`lotics tools`, `lotics run <tool>`) — the *agent tool registry*: what an agent, workflow,
   or automation may call. Workspace data, templates, knowledge, admin.
 - **Commands** (`lotics --help` § COMMANDS) — the CLI's *own verbs*: auth and org/workspace scoping,
-  file upload and download, and those that touch a local file for an app — `model apply`,
-  `model check`, `model pull`, `app create --custom`, `app pull` and `app deploy`.
+  file upload and download, and those that touch a local file for an app — `app apply`,
+  `app create --custom`, `app pull` and `app deploy`.
 
 Several capabilities exist **only** as commands and appear nowhere in `lotics tools` — downloading a
 file is the one most often mistaken for missing. Concluding "the platform can't do X" from the tool
 list alone is a mistake; check both.
 
-**`lotics <verb> --help` prints that verb's entries from § COMMANDS** (`lotics model --help`,
+**`lotics <verb> --help` prints that verb's entries from § COMMANDS** (`lotics app --help`,
 `lotics file download --help`); `lotics report --help` prints the report frame. To find out whether
 something exists, read `lotics --help` § COMMANDS — the whole section, not a narrow grep.
 
@@ -55,9 +59,8 @@ something exists, read `lotics --help` § COMMANDS — the whole section, not a
   and then re-running what you wanted. Never wrap it in a timeout waiting for a human — `--wait`
   exists if you really want one blocking command, and killing that one is safe too (the request
   survives and the next command claims it). A command run before Confirm exits 1 naming the page and
-  code again; once the 15 minutes are up it says to ask again. `lotics setup` falls into the same
-  flow by itself when the email it was given already has an account: it stops having created
-  nothing, and the SAME command run again carries on.
+  code again; once the 15 minutes are up it says to ask again. `lotics auth signup <email>` for an email that
+  already has an account creates nothing and names `auth login`.
 - **A credential is either a SIGN-IN or an API KEY, and `logout` treats them differently.** A profile
   from `auth login` / `auth signup` acts as the person who confirmed it and is theirs — `lotics auth
   logout` revokes it server-side, and it lapses on its own after 90 idle days (each use pushes that
@@ -71,8 +74,7 @@ something exists, read `lotics --help` § COMMANDS — the whole section, not a
   wrong. `lotics auth whoami` prints the kind, asking the server when the store cannot say.
 - **A key created in Settings never administers the organization, whatever its access.** The verbs
   `docs/cli_reference.md` marks *admin only* split in two under a key: `workspace doctor`, which only
-  reads inside a workspace the key reaches, runs as before, while applying or pulling a model
-  (`model apply`, `model pull`, `setup`), managing people, sharing or
+  reads inside a workspace the key reaches, runs as before, while managing people, sharing or
   ownership, creating or deleting a workspace, changing workspace settings, setting credit limits,
   reading the access log and publishing an app's API answer `403` and name the remedy: an admin signed in, so
   `lotics auth login <email>` and run it again. A sign-in acts as that person and is refused none of
@@ -92,16 +94,27 @@ something exists, read `lotics --help` § COMMANDS — the whole section, not a
   stderr; the result goes to stdout, so piping stays clean. `--json` switches stdout from the
   agent-readable summary to the full structured object.
 - **Every tool is invoked one way — `lotics run <tool>`.** Including the ones that RUN something
-  (`run_app_workflow`, `run_app_agent`, `run_app_query`) and every one that changes an app
-  (`set_app_queries`, `set_app_workflow`, `set_app_agent`, `update_app`, `rollback_app`). A command
+  (`run_app_workflow`, `run_app_query`) and every one that builds
+  (`set_tables`, `set_app`, `set_app_queries`, `set_app_workflow`). A command
   exists only for work that touches a local file.
-- **Every change to an app mints a version of it, and rolling back is the undo.** An apply, a
-  deploy, a single `set_app_*` or `remove_app_binding`: each is a new version, and `rollback_app` makes an
-  earlier one current again. It restores the app — never a table change or a row a workflow wrote,
+- **Building is two tools, each a writer that creates without an id and edits with one.** `set_tables`
+  takes `{ "tables": [...] }` — always a list, one or many, all or nothing — each table a document keyed
+  by alias (fields keyed by alias; a link names its table by id, or by the `ref` of another table of the
+  same call, and states `multi`; a two-way link states `pair` on both tables), edited by an RFC 7396
+  merge patch of that document, where `null` deletes. A call carries at most 50 tables, 200 first rows a table,
+  and 2000 rows and 2000 documents in all. `set_app` takes ONE app: `{ "body": <the App tree> }` to create, the app's
+  `name`, `description`, `icon` and `color` being props of the App node; `{ "app_id": …, "nodes": { "<address>": <patch> } }`
+  to change a node, refused with `base_version_id` when the app has moved past the version you read. `dry_run` checks
+  without writing, a refusal lists everything wrong in the call, and every answer states the permissions the write
+  granted and removed. The answer notes the treatments an author leaves unstated; nothing is written into the tree for them. A new workspace: one `set_tables` call with
+  the tables, then every `set_app` call, then fixes. The example files under `https://lotics.ai/presets/index.json` are read and their tables passed to
+  `set_tables`.
+- **Every change to an app mints a version of it, and applying the earlier tree again is the undo.** An apply, a
+  deploy, a single `set_app_*` or `remove_app_binding`: each is a new version. Applying the earlier tree again restores the app — never a table change or a row a workflow wrote,
   so try a write on a throwaway record.
 - **Exit codes are assertable, and they report the WORK rather than the call.** `lotics run` exits
-  non-zero when a `run_app_workflow` or `run_app_agent` result's own envelope carries a failed
-  `status` (`error`/`failed`/`cancelled`, or `not_previewed`: a preview asked for and not given) — any other tool's top-level status is data and exits 0 —
+  non-zero when a `run_app_workflow` result's own envelope carries a failed
+  `status` (`error`/`failed`/`cancelled`, or `not_previewed`: a dry run asked for and not given) — any other tool's top-level status is data and exits 0 —
   so `lotics run … && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on
   findings. An unrecognized status exits 0 — the list is an allowlist of failure, so a status added
   later never turns a working script red — and a parked run (`awaiting_input`) is not a failure.
@@ -134,7 +147,7 @@ something exists, read `lotics --help` § COMMANDS — the whole section, not a
 
 ## Where this CLI is not the answer
 
-- **Editing an app in a local directory.** An app stated in a model is changed by applying the
-  model again; its bindings through their `set_app_*` tools; a custom-code app's code by deploying
+- **Editing an app in a local directory.** An app stated as a tree is changed by applying the
+  tree again; its bindings through their `set_app_*` tools; a custom-code app's code by deploying
   its directory again. Nothing reads a local copy of a live app back.
 - **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.

package/README.md

@@ -28,8 +28,11 @@ Per-command contracts, flags, exit codes and gotchas are in
 The platform's primary surfaces have dedicated usage guides that ship inside this
 package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
 
+- [`docs/getting_started.md`](docs/getting_started.md) — what a workspace holds and the one page
+  to open for each job.
+- [`docs/first_build.md`](docs/first_build.md) — a whole workspace built call by call: which apps, a treatment per kind of row, what the check refuses.
 - [`docs/building_an_app.md`](docs/building_an_app.md) — building an app end to end: an app
-  stated in a model and applied with `lotics model apply`, or a custom-code app on
+  stated as a tree and written with `set_app`, or a custom-code app on
   `@lotics/app-sdk`. Read it once before starting an app.
 - [`docs/document_templates.md`](docs/document_templates.md) — generate finished documents
   (PDF, Excel, Word, email) by filling reusable templates: the five template types, the
@@ -37,48 +40,52 @@ package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
 - [`docs/migration.md`](docs/migration.md) — what to do when a release changes what the CLI once
   wrote to disk; read once, when something on disk no longer matches what the CLI does.
 - [`docs/knowledge_docs.md`](docs/knowledge_docs.md) — the AI's rulebook layer: authoring the
-  workspace facts an agent can't guess, who can read a doc, and the
-  catalog-then-stage retrieval model agents use to pull only the lines they need.
+  procedures and policies an agent can't guess, who can read a doc, and the
+  search-then-read retrieval agents use to pull only the lines they need.
+- [`docs/app_architecture.md`](docs/app_architecture.md) — one factory's split into apps, and
+  [`docs/working_in_a_workspace.md`](docs/working_in_a_workspace.md) — the means for each job once they exist.
 
-## Start in one command
+## Start in two commands
 
-Install the CLI, write a `model.json` and apply it; `setup` creates the account, applies the model
-to its workspace, and prints a one-time sign-in link:
+Install the CLI and create an account; the account's workspace is then built with the tools:
 
 ```bash
 curl -fsSL https://lotics.ai/install.sh | bash
-lotics setup model.json --email you@company.com
+lotics auth signup you@company.com
 ```
 
 The installer downloads one compiled executable — no Node.js, no npm: every app is deployed on
 Lotics. Node 18+ comes in only for a custom-code app, which is built on this machine to deploy.
 
-Add `--json` for one machine-readable object instead of progress — the organization, the
-workspace, the app ids, the sign-in link, and any warnings. Already signed in? Drop `--email` and
-`lotics setup model.json` applies to the account you have.
-
 ## Describe your workspace
 
-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. Complete example models of several trades are
-listed at `https://lotics.ai/presets/index.json` (each at `https://lotics.ai/presets/<slug>.json`) —
-read the closest one and write your own in your business's words.
+Tables and apps are written by two tools, the same on the CLI and over MCP. `set_tables` takes
+`{ "tables": [...] }` — always a list, all or nothing — each table a document keyed by alias: its fields
+(keyed by alias), options, links, views and how a row is recognised. A link names its table by id, or
+by the `ref` of another table of the same call, and states `multi`; a two-way link states `pair` on
+both tables. A table is edited by an RFC 7396 merge patch of its document, where `null` deletes.
+`set_app` takes one app per call: `{ "body": <the App tree> }` to create, the tree stating the app's `name`; `{ "app_id": …,
+"nodes": { "<address>": <patch> } }` to change one node (the App's own props change through `body`). Both create when
+given no id and edit when given one, and `dry_run` checks without writing. Every answer states the permissions the
+write granted and removed.
+
+A new workspace: one `set_tables` call with the tables (at most 50, 200 first rows each, a call), then every `set_app` call, then fixes. Example
+files of several trades are listed at `https://lotics.ai/presets/index.json` (each at
+`https://lotics.ai/presets/<slug>.json`) — read the closest one, write your own in your business's
+words, and pass its tables to `set_tables`.
 
 ```bash
-lotics docs model                    # how to write one, with a worked example
-lotics setup model.json --email you@company.com   # a new account, then the model applied to it
-lotics model apply model.json        # an account you already have: the tables, then every app
+lotics docs model                          # the keys, with a worked example
+lotics run set_tables @tables.json          # every table of the workspace, in one call
+lotics app apply orders.app.json --check   # set_app as a dry run: everything wrong, nothing written
+lotics app apply orders.app.json           # set_app: creates the app, or edits the one the file records
 ```
 
-`model apply` checks the whole file first — every problem at once — 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 a new version of
-each app the model declares. Change the file and apply it again; `--app <alias>` applies only the
-apps named. Rolling an app back (`lotics run rollback_app`) restores its earlier version — table
-changes and data writes stay.
+The answer notes the treatments an app leaves unstated that its rows call for; nothing is written into the
+tree for you. Change the file and apply it again; applying an earlier tree again is the undo — table changes
+and data writes stay.
 
-The other direction: `lotics model pull -o model.json` writes this workspace's model as that same
-file, rebuilt from what owns each part — its tables, how rows are recognised, and each app's body.
+The other direction: `lotics app pull <app_id>` writes an app's tree as a file.
 
 ## Install
 
@@ -125,7 +132,7 @@ lotics auth login a@b.com --local    # pins this directory to that org (implies
 
 A command run before you press Confirm names the page and the code again and exits 1; the request is good for 15 minutes, after which the next command says to ask again. Re-running `auth login` is always safe — it replaces the request, so only the newest code is the live one.
 
-**`lotics auth web`** — Send a magic link email to access the web app (requires prior signup or setup).
+**`lotics auth web`** — Send a magic link email to access the web app (requires prior signup).
 
 ```bash
 lotics auth web
@@ -182,7 +189,7 @@ In a custom-code app's directory, `lotics app deploy` derives the credential fro
 
 ### Diagnostics
 
-Every request identifies the CLI (`user-agent: lotics-cli/<version> node/<v> <platform>`) and names the command that made it (`x-lotics-cli-command: model.apply`), so a failure in the server's logs can be traced to the verb and version that produced it. Neither header carries arguments: the command chain stops before any id, path, `@file`, or JSON payload. It also names what it can do that an older CLI cannot (`x-lotics-cli-capabilities: docs-fallback`), so the server answers in a form it reads: an error names a page as `lotics docs <path>` to a CLI that declares `docs-fallback`, and as `lotics run docs '{"path":"<path>"}'` to any other.
+Every request identifies the CLI (`user-agent: lotics-cli/<version> node/<v> <platform>`) and names the command that made it (`x-lotics-cli-command: app.apply`), so a failure in the server's logs can be traced to the verb and version that produced it. Neither header carries arguments: the command chain stops before any id, path, `@file`, or JSON payload. It also names what it can do that an older CLI cannot (`x-lotics-cli-capabilities: docs-fallback`), so the server answers in a form it reads: an error names a page as `lotics docs <path>` to a CLI that declares `docs-fallback`, and as `lotics run docs '{"path":"<path>"}'` to any other.
 
 **`LOTICS_TELEMETRY=1` additionally records the session.** Off by default. Set it in your shell profile rather than per command — each invocation is its own process. When set:
 
@@ -255,13 +262,13 @@ lotics tools                    # list tools by category with descriptions
 lotics tools query_records      # show full description + input schema
 
 # Execute
-lotics run query_tables '{}'
+lotics run get_workspace '{"kind":"tables"}'
 lotics run query_records '{"table_id":"tbl_...","field_keys":["name"]}'
 
 # Large args (a knowledge-doc `content`, a bulk update) exceed the OS arg limit —
 # read them from a file or stdin instead of an inline arg:
-lotics run create_knowledge @args.json
-cat args.json | lotics run create_knowledge -          # the trailing - reads stdin
+lotics run set_knowledge @args.json
+cat args.json | lotics run set_knowledge -          # the trailing - reads stdin
 echo '{"table_id":"tbl_..."}' | lotics run query_records -
 
 # Upload files (multiple files and directories supported)
@@ -276,10 +283,10 @@ lotics file list --limit 50
 lotics file delete <file_id>          # refused while anything still references it
 
 # CI / non-interactive (key inline)
-LOTICS_API_KEY=ltk_... lotics run query_tables '{}'
+LOTICS_API_KEY=ltk_... lotics run get_workspace '{}'
 
 # One-off against a saved org/workspace, no switching
-LOTICS_ORG=acme LOTICS_WORKSPACE=wks_... lotics run query_tables '{}'
+LOTICS_ORG=acme LOTICS_WORKSPACE=wks_... lotics run get_workspace '{}'
 ```
 
 ## Knowledge docs
@@ -298,7 +305,7 @@ lotics knowledge list --deleted                               # deleted docs you
 lotics knowledge restore kdc_... [kdc_...]                    # bring them back, all or none
 ```
 
-`create` / `update` send the body inline; the server mints and version-chains the content file (and `update` diffs + resolves concurrency internally — no token to pass). `get` is the one content-read path, hydrating the body server-side.
+`create` / `update` are the tool `set_knowledge` (no `knowledge_doc_id` makes a doc, one patches it) and send the body inline; the server mints and version-chains the content file (and `update` diffs + resolves concurrency internally — no token to pass). `get` is the one content-read path, hydrating the body server-side.
 
 ## Custom-code apps
 
@@ -312,14 +319,12 @@ lotics app pull                            # in the project: bring it up to the
 # What the app reads and writes is bound on the app, and each change mints a version:
 lotics run set_app_queries '{"app_id":"app_...","queries":{"openInvoices":{...}}}'
 lotics run set_app_workflow '{"app_id":"app_...","alias":"issueInvoice","source":"..."}'
-lotics run rollback_app '{"app_id":"app_...","version_id":"apv_..."}'   # the undo; data stays
 
 # Running an app's alias is a TOOL call, like every other tool. Exits non-zero
 # when the RUN failed, not only when the call did.
 lotics run run_app_query '{"app_id":"app_abc","alias":"openInvoices","params":{}}'
 lotics run run_app_workflow '{"app_id":"app_abc","alias":"issueInvoice","inputs":{...}}'
 lotics run run_app_workflow '{...}' --print-created   # the records it created + a cleanup plan
-lotics run run_app_agent '{"app_id":"app_abc","alias":"recognize","input":{"image_file_id":"fil_..."}}'
 ```
 
 The app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the project. `lotics tools <name>` prints any tool's input.
@@ -331,7 +336,7 @@ import { LoticsClient } from "@lotics/cli";
 
 const client = new LoticsClient({ apiKey: "ltk_..." });
 
-const { result } = await client.execute("query_tables", {});
+const { result } = await client.execute("get_workspace", {});
 const upload = await client.uploadFiles(["./report.pdf", "./data.csv"]);
 await client.downloadFile(url, "./output.xlsx");
 const { tools, categories } = await client.listTools();