@aligndottech/cli 0.37.1 → 0.38.0

package/dist/commands/setup.js

@@ -29,6 +29,9 @@ const { version } = pkg;
 import { printBanner } from '../lib/brand.js';
 import { guardedPrompt } from '../lib/prompt-guard.js';
 import { setupSummaryLine, unresolvedGaps } from '../lib/connect-prompt.js';
+import { createSetupFunnel } from '../lib/setup-funnel.js';
+import { agentAskLine, agentConnectedLine, orderAgents, projectAgentsFromWritten } from '../lib/next-step.js';
+import { firstDecision } from '../lib/first-decision.js';
 const TIER_ORDER = { personal: 0, site: 1, workspace: 2 };
 // How many connectors import concurrently after auth. Each import is itself
 // batch-parallel (runPersonalImport), so this bounds total gateway load.
@@ -334,23 +337,30 @@ async function collectTokens(source, seed = {}, opts = {}) {
  * unmarked default, everything else is explicit.
  */
 export function importRetryHint(sourceId, envName) {
-    return envName === 'prod' ? `align import ${sourceId}` : `align import ${sourceId} --env ${envName}`;
+    return envName === 'prod' ? `align connect ${sourceId}` : `align connect ${sourceId} --env ${envName}`;
 }
+/**
+ * Returns the repo-relative files written (empty when the write failed), so the outro can
+ * tell whether the project .mcp.json - the one that wires Claude Code - actually landed
+ * (ALI-950). Naming an agent as connected off a write that threw would be false.
+ */
 function writeAgentAlignment(envName) {
     try {
         const written = setupAgentAlignment({ cwd: process.cwd(), env: envName });
         p.log.success(`Auto-alignment configured: ${written.join(', ')}`);
         p.log.info(chalk.dim('  A PostToolUse hook will check edits against your decision graph. Claude Code asks ' +
             'once to approve project hooks - accept it to enable automatic alignment.'));
+        return written;
     }
     catch (err) {
         p.log.warn(`Could not write auto-alignment files: ${err.message}`);
+        return [];
     }
 }
 /** Thrown inside the docs block to leave it without starting a read; never surfaces. */
 class SkipDocs extends Error {
 }
-async function runLocalValuePhase(opts = {}) {
+async function runLocalValuePhase(opts) {
     // Without a TTY neither prompt below can work: a piped stdin hangs forever and a closed
     // stdin crashes clack's raw-mode init (uv_tty_init EINVAL) AFTER local setup has already
     // succeeded (align-cli#118). Computed once, up front, and reused by both prompts in this
@@ -362,6 +372,10 @@ async function runLocalValuePhase(opts = {}) {
     const localEnv = config.getEnvironment('local');
     const localClient = createGatewayClient(localEnv);
     const capture = createCaptureCollector();
+    // ALI-949: local setup has begun. Sends now on a re-run (consent already on disk); on a
+    // first run it cannot, and the post-consent offer below is the one that lands. Fire-and-
+    // forget: a slow gateway never delays the value moment.
+    void opts.funnel.started(localEnv);
     // ALI-794: value before questions. Git needs no credential and no consent, so it runs
     // before anything is asked - the found-decisions summary below is what "here is what I
     // found" means, and it has to exist before the agent-wiring/consent/connector steps that
@@ -388,7 +402,7 @@ async function runLocalValuePhase(opts = {}) {
                 repoKnown = gitCount > 0;
                 if (repoKnown) {
                     console.log('');
-                    p.log.info(chalk.dim(`Git: ${gitCount} decisions from ${repo} are already in your graph. \`align import git --env local\` refreshes them.`));
+                    p.log.info(chalk.dim(`Git: ${gitCount} decisions from ${repo} are already in your graph. \`align connect git --env local\` refreshes them.`));
                 }
                 docsKnown = knownDb.hasDocsForRepo(repo);
             }
@@ -465,7 +479,7 @@ async function runLocalValuePhase(opts = {}) {
     // not after them.
     console.log('');
     if (docsKnown) {
-        p.log.info(chalk.dim('Repo docs: already in your graph. `align import docs --env local` refreshes them.'));
+        p.log.info(chalk.dim('Repo docs: already in your graph. `align connect docs --env local` refreshes them.'));
     }
     const localDocsSpinner = p.spinner();
     if (!docsKnown)
@@ -485,6 +499,18 @@ async function runLocalValuePhase(opts = {}) {
                 local: true,
                 funnel: { env: localEnv, source: 'docs' },
             });
+            // ALI-950: a repo can carry decision-shaped docs and no git history worth mining, and
+            // the outro's question must name a decision the wizard FOUND, whichever source found
+            // it. Read back the same way the git summary does, only when git left nothing to name.
+            if (!firstFoundTitle) {
+                const docsDb = createLocalDb(dbPath);
+                try {
+                    firstFoundTitle = buildFoundSummary(docsDb).recent[0]?.title;
+                }
+                finally {
+                    docsDb.close();
+                }
+            }
         }
         else {
             localDocsSpinner.stop('No ADRs or CLAUDE.md/AGENTS.md content found');
@@ -494,36 +520,51 @@ async function runLocalValuePhase(opts = {}) {
         if (!(e instanceof SkipDocs))
             localDocsSpinner.stop(`Docs import skipped - ${e.message}`);
     }
-    writeAgentAlignment('local');
+    const projectAgents = projectAgentsFromWritten(writeAgentAlignment('local'));
     // The agents installed on this machine, not just the ones this project configures. Local
     // setup skipped this and cloud did not, which is backwards: local mode is the one whose
     // entire pitch is an agent on your own machine reading a graph that never leaves it.
     console.log('');
     const localAgents = await connectDetectedAgents('local');
-    // The "try it" nudge (ALI-794): only when something was actually wired, and phrased against
-    // a REAL decision from the summary above when one exists - "why did we X" beats a generic
-    // question because it is checkable against the repo the user is sitting in.
-    if (localAgents.connected > 0) {
+    // ALI-950: whenever ANY agent was wired - the project .mcp.json counts. This used to print
+    // only when a GLOBAL config was written, so a Claude-Code-only user, wired through the
+    // project file a few lines up, never saw it. The question itself moves to the outro's
+    // last line, where it is the one thing left to do.
+    const agents = orderAgents({ project: projectAgents, global: localAgents.wired });
+    const connectedLine = agentConnectedLine(agents);
+    if (connectedLine) {
         console.log('');
-        p.log.info(chalk.dim('Your agent is connected. Try asking:'));
-        p.log.info(chalk.bold(firstFoundTitle ? `  "why did we ${firstFoundTitle}?"` : '  "What decisions exist in this codebase?"'));
+        p.log.info(chalk.dim(connectedLine));
     }
     // ALI-618: one-time, never asked again once answered. Local mode has no account, so consent
     // is the only thing that can ever turn this on - see usage-telemetry.ts's local-embedded
     // branch, which reads this same stored decision.
     await maybeRequestTelemetryConsent(config, Boolean(interactive));
-    return { interactive, config, localEnv, localClient, dbPath, opts, capture };
+    // ALI-949: the first checkpoint at which a local-mode setup_started CAN send - consent is
+    // only now on disk (or was already, on a re-run). The wizard-start offer in runSetup could
+    // not send for a fresh install, so the funnel object is offered the local env again here.
+    void opts.funnel.started(localEnv);
+    return { interactive, config, localEnv, localClient, dbPath, opts, capture, funnel: opts.funnel, agents, firstFoundTitle };
+}
+/** The ids `align connect --source` accepts: every local paste-token source, in picker order. */
+export function localConnectorIds() {
+    return buildSources(false)
+        .filter((s) => s.id !== 'git' && s.tokenLabel)
+        .sort((a, b) => TIER_ORDER[a.tier ?? 'personal'] - TIER_ORDER[b.tier ?? 'personal'])
+        .map((s) => s.id);
 }
 /**
- * The connector-picker tail, shared by every path that reaches local mode: `--local`
- * directly, the login-declined fallback in runCloudSetup, and (ALI-794) the fresh-install
- * flow after the upgrade question comes back "stay local". Split out of runLocalSetup as a
- * pure extraction - this body is byte-identical to what it replaced, just parameterised on
- * the value phase's result instead of closing over local variables (refactoring.md: a pure
- * move changes only how code is reached, never what it does).
+ * The picker-and-import tail of local setup: ask which read-only-token sources to connect,
+ * collect every credential up front, then fetch and import each one. Extracted from
+ * runLocalConnectorPhase for `align connect` (ALI-951), which is this same flow without the
+ * wizard around it - one picker, one paste path, one save rule, in one place. The body is
+ * the wizard's; `preselected`, `seedTokens` and `json` are the only additions, and each is
+ * inert when absent.
  */
-async function runLocalConnectorPhase(ctx) {
-    const { interactive, config, localEnv, localClient, dbPath, opts, capture } = ctx;
+export async function connectLocalSources(o) {
+    const { interactive, config, localEnv, localClient, capture, approve } = o;
+    const quiet = o.json === true;
+    const results = [];
     // Connectors: local mode connects by a read-only token the user mints themselves,
     // for every connector - their personal graph, their credential. OAuth belongs to
     // the personal-cloud path, where the hosted broker holds the client secrets. (This
@@ -538,13 +579,21 @@ async function runLocalConnectorPhase(ctx) {
     const localConnectors = buildSources(false)
         .filter((s) => s.id !== 'git' && s.tokenLabel)
         .sort((a, b) => TIER_ORDER[a.tier ?? 'personal'] - TIER_ORDER[b.tier ?? 'personal']);
-    console.log('');
+    if (o.preselected) {
+        const known = new Set(localConnectors.map((s) => s.id));
+        const unknown = o.preselected.filter((id) => !known.has(id));
+        if (unknown.length) {
+            throw new Error(`Unknown source ${unknown.join(', ')}. --source takes one of: ${[...known].join(', ')}.`);
+        }
+    }
+    if (!quiet)
+        console.log('');
     // Say WHY, at the point of use. This reason used to live only in the comment above:
     // the user was sent to a provider page to mint a token with no explanation, which reads
     // as the tool being clumsy rather than as the privacy trade they chose. The constraint
     // is the provider's, not ours - OAuth needs a client secret, and a secret inside a
     // distributed binary is not a secret. See ALI-778.
-    if (interactive && localConnectors.length > 0) {
+    if (interactive && localConnectors.length > 0 && !quiet) {
         // ONE story, stated as the design it is (Tom, 2026-08-31, superseding ALI-778's
         // local-OAuth direction): this is the user's PERSONAL graph, so the credential is
         // one they mint, scope and can revoke themselves. Earlier versions blamed the
@@ -564,7 +613,7 @@ async function runLocalConnectorPhase(ctx) {
         if (saved?.['token'])
             savedTokens.set(source.id, saved);
     }
-    if (savedTokens.size > 0) {
+    if (savedTokens.size > 0 && !quiet && !o.preselected) {
         const connected = localConnectors.filter((s) => savedTokens.has(s.id));
         const names = connected.map((s) => s.label).join(', ');
         // Named out loud, and left alone: a re-run adds what you pick and touches nothing else.
@@ -575,35 +624,38 @@ async function runLocalConnectorPhase(ctx) {
             p.log.info(chalk.dim(`Connected: ${names} (saved read-only tokens). Select one to re-import it, or to replace its token.`));
         }
         else {
-            const refresh = connected.map((s) => `align import ${s.id} --env local`).join(', ');
+            const refresh = connected.map((s) => `align connect --source ${s.id} --yes`).join(', ');
             p.log.info(chalk.dim(`Connected: ${names} (saved read-only tokens), left alone: no terminal to pick from. Refresh with ${refresh}.`));
         }
     }
-    // `interactive` computed once, at the top of this function - see the comment there.
+    // `interactive` computed once, by the caller - see runLocalValuePhase.
     // ALI-794: the found-summary above sits between this picker and the last clean screen,
     // which is the exact condition that used to corrupt clack's in-place redraw for an
     // outside tester (2026-08-30). Clear first so the picker gets its own canvas.
-    if (interactive)
+    const askPicker = interactive && !o.preselected;
+    if (askPicker)
         clearScreenForPicker();
     // A windowed list ends in "..." and reads as cut off; the count turns it into "scroll".
     const maxItems = pickerMaxItems(process.stdout.rows, localConnectors.length);
     const windowed = maxItems < localConnectors.length;
-    const selected = interactive
-        ? await p.multiselect({
-            message: `Connect more sources with a read-only token? (skip to finish${windowed ? `; ${localConnectors.length} sources, scroll for more` : ''})`,
-            options: localConnectors.map((s) => ({
-                value: s.id,
-                label: s.label,
-                // A connected connector stays in the list so it can be re-imported, or its expired
-                // token replaced, without a separate command. Not selecting it leaves it alone.
-                hint: savedTokens.has(s.id) ? 'connected - select to re-import' : s.description,
-            })),
-            required: false,
-            // Without maxItems clack renders all eight and its in-place redraw miscounts
-            // once the list is taller than the viewport, painting duplicate rows.
-            maxItems,
-        })
-        : [];
+    const selected = o.preselected
+        ? o.preselected
+        : askPicker
+            ? await p.multiselect({
+                message: `Connect more sources with a read-only token? (skip to finish${windowed ? `; ${localConnectors.length} sources, scroll for more` : ''})`,
+                options: localConnectors.map((s) => ({
+                    value: s.id,
+                    label: s.label,
+                    // A connected connector stays in the list so it can be re-imported, or its expired
+                    // token replaced, without a separate command. Not selecting it leaves it alone.
+                    hint: savedTokens.has(s.id) ? 'connected - select to re-import' : s.description,
+                })),
+                required: false,
+                // Without maxItems clack renders all eight and its in-place redraw miscounts
+                // once the list is taller than the viewport, painting duplicate rows.
+                maxItems,
+            })
+            : [];
     // Collect every credential up front, so the automatic phase below never stops to ask.
     const localReady = [];
     if (!p.isCancel(selected)) {
@@ -612,17 +664,23 @@ async function runLocalConnectorPhase(ctx) {
             const source = localConnectors.find((s) => s.id === id);
             if (!source)
                 continue;
-            console.log('');
-            p.log.step(chalk.bold(source.label));
+            if (!quiet) {
+                console.log('');
+                p.log.step(chalk.bold(source.label));
+            }
             // Jira and Confluence share one Atlassian account: same email, same site
             // domain, same id.atlassian.com API token. Ask once, reuse for the other, and
             // SAY so - the same disclosure rule as the gh-token reuse, because a silently
             // absorbed credential is the thing nobody can audit afterwards.
             const isAtlassian = source.id === 'jira' || source.id === 'confluence';
             let seed = isAtlassian ? { ...atlassianShared } : {};
-            if (isAtlassian && seed['token'] !== undefined) {
+            if (isAtlassian && seed['token'] !== undefined && !quiet) {
                 p.log.info(chalk.dim('  Using your Atlassian email, domain and API token from the previous connector.'));
             }
+            // ALI-951: `--token` (and any other field a flag supplied) seeds every preselected
+            // source the way the Atlassian reuse above does - a seeded field is never asked for.
+            if (o.seedTokens)
+                seed = { ...seed, ...o.seedTokens };
             // A connected connector that was selected: re-import with the saved token unless the
             // user wants to replace it. Seeding collectTokens with the saved fields is what skips
             // every paste; an empty seed is what asks for them. --approve never stops to ask.
@@ -633,7 +691,7 @@ async function runLocalConnectorPhase(ctx) {
             const saved = savedTokens.get(source.id);
             let reused = false;
             if (saved && seed['token'] === undefined) {
-                const reuse = opts.approve
+                const reuse = approve
                     ? true
                     : await p.confirm({
                         message: source.tokenShortLived
@@ -648,7 +706,19 @@ async function runLocalConnectorPhase(ctx) {
                     reused = true;
                 }
             }
-            const tokens = await collectTokens(source, seed, { approve: opts.approve });
+            // ALI-951: with no terminal there is nothing to paste into. Name the flag rather than
+            // letting clack crash on a closed stdin, which reads as the tool breaking (align-cli#118).
+            if (!interactive) {
+                const missing = (source.extraFields ?? []).map((f) => f.key).filter((k) => seed[k] === undefined);
+                if (source.tokenLabel && seed['token'] === undefined)
+                    missing.push('token');
+                if (missing.length) {
+                    const fieldFlags = missing.filter((k) => k !== 'token').map((k) => `--${k} <${k}>`);
+                    throw new Error(`${source.label} needs a ${source.tokenLabel ?? 'token'} and there is no terminal to paste one into. ` +
+                        `Pass --token <token>${fieldFlags.length ? `, or run align connect ${source.id} ${fieldFlags.join(' ')} --token <token>` : ''}.`);
+                }
+            }
+            const tokens = await collectTokens(source, seed, { approve });
             if (!tokens)
                 continue;
             if (isAtlassian) {
@@ -665,7 +735,7 @@ async function runLocalConnectorPhase(ctx) {
     // found" moment, not stranded behind the questions this phase exists to ask. This phase
     // is only the automatic import for the paste-token connectors just collected.
     for (const { source, tokens, reused } of localReady) {
-        const spinner = p.spinner();
+        const spinner = quiet ? { start() { }, stop() { } } : p.spinner();
         spinner.start(`Fetching from ${source.label}...`);
         try {
             const fetched = await source.fetch(tokens);
@@ -677,15 +747,19 @@ async function runLocalConnectorPhase(ctx) {
             // there is one rule here rather than a branch that has to stay in step with the reuse.
             config.saveConnectorFields('local', source.id, tokens);
             spinner.stop(`Found ${items.length} items`);
+            let imported = 0;
             if (items.length) {
-                await runPersonalImport(items, localClient, {
+                imported = await runPersonalImport(items, localClient, {
                     label: source.label,
                     approve: true,
                     appUrl: resolveAppUrl(localEnv),
                     local: true,
+                    quiet: quiet || undefined,
+                    silent: quiet || undefined,
                     funnel: { env: localEnv, source: source.id },
                 });
             }
+            results.push({ id: source.id, label: source.label, found: items.length, imported });
         }
         catch (e) {
             const msg = e.message;
@@ -700,8 +774,14 @@ async function runLocalConnectorPhase(ctx) {
             else {
                 spinner.stop(`Skipped ${source.label} - ${msg}`);
             }
+            results.push({ id: source.id, label: source.label, found: 0, imported: 0, error: msg });
         }
     }
+    return results;
+}
+async function runLocalConnectorPhase(ctx) {
+    const { interactive, config, localEnv, localClient, dbPath, opts, capture, funnel, agents, firstFoundTitle } = ctx;
+    await connectLocalSources({ interactive, config, localEnv, localClient, capture, approve: opts.approve ?? false });
     // ALI-827: what each source fetched and what it could not reach - once, after every
     // import has printed its own line, so the numbers sit together. A source whose fetch
     // THREW is not in it: its spinner line above already named the error, and a row of
@@ -733,7 +813,7 @@ async function runLocalConnectorPhase(ctx) {
             ? `export ${chalk.bold('ALIGN_ENV=local')} (or unset it)`
             : `run ${chalk.bold('align env set local')} to make local the default ` +
                 `(${chalk.dim(`align env set ${bareEnv}`)} switches back)`;
-        p.log.warn(`Bare commands (align ask, align import ...) use the ${bareEnv} cloud graph, not this local one, because ${cause}.\n` +
+        p.log.warn(`Bare commands (align ask, align connect ...) use the ${bareEnv} cloud graph, not this local one, because ${cause}.\n` +
             `Add ${chalk.bold('--env local')} per command, or ${remedy}.`);
     }
     // ALI-796: the graph names its own gaps - a ref whose platform has no connected
@@ -744,19 +824,24 @@ async function runLocalConnectorPhase(ctx) {
     const gaps = unresolvedGaps(refsDb.getAllRefs(), isConnected);
     refsDb.close();
     const gapLine = setupSummaryLine(gaps);
+    // ALI-950: the last line is the next step, and it happens in the agent - named, with a
+    // question about a decision the wizard just found, and no CLI verb. This used to end on
+    // `align ask "why <a thing you decided>"`, a prompt verb on the one screen whose job is to
+    // send the user into their agent. The gap line, when there is one, sits above it.
     p.outro(`${chalk.green('You are set up in local mode.')}\n` +
         `  Graph: ${chalk.dim(dbPath)}\n` +
-        `  Run ${chalk.bold('align')} any time to see your graph and what to do next.\n` +
-        // Deliberately NOT "What decisions exist in this codebase?", which this line used to
-        // suggest. That question is ABOUT the graph rather than IN it, so on-device search
-        // matches nothing and a tester was told his freshly imported graph was empty (ALI-771).
-        // It is a fine thing to ask an AGENT over MCP, and a bad first thing to type here.
-        `  Ask it something real: ${chalk.bold('align ask "why <a thing you decided>"')}${gapLine ? `\n\n  ${chalk.dim(gapLine)}` : ''}`);
+        `  Run ${chalk.bold('align')} any time to see your graph and what to do next.` +
+        `${gapLine ? `\n\n  ${chalk.dim(gapLine)}` : ''}\n\n` +
+        `  ${chalk.bold(agentAskLine({ agents, firstTitle: firstFoundTitle, inRepo: true, envName: 'local' }))}`);
+    // ALI-949: after the outro, never before it - telemetry must not delay what the user is
+    // waiting for. Awaited (unlike the other emitters) because this is the wizard's last act
+    // and the one row the funnel was blind to; there is nothing left for a 2s worst case to hold up.
+    await funnel.completed(localEnv);
 }
 // Local-embedded onboarding (opt-in via --local): no account, no cloud, no OAuth. Composes
 // the two phases above unchanged - this is exactly what ran before the ALI-794 split, just
 // as two calls instead of one function body.
-async function runLocalSetup(opts = {}) {
+async function runLocalSetup(opts) {
     const ctx = await runLocalValuePhase(opts);
     await runLocalConnectorPhase(ctx);
 }
@@ -787,11 +872,18 @@ export async function runSetup(opts = {}) {
     // The one place a full brand moment belongs: first run, before any questions.
     printBanner({ version });
     p.intro(commandIntro('align setup'));
+    // ALI-949: the wizard's setup_started / setup_completed emitter. NOT offered an env
+    // here, where the mode is still unknown: a `--local` run on a machine holding a cloud
+    // token would report a cloud setup_started for an explicitly offline session (review on
+    // #279). Each mode branch offers its own env at its top - runLocalValuePhase and
+    // runCloudSetup - and again once consent / login makes a send possible.
+    const funnel = createSetupFunnel();
     // ---- Step 0: Cloud (default) vs local (--local) ----
-    // Solo defaults to a personal CLOUD tenant: telemetry, the real cloud
-    // relationship classifier, backup, and a clean upgrade path to a team
-    // (reuses the personal->org join flow). --local is the opt-in offline
-    // escape hatch; --approve runs the cloud path non-interactively.
+    // Solo defaults to CLOUD: telemetry, the real cloud relationship classifier, backup.
+    // A work email lands you in the tenant already registered for that domain (or creates
+    // one, admin if first); a personal email gets a tenant of one, with a web-only invite
+    // path into a company tenant later (reuses the personal->org join flow). --local is
+    // the opt-in offline escape hatch; --approve runs the cloud path non-interactively.
     //
     // ALI-794: on a genuinely fresh machine (neither mode configured yet), interactively,
     // with neither flag forcing a mode, invert this - build the local graph and show what
@@ -799,7 +891,7 @@ export async function runSetup(opts = {}) {
     // not asked to sit through that again; they keep the question below, same as today.
     const interactive = process.stdin.isTTY && process.stdout.isTTY;
     if (!opts.local && !opts.approve && interactive && isFreshInstall(config)) {
-        await runFreshSetup({ config, env, client, envName, opts });
+        await runFreshSetup({ config, env, client, envName, opts, funnel });
         return;
     }
     let mode;
@@ -813,7 +905,7 @@ export async function runSetup(opts = {}) {
         const choice = await p.select({
             message: 'How are you using Align?',
             options: [
-                { value: 'cloud', label: 'Cloud (recommended) - your personal decision graph', hint: 'syncs, backed up, upgradeable to a team' },
+                { value: 'cloud', label: 'Cloud (recommended) - your personal decision graph', hint: "work email: your company's graph; personal email: just you" },
                 { value: 'local', label: 'Local only - private, offline, no account', hint: 'stays on this machine (--local)' },
             ],
             initialValue: 'cloud',
@@ -825,10 +917,10 @@ export async function runSetup(opts = {}) {
         mode = choice;
     }
     if (mode === 'local') {
-        await runLocalSetup({ approve: opts.approve });
+        await runLocalSetup({ approve: opts.approve, funnel });
         return;
     }
-    await runCloudSetup({ opts, config, env, client, envName });
+    await runCloudSetup({ opts, config, env, client, envName, funnel });
 }
 /**
  * ALI-794: the value-first fresh-install flow. Builds and shows the local graph with
@@ -841,22 +933,24 @@ export async function runSetup(opts = {}) {
  * provisional state (component 1's "nothing about the cloud path changes once chosen").
  */
 async function runFreshSetup(ctx) {
-    const phase = await runLocalValuePhase({ approve: ctx.opts.approve });
+    const phase = await runLocalValuePhase({ approve: ctx.opts.approve, funnel: ctx.funnel });
     // The value phase's capture report is printed by runLocalConnectorPhase, so choosing
     // cloud below drops it - deliberately: runCloudSetup re-imports git and docs into the
     // cloud tenant and prints its own report, which is the one that describes that graph.
     // Framed by what the graph is missing, not "how are you using Align" in the abstract -
     // there is already a local graph on screen, so the question is whether to extend it.
     //
-    // "A path to team sharing", never "for team sharing": choosing cloud creates a
-    // PERSONAL tenant (the option's hint says so) and a team is a separate join/upgrade
-    // later. The question and the option below must keep agreeing on that - the question
+    // "A path to team sharing", never "for team sharing": choosing cloud on a personal
+    // email creates a tenant of one (the option's hint says so), and joining a team is a
+    // separate web invite later. A work email already lands you in the shared tenant,
+    // which is why the hint distinguishes them rather than promising a generic upgrade.
+    // The question and the option below must keep agreeing on that - the question
     // overclaimed for a while and a live tester read it as sharing starting here.
     const choice = await p.select({
         message: 'Stay local, or sync to the cloud for backup, richer detection, and a path to team sharing?',
         options: [
             { value: 'local', label: 'Stay local - keep what you just built, private and offline', hint: 'no account' },
-            { value: 'cloud', label: 'Sync to the cloud - backup, team upgrade path, richer detection', hint: 'personal tenant' },
+            { value: 'cloud', label: 'Sync to the cloud - backup, team upgrade path, richer detection', hint: "work email: your company's graph; personal email: just you" },
         ],
         initialValue: 'local',
     });
@@ -874,7 +968,7 @@ async function runFreshSetup(ctx) {
 // then offer personal-scoped connectors. A personal-email login lands on an
 // isolated personal tenant server-side; connectors auto-bind to it.
 async function runCloudSetup(ctx) {
-    const { opts, config, env, envName } = ctx;
+    const { opts, config, env, envName, funnel } = ctx;
     let client = ctx.client;
     // ---- Step 1: Auth check (inline login when interactive + unauthenticated) ----
     const authSpinner = p.spinner();
@@ -882,6 +976,12 @@ async function runCloudSetup(ctx) {
     try {
         const me = await client.whoami();
         authSpinner.stop(`Logged in as ${me.user.email} (${me.tenant?.name ?? envName})`);
+        // ALI-949: cloud setup has begun, and the token is proven good. Offered only AFTER
+        // whoami (Copilot on #279): a stale stored token passes the emitter's token check, so an
+        // earlier offer would send a request the gateway rejects, count as sent, and suppress the
+        // post-login offer below that would have landed. Reached from every route into cloud
+        // setup, including the fresh-install upgrade question.
+        void funnel.started(config.getEnvironment(envName));
     }
     catch {
         authSpinner.stop('Not authenticated');
@@ -899,12 +999,15 @@ async function runCloudSetup(ctx) {
             }
             // Re-create the client so it carries the freshly stored token.
             client = createGatewayClient(config.getEnvironment(envName));
+            // ALI-949: the first checkpoint at which a fresh cloud install's setup_started CAN
+            // send - the token exists now. `env` above is the pre-login snapshot, so re-read.
+            void funnel.started(config.getEnvironment(envName));
         }
         else {
             // Declined cloud login: offer the local escape hatch instead of failing.
             const wantLocal = await p.confirm({ message: 'Set up local-only mode instead? (no account, stays on this machine)' });
             if (!p.isCancel(wantLocal) && wantLocal) {
-                await runLocalSetup({ approve: opts.approve });
+                await runLocalSetup({ approve: opts.approve, funnel });
                 return;
             }
             p.log.warn(`Run ${chalk.bold('align login')} when ready, then ${chalk.bold('align setup')}.`);
@@ -1017,9 +1120,11 @@ async function runCloudSetup(ctx) {
     // `align mcp --remove` as the undo. This block used to write to a user-level config without
     // a word when exactly one editor was detected and prompt only at two or more, and that
     // multiselect was unguarded, so `align setup --approve` with two agents installed hung.
-    const agents = await connectDetectedAgents(envName);
+    const globalAgents = await connectDetectedAgents(envName);
     // ---- Step 5b: Deterministic auto-alignment files (hook + nudges) ----
-    writeAgentAlignment(envName);
+    const projectAgents = projectAgentsFromWritten(writeAgentAlignment(envName));
+    // ALI-950: project config first - it is the one the user is most likely sitting in.
+    const agents = orderAgents({ project: projectAgents, global: globalAgents.wired });
     // ---- Step 6: Git auto-import (zero-auth baseline graph seed) ----
     let totalDecisions = 0;
     const sourcesImported = [];
@@ -1200,34 +1305,38 @@ async function runCloudSetup(ctx) {
     // ---- Outro ----
     const decisionsLine = totalDecisions > 0
         ? `  ${totalDecisions} decisions in your graph`
-        : `  No decisions yet - run ${chalk.bold('align import')} to load your history`;
+        : `  No decisions yet - run ${chalk.bold('align connect')} to load your history`;
     const sourceLine = sourcesImported.length > 0
         ? `\n  Sources: ${sourcesImported.join(', ')}`
         : '';
-    // ---- Step 8: First-query prompt ----
-    // Only when something was actually WIRED, not merely detected: telling someone their agent
-    // is connected when they declined the prompt would be false.
-    //
-    // The question stays as it is, deliberately. ALI-771 removed it from the LOCAL outro
-    // because typing it into `align ask` matches nothing - it is about the graph rather than in
-    // it. Asked of an AGENT over MCP it is a good opening question, because the agent answers
-    // it by calling a list tool rather than a similarity search. Different surface, different
-    // advice.
-    if (agents.connected > 0) {
+    // ---- Step 8: the agent is connected, and the next step is in it (ALI-950) ----
+    // Only when something was actually WIRED, not merely detected - and the project .mcp.json
+    // counts, which it did not before: this printed only for a global config, so a
+    // Claude-Code-only user never saw it.
+    const connectedLine = agentConnectedLine(agents);
+    if (connectedLine) {
         console.log('');
-        p.log.info(chalk.dim('Your agent is connected. Try asking:'));
-        p.log.info(chalk.bold('  "What decisions exist in this codebase?"'));
+        p.log.info(chalk.dim(connectedLine));
     }
+    // The question names a decision the wizard just put in the graph, read straight back
+    // rather than trusting the import's tally (same rule as the local found-summary). Only
+    // worth a request when something was imported.
+    const firstFoundTitle = totalDecisions > 0 ? (await firstDecision(client)).firstTitle : undefined;
+    // The last line is the next step, in the agent, with no CLI verb. It used to be
+    // `Run: align ask "any question about your codebase"`.
     const outroText = [
         chalk.bold('Setup complete.\n'),
         decisionsLine,
         sourceLine,
-        `\n\n  Run: ${chalk.bold('align ask "any question about your codebase"')}`,
         chalk.dim('\n\n  Want your whole team on a shared decision graph?'),
         chalk.dim('\n  Upgrade by accepting a team invite - your decisions come with you'),
         chalk.dim('\n  (you reconnect your connectors once in the team workspace).'),
         chalk.dim('\n  https://app.align.tech/pricing'),
+        `\n\n  ${chalk.bold(agentAskLine({ agents, firstTitle: firstFoundTitle, inRepo: true, envName }))}`,
     ].join('');
     p.outro(outroText);
+    // ALI-949: after the outro, and against the env as it is NOW (the inline login above may
+    // have stored the token after `env` was read). See runLocalConnectorPhase for why awaited.
+    await funnel.completed(config.getEnvironment(envName));
 }
 //# sourceMappingURL=setup.js.map