@lotics/cli 0.192.0 → 0.194.0

package/dist/src/client.d.ts

@@ -21,6 +21,11 @@ export interface AppQueryFilterGroup {
 export type AppQueryFilter = AppQueryFilterCondition | AppQueryFilterGroup;
 export interface LoticsClientOptions {
     apiKey: string;
+    /** The Lotics this key belongs to — `ResolvedContext.apiUrl`, which is the
+     *  registration's own `api_url`. Required and never defaulted: a client that
+     *  can fall back to an ambient host is a client that can send a private
+     *  instance's key to production (`docs/on_premise.md` section 8). */
+    apiUrl: string;
     workspaceId?: string;
     /** Admin "View as": when set, every request carries `x-view-as-member-id`, so
      *  the backend evaluates IAM scoping (and `is_current_member`) as this member.
@@ -342,7 +347,6 @@ export declare class LoticsRequestError extends Error {
     readonly body: Record<string, unknown>;
     constructor(message: string, status: number, body: Record<string, unknown>);
 }
-export declare const API_BASE_URL: string;
 /**
  * The website: where a person goes when the CLI cannot finish the job, and where
  * the presets are SERVED FROM. Held beside the API base so the pair is read
@@ -379,7 +383,7 @@ export interface OfficialStarter {
  * starter for what I do, or should I build?" is decided before an account
  * exists, so needing one to ask means signing up to find out the answer was no.
  */
-export declare function fetchOfficialStarters(): Promise<OfficialStarter[]>;
+export declare function fetchOfficialStarters(apiUrl: string): Promise<OfficialStarter[]>;
 /**
  * One keyless GET of JSON, bounded — the shape every read that predates an
  * account takes.
@@ -419,7 +423,7 @@ export declare function getPublicJson(url: string, what: string): Promise<{
  * throws: "unreachable" is not "not on the shelf", and answering both the same
  * way would tell an owner their package is missing every time the link drops.
  */
-export declare function readOfficialStarter(starter_id: string): Promise<{
+export declare function readOfficialStarter(apiUrl: string, starter_id: string): Promise<{
     ok: true;
     package: OfficialStarterRead;
 } | {
@@ -427,7 +431,7 @@ export declare function readOfficialStarter(starter_id: string): Promise<{
     status: number;
 }>;
 /** The same read for a caller with nothing to fall back to — a refusal is the end. */
-export declare function getOfficialStarter(starter_id: string): Promise<OfficialStarterRead>;
+export declare function getOfficialStarter(apiUrl: string, starter_id: string): Promise<OfficialStarterRead>;
 /** A column as the public read shows it: enough to write a model field from. */
 export interface OfficialStarterField {
     alias: string;
@@ -524,8 +528,8 @@ export type CliLoginState = {
  * The same answer whether or not the address has an account: it would
  * otherwise tell any stranger which emails are registered here.
  */
-export declare function startCliLogin(email: string): Promise<CliLoginRequest>;
-export declare function pollCliLogin(request_id: string, secret: string): Promise<CliLoginState>;
+export declare function startCliLogin(apiUrl: string, email: string): Promise<CliLoginRequest>;
+export declare function pollCliLogin(apiUrl: string, request_id: string, secret: string): Promise<CliLoginState>;
 export declare class LoticsClient {
     private apiKey;
     private workspaceId;
@@ -533,8 +537,8 @@ export declare class LoticsClient {
      *  construction — surfaced so `lotics app dev` can show it in the banner. */
     readonly viewAsMemberId: string | undefined;
     /** API URL the client is configured against. Read-only after construction.
-     *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
-     *  shows it in the banner). */
+     *  Surfaced for callers that need to display it (`lotics app dev`'s banner) or
+     *  to hand it on (the wrapper page's RPC target, the scaffold's font proxy). */
     readonly baseUrl: string;
     constructor(options: LoticsClientOptions);
     private throwResponseError;
@@ -987,13 +991,15 @@ export declare class LoticsClient {
         }>;
     }>>;
     /**
-     * Rename an app's public subdomain — its `<slug>.lotics.app` address.
-     * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
-     * resolving once the change lands.
+     * Rename an app's public subdomain — the label its origin is built on.
+     * Mirrors PUT /v1/apps/{app_id}/subdomain, and returns the finished `origin`
+     * because only the instance knows the domain and scheme it serves apps on.
+     * The old subdomain stops resolving once the change lands.
      */
     setAppSubdomain(app_id: string, public_subdomain: string): Promise<{
         app_id: string;
         public_subdomain: string;
+        origin: string;
     }>;
     getAppVersion(app_id: string, version_id: string): Promise<{
         id: string;

package/dist/src/client.js

@@ -149,10 +149,9 @@ var LoticsRequestError = class extends Error {
   status;
   body;
 };
-var API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
 var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
-async function fetchOfficialStarters() {
-  const read = await getPublicJson(`${API_BASE_URL}/v1/starters/official`, "list the packages");
+async function fetchOfficialStarters(apiUrl) {
+  const read = await getPublicJson(`${apiUrl}/v1/starters/official`, "list the packages");
   if (!read.ok) {
     throw new Error(
       `Lotics answered ${read.status} listing the packages. If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`
@@ -172,16 +171,16 @@ async function getPublicJson(url, what) {
   if (!response.ok) return { ok: false, status: response.status };
   return { ok: true, body: await response.json() };
 }
-async function readOfficialStarter(starter_id) {
+async function readOfficialStarter(apiUrl, starter_id) {
   const read = await getPublicJson(
-    `${API_BASE_URL}/v1/starters/official/${encodeURIComponent(starter_id)}`,
+    `${apiUrl}/v1/starters/official/${encodeURIComponent(starter_id)}`,
     `read ${starter_id}`
   );
   if (!read.ok) return read;
   return { ok: true, package: read.body };
 }
-async function getOfficialStarter(starter_id) {
-  const read = await readOfficialStarter(starter_id);
+async function getOfficialStarter(apiUrl, starter_id) {
+  const read = await readOfficialStarter(apiUrl, starter_id);
   if (!read.ok) {
     throw new Error(
       `Lotics answered ${read.status} reading ${starter_id}. Only packages Lotics publishes can be read without an account.`
@@ -190,10 +189,10 @@ async function getOfficialStarter(starter_id) {
   return read.package;
 }
 var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
-async function startCliLogin(email) {
+async function startCliLogin(apiUrl, email) {
   let response;
   try {
-    response = await fetch(`${API_BASE_URL}/v1/cli/login_requests`, {
+    response = await fetch(`${apiUrl}/v1/cli/login_requests`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ email }),
@@ -209,8 +208,8 @@ async function startCliLogin(email) {
   }
   return await response.json();
 }
-async function pollCliLogin(request_id, secret) {
-  const url = `${API_BASE_URL}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
+async function pollCliLogin(apiUrl, request_id, secret) {
+  const url = `${apiUrl}/v1/cli/login_requests/${encodeURIComponent(request_id)}`;
   let response;
   try {
     response = await fetch(url, {
@@ -237,14 +236,14 @@ var LoticsClient = class {
    *  construction — surfaced so `lotics app dev` can show it in the banner. */
   viewAsMemberId;
   /** API URL the client is configured against. Read-only after construction.
-   *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
-   *  shows it in the banner). */
+   *  Surfaced for callers that need to display it (`lotics app dev`'s banner) or
+   *  to hand it on (the wrapper page's RPC target, the scaffold's font proxy). */
   baseUrl;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.workspaceId = options.workspaceId;
     this.viewAsMemberId = options.viewAsMemberId;
-    this.baseUrl = API_BASE_URL;
+    this.baseUrl = options.apiUrl;
   }
   /**
    * The id is appended to the MESSAGE rather than carried on a field, because
@@ -647,9 +646,10 @@ var LoticsClient = class {
     return tables.filter((t) => t !== null);
   }
   /**
-   * Rename an app's public subdomain — its `<slug>.lotics.app` address.
-   * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
-   * resolving once the change lands.
+   * Rename an app's public subdomain — the label its origin is built on.
+   * Mirrors PUT /v1/apps/{app_id}/subdomain, and returns the finished `origin`
+   * because only the instance knows the domain and scheme it serves apps on.
+   * The old subdomain stops resolving once the change lands.
    */
   async setAppSubdomain(app_id, public_subdomain) {
     return this.request(
@@ -1161,7 +1161,6 @@ var LoticsClient = class {
   }
 };
 export {
-  API_BASE_URL,
   LoticsClient,
   LoticsRequestError,
   WEB_APP_URL,

package/docs/building_an_app.md

@@ -194,6 +194,13 @@ rather than rebuilding the frame. For a screen no shape covers, the kit's `examp
 screens as source; 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.
 
+**The record half is the same deal.** A screen is `[tabs] + list → record`, and the record is one
+frame too: `@lotics/ui/record_page` over the section bodies the record's field roles decide. Which
+roles become which sections is `lotics scaffold docs` § Apps and screens; which component each
+section kind names is `node_modules/@lotics/ui/docs/templates.md` § The record. A drawer and a page
+draw the same list of sections; `lotics scaffold check` prints it per screen, and `--from` emits it.
+A section's ADD act rides its heading row, never inside its body.
+
 **A screen no shape fits** is declared in the plan as `"shape": "custom"` with its slots as roles
 (`lotics scaffold docs` § Apps and screens) — never a shape bent to fit — and built from the kit
 like any other. Then file `lotics report` with `wanted` opening `shape <name>`: a custom slot set

package/docs/cli_reference.md

@@ -7,11 +7,11 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics` / `lotics --help` | Show full help with capabilities, tool categories, workflow |
 | `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |
 | `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>`, also mailed — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `library list`/`show`, `scaffold docs`/`check`, `app codegen`, `app workflow check` — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
-| `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
+| `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
 | `lotics auth web` | Send a magic link email to access the web app (requires auth) |
-| `lotics auth whoami` | Print active account name, email, org, resolved workspace, and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id` + `source`. |
+| `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url` + `source`. |
 | `lotics auth logout [<name\|id>]` | In a pinned dir: delete the local pin. Else: remove one profile (default the active org). `--all`: wipe the global store. |
-| `lotics org` | List saved orgs (profiles) from the global store, marks active for this directory (a local pin wins over the global default). |
+| `lotics org` | List saved orgs (profiles) from the global store with the instance each belongs to, marks active for this directory (a local pin wins over the global default). |
 | `lotics org use <name\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous → error) or id. No flag → global `active_org`; `--local` → a `.lotics/config.json` pointer in the current dir. |
 | `lotics workspace` | List workspaces in the active org, marks current with `(current)` |
 | `lotics workspace select <id>` | Set the workspace in the **active scope** — a local pin if the dir has one, else the active org's global profile |
@@ -37,7 +37,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics knowledge tag <id...> [--add <a,b>] [--remove <c,d>]` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, add_tags?, remove_tags? }` — one transaction over the whole set. A **DIFF applied to each doc's own labels**, never a replacement: the docs named on one command line carry different labels, so one array across them would strip whatever the others were filed under. Removal matches case-insensitively; adding a label a doc already carries writes nothing. Ids may be separate arguments or comma-separated. At least one of --add/--remove required. |
 | `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** — the Library's list, `list_knowledge`, and the corpus `grep_knowledge` searches — while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as "everything". |
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
-| `lotics app create <name> [path]` | Scaffold a Vite+React+TS custom-code app project; POST /v1/apps; npm install; vite build; upload as v1. The generated `package.json#name` is the app name FOLDED to ASCII (`Đơn hàng` → `don-hang`), never stripped of it — dropping the marks would treat each accented vowel as a separator and can slug a name away to nothing. The app's display name is unaffected; this is the npm field only. **`--from <model.json>#<app>`** scaffolds the app a PLAN describes: the file is checked as `scaffold check` checks it, the named app (or the only one) is taken, every screen's entity is found as a live table BY LABEL and every slot's field on it — a table the workspace lacks is refused first, naming every missing one and `scaffold apply`; then a field a table lacks, a label two tables or two fields share, or a field whose live type is not the model's — all before anything is created. Each screen is written as its registry shape from `@lotics/ui` (`LifecycleDesk`, `PartyRegister`, …) over `useQuery(<screen alias>)`, the slots reading the bound fields through `F`; a `custom` screen arrives as its rows and the slot list. The manifest declares one `project` query per screen (the slot columns, a picture bounded to one entry, a dated book newest first); the `.lotics` companions and `app_fields.ts` are written for them before the first build, and the deploy pushes the queries as it pushes any |
+| `lotics app create <name> [path]` | Scaffold a Vite+React+TS custom-code app project; POST /v1/apps; npm install; vite build; upload as v1. The generated `package.json#name` is the app name FOLDED to ASCII (`Đơn hàng` → `don-hang`), never stripped of it — dropping the marks would treat each accented vowel as a separator and can slug a name away to nothing. The app's display name is unaffected; this is the npm field only. **`--from <model.json>#<app>`** scaffolds the app a PLAN describes: the file is checked as `scaffold check` checks it, the named app (or the only one) is taken, every screen's entity is found as a live table BY LABEL and every field the model declares on it — the record shows the ones the list leaves out — and, for each child entity a record section is over, its table and the fields that section draws — a table the workspace lacks is refused first, naming every missing one and `scaffold apply`; then a field a table lacks, a label two tables or two fields share, or a field whose live type is not the model's — all before anything is created. Each screen is written as its registry shape from `@lotics/ui` (`LifecycleDesk`, `PartyRegister`, …) over `useQuery(<screen alias>)`, the slots reading the bound fields through `F`; a `custom` screen arrives as its rows and the slot list. The RECORD that shape opens is written too, off the same roles (`recordSections`): a `RecordFacts` of every field no other section owns, a `RecordProgress` over the lifecycle, a `RecordExpectedSet` per required set — the entity's own multi-select, or a child entity whose rows each file one entry — a `RecordChildren` per child entity — the identity, the figures and two more roles as columns, ranked so a narrow register sheds the contact before the money, with the row's whole projection in the drawer behind it — and a `RecordFiles` per files field. A `page` record is one `RecordPage` whose facts take the aside beside that work, or the main column itself where the record has none; a `drawer` record is the same sections stacked. The manifest declares one `project` query per screen (every column the screen and its record read, a files cell whole, a dated book newest first) plus one per child entity, filtered to the parent record through the child's `parent` link and taking it as a declared `{{params.<entity>_id}}`; the `.lotics` companions and `app_fields.ts` are written for them before the first build, and the deploy pushes the queries as it pushes any |
 | `lotics app pull <app_id> [path]` | Download source archive from R2 (presigned), extract, install dependencies (`npm ci --ignore-scripts` when a lockfile is present, else `npm install --ignore-scripts`), stamp package.json's `lotics` field. With no `[path]`: refresh the cwd IN PLACE when it's already this app's own project (its manifest `app_id` matches — the documented `cd <app> && lotics app pull` flow), else clone into an `<name>/` subdir. **A pull never overwrites a file that differs from what it is about to write** — it writes only what is ABSENT or already identical, keeps the rest, and reports which files it kept plus the commands that close the gap. The same rule covers `src/workflows/<alias>.ts` and `src/agents/<alias>.md`, so an unpushed body or prompt survives too. Those two are written from the LIVE App row (`apps.workflows` / `apps.agents`), which owns them, and the archive's own copy of them is deliberately SKIPPED on extract: a deploy tars the whole source directory, so the tarball holds a deploy-time snapshot that is stale for anything authored since. The comparison is against the app's own content, not git, so it holds for a project that was never a repo. `--force` takes the app's copy and DISCARDS local edits; there is no other way to lose them. **For a KEPT workflow body or agent prompt the pull records the server's fingerprint only when the server has not moved** — that token is `set_app_workflow`/`set_app_agent`'s lost-update precondition, so recording one for text the author has not seen would clear the next push's refusal by disarming the guard, and silently overwrite whoever edited it. When the live text HAS moved, the pull writes it beside the checkout (`.lotics/agents/<alias>.live.md`, `.lotics/workflows/<alias>.live.ts`), names it, and leaves the token stale: the next deploy is refused, which is correct, and the text to merge is now on disk. A file whose prose/body already reads back AS the live text is never "kept" at all — the baselines are healed from it, so a checkout whose prose was pushed out of band (chat, `lotics run set_app_agent`) converges instead of latching. **A pull also REPORTS the files it restored** when refreshing a tree that already claimed a version: a pull mirrors the last DEPLOYED source, so a file deleted locally comes back until the deletion itself ships, and saying so is the only honest fix — nothing can read a deletion off the disk. **When a pull ACROSS versions keeps files, the manifest is left on the OLDER of the two versions** — the tree is then part one and part the other, and claiming the newer would make `deploy`'s `prev_version_id` check pass and ship a half-and-half bundle. Older, not "the one it had": `--from-version` pulls a deliberately old revision, so the version it had is the NEWER side, and holding that would match what the server serves and let the old source ship. Either way a deploy from that tree is refused until you reconcile the listed files by hand and pull again, or take the app's copy with `--force`. The report says which version each side is on, because a kept file is your unshipped work when the project was already current and merely the OLD version when it was behind — and nothing in a byte comparison can tell those apart. **`--from-version <apv_…>`** pulls an OLDER revision instead of the current one (`lotics app versions` lists the ids) — point it at a NEW path to read a previous revision without disturbing the project you are in. The manifest records the version actually written, never the live pointer, so a deploy from that checkout is refused by the version guard rather than shipping old source over newer. — `workflows` and `agents` are sourced from the live App row (NOT the archived manifest), so `set_app_workflow` / `set_app_agent` authoring survives the pull. Regenerates `.lotics/app_{workflows,queries,agents}.d.ts` so `useWorkflow` / `useQuery` / `useAgentRun` stay typed, AND — AFTER `npm install`, so `node_modules/@lotics/ui` actually exists to read — `.lotics/tsconfig.link.json`'s peer pins and, for a kit old enough to ship one, its `react-native` augmentation (a kit that ships none has the previously-written copy deleted); a pulled project's own `tsc` used to fail until `app codegen` was run by hand, because nothing had regenerated either one after install populated node_modules. AND the runtime `.lotics/app_fields.ts` (the same generation `app codegen` runs, off the app row already fetched). That one is not optional: `app deploy` tars source with `--exclude=.lotics`, so no archive can carry it, and a pulled project whose `src/` imports `F`/`OPT` would fail to build with `Could not resolve "../../.lotics/app_fields"` until `app codegen` was run by hand. Skipped under `--view-as` (the schema is read as that member and silently drops tables they cannot see — a narrowed `F` map compiles and then throws at runtime, worse than the missing module). A schema fetch failure is non-fatal and names the right recovery for what is on disk: an existing file is kept, an ABSENT one warns about the build error and points at `app codegen`. Pull GENERATES but never RECONCILES `.lotics/` — deleting a companion whose alias the manifest no longer declares is `app codegen`'s alone, since pull's authority is the server's alias set and a declared-but-not-yet-`set` alias is supported. Also writes one `src/workflows/<alias>.ts` per bound workflow (faithful body from `get_app_workflow`) and one `src/agents/<alias>.md` per bound agent (its instructions, straight off the live row) — so the prose an author actually edits lives in a file. A pull writes it from live UNLESS the local file holds unpushed work, in which case it is kept and the live text is parked beside the checkout — the same rule the rest of this row describes. A legacy workflow alias with no rendered source, or an agent with no instructions, warns and is skipped. The stamped `lotics.agents` map carries the TYPED half only (`inputs`/`outputs`/`tool_names`/`model_tier`/…) — an agent's prose lives solely in its `.md`, so there is never a second local copy to desync; a stale `instructions` left by an older CLI is inert and disappears on the next pull |
 | `lotics app deploy [--prune] -m <message>` | `-m` is OPTIONAL — omitted, the deploy derives the version message from what it actually pushed; pass `-m` when you have a reason worth recording. `npm run typecheck`, `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. 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 the `.lotics/*.d.ts` companions and `.lotics/app_fields.ts` before building, since the build INLINES the latter and a stale copy would ship ids that no longer name what the source thinks they do — and then runs the app's own `npm run typecheck` against them, because Vite strips types and a filter or sort key the query does not project would otherwise ship. A `package.json` with no `typecheck` script is warned about, never passed in silence. `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. After a successful deploy it warns about any alias the source CALLS that is NOT bound, and **names the inverse** — but as a TRANSITION, not a state: bindings this bundle *stopped* calling, compared against what the previous deploy's bundle called (`package.json#lotics.bundle_calls`, which a deploy records). It does NOT remove them: **`--prune` does, and only when passed.** The distinction is what makes the report readable. A static scan sees the bundle's call sites and an agent's `query_aliases`/`workflow_aliases`; it cannot see `lotics run run_app_query`/`run_app_workflow`, whose whole contract is that the alias is bound server-side, or chat's call under `app:use` — and the capability catalog publishes EVERY declared alias to both. So an alias the bundle never called is the normal shape of an agent-facing binding, not a dead one, and reporting it fired on every app built to be driven by an agent while pointing at the flag that deletes it. An alias that WAS called and is not any more is different: that is a call site the author removed, which is compile-, check- and deploy-clean while the binding keeps serving. **No baseline ⇒ nothing reported** — a manifest from before this field, or one a `pull` rebuilt from the server row, costs one quiet deploy and then self-heals, because silence is the only honest answer with nothing to compare. The baseline is STICKY: it advances only once nothing is outstanding, so the `--prune` this warning names still finds the transition on a later run instead of reporting ✓ over a binding that still serves. Pruning 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. `--prune` 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 and pruning "the rest" would be guessing with a deletion. **A removal DELETES the local declaration too** — `package.json#lotics.<kind>.<alias>` and its `synced` baseline — because leaving it would undo the prune: the manifest is what the next plain deploy pushes FROM, so the binding came straight back. That makes the act destructive rather than merely reversible, so what it deleted is written to `.lotics/pruned/<kind>/<alias>.json` and the ✓ names that file plus the `set` verb that re-binds it, on the same line. (These trees are never committed, so git is not the fallback; `lotics app pull --from-version <apv_…>` is the only other route back.) After a successful prune the generated companions are regenerated from the narrowed manifest — the `.d.ts` set and, when a query was pruned, `.lotics/app_fields.ts`, whose table set is derived from the surviving query ASTs. A table named ONLY by the pruned query leaves `F`/`OPT`, which is reported: if your source still addresses it, add the table id to `package.json#lotics.codegen.tables`. A local write that fails at any of this reports what could not be written and which aliases were already unbound server-side; it never fails the release, which is already live. A binding that will not unbind is reported and does NOT fail the release: the version is live and correct — and the server refuses to unbind a WORKFLOW this workspace has actually run (a recorded execution means a caller the source cannot name), which surfaces here as `✗ could not unbind …` with the date it last ran. After a successful deploy it also REFRESHES the `.lotics/workflows/<alias>.globals.d.ts` of any alias whose `// lotics:declaration` stamp says this deploy moved its declaration (only those — refreshing every bound alias would cost one round trip each on every deploy to fix something only ever wrong right after a manifest edit), from the manifest declaration, re-wrapping the SAME on-disk body (never re-fetching it, so local edits survive). A deploy is the moment the manifest becomes real, so it is also the moment the local types stop matching it — and the author's next act is usually `workflow set`, whose body would otherwise be typechecked against the declaration as it stood before this deploy. Non-fatal: the release already shipped, and stale types never fail it. |
 | `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. Title → stderr, table → stdout (pipeable). |
@@ -61,7 +61,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics app query set <alias>` \| `--all` | Push `package.json#lotics.queries` (`{ ast, params? }` per alias) to `apps.queries` through `set_app_query` — **the only author of a query binding**, the mirror of `app workflow set`. A deploy pushes a DRIFTED declaration through this same verb before it ships (see `app deploy`), so this is the explicit single-alias path, not the only way a query reaches the app. The **server** validates each one exactly as it always did (alias identifier, workspace-only tables, resolvable fields, declared params). `--all` pushes every declared alias, alias-sorted, stopping at the first failure and naming what already landed. Clear error + non-zero exit on an alias absent from the manifest or a validation failure. **The declaration's fields MERGE**, so the manifest is not a snapshot: deleting `params` from an alias and pushing leaves the live params exactly where they were, because an absent key means "unchanged". Clear one with `params: null`, or replace the map with the set you want. After the push it regenerates `.lotics/app_queries.d.ts` from the manifest, so the types the next `npm run typecheck` reads match what was just pushed. |
 | `lotics app workflow pull` | Rewrite every `src/workflows/<alias>.ts` from the server (faithful body per bound alias via `get_app_workflow`) **+ its `.lotics/workflows/<alias>.globals.d.ts`** (via `getAppWorkflowDts`, so the body is locally typecheckable via `lotics app workflow check`) without a full `app pull` (no source archive, no npm install). A legacy alias with no rendered source warns and is skipped; a dts-fetch failure is non-fatal (body still written with the fallback wrapper, typecheck degraded). Each alias's `description` is folded back into `package.json#lotics.workflows.<alias>` from the same read — the alias binding the manifest is otherwise stamped from carries `inputs`/`outputs` but not the description, which lives on the workflow ROW, so without this a pull would erase an authored one. The server's GENERATED default is skipped, so an app that never described its workflows gains no manifest noise. Also idempotently patches the main `tsconfig.json` `exclude` to cover `src/workflows` + `.lotics/workflows` so a pre-existing app's `npm run typecheck` never loads the bodies or the colliding per-alias globals. |
 | `lotics app workflow check [alias]` | Check the editable workflow bodies locally, no auth / no network, in the **server's own order** — parse, then type-check. **Parse** runs `parseWorkflowJs` from `@lotics/shared` (the SAME module `verifyWorkflow` calls, never a second implementation) over the stripped body `set` would upload, with `toolNames: undefined` (the CLI ships no tool registry, so tool-name resolution stays a server check while every shape/scope rule runs here). A body the subset rejects reports **that error alone** and skips the compiler — it never reaches the server's compiler either, so tsc's opinion of it is noise. **Type-check** then builds an **isolated** `ts.Program` per alias from exactly that alias's `{body, globals}` pair — mirroring the server, which verifies one body at a time — so the per-alias ambient `trigger` never collides and `trigger.app_workflow.inputs` is checked against the right alias. All aliases run in ONE node process (N programs, not N `tsc` spawns), with the SAME compile options the server uses at set-time verify (lib `es2022` with no DOM, target ES2022, strict, NodeNext, `types:[]`, skipLibCheck) and the app's OWN `typescript` (resolved from its `node_modules`, never bundled into the CLI). What the compiler sees is the **checked source**, not the file: `rewriteAccumulatorAppends` from `@lotics/shared` — the SAME transform the server applies before its set-time compile — is applied in memory, so a pulled body's canonical `out = concat(out, [item])` accumulator checks green here exactly as it saves there, and the body on disk is never rewritten. Reports `<file>:<line>:<col> - <TS####\|subset>` at the **physical** line in `src/workflows/<alias>.ts`, so an editor jump lands on the offending code (these are deliberately NOT `set`'s body-relative numbers — `set` prints no file path, so there is no format to agree with); exits non-zero if any alias fails. Green is honest but not total: `set` additionally resolves names, lints and structurally validates against the live workspace — passes that need its tables and tool schemas, so they cannot run offline, and the success line says so. A bound alias with no body file yet warns + skips; a body with no globals errors (naming `lotics app codegen`, which refreshes types WITHOUT touching the body — a pull would overwrite it). **It also keeps the types honest.** Each alias's `.lotics/workflows/<alias>.globals.d.ts` carries a `// lotics:declaration <hash>` stamp of the manifest declaration it was rendered from; `check` compares it to `package.json#lotics.workflows.<alias>` and, when they differ, re-renders that alias's dts from the LOCAL declaration before compiling. Without it the verdict was confidently wrong in the exact case an author needs it — declare an input, run `check`, and get `TS2339: Property 'x' does not exist` pointing at your body for a schema the types have never been told about. The server renders a dts from a SUPPLIED declaration, so this works before the manifest has ever been deployed, which is when it matters (the order is edit → check → set). This is the ONE thing `check` uses the API for: it is skipped entirely when the stamps match (the common case, so `check` stays instant and offline), and with no credentials or a failed fetch it WARNS and checks against the older types rather than blocking. A file written before the stamp existed reads as unknown, never as matching, so a pre-existing checkout heals on its first run. |
-| `lotics app subdomain <new-subdomain>` | Rename the app's public `<slug>.lotics.app` address via `PUT /v1/apps/{id}/subdomain`. app_id comes from the local `package.json` manifest; the chosen slug must be a valid DNS label and free; the old address stops resolving. |
+| `lotics app subdomain <new-subdomain>` | Rename the app's public address under the instance's apps domain via `PUT /v1/apps/{id}/subdomain`. app_id comes from the local `package.json` manifest; the chosen slug must be a valid DNS label and free; the old address stops resolving. |
 | `lotics app rename "<new name>"` | Change the app's display name (launcher/title) via the `update_app` tool. app_id comes from the local `package.json` manifest; the public address (`subdomain`) and code (`deploy`) are unchanged. |
 | `lotics app dev [path] [--port=N] [--vite-port=N] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage: dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** (`dev/upload_relay.ts`) from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (`dev/file_relay.ts`, absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-sdk/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the app's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. **Every forwarded op logs one line naming its ALIAS** — `[rpc] query applicants 231ms` — and `query applicants (count)` for a count request, which is a SECOND full execution of the same query rather than a cheap lookup. When requests overlap the line carries `· N in flight`. That number is the one to watch: the server bounds how many app queries run at once, so requests past the bound wait and the wait lands inside each request's own duration — a burst reads as "every query got slower", which looks like a slow database and is not one. A screen firing its list plus three facet counts on one keystroke shows up here as eight lines over one or two aliases; see `@lotics/app-sdk` `docs/data_fetching.md` (`useCount`, and handing `usePaginatedQuery` a `total`) and `docs/queries.md` §10 for collapsing them. **Holds no realtime connection** — push belongs to the product frontend, so an app previewed here never updates on an external write (a CLI run, another tab, an agent): reload to see it. Deliberate rather than missing, since the alternative is a second implementation of the channel in the wrapper page, and a blanket poll here would hide an app whose queries do not declare their tables — the one mistake the real host punishes. The startup banner says `realtime: off` so this is visible without reading this table. The scaffold's `vite.config.ts` carries no dev-optimizer list: @lotics/ui ships built ESM, so Vite's own dep scanner reaches its CJS-interop imports and pre-bundles them without being told to. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |
 | `LOTICS_UI_SRC=<abs path to packages/ui/src>` (env, not a command) | Dev-link `@lotics/ui` to a monorepo checkout for the length of ONE command, **for every tool at once**. The app's `vite.config.ts` gets its whole `resolve` block from the kit (`resolve: loticsResolve()` — `@lotics/ui/vite`), which reads the variable at call time and adds the `@lotics/ui/*` → working-copy alias, so kit edits go live under `lotics app dev` (HMR) and bundle under `lotics app deploy`. In the same breath, every command that regenerates types (`create`/`pull`/`dev`/`deploy`/`codegen`, all via `writeAppDts`) writes **`.lotics/tsconfig.link.json`** — the matching `paths`, which the app's `tsconfig.json` `extends` — so `tsc`, vitest, eslint and your EDITOR resolve the same copy Vite does. Unset ⇒ every one of them goes back to `node_modules`, and the generated file is rewritten inert. **Why `paths` and not `npm link`:** under the dev-link a kit file sits OUTSIDE the app's `node_modules` and resolves its OWN `react` from the monorepo — two copies in one program and every shared type stops matching ("Two different types with this name exist, but they are unrelated"). The generated file therefore also pins every peer @lotics/ui declares to the APP's copy, types-package first (`react` → `@types/react`; pinning the runtime package instead strands tsc on a `.js` with no declarations). The pin set is derived from the installed kit's `peerDependencies`, so it tracks the kit rather than rotting. **Nothing hand-written is touched** — the generated file lives in `.lotics/` (the CLI's own dir) and no config is edited by regex. Identical for a monorepo app and an EXTERNAL one (e.g. `~/lotics_apps`). `app deploy` still warns whenever the variable is set — that the bundle carries kit code from your working copy, or that the app's config predates `loticsResolve()` and never reads it, so the PUBLISHED kit is going out. An app whose `tsconfig.json` already `extends` something else is told rather than rewritten: add `./.lotics/tsconfig.link.json` to the array yourself. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.192.0",
+  "version": "0.194.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
     "build": "tsgo -p tsconfig.build.json && node scripts/build_cli.mjs",
     "build:binaries": "node scripts/build_binaries.mjs",
     "publish:binaries": "node scripts/build_binaries.mjs && node scripts/publish_binaries.mjs",
+    "generate:results": "node --import tsx --import ./dev/markdown_text.ts dev/results_app.ts",
     "typecheck": "tsgo --noEmit",
     "lint": "oxlint",
     "test": "vitest run",