@uknows/setup 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @uknows/setup
 
-Add standard OpenTelemetry to your app, so it sends traces to UKNOWS.
+Add standard OpenTelemetry to your app, so it sends traces and logs to UKNOWS.
 
 Run it in the root folder of your repo:
 
@@ -9,24 +9,34 @@ npx @uknows/setup
 ```
 
 1. It finds each service in your repo: its language, its framework, its Dockerfile or start command, and where it runs.
-2. It shows the plan: the diff of every file it will change and the packages it will add. Nothing changes yet.
-3. You approve once. Press Enter, or type n to stop.
-4. It makes the change with your own files and your own package manager.
-5. It asks for your key and checks it: UKNOWS says which workspace and environment the key sends to, and the tool sends 1 test span. The key does not show on the screen and the tool never writes it to a file.
+2. It opens your browser. You sign in to UKNOWS and pick the workspace and the environment. Check that the browser shows the same code as the terminal. Your key then comes to the tool by itself: you never create, copy or paste it. The tool checks the key: UKNOWS says which workspace and environment the key sends to, and the tool sends 1 test span. A new key can take up to 2 minutes to reach the data intake of UKNOWS. The tool waits for it.
+3. It shows the whole plan: each file it changes and how many lines, how the agent stays up to date and why, where it stores your key (the app, the resource group and the subscription, a GitHub secret or a Kubernetes secret), the deploy file that would remove the key on the next deploy, the branch and the pull request, and the link where you watch your app connect. To show this, it reads your Azure subscriptions, your GitHub repo or your kubectl contexts. Nothing changes yet.
+4. It asks 1 question: `Do all of this? (Y/n)`. Type d to see every line that changes first. Press Enter to go ahead, or type n to stop.
+5. It does every step and shows 1 line for each, done or failed: it changes the files with your own package manager, stores the key (az, gh and kubectl read it from a pipe, never from a file or a command line), adds the key to the deploy file, and creates a branch with 1 commit of exactly the files it changed, pushes it and opens a pull request. On GitHub, the commit goes up through the GitHub API, so GitHub signs it and a branch rule that requires signed commits passes.
+6. The last line says what is left: merge the pull request and deploy as usual. It ends with the link to the page where you watch your app connect, and the tool opens it in your browser.
 
-Then commit, open a pull request and deploy as usual. `npx @uknows/setup remove` undoes the change.
+While the tool waits for your sign-in, press Enter to open the browser again, p to paste a key instead, or Ctrl+C to stop. Over ssh, or on a computer with no browser, open the link that it prints on any device. If the sign-in is cancelled in the browser or the link expires, it asks if you want to try again or paste a key. With `--paste-key`, it asks for the key instead of opening the browser. The key does not show on the screen, and the tool never writes it to a file in your repo.
 
-Full docs: https://uknows.defacloud.my/docs
+If a step cannot be done, for example `az` is not signed in, the plan says why, and the tool prints that step for you at the end. If the tool did not store your key, the last line says so: store the key before you merge, with `npx @uknows/setup key` or the key steps that the tool printed. If your branch has commits that are not on origin yet, the tool creates the branch and the commit but does not push, so your own commits never go out with the 1 yes. It prints the push command. `npx @uknows/setup remove` undoes the change.
+
+With `--step-by-step`, the tool changes the files first, then asks before each of the other steps, one at a time.
+
+The sign-in and the questions come only in a terminal. With `--yes` or `--json`, in a pipeline or without a terminal, the tool signs in to nothing, asks nothing, stores no key and opens no pull request. It prints the steps for you instead.
+
+Run it once on your computer, not in your pipeline. Your pipeline only builds and deploys the change, and sets your key on your app. See "CI/CD and pipelines" below.
+
+Full docs: https://uknows.my/docs
 
 ## What it supports
 
 | Stack | What setup does |
 |---|---|
-| Node.js (CommonJS and ES modules) | Adds the OpenTelemetry packages with npm, pnpm or yarn, loads them with `NODE_OPTIONS`, adds the 5 settings. |
-| Python | Adds the packages to `requirements.txt` or `pyproject.toml`, starts the app with `opentelemetry-instrument`, adds the 5 settings. |
-| Java | Adds the pinned OpenTelemetry Java agent to the Dockerfile (Docker checks its checksum), loads it with `JAVA_TOOL_OPTIONS`, adds the 5 settings. |
-| .NET | Adds `OpenTelemetry.AutoInstrumentation` to the project file, starts the app with `instrument.sh`, adds the 5 settings. |
-| Go, PHP, Ruby | Adds the 5 settings, then prints the code steps for you to do. |
+| Node.js (CommonJS and ES modules) | Adds the OpenTelemetry packages with npm, pnpm or yarn, adds the start file `uknows-otel.cjs` and loads it with `NODE_OPTIONS` or the start script, adds the 5 settings. |
+| Python | Adds the packages to `requirements.txt` or `pyproject.toml`, refreshes `uv.lock` or `poetry.lock` with your own uv or Poetry, starts the app with `opentelemetry-instrument`, adds the 5 settings. In a Dockerfile, it also adds the UKNOWS log bridge, so the logs go to UKNOWS and the app prints exactly what it printed before. |
+| Java (also Keycloak images) | Copies the OpenTelemetry Java agent from its image, pinned by digest, into the Dockerfile, loads it with `JAVA_TOOL_OPTIONS`, adds the 5 settings. |
+| .NET | Adds `OpenTelemetry.AutoInstrumentation` to the project file, refreshes `packages.lock.json` with `dotnet restore`, starts the app with `instrument.sh`, adds the 5 settings. |
+| Go, PHP, Ruby | Adds the 5 settings, then prints the code steps for you to do. For Go 1.23, 1.24 and 1.25, the `go get` lines name the OpenTelemetry versions for that Go. |
+| Azure Functions (Node.js v4 model, Python v2 model, .NET isolated) | If the function app does not send to Application Insights, adds 1 line to `host.json`. If it does, or setup cannot tell, adds small UKNOWS hooks to the code of the app instead, so Application Insights stays exactly as it is. The settings and the key go on the function app as app settings. |
 | Already uses OpenTelemetry | Adds only the settings. Keeps a Collector address and shows what to change. |
 
 | Where it runs | Found from |
@@ -35,40 +45,61 @@ Full docs: https://uknows.defacloud.my/docs
 | Kubernetes (AKS, EKS, GKE, Alibaba ACK) | Kubernetes manifests, Helm charts, kubectl and helm deploy steps, Alibaba ACK in Terraform |
 | Azure Container Apps | Terraform, Bicep, `az containerapp`, the deploy action, `azure.yaml` |
 | Azure App Service | Terraform, Bicep, `az webapp`, the deploy action, `azure.yaml` |
+| Azure Functions | Terraform, Bicep, `az functionapp`, the deploy action, `azure.yaml`, `host.json` |
 | AWS ECS and Fargate | Terraform, CloudFormation, task definition files, `aws ecs`, the deploy action, Copilot |
 | Alibaba SAE | Terraform, `aliyun sae`, SAE addresses |
 
-For each place it finds, it prints the steps to set your key once as a secret there.
+For each place it finds, it prints the steps to set your key once as a secret there, or in a terminal asks to do them for you. Then it checks your deploy files, so the next deploy keeps the key: `--replace-env-vars`, the `environmentVariables` or `yamlConfigPath` of the Container Apps deploy action, Bicep and Terraform templates, App Service slots, ECS task definition files, Kubernetes and GitHub Actions. Each check names the file and line.
+
+For a container app, setup also adds `OTEL_RESOURCE_ATTRIBUTES` with the Azure resource id of the app to the command that deploys it, so UKNOWS links the data to that exact app. It does this only when the deploy command names the subscription, the resource group and the app, and it never changes a value that you set. For an Azure VM, the key steps end with Mark each deploy: a step for the end of each deploy that sends 1 log record with the service name and the resource id of the VM, so UKNOWS knows when a deploy happened.
 
 ## What it changes
 
 - **Packages.** It adds the upstream OpenTelemetry packages for your stack:
   - Node.js: `@opentelemetry/api` and `@opentelemetry/auto-instrumentations-node`, with npm, pnpm or yarn.
-  - Python: `opentelemetry-distro`, the OTLP exporter and the packages for your libraries, in your requirements file or `pyproject.toml`.
-  - .NET: `OpenTelemetry.AutoInstrumentation` in your project file.
-  - Java: the OpenTelemetry Java agent, added to your Dockerfile with a pinned checksum.
-- **Startup.** It loads OpenTelemetry when your app starts, in your Dockerfile or start script. New Dockerfile lines go after your last `RUN`, so build steps never load OpenTelemetry. Lines you already have, such as `NODE_OPTIONS`, stay as they are. For Python, it changes the start command only when your image installs the file that it changed.
-- **Settings.** It adds 5 settings where your app keeps settings: your Dockerfile, your Kubernetes manifest or `otel.env`.
+  - Python: `opentelemetry-distro`, the OTLP exporter and the packages for your libraries, in your requirements file or `pyproject.toml`. A requirements file gets exact versions that fit your app: for example, `protobuf<5` gets OpenTelemetry 1.27.0, and the plan says why. A uv or Poetry project gets lower limits, and the tool runs `uv lock` (in the workspace root) or `poetry lock` on your computer, so your own resolver picks the versions. Your uv must be the version that your project or your image asks for.
+  - .NET: `OpenTelemetry.AutoInstrumentation` in your project file, plus `OpenTelemetry.Instrumentation.StackExchangeRedis` when your app uses StackExchange.Redis, also through a package such as NRedisStack. With `packages.lock.json`, the tool runs `dotnet restore --force-evaluate` with the `-r` of your Dockerfile. It needs a .NET SDK for your target framework on your computer.
+  - Java: the OpenTelemetry Java agent, copied into your image from the OpenTelemetry image, pinned by its digest. It needs no BuildKit.
+  - Azure Functions with the UKNOWS hooks: the OpenTelemetry packages of the hooks, at the versions that UKNOWS tested. If your app uses another version of the Functions library, the plan says so and asks you to check UKNOWS after the deploy.
+- **Lockfiles.** The tool records the lockfile that uv, Poetry or dotnet rewrites, so `remove` gives it back byte for byte without running the tool again. If the resolver finds no versions that fit, or the lockfile format changes, the tool puts every file back and says why.
+- **Startup.** It loads OpenTelemetry when your app starts, in your Dockerfile or start script. New Dockerfile lines go after your last `RUN`, so build steps never load OpenTelemetry. Lines you already have, such as `NODE_OPTIONS`, stay as they are.
+  - Node.js: it adds `uknows-otel.cjs` next to `package.json`. The file starts OpenTelemetry. On SIGTERM it sends the last data, then stops the app, also as PID 1 in a container. An app with its own SIGTERM handler keeps it. In a Dockerfile, a `COPY` line puts the file in the `WORKDIR` of the final stage. If the tool cannot tell the build context or the `WORKDIR`, or `.dockerignore` leaves the file out, it loads the OpenTelemetry register line instead and tells you why. For Python, it changes the start command only when your image installs the file that it changed. With `uv run` or `poetry run`, `opentelemetry-instrument` goes after `run` and its options. A `Procfile` never changes: the tool prints its new line as a step.
+  - Azure Functions: 1 line in `host.json`, `"telemetryMode": "OpenTelemetry"`, when the function app does not send to Application Insights. Otherwise the UKNOWS hooks: `uknows-otel.cjs` for Node.js, loaded through `"main"` in `package.json`; `uknows_otel.py` and 2 lines in `function_app.py` for Python; `UknowsOpenTelemetry.cs` and 2 lines in `Program.cs` for .NET. A Python function app also needs the app setting `PYTHON_ENABLE_WORKER_EXTENSIONS=1`, which setup lists with the other app settings. If the hooks are needed but cannot apply, for example to the Node.js v3 model or the .NET in-process model, setup changes nothing for that app and says why. `--functions-opentelemetry` puts the line in `host.json` instead of the hooks.
+- **Logs.** The setting `OTEL_LOGS_EXPORTER=otlp` sends the logs of your app to UKNOWS. A log line written during a request carries the trace id of that request.
+  - Python: the OpenTelemetry logging handler stays off the root logger (`OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false`), and the UKNOWS log bridge sends the log records instead. The bridge is a small folder, `uknows-otel`, that your image copies. Your app prints exactly what it printed before. A Python app that does not start with `opentelemetry-instrument` in its image sends traces only.
+  - .NET: `OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE=true`, so a log line keeps its values.
+- **Settings.** It adds 5 settings where your app keeps settings: your Dockerfile, your Kubernetes manifest, or `otel.env` when your repo has it or a file in your repo loads it (a systemd `EnvironmentFile=`, a Compose `env_file:`, `--env-file` or `. ./otel.env`). Otherwise it adds no file and prints the settings in the form of your platform, as a step for you.
   - `OTEL_SERVICE_NAME`
   - `OTEL_EXPORTER_OTLP_ENDPOINT`
   - `OTEL_EXPORTER_OTLP_PROTOCOL`
   - `OTEL_METRICS_EXPORTER`
   - `OTEL_LOGS_EXPORTER`
+
+  Some stacks get 1 or 2 more, and the plan lists them: for example, the resource detectors that send the host name of a Node.js or Python app, and the log settings of .NET above.
+- **Updates.** Setup keeps the UKNOWS agent up to date by itself. The plan and the pull request say which way it picked and why:
+  1. **The agent channel**, for Java, .NET and Node.js apps that build from a Dockerfile: 1 `COPY` line that takes the UKNOWS agent from the agent image of the stable channel at each build, and the settings that start it. Packages, lockfiles and the start command stay as they are, and a new agent reaches the app at its next build, so no update pull request is needed. If the agent files are missing or damaged, the app starts without the agent. The agent images are in `registry.uknows.my/uknows`, and your build pulls them without signing in, so a firewall in front of your builds must let them reach `registry.uknows.my` on port 443.
+  2. **Renovate**, for the other apps, when your repo uses Renovate already: a Renovate config file, or a `"renovate"` key in `package.json`. Setup never changes your config. It prints the rule to add for the UKNOWS and OpenTelemetry packages.
+  3. **Dependabot**, on GitHub, when your repo does not use Renovate: `.github/dependabot.yml` and the workflow `.github/workflows/uknows-updates.yml`. Dependabot proposes the OpenTelemetry updates, and the workflow merges them when the checks that your branch rules require pass, then starts your deploy.
+  4. On GitLab, Azure DevOps or Bitbucket, when your repo does not use Renovate: `renovate.json`, and 1 step for you: install the free Mend Renovate app for the repository. Renovate then proposes the UKNOWS and OpenTelemetry updates in 1 pull request, 3 days after each release, and merges it when your checks pass.
+
+  Azure Functions apps get no update bot: the UKNOWS hooks stay on the versions that UKNOWS tested. A repo with no `origin` remote gets none either, and the plan says how to add one. `--update-bot renovate`, `--update-bot dependabot`, `--update-bot none` and `--channel` choose instead of setup, and a rerun keeps the choice. Choosing never stops setup.
 - **A record.** It writes `.uknows/setup.json`, so `remove` can undo exactly what it changed. This file has no secrets. Commit it.
 
 For Go, PHP and Ruby, it adds the settings and prints the steps to do by hand.
 
-If your app already uses OpenTelemetry, it adds only the settings. If your app sends data to another address, such as an OpenTelemetry Collector, it keeps that address and its settings and shows you what to change. If your app uses another APM agent, such as Datadog or New Relic, it stops and explains your options.
+If your app already uses OpenTelemetry, it adds only the settings. If your app sends data to another address, such as an OpenTelemetry Collector, it keeps that address and its settings and shows you what to change. If your app uses Azure Monitor, it keeps it and adds UKNOWS beside it. If your app already uses another APM agent, it stops and explains your options.
 
 A frontend, such as a React app that nginx serves, gets no change. UKNOWS traces server apps.
 
 ## Your key
 
-Your key goes in `OTEL_EXPORTER_OTLP_HEADERS`. Set it once for each environment as a secret on your platform. After setup, the tool prints the steps for the platform it found in your repo.
+Your key goes in `OTEL_EXPORTER_OTLP_HEADERS`. Set it once for each environment as a secret on your platform. In a terminal, setup stores the key of the environment that you picked when you signed in, or prints the steps for the platform it found in your repo. If `OTEL_EXPORTER_OTLP_HEADERS` is set in your terminal, setup uses that key instead of signing you in, and the plan names its workspace and environment.
+
+For another environment, for example Production, run `npx @uknows/setup key` in the repo. It signs you in again, so you pick that environment, then checks the key and asks to store it in the same way. With `--paste-key`, it asks you to paste that key instead. It changes no file.
 
 Never put the key in a file in your repo.
 
-Right after setup, the tool asks for your key and checks it. To check it again later, run these 3 lines in bash. Paste your key when it asks. The key does not show on the screen and does not go in your shell history.
+The tool checks your key as soon as it gets it. To check it again later, run these 3 lines in bash. Paste your key when it asks. The key does not show on the screen and does not go in your shell history.
 
 ```sh
 read -rsp 'Paste your UKNOWS key: ' UKNOWS_KEY; echo
@@ -76,12 +107,13 @@ export OTEL_EXPORTER_OTLP_HEADERS="x-uknows-key=$UKNOWS_KEY"
 npx @uknows/setup check
 ```
 
-`check` asks UKNOWS which workspace and environment the key sends to, then sends 1 test span. A key that UKNOWS refuses gets its reason: not known, revoked, or a paused workspace. Apart from your package manager, the check is the only part of the tool that uses the network. Setup runs your package manager with install scripts turned off, so no code from your project or its packages runs. With a lockfile, npm and pnpm change only `package.json` and the lockfile.
+`check` asks UKNOWS which workspace and environment the key sends to, then sends 1 test span. A key that UKNOWS refuses gets its reason: not known, revoked, or a paused workspace. Apart from your package manager, the tool uses the network for the sign-in, the check and the steps after it. In a terminal, it reads your Azure subscriptions, your GitHub repo or your kubectl contexts to show the plan. It changes nothing there until you say yes. Setup runs your package manager with install scripts turned off, so no install script of your project or its packages runs. uv lock and dotnet restore can run your own project's build code to read its metadata. With a lockfile, npm and pnpm change only `package.json` and the lockfile.
 
 ## Commands and options
 
 ```text
 npx @uknows/setup [setup] [options]   Find your app, show the plan, then apply it.
+npx @uknows/setup key [--path <dir>]  Sign in, check and store the key of another environment.
 npx @uknows/setup remove [options]    Undo what setup changed.
 npx @uknows/setup check [--json]      Check your key and send 1 test span.
 ```
@@ -89,10 +121,16 @@ npx @uknows/setup check [--json]      Check your key and send 1 test span.
 | Option | What it does |
 |---|---|
 | `--dry-run` | Show the plan. Change nothing. |
-| `--yes`, `-y` | Apply without asking. It never asks any question and does not check the key, so it is safe in scripts. |
+| `--yes`, `-y` | Apply without asking. It never asks any question and never signs in. In a terminal with `OTEL_EXPORTER_OTLP_HEADERS` set, it checks that key. |
+| `--step-by-step` | Ask before each step, instead of 1 question for the whole plan. The files change first. |
+| `--paste-key` | Paste your key instead of signing in to UKNOWS in your browser. Also works with `key`. |
+| `--allow-ci` | Apply in a pipeline. Use it only for a bot or an AI agent that opens a pull request. |
 | `--path <folder>` | The folder to set up. The default is the current folder. |
 | `--all` | Set up every service folder in a monorepo. Each one gets its own `OTEL_SERVICE_NAME`. |
 | `--service-name <name>` | The name of the service in UKNOWS. Use lowercase letters, digits and `-`. |
+| `--channel <name>` | Java, .NET and Node.js apps with a Dockerfile: copy the UKNOWS agent from the agent image of a channel, `stable` or `early`, at each build. |
+| `--update-bot <name>` | `renovate`, `dependabot` or `none`: how the OpenTelemetry packages of your app stay up to date. Dependabot works on GitHub only. Without it, setup picks, as "Updates" says. |
+| `--functions-opentelemetry` | Azure Functions apps: turn on OpenTelemetry in `host.json` instead of adding the UKNOWS hooks. Application Insights then names each request by its route instead of the name of the function. |
 | `--json` | Print a JSON report. Without `--yes`, setup only plans. |
 | `--force` | Run even when the repo has changes that are not committed. With `remove`, delete the record even when some changes could not be undone. |
 | `--check` | The same as the `check` command. |
@@ -101,14 +139,40 @@ Setup stops when your repo has changes that are not committed, so you can review
 
 With `--path`, setup still reads the deploy files at the top of the git repo, such as `k8s/` and `.github/workflows/`, to find where your app runs. If the folder is part of a JavaScript workspace, or its .NET package versions are set in a file above it, setup changes nothing and asks you to run it from the repo root. There, pick the service from the list, or use `--all`.
 
+## CI/CD and pipelines
+
+Run setup once, on your computer, in your repo. Do not run it in your pipeline.
+
+1. Run `npx @uknows/setup` in your repo. Review the diff. Commit the change and open a pull request.
+2. Your pipeline builds and deploys the change as usual. It needs no UKNOWS step to build.
+3. Store your key in the secret store of your pipeline, once for each environment.
+4. In your deploy job, check that the secret is not empty. Set the key on your app before the deploy that uses it.
+5. If your deploy replaces all environment variables, add the key to that list. Otherwise each deploy removes the key.
+
+Setup and remove stop with exit code 2 when they run in a pipeline. A run counts as a pipeline when `CI` (not `0` or `false`), `GITHUB_ACTIONS`, `TF_BUILD`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI`, `JENKINS_URL`, `TEAMCITY_VERSION`, `BITBUCKET_BUILD_NUMBER` or `CODEBUILD_BUILD_ID` is set. `--dry-run`, `--json` without `--yes`, `check`, `--help` and `--version` still work there.
+
+To check in a pipeline that a repo is set up, run this step. It changes nothing, and it fails unless the repo is set up:
+
+```bash
+npx @uknows/setup --dry-run --json | jq -e '.status == "nothing-to-change" and .exitCode == 0'
+```
+
+A repo is set up when `"status"` is `"nothing-to-change"` and `"exitCode"` is `0`. That needs a commit with `.uknows/setup.json`, which lists every service, or a repo with no step left. Steps that the repo cannot show, such as the settings on your platform, are then listed in `manual[]` but do not change the exit code. In a monorepo, the check plans the services that `.uknows/setup.json` lists, so it needs no `--all`. Other statuses mean that the repo is not set up yet: `"planned"` (setup has changes to make), `"needs-steps"` (exit code 3: setup can change nothing, and the listed steps are yours, such as installing uv), and `"needs-selection"` (exit code 2: pick the services with `--all` or `--path`).
+
 ## Exit codes
 
-| Code | Meaning |
-|---|---|
-| 0 | Done, or nothing to do. |
-| 1 | Stopped or failed. Nothing changed. For example, another APM agent, a dirty repo, a key in a file that setup would change, or a package manager error. |
-| 2 | Usage error, or you need to pick a service. In a script, pass `--yes`, and `--all` or `--path` for a monorepo. |
-| 3 | You need to do 1 or more steps by hand. The tool prints them. |
+The exit code describes your repo. Setting your key on your platform, merging the pull request and deploying never change it. In a terminal, a key that UKNOWS refuses ends setup with exit code 1 before anything changes. With `--step-by-step`, the key comes after the files, so the changes to your repo stay. Ctrl+C while setup waits for your sign-in stops it with exit code 130, and nothing changes.
+
+| Code | setup | remove | check |
+|---|---|---|---|
+| 0 | Applied, already set up, or a dry run with no required step. Only the key steps on your platform are left. A frontend-only repo also gets 0. A repo that setup set up gets 0 on the next run, also when steps that the repo cannot show are listed. | Removed, or nothing to remove. | The key works and UKNOWS accepted the test span. |
+| 1 | Stopped or failed, and nothing changed. For example, a dirty repo, a key in a file, another APM agent, a package manager error, or no app found. In a terminal, also a key that UKNOWS refuses. | Failed. | Refused, or a network error. |
+| 2 | Needs your input, and nothing changed. For example, a usage error, a service to pick, no terminal and no `--yes`, or a pipeline without `--allow-ci`. | The same. | No key. |
+| 3 | Applied or planned, but you must do 1 or more steps in your repo before traces flow. The tool prints them. With nothing to change and no `.uknows/setup.json` yet, the status is `"needs-steps"`. | Partial. Some changes are left. | |
+
+`key` exits 0 when it stored the key or printed its steps, 1 when the folder is not set up or UKNOWS refuses the key or cannot be reached, and 2 without a terminal or without a key.
+
+In `--json`, `ci` says if the run counts as a pipeline, `services[].mode` says how the tool sets up each service, and `manual[].required` says if a step counts toward exit code 3. Advice never does.
 
 ## Undo
 
@@ -124,18 +188,21 @@ Node.js 18 or later, on macOS, Linux or Windows. The tool has no dependencies.
 
 ## Test addresses
 
-Setup writes `OTEL_EXPORTER_OTLP_ENDPOINT` with the UKNOWS ingest address, and check asks the UKNOWS site about your key. To use a test copy of UKNOWS, set both addresses. The test copy's `/docs` page gives the command with them:
+Setup writes `OTEL_EXPORTER_OTLP_ENDPOINT` with the UKNOWS ingest address, and check asks the UKNOWS site about your key. The last line links to the UKNOWS app, where you watch your app connect. To use a test copy of UKNOWS, set its addresses. The test copy's `/docs` page gives the command with them:
 
 ```sh
-UKNOWS_SITE_URL=https://uknows-test.example.com UKNOWS_INGEST_ENDPOINT=https://ingest-test.example.com/otlp npx @uknows/setup
+UKNOWS_SITE_URL=https://uknows-test.example.com UKNOWS_APP_URL=https://app-test.example.com UKNOWS_INGEST_ENDPOINT=https://ingest-test.example.com/otlp npx @uknows/setup
 ```
 
-Both must be https addresses. On your own computer, `http://127.0.0.1` and `http://localhost` work too. With only `UKNOWS_INGEST_ENDPOINT`, check sends the test span but does not ask which workspace the key sends to.
+They must be https addresses. On your own computer, `http://127.0.0.1` and `http://localhost` work too. With only `UKNOWS_INGEST_ENDPOINT`, check sends the test span but does not ask which workspace the key sends to. Setup signs you in at the app address. Without `UKNOWS_APP_URL`, a run with a test address cannot sign you in: it tells you to set `UKNOWS_APP_URL`, asks you to paste the key, prints no link to the app and opens no browser. If the test copy cannot make a sign-in link, setup says so and asks you to paste the key.
+
+`UKNOWS_AGENT_REGISTRY` sets another store of the UKNOWS agent images for the agent channel, as a registry and path, for example `registry.example.com/uknows`.
 
 To build a package for a test environment, bake its addresses in, the same build settings that `/docs` uses. Do not commit the result:
 
 ```sh
 VITE_UKNOWS_SITE_URL=https://uknows-test.example.com \
+VITE_UKNOWS_APP_URL=https://app-test.example.com \
 VITE_UKNOWS_INGEST_HOST=ingest-test.example.com \
 node tools/sync-contract.mjs
 npm pack