careermate 0.1.3 → 0.1.4

package/AGENTS.md

@@ -0,0 +1,33 @@
+# AGENTS.md — CareerMate 상시 지침 (모든 AI 에이전트 공통)
+
+이 파일은 CareerMate를 사용하는 AI 에이전트의 **상시 지침 단일 원본**입니다. Codex CLI는 이 파일을 자동으로 읽고, **Claude(`CLAUDE.md`)와 Gemini(`GEMINI.md`)는 이 파일을 그대로 가져다 씁니다.** 따라서 공통 규칙은 항상 여기 한 곳만 고치면 됩니다. 당신(AI 에이전트)이 **사용자의 커리어를 함께 관리**하기 위한 규칙입니다.
+
+## CareerMate란
+
+CareerMate는 사용자 PC에만 데이터를 두는 **로컬 커리어 작업 공간**입니다. 내부에 LLM이 없는 MCP-우선 도구이며, **AI 서비스가 아니라 "커리어 서랍장"** 입니다. 분석·글쓰기 같은 사고는 모두 **당신이** 하고, CareerMate는 구조화된 커리어 데이터를 저장·제공할 뿐입니다.
+
+> 프라임 디렉티브: **두뇌는 당신, 저장은 CareerMate.** 적합도 분석·자기소개서·면접 자료는 당신이 작성하고, 그 입력과 결과는 CareerMate 도구로 가져오고 저장합니다.
+
+## 규칙
+
+- **기존 데이터를 항상 먼저 활용하라.** 사용자에게 묻거나 무언가를 새로 만들기 전에, CareerMate를 MCP로 조회한다: `get_onboarding_status`(연결 직후 최우선), `get_application_context`, `list_jobs`, `get_profile`, `get_resumes`, `get_cover_letters`, `list_recent_activity`. 이미 채워진 항목은 다시 묻지 마라.
+- **사용자가 파일을 주면 `read_document`로 읽어라.** 이력서·경력기술서·자소서·채용공고가 PDF·Word(`.docx`)·한컴(`.hwp`/`.hwpx`)·텍스트(`.txt`/`.md`) 파일로 컴퓨터에 있고 사용자가 경로로 가리키면, `read_document({ path })`로 본문 텍스트를 추출한 뒤 그 내용으로 작업하고 결과는 아래 저장 도구로 보관한다(파일 내용을 새 파일로 다시 쓰지 마라). 경로는 가능하면 절대 경로로 준다. 이미지·스캔 PDF는 텍스트 레이어가 없어 추출되지 않을 수 있는데, 그때는 이미지를 직접 볼 수 있는 클라이언트로 읽거나 사용자에게 내용을 텍스트로 붙여넣어 달라고 안내한다.
+- **공고 분석·자소서 작성 전에는 반드시 `get_application_context`를 먼저 호출하라.** 한 번의 호출로 프로필·대표 이력서·경력·스킬·기존 자소서·대상 공고·선호 문체·강조 포인트를 모두 돌려준다. 맥락 없이 작성하지 마라.
+- **결과는 다시 CareerMate에 저장하라.** 분석 → `save_fit_analysis`, 자소서 → `save_cover_letter_version`, 공고 → `save_job_posting`, 면접 자료 → `save_interview_prep`. 커리어 데이터는 흩어진 파일이 아니라 CareerMate 안에 둔다. 임의의 로컬 파일 생성은 최소화하라(사용자가 파일을 원하면 `export_cover_letter`로 `~/.careermate/exports`에 내보낸다).
+- **5개 표준 워크플로우를 따르라**: onboarding, analyze_job, write_cover_letter, manage_application_status, prepare_interview. 순서가 헷갈리면 `get_workflow_guide`를 호출한다.
+- **사람이 쓴 듯한 글**이 필요할 때(자소서·자기 PR·지원 메일)는 작성 직전 `get_writing_style_guide`를 적용한다. 사실·수치·고유명사는 그대로 보존한다.
+- **8단계 지원 상태 게이팅을 존중하라**: `draft`(작성 중) → `planned`(지원 예정) → `applied`(지원 완료) → `document_passed`(서류 합격) → `interview`(면접 진행) → `final_passed`(최종 합격) / `rejected`(불합격) / `on_hold`(보류). 면접 준비는 **`document_passed` 이상**에서만 해금된다. 상태 변경은 `update_application_status`.
+- **결과를 낼 때마다 대시보드로 안내하라.** 공고 저장·적합도 분석·자소서 버전·상태 변경·면접 준비 등 무언가를 저장·완료할 때마다 대시보드(`http://127.0.0.1:4319`) 주소를 알려준다. 브라우저를 직접 여는 건 **첫 온보딩 때 한 번만**(`open_dashboard`) — 이후에는 자동으로 열지 말고 링크만 보여주고, 사용자가 "열어줘"라고 하면 그때 `open_application`(단건)·`open_dashboard`(전체)로 연다.
+- **절대 사용자 데이터를 외부로 업로드하지 마라.** 모든 데이터는 `~/.careermate`(Windows: `%USERPROFILE%\.careermate`)에만 있고, 대시보드는 `127.0.0.1`에만 바인딩된다. CareerMate는 (선택적 버전 확인 외) 네트워크로 사용자 데이터를 보내지 않는다.
+- 기술 용어(MCP, `job_id` 등)는 사용자에게 노출하지 말고, 매 단계 무엇을 하는지 쉬운 한국어로 설명하라. 확실하지 않으면 지어내지 말고 사용자에게 확인하라.
+
+## 아직 연결되지 않았다면
+
+CareerMate MCP 도구가 보이지 않으면(예: `get_onboarding_status` 호출 불가) **먼저 설치·등록부터** 한다. **클라이언트별 등록 방법은 [`./INSTALL.md`](INSTALL.md)** 에 있다(Claude Code/Desktop, Codex, Gemini 등). 요지: 해당 클라이언트의 MCP 설정에 stdio 서버로 등록 → AI 클라이언트를 **완전히 재시작** → `get_onboarding_status`를 한 번 호출해 응답이 오는지 확인한다.
+
+## 더 보기
+
+- [`./INSTALL.md`](INSTALL.md) — 설치·등록 런북(클라이언트별 등록 방법)
+- [`docs/START_WORKFLOW.md`](docs/START_WORKFLOW.md) — 연결 직후 사용자를 빠르게 생산적으로 만드는 단계별 런북
+- [`docs/MCP_TOOLS.md`](docs/MCP_TOOLS.md) — MCP 도구 레퍼런스(입력·반환·호출 시점)
+- [`docs/WORKFLOWS.md`](docs/WORKFLOWS.md) — 5개 표준 워크플로우 상세

package/dist/doctor.mjs

@@ -75869,7 +75869,7 @@ var ApplicationContextSchema = external_exports.object({
 });
 
 // packages/shared/src/build-info.ts
-var APP_VERSION = true ? "0.1.3" : "0.0.0-dev";
+var APP_VERSION = true ? "0.1.4" : "0.0.0-dev";
 var BUNDLED = true;
 
 // packages/shared/src/index.ts

package/dist/mcp.mjs

@@ -92893,7 +92893,7 @@ var ApplicationContextSchema = external_exports.object({
 });
 
 // packages/shared/src/build-info.ts
-var APP_VERSION = true ? "0.1.3" : "0.0.0-dev";
+var APP_VERSION = true ? "0.1.4" : "0.0.0-dev";
 var BUNDLED = true;
 
 // packages/shared/src/index.ts

package/dist/web.mjs

@@ -44200,7 +44200,7 @@ var ApplicationContextSchema = external_exports.object({
 });
 
 // packages/shared/src/build-info.ts
-var APP_VERSION = true ? "0.1.3" : "0.0.0-dev";
+var APP_VERSION = true ? "0.1.4" : "0.0.0-dev";
 var BUNDLED = true;
 
 // packages/shared/src/index.ts

package/docs/FAQ.md

@@ -0,0 +1,101 @@
+# 자주 묻는 질문 / 문제 해결 (FAQ & Troubleshooting)
+
+설치·연결·사용 중 자주 막히는 지점을 모았습니다. 설치 자체가 처음이라면
+[`../INSTALL.md`](../INSTALL.md)를, 연결 직후 무엇을 할지는
+[`START_WORKFLOW.md`](START_WORKFLOW.md)를 먼저 보세요.
+
+---
+
+## 설치 / 연결
+
+### "MCP 도구가 안 보여요" / AI가 CareerMate를 모릅니다
+1. AI 클라이언트를 **완전히 종료한 뒤 다시 시작**했는지 확인하세요(설정만 바꾸고 재시작을
+   안 하면 적용되지 않습니다).
+2. Claude Code는 첫 실행 시 프로젝트 서버에 대한 **1회 승인**을 묻습니다 — 승인하세요.
+3. 클라이언트의 `/mcp` 명령으로 `careermate`가 연결됐는지 확인하거나, AI에게
+   "온보딩 상태 확인해줘"라고 해 응답이 오는지 보세요.
+4. 그래도 안 되면 클라이언트별 등록 방법을 [`../INSTALL.md`](../INSTALL.md)와
+   [`SUPPORTED_AI_APPS.md`](SUPPORTED_AI_APPS.md)에서 확인하세요.
+
+### ChatGPT 웹/모바일, Gemini 웹에서 안 돼요
+정상입니다. 이들은 클라우드에서 실행되어 **원격 URL MCP만** 쓸 수 있고, CareerMate는
+사용자 컴퓨터에서 도는 **로컬 stdio 서버**라 닿지 못합니다. 로컬에서 실행되는
+**Claude Desktop · Claude Code · Codex CLI** 를 사용하세요(자세한 이유는
+[`SUPPORTED_AI_APPS.md`](SUPPORTED_AI_APPS.md)).
+
+### Node 버전 오류가 나요
+CareerMate는 **Node.js 22.5.0 이상**이 필요합니다(`node:sqlite` 사용).
+`node -v`로 확인하고 필요하면 업데이트하세요.
+
+---
+
+## 대시보드
+
+### "대시보드가 안 열려요" (`http://127.0.0.1:4319`)
+- 그 주소는 **CareerMate가 실행 중일 때만** 열립니다. AI에게 무언가를 저장해 달라고 해
+  서버가 떠 있는 상태인지 확인하세요.
+- **포트가 이미 사용 중**이면 자동으로 다른 포트로 폴백합니다. 환경변수
+  `CAREERMATE_PORT`로 고정할 수 있습니다.
+- 대시보드는 보안상 **`127.0.0.1`(이 컴퓨터)** 에만 열립니다. 다른 기기에서는 접속되지
+  않습니다(의도된 동작).
+
+### 브라우저를 자동으로 안 열어요
+첫 온보딩 때 한 번만 자동으로 엽니다. 이후에는 링크만 안내합니다 — 직접 주소를 열거나,
+AI에게 "대시보드 열어줘"라고 하세요. 자동 열기를 끄려면 `CAREERMATE_NO_OPEN=1`.
+
+---
+
+## 문서(이력서·공고) 읽기
+
+### "PDF가 안 읽혀요"
+- **스캔본/이미지 PDF**(텍스트 레이어 없음)는 추출되지 않습니다. 이미지를 직접 볼 수 있는
+  AI 클라이언트라면 PDF를 그대로 보여주고, 아니면 내용을 **텍스트로 붙여넣어** 주세요.
+- **암호로 보호된 PDF**는 읽을 수 없습니다. 뷰어에서 암호를 해제해 다시 저장하거나 텍스트로
+  붙여넣으세요.
+- 손상된 PDF, 25MB가 넘는 파일도 거부됩니다 — 안내 메시지에 이유가 나옵니다.
+
+### 지원하는 파일 형식은?
+PDF, Word(`.docx`), 한컴(`.hwp`/`.hwpx`), 텍스트(`.txt`/`.md`). 가능하면 **절대 경로**로
+파일 위치를 알려 주세요(예: `C:\Users\me\Desktop\이력서.pdf`).
+
+### 한글이 깨져요
+CareerMate는 UTF-8과 한국어 인코딩(CP949/EUC-KR)을 자동 감지합니다. 그래도 깨지면 파일을
+UTF-8로 다시 저장하거나 내용을 붙여넣어 주세요.
+
+---
+
+## 공고 분석 / 자소서
+
+### "공고 URL은 어떻게 넣어요?"
+URL을 그대로 붙여넣어도 되고, 공고 **본문 텍스트**를 붙여넣어도 됩니다. CareerMate는 LLM이
+없어 URL을 직접 크롤링하지 않으므로, **공고 본문 텍스트가 있으면 분석 품질이 가장 좋습니다.**
+AI에게 "이 공고 저장하고 분석해줘"라고 하면서 URL이나 본문을 함께 주세요.
+
+### "분석이 안 돼요" / 결과가 비어요
+- 분석은 **AI가** 수행하고 CareerMate는 입력(프로필·공고)과 결과를 저장합니다. 먼저
+  **프로필과 공고가 저장돼 있어야** 합니다.
+- AI에게 "분석 전에 application context부터 불러와줘"라고 하면 프로필·이력서·공고를 한 번에
+  모아 분석 맥락을 갖춥니다.
+
+### 면접 준비가 잠겨 있어요
+면접 준비는 지원 상태가 **'서류 합격(document_passed)' 이상**일 때만 열립니다. 먼저 해당
+공고의 상태를 서류 합격으로 바꿔 주세요(`draft → planned → applied → document_passed → …`).
+
+---
+
+## 데이터 / 프라이버시
+
+### 내 데이터는 어디에 저장되나요?
+사용자 컴퓨터의 `~/.careermate`(Windows: `%USERPROFILE%\.careermate`)에만 저장됩니다.
+대시보드 **설정 > 데이터 저장 위치**에서 정확한 경로를 볼 수 있습니다. 외부로 전송되지
+않습니다.
+
+### 백업하거나 전부 삭제하려면?
+대시보드 **설정 > 백업 / 내보내기**에서 백업 생성·전체 JSON 내보내기를, **위험 구역**에서
+전체 초기화를 할 수 있습니다(초기화 직전 자동 백업).
+
+---
+
+여기서 해결되지 않으면 [GitHub 이슈](https://github.com/osntak/CareerMate/issues)에 남겨
+주세요. **보안 문제**는 이슈가 아니라 [`../SECURITY.md`](../SECURITY.md)의 비공개 절차를
+이용해 주세요.

package/docs/MCP_TOOLS.md

@@ -0,0 +1,292 @@
+# MCP 도구 레퍼런스
+
+CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자는 자신의 ChatGPT/Claude/Gemini와 대화하고, 그 AI가 여기 정의된 MCP 도구를 호출해 로컬 커리어 DB(`~/.careermate/careermate.sqlite`)를 읽고 씁니다. **CareerMate 내부에는 LLM이 없습니다.** 적합도 분석·자기소개서 작성 같은 추론은 모두 사용자의 AI가 수행하고, CareerMate는 데이터를 저장하고 다시 돌려주는 역할만 합니다.
+
+이 문서는 `packages/mcp-tools/src/tools.ts`에 정의된 커리어 워크플로 **31개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
+
+> 설계 원칙: 이 도구들은 단순 CRUD 래퍼가 아닙니다. 각 도구는 AI가 사용자를 대신해 수행하는 실제 작업에 대응하며, 설명에 *언제* 그리고 *어떻게* 호출해야 하는지가 담겨 있습니다. 가장 중요한 도구는 [`get_application_context`](#get_application_context-) 입니다.
+
+관련 문서: 전체 워크플로우는 `get_workflow_guide` 도구 또는 `packages/workflows`를, 데이터 구조는 `packages/shared/src/schemas.ts`를 참고하세요.
+
+---
+
+## 읽기 전용(read-only) 표기 안내
+
+각 도구 항목의 **읽기전용** 열은 `tools.ts`의 `readOnly: true` 플래그를 그대로 반영합니다. 읽기전용 도구는 DB를 변경하지 않고 조회만 하며, 그 외 도구는 데이터를 생성·갱신하거나(쓰기) 브라우저를 여는 등의 부수효과를 가집니다.
+
+| 읽기전용(✅) 도구 | 쓰기/부수효과(✏️) 도구 |
+| --- | --- |
+| `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`로 표시합니다.
+
+---
+
+## 1. 온보딩 (Onboarding)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `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 클라이언트 연결 직후 가장 먼저 | ✅ |
+
+AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태를 파악한 뒤, 단계별 가이드가 필요하면 `get_workflow_guide('onboarding')`로 받으세요. 안내 흐름: 프로필 입력 → 이력서/경력·스킬 추가 → 대시보드 열기.
+
+---
+
+## 2. 프로필 (Profile)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `get_profile` | 기본 프로필 조회(이름, 한 줄 소개, 요약, 희망 직무/조건, 선호 문체, 강조 포인트, 링크) | 없음 | `ProfileRecord` 또는 `null` | 프로필 확인이 필요할 때 | ✅ |
+| `save_profile` | 프로필 저장(부분 저장 안전 — 전달한 필드만 갱신, 나머지는 유지) | 아래 프로필 필드 | 저장된 `ProfileRecord` | 이력서 구조화 후 이름/소개/희망 직무/선호 문체/강조 포인트를 채워 저장할 때 | ✏️ |
+
+프로필 입력 필드(`ProfileInputSchema`):
+
+- `name`(이름), `email`, `phone`, `location`
+- `headline`(한 줄 소개 / 직무 타이틀), `summary`(자기소개 요약)
+- `desired_roles[]`(희망 직무), `desired_conditions`(희망 근무 조건: 연봉·지역·근무형태)
+- `preferred_tone`(자기소개서 선호 문체, 예: "담백하고 구체적")
+- `emphasis_points[]`(강조하고 싶은 핵심 포인트)
+- `links[]`(`{ label, url }` — 포트폴리오/깃허브/링크드인)
+
+> `preferred_tone`과 `emphasis_points`는 이후 자기소개서 작성 품질에 직접 영향을 줍니다.
+
+---
+
+## 3. 이력서 (Resumes / Documents)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `add_resume` | 이력서·경력기술서·포트폴리오 등 문서 저장 | `title`, `content`(필수), `kind?`, `source?`, `is_primary?`, `tags?` | 저장된 `DocumentRecord` | 사용자가 업로드/붙여넣은 텍스트(또는 정리한 Markdown)를 보관할 때 | ✏️ |
+| `get_resumes` | 저장된 문서 조회(종류 필터 가능) | `kind?` | `DocumentRecord[]` | 저장된 이력서/문서를 확인할 때 | ✅ |
+
+- `kind` 값: `resume`(이력서, 기본값) / `career_description`(경력기술서) / `portfolio` / `other`
+- `is_primary: true`로 대표 문서를 지정하면 `get_application_context`의 `primary_resume`로 노출됩니다.
+
+---
+
+## 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)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `get_cover_letters` | 저장된 자기소개서 조회(공고별 필터 가능). 각 항목은 현재 버전 내용·버전 수 포함 | `job_id?` | `CoverLetterRecord[]` | 자소서 목록/내용을 확인할 때 | ✅ |
+| `save_cover_letter_version` | 자기소개서의 새 버전 저장 — 자소서 작성 워크플로우의 핵심 저장 단계 | `content`(필수), `cover_letter_id?`, `title?`, `job_id?`, `note?`, `source?`, `set_current?` | `{ coverLetter, version }` | 새 공고용 자소서를 생성·갱신해 버전으로 남길 때 | ✏️ |
+
+`save_cover_letter_version` 동작(`CoverLetterVersionInputSchema`):
+
+- `cover_letter_id`를 주면 기존 자소서에 **새 버전을 추가**하고, 없으면 새 자소서를 만들어 **v1**로 저장합니다(이때 `title` 권장).
+- `note`에 변경 요약(예: "지원동기 보강")을 남기면 대시보드 버전 히스토리에서 이해하기 쉽습니다.
+- `job_id`로 공고에 연결하면 지원(application) 항목과 자동 연결됩니다.
+- `set_current`(기본 `true`): 이 버전을 현재 버전으로 지정.
+
+> 기존 자소서를 학습용으로 보관하든 새 공고용 자소서를 새로 쓰든, 저장은 모두 `save_cover_letter_version`으로 합니다. `title`+`content`만 주면 새 자소서의 v1로 저장됩니다.
+
+---
+
+## 5. 채용공고 (Jobs)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `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` | 저장된 모든 공고를 지원 상태·적합도 점수와 함께 목록화 | 없음 | 공고 메타 포함 배열 | 전체 공고를 훑어볼 때 | ✅ |
+
+- `url`이 같으면 중복 생성 없이 갱신됩니다.
+- `requirements`에는 자격요건/우대사항 핵심, `keywords`에는 핵심 키워드를 정리해 넣으면 이후 적합도 분석·자소서 작성에 활용됩니다.
+- 붙여넣은 공고 원문의 구조화(회사명/직무/마감일/키워드 추출)는 AI가 직접 수행한 뒤 `save_job_posting`으로 저장합니다.
+
+---
+
+## 6. 적합도 (Fit Analysis)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `save_fit_analysis` | AI가 도출한 적합도 분석 결과 저장(같은 공고에 다시 저장하면 갱신) | `job_id`(필수), `score?`(0~100), `summary?`, `strengths?`, `gaps?`, `matched_keywords?`, `missing_keywords?`, `recommendations?` | 저장된 `FitAnalysisRecord` | 공고와 사용자 정보를 비교 분석한 결과를 저장할 때 | ✏️ |
+
+- `job_id`는 필수이며, 먼저 `save_job_posting`으로 공고가 저장되어 있어야 합니다.
+- 분석 자체는 AI가 수행하고, 이 도구는 결과만 저장합니다. 분석 전에는 반드시 [`get_application_context`](#get_application_context-)로 맥락을 가져오세요.
+
+---
+
+## 7. 지원 상태 (Application Status)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `update_application_status` | 지원 상태 변경. `document_passed` 이상이면 면접 준비를 제안하는 힌트 동봉 | `job_id`, `status`, `note?` | 변경 결과(`hint` 포함 가능) | 지원 진행 단계가 바뀔 때 | ✏️ |
+
+지원 상태 8단계(`APPLICATION_STATUSES`):
+
+| 상태 | 라벨 |
+| --- | --- |
+| `draft` | 작성 중 |
+| `planned` | 지원 예정 |
+| `applied` | 지원 완료 |
+| `document_passed` | 서류 합격 |
+| `interview` | 면접 진행 |
+| `final_passed` | 최종 합격 |
+| `rejected` | 불합격 |
+| `on_hold` | 보류 |
+
+> `document_passed`(서류 합격) 이상에서 면접 준비가 해금되며, 상태 변경 응답에 면접 준비 제안 힌트가 함께 돌아옵니다.
+
+---
+
+## 8. 면접 준비 (Interview Prep)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `save_interview_prep` | 예상 질문·꼬리 질문·STAR 답변 가이드·1분 자기소개 초안 등 면접 준비 자료 저장(같은 공고면 갱신) | `job_id`(필수), `questions?`, `star_guides?`, `self_introduction?`, `notes?` | 저장된 `InterviewPrepRecord`(질문 수 포함) | 보통 서류 합격 후, AI가 생성한 면접 자료를 저장할 때 | ✏️ |
+
+입력 구조(`InterviewPrepInputSchema`):
+
+- `questions[]`: `{ question, intent?(질문 의도), followups?(예상 꼬리 질문), answer_outline?(답변 가이드/핵심 포인트) }`
+- `star_guides[]`: `{ question, situation?, task?, action?, result? }`
+- `self_introduction`: 1분 자기소개 초안
+- `notes`: 면접 후기/메모
+
+---
+
+## 9. 내보내기 (Exports)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `export_cover_letter` | 자기소개서를 Markdown 또는 인쇄용 HTML 파일로 데이터 폴더 `exports/`에 저장 | `cover_letter_id`, `format?`(`md`(기본)/`html`) | `{ path, filename, content }` | 사용자가 "자소서 파일로 받고 싶어"라고 할 때 | ✏️ |
+
+- HTML은 인쇄용으로, 브라우저에서 PDF로 저장할 수 있습니다.
+- 대시보드의 Documents 페이지에서 직접 다운로드할 수도 있습니다.
+
+---
+
+## 10. 대시보드 (Dashboard UI)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `open_dashboard` | 로컬 대시보드를 사용자 브라우저에서 열기(서버 미실행 시 자동 시작) | 없음 | `{ url, running }` | 저장 결과를 사용자가 눈으로 확인하게 할 때(예: 분석/자소서 저장 후) | ✏️ |
+| `open_application` | 특정 공고의 지원 상세 페이지(`/#/jobs/{job_id}`)를 브라우저에서 열기 | `job_id` | `{ url, running }` | 적합도·자소서·면접 준비를 바로 확인하도록 안내할 때 | ✏️ |
+
+- 대시보드 기본 주소: `http://127.0.0.1:4319` (포트 사용 중이면 다음 포트로 폴백).
+- 서버가 실행 중이 아니면 안내 메시지에 `npm start` 실행을 권고합니다.
+
+---
+
+## 11. 활동 (Activity)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `list_recent_activity` | 최근 활동 내역(공고 저장, 적합도 분석, 자소서 버전, 상태 변경, 면접 준비 등) 조회 | `limit?`(기본 20) | `ActivityRecord[]` | "최근에 뭐 했지?" 또는 이어서 작업할 맥락이 필요할 때 | ✅ |
+
+---
+
+## 12. 워크플로우 가이드 (Workflow Guide)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `get_workflow_guide` | 표준 워크플로우의 단계별 안내 반환 | `workflow_id?` | 단일 워크플로우 Markdown 또는 전체 목록(`{ id, title, trigger }[]`) | 어떤 순서로 어떤 도구를 호출할지 확인할 때 | ✅ |
+
+`workflow_id` 값: `onboarding`, `analyze_job`, `write_cover_letter`, `manage_application_status`, `prepare_interview`. 생략하면 전체 목록을 돌려줍니다.
+
+---
+
+## 13. 글쓰기 스타일 가이드 (Writing Style Guide)
+
+| 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
+| --- | --- | --- | --- | --- | --- |
+| `get_writing_style_guide` | "AI 티 안 나는" 한국어 글쓰기 규칙 반환 | 없음 | `{ guide }` (작성 규칙 + 저장 전 자가 점검) | 자기소개서·자기 PR·지원 메일 등 사람이 쓴 듯한 글을 작성하기 직전 | ✅ |
+
+번역투·클리셰·기계적 병렬·상투적 연결어·균일한 문장 리듬 같은 AI-tell을 제거하면서, 사실·수치·고유명사는 그대로 보존하도록 안내합니다. `write_cover_letter` / `analyze_job` 워크플로우의 작성 단계에서 함께 적용합니다. (규칙 출처: `epoko77-ai/im-not-ai`, MIT.)
+
+---
+
+## 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`는 **가장 중요한 도구**입니다. 공고를 분석하거나 자기소개서를 작성하기 **전에 반드시 먼저** 호출하세요. 한 번의 호출로 사용자에 대한 모든 맥락을 돌려줍니다. 읽기전용(✅)입니다.
+
+**입력**
+
+- `job_id?`(선택) — 특정 공고 기준으로 맥락을 모을 때.
+
+**한 번에 반환하는 데이터 전체**(`ApplicationContextSchema`):
+
+| 필드 | 내용 |
+| --- | --- |
+| `profile` | 사용자 프로필(`ProfileRecord` 또는 `null`) |
+| `primary_resume` | 대표 이력서(`is_primary` 문서, 없으면 `null`) |
+| `resumes` | 전체 이력서/문서 배열 |
+| `experiences` | 전체 경력 배열 |
+| `projects` | 프로젝트 배열 |
+| `skills` | 기술스택 배열 |
+| `cover_letters` | 기존 자기소개서 배열(버전 정보 포함) |
+| `recent_applications` | 최근 지원 이력 배열 |
+| `job` | (`job_id` 제공 시) 대상 공고(`JobRecord` 또는 `null`) |
+| `fit_analysis` | (`job_id` 제공 시) 대상 공고의 이전 적합도 분석(`FitAnalysisRecord` 또는 `null`) |
+| `related_history` | 같은 회사/직무 관련 이전 기록 배열 — 각 항목 `{ job, application, fit_analysis }` |
+| `writing_preferences` | 자소서 작성 선호 — `{ preferred_tone, emphasis_points[] }` |
+
+**사용 흐름**
+
+1. (자소서/분석 대상이 있으면) `save_job_posting`으로 공고를 먼저 저장해 `job_id`를 확보.
+2. `get_application_context({ job_id })`로 위 데이터를 한 번에 가져옴.
+3. 이 데이터를 근거로 **AI가** 적합도 분석 또는 자기소개서를 작성.
+4. 결과를 `save_fit_analysis` / `save_cover_letter_version`으로 다시 저장.
+
+> CareerMate는 데이터를 제공할 뿐이고, 분석·작성은 사용자의 AI가 수행합니다. 맥락 없이 작성하지 말고 항상 이 도구로 먼저 사용자 데이터를 확보하세요.

package/docs/START_WORKFLOW.md

@@ -0,0 +1,137 @@
+# CareerMate 시작 런북 (연결 직후 AI용)
+
+설치·연결(`INSTALL.md`)이 끝난 직후, AI(당신)가 사용자를 빠르게 생산적으로 만들기 위해 따라가는 런북입니다. 도구는 정해진 순서로 호출하고, 매 단계 무엇을 하고 있는지 쉬운 한국어로 설명하세요. MCP·job_id 같은 기술 용어는 노출하지 마세요. 확실하지 않은 정보는 지어내지 말고 사용자에게 확인하세요.
+
+> 핵심 원칙: **분석과 글쓰기는 당신(AI)이 수행하고, CareerMate는 데이터를 제공·보관**합니다. 공고 분석이나 자기소개서 작성 전에는 항상 `get_application_context`를 먼저 호출해 근거 데이터를 가져오세요.
+
+> **대시보드 안내 정책**: 브라우저를 직접 여는 건 **첫 온보딩에서 한 번만**(`open_dashboard`)입니다. 이후 무언가를 저장·완료할 때는 **자동으로 새로 열지 말고** 주소(`http://127.0.0.1:4319`)만 안내하고, 사용자가 "열어줘"라고 할 때만 `open_application`(단건)·`open_dashboard`(전체)로 엽니다.
+
+---
+
+## A. 온보딩 (첫 연결 시 한 번)
+
+### 1. 현재 상태 확인 — `get_onboarding_status`
+
+- 연결 직후 가장 먼저 호출합니다.
+- 결과의 `has_profile` / `has_resume` / `has_cover_letter` / `has_experience` / `has_skills` / `has_job`, `profile_completeness`(0~100), `next_steps`를 확인합니다.
+- 사용자에게 "지금까지 등록된 정보"와 "앞으로 채우면 좋은 정보"를 짧게 안내합니다. **이미 채워진 항목은 다시 묻지 마세요.**
+- (선택) 단계별 가이드가 필요하면 `get_workflow_guide('onboarding')`로 받을 수 있습니다.
+
+### 2. 프로필 수집 및 저장 — `save_profile`
+
+- 사용자가 올린 이력서/자기소개서 파일 또는 직접 알려준 내용을 바탕으로 프로필을 구조화합니다.
+- 정리 항목: 이름, 연락처, 한 줄 소개(`headline`), 요약(`summary`), 희망 직무(`desired_roles`), 희망 근무 조건(`desired_conditions`).
+- **글쓰기 선호도**를 함께 물어보세요: 선호 문체(`preferred_tone`, 예: "담백하고 구체적")와 강조 포인트(`emphasis_points`). 이 두 값은 이후 자기소개서 품질에 직접 영향을 줍니다.
+- `save_profile`로 저장합니다. 전달한 필드만 갱신되고 나머지는 유지됩니다(부분 저장 안전). 한두 개만 바꿀 때도 그대로 `save_profile`을 다시 호출하면 됩니다.
+- 파일에서 읽은 정보는 `source`를 `upload`, 사용자가 말로 준 정보는 `manual`로 표시합니다.
+
+### 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`를 사용합니다.
+
+### 3-1. 경력·프로젝트·스킬 등록 (있는 경우) — `add_experience` · `add_project` · `add_skill`
+
+- 이력서에서 파악되는 경력·프로젝트·보유 기술은 본문 저장과 별개로 `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`
+
+- `open_dashboard`를 호출해 사용자가 자기 데이터를 눈으로 확인하게 합니다. (서버가 꺼져 있으면 `npm start` 안내를 돌려줍니다.)
+- 다시 `get_onboarding_status`로 완성도를 확인하고, 비어 있는 부분이 있으면 채우자고 제안합니다.
+- 마무리 제안: "지원하고 싶은 공고가 있으면 링크나 내용을 붙여주세요. 적합도를 분석해드릴게요."
+
+---
+
+## B. 공고 분석하기 (핵심 흐름)
+
+사용자가 공고 링크나 내용을 주면 아래 순서로 진행합니다.
+
+### 1. 공고 저장 — `save_job_posting`
+
+- `company`, `position`은 필수입니다. 공고 원문은 `description`에, 핵심 자격/우대는 `requirements` 배열에, 키워드는 `keywords`에 정리해 넣습니다.
+- 붙여넣은 원문의 회사명/직무/마감일/기술 키워드 구조화는 AI가 직접 수행한 뒤 위 필드에 채워 저장하세요.
+- 저장하면 지원(application) 항목이 자동 생성되고 `job_id`가 반환됩니다. 같은 `url`이면 중복 없이 갱신됩니다.
+
+### 2. 지원 맥락 가져오기 — `get_application_context` ⭐ (반드시 먼저)
+
+- **공고 분석/자소서 작성 전에 반드시 호출합니다.** `job_id`를 넘기면 한 번의 호출로 다음을 모두 돌려줍니다:
+  프로필, 대표 이력서, 전체 경력·프로젝트·스킬, 기존 자기소개서, 최근 지원 이력, 대상 공고와 이전 적합도 분석, 같은 회사/직무 관련 기록, 사용자의 선호 문체·강조 포인트.
+- 이 데이터를 **근거로** 분석/작성하고, 결과는 아래 저장 도구로 다시 저장합니다.
+
+### 3. 적합도 분석 결과 저장 — `save_fit_analysis`
+
+- AI가 공고와 사용자 정보를 비교해 도출한 분석을 저장합니다. `job_id` 필수(2단계의 공고가 먼저 저장돼 있어야 함).
+- 채울 필드: `score`(0~100), `summary`, `strengths`(강점), `gaps`(보완 필요), `matched_keywords` / `missing_keywords`, `recommendations`(자소서·지원 전략 제안).
+- 같은 공고에 다시 저장하면 갱신됩니다.
+
+---
+
+## C. 맞춤 자기소개서 쓰기
+
+### 1. (아직 안 했다면) `get_application_context`로 근거 확보
+
+- 선호 문체·강조 포인트·경력·대상 공고를 가져와 작성의 근거로 삼습니다.
+
+### 2. 새 버전 저장 — `save_cover_letter_version`
+
+- AI가 작성한 자기소개서를 새 버전으로 저장합니다(자소서 작성 워크플로우의 핵심 저장 단계).
+- `cover_letter_id`를 주면 기존 자소서에 새 버전을 추가하고, 없으면 새 자소서를 만들어 v1로 저장합니다(이때 `title` 권장).
+- `note`에 이 버전의 변경 요약(예: "지원동기 보강")을 남기면 사용자가 대시보드 버전 히스토리를 이해하기 쉽습니다.
+- `job_id`로 공고에 연결하면 지원 항목과 자동 연결됩니다.
+
+### 3. (요청 시) 파일로 내보내기 — `export_cover_letter`
+
+- 사용자가 "파일로 받고 싶어"라고 하면 `cover_letter_id`와 `format`(`md` 기본 / 인쇄용 `html`)으로 내보냅니다. 파일은 `~/.careermate/exports`에 저장되고 경로를 알려줍니다.
+
+---
+
+## D. 지원 상태 관리
+
+### `update_application_status`
+
+- 지원 상태를 변경합니다. 가능한 상태는 8단계뿐입니다(AGENTS.md 기준): draft(작성 중), planned(지원 예정), applied(지원 완료), document_passed(서류 합격), interview(면접 진행), final_passed(최종 합격), rejected(불합격), on_hold(보류). 이 외의 값(saved·offer·closed 등)은 대시보드가 모르므로 쓰지 마세요.
+- `note`에 변경 사유를 남길 수 있습니다.
+- 상태가 **서류 합격(document_passed) 이상**으로 바뀌면 면접 준비를 제안하는 힌트를 함께 돌려줍니다 → 다음 단계(E)로 이어집니다.
+
+---
+
+## E. 면접 준비
+
+### `save_interview_prep`
+
+- 보통 상태가 서류 합격으로 바뀐 뒤 진행합니다. 먼저 `get_application_context`(또는 `get_job_posting`)로 공고·직무·자소서를 가져와 근거로 삼으세요.
+- AI가 생성한 자료를 저장합니다: 예상 면접 질문, 꼬리 질문, STAR 답변 가이드, 1분 자기소개 초안 등. `job_id` 필수. 같은 공고에 다시 저장하면 갱신됩니다.
+- 저장 후 `open_application`(또는 `open_dashboard`)으로 사용자가 면접 페이지에서 바로 확인하게 안내합니다.
+
+---
+
+## 보조 도구
+
+- `get_workflow_guide` — 표준 워크플로우(온보딩, 공고 분석, 자소서 작성, 상태 관리, 면접 준비)의 단계별 안내. 어떤 순서로 어떤 도구를 호출할지 확인할 때 사용. `workflow_id` 생략 시 전체 목록.
+- `list_recent_activity` — 최근 활동(공고 저장, 적합도 분석, 자소서 버전, 상태 변경, 면접 준비 등). "최근에 뭐 했지?" 또는 작업을 이어갈 맥락이 필요할 때.
+- `list_jobs` / `get_job_posting` — 저장된 공고 목록 / 단건 상세(적합도·상태·연결 자소서·면접 준비 포함).
+- `get_profile` / `get_resumes` / `get_cover_letters` — 저장된 데이터 조회.
+- `open_dashboard` / `open_application` — 사용자가 결과를 눈으로 확인하도록 브라우저에서 페이지 열기.
+
+## 빠른 요약 — 공고 1건을 끝까지 처리하는 표준 경로
+
+1. `save_job_posting` — 공고 저장 (`job_id` 획득)
+2. `get_application_context` (`job_id`) — 근거 데이터 확보 ⭐
+3. `save_fit_analysis` — 적합도 분석 저장
+4. `save_cover_letter_version` — 맞춤 자소서 버전 저장
+5. `update_application_status` — 지원 상태 갱신
+6. `save_interview_prep` — (서류 합격 후) 면접 준비 저장
+7. `open_application` / `open_dashboard` — 사용자에게 결과 보여주기