@lotics/cli 0.205.0 → 0.205.2

package/AGENTS.md

@@ -55,12 +55,23 @@ response there is *not* evidence the subcommand is absent. To find out whether s
 - **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, which 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
+  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
@@ -84,12 +95,15 @@ response there is *not* evidence the subcommand is absent. To find out whether s
   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
+  publish` snapshots what the app's queries, workflows and agents 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.
+  `--acknowledge-breaking-api` (on `app deploy`, `app query set`, `app workflow set`,
+  `app agent 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.
+- **Exposure is per app, all or nothing** — a public share or a key reaches every alias an app
+  declares, so what outsiders may call is a second app over the same tables, scaffolded with
+  `lotics app create "<name>" --api` ([docs/building_an_app.md](./docs/building_an_app.md) § 9).
 - **`--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,9 +124,9 @@ 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: it acts as the member it was created for, 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.
+**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 — "This credential was revoked." / "expired." / "belongs to a member who is no longer active in this organization." — and names both remedies, because a credential acts as a person whether it is their own sign-in or a key an admin issued under their membership, and nothing on the row tells the two apart: sign in again with `lotics auth login <email>`, or ask the admin who issued it for a new key. A key the server does not recognize at all gets one generic answer, deliberately: an unrecognized key learns nothing from being refused.
+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.
 
@@ -341,6 +341,8 @@ lotics knowledge rm kdc_...                                   # archive
 ```bash
 # Scaffold / pull / deploy a Vite+React+TS app project
 lotics app create "Sales Desk"            # scaffold + deploy v1
+lotics app create "Orders API" --api       # no screens: its declarations are the whole surface,
+                                           # so nothing is built and nothing is deployed
 lotics app pull app_...                    # bootstrap an existing app locally (incl. .lotics/*)
 lotics app deploy -m "Add quote drawer"    # typecheck + build + upload a new version
 lotics app versions                        # deploy history: version, when, who, -m message (* = live)
@@ -353,13 +355,14 @@ 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
+# The app's API: what its declared queries, workflows and agents 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.
+# app agent 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