@uknows/setup 0.1.0 → 0.2.0

package/lib/engine.mjs

@@ -2,48 +2,229 @@
  * The setup and remove flows. Everything that reads the repo, runs a
  * program or asks the user comes in through deps, so tests can use fakes.
  * Each flow returns {code, report}: the exit code and the --json report.
+ *
+ * Exit codes describe the repo, never the key (README "Exit codes"):
+ *   0 applied, already set up, or nothing to do. Only the key steps on the platform are left. A repo whose manifest
+ *     lists every service and that has nothing to change is set up (status nothing-to-change), also with steps left
+ *     that the repo cannot show. With no manifest and only required steps, the status is needs-steps (exit 3).
+ *   1 stopped or failed, and nothing changed: dirty tree, key in a file, other APM, no app found, a failed command.
+ *   2 needs input, and nothing changed: usage, a service to pick, no terminal and no --yes, a pipeline without --allow-ci.
+ *   3 applied or planned, but required repo steps remain. Only blocks with required !== false count.
+ *
+ * Each service gets a mode before anything is planned (existing.mjs classify): standard, otel, azure-monitor
+ * or stop. With --channel (or a channel recorded in .uknows/setup.json), a standard Java, .NET or Node.js service
+ * with a Dockerfile gets the channel mode instead: the agent comes from the UKNOWS agent image (stacks/channel.mjs).
+ * A stop in any service stops the whole run. Lock refreshes (uv lock, poetry lock, dotnet restore
+ * --force-evaluate) are commands of kind 'lock': the manifest records the lockfile they rewrite as an ordinary text
+ * change, so remove gives back every byte without running the tool again. They run after the edits, and any failure
+ * puts every file back: a resolver that finds no solution, a lockfile format line that changed (keep), or a restore
+ * whose obj/project.assets.json needs a package the plan did not add (verify).
  */
-import { spawn as spawnChild } from 'node:child_process'
+import { spawn as spawnChild, spawnSync } from 'node:child_process'
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
 import { dirname, sep } from 'node:path'
-import { runCheck } from './check.mjs'
-import { CLI, EXAMPLE_SERVICE, INGEST_ENDPOINT, SECRET } from './contract.mjs'
+import { PUT, automates, changedFiles, connectUrl, deployEdits, deployFilesInTerminal, githubSecret, githubStepBlock, githubStepLines, k8sLoadsKey, keyStepsInTerminal,
+  keyTargets, lastLine, notCommitted, openBrowser, openChecks, pickApp, planKeyStores, plannedQuestions, prBody, prFacts, prPlan, prRun, pullRequest, runProgram,
+  storeName, storeRows, watchLine } from './automate.mjs'
+import { NEW_KEY, parseHeaders, request, runCheck } from './check.mjs'
+import { ciVariable } from './ci.mjs'
+import { PREDICT, cloudIdFacts, cloudIdLookups, cloudIdPlan, cloudIdSpots } from './cloudid.mjs'
+import { APP_INSIGHTS_SETTINGS, appInsightsSigns, functionAppSettingNames, hostJsonEdit } from './stacks/functions.mjs'
+import { APP_SERVICE_CODE, CI_CD, CLI, FUNCTIONS, HOSTS, INGEST_ENDPOINT, RESOLVE, SECRET, SETUP_NEXT, SETUP_STATUS, STACKS, keyCheckLine, settingsSnippet } from './contract.mjs'
 import { detect } from './detect.mjs'
-import { docsUrl, llmsUrl } from './endpoint.mjs'
+import { appUrl, docsUrl, llmsUrl, nextData } from './endpoint.mjs'
+import { askOnce, fileRows, printPlan as printOnePlan, step } from './plan.mjs'
+import { REAL_CLOCK, SIGN_IN, signIn } from './signin.mjs'
 import { countLines, unified } from './diff.mjs'
 import { shellWords } from './doc.mjs'
-import { explainApm, findExisting } from './existing.mjs'
-import { gitStatus } from './git.mjs'
-import { keySteps } from './hosts.mjs'
+import { classify, existingNotes, explainApm, explainStop, findExisting } from './existing.mjs'
+import { gitHost, gitIgnored, gitRemote, gitStatus } from './git.mjs'
+import { deployNames, keySteps } from './hosts.mjs'
 import { BOM, TOOL, VERSION, changeEntry, manifestPaths, manifestText, mergeManifest, readManifest, sha256, undoChange } from './manifest.mjs'
 import { hasKey, redactKey, settingsPlan } from './settings.mjs'
+import { lockedMode, verifyRestore, webProject } from './stacks/dotnet.mjs'
+import { channelMisfit } from './stacks/channel.mjs'
+import { updatesPlan } from './updates.mjs'
 import { APPLIERS } from './stacks/index.mjs'
+import { otelNotes } from './stacks/otel.mjs'
 import { UsageError, frameworkLabel, hostLabel, list, plural, stackLabel, unique } from './ui.mjs'
 import { createWorkspace, repoView } from './workspace.mjs'
 
-const DEFAULTS = { detect, findExisting, explainApm, settingsPlan, keySteps, appliers: APPLIERS, spawn: runCommand, gitStatus, createWorkspace, runCheck }
+const DEFAULTS = { detect, findExisting, classify, explainApm, explainStop, settingsPlan, keySteps, deployNames, appliers: APPLIERS, spawn: runCommand,
+  probe: probeTool, verify: verifyRestore, gitStatus, gitIgnored, gitRemote, gitHost, createWorkspace, runCheck, cli: runProgram, openUrl: openBrowser,
+  signIn, request, clock: REAL_CLOCK }
 /** The language menu, in this order, then 'Something else'. */
 const MENU = ['node', 'python', 'java', 'dotnet', 'go', 'php', 'ruby', 'otel']
-const LOCKFILES = new Set(['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock'])
+const LOCKFILES = new Set(['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock', 'uv.lock', 'poetry.lock', 'pdm.lock', 'packages.lock.json'])
+/** Local tools the plan can need, probed once before planning: name -> files in the repo that need it. */
+const TOOLS = { uv: /(?:^|\/)uv\.lock$/, poetry: /(?:^|\/)poetry\.lock$/ }
 const DIFF_LIMIT = 200
 /** On Windows, package managers run through a shell (.cmd files), so every argument must be plain. */
 const SAFE_ARG = /^[@A-Za-z0-9._/=:~+-]+$/
+/** The output of a command that the engine keeps, to say why a resolver failed. */
+const OUTPUT_LIMIT = 65536
 
 /**
- * @param {{root: string, dryRun?: boolean, yes?: boolean, all?: boolean, json?: boolean, serviceName?: string|null, force?: boolean}} opts
+ * @param {{root: string, dryRun?: boolean, yes?: boolean, all?: boolean, json?: boolean, serviceName?: string|null, force?: boolean,
+ *   allowCi?: boolean, env?: Record<string, string|undefined>, endpoint?: string}} opts
  * @param {Partial<typeof DEFAULTS> & {ui: ReturnType<typeof import('./ui.mjs').createUI>}} deps
  */
 export async function runSetup(opts, deps) {
   const d = { ...DEFAULTS, ...deps }
   const report = { schema: 1, tool: TOOL, version: VERSION, command: 'setup', status: 'failed', exitCode: 1,
-    services: [], files: [], hosts: [], keySteps: [], check: null, problems: [], next: CLI.next }
+    services: [], files: [], hosts: [], keySteps: [], check: null, problems: [], next: nextData(opts.env), ci: Boolean(ciVariable(opts.env)) }
   return guard(d.ui, report, () => setup(opts, d, report))
 }
 
-/** @param {{root: string, yes?: boolean, json?: boolean, force?: boolean}} opts */
+/**
+ * npx @uknows/setup key: paste the key of another environment (for example Production), check it, and store it on the
+ * platform of an app that setup set up, as the key steps of a setup run do. Only in a terminal. It changes no file.
+ * Exit codes: 0 stored, or its steps printed; 1 not set up yet, a refused key or a key that could not be checked;
+ * 2 no terminal (a pipeline, --json, a pipe) or no key given.
+ * @param {{root: string, env?: Record<string, string|undefined>}} opts
+ */
+export async function runKey(opts, deps) {
+  const d = { ...DEFAULTS, ...deps }
+  const report = { schema: 1, tool: TOOL, version: VERSION, command: 'key', status: 'failed', exitCode: 1, check: null, stored: [], problems: [],
+    ci: Boolean(ciVariable(opts.env)) }
+  return guard(d.ui, report, () => key(opts, d, report))
+}
+
+async function key(opts, d, report) {
+  const { ui } = d, root = opts.root, env = opts.env ?? {}
+  ui.print('UKNOWS key')
+  ui.print()
+  if (!automates({}, ui, env)) {
+    ui.print('Run npx @uknows/setup key in a terminal. It asks for your key, so it does not run in a pipeline or without a terminal. Nothing changed.')
+    return ['needs-terminal', 2]
+  }
+  const manifest = readManifest(root)
+  if (!manifest?.services.length) {
+    ui.print(`This folder is not set up yet: it has no ${CLI.manifest}. Run npx @uknows/setup first. It sets up your app and stores the key of your first environment.`)
+    return ['not-set-up', 1]
+  }
+  ui.print('This checks the key of 1 environment, for example Production, and stores it where your app runs. It changes no file in your repo.')
+  const detection = d.detect(root)
+  const repo = repoView(d.createWorkspace(root))
+  const names = d.deployNames(repo, detection.hosts)
+  const slug = d.gitRemote(root)
+  const plans = manifest.services.map((m) => ({ name: m.name, s: detection.services.find((s) => s.dir === m.dir) ?? { dir: m.dir, k8s: [] } }))
+  // Apps that keep their own metrics and logs got the traces-only settings: their key goes in the traces-only variable.
+  const tracesOnly = manifest.changes.some((c) => c.hunks.some((h) => h.after.some((l) => l.includes('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT')))
+    || (c.created && (repo.read(c.file) ?? '').includes('OTEL_EXPORTER_OTLP_TRACES_ENDPOINT')))
+  const secretName = tracesOnly ? TRACES_HEADERS : SECRET.name
+  // The key of this terminal is often the one of the first environment: a no to it goes on to the paste question.
+  const app = { name: plans.map((p) => p.name).join(', '), repo: slug ?? undefined, platform: platformOf(detection.hosts) }
+  const checked = await checkKey(ui, d, env, false, plans[0].name, { paste: true, pasteKey: opts.pasteKey, app })
+  if (checked?.stopped && checked.interrupt) { ui.print('Stopped. Nothing changed.'); return ['cancelled', 130] }
+  report.check = checked?.entry ?? null
+  const line = keyCheckLine(checkVars(env))
+  if (!checked || checked.stopped) {
+    ui.print('No key given. Nothing changed.')
+    return ['no-key', 2]
+  }
+  if (checked.notReady) {
+    ui.print(NEW_KEY.againKey)
+    return ['key-refused', 1]
+  }
+  if (report.check.status !== 'reached') {
+    ui.print(report.check.status === 'rejected' ? SETUP_NEXT.rejected : SETUP_NEXT.network)
+    ui.print(`  ${line}`)
+    ui.print('Then run npx @uknows/setup key again.')
+    return [report.check.status === 'rejected' ? 'key-refused' : 'network-error', 1]
+  }
+  const blocks = d.keySteps(detection.hosts, { view: repo, names, repo: slug, service: plans.length === 1 ? plans[0].name : undefined, secretName })
+  report.keySteps = blocks
+  const targets = keyTargets({ hosts: detection.hosts, names, view: repo, plans, repo: slug })
+  const environment = report.check.environment ?? null
+  const steps = await keyStepsInTerminal(ui, d.cli, blocks, targets, { key: bareKey(checked.headers), environment, env, root, secretName,
+    service: plans.length === 1 ? plans[0].name : null, services: plans.map((p) => p.name) })
+  report.stored = steps.stored.map((s) => s.done)
+  // The deploy files decide if the key stays: the checks that are open, the key step of a GitHub secret, and envFrom
+  // for a Kubernetes secret. key changes no file, so it prints them.
+  const rest = openChecks(blocks, { stored: steps.stored.map((s) => s.host), skipped: steps.skipped, secretName })
+  if (steps.github) rest.unshift(githubStepBlock(steps.github))
+  const k8s = steps.stored.some((s) => s.host === 'kubernetes') && !k8sLoadsKey(repo, plans)
+  if (k8s) rest.unshift(loadKeyBlock(blocks))
+  for (const block of rest) ui.block(block)
+  ui.print('Never put the key in a file in your repo.')
+  ui.print()
+  // A deploy file that drops the key (--replace-env-vars, environmentVariables) or a deployment without envFrom.
+  const drops = steps.github || k8s || deployEdits(repo, detection.hosts, plans, secretName).length > 0
+  const urls = plans.map((p) => connectUrl(p.name, environment, appUrl(env)))
+  const next = !steps.stored.length ? 'Do the steps above, then deploy as usual.'
+    : drops ? 'Your deploy files do not keep the key yet. Do the steps above, then deploy as usual.' : 'Your app gets the key when it starts again or with your next deploy.'
+  ui.print(`${next} ${watchLine(urls, environment)}`)
+  if (ui.terminal && urls[0]) d.openUrl(urls[0], env, () => ui.print(OPENING))
+  return [steps.stored.length ? 'stored' : 'steps', 0]
+}
+
+/**
+ * The app settings step of an Azure Functions app (settings.mjs), with the function app and resource group that the
+ * deploy files name. With more than 1 function app, the first one, as in the key script.
+ */
+function functionsSettingsNames(block, p, names) {
+  if (block.title !== FUNCTIONS.settings.title) return block
+  const fn = names.functions ?? { apps: [], groups: [] }
+  const group = new Set(fn.groups.map((g) => g.name)).size === 1 ? fn.groups[0] : null
+  const scriptNames = { ...(fn.apps[0] ? { app: fn.apps[0].name } : {}), ...(group ? { resourceGroup: group.name } : {}),
+    from: { ...(fn.apps[0] ? { app: fn.apps[0].where } : {}), ...(group ? { resourceGroup: group.where } : {}) } }
+  return { ...block, snippets: [settingsSnippet('azure-functions', p.settings.pairs ?? [], p.name, scriptNames)] }
+}
+
+/**
+ * How setup turns on OpenTelemetry for an Azure Functions app (stacks/functions.mjs): {route, signs, unknown,
+ * predicted}. route 'host': the line in host.json, when setup knows that the app does not send to Application Insights
+ * (a run in a terminal reads the names of the app settings of each function app that the deploy files name, and no
+ * deploy file sets the connection string), or with --functions-opentelemetry. route 'hooks': the UKNOWS worker hooks,
+ * which keep Application Insights exactly as it is, when the app sends to it or setup cannot tell. A dry run in a
+ * terminal shows the plan of a real run that finds no Application Insights (predicted). host.json that has the line
+ * already needs no decision.
+ */
+async function functionsDecision(s, it, { d, opts, ui, env, repo, detection, root }) {
+  if (!hostJsonEdit(repo.read(s.functions.hostJson)).after) return { route: 'host', signs: [] }
+  if (opts.functionsOpenTelemetry) return { route: 'host', signs: [] }
+  const signs = appInsightsSigns(s, repo, it.existing)
+  const deploys = signs.filter((x) => x.deploy)
+  if (automates(opts, ui, env)) {
+    const names = d.deployNames(repo, detection.hosts).functions ?? { apps: [], groups: [] }
+    const group = new Set(names.groups.map((g) => g.name)).size === 1 ? names.groups[0].name : null
+    const lookups = [...new Set(names.apps.map((a) => a.name))].map((app) => ({ app, group }))
+    const look = ui.progress('Looking at the app settings of your function app in Azure')
+    const facts = await functionAppSettingNames(d.cli, { root, env }, lookups)
+    look.end(null)
+    const platform = [...(facts ?? new Map())].flatMap(([app, list]) => (list ?? []).filter((n) => APP_INSIGHTS_SETTINGS.includes(n))
+      .map((n) => ({ file: `the app settings of ${app}`, what: n, deploy: false })))
+    const found = [...platform, ...deploys]
+    if (found.length) return { route: 'hooks', signs: found }
+    const known = Boolean(facts) && lookups.length > 0 && [...facts.values()].every((list) => Array.isArray(list))
+    return known ? { route: 'host', signs: [] } : { route: 'hooks', signs, unknown: true }
+  }
+  if (opts.dryRun && ui.interactive && !opts.json && !ciVariable(env) && !deploys.length) return { route: 'host', signs: [], predicted: true }
+  return deploys.length ? { route: 'hooks', signs: deploys } : { route: 'hooks', signs, unknown: true }
+}
+
+/** The platform of the app for the sign-in page: where it runs, not the pipeline that deploys it. */
+const platformOf = (hosts) => hosts.find((h) => h.id !== 'github-actions')?.id ?? hosts[0]?.id
+
+/** The step that loads a Kubernetes secret: envFrom in each deployment, from the snippets of the Kubernetes block. */
+/**
+ * True when every service of the run sends its logs to UKNOWS: the standard settings and the agent channel set
+ * OTEL_LOGS_EXPORTER=otlp. An app that keeps its own OpenTelemetry or Azure Monitor keeps its logs where they go now.
+ */
+const sendsLogs = (plans) => plans.length > 0 && plans.every((p) => p.mode === 'standard' || p.mode === 'channel')
+
+function loadKeyBlock(blocks) {
+  const k8s = blocks.find((b) => b.title === `Set your key once: ${HOSTS.find((h) => h.id === 'kubernetes').label}`)
+  return { title: 'Load the key in your deployment', lines: ['Add envFrom to each deployment, so new pods get the key. Commit this change.'],
+    snippets: (k8s?.snippets ?? []).filter((x) => /envFrom/.test(x.code) && !/kubectl/.test(x.code)) }
+}
+
+/** @param {{root: string, yes?: boolean, json?: boolean, force?: boolean, allowCi?: boolean, env?: Record<string, string|undefined>}} opts */
 export async function runRemove(opts, deps) {
   const d = { ...DEFAULTS, ...deps }
-  const report = { schema: 1, tool: TOOL, version: VERSION, command: 'remove', status: 'failed', exitCode: 1, files: [], commands: [], problems: [] }
+  const report = { schema: 1, tool: TOOL, version: VERSION, command: 'remove', status: 'failed', exitCode: 1, files: [], commands: [], problems: [],
+    ci: Boolean(ciVariable(opts.env)) }
   return guard(d.ui, report, () => remove(opts, d, report))
 }
 
@@ -91,7 +272,14 @@ async function setup(opts, d, report) {
     ui.print(`Found ${services.length} services:`)
     for (const s of services) ui.print(`  ${s.dir}: ${describe(s)}`)
     ui.print()
-    if (!opts.all) {
+    // A pipeline check (a plan with no terminal) of a repo that setup set up plans the services that it lists.
+    const listed = manifest ? services.filter((s) => manifest.services.some((m) => m.dir === s.dir)) : []
+    const planOnly = opts.dryRun || (opts.json && !opts.yes)
+    if (!opts.all && !ask && planOnly && listed.length) {
+      services = listed
+      ui.print(fillIn(SETUP_STATUS.recorded, { count: plural(listed.length, 'service'), manifest: CLI.manifest }))
+      ui.print()
+    } else if (!opts.all) {
       if (!ask) {
         report.services = services.map((s) => serviceReport(s))
         ui.print(`Pick the services to set up. Use --all to set up all of them, or --path <folder> to set up 1. Or run this in a terminal${opts.yes ? ' without --yes' : ''} to pick from a list.`)
@@ -115,9 +303,10 @@ async function setup(opts, d, report) {
     }
     services = services.filter((s) => !frontend(s))
     if (!services.length) {
+      // A frontend needs nothing from UKNOWS, so this is not a failure.
       report.services = detection.services.map((x) => serviceReport(x))
       ui.print(`Run this tool in the folder of your server app, or use --path <folder>. To set up UKNOWS by hand, see ${DOCS_URL}`)
-      return ['not-found', 3]
+      return ['nothing-to-change', 0]
     }
     ui.print()
   }
@@ -129,66 +318,149 @@ async function setup(opts, d, report) {
       ui.print(`No app found in ${where(s.dir)}.`)
       ui.print(`Run this tool in the folder of your app, or use --path <folder>. To set up UKNOWS by hand, see ${DOCS_URL}`)
       report.services = services.map((x) => serviceReport(x))
-      return ['not-found', 3]
+      return ['not-found', 1]
     }
     const pick = await ui.choose(`No app found in ${where(s.dir)}. What does your app use?`, [...MENU.map(stackLabel), 'Something else'])
     if (pick === MENU.length) {
       ui.print(`To set up UKNOWS by hand, see ${DOCS_URL}`)
       ui.print(`AI coding tools can read the same steps at ${LLMS_URL}`)
       report.services = services.map((x) => serviceReport(x))
-      return ['not-found', 3]
+      return ['not-found', 1]
     }
     ui.print()
     chosen.set(s.dir, MENU[pick])
     if (MENU[pick] !== 'otel') s.lang = MENU[pick]
   }
 
-  // Another APM agent in any service stops the whole run before anything is planned.
-  const items = services.map((s) => ({ s, name: opts.serviceName || s.name, existing: d.findExisting(s, ws) }))
-  report.services = items.map((it) => serviceReport(it.s, { name: it.name, otel: it.existing.otel, apm: it.existing.apm }))
-  const blocked = items.filter((it) => it.existing.apm.length)
+  // A mode for each service before anything is planned. A stop in any service stops the whole run.
+  const items = services.map((s) => {
+    const existing = d.findExisting(s, repo)
+    const cls = d.classify(existing, { lang: s.lang, hosts: detection.hosts })
+    const recorded = manifest?.services.find((m) => m.dir === s.dir)
+    // A service that setup already did keeps its mode: its own packages must not turn it into an otel app.
+    let mode = cls.mode === 'stop' ? 'stop' : recorded ? recorded.mode ?? (recorded.stack === 'otel' ? 'otel' : 'standard') : s.mode ?? cls.mode
+    // The agent channel: asked for in this run, recorded by an earlier one, or the default (updates.mjs, step 1) for a
+    // service that setup did not set up before. Only for a standard service that fits; never for an Azure Functions app.
+    const fallback = !recorded && !s.functions ? opts.defaultChannel ?? null : null
+    const channel = (recorded?.mode === 'channel' ? recorded.channel : null) ?? opts.channel ?? fallback
+    const misfit = channel && mode === 'standard' ? channelMisfit(s) : null
+    if (channel && mode === 'standard' && !misfit) mode = 'channel'
+    return { s, name: opts.serviceName || s.name, existing, cls, mode, channel: mode === 'channel' ? channel : null,
+      channelDefault: mode === 'channel' && channel === fallback && !opts.channel,
+      channelNote: misfit && opts.channel ? `${misfit} So ${s.dir === '.' ? 'this service' : s.dir} gets the packages instead.` : null }
+  })
+  report.services = items.map((it) => serviceReport(it.s, { name: it.name, mode: it.mode, otel: it.existing.otel, apm: it.existing.apm ?? [] }))
+  const blocked = items.filter((it) => it.mode === 'stop')
   if (blocked.length) {
-    for (const it of blocked) ui.block(d.explainApm(it.s, it.existing.apm))
+    for (const it of blocked) ui.block(it.cls.reason === 'apm' ? d.explainApm(it.s, it.existing.apm) : d.explainStop(it.s, it.existing, it.cls))
     ui.print('Nothing changed.')
     return ['refused', 1]
   }
+  const tools = probeTools(d, repo, items)
 
   // Plan each service. All edits go into 1 workspace, so each step reads the edits before it.
   const plans = []
   for (const it of items) {
     const { s } = it
-    const stack = known(s) ?? chosen.get(s.dir) ?? (it.existing.otel.length ? 'otel' : s.lang)
-    const applier = Object.prototype.hasOwnProperty.call(d.appliers, stack) ? d.appliers[stack] : null
+    const stack = known(s) ?? chosen.get(s.dir) ?? (it.mode === 'otel' ? 'otel' : s.lang)
+    // How the tool sets up this service: the classified mode, or otel for a stack picked as 'otel' from the menu.
+    const mode = stack === 'otel' ? 'otel' : it.mode
+    // An Azure Functions app (standard, or with App Insights in its code): the Functions host sends the data, or setup
+    // stands down (stacks/functions.mjs).
+    const fnApp = s.functions && (mode === 'standard' || mode === 'azure-monitor')
+    const id = fnApp ? 'functions' : mode === 'azure-monitor' ? 'azure' : mode === 'channel' ? 'channel' : stack
+    const applier = Object.prototype.hasOwnProperty.call(d.appliers, id) ? d.appliers[id] : null
     if (!applier) throw new Error(`This tool has no steps for ${stack}.`)
     report.problems.push(...s.problems)
     const ambiguous = s.problems.find((x) => x.code === 'dockerfile-ambiguous')
     if (ambiguous) {
       // Editing the wrong Dockerfile changes nothing that ships: say so, and change nothing for this service.
-      const manual = [{ title: 'Pick the Dockerfile you deploy', lines: [ambiguous.message, 'Then run npx @uknows/setup again.'] }]
-      plans.push({ ...it, stack, plan: { summary: [], edits: [], commands: [], extraSettings: [], manual, notes: [] },
-        settings: { target: null, edits: [], summary: [], manual: [], notes: [] }, manual, notes: [] })
+      const manual = [{ title: 'Pick the Dockerfile you deploy', verify: true, lines: [ambiguous.message, 'Then run npx @uknows/setup again.'] }]
+      plans.push({ ...it, stack, mode, plan: { summary: [], edits: [], commands: [], extraSettings: [], manual: manual.map(tidy), notes: [] },
+        settings: { target: null, edits: [], summary: [], manual: [], notes: [] }, manual: manual.map(tidy), notes: [] })
       continue
     }
-    if ((stack === 'node' || stack === 'python') && !s.start && !s.dockerfile && ask) {
+    // The Functions host starts a function app: no start command to ask for.
+    if ((stack === 'node' || stack === 'python') && !s.start && !s.dockerfile && !s.functions && ask) {
       const raw = await ui.ask('What command starts this app now? For example: node server.js. Press Enter to skip.')
       if (raw) s.start = { kind: 'answer', file: '', line: 0, form: 'shell', raw, argv: shellWords(raw) }
     }
-    const ctx = { ws, repo, name: it.name, detection, endpoint }
+    const functions = fnApp ? await functionsDecision(s, it, { d, opts, ui, env, repo, detection, root }) : undefined
+    const ctx = { ws, repo, name: it.name, detection, endpoint, mode, channel: it.channel, existing: it.existing, installed: it.existing.installed, tools, manifest,
+      ignored: (file) => d.gitIgnored(root, file), functions }
     const plan = applier.plan(s, ctx)
     for (const edit of plan.edits) ws.stage(edit)
     const settings = plan.stop ? { target: null, edits: [], summary: [], manual: [], notes: [] } : d.settingsPlan(s, ctx, plan.extraSettings ?? [])
     for (const edit of settings.edits) ws.stage(edit)
-    plans.push({ ...it, stack, plan, settings, manual: [...plan.manual, ...settings.manual].map(tidy),
-      notes: unique([...plan.notes, ...settings.notes].filter(Boolean)) })
+    const extra = existingNotes(it.existing, { hosts: detection.hosts, mode })
+    // otel mode: only the notes of the docs page that fit the language and what the repo uses.
+    const own = mode === 'otel' ? otelNotes(plan.notes, { lang: s.lang, existing: it.existing, tracesOnly: settings.tracesOnly, endpoint, docs: DOCS_URL }) : plan.notes
+    plans.push({ ...it, stack, mode, plan, settings, functions, manual: [...plan.manual, ...settings.manual, ...extra.advice].map(tidy),
+      notes: unique([...own, ...settings.notes, ...extra.notes, it.channelNote].filter(Boolean)) })
+  }
+  // How the agent stays up to date (updates.mjs): on by default; --update-bot and --channel choose. Each line shows with
+  // the first service that it is about (the channel's with the services on the channel, the update bot's with the
+  // services on the package route), and the pull request says which method was chosen and why.
+  let updates = { pr: [], methods: [] }
+  if (plans.length) {
+    updates = updatesPlan(plans, { ws, repo, bot: opts.updateBot ?? null, recorded: manifest?.updates ?? null, host: d.gitHost(root) })
+    for (const edit of updates.edits) ws.stage(edit)
+    const home = (names) => plans.find((p) => names.includes(p.name)) ?? plans[0]
+    for (const line of updates.summary) home(line === updates.channelLine ? updates.homes.channel : updates.homes.packages).plan.summary.push(line)
+    home(updates.homes.packages).manual.push(...updates.manual.map(tidy))
+    home(updates.homes.packages).notes.push(...updates.notes)
+  }
+  // The cloud id of each container app, in the command that deploys it (cloudid.mjs). az only reads, and only in a run
+  // in a terminal that asks (automates): never with --yes, --json or --dry-run, never in a pipeline. The run with 1 Yes
+  // reads after the key check, with the other reads (runOnce); --step-by-step reads here, before Apply. A dry run in a
+  // terminal shows the plan of a real run, as if az showed nothing in the way. Other runs change only the deploy steps
+  // that need no look in Azure.
+  const spots = cloudIdSpots(repo, detection.hosts)
+  const lookups = cloudIdLookups(spots)
+  const terminalRun = automates(opts, ui, env)
+  const dockerfiles = plans.map((p) => p.s.dockerfile).filter(Boolean)
+  const cloudLater = terminalRun && !opts.stepByStep && lookups.length > 0 && plans.length > 0 ? { dockerfiles } : null
+  let azureFacts = opts.dryRun && !opts.json && !ciVariable(env) ? PREDICT : null
+  if (terminalRun && opts.stepByStep && lookups.length > 0 && plans.length > 0) {
+    const look = ui.progress('Looking at your container apps in Azure')
+    azureFacts = await cloudIdFacts(d.cli, { root, env }, lookups)
+    look.end(null)
   }
-  report.services = plans.map((p) => serviceReport(p.s, { stack: p.stack, name: p.name, settings: p.settings.target ?? null,
+  const cloudIds = plans.length ? cloudIdPlan(repo, spots, azureFacts, { dockerfiles }) : { edits: [], summary: [] }
+  for (const edit of cloudIds.edits) ws.stage(edit)
+  // After the settings of the service: it is 1 more setting, set by the deploy.
+  if (plans.length) plans[0].settings.summary = [...plans[0].settings.summary, ...cloudIds.summary]
+  const cloudId = cloudIds.edits.length > 0
+  // App Service that deploys the code, not an image, never runs the Dockerfile: the start and the settings go on App Service.
+  const names = d.deployNames(repo, detection.hosts)
+  for (const p of plans) p.manual.push(...appServiceCode(p, names, repo).map(tidy))
+  for (const p of plans.filter((x) => x.s.functions)) p.manual = p.manual.map((b) => functionsSettingsNames(b, p, names))
+  report.services = plans.map((p) => serviceReport(p.s, { stack: p.stack, mode: p.mode, name: p.name, settings: p.settings.target ?? null,
     summary: steps(p), commands: p.plan.commands.map((c) => ({ cwd: c.cwd, argv: [c.cmd, ...c.args] })),
     manual: p.manual, notes: p.notes, otel: p.existing.otel }))
-  report.keySteps = d.keySteps(detection.hosts, { envFile: plans.some((p) => p.settings.target?.kind === 'env-file') })
-  // The docs snippets use an example service name. With 1 service, show its real name.
-  if (plans.length === 1) {
-    for (const snippet of report.keySteps.flatMap((b) => b.snippets ?? [])) snippet.code = snippet.code.split(EXAMPLE_SERVICE).join(plans[0].name)
-  }
+  // The key steps of each host, fitted to this repo: the names in its deploy files, how its apps start, the settings of
+  // this run, and the key variable of apps that keep their own metrics and logs (traces only).
+  const one = plans.length === 1 ? plans[0] : null
+  const tracesOnly = plans.length > 0 && plans.every((p) => p.settings.tracesOnly)
+  if (!tracesOnly) for (const p of plans.filter((x) => x.settings.tracesOnly)) p.notes.push(`For ${p.name}, use ${TRACES_HEADERS} instead of ${SECRET.name} in the key steps below.`)
+  const slug = d.gitRemote(root)
+  const secretName = tracesOnly ? TRACES_HEADERS : SECRET.name
+  const keyBlocks = d.keySteps(detection.hosts, {
+    view: repo, names, repo: slug, service: one?.name,
+    // How to load otel.env only when no repo file loads it. otel.env and systemd only when a service needs them.
+    envFile: plans.some((p) => p.settings.target?.kind === 'env-file' && !p.settings.target.loader),
+    otelEnv: plans.some((p) => p.settings.target?.kind === 'env-file'),
+    docker: plans.length > 0 && plans.every((p) => p.settings.target?.kind === 'dockerfile'),
+    settings: one?.settings.pairs?.length ? one.settings.pairs : null,
+    startLine: plans.some((p) => p.mode === 'standard' && START_PREFIX[p.stack]),
+    secretName,
+  })
+  // A function app where OpenTelemetry stays off (functionsDecision) gets no key: the key would only restart the app.
+  const fnPlans = plans.filter((p) => p.s.functions)
+  const fnOff = fnPlans.length > 0 && fnPlans.every((p) => p.plan.stop)
+  report.keySteps = !fnOff ? keyBlocks : fnPlans.length === plans.length ? [] : keyBlocks.filter((b) => b.title !== FUNCTIONS.key.title)
+  // Where a run in a terminal can store the key itself (automate.mjs). Only read from the repo here.
+  const targets = keyTargets({ hosts: detection.hosts, names, view: repo, plans, repo: slug })
   const changes = ws.changes()
   // A file that holds a key is never changed, so the key cannot reach the diff or the manifest.
   const keyed = changes.filter((c) => hasKey(c.before) || hasKey(c.after)).map((c) => c.file)
@@ -203,36 +475,121 @@ async function setup(opts, d, report) {
   }
   const commands = plans.flatMap((p) => p.plan.commands)
   const manual = plans.flatMap((p) => p.manual)
-  const exit = manual.length ? 3 : 0
+  const required = manual.filter((b) => b.required)
+  const exit = required.length ? 3 : 0
+  const planOnly = opts.dryRun || (opts.json && !opts.yes)
+  const app = { name: plans.map((p) => p.name).join(', '), repo: slug ?? undefined, platform: platformOf(detection.hosts) }
+  const KEEP = 'Keep the agent up to date: '
+  const keep = (updates.summary ?? []).filter((line) => line.startsWith(KEEP)).map((line) => line.slice(KEEP.length))
+  const last = { ask, opts, env, plans, required, root, hosts: detection.hosts, targets, secretName, app, cloudId, cloudLater, updates: updates.pr, bot: updates.bot, keep }
+  const record = plans.map((p) => ({ dir: p.s.dir, stack: p.stack, name: p.name, mode: p.mode, ...(p.channel ? { channel: p.channel } : {}),
+    ...(p.manual.some((b) => b.required && b.verify) ? { steps: p.manual.filter((b) => b.required && b.verify).map((b) => b.title) } : {}) }))
+  // In a terminal, the default is 1 Yes: sign in, show the whole plan, ask once, do it all (runOnce). --step-by-step
+  // keeps a question for each step. A dry run shows the same plan, unless it is --step-by-step or in a pipeline.
+  const once = automates(opts, ui, env) && !opts.stepByStep
+  const dryOnce = opts.dryRun && !opts.json && !opts.stepByStep && !ciVariable(env)
+  const facts = { ...last, ws, changes, commands, manifest, record, detection, view: repo, manual }
 
   if (!changes.length && !commands.length) {
-    ui.print(manual.length ? 'Nothing for this tool to change. The steps below are yours.' : 'Already set up. Nothing to change.')
-    printManual(ui, manual)
-    return ['nothing-to-change', exit]
+    // Set up: the manifest lists every service. Steps that this tool can check in the repo and that are not done
+    // yet leave it at steps-left (exit 3). Steps that it cannot check (often done on the platform) do not.
+    const recorded = Boolean(manifest) && plans.every((p) => manifest.services.some((m) => m.dir === p.s.dir))
+    if (recorded) {
+      const left = required.filter((b) => b.verify)
+      if (left.length) {
+        ui.print(fillIn(SETUP_STATUS.stepsLeft, { count: plural(left.length, 'step'), verb: left.length === 1 ? 'is' : 'are', pronoun: left.length === 1 ? 'it' : 'them' }))
+        ui.print()
+        for (const block of left) ui.block(block)
+        printManual(ui, manual.filter((b) => !left.includes(b)), true, SETUP_STATUS.doneSteps)
+        return ['steps-left', 3]
+      }
+      // After a no to the pull request, the files of setup are not committed yet: a rerun in a terminal asks again.
+      // It reads git only. The key steps are not asked again: npx @uknows/setup key does those. Then the first line
+      // says that setup has nothing more to change, so the question to commit does not read as a contradiction.
+      const terminal = automates(opts, ui, env)
+      const paths = [...manifestPaths(manifest)]
+      const pending = terminal ? await notCommitted(d.cli, { root, env, paths }) : []
+      ui.print(pending.length ? RERUN_UNCOMMITTED : SETUP_STATUS.done)
+      printManual(ui, manual, true, SETUP_STATUS.doneSteps)
+      if (terminal) {
+        const urls = plans.map((p) => connectUrl(p.name, null, appUrl(env)))
+        // .uknows/setup.json does not say if the key is stored, so the pull request and the last line say so (key: 'unknown').
+        const pr = await pullRequest(ui, d.cli, { root, env, paths, left: required.map((b) => b.title),
+          services: plans.map((p) => p.name), url: urls[0], rerun: true, key: 'unknown', logs: sendsLogs(plans), updates: updates.pr })
+        if (pr.state !== 'none') {
+          report.next = lastLine({ state: pr.state, urls, key: 'unknown' })
+          ui.print(report.next)
+        }
+      }
+      return ['nothing-to-change', 0]
+    }
+    // Nothing for this tool to change. Show where the app runs, the steps, and the key steps, and write the record so
+    // the pipeline check and remove know this service.
+    const status = exit ? 'needs-steps' : 'nothing-to-change'
+    // No record for a service that this tool could not set up: a Dockerfile to pick, or a plan that stopped.
+    const stopped = plans.some((p) => p.plan.stop || p.settings.stop || p.s.problems.some((x) => x.code === 'dockerfile-ambiguous'))
+    ui.print(exit ? SETUP_STATUS.steps : SETUP_STATUS.done)
+    ui.print()
+    const plain = !(dryOnce && !stopped) && !(once && !stopped)
+    if (plain) {
+      printHosts(ui, detection)
+      printManual(ui, manual)
+    }
+    if (dryOnce && !stopped) {
+      await printDryOnce(ui, d, report, { ...facts, recordOnly: true })
+      return [status, exit]
+    }
+    if (opts.dryRun && !opts.json) await printQuestions(ui, d, report, { ...last, view: repo, files: [CLI.manifest], manifest, apply: false })
+    if (planOnly || stopped || (ciVariable(opts.env) && !opts.allowCi)) return [status, exit]
+    if (once) return runOnce(ui, d, report, { ...facts, recordOnly: true, status, exit, declined: [status, exit] })
+    ui.print()
+    ui.print(fillIn(SETUP_STATUS.record, { manifest: CLI.manifest }))
+    if (!opts.yes) {
+      if (!ui.interactive) { ui.print(`Run again with --yes to write ${CLI.manifest}.`); return [status, exit] }
+      if (!(await ui.confirm(`Write ${CLI.manifest}? (Y/n)`))) { ui.print('Nothing changed.'); return [status, exit] }
+    }
+    const saved = await apply({ root, ws, changes: [], commands: [], manifest, services: record, d })
+    if (!saved) return ['failed', 1]
+    ui.print(`Wrote ${CLI.manifest}. To undo it, run npx @uknows/setup remove.`)
+    // The steps printed above already (plain): finish does not print them again.
+    return (await finish(ui, d, report, { ...last, shown: plain })) ?? [status, exit]
+  }
+
+  // A run that applies checks the pipeline and the git tree first, before the long plan.
+  if (!planOnly) {
+    if (stopInCi(ui, report, opts, env)) return ['planned', 2]
+    if (!opts.force) {
+      const git = d.gitStatus(root, manifestPaths(manifest))
+      if (!git.repo) {
+        const message = git.git ? 'This folder is not in a git repo. Keep a copy, so you can review what this tool changes.'
+          : 'git is not installed, so this tool cannot check for changes that are not committed.'
+        ui.print(`Note: ${message}`)
+        report.problems.push({ code: 'no-git', message })
+      } else if (git.paths.length) {
+        ui.error('This repo has changes that are not committed:')
+        for (const path of git.paths.slice(0, 10)) ui.error(`  ${path}`)
+        if (git.paths.length > 10) ui.error(`  and ${git.paths.length - 10} more`)
+        ui.error('Commit or stash your changes first, so you can review what this tool changes. Or run again with --force.')
+        report.problems.push({ code: 'dirty-tree', message: `${plural(git.paths.length, 'path')} in the repo are not committed.` })
+        return ['refused', 1]
+      }
+    }
+  }
+  if (dryOnce) {
+    await printDryOnce(ui, d, report, facts)
+    return ['planned', exit]
   }
+  if (once) return runOnce(ui, d, report, { ...facts, status: 'applied', exit, declined: ['planned', 0] })
   printPlan(ui, plans, detection, changes, commands, opts)
-  if (opts.dryRun || (opts.json && !opts.yes)) {
+  if (planOnly) {
     printManual(ui, manual)
+    if (opts.dryRun && !opts.json) {
+      const files = unique([...changes.map((c) => c.file), ...commands.flatMap((c) => c.touches), CLI.manifest])
+      await printQuestions(ui, d, report, { ...last, view: repo, files, manifest, apply: true })
+    }
     ui.print('This was a dry run. Nothing changed.')
     return ['planned', exit]
   }
-
-  if (!opts.force) {
-    const git = d.gitStatus(root, manifestPaths(manifest))
-    if (!git.repo) {
-      const message = git.git ? 'This folder is not in a git repo. Keep a copy, so you can review what this tool changes.'
-        : 'git is not installed, so this tool cannot check for changes that are not committed.'
-      ui.print(`Note: ${message}`)
-      report.problems.push({ code: 'no-git', message })
-    } else if (git.paths.length) {
-      ui.error('This repo has changes that are not committed:')
-      for (const path of git.paths.slice(0, 10)) ui.error(`  ${path}`)
-      if (git.paths.length > 10) ui.error(`  and ${git.paths.length - 10} more`)
-      ui.error('Commit or stash your changes first, so you can review what this tool changes. Or run again with --force.')
-      report.problems.push({ code: 'dirty-tree', message: `${plural(git.paths.length, 'path')} in the repo are not committed.` })
-      return ['refused', 1]
-    }
-  }
   if (!opts.yes) {
     if (!ui.interactive) {
       ui.print('Run again with --yes to apply.')
@@ -244,17 +601,565 @@ async function setup(opts, d, report) {
     }
   }
 
-  const record = plans.map((p) => ({ dir: p.s.dir, stack: p.stack, name: p.name }))
-  const saved = await apply({ root, ws, changes, commands, manifest, services: record, d })
+  const saved = await apply({ root, ws, changes, commands, manifest, services: record, updates: updates.bot, d })
   if (!saved) return ['failed', 1]
   report.files = printResult(ui, ws, saved, changes, commands)
-  printManual(ui, manual, false)
+  return (await finish(ui, d, report, last)) ?? ['applied', exit]
+}
+
+/** The key variable of apps that keep their own OTLP metrics and logs: only the traces exporter reads it. */
+const TRACES_HEADERS = 'OTEL_EXPORTER_OTLP_TRACES_HEADERS'
+/** The start line that a stack needs on a platform that does not run the Dockerfile. */
+const START_PREFIX = { python: 'opentelemetry-instrument', dotnet: 'sh ./instrument.sh' }
+
+/**
+ * After the files: ask for the key and check it, then the steps in the repo, the key steps of each platform, and 1
+ * line on what to do next. The next line depends on the check and on the steps left. In a terminal (automates()),
+ * setup then asks to do the last steps itself (finishInTerminal). Returns [status, exit code] that replace the ones of
+ * the repo, or null: a terminal run whose key UKNOWS refuses ends with 1, and Ctrl+C during the sign-in with 130.
+ */
+async function finish(ui, d, report, ctx) {
+  const { ask, opts, env, plans, required } = ctx
+  // --yes asks nothing. In a terminal with the key already set, it still checks that key.
+  const auto = !ask && opts.yes && ui.terminal && Boolean(env[SECRET.name]?.trim())
+  let checked = ask || auto ? await checkKey(ui, d, env, auto, plans[0]?.name ?? null, { pasteKey: opts.pasteKey, app: ctx.app }) : null
+  if (checked?.stopped && checked.interrupt) {
+    // Ctrl+C while setup waits for the sign-in: stop here. The files are changed already.
+    ui.print(`Stopped. The changes to your files stay. To undo them, run npx @uknows/setup remove.`)
+    return ['cancelled', 130]
+  }
+  if (checked?.stopped) checked = null
+  report.check = checked?.entry ?? null
+  if (automates(opts, ui, env)) {
+    const code = await finishInTerminal(ui, d, report, { ...ctx, headers: checked?.headers ?? null, notReady: Boolean(checked?.notReady) })
+    return code === null ? null : ['key-refused', code]
+  }
+  if (!ctx.shown) printManual(ui, plans.flatMap((p) => p.manual), true)
   for (const block of report.keySteps) ui.block(block)
   ui.print('Never put the key in a file in your repo.')
-  report.check = ask ? await checkKey(ui, d, env) : null
-  if (!report.check) ui.print(`To check your key, set ${SECRET.name} in this terminal, then run ${checkCommand(env)}.`)
-  ui.print(CLI.next)
-  return ['applied', exit]
+  ui.print()
+  const line = keyCheckLine(checkVars(env))
+  const status = report.check?.status
+  if (checked?.notReady) {
+    // A new key that UKNOWS did not get ready in 2 minutes: nothing to fix in the key, so no key advice.
+    ui.print(NEW_KEY.againFiles)
+    report.next = NEW_KEY.againFiles
+    return null
+  }
+  if (status === 'rejected' || status === 'network-error') {
+    ui.print(status === 'rejected' ? SETUP_NEXT.rejected : SETUP_NEXT.network)
+    ui.print(`  ${line}`)
+    report.next = status === 'rejected' ? SETUP_NEXT.rejected : SETUP_NEXT.network
+    return null
+  }
+  if (!report.check) {
+    ui.print(SETUP_NEXT.skipped)
+    ui.print(`  ${line}`)
+    ui.print()
+  }
+  report.next = required.length ? fillIn(SETUP_NEXT.steps, { count: plural(required.length, 'step') }) : nextData(env)
+  ui.print(report.next)
+  return null
+}
+
+/**
+ * The end of a run in a terminal: store the key on the platform, add the key to the deploy files, open the pull
+ * request, each after its own question (automate.mjs). What the user does not say yes to prints as today. A refused key
+ * stops here with exit 1: its steps print, and nothing is stored or committed.
+ */
+async function finishInTerminal(ui, d, report, { env, plans, required, root, hosts, targets, secretName, headers, cloudId = false, shown = false, updates = [], notReady = false }) {
+  const line = keyCheckLine(checkVars(env))
+  const status = report.check?.status
+  if (!shown) printManual(ui, plans.flatMap((p) => p.manual), true)
+  if (status === 'rejected') {
+    for (const block of report.keySteps) ui.block(block)
+    ui.print('Never put the key in a file in your repo.')
+    ui.print()
+    // A new key that UKNOWS did not get ready in 2 minutes: nothing to fix in the key, so no key advice.
+    report.next = notReady ? NEW_KEY.againFiles : SETUP_NEXT.rejected
+    ui.print(report.next)
+    if (!notReady) ui.print(`  ${line}`)
+    return 1
+  }
+  const environment = report.check?.environment ?? null
+  const steps = await keyStepsInTerminal(ui, d.cli, report.keySteps, targets, { key: status === 'reached' ? bareKey(headers) : null,
+    environment, env, root, secretName, service: plans.length === 1 ? plans[0].name : null, services: plans.map((p) => p.name) })
+  const view = () => repoView(d.createWorkspace(root))
+  const githubStep = steps.github ? githubStepLines(steps.github) : null
+  const applied = await deployFilesInTerminal(ui, deployEdits(view(), hosts, plans, secretName, { githubStep }), (edit) => applyDeployEdit(d.createWorkspace(root), edit))
+  const rest = openChecks(report.keySteps, { edits: applied, stored: steps.stored.map((s) => s.host), skipped: steps.skipped, secretName })
+  // The GitHub secret is stored: the step that reads it is left, unless the deploy file question added it.
+  if (steps.github && !applied.some((e) => e.checks.includes('github-step'))) rest.unshift(githubStepBlock(steps.github))
+  // A Kubernetes secret is only half: each deployment loads it with envFrom. Without that edit, the step stays.
+  if (steps.stored.some((s) => s.host === 'kubernetes') && !k8sLoadsKey(view(), plans)) rest.unshift(loadKeyBlock(report.keySteps))
+  for (const block of rest) ui.block(block)
+  ui.print('Never put the key in a file in your repo.')
+  ui.print()
+  const urls = plans.map((p) => connectUrl(p.name, environment, appUrl(env)))
+  const left = unique([...plans.flatMap((p) => p.manual).filter((b) => b.required).map((b) => b.title), ...steps.left, ...rest.map((b) => b.title)])
+  // Nothing stored and the key steps printed: a skipped key check, a no to the store question or a store that failed.
+  // The pull request and the last line then say to store the key before the merge (F-012-153).
+  const key = !steps.stored.length && steps.left.length ? 'left' : null
+  const pr = await pullRequest(ui, d.cli, { root, env, paths: [...manifestPaths(readManifest(root))], left, done: steps.stored.map((s) => s.done),
+    services: plans.map((p) => p.name), url: urls[0], environment, key, logs: sendsLogs(plans), cloudId, updates })
+  if (!report.check || status === 'network-error') {
+    ui.print(report.check ? SETUP_NEXT.network : SETUP_NEXT.skipped)
+    ui.print(`  ${line}`)
+    ui.print()
+  }
+  report.next = lastLine({ state: pr.state, required: required.length, urls, environment, key })
+  ui.print(report.next)
+  if (ui.terminal && urls[0]) d.openUrl(urls[0], env, () => ui.print(OPENING))
+  return null
+}
+
+/**
+ * A run in a terminal with 1 Yes (the default). Nothing changes until the Yes:
+ *   1. the key: from this terminal, a sign-in in the browser, or pasted (--paste-key, or p while waiting), then the check;
+ *   2. read only: where the key goes (az, gh, kubectl), the deploy files that would drop it, and git for the pull request;
+ *   3. the whole plan, and 1 question: Do all of this? (Y/n). d shows every line that changes;
+ *   4. every step, 1 line each with done or failed: the files, the key, the deploy files, the pull request;
+ *   5. what is left for the person, and the last line with the link to watch the app connect, which opens.
+ * A refused key stops before anything changes (exit 1). Ctrl+C while waiting for the sign-in: exit 130. A failed step
+ * after the files does not stop the others: its steps print at the end. Returns [status, exit code].
+ */
+async function runOnce(ui, d, report, ctx) {
+  const { opts, env, plans, required, root, hosts, targets, secretName, ws, commands, manifest, record, recordOnly = false, app, cloudLater = null, updates = [] } = ctx
+  let { changes, cloudId = false } = ctx
+  const services = plans.map((p) => p.name)
+  const checked = await checkKey(ui, d, env, false, plans[0]?.name ?? null, { once: true, pasteKey: opts.pasteKey, app })
+  if (checked?.stopped) {
+    ui.print('Stopped. Nothing changed.')
+    return checked.interrupt ? ['cancelled', 130] : ['stopped', 1]
+  }
+  report.check = checked?.entry ?? null
+  const status = report.check?.status ?? null
+  if (status === 'rejected') {
+    if (checked.notReady) ui.print(NEW_KEY.again)
+    else if (checked.from === 'signin') ui.print('UKNOWS did not accept the new key. Run npx @uknows/setup again in a minute. Nothing changed.')
+    else {
+      ui.print(SETUP_NEXT.rejected)
+      ui.print(`  ${keyCheckLine(checkVars(env))}`)
+      ui.print('Nothing changed.')
+    }
+    report.next = checked.notReady ? NEW_KEY.again : SETUP_NEXT.rejected
+    return ['key-refused', 1]
+  }
+  const mismatch = addressMismatch(checked?.link, opts.endpoint ?? INGEST_ENDPOINT)
+  if (mismatch) { ui.error(mismatch); return ['needs-input', 2] }
+  const environment = report.check?.environment ?? null
+  const keyCtx = { key: status === 'reached' ? bareKey(checked.headers) : null, environment, env, root, secretName,
+    service: plans.length === 1 ? plans[0].name : null, services }
+
+  // Read only: where the key goes, the deploy files, and git.
+  const look = ui.progress('Looking at where your app runs')
+  const stores = await planKeyStores(d.cli, report.keySteps, targets, keyCtx)
+  // The cloud id of a container app whose deploy command needs a look in Azure first (cloudid.mjs): read only.
+  if (cloudLater && !recordOnly) {
+    const view = repoView(ws)
+    const spots = cloudIdSpots(view, hosts)
+    const later = cloudIdPlan(view, spots, await cloudIdFacts(d.cli, { root, env }, cloudIdLookups(spots)), { dockerfiles: cloudLater.dockerfiles })
+    for (const edit of later.edits) ws.stage(edit)
+    if (later.edits.length) {
+      changes = ws.changes()
+      cloudId = true
+      if (plans.length) plans[0].settings.summary = [...plans[0].settings.summary, ...later.summary]
+    }
+  }
+  const ghStore = stores.stores.find((x) => x.t.kind === 'github')
+  const edits = deployEdits(repoView(ws), hosts, plans, secretName, { githubStep: ghStore && !ghStore.t.readsKey && !ghStore.found.partial ? githubStepLines(ghStore.block) : null })
+  const pr = await prPlan(d.cli, { root, env })
+  look.end(null)
+  const urls = plans.map((p) => connectUrl(p.name, environment, appUrl(env)))
+  const sendsTo = report.check?.workspace ? `${report.check.workspace}${environment ? `, environment ${environment}` : ''}` : null
+  printOnePlan(ui, onePlan({ ...ctx, changes, sendsTo, stores, edits, pr, urls, keyStatus: status, dry: false, keySteps: report.keySteps }))
+  if (!(await askOnce(ui, () => diffLines(changes, commands, edits)))) {
+    ui.print('Nothing changed.')
+    return ctx.declined ?? ['planned', 0]
+  }
+  ui.print()
+
+  // 1. The files, and the record that remove reads.
+  const quiet = muted(ui)
+  let saved = null
+  const files = await step(ui, recordOnly ? `Writing ${CLI.manifest}` : 'Adding OpenTelemetry to your app', async () => {
+    saved = await apply({ root, ws, changes, commands, manifest, services: record, updates: ctx.bot, d: { ...d, ui: quiet, spawn: (cmd, args, o) => d.spawn(cmd, args, { ...o, quiet: true }) } })
+    if (!saved) return { ok: false, line: 'Could not change your files. Nothing changed.', more: quiet.lines }
+    report.files = resultFiles(ws, saved, changes, commands).files
+    return { ok: true, line: recordOnly ? `Wrote ${CLI.manifest}` : `Added OpenTelemetry to your app (${plural(report.files.length, 'file')} changed)` }
+  })
+  if (!files.ok) return ['failed', 1]
+
+  // 2. The key, where setup found it can go.
+  const done = { stored: [], left: [], skipped: stores.skipped.map((x) => x.host), github: null }
+  let directFailed = false
+  for (const x of stores.stores) {
+    let put = { stored: false }
+    await step(ui, `Storing your key on ${storeName(x.found)}`, async () => {
+      put = await PUT[x.found.kind](d.cli, x.found, keyCtx)
+      if (put.stored) return { ok: true, line: put.done.replace(/\.$/, '') }
+      return { ok: false, line: put.why, more: [put.again === false ? 'Do the key steps at the end.' : 'Do the key steps at the end, or run npx @uknows/setup key to try again.'] }
+    })
+    if (put.stored) {
+      done.stored.push({ host: x.host, done: put.done })
+      if (x.t.kind === 'github' && put.partial) done.left.push(x.block.title)
+      else if (x.t.kind === 'github' && !x.t.readsKey) done.github = x.block
+    } else {
+      done.left.push(x.block.title)
+      if (x.t.kind !== 'github') directFailed = true
+    }
+  }
+  // The key is not on the app after all: the GitHub Actions block is needed again.
+  if (directFailed) for (const x of stores.skipped) { done.left.push(x.block.title); done.skipped = done.skipped.filter((h) => h !== x.host) }
+
+  // 3. The deploy files, as planned. The key step of a GitHub secret only when that secret is stored now.
+  const view = () => repoView(d.createWorkspace(root))
+  const planned = new Set(edits.map((e) => e.file))
+  const applied = []
+  for (const edit of deployEdits(view(), hosts, plans, secretName, { githubStep: done.github ? githubStepLines(done.github) : null }).filter((e) => planned.has(e.file))) {
+    const where = `${edit.file} ${edit.lines.length > 1 ? 'lines' : 'line'} ${list(edit.lines.map(String))}`
+    await step(ui, `Adding the key to ${edit.file}`, async () => {
+      try {
+        applyDeployEdit(d.createWorkspace(root), edit)
+        applied.push(edit)
+        return { ok: true, line: `Added the key to ${where}` }
+      } catch (error) {
+        return { ok: false, line: `Could not change ${edit.file}: ${error.message}. It is as it was.` }
+      }
+    })
+  }
+
+  // What is left for the person: steps in the repo, key steps, and deploy file checks.
+  const rest = openChecks(report.keySteps, { edits: applied, stored: done.stored.map((x) => x.host), skipped: done.skipped, secretName })
+  if (done.github && !applied.some((e) => e.checks.includes('github-step'))) rest.unshift(githubStepBlock(done.github))
+  if (done.stored.some((x) => x.host === 'kubernetes') && !k8sLoadsKey(view(), plans)) rest.unshift(loadKeyBlock(report.keySteps))
+  const leftTitles = new Set([...stores.left.map((x) => x.block.title), ...done.left])
+  const keyLeft = report.keySteps.filter((b) => leftTitles.has(b.title))
+  const left = unique([...plans.flatMap((p) => p.manual).filter((b) => b.required).map((b) => b.title), ...keyLeft.map((b) => b.title), ...rest.map((b) => b.title)])
+  const key = !done.stored.length && keyLeft.length ? 'left' : null
+
+  // 4. The branch and the pull request. Commits of the person that origin does not have never go along with 1 Yes.
+  let state = 'none'
+  if (pr?.from) {
+    const paths = await changedFiles(d.cli, { root, env, paths: [...manifestPaths(readManifest(root))] })
+    if (paths.length) {
+      const noPush = pr.ahead?.count ? aheadNote(pr) : null
+      const lines = []
+      const r = await step(ui, pr.gh && !noPush ? 'Opening a pull request' : 'Committing the change on a new branch', async () => {
+        const out = await prRun(d.cli, pr, { root, env, files: paths, noPush,
+          body: () => prBody({ services, files: paths, left, done: done.stored.map((x) => x.done), url: urls[0], environment, key, logs: sendsLogs(plans), cloudId, updates }) }, (l) => lines.push(l), (l) => lines.push(l))
+        state = out.state
+        const others = lines.filter((l) => l !== out.why && !l.startsWith('Created the branch') && !l.startsWith('Pushed ') && !l.startsWith('Opened the pull request'))
+        if (out.state === 'pr') return { ok: true, line: `Opened the pull request: ${out.url}`, more: others }
+        if (out.state === 'committed' && !out.why) return { ok: true, line: `Created the branch ${out.branch} with 1 commit`, more: others.filter((l) => l !== noPush) }
+        return { ok: false, line: out.why ?? 'Could not commit.', more: lines.filter((l) => l !== out.why) }
+      })
+      if (!r.ok && state === 'none') state = 'declined'
+    }
+  } else if (pr && !pr.from) {
+    ui.print('  This repo has no branch checked out, so setup did not commit. Commit the change and open a pull request yourself.')
+  }
+
+  ui.print()
+  printManual(ui, plans.flatMap((p) => p.manual), false)
+  for (const block of [...keyLeft, ...rest]) ui.block(block)
+  if (keyLeft.length || rest.length) { ui.print('Never put the key in a file in your repo.'); ui.print() }
+  if (status === 'network-error') {
+    ui.print(SETUP_NEXT.network)
+    ui.print(`  ${keyCheckLine(checkVars(env))}`)
+    ui.print()
+  }
+  report.next = lastLine({ state, required: required.length, urls, environment, key })
+  ui.print(report.next)
+  if (ui.terminal && urls[0]) d.openUrl(urls[0], env, () => ui.print(OPENING))
+  return [ctx.status, ctx.exit]
+}
+
+/** Why a run with 1 Yes commits but does not push: commits of the person that origin does not have would go along. */
+function aheadNote(pr) {
+  const n = pr.ahead.count
+  const names = pr.ahead.subjects.map((x) => `"${x}"`)
+  const shown = n > names.length ? `${names.join(', ')} and ${n - names.length} more` : list(names)
+  return `Your branch has ${plural(n, 'commit')} that ${n === 1 ? 'is' : 'are'} not on origin/${pr.base} yet: ${shown}. A push would take ${n === 1 ? 'it' : 'them'} along, so setup only commits. Push when you are ready.`
+}
+
+/** A UI that keeps what it would print, for the steps whose lines go under their done or failed line. */
+function muted(ui) {
+  const lines = []
+  return { ...ui, lines, print: (text = '') => { if (text) lines.push(text) }, error: (text) => lines.push(text), block: () => {} }
+}
+
+/**
+ * The plan of a run with 1 Yes, from what setup found: the app, the files, where the key goes, the deploy files, the
+ * pull request and the link. dry: a dry run, which signs in to nothing and looks up nothing outside this computer.
+ */
+function onePlan({ opts, plans, detection, changes, commands, manifest, recordOnly = false, stores, edits, pr, urls, sendsTo, keyStatus, dry, keySteps, secretName, keep = [] }) {
+  const one = plans.length === 1 ? plans[0] : null
+  const app = one ? [['App', `${one.name}, ${describeShort(one.s)}`]] : [['Apps', plans.map((p) => `${p.name} (${p.s.dir})`).join(', ')]]
+  const from = one && !opts.serviceName ? (one.s.nameFrom === 'existing' ? 'is set in your repo already' : one.s.nameFrom === 'folder' ? 'comes from the folder name' : `comes from ${one.s.nameFrom}`) : null
+  // GitHub Actions is how the app deploys, not where it runs.
+  const runs = detection.hosts.filter((h) => h.id !== 'github-actions')
+  if (runs.length) app.push(['Runs on', list(unique(runs.map((h) => hostLabel(h.id))))])
+  if (detection.hosts.some((h) => h.id === 'github-actions')) app.push(['Deploys with', hostLabel('github-actions')])
+  app.push(['Sends to', dry ? 'the workspace and environment that you pick when you sign in' : sendsTo ?? 'not checked: setup has no key yet'])
+  const steps = []
+  const good = []
+  steps.push(recordOnly
+    ? { title: `Write ${CLI.manifest}`, rows: [], notes: [fillIn(SETUP_STATUS.record, { manifest: CLI.manifest })] }
+    : { title: plans.length > 1 ? 'Add OpenTelemetry to your apps' : 'Add OpenTelemetry to your app', rows: fileRows(changes, commands, { manifest: Boolean(manifest) }), notes: runNotes(commands) })
+  // How the agent stays up to date, and why (updates.mjs): the method, said once.
+  if (!recordOnly && keep.length) steps.push({ title: 'Keep the agent up to date', rows: [], notes: keep.map((line) => `${line[0].toUpperCase()}${line.slice(1)}`) })
+  for (const x of stores.stores) {
+    const r = storeRows(x.found)
+    steps.push({ title: r.title, rows: r.rows, notes: [r.note] })
+  }
+  // Left for the person: the steps in the repo, the key steps that setup cannot do here, and the deploy file checks that
+  // the planned edits and stores do not cover.
+  const checks = openChecks(keySteps, { edits, stored: stores.stores.map((x) => x.host), skipped: stores.skipped.map((x) => x.host), secretName })
+  const byHand = [...plans.flatMap((p) => p.manual).filter((b) => b.required).map((b) => b.title), ...stores.left.map((x) => x.block.title), ...checks.map((b) => b.title)]
+  // The reasons say "the steps below" in a run with a question for each step. Here the steps come at the end.
+  const why = unique(stores.left.map((x) => x.why).filter((w) => w && w !== 'no-key')
+    .map((w) => w.replace(/use the steps below/g, 'do the key steps at the end').replace(/Use the steps below/g, 'Do the key steps at the end').replace(/with the steps below/g, 'with the key steps at the end')))
+  if (stores.left.some((x) => x.why === 'no-key')) {
+    good.push(keyStatus === 'network-error' ? 'Setup could not check your key, so it does not store it. The key steps print at the end.'
+      : dry ? 'Setup stores your key after you sign in.' : 'Setup has no key, so it does not store one. The key steps print at the end. To store it later, run npx @uknows/setup key.')
+  }
+  good.push(...why)
+  if (edits.length) {
+    steps.push({ title: 'Keep the key on each deploy', rows: [], notes: [...edits.flatMap((e) => e.about), `Setup adds the key ${edits.length > 1 ? 'to those files' : 'there'}.`] })
+  }
+  if (pr?.from) {
+    const into = pr.base && pr.slug ? [['Into', `${pr.base} of ${pr.slug}`]] : []
+    const branch = [['Branch', `${pr.branch}, with 1 commit of the files above`]]
+    if (pr.ahead?.count) steps.push({ title: 'Commit the change on a new branch', rows: branch, notes: [aheadNote(pr)] })
+    else if (dry && pr.slug && pr.base) steps.push({ title: 'Open a pull request', rows: [...branch, ...into], notes: ['If gh is not signed in, setup only commits and prints the push command.'] })
+    else if (pr.gh) steps.push({ title: 'Open a pull request', rows: [...branch, ...into], notes: [] })
+    else {
+      const reason = !pr.remote ? 'This repo has no remote named origin, so setup does not push.'
+        : !pr.base ? 'Setup cannot tell which branch of origin the pull request goes to, so it does not push.'
+          : !pr.slug ? 'origin is not on github.com, so setup does not open the pull request.'
+            : 'gh is not signed in, so setup does not push or open the pull request.'
+      steps.push({ title: 'Commit the change on a new branch', rows: branch, notes: [`${reason} The push command prints at the end.`] })
+    }
+  } else if (pr && !pr.from) good.push('This repo has no branch checked out, so setup does not commit. Commit the change and open a pull request yourself.')
+  for (const p of plans) {
+    const chosen = p.s.evidence?.find((e) => e.what.startsWith('Dockerfile for this service: '))
+    const kind = /dockerfile/i.test(chosen?.file.split('/').pop() ?? '') ? 'file' : 'Dockerfile'
+    // Only a Dockerfile that setup had to pick from others is worth a line.
+    const why = chosen?.what.slice('Dockerfile for this service: '.length)
+    if (chosen && why !== 'it is in the service folder') good.push(`Setup uses the ${kind} ${chosen.file}${plans.length > 1 ? ` for ${p.name}` : ''}, because ${why}.`)
+    good.push(...p.notes, ...p.s.problems.filter((x) => x.code !== 'dockerfile-ambiguous').map((x) => x.message))
+  }
+  const link = urls.filter(Boolean)
+  const merge = pr?.from ? (steps.at(-1).title === 'Open a pull request' ? 'merge the pull request' : 'push the branch, open a pull request, merge it') : 'commit, open a pull request, merge it'
+  const then = link.length ? `Then you ${merge} and deploy as usual. Watch your ${link.length > 1 ? 'apps' : 'app'} connect at ${list(link)}`
+    : `Then you ${merge} and deploy as usual, and watch your app connect in your test copy of UKNOWS.`
+  return { app, nameNote: from ? `The name ${one.name} ${from}. To change it, use --service-name.` : null, steps, byHand: unique(byHand), good: unique(good), then }
+}
+
+/** A short description of a service: its stack and frameworks, and its folder when it is not this one. */
+function describeShort(s) {
+  const frameworks = s.frameworks?.length ? ` (${s.frameworks.map(frameworkLabel).join(', ')})` : ''
+  return `${stackLabel(s.lang)}${frameworks}${s.dir && s.dir !== '.' ? ` in ${s.dir}` : ''}`
+}
+
+/**
+ * The dry run of a run with 1 Yes: the same plan, from this computer only (no sign-in, no cloud CLI, no network),
+ * then every line that changes and the steps that are left for the person.
+ */
+async function printDryOnce(ui, d, report, ctx) {
+  const { env, plans, hosts, targets, secretName, ws, changes, commands, root, manifest, recordOnly = false } = ctx
+  const stores = dryStores(report.keySteps, targets, plans.length)
+  const ghStore = stores.stores.find((x) => x.t.kind === 'github')
+  const edits = deployEdits(repoView(ws), hosts, plans, secretName, { githubStep: ghStore && !ghStore.t.readsKey ? githubStepLines(ghStore.block) : null })
+  const pr = d.gitStatus(root, manifestPaths(manifest)).repo ? await prFacts((args, more = {}) => d.cli('git', ['-C', root, ...args], { cwd: root, env, ...more })) : null
+  const urls = plans.map((p) => connectUrl(p.name, null, appUrl(env)))
+  printOnePlan(ui, onePlan({ ...ctx, stores, edits, pr, urls, dry: true, keySteps: report.keySteps }))
+  ui.say('A real run in a terminal signs you in to UKNOWS in your browser first. Then it shows this plan with your workspace, and asks 1 question: Do all of this? (Y/n)')
+  const lines = diffLines(changes, commands, edits)
+  if (lines.some(Boolean)) {
+    ui.print()
+    ui.print('Every line that changes:')
+    ui.print()
+    for (const line of lines.slice(0, DIFF_LIMIT)) ui.print(line)
+    if (lines.length > DIFF_LIMIT) ui.print(`And ${plural(lines.length - DIFF_LIMIT, 'more line')}. Run with --json to see every planned file.`)
+  }
+  printManual(ui, plans.flatMap((p) => p.manual))
+  // The key steps that the plan does not do, for the person. The ones it does are only for doing it by hand.
+  const byHand = report.keySteps.filter((b) => !stores.stores.some((x) => x.block.title === b.title) && !stores.skipped.some((x) => x.block.title === b.title))
+  if (byHand.length) {
+    ui.print()
+    ui.print(`You do ${byHand.length === 1 ? 'this step' : 'these steps'} yourself:`)
+    ui.print()
+    for (const block of byHand) ui.block(block)
+  } else ui.print()
+  ui.print('This was a dry run. Nothing changed.')
+}
+
+/**
+ * The stores of a dry run, from the repo only, as plannedQuestions knows them: an Azure app when the deploy files name 1
+ * app and the run has 1 service, a Kubernetes secret when the namespace is known, and the GitHub secret when nothing
+ * stores on the platform or a workflow reads the secret. found holds what the plan can name without a lookup.
+ */
+function dryStores(blocks, targets, services) {
+  const out = { stores: [], left: [], skipped: [] }
+  let direct = false
+  for (const block of blocks.filter((b) => b.title.startsWith('Set your key once: '))) {
+    const host = HOSTS.find((h) => block.title === `Set your key once: ${h.label}`)
+    const t = host ? targets.get(host.id) : null
+    if (host?.id === 'github-actions' && direct && !t?.readsKey) { out.skipped.push({ block, host: host.id }); continue }
+    let found = null
+    if (t && (t.kind === 'aca' || t.kind === 'webapp')) {
+      const apps = pickApp(t.apps.map((a) => a.name))
+      const groups = unique(t.groups.map((g) => g.name))
+      if (apps.length === 1 && services === 1 && !(t.kind === 'webapp' && t.slots?.length)) {
+        found = { kind: t.kind, name: apps[0], rg: groups.length === 1 ? groups[0] : 'the one that has this app', dry: true }
+      }
+    } else if (t?.kind === 'k8s') {
+      const spaces = unique(t.workloads.map((w) => w.namespace))
+      if (spaces.length === 1 && spaces[0]) found = { kind: 'k8s', ns: spaces[0], context: 'the one that has this app. A real run looks it up.', dry: true }
+    } else if (t?.kind === 'github' && t.repo) {
+      const g = githubSecret(t.jobs)
+      if (!g.why) found = { kind: 'github', repo: t.repo, env: g.env === null ? null : 'the one of the environment that you pick when you sign in', dry: true }
+    }
+    if (!found) { out.left.push({ block, host: host?.id ?? null, why: null }); continue }
+    out.stores.push({ block, host: host.id, t, found })
+    if (t.kind !== 'github') direct = true
+  }
+  return out
+}
+
+/** Said just before the page where the app connects opens in the browser. Nothing prints when no browser can open. */
+const OPENING = 'Opening it in your browser.'
+
+/** A rerun with nothing to change whose files are not committed yet: setup itself has nothing more to change. */
+const RERUN_UNCOMMITTED = 'Already set up. Setup itself has nothing more to change.'
+
+/** The key of x-uknows-key in the header text of a check, or null. */
+function bareKey(headers) {
+  const pairs = parseHeaders(headers ?? '')
+  const name = Object.keys(pairs).find((n) => n.toLowerCase() === SECRET.header)
+  const key = name ? pairs[name].trim() : ''
+  return key || null
+}
+
+/**
+ * Add the key to 1 deploy file, after a yes. The edit goes in the manifest like every other change, so remove gives back
+ * every byte, and a rerun finds nothing to add.
+ */
+function applyDeployEdit(ws, edit) {
+  for (const file of [edit.file, CLI.manifest]) inside(ws, file)
+  const abs = ws.abs(edit.file)
+  const beforeBytes = readBytes(abs)
+  if (beforeBytes === null || text(beforeBytes) !== edit.before) throw new Error('it changed while this ran')
+  const bom = beforeBytes.toString('utf8').startsWith(BOM)
+  if (!beforeBytes.equals(Buffer.from((bom ? BOM : '') + edit.before, 'utf8'))) throw new Error('it is not UTF-8 text')
+  const manifest = readManifest(ws.root)
+  if (!manifest) throw new Error(`${CLI.manifest} is missing`)
+  const afterBytes = Buffer.from((bom ? BOM : '') + edit.after, 'utf8')
+  const entry = changeEntry({ file: edit.file, before: edit.before, after: edit.after, bom }, beforeBytes, afterBytes)
+  writeAtomic(abs, afterBytes)
+  try {
+    writeAtomic(ws.abs(CLI.manifest), Buffer.from(manifestText(mergeManifest(manifest, { services: [], changes: [entry], packages: [] }))))
+  } catch (error) {
+    writeAtomic(abs, beforeBytes)
+    throw error
+  }
+}
+
+/**
+ * The dry run: the key steps and the questions that a run in a terminal asks after the plan. Not in a pipeline. It
+ * reads git on this computer only: no cloud CLI and no network. Without a terminal, the full key steps come first. In
+ * a terminal, the questions come first: the key steps that a question does follow them, under a heading that says
+ * they are only for doing it by hand. Key steps that no question does stay before the questions, as steps to do.
+ */
+async function printQuestions(ui, d, report, { env, hosts, plans, targets, secretName, view, files, manifest, root, apply }) {
+  ui.print()
+  if (ciVariable(env)) {
+    for (const block of report.keySteps) ui.block(block)
+    return
+  }
+  const edits = deployEdits(view, hosts, plans, secretName)
+  const pr = d.gitStatus(root, manifestPaths(manifest)).repo ? await prFacts((args, more = {}) => d.cli('git', ['-C', root, ...args], { cwd: root, env, ...more })) : null
+  const planned = plannedQuestions({ targets, edits, files: unique([...files, ...edits.map((e) => e.file)]), pr, services: plans.length })
+  const questions = [{ question: apply ? 'Apply? (Y/n)' : `Write ${CLI.manifest}? (Y/n)` }, { question: KEY_QUESTION }, ...planned.questions]
+  const asked = (block) => planned.hosts.some((id) => block.title.endsWith(`: ${HOSTS.find((h) => h.id === id)?.label}`))
+  const byHand = ui.interactive ? report.keySteps.filter(asked) : []
+  for (const block of report.keySteps.filter((b) => !byHand.includes(b))) ui.block(block)
+  ui.print('In a terminal, a real run asks you:')
+  questions.forEach((q, i) => {
+    ui.print(`  ${i + 1}. ${q.question}`)
+    if (q.after) ui.print(`     If you say no: ${q.after}`)
+  })
+  ui.print('Each question changes only what it says. When you answer no, setup prints that step for you to do.')
+  ui.print()
+  if (!byHand.length) return
+  ui.print(BY_HAND)
+  ui.print()
+  for (const block of byHand) ui.block(block)
+}
+
+/** The heading of the key steps that the questions of a real run do, in a dry run in a terminal. */
+const BY_HAND = 'These steps are only for doing it by hand. When you answer yes, the questions above do them for you:'
+
+/**
+ * The required step for an App Service code deploy (a zip or Oryx deploy, not an image): App Service never runs the
+ * Dockerfile, so the start line and the settings that this tool put there must be set on App Service too. Only for a
+ * service whose settings went into a Dockerfile.
+ */
+function appServiceCode(p, names, view = null) {
+  const deploy = names.code?.find((c) => c.kind === 'deploy')
+  if (!deploy || p.settings.target?.kind !== 'dockerfile') return []
+  const T = APP_SERVICE_CODE
+  const stack = STACKS.find((x) => x.id === p.stack)
+  const pairs = [...(p.settings.pairs ?? []), ...(p.mode === 'standard' ? (stack?.platformEnv ?? []).map((l) => [l.slice(0, l.indexOf('=')), l.slice(l.indexOf('=') + 1)]) : [])]
+  const web = names.webapp ?? { apps: [], groups: [], slots: [] }
+  const group = new Set(web.groups.map((g) => g.name)).size === 1 ? web.groups[0] : null
+  // The code goes to a deployment slot (then a swap moves it into production): the settings and the startup command go on
+  // that slot too, as the deploy of the repo does. Plain app settings move with the code on swap. A slot that only a
+  // workflow input or variable holds (slotUnknown) keeps an example SLOT, which the user replaces.
+  const slot = deploy.slot ?? null, unknown = deploy.slotUnknown ?? null
+  const scriptNames = { ...(web.apps[0] ? { app: web.apps[0].name } : {}), ...(group ? { resourceGroup: group.name } : {}),
+    ...(slot || unknown ? { slot: slot ?? unknown } : {}), ...(unknown ? { slotUnknown: true } : {}),
+    from: { ...(web.apps[0] ? { app: web.apps[0].where } : {}), ...(group ? { resourceGroup: group.where } : {}), ...(slot || unknown ? { slot: deploy.where } : {}) } }
+  const values = { where: deploy.where, dockerfile: p.settings.target.file, count: pairs.length }
+  const lines = T.lines.map((l) => fillIn(l, values))
+  if (unknown) lines.push(`${deploy.where} deploys to the slot ${unknown}. Set SLOT below to the name of that slot.`)
+  const snippets = [settingsSnippet('azure-app-service', pairs, p.name, scriptNames)]
+  const prefix = p.mode === 'standard' ? START_PREFIX[p.stack] : null
+  if (!prefix) return [{ title: T.title, lines, snippets }]
+  // The startup command of the slot that gets the code, else the first one.
+  const starts = names.code.filter((c) => c.kind === 'startup')
+  const startup = starts.find((c) => (c.slot ?? null) === slot && (c.slotUnknown ?? null) === unknown) ?? starts[0]
+  if (startup?.startup.startsWith(prefix)) {
+    // The deploy sets the startup command with the prefix already. The step is done when the deploy files also set
+    // every setting. Else only the settings are left, and they may be set on the platform, so the repo cannot show them.
+    return view && settingsInFiles(view, names, pairs) ? [] : [{ title: T.title, lines, snippets }]
+  }
+  const example = p.stack === 'python' ? stack.start.replace(/^opentelemetry-instrument\s+/, '') : `dotnet ${p.name}.dll`
+  const command = startup ? `${prefix} ${startup.startup}` : `${prefix} ${example}`
+  lines.push(startup ? fillIn(T.start, { startWhere: startup.where, startup: startup.startup, prefix }) : fillIn(T.startNone, { prefix }))
+  // The same first lines as the settings snippet: the comment and the names, up to its az line.
+  const head = settingsSnippet('azure-app-service', [], p.name, scriptNames).code.split('\n')
+  snippets.push({ caption: 'The startup command of your web app', language: 'bash',
+    code: [...head.slice(0, head.findIndex((l) => l.startsWith('az '))),
+      `az webapp config set --subscription "$SUBSCRIPTION" -g "$RESOURCE_GROUP" -n "$APP"${slot || unknown ? ' --slot "$SLOT"' : ''} -o none --startup-file "${command.replace(/"/g, '\\"')}"`].join('\n') })
+  // A deploy file sets the startup command, so each deploy sets it again: the repo shows when the step is done (F-012-10).
+  // With no startup command in the deploy files, it is set on the platform, and the repo cannot show it.
+  return [{ title: T.title, ...(startup ? { verify: true } : {}), lines, snippets }]
+}
+
+/**
+ * The deploy files of the App Service code deploy set each setting: as NAME=value (az --settings), "name": "NAME" (the
+ * JSON of azure/appservice-settings), or NAME: value and name: NAME (YAML). Comment lines do not count.
+ */
+function settingsInFiles(view, names, pairs) {
+  const files = [...new Set(names.code.map((c) => c.where.replace(/ line \d+$/, '')))]
+  const body = files.map((f) => { try { return view.read(f) ?? '' } catch { return '' } }).join('\n').replace(/^[ \t]*(?:#|\/\/).*$/gm, '')
+  return pairs.every(([name]) => {
+    const n = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    return new RegExp(`(?:^|[\\s"'(,\\[])${n}=|"name"\\s*:\\s*"${n}"|^[ \\t]*(?:-[ \\t]+)?(?:name[ \\t]*:[ \\t]*["']?${n}["']?[ \\t]*$|${n}[ \\t]*:)`, 'm').test(body)
+  })
 }
 
 /**
@@ -262,7 +1167,7 @@ async function setup(opts, d, report) {
  * failure, put every file back and return null. Returns the original bytes
  * of every path it touched.
  */
-async function apply({ root, ws, changes, commands, manifest, services, d }) {
+async function apply({ root, ws, changes, commands, manifest, services, updates = null, d }) {
   const { ui } = d
   // Ctrl-C stops the package manager. Stay alive, so the failed run is rolled back below.
   const hold = () => {}
@@ -298,22 +1203,55 @@ async function apply({ root, ws, changes, commands, manifest, services, d }) {
       written.set(c.file, bytes)
     }
     for (const command of commands) for (const file of command.touches) save(file)
+    const locked = []
     for (const command of commands) {
       const result = await d.spawn(command.cmd, command.args, { cwd: ws.abs(command.cwd) })
       if (result.code !== 0) {
         undo()
-        ui.error(`${command.cmd} failed${result.error ? `: ${result.error}` : ''}. Nothing changed.`)
-        ui.error(`  ${[command.cmd, ...command.args].join(' ')}${command.cwd === '.' ? '' : ` (in ${command.cwd})`}`)
+        const failed = command.kind === 'lock' && !result.error ? resolverFailure(command, result.output ?? '') : null
+        if (failed) {
+          for (const line of [failed.title, ...failed.lines]) ui.error(line)
+        } else {
+          ui.error(`${command.cmd} failed${result.error ? `: ${result.error}` : ''}. Nothing changed.`)
+          ui.error(`  ${[command.cmd, ...command.args].join(' ')}${command.cwd === '.' ? '' : ` (in ${command.cwd})`}`)
+        }
+        return null
+      }
+      if (command.kind !== 'lock') continue
+      // After a restore, the packages the build check sees must match the plan (dotnet.mjs verifyRestore).
+      const problem = command.verify ? d.verify(command.verify, (file) => { const b = readBytes(ws.abs(file)); return b === null ? null : text(b) }) : null
+      if (problem) {
+        undo()
+        for (const line of [problem.title, ...problem.lines]) ui.error(line)
         return null
       }
+      // A lock refresh must keep the lockfile format (the uv in the image reads only its own version).
+      for (const { file, pattern } of command.keep ?? []) {
+        const re = new RegExp(pattern, 'm')
+        const was = re.exec(text(saved.get(file) ?? Buffer.alloc(0)))?.[0] ?? null, now = re.exec(text(readBytes(ws.abs(file)) ?? Buffer.alloc(0)))?.[0] ?? null
+        if (was !== now) {
+          undo()
+          ui.error(`${command.cmd} changed ${file} from "${was}" to "${now}". The ${command.cmd} in your image may not read it. Nothing changed.`)
+          ui.error(`Install the ${command.cmd} version that your image uses. Then run npx @uknows/setup again.`)
+          return null
+        }
+      }
+      locked.push(command)
     }
     const entries = changes.map((c) => changeEntry(c, saved.get(c.file), written.get(c.file)))
-    const packages = commands.map((c) => ({ cwd: c.cwd, cmd: c.cmd, added: c.added, undo: [c.undo.cmd, ...c.undo.args], touches: c.touches,
-      before: Object.fromEntries(c.touches.map((file) => [file, sha256(saved.get(file))])) }))
+    // Files that a lock refresh rewrote are ordinary text changes, so remove restores them byte for byte.
+    for (const file of unique(locked.flatMap((c) => c.touches))) {
+      const before = saved.get(file), after = readBytes(ws.abs(file))
+      if (after === null || (before && before.equals(after))) continue
+      entries.push(changeEntry({ file, before: before ? text(before) : null, after: text(after), bom: Boolean(before && text(before) !== before.toString('utf8')) },
+        before, after))
+    }
+    const packages = commands.filter((c) => c.kind !== 'lock').map((c) => ({ cwd: c.cwd, cmd: c.cmd, added: c.added, undo: [c.undo.cmd, ...c.undo.args],
+      touches: c.touches, before: Object.fromEntries(c.touches.map((file) => [file, sha256(saved.get(file))])) }))
     save(CLI.manifest)
     const file = ws.abs(CLI.manifest)
     makeDirs(dirname(file), made)
-    writeAtomic(file, Buffer.from(manifestText(mergeManifest(manifest, { services, changes: entries, packages }))))
+    writeAtomic(file, Buffer.from(manifestText(mergeManifest(manifest, { services, changes: entries, packages, updates }))))
     return saved
   } catch (error) {
     undo()
@@ -344,6 +1282,7 @@ async function remove(opts, d, report) {
   }
   ui.print(`  Delete ${CLI.manifest}.`)
   if (opts.json && !opts.yes) return ['planned', 0]
+  if (stopInCi(ui, report, opts)) return ['planned', 2]
   if (!opts.yes) {
     if (!ui.interactive) {
       ui.print('Run again with --yes to remove.')
@@ -403,42 +1342,120 @@ async function remove(opts, d, report) {
   return ['removed', 0]
 }
 
-/** The check command as the reader should type it, with the test addresses of this run. */
-function checkCommand(env) {
-  const vars = [CLI.siteEnv, CLI.endpointEnv].filter((name) => env[name]).map((name) => `${name}=${env[name]}`)
-  return [...vars, 'npx @uknows/setup check'].join(' ')
+/** The question that asks for the key. */
+const KEY_QUESTION = 'Paste your UKNOWS key to check it now. It does not show on the screen. Press Enter to skip:'
+
+/** The test addresses of this run, as settings in front of the check command. */
+function checkVars(env) {
+  return [CLI.siteEnv, CLI.endpointEnv].filter((name) => env[name]).map((name) => `${name}=${env[name]}`)
 }
 
 /**
- * Check your key, right after setup: the key from this terminal, or one pasted now. The pasted key is never
- * written anywhere and never shows on the screen. Returns the --json check entry, or null when skipped.
+ * Check your key: the key from this terminal, a sign-in in the browser, or a key pasted now (--paste-key, or p while
+ * setup waits for the sign-in). The key is never written anywhere and never shows on the screen. auto: --yes in a
+ * terminal, so check the key in this terminal without a question. paste: after a no to the key of this terminal, get
+ * another key (the key command, which is for another environment). once: a run with 1 Yes, before its plan: a key in
+ * this terminal is used without a question, since the plan names its workspace and environment before the 1 Yes.
+ * pasteKey: --paste-key. app: what the browser shows about this app while signing in.
+ * Returns {entry, headers, from, link}: the --json check entry, the header text that was checked (in memory only, for
+ * the key steps in a terminal), where the key came from ('terminal', 'signin' or 'paste') and the answer of the sign-in.
+ * null when skipped. {stopped, interrupt} when the person stopped the sign-in (q, or Ctrl+C).
  */
-async function checkKey(ui, d, env) {
-  ui.print()
-  ui.print('Check your key')
-  let headers = null
-  if (env[SECRET.name]?.trim()) {
-    if (await ui.confirm(`Check the key in ${SECRET.name} from this terminal now? (Y/n)`)) headers = env[SECRET.name]
-  } else {
-    const key = (await ui.secret('Paste your UKNOWS key to check it now. It does not show on the screen. Press Enter to skip:')).trim()
-    // Accept the key as copied, also with the header name or quotes around it.
-    const bare = key.replace(/^["']|["']$/g, '').replace(new RegExp(`^${SECRET.header}\\s*[=:]\\s*`, 'i'), '').trim()
-    if (bare) headers = `${SECRET.header}=${bare}`
+async function checkKey(ui, d, env, auto = false, serviceName = null, { paste = false, once = false, pasteKey = false, app = null } = {}) {
+  if (!once) {
+    ui.print()
+    ui.print('Check your key')
+  }
+  let headers = null, from = null, link = null
+  const inTerminal = Boolean(env[SECRET.name]?.trim())
+  if (auto) {
+    ui.print(`Checking the key in ${SECRET.name} from this terminal.`)
+    headers = env[SECRET.name]
+    from = 'terminal'
+  } else if (inTerminal && once) {
+    ui.print(`Using the key in ${SECRET.name} from this terminal.`)
+    headers = env[SECRET.name]
+    from = 'terminal'
+  } else if (inTerminal && (await ui.confirm(`Check the key in ${SECRET.name} from this terminal now? (Y/n)`))) {
+    headers = env[SECRET.name]
+    from = 'terminal'
+  } else if (!inTerminal || paste) {
+    const got = await keyFromPerson(ui, d, env, { pasteKey, app })
+    if (got.stopped) return got
+    ;({ headers, from, link } = got)
   }
   if (!headers) return null
-  const result = await d.runCheck({ env, headers })
+  // The test span carries the name of the service of this run, so the workspace never lists a made-up app.
+  // A timeout gets 1 more try, which can take up to 30 seconds: say so, so the wait is not a surprise.
+  // The key of the sign-in is new: the data intake of UKNOWS learns it about 30 seconds later, so the check waits for
+  // it, for up to 2 minutes, with 1 line (check.mjs NEW_KEY). A pasted key or the key of this terminal gets 1 try.
+  const result = await d.runCheck({ env, headers, serviceName, onRetry: (line) => ui.print(`  ${line}`),
+    newKey: from === 'signin', clock: d.clock, onWait: () => newKeyLine(ui, d.clock) })
   for (const line of result.lines) (result.ok ? ui.print : ui.error)(`  ${line}`)
   ui.print()
   const status = result.ok ? 'reached' : result.status === null ? 'network-error' : 'rejected'
-  return { status, httpStatus: result.status, workspace: result.workspace, environment: result.environment }
+  return { entry: { status, httpStatus: result.status, workspace: result.workspace, environment: result.environment }, headers, from, link,
+    notReady: Boolean(result.notReady) }
 }
 
-function printPlan(ui, plans, detection, changes, commands, opts) {
+/** The 1 line while a new key gets ready (check.mjs NEW_KEY): a spinner with the time on a terminal, else 1 plain line. */
+function newKeyLine(ui, clock) {
+  const started = clock.now()
+  if (!ui.tty) ui.print(`  ${NEW_KEY.waitingPlain}`)
+  const spin = ui.progress(() => `${NEW_KEY.waiting} ${clockText(clock.now() - started)}`, '  ')
+  return (line) => spin.end(line === null ? null : `  ${line}`)
+}
+const clockText = (ms) => { const s = Math.max(0, Math.floor(ms / 1000)); return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}` }
+
+/**
+ * A key from the person at the terminal: a sign-in in the browser, or the hidden paste question (--paste-key, p while
+ * waiting, or a test copy of UKNOWS with no app address). {headers, from, link}, {headers: null} when skipped, or
+ * {stopped, interrupt}.
+ */
+async function keyFromPerson(ui, d, env, { pasteKey = false, app = null } = {}) {
+  const base = appUrl(env)
+  // A pipeline never starts a sign-in (only --allow-ci in a terminal gets here): it can only paste.
+  let paste = pasteKey || Boolean(ciVariable(env))
+  if (!paste && !base) {
+    // A test address without the app of that UKNOWS: never sign in at the production app. Say which setting is missing.
+    for (const line of SIGN_IN.noApp([CLI.siteEnv, CLI.endpointEnv].filter((name) => env[name]))) ui.print(line)
+    paste = true
+  }
+  if (!paste) {
+    const r = await d.signIn(ui, { base, app, env, openUrl: d.openUrl, request: d.request, clock: d.clock })
+    if (r.stopped) return { stopped: true, interrupt: Boolean(r.interrupt) }
+    if (r.approved) return { headers: `${SECRET.header}=${r.key}`, from: 'signin', link: r }
+    paste = r.pressed ? 'pressed' : true
+  }
+  let key = (await ui.secret(KEY_QUESTION)).trim()
+  // After p, an empty answer is more often a stray Enter than a choice to skip: ask once more.
+  if (!key && paste === 'pressed') key = (await ui.secret('Nothing was pasted. Paste your key, or press Enter again to skip:')).trim()
+  // Accept the key as copied, also with the header name or quotes around it.
+  const bare = key.replace(/^["']|["']$/g, '').replace(new RegExp(`^${SECRET.header}\\s*[=:]\\s*`, 'i'), '').trim()
+  return { headers: bare ? `${SECRET.header}=${bare}` : null, from: 'paste', link: null }
+}
+
+/**
+ * A sign-in answer whose ingest address is not the one that this run writes: the app would send to the wrong UKNOWS.
+ * Only a test copy of UKNOWS can get here (UKNOWS_APP_URL without UKNOWS_INGEST_ENDPOINT). The text, or null.
+ */
+function addressMismatch(link, endpoint) {
+  const norm = (u) => { try { const x = new URL(String(u).trim()); return `${x.origin}${x.pathname.replace(/\/+$/, '')}`.toLowerCase() } catch { return null } }
+  if (!link?.ingestEndpoint || !norm(link.ingestEndpoint) || norm(link.ingestEndpoint) === norm(endpoint)) return null
+  return `UKNOWS sends the data of this key to ${link.ingestEndpoint}, but this run would write ${endpoint}. Set ${CLI.endpointEnv}=${link.ingestEndpoint} and run setup again. Nothing changed.`
+}
+
+/** Where the app runs, from the deploy files. */
+function printHosts(ui, detection) {
   ui.print('Runs on:')
   for (const h of detection.hosts) {
     const files = unique(h.evidence.map((e) => e.file))
     ui.print(`  ${hostLabel(h.id)}. ${files.length ? `Found in ${files.join(', ')}.` : 'No deploy files found, so the steps are the general ones.'}`)
   }
+}
+
+function printPlan(ui, plans, detection, changes, commands, opts) {
+  printHosts(ui, detection)
   for (const p of plans) {
     const from = opts.serviceName ? 'from --service-name' : p.s.nameFrom === 'existing' ? 'already set in the repo'
       : p.s.nameFrom === 'folder' ? 'from the folder name' : `from ${p.s.nameFrom}`
@@ -448,9 +1465,12 @@ function printPlan(ui, plans, detection, changes, commands, opts) {
       ui.print(`Plan for ${p.name}:`)
     } else ui.print(`Plan for ${p.name} in ${p.s.dir} (name ${from}):`)
     steps(p).forEach((step, i) => ui.print(`  ${i + 1}. ${step}`))
-    if (p.manual.length) ui.print(`  After this, you do ${plural(p.manual.length, 'step')} by hand: ${p.manual.map((b) => b.title).join('. ')}.`)
+    const required = p.manual.filter((b) => b.required)
+    if (required.length) ui.print(`  After this, you do ${plural(required.length, 'step')} by hand: ${required.map((b) => b.title).join('. ')}.`)
     const chosen = p.s.evidence?.find((e) => e.what.startsWith('Dockerfile for this service: '))
-    if (chosen) ui.print(`  Dockerfile: ${chosen.file}, because ${chosen.what.slice('Dockerfile for this service: '.length)}.`)
+    // "the Dockerfile Dockerfile" reads as a typo: a file whose name says Dockerfile is "the file".
+    const kind = /dockerfile/i.test(chosen?.file.split('/').pop() ?? '') ? 'file' : 'Dockerfile'
+    if (chosen) ui.print(`  This tool uses the ${kind} ${chosen.file} for this service, because ${chosen.what.slice('Dockerfile for this service: '.length)}.`)
     for (const note of [...p.notes, ...p.s.problems.filter((x) => x.code !== 'dockerfile-ambiguous').map((x) => x.message)]) ui.print(`  Note: ${note}`)
   }
   ui.print()
@@ -461,8 +1481,7 @@ function printPlan(ui, plans, detection, changes, commands, opts) {
   if (created.length) ui.print(`Files to add: ${created.join(', ')}`)
   ui.print(`It also writes ${CLI.manifest}, so you can undo this with npx @uknows/setup remove.`)
   // Exactly what changes, before anything does: the diff of every file edit, and what each package manager adds.
-  const out = [...changes.flatMap((c) => unified(c.file, c.before, c.after).split('\n').map(redactKey)),
-    ...commands.map((c) => `${list(c.touches)}: ${c.cmd} adds ${list(c.added ?? [])}.`)]
+  const out = diffLines(changes, commands)
   if (out.length) {
     ui.print()
     ui.print('The changes:')
@@ -471,16 +1490,55 @@ function printPlan(ui, plans, detection, changes, commands, opts) {
     if (out.length > DIFF_LIMIT) ui.print(`And ${plural(out.length - DIFF_LIMIT, 'more line')}. Run with --json to see every planned file.`)
     ui.print()
   }
-  const tools = unique(commands.map((c) => c.cmd))
+  for (const line of runNotes(commands)) ui.print(line)
+}
+
+/** Every line that changes: the diff of each file edit, and what each package manager adds or updates. */
+function diffLines(changes, commands, edits = []) {
+  return [...changes.flatMap((c) => unified(c.file, c.before, c.after).split('\n').map(redactKey)),
+    ...commands.map((c) => (c.kind === 'lock' ? `${list(c.touches)}: ${[c.cmd, ...c.args].join(' ')} updates it.` : `${list(c.touches)}: ${c.cmd} adds ${list(c.added ?? [])}.`)),
+    ...edits.flatMap((e) => unified(e.file, e.before, e.after).split('\n').map(redactKey))]
+}
+
+/** What the package managers and lock refreshes of the plan run, and what they write. */
+function runNotes(commands) {
+  const out = []
+  const installs = commands.filter((c) => c.kind !== 'lock'), locks = commands.filter((c) => c.kind === 'lock')
+  const tools = unique(installs.map((c) => c.cmd))
   if (tools.length) {
-    ui.print(`This runs ${tools.join(' and ')} with install scripts turned off. ${commands.every((c) => c.lockOnly)
-      ? `${tools.length === 1 ? 'It writes' : 'They write'} only ${list(unique(commands.flatMap((c) => c.touches)))}.`
+    out.push(`This runs ${tools.join(' and ')} with install scripts turned off. ${installs.every((c) => c.lockOnly)
+      ? `${tools.length === 1 ? 'It writes' : 'They write'} only ${list(unique(installs.flatMap((c) => c.touches)))}.`
       : `${tools.length === 1 ? 'It downloads' : 'They download'} the packages.`}`)
   }
+  if (locks.length) {
+    // dotnet restore also fills the NuGet folder and writes obj/ folders, which remove does not undo. uv and Poetry write the lock only.
+    const restores = locks.filter((c) => c.cmd === 'dotnet'), others = locks.filter((c) => c.cmd !== 'dotnet')
+    const files = (cs) => list(unique(cs.flatMap((c) => c.touches)))
+    // The note on project build code names only the lock commands of this run.
+    const tools = list(unique(locks.map((c) => `${c.cmd} ${c.args[0]}`)))
+    out.push([`This runs ${list(unique(locks.map((c) => [c.cmd, ...c.args].join(' '))))}.`,
+      ...(others.length ? [fillIn(RESOLVE.writes, { command: list(unique(others.map((c) => `${c.cmd} ${c.args[0]}`))), files: files(others) })] : []),
+      ...(restores.length ? [fillIn(RESOLVE.restoreWrites, { files: files(restores) })] : []), fillIn(RESOLVE.buildCode, { commands: tools })].join(' '))
+  }
+  return out
 }
 
 /** Print the diff of every file this run changed. Returns the --json files list. */
 function printResult(ui, ws, saved, changes, commands) {
+  const { files, out } = resultFiles(ws, saved, changes, commands)
+  ui.print()
+  ui.print(`Done. Changed ${plural(files.length, 'file')}:`)
+  ui.print()
+  for (const line of out.slice(0, DIFF_LIMIT)) ui.print(line)
+  if (out.length > DIFF_LIMIT) ui.print('Run git diff to see the rest.')
+  ui.print()
+  ui.print(`To undo this, run npx @uknows/setup remove. ${CLI.manifest} lists what changed. It has no secrets.`)
+  ui.print()
+  return files
+}
+
+/** The --json files list of what this run changed, and the lines that say how (a diff when it differs from the plan). */
+function resultFiles(ws, saved, changes, commands) {
   const files = [], out = []
   for (const [file, before] of saved) {
     if (file === CLI.manifest) continue
@@ -502,55 +1560,143 @@ function printResult(ui, ws, saved, changes, commands) {
       out.push(...unified(file, a, b).split('\n').map(redactKey))
     }
   }
-  ui.print()
-  ui.print(`Done. Changed ${plural(files.length, 'file')}:`)
-  ui.print()
-  for (const line of out.slice(0, DIFF_LIMIT)) ui.print(line)
-  if (out.length > DIFF_LIMIT) ui.print('Run git diff to see the rest.')
-  ui.print()
-  ui.print(`To undo this, run npx @uknows/setup remove. ${CLI.manifest} lists what changed. It has no secrets.`)
-  ui.print()
-  return files
+  return { files, out }
 }
 
-function printManual(ui, manual, gap = true) {
-  if (!manual.length) return
-  if (gap) ui.print()
-  ui.print(`You need to do ${plural(manual.length, 'more step')}:`)
-  ui.print()
-  for (const block of manual) ui.block(block)
+/** Required steps first, then advice. Only the required steps count toward exit 3. title: another heading for the required steps. */
+function printManual(ui, manual, gap = true, title = null) {
+  const required = manual.filter((b) => b.required), advice = manual.filter((b) => !b.required)
+  for (const [blocks, heading] of [[required, title ?? `You need to do ${plural(required.length, 'more step')}:`], [advice, 'Advice:']]) {
+    if (!blocks.length) continue
+    if (gap) ui.print()
+    gap = true
+    ui.print(heading)
+    ui.print()
+    for (const block of blocks) ui.block(block)
+  }
+}
+
+/**
+ * In a pipeline, setup and remove change nothing, unless --allow-ci. Prints what happened and 1 next step, with the
+ * link to CI/CD and pipelines on /docs. True when it stopped.
+ */
+function stopInCi(ui, report, opts, env = opts.env ?? {}) {
+  const name = ciVariable(opts.env)
+  if (!name || opts.allowCi) return false
+  ui.block({ title: CI_CD.title, lines: [`${name} is set. ${CI_CD.stop}`, fillIn(CI_CD.next, { docs: `${docsUrl(env)}#${CI_CD.id}` }), CI_CD.allowCi] })
+  report.problems.push({ code: 'ci', message: `${name} is set, so this run counts as a pipeline. ${CI_CD.allowCi}` })
+  ui.print('Nothing changed.')
+  return true
 }
 
 const where = (dir) => (dir === '.' ? 'this folder' : dir)
-/** Drop empty lines from a block, so a docs note that is gone never prints as 'undefined'. */
-const tidy = (block) => ({ ...block, lines: block.lines.filter((line) => typeof line === 'string' && line) })
-const steps = (p) => unique([...p.plan.commands.map((c) => c.why), ...p.plan.summary, ...p.settings.summary])
+const fillIn = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+/**
+ * Drop empty lines from a block, so a docs note that is gone never prints as 'undefined'. A block is required
+ * unless its producer says required: false (advice, such as a note on sampling).
+ */
+const tidy = (block) => ({ ...block, lines: block.lines.filter((line) => typeof line === 'string' && line), required: block.required !== false })
+/** Plan sentences: package installs, then the edits, then lock refreshes (they run after the edits), then the settings. */
+const steps = (p) => unique([...p.plan.commands.filter((c) => c.kind !== 'lock').map((c) => c.why), ...p.plan.summary,
+  ...p.plan.commands.filter((c) => c.kind === 'lock').map((c) => c.why), ...p.settings.summary])
 const text = (bytes) => { const t = bytes.toString('utf8'); return t.startsWith(BOM) ? t.slice(1) : t }
 
 function describe(s, withDir = false) {
   const frameworks = s.frameworks.length ? ` (${s.frameworks.map(frameworkLabel).join(', ')})` : ''
-  const start = !s.start ? 'Its start command is not clear.'
-    : s.start.kind === 'package.json' ? `It starts from the start script in ${s.start.file}.`
-      : `It starts from ${s.start.file} line ${s.start.line}.`
+  const start = s.functions ? 'The Azure Functions host starts it.' : !s.start ? 'Its start command is not clear.'
+    : s.start.kind === 'package.json' ? `It starts with the start script in ${s.start.file}.`
+      : s.start.kind === 'dockerfile' ? `It starts with the start command in ${s.start.file} line ${s.start.line}.`
+        : `It starts with ${s.start.file} line ${s.start.line}.`
   return `${stackLabel(s.lang)}${frameworks}${withDir ? ` in ${where(s.dir)}` : ''}. ${start}`
 }
 
 /** A service in the --json report. start never holds the command text. */
 function serviceReport(s, extra = {}) {
-  return { dir: s.dir, lang: s.lang, stack: null, name: s.name, frameworks: s.frameworks,
+  return { dir: s.dir, lang: s.lang, stack: null, mode: s.mode ?? null, name: s.name, frameworks: s.frameworks,
     start: s.start ? { kind: s.start.kind, file: s.start.file, line: s.start.line } : null, settings: null,
     summary: [], commands: [], manual: [], notes: [], otel: [], apm: [], ...extra }
 }
 
-/** Run a package manager. Its output goes to stderr, so --json stdout stays clean. */
-export function runCommand(cmd, args, { cwd }) {
+/**
+ * Probe the local tools that the services can need, once, before planning: uv and Poetry for a Python service when
+ * the repo has their lockfile, dotnet for a locked .NET restore, npm for a Node.js service. Returns name -> version,
+ * or null when missing.
+ */
+function probeTools(d, repo, items) {
+  const tools = {}
+  // The channel mode changes no packages, so it needs no package tool.
+  const active = items.filter((it) => it.mode !== 'stop' && it.mode !== 'otel' && it.mode !== 'channel')
+  if (active.some((it) => it.s.lang === 'python')) {
+    let files = []
+    try { files = repo.files() } catch { /* unreadable */ }
+    for (const [name, re] of Object.entries(TOOLS)) if (files.some((f) => re.test(f))) tools[name] = d.probe(name)
+  }
+  // .NET with a locked restore: dotnet restore refreshes the lock, so it needs an SDK.
+  if (active.some((it) => it.s.lang === 'dotnet' && lockedMode(it.s, repo, webProject(it.s, repo)))) tools.dotnet = d.probe('dotnet')
+  // Node.js: npm here writes the package-lock.json that npm ci in the image reads (stacks/node.mjs npmGuard).
+  if (active.some((it) => it.s.lang === 'node' && it.mode === 'standard')) tools.npm = d.probe('npm')
+  return tools
+}
+
+/**
+ * The version of a local tool from `<cmd> --version`, or null when it is missing or fails. For dotnet, the newest
+ * SDK from `dotnet --list-sdks` (the SDK, not the runtime, restores). Runs nothing else.
+ */
+export function probeTool(cmd) {
+  const args = cmd === 'dotnet' ? ['--list-sdks'] : ['--version']
+  const run = (shell) => spawnSync(cmd, args, { encoding: 'utf8', timeout: 15000, shell, stdio: ['ignore', 'pipe', 'pipe'] })
+  try {
+    let r = run(false)
+    if (r.error?.code === 'ENOENT' && process.platform === 'win32' && /^[\w.-]+$/.test(cmd)) r = run(true)
+    if (r.status !== 0) return null
+    if (cmd === 'dotnet') {
+      const sdks = [...r.stdout.matchAll(/^(\d+\.\d+\.\d+[\w.-]*)\s+\[/gm)].map((m) => m[1])
+      return sdks.sort((a, b) => a.localeCompare(b, 'en', { numeric: true })).at(-1) ?? null
+    }
+    return /(\d+\.\d+(?:\.\d+)?)/.exec(`${r.stdout} ${r.stderr}`)?.[1] ?? '0'
+  } catch { return null }
+}
+
+/**
+ * Why a lock command failed, from its output: the resolver text (uv "No solution found", Poetry "version solving
+ * failed", NuGet "error NU1xxx") and the package it names. null when the output has none of these.
+ */
+export function resolverFailure(command, output) {
+  const lines = output.split(/\r?\n/).map((l) => l.replace(/\u001b\[[0-9;]*m/g, '').trimEnd())
+  const start = lines.findIndex((l) => /No solution found|version solving failed|SolverProblemError|Because .* depends on/.test(l))
+  const nuget = lines.filter((l) => /\berror NU\d{4}\b/.test(l))
+  if (start < 0 && !nuget.length) return null
+  let text = nuget.length ? [...new Set(nuget.map((l) => l.trim()))].slice(0, 5) : []
+  if (start >= 0) {
+    const end = lines.findIndex((l, i) => i > start && !l.trim() && i - start > 1)
+    text = lines.slice(start, end < 0 ? start + 14 : Math.min(end, start + 14)).map((l) => l.trim()).filter(Boolean)
+  }
+  const named = /Because (?:only )?(?:the following versions of )?([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(text.join(' '))?.[1]
+    ?? /Unable to find (?:a stable )?package '?([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(text.join(' '))?.[1]
+    ?? /\b(?:on|for) ([A-Za-z0-9][A-Za-z0-9._-]*) (?:\(|[<>=])/.exec(text.join(' '))?.[1] ?? 'a package'
+  const values = { tool: command.cmd, command: [command.cmd, ...command.args].join(' '), package: named }
+  const fill = (t) => t.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+  return { title: fill(RESOLVE.failed.title), lines: [fill(RESOLVE.failed.lines[0]), ...text.map((l) => `  ${l}`), fill(RESOLVE.failed.lines[1])], package: named }
+}
+
+/**
+ * Run a package manager. Its output goes to stderr, so --json stdout stays clean, or nowhere with quiet (the list of
+ * steps of a run with 1 Yes). The end of the output comes back too (output), so a failed resolver can say why.
+ */
+export function runCommand(cmd, args, { cwd, quiet = false }) {
   return new Promise((resolve) => {
     const shell = process.platform === 'win32'
     if (shell && ![cmd, ...args].every((arg) => SAFE_ARG.test(arg))) return resolve({ code: null, error: 'an argument has characters this tool does not pass to a shell' })
-    let settled = false
-    const finish = (result) => { if (!settled) { settled = true; resolve(result) } }
+    let settled = false, output = ''
+    const finish = (result) => { if (!settled) { settled = true; resolve({ ...result, output }) } }
+    const keep = (chunk) => {
+      if (!quiet) process.stderr.write(chunk)
+      output = (output + chunk.toString('utf8')).slice(-OUTPUT_LIMIT)
+    }
     try {
-      const child = spawnChild(cmd, args, { cwd, stdio: ['ignore', 2, 2], shell })
+      const child = spawnChild(cmd, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], shell })
+      child.stdout.on('data', keep)
+      child.stderr.on('data', keep)
       child.on('error', (error) => finish({ code: null, error: error.code === 'ENOENT' ? `${cmd} was not found` : error.message }))
       child.on('close', (code) => finish({ code, error: null }))
     } catch (error) {