@lotics/cli 0.189.0 → 0.190.0

package/AGENTS.md

@@ -8,7 +8,7 @@ conventions are, and where the traps are.
 | `lotics --help` | The verb inventory (§ COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |
 | `lotics tools` · `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |
 | `lotics docs` · `lotics docs <area>` | Every reference the packages installed beside the project actually ship — `@lotics/app-sdk`, `@lotics/ui` and the document engines each carry their own, and this index only covers THIS package. Discovered by looking, not by a list, so it reports the installed VERSION of each: a doc always describes the code that is really there. |
-| `lotics scaffold docs` | How to write a `model.json` — the file a workspace is built from. Two forms: `{"from": "<preset-slug>", "variants", "rename", "entities", "rows", "apply"}`, which names a preset by slug and carries only what this business differs by, and the full one, spelled out, for when no preset is the trade: every top-level key, every field type with the config it needs, the row format, the rules, and a worked example. Offline, and not part of `lotics docs`. It also covers the `apply` list — published packages copied in after the model's own tables, each with an optional `bind` onto them — and the `preset` block a published model carries. `lotics scaffold check` then proves the file — offline, except for the one read a `from` file's preset needs — including every branch of a preset merged onto its base; `lotics setup` applies it and refuses a table name the workspace already has, `lotics scaffold apply` adopts that table and adds what is missing. |
+| `lotics scaffold docs` | How to write a `model.json` — the file a workspace is built from. Two forms: `{"from": "<preset-slug>", "variants", "rename", "entities", "rows", "apply"}`, which names a preset by slug and carries only what this business differs by, and the full one, spelled out, for when no preset is the trade: every top-level key, every field type with the config it needs, the row format, the rules, and a worked example. Offline, and not part of `lotics docs`. It also covers the `apply` list — published packages copied in after the model's own tables, each with an optional `bind` onto them — and the `preset` block a published model carries. `lotics scaffold check` then proves the file — offline, except for the one read a `from` file's preset needs — including every branch of a preset merged onto its base; `lotics setup` applies it and refuses a table name the workspace already has, `lotics scaffold apply` adopts that table and adds what is missing. `lotics scaffold export` goes the other way — a workspace printed as one of these files, to edit into another business's model; a starting point, never a source of truth. |
 | [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE — scaffold, model, types, queries, workflows, screens, ship — and the deploy-free inner loop. The other references describe contracts; this one is the order they go in and why. Read it once before starting an app. |
 | [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas — the detail `--help` compresses. Read it before hand-building a `set_app_*` payload: several tools REPLACE rather than patch, and a CLI verb already owns the safe assembly. |
 | [docs/data_model.md](./docs/data_model.md) | How tables RELATE — one entity per table and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied between tables, a copy boundary that accounts for every source field, provenance as a link rather than a flag, a declared natural key so find-or-create never compares rendered text, and why derived DEPTH costs more than row count. Separate from building_an_app because every workspace starts with tables and many never get an app. The within-table half (one fact, one column) is stated at `create_table` / `update_table`, where you meet it while deciding. |
@@ -42,11 +42,16 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   from a shell serving many. Every command that resolves a workspace echoes its target to **stderr**
   (`lotics → <org> / <workspace>`); read it back before trusting a write. `file preview <fil_…>` is
   the one credentialed command with no echo. Resolution precedence is in README § Organizations.
-- **A machine with no key can still sign in.** `lotics auth login <email>` has Lotics email the
-  person a sign-in link; they open it and press Confirm on the page showing the code the command
-  printed, and the command finishes holding their credential. `lotics setup` does the same by itself
-  when the email it was given already has an account, so a second run of the onboarding prompt
-  carries on rather than asking anyone for an API key.
+- **A machine with no key can still sign in, and the sign-in never blocks you.** `lotics auth
+  login <email>` prints the page a person opens (also mailed) and the code that page must show,
+  records the request, and EXITS. They press Confirm whenever they get to it; the next command that
+  NEEDS a credential collects the key before doing its own work, so "sign in" costs you one command
+  and then re-running what you wanted. Never wrap it in a timeout waiting for a human — `--wait`
+  exists if you really want one blocking command, and killing that one is safe too (the request
+  survives and the next command claims it). A command run before Confirm exits 1 naming the page and
+  code again; once the 15 minutes are up it says to ask again. `lotics setup` falls into the same
+  flow by itself when the email it was given already has an account: it stops having created
+  nothing, and the SAME command run again carries on.
 - **Large payloads bypass `ARG_MAX`** — `lotics run <tool> @args.json` or piped stdin. A leading `@` is
   unambiguously a file path (JSON args start with `{`).
 - **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to

package/README.md

@@ -91,6 +91,10 @@ copied in — bound onto the tables the model just made — as part of the same
 `setup` refuses a table name your workspace already has; `lotics scaffold apply model.json` is the
 additive verb — it adopts that table, adds what the model declares beyond it, and deletes nothing.
 
+The other direction, once a workspace works: `lotics scaffold export > model.json` prints its
+tables (or only `--tables tbl_a,tbl_b`) as that same file, findings on stderr. It is a starting
+point for the next business, never a source of truth — the labels are this one's.
+
 ## Install
 
 ```bash
@@ -118,13 +122,19 @@ lotics auth signup                                   # interactive prompts
 lotics auth signup a@b.com --name "Agent"            # non-interactive
 ```
 
-**`lotics auth login`** — Signs in an account that already exists, on a machine that holds no key. Lotics emails a sign-in link; open it and press Confirm on the page showing the code the command printed, and the command finishes with the credential saved as a profile.
+**`lotics auth login`** — Signs in an account that already exists, on a machine that holds no key. **It does not wait for you.** It prints the page to open (also mailed to you) and the code that page must show, then exits. Sign in there if asked, check the code, press Confirm — and run whatever you wanted to run: the next command that needs a credential collects the key before doing its own work.
 
 ```bash
-lotics auth login a@b.com            # waits until you press Confirm
-lotics auth login a@b.com --local    # pins this directory to that org
+lotics auth login a@b.com            # prints the page + code, exits — nothing to keep open
+# …press Confirm in the browser…
+lotics auth whoami                   # picks up the key, then answers
+
+lotics auth login a@b.com --wait     # one command instead: holds the terminal until Confirm
+lotics auth login a@b.com --local    # pins this directory to that org (implies --wait)
 ```
 
+A command run before you press Confirm names the page and the code again and exits 1; the request is good for 15 minutes, after which the next command says to ask again. Re-running `auth login` is always safe — it replaces the request, so only the newest code is the live one.
+
 **`lotics auth web`** — Send a magic link email to access the web app (requires prior signup or setup).
 
 ```bash

package/dist/src/cli.js

@@ -44579,6 +44579,21 @@ var LoticsClient = class {
   async scaffoldWorkspace(body) {
     return this.request("POST", "/v1/workspaces/scaffold", body);
   }
+  /**
+   * Read this workspace's schema back as a model — the tables it has (or only
+   * the ones named), their fields, options and views, plus its roles.
+   *
+   * A pure read, and admin-only for the same reason the scaffold is: the whole
+   * schema is what comes back.
+   */
+  async exportWorkspaceModel(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.tables !== void 0 && opts.tables.length > 0) {
+      params.set("tables", opts.tables.join(","));
+    }
+    const qs = params.toString();
+    return this.request("GET", `/v1/workspaces/model${qs ? `?${qs}` : ""}`);
+  }
   /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
    *  target from the request's workspace, never a path id. */
   async updateWorkspace(body) {
@@ -45810,10 +45825,23 @@ function upsertProfile(orgId, fields) {
     profiles: { ...config2.profiles, [orgId]: profile },
     active_org: config2.active_org,
     email: config2.email,
+    pending_login: config2.pending_login,
     last_update_check: config2.last_update_check,
     latest_version: config2.latest_version
   });
 }
+function loadPendingLogin() {
+  return loadGlobalConfig()?.pending_login ?? null;
+}
+function savePendingLogin(pending) {
+  saveGlobalConfig({ ...loadGlobalConfig(), pending_login: pending });
+}
+function clearPendingLogin() {
+  const config2 = loadGlobalConfig();
+  if (!config2?.pending_login) return;
+  const { pending_login: _collected, ...rest2 } = config2;
+  saveGlobalConfig(rest2);
+}
 function clearProfileWorkspace(orgId) {
   const config2 = loadGlobalConfig();
   const existing = config2?.profiles?.[orgId];
@@ -45973,7 +46001,7 @@ function resultSideEffects(result) {
 }
 
 // src/version.ts
-var VERSION = "0.189.0";
+var VERSION = "0.190.0";
 
 // src/timezone.ts
 function machineTimezone() {
@@ -46158,6 +46186,10 @@ var COMMANDS = [
       "                                       It REFUSES a name a table here already has; use",
       "                                       lotics scaffold apply to add to what you have.",
       "                                       Drop --email to use the account you already have.",
+      "                                       An email that ALREADY has an account: it prints a",
+      "                                       sign-in page to open and stops, having created",
+      "                                       nothing \u2014 press Confirm and run the same command",
+      "                                       again. --wait holds the terminal instead",
       "                                       --json prints one object and nothing else"
     ]
   },
@@ -46181,7 +46213,13 @@ var COMMANDS = [
       "                                       where every bound table is empty. Renaming or",
       "                                       deleting is not the file's to do \u2014 after the",
       "                                       first run the workspace is the truth.",
-      "                                       --json prints one object and nothing else"
+      "                                       --json prints one object and nothing else",
+      "  lotics scaffold export [--tables]    Print this workspace's tables \u2014 or only the ids",
+      "                                       named \u2014 as a model.json: the file scaffold check",
+      "                                       reads, and what a preset is written from. Edit the",
+      "                                       labels into the trade's words and add a preset block",
+      "                                       with its two questions and its variants. A starting",
+      "                                       point, never a source of truth"
     ]
   },
   {
@@ -75143,6 +75181,7 @@ function parseArgs(argv) {
     port: void 0,
     vitePort: void 0,
     local: false,
+    wait: false,
     all: false,
     yes: false,
     printCreated: false,
@@ -75152,6 +75191,7 @@ function parseArgs(argv) {
     adopt: false,
     entity: [],
     limit: void 0,
+    tables: [],
     bind: [],
     version: false,
     help: false
@@ -75169,6 +75209,11 @@ function parseArgs(argv) {
     missingValue ??= { flag, expects };
     return "";
   };
+  const takeList = (flag, expects) => {
+    const parts = splitList(takeValue(flag, expects));
+    if (parts.length === 0) missingValue ??= { flag, expects };
+    return parts;
+  };
   while (i2 < argv.length) {
     const arg = argv[i2];
     if (subcommand !== void 0 && commandOwnsTail(command) && arg !== "--help" && arg !== "-h") {
@@ -75270,6 +75315,9 @@ function parseArgs(argv) {
       case "--local":
         flags.local = true;
         break;
+      case "--wait":
+        flags.wait = true;
+        break;
       case "--all":
         flags.all = true;
         break;
@@ -75293,11 +75341,14 @@ function parseArgs(argv) {
       // Comma-separated AND repeatable, like `--tags` above: an agent scripting
       // this reaches for whichever form it knows, and both accumulate.
       case "--entity":
-        flags.entity = [...flags.entity, ...splitList(takeValue(arg, "<alias>"))];
+        flags.entity = [...flags.entity, ...takeList(arg, "<alias>")];
         break;
       case "--limit":
         flags.limit = takeValue(arg, "<n>");
         break;
+      case "--tables":
+        flags.tables = [...flags.tables, ...takeList(arg, "<tbl_id,tbl_id>")];
+        break;
       // Repeatable and never split: the value's right half is a table or field
       // NAME, which may hold a comma.
       case "--bind":
@@ -76708,7 +76759,7 @@ var workspaceModelContractSchema = packageContractSchema.omit({ apps: true, fixt
   templates: zod_default.array(contractInlineTemplateSchema).default([]).describe("Document templates whose content travels inline (html or email)")
 }).strict();
 var modelApplyEntrySchema = zod_default.object({
-  starter: zod_default.string().min(1).describe("The package id to copy in"),
+  package: zod_default.string().min(1).describe("The package id to copy in"),
   bind: packageBindSchema.optional().describe("Entity alias \u2192 the labels this workspace calls that entity and its fields"),
   no_sample_data: zod_default.boolean().optional().describe("Decline the package's sample records")
 }).strict();
@@ -77478,7 +77529,7 @@ Captured ${totalRows} row${totalRows === 1 ? "" : "s"} across ${result.captured.
 import fs10 from "node:fs";
 
 // src/model_reference.md
-var model_reference_default = '# The Lotics workspace model (`model.json`)\n\nOne JSON file describing the tables, fields, options, views, roles and first rows\na workspace starts with. `lotics scaffold check model.json` proves it offline \u2014\nno account, no network. `lotics setup model.json --email you@company.com` creates\nthe account and applies it. `lotics scaffold apply model.json` applies it again,\ninto the workspace the credential names.\n\n**There are two forms of this file.** The full one, below, spells the model out.\nThe `from` one names a published preset and carries only what this business\ndiffers by \u2014 see \xA7 Starting from a preset, and prefer it whenever a preset fits\nthe trade.\n\nApps are not a model\'s to declare \u2014 build one in the workspace the model\ncreated, then publish that workspace as a starter.\n\n## The rules\n\n- **At least one entity, at most 50.** More tables than that is a data model\n  being designed, not scaffolded \u2014 scaffold the rest in a second call.\n- **Adoption is explicit.** `lotics setup` REFUSES an entity whose `label`\n  already names a table in the workspace, naming every colliding label at once.\n  `lotics scaffold apply` adopts those tables and adds the fields, options and\n  views they are missing. Nothing is ever modified or deleted, so applying the\n  same model twice creates nothing the second time.\n- **Adoption is by LABEL, not alias.** Change an entity\'s `label` and the next\n  run asks for a NEW table beside the old one. Renames and deletions go through\n  `lotics run update_table` / `lotics run delete_table`, never through the file.\n- **Rows land only where every bound table is empty.** One table already holding\n  records and no rows are written anywhere, and the result says\n  `rows_skipped: true`: sample rows landing among a customer\'s real ones cannot\n  be told apart from them.\n- **After the first run the WORKSPACE is the source of truth.** The file is an\n  authoring input, not a mirror \u2014 scaffold never deletes what the file stopped\n  naming.\n- **`lotics scaffold check` decides all of it offline**, and reports every\n  problem in one run rather than the first: an alias that resolves to nothing, a\n  link whose pair is not symmetric, and the rows themselves \u2014 a field the entity\n  does not declare, an option alias the field does not declare, a link naming no\n  row in the file, a `ref` used twice, a date that is not one, and a value on a\n  files or platform-computed field.\n\n## Top level\n\n```jsonc\n{\n  "entities": [ /* the tables */ ],\n  "roles":    [ /* workspace groups to create */ ],    // optional\n  "templates":[ /* inline html / email templates */ ], // optional\n  "rows":     { /* first records, keyed by entity alias */ },  // optional\n  "apply":    [ /* published packages to copy in afterwards */ ], // optional\n  "preset":   { /* a trade\'s branches, for a PUBLISHED model */ } // optional\n}\n```\n\nThe other form names a preset instead of restating one:\n\n```jsonc\n{\n  "from":     "field_service",             // the preset this model starts from, by slug\n  "variants": ["crews"],                   // optional \u2014 its branches to merge in, in order\n  "rename":   {                            // optional \u2014 what THIS business calls each table\n    "job": { "label": "\u0110\u01A1n h\xE0ng", "fields": { "code": "M\xE3 \u0111\u01A1n" } }\n  },\n  "entities": [ /* tables the preset does not declare */ ],    // optional\n  "rows":     { /* first records, keyed by entity alias */ },  // optional\n  "apply":    [ /* published packages to copy in afterwards */ ] // optional\n}\n```\n\n**A model may not carry** `apps`, `fixtures`, `knowledge` or `knowledge_expects`,\nand no `excel` / `word` / `pdf-form` template: each of those is content that\nlives in a published bundle, which a model has none of. An unknown top-level key is\nan error, never ignored.\n\n### Aliases\n\nEvery `alias` is a lowercase slug \u2014 a letter, then letters, digits and\nunderscores (`unit_price`, `so_1001`). Aliases are how the file cross-references\nitself; they are never shown to anyone. `label` is what a person sees.\n\nLabels must be unique within their namespace \u2014 two entities, two fields on one\nentity, two options on one field, two views on one entity, two roles or two\ntemplates cannot share a label, because scaffold matches by label.\n\n## Entity\n\n```jsonc\n{\n  "alias": "order",\n  "label": "Orders",            // the table\'s name\n  "description": "\u2026",           // optional\n  "fields": [ /* at least one */ ],\n  "views":  [ /* optional; an entity with none still gets the default grid */ ]\n}\n```\n\n## Field\n\nEvery field carries `alias`, `label`, an optional `description`, and an optional\n`required` \u2014 advisory only, read by app forms and workflows; the table itself has\nno required constraint. `label` may not contain `{` or `}` (formulas reference\nfields by label at the platform level).\n\n`default` is the value pre-filled into a NEW record. It applies on create only;\nexisting records are never backfilled. Only the types listed below accept one.\n\n### `text`\n\n```jsonc\n{ "alias": "name", "label": "Name", "type": "text",\n  "unique": false,              // optional \u2014 require distinct values\n  "format": "text",             // optional \u2014 "text" | "link" | "markdown"\n  "default": "" }               // optional\n```\n\n### `number`\n\n```jsonc\n{ "alias": "amount", "label": "Amount", "type": "number",\n  "format": "currency",         // optional \u2014 "number" | "currency" | "percentage"\n  "currency": "VND",            // optional \u2014 ISO 4217\n  "default": 0 }                // optional\n```\n\n### `date`\n\n```jsonc\n{ "alias": "placed_on", "label": "Placed on", "type": "date",\n  "format": "date",             // optional \u2014 "date" | "datetime" | "date_range" | "datetime_range"\n  "timezone": "Asia/Ho_Chi_Minh",  // optional \u2014 IANA name\n  "derive_from": "created_at",  // optional \u2014 "created_at" | "updated_at"; makes the field read-only\n  "default": "2026-01-01" }     // optional; refused together with derive_from\n```\n\n### `boolean`\n\n```jsonc\n{ "alias": "paid", "label": "Paid", "type": "boolean", "default": false }\n```\n\n### `select`\n\n```jsonc\n{ "alias": "tier", "label": "Tier", "type": "select",\n  "options": [                                     // at least one\n    { "alias": "standard", "label": "Standard", "color": "slate" },\n    { "alias": "gold",     "label": "Gold",     "color": "amber" }\n  ],\n  "multi": false,               // optional\n  "default": ["standard"] }     // optional \u2014 option ALIASES; one unless multi\n```\n\n`color` is one of: `red`, `orange`, `amber`, `yellow`, `lime`, `green`,\n`emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`,\n`fuchsia`, `pink`, `rose`, `slate`, `gray`, `zinc`, `neutral`, `stone`.\n\n### `select_member`\n\nA person picker over the workspace\'s members. No default: a model cannot name\nmembers of a workspace that does not exist yet.\n\n```jsonc\n{ "alias": "owner", "label": "Owner", "type": "select_member", "multi": false }\n```\n\n### `select_record_link`\n\n```jsonc\n{ "alias": "customer", "label": "Customer", "type": "select_record_link",\n  "target_entity": "customer",        // an entity alias this model declares\n  "cardinality": "one",               // optional \u2014 "one" | "many" (default "many")\n  "sync_both_ways": true,             // optional \u2014 keep a paired field on the target\n  "paired_field_alias": "orders",     // the partner field ON THE TARGET entity\n  "display_field_aliases": ["name"] } // optional \u2014 what the link shows / the picker\'s columns\n```\n\nA two-way link is declared on BOTH sides, each naming the other as its\n`paired_field_alias`; the pair must be symmetric or the model is refused. Declare\none side only (with no `paired_field_alias`) for a link with no back-reference.\n\n### `files`\n\n```jsonc\n{ "alias": "attachments", "label": "Attachments", "type": "files" }\n```\n\n### `formula`\n\n```jsonc\n{ "alias": "total", "label": "Total", "type": "formula",\n  "formula": {\n    "expression": "{amount} * 1.1",  // fields on THIS entity, by alias, in braces\n    "format": "currency",            // optional \u2014 "number" | "currency" | "percentage" | "link"\n    "currency": "VND"                // optional\n  } }\n```\n\n### `rollup`\n\nAggregates the records reached through a link on this entity.\n\n```jsonc\n{ "alias": "total_ordered", "label": "Total ordered", "type": "rollup",\n  "source_field_alias": "orders",    // a select_record_link field on THIS entity\n  "aggregate_option": {\n    "operation": "sum",              // count | sum | avg | median | min | max | range |\n                                     // empty | filled | percent_empty | percent_filled |\n                                     // unique | percent_unique |\n                                     // earliest | latest | date_range |\n                                     // checked | unchecked | percent_checked |\n                                     // percent_unchecked\n    "field_key": "amount"            // a field ALIAS on the linked entity ("count" may omit it)\n  },\n  "filter": { /* optional \u2014 see Views; every field_key is an alias on the LINKED entity */ } }\n```\n\nThe operation must be one the aggregated field\'s type allows \u2014 `sum` over a\nnumber, `earliest` over a date, `filled` over anything.\n\n### `lookup`\n\nDisplays a field from the linked records.\n\n```jsonc\n{ "alias": "customer_tier", "label": "Customer tier", "type": "lookup",\n  "source_field_alias": "customer",  // a select_record_link field on THIS entity\n  "lookup_field_alias": "tier",      // a field alias on the linked entity\n  "order_by": { "field_key": "placed_on", "direction": "desc" } }  // optional \u2014 pick the single extreme row\n```\n\n### `autonumber`\n\n```jsonc\n{ "alias": "seq", "label": "No.", "type": "autonumber",\n  "prefix": "SO-",     // optional \u2014 ignored when template is set\n  "padding": 4,        // optional \u2014 1..20, zero-pads the integer\n  "template": "SO-{YEAR}-{N:4}" }  // optional \u2014 {N}, {N:W}, {YEAR}, {YEAR:2}, {MONTH}, {DAY}\n```\n\n## Views\n\nSaved views live under the entity they belong to. Every field reference is a\nfield ALIAS on that entity.\n\n```jsonc\n{\n  "alias": "gold",\n  "label": "Gold customers",\n  "description": "\u2026",                       // optional\n  "columns": [                              // optional \u2014 omit to show every field\n    { "field_alias": "name", "visibility": "visible", "width": 240 },\n    { "field_alias": "tier", "visibility": "hidden" }\n  ],\n  "filters": {                              // optional\n    "node_type": "group",\n    "logic": "and",                         // "and" | "or"\n    "children": [\n      { "node_type": "condition", "type": "select", "field_key": "tier",\n        "operator": "has_any_of", "value": ["gold"] }\n    ]\n  },\n  "sort": [ { "field_key": "name", "order": "asc" } ],  // optional; order is "asc" | "desc" | null\n  "summary": { "amount": "sum" },           // optional \u2014 field alias \u2192 footer operation\n  "frozen_columns": 1                       // optional\n}\n```\n\nA condition\'s `type` is the field\'s type and its `operator` is one that type\nadmits \u2014 `has_any_of` / `has_none_of` / `has_all_of` / `is_empty` /\n`is_not_empty` for a select, `equals` / `greater_than` / `less_than` for a\nnumber, `on` / `before` / `after` / `between` for a date, `contains` /\n`is_any_of` for text. A select condition\'s `value` names option ALIASES.\n\n`columns`, when present, is exhaustive and must not be empty: a view renders\nexactly the entries it holds. Omit the key to show every field.\n\n## Roles\n\nA role becomes a workspace group. Members are added afterwards, in the app.\n\n```jsonc\n{ "alias": "sales", "label": "Sales" }\n```\n\n## Templates\n\nOnly inline `html` and `email` templates \u2014 the rest are file-backed and a model\nhas no bytes.\n\n```jsonc\n{ "alias": "order_ack", "label": "Order acknowledgement", "type": "email",\n  "content": "<p>Hello {{customer}}\u2026</p>" }\n```\n\n## Rows\n\nFirst records, keyed by entity alias. Up to 200 rows per entity and 2000 across\nthe model \u2014 a real data set belongs in an import, not a model.\n\n```jsonc\n"rows": {\n  "customer": [\n    { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } }\n  ]\n}\n```\n\n`ref` is a local handle (lowercase letters, digits, underscores) that other rows\'\nlink fields address. It is never persisted.\n\n`fields` is keyed by field alias, and every value is read against the field\'s\nDECLARED type:\n\n| Field type | Value |\n|---|---|\n| `text` / `number` / `boolean` | the value itself |\n| `date` | `"2026-03-14"`, or a relative expression (below) |\n| `select` | the option ALIAS \u2014 `"gold"`, or `["gold","vip"]` for a multi-select |\n| `select_record_link` | `"<entity-alias>:<ref>"` naming another row in this file \u2014 `"customer:acme"`, or an array for several |\n| `select_member` | `"self"` only \u2014 the person applying the model |\n| `files` | not allowed |\n| `formula`, `rollup`, `lookup`, `autonumber` | not allowed \u2014 the platform writes these |\n\n### Relative dates\n\nA date cell holds a literal `YYYY-MM-DD`, or an expression relative to the day\nthe model is applied, so a screen that opens on "this month" is not empty a month\nlater:\n\n- `@today` \u2014 the day of the run, in the workspace\'s timezone\n- `@month-start` \u2014 the 1st of that month\n- either with a whole-day offset: `@today-14`, `@month-start+9`\n\n`@month-start` exists because `@today-N` cannot promise a month: applied on the\n2nd, `@today-3` lands in the previous one.\n\n## Applying packages\n\n`apply` copies published packages into the workspace AFTER the model\'s own\ntables exist \u2014 apps over the tables you just described, and any tables of their\nown they still need. Ordered, and run by `lotics setup` and `lotics scaffold\napply` alike.\n\n```jsonc\n"apply": [\n  {\n    "starter": "apg_k3nf82ldpq",\n    "bind": {                              // optional \u2014 which of YOUR tables each entity is\n      "company": { "label": "Customers", "fields": { "name": "Company name" } }\n    },\n    "no_sample_data": true                 // optional\n  }\n]\n```\n\n`bind` is keyed by the package\'s entity alias and holds the LABELS this\nworkspace uses: scaffold adopts by label, so binding points the package at the\ntables the model created instead of a second set beside them. Only naming\nmoves \u2014 a bound field must be the TYPE the package declares, or the copy is\nrefused. `lotics library list` is the shelf, and `lotics library show <apg_id>`\nlists the aliases to bind.\n\nEntries run in the order they are written, because a later one may bind onto a\ntable an earlier one created. **A refused entry stops the run and the entries\nbefore it stay** \u2014 they are separate copies, committed as they land, so the\nrefusal names them rather than leaving a caller to re-run the file and copy them\ntwice.\n\n## Presets\n\nA preset is a trade\'s model, published to be READ. An assistant reads it, asks\nat most two questions, picks a variant and writes a `model.json` from it \u2014\nnothing is copied, and a preset is a file rather than anything a workspace\ninstalls.\n\n```jsonc\n"preset": {\n  "name": "Field service",\n  "description": "Jobs, the crew that runs them, and what each one billed.",\n  "questions": ["Do you dispatch crews, or one person per job?"],  // at most 2\n  "variants": {\n    "crews": {\n      "when": "work is dispatched to crews rather than to one person",\n      "entities": [ /* tables this branch ADDS */ ],\n      "fields": { "job": [ /* fields this branch ADDS to `job` */ ] }\n    }\n  }\n}\n```\n\nVariants are **additive only**: a branch adds entities and fields and never\nremoves them, so the base is a model in its own right rather than a draft.\n`lotics scaffold check` proves the base AND every variant merged onto it, so a\npreset ships with every branch already proven \u2014 the branch nobody took is the\none that fails in the workspace of whoever takes it.\n\n`preset` is not scaffolded. `lotics setup` and `lotics scaffold apply` ignore\nit and create the base model\'s tables.\n\n## Starting from a preset\n\n`lotics library list` is the shelf of them and `lotics library show <slug>`\nprints one whole: its questions, every table as `alias \xB7 label` with each field\nas `alias:type`, and each variant as `slug \xB7 when` followed by the tables and\nfields that branch adds. When one of them is the trade in front of you, do not\ntranscribe it \u2014 name it:\n\n```jsonc\n{\n  "from": "field_service",\n  "variants": ["crews"],\n  "rename": { "job": { "label": "\u0110\u01A1n h\xE0ng", "fields": { "code": "M\xE3 \u0111\u01A1n" } } },\n  "entities": [ /* a table this business has that the preset does not */ ],\n  "rows": { "job": [ { "ref": "j1", "fields": { "code": "J-1" } } ] }\n}\n```\n\n- **`from`** is the preset\'s SLUG \u2014 its own file name, a lowercase slug. Naming\n  it is what makes `entities` optional; every other rule on this page is\n  unchanged, because the file is resolved into the full form and then checked and\n  applied exactly as one. A slug nothing serves is refused with the ones there\n  are, never resolved against something else.\n- **`variants`** names the branches to merge onto the base, in order. Pick the\n  one whose `when` describes what the person said; a slug the preset does not\n  declare is refused rather than ignored.\n- **`rename`** is keyed by the preset\'s entity alias and holds the labels this\n  business uses \u2014 the same shape `apply[].bind` takes, and the same rule: only\n  naming moves. An alias the preset does not declare, and a label that is\n  already another table\'s, are both refused.\n- **`entities`** are added after the rename, already in this business\'s own\n  words.\n- **`rows`** and **`apply`** mean exactly what they mean in the full form \u2014\n  `"rows"` are this business\'s real first records, `"apply"` the packages copied\n  in once its tables exist.\n\nThis is the ONE thing on this page that needs the network: `check` reads the\npreset it names, once. Everything after that read is the same offline check.\n\nWrite the full form when no preset is the trade.\n\n## A complete model\n\n```json\n{\n  "entities": [\n    {\n      "alias": "customer",\n      "label": "Customers",\n      "fields": [\n        { "alias": "name", "label": "Name", "type": "text", "required": true },\n        {\n          "alias": "tier",\n          "label": "Tier",\n          "type": "select",\n          "options": [\n            { "alias": "standard", "label": "Standard", "color": "slate" },\n            { "alias": "gold", "label": "Gold", "color": "amber" }\n          ],\n          "default": ["standard"]\n        },\n        {\n          "alias": "orders",\n          "label": "Orders",\n          "type": "select_record_link",\n          "target_entity": "order",\n          "cardinality": "many",\n          "sync_both_ways": true,\n          "paired_field_alias": "customer",\n          "display_field_aliases": ["code"]\n        },\n        {\n          "alias": "total_ordered",\n          "label": "Total ordered",\n          "type": "rollup",\n          "source_field_alias": "orders",\n          "aggregate_option": { "operation": "sum", "field_key": "amount" }\n        }\n      ],\n      "views": [\n        {\n          "alias": "gold",\n          "label": "Gold customers",\n          "filters": {\n            "node_type": "condition",\n            "type": "select",\n            "field_key": "tier",\n            "operator": "has_any_of",\n            "value": ["gold"]\n          },\n          "sort": [{ "field_key": "name", "order": "asc" }]\n        }\n      ]\n    },\n    {\n      "alias": "order",\n      "label": "Orders",\n      "fields": [\n        { "alias": "code", "label": "Order no.", "type": "text", "unique": true },\n        { "alias": "placed_on", "label": "Placed on", "type": "date", "format": "date" },\n        {\n          "alias": "amount",\n          "label": "Amount",\n          "type": "number",\n          "format": "currency",\n          "currency": "VND"\n        },\n        {\n          "alias": "total",\n          "label": "Total with VAT",\n          "type": "formula",\n          "formula": { "expression": "{amount} * 1.1", "format": "currency", "currency": "VND" }\n        },\n        {\n          "alias": "customer",\n          "label": "Customer",\n          "type": "select_record_link",\n          "target_entity": "customer",\n          "cardinality": "one",\n          "sync_both_ways": true,\n          "paired_field_alias": "orders",\n          "display_field_aliases": ["name"]\n        }\n      ]\n    }\n  ],\n  "roles": [{ "alias": "sales", "label": "Sales" }],\n  "rows": {\n    "customer": [\n      { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } },\n      { "ref": "bluebird", "fields": { "name": "Bluebird Foods", "tier": "standard" } }\n    ],\n    "order": [\n      {\n        "ref": "so_1001",\n        "fields": {\n          "code": "SO-1001",\n          "placed_on": "@month-start+2",\n          "amount": 4200000,\n          "customer": "customer:acme"\n        }\n      },\n      {\n        "ref": "so_1002",\n        "fields": {\n          "code": "SO-1002",\n          "placed_on": "@today-3",\n          "amount": 1150000,\n          "customer": "customer:bluebird"\n        }\n      }\n    ]\n  }\n}\n```\n\n`lotics scaffold check` on this file reports\n`2 tables, 9 fields, 2 links, 1 view, 1 role, 4 rows`.\n';
+var model_reference_default = '# The Lotics workspace model (`model.json`)\n\nOne JSON file describing the tables, fields, options, views, roles and first rows\na workspace starts with. `lotics scaffold check model.json` proves it offline \u2014\nno account, no network. `lotics setup model.json --email you@company.com` creates\nthe account and applies it. `lotics scaffold apply model.json` applies it again,\ninto the workspace the credential names.\n\n**There are two forms of this file.** The full one, below, spells the model out.\nThe `from` one names a published preset and carries only what this business\ndiffers by \u2014 see \xA7 Starting from a preset, and prefer it whenever a preset fits\nthe trade.\n\nApps are not a model\'s to declare \u2014 build one in the workspace the model\ncreated, then publish that workspace as a starter.\n\n## The rules\n\n- **At least one entity, at most 50.** More tables than that is a data model\n  being designed, not scaffolded \u2014 scaffold the rest in a second call.\n- **Adoption is explicit.** `lotics setup` REFUSES an entity whose `label`\n  already names a table in the workspace, naming every colliding label at once.\n  `lotics scaffold apply` adopts those tables and adds the fields, options and\n  views they are missing. Nothing is ever modified or deleted, so applying the\n  same model twice creates nothing the second time.\n- **Adoption is by LABEL, not alias.** Change an entity\'s `label` and the next\n  run asks for a NEW table beside the old one. Renames and deletions go through\n  `lotics run update_table` / `lotics run delete_table`, never through the file.\n- **Rows land only where every bound table is empty.** One table already holding\n  records and no rows are written anywhere, and the result says\n  `rows_skipped: true`: sample rows landing among a customer\'s real ones cannot\n  be told apart from them.\n- **After the first run the WORKSPACE is the source of truth.** The file is an\n  authoring input, not a mirror \u2014 scaffold never deletes what the file stopped\n  naming.\n- **`lotics scaffold check` decides all of it offline**, and reports every\n  problem in one run rather than the first: an alias that resolves to nothing, a\n  link whose pair is not symmetric, and the rows themselves \u2014 a field the entity\n  does not declare, an option alias the field does not declare, a link naming no\n  row in the file, a `ref` used twice, a date that is not one, and a value on a\n  files or platform-computed field.\n\n## Top level\n\n```jsonc\n{\n  "entities": [ /* the tables */ ],\n  "roles":    [ /* workspace groups to create */ ],    // optional\n  "templates":[ /* inline html / email templates */ ], // optional\n  "rows":     { /* first records, keyed by entity alias */ },  // optional\n  "apply":    [ /* published packages to copy in afterwards */ ], // optional\n  "preset":   { /* a trade\'s branches, for a PUBLISHED model */ } // optional\n}\n```\n\nThe other form names a preset instead of restating one:\n\n```jsonc\n{\n  "from":     "field_service",             // the preset this model starts from, by slug\n  "variants": ["crews"],                   // optional \u2014 its branches to merge in, in order\n  "rename":   {                            // optional \u2014 what THIS business calls each table\n    "job": { "label": "\u0110\u01A1n h\xE0ng", "fields": { "code": "M\xE3 \u0111\u01A1n" } }\n  },\n  "entities": [ /* tables the preset does not declare */ ],    // optional\n  "rows":     { /* first records, keyed by entity alias */ },  // optional\n  "apply":    [ /* published packages to copy in afterwards */ ] // optional\n}\n```\n\n**A model may not carry** `apps`, `fixtures`, `knowledge` or `knowledge_expects`,\nand no `excel` / `word` / `pdf-form` template: each of those is content that\nlives in a published bundle, which a model has none of. An unknown top-level key is\nan error, never ignored.\n\n### Aliases\n\nEvery `alias` is a lowercase slug \u2014 a letter, then letters, digits and\nunderscores (`unit_price`, `so_1001`). Aliases are how the file cross-references\nitself; they are never shown to anyone. `label` is what a person sees.\n\nLabels must be unique within their namespace \u2014 two entities, two fields on one\nentity, two options on one field, two views on one entity, two roles or two\ntemplates cannot share a label, because scaffold matches by label.\n\n## Entity\n\n```jsonc\n{\n  "alias": "order",\n  "label": "Orders",            // the table\'s name\n  "description": "\u2026",           // optional\n  "fields": [ /* at least one */ ],\n  "views":  [ /* optional; an entity with none still gets the default grid */ ]\n}\n```\n\n## Field\n\nEvery field carries `alias`, `label`, an optional `description`, and an optional\n`required` \u2014 advisory only, read by app forms and workflows; the table itself has\nno required constraint. `label` may not contain `{` or `}` (formulas reference\nfields by label at the platform level).\n\n`default` is the value pre-filled into a NEW record. It applies on create only;\nexisting records are never backfilled. Only the types listed below accept one.\n\n### `text`\n\n```jsonc\n{ "alias": "name", "label": "Name", "type": "text",\n  "unique": false,              // optional \u2014 require distinct values\n  "format": "text",             // optional \u2014 "text" | "link" | "markdown"\n  "default": "" }               // optional\n```\n\n### `number`\n\n```jsonc\n{ "alias": "amount", "label": "Amount", "type": "number",\n  "format": "currency",         // optional \u2014 "number" | "currency" | "percentage"\n  "currency": "VND",            // optional \u2014 ISO 4217\n  "default": 0 }                // optional\n```\n\n### `date`\n\n```jsonc\n{ "alias": "placed_on", "label": "Placed on", "type": "date",\n  "format": "date",             // optional \u2014 "date" | "datetime" | "date_range" | "datetime_range"\n  "timezone": "Asia/Ho_Chi_Minh",  // optional \u2014 IANA name\n  "derive_from": "created_at",  // optional \u2014 "created_at" | "updated_at"; makes the field read-only\n  "default": "2026-01-01" }     // optional; refused together with derive_from\n```\n\n### `boolean`\n\n```jsonc\n{ "alias": "paid", "label": "Paid", "type": "boolean", "default": false }\n```\n\n### `select`\n\n```jsonc\n{ "alias": "tier", "label": "Tier", "type": "select",\n  "options": [                                     // at least one\n    { "alias": "standard", "label": "Standard", "color": "slate" },\n    { "alias": "gold",     "label": "Gold",     "color": "amber" }\n  ],\n  "multi": false,               // optional\n  "default": ["standard"] }     // optional \u2014 option ALIASES; one unless multi\n```\n\n`color` is one of: `red`, `orange`, `amber`, `yellow`, `lime`, `green`,\n`emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`,\n`fuchsia`, `pink`, `rose`, `slate`, `gray`, `zinc`, `neutral`, `stone`.\n\n### `select_member`\n\nA person picker over the workspace\'s members. No default: a model cannot name\nmembers of a workspace that does not exist yet.\n\n```jsonc\n{ "alias": "owner", "label": "Owner", "type": "select_member", "multi": false }\n```\n\n### `select_record_link`\n\n```jsonc\n{ "alias": "customer", "label": "Customer", "type": "select_record_link",\n  "target_entity": "customer",        // an entity alias this model declares\n  "cardinality": "one",               // optional \u2014 "one" | "many" (default "many")\n  "sync_both_ways": true,             // optional \u2014 keep a paired field on the target\n  "paired_field_alias": "orders",     // the partner field ON THE TARGET entity\n  "display_field_aliases": ["name"] } // optional \u2014 what the link shows / the picker\'s columns\n```\n\nA two-way link is declared on BOTH sides, each naming the other as its\n`paired_field_alias`; the pair must be symmetric or the model is refused. Declare\none side only (with no `paired_field_alias`) for a link with no back-reference.\n\n### `files`\n\n```jsonc\n{ "alias": "attachments", "label": "Attachments", "type": "files" }\n```\n\n### `formula`\n\n```jsonc\n{ "alias": "total", "label": "Total", "type": "formula",\n  "formula": {\n    "expression": "{amount} * 1.1",  // fields on THIS entity, by alias, in braces\n    "format": "currency",            // optional \u2014 "number" | "currency" | "percentage" | "link"\n    "currency": "VND"                // optional\n  } }\n```\n\n### `rollup`\n\nAggregates the records reached through a link on this entity.\n\n```jsonc\n{ "alias": "total_ordered", "label": "Total ordered", "type": "rollup",\n  "source_field_alias": "orders",    // a select_record_link field on THIS entity\n  "aggregate_option": {\n    "operation": "sum",              // count | sum | avg | median | min | max | range |\n                                     // empty | filled | percent_empty | percent_filled |\n                                     // unique | percent_unique |\n                                     // earliest | latest | date_range |\n                                     // checked | unchecked | percent_checked |\n                                     // percent_unchecked\n    "field_key": "amount"            // a field ALIAS on the linked entity ("count" may omit it)\n  },\n  "filter": { /* optional \u2014 see Views; every field_key is an alias on the LINKED entity */ } }\n```\n\nThe operation must be one the aggregated field\'s type allows \u2014 `sum` over a\nnumber, `earliest` over a date, `filled` over anything.\n\n### `lookup`\n\nDisplays a field from the linked records.\n\n```jsonc\n{ "alias": "customer_tier", "label": "Customer tier", "type": "lookup",\n  "source_field_alias": "customer",  // a select_record_link field on THIS entity\n  "lookup_field_alias": "tier",      // a field alias on the linked entity\n  "order_by": { "field_key": "placed_on", "direction": "desc" } }  // optional \u2014 pick the single extreme row\n```\n\n### `autonumber`\n\n```jsonc\n{ "alias": "seq", "label": "No.", "type": "autonumber",\n  "prefix": "SO-",     // optional \u2014 ignored when template is set\n  "padding": 4,        // optional \u2014 1..20, zero-pads the integer\n  "template": "SO-{YEAR}-{N:4}" }  // optional \u2014 {N}, {N:W}, {YEAR}, {YEAR:2}, {MONTH}, {DAY}\n```\n\n## Views\n\nSaved views live under the entity they belong to. Every field reference is a\nfield ALIAS on that entity.\n\n```jsonc\n{\n  "alias": "gold",\n  "label": "Gold customers",\n  "description": "\u2026",                       // optional\n  "columns": [                              // optional \u2014 omit to show every field\n    { "field_alias": "name", "visibility": "visible", "width": 240 },\n    { "field_alias": "tier", "visibility": "hidden" }\n  ],\n  "filters": {                              // optional\n    "node_type": "group",\n    "logic": "and",                         // "and" | "or"\n    "children": [\n      { "node_type": "condition", "type": "select", "field_key": "tier",\n        "operator": "has_any_of", "value": ["gold"] }\n    ]\n  },\n  "sort": [ { "field_key": "name", "order": "asc" } ],  // optional; order is "asc" | "desc" | null\n  "summary": { "amount": "sum" },           // optional \u2014 field alias \u2192 footer operation\n  "frozen_columns": 1                       // optional\n}\n```\n\nA condition\'s `type` is the field\'s type and its `operator` is one that type\nadmits \u2014 `has_any_of` / `has_none_of` / `has_all_of` / `is_empty` /\n`is_not_empty` for a select, `equals` / `greater_than` / `less_than` for a\nnumber, `on` / `before` / `after` / `between` for a date, `contains` /\n`is_any_of` for text. A select condition\'s `value` names option ALIASES.\n\n`columns`, when present, is exhaustive and must not be empty: a view renders\nexactly the entries it holds. Omit the key to show every field.\n\n## Roles\n\nA role becomes a workspace group. Members are added afterwards, in the app.\n\n```jsonc\n{ "alias": "sales", "label": "Sales" }\n```\n\n## Templates\n\nOnly inline `html` and `email` templates \u2014 the rest are file-backed and a model\nhas no bytes.\n\n```jsonc\n{ "alias": "order_ack", "label": "Order acknowledgement", "type": "email",\n  "content": "<p>Hello {{customer}}\u2026</p>" }\n```\n\n## Rows\n\nFirst records, keyed by entity alias. Up to 200 rows per entity and 2000 across\nthe model \u2014 a real data set belongs in an import, not a model.\n\n```jsonc\n"rows": {\n  "customer": [\n    { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } }\n  ]\n}\n```\n\n`ref` is a local handle (lowercase letters, digits, underscores) that other rows\'\nlink fields address. It is never persisted.\n\n`fields` is keyed by field alias, and every value is read against the field\'s\nDECLARED type:\n\n| Field type | Value |\n|---|---|\n| `text` / `number` / `boolean` | the value itself |\n| `date` | `"2026-03-14"`, or a relative expression (below) |\n| `select` | the option ALIAS \u2014 `"gold"`, or `["gold","vip"]` for a multi-select |\n| `select_record_link` | `"<entity-alias>:<ref>"` naming another row in this file \u2014 `"customer:acme"`, or an array for several |\n| `select_member` | `"self"` only \u2014 the person applying the model |\n| `files` | not allowed |\n| `formula`, `rollup`, `lookup`, `autonumber` | not allowed \u2014 the platform writes these |\n\n### Relative dates\n\nA date cell holds a literal `YYYY-MM-DD`, or an expression relative to the day\nthe model is applied, so a screen that opens on "this month" is not empty a month\nlater:\n\n- `@today` \u2014 the day of the run, in the workspace\'s timezone\n- `@month-start` \u2014 the 1st of that month\n- either with a whole-day offset: `@today-14`, `@month-start+9`\n\n`@month-start` exists because `@today-N` cannot promise a month: applied on the\n2nd, `@today-3` lands in the previous one.\n\n## Applying packages\n\n`apply` copies published packages into the workspace AFTER the model\'s own\ntables exist \u2014 apps over the tables you just described, and any tables of their\nown they still need. Ordered, and run by `lotics setup` and `lotics scaffold\napply` alike.\n\n```jsonc\n"apply": [\n  {\n    "package": "apg_k3nf82ldpq",\n    "bind": {                              // optional \u2014 which of YOUR tables each entity is\n      "company": { "label": "Customers", "fields": { "name": "Company name" } }\n    },\n    "no_sample_data": true                 // optional\n  }\n]\n```\n\n`bind` is keyed by the package\'s entity alias and holds the LABELS this\nworkspace uses: scaffold adopts by label, so binding points the package at the\ntables the model created instead of a second set beside them. Only naming\nmoves \u2014 a bound field must be the TYPE the package declares, or the copy is\nrefused. `lotics library list` is the shelf, and `lotics library show <apg_id>`\nlists the aliases to bind.\n\nEntries run in the order they are written, because a later one may bind onto a\ntable an earlier one created. **A refused entry stops the run and the entries\nbefore it stay** \u2014 they are separate copies, committed as they land, so the\nrefusal names them rather than leaving a caller to re-run the file and copy them\ntwice.\n\n## Presets\n\nA preset is a trade\'s model, published to be READ. An assistant reads it, asks\nat most two questions, picks a variant and writes a `model.json` from it \u2014\nnothing is copied, and a preset is a file rather than anything a workspace\ninstalls.\n\n```jsonc\n"preset": {\n  "name": "Field service",\n  "description": "Jobs, the crew that runs them, and what each one billed.",\n  "questions": ["Do you dispatch crews, or one person per job?"],  // at most 2\n  "variants": {\n    "crews": {\n      "when": "work is dispatched to crews rather than to one person",\n      "entities": [ /* tables this branch ADDS */ ],\n      "fields": { "job": [ /* fields this branch ADDS to `job` */ ] }\n    }\n  }\n}\n```\n\nVariants are **additive only**: a branch adds entities and fields and never\nremoves them, so the base is a model in its own right rather than a draft.\n`lotics scaffold check` proves the base AND every variant merged onto it, so a\npreset ships with every branch already proven \u2014 the branch nobody took is the\none that fails in the workspace of whoever takes it.\n\n`preset` is not scaffolded. `lotics setup` and `lotics scaffold apply` ignore\nit and create the base model\'s tables.\n\n`lotics scaffold export` prints a workspace that already works as one of these\nfiles \u2014 the starting point for a preset or for another business\'s model, never a\nsource of truth: it carries one business\'s words and stops describing that\nworkspace the moment either changes.\n\n## Starting from a preset\n\n`lotics library list` is the shelf of them and `lotics library show <slug>`\nprints one whole: its questions, every table as `alias \xB7 label` with each field\nas `alias:type`, and each variant as `slug \xB7 when` followed by the tables and\nfields that branch adds. When one of them is the trade in front of you, do not\ntranscribe it \u2014 name it:\n\n```jsonc\n{\n  "from": "field_service",\n  "variants": ["crews"],\n  "rename": { "job": { "label": "\u0110\u01A1n h\xE0ng", "fields": { "code": "M\xE3 \u0111\u01A1n" } } },\n  "entities": [ /* a table this business has that the preset does not */ ],\n  "rows": { "job": [ { "ref": "j1", "fields": { "code": "J-1" } } ] }\n}\n```\n\n- **`from`** is the preset\'s SLUG \u2014 its own file name, a lowercase slug. Naming\n  it is what makes `entities` optional; every other rule on this page is\n  unchanged, because the file is resolved into the full form and then checked and\n  applied exactly as one. A slug nothing serves is refused with the ones there\n  are, never resolved against something else.\n- **`variants`** names the branches to merge onto the base, in order. Pick the\n  one whose `when` describes what the person said; a slug the preset does not\n  declare is refused rather than ignored.\n- **`rename`** is keyed by the preset\'s entity alias and holds the labels this\n  business uses \u2014 the same shape `apply[].bind` takes, and the same rule: only\n  naming moves. An alias the preset does not declare, and a label that is\n  already another table\'s, are both refused.\n- **`entities`** are added after the rename, already in this business\'s own\n  words.\n- **`rows`** and **`apply`** mean exactly what they mean in the full form \u2014\n  `"rows"` are this business\'s real first records, `"apply"` the packages copied\n  in once its tables exist.\n\nThis is the ONE thing on this page that needs the network: `check` reads the\npreset it names, once. Everything after that read is the same offline check.\n\nWrite the full form when no preset is the trade.\n\n## A complete model\n\n```json\n{\n  "entities": [\n    {\n      "alias": "customer",\n      "label": "Customers",\n      "fields": [\n        { "alias": "name", "label": "Name", "type": "text", "required": true },\n        {\n          "alias": "tier",\n          "label": "Tier",\n          "type": "select",\n          "options": [\n            { "alias": "standard", "label": "Standard", "color": "slate" },\n            { "alias": "gold", "label": "Gold", "color": "amber" }\n          ],\n          "default": ["standard"]\n        },\n        {\n          "alias": "orders",\n          "label": "Orders",\n          "type": "select_record_link",\n          "target_entity": "order",\n          "cardinality": "many",\n          "sync_both_ways": true,\n          "paired_field_alias": "customer",\n          "display_field_aliases": ["code"]\n        },\n        {\n          "alias": "total_ordered",\n          "label": "Total ordered",\n          "type": "rollup",\n          "source_field_alias": "orders",\n          "aggregate_option": { "operation": "sum", "field_key": "amount" }\n        }\n      ],\n      "views": [\n        {\n          "alias": "gold",\n          "label": "Gold customers",\n          "filters": {\n            "node_type": "condition",\n            "type": "select",\n            "field_key": "tier",\n            "operator": "has_any_of",\n            "value": ["gold"]\n          },\n          "sort": [{ "field_key": "name", "order": "asc" }]\n        }\n      ]\n    },\n    {\n      "alias": "order",\n      "label": "Orders",\n      "fields": [\n        { "alias": "code", "label": "Order no.", "type": "text", "unique": true },\n        { "alias": "placed_on", "label": "Placed on", "type": "date", "format": "date" },\n        {\n          "alias": "amount",\n          "label": "Amount",\n          "type": "number",\n          "format": "currency",\n          "currency": "VND"\n        },\n        {\n          "alias": "total",\n          "label": "Total with VAT",\n          "type": "formula",\n          "formula": { "expression": "{amount} * 1.1", "format": "currency", "currency": "VND" }\n        },\n        {\n          "alias": "customer",\n          "label": "Customer",\n          "type": "select_record_link",\n          "target_entity": "customer",\n          "cardinality": "one",\n          "sync_both_ways": true,\n          "paired_field_alias": "orders",\n          "display_field_aliases": ["name"]\n        }\n      ]\n    }\n  ],\n  "roles": [{ "alias": "sales", "label": "Sales" }],\n  "rows": {\n    "customer": [\n      { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } },\n      { "ref": "bluebird", "fields": { "name": "Bluebird Foods", "tier": "standard" } }\n    ],\n    "order": [\n      {\n        "ref": "so_1001",\n        "fields": {\n          "code": "SO-1001",\n          "placed_on": "@month-start+2",\n          "amount": 4200000,\n          "customer": "customer:acme"\n        }\n      },\n      {\n        "ref": "so_1002",\n        "fields": {\n          "code": "SO-1002",\n          "placed_on": "@today-3",\n          "amount": 1150000,\n          "customer": "customer:bluebird"\n        }\n      }\n    ]\n  }\n}\n```\n\n`lotics scaffold check` on this file reports\n`2 tables, 9 fields, 2 links, 1 view, 1 role, 4 rows`.\n';
 
 // src/scaffold_commands.ts
 function printModelReference() {
@@ -77635,6 +77686,23 @@ function reportModelFindings(file2, findings) {
   The model's shape, every field type and a worked example:  lotics scaffold docs`
   );
 }
+async function scaffoldExport(client, opts = {}) {
+  const { contract, findings } = await client.exportWorkspaceModel(opts);
+  const file2 = { entities: contract.entities };
+  if (contract.roles.length > 0) file2.roles = contract.roles;
+  if (contract.templates.length > 0) file2.templates = contract.templates;
+  process.stdout.write(`${JSON.stringify(file2, null, 2)}
+`);
+  for (const finding of findings) {
+    console.error(`  \u2022 ${finding.severity}  ${finding.area}: ${finding.message}`);
+  }
+  const errors2 = findings.filter((finding) => finding.severity === "error").length;
+  if (errors2 > 0) {
+    console.error(`
+  ${count(errors2, "error")} \u2014 the file above does not describe this workspace in full.`);
+    process.exitCode = 1;
+  }
+}
 function scaffoldJson(target, result, applied, signinUrl) {
   return {
     ...target,
@@ -77642,7 +77710,7 @@ function scaffoldJson(target, result, applied, signinUrl) {
     // Always present, empty included: a caller reading this object indexes
     // `applied` to find the apps, and a key that appears only sometimes makes
     // "this model applied nothing" and "this CLI is too old" the same value.
-    applied: applied.map((entry) => ({ starter_id: entry.starter_id, apps: entry.apps })),
+    applied: applied.map((entry) => ({ package: entry.package, apps: entry.apps })),
     ...signinUrl === void 0 ? {} : { signin_url: signinUrl }
   };
 }
@@ -77656,22 +77724,22 @@ async function applyModelPackages(client, entries2) {
   const applied = [];
   for (const entry of entries2) {
     note(`
-Applying ${entry.starter}\u2026`);
+Applying ${entry.package}\u2026`);
     try {
       const copy = await copyPackage(client, {
-        starter_id: entry.starter,
+        starter_id: entry.package,
         adopt: true,
         ...entry.no_sample_data === true ? { noSampleData: true } : {},
         ...entry.bind !== void 0 ? { bind: entry.bind } : {}
       });
-      applied.push({ starter_id: entry.starter, apps: copy.apps });
+      applied.push({ package: entry.package, apps: copy.apps });
     } catch (error52) {
       throw new Error(
         `${error52 instanceof Error ? error52.message : String(error52)}
 
-  ${entry.starter} was refused, so the rest of this model's apply list did not run.
-  The tables${applied.length > 0 ? ` and ${applied.map((one) => one.starter_id).join(", ")}` : ""} already landed and must not be applied again \u2014 fix this entry
-  and copy it on its own:  lotics library init ${entry.starter}`
+  ${entry.package} was refused, so the rest of this model's apply list did not run.
+  The tables${applied.length > 0 ? ` and ${applied.map((one) => one.package).join(", ")}` : ""} already landed and must not be applied again \u2014 fix this entry
+  and copy it on its own:  lotics library init ${entry.package}`
       );
     }
   }
@@ -77741,39 +77809,93 @@ function requireNonEmpty(value2, field) {
     );
   }
 }
-async function awaitCliLogin(email3, options) {
+function signInPageUrl(pending) {
+  return `${WEB_APP_URL}/cli_login/${pending.request_id}`;
+}
+function expirySentence(pending) {
+  const remaining = Date.parse(pending.expires_at) - Date.now();
+  if (!Number.isFinite(remaining) || remaining <= 0) return "";
+  return ` The request expires in ${Math.max(1, Math.round(remaining / 6e4))} minutes.`;
+}
+function signInInstructions(pending, options) {
+  const ask = `Sign in from your browser: open ${signInPageUrl(pending)} (also in a mail to ${pending.email}), sign in if asked, check that the page shows code ${pending.code}, and press Confirm.`;
+  const then = options.waiting ? `Waiting here until you press Confirm.${expirySentence(pending)}` : `Then run your command again \u2014 this terminal picks up the key on its next command.${expirySentence(pending)}`;
+  return `${ask}
+${then}`;
+}
+async function startPendingLogin(email3) {
   const request = await startCliLogin(email3);
-  console.error(
-    `Check ${email3} for a sign-in link. Open it and press Confirm \u2014 the page shows code ${request.code}. Waiting\u2026`
-  );
-  const expiresAt = Date.parse(request.expires_at);
+  const pending = {
+    request_id: request.request_id,
+    secret: request.secret,
+    code: request.code,
+    expires_at: request.expires_at,
+    email: email3,
+    api_url: API_BASE_URL
+  };
+  savePendingLogin(pending);
+  return pending;
+}
+function saveApproval(state, email3, options) {
+  requireNonEmpty(state.api_key, "api_key");
+  requireNonEmpty(state.organization_id, "organization_id");
+  requireNonEmpty(state.workspace_id, "workspace_id");
+  upsertProfile(state.organization_id, {
+    api_key: state.api_key,
+    org_name: state.organization_name,
+    workspace_id: state.workspace_id
+  });
+  const existing = loadGlobalConfig() ?? {};
+  saveGlobalConfig({ ...existing, email: email3 });
+  setActiveOrg(state.organization_id, options?.local === true ? "local" : "global");
+  clearPendingLogin();
+  return {
+    email: email3,
+    orgId: state.organization_id,
+    orgName: state.organization_name,
+    workspaceId: state.workspace_id
+  };
+}
+async function claimPendingLogin() {
+  const pending = loadPendingLogin();
+  if (!pending) return { status: "none" };
+  const expired = `The sign-in request expired. Run again:  lotics auth login ${pending.email}`;
+  if (Date.parse(pending.expires_at) <= Date.now()) {
+    clearPendingLogin();
+    return pending.api_url === API_BASE_URL ? { status: "gone", message: expired } : { status: "none" };
+  }
+  if (pending.api_url !== API_BASE_URL) return { status: "none" };
+  const state = await pollCliLogin(pending.request_id, pending.secret);
+  if (state.status === "approved") {
+    return { status: "signed_in", account: saveApproval(state, pending.email) };
+  }
+  if (state.status === "pending") {
+    return {
+      status: "waiting",
+      message: `Still waiting for Confirm on ${signInPageUrl(pending)} (code ${pending.code}). Press it, then run this again \u2014 or ask again for a new one:  lotics auth login ${pending.email}`
+    };
+  }
+  clearPendingLogin();
+  return {
+    status: "gone",
+    message: state.status === "claimed" ? `The sign-in request was already used. Run again:  lotics auth login ${pending.email}` : expired
+  };
+}
+async function awaitCliLogin(email3, options) {
+  const pending = await startPendingLogin(email3);
+  console.error(signInInstructions(pending, { waiting: true }));
+  const expiresAt = Date.parse(pending.expires_at);
   for (; ; ) {
     let state;
     try {
-      state = await pollCliLogin(request.request_id, request.secret);
+      state = await pollCliLogin(pending.request_id, pending.secret);
     } catch (error52) {
       if (!(Date.now() < expiresAt)) throw error52;
       await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL_MS));
       continue;
     }
     if (state.status === "approved") {
-      requireNonEmpty(state.api_key, "api_key");
-      requireNonEmpty(state.organization_id, "organization_id");
-      requireNonEmpty(state.workspace_id, "workspace_id");
-      upsertProfile(state.organization_id, {
-        api_key: state.api_key,
-        org_name: state.organization_name,
-        workspace_id: state.workspace_id
-      });
-      const existing = loadGlobalConfig() ?? {};
-      saveGlobalConfig({ ...existing, email: email3 });
-      setActiveOrg(state.organization_id, options?.local === true ? "local" : "global");
-      return {
-        email: email3,
-        orgId: state.organization_id,
-        orgName: state.organization_name,
-        workspaceId: state.workspace_id
-      };
+      return saveApproval(state, email3, options);
     }
     if (state.status === "expired") {
       throw new Error(`That sign-in link expired. Run "lotics auth login ${email3}" again.`);
@@ -106702,8 +106824,8 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
 AUTHENTICATION
   lotics auth                          Show auth help
   lotics auth signup <email>           Create account (run "lotics auth" for details)
-  lotics auth login <email>            Sign in on this machine \u2014 Lotics emails a link, you
-                                       open it and press Confirm
+  lotics auth login <email>            Sign in on this machine \u2014 open the page it names,
+                                       press Confirm, then run your command again
   lotics auth api-key <key>            Save a key \u2014 registers its org as a profile
 
 ORGANIZATIONS
@@ -106745,7 +106867,11 @@ FLAGS
   --view-as <id>     Admin "View as": run every request as this member, so
                      is_current_member / row-scoping resolve to them (also
                      LOTICS_VIEW_AS env; admin key only; writes stay yours)
-  --local            Pin the current directory (lotics org use / auth login / auth api-key)
+  --local            Pin the current directory (lotics org use / auth login / auth api-key).
+                     On auth login / setup it implies --wait: only the terminal that
+                     stays in this directory can write its pin
+  --wait             (auth login / setup) Hold this terminal until Confirm is pressed,
+                     instead of picking the key up on the next command
   --all              (lotics auth logout) Remove every saved credential
   --version          Show version
 
@@ -106788,10 +106914,12 @@ function printAuthHelp() {
   console.log(`Authentication commands:
 
   lotics auth signup <email>           Create account, org, workspace, and API key
-  lotics auth login <email>            Sign in an account that already exists \u2014 Lotics emails
-                                       a link, you open it and press Confirm on the page
-                                       showing the code this command printed, and the key
-                                       lands here. --json prints one object and nothing else
+  lotics auth login <email>            Sign in an account that already exists. It does NOT
+                                       wait: it prints the page to open (also mailed) and the
+                                       code that page must show, and exits. Press Confirm,
+                                       then run your command again \u2014 this terminal picks the
+                                       key up on its next command. --wait holds the terminal
+                                       instead. --json prints one object and nothing else
   lotics auth api-key [key]            Save an API key \u2014 registers its org as a profile
   lotics auth web                      Send a magic link email to access the web app
   lotics auth whoami                   Show the active account, org, workspace, and source
@@ -106802,7 +106930,11 @@ function printAuthHelp() {
 Auth flags:
   --local                Pin the current directory instead of the global store.
                          signup/login/api-key write a ./.lotics/config.json pointer
-                         \u2014 the key itself stays in the global store.
+                         \u2014 the key itself stays in the global store. On login it
+                         implies --wait: a pin names THIS directory, and only the
+                         terminal that stays in it can write one.
+  --wait                 (login) Hold this terminal until Confirm is pressed, rather
+                         than picking the key up on the next command.
   --name <name>          (signup) Display name (defaults to email prefix)
   --timezone <timezone>  (signup) Workspace timezone (defaults to this machine's, e.g. Asia/Ho_Chi_Minh)
 
@@ -106939,15 +107071,38 @@ async function handleSignup(positionalEmail, flags) {
 Check your email for a magic link to access the Lotics web app.`);
   console.error(`Run "lotics auth web" to request a new link at any time.`);
 }
+function waitsForConfirm(flags) {
+  return flags.wait || flags.local;
+}
 async function handleLogin(positionalEmail, flags) {
   const email3 = positionalEmail ?? (process.stdin.isTTY ? await prompt("Email: ") : "");
   if (!email3) {
     console.error("Email is required. Usage: lotics auth login <email>");
     process.exit(1);
   }
+  if (!waitsForConfirm(flags)) {
+    const pending = await startPendingLogin(email3);
+    console.error(signInInstructions(pending, { waiting: false }));
+    if (flags.json) {
+      console.log(
+        JSON.stringify(
+          {
+            request_id: pending.request_id,
+            confirm_url: signInPageUrl(pending),
+            code: pending.code,
+            email: pending.email,
+            expires_at: pending.expires_at
+          },
+          null,
+          2
+        )
+      );
+    }
+    return;
+  }
   let account;
   try {
-    account = await awaitCliLogin(email3, flags.local === true ? { local: true } : {});
+    account = await awaitCliLogin(email3, flags.local ? { local: true } : {});
   } catch (error52) {
     console.error(error52 instanceof Error ? error52.message : String(error52));
     process.exit(1);
@@ -107004,6 +107159,7 @@ Multiple workspaces in ${info.organization_name}. Run "lotics workspace select <
   const existing = loadGlobalConfig() ?? {};
   saveGlobalConfig({ ...existing, email: info.email });
   setActiveOrg(info.organization_id, local ? "local" : "global");
+  clearPendingLogin();
   if (local) {
     console.error(`Authenticated as ${info.email} in ${info.organization_name}.`);
     console.error(`  Pinned this directory: ${getConfigPath("local")}`);
@@ -107012,8 +107168,23 @@ Multiple workspaces in ${info.organization_name}. Run "lotics workspace select <
     console.error(`  Saved to the "${info.organization_name}" profile in ~/.lotics`);
   }
 }
-function requireClient(flags, appWorkspaceId) {
-  const ctx = resolveContext(flags, appWorkspaceId);
+async function resolveContextOrClaim(flags, options) {
+  const appWorkspaceId = options?.appWorkspaceId;
+  const resolved = resolveContext(flags, appWorkspaceId);
+  if (resolved) return { ctx: resolved, claimed: null };
+  const claim = await claimPendingLogin();
+  if (claim.status === "none") return { ctx: null, claimed: null };
+  if (claim.status !== "signed_in") return { ctx: null, claimed: null, refusal: claim.message };
+  const { account } = claim;
+  note(`Signed in as ${account.email} \u2014 org ${account.orgName} (${account.orgId}).`);
+  return { ctx: resolveContext(flags, appWorkspaceId), claimed: account };
+}
+async function requireClient(flags, appWorkspaceId) {
+  const { ctx, refusal } = await resolveContextOrClaim(flags, { appWorkspaceId });
+  if (refusal !== void 0) {
+    console.error(refusal);
+    process.exit(1);
+  }
   if (!ctx) {
     console.error('Not authenticated. Run "lotics auth signup", "lotics auth api-key <key>", or set LOTICS_API_KEY.');
     process.exit(1);
@@ -107157,9 +107328,10 @@ async function main() {
   if (command === "setup") {
     const target = subcommand;
     if (!target) {
-      console.error("Usage: lotics setup <starter_id | model.json> [--email <you@co.com>] [--json]");
-      console.error("       Creates an account if this machine has none \u2014 or signs in the one that");
-      console.error("       email already has, by mailing a link \u2014 then fills its workspace.");
+      console.error("Usage: lotics setup <apg_id | model.json> [--email <you@co.com>] [--json]");
+      console.error("       Creates an account if this machine has none \u2014 or, when that email");
+      console.error("       already has one, prints a sign-in page and stops with nothing created;");
+      console.error("       press Confirm and run the same command again. Then fills its workspace.");
       console.error("       A STARTER id copies a published setup whole: schema, templates,");
       console.error("       knowledge docs, sample records and its apps, deployed.");
       console.error("       A model \u2014 any *.json file \u2014 creates the tables, fields, views, roles");
@@ -107180,7 +107352,11 @@ async function main() {
     if (toolArgs !== void 0) {
       warn(`A path is no longer needed \u2014 setup writes nothing to disk. Ignoring "${toolArgs}".`);
     }
-    const existing = resolveContext(flags);
+    const { ctx: existing, claimed, refusal } = await resolveContextOrClaim(flags);
+    if (refusal !== void 0) {
+      console.error(refusal);
+      process.exit(1);
+    }
     if (existing === null) {
       const email3 = flags.email ?? (process.stdin.isTTY ? await prompt("Email: ") : "");
       if (!email3) {
@@ -107197,10 +107373,13 @@ async function main() {
           ...flags.local === true ? { local: true } : {}
         });
         if (outcome.kind === "email_taken") {
-          const account = await awaitCliLogin(
-            email3,
-            flags.local === true ? { local: true } : {}
-          );
+          if (!waitsForConfirm(flags)) {
+            const pending = await startPendingLogin(email3);
+            console.error(signInInstructions(pending, { waiting: false }));
+            console.error("Then run this same command again.");
+            process.exit(1);
+          }
+          const account = await awaitCliLogin(email3, flags.local ? { local: true } : {});
           note(`Signed in as ${account.email} \u2014 org ${account.orgName} (${account.orgId}).`);
         } else {
           const { account } = outcome;
@@ -107210,7 +107389,7 @@ async function main() {
         console.error(error52 instanceof Error ? error52.message : String(error52));
         process.exit(1);
       }
-    } else if (flags.email !== void 0) {
+    } else if (flags.email !== void 0 && claimed?.email.toLowerCase() !== flags.email.toLowerCase()) {
       console.error(
         `Already authenticated (${SOURCE_LABELS[existing.source]}), so --email would create a SECOND account and set that one up instead.
   Use the account you have:     lotics setup ${target}
@@ -107218,7 +107397,7 @@ async function main() {
       );
       process.exit(1);
     }
-    const { client: client2, ctx: ctx2 } = requireClient(flags);
+    const { client: client2, ctx: ctx2 } = await requireClient(flags);
     await resolveWorkspace(client2, ctx2);
     if (model !== null) {
       const run = await scaffoldApply(client2, model.model, { file: target, adopt: false });
@@ -107250,6 +107429,12 @@ async function main() {
       printModelReference();
       return;
     }
+    if (subcommand === "export") {
+      const { client: client2, ctx: ctx2 } = await requireClient(flags);
+      await resolveWorkspace(client2, ctx2);
+      await scaffoldExport(client2, flags.tables.length > 0 ? { tables: flags.tables } : {});
+      return;
+    }
     if (subcommand === "check" || subcommand === "apply") {
       if (!toolArgs) {
         console.error(`Usage: lotics scaffold ${subcommand} <model.json>`);
@@ -107271,7 +107456,7 @@ async function main() {
         else console.log(summarizeModel(checked.model));
         return;
       }
-      const { client: client2, ctx: ctx2 } = requireClient(flags);
+      const { client: client2, ctx: ctx2 } = await requireClient(flags);
       await resolveWorkspace(client2, ctx2);
       const run = await scaffoldApply(client2, checked.model, { file: toolArgs, adopt: true });
       if (flags.json) {
@@ -107285,12 +107470,16 @@ async function main() {
       }
       return;
     }
-    console.error("Usage: lotics scaffold docs | check <model.json> | apply <model.json>");
+    console.error(
+      "Usage: lotics scaffold docs | check <model.json> | apply <model.json> | export [--tables <ids>]"
+    );
     console.error("       docs   \u2014 how to write a model, with a worked example (offline)");
     console.error("       check  \u2014 prove one, offline, before anyone has an account");
     console.error("       apply  \u2014 create it here; a table of the same name is ADOPTED and");
     console.error("                added to, never modified, and rows land only where every");
     console.error("                bound table is empty");
+    console.error("       export \u2014 print this workspace's tables as a model file, to edit into");
+    console.error("                a preset or the starting model for another business");
     process.exit(1);
   }
   if (command === "library") {
@@ -107299,7 +107488,7 @@ async function main() {
         await libraryListPublic();
         return;
       }
-      const { client: client2, ctx: ctx2 } = requireClient(flags);
+      const { client: client2, ctx: ctx2 } = await requireClient(flags);
       await resolveWorkspace(client2, ctx2);
       await libraryList(client2);
       return;
@@ -107336,7 +107525,7 @@ async function main() {
           emitJson(published.package);
           return;
         }
-        const { client: client3 } = requireClient(flags);
+        const { client: client3 } = await requireClient(flags);
         const pkg = await client3.getStarter(toolArgs);
         if (pkg.latest_version === 0) {
           console.error(`${toolArgs} has released no version yet, so it declares no contract.`);
@@ -107356,7 +107545,7 @@ async function main() {
         await libraryShowPublic(toolArgs);
         return;
       }
-      const { client: client2, ctx: ctx2 } = requireClient(flags);
+      const { client: client2, ctx: ctx2 } = await requireClient(flags);
       await resolveWorkspace(client2, ctx2);
       await libraryShow(client2, toolArgs);
       return;
@@ -107382,7 +107571,7 @@ async function main() {
         console.error(parsedBind.error);
         process.exit(1);
       }
-      const { client: client2, ctx: ctx2 } = requireClient(flags);
+      const { client: client2, ctx: ctx2 } = await requireClient(flags);
       await resolveWorkspace(client2, ctx2);
       if (restArgs[0] !== void 0) warn(`A path is no longer needed \u2014 a copy writes nothing to disk. Ignoring "${restArgs[0]}".`);
       const result = await libraryInit(client2, {
@@ -107412,7 +107601,7 @@ async function main() {
           process.exit(1);
         }
       }
-      const { client: client2, ctx: ctx2 } = requireClient(flags);
+      const { client: client2, ctx: ctx2 } = await requireClient(flags);
       await resolveWorkspace(client2, ctx2);
       await libraryFixturesCapture(client2, {
         entities: flags.entity,
@@ -107459,7 +107648,12 @@ async function main() {
       console.error(REPORT_USAGE);
       process.exit(1);
     }
-    const reportCtx = resolveContext(flags);
+    const { ctx: reportCtx, refusal } = await resolveContextOrClaim(flags);
+    if (refusal !== void 0) {
+      console.error(refusal);
+      echoReport(parsed2.report);
+      process.exit(1);
+    }
     if (!reportCtx) {
       console.error(
         'Not authenticated, so this could not be sent. Run "lotics auth signup", "lotics auth api-key <key>", or set LOTICS_API_KEY.'
@@ -107492,7 +107686,11 @@ async function main() {
       return;
     }
     if (subcommand === "whoami") {
-      const ctx2 = resolveContext(flags);
+      const { ctx: ctx2, refusal } = await resolveContextOrClaim(flags);
+      if (refusal !== void 0) {
+        console.error(refusal);
+        process.exit(1);
+      }
       if (!ctx2) {
         console.error('Not authenticated. Run "lotics auth signup", "lotics auth api-key <key>", or set LOTICS_API_KEY.');
         process.exit(1);
@@ -107548,11 +107746,12 @@ async function main() {
       }
       const [orgId, profile] = resolved;
       removeProfile(orgId);
+      clearPendingLogin();
       console.error(`Removed the "${profile.org_name}" credential (${orgId}).`);
       return;
     }
     if (subcommand === "web") {
-      const { client: client2 } = requireClient(flags);
+      const { client: client2 } = await requireClient(flags);
       const { email: email3 } = await client2.login();
       console.error(`Magic link sent to ${email3}. Check your email to access the Lotics web app.`);
       return;
@@ -107574,7 +107773,7 @@ async function main() {
   }
   if (command === "preview") {
     if (subcommand && isStoredFileId(subcommand)) {
-      const { client: client2 } = requireClient(flags);
+      const { client: client2 } = await requireClient(flags);
       const tmpDir = fs15.mkdtempSync(path12.join(os4.tmpdir(), "lotics-preview-"));
       try {
         const { path: localPath, filename } = await client2.downloadFileById(subcommand, tmpDir);
@@ -107739,7 +107938,7 @@ async function main() {
     process.exit(1);
   }
   const appPathArg = subcommand === "dev" ? toolArgs : void 0;
-  const { client, ctx } = requireClient(
+  const { client, ctx } = await requireClient(
     flags,
     appManifestWorkspaceId(command, subcommand, appPathArg, flags)
   );

package/dist/src/client.d.ts

@@ -306,6 +306,31 @@ export interface ScaffoldWorkspaceResult {
     /** Rows were sent and none were written, because the run adopted a table. */
     rows_skipped: boolean;
 }
+/**
+ * A workspace read BACK as a model — the inverse of the scaffold above.
+ *
+ * `entities` and `roles` are the model file's own two keys, whose authoritative
+ * shapes are `contractEntitySchema` / `contractRoleSchema` in `@lotics/shared` —
+ * specifiers a published `.d.ts` cannot resolve, so they are typed here as what
+ * this client does with them, which is hand them on whole. The same trade
+ * `ScaffoldWorkspaceRequest` makes in the other direction.
+ *
+ * `findings` are about the export rather than part of it: a workspace holds
+ * things a model file cannot express, and a file that dropped them silently
+ * would be read as the whole workspace.
+ */
+export interface WorkspaceModelExport {
+    contract: {
+        entities: Array<Record<string, unknown>>;
+        roles: Array<Record<string, unknown>>;
+        templates: Array<Record<string, unknown>>;
+    };
+    findings: Array<{
+        severity: "error" | "warning" | "info";
+        area: string;
+        message: string;
+    }>;
+}
 /**
  * A request the API refused. The message carries the status and the server's
  * sentence, which is what reaches a person; `status` and `body` are for the
@@ -573,6 +598,16 @@ export declare class LoticsClient {
      * rows land only where every bound table is empty. Admin-only.
      */
     scaffoldWorkspace(body: ScaffoldWorkspaceRequest): Promise<ScaffoldWorkspaceResult>;
+    /**
+     * Read this workspace's schema back as a model — the tables it has (or only
+     * the ones named), their fields, options and views, plus its roles.
+     *
+     * A pure read, and admin-only for the same reason the scaffold is: the whole
+     * schema is what comes back.
+     */
+    exportWorkspaceModel(opts?: {
+        tables?: string[];
+    }): Promise<WorkspaceModelExport>;
     /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
      *  target from the request's workspace, never a path id. */
     updateWorkspace(body: {

package/dist/src/client.js

@@ -356,6 +356,21 @@ var LoticsClient = class {
   async scaffoldWorkspace(body) {
     return this.request("POST", "/v1/workspaces/scaffold", body);
   }
+  /**
+   * Read this workspace's schema back as a model — the tables it has (or only
+   * the ones named), their fields, options and views, plus its roles.
+   *
+   * A pure read, and admin-only for the same reason the scaffold is: the whole
+   * schema is what comes back.
+   */
+  async exportWorkspaceModel(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.tables !== void 0 && opts.tables.length > 0) {
+      params.set("tables", opts.tables.join(","));
+    }
+    const qs = params.toString();
+    return this.request("GET", `/v1/workspaces/model${qs ? `?${qs}` : ""}`);
+  }
   /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
    *  target from the request's workspace, never a path id. */
   async updateWorkspace(body) {

package/docs/cli_reference.md

@@ -6,7 +6,7 @@ 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. Lotics emails a sign-in link; the person opens it and presses Confirm on the page showing the code this command printed, and the command finishes with the credential saved as a profile. `--local` pins this directory to that org instead of setting the global default. `--json` prints `organization_id`, `workspace_id` and `organization_name`, and nothing else. |
+| `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 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`. |
@@ -43,10 +43,11 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `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 upgrade [app_id]` | `POST /v1/apps/{id}/upgrade` — apply the latest version of the package this app was COPIED from. A copy records its provenance (`apps.origin`: package, version, app alias and the `bind` it was made under) and this is the only thing that reads it — a hand-built app, or one copied before the column existed, has no package to offer one and answers 400. Run it once per app: a package's apps each carry their own provenance. **The schema is additive** — fields, options and views the new version declares are created under the recorded bind, so they land on the same tables the copy did; nothing is renamed, retyped or deleted, and a field the new version stopped declaring keeps its column and its data and is REPORTED. **An artifact is replaced only while it is still byte-for-byte what was delivered**: a workflow or agent you have edited here is kept as it is and named, so the offer is partial by design and every part it declined to touch is printed. Queries are replaced outright (generated from the contract, no edit to lose) and only a knowledge doc the new version ADDS is created. The app is then redeployed from the new version's prebuilt dist — **nothing local is read or sent**, so a checkout on this machine is behind afterwards and the report ends at `lotics app pull <app_id>`. app_id from the local manifest, or pass one to upgrade any app without pulling it. **Already on the latest version prints that one line and exits 0** — it is a refusal before the first write, not a failure, and re-applying the version it is on would re-stamp your edits as delivered. Every other refusal (an unpublished package, a contract that no longer validates, a bind the new version broke) is a package that cannot be applied: the app is untouched, the server's sentence is printed, and the exit is 1. Anything else — no provenance to read, not an admin, no such app — exits 1. Admin-only. Audited as `app.upgrade`. |
 | `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 setup <apg_id \| model.json> [--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 fills its workspace, then prints the one-time sign-in link. **When that email already has an account it signs that account in rather than stopping** — the `lotics auth login` flow, so Lotics emails a sign-in link, the person presses Confirm, and the command carries on into the copy or the model with the credential it just received. **The argument decides which of the two forms this is, by SHAPE**: a `*.json` file is a workspace MODEL — in either of ITS two forms, spelled out or `{"from": "<preset-slug>", …}` — and anything else is a package id copied through `library init`. The suffix decides it alone — asking the filesystem would answer a long library id with `ENAMETOOLONG` instead of with a verdict — and a model is checked OFFLINE before an account is created, because a file with a typo in it must not leave an organization behind. The model form creates no apps, so its sign-in link lands on the first table it made. It sends no `adopt`: an entity whose `label` already names a table in the workspace is REFUSED with every collision named, and the refusal adds the line the server cannot — `lotics scaffold apply <model.json>`, the verb that adds to the workspace you already have. 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 package into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` copies into the account you already have and is a pure alias for `library init`. A path positional is accepted and IGNORED with a warning — nothing is written to disk any more — so a prompt written for an older CLI still runs. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_ids` (alias → id), `apps` (each app's `version_number`, or its `error`), `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. **The model form emits `entities`, `roles`, `record_ids` and `rows_skipped`** in place of `app_ids` / `apps` / `created` — a model creates no apps and nothing named for a copier to review. **The model form also runs the file's `apply` list** — each named package copied in after the tables exist, with that entry's `bind`, in order, stopping at a refusal with everything before it kept — and emits `applied: [{starter_id, apps}]` beside them; **the sign-in link then lands on the FIRST app any applied package created**, falling back to the first table when the model applied none. 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, the publisher's-code disclosure, an app that landed without a version. 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. Reachable with no install: `npx -y @lotics/cli setup …`. |
+| `lotics setup <apg_id \| model.json> [--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 fills its workspace, then prints the one-time sign-in link. **When that email already has an account it hands over to the `lotics auth login` flow** — it prints the sign-in page to open and the code it must show, and **exits 1 having created nothing**; the person presses Confirm and runs the same command again, which collects the key and carries on into the copy or the model. (`--wait` holds the terminal through the Confirm instead, finishing in one command.) The re-run is not refused for naming an `--email` it is now signed in as — that address IS the account it holds, not a second one. **The argument decides which of the two forms this is, by SHAPE**: a `*.json` file is a workspace MODEL — in either of ITS two forms, spelled out or `{"from": "<preset-slug>", …}` — and anything else is a package id copied through `library init`. The suffix decides it alone — asking the filesystem would answer a long library id with `ENAMETOOLONG` instead of with a verdict — and a model is checked OFFLINE before an account is created, because a file with a typo in it must not leave an organization behind. The model form creates no apps, so its sign-in link lands on the first table it made. It sends no `adopt`: an entity whose `label` already names a table in the workspace is REFUSED with every collision named, and the refusal adds the line the server cannot — `lotics scaffold apply <model.json>`, the verb that adds to the workspace you already have. 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 package into an org the caller did not name — the message says how to do each thing on purpose. Without it, `setup` copies into the account you already have and is a pure alias for `library init`. A path positional is accepted and IGNORED with a warning — nothing is written to disk any more — so a prompt written for an older CLI still runs. **`--json` prints one object on stdout and nothing else** — `organization_id`, `workspace_id`, `app_ids` (alias → id), `apps` (each app's `version_number`, or its `error`), `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. **The model form emits `entities`, `roles`, `record_ids` and `rows_skipped`** in place of `app_ids` / `apps` / `created` — a model creates no apps and nothing named for a copier to review. **The model form also runs the file's `apply` list** — each named package copied in after the tables exist, with that entry's `bind`, in order, stopping at a refusal with everything before it kept — and emits `applied: [{package, apps}]` beside them; **the sign-in link then lands on the FIRST app any applied package created**, falling back to the first table when the model applied none. 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, the publisher's-code disclosure, an app that landed without a version. 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. Reachable with no install: `npx -y @lotics/cli setup …`. |
 | `lotics scaffold docs` | **The model reference, from inside the binary.** Every top-level key of a `model.json`, every field `type` the contract admits with the config each one needs, the option / view / role / inline-template shapes, the row format (relative dates `@today` / `@month-start` with whole-day offsets; links as `"<entity-alias>:<ref>"`), the rules, the `apply` list (packages copied in after the model's own tables, each with an optional `bind` onto them), the `preset` block (a published model's branches and its at-most-two questions), the **`from` form** — `{from, variants, rename, entities, rows, apply}`, which names a preset by SLUG instead of restating it — and one complete worked example. **Offline, no account**, and not part of `lotics docs`. |
 | `lotics scaffold check <model.json> [--json]` | **Prove a model before anyone sees it — no network, no credential**, unless the file names a preset. ONE parse of the whole file against the model schema (strict, so `tabels` or `row` is an error rather than a silently dropped key, and a model cannot express what only a starter bundle carries: `apps`, `fixtures`, `knowledge`, `knowledge_expects`, a file-backed `excel`/`word`/`pdf-form` template), then `validateWorkspaceModel` — the caps, every cross-reference, and the first rows themselves (a field the entity does not declare, an unknown option alias, a link naming no row in the file, a duplicate `ref`, a date that is not one, a value on a files or computed field). **Reports EVERY problem in one run**, each as `<path>: <message>` in the file's own keys (`entities.0.fields.1.type`, `rows.order.so_1.customer`), so fixing a model is not a round trip per mistake. Exits 1 when there is one; exits 0 with a one-line summary (`N tables, N fields, N links, N views, N roles, N rows`) on stdout. `--json` replaces both with one object and nothing else: `{ok: true, tables, fields, links, views, roles, rows}` or `{ok: false, findings: [{path, message}]}`. **A `preset` is checked as N models, not one** — every variant merged onto the base (its added entities, and its added fields keyed by entity) and put through the same rules, each finding addressed `preset.variants.<slug>.<path>`, so a preset ships with every branch proven: the branch nobody took is the one that fails in the workspace of whoever takes it, who is the one reader who cannot fix it. A variant's `fields` key naming no declared entity is a finding too — the merge keys on the entity, so a typo'd alias adds those fields to nothing. Same verdict the server reaches, because it runs the server's own functions out of `@lotics/shared` rather than a second implementation of them. **A file written as `{"from": "<preset-slug>", …}` is resolved first** — one GET of that preset's file on the website — and that read is the one step on this path that needs the network; it says so when it cannot make it, and a slug nothing serves is answered with the slugs there ARE, read from the listing, rather than with a 404 the author cannot spell their way out of. Resolution is pure (`resolveModelFrom` in `@lotics/shared`): the named variants merged onto the preset's base in order, then `rename` through the same `applyBinding` a `--bind` goes through, then the file's own `entities` appended. What comes out is the full form and goes through everything above unchanged, so a `from` file cannot reach a workspace by a route the full form does not. A variant slug the preset does not declare, an alias `rename` names that it does not declare, and a renamed label that is already another table's are each a finding rather than a silent drop — a branch quietly ignored scaffolds the base and looks like it worked. |
-| `lotics scaffold apply <model.json> [--json]` | **Create the model in this workspace**: its tables, fields, select options, links, views, roles and first rows, through `POST /v1/workspaces/scaffold`. Runs `check` first, so a bad file never reaches the network, then resolves and ANNOUNCES its workspace (`lotics → <org> / <workspace>` on stderr) before writing — it is a destructive path. **Additive and re-runnable**: it is the verb that sends `adopt`, so an entity whose `label` already names a table here BINDS to that table and gains the fields, options and views it is missing, while `setup` refuses that same label. Nothing is ever modified or deleted, so applying the same model twice creates nothing the second time. **A renamed label therefore asks for a NEW table** — rename through `lotics run update_table` instead; after the first run the workspace is the source of truth and the file is an authoring input. **Rows land only where every bound table is empty**: one bound table already holding records and none are written anywhere, because sample rows landing among a customer's real ones cannot be told apart from them — it says so and reports `rows_skipped`. Prints `created`/`adopted` per entity with its table id, each role's group id, and rows written per entity. **Then it copies in every package the file's `apply` list names, in order** — each one a `library init` with that entry's `bind` and `no_sample_data`, and each sending `adopt`, because by then the workspace holds exactly the tables this same run just created. Order is load-bearing: a later entry may bind onto a table an earlier one made. **A refused entry stops the run and the entries before it stay** — they are separate copies, committed as they land — so the refusal carries the server's own message plus what already landed and the one-package command to retry with. `--json` prints one object and nothing else (`entities`, `roles`, `record_ids`, `rows_skipped`, `applied: [{starter_id, apps}]` — always present, empty included, so a reader cannot mistake "applied nothing" for "too old to say" — plus `organization_id`/`workspace_id` and a `warnings` array). Admin-only. A model declares no apps of its own — build one in the workspace and publish it as a package, or name a published package in `apply`. |
+| `lotics scaffold apply <model.json> [--json]` | **Create the model in this workspace**: its tables, fields, select options, links, views, roles and first rows, through `POST /v1/workspaces/scaffold`. Runs `check` first, so a bad file never reaches the network, then resolves and ANNOUNCES its workspace (`lotics → <org> / <workspace>` on stderr) before writing — it is a destructive path. **Additive and re-runnable**: it is the verb that sends `adopt`, so an entity whose `label` already names a table here BINDS to that table and gains the fields, options and views it is missing, while `setup` refuses that same label. Nothing is ever modified or deleted, so applying the same model twice creates nothing the second time. **A renamed label therefore asks for a NEW table** — rename through `lotics run update_table` instead; after the first run the workspace is the source of truth and the file is an authoring input. **Rows land only where every bound table is empty**: one bound table already holding records and none are written anywhere, because sample rows landing among a customer's real ones cannot be told apart from them — it says so and reports `rows_skipped`. Prints `created`/`adopted` per entity with its table id, each role's group id, and rows written per entity. **Then it copies in every package the file's `apply` list names, in order** — each one a `library init` with that entry's `bind` and `no_sample_data`, and each sending `adopt`, because by then the workspace holds exactly the tables this same run just created. Order is load-bearing: a later entry may bind onto a table an earlier one made. **A refused entry stops the run and the entries before it stay** — they are separate copies, committed as they land — so the refusal carries the server's own message plus what already landed and the one-package command to retry with. `--json` prints one object and nothing else (`entities`, `roles`, `record_ids`, `rows_skipped`, `applied: [{package, apps}]` — always present, empty included, so a reader cannot mistake "applied nothing" for "too old to say" — plus `organization_id`/`workspace_id` and a `warnings` array). Admin-only. A model declares no apps of its own — build one in the workspace and publish it as a package, or name a published package in `apply`. |
+| `lotics scaffold export [--tables <tbl_id,…>]` | **This workspace, read back as a model file** — `GET /v1/workspaces/model`. Prints the tables it has (or only the ids `--tables` names) with their fields, options and views, plus its roles and its html/email templates when it has any (a file-backed template is named on stderr and left out), as pretty JSON on **stdout**: exactly the file `lotics scaffold check` reads, so `lotics scaffold export > model.json && lotics scaffold check model.json` is the round trip. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr), like every other verb that reads one. **Findings go to stderr, each led by its severity** (`• <severity>  <area>: <message>`, and one line counting the errors underneath) — a workspace holds things a model cannot express, and a file that dropped them silently would read as the whole workspace; the model is printed either way, and the exit is 1 when any finding is an `error`, because a file with a hole in it is still worth having on disk. **What comes out is a STARTING POINT, never a source of truth**: it carries one business's labels and stops describing that workspace the moment either changes. Edit the labels into the trade's words, add the `preset` block with its questions and variants (`lotics scaffold docs`), and prove every branch with `lotics scaffold check` before it is published. Admin-only. |
 | `lotics library list` | **Works with no account**, and that is the point: whether to start from a preset, copy a package or build from scratch is decided before one exists, so requiring a key would mean signing up to learn the answer was no. **Two shelves, printed under their own headings and never merged**, because they are different kinds of thing and end in different commands. **Presets** are a trade's MODEL, served as static files on the website (`GET <site>/presets/index.json`, no credential, no server that knows what a preset is): each row is `slug · name`, the sentence, how many tables the base carries, and every branch as `slug · when`. The `when` rides the listing rather than waiting for a `show`, because it is what an answer is matched against — two trades whose names sound alike are told apart by which one has a branch describing the business in front of the reader. A preset is READ and turned into a `model.json`; nothing is copied. **Packages** are apps plus the tables they stand on, COPIED in whole. Unauthenticated it lists what Lotics publishes (`GET /v1/starters/official`, public); authenticated it lists the org shelf — the packages 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). Both render through one function, and each row names WHAT IS INSIDE it — its apps and how many tables — because that is the fact the choice turns on: a name and a sentence leave a chooser guessing, and an agent matching what someone said they manage has nothing else to match against. Nothing fitting on either shelf is a real answer: `lotics scaffold docs` is where that goes. |
 | `lotics library show <slug\|apg_id> [--json]` | **The argument says which shelf**, and both forms are allowlists rather than a fallback: an `apg_` id is a package, anything else is a preset slug (`^[a-z0-9_]+$`, refused before any request — a slug reaches a URL). **A SLUG** reads the preset's own file off the website with no credential and no account, which is the whole timing argument for serving it as a file: it prints the preset's name and sentence, the questions it may ask (at most two), every table as `alias · label` with each field as `alias:type`, and every branch as `slug · when` followed by the tables and fields taking it ADDS — a slug picked off its `when` alone cannot say whether the branch brings the column the person was asked about. It closes with the `{"from": …}` file to write. The file is proven as a MODEL on the way through (the same `readPresetModel` this repo's own test runs over these files), so a preset that would fail in the workspace of whoever takes a branch is refused here, named in the preset's own keys — ours to fix, not the reader's. **An `apg_` id** prints the package: name, description, current version, shelf tile and trust standing (`official` — reviewed by Lotics; `your organization's own`; otherwise `not copyable from this organization`), plus the date it was unpublished once it has been, then the same COMPACT table listing — each table as `alias · label`, each field as `alias:type` — which is exactly what a `--bind` is typed from. Read it before copying a package you did not publish. **Works with no account for anything Lotics publishes**, falling to `GET /v1/starters/official/{id}` the way `list` falls to the public shelf; signed in, the prose form is admin-only and readable by id from any org, but an unpublished package 404s for every org except the one that published it. `--json` prints the preset FILE for a slug, and the published contract read whole — views, labels and all — for a package: ONE shape whichever credentials the caller holds, because the reader of that object is a program writing a model from it. |
 | `lotics library init <apg_id> [--bind <entity>=<Label> ...]` | **Copy a package into this workspace.** Server-side it scaffolds the tables and fields, creates the document templates and knowledge docs, inserts the sample records, creates every app the package carries and materializes each one's queries, workflows and agents onto it — then deploys each app from the dist the package was published with, rewriting the publisher's sentinel field keys to this workspace's. No build runs anywhere, nothing is written to this machine, and nothing here needs node: the apps are live when the command returns. **What you get is yours outright**: ordinary apps plus ordinary tables, with no link back to what it came from and nothing pinned. It does STAMP what delivered it (`apps.origin`), which nothing resolves through and only `lotics app upgrade <app_id>` reads. Edit any of it — `lotics app pull <app_id>` is how an app's code is edited afterwards. **The publisher's code runs in your workspace as you** — its apps, workflows and agents — which is why provenance is the gate: **copyable only if the package is Lotics-reviewed or your own organization published it**, enforced server-side; the disclosure is printed (and carried in `--json`'s `warnings`) whenever the package is not your own. **Refuses a workspace that already has tables** unless `--adopt`: scaffold matches an entity by DISPLAY NAME, so a package declaring `Contacts` would bind to yours. An app whose deploy failed is reported by name with its reason and the exit is non-zero, but the copy is complete around it — the tables, the records and the app row exist — so it must not be run again; the publisher fixes the package and it is copied into a fresh workspace. The sign-in link lands on the app when there is one, else on the workspace's app list. `--json` prints one object on stdout instead of progress (the shape is under `lotics setup`). `--no-sample-data` skips the sample records, and a copy that ADOPTS an existing table writes none either — that table already holds real rows, and the fixture set links to itself, so it is all-or-nothing; with them, how many landed is reported. They are ordinary records, delete them whenever. **`--bind <entity>=<Label>` says which of YOUR tables the package's entities are, and `--bind <entity>.<field>=<Label>` which of your fields** — repeatable, and split on the FIRST `=` so a label may contain one. Scaffold adopts by DISPLAY LABEL, so a bind renames the contract to what you already call things and the copy lands on your tables instead of creating a second set beside them: this is how a package of apps lands on a workspace that already has its tables. Only naming moves — a bound field must be the TYPE the package declares, or the copy is refused (409). A bound entity needs no `--adopt`. The same target named twice is refused rather than overwritten, because the caller then believes one of the two took. `lotics library show <apg_id>` lists the aliases to bind. Resolves and ANNOUNCES its workspace first (`lotics → <org> / <workspace>` on stderr). Admin-only. Authoring the registry (`opctl library publish/unpublish`) stays operator-only. |

package/package.json

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