ima2-gen 1.1.8 → 1.1.9

package/config.ts

@@ -0,0 +1,331 @@
+// config.js — centralized runtime configuration (0.09.12).
+//
+// Single source of truth for ports, limits, paths, and tunables. All server,
+// lib, and script code should import `config` (or named legacy constants) from
+// here rather than reading `process.env` directly.
+//
+// Priority: env var > ${IMA2_CONFIG_DIR}/config.json > built-in default.
+// `config.json` is loaded once at module import. Mutating the file at runtime
+// requires a server restart (same as env vars).
+//
+// Keep this module dependency-free aside from node:* built-ins to avoid
+// circular imports with lib/*.
+
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, existsSync } from "node:fs";
+
+const env = process.env;
+const packageRoot = dirname(fileURLToPath(import.meta.url));
+const configDir = env.IMA2_CONFIG_DIR || join(homedir(), ".ima2");
+
+// ── Optional config.json layer ─────────────────────────────────────────
+// Users can drop `${configDir}/config.json` to override defaults without
+// setting env vars. Shape: same as the `config` object below (partial).
+function loadConfigJson() {
+  const candidates = [
+    join(configDir, "config.json"),
+    join(packageRoot, ".ima2", "config.json"),
+  ];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      const raw = readFileSync(p, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      // ignore malformed config.json; env+defaults still apply
+    }
+  }
+  return {};
+}
+const fileCfg = loadConfigJson();
+
+function firstDefined(...vals) {
+  return vals.find((v) => v !== undefined && v !== "");
+}
+function pickInt(envVal, fileVal, fallback) {
+  const candidate = firstDefined(envVal, fileVal);
+  if (candidate === undefined) return fallback;
+  const n = Number(candidate);
+  return Number.isFinite(n) ? n : fallback;
+}
+function pickPositiveInt(envVal, fileVal, fallback) {
+  const n = pickInt(envVal, fileVal, fallback);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function pickStr(envVal, fileVal, fallback) {
+  return firstDefined(envVal, fileVal) ?? fallback;
+}
+function pickBool(envVal, fileVal, fallback) {
+  const v = firstDefined(envVal, fileVal);
+  if (v === undefined) return fallback;
+  if (typeof v === "boolean") return v;
+  const s = String(v).toLowerCase();
+  return s === "1" || s === "true" || s === "yes";
+}
+
+export function defaultLogLevelForEnv(runtimeEnv = env) {
+  return runtimeEnv.IMA2_DEV === "1" ? "debug" : "info";
+}
+
+export const config = {
+  server: {
+    // Accept both IMA2_PORT and legacy PORT.
+    port: pickInt(firstDefined(env.IMA2_PORT, env.PORT), fileCfg.server?.port, 3333),
+    host: pickStr(env.IMA2_HOST, fileCfg.server?.host, "127.0.0.1"),
+    bodyLimit: pickStr(env.IMA2_BODY_LIMIT, fileCfg.server?.bodyLimit, "50mb"),
+  },
+  limits: {
+    maxRefB64Bytes: pickInt(env.IMA2_MAX_REF_B64_BYTES, fileCfg.limits?.maxRefB64Bytes, 7 * 1024 * 1024),
+    maxMetadataReadB64Bytes: pickInt(
+      env.IMA2_MAX_METADATA_READ_B64_BYTES,
+      fileCfg.limits?.maxMetadataReadB64Bytes,
+      12 * 1024 * 1024,
+    ),
+    maxRefCount: pickInt(env.IMA2_MAX_REF_COUNT, fileCfg.limits?.maxRefCount, 5),
+    maxParallel: pickInt(env.IMA2_MAX_PARALLEL, fileCfg.limits?.maxParallel, 8),
+    graphMaxNodes: pickInt(env.IMA2_GRAPH_MAX_NODES, fileCfg.limits?.graphMaxNodes, 500),
+    graphMaxEdges: pickInt(env.IMA2_GRAPH_MAX_EDGES, fileCfg.limits?.graphMaxEdges, 1000),
+    promptImportMaxFileBytes: pickInt(
+      env.IMA2_PROMPT_IMPORT_MAX_FILE_BYTES,
+      fileCfg.limits?.promptImportMaxFileBytes,
+      512 * 1024,
+    ),
+    promptImportMaxCandidatesPerFile: pickInt(
+      env.IMA2_PROMPT_IMPORT_MAX_CANDIDATES_PER_FILE,
+      fileCfg.limits?.promptImportMaxCandidatesPerFile,
+      100,
+    ),
+    promptImportMaxCandidatesPerImport: pickInt(
+      env.IMA2_PROMPT_IMPORT_MAX_CANDIDATES_PER_IMPORT,
+      fileCfg.limits?.promptImportMaxCandidatesPerImport,
+      100,
+    ),
+    promptImportFetchTimeoutMs: pickInt(
+      env.IMA2_PROMPT_IMPORT_FETCH_TIMEOUT_MS,
+      fileCfg.limits?.promptImportFetchTimeoutMs,
+      8000,
+    ),
+    promptImportMaxCandidateChars: pickInt(
+      env.IMA2_PROMPT_IMPORT_MAX_CANDIDATE_CHARS,
+      fileCfg.limits?.promptImportMaxCandidateChars,
+      12000,
+    ),
+    promptImportMinCandidateChars: pickInt(
+      env.IMA2_PROMPT_IMPORT_MIN_CANDIDATE_CHARS,
+      fileCfg.limits?.promptImportMinCandidateChars,
+      40,
+    ),
+    promptImportMaxSourceCharsScanned: pickInt(
+      env.IMA2_PROMPT_IMPORT_MAX_SOURCE_CHARS_SCANNED,
+      fileCfg.limits?.promptImportMaxSourceCharsScanned,
+      512 * 1024,
+    ),
+    promptImportMaxRepoIndexFiles: pickInt(
+      env.IMA2_PROMPT_IMPORT_MAX_REPO_INDEX_FILES,
+      fileCfg.limits?.promptImportMaxRepoIndexFiles,
+      500,
+    ),
+    promptImportCuratedSearchLimit: pickInt(
+      env.IMA2_PROMPT_IMPORT_CURATED_SEARCH_LIMIT,
+      fileCfg.limits?.promptImportCuratedSearchLimit,
+      50,
+    ),
+    promptImportIndexCacheTtlMs: pickInt(
+      env.IMA2_PROMPT_IMPORT_INDEX_CACHE_TTL_MS,
+      fileCfg.limits?.promptImportIndexCacheTtlMs,
+      24 * 60 * 60 * 1000,
+    ),
+    promptImportMaxFolderFiles: pickInt(
+      env.IMA2_PROMPT_IMPORT_MAX_FOLDER_FILES,
+      fileCfg.limits?.promptImportMaxFolderFiles,
+      100,
+    ),
+    promptImportMaxFolderPreviewFiles: pickInt(
+      env.IMA2_PROMPT_IMPORT_MAX_FOLDER_PREVIEW_FILES,
+      fileCfg.limits?.promptImportMaxFolderPreviewFiles,
+      20,
+    ),
+    promptImportDiscoverySearchLimit: pickInt(
+      env.IMA2_PROMPT_IMPORT_DISCOVERY_SEARCH_LIMIT,
+      fileCfg.limits?.promptImportDiscoverySearchLimit,
+      20,
+    ),
+    promptImportDiscoveryCacheTtlMs: pickInt(
+      env.IMA2_PROMPT_IMPORT_DISCOVERY_CACHE_TTL_MS,
+      fileCfg.limits?.promptImportDiscoveryCacheTtlMs,
+      60 * 60 * 1000,
+    ),
+    promptImportDiscoveryMaxQueries: pickInt(
+      env.IMA2_PROMPT_IMPORT_DISCOVERY_MAX_QUERIES,
+      fileCfg.limits?.promptImportDiscoveryMaxQueries,
+      5,
+    ),
+  },
+  history: {
+    defaultPageSize: pickInt(
+      env.IMA2_HISTORY_PAGE_SIZE,
+      fileCfg.history?.defaultPageSize ?? fileCfg.limits?.historyDefaultPageSize,
+      50,
+    ),
+    maxPageCap: pickInt(
+      env.IMA2_HISTORY_MAX_PAGE,
+      fileCfg.history?.maxPageCap ?? fileCfg.limits?.historyMaxPageCap,
+      500,
+    ),
+  },
+  oauth: {
+    // Accept both IMA2_OAUTH_PROXY_PORT and legacy OAUTH_PORT.
+    proxyPort: pickInt(firstDefined(env.IMA2_OAUTH_PROXY_PORT, env.OAUTH_PORT), fileCfg.oauth?.proxyPort, 10531),
+    // IMA2_NO_OAUTH_PROXY=1 disables auto-start; default is auto-start enabled.
+    autoStart: !pickBool(env.IMA2_NO_OAUTH_PROXY, fileCfg.oauth?.disableAutoStart, false),
+    statusTimeoutMs: pickInt(env.IMA2_OAUTH_STATUS_TIMEOUT_MS, fileCfg.oauth?.statusTimeoutMs, 3000),
+    generationTimeoutMs: pickInt(
+      env.IMA2_OAUTH_GENERATION_TIMEOUT_MS,
+      fileCfg.oauth?.generationTimeoutMs,
+      400 * 1000,
+    ),
+    restartDelayMs: pickInt(env.IMA2_OAUTH_RESTART_DELAY_MS, fileCfg.oauth?.restartDelayMs, 5000),
+    // Provider-backed masked edit is off until upstream STEP-0 verification is recorded.
+    maskedEditEnabled: pickBool(
+      env.IMA2_OAUTH_MASKED_EDIT_ENABLED,
+      fileCfg.oauth?.maskedEditEnabled,
+      false,
+    ),
+    researchSuffix: pickStr(
+      env.IMA2_RESEARCH_SUFFIX,
+      fileCfg.oauth?.researchSuffix,
+      "\n\nIf factual visual accuracy is required and the user's prompt or attached visual context is not already sufficient, use at least one concise web_search call for references before generating. If the user's prompt is already visually sufficient, do not search, rewrite, translate, summarize, or add clarifiers; pass the user's prompt through as the image_generation prompt argument.",
+    ),
+    validModeration: new Set(
+      Array.isArray(fileCfg.oauth?.validModeration) && fileCfg.oauth.validModeration.length
+        ? fileCfg.oauth.validModeration
+        : ["auto", "low"],
+    ),
+  },
+  github: {
+    token: pickStr(env.IMA2_GITHUB_TOKEN, fileCfg.github?.token, ""),
+  },
+  storage: {
+    configDir,
+    packageRoot,
+    generatedDir: pickStr(env.IMA2_GENERATED_DIR, fileCfg.storage?.generatedDir, join(configDir, "generated")),
+    trashDir: pickStr(env.IMA2_TRASH_DIR, fileCfg.storage?.trashDir, join(configDir, "generated", ".trash")),
+    generatedDirName: pickStr(env.IMA2_GENERATED_DIRNAME, fileCfg.storage?.generatedDirName, "generated"),
+    trashDirName: pickStr(env.IMA2_TRASH_DIRNAME, fileCfg.storage?.trashDirName, ".trash"),
+    dbPath: pickStr(env.IMA2_DB_PATH, fileCfg.storage?.dbPath, join(configDir, "sessions.db")),
+    promptImportIndexCacheFile: pickStr(
+      env.IMA2_PROMPT_IMPORT_INDEX_CACHE_FILE,
+      fileCfg.storage?.promptImportIndexCacheFile,
+      join(configDir, "prompt-import-index.json"),
+    ),
+    promptImportDiscoveryRegistryFile: pickStr(
+      env.IMA2_PROMPT_IMPORT_DISCOVERY_REGISTRY_FILE,
+      fileCfg.storage?.promptImportDiscoveryRegistryFile,
+      join(configDir, "prompt-import-discovery.json"),
+    ),
+    configFile: join(configDir, "config.json"),
+    advertiseFile: pickStr(env.IMA2_ADVERTISE_FILE, fileCfg.storage?.advertiseFile, join(configDir, "server.json")),
+    staticMaxAge: pickStr(env.IMA2_STATIC_MAX_AGE, fileCfg.storage?.staticMaxAge, "1y"),
+  },
+  ids: {
+    generatedHexBytes: pickInt(env.IMA2_GENERATED_HEX_BYTES, fileCfg.ids?.generatedHexBytes, 4),
+    nodeHexBytes: pickInt(env.IMA2_NODE_HEX_BYTES, fileCfg.ids?.nodeHexBytes, 5),
+  },
+  inflight: {
+    ttlMs: pickInt(env.IMA2_INFLIGHT_TTL_MS, fileCfg.inflight?.ttlMs, 10 * 60 * 1000),
+    reapMs: pickInt(env.IMA2_INFLIGHT_REAP_MS, fileCfg.inflight?.reapMs, 60 * 1000),
+    terminalTtlMs: pickInt(env.IMA2_INFLIGHT_TERMINAL_TTL_MS, fileCfg.inflight?.terminalTtlMs, 5 * 60 * 1000),
+  },
+  trash: {
+    ttlMs: pickInt(env.IMA2_TRASH_TTL_MS, fileCfg.trash?.ttlMs, 10_000),
+  },
+  styleSheet: {
+    maxPrefix: pickInt(env.IMA2_STYLE_SHEET_MAX_PREFIX, fileCfg.styleSheet?.maxPrefix, 4000),
+    model: pickStr(env.IMA2_STYLE_MODEL, fileCfg.styleSheet?.model, "gpt-5.4-mini"),
+  },
+  imageModels: {
+    default: pickStr(env.IMA2_IMAGE_MODEL_DEFAULT, fileCfg.imageModels?.default, "gpt-5.4-mini"),
+    valid: new Set(["gpt-5.5", "gpt-5.4", "gpt-5.4-mini"]),
+    unsupported: new Set(["gpt-5.3-codex-spark"]),
+    reasoningEffort: pickStr(
+      env.IMA2_REASONING_EFFORT,
+      fileCfg.imageModels?.reasoningEffort,
+      "medium",
+    ),
+    validReasoningEfforts: new Set(["none", "low", "medium", "high", "xhigh"]),
+  },
+  apiProvider: {
+    defaultImageModel: pickStr(
+      env.IMA2_API_IMAGE_MODEL_DEFAULT,
+      fileCfg.apiProvider?.defaultImageModel,
+      "gpt-5.4-mini",
+    ),
+    defaultReasoningEffort: pickStr(
+      env.IMA2_API_REASONING_EFFORT,
+      fileCfg.apiProvider?.defaultReasoningEffort,
+      "low",
+    ),
+    defaultSize: pickStr(env.IMA2_API_IMAGE_SIZE, fileCfg.apiProvider?.defaultSize, "1024x1024"),
+    allowWebSearch: pickBool(env.IMA2_API_ALLOW_WEB_SEARCH, fileCfg.apiProvider?.allowWebSearch, true),
+  },
+  log: {
+    level: pickStr(env.IMA2_LOG_LEVEL, fileCfg.log?.level, defaultLogLevelForEnv(env)),
+    pretty: env.NODE_ENV !== "production",
+  },
+  features: {
+    cardNews: pickBool(env.IMA2_CARD_NEWS, fileCfg.features?.cardNews, env.IMA2_DEV === "1"),
+  },
+  cardNewsPlanner: {
+    enabled: pickBool(env.IMA2_CARD_NEWS_PLANNER, fileCfg.cardNewsPlanner?.enabled, true),
+    model: pickStr(env.IMA2_CARD_NEWS_PLANNER_MODEL, fileCfg.cardNewsPlanner?.model, "gpt-5.4-mini"),
+    timeoutMs: pickInt(env.IMA2_CARD_NEWS_PLANNER_TIMEOUT_MS, fileCfg.cardNewsPlanner?.timeoutMs, 60_000),
+    deterministicFallback: pickBool(
+      env.IMA2_CARD_NEWS_PLANNER_FALLBACK,
+      fileCfg.cardNewsPlanner?.deterministicFallback,
+      false,
+    ),
+  },
+  comfy: {
+    defaultUrl: pickStr(env.IMA2_COMFY_URL, fileCfg.comfy?.defaultUrl, "http://127.0.0.1:8188"),
+    uploadTimeoutMs: pickPositiveInt(
+      env.IMA2_COMFY_UPLOAD_TIMEOUT_MS,
+      fileCfg.comfy?.uploadTimeoutMs,
+      30_000,
+    ),
+    maxUploadBytes: pickPositiveInt(
+      env.IMA2_COMFY_MAX_UPLOAD_BYTES,
+      fileCfg.comfy?.maxUploadBytes,
+      50 * 1024 * 1024,
+    ),
+  },
+  dev: {
+    viteDevMode: pickBool(env.VITE_IMA2_DEV, fileCfg.dev?.viteDevMode, false),
+  },
+};
+
+export default config;
+
+// ── Backward-compatible flat re-exports (used by lib/inflight.js & earlier
+//    call sites). Prefer `import { config } from "./config.js"` going forward.
+export const PORT = config.server.port;
+export const OAUTH_PORT = config.oauth.proxyPort;
+export const OAUTH_URL = `http://127.0.0.1:${config.oauth.proxyPort}`;
+export const CONFIG_DIR = config.storage.configDir;
+export const CONFIG_FILE = config.storage.configFile;
+export const ADVERTISE_FILE = config.storage.advertiseFile;
+export const DB_FILE = config.storage.dbPath;
+export const GENERATED_DIR = config.storage.generatedDir;
+export const BODY_LIMIT = config.server.bodyLimit;
+export const MAX_REF_B64_BYTES = config.limits.maxRefB64Bytes;
+export const MAX_REFS = config.limits.maxRefCount;
+export const MAX_N = config.limits.maxParallel;
+export const INFLIGHT_TTL_MS = config.inflight.ttlMs;
+export const INFLIGHT_REAP_MS = config.inflight.reapMs;
+export const INFLIGHT_TERMINAL_TTL_MS = config.inflight.terminalTtlMs;
+export const STYLE_SHEET_MAX_PREFIX = config.styleSheet.maxPrefix;
+export const LOG_LEVEL = config.log.level;
+export const NO_OAUTH_PROXY = !config.oauth.autoStart;
+export const DEV_MODE = config.dev.viteDevMode;
+export const CARD_NEWS_ENABLED = config.features.cardNews;

package/docs/API.md

@@ -10,18 +10,20 @@ http://localhost:3333
 
 ## Provider Policy
 
-Image generation is OAuth-only in the current build.
+Image generation supports both OAuth and API-key providers.
 
-- `provider: "oauth"` is the supported generation path.
-- `provider: "api"` returns `403` with `APIKEY_DISABLED` for image generation, edit, and node generation.
-- API keys may still be used by auxiliary developer paths such as billing checks or style-sheet extraction.
+- `provider: "oauth"` uses the local Codex OAuth proxy.
+- `provider: "api"` uses the OpenAI Responses API with the hosted `image_generation` tool.
+- API-key generation covers classic generate, edit, mask-guided edit, multimode, and node generation.
+- If `provider: "api"` is requested without an API key, routes fail before upstream with `401` and `API_KEY_REQUIRED`.
+- Mask edits are mask/selection guided edits, not pixel-perfect inpaint guarantees.
 
 ## Health And Status
 
 | Method | Path | Notes |
 |---|---|---|
 | `GET` | `/api/health` | Server health, version, paths, provider policy |
-| `GET` | `/api/providers` | Provider availability; API-key generation is disabled |
+| `GET` | `/api/providers` | Provider availability and runtime ports |
 | `GET` | `/api/oauth/status` | OAuth proxy status and visible models |
 | `GET` | `/api/billing` | Billing/status probe, including API key source when configured |
 
@@ -106,7 +108,7 @@ Recommended model: `gpt-5.4`. Current app default: `gpt-5.4-mini`. `gpt-5.5` is
 
 Image edit / image-to-image generation.
 
-The request includes a prompt and image payload. Like `/api/generate`, this route rejects `provider: "api"` unless API-key image generation is intentionally implemented in code.
+The request includes a prompt and image payload. `provider: "api"` sends the prompt and image through the shared Responses image adapter. Optional masks are forwarded as mask guidance, not a pixel-perfect edit guarantee.
 
 ### `POST /api/node/generate`
 
@@ -198,13 +200,14 @@ X-Ima2-Tab-Id
 | `PATCH` | `/api/sessions/:id/style-sheet/enabled` | Toggle style sheet usage |
 | `POST` | `/api/sessions/:id/style-sheet/extract` | Extract style fields from prompt/reference |
 
-Style-sheet extraction can require an API key/openai client. This does not reopen API-key image generation.
+Style-sheet extraction can require an API key/openai client. Image generation also supports `provider: "api"` through the shared Responses API image adapter when an API key is configured.
 
 ## Common Error Codes
 
 | Code | Meaning |
 |---|---|
-| `APIKEY_DISABLED` | API-key image generation is disabled |
+| `API_KEY_REQUIRED` | `provider: "api"` was requested without a configured API key |
+| `APIKEY_DISABLED` | Legacy/deprecated hard-block code from older builds |
 | `INVALID_IMAGE_MODEL` | Model name is unknown or unsupported |
 | `IMAGE_MODEL_UNSUPPORTED` | Model exists but cannot use image generation |
 | `INVALID_REQUEST` | Upstream request parameters are invalid; raw provider details may be included as `upstreamCode`, `upstreamType`, and `upstreamParam` |
@@ -221,6 +224,43 @@ Style-sheet extraction can require an API key/openai client. This does not reope
 | `GRAPH_TOO_LARGE` | Graph exceeds node/edge limits |
 | `NODE_NOT_FOUND` | Node metadata was not found |
 
+## Endpoint → CLI Mapping
+
+As of 0.09.x, every server route under `/api/*` has a CLI wrapper. Use this table to find the command that calls a given endpoint. (See README.md "Client" section for full flag lists.)
+
+| Endpoint | CLI |
+|---|---|
+| `POST /api/generate` | `ima2 gen` |
+| `POST /api/edit` | `ima2 edit` |
+| `POST /api/generate/multi` (SSE) | `ima2 multimode` |
+| `POST /api/node/generate` (SSE) / `GET /api/node/:id` | `ima2 node generate` / `ima2 node show` |
+| `GET /api/history` | `ima2 ls` |
+| `DELETE /api/history/:name` / `…/permanent` | `ima2 history rm [--permanent]` |
+| `POST /api/history/restore` | `ima2 history restore --trash-id` |
+| `POST /api/history/favorite` | `ima2 history favorite` |
+| `POST /api/history/import-local` | `ima2 history import` |
+| `POST /api/metadata/read` | `ima2 metadata` / `ima2 show --metadata` |
+| `GET/POST/PUT/DELETE /api/sessions[/…]` | `ima2 session ls/show/create/rm/rename` |
+| `GET/PUT /api/sessions/:id/graph` | `ima2 session graph load/save` |
+| `GET/PUT /api/sessions/:id/style-sheet[/…]` | `ima2 session style-sheet …` |
+| `GET/PUT/DELETE /api/annotations/:name` | `ima2 annotate get/set/rm` |
+| `POST /api/canvas-versions` / `PUT /api/canvas-versions/:name` | `ima2 canvas-versions save/update` |
+| `GET/POST/PUT/DELETE /api/prompts[/…]` | `ima2 prompt …` |
+| `GET/POST/PUT/DELETE /api/prompt-folders[/…]` | `ima2 prompt folder …` |
+| `…/api/prompt-import/…` | `ima2 prompt import sources/refresh/curated/discovery/folder` |
+| `…/api/cardnews/…` (gated on `features.cardNews`) | `ima2 cardnews …` |
+| `POST /api/comfy/export-image` | `ima2 comfy export` |
+| `GET /api/inflight` / `DELETE /api/inflight/:id` | `ima2 inflight ls` (alias `ps`) / `ima2 inflight rm` (alias `cancel`) |
+| `GET /api/storage/status` / `POST /api/storage/open-generated-dir` | `ima2 storage status` / `ima2 storage open` |
+| `GET /api/billing` / `GET /api/providers` / `GET /api/oauth/status` | `ima2 billing` / `ima2 providers` / `ima2 oauth status` |
+| `GET /api/health` | `ima2 ping` |
+
+Notes:
+- `ima2 history favorite` and `ima2 annotate …` send `X-Ima2-Browser-Id: cli-<sha1prefix>` derived from the config dir, so CLI activity does not collide with browser sessions.
+- `ima2 session graph save` performs a GET-then-PUT with `If-Match: "<version>"` to guard against `GRAPH_VERSION_CONFLICT`.
+- `ima2 history import` and `ima2 canvas-versions save/update` send raw bytes with `Content-Type: image/<png|jpeg|webp>`; the SSE endpoints (`multimode`, `node generate`) use `Accept: text/event-stream`.
+- `ima2 cardnews …` checks `runtimeConfig.features.cardNews` before calling the gated endpoints; when disabled the CLI exits 2 with a clear message instead of producing a 404.
+
 ## CLI Discovery
 
 The server writes an advertisement file at:

package/docs/CLI.md

@@ -0,0 +1,190 @@
+# CLI Reference
+
+Every server route under `/api/*` has a CLI wrapper. The CLI is a thin shell over the local server, so most commands require a running `ima2 serve` (the few exceptions — `serve`, `setup`, `doctor`, `status`, `open`, `reset`, `config` — work without a live server).
+
+For a quick start, see the [main README](../README.md). For endpoint mapping, see [API.md](API.md).
+
+## Server commands
+
+| Command | Description |
+|---|---|
+| `ima2 serve [--dev]` | Start the local web server; `--dev` enables verbose server diagnostics |
+| `ima2 setup` / `ima2 login` | Reconfigure saved auth (interactive) |
+| `ima2 status` | Show config and OAuth status |
+| `ima2 doctor` | Diagnose Node, package, config, and auth |
+| `ima2 open` | Open the web UI in a browser |
+| `ima2 reset` | Remove saved config |
+
+## Common flags
+
+These work on most client commands:
+
+| Flag | Meaning |
+|---|---|
+| `--server <url>` | Override server discovery (default uses `~/.ima2/server.json`, falls back to `IMA2_SERVER` env) |
+| `--json` | Emit machine-readable JSON instead of human-formatted output |
+| `-h`, `--help` | Show subcommand help |
+
+## Generation
+
+| Command | Description |
+|---|---|
+| `ima2 gen <prompt>` | Generate from the CLI |
+| `ima2 edit <file> --prompt <text>` | Edit an existing image |
+| `ima2 multimode <prompt>` | Multi-image SSE generation (streams `phase` / `partial` / `image` events) |
+| `ima2 node generate` | Node-mode generate (SSE; supports `--no-stream`) |
+| `ima2 node show <nodeId>` | Read node metadata |
+
+Generation flags include `--reasoning-effort {none\|low\|medium\|high\|xhigh}`, `--web-search` / `--no-web-search`, `--model`, `--mode`, `--moderation`, `--ref <file>` (repeatable, up to 5), `-q low|medium|high`, `-n <count>`, `-o <file>`.
+
+```bash
+ima2 gen "a poster of a samurai cat" --model gpt-5.4 --reasoning-effort high
+ima2 edit input.png --prompt "make it rainy" --web-search
+ima2 multimode "two cats playing" -n 2
+ima2 node generate --node n_abc --prompt "add neon lights" --no-stream
+```
+
+## History and metadata
+
+| Command | Description |
+|---|---|
+| `ima2 ls [--session <id>] [--favorites]` | List recent history |
+| `ima2 show <name> [--metadata]` | Reveal a generated asset; optional embedded-metadata read |
+| `ima2 history rm <name> [--permanent]` | Soft-delete (default) or permanently delete |
+| `ima2 history restore --trash-id <id>` | Restore from trash |
+| `ima2 history favorite <name>` | Toggle favorite (sends `X-Ima2-Browser-Id`) |
+| `ima2 history import <file>` | Import a local image (raw PNG/JPEG/WEBP) into history |
+| `ima2 metadata <file>` | Read embedded metadata from any local image (no server roundtrip needed for the read itself, but the route lives on the server) |
+
+## Sessions and graphs
+
+| Command | Description |
+|---|---|
+| `ima2 session ls / show <id> / create <title> / rm <id> / rename <id> <title>` | Session CRUD |
+| `ima2 session graph save <id> --file <graph.json>` | Save a graph (uses GET-then-PUT with `If-Match` to guard against `GRAPH_VERSION_CONFLICT`) |
+| `ima2 session graph load <id>` | Read the latest graph snapshot |
+| `ima2 session style-sheet get <id> / put <id> --file <style.json> / enable <id> / disable <id> / extract <id>` | Style-sheet ops (advanced; UI no longer surfaces this — kept for API-level workflows) |
+
+## Annotations and canvas
+
+| Command | Description |
+|---|---|
+| `ima2 annotate get <name>` | Read annotation for an image |
+| `ima2 annotate set <name> --body <json\|@file\|->` | Write annotation (sends `X-Ima2-Browser-Id`) |
+| `ima2 annotate rm <name>` | Remove annotation |
+| `ima2 canvas-versions save <imagefile> [--source <name>] [--prompt <text>]` | Save a raw PNG canvas version |
+| `ima2 canvas-versions update <name> <imagefile>` | Update an existing canvas version |
+
+## Prompt library
+
+| Command | Description |
+|---|---|
+| `ima2 prompt ls [-q <search>] [--folder <id>] [--favorites]` | List prompts |
+| `ima2 prompt show <id>` | Read one prompt |
+| `ima2 prompt create --name <n> --text <t> [--folder <id>] [--tags <a,b>]` | Create |
+| `ima2 prompt edit <id> [--name] [--text] [--folder] [--tags]` | Edit |
+| `ima2 prompt rm <id>` | Delete |
+| `ima2 prompt favorite <id>` | Toggle favorite |
+| `ima2 prompt export <id> [-o <file>]` | Export one prompt to JSON |
+| `ima2 prompt folder ls / create <name> / rename <id> <name> / rm <id> [--strategy moveToRoot\|deleteItems]` | Folder CRUD |
+| `ima2 prompt import sources` | List configured import sources |
+| `ima2 prompt import refresh --source <id>` | Re-index a source |
+| `ima2 prompt import curated --source <id> --q <query>` | Curated import (commits prompts) |
+| `ima2 prompt import discovery --q <query> --seeds <a,b,c>` | Discovery import (curator-only on some servers) |
+| `ima2 prompt import folder <localpath>` | Import a local folder of prompts |
+
+## Card News (gated)
+
+Card News requires the server to be started with `IMA2_CARD_NEWS=1` (or `features.cardNews: true` in `~/.ima2/config.json`). When disabled, the CLI exits 2 with a clear message instead of producing a 404.
+
+| Command | Description |
+|---|---|
+| `ima2 cardnews templates` | List image-templates and role-templates |
+| `ima2 cardnews template preview <id>` | Preview an image template |
+| `ima2 cardnews sets` | List card sets |
+| `ima2 cardnews set show <id>` / `set manifest <id>` | Show a set or its manifest |
+| `ima2 cardnews draft / generate / export [--data <json>]` | Pass-through bodies (server forwards `req.body`) |
+| `ima2 cardnews job create [--data <json>]` | Create + start a job |
+| `ima2 cardnews job show <jobId>` | Show one job |
+| `ima2 cardnews job retry <jobId> [--cards <id,id>]` | Retry a job (optionally specific cards) |
+| `ima2 cardnews card regenerate <cardId> [--data <json>]` | Regenerate a single card |
+
+## Observability and jobs
+
+| Command | Description |
+|---|---|
+| `ima2 ps` | Alias for `inflight ls` (kept for backward compatibility) |
+| `ima2 cancel <id>` | Alias for `inflight rm` |
+| `ima2 inflight ls [--kind classic\|node] [--session <id>] [--terminal]` | List active (and optionally terminal) jobs with phase / model / prompt |
+| `ima2 inflight rm <requestId>` | Force-remove a stuck job |
+| `ima2 storage status` | Storage inspection (richer than `doctor`) |
+| `ima2 storage open` | Open the generated dir in the OS file manager (POST) |
+| `ima2 billing` | API usage / quota |
+| `ima2 providers` | Configured providers |
+| `ima2 oauth status` | OAuth proxy state |
+| `ima2 ping` | Health-check the running server |
+
+## Config
+
+`config` reads/writes `~/.ima2/config.json` (the file layer). Effective values follow `env > file > defaults`.
+
+| Command | Description |
+|---|---|
+| `ima2 config path` | Print the config file path |
+| `ima2 config ls [--effective]` | Print the file layer (default), or merged effective config with `--effective` |
+| `ima2 config get <key>` | Read a dotted key from the effective config; secrets matching `/token\|secret\|apikey\|password/i` are redacted |
+| `ima2 config set <key> <value>` | Write to the file layer; rejects unknown keys, refuses auth keys (`provider`, `apiKey`), warns when an env var is overriding the same key, prints a restart-required note |
+| `ima2 config rm <key>` | Remove a key from the file layer |
+
+Allowed keys (whitelist):
+
+```
+imageModels.default          imageModels.reasoningEffort
+log.level                    features.cardNews
+cardNewsPlanner.{enabled,model,timeoutMs,deterministicFallback}
+comfy.{defaultUrl,uploadTimeoutMs,maxUploadBytes}
+storage.{generatedDir,generatedDirName}
+server.{port,host,bodyLimit}
+oauth.{proxyPort,statusTimeoutMs,restartDelayMs}
+limits.{maxRefCount,maxParallel}
+history.{defaultPageSize,maxPageCap}
+```
+
+To change `provider` / `apiKey`, run `ima2 setup` or `ima2 login` instead.
+
+## Other
+
+| Command | Description |
+|---|---|
+| `ima2 comfy export <filename>` | Export a ComfyUI workflow (`POST /api/comfy/export-image`) |
+
+## Discovery
+
+The server writes `~/.ima2/server.json` on start. CLI commands read this file to find the actual port (the backend can fall back from `3333` to `3334+`). Override discovery with `--server <url>` or `IMA2_SERVER=http://localhost:3333`.
+
+## Examples
+
+```bash
+# Generation with reasoning effort and web search
+ima2 gen "poster" --model gpt-5.4 --moderation low --reasoning-effort high
+ima2 edit input.png --prompt "make it rainy" --web-search
+ima2 multimode "two cats playing" -n 2 -o cat_{i}.png
+
+# History and metadata
+ima2 ls --session sess_abc --favorites
+ima2 show img_xyz.png --metadata
+ima2 history import ./local.png
+
+# Prompts
+ima2 prompt ls -q sunset
+ima2 prompt import refresh --source curated
+
+# Observability
+ima2 inflight ls --terminal
+ima2 storage status --json
+
+# Config
+ima2 config set imageModels.reasoningEffort high
+ima2 config get log.level
+ima2 config ls --effective --json
+```

package/docs/FAQ.ko.md

@@ -12,7 +12,7 @@ English version: [FAQ.md](FAQ.md)
 |---|---|
 | 서버에 연결되지 않음 | `ima2 serve`를 켠 뒤 `ima2 ping`을 실행합니다. |
 | OAuth 로그인이 안 됨 | `npx @openai/codex login`을 실행하고 `ima2 serve`를 다시 시작합니다. |
-| API key generation disabled | 이미지 생성은 OAuth로 사용합니다. API 키는 일부 보조 기능에서만 쓰입니다. |
+| API key provider가 `API_KEY_REQUIRED`를 반환함 | API 키를 설정하거나 OAuth 공급자로 다시 전환합니다. |
 | 업데이트 후 예전 이미지가 안 보임 | `ima2 doctor`를 실행한 뒤 [예전 이미지 복구 안내](RECOVER_OLD_IMAGES.md)를 확인합니다. |
 | `gpt-5.5`만 실패함 | Codex CLI를 업데이트하고, 안정 대안으로 `gpt-5.4`를 사용합니다. |
 | 레퍼런스 업로드 실패 | JPEG/PNG로 변환하고 해상도를 낮춰 보세요. 레퍼런스는 최대 5장입니다. |
@@ -70,13 +70,13 @@ npm install -g ima2-gen@latest
 
 ### OpenAI API 키가 필요한가요?
 
-이미지 생성에는 필요하지 않습니다. 기본 생성 경로는 로컬 Codex/ChatGPT OAuth 세션을 사용합니다.
+기본 생성 경로에는 필요하지 않습니다. 기본 경로는 로컬 Codex/ChatGPT OAuth 세션을 사용합니다.
 
-설정 화면에서 API 키가 감지될 수는 있습니다. 하지만 이미지 생성 엔드포인트는 `provider: "api"`를 받으면 `APIKEY_DISABLED`로 거절합니다. API 키는 billing 확인이나 style-sheet 추출 같은 보조 기능에만 쓰일 수 있습니다.
+API 키를 설정하면 이미지 생성 엔드포인트도 `provider: "api"`로 Responses API `image_generation` 도구를 사용할 수 있습니다.
 
-### 설정 화면의 "Configured but disabled"는 무슨 뜻인가요?
+### 설정 화면의 "API key provider available"은 무슨 뜻인가요?
 
-env/config에 API 키가 있지만, 현재 빌드에서 API-key 이미지 생성은 비활성화되어 있다는 뜻입니다. 이미지는 OAuth로 생성하세요.
+`ima2-gen`이 유효한 API 키를 찾았다는 뜻입니다. API-Key 모드는 생성, 편집, 멀티모드, 노드 출력을 지원합니다. 키가 없으면 `provider: "api"` 요청은 upstream 호출 전에 `API_KEY_REQUIRED`로 실패합니다.
 
 ### Codex CLI에 이미 로그인되어 있으면 자동으로 잡히나요?