ima2-gen 1.0.6 → 1.0.8

package/.env.example

@@ -1,2 +1,49 @@
-OPENAI_API_KEY=sk-proj-your-key-here
-PORT=3333
+# ima2-gen runtime configuration (see config.js).
+# Copy to .env or export in your shell. All keys are optional; defaults live in config.js.
+# Priority: env var > ${IMA2_CONFIG_DIR}/config.json > built-in default.
+
+# ── Server ─────────────────────────────────────────────────────────────
+# IMA2_PORT=3333            # also accepted: PORT
+# IMA2_HOST=127.0.0.1
+# IMA2_BODY_LIMIT=50mb
+
+# ── OAuth proxy (openai-oauth subprocess) ──────────────────────────────
+# IMA2_OAUTH_PROXY_PORT=10531   # also accepted: OAUTH_PORT
+# IMA2_NO_OAUTH_PROXY=1         # disable auto-start (unit tests / CI)
+# IMA2_OAUTH_STATUS_TIMEOUT_MS=3000
+# IMA2_OAUTH_RESTART_DELAY_MS=5000
+# IMA2_RESEARCH_SUFFIX="..."    # appended to every image prompt
+
+# ── Paths ──────────────────────────────────────────────────────────────
+# IMA2_CONFIG_DIR=/custom/path  # defaults to ~/.ima2
+# IMA2_DB_PATH=/custom/sessions.db
+# IMA2_GENERATED_DIR=/custom/generated
+# IMA2_TRASH_DIR=/custom/generated/.trash
+# IMA2_ADVERTISE_FILE=/custom/server.json
+# IMA2_STATIC_MAX_AGE=1y
+
+# ── Limits ─────────────────────────────────────────────────────────────
+# IMA2_MAX_REF_B64_BYTES=7340032   # ~5.2MB decoded
+# IMA2_MAX_REF_COUNT=5
+# IMA2_MAX_PARALLEL=8
+# IMA2_HISTORY_PAGE_SIZE=50
+# IMA2_HISTORY_MAX_PAGE=500
+# IMA2_GRAPH_MAX_NODES=500
+# IMA2_GRAPH_MAX_EDGES=1000
+
+# ── IDs & TTLs ─────────────────────────────────────────────────────────
+# IMA2_GENERATED_HEX_BYTES=4
+# IMA2_NODE_HEX_BYTES=5
+# IMA2_INFLIGHT_TTL_MS=600000
+# IMA2_INFLIGHT_REAP_MS=60000
+# IMA2_TRASH_TTL_MS=10000
+
+# ── Style sheet (0.10) ─────────────────────────────────────────────────
+# IMA2_STYLE_SHEET_MAX_PREFIX=4000
+# IMA2_STYLE_MODEL=gpt-5.4-mini
+
+# ── Logging ────────────────────────────────────────────────────────────
+# IMA2_LOG_LEVEL=info    # trace|debug|info|warn|error|fatal
+
+# ── Secrets (not merged from config.json, env only) ────────────────────
+# OPENAI_API_KEY=sk-...

package/README.md

@@ -1,12 +1,14 @@
 # ima2-gen
 
 [![npm version](https://img.shields.io/npm/v/ima2-gen)](https://www.npmjs.com/package/ima2-gen)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 > **Read in other languages**: [한국어](docs/README.ko.md) · [日本語](docs/README.ja.md) · [简体中文](docs/README.zh-CN.md)
 
-Minimal CLI + web UI for OpenAI **GPT Image 2** (`gpt-image-2`) image generation. OAuth (free via ChatGPT Plus/Pro) or API key. Parallel generation, multi-image references, CLI automation, persistent history.
+`ima2-gen` is a local CLI + web studio for OpenAI image generation through the ChatGPT/Codex OAuth route. It includes a React UI, headless CLI commands, persistent history, reference uploads, production node-mode branching, and safe request observability.
+
+Generation is currently **OAuth-only**. API keys can still be configured for auxiliary developer paths such as billing/status checks and style-sheet extraction, but image generation endpoints reject `provider: "api"` with `APIKEY_DISABLED` unless the provider policy is intentionally changed in code.
 
 ![ima2-gen screenshot](assets/screenshot.png)
 
@@ -15,7 +17,7 @@ Minimal CLI + web UI for OpenAI **GPT Image 2** (`gpt-image-2`) image generation
 ## Quick Start
 
 ```bash
-# Run instantly with npx (no install)
+# Run instantly with npx
 npx ima2-gen serve
 
 # Or install globally
@@ -23,178 +25,218 @@ npm install -g ima2-gen
 ima2 serve
 ```
 
-First run prompts you to pick an auth method:
+The first run opens setup:
 
+```text
+1) API Key  — save an OpenAI API key for supported auxiliary paths
+2) OAuth    — log in with a ChatGPT/Codex account for image generation
 ```
-  Choose authentication method:
-    1) API Key  — paste your OpenAI API key (paid)
-    2) OAuth    — login with ChatGPT account (free)
+
+For the current release, choose OAuth for generation. If Codex is not logged in yet, run:
+
+```bash
+npx @openai/codex login
+ima2 serve
 ```
 
-Web UI opens at `http://localhost:3333`.
+The web UI opens at `http://localhost:3333` by default.
 
 ---
 
-## Features
+## What Works Now
 
-Everything in the screenshot above, shipping today:
+### OAuth Generation
 
-### Authentication
-- **OAuth** — log in with your ChatGPT Plus/Pro account, $0 per image
-- **API Key** — paste your `sk-...` key, pay per call
+- Text-to-image through `/api/generate`
+- Image edit / image-to-image through `/api/edit`
+- Up to 5 reference images per root generation
+- Quality controls: `low`, `medium`, `high`
+- Moderation controls: `low`, `auto`
+- PNG/JPEG/WebP output
+- Parallel count: 1, 2, or 4 from the UI; CLI/server cap is 8
+- Size presets aligned to `gpt-image-2` constraints
 
-Both indicators shown live in the left panel (green dot = ready, red dot = disabled). API key path is hard-disabled by default; OAuth is the primary route.
+### UI Workflow
 
-### Generation controls
-| Control | Options |
-|---------|---------|
-| **Quality** | Low (fast) · Medium (balanced) · High (best) |
-| **Size** | `1024²` `1536×1024` `1024×1536` `1360×1024` `1024×1360` `1824×1024` `1024×1824` `2048²` `2048×1152` `1152×2048` `3824×2160` `2160×3824` · `auto` · custom |
-| **Format** | PNG · JPEG · WebP |
-| **Moderation** | Low (relaxed filter, default) · Auto (standard filter) |
-| **Count** | 1 · 2 · 4 parallel |
+- Prompt composer with drag/drop and Cmd/Ctrl+V image paste
+- Current-image reuse from the canvas
+- Gallery strip and full gallery modal
+- Delete/restore for generated assets
+- Settings workspace opened from the header gear
+- Theme and account/status settings moved out of the crowded sidebar
+- Right sidebar now contains only generation details
+- In-flight jobs survive refresh and reconcile back into the UI
 
-All sizes respect gpt-image-2 constraints: every side is a multiple of 16, long:short ratio ≤ 3:1, 655,360–8,294,400 total pixels.
+### Node Mode
 
-### Workflow
-- **Multi-reference** — attach up to 5 reference images, drag & drop anywhere on the left panel
-- **Prompt-with-context** — mixes text + reference images in one request
-- **Use current** — one-click re-use of the selected image as a new reference
-- **Download** · **Copy to clipboard** · **Copy prompt** directly from the canvas
-- **Sticky gallery strip** at the bottom, fixed-position so it never scrolls away
-- **Gallery modal (+)** — grid view of everything in history
-- **Session persistence** — refresh mid-generation and your pending jobs reconcile automatically
+Node mode is available in the packaged web UI and can be opened from the mode switch next to the composer.
 
-### CLI (headless automation)
-```bash
-ima2 gen "a shiba in space" -q high -o shiba.png
-ima2 gen "merge these" --ref a.png --ref b.png -n 4 -d out/
-ima2 ls -n 10
-ima2 ps
-ima2 ping
-```
+- SQLite-backed graph sessions
+- Branching child generations
+- Duplicate branch / new-from-here flows
+- Node-local reference attachments for root nodes with drag/drop, paste, and file picker support
+- Reference count metadata in node sidecars and history responses
+- Session style sheets that can prepend a house style to node/classic prompts
+- Gallery grouping by session title instead of raw server IDs
+
+### Observability
 
-Full command matrix below ↓
+- Safe structured logs for generation, edit, node, OAuth, session, history, and in-flight lifecycle
+- Correlation by `requestId`
+- Active-only `/api/inflight` by default
+- Optional recent terminal jobs via `/api/inflight?includeTerminal=1`
+- Logs avoid raw prompts, effective prompts, revised prompts, tokens, auth headers, cookies, request bodies, reference data URLs, generated base64, and raw upstream response bodies
 
 ---
 
 ## CLI Commands
 
-### Server commands
+### Server Commands
+
 | Command | Alias | Description |
-|---------|-------|-------------|
-| `ima2 serve` | — | Start the web server (auto-setup on first run) |
-| `ima2 setup` | `login` | Reconfigure authentication method |
-| `ima2 status` | — | Show current config & auth status |
-| `ima2 doctor` | — | Diagnose environment & dependencies |
-| `ima2 open` | — | Open web UI in browser |
-| `ima2 reset` | — | Clear saved configuration |
-| `ima2 --version` | `-v` | Show version |
-| `ima2 --help` | `-h` | Show help |
-
-### Client commands (require a running `ima2 serve`)
+|---|---|---|
+| `ima2 serve` | — | Start the local web server |
+| `ima2 setup` | `login` | Reconfigure saved auth |
+| `ima2 status` | — | Show config and OAuth session status |
+| `ima2 doctor` | — | Diagnose Node, package, config, and auth state |
+| `ima2 open` | — | Open the web UI |
+| `ima2 reset` | — | Remove saved config |
+| `ima2 --version` | `-v` | Print package version |
+| `ima2 --help` | `-h` | Print help |
+
+### Client Commands
+
+These require a running `ima2 serve`.
+
 | Command | Description |
-|---------|-------------|
+|---|---|
 | `ima2 gen <prompt>` | Generate image(s) from the CLI |
-| `ima2 edit <file>` | Edit an existing image (requires `--prompt`) |
-| `ima2 ls` | List recent history (table or `--json`) |
-| `ima2 show <name>` | Reveal one history item (`--reveal`) |
-| `ima2 ps` | List active jobs (`--kind`, `--session`) |
+| `ima2 edit <file> --prompt <text>` | Edit an existing image |
+| `ima2 ls` | List history, table or `--json` |
+| `ima2 show <name>` | Show/reveal a generated asset |
+| `ima2 ps` | List active in-flight jobs |
 | `ima2 ping` | Health-check the running server |
 
-The running server advertises itself at `~/.ima2/server.json`. Client commands auto-discover it; override with `--server <url>` or `IMA2_SERVER=...`.
+The server advertises its port at `~/.ima2/server.json`. Client commands auto-discover it. Override with `--server <url>` or `IMA2_SERVER=http://localhost:3333`.
+
+### Exit Codes
 
-### Exit codes
-`0` ok · `2` bad args · `3` server unreachable · `4` APIKEY_DISABLED · `5` 4xx · `6` 5xx · `7` safety refusal · `8` timeout.
+`0` OK · `2` bad arguments · `3` server unreachable · `4` `APIKEY_DISABLED` · `5` 4xx · `6` 5xx · `7` safety refusal · `8` timeout.
 
 ---
 
-## Roadmap
+## API Endpoints
+
+```text
+GET    /api/health
+GET    /api/providers
+GET    /api/oauth/status
+GET    /api/billing
+GET    /api/inflight
+GET    /api/inflight?includeTerminal=1
+POST   /api/generate
+POST   /api/edit
+GET    /api/history
+GET    /api/history?groupBy=session
+DELETE /api/history/:filename
+POST   /api/history/:filename/restore
+GET    /api/sessions
+POST   /api/sessions
+GET    /api/sessions/:id
+PATCH  /api/sessions/:id
+DELETE /api/sessions/:id
+PUT    /api/sessions/:id/graph
+GET    /api/node/:nodeId
+POST   /api/node/generate
+```
 
-Public roadmap — subject to change. Version numbers reflect the actual ship cycle, not time estimates.
+### OAuth Generation Request
 
-### ✅ Shipped
-- **0.06** Session DB — SQLite-backed history with sidecar JSON
-- **0.07** Multi-reference — up to 5 attachments, i2i merged into unified flow
-- **0.08** Inflight tracking — refresh-safe pending state, phase tracking
-- **0.09** Node mode (dev-only) — graph-based canvas for branching generations
-- **0.09.1** CLI integration — `gen / edit / ls / show / ps / ping` + `/api/health` + port advertisement
+```bash
+curl -X POST http://localhost:3333/api/generate \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "prompt": "a shiba in space",
+    "quality": "medium",
+    "size": "1024x1024",
+    "moderation": "low",
+    "provider": "oauth"
+  }'
+```
 
-### 🚧 0.10 — Compare & Reuse (current cycle)
-- **F3 Prompt presets** — save/apply `{prompt, refs, quality, size}` bundles
-- **F3 Gallery groupBy** — `preset / date / compareRun` grouping
-- **F2 Batch A/B compare** — spawn 2–6 parallel variants from one prompt, keyboard-driven judging (`1-6`, `Space`=winner, `V`=variation, `P`=save preset)
-- **F4 Export bundle** — zip selected images with `manifest.json` + per-image prompt `.txt`
-- Every server verb ships with its CLI mirror (`ima2 preset / compare / export`)
+### API-Key Configuration And Activation Notes
 
-### 🔭 0.11 — Card-news mode
-- Instagram carousel generation (4 / 6 / 10 cards)
-- Style consistency via `file_id` fan-out (not `previous_response_id`, not seed)
-- Parallel card regeneration without breaking the style chain
+Current behavior:
 
-### 🔭 0.12 — Style kit
-- Codified house-style presets with style-reference uploads
-- Optional `input_fidelity: "high"` for identity-critical edits
+- `provider: "oauth"` is the supported generation path.
+- `provider: "api"` returns `403` / `APIKEY_DISABLED` in `routes/generate.js`, `routes/edit.js`, and `routes/nodes.js`.
+- `OPENAI_API_KEY` or `~/.ima2/config.json` can still be used for non-generation helpers such as billing probes and style-sheet extraction.
 
-### 🗂 Backlog
-- Web UI dark/light toggle
-- Keyboard shortcuts cheat-sheet overlay
-- Collaborative sessions (shared SQLite over WebSocket)
-- Plugin system for custom post-processing
+Configure an API key for those auxiliary paths:
 
----
+```bash
+export OPENAI_API_KEY="sk-..."
+ima2 serve
+```
 
-## Architecture
+or:
 
+```json
+{
+  "provider": "api",
+  "apiKey": "sk-..."
+}
 ```
-ima2 serve
-  ├── Express server (:3333)
-  │   ├── GET  /api/health         — version, uptime, activeJobs, pid
-  │   ├── GET  /api/providers      — available auth methods
-  │   ├── GET  /api/oauth/status   — OAuth proxy health check
-  │   ├── POST /api/generate       — text+ref → image (parallel via n)
-  │   ├── POST /api/edit           — ref-heavy edit path
-  │   ├── GET  /api/history        — paginated sidecar listing
-  │   ├── GET  /api/inflight       — in-progress jobs (kind/session filters)
-  │   ├── GET  /api/sessions/*     — node-graph sessions (dev-only)
-  │   ├── GET  /api/billing        — API credit / cost info
-  │   └── Static files (public/)   — web UI
-  │
-  ├── openai-oauth proxy (:10531)  — embedded OAuth relay
-  └── ~/.ima2/server.json          — port advertisement for CLI auto-discovery
-```
 
-**Node mode** is dev-only (`npm run dev`) and gated from npm publishes until the session DB + multi-user story lands.
+saved at `~/.ima2/config.json`.
+
+To intentionally reopen API-key image generation as a developer, audit and change the explicit `provider === "api"` guards in:
+
+- `routes/generate.js`
+- `routes/edit.js`
+- `routes/nodes.js`
+
+Then wire the OpenAI SDK generation/edit implementation, update tests for both OAuth and API-key paths, and update this README. Do not simply remove the guards without adding the API implementation and billing/error tests.
 
 ---
 
 ## Configuration
 
-Config lives in `.ima2/config.json` (auto-created, gitignored).
+Config priority is:
 
-### Environment Variables
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `OPENAI_API_KEY` | — | OpenAI API key (skips OAuth) |
-| `PORT` | `3333` | Web server port |
-| `OAUTH_PORT` | `10531` | OAuth proxy port |
-| `IMA2_SERVER` | — | Client: override target server URL |
-
-```bash
-cp .env.example .env
+```text
+environment variables > ~/.ima2/config.json > built-in defaults
 ```
 
+| Variable | Default | Description |
+|---|---:|---|
+| `IMA2_PORT` / `PORT` | `3333` | Web server port |
+| `IMA2_OAUTH_PROXY_PORT` / `OAUTH_PORT` | `10531` | OAuth proxy port |
+| `IMA2_SERVER` | — | CLI target override |
+| `IMA2_CONFIG_DIR` | `~/.ima2` | Config and SQLite location |
+| `IMA2_GENERATED_DIR` | `~/.ima2/generated` | Generated image directory |
+| `IMA2_NO_OAUTH_PROXY` | — | Set `1` to disable auto-starting the OAuth proxy |
+| `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | Retention for opt-in terminal in-flight debug jobs |
+| `VITE_IMA2_NODE_MODE` | enabled | Set `0` at UI build time to hide node mode |
+| `OPENAI_API_KEY` | — | API key for supported auxiliary paths |
+
 ---
 
-## API Pricing (API Key mode only)
+## Architecture
 
-| Quality | 1024×1024 | 1024×1536 | 1536×1024 | 2048×2048 | 3840×2160 |
-|---------|-----------|-----------|-----------|-----------|-----------|
-| Low     | $0.006    | $0.005    | $0.005    | $0.012    | $0.023    |
-| Medium  | $0.053    | $0.041    | $0.041    | $0.106    | $0.200    |
-| High    | $0.211    | $0.165    | $0.165    | $0.422    | $0.800    |
+```text
+ima2 serve
+  ├── Express server (:3333)
+  │   ├── route modules in routes/
+  │   ├── OAuth image calls via lib/oauthProxy.js
+  │   ├── generated/ image + sidecar JSON storage
+  │   ├── SQLite sessions via better-sqlite3
+  │   └── ui/dist React app
+  ├── openai-oauth proxy (:10531)
+  └── ~/.ima2/server.json for CLI discovery
+```
 
-**OAuth mode is free** — billed against your existing ChatGPT Plus/Pro plan.
+The server uses ES modules, centralized config in `config.js`, and route helpers under `lib/`.
 
 ---
 
@@ -204,50 +246,48 @@ cp .env.example .env
 git clone https://github.com/lidge-jun/ima2-gen.git
 cd ima2-gen
 npm install
-npm run dev    # server with --watch + Node mode enabled
-npm test       # 51+ tests (health, CLI lib, commands, server)
+npm run dev
+npm test
+npm run build
 ```
 
-Frontend stack:
-- Vanilla HTML/CSS/JS (no framework in the published build)
-- Vite + React for the Node-mode canvas (dev-only, gated)
-- Fonts: Outfit + Geist Mono
+`npm run dev` builds the UI and starts `server.js` with `--watch`. Node mode is now a normal product surface in both dev and packaged builds. Set `VITE_IMA2_NODE_MODE=0` only when you intentionally need a classic-only bundle.
 
-## Tech Stack
-- **Runtime**: Node.js ≥18
-- **Server**: Express 5, SQLite (better-sqlite3)
-- **API**: OpenAI SDK v5
-- **OAuth**: `openai-oauth` proxy
-- **Tests**: Node built-in test runner
+Test coverage currently includes CLI behavior, config loading, history pagination/delete/restore, reference validation, OAuth parameter normalization, prompt fidelity, in-flight tracking, safe logging, and route health checks.
 
 ---
 
 ## Troubleshooting
 
-**Port already in use / "why is it on 3457?"**
-→ The default is `3333`. If `PORT` is set in your shell (e.g. inherited from another server like `cli-jaw`), ima2 uses that instead. Unset it or run `PORT=3333 ima2 serve`.
+**`ima2 ping` says the server is unreachable**
+Start `ima2 serve`, then check `~/.ima2/server.json`. You can override discovery with `ima2 ping --server http://localhost:3333`.
 
-**`ima2 ping` says server unreachable**
-→ Is `ima2 serve` running? Check `~/.ima2/server.json`. Override with `ima2 ping --server http://localhost:3333`.
+**OAuth login does not work**
+Run `npx @openai/codex login`, confirm `ima2 status`, then restart `ima2 serve`.
 
-**OAuth login not working**
-→ Run `npx @openai/codex login` manually, then `ima2 serve`.
+**Images fail with `APIKEY_DISABLED`**
+You are trying to generate with `provider: "api"`. Use OAuth for generation in the current release.
 
-**`ima2 doctor` fails on node_modules**
-→ `npm install`.
+**An API key is configured but generation still uses OAuth**
+That is expected. API keys are currently recognized for auxiliary status/extraction paths, not for image generation.
 
-**Images not generating**
-→ `ima2 status` to verify config. API key must start with `sk-`.
+**Port is unexpectedly `3457`**
+Your shell may have inherited `PORT=3457` from another local tool. Run `unset PORT` or start with `IMA2_PORT=3333 ima2 serve`.
 
 ---
 
-## Release
-
-```bash
-npm run release:patch   # 1.0.2 → 1.0.3
-npm run release:minor   # 1.0.x → 1.1.0
-npm run release:major   # 1.x.x → 2.0.0
-```
+## Recent Changelog Highlights
+
+- Node mode enabled in packaged builds
+- Node-local references and branch duplication for node mode
+- `refsCount` metadata for node reference usage
+- npm package includes modular `routes/` server files
+- Settings workspace with account/theme controls
+- Prompt fidelity and revised prompt capture
+- OAuth quality handling for `low`, `medium`, `high`
+- Safer structured request logs and terminal in-flight debug snapshots
+- Session-title gallery grouping
+- Cross-platform CLI fixes for Windows process spawning
 
 ## License
 

package/bin/commands/edit.js

@@ -23,7 +23,7 @@ const HELP = `
 
   Options:
     -p, --prompt <text>        Edit instruction (required)
-    -q, --quality <low|medium|high|auto>
+    -q, --quality <low|medium|high>
     -s, --size <WxH>
     -o, --out <file>
         --json

package/bin/commands/gen.js

@@ -27,7 +27,7 @@ const HELP = `
   Generate image(s) via the running ima2 server.
 
   Options:
-    -q, --quality <low|medium|high|auto>    Default: low
+    -q, --quality <low|medium|high>         Default: low
     -s, --size <WxH | auto>                 Default: 1024x1024
     -n, --count <1..8>                      Default: 1
         --ref <file>                        Attach reference image (repeatable, max 5)

package/bin/ima2.js

@@ -6,16 +6,18 @@ import { fileURLToPath } from "url";
 import { spawn, execSync } from "child_process";
 import { networkInterfaces, homedir } from "os";
 import { openUrl, resolveBin } from "./lib/platform.js";
+import { maybePromptGithubStar } from "./lib/star-prompt.js";
 import { detectCodexAuth } from "../lib/codexDetect.js";
+import { config as runtimeConfig } from "../config.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
 const HOME = homedir();
-// Config lives in $IMA2_CONFIG_DIR (tests) or ~/.ima2 to match server.js and
-// ~/.ima2/server.json advertise path. Legacy installs that stored config at
-// <packageRoot>/.ima2/config.json will be migrated on first write.
-const CONFIG_DIR = process.env.IMA2_CONFIG_DIR || join(HOME, ".ima2");
-const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+// Config lives under runtimeConfig.storage.configDir (honors IMA2_CONFIG_DIR).
+// Legacy installs that stored config at <packageRoot>/.ima2/config.json will be
+// migrated on first write.
+const CONFIG_DIR = runtimeConfig.storage.configDir;
+const CONFIG_FILE = runtimeConfig.storage.configFile;
 const LEGACY_CONFIG_FILE = join(ROOT, ".ima2", "config.json");
 
 // Load package.json for version
@@ -100,6 +102,12 @@ async function setup() {
 }
 
 async function serve() {
+  try {
+    await maybePromptGithubStar();
+  } catch (err) {
+    console.error(`[ima2] Star prompt skipped: ${err?.message || err}`);
+  }
+
   let config = loadConfig();
 
   if (!config.provider) {
@@ -234,7 +242,7 @@ async function doctor() {
   }
 
   // Port availability (simple check)
-  const port = process.env.PORT || 3333;
+  const port = runtimeConfig.server.port;
   console.log(`  ℹ Default port: ${port}`);
 
   console.log(`\n  ${ok} passed, ${fail} failed\n`);
@@ -242,7 +250,7 @@ async function doctor() {
 }
 
 function openBrowser() {
-  const port = process.env.PORT || 3333;
+  const port = runtimeConfig.server.port;
   const url = `http://localhost:${port}`;
   const res = openUrl(url);
   if (res.ok) {