careermate 0.1.0 → 0.1.1

package/docs/MCP_TOOLS.md

@@ -2,7 +2,7 @@
 
 CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자는 자신의 ChatGPT/Claude/Gemini와 대화하고, 그 AI가 여기 정의된 MCP 도구를 호출해 로컬 커리어 DB(`~/.careermate/careermate.sqlite`)를 읽고 씁니다. **CareerMate 내부에는 LLM이 없습니다.** 적합도 분석·자기소개서 작성 같은 추론은 모두 사용자의 AI가 수행하고, CareerMate는 데이터를 저장하고 다시 돌려주는 역할만 합니다.
 
-이 문서는 `packages/mcp-tools/src/tools.ts`에 정의된 **24개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
+이 문서는 `packages/mcp-tools/src/tools.ts`에 정의된 **30개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
 
 > 설계 원칙: 이 도구들은 단순 CRUD 래퍼가 아닙니다. 각 도구는 AI가 사용자를 대신해 수행하는 실제 작업에 대응하며, 설명에 *언제* 그리고 *어떻게* 호출해야 하는지가 담겨 있습니다. 가장 중요한 도구는 [`get_application_context`](#get_application_context-) 입니다.
 
@@ -16,7 +16,7 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 | 읽기전용(✅) 도구 | 쓰기/부수효과(✏️) 도구 |
 | --- | --- |
-| `get_onboarding_status`, `start_onboarding`, `get_profile`, `get_resumes`, `get_cover_letters`, `get_job_posting`, `list_jobs`, `parse_job_posting`, `get_application_context`, `list_recent_activity`, `get_workflow_guide`, `get_writing_style_guide` | `save_profile`, `update_profile`, `add_resume`, `add_cover_letter`, `save_cover_letter_version`, `save_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `export_cover_letter`, `open_dashboard`, `open_application` |
+| `get_onboarding_status`, `start_onboarding`, `get_profile`, `get_resumes`, `get_experiences`, `get_projects`, `get_skills`, `get_cover_letters`, `get_job_posting`, `list_jobs`, `parse_job_posting`, `get_application_context`, `list_recent_activity`, `get_workflow_guide`, `get_writing_style_guide` | `save_profile`, `update_profile`, `add_resume`, `add_experience`, `add_project`, `add_skill`, `add_cover_letter`, `save_cover_letter_version`, `save_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `export_cover_letter`, `open_dashboard`, `open_application` |
 
 ---
 
@@ -64,6 +64,25 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 ---
 
+## 3-1. 경력·프로젝트·기술스택 (Experiences / Projects / Skills)
+
+이력서 본문(`add_resume`)과 별개로, **구조화된** 경력·프로젝트·기술을 각각의 테이블에 항목 단위로 저장합니다. `get_application_context`의 `experiences`/`projects`/`skills`로 노출되며, `get_onboarding_status`의 `has_experience`/`has_skills`와 프로필 완성도(0~100) 계산에 직접 반영됩니다. (대시보드의 Profile 페이지에서도 같은 데이터를 편집합니다.)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `add_experience` | 경력(직장 단위) 항목 저장 | `company`(필수), `role?`, `employment_type?`, `start_date?`, `end_date?`, `is_current?`, `description?`, `achievements?`, `tech?`, `order_index?` | 저장된 `ExperienceRecord` | 이력서에서 경력을 구조화해 보관할 때 | ✏️ |
+| `get_experiences` | 저장된 경력을 시간 역순으로 조회 | 없음 | `ExperienceRecord[]` | 경력 목록만 빠르게 확인할 때 | ✅ |
+| `add_project` | 대표 프로젝트 항목 저장 | `name`(필수), `role?`, `description?`, `highlights?`, `tech?`, `url?`, `start_date?`, `end_date?`, `order_index?` | 저장된 `ProjectRecord` | 프로젝트 이력을 구조화해 보관할 때 | ✏️ |
+| `get_projects` | 저장된 프로젝트 조회 | 없음 | `ProjectRecord[]` | 프로젝트 목록만 확인할 때 | ✅ |
+| `add_skill` | 기술스택 항목 저장(개당 1건) | `name`(필수), `category?`, `level?`, `years?`, `order_index?` | 저장된 `SkillRecord` | 보유 기술을 정리해 둘 때 | ✏️ |
+| `get_skills` | 저장된 기술스택 조회 | 없음 | `SkillRecord[]` | 기술 목록만 확인할 때 | ✅ |
+
+- `achievements`/`highlights`에는 정량 지표가 담긴 성과를, `tech`에는 사용 기술을 배열로 넣으면 적합도 분석·자소서·면접 준비에서 근거로 활용됩니다.
+- 기술은 항목당 1건이므로 여러 개면 `add_skill`을 반복 호출하세요.
+- 입력 스키마: `ExperienceInputSchema` / `ProjectInputSchema` / `SkillInputSchema`(`packages/shared/src/schemas.ts`).
+
+---
+
 ## 4. 자기소개서 (Cover Letters)
 
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |

package/docs/ROADMAP.md

@@ -2,15 +2,15 @@
 
 CareerMate는 MCP-우선 로컬 커리어 관리 도구다. 사용자는 자신의 ChatGPT/Claude/Gemini와 대화하고, 그 AI가 CareerMate의 로컬 MCP 도구를 호출해 로컬 커리어 DB를 읽고 쓴다. CareerMate 내부에는 LLM이 없으며(분석·작성은 사용자의 AI가 수행), 모든 데이터는 로컬에만 저장된다.
 
-이 문서는 현재 버전(`0.1.0`)의 MVP 완료 범위와, 지금은 제외하되 구조는 열어둔 향후 과제를 정리한다.
+이 문서는 현재 버전(`0.1.1`)의 MVP 완료 범위와, 지금은 제외하되 구조는 열어둔 향후 과제를 정리한다.
 
-관련 문서: [README](../README.md), [설치 안내](./INSTALL.md), [워크플로우](./WORKFLOWS.md), [시작하기 워크플로우](./START_WORKFLOW.md)
+관련 문서: [README](../README.md), [설치 런북](../INSTALL.md), [지원 앱·설치 레퍼런스](./SUPPORTED_AI_APPS.md), [워크플로우](./WORKFLOWS.md), [시작하기 워크플로우](./START_WORKFLOW.md)
 
 ---
 
 ## 현재 버전
 
-- 버전: `0.1.0` (`package.json`)
+- 버전: `0.1.1` (`package.json`)
 - 런타임 요구: Node `>=22.5.0` (`node:sqlite` 내장 사용, 네이티브 컴파일 없음)
 - 실행 방식: 무빌드(tsx) — `node --no-warnings --import tsx ...`
 

package/docs/RUNTIME_DISTRIBUTION_RESEARCH.md

@@ -0,0 +1,135 @@
+# 런타임·배포 조사: 완전 원클릭(Codex .exe / Claude `.mcpb`) 실현 가능성
+
+- **작성일**: 2026-06-15
+- **상태**: 조사 완료 / 큰 작업은 **보류(문서만)**
+- **관련**: [ADR #1 `node:sqlite` 채택](./DECISIONS.md), [ADR #6 대시보드·MCP의 SQLite(WAL) 공유 + `server.json` 핸드셰이크](./DECISIONS.md), [ROADMAP](./ROADMAP.md)
+
+> 이 문서는 "사용자가 Node/npx/git을 미리 깔지 않고도 한 번에 설치되는 경험"을 두 경로
+> (① OpenAI **Codex Windows 앱** + 단일 `.exe`, ② Claude Desktop **`.mcpb`**)에서 만들 수
+> 있는지 조사한 기록이다. 결론과 근거, 그리고 다음에 누가 이어받든 헛수고하지 않도록
+> "무엇이 작은 수정이고 무엇이 큰 작업인지"를 남긴다.
+
+---
+
+## TL;DR
+
+- **공통 근본 제약**: CareerMate는 **`node:sqlite`(Node ≥22.5의 최신 내장 기능)**에 의존한다.
+  "무설치 번들 런타임" 전략의 성패는 전부 **"충분히 새로운 Node를 어떻게 확보하느냐"**로 수렴한다.
+- **Codex Windows 앱 + 단일 `.exe`**: 패키징(Node SEA)은 **기술적으로 성립**하나, **자가등록 지속성**과
+  **샌드박스** 두 개의 (2026-05~06 기준) 외부 버그/제약 때문에 **진정한 무인 원클릭은 현재 불가**. → **보류.**
+- **Claude `.mcpb`**: 산출물(`dist/mcp.mjs`)은 **Node ≥22.5에서 정상 동작**함을 실증함. 사용자가 겪은
+  "설치는 됐는데 도구가 안 뜸/빨간 에러"는 **Claude Desktop 내장 Node가 22.5 미만**일 때의 증상으로 추정되며,
+  그 경우의 해결은 **저장 계층 rewrite(= 큰 작업)**다. → **로그로 근본 원인 확정 후 결정.**
+
+---
+
+## 1. 배경 / 질문
+
+- CareerMate는 로컬 MCP stdio 서버 + 로컬 웹 대시보드. 저장은 `node:sqlite`.
+- 목표: 비개발자가 **아무것도 미리 설치하지 않고** 한 번에 쓰기 시작하는 경험.
+- 두 경로를 검토:
+  1. **Codex Windows 데스크톱 앱**(2026-03 출시, MS Store, 로컬 샌드박스+PowerShell)에 **Node 런타임을
+     동봉한 단일 `.exe`**(Node SEA)를 더블클릭 → 자가등록 → 동작.
+  2. **Claude Desktop `.mcpb`**(런타임 동봉형 원클릭) — 이미 빌드 파이프라인 존재(`scripts/build-mcpb.mjs`).
+
+---
+
+## 2. Codex Windows 앱 + 단일 `.exe` (Node SEA)
+
+### 2.1 패키징 자체 — 성립 (조건부 가능)
+
+| 항목 | 판정 | 근거 |
+|---|---|---|
+| Windows에서 SEA `.exe` 생성 | 가능 | Node SEA의 **첫 번째 CI 테스트 플랫폼이 Windows**. `.exe` 출력 지원. 안정성 지수는 1.1(Active development). |
+| 빌드 워크플로 | 간소화됨 | Node **25.5.0**의 `--build-sea` 단일 플래그로 통합(종전 postject 3단계 불필요). |
+| 정적 자산(대시보드 HTML/CSS/JS) 임베드 | 가능 | `sea.getAsset()`/`getRawAsset()` 계열로 번들·런타임 서빙(v20.12.0~). 단 현재 `apps/web`는 디스크에서 자산을 읽으므로 **임베드용 코드 수정 필요**. |
+| `node:sqlite` 플래그 | 사실상 비이슈 | **Node ≥22.13 / ≥23.4부터 `--experimental-sqlite` 없이 동작**. 최신 Node를 임베드하면 해결. 필요시 SEA `execArgv`로 플래그 주입도 가능. |
+
+근거 출처(주요): nodejs.org `single-executable-applications`, `sqlite` 문서; Node v25.5.0 릴리스 블로그;
+Joyee Cheung 블로그(Windows PE 주입 실테스트); commit `55239a48b6`("unflag sqlite module").
+
+### 2.2 자가등록·동작을 막는 두 개의 블로커 — 현재 불가
+
+1. **🚨 Codex 데스크톱이 시작 시 `~/.codex/config.toml`을 재작성하며 사용자 커스텀 `[mcp_servers]` 블록을 삭제**
+   - openai/codex **issue #24718** (2026-05-27 OPEN, v26.519.11010.0, Win11 26200): "Codex Desktop overwrites
+     `%USERPROFILE%\.codex\config.toml` during startup ... removes a manually configured custom MCP server",
+     "blocking data-loss issue." (보강: #26530, #24387, JetBrains LLM-24906)
+   - 의미: `.exe`가 `init`으로 스스로 등록해도 **앱이 지워버릴 수 있음** → 자가등록 전략의 핵심 전제가 깨짐.
+2. **샌드박스가 MCP stdio 서브프로세스에도 상속됨**
+   - 공식 문서: "The sandbox applies to spawned commands ... inherit the same sandbox boundaries", "Every file
+     write, terminal command, network request, and process spawn goes through the sandbox."
+   - 기본 `workspace-write`의 쓰기 가능 루트는 `cwd + $TMPDIR + /tmp`뿐 → **워크스페이스 바깥인
+     `~/.careermate` 쓰기와 127.0.0.1 포트 바인딩이 기본 거부**. `danger-full-access` 또는
+     `sandbox_workspace_write.writable_roots` 명시 필요. (실증: issue #18243, #24727 "windows sandbox failed: spawn setup")
+
+> 두 블로커 모두 **CareerMate 코드 문제가 아니라 Codex 앱 측 미해결 버그/설계 제약**이라 우리가 코드로 못 고친다.
+> #24718이 패치되고 샌드박스 정책이 정리되면 결론이 뒤집힐 수 있으므로 **추적 대상**.
+
+### 2.3 결론(Codex)
+
+- 패키징은 가능, **무인 원클릭은 현재 불가** → **보류.** 당분간 Codex는 CLI/IDE 확장 경로 또는
+  "Node 1회 설치 → `npx -y careermate init`" 안내가 현실적.
+
+---
+
+## 3. Claude Desktop `.mcpb`
+
+### 3.1 실증 결과 (이 저장소, 2026-06-15, Node v25)
+
+- `manifest.json`은 정상: `server.type:"node"`, `args:["--experimental-sqlite","${__dirname}/dist/mcp.mjs"]`.
+- **`dist/mcp.mjs` 단독 부팅 성공** — `initialize` 응답 정상, **도구 24개** 로드, 데이터 `~/.careermate` 연결.
+- 이 PC의 **Node v25**에서: `--experimental-sqlite`는 **거부되지 않고 경고만**, 플래그 없이도 `node:sqlite` 동작.
+  → "최신 Node가 플래그를 거부해 죽는다" 시나리오는 (최소 v25까지) **없음**.
+
+### 3.2 그렇다면 사용자가 본 "도구 안 뜸/빨간 에러"의 원인
+
+- 산출물·플래그가 Node ≥22.5에서 멀쩡하므로, **sqlite 경로의 유일한 실패 원인 = Claude Desktop 내장 Node < 22.5**.
+  그 경우 `node:sqlite` 모듈이 **아예 없고** `--experimental-sqlite`도 **모르는 옵션**이라 서버가 즉시 죽는다.
+- (대안 가설) sqlite 무관 환경 문제 — 단 Claude Desktop 미설치 환경에서는 재현 불가.
+- **확정 방법(저비용, 먼저 할 것)**: `.mcpb`를 깐 PC에서 로그 확인
+  - Windows: `%APPDATA%\Claude\logs\mcp-server-careermate.log` (또는 `mcp.log`)
+  - `bad option: --experimental-sqlite` / `No such built-in module: node:sqlite` → **내장 Node < 22.5 확정**
+  - 그 외(경로/ESM/`__dirname`) → 패키징 문제(별개 갈래)
+
+### 3.3 내장 Node < 22.5가 확정될 경우 — 저장 계층 대안
+
+코드 결합도는 낮다. `node:sqlite`를 만지는 곳은 **3개 파일**뿐:
+`packages/db/src/{connection.ts, schema.ts, repositories.ts}`. 사용 API도 작은 부분집합
+(`DatabaseSync`, `exec`, `prepare().get()/.all()/.run()`, `?`/`@name` 인자, `.changes`, `close`), **JOIN 없음**.
+→ `getDb()` 뒤 어댑터 교체 자체는 소규모.
+
+**그러나 두 개의 지뢰:**
+
+1. **2-프로세스 동시성(ADR #6)** — 웹 대시보드와 MCP 서버가 **별도 프로세스로 같은 DB를 WAL 동시 접근**.
+   - `sql.js`(WASM): 낡은 Node까지 호환되지만 **인메모리+수동 저장**이라 두 프로세스 공유 시 last-writer-wins로 **깨짐**.
+   - JSON 스토어(lowdb 등): 동일하게 동시성 재설계 필요.
+2. **네이티브 ABI** — `better-sqlite3`는 API가 거의 동일하지만 **네이티브 모듈**이라 내장 Node ABI와
+   prebuilt 불일치(NODE_MODULE_VERSION) 위험. 버전 문제를 다른 형태로 되살림.
+
+| 대안 | 낡은 내장 Node 호환 | 2-프로세스 동시성 | 비용 |
+|---|---|---|---|
+| sql.js (WASM) | ✅ | ❌ 재설계 필요 | 中~大 |
+| better-sqlite3 | ❌ ABI 위험 | ✅ | 中(근본 미해결) |
+| JSON 스토어 | ✅ | ❌ 재설계 필요 | 中~大 |
+
+가장 깔끔한 방향: **MCP 서버가 DB를 직접 열지 않고 웹 서버의 127.0.0.1 HTTP로 데이터를 요청 → 웹 서버가
+단일 DB 소유자**. 이러면 sql.js가 성립하지만 "대시보드가 안 떠 있어도 MCP 동작" UX를 잃는다(진짜 아키텍처 변경).
+
+→ 어느 쪽이든 **"작은 수정"이 아니라 아키텍처 변경**이므로, 근본 원인(로그) 확정 전에는 착수하지 않는다.
+
+---
+
+## 4. 권고 / 다음 단계
+
+1. **(먼저, 저비용)** `.mcpb` 깐 PC에서 로그 한 줄 확인 → 내장 Node < 22.5 여부 확정.
+   - 플래그류 에러면: (가설과 달리) 단순 수정 가능성 → 재검토.
+   - `node:sqlite` 부재면: 아래 3.3 rewrite를 정식 과제로.
+2. **단기 우회**(무설치 포기 허용 시): "Node ≥22.5 1회 설치 → `npx -y careermate init`" — Claude/Codex 공통으로 가장 견고.
+3. **추적**: Codex issue #24718(config 재작성) 상태. 닫히면 Codex SEA 원클릭을 재평가.
+
+## 5. 검증 메모 / 한계
+
+- Codex 데스크톱 관련 결론은 **2026-05~06 기준 OPEN 버그**에 의존(시간 민감).
+- #24718의 구체 재현은 HTTP MCP였다는 점에서 stdio 삭제는 광범위 재작성 정황으로의 소폭 일반화.
+- 미서명 `.exe`의 SmartScreen/Defender 경고가 원클릭 UX를 얼마나 저해하는지는 **이번 라운드에서 확정 근거 미확보**(미검증).
+- `.mcpb` 실패의 "내장 Node < 22.5" 결론은 **로그로 직접 확정 전까지 강한 추정**이다.

package/docs/START_WORKFLOW.md

@@ -4,6 +4,8 @@
 
 > 핵심 원칙: **분석과 글쓰기는 당신(AI)이 수행하고, CareerMate는 데이터를 제공·보관**합니다. 공고 분석이나 자기소개서 작성 전에는 항상 `get_application_context`를 먼저 호출해 근거 데이터를 가져오세요.
 
+> **대시보드 안내 정책**: 브라우저를 직접 여는 건 **첫 온보딩에서 한 번만**(`open_dashboard`)입니다. 이후 무언가를 저장·완료할 때는 **자동으로 새로 열지 말고** 주소(`http://127.0.0.1:4319`)만 안내하고, 사용자가 "열어줘"라고 할 때만 `open_application`(단건)·`open_dashboard`(전체)로 엽니다.
+
 ---
 
 ## A. 온보딩 (첫 연결 시 한 번)
@@ -25,6 +27,10 @@
 
 ### 3. 이력서 등록 — `add_resume`
 
+- **사용자가 이력서를 주는 방법은 앱마다 다릅니다.** 상황에 맞게 안내하세요:
+  - 가장 쉬운 공통 방법은 **내용을 대화창에 그대로 붙여넣기**(파일 위치 무관).
+  - Claude 채팅 앱(.mcpb)이면 **파일 직접 첨부**, 폴더 기반(Claude Code 탭/Codex/Antigravity)이면 작업 폴더에 두고 **파일명·경로로 지시**.
+  - 스캔본(이미지) PDF·보안 걸린 파일은 못 읽을 수 있으니, 그때는 **텍스트로 붙여넣어** 달라고 요청합니다.
 - 업로드한 이력서/경력기술서/포트폴리오 본문을 `add_resume`로 저장합니다.
 - `kind`(resume / career_description / portfolio / other)와 `title`을 적절히 지정하고, 대표 문서는 `is_primary=true`로 설정합니다. 대표 문서는 이후 `get_application_context`의 `primary_resume`로 노출됩니다.
 - `source`는 `upload`를 사용합니다.

package/docs/SUPPORTED_AI_APPS.md

@@ -1,60 +1,112 @@
-# 지원 AI 앱 (Supported AI Apps)
+# 지원 AI 앱 & 설치 레퍼런스 (Supported AI Apps)
 
-CareerMate는 LLM이 없는 **로컬 MCP 도구**입니다. 그래서 *내 컴퓨터에서 로컬 프로그램을 직접 실행할 수 있는* AI 앱에서만 동작합니다. 1차 지원(first-class) 앱은 다음 셋입니다.
+CareerMate는 LLM이 없는 **로컬 MCP 도구**입니다. *내 컴퓨터에서 로컬 프로그램을 직접 실행할 수 있는* AI 앱에서만 동작합니다.
 
-| 앱 | 영구 지침 | MCP 등록 위치 |
-| --- | --- | --- |
-| **Claude Desktop** | — | `.mcpb` 번들 (원클릭) |
-| **Claude Code** | 루트 `CLAUDE.md` | 프로젝트 `.mcp.json` |
-| **Codex** (OpenAI Codex CLI) | 루트 `AGENTS.md` | `~/.codex/config.toml` |
+> **가장 쉬운 사람용 설치 안내는 https://careermate.life (랜딩)** 입니다. 이 문서는 **지원 앱 매트릭스 + 클라이언트별 수동 MCP 설정 + 알려진 제약**을 모은 레퍼런스입니다. AI 에이전트가 따라가는 단계별 런북은 루트 [`/INSTALL.md`](../INSTALL.md), 설치 후 사용 흐름은 [docs/START_WORKFLOW.md](./START_WORKFLOW.md)를 보세요.
 
 ---
 
-## Claude Desktop
+## 설치는 크게 3가지 — "누가 설치하느냐"
 
-Claude Desktop이 Node를 내장 제공하므로 미리 깔 것이 없습니다.
+| | 무엇 | Node | 대상 |
+|---|---|---|---|
+| **1. 에이전트가 대신 설치** | 작업 폴더에서 **한 문장** → AI가 `careermate.life/llms-install.txt`를 읽고 npm 설치 + MCP 등록 | 필요(에이전트가 winget/brew 또는 nodejs.org로 도와줌) | Claude Code(데스크톱 **"Code" 탭** / CLI)·Codex CLI·Gemini CLI·Cursor 등 *명령 실행 가능한 에이전트* |
+| **2. npm 명령 직접** | 터미널에 `npx -y careermate init` 한 줄(감지된 앱 자동 등록) | 필요 | Claude Desktop·Codex·Cursor 등(그 외는 `--print`로 수동) |
+| **3. `.mcpb`** | 파일 하나를 설정에서 추가 | **불필요**(Claude Desktop 내장) | **Claude Desktop "채팅" 앱 전용** |
 
-1. **Claude Desktop 설치**
-2. **`careermate.mcpb` 받기** — Release `v0.1.0`에 첨부돼 있으나 저장소가 **비공개**라 접근 권한이 있어야 받을 수 있습니다. 그 외에는 소스에서 `npm run build:mcpb`로 직접 빌드하세요.
-3. **더블클릭** (또는 Settings → Extensions 로 끌어다 놓기)
-4. **Claude Desktop 재시작**
+**1·2는 같은 메커니즘**(Node + npm/npx + MCP 등록) — 에이전트가 치느냐 / 내가 치느냐의 차이일 뿐입니다. 그래서 1·2의 "대상" 제품군이 서로 **겹칩니다**(같은 Claude Code·Codex·Cursor 등). 어느 앱이 어느 방식을 쓰는지는 아래 **앱 × 방식** 매트릭스로 보세요. **3(`.mcpb`)만 Claude Desktop "채팅" 앱 전용**이라 성격이 다릅니다(내장 Node 사용, 단 버전<22.5면 불안정).
 
----
-
-## Claude Code
+### 앱 × 방식
 
-CareerMate 폴더 안에서 실행하는 것이 핵심입니다.
+| 앱 | 1 에이전트 | 2 npm직접 | 3 .mcpb | 영구 지침 | MCP 등록 위치 |
+|---|---|---|---|---|---|
+| **Claude Desktop "채팅"** | — | ✅(config 등록) | ✅ | — | `.mcpb` 또는 `claude_desktop_config.json` |
+| **Claude Code (Code 탭 / CLI)** | ✅ | ✅ | — | 루트 `CLAUDE.md` | 프로젝트 `.mcp.json` |
+| **Codex CLI** (⚠️ 데스크톱 앱 ✗) | ✅ | ✅ | — | 루트 `AGENTS.md` | `~/.codex/config.toml` |
+| **Gemini CLI / Antigravity** | ✅ | ✅ | — | — | Gemini CLI `~/.gemini/settings.json` · Antigravity `~/.gemini/.../mcp_config.json` |
+| **Cursor · Cline · Windsurf** | ✅ | ✅ | — | — | `~/.cursor/mcp.json` 등 |
 
-1. **Claude Code 실행** (CareerMate 폴더에서)
-2. 프롬프트 입력:
-   > "CareerMate를 설치하고 설정해줘. INSTALL.md를 따라 진행해줘."
+> **Gemini CLI → Antigravity 전환(2026-06):** Google이 소비자(무료/Pro/Ultra)용 Gemini CLI를 **2026-06-18부터 Antigravity CLI로 전환**합니다(Gemini CLI repo는 오픈소스로 유지·엔터프라이즈 계속). MCP 스키마는 동일(`mcpServers` + `command`/`args`/`env`)합니다. `careermate init`은 **Gemini CLI(`~/.gemini/settings.json`)를 자동 등록**하고, **Antigravity는 설정 파일 경로가 유동적이라 후보 파일이 이미 있을 때만** 등록합니다(없으면 위 mcpServers 블록을 해당 파일에 수동 추가).
 
-프로젝트 스코프 `.mcp.json`을 CareerMate 폴더에 등록하고, 첫 실행 때 **1회 승인**을 묻습니다. 승인하면 끝입니다.
+### 동작하지 않는 것
+**ChatGPT · Gemini · Claude의 웹·모바일 앱은 안 됩니다.** 클라우드에서 실행되어 **원격 URL 기반 MCP만** 지원하므로, 내 컴퓨터의 로컬 stdio 서버에 직접 닿을 수 없습니다.
 
 ---
 
-## Codex
+## 구독·준비물 (2026)
 
-OpenAI Codex CLI(로컬 코딩 에이전트)에서 동작합니다.
+- **Claude Code**(Code 탭/CLI): **Pro 이상**(무료 플랜 불가) 또는 `ANTHROPIC_API_KEY` 종량제.
+- **Codex**: **ChatGPT Plus 이상** 로그인으로 충분(API 키 불필요).
+- **`.mcpb`**(Claude Desktop 채팅 확장): **무료 플랜에서도 설치** 가능(안정성이 변수).
+- **터미널/npx**: 무료(Node만). 연결할 앱의 구독 정책은 별개.
 
-1. **Codex 실행** (CareerMate 폴더에서)
-2. 프롬프트 입력:
-   > "CareerMate를 설치하고 설정해줘. INSTALL.md를 따라 진행해줘."
+> **런타임.** CareerMate 서버는 Node 프로그램이라 **Node.js 22.5+ 가 필요**합니다 — 위 1·2 경로 공통(없으면 에이전트가 winget/brew, 안 되면 [nodejs.org](https://nodejs.org) LTS 설치 파일). **Node가 아예 필요 없는 길은 `.mcpb` 하나뿐**인데 그건 내장 Node 버전에 의존해 불안정할 수 있습니다 — **"완전 무설치 + 안정"을 동시에 주는 길은 아직 없습니다.**
+>
+> **Windows + Claude Code(Code 탭)**: [Git for Windows](https://git-scm.com/download/win) 사전 설치가 필요합니다(앱이 없으면 "Git is required" 안내). Claude Code가 **세션 격리(git worktree)와 내부 POSIX 셸 도구**에 Git을 쓰기 때문이며 CareerMate와는 무관합니다. macOS는 Git 기본 포함이라 불필요.
+
+---
 
-`~/.codex/config.toml`의 `[mcp_servers.careermate]` 항목을 등록합니다. Codex 안에서 `/mcp` 명령으로 연결을 확인하세요.
+## 작업 폴더 안에 설치 (권장 — GUI 앱·샌드박스 친화)
+
+Claude "Code" 탭이나 Codex처럼 **작업 폴더(cwd)를 잡고** 쓰는 경우, 설치물과 데이터를 그 폴더 **안에** 두면 (1) 폴더만 백업·이동하면 데이터가 따라오고 (2) 샌드박스가 cwd 하위 쓰기를 허용해 마찰이 줄어듭니다. `<WS>`를 작업 폴더 절대경로라 할 때:
+
+```bash
+npm install --prefix "<WS>/.cm/app" careermate
+```
+데이터는 `CAREERMATE_DATA_DIR` 환경변수로 작업 폴더 안에 고정합니다(기본값 `~/.careermate` 대신). 아래 MCP 등록의 `env`에 넣으면 됩니다:
+```
+CAREERMATE_DATA_DIR = <WS>/.cm/data
+```
+- `<BIN>` = `<WS>/.cm/app/node_modules/careermate/bin/careermate.mjs` (이 셸이 `--experimental-sqlite`를 알아서 붙임).
+- 데이터 폴더 이름을 `.git`·`.codex`·`.agents`로 두지 마세요(앱이 읽기 전용으로 보호).
+- **포터블 Node(고급):** 시스템에 Node 22.5+가 없으면, 작업 폴더 안에 포터블 Node를 두고 `command`를 그 `node` 절대경로로 가리켜도 동작합니다. 단 다운로드 용량·OS 보안 경고·폴더 이동 시 경로 갱신 부담이 있어, 지금은 "시스템 Node 1회 설치"가 더 단순합니다.
 
 ---
 
-## 그 외 — 기타 MCP 클라이언트
+## 클라이언트별 수동 MCP 설정 (방식 2의 수동판)
+
+대부분 `npx -y careermate init`(또는 소스에서 `npm run init`)이 자동 등록하므로 **수동 설정은 보통 불필요**합니다. 직접 붙여넣어야 할 때만 참고하세요. `npm run init -- --print`로 아래 스니펫을 출력할 수도 있습니다.
 
-Cursor · Cline · Windsurf 등 로컬 stdio MCP를 지원하는 클라이언트도 동작합니다. CareerMate 폴더에서 `npm run init`(또는 설정만 출력하는 `npm run init -- --print`)으로 등록하세요.
+**경로 규칙** — 아래 `<BIN>`은 **실제 절대경로**로 바꾸세요(`~`·`$HOME`은 설정 파일 안에서 확장 안 됨).
+- **Windows**: JSON에서 역슬래시는 `\\`로 두 번(`C:\\...\\careermate.mjs`). TOML은 **작은따옴표 리터럴**(`'C:\...\careermate.mjs'`)을 쓰면 한 번만.
+- **macOS/Linux**: `/` 그대로.
 
-## 동작하지 않는 것
+### Claude Desktop (채팅앱 수동)
+설정 파일: Windows `%APPDATA%\Claude\claude_desktop_config.json` · macOS `~/Library/Application Support/Claude/claude_desktop_config.json` (Settings → Developer → Edit Config로도 열림)
+```json
+{ "mcpServers": { "careermate": { "command": "node", "args": ["<BIN>", "mcp"] } } }
+```
 
-**ChatGPT / Gemini 웹·모바일은 동작하지 않습니다.** 이들은 클라우드에서 실행되므로 내 컴퓨터의 **로컬 stdio MCP 서버에 닿을 수 없습니다.** 로컬에서 도는 Codex(CLI) · Claude Code · Claude Desktop만 CareerMate를 쓸 수 있습니다.
+### Claude Code (프로젝트 `.mcp.json`, 작업 폴더 최상단)
+```json
+{ "mcpServers": { "careermate": { "type": "stdio", "command": "node", "args": ["<BIN>", "mcp"], "env": { "CAREERMATE_DATA_DIR": "<WS>/.cm/data" } } } }
+```
+또는 CLI: `claude mcp add --scope project --transport stdio careermate -- node <BIN> mcp` · 첫 실행 시 **1회 승인**.
+
+### Codex CLI (`~/.codex/config.toml`)
+```toml
+[mcp_servers.careermate]
+command = "node"
+args = ["<BIN>", "mcp"]
+# 작업 폴더 안에 데이터: env = { CAREERMATE_DATA_DIR = "<WS>/.cm/data" }
+```
+또는 CLI: `codex mcp add careermate -- node <BIN> mcp` · 등록 후 `/mcp`로 확인.
+
+### Cursor / Cline / Windsurf
+`~/.cursor/mcp.json`(전역) 또는 `.cursor/mcp.json`(프로젝트) 등에 위 Claude Code와 같은 `mcpServers` 블록. 추가 후 클라이언트 재시작.
+
+> **소스를 클론한 개발자**는 `<BIN>` 대신 TS 소스를 직접 가리킬 수 있습니다(빌드 불필요):
+> `node --no-warnings --experimental-sqlite --import tsx <careermate>/apps/mcp/src/index.ts mcp`
 
 ---
 
-설치 절차 전체는 [/INSTALL.md](../INSTALL.md)(AI용 런북)를 따르세요. 클라이언트별 **수동 MCP 설정 스니펫**은 [docs/INSTALL.md](./INSTALL.md), 사람용 두 갈래 설치는 [docs/INSTALL_AND_USAGE.md](./INSTALL_AND_USAGE.md)를 참고하세요.
+## 알려진 제약 · 트러블슈팅
+
+- **Codex 데스크톱 앱(⚠️ CLI 권장):** [#24718](https://github.com/openai/codex/issues/24718)(OPEN) 시작 시 전역 `config.toml`을 재작성해 등록이 사라질 수 있음 + [#13025](https://github.com/openai/codex/issues/13025)(OPEN) 프로젝트 `.codex/config.toml` 무시. 그래서 **데스크톱 앱은 비권장, CLI를 쓰세요.** 설치 단계 `npm install`은 기본 샌드박스에서 네트워크가 꺼져 있어 **1회 허용**(또는 `[sandbox_workspace_write] network_access = true`)이 필요. (단 **MCP 서버 자체는 샌드박스 밖에서 돌아** 연결 후 데이터 읽기/쓰기는 막히지 않습니다.)
+- **Claude Desktop에서 등록이 사라짐:** 팀/클라우드 동기화가 로컬 MCP를 덮어쓴 이슈([#59368](https://github.com/anthropics/claude-code/issues/59368), 수정됨). 동기화를 끄거나 **CLI + 프로젝트 `.mcp.json`** 사용.
+- **연결 검증:** `get_onboarding_status` 호출(Codex는 `/mcp`). 빠른 점검: `npx -y careermate doctor`(Node·데이터 폴더·DB 상태).
+- **자세한 복구**(포트 충돌·DB 마이그레이션·완전 초기화): 루트 [`/INSTALL.md`](../INSTALL.md) 9단계.
+
+---
 
-각 모드의 **영구 지침 파일**: Claude Code → [/CLAUDE.md](../CLAUDE.md), Codex → [/AGENTS.md](../AGENTS.md).
+각 모드의 **영구 지침 파일**: Claude Code → [/CLAUDE.md](../CLAUDE.md), Codex → [/AGENTS.md](../AGENTS.md). 사람용 설치 → https://careermate.life · 사용 흐름 → [docs/START_WORKFLOW.md](./START_WORKFLOW.md).

package/docs/WORKFLOWS.md

@@ -7,7 +7,7 @@ CareerMate는 내부에 LLM을 두지 않는다. 분석과 작성은 사용자
 관련 문서:
 
 - 연결 직후 AI가 따라가는 시작 런북은 [시작 런북](./START_WORKFLOW.md)을 참고한다.
-- 설치·연결 절차는 [설치 가이드](./INSTALL.md)를 참고한다.
+- 설치·연결 절차는 [설치 런북](../INSTALL.md)(또는 [지원 앱·설치 레퍼런스](./SUPPORTED_AI_APPS.md))을 참고한다.
 - MCP 도구 24종의 입출력 명세는 코드(`packages/mcp-tools/src/tools.ts`)에 정의되어 있으며, AI는 각 도구의 `inputSchema`로 직접 확인할 수 있다.
 
 ## 워크플로우 5종 개요

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "careermate",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "CareerMate — an MCP-first, local-first career workspace. Connect it to a local AI agent (Claude Desktop, Claude Code, Codex); CareerMate stores your career data locally on your machine and exposes it over MCP.",
   "license": "MIT",
@@ -29,7 +29,6 @@
     "apps",
     "packages",
     "scripts",
-    "install-page",
     "docs",
     "tsconfig.json",
     "README.md",
@@ -48,6 +47,8 @@
     "mcp": "node --no-warnings --experimental-sqlite --import tsx apps/mcp/src/index.ts",
     "migrate": "node --no-warnings --experimental-sqlite --import tsx scripts/migrate.ts",
     "seed": "node --no-warnings --experimental-sqlite --import tsx scripts/seed.ts",
+    "shots:seed": "node --no-warnings --experimental-sqlite --import tsx scripts/shots-seed.ts",
+    "shots": "node --no-warnings --experimental-sqlite --import tsx scripts/shots.ts",
     "doctor": "node --no-warnings --experimental-sqlite --import tsx scripts/doctor.ts",
     "test": "node --no-warnings scripts/run.mjs scripts/test.ts \"TEST_VERDICT PASS\"",
     "test:ui": "node --no-warnings scripts/run.mjs scripts/ui-smoke.ts \"UI_VERDICT PASS\"",

package/packages/core/src/services.ts

@@ -20,6 +20,12 @@ import {
   type DocumentRecord,
   type ProfileInput,
   type ProfileRecord,
+  type ExperienceInput,
+  type ExperienceRecord,
+  type ProjectInput,
+  type ProjectRecord,
+  type SkillInput,
+  type SkillRecord,
   APPLICATION_STATUS_LABELS,
   INTERVIEW_UNLOCK_STATUSES,
 } from '@careermate/shared';
@@ -31,6 +37,9 @@ import {
   interviewRepo,
   documentRepo,
   profileRepo,
+  experienceRepo,
+  projectRepo,
+  skillRepo,
   activityRepo,
 } from '@careermate/db';
 
@@ -50,6 +59,30 @@ export function addResume(input: Omit<DocumentInput, 'kind'> & { kind?: Document
   return doc;
 }
 
+/* ----------------------------------------------- Experiences / Projects / Skills */
+
+// These structured-profile entities have no dedicated activity type; the dashboard
+// logs them under 'profile_updated' (see apps/web routes), so the MCP path matches.
+// Summaries carry only company/project/skill names — never résumé body text.
+
+export function addExperience(input: ExperienceInput): ExperienceRecord {
+  const exp = experienceRepo.add(input);
+  activityRepo.log('profile_updated', `경력(${exp.company})을 추가했습니다.`, 'experience', exp.id);
+  return exp;
+}
+
+export function addProject(input: ProjectInput): ProjectRecord {
+  const prj = projectRepo.add(input);
+  activityRepo.log('profile_updated', `프로젝트(${prj.name})를 추가했습니다.`, 'project', prj.id);
+  return prj;
+}
+
+export function addSkill(input: SkillInput): SkillRecord {
+  const skill = skillRepo.add(input);
+  activityRepo.log('profile_updated', `기술(${skill.name})을 추가했습니다.`, 'skill', skill.id);
+  return skill;
+}
+
 /* -------------------------------------------------------------------- Jobs */
 
 /** Save (or update) a posting and make sure an application row tracks it. */
@@ -139,7 +172,15 @@ export function updateApplicationStatus(
 export function saveInterviewPrep(input: InterviewPrepInput): InterviewPrepRecord {
   const job = jobRepo.get(input.job_id);
   if (!job) throw new Error(`공고를 찾을 수 없습니다: ${input.job_id}`);
-  applicationRepo.ensure(job.id);
+  // Spec gate: interview prep is only allowed once the application has reached
+  // 서류 합격(document_passed) or beyond. Enforce it server-side, not just in prompts.
+  const app = applicationRepo.getByJob(job.id);
+  if (!app || !INTERVIEW_UNLOCK_STATUSES.includes(app.status)) {
+    const current = app ? APPLICATION_STATUS_LABELS[app.status] : '미지원';
+    throw new Error(
+      `면접 준비는 '서류 합격' 이상 상태에서만 저장할 수 있습니다. 현재 상태: '${current}'. 먼저 update_application_status로 상태를 올린 뒤 다시 시도하세요.`,
+    );
+  }
   const prep = interviewRepo.save(input);
   activityRepo.log('interview_prep_saved', `${job.company} · ${job.position} 면접 준비 자료를 저장했습니다.`, 'interview_prep', prep.id);
   return prep;

package/packages/db/src/connection.ts

@@ -28,6 +28,36 @@ export function closeDb(): void {
   }
 }
 
+let _inTx = false;
+
+/**
+ * Run `fn` inside a single transaction so multi-statement writes are atomic:
+ * any thrown error rolls back every statement instead of leaving a half-written
+ * row. node:sqlite has no transaction() helper, so we drive BEGIN/COMMIT/ROLLBACK
+ * directly. Re-entrant: a nested tx() call joins the outer transaction (SQLite
+ * has no nested transactions), so only the outermost call commits or rolls back.
+ */
+export function tx<T>(fn: () => T): T {
+  if (_inTx) return fn();
+  const db = getDb();
+  db.exec('BEGIN');
+  _inTx = true;
+  try {
+    const result = fn();
+    db.exec('COMMIT');
+    return result;
+  } catch (err) {
+    try {
+      db.exec('ROLLBACK');
+    } catch {
+      /* ignore rollback failure; surface the original error */
+    }
+    throw err;
+  } finally {
+    _inTx = false;
+  }
+}
+
 /** Helpers for the JSON-text columns. */
 export function toJson(value: unknown): string {
   return JSON.stringify(value ?? null);

package/packages/db/src/index.ts

@@ -19,4 +19,5 @@ export {
   applicationRepo,
   interviewRepo,
   activityRepo,
+  getEntityCounts,
 } from './repositories.ts';