@lotics/cli 0.284.0 → 0.284.1

package/AGENTS.md

@@ -7,12 +7,15 @@ 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>]` | 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 custom-code app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the app. |
+| `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`, then `lotics download` for each PNG. |
 | [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/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 lifecycle workflows. |
 | [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. |
@@ -90,10 +93,10 @@ something exists, read `lotics --help` § COMMANDS — the whole section, not a
   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_query`, `set_app_workflow`, `set_app_agent`, `update_app`, `rollback_app`). A command
+  (`set_app_queries`, `set_app_workflow`, `set_app_agent`, `update_app`, `rollback_app`). 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_*`: each is a new version, and `rollback_app` makes an
+  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,
   so try a write on a throwaway record.
 - **Exit codes are assertable, and they report the WORK rather than the call.** `lotics run` exits

package/README.md

@@ -15,8 +15,10 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
 **`lotics docs`** lists this CLI's references, carried inside it — the model reference and every
 doc below — so a doc always describes the binary answering. `lotics docs <area>` prints one
 (`lotics docs model`). Every answer is capped at a page, so a long doc hands back its section list
-and `lotics docs <area>/<section>`. A custom-code app's SDK reference ships inside
-`@lotics/app-sdk`, in the app's own `node_modules`.
+and `lotics docs <area>/<section>`. A page the CLI's copy lacks — one the server added since, which
+an error can cite — is read from the server, and `lotics docs [<area>] --grep <text>` searches the
+references the server serves; both use this machine's credential. A custom-code app's SDK reference
+ships inside `@lotics/app-sdk`, in the app's own `node_modules`.
 
 **Driving this CLI from an agent? Start at [AGENTS.md](./AGENTS.md)** (`node_modules/@lotics/cli/AGENTS.md`)
 — which surface answers which question, the conventions that hold across every command, and the traps.
@@ -180,7 +182,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.
+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.
 
 **`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:
 
@@ -266,7 +268,7 @@ echo '{"table_id":"tbl_..."}' | lotics run query_records -
 lotics upload ./report.pdf ./data.csv ./documents/
 
 # Generate a file, then download it
-lotics run generate_excel_from_template '{"..."}'
+lotics run generate_document '{"..."}'
 lotics download <file_id> -o ./reports/
 
 # What is in the store, newest first — one page, with the command for the next one
@@ -305,7 +307,7 @@ npm run typecheck && npm run lint && npm test
 lotics app deploy -m "Add quote drawer"    # build + upload a new version of the live app
 
 # What the app reads and writes is bound on the app, and each change mints a version:
-lotics run set_app_query '{"app_id":"app_...","alias":"openInvoices","declaration":{...}}'
+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