meetsoma 0.2.0 → 0.3.2

package/dist/welcome/auth.js

@@ -0,0 +1,126 @@
+/**
+ * API key setup wizard — guides new users through auth.
+ */
+import { soma as voice } from "../personality.js";
+import { bold, dim, cyan, green, yellow, typeOut, typeParagraph, waitForKey, readSecret } from "../lib/display.js";
+import { hasAnyAuth, getShellConfigPath, getShellConfigAbsPath, openBrowser } from "../lib/detect.js";
+import { appendFileSync } from "fs";
+
+export async function apiKeySetup() {
+  console.log(`  ${yellow("!")} One more thing — Soma needs an AI provider to work.`);
+  console.log("");
+  await typeOut(`  ${voice.spin("{Do you have an Anthropic API key?|Got a Claude API key?|Have an API key for Claude?}")}\n`);
+  console.log("");
+  console.log(`    ${green("y")}  ${dim("Yes, I have a key")}`);
+  console.log(`    ${green("n")}  ${dim("No, I need one")}`);
+  console.log(`    ${green("s")}  ${dim("I have a Claude Pro/Max subscription")}`);
+  console.log(`    ${green("?")}  ${dim("What's an API key?")}`);
+  console.log("");
+
+  const key = await waitForKey(`  ${dim("→")} `);
+  const choice = key.toLowerCase();
+
+  if (choice === "y") {
+    await apiKeyEntry();
+  } else if (choice === "s") {
+    await oauthGuide();
+  } else if (choice === "?") {
+    await apiKeyExplain();
+  } else {
+    await apiKeyGetOne();
+  }
+}
+
+export async function apiKeyExplain() {
+  console.log("");
+  await typeParagraph("An API key is like a password that lets Soma talk to an AI model. You get one from Anthropic (the company that makes Claude), paste it into your terminal config, and Soma handles the rest. Your key stays on your machine — Soma never sends it anywhere.");
+  console.log("");
+  await typeParagraph("If you have a Claude Pro or Max subscription, you don't need a separate key — you can log in with your account instead.");
+  console.log("");
+
+  console.log(`    ${green("g")}  ${dim("Get a key (I'll show you how)")}`);
+  console.log(`    ${green("s")}  ${dim("I have Claude Pro/Max — log in instead")}`);
+  console.log("");
+
+  const key = await waitForKey(`  ${dim("→")} `);
+  if (key.toLowerCase() === "s") {
+    await oauthGuide();
+  } else {
+    await apiKeyGetOne();
+  }
+}
+
+export async function apiKeyGetOne() {
+  console.log("");
+  await typeOut(`  ${voice.spin("{Here's how.|Let me walk you through it.|Quick steps.}")}\n`);
+  console.log("");
+  console.log(`  ${cyan("Step 1:")} Open this link to create a key:`);
+  console.log("");
+  console.log(`    ${cyan("https://console.anthropic.com/settings/keys")}`);
+  console.log("");
+  openBrowser("https://console.anthropic.com/settings/keys");
+  console.log(`    ${dim("(opened in your browser)")}`);
+  console.log("");
+  const { confirm } = await import("../lib/display.js");
+  await confirm(`  ${dim("→")} Press ${bold("Enter")} when you have your key`);
+  await apiKeyEntry();
+}
+
+export async function apiKeyEntry() {
+  console.log("");
+  console.log(`  ${cyan("Step 2:")} Paste your key below.`);
+  console.log(`  ${dim("It starts with")} sk-ant-...`);
+  console.log("");
+
+  const apiKey = await readSecret(`  ${dim("Key:")} `);
+
+  if (!apiKey || !apiKey.startsWith("sk-")) {
+    console.log("");
+    if (!apiKey) {
+      console.log(`  ${dim("No key entered. You can set it up later.")}`);
+    } else {
+      console.log(`  ${yellow("!")} That doesn't look like an Anthropic key.`);
+      console.log(`  ${dim("Keys start with")} sk-ant-...`);
+    }
+    console.log("");
+    const sc = getShellConfigPath();
+    console.log(`  ${dim("When you have your key, add it to")} ${dim(sc)}${dim(":")}`);
+    console.log(`    ${green('export ANTHROPIC_API_KEY="your-key-here"')}`);
+    console.log(`  ${dim("Then restart your terminal and run")} ${green("soma")}`);
+    console.log("");
+    return;
+  }
+
+  const shellConfigPath = getShellConfigAbsPath();
+  const shellConfigName = getShellConfigPath();
+  const exportLine = `\nexport ANTHROPIC_API_KEY="${apiKey}"\n`;
+
+  try {
+    appendFileSync(shellConfigPath, exportLine);
+    console.log("");
+    console.log(`  ${green("✓")} Key saved to ${dim(shellConfigName)}`);
+    console.log("");
+    process.env.ANTHROPIC_API_KEY = apiKey;
+    await typeOut(`  ${voice.spin("{You're all set.|Good to go.|Ready.}")} ${dim("Soma can start now.")}\n`);
+    console.log("");
+  } catch {
+    console.log("");
+    console.log(`  ${yellow("!")} Couldn't write to ${dim(shellConfigName)}.`);
+    console.log(`  ${dim("Add this line manually:")}`);
+    console.log(`    ${green(`export ANTHROPIC_API_KEY="${apiKey}"`)}`);
+    console.log(`  ${dim("Then restart your terminal and run")} ${green("soma")}`);
+    console.log("");
+  }
+}
+
+export async function oauthGuide() {
+  console.log("");
+  await typeParagraph("Nice — with a Pro or Max subscription, you can log in with your Anthropic account. No API key needed.");
+  console.log("");
+  console.log(`  ${dim("When Soma starts, type")} ${green("/login")} ${dim("and follow the prompts.")}`);
+  console.log(`  ${dim("It'll open your browser to authenticate.")}`);
+  console.log("");
+  await typeOut(`  ${voice.spin("{Let's launch.|Starting up.|Here we go.}")}\n`);
+  console.log("");
+  process.env._SOMA_OAUTH_PENDING = "1";
+}

package/dist/welcome/intro.js

@@ -0,0 +1,90 @@
+/**
+ * Welcome experience — first run and returning user flow.
+ */
+import { soma as voice } from "../personality.js";
+import { bold, dim, green, white, printSigma, typeOut, typeParagraph, readLine, confirmYN } from "../lib/display.js";
+import { isInstalled, hasAnyAuth, hasGitHubCLI, getGitHubUsername, detectKeyInShellConfig, getShellConfigPath } from "../lib/detect.js";
+import { getCliVersion } from "../lib/detect.js";
+import { SITE_URL } from "../lib/config.js";
+import { apiKeySetup } from "./auth.js";
+import { handleQuestion, interactiveQ } from "./qa.js";
+
+export async function showWelcome(delegateToCore, initSoma) {
+  const VERSION = getCliVersion();
+  printSigma();
+  console.log(`  ${bold("Soma")} ${dim("—")} ${white("the AI agent that remembers")}`);
+  console.log("");
+
+  if (isInstalled()) {
+    const ghUser = hasGitHubCLI() ? getGitHubUsername() : null;
+    if (ghUser) {
+      console.log(`  ${green("✓")} ${voice.greetBack(ghUser)}`);
+    }
+
+    if (!hasAnyAuth()) {
+      console.log(`  ${green("✓")} Core installed`);
+      console.log("");
+
+      const unloadedKey = detectKeyInShellConfig();
+      if (unloadedKey) {
+        console.log(`  ${dim("yellow")} Found ${bold(unloadedKey)} in ${dim(getShellConfigPath())} but it's not loaded.`);
+        console.log(`  ${dim("Restart your terminal and run")} ${green("soma")} ${dim("again.")}`);
+        console.log("");
+        return;
+      }
+
+      await apiKeySetup();
+
+      if (!hasAnyAuth() && !process.env.ANTHROPIC_API_KEY && !process.env._SOMA_OAUTH_PENDING) {
+        console.log(`  ${dim("No worries.")} ${voice.spin("{Come back when you're ready.|Set up a key and run soma again.|We'll be here.}")}`);
+        console.log("");
+        console.log(`  ${dim(`v${VERSION} · BSL 1.1 · soma.gravicity.ai`)}`);
+        console.log("");
+        return;
+      }
+    } else {
+      console.log(`  ${green("✓")} Core installed. Starting Soma...`);
+    }
+    console.log("");
+    await delegateToCore();
+    return;
+  }
+
+  // ── Not installed — first time ever ──
+  await typeOut(`  ${voice.greet()}\n`);
+  console.log("");
+  await typeParagraph("Soma is an AI coding agent that remembers across sessions. It learns your patterns, builds its own tools, and picks up where it left off.");
+  console.log("");
+  console.log(`  ${dim("─".repeat(58))}`);
+  console.log("");
+  console.log(`  ${dim("→")} Press ${green("Enter")} to set up, or type a question.`);
+  console.log("");
+
+  const input = await readLine(`  ${dim("→")} `);
+
+  if (input && input !== "") {
+    await handleQuestion(input);
+    await interactiveQ();
+  }
+
+  await initSoma();
+
+  if (isInstalled() && !hasAnyAuth()) {
+    await apiKeySetup();
+  }
+
+  if (isInstalled() && (hasAnyAuth() || process.env.ANTHROPIC_API_KEY || process.env._SOMA_OAUTH_PENDING)) {
+    console.log(`  ${dim("─".repeat(58))}`);
+    console.log("");
+    const launch = await confirmYN(`  ${voice.spin("{Ready to go?|Want to start your first session?|Launch Soma?}")}`);
+    if (launch) {
+      console.log("");
+      await delegateToCore();
+      return;
+    }
+  }
+
+  console.log("");
+  console.log(`  ${dim(`v${VERSION} · BSL 1.1 · soma.gravicity.ai`)}`);
+  console.log("");
+}

package/dist/welcome/qa.js

@@ -0,0 +1,131 @@
+/**
+ * Interactive Q&A — "ask me anything" flow for new users.
+ */
+import { soma as voice } from "../personality.js";
+import { bold, dim, cyan, green, typeOut, typeParagraph, readLine } from "../lib/display.js";
+
+const QUESTION_MAP = [
+  { triggers: ["compact", "compaction", "summarise", "summarize", "summarization", "compress", "waiting", "context limit", "token limit", "context fills", "context window", "run out", "limit"], topic: "no_compaction", label: "Why no compaction?" },
+  { triggers: ["heat", "hot", "cold", "fade", "decay", "temperature"],   topic: "what_is_heat",           label: "What is the heat system?" },
+  { triggers: ["breath", "inhale", "exhale", "cycle", "session lifecycle"], topic: "what_is_breath",       label: "What is the breath cycle?" },
+  { triggers: ["protocol", "rule", "behaviour", "behavior", "protocols"], topic: "what_are_protocols",    label: "What are protocols?" },
+  { triggers: ["muscle", "muscles", "learn", "pattern", "grow", "correction"], topic: "what_are_muscles", label: "What are muscles?" },
+  { triggers: ["script", "scripts", "tool", "tools", "automate", "automation"], topic: "what_are_scripts", label: "What are scripts?" },
+  { triggers: ["memory", "remember", "forget", "remembers", "change"],   topic: "how_memory_works",      label: "How does memory work?" },
+  { triggers: ["license", "source", "open", "bsl", "mit", "available"], topic: "why_source_available",   label: "Why source-available?" },
+  { triggers: ["install", "set up", "setup", "get started", "start", "begin", "getting started", "requirements", "require", "need to", "prerequisites"],      topic: "how_to_install",  label: "How do I install?" },
+  { triggers: ["sign up", "signup", "register", "join", "invite", "invitation", "apply"], topic: "how_to_source",    label: "How do I get source access?" },
+  { triggers: ["cost", "price", "pricing", "free", "pay", "money", "subscription", "plan"],            topic: "how_to_cost",     label: "What does it cost?" },
+  { triggers: ["language", "languages", "python", "rust", "java", "typescript", "ruby", "go", "cpp", "swift"], topic: "how_to_languages", label: "What languages does it support?" },
+  { triggers: ["api key", "api_key", "anthropic", "openai", "gemini", "key", "token", "provider"],     topic: "how_to_api_key",  label: "Do I need an API key?" },
+  { triggers: ["model", "llm", "claude", "gpt", "which model", "what model"],                          topic: "how_to_model",    label: "What model does it use?" },
+  { triggers: ["try", "demo", "preview", "test", "sample", "example"],                                 topic: "how_to_try",      label: "Can I try it?" },
+  { triggers: ["are you ai", "are you real", "are you alive", "sentient", "conscious", "artificial"],  topic: "meta_self",       label: "Are you AI?" },
+  { triggers: ["feel", "feelings", "emotion", "aware", "think", "alive"],                              topic: "meta_feelings",   label: "Do you have feelings?" },
+  { triggers: ["who made", "who built", "who created", "creator", "developer", "behind"],              topic: "meta_who_made",   label: "Who made Soma?" },
+  { triggers: ["cursor", "copilot", "windsurf", "claude code", "cline", "better", "competitor", "vs", "compared"], topic: "meta_competitor", label: "How does Soma compare?" },
+  { triggers: ["how do you work", "how does this work", "what are you", "how are you built"],          topic: "meta_how_work",   label: "How does this CLI work?" },
+  { triggers: ["cool", "amazing", "impressive", "wow", "nice", "love", "awesome", "brilliant"],        topic: "meta_impressed",  label: "I'm impressed" },
+  { triggers: ["soma", "agent", "what is"],                              topic: "what_is_soma",          label: "What is Soma?" },
+];
+
+function matchQuestion(input) {
+  const lower = input.toLowerCase();
+  let best = null;
+  let bestScore = 0;
+  for (const q of QUESTION_MAP) {
+    const score = q.triggers.filter(t => lower.includes(t)).length;
+    if (score > bestScore) {
+      bestScore = score;
+      best = q;
+    }
+  }
+  return best;
+}
+
+export async function handleQuestion(input) {
+  const match = matchQuestion(input);
+  if (match) {
+    const answer = voice.ask(match.topic);
+    console.log("");
+    await typeParagraph(answer);
+    return true;
+  }
+
+  const lower = input.toLowerCase();
+  const rude = /suck|stupid|dumb|trash|garbage|hate|worst|bad|ugly|boring|lame|waste/.test(lower);
+  const impressed = /cool|amazing|wow|nice|love|awesome|brilliant|impressive|neat|sick|fire|goat/.test(lower);
+  const meta = /are you|what are you|how do you|who are you|real|alive|ai\b|bot\b/.test(lower);
+  const greeting = /^(hi|hey|hello|sup|yo|howdy|hola|greetings|good morning|good evening)\b/.test(lower);
+
+  console.log("");
+  if (greeting) {
+    await typeOut(`  ${voice.greet()} ${voice.spin("{Ask me anything.|What do you want to know?|I know about 9 topics — pick one.}")}\n`);
+  } else if (rude) {
+    await typeParagraph(voice.ask("meta_rude"));
+  } else if (impressed) {
+    await typeParagraph(voice.ask("meta_impressed"));
+  } else if (meta) {
+    await typeParagraph(voice.ask("meta_self"));
+  } else {
+    await typeParagraph(voice.ask("meta_nonsense"));
+  }
+  return false;
+}
+
+export async function interactiveQ() {
+  console.log("");
+  console.log(`  ${bold("Ask me anything.")}`);
+  console.log("");
+  console.log(`    ${dim("•")} How do I install?    ${dim("•")} What is heat?`);
+  console.log(`    ${dim("•")} What does it cost?   ${dim("•")} What are muscles?`);
+  console.log(`    ${dim("•")} Why no compaction?   ${dim("•")} Are you AI?`);
+  console.log(`    ${dim("•")} How does it compare? ${dim("•")} Who made this?`);
+  console.log("");
+  console.log(`  ${dim("...or ask anything. Press")} ${green("Enter")} ${dim("when you're ready to install.")}`);
+
+  let rounds = 0;
+  const maxRounds = 8;
+
+  while (rounds < maxRounds) {
+    console.log("");
+    const input = await readLine(`  ${cyan("?")} `);
+
+    if (!input || input === "q" || input === "quit" || input === "exit") {
+      break;
+    }
+
+    await handleQuestion(input);
+    rounds++;
+
+    if (rounds < maxRounds) {
+      console.log("");
+      console.log(`  ${dim("Ask another, or")} ${green("Enter")} ${dim("to install Soma.")}`);
+    }
+  }
+
+  if (rounds >= maxRounds) {
+    console.log("");
+    await typeOut(`  ${voice.spin("{Curious enough?|Intrigued?|Want to see it in action?}")} ${dim("Let's set you up.")}\n`);
+  }
+}
+
+export const CONCEPTS = [
+  { title: "Memory isn't retrieval. Memory is change.",  topic: "how_memory_works" },
+  { title: "Your agent should know who it is.",          topic: "what_is_soma" },
+  { title: "Protocols evolve. Muscles grow.",            topic: "what_are_protocols" },
+  { title: "The breath cycle.",                          topic: "what_is_breath" },
+  { title: "Tools that survive across sessions.",        topic: "what_are_scripts" },
+  { title: "Heat tracks what matters.",                  topic: "what_is_heat" },
+  { title: "What are muscles?",                          topic: "what_are_muscles" },
+  { title: "No compaction. Ever.",                        topic: "no_compaction" },
+];
+
+export function getConceptIndex() {
+  const day = Math.floor(Date.now() / 86400000);
+  return day % CONCEPTS.length;
+}
+
+export function getConceptBody(topic) {
+  return voice.ask(topic) || "";
+}

package/package.json

@@ -1,44 +1,91 @@
 {
-  "name": "meetsoma",
-  "version": "0.2.0",
-  "description": "Soma \u2014 the AI coding agent with self-growing memory",
-  "type": "module",
-  "bin": {
-    "soma": "dist/thin-cli.js"
-  },
-  "files": [
-    "dist/thin-cli.js",
-    "dist/personality.js",
-    "dist/postinstall.js",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "keywords": [
-    "soma",
-    "meetsoma",
-    "ai",
-    "agent",
-    "memory",
-    "coding-agent",
-    "identity",
-    "muscles",
-    "protocols",
-    "self-evolving",
-    "cli",
-    "llm"
-  ],
-  "author": "Gravicity <hello@gravicity.ai>",
-  "license": "BSL-1.1",
-  "homepage": "https://soma.gravicity.ai",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/meetsoma/soma-agent.git"
-  },
-  "scripts": {
-    "postinstall": "node dist/postinstall.js"
-  },
-  "engines": {
-    "node": ">=20.6.0"
-  }
-}
+	"name": "meetsoma",
+	"version": "0.3.2",
+	"description": "AI coding agent with self-growing memory — identity, protocols, and muscles that evolve with use",
+	"type": "module",
+	"piConfig": {
+		"name": "soma",
+		"configDir": ".soma"
+	},
+	"bin": {
+		"soma": "dist/cli.js"
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./hooks": {
+			"types": "./dist/core/hooks/index.d.ts",
+			"import": "./dist/core/hooks/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"bin",
+		"scripts/install-gum.sh",
+		"CHANGELOG.md"
+	],
+	"dependencies": {
+		"@mariozechner/jiti": "^2.6.5",
+		"@mariozechner/pi-agent-core": "^0.64.0",
+		"@mariozechner/pi-ai": "^0.64.0",
+		"@mariozechner/pi-tui": "^0.64.0",
+		"@silvia-odwyer/photon-node": "^0.3.4",
+		"@sinclair/typebox": "^0.34.48",
+		"chalk": "^5.5.0",
+		"cli-highlight": "^2.1.11",
+		"diff": "^8.0.2",
+		"extract-zip": "^2.0.1",
+		"file-type": "^21.1.1",
+		"glob": "^13.0.1",
+		"hosted-git-info": "^9.0.2",
+		"ignore": "^7.0.5",
+		"marked": "^15.0.12",
+		"minimatch": "^10.2.3",
+		"proper-lockfile": "^4.1.2",
+		"strip-ansi": "^7.1.0",
+		"undici": "^7.19.1",
+		"yaml": "^2.8.2"
+	},
+	"overrides": {
+		"rimraf": "6.1.2",
+		"gaxios": {
+			"rimraf": "6.1.2"
+		}
+	},
+	"optionalDependencies": {
+		"@mariozechner/clipboard": "^0.3.2"
+	},
+	"keywords": [
+		"soma",
+		"meetsoma",
+		"ai",
+		"agent",
+		"memory",
+		"coding-agent",
+		"identity",
+		"muscles",
+		"protocols",
+		"self-evolving",
+		"cli",
+		"llm",
+		"persistence",
+		"session"
+	],
+	"author": "Gravicity <hello@gravicity.ai>",
+	"license": "BSL-1.1",
+	"homepage": "https://soma.gravicity.ai",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/meetsoma/soma-agent.git"
+	},
+	"engines": {
+		"node": ">=20.6.0"
+	},
+	"scripts": {
+		"postinstall": "bash scripts/install-gum.sh || true"
+	}
+}

package/scripts/install-gum.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+# ═══════════════════════════════════════════════════════════════════════════
+# install-gum.sh — download gum binary for soma TUI support
+# ═══════════════════════════════════════════════════════════════════════════
+#
+# Called by postinstall. Downloads the correct gum binary for the current
+# platform into the package's bin/ directory. Falls back gracefully —
+# soma works without gum, it just looks better with it.
+#
+# Usage: bash install-gum.sh [--force]
+#
+# Env:
+#   SOMA_SKIP_GUM=1    Skip gum installation entirely
+#   GUM_VERSION         Override version (default: 0.17.0)
+
+set -euo pipefail
+
+GUM_VERSION="${GUM_VERSION:-0.17.0}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PKG_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+BIN_DIR="$PKG_DIR/bin"
+GUM_BIN="$BIN_DIR/gum"
+
+# ─── Skip checks ──────────────────────────────────────────────────────────
+
+if [ "${SOMA_SKIP_GUM:-0}" = "1" ]; then
+  echo "  ℹ Skipping gum install (SOMA_SKIP_GUM=1)"
+  exit 0
+fi
+
+# Already installed and not forcing
+if [ -x "$GUM_BIN" ] && [ "${1:-}" != "--force" ]; then
+  existing=$("$GUM_BIN" --version 2>/dev/null | grep -o '[0-9]*\.[0-9]*\.[0-9]*' || echo "unknown")
+  echo "  ✓ gum $existing already installed"
+  exit 0
+fi
+
+# Check if system gum exists
+if command -v gum >/dev/null 2>&1 && [ "${1:-}" != "--force" ]; then
+  sys_version=$(gum --version 2>/dev/null | grep -o '[0-9]*\.[0-9]*\.[0-9]*' || echo "unknown")
+  echo "  ✓ System gum $sys_version found, skipping bundled install"
+  # Symlink to system gum for consistent path
+  mkdir -p "$BIN_DIR"
+  ln -sf "$(command -v gum)" "$GUM_BIN" 2>/dev/null || true
+  exit 0
+fi
+
+# ─── Detect platform ──────────────────────────────────────────────────────
+
+OS="$(uname -s)"
+ARCH="$(uname -m)"
+
+case "$OS" in
+  Darwin) PLATFORM="Darwin" ;;
+  Linux)  PLATFORM="Linux" ;;
+  MINGW*|MSYS*|CYGWIN*) 
+    echo "  ⚠ Windows detected — install gum manually: scoop install gum"
+    exit 0
+    ;;
+  *)
+    echo "  ⚠ Unsupported OS: $OS — gum TUI features will be unavailable"
+    exit 0
+    ;;
+esac
+
+case "$ARCH" in
+  x86_64|amd64) MACHINE="x86_64" ;;
+  arm64|aarch64) MACHINE="arm64" ;;
+  armv7*)        MACHINE="armv7" ;;
+  armv6*)        MACHINE="armv6" ;;
+  *)
+    echo "  ⚠ Unsupported architecture: $ARCH — gum TUI features will be unavailable"
+    exit 0
+    ;;
+esac
+
+# ─── Download ──────────────────────────────────────────────────────────────
+
+FILENAME="gum_${GUM_VERSION}_${PLATFORM}_${MACHINE}.tar.gz"
+URL="https://github.com/charmbracelet/gum/releases/download/v${GUM_VERSION}/${FILENAME}"
+TMP_DIR=$(mktemp -d)
+
+cleanup() {
+  rm -rf "$TMP_DIR"
+}
+trap cleanup EXIT
+
+echo "  ↓ Downloading gum v${GUM_VERSION} for ${PLATFORM}/${MACHINE}..."
+
+# Try curl first, then wget
+if command -v curl >/dev/null 2>&1; then
+  HTTP_CODE=$(curl -fsSL -o "$TMP_DIR/$FILENAME" -w "%{http_code}" "$URL" 2>/dev/null) || true
+  if [ "$HTTP_CODE" != "200" ] && [ ! -s "$TMP_DIR/$FILENAME" ]; then
+    echo "  ⚠ Download failed (HTTP $HTTP_CODE) — gum TUI features will be unavailable"
+    echo "    Install manually: brew install gum"
+    exit 0
+  fi
+elif command -v wget >/dev/null 2>&1; then
+  wget -q -O "$TMP_DIR/$FILENAME" "$URL" 2>/dev/null || {
+    echo "  ⚠ Download failed — gum TUI features will be unavailable"
+    echo "    Install manually: brew install gum"
+    exit 0
+  }
+else
+  echo "  ⚠ Neither curl nor wget found — install gum manually: brew install gum"
+  exit 0
+fi
+
+# ─── Extract ───────────────────────────────────────────────────────────────
+
+echo "  ⊙ Extracting..."
+tar -xzf "$TMP_DIR/$FILENAME" -C "$TMP_DIR" 2>/dev/null || {
+  echo "  ⚠ Extraction failed — gum TUI features will be unavailable"
+  exit 0
+}
+
+# Find the gum binary in extracted files
+GUM_EXTRACTED=$(find "$TMP_DIR" -name "gum" -type f -perm +111 2>/dev/null | head -1)
+if [ -z "$GUM_EXTRACTED" ]; then
+  GUM_EXTRACTED=$(find "$TMP_DIR" -name "gum" -type f 2>/dev/null | head -1)
+fi
+
+if [ -z "$GUM_EXTRACTED" ]; then
+  echo "  ⚠ gum binary not found in archive — TUI features will be unavailable"
+  exit 0
+fi
+
+# ─── Install ───────────────────────────────────────────────────────────────
+
+mkdir -p "$BIN_DIR"
+rm -f "$GUM_BIN"
+cp "$GUM_EXTRACTED" "$GUM_BIN"
+chmod +x "$GUM_BIN"
+
+# Verify
+if "$GUM_BIN" --version >/dev/null 2>&1; then
+  installed_version=$("$GUM_BIN" --version | grep -o '[0-9]*\.[0-9]*\.[0-9]*')
+  echo "  ✓ gum v${installed_version} installed to $GUM_BIN"
+else
+  echo "  ⚠ gum installed but verification failed"
+fi