@lotics/cli 0.136.1 → 0.142.0

package/dist/src/client.d.ts

@@ -167,6 +167,26 @@ export declare class LoticsClient {
         organization_id: string;
         organization_name: string;
     }>;
+    /**
+     * File a hand-written report. Unlike a telemetry flush, the headers this
+     * stamps are CORRECT: the invocation making the request is the one the report
+     * is about, so the courier and the cargo are the same session.
+     */
+    sendReport(body: {
+        report: {
+            goal: string;
+            actual: string;
+            expected?: string;
+            tried?: string;
+            wanted?: string;
+        };
+        cli_session_id: string | null;
+        cli_version: string;
+        workspace_id?: string;
+        app_id?: string;
+    }): Promise<{
+        accepted: true;
+    }>;
     setWorkspaceId(id: string): void;
     /** The workspace id the client targets (the `x-workspace-id` header), if resolved. */
     getWorkspaceId(): string | undefined;

package/dist/src/client.js

@@ -122,6 +122,14 @@ export class LoticsClient {
     async whoami() {
         return this.request("GET", "/v1/cli/whoami");
     }
+    /**
+     * File a hand-written report. Unlike a telemetry flush, the headers this
+     * stamps are CORRECT: the invocation making the request is the one the report
+     * is about, so the courier and the cargo are the same session.
+     */
+    async sendReport(body) {
+        return this.request("POST", "/v1/cli/report", body);
+    }
     setWorkspaceId(id) {
         this.workspaceId = id;
     }

package/docs/building_an_app.md

@@ -0,0 +1,229 @@
+# Building an app, end to end
+
+The other references here describe **contracts** — what a query may express, what a workflow body
+may say, which props a component takes. This one describes the **sequence**: the order the steps go
+in, and why that order and not another. Read it once for the shape, then reach for the area doc
+(`lotics docs`) whenever you need the detail.
+
+Everything below is deploy-free until the last step. That is the point: a deploy is a release, and
+using one to find out whether something works is the slowest possible way to learn it.
+
+---
+
+## 1 — Scaffold, or pull what exists
+
+```
+lotics app create "<name>"          # new: a real Vite + React + TS project, deps installed
+cd <dir> && lotics app pull <app_id>   # existing: refresh to the latest first, then read its README
+```
+
+A pull writes more than source: one `src/workflows/<alias>.ts` per bound workflow, one
+`src/agents/<alias>.md` per bound agent, and the `.lotics/` type companions — so an existing app
+arrives fully editable rather than as an archive you have to reconstruct.
+
+## 2 — Clarify what is being asked, before modelling it
+
+**A metric name is not a definition.** "Revenue", "in stock", "active", "overdue" — each is a
+business rule the person asking owns, and the cost of guessing is a screen that is confidently
+wrong. Ask until there is no ambiguity left:
+
+- Which rows count, keyed off which field — a date, a status, a flag?
+- Does the same metric need a **different rule per table**? One table may key off a date and
+  another off a status; one rule rarely covers both.
+- Snapshot or flow? "Current stock" is as-of-now; "revenue this month" is a window. They compile
+  to different filters.
+- If the data cannot support the definition asked for — the field simply is not there — **say so
+  and show the options.** Silently substituting a near-miss produces a number nobody can trace.
+
+This is the step that gets skipped under time pressure, and it is the only one whose mistakes are
+invisible in review: every later artifact is correct with respect to the wrong definition.
+
+## 3 — The data model, before any code
+
+Get this wrong and nothing above it can be precise. Each entity is its own table with
+`record_link`s into the spine; attributes and evidence are fields on their owner. A single table
+with a `type` column standing in for three entities collapses the distinctions every later query
+needs.
+
+**Verify real VALUES, never just that a field exists.** `lotics run query_records` a sample and
+look at fill rates — a field that is present and empty on 90% of rows will not support the screen
+you are about to design.
+
+## 4 — Typed field access
+
+```
+lotics app codegen        # no deploy, no version bump
+```
+
+Regenerates `.lotics/`: the three `.d.ts` companions that type `useQuery` / `useWorkflow` /
+`useAgentRun`, and — when credentials resolve — `app_fields.ts`, exporting `F` (table → field →
+`"fld_…"`) and `OPT` (table → select field → option → `"opt_…"`) keyed by display-name aliases.
+
+Address fields by alias, never by a pasted id:
+
+```tsx
+row.opt(r[F.SHIPMENT.direction]) === OPT.SHIPMENT.direction.export
+```
+
+A rename in the platform then moves your call sites when you re-run `codegen`, and a stale alias
+fails `tsc` instead of failing at runtime. **Re-run after any schema change** — local typecheck is
+only honest if the generated ids are current, and you never deploy to refresh types.
+
+## 5 — Named queries
+
+Author them as `kind: "project"` with a `filter`. A bare `from_table` over-exposes columns and
+degrades at scale. Scope per-user reads with `is_current_member` **inside the template** — a
+`member_id` passed from the client is an IDOR, since the caller chooses it.
+
+Decode cells with the `row.*` helpers (`row.text`, `row.opt`, `readSelect`, `readLinks`), never by
+reaching into the raw shape: a select cell is `[{key,label}]`, and a hand-rolled reader silently
+returns the wrong half.
+
+Iterating a query needs no deploy either:
+
+```
+lotics app query set <alias>     # pushes package.json#lotics.queries.<alias>, server-validated
+```
+
+Details: `lotics docs queries`.
+
+## 6 — Workflows, the only way an app writes
+
+A workflow body is a file you open and edit. The new-alias path is typed from the first line:
+
+1. Declare it in `package.json#lotics.workflows.<alias>` — its `inputs`, and `outputs` only to
+   narrow beyond what the body infers.
+2. Write `src/workflows/<alias>.ts`.
+3. `lotics app codegen` — the dts is generated **from your declaration**, so the body gets real
+   types (`trigger.app_workflow.inputs.*`, the tool globals) before the alias is bound at all.
+4. `lotics app workflow check` — runs the server's own parse and typecheck locally. It catches the
+   JS-subset rejections that read as ordinary TypeScript: a `function` declaration, a typed
+   parameter, `push` on a const. Those otherwise cost a full push round trip.
+5. `lotics app workflow set <alias>` — the server re-verifies (parse → typecheck → resolve names →
+   lint → structural validate).
+
+`outputs` are declared, else **derived** from `return({ status, message, data })` — so a workflow
+that returns an id must keep its `data` clause or the app receives nothing. When derived, `set`
+writes the schema back into the manifest and refreshes that alias's types in place.
+
+The alias's `description` rides along from the manifest. It is the one line an agent reads when
+choosing between your workflows, so write it rather than leaving the generated placeholder.
+
+**Static green is not a run.** `check` and `set` prove parse, types, name resolution and lint —
+they evaluate nothing. Rehearse before the first live run:
+
+```
+lotics run dry_run_workflow '{"trigger_type":"app_workflow","trigger_payload":{…},"live_reads":true}'
+```
+
+It walks the real step tree and returns the resolved plan plus expression and tool-input errors,
+dispatching no write. Pass the raw body — the file carries a wrapper that `set` strips and this
+tool does not. **`live_reads: true` matters whenever the body reads anything**: without it every
+read returns a stub, so a duplicate check finds no duplicate and every data-gated branch takes the
+empty path — green, and proving nothing about the branch you care about.
+
+Then prove it end to end without a screen:
+
+```
+lotics app workflow run <alias> '<json>'    # exits non-zero on error, so it is assertable
+```
+
+A workflow is also how an app **produces a document** — an invoice, a debit note, a shipping
+label. The `generate_*_from_template` tools fill a template you registered once, and the file
+comes back to the app on `result.files[]`, **not** through `return({ data })`; that channel
+carries values, never files. Registering the template is a CLI job, not an app one:
+`lotics docs document_templates`.
+
+Authoring rules for the body itself: `lotics docs workflows`.
+
+## 7 — Screens
+
+**Before any JSX**, read `lotics docs ui` and the kit's `examples/` — the catalog, the composition
+grammar, and the worked `tpl_*` screens. Reuse the template that matches; if the pattern is
+genuinely missing, build it as a kit component rather than a local one-off, or the next screen
+re-derives it differently.
+
+Two rules that cause most of the rework:
+
+- **Never copy server data into `useState`.** Derive from `useQuery` / `useWorkflow` with
+  `useMemo`; a copy goes stale the moment anything else writes.
+- **Design the loading, empty and error states.** Reserve their space so the layout does not jump.
+
+## 8 — Run it locally, and prove it
+
+```
+lotics app dev
+```
+
+Vite plus an RPC-forwarding server, in a sandboxed iframe matching production, with real data and
+auth and HMR. File flows work too — the dev server relays the bytes, so upload, preview and
+download are all exercisable locally.
+
+Deploying to find out whether a change worked is the smell this step exists to remove.
+
+**Drive it with a browser, in this order** — each step's failure means something different:
+
+1. **Does it render at all?** A blank iframe is almost always a bundling problem, not your code.
+2. **Read the console before the DOM.** A React error boundary shows a blank region; the reason is
+   only in the console.
+3. **Does the data arrive?** Check the query result before blaming the layout — an empty list and a
+   broken list look identical.
+4. **Then interact.** Click the real control rather than calling the handler: an element that is
+   covered, disabled, or outside the viewport fails only under a real click.
+
+**Everything inside the app is a separate frame.** The app renders in a sandboxed iframe served
+from a different port, so it is cross-origin to the wrapper: parent-page JavaScript cannot reach
+`contentDocument`, and a selector run against the page finds nothing. Address it through the frame
+— `page.frameLocator("iframe")`, or the frame refs an accessibility snapshot gives you — and run
+any injected script in the frame's own context, or its `window` and coordinates are the wrong ones.
+
+Three kit anatomies then need driving deliberately rather than clicked: a pressable row's named
+button always intercepts pointer events, overlays portal to the top of the DOM, and custom pointer
+drag ignores `dragTo`. All three are by design and all three read as bugs — `lotics docs testing`.
+
+Read a failure by what it *cannot* be. A control that takes its value while its list never appears
+is not a wiring bug — the list is rendered somewhere the harness cannot see. Assert what the DOM
+actually carries, not what the source says it should.
+
+## 9 — Verify, then ship
+
+```
+npm run typecheck && npm run lint && npm test
+lotics app check                     # every pre-flight a deploy runs, without building or shipping
+lotics app deploy -m "<what changed + why>"
+```
+
+`-m` is optional; the deploy derives a message from what it pushed. Write one when the *why* is
+worth keeping.
+
+Then set the icon and colour — the most-forgotten step, and the deploy warns when they are unset:
+
+```
+lotics run update_app '{"app_id":"…","icon":"<lucide-name>","theme":{"color":"blue"}}'
+```
+
+Finally, update the app's own `README.md` on any model or behaviour change and redeploy, so the
+brief travels with the app rather than living in whoever built it.
+
+---
+
+## The inner loop
+
+Once scaffolded, everything below happens locally:
+
+```
+edit src/workflows/<alias>.ts        # or a screen, or a query
+lotics app codegen                   # after any schema change
+npm run typecheck                    # honest, because codegen is current
+lotics app workflow run <alias> …    # prove the mutation path
+lotics app dev                       # prove the screen
+…
+lotics app workflow set <alias>      # push the body; the server verifies
+lotics app deploy -m "…"             # pushes pending bindings, then ships
+```
+
+A deploy pushes any workflow body, agent prose or query that is ahead of the app **before** it
+ships the bundle, so forgetting a `set` no longer ships a bundle typed against a binding that does
+not exist. `lotics app check` reports the same set without pushing.
+
+Keep the CLI current: an old one silently drops manifest fields it does not model.

package/docs/cli_reference.md

@@ -33,7 +33,11 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app deploy -m <message>` | `-m` is OPTIONAL — omitted, the deploy derives the version message from what it actually pushed. Requiring it was the most common real failure in CLI telemetry, and a hard stop yields a retry plus filler rather than an audit trail; pass `-m` when you have a reason worth recording. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. **One command ships everything**: before the bundle moves, a deploy pushes every binding the project has ahead of the app — an edited workflow body or declaration, edited agent prose, a changed query — through `set_app_query`, then `set_app_workflow`, then `set_app_agent`, and fails the release if any push is refused. That order is required: an agent declares the query and workflow aliases it may call, so pushing it before its own new query is refused. A workflow's `description` is part of that push and is compared against the recorded baseline, not the live app — it lives on the workflow ROW, which `getApp` does not carry, so checking it live would cost one request per alias inside a deploy. It never AUTHORS a binding itself — those verbs stay the single writers — and each push carries the fingerprint the project last saw live (`lotics.synced`), so a stale checkout is refused rather than overwriting another author's edit. `package.json` means the same thing for both artifacts: editing `lotics.agents.<alias>.inputs`/`outputs` is pushed exactly like the workflow equivalent (only those two fields — `set_app_agent` merges, so everything the manifest does not model is left untouched). It also regenerates `.lotics/app_fields.ts` before building, since the build INLINES it and which form is correct follows from whether the app is a package installation — a deploy that skipped it could ship an origin's baked ids into every other install. `lotics app check` reports the same set without pushing; neither has a `--strict`. What the version RECORDS as the aliases it calls — the set `remove_app_workflow` / `remove_app_query` / `remove_app_agent` consult to refuse unbinding one the served version still reaches — is read by the SERVER out of the source archive this deploy uploads, not reported by the deploy. That matters because the deploy is also what unbinds: a client supplying the evidence used to refuse its own removal cannot be checked by it, and the guard is now independent of which CLI ran. After a successful deploy it warns about any alias the source CALLS that is NOT bound, and **unbinds the inverse** — bindings the app still serves that this bundle names nowhere. No flag: an orphan is a live, callable read path under the deployer's authority, and a deploy that adds bindings automatically but requires a decision to remove one just accumulates them. Unbinding runs AFTER the version is live, because the removal tools refuse an alias the SERVED version still declares — so doing it first is refused by the guard that makes it safe. It is skipped ENTIRELY (with a warning, never a failure) when the source computes an alias at run time, since the scan cannot tell which binding that reaches; that is the only case where the reference set is incomplete, because a binding is reachable from the bundle and from an agent's `query_aliases`/`workflow_aliases` and from nothing else — an app workflow carries no `on({...})` trigger, so no table event or schedule reaches one. A binding that will not unbind is reported and does NOT fail the release: the version is live and correct, and the leftover is the state every deploy left behind before this existed. |
 | `lotics app versions [app_id]` | `GET /v1/apps/{id}/versions` — print deploy history newest-first (version number, timestamp, deployer name, build status, the `-m` message; `*` marks the currently-served version). app_id from the local manifest, or pass one to inspect any app without pulling it. Admin-only server-side (mirrors deploy + source download). Answers "what shipped, when, by whom" — e.g. whether a fix was live at an incident's time. The deploy pipeline already persisted all of this in `app_versions`; this is the read surface. Title → stderr, table → stdout (pipeable). |
 | `lotics app codegen [path]` | Regenerate `.lotics/*` from the manifest + workspace schema **without a deploy**. The three `.d.ts` companions (`app_{workflows,queries,agents}.d.ts`) are always rewritten (synchronous, no network). When credentials resolve, also rewrites the **runtime** `.lotics/app_fields.ts` — **branched on whether the app is a package installation** (`getApp().package_id` set, from `generate_package_fields.ts`): a **linked/published** app emits the BINDING form (`F`/`OPT`/`ROLE` resolved from the installation's LIVE binding — via `appBinding` / the `binding` RPC — at module load through `getAppBinding()` + top-level await, so the source stays portable across every install); a **bespoke** app emits the BAKED form (`generate_app_fields.ts`) — a real `.ts` exporting `F` (table→field→`"fld_…"`) + `OPT` (table→select-field→option→`"opt_…"`) keyed by display-name aliases, for the tables the app's queries reference (+ optional `package.json#lotics.codegen.tables` allowlist). Both forms share the `F`/`OPT` shape (contract aliases derive from the same slugified display names), so a published origin's deployed source compiles unchanged. Writing the BINDING form also heals the project's vitest setup (`ensureAppVitestSetup`, folded into the same write boundary): the binding form awaits `getAppBinding()` (a network call) at module load, so without a stub `npm test` fails to collect any test that imports the app graph — the heal writes `vitest.setup.ts` (mocks only `getAppBinding`, returning an echo binding: any alias → a self-identifying `fld:test:…`/`opt:test:…`/`grp:test:…` id) if absent, and warns the one-liner to add to `vite.config.ts`'s `test.setupFiles` if the wiring is missing (TS source isn't safely munged, mirroring `ensureAppTsconfig`'s JSONC-tsconfig warn). New scaffolds ship both. Also refreshes each bound workflow's `.lotics/workflows/<alias>.globals.d.ts` + re-wraps its EXISTING `src/workflows/<alias>.ts` body in the current envelope (strips + re-wraps; never re-fetches the body, so local edits survive). **`.lotics/` is reconciled to the manifest, not merely added to** — a `<alias>.globals.d.ts` whose alias the manifest no longer declares is DELETED (that directory is read as the app's alias inventory, so a companion for a binding nobody can reach misreports what the app has). Only that exact filename shape is removed; anything else in the directory is left alone. The reconcile runs before the credential branch, so it happens offline too. The authored counterpart is never deleted — a `src/workflows/<alias>.ts` the manifest does not declare is NAMED instead (`check` and `set` both take their alias set from the manifest, so editing an undeclared body is a silent no-op). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). **Re-silvers `package.json#lotics.agents`** from the live app row whenever its `inputs`/`outputs` disagree, then rewrites the agent `.d.ts` from the refreshed block: that block is a mirror AND the offline seed for `useAgentRun` typings, so a stale copy types the app against an agent that does not exist. Refreshing here makes the divergence self-healing on a command already in the loop and keeps the remedy off `app pull` (which rewrites `src/workflows/*.ts` and would eat uncommitted body edits). The write is surgical and order-preserving (`orderedLike`), so it changes only the fields that actually differ. A hand edit to that block is therefore reverted — it never changed the agent anyway; to change one, `set_app_agent`. |
-| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings the app serves that the source names nowhere, capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, and a notice for any alias the source computes at runtime (invisible to every check here and to the deploy's unbind guard). Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. The point is the question being ASKABLE: these checks used to cost a build, a tar, an upload and a version row in the audit trail, which is expensive enough that the honest move was to skip them and find out in production. |
+| `lotics install <package_id>` | Materialize a published package into the current workspace via `POST /v1/packages/{id}/installations` — an **app** package scaffolds, deploys, materializes and pins (reporting the app id and how to reach it); a **content** package delivers its docs and templates. Installs at the package's LATEST version; a version pin is the operator's concern and lives in `opctl`. **Bundled knowledge the install could not bind is NAMED, not counted** — an unbound doc leaves a working app whose agent reads nothing from it and answers from nowhere. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr) like every other data command — it materializes tables, an app and knowledge docs, so the one thing it must never do is land them in whatever workspace another shell last left in the machine-wide profile. Admin-only, enforced server-side. This is the CONSUMER half of packages: authoring the registry (`app publish/release/unpublish`, `package *`) stays operator-only, because those mutate what everyone else installs, while this acts on the caller's own workspace. |
+| `lotics upgrade` | Take the installed package's next version for the app in this directory (`app_id` from the local manifest — and the WORKSPACE from the same manifest, exactly as `lotics app *` does, so the command that knows which workspace it belongs to never rides the ambient profile). Announces its target on stderr before acting. **Applies the version it PREVIEWED**, not "latest" re-resolved server-side, so a release landing mid-command cannot install a contract whose diff was never checked. **Previews first and applies only a CLEAN upgrade**: a breaking contract change, a locally modified artifact, binding drift, or bundled knowledge needing consent (all FOUR sources the preview returns — the server throws for each, so omitting one only swapped the framed refusal for a raw wire 400) is reported per item and REFUSED with exit 1, because each resolves by choosing what to keep and a guess discards work nobody asked to lose. Already-current is a no-op that says so. On success it names the new version and the changelog, and points at `lotics app pull` to bring the checkout in step. The resolutions flow for a conflicted upgrade stays in `opctl` — that case needs a person, and the person is an operator. |
+| `lotics docs` \| `lotics docs <area>` | The index of the reference docs, **resolved out of the packages installed beside this project** — never carried by this CLI. **Both levels are discovered by looking**: every `@lotics/*` package carrying an `AGENTS.md` or a `docs/` in any `node_modules/@lotics` from the current directory UPWARD (nearest wins, so a hoisted root copy never shadows the one a project's own imports resolve to — checking only cwd made an agent editing `src/App.tsx`, or anyone on a workspaces/pnpm layout, see app-sdk and ui vanish while the `@lotics/cli` fallback kept the index looking complete) (six do today — app-sdk, ui, cli, docx, ooxml, xlsx), and within each, every area it actually ships. Titles come from each file's own `# heading` and the version from the installed `package.json`, so a doc OR a whole package added upstream appears with no change to this CLI, and a skewed install is visible rather than reassuring. A package's index is named after the package (`lotics docs ui`), never `index` — every package has one, so a shared name would make the most obvious query the one guaranteed to be ambiguous. `@lotics/app-sdk`, `@lotics/ui` and `@lotics/cli` sort first as a reading ORDER, not a filter. Bundling them here instead would print the contract of whichever kit version this CLI was built against — the kit publishes several times a day — and serving them from an endpoint would answer `latest` to a project on a pin: both are current-and-wrong, which is the one failure npm already prevents. Both the index and `<area>` print to **stdout** — the index is the payload of a bare `lotics docs`, so `lotics docs | grep -i excel` works — with only the provenance line on stderr, so `lotics docs ai > ai.md` is the doc alone; a name two packages share is refused with both qualified forms (`lotics docs ui/templates`) rather than resolved silently. Needs no auth — the references describe the product, not a workspace, so a key that will not resolve is exactly when someone reaches for them. Outside a project only `@lotics/cli`'s own resolve, and it says so. |
+| `lotics report '<json>'` \| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** — `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. The frame exists because a session join reconstructs what was RUN and can never reconstruct what was WANTED: "the deploy warned twice" is unactionable, the same line under a goal names the defect. Each field becomes its own log attribute, so `goal` clusters across sessions instead of being grepped out of prose. **No severity or category** — those are judgements rather than facts, derivable at analysis time (a report followed by more commands on the same task shows a workaround; one followed by nothing shows a dead end), and a taxonomy shipped in a released binary cannot be corrected without a release. Ingest is inline JSON, `@file`, or `-` for stdin. The explicit `-` is the one place this departs from `run`, and it has to: `run` reaches stdin only after a tool name, while a report's single positional IS the payload, so bare and piped are the same argv. `isTTY` cannot separate them — it is falsy for a pipe a supervisor holds open and never writes to — so guessing hangs the bare form forever, and a grace period instead drops the report of any writer slower than the timer. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` — invoking it IS the consent that passive collection needs an opt-in for — but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. |
+| `lotics app check` | Every pre-flight `deploy` runs, WITHOUT building or shipping: the manifest's agent schemas against the live app row, every binding a deploy would push, aliases the source calls that nothing bound (queries, workflows AND agents), bindings the app serves that the source names nowhere, capability-gated SDK calls the manifest doesn't declare, a missing icon/theme, a `vite.config.ts` that never defines `global`/`__DEV__` and a `window.open` in the app's own source (both fail ONLY in the deployed app — dev bundles with esbuild and production with rollup, so typecheck, lint, build and `app dev` are all green while react-native-web reads `global.cancelAnimationFrame` as a free variable and the sandboxed iframe drops a popup silently), an agent holding `run_app_query`/`run_app_workflow` with an EMPTY `query_aliases`/`workflow_aliases` (the tool is the capability, the alias list is the reach — empty means every call it makes is refused while the run still COMPLETES, so it surfaces as a model ignoring its prompt; read off the live row, never the manifest, which mirrors those fields but is pushed by no verb), and a notice for any alias the source computes at runtime (invisible to every check here and to the deploy's unbind guard). Adds no rule of its own — each finding is the same helper `deploy` calls, so a green check means a deploy will not complain. **Exits 1 on what a `deploy` would REFUSE or PUSH** — an agent schema that disagrees with the live app, and any binding the project has ahead of the app (an edited workflow body or declaration, edited agent prose, a changed query). Both are things a deploy would act on, so CI gating on a green check means a deploy has nothing left to do; genuine advisories (capabilities, branding, a runtime-computed alias, orphaned bindings) stay advisory and never fail it. The point is the question being ASKABLE: these checks used to cost a build, a tar, an upload and a version row in the audit trail, which is expensive enough that the honest move was to skip them and find out in production. |
 | `lotics app workflow run <alias> '<json>'` | Execute a bound app workflow end-to-end via `appWorkflow`. `app_id` comes from the local manifest; the alias must be bound (`set_app_workflow`). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin — bulk inputs bypass `ARG_MAX`). Prints the full `{status,message,data,files,side_effects}` JSON to stdout + a one-line summary to stderr; exits non-zero on `status:"error"` (assertable). `--print-created` (alias `--report-effects`) renders the honest post-run harvest: created records grouped by table, a paste-ready `lotics run delete_records …` per table, then the **mandatory caveat** naming what cannot be auto-undone (external integrations + notifications) and that sub-workflows may have run. `--cleanup` (DEFAULT OFF, implies the report) additionally runs the deletes for harvested records ONLY — never files / external / notifications. Neither is a rollback — a rollback is structurally impossible here. |
 | `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` **and the `description`** from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). The `description` is the one line an agent reads when choosing between the app's aliases (the workflow counterpart to a query's) — authored in the manifest so it lives beside the body in version control and rides every push; omit it and the workflow keeps whatever description it already has, so a push can never blank one set elsewhere. When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. Deploy still never authors workflows — this is a CLI convenience over the existing tool. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. |
 | `lotics app agent set <alias>` | Push `src/agents/<alias>.md` — plus `inputs`/`outputs` when `package.json#lotics.agents.<alias>` declares them — through `set_app_agent`. The agent mirror of `app workflow set`, and the deploy-free authoring path for an agent's prose and its typed edges. **It sends only those fields.** Everything else is absent, and absent means unchanged, so a declaration this CLI does not model cannot be reverted by a push from a checkout that predates it — the chat authoring agent's `knowledge_doc_ids`, another operator's `query_aliases` grant. To change one of those, call `set_app_agent` with just that field (`lotics run set_app_agent '{"app_id":…,"alias":…,"tool_names":[…]}'` — it merges), then `app pull` to bring the manifest back in step. **CREATES the alias when the app has not bound one yet**, so a new agent is authored the same way a new workflow is: write the prose, declare the typed half, push. A create needs the prose file (an agent without instructions is not an agent); it is gated on nothing else, because what keeps a binding alive is a `useAppAgentRun("<alias>")` call site in the shipped bundle — a deploy prunes an agent the bundle never names, manifest entry or not. The prose push is a conditional write against the fingerprint this project last saw, so it is refused rather than allowed to overwrite prose someone else changed. Clear error + non-zero exit when there is no prose file and nothing declared to push instead, when a create has no prose to create from, or when the file is empty once the header is stripped. |

package/docs/document_templates.md

@@ -24,7 +24,7 @@ office file and mark it up; **inline** (`html`, `email`) store the markup you au
 ## The lifecycle: create → generate → chain
 
 1. **Create** a template — register the file (or inline markup) and declare a `variables`
-   map (the named slots the template fills). This returns a template id (`tpl_…`).
+   map (the named slots the template fills). This returns a template id (`dtl_…`).
 2. **Generate** a filled file — call the matching `generate_*_from_template` with the
    template id, a `filename` (no extension), and a `data` map keyed by your variable names.
    It substitutes the markers and returns a **generated file** (with a `file_id`).
@@ -121,8 +121,8 @@ Run `lotics tools create_excel_template`, `create_word_template`, `create_pdf_te
 ```bash
 # See what a template expects, then fill it
 lotics tools generate_excel_from_template
-lotics run get_template '{"template_id":"tpl_..."}'          # its declared variables
-lotics run generate_excel_from_template '{"document_template_id":"tpl_...","filename":"invoice-1042","data":{"company_name":"Acme","total":1042,"items":[...]}}'
+lotics run get_template '{"template_id":"dtl_..."}'          # its declared variables
+lotics run generate_excel_from_template '{"document_template_id":"dtl_...","filename":"invoice-1042","data":{"company_name":"Acme","total":1042,"items":[...]}}'
 lotics download <file_id> -o ./out/
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.136.1",
+  "version": "0.142.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {