@lotics/cli 0.204.0 → 0.205.1

package/AGENTS.md

@@ -52,6 +52,34 @@ response there is *not* evidence the subcommand is absent. To find out whether s
   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.
+- **A credential is either a SIGN-IN or an API KEY, and `logout` treats them differently.** A profile
+  from `auth login` / `auth signup` acts as the person who confirmed it and is theirs — `lotics auth
+  logout` revokes it server-side, and it lapses on its own after 90 idle days (each use pushes that
+  out). A profile from `auth api-key` holds a key an ADMIN issued. A key created in Settings carries
+  its OWN access — every app and table, or only the ones chosen on the key, so a listing that comes
+  back short is the key's reach, not a bug — while a key created FOR a person carries that
+  person's access and dies with their membership. Either is routinely also on a server and on
+  other machines, so logout only forgets it locally and says so; only an admin revokes it. A profile that states no kind (saved before the field existed) is resolved against the SERVER
+  and revoked only if the answer is a sign-in; a bare `--api-key` / `LOTICS_API_KEY` names no
+  profile to remove at all. Nothing is ever revoked on a guess — between two, the destructive one is
+  wrong. `lotics auth whoami` prints the kind, asking the server when the store cannot say.
+- **A key created in Settings never administers the organization, whatever its access.** The verbs
+  `docs/cli_reference.md` marks *admin only* split in two under a key: the ones that BUILD inside a workspace
+  the key reaches — `scaffold apply`, `library init`, `app upgrade`, `workspace doctor`, `scaffold
+  export`, `field rename` — run as before, while managing people, sharing or ownership, creating or
+  deleting a workspace, changing workspace settings, setting credit limits, reading the access log
+  and publishing a starter or an app's API answer `403` and name the remedy: an admin signed in, so
+  `lotics auth login <email>` and run it again. A sign-in acts as that person and is refused none of
+  them. Do not retry a `403` with the same credential and do not ask for a wider key — no answer on
+  the key's own screen grants this.
+- **A 401 names its remedy — act on the hint, do not retry.** "This credential expired / was
+  revoked / belongs to a member who is no longer active" carries the one remedy that ends this
+  credential: run `lotics auth login <email>` for a sign-in, or ask the admin who issued it for a
+  new key. A credential minted before that was recorded carries BOTH, because nothing on the row
+  tells them apart — so on a box with no browser, take the second. Only an UNRECOGNIZED key gets
+  the generic "Invalid or disabled API key", and that one is generic on purpose, so re-sending it
+  teaches nothing. A `reason` rides on the body for a script to branch on, since the code stays
+  `unauthorized` for every 401.
 - **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
@@ -66,6 +94,13 @@ response there is *not* evidence the subcommand is absent. To find out whether s
   so `lotics run … && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on
   findings. An unrecognized status exits 0 — the list is an allowlist of failure, so a status added
   later never turns a working script red — and a parked run (`awaiting_input`) is not a failure.
+- **An app that PUBLISHES an API turns every later manifest write into a release.** `lotics app api
+  publish` snapshots what the app's queries and workflows promise to callers outside it — a
+  customer's own site or server, which nobody here can redeploy. From then on an additive change
+  re-snapshots silently and a breaking one is REFUSED, naming each change;
+  `--acknowledge-breaking-api` (on `app deploy`, `app query set`, `app workflow set`, `app upgrade`)
+  is the answer that carries it out and snapshots the break as a new contract version. An app that
+  publishes nothing is untouched by any of it.
 - **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the
   records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs
   those deletes (records only — never files, integrations or notifications). Neither is a rollback.

package/README.md

@@ -124,6 +124,10 @@ The CLI checks for updates once per day and prints a note on stderr, naming the
 
 ## Authentication
 
+**Two kinds of credential, and which you hold decides what `logout` does.** `auth signup` / `auth login` give this machine a **sign-in** — it acts as you, carries whatever role you have, and is yours to see and revoke at Settings → Security → *Keys and terminals*; it lapses after 90 days of disuse, and each use pushes that out. `auth api-key` saves an **API key** an admin issued. A key an admin creates in Settings has its own name and its own access, reaching either every app and table or only the ones chosen on the key; a key created FOR a person carries that person's access and stops working when that person is removed. Either kind often lives on a server and on other people's machines too, and only an admin revokes it. `lotics auth whoami` prints which kind this machine holds — from the saved profile, or from the server when the profile does not say.
+
+When a credential stops working the refusal says which of the three ways it is dead — "… was revoked." / "… expired." / "… belongs to a member who is no longer active in this organization." — and its `hint` names the remedy: `lotics auth login <email>` for a terminal sign-in, ask an admin for a new key for an API key. A credential whose record does not say which of the two it is gets both. A key the server does not recognize at all gets one generic answer, deliberately: an unrecognized key learns nothing from being refused.
+
 **`lotics auth signup`** — Creates a new Lotics account, organization, workspace, and API key in one step. Sends a magic link email so you can access the web app.
 
 ```bash
@@ -157,7 +161,7 @@ lotics auth api-key                  # interactive prompt
 lotics auth api-key ltk_...          # registers the key's org as a profile (now active)
 ```
 
-Run `lotics auth logout [<name|id>]` to remove a profile (default: the active org), or `lotics auth logout --all` to wipe the store. Inside a pinned directory the bare form removes the **pin**, not a profile — name the org to remove its credential.
+Run `lotics auth logout [<name|id>]` to remove a profile (default: the active org), or `lotics auth logout --all` to wipe the store. Inside a pinned directory the bare form removes the **pin**, not a profile — name the org to remove its credential. A profile saved by `auth login` / `auth signup` is a **sign-in**, and logging out revokes it server-side too. One saved by `auth api-key` is an admin-issued key that other machines may also hold, so it is only removed from this machine and stays active until an admin revokes it under Settings → API keys. A profile saved before the kind was recorded states nothing, so the server is asked and the credential is revoked only if the answer is a sign-in.
 
 ## Organizations
 
@@ -349,6 +353,18 @@ lotics app versions app_...                # ...for any app, without pulling it
 lotics app upgrade                         # the app this directory's manifest names
 lotics app upgrade app_...                 # ...for any app, without pulling it first
 
+# The app's API: what its declared queries and workflows promise to a caller
+# OUTSIDE the app — a customer's own site or server. Publishing snapshots that
+# promise as a numbered contract; from then on a manifest write that would break
+# it is refused and every breaking change is named, unless the write carries
+# --acknowledge-breaking-api (app deploy / app query set / app workflow set /
+# app upgrade). A query that does not name the columns it returns is refused at
+# publish: those field names are the table's, not the app's to promise.
+lotics app api publish                     # snapshot the contract; prints the version + warnings
+lotics app api status                      # is one published, and which version callers hold
+lotics app api spec -o api.openapi.json    # the OpenAPI 3.1 document, for the consumer's generator
+lotics app api unpublish                   # end the promise
+
 # 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.