@jacebenson/jsn 4.3.9 → 4.3.10-dev.67

package/src/commands/auth.js

@@ -1,65 +1,97 @@
-import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile, setProfile } from '../config.js';
+import { getEffectiveInstance, normalizeInstanceURL, saveConfig, setActiveProfile } from '../config.js';
 import { errUsage, errUsageHint } from '../errors.js';
-import { canUsePicker } from '../helpers.js';
+import { canUsePicker, formatCommandList, quoteShellArg } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 import process from 'node:process';
+import { refreshSession } from '../session.js';
+
+function syncSession(app) {
+  if (typeof app._buildSdk === 'function' && typeof app.loadContext === 'function') refreshSession(app);
+}
 
 // Auth manages local credentials/profiles — runs without a configured
 // instance. (Not in the daily-check skip-list: legacy behavior checks for
 // updates here.)
-declareCapabilities('auth', { noInstance: true });
+declareCapabilities('auth', { noInstance: true, skipContextHeader: true });
 
-/**
- * Render the `jsn auth status` styled (TTY) view: one line per profile with
- * default marker, auth ✓/✗, 🔒 read_only, ⚡ skip_confirmations, ✅/⚠️
- * live-verification, and stale-last-seen hints.
- *
- * This view logic lives in the auth command — NOT in src/output.js — and is
- * shipped to the OutputWriter as `data._formatted` (the documented escape
- * hatch for command-curated visuals; see the interface comment in
- * src/output.js). The `summary` line is folded into the formatted string
- * because the writer suppresses opts.summary when _formatted is present.
- * Golden-pinned by test/auth.test.js ("auth status styled output").
- */
-export function renderAuthStatus(result, summary) {
-  let out = summary ? `${summary}\n\n` : '';
+/** Render a compact status table; identity fields require explicit details. */
+export function renderAuthStatus(result, summary, { details = false } = {}) {
   const profiles = Array.isArray(result.profiles) ? result.profiles : [];
-  if (profiles.length > 0) {
-    out += '\n';
-    for (const p of profiles) {
-      const prefix = p.default ? '* ' : '  ';
-      const authIcon = p.authenticated ? '✓' : '✗';
-
-      // Show verified status if we got one
-      let verifiedStr = '';
-      if (p.verified === true) {
-        verifiedStr = ' ✅';
-      } else if (p.verified === false) {
-        verifiedStr = ' ⚠️';
-      }
-
-      // Show stale hint if >7 days since last seen
-      let staleStr = '';
-      if (p.stale && p.days_since_last_seen) {
-        staleStr = ` (${p.days_since_last_seen}d ago — may have been released)`;
-      }
-
-      // Show lock icon for read-only profiles
-      const lockIcon = p.read_only ? ' 🔒' : '';
+  if (!profiles.length) return 'No profiles configured.\nRun: jsn auth login <instance> --browser\n';
+  const methods = { oauth: 'OAuth', basic: 'Basic', gck: 'Browser session' };
+  const states = { available: 'Available', missing: 'Missing', expired: 'Expired', refreshable: 'Refresh required', malformed: 'Invalid' };
+  const headings = ['PROFILE', 'AUTH', 'CREDENTIALS', 'CONNECTION', 'ACCESS', 'DELETES', 'COUNTS'];
+  if (details) headings.push('USER', 'INSTANCE');
+  const notes = [];
+  const rows = profiles.map((profile, index) => {
+    const diagnostics = profile.diagnostics || {};
+    const probe = diagnostics.probe || {};
+    const label = profile.name || `Profile ${index + 1}`;
+    const connection = profile.verified === true ? 'Verified'
+      : probe.code === 'account_mismatch' ? 'User mismatch'
+      : profile.verified === false ? 'Failed' : 'Not checked';
+    const row = [
+      `${label}${profile.active ? ' *' : ''}${profile.default ? ' (default)' : ''}`,
+      methods[diagnostics.auth_method] || 'Not configured',
+      states[diagnostics.state] || (profile.authenticated ? 'Available' : 'Missing'),
+      connection,
+      profile.read_only ? 'Read-only' : 'Read/write',
+      profile.skip_confirmations ? 'No prompt' : 'Confirm',
+      profile.include_counts === false ? 'Off' : 'On',
+    ];
+    if (details) {
+      const user = profile.username || profile.verified_as || 'Not recorded';
+      row.push(`${user}${profile.verified_as && profile.verified_as !== user ? ` (session: ${profile.verified_as})` : ''}`, profile.instance || 'Not configured');
+    }
+    if (profile.verified !== true && probe.message) notes.push(`${label}: ${probe.message}`);
+    if (profile.name && profile.verified !== true) {
+      const command = `jsn auth ${diagnostics.state === 'refreshable' ? 'refresh' : 'login'} --profile ${quoteShellArg(profile.name)}`;
+      const hint = ['missing', 'expired', 'refreshable', 'malformed'].includes(diagnostics.state)
+        || ['unauthorized', 'invalid_browser_session', 'refresh_failed', 'account_mismatch'].includes(probe.code)
+        ? command : probe.hint;
+      if (hint) notes.push(`${label}: ${hint}`);
+    }
+    return row;
+  });
+  const widths = headings.map((heading, column) => Math.max(heading.length, ...rows.map(row => row[column].length)));
+  const formatRow = row => row.map((cell, column) => cell.padEnd(widths[column])).join('  ').trimEnd();
+  const lines = [summary || `${profiles.length} profiles`, '', formatRow(headings), ...rows.map(formatRow)];
+  if (profiles.some(profile => profile.active)) lines.push('', '* selected profile');
+  if (profiles.some(profile => profile.diagnostics?.probe?.code === 'not_requested')) lines.push('', 'Connection not checked (--local).');
+  if (notes.length) lines.push('', ...notes);
+  if (!details) lines.push('', 'Show users and instance URLs: jsn auth status --details');
+  return lines.join('\n') + '\n';
+}
 
-      // Show confirmations-off badge for skip_confirmations profiles
-      const confirmBadge = p.skip_confirmations ? ' ⚡' : '';
+export function profileSettingValues(argv = {}) {
+  if (argv['confirm-deletes'] !== undefined && argv['skip-confirmations'] !== undefined
+    && argv['confirm-deletes'] === argv['skip-confirmations']) {
+    throw errUsage('--confirm-deletes and --skip-confirmations request conflicting values.');
+  }
+  return {
+    ...argv,
+    'skip-confirmations': argv['confirm-deletes'] !== undefined ? !argv['confirm-deletes'] : argv['skip-confirmations'],
+  };
+}
 
-      if (p.name) {
-        out += `${prefix}${authIcon} ${p.name} — ${p.instance}${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`;
-      } else if (p.username) {
-        out += `${prefix}${authIcon} ${p.instance} (as ${p.username})${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`;
-      } else {
-        out += `${prefix}${authIcon} ${p.instance}${lockIcon}${confirmBadge}${verifiedStr}${staleStr}\n`;
-      }
+/** The same profile preferences are offered by setup and new-profile login. */
+export async function configureProfileOptions(profile, argv = {}, { interactive = false, confirm } = {}) {
+  argv = profileSettingValues(argv);
+  if (interactive && !confirm) ({ confirm } = await import('../prompts.js'));
+  const settings = [
+    ['read_only', 'read-only', 'Read-only profile (blocks mutation commands)?', false],
+    ['skip_confirmations', 'skip-confirmations', 'Confirm before deleting records?', false],
+    ['include_counts', 'include-counts', 'Include result totals on list commands?', true],
+  ];
+  for (const [key, flag, message, fallback] of settings) {
+    if (argv[flag] !== undefined) profile[key] = argv[flag];
+    else if (interactive) {
+      const current = profile[key] ?? fallback;
+      const value = await confirm({ message, default: key === 'skip_confirmations' ? !current : current });
+      profile[key] = key === 'skip_confirmations' ? !value : value;
     }
   }
-  return out;
+  return profile;
 }
 
 /**
@@ -88,8 +120,15 @@ export function resolveTargetProfile(argv = {}, cfg = {}, instanceURL = '') {
   if (argv.profile && cfg.profiles?.[argv.profile]) {
     return { name: argv.profile, profile: cfg.profiles[argv.profile] };
   }
-  const entry = Object.entries(cfg.profiles || {})
-    .find(([, profile]) => normalizeInstanceURL(profile.instance_url) === instanceURL);
+  if (argv.instance && cfg.profiles?.[argv.instance]) return { name: argv.instance, profile: cfg.profiles[argv.instance] };
+  const matches = Object.entries(cfg.profiles || {})
+    .filter(([, profile]) => normalizeInstanceURL(profile.instance_url) === instanceURL);
+  if (matches.length > 1) {
+    const active = cfg.activeProfile || cfg.defaultProfile;
+    if (!argv.instance && matches.some(([name]) => name === active)) return { name: active, profile: cfg.profiles[active] };
+    throw errUsage('Multiple profiles use this instance. Choose the user with --profile <name>.');
+  }
+  const entry = matches[0];
   return entry ? { name: entry[0], profile: entry[1] } : { name: null, profile: null };
 }
 
@@ -100,6 +139,7 @@ export function resolveTargetProfile(argv = {}, cfg = {}, instanceURL = '') {
  */
 export function shouldUseBasicAuth(argv = {}, cfg = {}, instanceURL = '', targetProfile = null) {
   if (argv.basic || argv.password) return true;
+  if (argv.oauth || argv.code || argv.printUrl || argv.browser || argv.gck || argv.headers) return false;
   if (targetProfile) return targetProfile.auth_method === 'basic';
   return Object.values(cfg.profiles || {}).some(profile =>
     profile.instance_url === instanceURL && profile.auth_method === 'basic'
@@ -107,7 +147,8 @@ export function shouldUseBasicAuth(argv = {}, cfg = {}, instanceURL = '', target
 }
 
 export function shouldUseGckAuth(argv = {}, cfg = {}, instanceURL = '', targetProfile = null) {
-  if (argv.gck || argv.headers) return true;
+  if (argv.gck || argv.headers || argv.browser) return true;
+  if (argv.basic || argv.password || argv.oauth || argv.code || argv.printUrl) return false;
   if (targetProfile) return targetProfile.auth_method === 'gck';
   return Object.values(cfg.profiles || {}).some(profile =>
     profile.instance_url === instanceURL && profile.auth_method === 'gck'
@@ -116,7 +157,20 @@ export function shouldUseGckAuth(argv = {}, cfg = {}, instanceURL = '', targetPr
 
 export function validateLoginSelectors(argv = {}, targetProfile = null) {
   const basic = argv.basic === true || argv.password === true;
-  const gck = argv.gck === true || argv.headers !== undefined;
+  const gck = argv.gck === true || argv.headers !== undefined || argv.browser === true;
+  const oauth = argv.oauth === true || argv.code !== undefined || argv.printUrl === true || argv.waitFile !== undefined;
+  if (oauth && (basic || gck)) throw errUsage('Choose only one authentication method: --oauth, --basic, or --browser/--gck.');
+  if (argv.waitFile && !argv.printUrl) throw errUsage('--wait-file requires --print-url.');
+  if (argv.code !== undefined && argv.printUrl) throw errUsage('--code cannot be combined with --print-url.');
+  if (argv.browserUrl !== undefined && !argv.browser) {
+    throw errUsage('--browser-url requires --browser.');
+  }
+  if (argv.browserName !== undefined && (!argv.browser || argv.browserUrl !== undefined)) {
+    throw errUsage('--browser-name requires --browser and cannot be combined with --browser-url.');
+  }
+  if (argv.browser && (argv.headers !== undefined || argv.code !== undefined || argv.printUrl || argv.waitFile)) {
+    throw errUsage('--browser cannot be combined with --headers, --code, --print-url, or --wait-file.');
+  }
   if (basic && gck) {
     throw errUsage('Basic and browser-session selectors are mutually exclusive; choose --basic/--password or --gck/--headers.');
   }
@@ -126,6 +180,19 @@ export function validateLoginSelectors(argv = {}, targetProfile = null) {
   if (gck && targetProfile?.auth_method === 'basic') {
     throw errUsage('This profile is configured for basic authentication; use --basic/--password or change the profile method.');
   }
+  if (oauth && targetProfile?.auth_method && targetProfile.auth_method !== 'oauth') {
+    throw errUsage(`This profile is configured for ${targetProfile.auth_method} authentication. Use --name to create a separate OAuth profile.`);
+  }
+}
+
+export async function loginUsingBrowser(app, instance, argv = {}, username) {
+  if (argv.browserUrl) return app.auth.loginWithBrowser(instance, { browserUrl: argv.browserUrl }, username);
+  const { chooseBrowser } = await import('../browser-launch.js');
+  const browser = await chooseBrowser({ browserName: argv.browserName, interactive: canUsePicker(app, argv) });
+  return app.auth.loginWithBrowser(instance, {
+    launch: true, browser,
+    onProgress: message => process.stderr.write(`${message}\n`),
+  }, username);
 }
 
 /**
@@ -134,13 +201,19 @@ export function validateLoginSelectors(argv = {}, targetProfile = null) {
  * none configured. A non-interactive caller (agent, pipe, --json/--get)
  * never opens a picker; it falls back to the single/default profile.
  */
-export async function pickProfile(app, message) {
-  const { search } = await import('@inquirer/prompts');
+export async function pickProfile(app, message, argv = {}) {
+  const { search } = await import('../prompts.js');
   const profileNames = Object.keys(app.config.profiles || {});
   if (profileNames.length === 0) throw errUsage('No profiles configured. Run "jsn setup" first.');
-  if (profileNames.length === 1 || !canUsePicker(app, {})) return profileNames[0];
+  if (argv.name || argv.profile) {
+    const selected = argv.name || argv.profile;
+    if (!app.config.profiles[selected]) throw errUsage(`Profile not found: ${selected}`);
+    return selected;
+  }
+  if (profileNames.length === 1) return profileNames[0];
+  if (!canUsePicker(app, argv)) throw errUsageHint(`Which profile? ${profileNames.length} profiles are configured: ${profileNames.join(', ')}`, 'Pass --profile <name>, or jsn auth switch <name> to choose a default.');
   const choices = profileNames.map(name => ({
-    name: `${name} — ${app.config.profiles[name].instance_url}`,
+    name,
     value: name,
   }));
   return search({
@@ -205,166 +278,48 @@ export async function readBrowserSessionInput() {
   });
 }
 
-/**
- * Interactive first-run wizard (formerly `jsn setup`).
- *
- * Walks: instance URL → profile name → auth method → optional OAuth login.
- * Creates and activates the profile, then returns the result so the caller
- * decides how to report it. Basic auth saves credentials directly (the OAuth
- * path has no interactive username/password).
- */
+/** Collect human answers, then call the same login operation as auth login. */
 export async function loginWizard(app, argv = {}) {
-  const readline = (await import('node:readline')).default;
-  let rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
-
-  console.log('Welcome to JSN - ServiceNow CLI');
-  console.log();
-
-  // Ask for the instance URL unless one was explicitly provided (env var,
-  // --instance flag/override). NEVER pre-fill from the config's default
-  // profile — this wizard adds an instance, so it must always ask.
-  // (Regression: setup → Add skipped the URL ask when a default profile
-  // existed, silently re-targeting the default instance.)
-  let instance = resolveWizardInstance(app, argv);
-  if (instance) {
-    instance = normalizeInstanceURL(instance);
-  } else {
-    instance = await ask('ServiceNow instance URL (e.g., dev12345.service-now.com): ');
-    instance = normalizeInstanceURL(instance);
-  }
-  console.log(`Instance: ${instance}`);
-
-  // Warn if another profile already uses this instance URL
-  const existing = Object.entries(app.config.profiles || {}).find(([, p]) => p.instance_url === instance);
-  if (existing) {
-    console.log(`Note: instance is also used by profile "${existing[0]}".`);
-  }
-
-  const profileName = (await ask('Profile name (default): ')) || 'default';
-  const profile = { instance_url: instance };
-  if (argv['read-only']) {
-    profile.read_only = true;
-  }
-  if (argv['skip-confirmations']) {
-    profile.skip_confirmations = true;
-  }
-
-  const authMethod = await ask('Authentication method (OAuth/Basic/Browser session) [OAuth]: ');
-  const useGck = authMethod.toLowerCase().startsWith('g') || authMethod.toLowerCase().startsWith('browser');
-  const useBasic = !useGck && authMethod.toLowerCase().startsWith('b');
-
-  let loggedIn = false;
-  if (useBasic) {
-    const username = await ask('Username: ');
-    rl.close(); // Close outer readline before askHidden creates its own
-    const { askHidden } = await import('../auth.js');
-    const existingCreds = app.auth.loadCredentials(instance) || app.auth.loadCredentials(instance, username);
-    if (existingCreds && existingCreds.auth_method === 'basic') {
-      console.log(`Using existing credentials for ${instance}`);
-    } else {
-      const password = await askHidden('Password: ');
-      app.auth.saveCredentials(instance, { auth_method: 'basic', username, password }, username);
-      console.log('Basic auth credentials saved');
-    }
-    profile.username = username;
-    profile.auth_method = 'basic';
-  } else if (useGck) {
-    rl.close();
-    const input = await readBrowserSessionInput();
-    await app.auth.loginWithGck(instance, input);
-    profile.auth_method = 'gck';
-    loggedIn = true;
-  } else {
-    profile.auth_method = 'oauth';
-  }
-
-  await setProfile(app.config, profileName, profile);
-  // Set as active profile so subsequent commands know which instance to use
-  app.config.activeProfile = profileName;
-  app.config.defaultProfile = profileName;
-
-  // Present all connection-level options during setup. Gated on
-  // interactivity so a piped/scripted call never blocks on prompts.
-  if (canUsePicker(app, argv)) {
-    // @inquirer/prompts owns stdin while these confirmations run. Close the
-    // older readline interface before handing stdin to Inquirer. This matters
-    // on Windows Git Bash: leaving both readers attached can make the later
-    // OAuth question see EOF and let Node exit instead of waiting for input.
-    rl.close();
-    const { confirm } = await import('@inquirer/prompts');
-    profile.read_only = await confirm({ message: 'Read-only profile (blocks mutation commands)?', default: profile.read_only || false });
-    profile.skip_confirmations = await confirm({ message: 'Skip confirmations (deletes run without prompting)?', default: profile.skip_confirmations || false });
-    profile.include_counts = await confirm({ message: 'Include result totals on list commands?', default: profile.include_counts !== false });
-    console.log('');
-  }
-
-  await saveConfig(app.config);
-
-  if (!useBasic && !useGck) {
-    // Recreate readline after Inquirer has released stdin. Do not reuse the
-    // interface that was open before the confirmation prompts.
-    rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const loginNow = await ask('Login now? [Y/n]: ');
-    rl.close();
-    if (!loginNow || loginNow.toLowerCase() !== 'n') {
-      await app.auth.login(instance);
-      // Re-save credentials under <user>@<instance> after verifying username
-      try {
-        const sdk = app.getSDKForProfile
-          ? app.getSDKForProfile(instance, { authMethod: 'oauth' })
-          : app.sdk;
-        const user = await sdk.getCurrentUser();
-        if (user && user.user_name) {
-          app.auth.migrateLegacyCredential(instance, user.user_name);
-          profile.username = user.user_name;
-        }
-      } catch {
-        // Non-fatal — token saved, username will be set on next auth login
-      }
-      console.log('Login successful!');
-      loggedIn = true;
-
-      // Probe domain separation capability once and stamp the profile, so
-      // `jsn domains` (and its help entry) only appear on instances with it.
-      try {
-        const domainsMod = await import('./domains.js');
-        const sdk = app.getSDKForProfile
-          ? app.getSDKForProfile(instance, {
-            profile,
-            authMethod: profile.auth_method || 'oauth',
-            username: profile.username,
-          })
-          : app.sdk;
-        profile.domain_separation = await domainsMod.isDomainSeparationInstalled({ sdk });
-        await setProfile(app.config, profileName, profile);
-
-        // If domain separation is installed, offer to pick a default domain
-        // for the profile — every request will be scoped to it via X-Now-Domain.
-        if (profile.domain_separation) {
-          const { confirm } = await import('@inquirer/prompts');
-          const setDomainNow = await confirm({
-            message: 'Domain separation detected. Configure a domain for this instance?',
-            default: false,
-          });
-          if (setDomainNow) {
-            const domainSysID = await domainsMod.pickDomain({ ...app, sdk });
-            if (domainSysID) {
-              profile.domain = domainSysID;
-              await setProfile(app.config, profileName, profile);
-              console.log('Domain configured.');
-            }
-          }
-        }
-      } catch {
-        // Non-fatal — capability unknown; domains command falls back to probing
-      }
-    }
-  } else {
-    rl.close();
+  const { input, select, confirm, password } = await import('../prompts.js');
+  const explicitInstance = resolveWizardInstance(app, argv);
+  const instance = resolveInstanceArg(explicitInstance || await input({
+    message: 'ServiceNow instance name or URL:',
+    validate: value => value.trim() ? true : 'An instance is required',
+  }), app.config);
+  const name = argv.name || await input({
+    message: 'Profile name:', default: suggestedProfileName(instance),
+    validate: value => !value.trim() ? 'A profile name is required'
+      : app.config.profiles?.[value.trim()] ? 'That profile already exists; choose another name or sign in again.' : true,
+  });
+  const method = argv.browser ? 'browser' : argv.basic || argv.password ? 'basic' : await select({
+    message: 'Authentication method:',
+    choices: [
+      { name: 'Browser — sign in on this computer', value: 'browser' },
+      { name: 'OAuth — authorization code', value: 'oauth' },
+      { name: 'Basic — username and password', value: 'basic' },
+    ],
+  });
+  const request = { ...argv, profile: undefined, instance, name: name.trim() };
+  if (method === 'browser') request.browser = true;
+  if (method === 'oauth') request.oauth = true;
+  if (method === 'basic') {
+    request.basic = true;
+    const username = await input({ message: 'Username:', validate: value => value.trim() ? true : 'A username is required' });
+    request._basicCredentials = { username: username.trim(), password: await password({ message: 'Password:' }) };
   }
+  const settings = await configureProfileOptions({}, argv, { interactive: true });
+  request['read-only'] = settings.read_only;
+  request['skip-confirmations'] = settings.skip_confirmations;
+  request['include-counts'] = settings.include_counts;
+  request.makeDefault = argv.makeDefault ?? await confirm({
+    message: 'Use this profile by default?', default: !app.config.defaultProfile,
+  });
+  const result = await loginProfile(request, app);
+  return { instanceURL: instance, profileName: result.profile, loggedIn: result.authenticated };
+}
 
-  return { instanceURL: instance, profileName, loggedIn };
+function suggestedProfileName(instance) {
+  return instance.replace(/https?:\/\//, '').replace(/\.service-now\.com.*/, '').replace(/[^a-zA-Z0-9]/g, '-');
 }
 
 /**
@@ -375,7 +330,7 @@ export async function loginWizard(app, argv = {}) {
  * Returns { addNew: true, instanceName } or { addNew: false, name }.
  */
 async function pickLoginTarget(app) {
-  const { search, input } = await import('@inquirer/prompts');
+  const { search, input } = await import('../prompts.js');
   const ADD_NEW = '__add_new__';
   const profileNames = Object.keys(app.config.profiles || {});
   let lastInput = '';
@@ -386,11 +341,11 @@ async function pickLoginTarget(app) {
       lastInput = term || '';
       const profiles = profileNames
         .filter((name) => {
-          const label = `${name} — ${app.config.profiles[name].instance_url}`.toLowerCase();
+          const label = `${name} — ${app.config.profiles[name].instance_url} ${app.config.profiles[name].username || ''}`.toLowerCase();
           return !filter || label.includes(filter);
         })
         .map((name) => ({
-          name: `${name} — ${app.config.profiles[name].instance_url}`,
+          name: `${name} — ${app.config.profiles[name].instance_url} (${app.config.profiles[name].username || 'account not recorded'})`,
           value: name,
         }));
       const addLabel = filter
@@ -414,7 +369,7 @@ async function pickLoginTarget(app) {
 /** Per-profile configurable flags (extensible — any boolean on the profile). */
 const PROFILE_FLAGS = [
   { name: 'Read-only (blocks mutation commands)', value: 'read_only', icon: '🔒' },
-  { name: 'Skip confirmations (deletes run without prompting)', value: 'skip_confirmations', icon: '⚡' },
+  { name: 'Confirm before deleting records', value: 'skip_confirmations', icon: '⚡' },
   { name: 'Include result totals on list commands', value: 'include_counts', icon: '🔢' },
 ];
 
@@ -423,9 +378,20 @@ const PROFILE_FLAGS = [
  * Interactive picker when no flag passed; testable via argv.flag/argv.domain.
  */
 export async function modifyProfile(app, argv = {}) {
-  const name = argv.name || await pickProfile(app, 'Modify which instance?');
+  argv = profileSettingValues(argv);
+  const name = argv.name || argv.profile || await pickProfile(app, 'Modify which profile?', argv);
   const profile = app.config.profiles?.[name];
   if (!profile) throw new Error(`Profile not found: ${name}`);
+  const explicitSettings = ['read-only', 'skip-confirmations', 'include-counts'].some(flag => argv[flag] !== undefined);
+  if (explicitSettings) {
+    if (argv.domain !== undefined) throw errUsage('Set profile preferences and domain separately.');
+    const updated = await configureProfileOptions({ ...profile }, argv);
+    app.config.profiles[name] = updated;
+    await saveConfig(app.config);
+    app.ok({ profile: name, read_only: updated.read_only === true, confirm_deletes: updated.skip_confirmations !== true, include_counts: updated.include_counts !== false },
+      { summary: `Settings saved for ${name}` });
+    return;
+  }
 
   // Domain setting path: --domain <name|sys_id|clear>
   if (argv.domain !== undefined) {
@@ -454,10 +420,12 @@ export async function modifyProfile(app, argv = {}) {
   }
 
   let flag = argv.flag;
+  let picked = false;
   if (!flag) {
-    const { select } = await import('@inquirer/prompts');
+    if (!canUsePicker(app, argv)) throw errUsageHint('Specify the settings to change when noninteractive.', 'Use --read-only, --no-include-counts, or --confirm-deletes.');
+    const { select } = await import('../prompts.js');
     const choices = PROFILE_FLAGS.map(f => ({
-      name: `${f.icon} ${f.name}: ${profile[f.value] ? 'on' : 'off'}`,
+      name: `${f.icon} ${f.name}: ${(f.value === 'include_counts' ? profile[f.value] !== false : f.value === 'skip_confirmations' ? !profile[f.value] : profile[f.value]) ? 'on' : 'off'}`,
       value: f.value,
     }));
     if (profile.domain_separation) {
@@ -473,13 +441,14 @@ export async function modifyProfile(app, argv = {}) {
       message: `Modify ${name} (${profile.instance_url})`,
       choices,
     });
+    picked = true;
     if (flag === 'domain') {
       const domainsMod = await import('./domains.js');
       const installed = await domainsMod.isDomainSeparationInstalled({ sdk });
       if (!installed) {
         throw new Error(`Domain separation is not installed on ${profile.instance_url}`);
       }
-      const { confirm } = await import('@inquirer/prompts');
+      const { confirm } = await import('../prompts.js');
       const clear = profile.domain
         ? await confirm({ message: `Domain is set. Clear it?`, default: false })
         : false;
@@ -499,7 +468,17 @@ export async function modifyProfile(app, argv = {}) {
     }
   }
 
-  profile[flag] = !profile[flag];
+  if (picked) {
+    const setting = { read_only: 'read-only', skip_confirmations: 'confirm-deletes', include_counts: 'include-counts' }[flag];
+    const { confirm } = await import('../prompts.js');
+    const value = await confirm({
+      message: { read_only: 'Read-only profile (blocks mutation commands)?', skip_confirmations: 'Confirm before deleting records?', include_counts: 'Include result totals on list commands?' }[flag],
+      default: flag === 'skip_confirmations' ? !profile[flag] : flag === 'include_counts' ? profile[flag] !== false : !!profile[flag],
+    });
+    return modifyProfile(app, { name, [setting]: value });
+  }
+
+  profile[flag] = flag === 'include_counts' ? profile[flag] === false : !profile[flag];
   await saveConfig(app.config);
   app.ok({ profile: name, [flag]: profile[flag] },
     { summary: `${flag} is now ${profile[flag] ? 'ON' : 'off'} for ${name}` });
@@ -524,6 +503,7 @@ export async function removeProfile(app, name) {
   if (app.config.defaultProfile === name) app.config.defaultProfile = '';
   if (app.config.activeProfile === name) app.config.activeProfile = '';
   saveConfig(app.config);
+  syncSession(app);
 
   // Delete only this profile's credential identity. Other profiles may share
   // the instance URL but must retain their separate credentials.
@@ -545,16 +525,522 @@ function canLogoutBareProfile(app, instance, target, explicitlySelected) {
   return sameInstance.length <= 1;
 }
 
+export async function loginProfile(argv, app) {
+  argv = profileSettingValues(argv);
+  validateLoginSelectors(argv);
+  if (argv.name !== undefined) {
+    if (!argv.name.trim()) throw errUsage('--name requires a nonempty profile name.');
+    if (argv.profile) throw errUsage('Use --profile to reconnect or --name to create a profile, not both.');
+    if (app.config.profiles?.[argv.name]) throw errUsage(`Profile "${argv.name}" already exists. Reconnect with --profile or choose another --name.`);
+  }
+  let instanceURL;
+  let selectedProfileName = argv.profile || (argv.instance && app.config.profiles?.[argv.instance] ? argv.instance : null);
+  if (argv.profile) {
+    const namedProfile = app.config.profiles?.[argv.profile];
+    if (!namedProfile?.instance_url) {
+      throw errUsage(`Profile "${argv.profile}" is not configured.`);
+    }
+    // An explicit profile is authoritative, including in an
+    // interactive terminal. Never let the picker retarget it.
+    instanceURL = normalizeInstanceURL(namedProfile.instance_url);
+  } else if (argv.instance) {
+    instanceURL = resolveInstanceArg(argv.instance, app.config);
+  } else if (canUsePicker(app, argv)) {
+    // gh-faithful: interactive terminals always get a picker —
+    // existing profiles plus "＋ Add a new instance". Zero profiles
+    // goes straight to the setup wizard.
+    const profileNames = Object.keys(app.config.profiles || {});
+    if (profileNames.length === 0) {
+      return loginWizard(app, argv);
+    }
+    const target = await pickLoginTarget(app);
+    if (target.addNew) {
+      return loginWizard(app, { ...argv, instance: resolveInstanceArg(target.instanceName, app.config) });
+    } else {
+      instanceURL = normalizeInstanceURL(app.config.profiles[target.name].instance_url);
+      selectedProfileName = target.name;
+    }
+  } else {
+    instanceURL = getEffectiveInstance(app.config);
+    if (!instanceURL) {
+      throw errUsage(`Instance URL required.
+
+Examples:
+  jsn auth login https://dev12345.service-now.com
+  jsn auth login dev373698
+  jsn auth login --basic https://dev328604.service-now.com
+
+Find your instance URL in your browser's address bar when logged into ServiceNow.`);
+    }
+  }
+
+  const matchingProfiles = Object.entries(app.config.profiles || {})
+    .filter(([, profile]) => normalizeInstanceURL(profile.instance_url) === instanceURL);
+  if (!selectedProfileName && !argv.name && matchingProfiles.length > 1) {
+    throw errUsage('Multiple profiles use this instance. Choose the account with: jsn auth login --profile <name>');
+  }
+  const target = argv.name ? { name: argv.name, profile: null }
+    : resolveTargetProfile({ ...argv, profile: selectedProfileName }, app.config, instanceURL);
+  const targetProfile = target.profile;
+  validateLoginSelectors(argv, targetProfile);
+  let targetUsername = targetProfile?.username || '';
+  const methodConfig = argv.name ? { profiles: {} } : app.config;
+  const useBasic = shouldUseBasicAuth(argv, methodConfig, instanceURL, targetProfile);
+  const useGck = shouldUseGckAuth(argv, methodConfig, instanceURL, targetProfile);
+  const interactive = canUsePicker(app, argv);
+  if (useGck && !argv.browser && !argv.headers && !interactive) {
+    throw errUsage('Browser sign-in needs a human. Pass --browser to explicitly open a login window, or supply a captured session.');
+  }
+  if (!useGck && !useBasic && !argv.printUrl && !argv.code && !interactive) {
+    throw errUsage('OAuth login requires --print-url followed by --code <code> when noninteractive.');
+  }
+  const preliminary = argv.printUrl && !argv.waitFile;
+  const preferences = await configureProfileOptions({ ...targetProfile }, argv, {
+    interactive: !targetProfile && interactive && !preliminary,
+  });
+  let setDefault = argv.makeDefault === true;
+  if (!targetProfile && argv.makeDefault === undefined && interactive && !preliminary) {
+    const { confirm } = await import('../prompts.js');
+    setDefault = await confirm({ message: 'Use this profile by default?', default: !app.config.defaultProfile });
+  }
+  // --basic (with --password as a compatibility alias): authenticate
+  // with basic auth from env vars and persist it for this profile.
+  if (useGck) {
+    const credentials = (argv.browser || (!argv.gck && !argv.headers))
+      ? await loginUsingBrowser(app, instanceURL, argv, targetUsername || null)
+      : await app.auth.loginWithGck(instanceURL, argv.headers || await readBrowserSessionInput(), targetUsername || null);
+    targetUsername = credentials?.username || targetUsername;
+  } else if (useBasic) {
+    let credentials;
+    try {
+      credentials = argv._basicCredentials
+        ? await app.auth.loginWithPassword(instanceURL, targetUsername || null, argv._basicCredentials)
+        : await app.auth.loginWithPassword(instanceURL, targetUsername || null);
+    } catch (error) {
+      if (!interactive || argv._basicCredentials || error.code !== 'auth_error') throw error;
+      const { input, password } = await import('../prompts.js');
+      const username = targetUsername || await input({ message: 'Username:', validate: value => value.trim() ? true : 'A username is required' });
+      credentials = await app.auth.loginWithPassword(instanceURL, targetUsername || null, {
+        username, password: await password({ message: 'Password:' }),
+      });
+    }
+    // A new profile has no configured username yet. The auth
+    // manager saves env/stored credentials under creds.username;
+    // carry that identity into verification and profile creation.
+    targetUsername = credentials?.username || targetUsername;
+  }
+  // --print-url with --wait-file: print URL and wait for code file
+  else if (argv.printUrl && argv.waitFile) {
+    await app.auth.buildAuthURL(instanceURL, argv.waitFile, targetUsername || null);
+  }
+  // --print-url: just print the URL and exit
+  else if (argv.printUrl) {
+    const authURL = app.auth.buildAuthURL(instanceURL, undefined, targetUsername || null);
+    const result = { authorization_url: authURL, instance: instanceURL, profile: target.name || undefined };
+    const targetFlag = argv.name ? `--name ${quoteShellArg(argv.name)}` : target.name ? `--profile ${quoteShellArg(target.name)}` : '';
+    const settingsFlags = ['read-only', 'skip-confirmations', 'include-counts']
+      .filter(flag => argv[flag] !== undefined).map(flag => `--${argv[flag] ? '' : 'no-'}${flag}`);
+    if (argv.makeDefault !== undefined) settingsFlags.push(`--${argv.makeDefault ? '' : 'no-'}make-default`);
+    app.ok(result, {
+      summary: 'Open the authorization URL, then complete login with the returned code.',
+      breadcrumbs: [{ action: 'Complete login', cmd: ['jsn auth login', quoteShellArg(instanceURL), targetFlag, '--code <code>', ...settingsFlags].filter(Boolean).join(' '), description: 'Keep the same profile name and settings when exchanging the code' }],
+    });
+    return result;
+  }
+  // --code: exchange the provided authorization code directly
+  else if (argv.code) {
+    await app.auth.loginWithCode(instanceURL, argv.code, targetUsername || null);
+  } else {
+    // Interactive: full OAuth flow with browser + prompt
+    await app.auth.login(instanceURL, targetUsername || null);
+  }
+
+  // Verify auth by fetching current user
+  let username = '';
+  try {
+    const activeName = app.config.activeProfile || app.config.defaultProfile;
+    const activeProfile = app.config.profiles?.[activeName];
+    const activeInstance = app.getEffectiveInstance?.() || activeProfile?.instance_url || '';
+    const activeUsername = activeProfile?.username || '';
+    const activeMethod = activeProfile?.auth_method || '';
+    const targetMethod = useGck ? 'gck' : useBasic ? 'basic' : 'oauth';
+    const targetDiffers = instanceURL !== activeInstance
+      || targetUsername !== activeUsername
+      || targetMethod !== activeMethod;
+    if (!app.sdk || targetDiffers) {
+      app.sdk = app.getSDKForProfile
+        ? app.getSDKForProfile(instanceURL, {
+          authMethod: targetMethod,
+          username: targetUsername,
+          profile: targetProfile,
+        })
+        : app.sdk;
+    }
+    const user = await app.sdk.getCurrentUser();
+    username = user?.user_name || user?.name || '';
+  } catch {
+    // Non-fatal — token is saved, just couldn't verify
+  }
+
+  // Basic/GCK auth establishes the target identity before the
+  // profile exists; preserve it when verification is unavailable.
+  username = username || targetUsername;
+
+  // Save to profiles — deduplicate by instance URL
+  if (!app.config.profiles) {
+    app.config.profiles = {};
+  }
+
+  // Preserve an explicitly selected profile even when another profile
+  // shares the same instance URL.
+  let profileName = target.name;
+  if (!profileName) {
+    for (const [existingName, existingProfile] of Object.entries(app.config.profiles)) {
+      if (existingProfile.instance_url === instanceURL) {
+        profileName = existingName;
+        break;
+      }
+    }
+  }
+
+  // If no existing profile found, generate a name from the URL
+  if (!profileName) {
+    profileName = suggestedProfileName(instanceURL);
+  }
+
+  app.config.profiles[profileName] = {
+    ...(app.config.profiles[profileName] || {}),
+    instance_url: instanceURL,
+    auth_method: useGck ? 'gck' : useBasic ? 'basic' : 'oauth',
+    username: username || undefined,
+    read_only: preferences.read_only,
+    skip_confirmations: preferences.skip_confirmations,
+    include_counts: preferences.include_counts,
+  };
+  if (!targetProfile && interactive) {
+    try {
+      const domains = await import('./domains.js');
+      const profile = app.config.profiles[profileName];
+      const sdk = app.getSDKForProfile
+        ? app.getSDKForProfile(instanceURL, { profile, authMethod: profile.auth_method, username: profile.username }) : app.sdk;
+      profile.domain_separation = await domains.isDomainSeparationInstalled({ sdk });
+      if (profile.domain_separation) {
+        const { confirm } = await import('../prompts.js');
+        if (await confirm({ message: 'Configure a default domain?', default: false })) profile.domain = await domains.pickDomain({ ...app, sdk });
+      }
+    } catch (error) {
+      if (error.name === 'PromptCancelled') throw error;
+      // Capability discovery remains best-effort, as in setup.
+    }
+  }
+
+  // Re-save OAuth credentials with username now that we have it,
+  // so they're keyed by <user>@<instance> for per-user isolation.
+  // The legacy bare-instance key is cleaned up behind the
+  // AuthManager seam (credential-store internals don't leak here).
+  if (!useBasic && username) {
+    app.auth.migrateLegacyCredential?.(instanceURL, username);
+  }
+
+  if (setDefault) {
+    app.config.instanceURL = instanceURL;
+    app.config.defaultProfile = profileName;
+    app.config.activeProfile = profileName;
+  }
+
+  const { saveConfig } = await import('../config.js');
+  saveConfig(app.config);
+  syncSession(app);
+
+  const result = {
+    authenticated: true,
+    instance: instanceURL,
+    username: username || undefined,
+    profile: profileName,
+    default: setDefault || undefined,
+  };
+  const summary = username
+    ? `✓ Authenticated to ${instanceURL} as ${username} (profile: ${profileName})`
+    : `✓ Authenticated to ${instanceURL} (profile: ${profileName})`;
+  const settings = app.config.profiles[profileName];
+  const breadcrumbs = !targetProfile ? [
+    {
+      action: 'Verify this profile', cmd: `jsn --profile ${quoteShellArg(profileName)} auth status`,
+      description: 'Check the account and connection for this profile',
+    },
+    {
+      action: 'Profile settings', cmd: `jsn auth modify ${quoteShellArg(profileName)}`,
+      description: `${settings.read_only ? 'read-only' : 'writes allowed'}; ${settings.skip_confirmations ? 'delete confirmations off' : 'confirm deletes'}; counts ${settings.include_counts === false ? 'off' : 'on'}`,
+    },
+    {
+      action: 'New profile flags', cmd: 'jsn auth login <instance> --read-only --no-include-counts',
+      description: 'Set these at login; --skip-confirmations disables delete prompts',
+    },
+  ] : [];
+  app.ok(result, { summary, breadcrumbs });
+  return result;
+}
+
+export async function logoutProfile(argv, app) {
+  if (!argv.instance && !argv.profile && canUsePicker(app, argv)) {
+    argv = { ...argv, profile: await pickProfile(app, 'Sign out of which profile?', argv) };
+  }
+  let instanceURL;
+  if (argv.profile) {
+    instanceURL = app.config.profiles?.[argv.profile]?.instance_url;
+    if (!instanceURL) throw errUsage(`Profile not found: ${argv.profile}`);
+  } else if (argv.instance) {
+    instanceURL = resolveInstanceArg(argv.instance, app.config);
+  } else {
+    instanceURL = getEffectiveInstance(app.config);
+    if (!instanceURL) {
+      throw errUsage(`No instance specified.
+
+Examples:
+  jsn auth logout
+  jsn auth logout https://dev12345.service-now.com`);
+    }
+  }
+  const target = resolveTargetProfile(argv, app.config, instanceURL);
+  const username = target.profile?.username ?? null;
+  if (username || canLogoutBareProfile(app, instanceURL, target.profile, !!argv.profile)) {
+    app.auth.logout(instanceURL, username);
+  }
+  app.ok({ logged_out: true, instance: instanceURL }, { summary: `✓ Logged out from ${instanceURL}` });
+}
+
+export async function showAuthStatus(argv, app) {
+  const configuredDefault = app.config.profiles?.[app.config.defaultProfile];
+  const defaultInstance = configuredDefault?.instance_url || app.config.instanceURL || '';
+
+  // Check environment auth
+  const envToken = process.env.SERVICENOW_OAUTH_TOKEN || '';
+
+  const profiles = [];
+  const configuredProfiles = Object.entries(app.config.profiles || {});
+  const selectedProfiles = argv.profile
+    ? configuredProfiles.filter(([name]) => name === argv.profile)
+    : configuredProfiles;
+  for (const [name, profile] of selectedProfiles) {
+    const instance = profile.instance_url;
+    const authOptions = { authMethod: profile.auth_method, username: profile.username };
+    const identityOptions = { username: profile.username, authMethod: profile.auth_method };
+    const isAuth = app.auth.isAuthenticatedFor(instance, identityOptions);
+    const lastSeen = app.auth.getLastSeen(instance, identityOptions);
+    const authState = app.auth.getAuthState(instance, authOptions);
+    const legacy = !isAuth && app.auth.hasLegacyCredentials(instance, identityOptions) ? true : undefined;
+    // Keep the established status field contract: unauthenticated
+    // profiles omit auth_source, except legacy credentials retain
+    // their historical `legacy` marker. getAuthState remains the
+    // safe metadata seam for authenticated profiles.
+    const authSource = isAuth ? authState.auth_source : (legacy ? 'legacy' : undefined);
+
+    // Try live verification through AuthManager's read-only probe seam.
+    let verified = null;
+    let verifiedAt = null;
+    let probe;
+    if (argv.local) {
+      probe = { status: 'not_attempted', code: 'not_requested', classification: 'not_checked' };
+    } else if (!instance) {
+      probe = app.auth.probeUnavailable?.('missing_instance') || { status: 'not_attempted', code: 'missing_instance', classification: 'unavailable' };
+    } else {
+      try {
+        const sdk = app.getSDKForProfile
+          ? app.getSDKForProfile(instance, { ...authOptions, profile })
+          : app.sdk || { getCurrentUser: async () => null };
+        let user;
+        probe = await app.auth.probeCurrentUser(instance, {
+          getCurrentUser: async (options) => {
+            user = await sdk.getCurrentUser(options);
+            return user;
+          },
+        }, authOptions);
+        if (probe.status === 'succeeded' && user?.user_name) {
+          verified = true;
+          verifiedAt = user.user_name;
+          if (profile.username && profile.username !== user.user_name) {
+            verified = false;
+            probe = {
+              status: 'failed', code: 'account_mismatch', classification: 'account_mismatch',
+              message: 'The session account does not match the configured profile account.',
+            };
+          }
+        } else if (probe.status !== 'not_attempted') {
+          verified = false;
+        }
+      } catch {
+        probe = app.auth.probeUnavailable?.('sdk_construction_failed') || { status: 'not_attempted', code: 'sdk_construction_failed', classification: 'configuration_error' };
+        verified = false;
+      }
+    }
+
+    // Calculate days since last seen
+    let daysSinceLastSeen = null;
+    if (lastSeen) {
+      daysSinceLastSeen = Math.floor((Date.now() / 1000 - lastSeen) / 86400);
+    }
+
+    profiles.push({
+      name,
+      instance,
+      username: profile.username || undefined,
+      active: name === (app.session?.profileName || app.config.activeProfile || app.config.defaultProfile),
+      authenticated: isAuth,
+      legacy,
+      auth_source: authSource,
+      verified,
+      verified_as: verifiedAt || undefined,
+      last_seen: lastSeen || undefined,
+      days_since_last_seen: daysSinceLastSeen,
+      stale: daysSinceLastSeen > 7,
+      default: name === app.config.defaultProfile,
+      read_only: profile.read_only || false,
+      skip_confirmations: profile.skip_confirmations || false,
+      include_counts: profile.include_counts !== false,
+      diagnostics: {
+        auth_method: authState.auth_method,
+        auth_source: authState.auth_source,
+        state: authState.state,
+        probe,
+      },
+    });
+  }
+
+  const result = {
+    default_instance: defaultInstance,
+    authenticated: app.auth.isAuthenticated(),
+    environment_auth: envToken ? true : undefined,
+    profiles,
+  };
+
+  const summary = `${profiles.length} ${profiles.length === 1 ? 'profile' : 'profiles'}`;
+  // Ship the styled view as _formatted (see renderAuthStatus); the
+  // OutputWriter prints it verbatim and suppresses the summary.
+  result._formatted = renderAuthStatus(result, summary, { details: argv.details === true });
+  if (!argv.details) {
+    delete result.default_instance;
+    result.profiles = profiles.map(({ instance: _instance, username: _username, verified_as: _verifiedAs, ...visible }) => visible);
+  }
+  app.ok(result, {
+    summary,
+    breadcrumbs: [
+      { action: 'Switch profile', cmd: 'jsn auth switch <name>', description: 'Choose the default profile' },
+      { action: 'Renew session', cmd: 'jsn auth refresh --profile <name>', description: 'Refresh OAuth or sign in again in a browser' },
+      { action: 'Change settings', cmd: 'jsn auth modify --profile <name>', description: 'Read-only access, delete confirmations, and counts' },
+    ],
+  });
+
+  // Warn about legacy credentials that need re-authentication
+  const legacyProfiles = profiles.filter(p => p.legacy);
+  if (legacyProfiles.length > 0) {
+    process.stderr.write(
+      '\n⚠️  This release changed how credentials are stored.\n' +
+      '   Some profiles still use the old format.\n' +
+      '   Run the following to re-authenticate:\n'
+    );
+    for (const p of legacyProfiles) {
+      process.stderr.write(`     jsn auth login ${p.name}\n`);
+    }
+    process.stderr.write('\n');
+  }
+}
+
+export async function refreshProfile(argv, app) {
+  let instanceURL;
+  if (argv.profile) {
+    instanceURL = app.config.profiles?.[argv.profile]?.instance_url;
+    if (!instanceURL) throw errUsage(`Profile not found: ${argv.profile}`);
+  } else if (argv.instance) {
+    instanceURL = resolveInstanceArg(argv.instance, app.config);
+  } else {
+    instanceURL = getEffectiveInstance(app.config);
+    if (!instanceURL) {
+      throw errUsage(`No instance specified and no default configured.
+
+Examples:
+  jsn auth refresh
+  jsn auth refresh https://dev12345.service-now.com
+  jsn auth refresh dev12345`);
+    }
+  }
+
+  const target = resolveTargetProfile(argv, app.config, instanceURL);
+  const targetProfile = target.profile;
+  if (targetProfile?.auth_method === 'gck') {
+    return loginProfile({
+      ...argv, instance: instanceURL, profile: target.name,
+      browser: argv.browser || (!argv.headers && canUsePicker(app, argv)),
+    }, app);
+  }
+  const targetAuthOptions = {
+    authMethod: targetProfile ? targetProfile.auth_method : 'oauth',
+    username: targetProfile?.username,
+  };
+  const creds = await app.auth.getCredentialsFor(
+    instanceURL,
+    targetProfile?.username,
+    { ...targetAuthOptions, refresh: false }
+  );
+  const refreshed = await app.auth.refreshToken(instanceURL, creds, targetProfile?.username ?? null);
+
+  // Re-probe domain separation on refresh so the capability flag
+  // stays in sync if the plugin was installed/removed since setup.
+  try {
+    const { isDomainSeparationInstalled } = await import('./domains.js');
+    const sdk = app.getSDKForProfile
+      ? app.getSDKForProfile(instanceURL, {
+        ...targetAuthOptions,
+        profile: targetProfile,
+      })
+      : app.sdk;
+    const hasDS = await isDomainSeparationInstalled({ sdk });
+    const name = target.name || app.config.activeProfile || app.config.defaultProfile;
+    if (name && app.config.profiles[name] && app.config.profiles[name].instance_url === instanceURL) {
+      app.config.profiles[name].domain_separation = hasDS;
+      await saveConfig(app.config);
+    }
+  } catch {
+    // Non-fatal — capability probe is best-effort
+  }
+
+  app.ok({
+    refreshed: true,
+    instance: instanceURL,
+    expires_at: refreshed.expires_at,
+  }, { summary: `✓ Token refreshed for ${instanceURL}` });
+}
+
+export async function switchProfile(argv, app) {
+  const name = argv.name || argv.profile || await pickProfile(app, 'Use which profile by default?', argv);
+  if (!app.config.profiles?.[name]) throw errUsage(`Profile not found: ${name}`);
+  app.config.instanceURL = app.config.profiles[name].instance_url;
+  await setActiveProfile(app.config, name);
+  syncSession(app);
+  app.ok({ active_profile: name }, { summary: `Default profile: ${name}` });
+}
+
+export async function removeConnection(argv, app) {
+  let name = argv.name;
+  if (!name) {
+    name = await pickProfile(app, 'Remove which profile?', argv);
+  }
+  await removeProfile(app, name);
+}
+
 export function authCmd(wrap) {
   return {
     command: 'auth [subcommand]',
-    describe: 'Manage authentication (OAuth or Basic Auth)',
+    describe: 'Manage authentication (OAuth, Basic, or browser session)',
     builder: (yargs) => {
       return yargs
         .command({
           command: 'login [instance]',
           describe: 'Authenticate with a ServiceNow instance (interactive picker when run bare)',
           builder: (sub) => sub
+            .option('name', { type: 'string', describe: 'Create a new named profile, including another user on the same instance' })
+            .option('make-default', { type: 'boolean', describe: 'Explicitly use this profile by default' })
+            .option('oauth', { type: 'boolean', describe: 'Authenticate using OAuth authorization code with PKCE' })
+            .option('confirm-deletes', { type: 'boolean', describe: 'Require confirmation before deleting records' })
             .option('code', {
               describe: 'Authorization code from browser (bypasses interactive prompt)',
               type: 'string',
@@ -572,6 +1058,18 @@ export function authCmd(wrap) {
               describe: 'Browser request headers or cURL command for browser-session auth',
               type: 'string',
             })
+            .option('browser', {
+              describe: 'Open a browser and wait for you to log in to ServiceNow',
+              type: 'boolean',
+            })
+            .option('browser-name', {
+              describe: 'Browser to launch: chromium, chrome, or edge (otherwise choose an installed browser)',
+              type: 'string',
+            })
+            .option('browser-url', {
+              describe: 'Advanced: connect to an existing local debugging URL instead of launching (requires --browser)',
+              type: 'string',
+            })
             .option('print-url', {
               describe: 'Print the OAuth URL and exit (saves PKCE state for --code)',
               type: 'boolean',
@@ -583,446 +1081,60 @@ export function authCmd(wrap) {
             .option('read-only', {
               describe: 'Mark the created profile as read-only (blocks mutation commands)',
               type: 'boolean',
-              default: false,
             })
             .option('skip-confirmations', {
               describe: 'Skip delete confirmations on this profile (deletes run without prompting)',
               type: 'boolean',
-              default: false,
             })
             .option('include-counts', {
               describe: 'Include result totals on list commands (default on; pass --no-include-counts to opt out)',
               type: 'boolean',
             }),
-          handler: wrap(async (argv, app) => {
-            let instanceURL;
-            if (argv.profile) {
-              const namedProfile = app.config.profiles?.[argv.profile];
-              if (!namedProfile?.instance_url) {
-                throw errUsage(`Profile "${argv.profile}" is not configured.`);
-              }
-              // An explicit profile is authoritative, including in an
-              // interactive terminal. Never let the picker retarget it.
-              instanceURL = normalizeInstanceURL(namedProfile.instance_url);
-            } else if (argv.instance) {
-              instanceURL = resolveInstanceArg(argv.instance, app.config);
-            } else if (canUsePicker(app, argv)) {
-              // gh-faithful: interactive terminals always get a picker —
-              // existing profiles plus "＋ Add a new instance". Zero profiles
-              // goes straight to the setup wizard.
-              const profileNames = Object.keys(app.config.profiles || {});
-              if (profileNames.length === 0) {
-                const wizard = await loginWizard(app, argv);
-                if (wizard.loggedIn) {
-                  app.ok({ authenticated: true, instance: wizard.instanceURL, profile: wizard.profileName },
-                    { summary: `✓ Authenticated to ${wizard.instanceURL} (profile: ${wizard.profileName})` });
-                } else {
-                  app.ok({ setup: true, instance: wizard.instanceURL, profile: wizard.profileName },
-                    { summary: `Profile "${wizard.profileName}" created for ${wizard.instanceURL}. Run "jsn auth login" to authenticate.` });
-                }
-                return;
-              }
-              const target = await pickLoginTarget(app);
-              if (target.addNew) {
-                instanceURL = resolveInstanceArg(target.instanceName, app.config);
-              } else {
-                instanceURL = normalizeInstanceURL(app.config.profiles[target.name].instance_url);
-              }
-            } else {
-              instanceURL = getEffectiveInstance(app.config);
-              if (!instanceURL) {
-                throw errUsage(`Instance URL required.
-
-Examples:
-  jsn auth login https://dev12345.service-now.com
-  jsn auth login dev373698
-  jsn auth login --basic https://dev328604.service-now.com
-
-Find your instance URL in your browser's address bar when logged into ServiceNow.`);
-              }
-            }
-
-            const target = resolveTargetProfile(argv, app.config, instanceURL);
-            const targetProfile = target.profile;
-            validateLoginSelectors(argv, targetProfile);
-            let targetUsername = targetProfile?.username || '';
-            const useBasic = shouldUseBasicAuth(argv, app.config, instanceURL, targetProfile);
-            const useGck = shouldUseGckAuth(argv, app.config, instanceURL, targetProfile);
-            // --basic (with --password as a compatibility alias): authenticate
-            // with basic auth from env vars and persist it for this profile.
-            if (useGck) {
-              const input = argv.headers || await readBrowserSessionInput();
-              const credentials = await app.auth.loginWithGck(instanceURL, input, targetUsername || undefined);
-              targetUsername = credentials?.username || targetUsername;
-            } else if (useBasic) {
-              const credentials = await app.auth.loginWithPassword(instanceURL, targetUsername || undefined);
-              // A new profile has no configured username yet. The auth
-              // manager saves env/stored credentials under creds.username;
-              // carry that identity into verification and profile creation.
-              targetUsername = credentials?.username || targetUsername;
-            }
-            // --print-url with --wait-file: print URL and wait for code file
-            else if (argv.printUrl && argv.waitFile) {
-              await app.auth.buildAuthURL(instanceURL, argv.waitFile, targetUsername || undefined);
-            }
-            // --print-url: just print the URL and exit
-            else if (argv.printUrl) {
-              const authURL = app.auth.buildAuthURL(instanceURL);
-              console.log(authURL);
-              return;
-            }
-            // --code: exchange the provided authorization code directly
-            else if (argv.code) {
-              await app.auth.loginWithCode(instanceURL, argv.code, targetUsername || undefined);
-            } else {
-              // Interactive: full OAuth flow with browser + prompt
-              await app.auth.login(instanceURL, targetUsername || undefined);
-            }
-
-            // Verify auth by fetching current user
-            let username = '';
-            try {
-              const activeName = app.config.activeProfile || app.config.defaultProfile;
-              const activeProfile = app.config.profiles?.[activeName];
-              const activeInstance = app.getEffectiveInstance?.() || activeProfile?.instance_url || '';
-              const activeUsername = activeProfile?.username || '';
-              const activeMethod = activeProfile?.auth_method || '';
-              const targetMethod = useGck ? 'gck' : useBasic ? 'basic' : 'oauth';
-              const targetDiffers = instanceURL !== activeInstance
-                || targetUsername !== activeUsername
-                || targetMethod !== activeMethod;
-              if (!app.sdk || targetDiffers) {
-                app.sdk = app.getSDKForProfile
-                  ? app.getSDKForProfile(instanceURL, {
-                    authMethod: targetMethod,
-                    username: targetUsername,
-                    profile: targetProfile,
-                  })
-                  : app.sdk;
-              }
-              const user = await app.sdk.getCurrentUser();
-              username = user?.user_name || user?.name || '';
-            } catch {
-              // Non-fatal — token is saved, just couldn't verify
-            }
-
-            // Basic/GCK auth establishes the target identity before the
-            // profile exists; preserve it when verification is unavailable.
-            username = username || targetUsername;
-
-            // Save to profiles — deduplicate by instance URL
-            if (!app.config.profiles) {
-              app.config.profiles = {};
-            }
-
-            // Preserve an explicitly selected profile even when another profile
-            // shares the same instance URL.
-            let profileName = target.name;
-            if (!profileName) {
-              for (const [existingName, existingProfile] of Object.entries(app.config.profiles)) {
-                if (existingProfile.instance_url === instanceURL) {
-                  profileName = existingName;
-                  break;
-                }
-              }
-            }
-
-            // If no existing profile found, generate a name from the URL
-            if (!profileName) {
-              profileName = instanceURL.replace(/https?:\/\//, '').replace(/\.service-now\.com.*/, '').replace(/[^a-zA-Z0-9]/g, '-');
-            }
-
-            app.config.profiles[profileName] = {
-              ...(app.config.profiles[profileName] || {}),
-              instance_url: instanceURL,
-              auth_method: useGck ? 'gck' : useBasic ? 'basic' : 'oauth',
-              username: username || undefined,
-              read_only: argv['read-only'] || undefined,
-              skip_confirmations: argv['skip-confirmations'] || undefined,
-              include_counts: argv['include-counts'] === true ? true : argv['include-counts'] === false ? false : undefined,
-            };
-
-            // Re-save OAuth credentials with username now that we have it,
-            // so they're keyed by <user>@<instance> for per-user isolation.
-            // The legacy bare-instance key is cleaned up behind the
-            // AuthManager seam (credential-store internals don't leak here).
-            if (!useBasic && username) {
-              app.auth.migrateLegacyCredential?.(instanceURL, username);
-            }
-
-            // Set as default if this is the first one
-            const setDefault = !app.config.instanceURL && !app.config.defaultProfile;
-            if (setDefault) {
-              app.config.instanceURL = instanceURL;
-              app.config.defaultProfile = profileName;
-            }
-
-            const { saveConfig } = await import('../config.js');
-            saveConfig(app.config);
-
-            const result = {
-              authenticated: true,
-              instance: instanceURL,
-              username: username || undefined,
-              profile: profileName,
-              default: setDefault || undefined,
-            };
-            const summary = username
-              ? `✓ Authenticated to ${instanceURL} as ${username} (profile: ${profileName})`
-              : `✓ Authenticated to ${instanceURL} (profile: ${profileName})`;
-            app.ok(result, { summary });
-          }),
+          handler: wrap(loginProfile),
         })
         .command({
           command: 'logout [instance]',
           describe: 'Clear stored credentials (keeps the instance entry — use "auth remove" to delete it)',
-          handler: wrap(async (argv, app) => {
-            let instanceURL;
-            if (argv.instance) {
-              instanceURL = resolveInstanceArg(argv.instance, app.config);
-            } else {
-              instanceURL = getEffectiveInstance(app.config);
-              if (!instanceURL) {
-                throw errUsage(`No instance specified.
-
-Examples:
-  jsn auth logout
-  jsn auth logout https://dev12345.service-now.com`);
-              }
-            }
-            const target = resolveTargetProfile(argv, app.config, instanceURL);
-            const username = target.profile?.username ?? null;
-            if (username || canLogoutBareProfile(app, instanceURL, target.profile, !!argv.profile)) {
-              app.auth.logout(instanceURL, username);
-            }
-            app.ok({ logged_out: true, instance: instanceURL }, { summary: `✓ Logged out from ${instanceURL}` });
-          }),
+          handler: wrap(logoutProfile),
         })
         .command({
           command: 'status',
-          describe: 'Show detailed authentication status',
-          handler: wrap(async (argv, app) => {
-            const configuredDefault = app.config.profiles?.[app.config.defaultProfile];
-            const defaultInstance = configuredDefault?.instance_url || app.config.instanceURL || '';
-
-            // Check environment auth
-            const envToken = process.env.SERVICENOW_OAUTH_TOKEN || '';
-
-            const profiles = [];
-            const configuredProfiles = Object.entries(app.config.profiles || {});
-            const selectedProfiles = argv.profile
-              ? configuredProfiles.filter(([name]) => name === argv.profile)
-              : configuredProfiles;
-            for (const [name, profile] of selectedProfiles) {
-              const instance = profile.instance_url;
-              const authOptions = { authMethod: profile.auth_method, username: profile.username };
-              const identityOptions = { username: profile.username, authMethod: profile.auth_method };
-              const isAuth = app.auth.isAuthenticatedFor(instance, identityOptions);
-              const lastSeen = app.auth.getLastSeen(instance, identityOptions);
-              const authState = app.auth.getAuthState(instance, authOptions);
-              const legacy = !isAuth && app.auth.hasLegacyCredentials(instance, identityOptions) ? true : undefined;
-              // Keep the established status field contract: unauthenticated
-              // profiles omit auth_source, except legacy credentials retain
-              // their historical `legacy` marker. getAuthState remains the
-              // safe metadata seam for authenticated profiles.
-              const authSource = isAuth ? authState.auth_source : (legacy ? 'legacy' : undefined);
-
-              // Try live verification through AuthManager's read-only probe seam.
-              let verified = null;
-              let verifiedAt = null;
-              let probe;
-              if (!instance) {
-                probe = app.auth.probeUnavailable?.('missing_instance') || { status: 'not_attempted', code: 'missing_instance', classification: 'unavailable' };
-              } else {
-                try {
-                  const sdk = app.getSDKForProfile
-                    ? app.getSDKForProfile(instance, { ...authOptions, profile })
-                    : app.sdk || { getCurrentUser: async () => null };
-                  let user;
-                  probe = await app.auth.probeCurrentUser(instance, {
-                    getCurrentUser: async (options) => {
-                      user = await sdk.getCurrentUser(options);
-                      return user;
-                    },
-                  }, authOptions);
-                  if (probe.status === 'succeeded' && user?.user_name) {
-                    verified = true;
-                    verifiedAt = user.user_name;
-                  } else if (probe.status !== 'not_attempted') {
-                    verified = false;
-                  }
-                } catch {
-                  probe = app.auth.probeUnavailable?.('sdk_construction_failed') || { status: 'not_attempted', code: 'sdk_construction_failed', classification: 'configuration_error' };
-                  verified = false;
-                }
-              }
-
-              // Calculate days since last seen
-              let daysSinceLastSeen = null;
-              if (lastSeen) {
-                daysSinceLastSeen = Math.floor((Date.now() / 1000 - lastSeen) / 86400);
-              }
-
-              profiles.push({
-                name,
-                instance,
-                authenticated: isAuth,
-                legacy,
-                auth_source: authSource,
-                verified,
-                verified_as: verifiedAt || undefined,
-                last_seen: lastSeen || undefined,
-                days_since_last_seen: daysSinceLastSeen,
-                stale: daysSinceLastSeen > 7,
-                default: name === app.config.defaultProfile,
-                read_only: profile.read_only || false,
-                skip_confirmations: profile.skip_confirmations || false,
-                include_counts: profile.include_counts !== false,
-                diagnostics: {
-                  auth_method: authState.auth_method,
-                  auth_source: authState.auth_source,
-                  state: authState.state,
-                  probe,
-                },
-              });
-            }
-
-            const result = {
-              default_instance: defaultInstance,
-              authenticated: app.auth.isAuthenticated(),
-              environment_auth: envToken ? true : undefined,
-              profiles,
-            };
-
-            const summary = `${profiles.length} profile(s)`;
-            // Ship the styled view as _formatted (see renderAuthStatus); the
-            // OutputWriter prints it verbatim and suppresses the summary.
-            result._formatted = renderAuthStatus(result, summary);
-            app.ok(result, { summary });
-
-            // Warn about legacy credentials that need re-authentication
-            const legacyProfiles = profiles.filter(p => p.legacy);
-            if (legacyProfiles.length > 0) {
-              process.stderr.write(
-                '\n⚠️  This release changed how credentials are stored.\n' +
-                '   Some profiles still use the old format.\n' +
-                '   Run the following to re-authenticate:\n'
-              );
-              for (const p of legacyProfiles) {
-                process.stderr.write(`     jsn auth login ${p.name}\n`);
-              }
-              process.stderr.write('\n');
-            }
+          describe: 'Show authentication status (use --details for users and instance URLs)',
+          builder: sub => sub.option('local', {
+            type: 'boolean', describe: 'Show saved credential state without contacting any instance',
+          }).option('details', {
+            type: 'boolean', describe: 'Include users and instance URLs in status output',
           }),
+          handler: wrap(showAuthStatus),
         })
         .command({
           command: 'refresh [instance]',
-          describe: 'Refresh OAuth token for an instance',
-          handler: wrap(async (argv, app) => {
-            let instanceURL;
-            if (argv.instance) {
-              instanceURL = resolveInstanceArg(argv.instance, app.config);
-            } else {
-              instanceURL = getEffectiveInstance(app.config);
-              if (!instanceURL) {
-                throw errUsage(`No instance specified and no default configured.
-
-Examples:
-  jsn auth refresh
-  jsn auth refresh https://dev12345.service-now.com
-  jsn auth refresh dev12345`);
-              }
-            }
-
-            const target = resolveTargetProfile(argv, app.config, instanceURL);
-            const targetProfile = target.profile;
-            const targetAuthOptions = {
-              authMethod: targetProfile ? targetProfile.auth_method : 'oauth',
-              username: targetProfile?.username,
-            };
-            const creds = await app.auth.getCredentialsFor(
-              instanceURL,
-              targetProfile?.username,
-              targetAuthOptions
-            );
-            const refreshed = await app.auth.refreshToken(instanceURL, creds, targetProfile?.username ?? null);
-
-            // Re-probe domain separation on refresh so the capability flag
-            // stays in sync if the plugin was installed/removed since setup.
-            try {
-              const { isDomainSeparationInstalled } = await import('./domains.js');
-              const sdk = app.getSDKForProfile
-                ? app.getSDKForProfile(instanceURL, {
-                  ...targetAuthOptions,
-                  profile: targetProfile,
-                })
-                : app.sdk;
-              const hasDS = await isDomainSeparationInstalled({ sdk });
-              const name = target.name || app.config.activeProfile || app.config.defaultProfile;
-              if (name && app.config.profiles[name] && app.config.profiles[name].instance_url === instanceURL) {
-                app.config.profiles[name].domain_separation = hasDS;
-                await saveConfig(app.config);
-              }
-            } catch {
-              // Non-fatal — capability probe is best-effort
-            }
-
-            app.ok({
-              refreshed: true,
-              instance: instanceURL,
-              expires_at: refreshed.expires_at,
-            }, { summary: `✓ Token refreshed for ${instanceURL}` });
-          }),
+          describe: 'Refresh OAuth credentials or renew a browser session',
+          builder: sub => sub
+            .option('browser', { type: 'boolean', describe: 'Explicitly open a browser to renew the session' })
+            .option('browser-name', { type: 'string', describe: 'Browser to launch: chromium, chrome, or edge' })
+            .option('browser-url', { type: 'string', describe: 'Advanced: local browser debugging URL (requires --browser)' })
+            .option('headers', { type: 'string', describe: 'Captured browser request headers or cURL command' }),
+          handler: wrap(refreshProfile),
         })
         .command({
           command: 'switch [name]',
-          describe: 'Switch active profile (gh: auth switch)',
+          describe: 'Choose the profile used by default',
           builder: (sub) => sub
             .positional('name', {
               describe: 'Profile name to activate',
               type: 'string',
             }),
-          handler: wrap(async (argv, app) => {
-            let name = argv.name;
-            if (!name) {
-              const profileNames = Object.keys(app.config.profiles || {});
-              if (profileNames.length === 0) {
-                throw errUsage('No profiles configured. Run "jsn auth login" first.');
-              }
-              if (profileNames.length === 1) {
-                name = profileNames[0];
-              } else if (canUsePicker(app, argv)) {
-                const { search } = await import('@inquirer/prompts');
-                const choices = profileNames.map(profileName => ({
-                  name: `${profileName} — ${app.config.profiles[profileName].instance_url}`,
-                  value: profileName,
-                }));
-                const selected = await search({
-                  message: 'Select a profile:',
-                  source: (input) => {
-                    const filter = (input || '').toLowerCase();
-                    return choices.filter(c => c.name.toLowerCase().includes(filter));
-                  },
-                });
-                name = selected;
-              } else {
-                // Never silently switch the active profile for a
-                // non-interactive caller: picking one for them is a
-                // config write they did not ask for.
-                throw errUsageHint(
-                  `Which profile? ${profileNames.length} profiles are configured: ${profileNames.join(', ')}`,
-                  'Pass the profile name: jsn auth switch <name>'
-                );
-              }
-            }
-            await setActiveProfile(app.config, name);
-            app.ok({ active_profile: name }, { summary: `Active profile: ${name}` });
-          }),
+          handler: wrap(switchProfile),
         })
         .command({
           command: 'modify [name]',
-          describe: 'Toggle instance configuration (read-only, skip confirmations, domain)',
+          describe: 'Change profile settings (read-only, counts, delete confirmations, domain)',
           builder: (sub) => sub
+            .option('read-only', { type: 'boolean', describe: 'Set read-only access (use --no-read-only to allow writes)' })
+            .option('include-counts', { type: 'boolean', describe: 'Set result counts (use --no-include-counts to disable)' })
+            .option('confirm-deletes', { type: 'boolean', describe: 'Set delete confirmations (use --no-confirm-deletes to disable)' })
+            .option('skip-confirmations', { type: 'boolean', describe: 'Compatibility flag: disable delete confirmations' })
             .positional('name', {
               describe: 'Profile name to modify',
               type: 'string',
@@ -1043,25 +1155,26 @@ Examples:
               describe: 'Profile name to delete',
               type: 'string',
             }),
-          handler: wrap(async (argv, app) => {
-            let name = argv.name;
-            if (!name) {
-              name = await pickProfile(app, 'Remove which instance?');
-            }
-            await removeProfile(app, name);
-          }),
+          handler: wrap(removeConnection),
         });
     },
-    handler: () => {
-      console.log('Manage authentication for ServiceNow instances.');
-      console.log('');
-      console.log('Available subcommands:');
-      console.log('  login <url|name>  Log in / add an instance (picker when run bare)');
-      console.log('  refresh           Refresh the access token');
-      console.log('  status            Show auth status for all profiles');
-      console.log('');
-      console.log('Tip: "jsn setup" is the interactive manager — add, switch, remove, or modify instances.');
-      console.log('Run "jsn auth <command> --help" for details.');
-    },
+    handler: wrap(async (_argv, app) => {
+      const commands = [
+        { name: 'login', description: 'Sign in or add a connection' },
+        { name: 'status', description: 'Show authentication and connection status' },
+        { name: 'refresh', description: 'Refresh OAuth credentials or renew a browser session' },
+        { name: 'switch', description: 'Choose the default profile' },
+        { name: 'modify', description: 'Change connection settings' },
+        { name: 'logout', description: 'Sign out and keep the profile' },
+        { name: 'remove', description: 'Remove a connection and its credentials' },
+      ];
+      app.ok({
+        commands: commands.map(command => command.name),
+        _formatted: formatCommandList({ title: 'Manage ServiceNow authentication and connection settings', commands }),
+      }, {
+        summary: 'Manage ServiceNow authentication and connection settings',
+        breadcrumbs: [{ action: 'Guided setup', cmd: 'jsn setup', description: 'Interactive login and connection management' }],
+      });
+    }),
   };
 }