careermate 0.1.1 → 0.1.2

package/docs/ARCHITECTURE.md

@@ -11,7 +11,7 @@
 CareerMate는 독립적으로 동작하는 **두 개의 로컬 프로세스**로 구성된다.
 
 - **대시보드 웹서버** (`apps/web`) — `npm start`로 사용자가 직접 기동. `http://127.0.0.1:4319`(사용 중이면 다음 포트로 폴백)에 바인딩하고 브라우저를 자동으로 연다. 사람이 보는 UI와 REST API를 제공한다.
-- **MCP stdio 서버** (`apps/mcp`) — AI 클라이언트(Claude Desktop, ChatGPT, Cursor 등)가 `npm run mcp` 형태로 기동. stdio 위에서 MCP 프로토콜로 통신하며, 24개의 CareerMate 도구를 노출한다.
+- **MCP stdio 서버** (`apps/mcp`) — AI 클라이언트(Claude Desktop, ChatGPT, Cursor 등)가 `npm run mcp` 형태로 기동. stdio 위에서 MCP 프로토콜로 통신하며, 31개의 CareerMate 도구를 노출한다.
 
 두 프로세스는 서로를 직접 호출하지 않는다. 대신 **같은 로컬 SQLite 파일**(`~/.careermate/careermate.sqlite`)을 공유한다. AI가 도구로 쓴 내용은 대시보드에 즉시 보이고, 사용자가 대시보드에서 편집한 내용은 AI가 다음 도구 호출에서 그대로 읽는다. SQLite는 WAL(Write-Ahead Logging) 모드로 열려 두 프로세스의 동시 읽기/쓰기를 안전하게 처리한다.
 
@@ -28,7 +28,7 @@ CareerMate는 독립적으로 동작하는 **두 개의 로컬 프로세스**로
   │  │  대시보드 웹서버          │            │  MCP stdio 서버           │       │
   │  │  (npm start)             │            │  (npm run mcp,           │       │
   │  │                          │            │   AI 클라이언트가 기동)   │       │
-  │  │  보안 게이트 → API 라우터 │            │  24개 도구 등록           │       │
+  │  │  보안 게이트 → API 라우터 │            │  31개 도구 등록           │       │
   │  │  → 정적 대시보드/설치페이지│            │  toCallToolResult        │       │
   │  └───────────┬──────────────┘            └───────────┬──────────────┘       │
   │              │                                       │                      │
@@ -72,7 +72,7 @@ CareerMate는 독립적으로 동작하는 **두 개의 로컬 프로세스**로
   ┌───────────────────────────┬───────────────────────────┐
   │                           │                           │
   apps/web (REST API)         packages/mcp-tools          │
-  · routes.ts                 · 24개 도구 정의             │
+  · routes.ts                 · 31개 도구 정의             │
   · security/http/exports     · 핸들러 → core 호출         │
                               └──────────┬────────────────┘
                                          ▼
@@ -190,7 +190,7 @@ CareerMate의 두 표면(MCP 도구, REST API)은 각각 다른 클라이언트
 | `packages/shared` | `@careermate/shared` | 타입, zod 입력 스키마, 상태/문서 라벨·순서 등 상수. 모든 계층이 공유. | (없음) |
 | `packages/db` | `@careermate/db` | 단일 `DatabaseSync` 연결(WAL), 12개 테이블 스키마/마이그레이션, 리포지토리, 데이터 경로(`paths.ts`), 런타임 핸드셰이크(`runtime.ts`). | shared |
 | `packages/core` | `@careermate/core` | 비즈니스 유스케이스. `getApplicationContext`(핵심), `saveProfile`, `saveJobPosting`, `saveFitAnalysis`, `saveCoverLetterVersion`, `updateApplicationStatus`, `saveInterviewPrep`, 온보딩/요약/활동 조회 등. 두 진입점이 공유. | db, shared |
-| `packages/mcp-tools` | `@careermate/mcp-tools` | 24개 MCP 도구 정의(`TOOLS`)와 핸들러, `toCallToolResult`. 도구 핸들러는 core를 호출. | core, shared, parsers/prompts/workflows |
+| `packages/mcp-tools` | `@careermate/mcp-tools` | 31개 MCP 도구 정의(`TOOLS`)와 핸들러, `toCallToolResult`. 도구 핸들러는 core를 호출. | core, shared, parsers/prompts/workflows |
 | `packages/parsers` | `@careermate/parsers` | 공고 텍스트 정제(`cleanJobPosting`), 업로드 파일 텍스트 추출(`extractText`). | shared |
 | `packages/exporters` | `@careermate/exporters` | md/html/txt 내보내기 포맷팅(`ExportResult`). | shared |
 | `packages/prompts` | `@careermate/prompts` | 사용자 AI에 전달할 프롬프트 텍스트(`PROMPTS`). | shared |
@@ -204,5 +204,5 @@ CareerMate의 두 표면(MCP 도구, REST API)은 각각 다른 클라이언트
 
 - 기술 의사결정 근거 및 보안 모델: [DECISIONS.md](./DECISIONS.md)
 - 데이터 모델(테이블 12개): [DATA_MODEL.md](./DATA_MODEL.md)
-- MCP 도구 목록(24개): [MCP_TOOLS.md](./MCP_TOOLS.md)
+- MCP 도구 목록(31개): [MCP_TOOLS.md](./MCP_TOOLS.md)
 - 워크플로우: [WORKFLOWS.md](./WORKFLOWS.md)

package/docs/DECISIONS.md

@@ -140,7 +140,7 @@ CareerMate 내부에는 LLM을 두지 않는다. 대신 MCP(Model Context Protoc
 - 데이터 흐름의 통제권이 사용자에게 있다(어떤 AI를 쓸지 사용자가 선택).
 - "인터페이스 = 대화, 저장소 = 로컬 DB"라는 역할 분리가 명확하다.
 - 트레이드오프: CareerMate 단독으로는 분석을 못 한다. MCP를 지원하는 AI 클라이언트가
-  전제된다. 도구 표면(24개 MCP 도구)과 워크플로 가이드 설계가 제품 품질의 핵심이 된다.
+  전제된다. 도구 표면(31개 MCP 도구)과 워크플로 가이드 설계가 제품 품질의 핵심이 된다.
 
 ---
 

package/docs/DEMO.md

@@ -95,14 +95,14 @@ npm start
 - **글쓰기 선호도**를 꼭 채우세요: 선호 문체(`preferred_tone`)와 강조 포인트(`emphasis_points`). 이 두 값이 이후 자기소개서 품질에 직접 영향을 줍니다.
 - 경력·프로젝트·기술도 이 화면에서 추가할 수 있습니다.
 
-> 참고: 같은 작업을 AI에게 맡길 수도 있습니다. 그 경우 AI가 `save_profile`(전체/부분 저장)·`update_profile`(일부 수정)을 호출합니다. 전달한 필드만 갱신되고 나머지는 유지됩니다(부분 저장 안전).
+> 참고: 같은 작업을 AI에게 맡길 수도 있습니다. 그 경우 AI가 `save_profile`을 호출합니다. 전달한 필드만 갱신되고 나머지는 유지됩니다(부분 저장 안전).
 
 ### 4단계 — 자기소개서/이력서 추가 🧑
 
 - 가진 이력서가 있으면 Documents 페이지에서 추가하고, 대표 문서로 지정합니다(대표 이력서는 이후 분석의 근거로 쓰입니다).
 - 기존 자기소개서가 있으면 함께 등록해 두면 좋습니다(AI가 톤·표현을 참고).
 
-> AI에게 맡기면 `add_resume`(이력서/경력기술서/포트폴리오), `add_cover_letter`(기존 자소서)를 호출합니다.
+> AI에게 맡기면 `add_resume`(이력서/경력기술서/포트폴리오), `save_cover_letter_version`(기존 자소서는 title+content로 v1 저장)을 호출하고, 구조화된 경력·프로젝트·스킬은 `add_experience`·`add_project`·`add_skill`로 저장합니다.
 
 ### 5단계 — AI 클라이언트에서 MCP 연결 확인 🧑
 
@@ -143,7 +143,7 @@ npm run mcp
 
 ### 9단계 — AI가 공고를 구조화해 저장 🤖
 
-- 🤖 (선택) `parse_job_posting`으로 붙여넣은 원문에서 회사명/직무/마감일/키워드를 빠르게 추출합니다(판단은 AI가 직접).
+- 🤖 붙여넣은 원문에서 회사명/직무/마감일/키워드를 AI가 직접 구조화합니다.
 - 🤖 `save_job_posting`으로 저장합니다. `company`·`position`은 필수, 원문은 `description`, 자격/우대는 `requirements`, 키워드는 `keywords`에 넣습니다. 저장하면 **지원(application) 항목이 자동 생성**됩니다. 같은 `url`이면 중복 없이 갱신됩니다.
 
 ### 10단계 — AI가 지원 맥락을 가져옴 (★핵심) 🤖

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`에 정의된 **30개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
+이 문서는 `packages/mcp-tools/src/tools.ts`에 정의된 커리어 워크플로 **31개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
 
 > 설계 원칙: 이 도구들은 단순 CRUD 래퍼가 아닙니다. 각 도구는 AI가 사용자를 대신해 수행하는 실제 작업에 대응하며, 설명에 *언제* 그리고 *어떻게* 호출해야 하는지가 담겨 있습니다. 가장 중요한 도구는 [`get_application_context`](#get_application_context-) 입니다.
 
@@ -16,7 +16,36 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 | 읽기전용(✅) 도구 | 쓰기/부수효과(✏️) 도구 |
 | --- | --- |
-| `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` |
+| `read_document`, `read_inbox`, `get_onboarding_status`, `get_profile`, `get_resumes`, `get_experiences`, `get_projects`, `get_skills`, `get_cover_letters`, `get_job_posting`, `list_jobs`, `get_application_context`, `list_recent_activity`, `get_workflow_guide`, `get_writing_style_guide`, `check_for_update` | `open_inbox`, `save_profile`, `add_resume`, `add_experience`, `add_project`, `add_skill`, `save_cover_letter_version`, `save_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `export_cover_letter`, `open_dashboard`, `open_application`, `update_careermate` |
+
+---
+
+## 0. 문서 읽기 (Read Document)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `read_document` | 컴퓨터의 문서 파일에서 본문 텍스트 추출(PDF·Word·한컴·텍스트) | `path`(절대 경로 권장), `max_chars?` | `{ path, format, characters, truncated, warnings[], text }` | 사용자가 파일 경로를 주며 "이 파일 읽어줘/참고해줘"라고 할 때 | ✅ |
+
+- 지원 형식: `.pdf`, `.docx`, `.hwp`(HWP 5.x), `.hwpx`, `.txt`/`.md` 등 텍스트. 전부 **순수 JS로 추출**하며 외부 변환기(poppler 등) 설치가 필요 없습니다.
+- 추출한 텍스트는 그대로 새 파일로 다시 쓰지 말고, 분석/작성에 활용한 뒤 결과를 `add_resume`·`save_job_posting`·`save_cover_letter_version` 등으로 CareerMate에 저장하세요.
+- **이미지·스캔 PDF**는 텍스트 레이어가 없어 추출되지 않습니다(`unsupported`로 반환되며 `warnings`에 안내). 이때는 이미지를 직접 볼 수 있는 클라이언트(예: Claude)로 읽거나, 사용자에게 내용을 텍스트로 붙여넣어 달라고 안내하세요. 구형 `.doc`/`.ppt`/`.xls`·`.odt`·iWork는 미지원이니 PDF/`.docx`로 다시 저장하도록 안내합니다.
+- 파일은 **로컬에서만** 처리되며 외부로 전송되지 않습니다. 25MB를 넘는 파일은 거부합니다.
+
+---
+
+## 0-1. 인입 폴더 (Inbox)
+
+CLI 클라이언트(Claude Code·Codex 등)는 파일 첨부가 안 되므로, 사용자가 기존 이력서·경력기술서 파일을 끌어다 넣을 수 있는 로컬 인입 폴더(`~/.careermate/inbox`)를 두고 그 안의 파일을 읽습니다. 사용자가 파일 **경로**를 직접 알려주는 경우에는 인입 폴더 대신 `read_document`를 쓰세요.
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `open_inbox` | 인입 폴더(`~/.careermate/inbox`)를 보장하고 파일 탐색기로 열기 + 현재 들어 있는 파일 목록 반환 | 없음 | `{ dir, files[] }` | 온보딩에서 사용자가 "기존에 작성해 둔 이력서 파일이 있다"고 답했을 때만(묻지 않고 자동으로 열지 마세요) | ✏️ |
+| `read_inbox` | 인입 폴더에 넣어 둔 문서들의 본문을 한 번에 추출해 반환 | `filename?`(대소문자 무시, 생략 시 전체), `max_chars?`(파일별 기본 20000자) | `{ dir, files[] }`(각 `{ filename, path, format, unsupported, truncated, warnings[], text }`) | `open_inbox`로 안내한 뒤 사용자가 "다 넣었어"라고 할 때 | ✅ |
+
+- `open_inbox`는 폴더를 열기만 합니다. 사용자가 파일을 다 넣었다고 하면 `read_inbox`로 본문을 읽으세요.
+- `docx`/`hwp`/`hwpx`/텍스트는 텍스트를 추출하고, **`pdf`·이미지는 추출하지 않고 파일 경로만** 돌려주니(`unsupported`) AI 클라이언트의 파일 읽기 기능으로 그 경로를 직접 열어 읽으세요.
+- 읽은 내용은 그대로 새 파일로 다시 쓰지 말고, 구조화해 `save_profile`·`add_resume` 등 알맞은 도구로 CareerMate에 저장하세요.
+- 응답 폭발을 막기 위해 파일별 본문은 `max_chars`(기본 20000자)로 잘라서 돌려주며, 잘린 경우 `truncated: true`로 표시합니다.
 
 ---
 
@@ -25,9 +54,8 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
 | `get_onboarding_status` | CareerMate에 어떤 정보(프로필·이력서·경력·스킬·자소서·공고)가 준비되어 있는지 확인하고 다음 단계를 제시 | 없음 | `completed`, `has_profile`/`has_resume`/`has_cover_letter`/`has_experience`/`has_skills`/`has_job`, `profile_completeness`(0~100), `next_steps[]` | AI 클라이언트 연결 직후 가장 먼저 | ✅ |
-| `start_onboarding` | 가이드형 온보딩 시작. 현재 상태 + AI가 사용자를 안내하는 단계별 지침 반환 | 없음 | `status`(온보딩 상태), `guide`(온보딩 프롬프트 텍스트) | 사용자가 "시작하자 / 설정 도와줘"라고 할 때 | ✅ |
 
-안내 흐름(가이드): 프로필 입력 → 이력서/자소서 추가 → 대시보드 열기.
+AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태를 파악한 뒤, 단계별 가이드가 필요하면 `get_workflow_guide('onboarding')`로 받으세요. 안내 흐름: 프로필 입력 → 이력서/경력·스킬 추가 → 대시보드 열기.
 
 ---
 
@@ -37,7 +65,6 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 | --- | --- | --- | --- | --- | --- |
 | `get_profile` | 기본 프로필 조회(이름, 한 줄 소개, 요약, 희망 직무/조건, 선호 문체, 강조 포인트, 링크) | 없음 | `ProfileRecord` 또는 `null` | 프로필 확인이 필요할 때 | ✅ |
 | `save_profile` | 프로필 저장(부분 저장 안전 — 전달한 필드만 갱신, 나머지는 유지) | 아래 프로필 필드 | 저장된 `ProfileRecord` | 이력서 구조화 후 이름/소개/희망 직무/선호 문체/강조 포인트를 채워 저장할 때 | ✏️ |
-| `update_profile` | 기존 프로필을 유지하며 일부 필드만 수정(`save_profile`과 동일 동작, 의미 명확화용) | 프로필 필드(모두 선택) | 저장된 `ProfileRecord` | 한두 개 항목만 바꿀 때 | ✏️ |
 
 프로필 입력 필드(`ProfileInputSchema`):
 
@@ -87,7 +114,6 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
-| `add_cover_letter` | 기존 자기소개서를 등록(`content`를 주면 첫 버전 v1로 저장) | `title`, `content?`, `job_id?`, `is_primary?`, `note?`, `source?` | 생성/저장된 `CoverLetterRecord` | 사용자가 이미 쓴 자소서를 학습용으로 보관할 때 | ✏️ |
 | `get_cover_letters` | 저장된 자기소개서 조회(공고별 필터 가능). 각 항목은 현재 버전 내용·버전 수 포함 | `job_id?` | `CoverLetterRecord[]` | 자소서 목록/내용을 확인할 때 | ✅ |
 | `save_cover_letter_version` | 자기소개서의 새 버전 저장 — 자소서 작성 워크플로우의 핵심 저장 단계 | `content`(필수), `cover_letter_id?`, `title?`, `job_id?`, `note?`, `source?`, `set_current?` | `{ coverLetter, version }` | 새 공고용 자소서를 생성·갱신해 버전으로 남길 때 | ✏️ |
 
@@ -98,7 +124,7 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 - `job_id`로 공고에 연결하면 지원(application) 항목과 자동 연결됩니다.
 - `set_current`(기본 `true`): 이 버전을 현재 버전으로 지정.
 
-> 새 공고용 자소서를 "생성"해서 저장할 때는 버전 관리를 위해 `add_cover_letter`보다 `save_cover_letter_version`을 사용하는 편이 좋습니다.
+> 기존 자소서를 학습용으로 보관하든 새 공고용 자소서를 새로 쓰든, 저장은 모두 `save_cover_letter_version`으로 합니다. `title`+`content`만 주면 새 자소서의 v1로 저장됩니다.
 
 ---
 
@@ -109,11 +135,10 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 | `save_job_posting` | 채용공고 저장(있으면 갱신). 저장 시 지원(application) 항목 자동 생성 | `company`, `position`(필수), `url?`, `location?`, `employment_type?`, `description?`, `requirements?`, `keywords?`, `deadline?`, `source?` | 저장된 `JobRecord`(`job_id` 포함) | 공고를 DB에 등록/갱신할 때 | ✏️ |
 | `get_job_posting` | 공고 1건 상세 조회 | `job_id` | `{ job, fit, application, cover_letters, interview }` | 한 공고의 분석·상태·자소서·면접 자료를 한 번에 볼 때 | ✅ |
 | `list_jobs` | 저장된 모든 공고를 지원 상태·적합도 점수와 함께 목록화 | 없음 | 공고 메타 포함 배열 | 전체 공고를 훑어볼 때 | ✅ |
-| `parse_job_posting` | 붙여넣은 공고 원문을 정리해 회사명/직무/마감일 추정 + 기술 키워드 추출 | `raw`(공고 원문 텍스트) | 정리된 공고 구조 | `save_job_posting` 전에 빠르게 구조화할 때(보조) | ✅ |
 
 - `url`이 같으면 중복 생성 없이 갱신됩니다.
 - `requirements`에는 자격요건/우대사항 핵심, `keywords`에는 핵심 키워드를 정리해 넣으면 이후 적합도 분석·자소서 작성에 활용됩니다.
-- `parse_job_posting`은 텍스트 정리만 하며 판단/분석은 AI가 직접 수행합니다.
+- 붙여넣은 공고 원문의 구조화(회사명/직무/마감일/키워드 추출)는 AI가 직접 수행한 뒤 `save_job_posting`으로 저장합니다.
 
 ---
 
@@ -217,6 +242,21 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 ---
 
+## 14. 업데이트 (Update)
+
+CareerMate를 최신 버전으로 유지하기 위한 유지보수 도구입니다. 확인은 `check_for_update`로, 실제 적용은 `update_careermate`로 합니다.
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `check_for_update` | npm 레지스트리에서 새 버전이 있는지 지금 확인(공개 버전 정보만 GET, 사용자 데이터 미전송) | 없음 | `{ current, latest, update_available }` | 사용자가 "최신이야?/업데이트 있어?"라고 묻거나 `get_onboarding_status`가 새 버전을 알릴 때 | ✅ |
+| `update_careermate` | 설치 폴더에 `careermate@latest`를 npm으로 설치해 최신 버전으로 업데이트 | 없음 | 업데이트 결과(`{ ok, message, manual? }`) | 사용자가 명시적으로 "업데이트해줘"라고 할 때만 | ✏️ |
+
+- `check_for_update`는 확인만 하며 데이터를 변경하지 않습니다. 새 버전이 있으면 `update_careermate`로 적용하세요.
+- `update_careermate` 성공 후에는 적용을 위해 AI 앱(또는 MCP 연결) **재시작**이 필요합니다. 재시작 시 데이터베이스는 자동 마이그레이션되어 기존 데이터가 보존됩니다.
+- 자동 설치가 막히면(개발 모드·비표준 설치) 직접 칠 명령(`manual`)을 안내합니다.
+
+---
+
 ## ⭐ get_application_context — 분석/작성 전 필수 호출
 
 > `get_application_context`는 **가장 중요한 도구**입니다. 공고를 분석하거나 자기소개서를 작성하기 **전에 반드시 먼저** 호출하세요. 한 번의 호출로 사용자에 대한 모든 맥락을 돌려줍니다. 읽기전용(✅)입니다.

package/docs/ROADMAP.md

@@ -42,10 +42,11 @@ CareerMate는 MCP-우선 로컬 커리어 관리 도구다. 사용자는 자신
 
 ### MCP 서버 (`apps/mcp`) + 도구 (`packages/mcp-tools`)
 - [x] **MCP stdio 서버**: `@modelcontextprotocol/sdk` 기반, AI 클라이언트가 `npm run mcp`로 기동, 대시보드와 동일 DB 공유
-- [x] **24개 MCP 도구**:
-  - 온보딩/프로필: `get_onboarding_status`, `start_onboarding`, `save_profile`, `get_profile`, `update_profile`
-  - 문서: `add_resume`, `get_resumes`, `add_cover_letter`, `get_cover_letters`
-  - 공고: `save_job_posting`, `get_job_posting`, `list_jobs`, `parse_job_posting`
+- [x] **커리어 워크플로 MCP 도구 (26개)**:
+  - 온보딩/프로필: `get_onboarding_status`, `save_profile`, `get_profile`
+  - 문서: `add_resume`, `get_resumes`, `get_cover_letters`
+  - 경력·프로젝트·스킬: `add_experience`, `get_experiences`, `add_project`, `get_projects`, `add_skill`, `get_skills`
+  - 공고: `save_job_posting`, `get_job_posting`, `list_jobs`
   - 컨텍스트(핵심): `get_application_context`
   - 분석/작성: `save_fit_analysis`, `save_cover_letter_version`
   - 지원/면접: `update_application_status`, `save_interview_prep`
@@ -57,7 +58,7 @@ CareerMate는 MCP-우선 로컬 커리어 관리 도구다. 사용자는 자신
 
 ### 기능 흐름 (저장/관리)
 - [x] **온보딩**: 프로필·경력·프로젝트·스킬 입력 흐름
-- [x] **공고 저장 및 파싱**: 공고 본문 저장 + `parse_job_posting`로 구조화
+- [x] **공고 저장**: 공고 본문 저장(회사명/직무/키워드 구조화는 AI가 수행)
 - [x] **적합도(fit) 분석 저장**: `save_fit_analysis`
 - [x] **자소서 버전 관리**: `cover_letter_versions` 테이블 + 타임라인 (Documents 페이지)
 - [x] **지원 상태 관리**: 8단계 칸반 (Applications 페이지) + `update_application_status`
@@ -92,8 +93,8 @@ CareerMate는 MCP-우선 로컬 커리어 관리 도구다. 사용자는 자신
 아래 항목은 **지금은 제외하되, 구조는 열어둔다**. 즉 현재 MVP 범위에서 구현하지 않지만, 패키지 경계·데이터 모델·도구 인터페이스가 이후 추가를 수용할 수 있도록 설계되어 있다.
 
 ### 공고 크롤링 (사람인 / 잡코리아 / 원티드)
-- 현재는 사용자가 공고 본문을 붙여넣으면 `parse_job_posting`이 구조화한다. URL 입력 시 자동 크롤링은 미구현.
-- 구조 개방: 파싱 로직이 `packages/parsers`로 분리되어 있어, 사이트별 크롤러/어댑터를 추가하는 형태로 확장 가능.
+- 현재는 사용자가 공고 본문을 붙여넣으면 AI가 직접 구조화해 `save_job_posting`으로 저장한다. URL 입력 시 자동 크롤링은 미구현.
+- 구조 개방: 텍스트 정제 로직이 `packages/parsers`로 분리되어 있어(대시보드 `/api/parse/job`에서 사용), 사이트별 크롤러/어댑터를 추가하는 형태로 확장 가능.
 - **지금은 제외, 구조는 열어둠.**
 
 ### 클라우드 동기화

package/docs/START_WORKFLOW.md

@@ -15,14 +15,14 @@
 - 연결 직후 가장 먼저 호출합니다.
 - 결과의 `has_profile` / `has_resume` / `has_cover_letter` / `has_experience` / `has_skills` / `has_job`, `profile_completeness`(0~100), `next_steps`를 확인합니다.
 - 사용자에게 "지금까지 등록된 정보"와 "앞으로 채우면 좋은 정보"를 짧게 안내합니다. **이미 채워진 항목은 다시 묻지 마세요.**
-- (선택) 가이드형 안내가 필요하면 `start_onboarding`을 호출해 단계별 지침을 받을 수 있습니다.
+- (선택) 단계별 가이드가 필요하면 `get_workflow_guide('onboarding')`로 받을 수 있습니다.
 
 ### 2. 프로필 수집 및 저장 — `save_profile`
 
 - 사용자가 올린 이력서/자기소개서 파일 또는 직접 알려준 내용을 바탕으로 프로필을 구조화합니다.
 - 정리 항목: 이름, 연락처, 한 줄 소개(`headline`), 요약(`summary`), 희망 직무(`desired_roles`), 희망 근무 조건(`desired_conditions`).
 - **글쓰기 선호도**를 함께 물어보세요: 선호 문체(`preferred_tone`, 예: "담백하고 구체적")와 강조 포인트(`emphasis_points`). 이 두 값은 이후 자기소개서 품질에 직접 영향을 줍니다.
-- `save_profile`로 저장합니다. 전달한 필드만 갱신되고 나머지는 유지됩니다(부분 저장 안전). 한두 개만 바꿀 때는 `update_profile`을 사용해도 됩니다.
+- `save_profile`로 저장합니다. 전달한 필드만 갱신되고 나머지는 유지됩니다(부분 저장 안전). 한두 개만 바꿀 때도 그대로 `save_profile`을 다시 호출하면 됩니다.
 - 파일에서 읽은 정보는 `source`를 `upload`, 사용자가 말로 준 정보는 `manual`로 표시합니다.
 
 ### 3. 이력서 등록 — `add_resume`
@@ -35,10 +35,16 @@
 - `kind`(resume / career_description / portfolio / other)와 `title`을 적절히 지정하고, 대표 문서는 `is_primary=true`로 설정합니다. 대표 문서는 이후 `get_application_context`의 `primary_resume`로 노출됩니다.
 - `source`는 `upload`를 사용합니다.
 
-### 4. 자기소개서 등록 (있는 경우) — `add_cover_letter`
+### 3-1. 경력·프로젝트·스킬 등록 (있는 경우) — `add_experience` · `add_project` · `add_skill`
 
-- 기존 자기소개서가 있으면 `add_cover_letter`로 저장합니다(`title` + `content`). 특정 공고용이면 `job_id`를 연결합니다.
-- `content`를 함께 주면 첫 버전(v1)으로 저장됩니다. 학습/참고용 보관에 적합합니다.
+- 이력서에서 파악되는 경력·프로젝트·보유 기술은 본문 저장과 별개로 `add_experience` / `add_project` / `add_skill`로 항목 단위 저장하면 적합도 분석·자소서·면접 준비에서 정밀하게 활용됩니다.
+- 경력 `achievements`에는 가능하면 정량 지표를 넣고, 기술은 항목당 1건이라 여러 개면 `add_skill`을 반복 호출합니다.
+- 이 항목들은 `get_onboarding_status`의 `has_experience` / `has_skills`와 프로필 완성도(0~100)에 반영됩니다.
+
+### 4. 자기소개서 등록 (있는 경우) — `save_cover_letter_version`
+
+- 기존 자기소개서가 있으면 `save_cover_letter_version`으로 저장합니다(`title` + `content`). 특정 공고용이면 `job_id`를 연결합니다.
+- `cover_letter_id` 없이 `title`+`content`만 주면 새 자소서의 첫 버전(v1)으로 저장됩니다. 학습/참고용 보관에 적합합니다.
 - 없으면 "나중에 공고를 분석한 뒤 맞춤 자기소개서를 써드릴 수 있어요"라고 안내만 합니다.
 
 ### 5. 대시보드 열기 & 다음 단계 — `open_dashboard`
@@ -56,7 +62,7 @@
 ### 1. 공고 저장 — `save_job_posting`
 
 - `company`, `position`은 필수입니다. 공고 원문은 `description`에, 핵심 자격/우대는 `requirements` 배열에, 키워드는 `keywords`에 정리해 넣습니다.
-- (선택) 붙여넣은 원문을 빠르게 구조화하려면 먼저 `parse_job_posting`으로 회사명/직무/마감일 추정과 기술 키워드를 추출할 수 있습니다. 판단은 AI가 직접 하세요.
+- 붙여넣은 원문의 회사명/직무/마감일/기술 키워드 구조화는 AI가 직접 수행한 뒤 위 필드에 채워 저장하세요.
 - 저장하면 지원(application) 항목이 자동 생성되고 `job_id`가 반환됩니다. 같은 `url`이면 중복 없이 갱신됩니다.
 
 ### 2. 지원 맥락 가져오기 — `get_application_context` ⭐ (반드시 먼저)
@@ -96,7 +102,7 @@
 
 ### `update_application_status`
 
-- 지원 상태를 변경합니다. 가능한 상태: saved(저장됨), applied(지원함), document_passed(서류 합격), interview(면접), offer(합격/오퍼), rejected(불합격), closed(종료) 등.
+- 지원 상태를 변경합니다. 가능한 상태는 8단계뿐입니다(AGENTS.md 기준): draft(작성 중), planned(지원 예정), applied(지원 완료), document_passed(서류 합격), interview(면접 진행), final_passed(최종 합격), rejected(불합격), on_hold(보류). 이 외의 값(saved·offer·closed 등)은 대시보드가 모르므로 쓰지 마세요.
 - `note`에 변경 사유를 남길 수 있습니다.
 - 상태가 **서류 합격(document_passed) 이상**으로 바뀌면 면접 준비를 제안하는 힌트를 함께 돌려줍니다 → 다음 단계(E)로 이어집니다.
 

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

@@ -8,7 +8,7 @@ CareerMate는 내부에 LLM을 두지 않는다. 분석과 작성은 사용자
 
 - 연결 직후 AI가 따라가는 시작 런북은 [시작 런북](./START_WORKFLOW.md)을 참고한다.
 - 설치·연결 절차는 [설치 런북](../INSTALL.md)(또는 [지원 앱·설치 레퍼런스](./SUPPORTED_AI_APPS.md))을 참고한다.
-- MCP 도구 24종의 입출력 명세는 코드(`packages/mcp-tools/src/tools.ts`)에 정의되어 있으며, AI는 각 도구의 `inputSchema`로 직접 확인할 수 있다.
+- 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.1",
+  "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",
@@ -56,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/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 });

package/packages/mcp-tools/src/bridge.ts

@@ -5,14 +5,11 @@
  * web server publishes it to a runtime file (see @careermate/db runtime). If the
  * server isn't running we start it (detached) and wait for it to register.
  */
-import { spawn } from 'node:child_process';
+import { spawn, type SpawnOptions } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readRuntimeInfo, isProcessAlive } from '@careermate/db';
-
-// 번들 빌드(esbuild)에서 true로 치환된다. tsx 개발 실행에서는 정의되지 않아 typeof로 안전 분기.
-declare const __BUNDLED__: boolean | undefined;
-const BUNDLED = typeof __BUNDLED__ !== 'undefined' && __BUNDLED__;
+import { BUNDLED } from '@careermate/shared';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // packages/mcp-tools/src -> repo root (dev). 번들에서는 __dirname이 dist/ 이다.
@@ -28,26 +25,38 @@ function liveServer() {
   return null;
 }
 
-/** Start the dashboard server detached and wait until it publishes its address. */
-export async function ensureServer(timeoutMs = 12000): Promise<{ url: string } | null> {
-  const existing = liveServer();
-  if (existing) return { url: existing.url };
-
+/**
+ * Fire-and-forget detached spawn that NEVER throws — synchronously OR
+ * asynchronously. A missing binary (e.g. `xdg-open` on a headless Linux box)
+ * makes spawn emit an async `'error'` event; with no listener that becomes an
+ * uncaughtException and crashes the MCP process. A surrounding try/catch only
+ * guards the synchronous spawn() call, not the later event — so attach the
+ * listener here. stdio defaults to 'ignore'; callers may override via opts.
+ */
+function spawnDetached(cmd: string, args: string[], opts: SpawnOptions = {}): void {
   try {
-    // prod(번들): dist/web.mjs를 플레인 node로 실행. dev: tsx로 소스 실행.
-    const [bin, args, cwd] = BUNDLED
-      ? [process.execPath, ['--experimental-sqlite', path.join(__dirname, 'web.mjs')], __dirname]
-      : [process.execPath, ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', 'apps/web/src/index.ts'], REPO_ROOT];
-    const child = spawn(bin, args, {
-      cwd,
-      detached: true,
-      stdio: 'ignore',
-      env: { ...process.env, CAREERMATE_NO_OPEN: '1' },
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true, ...opts });
+    child.on('error', () => {
+      /* binary missing / spawn failed — best-effort, never crash */
     });
     child.unref();
   } catch {
-    return null;
+    /* best-effort */
   }
+}
+
+/** Start the dashboard server detached and wait until it publishes its address. */
+export async function ensureServer(timeoutMs = 12000): Promise<{ url: string } | null> {
+  const existing = liveServer();
+  if (existing) return { url: existing.url };
+
+  // prod(번들): dist/web.mjs를 플레인 node로 실행. dev: tsx로 소스 실행.
+  const [bin, args, cwd] = BUNDLED
+    ? [process.execPath, ['--experimental-sqlite', path.join(__dirname, 'web.mjs')], __dirname]
+    : [process.execPath, ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', 'apps/web/src/index.ts'], REPO_ROOT];
+  // Spawn failures (sync or async) just leave the server down; the poll loop
+  // below then times out and returns null — no crash.
+  spawnDetached(bin as string, args as string[], { cwd: cwd as string, env: { ...process.env, CAREERMATE_NO_OPEN: '1' } });
 
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
@@ -58,21 +67,35 @@ export async function ensureServer(timeoutMs = 12000): Promise<{ url: string } |
   return null;
 }
 
-export function openInBrowser(url: string): void {
-  const platform = process.platform;
-  try {
-    if (platform === 'win32') {
-      spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
-    } else if (platform === 'darwin') {
-      spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
-    } else {
-      spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
-    }
-  } catch {
-    /* best-effort */
+/** Open a URL or a local folder via the OS default handler. Best-effort, never throws. */
+function openOsTarget(target: string): void {
+  switch (process.platform) {
+    case 'win32':
+      // `start` is a cmd builtin; the empty "" is the window-title arg so a
+      // quoted target isn't mistaken for the title. (explorer also opens URLs,
+      // but `start` is the canonical default-handler launcher.)
+      spawnDetached('cmd', ['/c', 'start', '', target]);
+      break;
+    case 'darwin':
+      spawnDetached('open', [target]);
+      break;
+    default:
+      spawnDetached('xdg-open', [target]);
   }
 }
 
+export function openInBrowser(url: string): void {
+  openOsTarget(url);
+}
+
+/** Open a local folder in the OS file manager (Explorer/Finder/xdg). Best-effort. */
+export function openInFileManager(dir: string): void {
+  // Windows: `explorer <dir>` is the idiomatic folder opener (start "" <dir>
+  // also works, but explorer focuses an existing window if already open).
+  if (process.platform === 'win32') spawnDetached('explorer', [dir]);
+  else openOsTarget(dir);
+}
+
 /** Resolve the dashboard URL, starting the server if needed. */
 export async function resolveDashboardUrl(hash = ''): Promise<{ url: string; running: boolean }> {
   const live = liveServer();

package/packages/mcp-tools/src/index.ts

@@ -6,3 +6,12 @@
 export { TOOLS, EXPORTS_LOCATION } from './tools.ts';
 export { ok, fail, toCallToolResult, type ToolDef, type ToolResult } from './result.ts';
 export { resolveDashboardUrl, openInBrowser, ensureServer, projectRoot } from './bridge.ts';
+export {
+  getUpdateStatus,
+  getUpdateStatusAsync,
+  runSelfUpdate,
+  installPrefix,
+  compareVersions,
+  type UpdateStatus,
+  type UpdateResult,
+} from './update.ts';