@lotics/cli 0.165.0 → 0.171.0

package/dist/src/client.d.ts

@@ -126,6 +126,30 @@ export interface KnowledgeWarnings {
     missing_expected_docs: string[];
 }
 export declare const API_BASE_URL: string;
+/**
+ * Where a person goes when the CLI cannot finish the job — the one case being a
+ * returning user on a machine that holds no key, since every route back in
+ * needs one. Held beside the API base so the pair is read together, and named
+ * once rather than inlined at each message that has to point somewhere.
+ */
+export declare const WEB_APP_URL = "https://lotics.ai";
+/** One starter on the public shelf — what a chooser decides with, nothing else. */
+export interface OfficialStarter {
+    id: string;
+    name: string;
+    description: string | null;
+    icon: string | null;
+    latest_version: number;
+}
+/**
+ * The starters Lotics publishes, fetched with no credential.
+ *
+ * A plain function rather than a `LoticsClient` method because there is no key
+ * to build a client around — and that is the point of the endpoint. "Is there a
+ * 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 class LoticsClient {
     private apiKey;
     private workspaceId;
@@ -340,13 +364,17 @@ export declare class LoticsClient {
         description?: string | null;
         icon?: string | null;
         theme?: {
-            color: string;
+            color?: string | null;
         } | null;
     }): Promise<{
         id: string;
         name: string;
         description: string | null;
         icon?: string | null;
+        /** Optional for the same reason as `getPackage`'s: an older server omits it. */
+        theme?: {
+            color?: string | null;
+        } | null;
     }>;
     /**
      * The starters this organization can copy — Lotics-reviewed ones plus its own,
@@ -436,6 +464,15 @@ export declare class LoticsClient {
         retired_at: string | null;
         /** Absent from a pre-deploy server — treat undefined as not-owned (the badge under-claims, never over-claims). */
         owned_by_caller?: boolean;
+        /**
+         * The shelf tile, which every copy's app inherits.
+         *
+         * Optional for the same reason `owned_by_caller` is: a server that predates
+         * the field answers without it, and a CLI newer than the deployment it is
+         * talking to must read that as "not stated" rather than "not set".
+         */
+        icon?: string | null;
+        theme?: Record<string, unknown> | null;
         created_at: string;
         updated_at: string;
     }>;

package/dist/src/client.js

@@ -73,6 +73,48 @@ function getMimeType(filename) {
     return MIME_MAP[ext] ?? "application/octet-stream";
 }
 export const API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
+/**
+ * Where a person goes when the CLI cannot finish the job — the one case being a
+ * returning user on a machine that holds no key, since every route back in
+ * needs one. Held beside the API base so the pair is read together, and named
+ * once rather than inlined at each message that has to point somewhere.
+ */
+export const WEB_APP_URL = "https://lotics.ai";
+/**
+ * The starters Lotics publishes, fetched with no credential.
+ *
+ * A plain function rather than a `LoticsClient` method because there is no key
+ * to build a client around — and that is the point of the endpoint. "Is there a
+ * 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 async function fetchOfficialStarters() {
+    // Bounded, because this is the FIRST command a new user runs and a hang with
+    // nothing on screen is the worst version of the failure. `config.ts` bounds
+    // its own unattended fetch for the same reason; `docs/network_reliability.md`
+    // is a log of connections from our users' networks degrading rather than
+    // refusing, which is the shape that hangs.
+    let response;
+    try {
+        response = await fetch(`${API_BASE_URL}/v1/starters/official`, {
+            signal: AbortSignal.timeout(SHELF_FETCH_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        // Nothing answered. This is the only branch where "check your connection"
+        // is true — a status code below means the server replied and the network is
+        // demonstrably fine.
+        throw new Error(`Could not reach Lotics to list the starters (${error instanceof Error ? error.message : String(error)}). ` +
+            `Check your connection, or browse ${WEB_APP_URL}/docs/cli.`);
+    }
+    if (!response.ok) {
+        throw new Error(`Lotics answered ${response.status} listing the starters. ` +
+            `If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`);
+    }
+    return (await response.json());
+}
+/** Long enough for a slow link, short enough that a dead one still says so. */
+const SHELF_FETCH_TIMEOUT_MS = 10_000;
 export class LoticsClient {
     apiKey;
     workspaceId;

package/docs/building_an_app.md

@@ -156,6 +156,14 @@ Two rules that cause most of the rework:
   `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.
 
+**The kit is a strong recommendation, not a requirement.** `@lotics/app-sdk` is data and RPC only —
+its peers are `react`, `react-dom` and `react-router`, nothing else — so an app can be plain DOM
+React with your own CSS and still use every hook, deploy the same way, and run the same server-side.
+What the scaffold buys you is the part that is hard to get right by hand: a screen that looks
+deliberate, states that are already designed, and behaviour that matches the rest of the product.
+Building without it means owning all of that, so reach for it unless you have a specific reason not
+to — and if you do, the ONLY thing you give up is the components.
+
 ## 8 — Run it locally, and prove it
 
 ```

package/docs/cli_reference.md

@@ -41,9 +41,10 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `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 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 `.lotics/app_fields.ts` before building, since the build INLINES it and a stale copy would ship ids that no longer name what the source thinks they do. `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** — bindings the app still serves that this bundle mentions nowhere. It does NOT remove them: **`--prune` does, and only when passed.** A static scan sees the bundle's call sites and an agent's `query_aliases`/`workflow_aliases`; it cannot see `lotics run run_app_workflow`, whose whole contract is that the alias is bound server-side, or chat's call under `app:use`. An operator-driven workflow therefore leaves no call site anywhere in the source and is indistinguishable from a dead one here — so a deploy that pruned by default deleted working tooling and printed it as a ✓. 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). |
 | `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` — 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). **There is one form, and that is what makes a starter's source portable**: the keys are slugified DISPLAY NAMES and a starter carries its labels verbatim, so running codegen in a copy's own workspace emits the same keys pointing at that workspace's ids — no binding fetched at load, no prebuilt bundle to keep in step. 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. 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. The write is surgical and order-preserving, 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 starter list` | The starters this organization can copy — Lotics-reviewed ones plus its own, each with at least one released version. Deliberately NOT a catalogue of everything published: the server returns exactly what a copy would be allowed to take, so the list can never offer something that then refuses. Admin-only. |
+| `lotics start <starter_id> [path] [--email <addr>] [--json]` | **The whole first run, in one command.** Creates an account when this machine has no credential (the same call `auth signup` makes — `--name` and `--timezone` apply), then does exactly what `starter init` does, then prints the one-time sign-in link. It exists because the two-command form has a seam where the FIRST command exists only to produce a credential for the second, and a caller pasting a prompt has to get both right. **`--email` is only for creating an account**: with a credential already resolvable it is REFUSED rather than obeyed, because the two can name different organizations and preferring either one silently copies a starter into an org the caller did not name — the message says how to do each thing on purpose. Without it, `start` copies into the account you already have and is a pure alias for `starter init`. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_id`, `project_dir`, `signin_url`, and `created` — which NAMES what landed (`tables`, `templates` and `knowledge_docs` are alias arrays; `sample_records` is a row count, since rows are not named things). Aliases rather than counts because the next question is about a particular artifact: a copied template carries the publisher's wording and a copied knowledge doc describes how they work, so "which of these should be mine?" is the conversation a copy starts, and a count cannot begin it. Plus a `warnings` array carrying everything the prose form would have said out of band — an unbindable knowledge doc, a sign-in link that could not be minted, and the notice naming whose build is about to run on this machine. A warning is never merely silenced: when the command fails with an error before it can emit, the ones it had collected go to stderr alongside it. npm's and vite's own output is captured under `--json` and surfaced only if the build FAILS, where it rides out in the error. Reachable with no install: `npx -y @lotics/cli start …`. |
+| `lotics starter list` | **Works with no account**, and that is the point: whether to copy a starter or build from scratch is decided before one exists, so requiring a key would mean signing up to learn the answer was no. Unauthenticated it lists what Lotics publishes (`GET /v1/starters/official`, public). Authenticated it is the org shelf — The starters this organization can copy — Lotics-reviewed ones plus its own, each with at least one released version. Deliberately NOT a catalogue of everything published: the server returns exactly what a copy would be allowed to take, so the list can never offer something that then refuses. Admin-only. |
 | `lotics starter show <starter_id>` | One starter's name, description, current version and trust standing (`official` — reviewed by Lotics; `your organization's own`). Read it before copying a starter you did not publish. |
-| `lotics starter init <starter_id> [path]` | **Copy a starter into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates a BESPOKE app and materializes its queries, workflows and agents onto it. Then it stops: a starter ships **source only**, with no prebuilt bundle, so the app source is downloaded here, hydrated against the live app (the same steps `app pull` runs), built, and deployed — which is why this needs node and a few minutes, and why the app is not servable until the deploy lands. **What you get is yours outright**: an ordinary app plus ordinary tables, with no link back to the starter, nothing pinned, and nothing to upgrade. Edit any of it. **It builds the publisher's code on your machine** — the copy has to build where your workspace's field ids are, so `npm run build` runs their build script and vite loads their `vite.config.ts` in Node, as you. Dependencies install with `npm ci --ignore-scripts` — the lockfile's exact tree (so a starter published months ago resolves the same packages today), and no lifecycle scripts (the path that fires before you run anything). Neither changes the build itself. That is why provenance is the gate: **copyable only if the starter is Lotics-reviewed or your own organization published it** — copying runs the author's code (its bundle, its workflows, its agents) under YOUR authority, so provenance is the gate, enforced server-side. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a starter declaring `Contacts` would bind to yours. `--no-sample-data` skips the sample records; with them, the created record ids are reported — they are ordinary records, delete them whenever. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`starter publish/release/unpublish`) stays operator-only. |
+| `lotics starter init <starter_id> [path]` | **Copy a starter into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates a BESPOKE app and materializes its queries, workflows and agents onto it. Then it stops: a starter ships **source only**, with no prebuilt bundle, so the app source is downloaded here, hydrated against the live app (the same steps `app pull` runs), built, and deployed — which is why this needs node and a few minutes, and why the app is not servable until the deploy lands. **What you get is yours outright**: an ordinary app plus ordinary tables, with no link back to the starter, nothing pinned, and nothing to upgrade. Edit any of it. **It builds the publisher's code on your machine** — the copy has to build where your workspace's field ids are, so `npm run build` runs their build script and vite loads their `vite.config.ts` in Node, as you. Dependencies install with `npm ci --ignore-scripts` — the lockfile's exact tree (so a starter published months ago resolves the same packages today), and no lifecycle scripts (the path that fires before you run anything). Neither changes the build itself. That is why provenance is the gate: **copyable only if the starter is Lotics-reviewed or your own organization published it** — copying runs the author's code (its bundle, its workflows, its agents) under YOUR authority, so provenance is the gate, enforced server-side. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a starter declaring `Contacts` would bind to yours. `--json` prints one object on stdout instead of progress (the shape is under `lotics start`) and captures npm/vite output unless the build fails. `--no-sample-data` skips the sample records; with them, the created record ids are reported — they are ordinary records, delete them whenever. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`starter publish/release/unpublish`) stays operator-only. |
 | `lotics starter fixtures capture [--entity <alias> ...] [--limit <n>]` | **(authoring)** Write this app's live records into the project as `fixtures/<entity-alias>.json` — the sample data a starter carries, so a copy lands with something in it. Run from an app project; the app id comes from its manifest. The alias-keyed shape is produced server-side, because the aliases are minted when the starter is extracted and exist nowhere a project can read them. `--entity` is repeatable and comma-separated; omitted, every table the app declares is captured. **Capture a linked set in ONE call** — a link between two rows only resolves within a single capture, so taking companies and contacts separately drops the edge between them (it says so when it happens). `--limit` bounds rows per table (default 10, max 200). **READ WHAT IT WROTE before committing**: these rows are created verbatim in every workspace that copies the starter, so a real customer name, price or address captured here is published. Files, formulas, rollups, lookups and autonumbers are never captured — the platform writes those. Admin-only; writes nothing to the workspace. |
 | `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), 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`. `@lotics/app-sdk`, `@lotics/ui` and `@lotics/cli` sort first as a reading ORDER, not a filter. 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. 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. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.165.0",
+  "version": "0.171.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -17,12 +17,15 @@
   ],
   "scripts": {
     "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",
     "typecheck": "tsgo --noEmit",
     "lint": "oxlint",
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1078.0",
     "@lotics/docx": "*",
     "@lotics/ooxml": "*",
     "@lotics/shared": "*",