@lotics/cli 0.264.0 → 0.267.0

package/AGENTS.md

@@ -9,7 +9,7 @@ conventions are, and where the traps are.
 | `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 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/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) | 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. |
@@ -31,10 +31,9 @@ Several capabilities exist **only** as commands and appear nowhere in `lotics to
 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
 
@@ -65,10 +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 — `model apply`, `model pull`, `workspace doctor` — 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 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.
@@ -80,7 +80,7 @@ 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

package/README.md

@@ -69,8 +69,8 @@ lotics model apply model.json        # an account you already have: the tables,
 ```
 
 `model apply` checks the whole file first — every problem at once — then adopts or creates each
-table (an existing table 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
+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.
@@ -176,6 +176,8 @@ 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: 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.
@@ -226,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 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.
-
 ## Workspaces
 
 Workspaces live inside the active org. If the org has more than one, select before running tools: