evals 2.7.0 → 2.8.1

package/cli.js

@@ -2,7 +2,7 @@
 
 import React, { useState, useEffect } from 'react';
 import { render, Box, Text, useInput, useApp, Static } from 'ink';
-import { exec, spawn } from 'child_process';
+import { exec, spawn, spawnSync } from 'child_process';
 import {
   existsSync,
   readFileSync,
@@ -62,6 +62,23 @@ const ENV_FILE_NAME = 'harness.env';
 // staged by start.sh can be cleared by `npx evals` and vice versa.
 const BUNDLE_EXTRA_FILES = ['MANIFEST'];
 
+// The Arize agent skills, installed into the chosen agent's *global* skills
+// directory before we spawn it. Doing it here rather than from the prompt is the
+// whole point: a skill installed mid-session is not in the agent's invocable skill
+// list, so the prompt used to have to hunt for `SKILL.md` by path across four
+// possible agent directories. Installed before launch, `arize-instrumentation` is
+// just a skill the agent can call by name.
+//
+// Deliberately fetched rather than vendored like the harness wheel: the skills
+// change far more often than this package publishes, and a user is better served
+// by the current set than by whichever set was current at our last release.
+const SKILLS_PACKAGE = 'Arize-ai/arize-skills';
+
+// Bounded, because this is an enhancement and not a prerequisite — a slow clone
+// must never hold the agent launch hostage. Everything the skills do has a docs
+// fallback in the prompt, so the cost of giving up here is a longer Step 6.
+const SKILLS_TIMEOUT_MS = 120_000;
+
 // Where the prompt and the offline bundle get staged: `~/.arize/onboarding`.
 // Deliberately stable rather than a fresh temp directory. The agent is asked to
 // read a file outside its workspace, and that is an approval a human can grant
@@ -200,18 +217,26 @@ function prepareSeedPrompt() {
   // No "in this project": the launcher may well be run from a home directory, and
   // Step 4 is what scopes the work — an app here, an app at another path, a starter
   // app, or the coding agent itself. Keep this wording in step with start.{sh,ps1}.
-  const seed = `Read the file '${promptFile}' and follow it to set up Arize AX tracing, walking me through each step and asking me questions as needed.`;
+  const seed = `Read the file '${promptFile}' in full with your file-reading tool, not a shell command, then follow it to set up Arize AX tracing, walking me through each step and asking me questions as needed.`;
   return { seed, dir, fellBack };
 }
 
 // Coding agents we can launch interactively, seeded with the prompt.
 // `args(seed)` returns the argv that starts the agent's REPL pre-loaded with `seed`.
+//
+// `skillsAgent` is the name the `skills` CLI knows the agent by, which is its own
+// registry and not ours: our ids are binary names because the shell launchers
+// `exec` them (see the test that pins bin === id), so `cursor-agent` is `cursor`
+// there and `agy` is `antigravity-cli`. Two catalogs, no overlap in naming rules —
+// hence a field rather than a derivation. All five values were verified against
+// that registry; one it doesn't know exits 1 (`Invalid agents: …`), so drift shows
+// up as a skipped install rather than skills landing somewhere unexpected.
 export const AGENTS = [
-  { id: 'claude', label: 'Claude Code', bin: 'claude', args: (s) => [s], installUrl: 'https://docs.claude.com/en/docs/claude-code' },
-  { id: 'codex', label: 'OpenAI Codex', bin: 'codex', args: (s) => [s], installUrl: 'https://developers.openai.com/codex/cli' },
-  { id: 'cursor-agent', label: 'Cursor', bin: 'cursor-agent', args: (s) => [s], installUrl: 'https://docs.cursor.com/en/cli/overview' },
-  { id: 'copilot', label: 'GitHub Copilot', bin: 'copilot', args: (s) => ['-i', s], installUrl: 'https://github.com/features/copilot/cli' },
-  { id: 'agy', label: 'Antigravity CLI', bin: 'agy', args: (s) => ['-i', s], installUrl: 'https://antigravity.google/docs/cli/getting-started' }
+  { id: 'claude', label: 'Claude Code', bin: 'claude', skillsAgent: 'claude-code', args: (s) => [s], installUrl: 'https://docs.claude.com/en/docs/claude-code' },
+  { id: 'codex', label: 'OpenAI Codex', bin: 'codex', skillsAgent: 'codex', args: (s) => [s], installUrl: 'https://developers.openai.com/codex/cli' },
+  { id: 'cursor-agent', label: 'Cursor', bin: 'cursor-agent', skillsAgent: 'cursor', args: (s) => [s], installUrl: 'https://docs.cursor.com/en/cli/overview' },
+  { id: 'copilot', label: 'GitHub Copilot', bin: 'copilot', skillsAgent: 'github-copilot', args: (s) => ['-i', s], installUrl: 'https://github.com/features/copilot/cli' },
+  { id: 'agy', label: 'Antigravity CLI', bin: 'agy', skillsAgent: 'antigravity-cli', args: (s) => ['-i', s], installUrl: 'https://antigravity.google/docs/cli/getting-started' }
 ];
 
 // PATH scan — detects an agent without executing it (running it could hang).
@@ -232,6 +257,40 @@ export function isInstalled(bin) {
   return false;
 }
 
+// argv for the skills install. Two `--yes` flags and they are not a typo: the first
+// is npx's ("don't prompt before fetching the package"), the last is `skills add`'s
+// ("don't prompt for scope or confirmation"). Without both it blocks on a prompt
+// nobody is watching, because we run between the picker unmounting and the agent
+// taking the terminal.
+//
+// `--global` on purpose. Left to itself the CLI auto-detects scope and picks
+// *project* when run inside one, which would write `.claude/skills/` into whatever
+// repo the user happened to launch us from. Global also outlives this session,
+// which is the behaviour someone onboarding to Arize actually wants.
+export function buildSkillsArgs(skillsAgent, pkg = SKILLS_PACKAGE) {
+  return ['--yes', 'skills', 'add', pkg, '--skill', '*', '--agent', skillsAgent, '--global', '--yes'];
+}
+
+// Install the Arize skills for the agent we are about to launch. Returns true only
+// on a clean install. Never throws and never blocks the launch: a false here costs
+// the user a docs-path Step 6, while a throw would cost them the whole flow.
+// Output is captured rather than inherited — the CLI prints a box listing all
+// fourteen skills, which is noise on the last screen before the agent takes over.
+export function installArizeSkills(agent, { run = spawnSync, isWin = process.platform === 'win32' } = {}) {
+  if (!agent || !agent.skillsAgent) return false;
+  try {
+    const result = run('npx', buildSkillsArgs(agent.skillsAgent), {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: SKILLS_TIMEOUT_MS,
+      shell: isWin, // npx is npx.cmd on Windows and needs the shell to resolve
+      encoding: 'utf8',
+    });
+    return result != null && result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
 // "ARIZE AX" on one line — 66 columns wide, so Header() drops to the compact
 // two-row art below 68 and to plain text below 30.
 const largeLogo = `
@@ -473,6 +532,15 @@ function launchAgent(agent) {
     console.log('Instrumenting an app still works; tracing this coding agent (Step 4A) needs a writable home directory.');
   }
 
+  // Before the spawn, so they land in the agent's skill list at session start
+  // rather than mid-flow. Announced first: this clones over the network and can
+  // take a few seconds, and a launcher that goes quiet looks hung.
+  console.log(`\nInstalling the Arize skills for ${agent.label}…`);
+  const skillsInstalled = installArizeSkills(agent);
+  console.log(skillsInstalled
+    ? '  Done.'
+    : '  Skipped — the setup will follow the Arize docs instead.');
+
   console.log(`\nLaunching ${agent.label}…\n`);
 
   const child = spawn(agent.bin, agent.args(prepared.seed), {

package/onboarding-prompt.md

@@ -2,16 +2,28 @@
 
 Guide the user from zero to their first traces in Arize AX. Use the AX CLI, the Arize agent skills, and the official docs.
 
-Work through the flow below in order. Installing the AX CLI and Arize skills, authenticating, and listing your spaces are all fine before approval — those are your own tooling. But do not create AX resources (like API keys), edit application files, or install the app's tracing dependencies before the user approves the plan in Step 5.
+**Read all of this file before you act.** If your tools return only part of it, keep reading to the last line. Rules you need are at the end.
+
+Work through the flow in order. Installing the AX CLI and Arize skills, authenticating, and listing spaces are fine before approval — that is your own tooling. Do not create AX resources (like API keys), edit application files, or install the app's tracing dependencies before the user approves the plan in Step 5.
+
+## How to write to the user
+
+**Use ASD-STE100 Simplified Technical English for all responses.** One idea per sentence, active voice, present tense. Use the simplest word that carries the meaning, and keep the same word for the same thing every time. Aim for 20 words or fewer per sentence.
+
+**Be succinct, not verbose.** Say what you did and what you need next, then stop. No preamble, no restating the step, no describing work first, and no recap of what the user just read. Do not pad with reassurance or apology. If a sentence does not change what the user knows or does, delete it.
+
+Two exceptions. Where a step tells you to send a block as written, send it exactly as written. Never simplify a command, path, or identifier.
+
+**Never let a URL wrap** — a wrapped URL is not clickable. Keep the line to 80 characters or fewer. If a label plus the URL is longer, put the URL alone on the next line. Add no punctuation after a URL.
 
 ## Step 0: Welcome and confirm
 
-Greet the user and show the plan, then ask before doing anything. Send this block as written and nothing else: no added steps, no parentheticals on the ones here (not "browser OAuth", not a folder path), and no preamble about the network check or the approval gate. Both come later in the flow, and explaining them before the user has agreed to anything is noise.
+Greet the user, show the plan, ask before doing anything. Send this block as written and nothing else: no added steps, no preamble about the approval gate. It comes later.
 
 ```text
 Welcome to Arize AX. I'll get you set up with tracing. Here's what I'll do:
 
-1. Install the AX CLI and Arize skills
+1. Install the AX CLI and Arize skills if needed
 2. Create a free Arize AX account or sign you in
 3. Add tracing to an existing app, a new starter app, or this coding agent itself
 
@@ -20,51 +32,83 @@ Shall I proceed?
 
 Do not proceed until the user approves.
 
-## Prerequisites
+## Track progress
 
-**Check network access first.** Every step below needs it: the CLI comes from PyPI, and auth and traces go to Arize. Agent sandboxes often block network by default, and it fails as a hang rather than an error:
+**Track this flow in your task list.** It is long. A task list shows the user how far through they are, and keeps your place if your context is compacted.
 
-```bash
-for h in pypi.org registry.npmjs.org api.arize.com app.arize.com; do
-  code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "https://$h")
-  [ "$code" != "000" ] && echo "$h ok" || echo "$h BLOCKED"
-done
-```
+Find the tool first. Names differ between agents: `TaskCreate` and `TaskUpdate`, `TodoWrite`, or a plan tool. Some agents do not load these tools until you search, so search your tools for "task" or "todo" before you decide you have none.
+
+Create the list as soon as the user approves in Step 0. One task per milestone:
+
+1. Install the AX CLI and Arize skills
+2. Sign in to Arize AX
+3. Select the AX space
+4. Choose what to trace
+
+Add the rest at Step 4, once you know the user's choice. For an existing app or a starter app:
+
+5. Agree the plan
+6. Create the API key and add tracing
+7. Run the app and wait for the first traces
+8. Send the link to the traces
 
-`000` is a DNS or connect failure — your sandbox, not the user's connection.
+For tracing this coding agent:
 
-If anything is blocked, ask your harness to escalate: request network or elevated permissions for the commands that need them, rather than retrying silently or waiting. If escalation is refused or your harness doesn't offer it, stop — with no network this flow cannot complete, so don't retry and don't look for a workaround:
+5. Approve agent tracing
+6. Install harness tracing
+7. Start a new session and wait for traces
+8. Send the link to the traces
+
+Rules:
+
+- One task per milestone. Never add sub-tasks or split a milestone.
+- Keep exactly one task in progress.
+- Mark a task complete when it is done, not when you start it. A list that lags behind is worse than no list.
+- Do not mention the list in chat. Do not print it or say you updated it.
+- Skip this section only if you searched and found no task list tool. Do not print a checklist instead.
+
+## Note
+
+**Every step below needs network access.**
+
+A connection or DNS error from any command means network, not authentication. Do not retry, do not look for a workaround, and do not re-authenticate or recreate a profile. Agent sandboxes often block the network, and the block can look like a hang.
+
+When it happens, ask your harness to escalate: request network or elevated permissions for that command. If it refuses, or offers no escalation, stop and tell the user:
 
 ```text
 My sandbox is blocking network access, so I can't install the CLI or reach
 Arize. Restart me with network access enabled and I'll pick this up.
 ```
 
-Later in the flow, treat a connection or DNS error from any command the same way: it means network, not authentication, so stop and report rather than re-authenticating or recreating a profile.
-
-The AX CLI must be **arize-ax-cli `0.29.0` or newer** (Step 1 installs the latest) and needs **Python 3.11+** — a hard requirement. If Python is missing, stop and have the user install it from https://www.python.org/downloads/ and re-run. **Node.js 18+ with npx** is optional but installs the Arize skills; without it, don't stop — continue and use the docs paths in Step 6 (the Vercel AI SDK v7 starter needs Node.js 22+).
+## Step 1: Install the AX CLI, check the Arize skills
 
-## Step 1: Install or update the AX CLI and Arize skills
-
-Check the version with `ax --version`. If it's missing or older than the version above, install or upgrade `arize-ax-cli` — prefer `pipx`, otherwise pip:
+Check the version with `ax --version`. If it's missing or older than 0.29.0, install or upgrade `arize-ax-cli` — prefer `uv` or `pipx`, otherwise pip:
 
 ```bash
-pipx install arize-ax-cli   # already installed: pipx upgrade arize-ax-cli
-# without pipx:
+uv tool install arize-ax-cli   # already installed: uv tool upgrade arize-ax-cli
+# without uv:
+pipx install arize-ax-cli      # already installed: pipx upgrade arize-ax-cli
+# without either:
 python3 -m pip install --upgrade arize-ax-cli
 ```
 
-If npx is available, install the Arize agent skills; otherwise skip and continue (Step 6 falls back to the docs paths). If the install errors or doesn't finish promptly, skip it and continue rather than waiting — the same fallback applies:
+Try `uv` first, even if `pipx` is installed.
+
+**Check your skill list for `arize-instrumentation` and `arize-link` first.** They are usually installed already. If they are listed, do not run the install — invoke them by name when needed and go to Step 2.
+
+Install them only if they are absent, or you cannot see your skill list, and npx is available:
 
 ```bash
-npx skills add Arize-ai/arize-skills --skill '*' --yes
+npx skills add Arize-ai/arize-skills --skill '*' --global --yes
 ```
 
-This writes the skills to disk but does **not** load them into your current session — a mid-session install is not in your invocable skill list, so don't call it by name. When you need a skill (Step 6), load it by reading its `SKILL.md` directly from the install path (the command prints where it wrote them). Skill directories are named `arize-<name>`, e.g. `arize-instrumentation`.
+Skip this and continue if npx is missing, the install errors, or it does not finish promptly.
+
+A skill installed now does **not** join your skill list, so do not call it by name. Read its `SKILL.md` from the path the command prints. Directories are named `arize-<name>`.
 
 ## Step 2: Authenticate the CLI
 
-The CLI authenticates through a profile named `default`, and every later `ax` command — including the trace check at the end — uses that profile. A bare `ARIZE_API_KEY` in the environment does **not** authenticate the CLI on its own; a profile must exist. Get one working before continuing.
+The CLI authenticates through a profile named `default`, and every later `ax` command uses it. A bare `ARIZE_API_KEY` in the environment does **not** authenticate the CLI; a profile must exist. Get one working before continuing.
 
 First check whether the CLI is already authenticated:
 
@@ -74,15 +118,15 @@ ax spaces list --limit 1 --output json
 
 If this succeeds, a profile is already set up — skip the rest of this step.
 
-If it fails, first check whether a `default` profile already exists from a prior run:
+If it fails, check whether a `default` profile exists from a prior run:
 
 ```bash
 ax profiles list
 ```
 
-If a `default` profile exists but the probe failed, it's signed out or expired, not missing — for an OAuth profile, refresh it with `ax auth login` (see the OAuth handling below) and re-run the probe rather than recreating it. Only create a new profile when none exists (or an existing api-key profile has an invalid key). To create one, look for an existing key first: check for `ARIZE_API_KEY` in the environment **or** the project's `.env` / `.env.local`.
+If a `default` profile exists but the probe failed, it is signed out or expired, not missing — for an OAuth profile, refresh it with `ax auth login` (see below) and re-run the probe rather than recreating it. Only create a profile when none exists, or an api-key profile has an invalid key. To create one, look for an existing key first: check `ARIZE_API_KEY` in the environment **or** the project's `.env` / `.env.local`.
 
-- **A key is available** — the user already has an account and key, so skip the browser flow. Resolve the value (never print it): use `$ARIZE_API_KEY` if it's exported in your shell; if it's only in a dotenv file, load it from there for this one command. Then create an api-key profile and re-run the probe to confirm:
+- **A key is available** — the user has an account and key, so skip the browser flow. Resolve the value, never print it: use `$ARIZE_API_KEY` if exported; if it is only in a dotenv file, load it from there for this one command. Then create an api-key profile and re-run the probe:
 
   ```bash
   # if the key is only in a dotenv file, load it first (nothing is printed);
@@ -91,7 +135,7 @@ If a `default` profile exists but the probe failed, it's signed out or expired,
   ax profiles create default --auth-method api-key --api-key "$ARIZE_API_KEY"
   ```
 
-  Reuse this key throughout — do **not** create a new one in Step 6. Only if the probe passes, though: a stale or wrong-org `ARIZE_API_KEY` still looks present. If it fails, `ax profiles delete default`, take the OAuth path below, and let Step 6 create a key as normal.
+  Reuse this key throughout — do **not** create a new one in Step 6. Only if the probe passes: a stale or wrong-org `ARIZE_API_KEY` still looks present. If it fails, `ax profiles delete default`, take the OAuth path below, and let Step 6 create a key.
 
 - **No key anywhere** — sign up or sign in with browser OAuth:
 
@@ -99,15 +143,15 @@ If a `default` profile exists but the probe failed, it's signed out or expired,
   ax profiles create default --auth-method oauth --utm-params "utm_source=npmevals&utm_medium=cli&utm_campaign=prompt-first-onboarding"
   ```
 
-Pass `--utm-params` verbatim on the two browser OAuth commands that carry it (`profiles create --auth-method oauth` and the `ax auth login` fallback) and add it to no other `ax` command — it tags a new sign-up with onboarding attribution.
+Pass `--utm-params` verbatim on the two browser OAuth commands (`profiles create --auth-method oauth` and the `ax auth login` fallback) and on no other `ax` command — it tags a new sign-up with onboarding attribution.
 
 Always pass the positional profile name `default`. Without it, the CLI prompts `profile name [default]:`, receives EOF from an agent-run command, and exits with `Goodbye!` without creating a profile.
 
 The rest of this step applies only to the **browser OAuth** branch.
 
-Creating an OAuth profile **is** the browser login flow. Treat it as an interactive browser handoff: it opens a browser, starts a localhost callback server such as `127.0.0.1:<port>/callback`, and waits for the browser redirect. The command must stay alive until the redirect lands and the CLI exits on its own.
+Creating an OAuth profile **is** the browser login flow. Treat it as an interactive handoff: it opens a browser, starts a localhost callback server such as `127.0.0.1:<port>/callback`, and waits for the redirect. The command must stay alive until the redirect lands and the CLI exits.
 
-While the OAuth command is waiting, do not close its stdin, send Ctrl-C, `pkill` the AX process, start a second auth command, or run an auth probe. Any of these aborts the in-progress browser flow. There is no exception: every sign-in path — existing account, Google/SSO, existing or brand-new email/password — completes through the same callback, so the command always gets there on its own.
+While the OAuth command is waiting, do not close its stdin, send Ctrl-C, `pkill` the AX process, start a second auth command, or run an auth probe. Any of these aborts the browser flow. There is no exception: every sign-in path — existing account, Google/SSO, existing or new email/password — completes through the same callback, so the command always gets there.
 
 After launching the OAuth command, tell the user:
 
@@ -117,21 +161,21 @@ A browser window is opening for Arize AX sign-in.
 Sign in — or create a new account — in the browser. I'll continue
 automatically once it completes.
 
-Creating a BRAND-NEW account with email and password? Arize emails you a
+Creating a brand new account with email and password? Arize emails you a
 validation link. Click it and finish in the browser; I'll wait.
 ```
 
-Then wait for the command to exit on its own. Treat exit code `0`, or CLI success output such as `Configuration saved to profile 'default'` or `Active profile set`, as the primary completion signal. A new email/password sign-up can sit waiting for a while — the user has to find the validation email — so a long wait is not a hang; leave it alone.
+Then wait for the command to exit. Treat exit code `0`, or success output such as `Configuration saved to profile 'default'` or `Active profile set`, as the completion signal. A new email/password sign-up can wait a while — the user has to find the validation email — so a long wait is not a hang. Leave it alone.
 
-Only after the OAuth command completes, re-run the probe from the top of this step. If it succeeds, continue. If the default OAuth profile already existed and the probe returns an authentication error, the profile is signed out or expired — run the fallback:
+Only after the OAuth command completes, re-run the probe from the top of this step. If it succeeds, continue. If the profile already existed and the probe returns an authentication error, it is signed out or expired — run the fallback:
 
 ```bash
 ax auth login --utm-params "utm_source=npmevals&utm_medium=cli&utm_campaign=prompt-first-onboarding"
 ```
 
-Handle `ax auth login` with the same rules: keep its callback server alive, wait for it to exit or print a success line, then rerun the probe. Do not run `ax auth login` immediately after creating an OAuth profile; the profile creation already performed login.
+Handle `ax auth login` with the same rules: keep its callback server alive, wait for it to exit or print a success line, then rerun the probe. Do not run it immediately after creating an OAuth profile; profile creation already logged in.
 
-Do not treat `ax profiles show` alone as proof that OAuth completed; it can show profile configuration even when the user still needs to authenticate. Use it only for troubleshooting profile configuration, and never with `--expand`.
+Do not treat `ax profiles show` as proof that OAuth completed; it shows configuration even when the user still needs to authenticate. Use it only to troubleshoot configuration, and never with `--expand`.
 
 Run no other remote `ax` command (creating keys, listing all spaces, inspecting resources) until the probe succeeds.
 
@@ -143,9 +187,9 @@ List the spaces the authenticated profile can access:
 ax spaces list --output json
 ```
 
-If `ARIZE_SPACE_ID` is already set (environment or `.env` / `.env.local`), use it **only if it appears in that list** — that confirms the active profile can reach it (the app's existing key and your CLI profile may point at different spaces). If it's set but not in the list, don't trust it; select from the list instead. Otherwise: if exactly one space is returned, use it; if multiple, ask the user which to use; if none, guide the user to create a space in the Arize AX UI (or with an organization ID if available), then re-list.
+If `ARIZE_SPACE_ID` is already set (environment or `.env` / `.env.local`), use it **only if it appears in that list** — that confirms the active profile can reach it, since the app's key and your CLI profile may point at different spaces. If it is set but absent from the list, select from the list instead. Otherwise: one space returned, use it; several, ask the user which; none, guide the user to create one in the Arize AX UI (or with an organization ID if available), then re-list.
 
-Capture the space's **ID** (not its display name) for `ARIZE_SPACE_ID`. The `arize-otel` tracing config requires the space ID; a name will silently fail to route traces.
+Capture the space's **ID**, not its display name, for `ARIZE_SPACE_ID`. `arize-otel` requires the ID; a name silently fails to route traces.
 
 ## Step 4: Choose what to trace
 
@@ -163,25 +207,27 @@ Which one?
 
 If they pick **3**, go to [Step 4A](#step-4a-trace-this-coding-agent) and skip the folder inspection entirely. If they pick **2**, go straight to "Create a starter app" below — don't inspect anything. For **1**, continue.
 
-For options **1** and **2**, one directory ends up being **the app folder**: the app you instrument, which is not always the folder you were launched in. Establish it in this step and use it for every path in Steps 5 to 7.
+You now know the path, so add the remaining tasks to your task list (see "Track progress").
+
+For options **1** and **2**, one directory becomes **the app folder**: the app you instrument, which is not always the folder you were launched in. Establish it here and use it for every path in Steps 5 to 7.
 
 ### Detecting an app
 
-Inspect a candidate folder to decide whether an app already exists. Do not change files during inspection. Look for:
+Inspect a candidate folder to decide whether an app exists. Change no files while inspecting. Look for:
 
 - Python: `pyproject.toml`, `requirements.txt`, `setup.py`, `Pipfile`, imports.
 - TypeScript/JavaScript: `package.json`, lockfiles, `src`, `app`, `pages`, provider imports.
 - Go: `go.mod`. Java: `pom.xml`, `build.gradle`, `build.gradle.kts`.
 - Existing observability: `opentelemetry`, `TracerProvider`, `ARIZE_*`, `OTEL_*`, `OTLP_*`, Datadog, Honeycomb, Sentry, or other tracing.
-- Agent framework: identify it by its import/package — e.g. `langchain` / `langgraph`, `llama_index`, `crewai`, `autogen`, `semantic_kernel`, `pydantic_ai`, `google.adk`, `dspy`, `agent_framework`, and others. **Route on the framework, not the provider client it wraps** — an `openai` or `anthropic` import inside a framework app is not the thing to instrument; the framework almost certainly has its own integration (see Step 6).
+- Agent framework: identify it by its import/package — e.g. `langchain` / `langgraph`, `llama_index`, `crewai`, `autogen`, `semantic_kernel`, `pydantic_ai`, `google.adk`, `dspy`, `agent_framework`, and others. **Route on the framework, not the provider client it wraps** — an `openai` or `anthropic` import inside a framework app is not what to instrument; the framework almost certainly has its own integration (see Step 6).
 
-In a monorepo, check the git root to get oriented, but only instrument apps in or below the folder you are scanning. If the project spans more than one language, instrument each one (route each through its own integration page in Step 6).
+In a monorepo, check the git root to orient yourself, but only instrument apps in or below the folder you are scanning. If the project spans several languages, instrument each one (route each through its own integration page in Step 6).
 
 Run this detection on the current folder first, then branch on what you found.
 
 ### If an app exists in the current folder
 
-Summarize the detected stack and offer both routes — declining the local app must not be a dead end, because the user may well have run this from a folder above the app they care about:
+Summarize the detected stack and offer both routes — declining the local app must not be a dead end, because the user may have started from a folder above the app they care about:
 
 ```text
 I found a <language>/<framework> app in this folder. I can trace that, or an
@@ -197,7 +243,7 @@ On **1**, the app folder is the current folder; continue to Step 5. On **2**, fo
 
 ### If no app exists in the current folder
 
-Do not ask whether to instrument the empty folder, and do not assume a starter app is what they want. Ask for a path first:
+Do not ask whether to instrument the empty folder, and do not assume they want a starter app. Ask for a path first:
 
 ```text
 I don't see an app in this folder. Give me the path to the app you want to
@@ -209,25 +255,25 @@ On a path, follow the next section. On "starter", go to "Create a starter app".
 
 ### If the user gives a path
 
-- Expand `~` and resolve a relative path against the current folder, then confirm the resolved absolute path back to the user before you scan it. A typo caught here beats an API key written into the wrong repo.
-- Run the detection checklist on that folder. If it holds an app, that folder is the app folder from now on — summarize the stack you found there and continue to Step 5.
-- If the path doesn't exist, or exists but has no app in it, say what you actually found and ask for another path. Don't quietly fall through to a starter app.
-- If your own permission or sandbox layer won't let you read and write outside the folder you were launched in, say so plainly instead of half-instrumenting the app. Give the two ways out: the user grants access to that path, or they re-run `npx evals` from inside the app folder.
+- Expand `~` and resolve a relative path against the current folder, then confirm the absolute path back to the user before you scan it. A typo caught here beats an API key written into the wrong repo.
+- Run the detection checklist on that folder. If it holds an app, that folder is the app folder from now on — summarize the stack and continue to Step 5.
+- If the path doesn't exist, or has no app in it, say what you found and ask for another path. Don't quietly fall through to a starter app.
+- If your permission or sandbox layer won't let you read and write outside the folder you were launched in, say so instead of half-instrumenting the app. Give the two ways out: the user grants access to that path, or starts you again inside the app folder.
 
 ### Create a starter app
 
-For option 2, or when the user asks for a starter app after the questions above. Ask which folder to create it in — that folder becomes the app folder — then offer these choices:
+For option 2, or when the user asks for a starter app. Ask which folder to create it in — that becomes the app folder — then offer these choices:
 
-- OpenAI — Python or TypeScript (with a tool call)
-- Anthropic — Python (with a tool call; official AX auto-instrumentation)
-- LangChain with OpenAI — Python or TypeScript (a tool-using agent)
-- Vercel AI SDK with OpenAI — TypeScript (a tool-using agent)
+1. OpenAI — Python or TypeScript (with a tool call)
+2. Anthropic — Python (with a tool call; official AX auto-instrumentation)
+3. LangChain with OpenAI — Python or TypeScript (a tool-using agent)
+4. Vercel AI SDK with OpenAI — TypeScript (a tool-using agent)
 
-If the user picks an unsupported pairing, explain the supported options and ask again.
+If the user picks an unsupported pairing, explain the supported options and ask again. Use the numbers for the picker.
 
 ## Step 4A: Trace this coding agent
 
-Only for option 3. This traces the **agent harness**, not an app: every session the user runs, in every project on this machine. It edits files under their home directory, nothing in the current repo. When done, go to Step 8 — Steps 5 to 7 are app-only.
+Only for tracing this coding agent. This traces the **agent harness**, not an app: every session the user runs, in every project on this machine. It edits files under their home directory, nothing in the current repo. When done, go to Step 8 — Steps 5 to 7 are app-only.
 
 Installer harness names: `claude`, `codex`, `cursor`, `copilot`, `antigravity`, `gemini`, `kiro`, `opencode`, `omp` — note Cursor is `cursor`, not `cursor-agent`, and Antigravity is `antigravity`, not `agy`. Default to the agent you are running inside: state which you are and confirm, rather than asking.
 
@@ -235,13 +281,13 @@ Per-agent setup, including the Claude Code and Cursor marketplace-plugin routes,
 
 ### Check the home directory is writable first
 
-Everything below writes under `~/.arize` — the credentials file, then the harness itself. Confirm that works before asking for approval, so a read-only or restricted home fails here rather than halfway through an install the user already said yes to:
+Everything below writes under `~/.arize` — the credentials file, then the harness. Confirm that works before asking for approval, so a read-only home fails here rather than halfway through an install the user already approved:
 
 ```bash
 mkdir -p ~/.arize/onboarding && touch ~/.arize/onboarding/.probe && rm -f ~/.arize/onboarding/.probe
 ```
 
-If that fails, say so and stop this path — agent tracing needs a writable home and there is no workaround from inside the session. Instrumenting an app (options 1 and 2) does not, so offer that instead. If the launcher already told the user it couldn't use `~/.arize/onboarding`, this is the same cause; don't re-diagnose it.
+If that fails, say so and stop this path — agent tracing needs a writable home and there is no workaround from inside the session. Instrumenting an app (options 1 and 2) does not, so offer that instead. If the user was already told `~/.arize/onboarding` couldn't be used, this is the same cause; don't re-diagnose it.
 
 ### Get approval — this needs its own explicit yes
 
@@ -271,7 +317,7 @@ The installer reads credentials from a dotenv file, keeping the API key out of t
 : > ~/.arize/onboarding/harness.env && chmod 600 ~/.arize/onboarding/harness.env
 ```
 
-Add the Step 3 space ID as file contents, plus one `true` line per category the user **accepted**. Unattended installs capture nothing unless asked to, so a category you omit is off — omit the line for anything they declined:
+Add the Step 3 space ID as file contents, plus one `true` line per category the user **accepted**. Unattended installs capture nothing by default, so omit the line for anything they declined:
 
 ```dotenv
 ARIZE_SPACE_ID=<space-id-from-step-3>
@@ -282,15 +328,17 @@ ARIZE_LOG_TOOL_CONTENT=true
 
 Do **not** set `ARIZE_PROJECT_NAME` — each harness defaults to its own project (`claude-code`, `codex`, …), which keeps two traced agents apart, and you read the real name back after installing. Then create the key into the same file, written atomically and never printed:
 
+Replace <date> with the actual date, to avoid a name clash.
+
 ```bash
-ax api-keys create --name "Coding agent tracing" --env-file ~/.arize/onboarding/harness.env
+ax api-keys create --name "Coding agent tracing <date>" --env-file ~/.arize/onboarding/harness.env
 ```
 
 **Skip that if `ARIZE_API_KEY` already existed in Step 2** — copy the existing value in without echoing it. At most one key, ever.
 
 ### Install, then delete the file
 
-If a directory named `arize-offline/` sits beside this prompt file, install from it — no download, no remote script, so it is faster and far less likely to be refused:
+If a directory named `arize-offline/` sits beside this prompt file, install from it — no download, no remote script, so it is faster and less likely to be refused:
 
 ```bash
 # keep `< /dev/null`: an installer too old for --non-interactive then fails
@@ -308,7 +356,7 @@ ARIZE_ENV_FILE=~/.arize/onboarding/harness.env \
   <harness> --non-interactive < /dev/null
 ```
 
-Delete the env file only once the install has actually run — a retry needs it, and so does the user if they end up running the command:
+Delete the env file only after the install has run — a retry needs it, and so does the user if they run the command themselves:
 
 ```bash
 rm -f ~/.arize/onboarding/harness.env
@@ -346,7 +394,7 @@ A go-ahead authorizes that one command, nothing wider. **Never** frame this as b
 ~/.arize/harness/install.sh status --json
 ```
 
-Exit `0` means configured **and** hooks wired up; `1` nothing configured; `2` configured but hooks missing (the `unregistered` list names which to re-install). Continue only on `0`. Take the project name for polling from `harnesses[].project_name` in the payload rather than guessing it. The payload holds no secrets.
+Exit `0` means configured **and** hooks wired up; `1` nothing configured; `2` configured but hooks missing (the `unregistered` list names which to re-install). Continue only on `0`. Take the polling project name from `harnesses[].project_name` rather than guessing. The payload holds no secrets.
 
 ### Get the first traces
 
@@ -369,9 +417,9 @@ Steps 5 to 7 are for the app paths only; if you took Step 4A, go straight to Ste
 
 Before creating any remote resource, writing files, or installing dependencies, present one consolidated plan and wait for approval.
 
-For an existing app, cover: detected language and framework, package manager, LLM provider or agent framework, any existing tracing to preserve, the env file that will be updated, the instrumentation packages and files that will change, whether a new AX user API key will be created or the existing `ARIZE_API_KEY` reused, and the project name that will be used.
+For an existing app, cover: language and framework, package manager, LLM provider or agent framework, any existing tracing to preserve, the env file to update, the instrumentation packages and files that will change, whether a new API key will be created or the existing `ARIZE_API_KEY` reused, and the project name.
 
-For a starter app, cover: the chosen provider and language, the target folder, the packages that will be installed, and the project name.
+For a starter app, cover: provider and language, target folder, packages to install, and project name.
 
 **State the app folder's absolute path in the plan whenever it isn't the folder you were launched in** — every file you touch lands there, and it's the one detail the user cannot verify from context.
 
@@ -397,11 +445,11 @@ The env file lives in the **app folder** from Step 4. Pick its name to match the
 
 Do not read existing env file contents into chat. Preserve unrelated variables and never reveal their values.
 
-Make sure the env file is git-ignored before writing the API key to it — check the `.gitignore` of the app folder's own repo. If it has one, confirm it covers the file (add `.env` / `.env.local` if not); for a starter app you create, add one. The API key must never be committed to version control.
+Make sure the env file is git-ignored before writing the API key — check the `.gitignore` of the app folder's own repo. If it has one, confirm it covers the file (add `.env` / `.env.local` if not); for a starter app, create one. The API key must never be committed.
 
 ### Write the non-secret variables
 
-Add these two lines to the env file you chose — as file contents, not shell commands. Create the file if needed; if a line already exists, update it in place rather than duplicating. They're not secret. Skip `ARIZE_SPACE_ID` if it's already set to the value you're using.
+Add these two lines to the env file you chose — as file contents, not shell commands. Create the file if needed; if a line exists, update it in place rather than duplicating. Neither is secret. Skip `ARIZE_SPACE_ID` if it already holds the value you are using.
 
 ```dotenv
 ARIZE_SPACE_ID=<space-id>
@@ -414,10 +462,10 @@ An exported variable beats this file — both `dotenv` implementations leave an
 
 **Skip this entirely if `ARIZE_API_KEY` was already present and validated in Step 2** — reuse it and leave its env value untouched. Only create a key when you authenticated with browser OAuth and the app has no key yet.
 
-Create the key and write it into the env file in one step:
+Create the key and write it into the env file in one step. Replace <date> with the actual date, to avoid a name clash.
 
 ```bash
-ax api-keys create --name "Local Arize AX tracing" --env-file .env
+ax api-keys create --name "Local Arize AX tracing <date>" --env-file .env
 ```
 
 `--env-file` writes `ARIZE_API_KEY` atomically and **never prints it** — no temp file, no secret in your terminal or chat. Use `.env.local` if that's the app's convention, and always pass the app folder's path (`--env-file /path/to/app/.env`) — a bare `.env` would leave a stray key file in the wrong directory. The file is created if missing, an existing `ARIZE_API_KEY` is replaced in place, and other variables are preserved.
@@ -429,13 +477,13 @@ If key creation fails, have the user create one in the Arize AX UI and add it to
 Handle the LLM provider's own key (e.g. `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) in the same env file — the app can't make a call or produce traces without it:
 
 - **Existing app:** confirm the key is already present. If it's missing, ask the user for it and add it without echoing the value.
-- **New starter app:** add a placeholder line for the provider key the app needs (e.g. `OPENAI_API_KEY=` with an empty value) to the env file, so the user knows exactly what to fill in. Tell them to set it before running; if they share it now, fill it in without echoing the value.
+- **New starter app:** add a placeholder line for the provider key (e.g. `OPENAI_API_KEY=`) to the env file, so the user knows what to fill in. Tell them to set it before running; if they share it now, fill it in without echoing the value.
 
 ### Add instrumentation
 
-**Prefer the Arize instrumentation skill.** If you installed the skills in Step 1, load it now by reading its `SKILL.md` directly (a mid-session install isn't in your invocable list, so don't call it by name): read `arize-instrumentation/SKILL.md` from your agent's skills directory — project-level (`.claude/skills/`, `.cursor/skills/`, `.codex/…`, `.windsurf/…`) or the matching `~/.<agent>/…` global path. Follow the skill as your source of truth and **skip the rest of this section**. Use the docs fallback below only if the skill file doesn't exist (e.g. npx was missing in Step 1).
+**Prefer the `arize-instrumentation` skill.** Invoke it by name if it is in your skill list. If you installed the skills yourself in Step 1, read `arize-instrumentation/SKILL.md` from the path that install printed. Either way, follow the skill as your source of truth and **skip the rest of this section**. Use the docs fallback below only if you have no skill.
 
-**Route by the framework you detected — search the index for *its* name and follow that page.** Look up the framework you identified in Step 4 (not the provider it wraps) in the index at https://arize.com/docs/ax/integrations (machine-readable: https://arize.com/docs/llms.txt). Most agent frameworks have a dedicated page even though they aren't in the shortcuts below, so actually search the index before concluding a framework is unsupported — it lists every supported provider and framework with the exact, verified setup. Don't force a stack onto a listed framework's setup, and don't wander into unrelated Arize docs once you're on the right page.
+**Route by the framework you detected — search the index for *its* name and follow that page.** Look up the framework from Step 4, not the provider it wraps, in the index at https://arize.com/docs/ax/integrations (machine-readable: https://arize.com/docs/llms.txt). Most agent frameworks have a page even when they are not in the shortcuts below, so search the index before concluding one is unsupported — it lists every supported provider and framework with the exact setup. Don't force a stack onto a listed framework's setup, and don't wander into unrelated Arize docs once you are on the right page.
 
 Common shortcuts:
 
@@ -449,8 +497,8 @@ Common shortcuts:
 **Only if the framework genuinely has no page in the index**, fall back in this order — never hand-roll a raw OpenTelemetry `TracerProvider` + OTLP exporter when a helper exists:
 
 1. Use a framework-specific OpenInference instrumentor if one exists (`openinference-instrumentation-<name>` / `@arizeai/openinference-instrumentation-<name>`), wired up with `arize-otel` per the manual-instrumentation guide; install it unpinned.
-1. Instrument the underlying provider (OpenAI, Anthropic, Bedrock, …) with its instrumentor **only if the framework calls the provider SDK directly**. Many agent frameworks instead drive the model through their own client layer and emit their own OpenTelemetry spans — a provider instrumentor captures **no traces** for those. Never reach for the provider instrumentor as a blind fallback just because you recognize an `openai`/`anthropic` client.
-1. Otherwise instrument manually by code — follow https://arize.com/docs/ax/instrument/manual-instrumentation#by-code — or stop and ask the user if you still can't determine a setup. `arize-otel` gives you a tracer, not LLM spans: **set the OpenInference span kind on every span you create** (`LLM` for a model call, `TOOL` for a tool, `AGENT` for the loop, `CHAIN` for a step), **and set the span status** — `ERROR` with the exception recorded on failure, `OK` otherwise. Without the kind, spans arrive as generic spans that AX cannot read as LLM calls: Step 7's span count comes back non-zero and looks like success while the trace shows no input, output, model, or token counts. Without the status, failed calls look like successful ones and errors never surface in AX.
+1. Instrument the underlying provider (OpenAI, Anthropic, Bedrock, …) with its instrumentor **only if the framework calls the provider SDK directly**. Many agent frameworks drive the model through their own client layer and emit their own OpenTelemetry spans — a provider instrumentor captures **no traces** for those. Never use it as a blind fallback just because you recognize an `openai`/`anthropic` client.
+1. Otherwise instrument manually by code — follow https://arize.com/docs/ax/instrument/manual-instrumentation#by-code — or stop and ask the user if you still cannot determine a setup. `arize-otel` gives you a tracer, not LLM spans: **set the OpenInference span kind on every span** (`LLM` for a model call, `TOOL` for a tool, `AGENT` for the loop, `CHAIN` for a step), **and set the span status** — `ERROR` with the exception recorded on failure, `OK` otherwise. Without the kind, AX cannot read the spans as LLM calls: Step 7's count looks like success while the trace shows no input, output, model, or token counts. Without the status, failed calls look successful and errors never surface in AX.
 
 For existing apps:
 
@@ -462,27 +510,27 @@ For existing apps:
 
 For starter apps:
 
-- Every starter should make a real LLM call that invokes at least one tool (e.g. a calculator or a canned data lookup), with the model deciding to call it and the result fed back for a final answer — so the first traces show a multi-step trajectory (the LLM call plus the tool call as its own span), not one flat span.
+- Every starter must make a real LLM call that invokes at least one tool (e.g. a calculator or a canned lookup), with the model deciding to call it and the result fed back for a final answer — so the first traces show a multi-step trajectory, not one flat span.
   - Agent frameworks (LangChain, Vercel AI SDK): define the tool the framework's way; the instrumentor captures the tool and agent spans automatically.
-  - Plain providers (OpenAI, Anthropic): use the provider's native tool/function calling, and add tool spans with the OpenInference decorators — `@tracer.tool` on the tool function and `@tracer.agent` on the top-level loop. These decorators require wrapping the tracer in `OITracer` from `openinference-instrumentation` (the raw `arize.otel.register()` tracer doesn't expose them and `@tracer.tool` will raise `AttributeError`); see https://arize.com/docs/ax/instrument/manual-instrumentation.
+  - Plain providers (OpenAI, Anthropic): use the provider's native tool/function calling, and add tool spans with the OpenInference decorators — `@tracer.tool` on the tool function and `@tracer.agent` on the top-level loop. These decorators need the tracer wrapped in `OITracer` from `openinference-instrumentation` — the raw `arize.otel.register()` tracer does not expose them and `@tracer.tool` raises `AttributeError`; see https://arize.com/docs/ax/instrument/manual-instrumentation.
 - Ensure short-lived scripts flush/shut down the tracer provider before exit, or spans won't export.
 - Give a clear run command and note which provider key env var is needed.
 
 ### Package guidance
 
-Install into the app's existing environment — the one in the app folder, using its virtualenv if it has one — exactly the packages the detected framework's integration page lists — instrumentor names and peer dependencies differ per framework, so follow that page rather than copying from another stack or guessing versions.
+Install into the app's existing environment — the one in the app folder, using its virtualenv if it has one — exactly the packages the framework's integration page lists. Instrumentor names and peer dependencies differ per framework, so follow that page rather than copying from another stack or guessing versions.
 
 ## Step 7: Run the app and poll for the first trace
 
 First confirm the LLM provider's API key is set in the env file (from Step 6); a missing provider key is the most common reason the run produces no traces.
 
-If you created a starter app in this flow, offer to run it for the user:
+If you created a starter app, offer to run it:
 
 ```text
 Your starter app is ready. Want me to run it for you?
 ```
 
-If they say yes, run it yourself with the run command, then poll. If they say no — or if you instrumented their existing app rather than creating a starter — tell them the exact run command and ask them to run it. When the app folder isn't the folder they're sitting in, lead with the `cd` so the command works as pasted:
+If they say yes, run it and poll. If they say no — or you instrumented their existing app — tell them the exact run command and ask them to run it. When the app folder is not the folder they are sitting in, lead with the `cd` so the command works as pasted:
 
 ```text
 Run your app with:
@@ -494,9 +542,9 @@ It should make at least one LLM call. I'll poll Arize AX and let you know as
 soon as your first traces arrive.
 ```
 
-Once the app has run (whether you ran it or the user did), poll for spans. Pass the actual project name and space ID as literal arguments — do not use `$ARIZE_PROJECT_NAME`/`$ARIZE_SPACE_ID`, which live in the env file and are not exported to your shell. Query every ~15 seconds for up to ~3 minutes.
+Once the app has run, poll for spans. Pass the project name and space ID as literal arguments — do not use `$ARIZE_PROJECT_NAME`/`$ARIZE_SPACE_ID`, which live in the env file and are not exported to your shell. Query every ~15 seconds for up to ~3 minutes.
 
-Span bodies can contain prompts, completions, tool arguments, and user data, so don't dump them into chat. Pipe the export through a counter that surfaces only how many spans arrived:
+Span bodies can contain prompts, completions, tool arguments, and user data, so don't dump them into chat. Pipe the export through a counter that shows only how many spans arrived:
 
 ```bash
 ax spans export "<project-name>" --space "<space-id>" --limit 5 --stdout \
@@ -505,7 +553,7 @@ ax spans export "<project-name>" --space "<space-id>" --limit 5 --stdout \
 
 A non-zero count confirms traces are arriving. If you need to inspect a span to debug, write the export to a file outside the repo and read only the fields you need — never paste raw span bodies into chat.
 
-This uses the CLI profile from Step 2 (OAuth or api-key) — it works the same either way. If the export errors with an authentication failure, the profile isn't valid; re-run the Step 2 probe and re-authenticate, or fall back to having the user open the project in the Arize AX UI to confirm traces.
+This uses the CLI profile from Step 2, OAuth or api-key alike. If the export fails to authenticate, the profile is not valid; re-run the Step 2 probe and re-authenticate, or have the user open the project in the Arize AX UI to confirm traces.
 
 - When spans come back, stop polling and continue to Step 8.
 - On timeout, do not fail silently. Tell the user no traces arrived yet, and give likely causes: app didn't make an LLM call, tracing initialized after the client was created, a short-lived script exited before flushing spans, the wrong space/project/env file, or **an exported `ARIZE_*` variable overriding the env file** (`env | grep ARIZE_`). Offer to re-check once they've run it again.
@@ -514,16 +562,16 @@ Do not fabricate trace results. Only report traces the export command actually r
 
 ## Step 8: Report the first traces with a link
 
-Once spans arrive, report the span count and give the user a deep link to the project in Arize AX. Point them at the UI to explore the trace contents rather than printing span bodies into chat.
+Once spans arrive, report the span count and give the user a deep link to the project in Arize AX. Point them at the UI to explore the traces rather than printing span bodies into chat.
 
-Build that link with the **Arize link skill**: if you installed the skills in Step 1, load it now by reading `arize-link/SKILL.md` from your agent's skills directory (same paths as Step 6) and follow it. It owns the URL format and the `ax` commands that discover the organization and project IDs; you already have the project name and the space ID from Step 3.
+Build that link with the **`arize-link` skill**: invoke it by name, or read `arize-link/SKILL.md` from the path a Step 1 install printed, and follow it. It owns the URL format and the `ax` commands that find the organization and project IDs; you have the project name and space ID from Step 3.
 
 ```text
 Your first traces are in Arize AX. Open project `<ARIZE_PROJECT_NAME>` here:
 <project link>
 ```
 
-If that skill file doesn't exist (e.g. npx was missing in Step 1), don't invent a URL structure: fall back to `https://app.arize.com/` plus instructions to select the project.
+If you have no `arize-link` skill at all, don't invent a URL structure: fall back to `https://app.arize.com/` plus instructions to select the project.
 
 ## Step 9: Point at docs
 
@@ -540,7 +588,8 @@ You're set up. To go further:
 If you took Step 4A, add the controls that matter for agent tracing:
 
 ```text
-- Your agent's tracing page: https://arize.com/docs/ax/integrations/platforms/<agent>/<agent>-tracing
+- Your agent's tracing page:
+https://arize.com/docs/ax/integrations/platforms/<agent>/<agent>-tracing
 - Check it's still wired up: ~/.arize/harness/install.sh status
 - Pause it: set ARIZE_TRACE_ENABLED=false in <agent>'s settings
 - Remove it: ~/.arize/harness/install.sh uninstall <installer-name>
@@ -548,11 +597,12 @@ If you took Step 4A, add the controls that matter for agent tracing:
 
 ## Critical rules
 
+- Keep your task list current if you have one (see "Track progress"): one task per milestone, exactly one in progress, complete only when done, never mentioned in chat.
 - Get the user's approval (Step 5) before creating AX resources, editing files, or installing dependencies.
 - Authenticate the CLI (Step 2) before any other `ax` call; env vars alone don't. Never interrupt a waiting OAuth command — no stdin close, Ctrl-C, `pkill`, or probe. A slow wait is not a hang.
 - Never print, log, or summarize secrets in chat — API keys, env-file contents/values, or span bodies (prompts, completions, tool args, user data) — and never read env files into chat. Only report traces a command actually returned.
 - One AX API key, ever: reuse a **validated** `ARIZE_API_KEY`, else a **single** `ax api-keys create --env-file <file>` into an already-git-ignored file.
-- Ambient `ARIZE_*` variables are claims to verify, not facts to adopt: probe a found API key before reusing it, and remember that an exported variable overrides the env file you write.
+- Ambient `ARIZE_*` variables are claims to verify, not facts to adopt: probe a found API key before reusing it, and remember an exported variable overrides the env file you write.
 - Everything you write goes in the **app folder** (Step 4), which may not be the folder you were launched in. Name its absolute path in the plan; pass it explicitly to `--env-file` and the run command.
 - Write the space **ID** (not its name) to `ARIZE_SPACE_ID`, or traces won't route; never create an AX project explicitly (it's made on first ingestion).
 - Initialize tracing before LLM clients exist; flush before short-lived scripts exit. Vercel AI SDK v7 also needs Node.js 22+, `@ai-sdk/otel` registered, and per-call `experimental_telemetry`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evals",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "description": "Arize AX onboarding — instrument your app with tracing via your coding agent",
   "type": "module",
   "main": "cli.js",

package/start.ps1

@@ -241,7 +241,7 @@ try {
 # where embedded double quotes would not.
 # No "in this project": this may well be run from a home directory, and Step 4 is
 # what scopes the work. Keep this wording in step with cli.js and start.sh.
-$seed = "Read the file '$promptFile' and follow it to set up Arize AX tracing, walking me through each step and asking me questions as needed."
+$seed = "Read the file '$promptFile' in full with your file-reading tool, not a shell command, then follow it to set up Arize AX tracing, walking me through each step and asking me questions as needed."
 
 if (-not $chosen) {
   # Addressed to the person, two lines, recommendation first - see the note in cli.js.

package/start.sh

@@ -272,7 +272,7 @@ fi
 
 # No "in this project": this may well be run from a home directory, and Step 4 is
 # what scopes the work. Keep this wording in step with cli.js and start.ps1.
-SEED="Read the file '$PROMPT_FILE' and follow it to set up Arize AX tracing, walking me through each step and asking me questions as needed."
+SEED="Read the file '$PROMPT_FILE' in full with your file-reading tool, not a shell command, then follow it to set up Arize AX tracing, walking me through each step and asking me questions as needed."
 
 if [[ -z "$CHOSEN" ]]; then
   # Addressed to the person, two lines, recommendation first — see the note in cli.js.

package/vendor/MANIFEST

@@ -1,6 +1,6 @@
 a9cede65f98d3415b13e1c6a437d0fdee27286bfff0186dd72bb65d9869b7864  LICENSE-coding-harness-tracing
 62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775  certifi-2026.7.22-py3-none-any.whl
-e8b1f9519ddf75de49fe5334e9df38e6f76d169fd34be2322e678cce9ecf01e0  coding_harness_tracing-0.1.0-py3-none-any.whl
+e6269ca4232d31c6e3e1cbfc00b4958120378530c26253920a80bcb6ab9c593c  coding_harness_tracing-0.1.0-py3-none-any.whl
 aca14e09ca99c253d2a142e2d5c5c38c8c7cf90840d3cb10b241c29929871fa4  harness-install.bat
 a7ba18a98280e236b20ab4cb9f8a4006068b454586a2af50bf23fb0dbe70583d  harness-install.sh
 b81ee9561e9ca4004139c6cbba3a238c32b03e4894671e181b671e8cb8425d61  python_dotenv-1.2.1-py3-none-any.whl

package/vendor/harness-pin.lock.json

@@ -1,11 +1,11 @@
 {
   "repo": "https://github.com/Arize-ai/coding-harness-tracing",
   "ref": "main",
-  "resolvedSha": "dd3ed1c455daab380e915fc5404a167811c460f0",
+  "resolvedSha": "054e4b8ff444ba4ee1ba2fa74c036999b6986829",
   "source": "git",
   "wheel": "coding_harness_tracing-0.1.0-py3-none-any.whl",
   "wheelVersion": "0.1.0",
-  "wheelSha256": "e8b1f9519ddf75de49fe5334e9df38e6f76d169fd34be2322e678cce9ecf01e0",
+  "wheelSha256": "e6269ca4232d31c6e3e1cbfc00b4958120378530c26253920a80bcb6ab9c593c",
   "files": [
     "LICENSE-coding-harness-tracing",
     "MANIFEST",