feat: interactive setup command, banner footer, and TTY-gated color

Add a 'setup [shell]' command that installs shell integration for the user:
it detects the shell, then either appends a single 'shannon init' line to the
startup file (resolving the live PowerShell $PROFILE) or prints just that line
to paste — replacing the wall-of-snippet that 'init' dumped. 'init' stays the
raw eval target. The banner gains a title/version/attribution footer, and
output is colorized only when stdout is a TTY (honoring NO_COLOR/FORCE_COLOR)
so pipes, eval'd snippets, and copied text stay plain. Standalone 'use' now
points at 'setup'. Adds integration helpers + tests and documents it.

Author: cbnsndwch

CLAUDE.md

@@ -53,7 +53,7 @@ Profile names must match `[A-Za-z0-9_-]+` (reject empty, leading `.`, `..`, `/`,
 
 ## Command interface
 
-`create <name> [--from <src>] [--with-credentials]`, `list`/`ls`, `default [name]`, `which [name]`, `use <name>`, `clone <src> <dst> [--with-credentials]`, `delete`/`rm <name> [--yes]`, `status`/`st`, `init <shell>`, `update`/`upgrade`, `help`, `--version`. Bare `shannon` (no args) prints profile status and never launches `claude` implicitly. `shannon run …`, `shannon -- …`, or any non-subcommand token launches `claude` with the active profile. `create --from <src>` copies an existing profile (same shared copy routine as `clone`); both omit `.credentials.json` unless `--with-credentials` is passed.
+`create <name> [--from <src>] [--with-credentials]`, `list`/`ls`, `default [name]`, `which [name]`, `use <name>`, `clone <src> <dst> [--with-credentials]`, `delete`/`rm <name> [--yes]`, `status`/`st`, `setup [shell]` (interactive integration installer — adds one `init` line to the shell startup file, or shows it), `init <shell>` (raw emit, eval target), `update`/`upgrade`, `help`, `--version`. Bare `shannon` (no args) prints profile status and never launches `claude` implicitly. `shannon run …`, `shannon -- …`, or any non-subcommand token launches `claude` with the active profile. `create --from <src>` copies an existing profile (same shared copy routine as `clone`); both omit `.credentials.json` unless `--with-credentials` is passed.
 
 ## Design constraints (do not violate)
 
@@ -72,6 +72,7 @@ Profile names must match `[A-Za-z0-9_-]+` (reject empty, leading `.`, `..`, `/`,
 - **M3 (done)** — `create <name> --from <src> [--with-credentials]`: create a profile by copying an existing one, sharing the single `copyProfile` routine behind `clone` (credentials omitted unless `--with-credentials`).
 - **M4 (done)** — release CI: `.github/workflows/ci.yml` (build+test matrix) and `release.yml` (tag-triggered). On a `v*` tag it verifies the tag matches `package.json`, builds Node SEA single-file binaries for linux/macOS/Windows (esbuild bundles `build/sea-entry.ts` → CJS, `postject` injects the blob) uploaded to a GitHub Release via the `gh` CLI, then publishes to npm with provenance (`pnpm publish --provenance`, `id-token: write`, `NPM_TOKEN`). Every action is pinned by commit SHA; pnpm comes from corepack; build-only devDeps (`esbuild`, `postject`) are exact-pinned and runtime deps stay zero. See `RELEASING.md`.
 - **M5 (done)** — docs polish (no analytics): self-contained README with a quickstart, a complete command reference matching the CLI help, shell-integration / per-directory `.shannon` docs, an environment-variable note, a troubleshooting/FAQ, and a short `CONTRIBUTING.md` + `SECURITY.md`. No analytics, tracking, or SEO cruft.
+- **M7 (done)** — UX polish: banner gains a title/version/attribution footer; TTY-gated ANSI colour (`src/core/style.ts`, honoring `NO_COLOR`/`FORCE_COLOR`, never emitted to captured/eval'd output); and an interactive `setup [shell]` command (`src/core/integration.ts` for the pure bits) that adds a single `shannon init` line to the shell startup file for the user — or prints just that line to paste — instead of dumping the full snippet. `init` stays the raw eval target.
 - **M6 (done)** — branding + self-update: a low-entropy dot-halftone portrait banner (`src/banner.ts`) on `status`/`help` with terminal Unicode detection and an ASCII fallback (`SHANNON_BANNER` to force); a passive update check (`src/core/updates.ts`) that refreshes a ≤24h npm-registry cache in a detached background process and appends a one-line CTA to ordinary commands, plus an explicit `update`/`upgrade` command. Opt-out and zero-dep (built-in `fetch`); no runtime dependency added.
 
 ## When modifying

README.md

@@ -102,7 +102,8 @@ A bare `shannon` (or `claudep` / `clp`) prints profile status — it never launc
 | `clone <src> <dst> [--with-credentials]` | Copy a profile. Credentials are omitted unless `--with-credentials`. |
 | `delete <name> [--yes]` (`rm`) | Delete a profile and its data. `--yes` (aliases `-y`, `--force`) skips the confirmation prompt. |
 | `status` (`st`) | Show the active and default profile. |
-| `init <bash\|zsh\|fish\|pwsh>` | Print the shell integration snippet for that shell (see below). |
+| `setup [shell]` | Install shell integration interactively — adds one line to your startup file for you, or shows it to paste (see below). |
+| `init <bash\|zsh\|fish\|pwsh>` | Print the raw shell integration snippet for that shell (what `setup`'s one line re-generates at startup). |
 | `update` (`upgrade`) | Check the npm registry for a newer release and print how to upgrade. |
 | `help` (`-h`, `--help`) | Show the command reference. |
 | `--version` | Print the version. |
@@ -120,7 +121,15 @@ A bare `shannon` (or `claudep` / `clp`) prints profile status — it never launc
 
 ## Shell integration
 
-The launcher already resolves the default profile, but two things need a shell function: making `use` switch the *live* shell, and auto-selecting a profile when you `cd` into a project. Add the line for your shell to its startup file:
+The launcher already resolves the default profile, but two things need a shell function: making `use` switch the *live* shell, and auto-selecting a profile when you `cd` into a project.
+
+The easiest way is to let Shannon set it up for you:
+
+```sh
+shannon setup        # detects your shell, offers to add one line to its startup file
+```
+
+`setup` is interactive: it either adds the line for you or prints just that line to paste — your call. To do it by hand, add the line for your shell to its startup file:
 
 ```sh
 # bash — ~/.bashrc
@@ -136,6 +145,8 @@ shannon init fish | source
 shannon init pwsh | Out-String | Invoke-Expression
 ```
 
+(`shannon init <shell>` prints the full integration that the one line above re-generates on each shell launch — you don't paste that yourself.)
+
 This defines `shannon` / `claudep` / `clp` as thin wrappers around the binary. With it loaded:
 
 ```sh
@@ -158,6 +169,7 @@ Leaving the directory reverts to the default profile. A manual `shannon use` ove
 - **`CLAUDE_CONFIG_DIR`** — the variable Claude Code reads to find its config directory; setting it is how Shannon selects a profile. An explicit value in your environment **overrides the default profile** for that session, and that is what `status` and `list` report as *active*. `shannon use` (with shell integration) sets it for you.
 - **`SHANNON_AUTO`** — internal state managed by the shell hooks to track which profile was auto-selected from a `.shannon` file. You don't set this yourself.
 - **`SHANNON_BANNER`** — controls the portrait banner shown above `status` and `help` (only when stdout is a terminal — it's suppressed for pipes, scripts, and the shell-integration wrappers). By default Shannon auto-detects whether your terminal supports Unicode and falls back to an ASCII rendering otherwise; set `SHANNON_BANNER=ascii` or `SHANNON_BANNER=unicode` to force one.
+- **`NO_COLOR` / `FORCE_COLOR`** — Shannon colorizes output only when stdout is a terminal; set `NO_COLOR` to force plain output or `FORCE_COLOR` to keep colors when piping. (Colors are never written to captured/eval'd output, so copied text and shell snippets stay clean regardless.)
 - **`SHANNON_NO_UPDATE_CHECK`** — set to any value to disable the update check. Shannon otherwise checks the npm registry at most once a day (in a detached background process, never blocking a command) and appends a one-line notice when a newer release exists; the check sends no identifying data. `NO_UPDATE_NOTIFIER` and `CI` are also honored, and the notice is suppressed when output isn't a terminal.
 
 ## Profiles
@@ -175,7 +187,7 @@ Shannon launches the real `claude`; it doesn't bundle it. Install [Claude Code](
 Your package manager's global bin directory isn't on `PATH`. Find it with `pnpm bin -g` (or `npm bin -g`) and add it to your shell's `PATH`. With pnpm, `pnpm setup` configures this for you.
 
 **`shannon use <name>` seems to do nothing.**
-A child process can't change its parent shell's environment, so on its own `use` only prints the export line for you to run. To make it switch the live shell, load [shell integration](#shell-integration) (`shannon init <shell>`) once. Until then, copy the printed `export …` / `$env:…` line.
+A child process can't change its parent shell's environment, so on its own `use` only prints the export line for you to run. To make it switch the live shell, run `shannon setup` once (see [shell integration](#shell-integration)). Until then, copy the printed `export …` / `$env:…` line.
 
 **Migrating from `claude-code-profiles`.**
 Shannon's storage is byte-compatible with the original shell tool (same directory layout, same `.default` file). Your existing profiles just work — there's no migration step. Install Shannon, run `shannon list`, and they'll be there.

src/commands.ts

@@ -1,3 +1,6 @@
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import {
     clearDefault,
@@ -23,6 +26,17 @@ import {
     refreshInBackground,
     updatesDisabled
 } from './core/updates.js';
+import {
+    type Shell,
+    SUPPORTED_SHELLS,
+    alreadyInstalled,
+    blockToAppend,
+    detectShell,
+    integrationLine,
+    isSupportedShell,
+    startupFile
+} from './core/integration.js';
+import { bold, cyan, dim, green, yellow } from './core/style.js';
 
 // Single-sourced against package.json by test/version.test.ts, so a release
 // bump cannot ship a stale self-reported version on npm or the SEA binaries.
@@ -42,6 +56,7 @@ const MANAGEMENT = new Set<string>([
     'status',
     'st',
     'init',
+    'setup',
     'update',
     'upgrade',
     'help',
@@ -121,6 +136,8 @@ async function route(argv: string[]): Promise<number> {
                 return cmdStatus();
             case 'init':
                 return cmdInit(argv.slice(1));
+            case 'setup':
+                return cmdSetup(argv.slice(1));
             case 'update':
             case 'upgrade':
                 return cmdUpdate();
@@ -369,8 +386,12 @@ function cmdUse(args: string[]): number {
     }
 
     // Standalone: a child process cannot mutate the parent shell, so show how.
+    // The human-facing lines go to stderr; the copy/eval-able export lines go to
+    // stdout (plain, so `eval`/redirect capture them cleanly).
+    process.stderr.write(`Profile ${bold(name)} → ${dim(dir)}\n`);
     process.stderr.write(
-        `Profile '${name}' resolved. For seamless 'use', run 'shannon init <shell>' (see help); until then activate it with:\n`
+        `For automatic switching, run ${bold('shannon setup')} once. ` +
+            `Or set it in this shell now:\n`
     );
     process.stdout.write(
         `${exportLine('posix', 'CLAUDE_CONFIG_DIR', dir)}      # bash / zsh\n`
@@ -461,6 +482,169 @@ function cmdInit(args: string[]): number {
     return 0;
 }
 
+/**
+ * Interactive shell-integration installer. Rather than dumping the full snippet
+ * (which belongs at shell-startup, not in the user's hands), it offers to add a
+ * single `shannon init` line to the appropriate startup file for them, or to
+ * print just that line to paste. Non-interactively it only prints instructions —
+ * it never edits a file without a yes.
+ */
+async function cmdSetup(args: string[]): Promise<number> {
+    const requested = args[0];
+    let shell: Shell;
+    if (requested !== undefined) {
+        if (!isSupportedShell(requested)) {
+            throw new ShannonError(
+                `unsupported shell '${requested}'. Supported: ${SUPPORTED_SHELLS.join(', ')}`
+            );
+        }
+        shell = requested;
+    } else {
+        shell = detectShell();
+    }
+    const line = integrationLine(shell);
+    const file = resolveStartupFile(shell);
+
+    if (file && existsSync(file) && alreadyInstalled(readFileSync(file, 'utf8'))) {
+        process.stdout.write(
+            `${green('✓')} Shell integration already set up in ${bold(file)}.\n`
+        );
+        process.stdout.write(
+            dim(`  Restart your shell to pick up any changes.\n`)
+        );
+        return 0;
+    }
+
+    // No prompting unless we have a real terminal both ways — otherwise just
+    // show the manual steps so we never edit a file behind the user's back.
+    if (!(process.stdin.isTTY && process.stdout.isTTY)) {
+        printManualSetup(shell, line, file);
+        return 0;
+    }
+
+    process.stdout.write(
+        `\nSet up ${bold(shell)} integration so ${bold('shannon use')} switches the ` +
+            `live shell and a ${bold('.shannon')} file auto-selects a profile per directory.\n\n`
+    );
+    const choice = await promptMenu([
+        file
+            ? `Set it up for me   ${dim(`(adds one line to ${file})`)}`
+            : 'Set it up for me',
+        'Show me the line to add myself',
+        'Cancel'
+    ]);
+
+    if (choice === 0) {
+        if (!file) {
+            process.stdout.write(
+                yellow('\nCould not locate your PowerShell $PROFILE automatically.\n')
+            );
+            printManualSetup(shell, line, file);
+            return 0;
+        }
+        mkdirSync(dirname(file), { recursive: true });
+        appendFileSync(file, blockToAppend(shell));
+        process.stdout.write(
+            `\n${green('✓')} Added shannon integration to ${bold(file)}.\n`
+        );
+        process.stdout.write(
+            dim(`  Restart your shell (or run ${reloadHint(shell)}) to activate it.\n`)
+        );
+        return 0;
+    }
+    if (choice === 1) {
+        printManualSetup(shell, line, file);
+        return 0;
+    }
+    process.stdout.write('Cancelled.\n');
+    return 0;
+}
+
+/** Print the one line and where it goes, for manual copy/paste. */
+function printManualSetup(
+    shell: Shell,
+    line: string,
+    file: string | null
+): void {
+    const where = file ? bold(file) : 'your shell startup file';
+    process.stdout.write(`\nAdd this line to ${where}:\n\n`);
+    process.stdout.write(`    ${cyan(line)}\n\n`);
+    process.stdout.write(
+        dim(`Then restart your shell or run ${reloadHint(shell)}.\n`)
+    );
+}
+
+/** The command to reload a shell's startup file in place. */
+function reloadHint(shell: Shell): string {
+    switch (shell) {
+        case 'pwsh':
+            return '. $PROFILE';
+        case 'fish':
+            return 'source ~/.config/fish/config.fish';
+        case 'zsh':
+            return 'source ~/.zshrc';
+        default:
+            return 'source ~/.bashrc';
+    }
+}
+
+/**
+ * Resolve the startup file to edit: the conventional path for POSIX shells, or
+ * the live `$PROFILE` for PowerShell (queried by spawning pwsh/powershell, since
+ * it varies — e.g. OneDrive-redirected Documents). Null if it can't be found.
+ */
+function resolveStartupFile(shell: Shell): string | null {
+    if (shell !== 'pwsh') return startupFile(shell);
+    for (const exe of ['pwsh', 'powershell']) {
+        try {
+            const r = spawnSync(
+                exe,
+                [
+                    '-NoProfile',
+                    '-NoLogo',
+                    '-Command',
+                    '$PROFILE.CurrentUserCurrentHost'
+                ],
+                { encoding: 'utf8' }
+            );
+            if (!r.error && r.status === 0) {
+                const path = (r.stdout ?? '').trim();
+                if (path) return path;
+            }
+        } catch {
+            // Try the next executable.
+        }
+    }
+    return null;
+}
+
+/**
+ * Print a numbered menu and return the chosen zero-based index. An empty answer
+ * selects the first (recommended) option; out-of-range answers re-prompt.
+ */
+async function promptMenu(options: string[]): Promise<number> {
+    options.forEach((opt, i) =>
+        process.stdout.write(`  ${bold(String(i + 1))}  ${opt}\n`)
+    );
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    try {
+        for (;;) {
+            const answer = (await rl.question(dim('\nChoose [1]: '))).trim();
+            if (answer === '') return 0;
+            const n = Number.parseInt(answer, 10);
+            if (n >= 1 && n <= options.length) return n - 1;
+            process.stdout.write(
+                yellow(`Please enter a number between 1 and ${options.length}.\n`)
+            );
+        }
+    } finally {
+        rl.close();
+    }
+}
+
 /**
  * Internal: invoked by the `shannon init` directory hook. Emits the shell
  * commands needed to reconcile the auto-selected profile for the working
@@ -557,6 +741,13 @@ function printHelp(): number {
 function printBanner(): void {
     if (!process.stdout.isTTY) return;
     process.stdout.write(banner() + '\n');
+    process.stdout.write(
+        `${bold(cyan('shannon'))} ${dim(`v${VERSION}`)} ` +
+            `${dim('— isolated Claude Code configuration profiles')}\n`
+    );
+    process.stdout.write(
+        dim('  Not affiliated with Anthropic · a nod to Claude Shannon\n')
+    );
 }
 
 // --- helpers ---
@@ -746,7 +937,8 @@ Commands:
   clone <src> <dst>        Copy a profile (omits credentials; --with-credentials to include)
   delete, rm <name>        Delete a profile (--yes/-y/--force to skip confirmation)
   status, st               Show active + default profile
-  init <shell>             Print shell integration (bash | zsh | fish | pwsh)
+  setup [shell]            Install shell integration (interactive; does it for you)
+  init <shell>             Print raw shell integration (bash | zsh | fish | pwsh)
   update, upgrade          Check for a newer release and show how to upgrade
   help, -h, --help         Show this help
   --version                Show version