@terminus-ai/cli 0.0.1

package/README.md

@@ -0,0 +1,1055 @@
+# @terminus-ai/cli
+
+Lightweight Terminus tooling for developers working on their own machines
+(Node.js 22.16 or newer; zero runtime dependencies).
+(Inside the Terminus platform itself there is no CLI: apps are created and
+staged natively by asking Norbert, and published from the Store UI.)
+
+Installs the `terminus` command (once the package's first npm publish lands —
+until then install from the repo: `npm install -g github:Terminus-Intelligence/terminus-cli`):
+
+```sh
+npm install -g @terminus-ai/cli
+```
+
+(One-off runs work too: `npx @terminus-ai/cli status`.)
+
+## Catalog search
+
+Search the Terminus catalog as your account (run `terminus login` first):
+
+```sh
+terminus search "browser automation"
+terminus skills use "browser automation"
+```
+
+The installed binary is also available as `terminus-cli`:
+
+```sh
+terminus-cli search "browser automation"
+terminus-cli skills use "browser automation"
+```
+
+`skills use` searches the catalog, prompts for a numbered result, records the selected use on your
+account, and prints the selected skill content for the agent to follow. In non-interactive
+shells, pass an explicit selection:
+
+```sh
+terminus-cli skills use "browser automation" --select 1
+terminus-cli skills use "browser automation" --use-first
+```
+
+When the argument is a skill address or id instead of a query, `skills use` skips search and loads
+that exact skill (installed pointer skills rely on this):
+
+```sh
+terminus-cli skills use "@zarazhangrui/frontend-slides"
+```
+
+## Installing skills (pointers by default)
+
+`terminus skills install <skill> --agent claude|codex|both` adds a skill to a coding agent so it auto-triggers in future sessions. By default it
+writes a small pointer stub — the skill's name and description plus instructions to load the real
+content from Terminus at use time — so content stays fresh on the platform and every use is
+counted. `--local` copies the full package to disk instead, like `npx skills`; local copies do
+not count uses, and `terminus skills update` refreshes them. Either way the content comes through
+`terminus skills use`, which serves open-source skills only: a skill whose content is closed is
+used on Terminus itself, and `skills install`, `fetch`, `files`, and `file` refuse it (exit 77) —
+though its owner can still `fetch` it and read its files.
+
+```sh
+terminus skills install "@zarazhangrui/frontend-slides" --agent claude            # → ./.claude/skills/
+terminus skills install "@zarazhangrui/frontend-slides" --agent claude --global   # → ~/.claude/skills/
+terminus skills install "@zarazhangrui/frontend-slides" --agent codex             # → ./.codex/skills/
+terminus skills install "@zarazhangrui/frontend-slides" --local                   # full copy (open-source only)
+terminus skills list
+terminus skills update                        # or: terminus skills update frontend-slides
+terminus skills uninstall frontend-slides
+```
+
+Without `--agent`, install picks the agent you are running in (Codex when its environment says
+so), else Claude Code. Installs are recorded in a `.terminus-install.json` manifest inside the skill
+directory; `skills uninstall` only removes directories that have one. Every skill command lives
+under `terminus skills`, and `terminus skills` on its own lists them. `terminus skills update`
+rewrites a pointer an older CLI wrote into today's wording.
+
+`skills update` looks every install up by the uid its manifest recorded (signed in, never by
+search, so a skill that is gone is never swapped for a look-alike):
+
+- A pointer already loads the latest instructions at each use, so update only rewrites the stub,
+  and only when it would read differently: a new name, description, or address, or wording from
+  an older terminus. The folder keeps its name. No content is delivered and no use is counted.
+- A `--local` copy is downloaded again when the skill's change hash moved; that delivery counts as
+  a use, like the install did.
+- A skill that left Terminus, or a local copy whose skill is no longer open source, is reported and
+  left as it is; the command then exits 1.
+
+## Fetching supporting files
+
+Skills that reference scripts, templates, or other package files can be materialized into a
+revision-keyed local cache (`~/.terminus/cache/<uid>@<change_hash>/`). The cache is ephemeral: safe to
+delete anytime, reused until the publisher ships a new revision.
+
+```sh
+terminus skills fetch "@zarazhangrui/frontend-slides"
+terminus skills fetch "@zarazhangrui/frontend-slides" --refresh
+```
+
+## Scaffolding a new skill
+
+```sh
+terminus init my-skill --name my-skill --description "One sentence on when agents should use this."
+terminus validate my-skill
+# make the skill on the web (Creations → New creation); it shows the address
+terminus remote add @you/my-skill my-skill
+terminus push my-skill
+```
+
+Then publish it from its page on the web; `terminus push` prints the link.
+
+## Login
+
+`login` checks the local session first. If you are already logged in it prints your current profile
+name and `@username`.
+Otherwise it opens the browser login and stores a local device session at
+`~/.terminus/session.json`.
+
+```sh
+terminus login
+```
+
+See who you are signed in as and what is waiting for you:
+
+```sh
+terminus account          # Hi, Winston Gao (@winstongu) / Notifications: 3 · Creations: 5
+terminus notifications    # invitations, then unread notifications (--all adds read ones)
+terminus creations        # what you have published (and anything Terminus has suspended)
+terminus drafts           # what you have not published yet
+```
+
+`account` refreshes your profile, then counts the two things the web keeps for you:
+**Notifications** is what the notification box's badge counts (pending invitations to collaborate
+or to join a chat, plus unread notifications), and **Creations** is how many apps, agents,
+services, and skills you have published, the way Creations on the web lists them (not ones shared
+with you, not the platform's official rows, not external skill mirrors). A count that cannot be read
+drops out of the line; on the session's last day a third line says it is about to expire. Signed
+out, it says how to log in and exits with status 3, so scripts can check. Its JSON output never
+includes the session token. Reading notifications here does not mark them read. (`terminus status`
+is the working-copy command; outside a package it points here.)
+
+Browser login opens `https://www.terminus.build/login` with a loopback callback. After the user signs
+in, the web app hands the callback a five-minute, one-time CLI login code bound to this process with
+PKCE S256. The CLI exchanges it via
+`POST /v1/auth/cli-login-code/exchange` for a seven-day database-backed session associated with this
+device. The browser tab says "You're signed in" only after that exchange succeeds; if Terminus
+refuses it, the tab shows the reason instead. The session is stored with owner-only permissions.
+`terminus logout` revokes it immediately before clearing the local file. System Settings → General
+→ Devices on the web shows its computer, platform, client version, activity, and expiration, and
+can revoke it remotely.
+
+For a fully local auth test, run both the local API and local frontend and point the CLI at both:
+
+```sh
+terminus login --api-base http://localhost:3001 --web-base http://localhost:3000
+```
+
+The hosted login page intentionally refuses a localhost API target so a crafted production login
+link cannot send credentials to an arbitrary service on the user's machine.
+
+For automation (a coding agent in a container, a script), set `TERMINUS_TOKEN` to a session
+token; it takes precedence over the saved login and `terminus account` names its account. There
+are no API keys: every token is a device session, so it expires after seven days and is revoked
+with its device.
+
+Catalog commands (`search` and every `skill` command) require a signed-in account; there is no
+anonymous lane. A 401 from Terminus usually means the login expired or was revoked on the web; the
+error says to run `terminus login`.
+
+## How creations move (the Git and GitHub model)
+
+Every creation starts on the web — Creations → New creation
+(`https://www.terminus.build/os?open=create`) — which gives it its address, the
+way a new GitHub repository gets its URL. The CLI moves files between a folder
+and a creation that already exists; it never makes or publishes one (a fork is
+made by Terminus, the way GitHub's Fork button makes one):
+
+```sh
+terminus clone @you/my-app            # a fresh folder, linked (git clone)
+terminus remote add @you/my-app             # connect a folder you already have (git remote add)
+terminus push                         # upload your changes to its draft (git push)
+terminus pull                         # bring the draft down (git pull)
+terminus fork @someone/their-app      # fork it on Terminus, then clone your fork
+```
+
+`fork` makes free forks. When a creation charges for forking, `fork` says the
+price and prints the creation's page: the fork is bought there, and then
+`terminus clone` brings your fork down.
+
+Publishing is done on the web, from the creation's page: that is where the
+version is chosen and what people get changes. `terminus push` prints the page.
+
+## Developing a skill
+
+One of your own skills comes down the same way an app does: `terminus clone
+@you/my-skill` writes its SKILL.md and package files into a fresh directory and
+records the skill's `id` in the frontmatter (`terminus remote add` records it in a
+folder you already have), so a push updates that exact skill even if you rename
+it. `terminus push` uploads SKILL.md and the files it references.
+
+A skill keeps a draft beside its live version, exactly as an app does: a push
+lands on the draft, and what people are using does not move until the skill is
+published again on the web. `terminus status`, `diff`, `log`, `pull`, and
+`restore` read a skill folder the same way they read an app's. Publishing, and
+a skill's source visibility, billing, and price, are set on the web.
+
+## Commands
+
+Browser apps can use a zero-build starter or a full framework project:
+
+```sh
+terminus init app my-app --template react          # positional kind shorthand
+terminus init my-app --kind app --template react   # vanilla | react | svelte
+cd my-app && npm install
+terminus remote add @you/my-app                          # the address the web gave it; writes id into terminus.json
+npm run build                                      # required before starting the runtime
+terminus dev                                       # terminal 1: the app runtime (/_terminus) + fixture data
+npm run dev                                        # optional terminal 2: hot reload; proxies /_terminus
+terminus push                                      # builds, validates, uploads the draft
+```
+
+Cloning an empty creation gives a folder holding only its address;
+`terminus init <kind> .` fills it in and keeps that link.
+
+The same shorthand works for `agent`, `service`, and `skill` (including the
+plural aliases). Every creation versions the same way: strict
+`MAJOR.MINOR.PATCH`, starting at `0.0.1` — app, agent, and service scaffolds
+carry `"version": "0.0.1"` in `terminus.json`, and skills declare `version:`
+in their `SKILL.md` frontmatter. The version is chosen when you publish on the
+web, and every release must be strictly above the latest; you pick the bump
+(patch, minor, or major), the platform only requires that there is one.
+
+Pushing hashes files locally and sends only the bundle index through the
+Terminus API. Missing content hashes stream directly from the CLI to short-lived,
+checksum-bound S3 upload URLs with bounded concurrency; repeated assets are
+deduplicated. Bundle bytes are therefore not base64-expanded into one JSON
+request, and the former 256-file / 4 MiB-file / 16 MiB-bundle CLI caps do not
+apply. The platform retains configurable operational guardrails for abuse and
+storage safety.
+
+`terminus dev` first requires the configured bundle entry point (normally
+`dist/index.html`). If it is missing, the command exits before it creates
+fixture state or binds ports and tells you to run `npm run build`.
+It then serves the production runtime protocol over a local fixture data space,
+one port per simulated member. Plain `terminus dev` is Alan alone;
+`--members 3` creates Alan, Bob, and
+Carol; counts from 1 through 26 use the stable Alan-to-Zoe directory, with a
+display name, bio, deterministic default avatar, and local public profile for
+every account. Comma-separated handles such as `--members alice,bob` remain
+supported for compatibility and receive generated profiles too. It also serves
+the built bundle from disk, so `terminus build` + refresh works without vite.
+The first member uses port `8868` by default and later members use consecutive
+ports; `--port 5000` changes the starting port.
+Every dev server (this harness, `--remote`, agents, services) listens on
+127.0.0.1 only: dev tokens, fixture data, and capabilities billed to you are
+never reachable from another machine. `localhost` reaches it, and a port that
+another program holds on any loopback address, 127.0.0.1, ::1, or all
+interfaces, counts as taken, so a browser resolving `localhost` never lands on
+that program instead. Each one also answers only requests addressed to a
+loopback name (`localhost`, `*.localhost`, `127.x`, or `[::1]`, at any port):
+a web page that re-points its own domain at 127.0.0.1 still sends its own
+`Host`, and gets a 403 rather than a dev token. Proxies that keep a loopback
+`Host`, like the scaffolded Vite proxy, pass. The app runtime (`/_terminus/*`)
+and the harness's own controls (`/__terminus_dev/*`) also refuse what a page
+on another site sends blind: an `Origin` that isn't a loopback page, or
+`Sec-Fetch-Site: cross-site` on a request with no `Origin` (an `<img>`, a
+no-cors GET). Loopback pages at any port, the Vite dev server's included,
+and clients that send neither header (curl, scripts, the SDK outside a
+browser) pass, and the app's pages stay open to a link from anywhere. Agent
+and service dev apply the same test to their token-gated `/api` doors.
+Before `--fresh` clears fixture data, the harness checks the entire requested
+port range. If a listener is already present, startup reports every blocked
+port and its simulated member, and says who holds it: another `terminus dev` by
+its app, folder, member, PID, and uptime (every harness answers
+`GET /__terminus_dev/about`), and any other program by its
+command line, folder, PID, and uptime where `ps` and `lsof` can tell; otherwise
+it prints a command to inspect the listener. It then says how to stop the
+holder and suggests a currently free consecutive range with a copyable version
+of the original command. When the holder is this same folder's harness, it
+reports the app as already running instead, since two harnesses on one folder
+would overwrite each other's spaces. An explicit `--port` is replaced in that
+suggestion, never changed silently; when using the scaffolded Vite proxy, point
+its target at the chosen port. Agent and service dev report a busy explicit
+`--port` the same way, before they start the engine or import the draft;
+without `--port` they take the next free port.
+
+`--guest` adds one more port, after the members': a visitor who is not signed
+in, the way an app open to guests meets one on Terminus. There the bootstrap
+is the platform's guest bootstrap (`guest: true`, no installation, no user),
+the app's own files are served (without the notification corner: a guest has
+no account), and a capability's assets are forwarded for a capability the app
+declares, fetched with no credential, as the app host fetches a guest's. Every
+other `/_terminus` door answers `401 unauthorized` ("Sign in to use this (guest
+mode)"), as production does, and so do the harness's own controls. The app's
+`session.signIn()` opens `/_terminus/signin?return_to=<path>`: on the guest's
+port that is a page listing the members, and picking one (a same-origin form
+POST, never a link) makes the port that member, on the same origin, so what the
+SDK kept for the guest in the browser moves into the account, and returns to the
+path. A `return_to` that is not a path on this origin returns to `/`. Signing
+out there (`/_terminus/logout`) makes the port a guest again. On a member's
+port, sign-in goes straight back to the path.
+User lookup and app-owned space/member operations are intrinsic, app-scoped SDK
+calls. Optional cross-boundary authority such as `network_proxy` still refuses
+locally unless the release declares it.
+
+The fixture runtime also mirrors the production space contract. A `direct`
+space is limited to two people, rejects group member actions, and persists
+peer block/unblock state; a `group` persists owner/admin/editor/viewer roles (a
+viewer reads the space and writes nothing in it) and enforces rename, invite,
+role-change, removal, and leave permissions. Space rows carry the same
+`my_role` and `capabilities` fields that apps render in production, and a
+direct space names the other person as its `peer` — the person invited,
+until they answer.
+
+When one simulated member starts a chat or sends a space invitation, the
+invitee's local app origin shows a Terminus-owned request popup with
+**Accept**, **Decline**, and a close-for-now button. Closing hides that request
+for the life of the page without accepting or declining it; reloading shows an
+unresolved request again.
+
+Being asked to talk to one person and being added to a room are different
+questions, so the card is built from the space's `kind` and asks each on its
+own terms. A `direct` request leads with the person — their face in
+a circle, "@handle wants to chat", and **Accept**. A `group` invitation leads
+with the room — its mark in a rounded square, its name, who invited you, the
+people already in it, and **Join**. Pending requests are shown one at a time
+with the queue depth beside them, and `GET /__terminus_dev/requests` carries
+`kind`, a ready-made `title`, and the current `members` so any surface can
+draw the same distinction. The control is injected into served HTML
+by the local harness and lives outside `/_terminus`, so apps still cannot
+consent on a user's behalf through the SDK. The JSON controls remain available
+for automated tests at `GET /__terminus_dev/requests` and
+`POST /__terminus_dev/requests/{id}/{accept|decline}`. Like the desk's corner,
+it hears the member's account frames live — `GET
+/__terminus_dev/notifications/stream`, which never counts as the member
+being online — rather than polling. `dev --remote` does not
+inject this simulator because production consent belongs to the Terminus
+notification surfaces.
+
+`terminus dev --remote` keeps the local `ui/` bundle but sends `/_terminus/*`
+to the production runtime instead of the fixture space: the CLI uses your
+`terminus login` session to mint an app session exactly as the hosted app
+origin does (`POST /v1/app-runtime/authorizations` → `POST
+/v1/app-runtime/session`), then proxies every runtime call with that bearer and
+streams SSE feeds through. Signing out of the app (`/_terminus/logout`) revokes
+that session as the hosted origin does, and opening the app again mints a new
+one. It needs a published app whose address matches the package `id` and an
+installation for your account. Sign-in (`/_terminus/signin`) goes straight
+back to the path it names, minting a new session first when signed out. You are
+acting on real data under real quotas; the SQLite harness stays the default and
+`--members`, `--profiles`, `--guest`, and `--fresh` do not apply.
+
+Use `--profiles` only when a test needs custom identities. If `--members` is
+omitted, the JSON keys become the member list; omitted avatars keep their
+generated defaults, and avatar paths are resolved relative to the JSON file:
+
+```json
+{
+  "alice": {
+    "name": "Alice Chen",
+    "bio": "Designing calm collaboration tools.",
+    "avatar": "./fixtures/alice.png"
+  },
+  "bob": {
+    "name": "Bob Li",
+    "bio": "Local test account"
+  }
+}
+```
+
+```sh
+terminus dev . --profiles ./dev-profiles.json --fresh
+```
+
+`ready().user`, `users.lookup/search`, and `spaces.members` then expose the
+same `{ id, handle, displayName, avatarUrl, publicProfileUrl }` SDK shape as
+published apps. Avatar and public-profile URLs remain same-origin and open
+local fixture content. The profile file is development input only; exclude it
+with `.terminusignore` if it should not be included in source sync.
+
+The online editor and CLI share one canonical **source draft**, identified by
+the committed `id` in `terminus.json` and an increasing server draft revision.
+Bring a creation made on the web down with `terminus clone @you/app`, or run
+`terminus remote add @you/app` inside an existing directory. Link writes that
+canonical address into `terminus.json` (a service is named by it too); there is
+no second local identity file. After that, from the project directory:
+
+```sh
+terminus status                  # what changed here, and what the draft has that you do not
+terminus diff                    # those changes, line by line
+terminus pull                    # merge the draft's commits into this folder
+terminus push --message "..."    # send yours, as one entry in the draft's history
+terminus log                     # the draft's commits, newest first
+terminus restore <commit>        # put the draft back the way it was
+```
+
+Each push is one commit to the draft (`POST /v1/apps/{id}/draft/commits`): the
+files that differ from the draft's head, the ones the folder no longer has,
+and the fields `terminus.json` compiles to. The draft keeps every commit —
+pushes, web-editor saves, a version chosen on the web — and its page shows
+them under History, with the `--message` a push gave. A push that changes
+nothing records nothing ("Everything up to date"). A service's push goes
+through its import door, which compiles the OpenAPI contract and records the
+import the same way.
+
+The folder remembers which commit it matches, in `.terminus/sync.json` (git's
+`origin/main`, with a `.gitignore` of its own so it stays out of your
+repository). That is what makes the loop behave like git:
+
+- **push refuses a non-fast-forward.** If the draft has commits this folder
+  has not pulled, push says so and stops rather than replacing them;
+  `--force` is the deliberate override.
+- **pull merges.** A file only the draft changed is taken, one only you
+  changed is kept, one both changed is merged line by line, and
+  `terminus.json` merges key by key. What cannot be merged is written between
+  `<<<<<<< yours` / `>>>>>>> draft` markers and named; push waits until you
+  resolve it. `pull --force` replaces the folder with the draft instead.
+- **restore is a revert, not a reset.** It puts the draft's files and
+  compiled settings back to an earlier commit as a NEW commit, so the state
+  it replaced stays in the history.
+
+Git remains your local history: Terminus keeps the draft's, one commit per
+push or save.
+
+A push never publishes: open the creation's page (push prints it) and publish
+there, which releases the draft as it stands.
+
+`clone` answers for a skill you own as well. Someone else's open-source
+creation clones **read-only** — the files of its latest release, with
+`terminus pull` bringing newer ones in. It cannot be pushed; `terminus fork`
+makes a copy in your account that can.
+
+An app package can be as small as:
+
+```json
+{
+  "kind": "app",
+  "id": "@publisher/chat",
+  "version": "0.0.1"
+}
+```
+
+Name, description, icon, listing, source visibility, and commerce settings are
+set on the web and are never duplicated in this file. The app uses the stable
+same-origin `/_terminus/icon` URL; the hosted worker and `terminus dev` resolve
+the icon set on the web, so generated icons do not become repository assets and
+no icon pull command is needed.
+
+Developer-authored `terminus.json` files — app, agent, and service alike —
+have no top-level `schema_version`. The CLI accepts older app and agent files
+that include one, removes it when reconstructing a working copy, and compiles
+the current authoring format into the backend's internally versioned release
+manifest; a service file that still carries the line is asked to delete it.
+
+Source discovery respects two layers. `.gitignore` defines the repository's
+normal source tree. Optional `.terminusignore` removes additional files from
+Terminus source sync even when Git tracks them—for example local fixtures or
+internal design notes. Neither file controls the explicitly configured runtime
+payload: `terminus push` runs the build and attaches that output as a derived,
+content-addressed bundle bound to the resulting source revision. The platform
+serves that bundle, but it is not editable state and is never pulled back into
+the working tree.
+
+Secrets, dependency trees (`node_modules/`), Git metadata, and local dev fixtures
+are denied in every plane even if an ignore file or Git index includes them. A
+source edit makes the previous bundle stale; publishing succeeds only after a
+fresh bundle is attached for that exact revision. A differing `pull` stops
+without changing files unless `--force` is supplied.
+
+Published apps are normal multi-file websites on their own
+`*.apps.terminus.build` origin. The SDK uses same-origin, app-scoped APIs for
+managed collections, storage buckets, the person's own files (the private and
+output zones), spaces, collaborative events, notifications, logs, and the
+external services an app's code names. The user's Terminus login token is never exposed to
+app JavaScript. Managed collections are defined once where app code opens them
+(`db.collection(...)`) and are provisioned lazily for the installed
+release; they are not duplicated in `terminus.json` (only a collection that
+nothing but an automation writes is declared there, below). For conventional npm
+projects the CLI also infers `npm run build` and `dist/`, so `ui` is needed only
+as a nonstandard override. The manifest stays focused on canonical identity and
+technical release configuration.
+
+Every generated starter imports the SDK by name (`import { db, ready } from
+"@terminus-ai/app-sdk"`), so its bundle carries only the namespaces it uses. It
+is collection-first: its sample UI opens a live `items` collection, renders the
+persistent IndexedDB-backed cached view, and uses optimistic `put`/`delete`
+mutations. The generated `AGENTS.md` records the same architecture for future
+coding agents: collections for structured state, storage buckets and files for
+blobs and exported files. App code must not add an app-owned backend database;
+user-owned capsules stay independent of the app release and therefore survive
+forks, upgrades, and migrations.
+
+Apps declare background work as data, not as a deployment.
+`workloads.automations` is a bounded list of JSON steps using only
+`collection.put`, `collection.delete`, `notification.create`,
+`connector.request`, `service.invoke`, and `server.run`.
+`workloads.schedules` attaches a five-field cron plus an optional IANA
+`timezone` (UTC by default) to one automation, and `lifecycle.migrations` advances an
+integer app-data version through the same durable job path.
+
+An app that needs logic the browser cannot run keeps it in `server/`:
+standard-library Node in `server/main.js`, exporting its ops
+(`exports.ops = { top(input, { terminus, ctx }) { … } }`), or Python in
+`server/main.py`. Nothing about it is written in `terminus.json`: what the
+server code may do is read from the code itself, as it is for everything else
+an app uses:
+
+- An op exists because something calls it: the app, with
+  `server.call("<op>", input)` from `@terminus-ai/app-sdk`, or an
+  automation, with a `server.run` step — always by literal name. An op the
+  app calls runs within 10 s; an op only automations run is background-only
+  and runs within 120 s.
+- Records are the scopes and collections the server code's literal
+  `terminus.records.<get|put|delete|query|update>("<scope>", "<collection>", …)`
+  calls name: `global` is one pool for the whole app, `installation` one
+  per user.
+- Every op called must be one the entry exports; `terminus validate` loads
+  the entry to check.
+
+`terminus.records.query` answers one page, `{documents, next_cursor}`: by
+doc id, or by one top-level field with `sort: "-best"`, at most `limit`
+(1–100) documents, and the next page with `after: next_cursor`.
+`terminus.records.update(scope, collection, doc, fn)` is the compare-and-set
+loop in one call: it reads the record, writes what `fn(current)` returns
+against the version it read, and reads again on a `version_conflict`. A
+refused syscall throws an `Error` whose `code` and `status` are the
+platform's (`version_conflict` 409, `quota_exceeded` 402, …) — branch on
+`error.code`, never on the message.
+
+The CLI ships `server/` as release materials with `role: "server"` (runtime
+code: it travels with a closed-source release and never enters the browser
+bundle) and holds the entrypoint to 128 KiB and `server/` to 512 KiB.
+`terminus dev` runs it the way the platform does: every `server.call` and
+every `server.run` step runs the op in a fresh sandbox — the standard
+library and `server/` siblings only, no network but `terminus.webFetch`, no
+files outside `server/`, the op's time budget — under the platform's
+records, capsule, fetch and collect rules, limits and error messages.
+Records live in `.terminus/dev/` (one global pool for the app, one
+installation pool per member), and each op's console output prints in the
+terminal. Node server code runs locally on macOS and Linux (where one
+syscall argument, such as a `records.put` document, is capped at 128 KiB —
+tighter than on the platform); Python needs `python3`.
+
+Agents do not use `workloads` at all: an agent is its own orchestrator, so a
+trigger on an agent just means "wake the agent". Agents declare four
+top-level prompt-form sections, each entry carrying at most a `prompt` (what
+the wake says — optional, since `AGENT.md` already says what the agent does)
+and `enabled`. Every standing run notifies — there is no toggle: the
+notification is a compact card (the agent's identity, a short preview the
+platform derives from the reply's first line, and the agent as the
+click-through), and a run whose reply is empty sends nothing:
+
+- `schedules` (≤64): a structured cadence — `{ "every": "day" | a weekday |
+  "month" | "30m" | "2h", "at": "HH:MM", "on_day": 1-31, "timezone": IANA
+  or `"user"` }` — or a raw five-field `cron` escape hatch. `"user"` means
+  each installer's own timezone: the platform resolves it per installation
+  (captured at install approval, re-resolved hourly), so "every Monday
+  morning" is every user's own Monday morning.
+- `webhooks` (`{ name?, prompt?, description?, enabled?,
+  coalesce_seconds? }`, ≤16): installing provisions one capability-URL
+  endpoint per webhook; the person who installed the agent makes its URL in
+  the installation's Automations window on Terminus, which shows it once
+  (making a new one revokes the old), and deliveries at
+  `POST /v1/hooks/{token}` wake the agent with the payload.
+- `watches` (`{ name?, url, pattern?, interval_minutes?, condition?,
+  prompt?, description?, enabled? }`, ≤8, https only, 15-minute floor,
+  hourly by default): the platform polls the source, extracts the optional
+  regex match, and only a real content change wakes the agent with the
+  diff. `condition` gates firing on a numeric threshold the poller
+  evaluates with **no model spend** — exactly one of
+  `{ "changed_by_pct": 2 }` (the watched number moved 2% from the value
+  last fired about), `{ "below": 220 }`, or `{ "above": 250 }` (crossing
+  the level) — so "tell me when AAPL moves 2%" costs nothing while the
+  market sleeps.
+- `events` (`{ name?, collection, prompt?, description?, enabled?,
+  coalesce_seconds? }`, ≤16): wakes the agent when records in one of the
+  agent's own declared collections change.
+
+`name` is optional while a section has a single entry and required to
+disambiguate several. `coalesce_seconds` (0–3600) batches webhook/event
+firings into fixed wall-clock windows delivered together when the window
+closes. Event payloads are data, never instructions — the platform appends
+them to the wake prompt inside an explicit untrusted-event-data fence. A
+trigger that fails ten firings in a row pauses itself and notifies the
+owner.
+
+`terminus validate` compiles these sections into the platform's canonical
+`workloads` wire shape (shared `scheduled-run` automations parametrized by
+`input.prompt`), so the runtime — scheduling, fatigue, the durable
+runner — is identical to an app's. Publishing a `workloads` block on a
+`kind: agent` manifest is refused with a migration hint. An app example:
+
+```json
+{
+  "workloads": {
+    "automations": [{
+      "name": "remind",
+      "steps": [{
+        "action": "notification.create",
+        "params": { "title": { "$from": "input.title" } }
+      }]
+    }],
+    "schedules": [{
+      "name": "morning",
+      "cron": "0 9 * * *",
+      "automation": "remind",
+      "input": { "title": "Good morning" }
+    }]
+  },
+  "shell": { "notifications": true },
+  "lifecycle": { "data_version": 1, "migrations": [] }
+}
+```
+
+`terminus validate` checks names, cron syntax, migration chains, action
+permissions, and explicit `input.*` / `context.*` substitutions. `terminus
+dev` simulates collection and notification actions plus job/schedule/lifecycle
+SDK routes. Connector and external-service actions stay broker boundaries and
+should be mocked in local app tests. Unlike collections opened only by browser
+code, a collection referenced by a background automation must also be declared
+in `resources.collections`; this gives the platform a release-approved schema
+to enforce when no browser session is present.
+
+Agent packages keep their prompt in `AGENT.md`, any files the agent should
+know beside it (the whole package ships read-only in the agent's working
+directory, at its own paths), and a small semantic tool list in
+`terminus.json`.
+Terminus compiles
+those ids into the detailed release grant; OAuth tokens, connection ids, and
+per-user resource grants never enter the package. A scheduled inbox agent can
+look like this:
+
+```json
+{
+  "kind": "agent",
+  "id": "@publisher/daily-inbox",
+  "version": "0.0.1",
+  "tools": [
+    {
+      "id": "gmail.read",
+      "when": "Prepare the user's daily inbox digest."
+    }
+  ],
+  "schedules": [{
+    "every": "day",
+    "at": "07:00",
+    "timezone": "America/Los_Angeles",
+    "prompt": "Summarize what happened in my inbox yesterday."
+  }]
+}
+```
+
+That one entry is the whole standing life: the agent runs every morning at
+7:00 Pacific, and a compact notification lands — the agent, one preview
+line drawn from the reply's opening, and a tap-through to the agent (a
+morning with nothing to say sends nothing). The prompt is optional —
+without it the wake just tells the agent which schedule fired and
+`AGENT.md` carries the task — and `shell.notifications` is derived from
+declaring a trigger, never hand-written.
+
+Run `terminus connectors gmail` to inspect the currently supported Gmail tool
+ids, operations, and scopes. Then `terminus validate .` and `terminus dev .`
+— local agent dev: the loop runs on your machine (bash/python execute
+natively inside a workspace-write sandbox over the lane workspace in
+`.terminus/dev/agent/`), while the system prompt and tool definitions
+compile server-side from your manifest, so local runs always match what
+publishing produces. It works immediately after init — no creation or link
+required — and `terminus dev . --prompt "…" [--json]` gives scripts and coding
+agents a one-shot lane.
+
+An agent chooses its models in one `models` section. `terminus init agent`
+writes the house configuration, which is also what an agent that says nothing
+gets: every model on Terminus, starting on GPT-5.6 Luna.
+
+```json
+"models": { "default": "openai:gpt-5.6-luna", "mode": "all" }
+```
+
+`"mode": "selective"` with an `"available"` list narrows the choice, and
+`"mode": "default"` keeps the agent on its default alone.
+
+An agent's `type` says who can read its conversations. Left out, it is
+`"default"`: each conversation stays private to the person having it.
+`"observed"` shares every conversation with the agent's maintainers, and
+people accept a notice saying so before their first message. The
+inspector's Type switch writes the key for you.
+
+```json
+"type": "observed"
+```
+
+Declared triggers are exercisable locally before publishing: the
+inspector's Schedules section shows every trigger as a card — the cadence in
+words, the wake prompt, whether it notifies — with add, edit, and remove
+writing `terminus.json` in place (webhooks also accept real deliveries at
+the local `POST /hooks/{token}` URL the webhook's card shows; point curl or a
+tunnel at it. As on the platform, the token is the whole capability: it
+admits a delivery under any `Host`, and each webhook keeps its token in
+`.terminus/dev/agent/webhook-tokens.json`, so a tunnel survives restarts;
+delete the file to rotate them), and
+`terminus dev . --trigger <name> [--payload file.json] [--json]` is the
+headless lane. A simulated firing builds the trigger's input the way the
+platform builds it, runs the wake as a real local turn behind the same
+untrusted-event fence, and reports the notification (or its skip, when the
+run produced no text) on the transcript. Connect your own Gmail account in Terminus to
+exercise `gmail.read` live; before publishing, `terminus dev . --remote`
+runs the same conversation on the platform's real engine and real isolate.
+Publishing and installing the release binds the same `gmail.read`
+declaration to each visitor's own Gmail connection; the hosted schedule then
+runs on that visitor's durable VM-free session.
+
+Service artifacts describe atomic callable APIs. `runtime.kind` says how the
+platform reaches the implementation: `external` names an HTTP endpoint (yours,
+platform-hosted, or a third party's — the `authentication` mode and explicit
+commerce fields carry that difference, while `provider_relationship`,
+`upstream_cost_bearer`, `payout_recipient`, and `health_path` default to the
+first-party posture `owned`/`none`/`publisher`/`/health/ready`); `builtin`
+names an engine implemented inside the Terminus backend and carries nothing
+else.
+
+```sh
+terminus init my-converter --kind service                  # describe an existing HTTPS API
+# set runtime.base_url and the auth mode in terminus.json; state
+# provider_relationship/cost bearer only when they differ from the defaults
+terminus validate my-converter                   # validates the manifest + OpenAPI
+# make the service on the web (Creations → New creation), then connect the folder
+terminus remote add @you/my-converter my-converter     # names the package after its address
+# deploy the API on AWS/Azure/etc; test updates the service's private draft
+terminus service test my-converter document.convert --file sample.pdf
+terminus dev my-converter                        # serves the package's dev/ test page
+terminus push my-converter                       # uploads the draft; publish it on the web
+
+```
+
+`terminus dev <service-dir>` starts a local test session on its own port: it
+refreshes the linked service's draft from the folder, serves the package's own `dev/index.html` (plus siblings in
+`dev/`), and relays invocations through the free draft-test lane — a direct
+signed call for public `terminus_signed` endpoints, the gateway test door
+otherwise. The page contract is host-provided: the harness injects
+`window.__SERVICE_DEV__ = { service, operations, invoke }`, and the page calls
+`invoke(operationId, { input, query, bytes, idempotencyKey })` — `input` for
+JSON operations, `bytes` (an ArrayBuffer or Blob) with `query` parameters for
+binary ones — and receives the test-lane result `{ status, content_type,
+body, body_base64, … }`. Never hard-code a transport: `dev/` files upload
+with the release (`role: "dev"`, outside every runtime plane), and whatever
+serves the page later provides its own `invoke`.
+
+For an external service, `openapi.json` is the machine contract and `README.md`
+is human/agent guidance. The contract lives at the repository root by default;
+`terminus.json` states an `openapi` path only when the file deliberately lives
+elsewhere, and a package with neither is refused. The manifest otherwise
+contains the unscoped package name, version, description, endpoint,
+provider/cost relationship, payout policy, and authentication mode. API-key or
+OAuth secrets are referenced by environment-variable name and uploaded
+separately; their values never enter the package or release. The backend is the
+authoritative parser: each test/publish uploads the raw package, compiles
+OpenAPI, and creates or updates the private service draft and binding. Terminus
+retains the publisher address, price, icon, listing, release/verification state,
+and encrypted secrets. Terminus-signed tests receive a short-lived scoped JWT
+and call the manifest endpoint directly; other auth modes use the broker. No
+credits move during tests, and there is no arbitrary URL override.
+
+Terminus does not execute service-package code. Browser apps call only the
+external operations declared in their release; the broker supplies scoped
+identity, enforces consent and billing, and keeps provider credentials out of
+browser JavaScript.
+
+Bare `terminus` (or `terminus help`) prints its version and the everyday commands, grouped, each
+with what it does on one line (`<word>` is a placeholder, `[ ]` is optional):
+
+```text
+Terminus v0.0.1, created by Terminus Intelligence
+
+Account:
+  terminus login                         Open your browser and sign in
+  terminus account                       Your account's station
+  terminus notifications                 Check your notifications
+
+Explore:
+  terminus search <query>                Search the Terminus catalog
+
+Developing:
+  terminus init <kind> [<dir>]           Start a new creation
+  terminus clone <address> [<dir>]       Download a creation to edit
+  terminus remote add <address> [<dir>]  Connect a folder to a creation
+  terminus dev [<dir>]                   Mock your creation locally
+  terminus validate [<dir>]              Check a package for problems
+  terminus status [<dir>]                Compare your copy with Terminus
+  terminus pull [<dir>]                  Merge the draft's changes into yours
+  terminus push [<dir>]                  Upload your changes as a draft
+  terminus logs <app>                    Show a published app's logs
+
+  Mock it locally so your coding agent can test end to end — an app:
+    terminus clone @you/app && cd app
+    npm run build                        # apps are built before they run
+    terminus dev --members 3             # three at once; --fresh to start empty
+    terminus push --message "Rooms can be renamed"
+
+  An agent, which has no build step:
+    terminus clone @you/agent && cd agent
+    terminus dev                         # a chat page; --remote for real data
+    terminus dev --prompt "Two lines on today's inbox"
+    terminus push --message "Sharper summary"
+
+  Every other key, --port included, and what each kind runs: terminus help dev
+
+Install Skills:
+  terminus skills                        Install skills in Claude Code or Codex
+
+Management:
+  terminus creations                     Manage your published creations
+  terminus drafts                        Manage your drafts
+
+Further help:
+  terminus commands                      List every command
+  terminus help [<command>]              Show how to use a command
+  https://www.terminus.build/docs/
+```
+
+`terminus commands` lists every command, then the options, environment
+variables, and exit codes they share; `terminus help <command>` and
+`terminus <command> --help` show one command's usage, options, and examples, the
+way `brew search --help` does. `terminus skills` on its own lists every skills
+command, each with what it does. A command given the wrong arguments prints that
+same help, then `Error: Invalid usage: …` naming what was wrong (`--json` keeps
+just that line). Both blocks here are the CLI's exact output, kept in sync by a
+test.
+
+```text
+Usage: terminus <command> [<arguments>] [<options>]
+
+Account:
+  login          Sign in to Terminus in your browser
+  logout         Sign out and revoke this device's session
+  account        Your account's station
+  notifications  Check your notifications
+
+Explore:
+  search         Search the catalog
+
+Developing:
+  init           Create a new app, agent, service, or skill
+  clone          Copy a creation into a new folder
+  fork           Fork someone's open-source creation and clone it
+  remote         Show or change the creation a folder is connected to
+  dev            Run a package on this machine
+  build          Build an app's browser bundle
+  validate       Check a package for problems before pushing
+  status         Compare your working copy with its draft and live release
+  diff           Show your changes, or compare two releases
+  pull           Merge the draft's changes into your working copy
+  push           Upload your working copy to its online draft
+  log            Show a draft's history, or a creation's releases
+  restore        Put the draft back the way it was at an earlier commit
+  logs           Show a published app's recent logs
+  secrets        Manage sealed credentials for your package
+  data           Inspect, export, or import local dev data
+  service        Inspect services, test operations, and run jobs
+  connectors     List the connectors your agents can use
+
+Install Skills:
+  skills         Install and use skills in Claude Code or Codex
+
+Management:
+  creations      Manage your published creations
+  drafts         Manage your drafts
+
+Your published apps:
+  inspect        Show a published app's runtime state
+
+Releases:
+  outdated       Check a creation's dependencies for newer releases
+
+Help:
+  help           Show help for a command
+  commands       List every command
+  version        Print the CLI version
+
+Options:
+  -h, --help        Show help for terminus or a command
+  -v, --version     Print the CLI version
+  --json            Print machine-readable output (most commands)
+  --api-base <url>  Use another Terminus API (default:
+                    https://api.terminus.build)
+
+Environment:
+  TERMINUS_TOKEN     Use this access token instead of your saved login
+  TERMINUS_API_BASE  Same as --api-base
+
+Exit codes:
+  0 success, 1 error, 2 bad usage, 3 not signed in, 69 Terminus unreachable,
+  75 rate limited, 77 not allowed. With --json, errors are printed to stderr
+  as JSON.
+
+Run 'terminus help <command>' for details on a command.
+Docs: https://www.terminus.build/docs/
+```
+
+Flags are parsed strictly: an option a command does not declare (or a typo
+such as `--limt`) fails before any network call.
+
+## The agentd binary
+
+`terminus dev <agent-dir>` runs the agent on `terminus-agentd`. Installing
+this CLI installs it too: the four `@terminus-ai/agentd-*` packages are
+`optionalDependencies` carrying one prebuilt binary each, and their `os`
+and `cpu` fields mean npm unpacks only the one your machine can run. Once
+those packages are on npm there is no download on first use and nothing to
+authenticate against. Until their first publish, which waits for initial
+development to finish, agentd runs from a build of your own: lane 1, or
+lane 3 staged by hand.
+
+The CLI takes the first of these it finds:
+
+1. `--agentd PATH` or `$TERMINUS_AGENTD` — point either at your own build;
+2. a `terminus-agentd` on `$PATH`;
+3. the installed `@terminus-ai/agentd-*` package.
+
+On a platform with no build — Windows, or an unusual architecture — npm
+skips all four packages and installs the CLI anyway; everything except
+`terminus dev` on an agent works, and that command asks for
+`$TERMINUS_AGENTD`.
+
+To run `terminus dev` against an agentd you built yourself, set
+`$TERMINUS_AGENTD` (lane 1) — or, to exercise the packaging itself, follow
+`docs/LOCAL_DEVELOPMENT.md` in the terminus-agent repo.
+
+## Sealed secrets
+
+Outbound calls a package declares can use credentials the platform keeps sealed. Set them per
+linked package; values come from stdin (or `$TERMINUS_SECRET_VALUE`), never the command line, and
+can never be read back:
+
+```sh
+pbpaste | terminus secrets set OPENAI_API_KEY
+terminus secrets list
+terminus secrets delete OPENAI_API_KEY
+```
+
+## Exit codes
+
+| Code | Meaning | `--json` error code |
+| ---- | ------- | ------------------- |
+| `0` | success | — |
+| `1` | any other failure (another API 4xx/5xx, an invalid package, …) | `error` |
+| `2` | usage: unknown command or option, missing argument | `usage` |
+| `3` | not signed in: no login, an expired one, or the API answered 401 (`unauthorized`, `session_ended`) | `auth` |
+| `69` | Terminus unreachable: connection failure, timeout, 502/503/504 | `unavailable` |
+| `75` | rate limited (429; the message carries the retry hint) | `rate_limited` |
+| `77` | not allowed: the API answered 403 (`forbidden`, `grant_required`), or a closed skill's content was asked for | `forbidden` |
+
+With `--json`, a failure writes exactly one JSON object to stderr —
+`{"error":{"code":"…","message":"…"}}` — so agents can branch on the code
+without parsing prose. A failure the Terminus API answered also carries its
+HTTP `status`, the API's own `api_code` (for example `grant_required` or
+`price_confirmation_required`), and its `details` when it gave any. Without
+`--json` the message is printed as plain text.
+
+Reads (and any request carrying an Idempotency-Key) are retried twice, with
+backoff, when Terminus is briefly unavailable or the connection drops; other
+writes are sent once. A request has 30 seconds to be answered, plus time for
+what it uploads, and a download may take as long as its bytes keep arriving.
+
+## Version history
+
+Artifacts whose listing enables source visibility (set on the web) expose their
+code and release history publicly — on the web (the artifact page's Code and History
+tabs) and locally:
+
+```sh
+terminus log @terminus/chats                 # release list with publish messages
+terminus diff @terminus/chats                # latest release vs the previous one
+terminus diff @terminus/chats --from 1.0.0 --to 1.2.0
+terminus diff @terminus/chats --from 1 --to 3   # release numbers work too
+```
+
+The note you write when publishing on the web annotates the release, like a
+commit message. Skills use the same commands over their revision ledger. Versions follow the
+one grammar everywhere: `"version": "1.2.0"` in `terminus.json` (`version:`
+frontmatter for skills) names the release; a named version can never be
+reused for different content, and every publish must climb past the latest —
+bump patch, minor, or major per release, your call. `terminus outdated <ref>`
+reports every declared dependency's pin against its current version.
+
+The CLI compiles the authored package into the backend's internal wire
+contract. Every runtime and source file carries its decoded byte length and SHA-256 digest, and a sorted
+aggregate digest identifies the complete package. The backend verifies both
+the file index and file bytes before accepting or materializing a release.
+
+Presentation, visibility, and commerce settings change live on the web without
+a republish because they are artifact metadata, not package or release fields.
+
+## Environment
+
+- `TERMINUS_TOKEN`: a session token every command uses instead of the saved login.
+- `TERMINUS_API_BASE`: defaults to `https://api.terminus.build`; `/v1` is added automatically if omitted.
+- `TERMINUS_WEB_BASE`: the web app browser login opens. Defaults to `https://www.terminus.build`.
+- `TERMINUS_AGENTD`: a `terminus-agentd` binary for `terminus dev` on agents (same as `--agentd`).
+- `TERMINUS_SECRET_VALUE`: the value for `terminus secrets set` when stdin is not used.
+
+## Platform services
+
+`terminus service inspect @terminus/brave-search --json` reads the published
+operation contract without making a provider call. Every provider is an atomic
+service under the same address/operation permissions. In app source,
+`services.search("@terminus/brave-search", input)` and
+`services.fetch("@terminus/obscura", input)` infer `search` and `fetch` grants.
+Use literal addresses so the release can show its exact dependencies. Provider
+credentials stay with each service on Terminus and never enter a package; the
+agent tools `web.search` and `web.fetch` are routed across providers by the
+platform. `terminus service test` tests your own external service package.
+
+### Durable service jobs
+
+Submit a managed image, document, code, or email operation with a stable key:
+
+```sh
+terminus service submit SERVICE_UUID execute --input '{"runtime":"python","code":"print(2 + 2)"}' --idempotency-key calculation-123
+terminus service job JOB_UUID --wait
+terminus service jobs --service-id SERVICE_UUID
+terminus service cancel JOB_UUID
+terminus service save JOB_UUID FILE_UUID home/result.txt
+```
+
+Use `--file input.json` instead of `--input` for larger inputs. File references
+must name a `home/` path and its SHA-256 version. `save` creates by default; add
+`--expected-sha256 PREVIOUS_SHA` to replace exactly the version you inspected.
+Temporary results expire unless saved. The list command returns the latest 50
+jobs; API consumers can page using the last `(created_at, job_id)` tuple.
+
+Operations are `generate`/`edit`, `convert`, `execute`, and `send`. SDK helper
+calls compile to the corresponding service-operation grants during app build.
+Image helpers grant both generation and editing. Execution supports bounded
+shell/Python/JavaScript, not native packages or network access. Private jobs
+require the hosted runtime; the local app harness does not emulate provider
+side effects. `--wait` stops after five minutes or at a terminal/`reconciling`
+state. Reuse the same key to inspect an uncertain submission; do not generate
+a fresh key automatically. SMTP acceptance is distinct from inbox delivery.
+
+## Working on this CLI
+
+```bash
+npm test                            # the offline suite (no network)
+npm link                            # use this checkout as `terminus`
+npm uninstall -g @terminus-ai/cli   # remove the linked CLI
+```
+
+Pull-request CI runs `npm test` and `npm run build` and cancels superseded runs
+for the same PR; a change to docs alone skips them, except this README, whose
+help blocks the suite checks. The suite is not repeated after merge; run it
+locally before pushing code changes.
+
+Releases are published from GitHub, never from a laptop: a maintainer
+dispatches the manual `cli-publish` workflow on `main`, which runs the suite on
+that commit and publishes it to npm as `@terminus-ai/cli` (with provenance once
+this repository is public). The unscoped name `terminus` belongs to another
+npm package; never publish under it.