@lotics/cli 0.188.0 → 0.190.0

package/AGENTS.md

@@ -8,6 +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 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. |
@@ -41,6 +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, 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

@@ -36,7 +36,7 @@ package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
   workspace facts an agent can't guess, the access-vs-activation model, and the
   catalog-then-stage retrieval model agents use to pull only the lines they need.
 
-## Start from a starter, in one command
+## Start from the library, in one command
 
 Install the CLI, then copy a starter — it creates the account, copies the starter into its
 workspace, deploys its apps, and prints a one-time sign-in link:
@@ -52,7 +52,48 @@ you pull an app's source to change it (`lotics app pull <app_id>`) and build it
 
 Add `--json` for one machine-readable object instead of progress — the organization, the
 workspace, the app ids, what was created, the sign-in link, and any warnings. Already signed in?
-Drop `--email` and `lotics setup <starter_id>` copies into the account you have.
+Drop `--email` and `lotics setup <apg_id>` copies into the account you have.
+
+`lotics library list` reads both shelves with no account at all. **Presets** are a trade's model,
+named by a slug: read one and write a `model.json` from it — nothing is copied. **Packages** are
+apps and the tables they stand on, named `apg_…`, copied in whole; each row names how many tables
+and which apps a copy creates, so what you actually manage can be matched against them.
+`lotics library show <slug|apg_id>` reads one, with no account either — each table as
+`alias · label`, each field as `alias:type`, and a preset's variants beside the sentence that
+selects each.
+
+## Or describe your own workspace
+
+A `model.json` names the tables, fields, options, links, views, roles and first rows, and
+`lotics setup` builds them. **Start from a preset when one is your trade** — name it instead of
+restating it:
+
+```json
+{
+  "from": "field_service",
+  "variants": ["crews"],
+  "rename": { "job": { "label": "Jobs", "fields": { "code": "Job no." } } },
+  "rows": { "job": [{ "ref": "j1", "fields": { "code": "J-1" } }] }
+}
+```
+
+No preset is your trade? Write the full form instead, spelling the tables out. Either way:
+
+```bash
+lotics scaffold docs                 # how to write one, both forms, with a worked example. Offline
+lotics scaffold check model.json     # prove it — every problem at once, offline unless it names a preset
+lotics setup model.json --email you@company.com
+```
+
+It creates no apps of its own: build one in the workspace afterwards
+(`lotics docs building_an_app`), or name a published package in the file's `apply` list and it is
+copied in — bound onto the tables the model just made — as part of the same run.
+`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
 
@@ -81,6 +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. **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            # 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
@@ -289,6 +343,13 @@ lotics app deploy -m "Add quote drawer"    # typecheck + build + upload a new ve
 lotics app versions                        # deploy history: version, when, who, -m message (* = live)
 lotics app versions app_...                # ...for any app, without pulling it first
 
+# Apply the latest version of the package this app was COPIED from. Additive on
+# the schema; a workflow or agent you have edited here is kept and named, and so
+# is a field the new version stopped declaring. Redeploys from the published
+# dist, so nothing local is sent — pull afterwards to edit the new code.
+lotics app upgrade                         # the app this directory's manifest names
+lotics app upgrade app_...                 # ...for any app, without pulling it first
+
 # Regenerate .lotics/* WITHOUT a deploy: the .d.ts type companions (always) +
 # the runtime app_fields.ts (when authenticated) — F/OPT maps that address
 # fields + select options by stable display-name aliases instead of opaque ids.