ima2-gen 1.1.13 → 1.1.16

package/docs/PROMPT_STUDIO.ko.md

@@ -0,0 +1,111 @@
+# Prompt Studio 사용 설명서
+
+Prompt Studio는 이미지를 반복해서 뽑고 비교하는 Classic 작업공간 프로필입니다.
+가운데에는 이미지 뷰어, 옆에는 최근 생성, 아래에는 프롬프트 작성창과 생성
+컨트롤을 둡니다.
+
+어떤 기능인지 헷갈리거나, 작업공간 문제를 재현해서 제보해야 할 때 이 문서를
+먼저 확인하세요.
+
+## 기능 지도
+
+| 영역 | 하는 일 | 참고 |
+|---|---|---|
+| 프롬프트 작성창 | 다음 생성 요청에 보낼 프롬프트를 보관합니다. | 기존 이미지를 선택하는 동작은 보기 전용입니다. 작성창을 덮어쓰면 안 됩니다. |
+| 멀티모드 | 현재 프롬프트로 여러 개의 이미지 요청을 시작합니다. | 각 슬롯은 후보 이미지입니다. 콜라주 칸이나 보장된 연속 장면이 아닙니다. |
+| 1:1 Direct | 앱이 프롬프트를 덜 바꾸고 원문에 가깝게 전달합니다. | 정확한 문구 비교, 엄격한 템플릿, provider 쪽 prompt syntax 실험에 씁니다. |
+| 모델 빠른 메뉴 | 사이드바 상단에서 모델과 추론 강도를 바로 바꿉니다. | 자세한 설명과 전체 설정은 Settings 작업공간에 남아 있습니다. |
+| 최근 생성 | Prompt Studio에서 보이는 최근 생성 범위를 보여줍니다. | 화살표 이동은 화면에 보이는 최근 생성 범위와 맞아야 합니다. |
+| 갤러리 | 로컬 저장 이미지, 전체/즐겨찾기 탭, 폴더를 봅니다. | 즐겨찾기 추가/제거는 보고 있던 갤러리 위치를 유지해야 합니다. |
+| 프롬프트 라이브러리 | 저장된 프롬프트를 의도적으로 작성창에 넣습니다. | 라이브러리 삽입/이어가기 같은 명시적 액션만 프롬프트를 가져옵니다. |
+
+## 멀티모드 프롬프트 작성법
+
+멀티모드는 하나의 요청 형태를 여러 후보 슬롯에 반복해서 보냅니다. 여러 대안을
+뽑는 기능이지, 한 장 안에 여러 칸을 만드는 기능은 아닙니다.
+
+서로 관련 있는 후보를 원하면 공통 대상을 먼저 적고, 바뀌어도 되는 요소를 뒤에
+적으세요.
+
+```text
+모든 이미지에서 같은 캐릭터 디자인: 은발의 배달원, 빨간 우비, 작은 검은 가방.
+4개의 대안을 만들되 카메라 각도, 조명, 배경 골목만 바꿔 주세요.
+얼굴, 옷, 나이, 색감은 유지해 주세요.
+```
+
+서로 관계없는 후보를 원하면 그 점을 직접 적으세요.
+
+```text
+로컬 이미지 생성 앱을 위한 서로 관계없는 스티커 아이디어 4개.
+각 이미지는 마스코트, 색상, 구도가 모두 달라야 합니다.
+```
+
+2컷 만화, 전후 비교, 콜라주, 접촉 시트처럼 한 장 안의 구성이 필요하면
+멀티모드가 아니라 일반 한 장 생성에서 그렇게 요청하세요.
+
+```text
+한 장의 2패널 비교 이미지를 만들어 주세요. 왼쪽은 거친 스케치 UI,
+오른쪽은 다듬어진 Prompt Studio UI. 각 패널 안에 작은 라벨을 넣어 주세요.
+```
+
+## 1:1 Direct
+
+**1:1 Direct**는 프롬프트의 정확한 문구가 중요할 때 켭니다.
+
+- 문구 차이를 비교할 때
+- 구조화된 프롬프트 템플릿을 유지할 때
+- provider 쪽 지시문 스타일을 실험할 때
+- 문제 재현 중 앱의 문구 보정을 줄이고 싶을 때
+
+Direct와 멀티모드를 동시에 켤 수 있습니다. 이때 각 멀티모드 슬롯은 같은 Direct
+프롬프트 요청 형태를 받습니다.
+
+## 추론 강도
+
+추론 강도는 선택한 모델이 생성 전후로 얼마나 많은 계획을 쓰는지에 가까운
+설정입니다. 평소에는 기본값으로 시작하고, 제약이 많거나 레퍼런스/구도 조건이
+복잡할 때 올리세요.
+
+사이드바의 모델 표시를 누르면 모델과 추론 강도를 빠르게 바꿀 수 있습니다.
+자세한 설명과 전체 모델 설정은 Settings 작업공간에 남아 있습니다.
+
+## 갤러리와 프롬프트 안전
+
+Prompt Studio는 보기와 작성을 분리합니다.
+
+- 단순 이미지 선택은 보기 전용입니다.
+- 히스토리나 갤러리 이미지를 클릭하면 이미지를 보는 데만 초점이 갑니다.
+- 즐겨찾기 추가/제거는 저장 이미지의 metadata만 바꾸며, 보던 갤러리 위치를
+  튀게 만들면 안 됩니다.
+- 전체/즐겨찾기 탭 전환은 탐색 필터입니다. 프롬프트를 가져오는 동작이 아닙니다.
+- 프롬프트 라이브러리 삽입, "이 이미지에서 이어가기", 명시적인 재사용 액션은
+  작성창을 바꾸는 의도적 액션입니다.
+
+명시적 프롬프트 가져오기 액션을 썼다면 생성 전에 작성창을 한 번 확인하세요.
+단순 이미지 선택은 작성 중인 초안을 건드리지 않아야 합니다.
+
+## Issue #75 정리
+
+v1.1.13 Prompt Studio 문제를 고치면서 아래 동작을 계약으로 고정했습니다.
+
+- 동시에 끝나는 멀티모드 결과는 각 슬롯/request identity를 유지합니다.
+- 키보드 이동은 화면에 보이는 최근 생성 범위를 따릅니다.
+- 갤러리 버튼은 최근 생성 옆에서 계속 접근 가능해야 합니다.
+- 긴 프롬프트가 기본 이미지 뷰어 영역을 과하게 빼앗지 않습니다.
+- Direct와 멀티모드 상태를 동시에 볼 수 있어야 합니다.
+- 갤러리 즐겨찾기 토글과 탭 전환은 보고 있던 위치를 유지합니다.
+- 기존 이미지를 보기 위해 선택하는 것만으로 작성창이 자동 변경되지 않습니다.
+
+## Prompt Studio 문제 제보 방법
+
+이슈를 열 때는 아래를 포함해 주세요.
+
+- `ima2-gen` 버전과 운영체제
+- 레이아웃 문제라면 브라우저와 화면 크기
+- 작업공간 프로필, 모드 토글, 모델, 추론 강도, 이미지 개수
+- 새 `ima2 serve` 세션에서 재현하는 순서
+- 전체/즐겨찾기/최근 생성 중 어느 화면에서 생겼는지
+- 개인 프롬프트가 드러나지 않는 안전한 스크린샷 또는 화면 녹화
+
+ChatGPT 쿠키, OAuth token 파일, API key, raw upstream response, private prompt
+history, generated base64 data는 공유하지 마세요.

package/docs/PROMPT_STUDIO.md

@@ -0,0 +1,115 @@
+# Prompt Studio Manual
+
+Prompt Studio is the Classic workspace profile for repeated image iteration. It
+keeps the image viewer in the center, recent generations on the side, and the
+composer plus generation controls close to the current image.
+
+Use this page when you are not sure what a Prompt Studio control does or when
+you want a reproducible way to report a workspace issue.
+
+## Feature Map
+
+| Area | What it does | Notes |
+|---|---|---|
+| Composer | Holds the prompt for the next request. | Selecting an existing image is view-only. It should not overwrite the composer. |
+| Multimode | Starts several separate image requests from the current prompt. | Each slot is a candidate output, not a collage panel or a guaranteed scene sequence. |
+| 1:1 Direct | Sends the prompt through with less rewriting by the app. | Use it for exact wording, strict prompt experiments, or provider-side prompt syntax. |
+| Model quick menu | Changes the image model and reasoning effort from the sidebar header. | The full Settings workspace remains the detailed configuration page. |
+| Recent generations | Shows the visible Prompt Studio history domain. | Arrow keys move inside the same visible recent domain instead of hidden older rows. |
+| Gallery | Browses saved local images, All/Favorites tabs, and folders. | Favorite toggles should preserve the gallery viewport you were browsing. |
+| Prompt library | Imports saved prompt text into the composer intentionally. | Library insert/continue actions are explicit prompt imports; passive image selection is not. |
+
+## Multimode Prompting
+
+Multimode repeats one generation request shape across several candidate slots.
+It is useful when you want alternatives, not when you need one combined
+multi-panel image.
+
+For related candidates, put the shared subject first and the variation rule
+second:
+
+```text
+Same character design in every image: a silver-haired courier in a red raincoat.
+Make 4 alternatives that vary only camera angle, lighting, and background street.
+Keep face, outfit, age, and color palette consistent.
+```
+
+For unrelated candidates, say so directly:
+
+```text
+Create 4 unrelated sticker ideas for a local image generation app.
+Each image should use a different mascot, color palette, and composition.
+```
+
+If you need a true two-panel comic, contact sheet, before/after comparison, or
+collage, ask for that in a single normal image request instead of relying on
+multimode slots:
+
+```text
+Create one 2-panel comparison image. Left panel: rough sketch UI. Right panel:
+polished Prompt Studio UI. Add small labels inside each panel.
+```
+
+## Direct Mode
+
+Use **1:1 Direct** when the exact prompt text matters. It is helpful for:
+
+- comparing prompt wording changes,
+- preserving a structured prompt template,
+- using provider-specific instruction style,
+- avoiding app-side phrasing changes during troubleshooting.
+
+Direct mode can be used together with Multimode. In that case, each multimode
+slot receives the same direct prompt request shape.
+
+## Reasoning Effort
+
+Reasoning effort controls how much planning the selected model may spend before
+or during generation. Start with the default for everyday work. Raise it when
+the prompt has many constraints, references, or composition requirements.
+
+The sidebar model label opens quick settings for both model and reasoning. The
+Settings workspace still shows the full model configuration and explanatory
+copy.
+
+## Gallery And Prompt Safety
+
+Prompt Studio separates browsing from composing:
+
+- Passive image selection is view-only.
+- Clicking a history or gallery image focuses the image for viewing.
+- Favorite on/off changes the saved image metadata and should not jump your
+  gallery browsing position.
+- The All and Favorites tabs are browsing filters. Switching between them does
+  not intentionally import a prompt.
+- Prompt Library insert, "continue from this image", and explicit reuse actions
+  are the actions that intentionally change the composer.
+
+Before generating, glance at the composer if you were using explicit prompt
+import actions. Passive image selection should leave your draft alone.
+
+## Issue #75 Closeout Notes
+
+The v1.1.13 Prompt Studio fixes tightened these user-visible contracts:
+
+- concurrent multimode completions keep their slot/request identity,
+- keyboard navigation follows the visible recent history domain,
+- the gallery button remains reachable beside recent history,
+- long prompts no longer starve the default image viewer,
+- Direct and Multimode states can be seen at the same time,
+- gallery favorite toggles and tab changes preserve the browsing viewport,
+- passive image selection does not refill the composer.
+
+## Reporting A Prompt Studio Problem
+
+When opening an issue, include:
+
+- `ima2-gen` version and operating system,
+- browser and viewport size if layout is involved,
+- workspace profile, mode toggles, model, reasoning effort, and image count,
+- numbered steps from a fresh `ima2 serve` session,
+- whether the problem happens in All, Favorites, or recent history,
+- safe screenshots or screen recordings if they do not reveal private prompts.
+
+Do not share ChatGPT cookies, OAuth token files, API keys, raw upstream
+responses, private prompt history, or generated base64 data.

package/docs/README.ko.md

@@ -6,11 +6,13 @@
 
 > 🌐 **Live site**: [lidge-jun.github.io/ima2-gen](https://lidge-jun.github.io/ima2-gen/) · [한국어 페이지](https://lidge-jun.github.io/ima2-gen/ko/)
 >
+> 📖 **개발자 문서**: [문서 사이트](https://lidge-jun.github.io/ima2-gen/ko/docs) · [English](https://lidge-jun.github.io/ima2-gen/docs)
+>
 > **다른 언어로 읽기**: [English](../README.md) · [日本語](README.ja.md) · [简体中文](README.zh-CN.md)
 
 `ima2-gen`은 ChatGPT/Codex OAuth 이미지 생성 흐름을 로컬 웹앱처럼 쓸 수 있게 만든 이미지 생성 스튜디오입니다.
 
-`npx`로 실행하고, Codex OAuth로 로그인한 뒤, 프롬프트를 입력하면서 히스토리, 레퍼런스, 노드 브랜치, 멀티모드 배치, Canvas Mode 정리 작업으로 계속 이어갈 수 있습니다. 기본 이미지 생성 경로에서는 OpenAI API 키가 필요하지 않습니다.
+`npx`로 실행하고, Codex OAuth로 로그인한 뒤, 프롬프트를 입력하면서 히스토리, 레퍼런스, 노드 브랜치, 멀티모드 배치, Canvas Mode 정리 작업으로 계속 이어갈 수 있습니다. 기본 이미지 생성 경로에서는 OpenAI API 키가 필요하지 않으며, 설정된 경우 OpenAI API-key 경로와 번들 Grok 경로도 사용할 수 있습니다.
 
 ![프롬프트 작성창, 생성 이미지, 모델 표시, 결과 메타데이터가 보이는 ima2-gen 클래식 생성 화면](../assets/screenshots/classic-generate-light.png)
 
@@ -50,13 +52,19 @@ ima2 serve
 - **Mobile shell**: 작은 화면에서는 app bar, compose sheet, compact settings toggle로 조작합니다.
 - **Observable jobs**: 진행 중인 작업과 최근 완료된 작업을 request ID로 추적합니다.
 
-## 이미지 생성은 OAuth와 API Key를 지원합니다
+## 이미지 생성 공급자
+
+이미지 생성은 로컬 Codex/ChatGPT OAuth, OpenAI API key, 번들 Grok 공급자를 지원합니다.
 
-기본 이미지 생성은 로컬 Codex/ChatGPT OAuth 경로로 실행됩니다.
+- `provider: "oauth"`는 로컬 Codex OAuth 프록시를 사용합니다.
+- `provider: "api"`는 OpenAI Responses API의 `image_generation` 도구를 사용합니다.
+- `provider: "grok"`는 번들 `progrok`을 `127.0.0.1:18645`에서 띄우고, xAI Web Search와 `grok-4.3` planner를 거친 뒤 xAI Images API를 호출합니다.
 
-API 키가 env/config에 있으면 생성 엔드포인트에서 `provider: "api"`를 보내 Responses API `image_generation` 도구를 사용할 수 있습니다.
+Grok은 Classic, Node, Agent 흐름을 지원합니다. Classic 레퍼런스, Node 부모 이미지, Agent 현재 이미지가 있으면 최종 Grok 호출은 xAI image edit 경로로 전환되어 image-to-image 맥락을 유지합니다. 기본 모델은 `grok-imagine-image`이고, `quality: "high"`에서는 `grok-imagine-image-quality`를 사용합니다.
 
-설정 화면에 **API key provider available**이 보이면, API 키가 감지됐고 생성/편집/멀티모드/노드 요청에 사용할 수 있다는 뜻입니다.
+Grok video 생성(T2V/I2V)은 `1.1.15`에 포함되지 않았습니다. `docs/grok-video-i2v-plan.md`와 `docs/grok-video-i2v-research.md`는 구현 계획과 조사 문서이며, 공개 런타임은 아직 이미지 생성만 지원합니다.
+
+설정 화면에 **API key provider available**이나 **Grok provider available**이 보이면 해당 공급자가 감지됐고 생성 요청에 사용할 수 있다는 뜻입니다.
 
 ![OAuth 활성화와 API 키 비활성 상태를 보여주는 설정 화면](../assets/screenshots/settings-oauth-generation.png)
 
@@ -82,6 +90,10 @@ API 키가 env/config에 있으면 생성 엔드포인트에서 `provider: "api"
 4. 한 장을 만들거나, multimode를 켜서 같은 프롬프트에서 여러 후보 슬롯을 만듭니다.
 5. 생성 후 복사, 다운로드, 이어서 작업, Canvas Mode 정리를 선택합니다.
 
+Prompt Studio의 각 컨트롤, 멀티모드 작성법, 1:1 Direct, 추론 강도, 갤러리
+즐겨찾기 동작은 [Prompt Studio 사용 설명서](PROMPT_STUDIO.ko.md)에 정리되어
+있습니다.
+
 ![하나의 프롬프트에서 네 후보 슬롯이 생성 중이고 sidebar에 active job history가 보이는 multimode sequence 화면](../assets/screenshots/multimode-sequence.png)
 
 ### Node mode
@@ -172,9 +184,14 @@ environment variables > ~/.ima2/config.json > built-in defaults
 | `IMA2_GENERATED_DIR` | `~/.ima2/generated` | 생성 이미지 저장 위치 |
 | `IMA2_IMAGE_MODEL_DEFAULT` | `gpt-5.4-mini` | 서버 fallback 이미지 모델 |
 | `IMA2_NO_OAUTH_PROXY` | — | `1`이면 OAuth 프록시 자동 시작 비활성화 |
+| `IMA2_GROK_PROXY_HOST` | `127.0.0.1` | 번들 progrok 프록시 host |
+| `IMA2_GROK_PROXY_PORT` | `18645` | 번들 progrok 프록시 port |
+| `IMA2_NO_GROK_PROXY` | — | `1`이면 progrok 자동 시작 비활성화 |
+| `IMA2_GROK_PLANNER_MODEL` | `grok-4.3` | 최종 이미지 호출 전 Grok 검색/planner 모델 |
+| `IMA2_GROK_IMAGE_MODEL_DEFAULT` | `grok-imagine-image` | 기본 Grok 이미지 모델 |
 | `IMA2_LOG_LEVEL` | `warn` | 일반 `serve`는 `warn`, dev 모드는 `debug`. `debug`, `info`, `warn`, `error`, `silent` 지원 |
 | `IMA2_INFLIGHT_TERMINAL_TTL_MS` | `30000` | 디버그용 최근 작업 보존 시간 |
-| `OPENAI_API_KEY` | — | 보조 기능용 API 키. 이미지 생성용은 아님 |
+| `OPENAI_API_KEY` | — | `provider: "api"` Responses 이미지 경로와 보조 기능용 API 키 |
 
 ### 로그 모드
 
@@ -186,7 +203,10 @@ environment variables > ~/.ima2/config.json > built-in defaults
 
 엔드포인트 목록은 [API Reference](API.md)로 분리했습니다.
 
-자주 묻는 질문은 [FAQ](FAQ.ko.md)에 정리했습니다. 업데이트 후 예전 이미지가 안 보이면 [예전 이미지 복구 안내](RECOVER_OLD_IMAGES.md)를 먼저 확인하세요.
+자주 묻는 질문은 [FAQ](FAQ.ko.md)에 정리했습니다. Prompt Studio 기능은
+[Prompt Studio 사용 설명서](PROMPT_STUDIO.ko.md)를 확인하세요. 업데이트 후
+예전 이미지가 안 보이면 [예전 이미지 복구 안내](RECOVER_OLD_IMAGES.md)를
+먼저 확인하세요.
 
 ## 문제 해결