fix: prompt for catalog provider API keys and clarify update behavior (#7)

## Related Issue

No linked issue — problem explained below.

## Problem

Connecting a provider from the models.dev catalog in `/login` or
`/provider` failed with `Environment variable "X" is not set or is
empty.` instead of asking for an API key. The same gate also broke the
OpenAI (API key) and Anthropic (API key) login entries, which route
through the same path, and `pythinker provider catalog add` had no way
to pass a key directly. Separately, the update banner and `/update`
implied Homebrew installs auto-update when they deliberately do not, and
the native install scripts pointed at nonexistent release assets.

## What changed

- Catalog provider login now falls back to the API key input dialog when
the provider's environment variable is unset or empty, and stores the
entered key in `config.toml` via the existing `api_key` provider field.
When the env var is set, behavior is unchanged.
- `pythinker provider catalog add` gains `--api-key <key>`, taking
precedence over `--api-key-env` and the catalog's declared env var;
error messages now mention the flag.
- `/update` and the startup update notice state that Homebrew installs
do not auto-update and show the native installer command for automatic
background updates.
- The native install scripts download the correct published release
assets.
- Site: legacy downloads popup and Python download milestone highlight.

Tests: new coverage for the prompt fallback (env set / unset /
undeclared / cancelled) in the TUI, and for `--api-key` precedence and
Commander wiring in the CLI. Full suite green.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/Pythoughts-labs/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [x] I have linked a related issue, or explained the problem above.
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Catalog provider setup now accepts API keys interactively or through
`--api-key`.
- Native installers download verified, architecture-specific release
packages on macOS, Linux, and Windows.
- Added a dismissible community download milestone popup to the website.
- Updated installation guidance, including Homebrew recommendations for
automatic updates.

- **Bug Fixes**
- Provider login no longer fails when the configured API-key environment
variable is missing or empty.

- **Documentation**
  - Updated architecture imagery and installation messaging.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elkaix

.changeset/catalog-provider-api-key-prompt.md

@@ -0,0 +1,5 @@
+---
+'@pythoughts/pythinker-code': patch
+---
+
+Prompt for an API key when connecting a catalog provider whose environment variable is not set, instead of failing with "Environment variable is not set or is empty". Applies to `/login`, `/provider`, and `pythinker provider catalog add`, which now also accepts `--api-key <key>`.

.changeset/homebrew-update-hint.md

@@ -0,0 +1,5 @@
+---
+'@pythoughts/pythinker-code': patch
+---
+
+Explain in `/update` and the startup update notice that Homebrew installs do not auto-update, and point to the native installer for automatic background updates.

.changeset/native-install-script-assets.md

@@ -0,0 +1,5 @@
+---
+'@pythoughts/pythinker-code': patch
+---
+
+Point the native install scripts at the published release assets.

.changeset/old-node-launch-guard.md

@@ -0,0 +1,5 @@
+---
+'@pythoughts/pythinker-code': patch
+---
+
+Show a clear requirement message with the native-installer alternative when the CLI is launched on Node.js older than 26.4, instead of failing with a cryptic flag error.

.github/workflows/install-smoke.yml

@@ -36,4 +36,4 @@ jobs:
 
       - name: Check PowerShell syntax
         run: |
-          pwsh -NoProfile -Command '[void][System.Management.Automation.Language.Parser]::ParseFile("apps/pythinker-web/public/install.ps1", [ref]$null, [ref]$errs); if ($errs.Count) { $errs; exit 1 }'
+          pwsh -NoProfile -Command '$errs = $null; [void][System.Management.Automation.Language.Parser]::ParseFile("apps/pythinker-web/public/install.ps1", [ref]$null, [ref]$errs); if ($errs.Count) { $errs; exit 1 }'

README.md

@@ -227,30 +227,9 @@ See the [configuration docs](https://pythoughts-labs.github.io/pythinker-code/co
 
 Pythinker Code is a **pnpm monorepo**. The CLI consumes capabilities through the SDK and never depends directly on internal engine packages.
 
-```mermaid
-flowchart LR
-  subgraph Apps
-    CLI["pythinker-code<br/>(CLI / TUI)"]
-    WEB["pythinker-web<br/>(Browser UI)"]
-    DASH["dashboard<br/>(Session replay)"]
-  end
-
-  subgraph Packages
-    SDK["node-sdk"]
-    CORE["agent-core"]
-    ANYLLM["Any LLM<br/>(provider abstraction)"]
-    KAOS["kaos<br/>(Execution env)"]
-    SERVER["server<br/>(REST + WebSocket)"]
-  end
-
-  CLI --> SDK
-  WEB --> SERVER
-  DASH --> SERVER
-  SDK --> CORE
-  SERVER --> CORE
-  CORE --> ANYLLM
-  CORE --> KAOS
-```
+<p align="center">
+  <img src="docs/media/Architecture.webp" alt="Pythinker Code architecture" width="836" />
+</p>
 
 | Package | Role |
 |---------|------|

_typos.toml

@@ -25,3 +25,4 @@ nd = "nd"                     # ndJsonStream, `Nd` cron interval token
 dows = "dows"                 # formatDows — days-of-week (cron)
 fo = "fo"                     # `/FO` flag of Windows schtasks
 pn = "pn"                     # "PNGs" tokenized as PN by the checker
+iterm = "iterm"               # iTerm2 terminal app identifier

apps/pythinker-code/src/cli/sub/provider.ts

@@ -65,6 +65,7 @@ interface CatalogListOptions {
 }
 
 interface CatalogAddOptions {
+  readonly apiKey?: string;
   readonly apiKeyEnv?: string;
   readonly defaultModel?: string;
   readonly url?: string;
@@ -331,19 +332,24 @@ export async function handleCatalogAdd(
     deps.exit(1);
   }
 
+  const literalApiKey = opts.apiKey?.trim();
   const apiKeyEnvVar = (opts.apiKeyEnv ?? entry.env?.[0])?.trim();
-  if (apiKeyEnvVar === undefined || apiKeyEnvVar.length === 0) {
-    deps.stderr.write(
-      `Provider "${providerId}" does not declare an API key environment variable.\n`,
-    );
-    deps.exit(1);
-  }
-  const apiKey = deps.env[apiKeyEnvVar]?.trim();
-  if (apiKey === undefined || apiKey.length === 0) {
-    deps.stderr.write(
-      `Environment variable "${apiKeyEnvVar}" is not set or is empty.\n`,
-    );
-    deps.exit(1);
+  let useEnvVar = false;
+  if (literalApiKey === undefined || literalApiKey.length === 0) {
+    if (apiKeyEnvVar === undefined || apiKeyEnvVar.length === 0) {
+      deps.stderr.write(
+        `Provider "${providerId}" does not declare an API key environment variable. Pass --api-key <key>.\n`,
+      );
+      deps.exit(1);
+    }
+    const envValue = deps.env[apiKeyEnvVar]?.trim();
+    if (envValue === undefined || envValue.length === 0) {
+      deps.stderr.write(
+        `Environment variable "${apiKeyEnvVar}" is not set or is empty. Set it or pass --api-key <key>.\n`,
+      );
+      deps.exit(1);
+    }
+    useEnvVar = true;
   }
 
   const models = catalogProviderModels(entry);
@@ -386,7 +392,8 @@ export async function handleCatalogAdd(
     catalogUrl: url,
     wire,
     baseUrl,
-    apiKeyEnvVar,
+    apiKey: useEnvVar ? undefined : literalApiKey,
+    apiKeyEnvVar: useEnvVar ? apiKeyEnvVar : undefined,
     models,
     selectedModelId: opts.defaultModel ?? '',
     thinking: false,
@@ -519,17 +526,19 @@ export function registerProviderCommand(parent: Command, deps?: Partial<Provider
   catalog
     .command('add <providerId>')
     .description('Import a known provider from the catalog by id.')
+    .option('--api-key <key>', 'Provider API key to store in config.toml (takes precedence over --api-key-env).')
     .option('--api-key-env <name>', 'Environment variable containing the provider API key.')
     .option('--default-model <modelId>', 'Mark the imported model as default_model after import.')
     .option('--url <url>', `Override catalog URL. Defaults to ${DEFAULT_CATALOG_URL}.`)
     .action(
       async (
         providerId: string,
-        options: { apiKeyEnv?: string; defaultModel?: string; url?: string },
+        options: { apiKey?: string; apiKeyEnv?: string; defaultModel?: string; url?: string },
       ) => {
         const resolved = resolveDeps(deps);
         await runAction(resolved, () =>
           handleCatalogAdd(resolved, providerId, {
+            apiKey: options.apiKey,
             apiKeyEnv: options.apiKeyEnv,
             defaultModel: options.defaultModel,
             url: options.url,

apps/pythinker-code/src/cli/update/preflight.ts

@@ -168,11 +168,17 @@ export function renderManualUpdateMessage(
       sourceDesc = 'unsupported package manager or layout.';
       break;
   }
+  const homebrewHint =
+    source === 'homebrew'
+      ? `Homebrew installs do not auto-update. For automatic background updates, ` +
+        `switch to the native installer: ${NATIVE_INSTALL_COMMAND_UNIX}\n`
+      : '';
   return (
     `A newer version of ${NPM_PACKAGE_NAME} is available ` +
     `(${currentVersion} -> ${target.version}).\n` +
     `Detected install source: ${sourceDesc}\n` +
-    `To update manually, run: ${installCommand}\n`
+    `To update manually, run: ${installCommand}\n` +
+    homebrewHint
   );
 }
 
@@ -717,7 +723,12 @@ export type ManualUpdateResult =
   | { readonly status: 'check-failed'; readonly message: string }
   | { readonly status: 'started'; readonly version: string }
   | { readonly status: 'in-progress'; readonly version: string }
-  | { readonly status: 'manual'; readonly version: string; readonly command: string };
+  | {
+    readonly status: 'manual';
+    readonly version: string;
+    readonly command: string;
+    readonly source: InstallSource;
+  };
 
 /**
  * Explicit user-requested update (TUI `/update`). Unlike the passive
@@ -746,6 +757,7 @@ export async function startManualUpdate(
       status: 'manual',
       version: target.version,
       command: installCommandFor(source, target.version, platform),
+      source,
     };
   }
 
@@ -763,6 +775,7 @@ export async function startManualUpdate(
       status: 'manual',
       version: target.version,
       command: installCommandFor(source, target.version, platform),
+      source,
     };
   }
 

apps/pythinker-code/src/launcher.ts

@@ -4,6 +4,24 @@ const FFI_FLAG = '--experimental-ffi';
 const FFI_WARNING_FLAG = '--disable-warning=ExperimentalWarning';
 const FFI_CHILD_ENV = 'PYTHINKER_CODE_FFI_CHILD';
 const REQUIRED_RUNTIME = 'Node.js 26.4.0 or newer with experimental FFI support';
+const MINIMUM_NODE = [26, 4, 0] as const;
+const NATIVE_INSTALL_HINT =
+  'Alternatively, use the native installer (no Node.js required): https://code.pythinker.com';
+
+/**
+ * Older Node (e.g. 24 LTS) has no `--experimental-ffi`, so the re-exec below
+ * would die with a cryptic `bad option` error. npm installs the package on any
+ * Node version (engines is only a warning for consumers), so guard here with
+ * an actionable message instead.
+ */
+function isRuntimeTooOld(): boolean {
+  const parts = process.versions.node.split('.').map(Number);
+  const [major = 0, minor = 0, patch = 0] = parts;
+  const [reqMajor, reqMinor, reqPatch] = MINIMUM_NODE;
+  if (major !== reqMajor) return major < reqMajor;
+  if (minor !== reqMinor) return minor < reqMinor;
+  return patch < reqPatch;
+}
 
 function isFfiProcess(): boolean {
   // Only execArgv decides: a stale env marker must never bypass the FFI re-exec.
@@ -66,6 +84,15 @@ function launchWindowsFallback(
 }
 
 async function launch(): Promise<void> {
+  if (isRuntimeTooOld()) {
+    process.stderr.write(
+      `Pythinker Code requires ${REQUIRED_RUNTIME}; you are running Node.js ${process.versions.node}.\n` +
+        `${NATIVE_INSTALL_HINT}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
   if (isFfiProcess()) {
     await import(new URL('./main.mjs', import.meta.url).href);
     return;