nylorun 0.4.0-beta → 0.5.0-beta

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # nylorun
 
+## 0.5.0-beta
+
+### Minor Changes
+
+- f96fe32: **Studio reports anonymous page views, unless you opt out.** Studio sends page views to Google Analytics with every Tenant, agent and session id replaced by `:id` and the query dropped; nothing sent to agents is collected. `nylorun start` says so once, and passes the measurement id to the Studio container as `NYLORUN_STUDIO_ANALYTICS_ID`. Turn it off with `nylorun telemetry disable`, `NYLORUN_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`; it is always off in CI, inside an embedding app, and when the browser sends Do Not Track or Global Privacy Control.
+- 4b9906f: **Breaking: "Tenant" replaces "stack", and `nylorun start` works anywhere.** Each local installation holds one Tenant, and its name is the Tenant's name, so help, output, errors and docs say Tenant. See MIGRATION.md.
+
+  - **Breaking (`nylorun`): selection.** Every command acts on the Tenant `--tenant <name>` names (replaces `--name`, which is removed), else `NYLORUN_TENANT` (replaces `NYLORUN_STACK`), else the Project link's `tenant`; `start` in a project names a new one after the project directory. Outside a project, or with `start --no-link`, commands act on the Tenant `default`. In a project without a link, commands other than `start` exit 2 and list the machine's Tenants. A name starting with `tn_` (a Tenant id) is refused.
+  - **Breaking (`nylorun`): files.** Host roots are under `~/.nylorun/tenants/<name>/` (was `~/.nylorun/stacks/<name>/`) with `tenant.json` (was `stack.json`); the `.env` key is `NYLORUN_TENANT_NAME` (was `NYLORUN_STACK_NAME`); `NYLORUN_COMPOSE_PROJECT` replaces `NYLORUN_STACK_PROJECT`. Compose projects stay `nylorun-<name>`. Every command first moves 0.4 Host roots from `~/.nylorun/stacks/` to `~/.nylorun/tenants/` (renaming `stack.json` and the `.env` key), so they keep their volumes and keys. `nylorun ls` lists only directories with `tenant.json`.
+  - **Breaking (`nylorun`): removed.** `nylorun legacy` and all handling of the single stack of releases before 0.4; the hidden `nylorun stack <cmd>` alias; `nylorun doctor stack|runtime`. Output says Tenant: `ls` prints `TENANT` and JSON `{ "tenants": [...] }`, `status` prints the Tenant id on its own line, and `doctor`'s row is `tenant`.
+  - **Breaking: Project link format 3.** `.nylorun/link.json` is `{ "format": 3, "tenant", "tenantId", "hostUrl", "hostId" }`; `tenant` replaces `stack`. `@nylorun/agents`, `@nylorun/cli` and `@nylorun/admin` refuse an older link and name `npx nylorun start`, which rewrites it. `@nylorun/core`'s `ProjectLinkFileSchema` parses formats 0–3 with `tenant`.
+  - **Breaking (`@nylorun/admin`):** `createAdmin({ tenant })` replaces `{ stack }`, `tenantHostRoot(name)` replaces `stackHostRoot(name)`, and local resolution reads `NYLORUN_TENANT` and the link's `tenant`.
+  - `@nylorun/cli`: `status` and `endpoints` drop the `stack` line and JSON key; messages say Tenant. `@nylorun/agents`: a Runtime too old for the client says "update the Runtime (npx nylorun@latest start)". `@nylorun/studio`: setup hints say Tenant. `@nylorun/create-agent`: the next steps describe `npx nylorun@beta start` as this project's Tenant and its link.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [4b9906f]
+  - @nylorun/core@0.11.0-beta
+
 ## 0.4.0-beta
 
 ### Major Changes

package/README.md

@@ -1,23 +1,23 @@
 # nylorun
 
-Sets up and runs local Nylorun stacks: the Runtime and Studio, as Docker
-Compose stacks, one per project. It needs nothing in your project; run it with
+Sets up and runs local Nylorun Tenants: the Runtime and Studio, in Docker
+Compose, one Tenant per project. It needs nothing in your project; run it with
 `npx` in the project's directory:
 
 ```sh
-npx nylorun start   # create (first run) and start this project's stack, its Tenant and the Project link
+npx nylorun start   # create (first run) and start this project's Tenant, and the Project link
 npx nylorun stop    # stop it; volumes (and the Tenant's data) are kept
 ```
 
-A stack is one installation: one Runtime with its own Postgres, Restate and
-S2, serving exactly one Tenant. `nylorun start` in a project creates the
-project's stack, the Runtime creates the stack's Tenant on its first start,
-and `nylorun start` links the project to it. There are no Tenant commands:
-projects that must not share agents, credentials or history run separate
-stacks. Agents, sessions and model providers belong to the Runtime client,
-[`@nylorun/cli`](../cli/README.md) (command `nylo`). Depends on `@nylorun/core`
-only among Nylorun packages and never imports `@nylorun/runtime`. Vocabulary:
-[runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
+A local Tenant is one installation: one Runtime with its own Postgres, Restate
+and S2, serving exactly that Tenant, and its name is the Tenant's name.
+`nylorun start` in a project creates the project's Tenant (the Runtime creates
+it on its first start) and links the project to it; anywhere else, it starts
+the Tenant `default`. Projects that must not share agents, credentials or
+history run separate Tenants. Agents, sessions and model providers belong to
+the Runtime client, [`@nylorun/cli`](../cli/README.md) (command `nylo`).
+Depends on `@nylorun/core` only among Nylorun packages and never imports
+`@nylorun/runtime`. Vocabulary: [runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
 
 Prerequisites, installed by the developer (nylorun never downloads them): Node
 24 or newer, and Docker with Compose v2 ([Docker
@@ -28,53 +28,57 @@ another engine). On Windows, install them inside
 supported.
 
 ```sh
-npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the stack's health
+npx nylorun doctor                 # Node 24+, Docker, Compose v2, and the Tenant's health
 ```
 
 ## Commands
 
 ```sh
-nylorun up|start [--name <stack>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
-                                   # create (first run) and start the stack; link the project; print the URLs; open Studio signed in
-nylorun down|stop [--name <stack>] # stop the containers; keep volumes
-nylorun status [--name <stack>] [--json]   # the stack, its Host root and Tenant, services, endpoints, Runtime health
-nylorun logs [service] [--name <stack>] [-f] [--tail <n>]   # postgres, restate, s2, gateway, runtime, studio
-nylorun studio [--name <stack>] [--no-open]   # sign a browser in to Studio on the stack's Tenant; starts the stack if needed
-nylorun reset [--name <stack>] [--yes]        # delete the stack's volumes and Tenant directory; the next start creates a new Tenant
-nylorun ls [--json]                # the stacks on this machine
-nylorun delete <stack> --yes       # remove a stack: containers, volumes, Host root and vault key
-nylorun legacy stop|delete [--yes] # the single stack of older releases
-nylorun doctor [--json]            # prerequisites and stack health
+nylorun up|start [--tenant <name>] [--no-link] [--no-studio] [--no-open] [--allow-downgrade] [--studio-embed-origin <origin>]... [--studio-embed-origin-reset]
+                                   # create (first run) and start the Tenant; link the project; print the URLs; open Studio signed in
+nylorun down|stop [--tenant <name>]   # stop the containers; keep volumes
+nylorun status [--tenant <name>] [--json]   # the Tenant, its Host root and id, services, endpoints, Runtime health
+nylorun logs [service] [--tenant <name>] [-f] [--tail <n>]   # postgres, restate, s2, gateway, runtime, studio
+nylorun studio [--tenant <name>] [--no-open]   # sign a browser in to Studio on the Tenant; starts it if needed
+nylorun reset [--tenant <name>] [--yes]        # delete the Tenant's volumes, Tenant directory and vault key; the next start creates it anew
+nylorun ls [--json]                # the Tenants on this machine
+nylorun delete <tenant> --yes      # remove a Tenant: containers, volumes, Host root and vault key
+nylorun doctor [--json]            # prerequisites and the Tenant's health
+nylorun telemetry [status|enable|disable]   # Studio's anonymous usage analytics
 ```
 
 `up` and `down` are the Docker Compose spellings of `start` and `stop`: `down`
-stops the containers and keeps the volumes, so no Tenant data is lost.
-`nylorun stack <command>` still works as a hidden alias. Removed commands exit
-2 naming the replacement: `nylorun tenant …` (`nylorun start` creates the
-Tenant; `nylorun status|reset`, or `nylo status|reset|endpoints`), `nylorun
-dev`, `nylorun configure`, `nylorun status --env` and `nylorun doctor sandbox`.
+stops the containers and keeps the volumes, so no Tenant data is lost. Removed
+commands exit 2 naming the replacement: `nylorun dev`, `nylorun configure`,
+`nylorun status --env` and `nylorun doctor sandbox`.
 
-## Stacks
+## Tenants
 
-Every command acts on one stack, chosen in this order:
+Every command acts on one Tenant, chosen in this order:
 
-1. `--name <stack>`;
-2. `NYLORUN_STACK`;
-3. the stack in the project's link (`.nylorun/link.json`, found from the
+1. `--tenant <name>`;
+2. `NYLORUN_TENANT`;
+3. the Tenant in the project's link (`.nylorun/link.json`, found from the
    working directory upwards);
-4. for `start` in a project only: the project directory's name, lowercased,
-   with characters outside `[a-z0-9_-]` as `-`, and a suffix (`-2`, `-3`, …)
-   when a stack of that name was created for another project directory.
-
-Outside a project, `start` needs `--name`, and the other commands need
-`--name`, `NYLORUN_STACK` or a linked project. `nylorun ls` lists the stacks.
-
-Each stack has its own Host root `~/.nylorun/stacks/<name>/`, Compose project
-`nylorun-<name>` (`NYLORUN_STACK_PROJECT` overrides it), volumes, network and
-ports. `NYLORUN_HOME` replaces the whole Host root (the stack's name then comes
-from its `stack.json`, the project directory or the Host root's own name).
-
-A stack refuses only a Runtime older than its own database: `start` records
+4. for `start` in a project: the project directory's name, lowercased, with
+   characters outside `[a-z0-9_-]` as `-`, and a suffix (`-2`, `-3`, …) when a
+   Tenant of that name was created for another project directory;
+5. outside a project, or `start --no-link`: the Tenant `default`.
+
+In a project without a link, the commands other than `start` exit 2 and list
+the Tenants on this machine. A name is lowercase letters, digits, `-` and `_`;
+a Tenant id (`tn_…`) is refused: pass the Tenant's name (`nylorun ls` lists
+them).
+
+Each Tenant has its own Host root `~/.nylorun/tenants/<name>/`, Compose project
+`nylorun-<name>` (`NYLORUN_COMPOSE_PROJECT` overrides it), volumes, network and
+ports. `NYLORUN_HOME` replaces the whole Host root (the Tenant's name then
+comes from its `tenant.json`, the project directory or the Host root's own
+name). nylorun 0.4 kept Host roots in `~/.nylorun/stacks/`: the first command
+of this release moves them to `~/.nylorun/tenants/`, keeping their Compose
+projects and volumes.
+
+A Tenant refuses only a Runtime older than its own database: `start` records
 the pinned Runtime version in `host.json` (`runtimeVersion`) and exits 5 when
 this nylorun pins an older one. Update nylorun, or pass `--allow-downgrade`
 when both versions use the same database schema (otherwise the Runtime reports
@@ -84,51 +88,51 @@ recorded version.
 
 ## The Project link
 
-`nylorun start` in a project waits until the stack's Tenant is open
+`nylorun start` in a project waits until the Tenant is open
 (`/v1/admin/status`), then writes, in a `.nylorun/` directory (mode 0700, with
 its own `.gitignore` of `*`):
 
-- `link.json`: `{ "format": 2, "stack", "hostUrl", "hostId", "tenantId" }`.
-  The Tenant id is information only: nothing in a request selects a Tenant.
+- `link.json`: `{ "format": 3, "tenant", "tenantId", "hostUrl", "hostId" }`.
+  `tenant` is the local Tenant's name; the Tenant id is information only:
+  nothing in a request selects a Tenant.
 - `credentials.json` (mode 0600): the key of the derived principal `project`,
-  derived from the stack's admin key, and its id.
+  derived from the Tenant's admin key, and its id.
 
-Later starts reuse the stack and rewrite the link only when the stack, its URL,
-Host or Tenant changed (after `nylorun reset`, for example). When it writes a
+Later starts reuse the Tenant and rewrite the link only when the Tenant's name,
+URL, Host or id changed (after `nylorun reset`, for example). When it writes a
 new link, `start` seeds the Tenant from the project's `.env`: the sandbox
 backend (`NYLORUN_SANDBOX=auto|virtual`) and the model credential
 (`MODEL_PROVIDER`, `MODEL`, `MODEL_PROVIDER_API_KEY`, `MODEL_PROVIDER_BASE_URL`,
 or `.nylorun/auth.json`), unless the Tenant has a model or
-`NYLORUN_DEV_MODEL=fixture`. `.env` never configures the stack itself.
+`NYLORUN_DEV_MODEL=fixture`. `.env` never configures the containers.
 
 A fresh clone or a second worktree has no link: `nylorun start` there creates a
-new stack, or `nylorun start --name <stack>` attaches it to an existing one so
-both share the stack's Tenant. `--no-link` starts a stack without linking the
-working directory (scripts). A link of format 0 or 1 named a Tenant on the
-shared stack of an older Runtime: `start` says so, creates the project's own
-stack and replaces the link.
+new Tenant, or `nylorun start --tenant <name>` attaches it to an existing one so
+both share it. `--no-link` starts a Tenant without linking the working
+directory (scripts). A link of an older nylorun (format 0 to 2) counts as no
+link: `start` replaces it.
 
 The Runtime registers the derived principals of `NYLORUN_DERIVED_PRINCIPALS`
-(comma-separated, from the environment of `nylorun start`, kept in the stack's
+(comma-separated, from the environment of `nylorun start`, kept in the Tenant's
 `.env`) when it creates the Tenant; `project` is always among them.
 
-## The stack
+## The containers
 
 `nylorun start` writes `compose.yaml` and `.env` (mode 0600) under
-`~/.nylorun/stacks/<name>/docker/` on the first run and reuses them after that: `postgres`,
+`~/.nylorun/tenants/<name>/docker/` on the first run and reuses them after that: `postgres`,
 `restate`, `s2`, `gateway`, `runtime` and `studio`. Postgres initialises the
-stack's database with C collation. The Runtime and Studio images are pinned by
+Tenant's database with C collation. The Runtime and Studio images are pinned by
 this release (`package.json` `nylorun.runtime` and `nylorun.studio`);
 `NYLORUN_RUNTIME_IMAGE` and `NYLORUN_STUDIO_IMAGE` override them (local builds,
 CI). Ports publish on loopback only: the Runtime on `8787`, its operator
 listener (Admin API) on `8788`, Studio on `4161` and the Restate UI on `9070`,
-or free ports chosen on the stack's first start, avoiding the ports other
-stacks keep, and kept in its `.env`.
+or free ports chosen on the Tenant's first start, avoiding the ports other
+Tenants keep, and kept in its `.env`.
 
 `start` prints Studio as `http://localhost:<port>`. Studio has no password: in a
 terminal (not in CI, and not with `--no-open`), `start` asks the Studio container
 for a single-use login token with the admin key (`POST /_studio/login-tokens`)
-and opens `http://localhost:<port>/login?token=…` on the stack's Tenant in the
+and opens `http://localhost:<port>/login?token=…` on the Tenant's page in the
 browser. That sets a session cookie for 30 days, which survives Studio
 restarts, so the printed URL keeps working in that browser. The token itself is
 never printed unless no browser starts. Otherwise `start` says to run `nylorun
@@ -140,49 +144,55 @@ prints the login URL (it works once, for two minutes) instead.
 A desktop app such as Babai Desktop can show Studio inside its own window, in
 an iframe loaded from Studio's URL (`studio.url` in `nylorun status --json`).
 Only exact origins listed in `NYLORUN_STUDIO_FRAME_ANCESTORS` (in
-`~/.nylorun/stacks/<name>/docker/.env`) may frame it. The default is Babai's
+`~/.nylorun/tenants/<name>/docker/.env`) may frame it. The default is Babai's
 `nylorun://localhost http://nylorun.localhost`; `nylorun status` lists them
 under `Embeds`. While building such an app, add its dev server once with
 `nylorun start --studio-embed-origin http://localhost:1420`; the list is kept
 across starts until `--studio-embed-origin-reset`. Wildcards are refused.
 
-The app's backend mints a single-use login token for the stack's Tenant with
+The app's backend mints a single-use login token for the Tenant with
 `mintStudioLoginToken` from `@nylorun/admin` (it needs the admin key), and its
 page passes the token to Studio by `postMessage`. The message contract is
 `@nylorun/agents/studio-embed`.
 
+### Telemetry
+
+Studio reports anonymous page views to Google Analytics, so we can see which
+parts of it are used. A page view carries the route's shape only: every Tenant,
+agent and session id becomes `:id` (`/tenants/:id/agents/:id/sessions/:id`)
+and the query is dropped. Nothing you send to agents, no names, keys or
+responses, and no Google signals or ad personalization are collected. Studio
+loads no analytics inside an embedding app, or when the browser sends Do Not
+Track or Global Privacy Control.
+
+It is on by default, and `nylorun start` says so the first time. Turn it off on
+this machine with `nylorun telemetry disable` (kept in
+`~/.nylorun/telemetry.json`), or for one start with `NYLORUN_TELEMETRY_DISABLED=1`
+or `DO_NOT_TRACK=1`. It is always off when `CI` is set. `nylorun start` decides
+on every start and writes the result to `NYLORUN_STUDIO_ANALYTICS_ID` in
+`docker/.env` (empty when off); `nylorun telemetry` reports the current choice.
+
 ## Sandboxes
 
 A session gets a sandbox when it is opened with one, or when the Tenant's
-default names one (`PUT /v1/tenant/sandbox`). The stack runs them on the
+default names one (`PUT /v1/tenant/sandbox`). A local Tenant runs them on the
 Runtime's **virtual** backend: an emulated shell in the Runtime process, with no
 extra containers. It is not a VM or container boundary.
 
 ## Host root
 
-The **Host root** is `~/.nylorun/stacks/<name>/`, or `NYLORUN_HOME`. It is
-bind-mounted into the Runtime and Studio containers, and holds `stack.json`
-(the stack's name and the project it was created for), `host.json` (the
-client-facing host and port), `host-credentials.json` (the admin key, mode
-0600), the Docker Compose files in `docker/`, the Tenant directory `tenant/` (homes, logs) and
-`keys/vault-kek`, the Tenant's vault key, which only the gateway container
-mounts. The Tenant's data lives in the stack's Postgres, Restate and S2
-volumes.
-
-`nylorun reset` deletes the selected stack's volumes, `tenant/` and `keys/`, and keeps
-its files and ports; the next start creates a new Tenant and relinks the
-project. `nylorun delete <stack> --yes` removes the stack's containers,
-volumes and Host root: the vault key (KEK) and all the Tenant's data go with it.
-
-## Upgrading from a shared stack
-
-Older releases ran one stack per machine (Compose project `nylorun`, Host root
-`~/.nylorun`) with a Tenant per project. This release starts fresh and leaves
-that stack as it is: `nylorun start` mentions it once, and `nylorun ls` shows
-it. `nylorun legacy stop` stops it; `nylorun legacy delete --yes` removes its
-containers, volumes and files under `~/.nylorun` (never `~/.nylorun/stacks`).
-Model credentials come from each project's `.env` (or Studio), and agents
-register again (`npm run dev`). See [MIGRATION.md](../MIGRATION.md).
+The **Host root** is `~/.nylorun/tenants/<name>/`, or `NYLORUN_HOME`. It is
+bind-mounted into the Runtime and Studio containers, and holds `tenant.json`
+(`{ "format": 1, "name", "project"? }`: the Tenant's name and the project it
+was created for), `host.json` (the client-facing host and port),
+`host-credentials.json` (the admin key, mode 0600), the Docker Compose files in
+`docker/`, the Tenant directory `tenant/` (homes, logs) and `keys/vault-kek`,
+the Tenant's vault key, which only the gateway container mounts. The Tenant's data lives in its Postgres, Restate and S2 volumes.
+
+`nylorun reset` deletes the selected Tenant's volumes, `tenant/` and `keys/`, and keeps
+its files and ports; the next start creates the Tenant anew (with a new id) and
+relinks the project. `nylorun delete <tenant> --yes` removes the Tenant's
+containers, volumes and Host root: the vault key (KEK) and all its data go with it.
 
 ## Exit codes
 
@@ -190,11 +200,11 @@ register again (`npm run dev`). See [MIGRATION.md](../MIGRATION.md).
 | --- | --- |
 | 0 | Success |
 | 1 | Generic failure, including a missing Docker or Compose v2 |
-| 2 | Usage error (including no stack selected, or `delete` without `--yes`), or a removed or moved command |
-| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no stack yet; `delete`: no such stack |
+| 2 | Usage error (including no Tenant selected, or `delete` without `--yes`), or a removed or moved command |
+| 3 | `status`: the Runtime is not answering; `stop`/`logs`: no Tenant yet; `delete`: no such Tenant |
 | 4 | The Runtime port is held by another Host |
-| 5 | `up`/`start`/`studio`: this nylorun pins a Runtime older than the one that last ran the stack; update nylorun, or `start --allow-downgrade` |
-| 7 | The stack, its Tenant or Studio did not become ready (an unavailable Tenant's cause is printed) |
+| 5 | `up`/`start`/`studio`: this nylorun pins a Runtime older than the one that last ran the Tenant; update nylorun, or `start --allow-downgrade` |
+| 7 | The containers, the Tenant or Studio did not become ready (an unavailable Tenant's cause is printed) |
 | 130 / 143 | SIGINT / SIGTERM |
 
 ## Troubleshooting
@@ -204,8 +214,8 @@ register again (`npm run dev`). See [MIGRATION.md](../MIGRATION.md).
 | Docker missing or not running | Install or start Docker Desktop, OrbStack or Colima; `nylorun doctor` checks |
 | `426` from the Runtime | Upgrade nylorun (`npx nylorun@latest start`), or pin a matching older set |
 | `Refusing to start Runtime …` (exit 5) | Upgrade nylorun (`npx nylorun@latest start`); `--allow-downgrade` only when both Runtimes share the database schema |
-| `The Tenant of stack … is unavailable` (exit 7) | Follow the repair it names; `nylorun logs runtime` |
-| Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `~/.nylorun/stacks/<name>/docker/.env` |
+| `Tenant … is unavailable` (exit 7) | Follow the repair it names; `nylorun logs runtime` |
+| Port conflict | Change `NYLORUN_PORT` / `NYLORUN_STUDIO_PORT` in `~/.nylorun/tenants/<name>/docker/.env` |
 | Logs | `nylorun logs runtime -f` |
 | Studio login expired | `nylorun studio` |
 

package/dist/cli.js

@@ -3,28 +3,30 @@ import "./baseline.js";
 import { baselineEnv } from "./baseline.js";
 import { CliError } from "./errors.js";
 import { isStackCommand, stackCommand, stackUsage, studioCommand, } from "./stack/index.js";
-const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|legacy|doctor>
+const usage = `nylorun <up|down|start|stop|status|logs|studio|reset|ls|delete|doctor|telemetry>
 
-Local stacks (Docker Compose), one per project:
+Local Tenants (Docker Compose), one per project:
 ${stackUsage}
-  doctor [--json]                     check Node, Docker and Compose v2, and the stack's health
+  doctor [--json]                     check Node, Docker and Compose v2, and the Tenant's health
+  telemetry [status|enable|disable]   Studio's anonymous usage analytics (on unless disabled,
+                                      NYLORUN_TELEMETRY_DISABLED=1, DO_NOT_TRACK=1 or CI)
 
-A command acts on the stack --name or NYLORUN_STACK names, else the linked project's;
-NYLORUN_HOME sets its Host root (default ~/.nylorun/stacks/<name>).
+A command acts on the Tenant --tenant or NYLORUN_TENANT names, else the linked project's,
+else (outside a project) the default Tenant; NYLORUN_HOME sets its Host root
+(default ~/.nylorun/tenants/<name>).
 
-nylorun sets up and runs local stacks. "nylorun start" in a project creates the
-project's stack, its one Tenant and the Project link. Agents, sessions and model
-providers belong to the Runtime client: npx @nylorun/cli --help`;
+nylorun sets up and runs local Tenants. "nylorun start" in a project creates the
+project's Tenant and the Project link; anywhere else, it starts the default Tenant.
+Agents, sessions and model providers belong to the Runtime client: npx @nylorun/cli --help`;
 const CLIENT = "npx @nylorun/cli";
 /** Commands that were removed, or moved to the Runtime client (`@nylorun/cli`, command `nylo`). */
 const MOVED_TO_CLIENT = {
-    dev: "nylorun dev was removed: run `npx nylorun start` in your project (it creates the project's stack, its Tenant and the Project link), then your project's `npm run dev`.",
-    tenant: `Tenant commands were removed: a stack serves one Tenant, which \`npx nylorun start\` in a project creates with the stack and the Project link. Use nylorun status|reset, or ${CLIENT} status|reset|endpoints.`,
+    dev: "nylorun dev was removed: run `npx nylorun start` in your project (it creates the project's Tenant and the Project link), then your project's `npm run dev`.",
     configure: `nylorun configure moved to the Runtime client: ${CLIENT} configure`,
     serve: "nylorun serve was removed. Use node dist/src/main.js with NYLORUN_RUNTIME_URL and NYLORUN_SERVER_KEY.",
-    runtime: "nylorun runtime was removed: the local Runtime runs in the Docker Compose stack. Use nylorun up|down|status|logs.",
+    runtime: "nylorun runtime was removed: the local Runtime runs in Docker Compose. Use nylorun up|down|status|logs.",
 };
-const LOCAL_UI_REMOVED = "--local-ui was removed: Studio runs in the stack's studio container. Run nylorun studio.";
+const LOCAL_UI_REMOVED = "--local-ui was removed: Studio runs in its own container. Run nylorun studio.";
 const usageError = (message) => new CliError(message, 2);
 async function main() {
     const [command, ...args] = process.argv.slice(2);
@@ -47,23 +49,23 @@ async function main() {
         process.exitCode = await stackCommand(command, args, baselineEnv());
         return;
     }
-    // `nylorun stack <command>`: the Wave 1 spelling, kept as a hidden alias.
-    if (command === "stack") {
-        const [name, ...rest] = args;
-        if (!isStackCommand(name))
-            throw usageError(usage);
-        process.exitCode = await stackCommand(name, rest, baselineEnv());
+    if (command === "telemetry") {
+        const { telemetryCommand } = await import("./telemetry.js");
+        const { defaultNylorunRoot } = await import("./stack/stacks.js");
+        process.exitCode = await telemetryCommand(args, {
+            nylorunRoot: defaultNylorunRoot(),
+            env: baselineEnv(),
+            out: (line) => console.log(line),
+        });
         return;
     }
     if (command === "doctor") {
-        // `doctor stack` and `doctor runtime` are older spellings of `doctor`.
-        const options = args[0] === "stack" || args[0] === "runtime" ? args.slice(1) : args;
         if (args[0] === "sandbox")
             throw usageError(`nylorun doctor sandbox moved to the Runtime client: ${CLIENT} doctor sandbox`);
-        if (options.some((option) => option !== "--json"))
+        if (args.some((option) => option !== "--json"))
             throw usageError("Usage: nylorun doctor [--json]");
         const { doctorStack } = await import("./doctor.js");
-        process.exitCode = await doctorStack({ json: options.includes("--json"), env: baselineEnv() });
+        process.exitCode = await doctorStack({ json: args.includes("--json"), env: baselineEnv() });
         return;
     }
     throw usageError(usage);

package/dist/doctor.d.ts

@@ -6,20 +6,20 @@ export interface StackDoctorReport {
     };
     docker: Check;
     compose?: Check;
-    stack?: Pick<StackStatus, "name" | "project" | "home" | "state" | "runtime" | "tenant" | "studio" | "gateway">;
-    /** Why no stack was checked: none is selected here (no link, NYLORUN_STACK or NYLORUN_HOME). */
-    noStack?: string;
+    tenant?: Pick<StackStatus, "name" | "project" | "home" | "state" | "runtime" | "tenant" | "studio" | "gateway">;
+    /** Why no Tenant was checked: none is selected here (a project without a link). */
+    noTenant?: string;
 }
 /**
- * `nylorun doctor`: check the prerequisites of the local stack (Node 24+,
- * Docker, Compose v2) and, when they pass, the stack's health. Prints the fix
+ * `nylorun doctor`: check the prerequisites of a local Tenant (Node 24+,
+ * Docker, Compose v2) and, when they pass, the Tenant's health. Prints the fix
  * for each problem and returns 1 when a prerequisite is missing or a running
- * stack is unhealthy; installs and starts nothing.
+ * Tenant is unhealthy; installs and starts nothing.
  */
 export declare function doctorStack(options: {
     json: boolean;
     env?: Readonly<Record<string, string | undefined>>;
-    /** Stack dependencies (tests). */
+    /** Command dependencies (tests). */
     deps?: StackDeps;
     log?: (line: string) => void;
 }): Promise<number>;

package/dist/doctor.js

@@ -1,12 +1,12 @@
 import { CliError } from "./errors.js";
 import { checkDocker, defaultStackDeps, readStackStatus, } from "./stack/index.js";
-/** Oldest Node the stack's tooling and the developer's application run on. */
+/** Oldest Node nylorun and the developer's application run on. */
 const MIN_NODE_MAJOR = 24;
 /**
- * `nylorun doctor`: check the prerequisites of the local stack (Node 24+,
- * Docker, Compose v2) and, when they pass, the stack's health. Prints the fix
+ * `nylorun doctor`: check the prerequisites of a local Tenant (Node 24+,
+ * Docker, Compose v2) and, when they pass, the Tenant's health. Prints the fix
  * for each problem and returns 1 when a prerequisite is missing or a running
- * stack is unhealthy; installs and starts nothing.
+ * Tenant is unhealthy; installs and starts nothing.
  */
 export async function doctorStack(options) {
     const log = options.log ?? ((line) => console.log(line));
@@ -20,7 +20,7 @@ export async function doctorStack(options) {
     if (checks.docker.ok && checks.compose?.ok) {
         try {
             const status = await readStackStatus(deps);
-            report.stack = {
+            report.tenant = {
                 name: status.name,
                 project: status.project,
                 home: status.home,
@@ -34,14 +34,14 @@ export async function doctorStack(options) {
         catch (error) {
             if (!(error instanceof CliError) || error.exitCode !== 2)
                 throw error;
-            report.noStack = error.message;
+            report.noTenant = error.message;
         }
     }
-    const stackBroken = report.stack?.state === "running" &&
-        (!report.stack.runtime.healthy ||
-            !report.stack.gateway.healthy ||
-            report.stack.tenant?.cause !== undefined);
-    const failed = !nodeOk || !checks.docker.ok || checks.compose?.ok === false || stackBroken;
+    const broken = report.tenant?.state === "running" &&
+        (!report.tenant.runtime.healthy ||
+            !report.tenant.gateway.healthy ||
+            report.tenant.tenant?.cause !== undefined);
+    const failed = !nodeOk || !checks.docker.ok || checks.compose?.ok === false || broken;
     if (options.json) {
         log(JSON.stringify(report, null, 2));
         return failed ? 1 : 0;
@@ -61,41 +61,41 @@ export async function doctorStack(options) {
         ["docker", line(checks.docker)],
         ["compose", line(checks.compose)],
     ];
-    const stack = report.stack;
-    if (report.noStack)
-        rows.push(["stack", `- ${report.noStack}`]);
-    if (stack) {
+    const local = report.tenant;
+    if (report.noTenant)
+        rows.push(["tenant", `- ${report.noTenant}`]);
+    if (local) {
         rows.push([
-            "stack",
-            stack.state === "absent"
-                ? `- ${stack.name} not created under ${stack.home}: run nylorun up`
-                : stack.state === "stopped"
-                    ? `- ${stack.name} stopped (Compose project ${stack.project}): run nylorun up`
-                    : stack.runtime.healthy
-                        ? `✓ ${stack.name} running (Compose project ${stack.project})`
-                        : `✗ ${stack.name} running, but the Runtime does not answer: see nylorun status and nylorun logs runtime`,
+            "tenant",
+            local.state === "absent"
+                ? `- ${local.name} not created under ${local.home}: run nylorun up`
+                : local.state === "stopped"
+                    ? `- ${local.name} stopped (Compose project ${local.project}): run nylorun up`
+                    : local.runtime.healthy
+                        ? `✓ ${local.name} running (Compose project ${local.project})`
+                        : `✗ ${local.name} running, but the Runtime does not answer: see nylorun status and nylorun logs runtime`,
         ]);
-        if (stack.state === "running") {
+        if (local.state === "running") {
             rows.push([
                 "runtime",
-                stack.runtime.healthy
-                    ? `✓ ${stack.runtime.url ?? "?"} · ${stack.runtime.version ?? "?"}`
-                    : `✗ ${stack.runtime.url ?? "?"} not answering`,
+                local.runtime.healthy
+                    ? `✓ ${local.runtime.url ?? "?"} · ${local.runtime.version ?? "?"}`
+                    : `✗ ${local.runtime.url ?? "?"} not answering`,
             ]);
             rows.push([
                 "gateway",
-                stack.gateway.healthy
-                    ? `✓ ${stack.gateway.state} · combined packing (runtime: core,loop; gateway: gates)`
-                    : `✗ ${stack.gateway.state}: model calls fail; see nylorun logs gateway`,
+                local.gateway.healthy
+                    ? `✓ ${local.gateway.state} · combined packing (runtime: core,loop; gateway: gates)`
+                    : `✗ ${local.gateway.state}: model calls fail; see nylorun logs gateway`,
             ]);
-            if (stack.tenant)
+            if (local.tenant)
                 rows.push([
-                    "tenant",
-                    stack.tenant.state === "open"
-                        ? `✓ ${stack.tenant.id ?? "?"} open`
-                        : `✗ ${stack.tenant.id ?? "?"} unavailable${stack.tenant.cause ? `: ${stack.tenant.cause.code}: ${stack.tenant.cause.repair}` : " (opening)"}`,
+                    "tenant id",
+                    local.tenant.state === "open"
+                        ? `✓ ${local.tenant.id ?? "?"} open`
+                        : `✗ ${local.tenant.id ?? "?"} unavailable${local.tenant.cause ? `: ${local.tenant.cause.code}: ${local.tenant.cause.repair}` : " (opening)"}`,
                 ]);
-            rows.push(["studio", `${stack.studio.url ?? "?"} · ${stack.studio.state}`]);
+            rows.push(["studio", `${local.studio.url ?? "?"} · ${local.studio.state}`]);
         }
     }
     const width = Math.max(...rows.map(([key]) => key.length)) + 2;

package/dist/home.d.ts

@@ -1,5 +1,5 @@
 /**
- * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. The stack
+ * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. Compose
  * bind-mounts it into the Runtime and Studio containers, and `@nylorun/admin`
  * reads `host.json` and the admin key from it.
  */

package/dist/home.js

@@ -1,7 +1,7 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 /**
- * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. The stack
+ * The Host root: an explicit home, `NYLORUN_HOME`, or `~/.nylorun`. Compose
  * bind-mounts it into the Runtime and Studio containers, and `@nylorun/admin`
  * reads `host.json` and the admin key from it.
  */

package/dist/project/derived-key.d.ts

@@ -1,7 +1,7 @@
-/** The derived principal a Project uses; the stack's Runtime registers it on its Tenant. */
+/** The derived principal a Project uses; the local Runtime registers it on its Tenant. */
 export declare const PROJECT_PRINCIPAL_ID = "project";
 /**
- * Key of a derived principal on the stack's Tenant, from the admin key. A copy of
+ * Key of a derived principal on the local Tenant, from the admin key. A copy of
  * `deriveTenantKey` in `@nylorun/admin` (nylorun depends on `@nylorun/core` only); both are
  * tested against the same fixed vector.
  */

package/dist/project/derived-key.js

@@ -1,8 +1,8 @@
 import { createHmac } from "node:crypto";
-/** The derived principal a Project uses; the stack's Runtime registers it on its Tenant. */
+/** The derived principal a Project uses; the local Runtime registers it on its Tenant. */
 export const PROJECT_PRINCIPAL_ID = "project";
 /**
- * Key of a derived principal on the stack's Tenant, from the admin key. A copy of
+ * Key of a derived principal on the local Tenant, from the admin key. A copy of
  * `deriveTenantKey` in `@nylorun/admin` (nylorun depends on `@nylorun/core` only); both are
  * tested against the same fixed vector.
  */