careermate 0.1.0 → 0.1.2

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/TODO.md

@@ -54,4 +54,4 @@
 - **.mcpb GitHub Release 생성됨(접근 제한)** — Release `v0.1.0`에 `careermate.mcpb` 첨부. 단 저장소가 **비공개**라 공개 다운로드 링크는 아직 없음. → 저장소를 public으로 전환하면 공개 다운로드 활성화.
 - **공개 repo URL 확정** — git remote 기준 정본은 `osntak/CareerMate`(현재 **비공개**). 공개 전환 여부는 별도 결정 사항.
 - **THIRD_PARTY_NOTICES — `im-not-ai`(MIT)** 항목의 저작권자/연도가 비어 있다. 실제 저작권자·연도로 채우기.
-- **THIRD_PARTY_NOTICES — `im-not-ai`(MIT)** 항목의 저작권자/연도가 비어 있다. 실제 저작권자·연도로 채우기.
+- **`install-page/` 폴더명 변경** — 이제 랜딩+시작마법사+데모(`/demo`)+설치안내를 모두 담는 "공개 웹사이트" 폴더라 `install-page`는 이름이 안 맞는다. 후보: `site` / `www` / `landing`. 주의: 이 폴더는 **Vercel 프로젝트의 Root Directory 설정**이므로, 폴더명을 바꾸면 Vercel 대시보드의 Root Directory 값도 같이 바꿔야 배포가 안 깨진다. 레포 내 코드 참조(고쳐야 할 곳): `scripts/build-dist.mjs`·`scripts/build-mcpb.mjs`·`scripts/shots.ts`·`scripts/gen-og.mjs`·`apps/web/src/server.ts`. 데모 완성 후 진행하기로 합의(2026-06-16).

package/docs/WORKFLOWS.md

@@ -7,8 +7,8 @@ CareerMate는 내부에 LLM을 두지 않는다. 분석과 작성은 사용자
 관련 문서:
 
 - 연결 직후 AI가 따라가는 시작 런북은 [시작 런북](./START_WORKFLOW.md)을 참고한다.
-- 설치·연결 절차는 [설치 가이드](./INSTALL.md)를 참고한다.
-- MCP 도구 24종의 입출력 명세는 코드(`packages/mcp-tools/src/tools.ts`)에 정의되어 있으며, AI는 각 도구의 `inputSchema`로 직접 확인할 수 있다.
+- 설치·연결 절차는 [설치 런북](../INSTALL.md)(또는 [지원 앱·설치 레퍼런스](./SUPPORTED_AI_APPS.md))을 참고한다.
+- MCP 도구 31종의 입출력 명세는 코드(`packages/mcp-tools/src/tools.ts`)에 정의되어 있으며, AI는 각 도구의 `inputSchema`로 직접 확인할 수 있다.
 
 ## 워크플로우 5종 개요
 
@@ -41,9 +41,10 @@ CareerMate는 내부에 LLM을 두지 않는다. 분석과 작성은 사용자
 2. 비어 있는 항목을 사용자에게 쉬운 한국어로 안내하고, 이력서/자기소개서 파일 업로드 또는 정보 입력을 요청한다.
 3. 수집한 정보를 구조화해 `save_profile`로 저장한다(이름·연락처·`headline`·`summary`·`desired_roles`·`desired_conditions`, 그리고 글쓰기 선호인 `preferred_tone`과 `emphasis_points` 포함). 파일 출처는 `source=upload`, 직접 입력은 `manual`.
 4. 업로드한 이력서/경력기술서/포트폴리오 본문을 `add_resume`로 저장한다(`kind`·`title` 지정, 대표 문서는 `is_primary=true`).
-5. 기존 자기소개서가 있으면 `add_cover_letter`로 저장한다(없으면 나중에 작성 가능함을 안내).
-6. `open_dashboard`를 호출해 사용자가 자기 데이터를 확인하게 한다.
-7. 다시 `get_onboarding_status`로 완성도를 확인하고, 다음 단계(공고 분석 등)를 제안한다.
+5. 경력·프로젝트·스킬이 파악되면 `add_experience`·`add_project`·`add_skill`로 각각 저장한다(완성도의 `has_experience`/`has_skills`에 반영).
+6. 기존 자기소개서가 있으면 `save_cover_letter_version`으로 저장한다(`title`+`content`면 v1로 저장, 없으면 나중에 작성 가능함을 안내).
+7. `open_dashboard`를 호출해 사용자가 자기 데이터를 확인하게 한다.
+8. 다시 `get_onboarding_status`로 완성도를 확인하고, 다음 단계(공고 분석 등)를 제안한다.
 
 **도구 호출 순서 요약:**
 
@@ -51,7 +52,8 @@ CareerMate는 내부에 LLM을 두지 않는다. 분석과 작성은 사용자
 get_onboarding_status
   → save_profile
   → add_resume
-  → add_cover_letter (선택)
+  → add_experience / add_project / add_skill (있으면)
+  → save_cover_letter_version (기존 자소서가 있으면)
   → open_dashboard
   → get_onboarding_status (재확인)
 ```

package/docs/superpowers/specs/2026-06-16-demo-dashboard-deploy-design.md

@@ -0,0 +1,64 @@
+# 데모 대시보드 배포 설계 (careermate.life/demo)
+
+작성일: 2026-06-16
+
+## 목표
+
+랜딩 방문자가 **로그인·설치 없이** CareerMate 대시보드를 둘러볼 수 있는 데모 페이지를
+`careermate.life/demo`에 배포한다. 사용자(개발자)가 원격에서 로컬 대시보드(127.0.0.1)에
+접근할 수 없는 문제도 함께 해소한다.
+
+## 결정 사항 (사용자 확인 완료)
+
+- **상호작용**: 편집 가능. 단 메모리 전용 — 디스크/서버 저장 없음, 새로고침 시 샘플로 리셋.
+- **위치**: 기존 Vercel 랜딩(`install-page/`) 하위 `/demo` 서브경로. Vercel 설정·빌드 무변경.
+
+## 핵심 구조
+
+대시보드는 정적 SPA(`apps/web/public`)가 로컬 Node 서버의 `/api/*` JSON을 호출하는 구조다.
+서버 없이 배포하려면 **클라이언트에서 `fetch('/api/*')`를 가로채 메모리 DB로 응답하는 shim**을 끼운다.
+
+대부분의 GET 응답(`/api/summary`, `/api/applications`, `/api/interview`, `/api/jobs/:id` 등)은
+몇 개 기본 컬렉션(jobs, applications, coverLetters, profile, experiences, projects, skills,
+documents, interviews, fits, activities)에서 **파생**된다. shim이 그 파생 로직을 재현하므로
+"한 곳을 수정하면 홈 카운트·목록이 자동 갱신"되는 동작이 공짜로 따라온다.
+
+## 구성 요소
+
+1. **데모 오버레이 소스** (`apps/web/demo/`, 원본 대시보드와 분리)
+   - `seed.js` — 풍부한 샘플 데이터(공고 6+, 지원 단계 다양, 프로필/경력/스킬/문서/자소서/면접).
+   - `demo-shim.js` — 메모리 가변 DB + `window.fetch` 가로채기. GET=읽기, POST/PUT/DELETE=메모리 변경.
+     서버 라우트(`apps/web/src/routes.ts`)와 동일한 응답 형태/파생 로직을 미러링.
+   - `demo.css` + 하단 고정 배너(데모 안내 + "CareerMate 소개로 →" 링크).
+
+2. **빌드 스크립트** (`scripts/build-demo.mjs`)
+   - `apps/web/public/*` → `install-page/demo/`로 복사.
+   - 복사본의 루트 절대경로(`/lib.js`, `/app.js`, `/pages/`, `/styles.css`, `/fonts/`,
+     `/icon-180.png`)를 `/demo/...`로 재작성. `/api/`는 그대로(shim이 처리).
+   - `index.html` `<head>`에 데모 shim(classic script, fetch 선패치) + `demo.css` 주입,
+     `<body>` 끝에 데모 배너 주입.
+   - Node 25의 `fs.rmSync(recursive)` 크래시 회피 → 수동 재귀 삭제 사용.
+
+3. **진입 동선**
+   - 랜딩(`install-page/index.html`)에 "데모 둘러보기" 링크.
+   - 데모 하단 배너의 "CareerMate 소개로 →" 버튼이 랜딩(`/`)으로 복귀.
+
+4. **배포**
+   - 생성물 `install-page/demo/`를 git 커밋 → 기존 Vercel이 자동 서빙.
+   - 갱신: `node scripts/build-demo.mjs`.
+
+## 후속 작업 (TODO)
+
+- [ ] **`install-page/` 폴더명 변경** — 이제 랜딩+시작마법사+데모+설치안내를 모두 담는
+  "공개 웹사이트"라 `install-page`는 이름이 안 맞음. 후보: `site` / `www` / `landing`.
+  주의: 이 폴더는 Vercel 프로젝트의 **Root Directory 설정**이라, 폴더명을 바꾸면
+  Vercel 대시보드의 Root Directory 값도 같이 바꿔야 배포가 안 깨짐(레포 내 참조는 코드 5곳
+  +문서: `scripts/build-dist.mjs`·`build-mcpb.mjs`·`shots.ts`·`gen-og.mjs`·`apps/web/src/server.ts`).
+  → **데모 완성 후 진행하기로 사용자와 합의(2026-06-16).** 그때까지는 `install-page/` 유지.
+
+## 비고 / 한계
+
+- 쓰기 동작 중 AI가 생성하는 것(적합도 분석·자소서 본문·면접 질문)은 시드에 미리 채워 보여주고,
+  대시보드의 수동 쓰기 경로(공고/프로필/상태/문서 CRUD)만 메모리에 반영한다.
+- 데이터는 전부 브라우저 메모리에만 존재. 외부 전송 없음(프라이버시 약속 유지).
+- 검증: 로컬에서 `install-page`를 정적 서빙하고 Playwright로 `/demo` 전 페이지 스크린샷 확인.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "careermate",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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\"",
@@ -55,13 +56,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "fflate": "^0.8.3",
+    "hwp.js": "^0.0.3",
+    "mammoth": "^1.12.0",
+    "pdfjs-dist": "^6.0.0",
     "tsx": "^4.19.2",
     "zod": "^3.24.1"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
     "@types/node": "^22.10.0",
-    "esbuild": "^0.24.0",
+    "esbuild": "^0.28.1",
     "playwright": "^1.60.0",
     "typescript": "^5.7.2"
   }

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';

package/packages/db/src/paths.ts

@@ -34,6 +34,17 @@ export function getUploadsDir(): string {
   return dir;
 }
 
+/**
+ * Drop folder where the user places existing résumé/career files for the AI to
+ * ingest — a workaround for CLI clients that can't attach files (only paths).
+ * Lives under the data dir (not the user's project) so it never pollutes a repo.
+ */
+export function getInboxDir(): string {
+  const dir = path.join(getDataDir(), 'inbox');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
 export function getBackupsDir(): string {
   const dir = path.join(getDataDir(), 'backups');
   fs.mkdirSync(dir, { recursive: true });