@lotics/cli 0.263.0 → 0.266.0

package/AGENTS.md

@@ -7,14 +7,14 @@ 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>]` | Every reference the packages installed beside the project actually ship — `@lotics/app-runtime`, `@lotics/ui` and the document engines each carry their own, and this index only covers THIS package. Discovered by looking, not by a list, so it reports the installed VERSION of each: a doc always describes the code that is really there. 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. |
-| `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. Carried inside this CLI at its own version, since it describes this CLI's model checker, and paged like every doc: the first page is the working order and the section addresses. Two forms: `{"from": "<preset-slug>", "variants", "rename", "entities", "rows", "apply"}`, which names a preset by slug and carries only what this business differs by, and the full one, spelled out, for when no preset is the trade: every top-level key, every field type with the config it needs, the row format, the rules, and a worked example. Offline. It also covers the `apply` list — published packages copied in after the model's own tables, each with an optional `bind` onto them — and the `preset` block a published model carries. `lotics scaffold check` then proves the file — offline, except for the one read a `from` file's preset needs — including every branch of a preset merged onto its base; `lotics setup` applies it and refuses a table name the workspace already has, `lotics scaffold apply` adopts that table and adds what is missing, and the WORKSPACE remembers what each alias became, so every later run binds by id and a relabel on either side is a rename it reports rather than a second table it adds. `lotics scaffold export` goes the other way — a workspace printed as one of these files, to edit into another business's model; a starting point, never a source of truth. |
-| [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE — scaffold, model, types, queries, workflows, screens, ship — and the deploy-free inner loop. The other references describe contracts; this one is the order they go in and why. Read it once before starting an app. |
-| [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas — the detail `--help` compresses. Read it before hand-building a `set_app_*` payload: several tools REPLACE rather than patch, and a CLI verb already owns the safe assembly. |
+| `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 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. |
+| [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. |
+| [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) | How tables RELATE — one entity per table and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied between tables, a copy boundary that accounts for every source field, provenance as a link rather than a flag, a declared natural key so find-or-create never compares rendered text, and why derived DEPTH costs more than row count. Separate from building_an_app because every workspace starts with tables and many never get an app. The within-table half (one fact, one column) is stated at `create_table` / `update_table`, where you meet it while deciding. |
 | [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/migration.md](./docs/migration.md) | What to DO when a release changes the shape of a project this CLI owns. Read once, when something already on disk no longer matches what the CLI writes — for one, an app built from a model is `app.json` version 2, rendered by `@lotics/app-runtime`. |
+| [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. |
 
 ## Two surfaces, and the trap between them
@@ -23,26 +23,25 @@ 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/download/preview, and the whole custom-code app loop (scaffold, pull, deploy, codegen,
-  dev, and running a bound workflow or agent end to end).
+- **Commands** (`lotics --help` § COMMANDS) — the CLI's *own verbs*: auth and org/workspace scoping,
+  file upload and download, and the four that touch a local file for an app — `model apply`,
+  `model pull`, `app create --custom` and `app deploy`.
 
 Several capabilities exist **only** as commands and appear nowhere in `lotics tools` — downloading a
-file and running a bound app agent are the two that most often get mistaken for missing. Concluding
-"the platform can't do X" from the tool list alone is a mistake; check both.
+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 <subcommand> --help` prints the generic top-level help**, except `lotics report --help`
-and a bare `lotics auth`, which print their own. It does not describe the subcommand, so an unhelpful
-response there is *not* evidence the subcommand is absent. To find out whether something exists, read
-`lotics --help` § COMMANDS — the whole section, not a narrow grep.
+**`lotics <verb> --help` prints that verb's entries from § COMMANDS** (`lotics model --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.
 
 ## Conventions that hold across every command
 
 - **Scope is resolved per invocation.** `LOTICS_ORG` / `LOTICS_WORKSPACE` (or `LOTICS_API_KEY`) scope a
   single call without changing the active org or a directory pin — the safe way to touch one tenant
   from a shell serving many. Every command that resolves a workspace echoes its target to **stderr**
-  (`lotics → <org> / <workspace>`); read it back before trusting a write. `file preview <fil_…>` is
-  the one credentialed command with no echo. Resolution precedence is in README § Organizations.
+  (`lotics → <org> / <workspace>`); read it back before trusting a write. Resolution precedence is
+  in README § Organizations.
 - **A machine with no key can still sign in, and the sign-in never blocks you.** `lotics auth
   login <email>` prints the page a person opens (also mailed) and the code that page must show,
   records the request, and EXITS. They press Confirm whenever they get to it; the next command that
@@ -65,11 +64,11 @@ response there is *not* evidence the subcommand is absent. To find out whether s
   profile to remove at all. Nothing is ever revoked on a guess — between two, the destructive one is
   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: the ones that BUILD inside a workspace
-  the key reaches — `scaffold apply`, `library init`, `app upgrade`, `workspace doctor`, `scaffold
-  export`, `field rename` — run 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 a starter or an app's API answer `403` and name the remedy: an admin signed in, so
+  `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
+  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
   them. Do not retry a `403` with the same credential and do not ask for a wider key — no answer on
   the key's own screen grants this.
@@ -81,30 +80,33 @@ response there is *not* evidence the subcommand is absent. To find out whether s
   the generic "Invalid or disabled API key", and that one is generic on purpose, so re-sending it
   teaches nothing. A `reason` rides on the body for a script to branch on, since the code stays
   `unauthorized` for every 401.
-- **Large payloads bypass `ARG_MAX`** — `lotics run <tool> @args.json` or piped stdin. A leading `@` is
+- **Large payloads bypass `ARG_MAX`** — `lotics run <tool> @args.json`, or piped stdin behind `-`. A leading `@` is
   unambiguously a file path (JSON args start with `{`).
 - **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to
   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`). An `app` command exists only for work no
-  tool call can do: scaffold, build, typecheck, serve, or read and push a local file.
+  (`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`, the
+  `sandbox_*` tools). 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
+  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
   non-zero when a `run_app_workflow` or `run_app_agent` result's own envelope carries a failed
   `status` (`error`/`failed`/`cancelled`) — 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.
-- **An app that PUBLISHES an API turns every later manifest write into a release.** `lotics app api
-  publish` snapshots what the app's queries, workflows and agents promise to callers outside it — a
+- **An app that PUBLISHES an API turns every later binding write into a release.** Publishing
+  snapshots what the app's queries, workflows and agents promise to callers outside it — a
   customer's own site or server, which nobody here can redeploy. From then on an additive change
-  re-snapshots silently and a breaking one is REFUSED, naming each change;
-  `--acknowledge-breaking-api` (on `app deploy`, `app query set`, `app workflow set`,
-  `app agent set`, `app upgrade`) is the answer that carries it out and snapshots the break as a new
-  contract version. An app that publishes nothing is untouched by any of it.
+  re-snapshots silently and a breaking one is REFUSED, naming each change; the tool's
+  `acknowledge_breaking_api_change` carries it out and snapshots the break as a new contract version.
 - **Exposure is per app, all or nothing** — a public share or a key reaches every alias an app
-  declares, so what outsiders may call is a second app over the same tables, scaffolded with
-  `lotics app create "<name>" --api` ([docs/building_an_app.md](./docs/building_an_app.md) § 9).
+  declares, so what outsiders may call is a second app over the same tables
+  ([docs/building_an_app.md](./docs/building_an_app.md) § 7).
 - **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the
   records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs
   those deletes (records only — never files, integrations or notifications). Neither is a rollback.
@@ -126,29 +128,7 @@ response there is *not* evidence the subcommand is absent. To find out whether s
 
 ## Where this CLI is not the answer
 
-- **Authoring a binding via `app deploy`.** Deploy ships code, queries, and capabilities — it never
-  authors bindings. Workflow bodies go through `app workflow set`, agent instructions through
-  `app agent set` (both edit a file on disk that `app pull` wrote from the live row). A binding's TYPED
-  half — an agent's `tool_names`/`inputs`/`outputs`, a workflow's schemas — is authored by the
-  `set_app_*` tools. A manifest alias with no server binding only fails at the app's first call, so
-  deploy warns about the mismatch.
-
-  **The four `lotics.*` keys look alike and point in three different directions.** Before editing one,
-  know which you are touching — this is the single most expensive thing to get wrong in a manifest:
-
-  | `lotics.<key>` | Owned by | Your edit reaches the app via |
-  |---|---|---|
-  | `queries`, `capabilities` | the manifest | `app deploy` — re-synced on every one (an absent `capabilities` block turns them all OFF) |
-  | `knowledge` | the manifest | nothing, until the app is published as a starter — it declares which docs ship with it |
-  | `workflows` | the workflow row's verified contract | `app workflow set`, which type-checks the BODY against your declaration and refuses a schema the body cannot satisfy |
-  | `agents` | `inputs`/`outputs`: the manifest. Everything else: the app row | `app agent set`, and `app deploy`, which pushes a diverged `inputs`/`outputs` before it ships. The rest is a mirror `app codegen` re-silvers, changed with `set_app_agent` |
-
-  `agents` is the one that bites, because the two halves of the same block behave differently:
-  editing `tool_names` or `knowledge_doc_ids` still retypes `useAgentRun` — green locally, unchanged
-  in production, and reverted by the next `app codegen`. An agent's PROSE is not in the manifest at
-  all: it lives in `src/agents/<alias>.md` and is pushed by `app agent set`.
-- **Editing a local `.xlsx` / `.docx`.** A library call, not a verb: script `@lotics/xlsx` /
-  `@lotics/docx` (`lotics docs xlsx` / `lotics docs docx` prints the installed copy's API guide).
-  `lotics file preview` draws the result so it can be looked at.
+- **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
+  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.
-- **Anything needing a browser.** `app dev` and `file preview` shell out to a local Chrome.

package/README.md

@@ -12,13 +12,11 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
 
 ## Capability guides
 
-**`lotics docs`** lists every reference the packages installed beside your project ship — each
-`@lotics/*` package carries its own, so a doc always describes the version you actually have.
-`lotics docs <area>` prints one (`lotics docs ai`); `lotics docs ui` prints a package's index.
-Every answer is capped at a page, so a long doc hands back its section list and
-`lotics docs <area>/<section>` — or, for a doc that is one table, `lotics docs ui/catalog/Button`.
-Nothing is copied here — the packages, the areas, the titles and the versions are all read at run
-time, so a doc or a whole package added upstream shows up without upgrading this CLI.
+**`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`.
 
 **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.
@@ -28,86 +26,57 @@ 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/building_an_app.md`](docs/building_an_app.md) — building a custom-code app end to end:
-  the sequence the steps go in (clarify → model → types → queries → workflows → screens → ship)
-  and the deploy-free inner loop. Read it once before starting an app.
+- [`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
+  `@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
   create → generate → chain lifecycle, and the marker capabilities.
-- [`docs/migration.md`](docs/migration.md) — what to do when a release changes the shape of a
-  project this CLI owns; read once, when something on disk no longer matches what the CLI writes.
+- [`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.
 
-## Start from the library, in one command
+## Start in one command
 
-Install the CLI, then copy a starter — it creates the account, copies the starter into its
-workspace, deploys its apps, and prints a one-time sign-in link:
+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:
 
 ```bash
 curl -fsSL https://lotics.ai/install.sh | bash
-lotics setup <starter_id> --email you@company.com
+lotics setup model.json --email you@company.com
 ```
 
-The installer downloads one compiled executable — no Node.js, no npm, and copying a starter needs
-neither: every app is deployed on Lotics and nothing is written here. Node 18+ comes in only when
-you pull an app's source to change it (`lotics app pull <app_id>`) and build it to deploy again.
+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, what was created, the sign-in link, and any warnings. Already signed in?
-Drop `--email` and `lotics setup <apg_id>` copies into the account you have.
-
-`lotics library list` reads both shelves with no account at all. **Presets** are a trade's model,
-named by a slug: read one and write a `model.json` from it — nothing is copied. **Packages** are
-apps and the tables they stand on, named `apg_…`, copied in whole; each row names how many tables
-and which apps a copy creates, so what you actually manage can be matched against them.
-`lotics library show <slug|apg_id>` reads one, with no account either — each table as
-`alias · label`, each field as `alias:type`, and a preset's variants beside the sentence that
-selects each.
+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.
 
-## Or describe your own workspace
+## 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; `lotics setup` builds the tables. **Start from a preset when one is your trade** — name it instead of
-restating it:
-
-```json
-{
-  "from": "field_service",
-  "variants": ["crews"],
-  "rename": { "job": { "label": "Jobs", "fields": { "code": "Job no." } } },
-  "rows": { "job": [{ "ref": "j1", "fields": { "code": "J-1" } }] }
-}
-```
-
-No preset is your trade? Write the full form instead, spelling the tables out. Either way:
+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.
 
 ```bash
-lotics docs model                    # how to write one, both forms, with a worked example. Offline
-lotics scaffold check model.json     # prove it — every problem at once, offline unless it names a preset
-lotics setup model.json --email you@company.com
+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
 ```
 
-It creates no apps of its own: build one in the workspace afterwards
-(`lotics docs building_an_app`), or name a published package in the file's `apply` list and it is
-copied in — bound onto the tables the model just made — as part of the same run.
-For a model that declares apps, `lotics workspace build model.json` is the whole path in one
-command — check, apply where the workspace differs, then create or regenerate each app beside the
-model file and check it, deploying each under `--deploy`. An app that conflicts or checks red is
-named and the rest still run; `--dry-run` writes nothing anywhere.
-`setup` refuses a table name your workspace already has; `lotics scaffold apply model.json` is the
-additive verb — it adopts that table, adds what the model declares beyond it, and deletes nothing.
-Because it never renames, the file and the workspace drift: `lotics scaffold diff model.json`
-prints exactly where and exits non-zero on any difference, and
-`lotics field rename <table> <field> "<new label>"` moves a label on the platform, in the file
-(`--model`) and in every app bound to it (`--apps`) at once. `lotics scaffold apply model.json
---documents` writes only the file cells of the model's rows, onto the records the first run made —
-rows land only into empty tables, so it is the one way back for attachments that were missed.
-
-The other direction, once a workspace works: `lotics scaffold export > model.json` prints its
-tables (or only `--tables tbl_a,tbl_b`) as that same file, findings on stderr. It is a starting
-point for the next business, never a source of truth — the labels are this one's.
+`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 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.
 
 ## Install
 
@@ -207,9 +176,11 @@ Every command that resolves a workspace names its target before it acts — `lot
 
 **`LOTICS_ORG` is resolved once, before any command runs.** A value matching no saved credential refuses every verb with one sentence — a read, a write, and a check that needs no credential alike — and the refusal lists the orgs this machine does hold, so it is answerable without another command. It refuses even when a key arrives another way: a variable that scopes the command must not go unread while `LOTICS_API_KEY` sends the write somewhere else. When the variable resolves AND a key is supplied, the key decides the org and the command says so. An org keeps the name it was saved under: a server-side rename never moves it, the new name resolves as well, and `lotics org` prints both when they differ.
 
+In a custom-code app's directory, `lotics app deploy` derives the credential from the directory when nothing explicit chose one: the manifest names the app's workspace, and when exactly one saved profile owns that workspace, that profile is used — the machine-wide default is never consulted. An explicit flag, env var, or directory pin still wins, and an org whose profile remembers a different workspace simply falls through to the announced default.
+
 ### 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: app.workflow.set`), 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.
 
 **`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:
 
@@ -257,8 +228,6 @@ needs an opt-in for), posts immediately, and tells you if it did not land.
 
 Do not paste records, file contents, or credentials.
 
-In an app project, `lotics app *` commands derive the credential from the directory when nothing explicit chose one: the manifest names the app's workspace, and when exactly one saved profile owns that workspace, that profile is used — the machine-wide default is never consulted. An explicit flag, env var, or directory pin still wins, and an org whose profile remembers a different workspace simply falls through to the announced default.
-
 ## Workspaces
 
 Workspaces live inside the active org. If the org has more than one, select before running tools:
@@ -311,21 +280,6 @@ LOTICS_API_KEY=ltk_... lotics run query_tables '{}'
 LOTICS_ORG=acme LOTICS_WORKSPACE=wks_... lotics run query_tables '{}'
 ```
 
-## Local .xlsx and .docx files
-
-Edit them by scripting Lotics's own engines, published as `@lotics/xlsx` and `@lotics/docx`. Prefer them over `xlsx` / `exceljs` / `docx` from npm: they round-trip faithfully with the Lotics editor, template engine, and formula engine. `npm i @lotics/xlsx @lotics/docx`, then read the API guide that ships inside the package: `lotics docs xlsx` / `lotics docs docx` prints the installed copy (`node_modules/@lotics/<pkg>/AGENTS.md` on a machine with no CLI). Both packages ship `.ts` sources as their entry, so run the script under a TypeScript-aware runner.
-
-```ts
-import { readFile, writeFile } from "node:fs/promises";
-import { parseDocx, replaceText, serializeDocx } from "@lotics/docx";
-
-const { doc, count } = replaceText(await parseDocx(await readFile("in.docx")), "{{name}}", "Acme Ltd.");
-if (count === 0) throw new Error("{{name}} is not in this document — nothing written");
-await writeFile("out.docx", await serializeDocx(doc));
-```
-
-`lotics preview <file.xlsx|.docx>` draws one of those files to a PNG with the same engines, so a script's output can be looked at rather than guessed at.
-
 ## Knowledge docs
 
 A file-native surface over the workspace's knowledge docs — the AI's rulebook layer. The body is a Markdown file: `create`/`update` read it from your filesystem, `get` writes it back. See [`docs/knowledge_docs.md`](docs/knowledge_docs.md) for the model.
@@ -345,135 +299,25 @@ lotics knowledge rm kdc_...                                   # archive
 ## Custom-code apps
 
 ```bash
-# SEE THE APP BEFORE IT EXISTS. The model's app is compiled against the workspace the
-# model WOULD become and every read is answered from the model's own `rows` (a few
-# synthesized for an entity that states none), so there is no app row, no table and
-# no credential in the run — then the same headless walk `app check --screens` takes,
-# at the same two widths, measured by the same probes: the register, the record in
-# its door, the add. Exits 1 on any finding and prints what each phase cost. It
-# renders in the cached project of its dependency set (`~/.lotics/render/`, shared
-# with `app check --screens`), installed once from the registry — the kit and the
-# runtime are published packages — and rewritten from the model on every run.
-lotics app preview model.json#sales_desk
-lotics app preview model.json#sales_desk --shots ./shots --width 375
-
-# Scaffold / pull / deploy a Vite+React+TS app project
-lotics app create "Sales Desk"            # scaffold + deploy v1
-lotics app create "Sales Desk" --from model.json#sales_desk   # the model's app, as app.json
-lotics app create "Orders API" --api       # no screens: its declarations are the whole surface,
-                                           # so nothing is built and nothing is deployed
-lotics app pull app_...                    # bootstrap an existing app locally (incl. .lotics/*)
-lotics app deploy -m "Add quote drawer"    # typecheck + build + upload a new version
-lotics app versions                        # deploy history: version, when, who, -m message (* = live)
-lotics app versions app_...                # ...for any app, without pulling it first
-
-# Apply the latest version of the package this app was COPIED from. Additive on
-# the schema; a workflow or agent you have edited here is kept and named, and so
-# is a field the new version stopped declaring. Redeploys from the published
-# dist, so nothing local is sent — pull afterwards to edit the new code.
-lotics app upgrade                         # the app this directory's manifest names
-lotics app upgrade app_...                 # ...for any app, without pulling it first
-
-# The app's API: what its declared queries, workflows and agents promise to a
-# caller OUTSIDE the app — a customer's own site or server. Publishing snapshots
-# that promise as a numbered contract; from then on a manifest write that would
-# break it is refused and every breaking change is named, unless the write carries
-# --acknowledge-breaking-api (app deploy / app query set / app workflow set /
-# app agent set / app upgrade). A query that does not name the columns it returns
-# is refused at publish: those field names are the table's, not the app's to
-# promise.
-lotics app api publish                     # snapshot the contract; prints the version + warnings
-lotics app api status                      # is one published, and which version callers hold
-lotics app api spec -o api.openapi.json    # the OpenAPI 3.1 document, for the consumer's generator
-lotics app api unpublish                   # end the promise
-
-# Regenerate .lotics/* WITHOUT a deploy: the .d.ts type companions (always) +
-# the runtime app_fields.ts (when authenticated) — F/OPT maps that address
-# fields + select options by stable display-name aliases instead of opaque ids.
-# `app pull` writes both too (a deploy archive can never carry app_fields.ts);
-# use this after a rename, or when a pull ran offline.
-lotics app codegen                         # import { F, OPT } from "../.lotics/app_fields"
-
-# Install @lotics/app-runtime from your CHECKOUT, to prove a change on a real app
-# before it is published: build, pack into .lotics/kit/, install by file
-# specifier, then hash one built file on both sides — a repack under the same name
-# is otherwise served from the lockfile's first tarball. `app check` warns and
-# `app deploy` refuses (--allow-local-kit ships it anyway), because that tarball is
-# not in the source archive. --published puts back the range the app listed before
-# the first checkout (an app with none recorded moves to the registry's). Either
-# keeps @lotics/ui at the runtime's range and migrates an app on @lotics/app-sdk.
-lotics app kit ../lotics/packages/app-runtime
-lotics app kit --published
-
-# Every deploy pre-flight, WITHOUT the build or the version row: the app's own
-# typecheck over regenerated .lotics types, agent schemas vs the live app, aliases
-# the code calls that nothing bound, undeclared capabilities, query drift. Exits 1 on what a deploy refuses, so CI can gate on it.
-lotics app check
-
-# --screens adds the rendered surface: each screen the app's navigation reaches,
-# and the first record each one opens onto a PAGE, headless in Chrome at 1280
-# and 375, measured against @lotics/ui docs/reviewing.md. --screen and --width
-# narrow it while you iterate on one screen. It renders in the cached project of the
-# app's dependency set (~/.lotics/render/, shared with app preview) and prints what
-# each phase cost. --changed walks only when something the screens read has moved
-# since this checkout's last walk (.lotics/screens_check.json), and otherwise
-# reprints that walk's report.
-lotics app check --screens
-lotics app check --screens --screen "Đơn hàng" --width 375
-lotics app check --screens --changed
+lotics app create "Sales Desk" --custom    # the app, plus a Vite + React + TS project on @lotics/app-sdk
+cd "Sales Desk"
+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_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_workflow '{"app_id":"app_...","alias":"issueInvoice","inputs":{"record_id":"rec_..."}}'
-cat args.json | lotics run run_app_workflow -  # bulk inputs bypass ARG_MAX
-# Honest post-run harvest: created records + a paste-ready cleanup plan + the
-# caveat (external/notification calls can't be auto-undone; sub-workflows may run).
-lotics run run_app_workflow '{...}' --print-created
-lotics run run_app_workflow '{...}' --cleanup   # also deletes created records (NOT a rollback)
-
-# Edit workflow bodies as files. `app pull` writes src/workflows/<alias>.ts (the
-# faithful server source, wrapped + referencing its .lotics/workflows/<alias>.globals.d.ts);
-# edit the body, then push it back through set_app_workflow — the server verifies it
-# (a deploy calls the same verb for every alias the project holds ahead of the app, so
-# this is the one-alias spelling of it). `app workflow check` runs the server's own
-# JS-subset parser + type-check locally, then asks the server for every check `set`
-# makes (`verify_only`, nothing written), so a body that passes is one `set` will accept:
-lotics app workflow pull                    # rewrite src/workflows/*.ts + globals from the server
-lotics app workflow check                   # every check `set` makes, writing nothing ([alias...] for some)
-lotics app workflow diff issueInvoice       # how the local body differs from the one the server runs
-lotics app workflow set issueInvoice        # push the edited src/workflows/issueInvoice.ts
-
-# Iterate on a named query WITHOUT a deploy: push package.json#lotics.queries.<alias>
-# to apps.queries (server-validated like a deploy). apps.queries is manifest-
-# authoritative, so the next `app deploy` re-syncs it — keep the manifest current.
-lotics app query set openInvoices           # push package.json#lotics.queries.openInvoices
-lotics app query run openInvoices --params '{"customer":"rec_..."}'  # the bound query's rows, as a screen gets them
-
-# Move one alias out of this app and into another of the same workspace — the
-# declaration (and a workflow's body) land in the target project, the target is
-# bound to its OWN row, and the source is unbound and undeclared here. No release
-# either side. Run it in the source project; refused while anything here still
-# calls the alias, unless you say --even-if-invoked.
-lotics app query move openInvoices --to ../ke-toan
-lotics app workflow move issueInvoice --to ../ke-toan
-
-# Run a bound app agent end-to-end (no deployed UI needed — app row + declaration
-# + member auth). Streams progress to stderr; reports the SETTLED run (structured
-# output / final text) to stdout; exits 0 only when the run completed.
+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_..."}}'
-cat input.json | lotics run run_app_agent -          # inputs via stdin/@file
-lotics run run_app_agent '{...}' --json              # full run summary to stdout
-# A run that outlives the call's bounded wait keeps going server-side; read it with
-lotics run get_app_agent_run '{"app_id":"app_abc","run_id":"run_..."}'
-
-# Dev-link @lotics/ui to a monorepo checkout for ONE command — nothing hand-written is touched
-# (the matching tsc `paths` land in the CLI's own .lotics/tsconfig.link.json)
-LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app dev
-LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app deploy -m "..."   # warns: bundles YOUR kit copy
-lotics app dev                             # unset ⇒ @lotics/ui resolves from node_modules again
 ```
 
-`app codegen` puts a table in `app_fields.ts` when a declared query reads it or a bound workflow writes it — the queries come from `package.json#lotics.queries`, the written tables from each binding's own `table_ids`, so a table only a workflow body touches is addressable by alias with nothing to declare.
+The app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the project. `lotics tools <name>` prints any tool's input.
 
 ## SDK