@lotics/cli 0.188.0 → 0.189.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. |
 | [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,11 @@ 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.
 - **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,44 @@ 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.
 
 ## Install
 
@@ -81,6 +118,13 @@ 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.
+
+```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 web`** — Send a magic link email to access the web app (requires prior signup or setup).
 
 ```bash
@@ -289,6 +333,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.