feat(study-builder): publish production authoring and practice runtime

AGENTS.md

@@ -3,6 +3,24 @@
 이 문서는 새 에이전트가 현재 작업을 안전하게 이어가기 위한 저장소 수준 안내서다.
 작업 시작 전 이 파일과 수정 대상 아래의 `prototype/AGENTS.md`를 모두 읽는다.
 
+## 0. 최우선 계약: 프로토타입이 아닌 프로덕션 제품
+
+Study Builder의 개발 목표는 화면 시연용 프로토타입이 아니라 실제 사용자 데이터,
+로컬 파일, 프로세스와 AI Provider를 안전하게 다루는 배포 가능한 Electron 제품이다.
+`prototype/`은 역사적인 디렉터리 이름일 뿐 품질 기준이 아니다.
+
+작업 시작 전 반드시 [`docs/production-development-contract.md`](docs/production-development-contract.md)를
+읽고 따른다. 특히 다음을 금지한다.
+
+- Renderer에 고정된 학습서, 진행률, 파일, 실행 결과 또는 AI 답변을 실제 데이터처럼 넣기
+- 파일·PTY·Provider를 호출하지 않고 `setTimeout`이나 로컬 상태로 성공을 연출하기
+- 브라우저 fallback이나 테스트 mock을 Electron 제품 기능의 완료 증거로 사용하기
+- 저장·실행 실패를 성공 Toast나 빈 결과로 숨기기
+
+기능 완료는 실제 Renderer → Preload → Main → 저장소·Workspace·프로세스·Provider
+왕복과 실패·취소·재시작 복원을 검증한 뒤에만 선언한다. 현재 공개 배포에 남은 서명,
+공증 등의 작업은 숨기거나 가짜로 대체하지 않는다.
+
 ## 1. 현재 제품 방향
 
 Study Builder는 로컬 우선 Electron 학습 애플리케이션이다.
@@ -15,6 +33,7 @@ Study Builder는 로컬 우선 Electron 학습 애플리케이션이다.
 
 상세 제품 결정과 반응형 규칙은 다음 문서가 기준이다.
 
+- `docs/production-development-contract.md`
 - `prototype/AGENTS.md`
 - `design.md`
 - `README.md`

INSTALLER_FIX.md

@@ -0,0 +1,6 @@
+# Practice Runtime installer hotfix
+
+이 수정본은 설치 스크립트가 존재하지 않는 `prototype/tests/unit/ipc-contract.test.ts`를 찾던 문제를 수정합니다.
+실제 파일인 `prototype/tests/unit/ipc-contracts.test.ts`를 사용합니다.
+
+저장소 루트에서 압축을 덮어쓴 뒤 기존 적용 스크립트를 다시 실행하세요.

PRACTICE_RUNTIME_UPDATE.md

@@ -0,0 +1,94 @@
+# Study Builder 실습 런타임 통합 수정본
+
+현재 적용된 위키 UI 통합, Java·Spring 파일 생성, 브라우저식 탭 이동, VS Code 스타일 Explorer를 유지하면서 실습 화면의 런타임 문제를 정리합니다.
+
+## 반영 내용
+
+### 바로 실습
+
+- Spring Boot 위키 페이지 상단에 연결된 실습의 `바로 실습하기` 버튼을 표시합니다.
+- 실습 가이드에는 현재 단계의 목표 파일을 바로 열거나 생성하는 버튼을 표시합니다.
+- 목표 Java 파일이 없으면 상위 package 폴더를 순서대로 만들고, 경로와 파일명을 분석해 package·class·Spring 골격까지 생성합니다.
+
+### 메시지 수명 주기
+
+- 파일 생성, 저장, 폴더 연결 등의 성공 알림은 자동으로 닫힙니다.
+- 오류 알림은 자동으로 사라지지 않으며 사용자가 닫을 수 있습니다.
+- `이전 실습 노트가 저장되어 있습니다` 고정 토스트를 제거하고 가이드 하단의 작은 상태 정보로 변경합니다.
+- Markdown 가져오기와 출처 복사 알림도 일정 시간 후 닫힙니다.
+
+### 상호작용 터미널
+
+- 하단 `터미널`을 클릭하면 현재 실습 폴더를 작업 디렉터리로 사용하는 실제 PTY 셸을 시작합니다.
+- macOS는 사용자의 기본 셸을 우선 사용하고, 사용할 수 없으면 zsh·bash·sh 순서로 확인합니다.
+- Windows는 `ComSpec`, Linux는 기본 셸 환경을 사용합니다.
+- 키 입력, Ctrl+C, 방향키, ANSI 출력, 창 크기 변경을 PTY로 전달합니다.
+- 테스트 실행과 상호작용 셸은 동시에 점유하지 않으며 서로 전환할 때 기존 세션을 정리합니다.
+- 터미널 세션은 현재 Electron 창과 현재 승인된 실습 폴더에만 연결됩니다.
+
+### 대화형 AI 학습 도우미
+
+- `테스트 실패`를 전제로 하던 패널을 일반 Java·Spring 학습 도우미로 변경합니다.
+- 현재 코드의 역할, 호출 흐름, 다음 구현 순서, 터미널 오류 등 자유로운 질문을 입력할 수 있습니다.
+- 답변 뒤 같은 패널에서 후속 질문을 계속할 수 있습니다.
+- 현재 파일 외에 관련성이 높은 텍스트 파일을 최대 8개까지 문맥 후보로 선택합니다.
+- 최근 대화 8개 메시지와 실행 중이거나 최근 종료된 터미널 출력도 선택적으로 포함합니다.
+- `.env`, credential·secret·token 파일, 개인 키·인증서, `.git`, `.gradle`, `build`, `node_modules` 등은 관련 파일 후보에서 제외합니다.
+- 매 질문마다 전송 파일, 대화 수, 터미널 포함 여부, 전체 전송량을 먼저 확인합니다.
+- 수정안은 기존 Diff Review를 거쳐 편집기 버퍼에만 적용되며, 디스크 저장은 별도로 승인해야 합니다.
+
+### 실습 폴더 복원
+
+- 이전에 승인한 실습 폴더 복원 기능을 그대로 유지합니다.
+- 앱 재실행, 홈 이동, 위키 전환, 실습 탭 재진입 후에도 최근 유효한 폴더를 다시 연결합니다.
+- 폴더가 이동되거나 삭제된 경우에만 폴더 선택 화면을 표시합니다.
+
+## 적용 전
+
+현재 정상 동작하는 상태를 커밋해 두는 것을 권장합니다.
+
+```bash
+git add .
+git commit -m "chore: checkpoint before practice runtime update"
+```
+
+## 적용
+
+ZIP을 저장소 루트에 덮어쓴 뒤 실행합니다.
+
+```bash
+cd /Users/wars/Github/study-builder
+unzip -o ~/Downloads/study-builder-practice-runtime-update-final.zip -d .
+chmod +x apply-study-builder-practice-runtime-update.sh
+./apply-study-builder-practice-runtime-update.sh
+```
+
+적용 스크립트는 여러 번 실행해도 같은 IPC 항목이나 상태 전이를 중복 추가하지 않습니다.
+
+## 검증
+
+```bash
+cd prototype
+npm run typecheck
+npm test
+npm run build:desktop
+```
+
+실제 앱을 실행합니다.
+
+```bash
+npm run dev:desktop
+```
+
+## 수동 확인 순서
+
+1. 위키 페이지에서 `바로 실습하기`를 눌러 현재 탭에서 실습 화면으로 이동합니다.
+2. 실습 목표 파일이 없으면 package 폴더와 Java 골격이 함께 생성되는지 확인합니다.
+3. 파일 생성 성공 메시지가 자동으로 사라지는지 확인합니다.
+4. 하단 `터미널`을 누르고 `pwd`, `ls`, `./gradlew tasks`를 직접 입력합니다.
+5. 터미널이 열린 상태에서 `테스트`를 누르면 셸을 정리한 뒤 승인 화면으로 전환되는지 확인합니다.
+6. AI 패널을 열고 테스트 실패와 무관한 질문을 입력합니다.
+7. 문맥 미리보기에서 현재 파일, 관련 파일, 대화 기록, 터미널 전송량을 확인합니다.
+8. 첫 답변 뒤 후속 질문을 입력해 대화가 이어지는지 확인합니다.
+9. 수정안이 있는 응답만 Diff Review를 표시하고, 적용 뒤에도 저장 전까지 디스크가 바뀌지 않는지 확인합니다.
+10. 앱을 완전히 종료하고 다시 실행해 이전 실습 폴더가 자동 복원되는지 확인합니다.

README.md

@@ -6,6 +6,14 @@ AI는 선택 기능입니다. AI를 사용하지 않아도 위키, 파일 편집
 
 현재 MVP의 원칙은 **로컬 우선**, **사용자 승인**, **기존 파일 비파괴**, **BYOP(Bring Your Own Provider)**입니다. 클라우드 계정, 동기화, 협업, 결제와 자동 업데이트는 포함하지 않습니다.
 
+## 개발 문서
+
+이 저장소의 `prototype/`은 역사적인 디렉터리 이름입니다. 개발 대상은 시연용
+프로토타입이 아니라 실제 파일·저장 데이터·프로세스·Provider를 사용하는 Electron
+제품입니다. 새 기능을 만들기 전에 [프로덕션 개발 계약](docs/production-development-contract.md)을
+읽고, 런타임 하드코딩 금지·실제 IPC 경계·실패 처리·재시작 복원·완료 증거 규칙을
+따르십시오.
+
 ## 현재 MVP 기능
 
 - 홈, 위키 문서, 실습 화면을 누적하는 커스텀 Electron 상단 탭 Bar
@@ -148,7 +156,7 @@ npm run dev
 
 ## 학습서 콘텐츠 만들기
 
-현재 상용 UI의 배포 학습서는 읽기 전용입니다. 앱 안에서 새 문서를 만들거나 Markdown을 가져오고 원문을 수정하지 않습니다. 콘텐츠 저자는 `prototype/resources/course-sources/` 아래 Markdown과 manifest를 수정한 뒤 `npm run build:course`로 Renderer 콘텐츠와 Electron seed를 함께 생성합니다.
+배포 학습서 원문은 읽기 전용으로 보호합니다. 사용자는 읽기 전용 원문을 덮어쓰지 않고 개인 학습서에서 새 문서 생성, UTF-8 Markdown 가져오기, 블록 편집과 저장을 수행할 수 있습니다. 콘텐츠 저자는 `prototype/resources/course-sources/` 아래 Markdown과 manifest를 수정한 뒤 `npm run build:course`로 Renderer 콘텐츠와 Electron seed를 함께 생성합니다.
 
 실습 계약은 `practice-manifest.json`, 시작 프로젝트는 `prototype/resources/template-sources/spring-boot-rest/`에서 관리합니다. 자세한 스키마와 생성물 경계는 [강의 자료 제작 방법](prototype/docs/course-authoring.md)을 참고하십시오.
 

TYPECHECK_FIX.md

@@ -0,0 +1,8 @@
+# Practice Runtime Typecheck Fix
+
+`ContextManifest.terminal`에 `included` 필드가 추가됐지만 기존 `assistant-proposal.test.ts` fixture가 갱신되지 않은 문제를 수정합니다.
+
+```bash
+chmod +x apply-practice-runtime-typecheck-fix.sh
+./apply-practice-runtime-typecheck-fix.sh
+```

apply-practice-runtime-typecheck-fix.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT"
+node scripts/apply-practice-runtime-typecheck-fix.mjs

apply-study-builder-practice-runtime-update.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ ! -f "prototype/package.json" ]]; then
+  echo "study-builder 저장소 루트에서 실행해 주세요." >&2
+  exit 1
+fi
+
+required_files=(
+  "prototype/src/practice/java-file-template.js"
+  "prototype/src/practice/java-editor-setup.js"
+  "prototype/src/practice/ProjectFileTree.jsx"
+  "prototype/src/hooks/useWorkspaceActions.js"
+  "prototype/src/wiki/CourseWorkspaceHeader.jsx"
+  "prototype/src/wiki/SyntaxHighlightedCode.jsx"
+  "prototype/electron/terminal/course-approved-commands.ts"
+)
+
+for required_file in "${required_files[@]}"; do
+  if [[ ! -f "$required_file" ]]; then
+    echo "필수 선행 파일이 없습니다: $required_file" >&2
+    echo "앞서 적용한 Java/Spring 편집기 및 VS Code Explorer 수정본이 반영된 저장소에서 실행해 주세요." >&2
+    exit 1
+  fi
+done
+
+node ./scripts/apply-study-builder-practice-runtime-update.mjs

docs/development-plan.md

@@ -1,8 +1,8 @@
 # Study Builder Electron MVP 개발 계획
 
-> 상태: **피드백 P0/P1 구현 및 회귀 QA 완료, unsigned macOS 릴리스 후보 검증 완료**
+> 상태: **피드백 P0/P1 구현·실습 검증 계약·회귀 QA 완료, unsigned macOS 릴리스 후보 검증 완료**
 >
-> 기준일: 2026-07-31 · 대상: macOS 우선의 로컬 Electron 제품
+> 기준일: 2026-08-06 · 대상: macOS 우선의 로컬 Electron 제품
 
 ### 2026-08-02 피드백 구현 결과
 
@@ -11,12 +11,13 @@
 | 위키 | 경제학과 Spring 학습서를 저장 데이터로 렌더링하고 배포 콘텐츠는 읽기 전용으로 통일했다. 경제학 선택 문장 질문은 설정된 Provider의 실제 스트리밍 응답을 사용한다. |
 | 학습 UI | 기본 가이드 집중 화면, `01`~`18` 축약 내비게이션과 hover/focus 설명, 단일 관련 파일 동선, Terminal 접기·닫기 구분을 반영했다. |
 | 파일 | 탐색기의 새 파일과 실습 대상 파일은 답안 템플릿 없이 빈 파일로 생성한다. |
-| 실습 계약 | 18개 단위에 산출물, 최소 2개 요구사항과 최소 2개 완료 기준을 정의하고 course build에서 검증한다. |
+| 개인 위키 | 배포 강의 원문은 읽기 전용으로 유지하고, 사용자 문서는 실제 revisioned IPC를 통해 Markdown 가져오기·블록 편집·저장·삭제·재시작 복원을 제공한다. |
+| 실습 계약 | 18개 단위에 산출물, 최소 2개 요구사항과 최소 2개 완료 기준을 정의하고 course build에서 검증한다. 16개 command 단계에는 실제 JUnit 검증 클래스가 시작 템플릿에 포함되며, 참조 완성 프로젝트에서 모두 통과한다. |
 | Provider | Main에서 모델 목록을 조회하고 Provider metadata에 추론 강도를 저장한다. API Key는 Renderer로 반환하지 않는다. |
-| 회귀 QA | TypeScript 통과, Vitest 46 files·240 tests, Sites 4 tests, Electron E2E 54 tests를 retry 0으로 통과했다. 1440·1280·1024 실제 Electron 캡처를 현재 기본 화면으로 갱신했다. |
+| 회귀 QA | TypeScript 통과, Vitest 46 files·240 tests, Sites 4 tests, Electron E2E 56 tests를 retry 0으로 통과했다. 1440·1280·1024 실제 Electron 캡처를 현재 기본 화면으로 갱신했다. |
 | 패키징 | macOS arm64 unsigned `.app`·DMG·ZIP 생성, ASAR 6,521 entries와 native `node-pty`·Spring 템플릿 감사, 패키지 실행·재시작 Smoke Test 1개를 통과했다. |
 
-릴리스 전 남은 핵심 작업은 manifest가 참조하는 단계별 Spring 검증 클래스 제공이다. 현재 시작 템플릿에는 `StudymateApplicationTests`만 있으므로 후반 실습 명령은 해당 테스트 소스가 추가되기 전에는 성공할 수 없다. classpath 기반 Eclipse JDT Language Server 통합도 아직 없으며 현재는 Monaco의 정적 Java 지원과 템플릿의 VS Code 확장 권장으로 제한한다.
+manifest가 참조하는 16개 단계별 Spring 검증 클래스는 시작 템플릿에 포함되어 있다. 시작 템플릿에서 아직 구현하지 않은 단계가 실패하는 것은 의도된 학습 계약이며, 학습자가 코드를 작성한 뒤 해당 검증 명령으로 완료를 확인한다. 2단계 관찰 실습은 명령 성공과 비어 있지 않은 실습 노트 저장을 함께 요구한다. classpath 기반 Eclipse JDT Language Server 통합은 아직 없으며 현재는 Monaco의 정적 Java 지원과 템플릿의 VS Code 확장 권장으로 제한한다.
 
 ### 2026-07-31 실행 결과