careermate 0.0.4 → 0.0.6

package/docs/FAQ.md

@@ -6,6 +6,20 @@
 
 ---
 
+## 시작하기 전에
+
+### 돈이 드나요? API 키가 필요한가요?
+CareerMate 자체는 **무료·오픈소스**이고, 내부에 LLM이 없어 **별도 API 키가 필요 없습니다.**
+분석·작성은 이미 쓰고 있는 AI 구독(Claude 등)이 그대로 수행하고, CareerMate는 커리어
+데이터를 로컬에 저장·제공하는 "서랍장" 역할만 합니다.
+
+### 어떻게 업데이트하나요?
+AI에게 **"CareerMate 업데이트해줘"**(`update_careermate`)라고 하면 최신 버전으로 올립니다.
+확인만 하려면 "최신이야?"(`check_for_update`). 업데이트 후에는 AI 앱 또는 MCP 연결을
+**재시작**해 주세요.
+
+---
+
 ## 설치 / 연결
 
 ### "MCP 도구가 안 보여요" / AI가 CareerMate를 모릅니다
@@ -32,10 +46,11 @@ CareerMate는 **Node.js 22.5.0 이상**이 필요합니다(`node:sqlite` 사용)
 ## 대시보드
 
 ### "대시보드가 안 열려요" (`http://127.0.0.1:4319`)
-- 그 주소는 **CareerMate가 실행 중일 때만** 열립니다. AI에게 무언가를 저장해 달라고 해
-  서버가 떠 있는 상태인지 확인하세요.
+- 그 주소는 **CareerMate가 실행 중일 때만** 열립니다. AI에게 **"대시보드 열어줘"** 라고 하면
+  서버가 꺼져 있을 때도 백그라운드로 자동 시작한 뒤 브라우저를 엽니다.
 - **포트가 이미 사용 중**이면 자동으로 다른 포트로 폴백합니다. 환경변수
   `CAREERMATE_PORT`로 고정할 수 있습니다.
+- 자동 시작이 실패하면 `~/.careermate/server.log`를 확인하세요.
 - 대시보드는 보안상 **`127.0.0.1`(이 컴퓨터)** 에만 열립니다. 다른 기기에서는 접속되지
   않습니다(의도된 동작).
 
@@ -77,9 +92,15 @@ AI에게 "이 공고 저장하고 분석해줘"라고 하면서 URL이나 본문
 - AI에게 "분석 전에 application context부터 불러와줘"라고 하면 프로필·이력서·공고를 한 번에
   모아 분석 맥락을 갖춥니다.
 
-### 면접 준비가 잠겨 있어요
-면접 준비는 지원 상태가 **'서류 합격(document_passed)' 이상**일 때만 열립니다. 먼저 해당
-공고의 상태를 서류 합격으로 바꿔 주세요(`draft → planned → applied → document_passed → …`).
+### 면접 준비는 언제 만들 수 있나요
+공고가 저장되어 있으면 AI에게 면접 준비를 요청해 저장할 수 있습니다. 다만 지원 상태가
+**'서류 합격(document_passed)' 이상**이 되면 대시보드가 면접 준비를 다음 행동으로 더 적극적으로 제안합니다.
+
+### 이력서·자소서를 파일로 받을 수 있나요?
+네. AI에게 **"이력서 파일로 내보내줘"**(또는 자소서/프로필)라고 하면
+`~/.careermate/exports`에 **Markdown** 또는 **인쇄용 HTML**(브라우저에서 "인쇄 → PDF로 저장")로
+저장됩니다(`export_resume`/`export_profile`/`export_cover_letter`). 대시보드 **문서·프로필
+페이지**에서 버튼으로 직접 다운로드할 수도 있습니다.
 
 ---
 

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`에 정의된 커리어 워크플로 **35개 도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
+이 문서는 `packages/mcp-tools/src/tools.ts`에 정의된 커리어 워크플로 **도구**의 레퍼런스입니다. 도구의 입력 파라미터는 `packages/shared/src/schemas.ts`의 zod 스키마와 일치합니다.
 
 > 설계 원칙: 이 도구들은 단순 CRUD 래퍼가 아닙니다. 각 도구는 AI가 사용자를 대신해 수행하는 실제 작업에 대응하며, 설명에 *언제* 그리고 *어떻게* 호출해야 하는지가 담겨 있습니다. 가장 중요한 도구는 [`get_application_context`](#get_application_context-) 입니다.
 
@@ -16,7 +16,7 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 | 읽기전용(✅) 도구 | 쓰기/부수효과(✏️) 도구 |
 | --- | --- |
-| `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_playbook`, `get_verifier`, `validate_cover_letter`, `get_writing_style_guide`, `check_for_update` | `open_inbox`, `save_profile`, `add_resume`, `add_experience`, `add_project`, `add_skill`, `save_cover_letter_version`, `set_verify_mode`, `save_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `export_cover_letter`, `open_dashboard`, `open_application`, `update_careermate` |
+| `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_playbook`, `get_verifier`, `validate_cover_letter`, `get_writing_style_guide`, `check_for_update` | `open_inbox`, `save_profile`, `add_resume`, `delete_resume`, `add_experience`, `delete_experience`, `add_project`, `delete_project`, `add_skill`, `delete_skill`, `save_cover_letter_version`, `delete_cover_letter`, `set_verify_mode`, `save_job_posting`, `delete_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `export_cover_letter`, `export_resume`, `export_profile`, `open_dashboard`, `open_application`, `update_careermate` |
 
 ---
 
@@ -35,16 +35,16 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 ## 0-1. 인입 폴더 (Inbox)
 
-CLI 클라이언트(Claude Code·Codex 등)는 파일 첨부가 안 되므로, 사용자가 기존 이력서·경력기술서 파일을 끌어다 넣을 수 있는 로컬 인입 폴더(`~/.careermate/inbox`)를 두고 그 안의 파일을 읽습니다. 사용자가 파일 **경로**를 직접 알려주는 경우에는 인입 폴더 대신 `read_document`를 쓰세요.
+CLI 클라이언트(Claude Code·Codex 등)는 파일 첨부가 안 되므로, 사용자가 기존 이력서·경력기술서·포트폴리오·자기소개서 파일을 끌어다 넣을 수 있는 로컬 인입 폴더(`~/.careermate/inbox`)를 두고 그 안의 파일을 읽습니다. 사용자가 파일 **경로**를 직접 알려주는 경우에는 인입 폴더 대신 `read_document`를 쓰세요.
 
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
-| `open_inbox` | 인입 폴더(`~/.careermate/inbox`)를 보장하고 파일 탐색기로 열기 + 현재 들어 있는 파일 목록 반환 | 없음 | `{ dir, files[] }` | 온보딩에서 사용자가 "기존에 작성해 둔 이력서 파일이 있다"고 답했을 때만(묻지 않고 자동으로 열지 마세요) | ✏️ |
+| `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에 저장하세요.
+- 읽은 내용은 그대로 새 파일로 다시 쓰지 말고, 구조화해 프로필은 `save_profile`, 이력서·경력기술서·포트폴리오는 `add_resume`, 기존 자기소개서는 `save_cover_letter_version`으로 저장하세요.
 - 응답 폭발을 막기 위해 파일별 본문은 `max_chars`(기본 20000자)로 잘라서 돌려주며, 잘린 경우 `truncated: true`로 표시합니다.
 
 ---
@@ -85,6 +85,7 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | --- | --- | --- | --- | --- | --- |
 | `add_resume` | 이력서·경력기술서·포트폴리오 등 문서 저장 | `title`, `content`(필수), `kind?`, `source?`, `is_primary?`, `tags?` | 저장된 `DocumentRecord` | 사용자가 업로드/붙여넣은 텍스트(또는 정리한 Markdown)를 보관할 때 | ✏️ |
 | `get_resumes` | 저장된 문서 조회(종류 필터 가능) | `kind?` | `DocumentRecord[]` | 저장된 이력서/문서를 확인할 때 | ✅ |
+| `delete_resume` | 저장된 문서(이력서·경력기술서·포트폴리오) 삭제 | `document_id`, `confirm`(=`DELETE`) | `{ deleted, id }` | 사용자가 특정 문서 삭제를 명확히 요청했을 때(먼저 get_resumes로 확인) | ✏️ |
 
 - `kind` 값: `resume`(이력서, 기본값) / `career_description`(경력기술서) / `portfolio` / `other`
 - `is_primary: true`로 대표 문서를 지정하면 `get_application_context`의 `primary_resume`로 노출됩니다.
@@ -99,11 +100,15 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | --- | --- | --- | --- | --- | --- |
 | `add_experience` | 경력(직장 단위) 항목 저장 | `experiences[]` — 각 항목: `company`(필수), `role?`, `employment_type?`, `start_date?`, `end_date?`, `is_current?`, `description?`, `achievements?`, `tech?`, `order_index?` | `ExperienceRecord[]` + 신규/갱신 건수 | 이력서에서 경력을 구조화해 보관할 때(여러 건 한 번에) | ✏️ |
 | `get_experiences` | 저장된 경력을 시간 역순으로 조회 | 없음 | `ExperienceRecord[]` | 경력 목록만 빠르게 확인할 때 | ✅ |
+| `delete_experience` | 경력 항목 1건 삭제 | `experience_id`, `confirm`(=`DELETE`) | `{ deleted, id }` | 잘못 추출/입력된 경력을 지울 때(먼저 get_experiences로 확인) | ✏️ |
 | `add_project` | 대표 프로젝트 항목 저장 | `projects[]` — 각 항목: `name`(필수), `role?`, `description?`, `highlights?`, `tech?`, `url?`, `start_date?`, `end_date?`, `order_index?` | `ProjectRecord[]` + 신규/갱신 건수 | 프로젝트 이력을 구조화해 보관할 때(여러 건 한 번에) | ✏️ |
 | `get_projects` | 저장된 프로젝트 조회 | 없음 | `ProjectRecord[]` | 프로젝트 목록만 확인할 때 | ✅ |
+| `delete_project` | 프로젝트 항목 1건 삭제 | `project_id`, `confirm`(=`DELETE`) | `{ deleted, id }` | 잘못 추출/입력된 프로젝트를 지울 때(먼저 get_projects로 확인) | ✏️ |
 | `add_skill` | 기술스택 항목 저장 | `skills[]` — 각 항목: `name`(필수), `category?`, `level?`, `years?`, `order_index?` | `SkillRecord[]` + 신규/갱신 건수 | 보유 기술을 정리해 둘 때(여러 개 한 번에) | ✏️ |
 | `get_skills` | 저장된 기술스택 조회 | 없음 | `SkillRecord[]` | 기술 목록만 확인할 때 | ✅ |
+| `delete_skill` | 기술 항목 1건 삭제 | `skill_id`, `confirm`(=`DELETE`) | `{ deleted, id }` | 잘못 추출/입력된 기술을 지울 때(먼저 get_skills로 확인) | ✏️ |
 
+- `delete_*`는 항목 1건만 지웁니다. **수정**은 별도 도구 없이 `add_*`로 같은 항목(같은 식별자)을 다시 저장하면 갱신됩니다(멱등).
 - 세 도구 모두 **배열을 받아 여러 건을 한 번에 저장**합니다(한 건이어도 배열로). 항목마다 도구를 반복 호출하지 마세요.
 - **멱등 저장**: 같은 항목(스킬=`name`, 경력=`company`+`role`+`start_date`, 프로젝트=`name`, 대소문자 무시)을 다시 넣어도 중복 행을 만들지 않고 갱신합니다. 누락한 필드는 기존 값을 보존합니다. 한 번의 호출은 한 트랜잭션으로 원자 처리됩니다.
 - `achievements`/`highlights`에는 정량 지표가 담긴 성과를, `tech`에는 사용 기술을 배열로 넣으면 적합도 분석·자소서·면접 준비에서 근거로 활용됩니다.
@@ -117,6 +122,7 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | --- | --- | --- | --- | --- | --- |
 | `get_cover_letters` | 저장된 자기소개서 조회(공고별 필터 가능). 각 항목은 현재 버전 내용·버전 수 포함 | `job_id?` | `CoverLetterRecord[]` | 자소서 목록/내용을 확인할 때 | ✅ |
 | `save_cover_letter_version` | 자기소개서의 새 버전 저장 — 자소서 작성 워크플로우의 핵심 저장 단계 | `content`(필수), `cover_letter_id?`, `title?`, `job_id?`, `note?`, `source?`, `set_current?` | `{ coverLetter, version }` | 새 공고용 자소서를 생성·갱신해 버전으로 남길 때 | ✏️ |
+| `delete_cover_letter` | 자기소개서 삭제(모든 버전 포함) | `cover_letter_id`, `confirm:"DELETE"` | 삭제 결과 | 사용자가 목록에서 삭제 대상을 확인한 뒤 | ✏️ |
 
 `save_cover_letter_version` 동작(`CoverLetterVersionInputSchema`):
 
@@ -127,6 +133,8 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 
 > 기존 자소서를 학습용으로 보관하든 새 공고용 자소서를 새로 쓰든, 저장은 모두 `save_cover_letter_version`으로 합니다. `title`+`content`만 주면 새 자소서의 v1로 저장됩니다.
 
+`delete_cover_letter`는 되돌릴 수 없는 작업이므로, 먼저 `get_cover_letters`로 목록을 확인하고 사용자가 삭제할 항목을 명확히 고른 뒤 호출합니다. 삭제된 자기소개서의 버전은 함께 사라지며, 연결된 지원 기록은 자기소개서 연결만 비워집니다.
+
 ---
 
 ## 5. 채용공고 (Jobs)
@@ -136,10 +144,12 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | `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` | 저장된 모든 공고를 지원 상태·적합도 점수와 함께 목록화 | 없음 | 공고 메타 포함 배열 | 전체 공고를 훑어볼 때 | ✅ |
+| `delete_job_posting` | 채용공고 삭제 | `job_id`, `confirm:"DELETE"` | 삭제 결과 | 사용자가 목록에서 삭제 대상을 확인한 뒤 | ✏️ |
 
 - `url`이 같으면 중복 생성 없이 갱신됩니다.
 - `requirements`에는 자격요건/우대사항 핵심, `keywords`에는 핵심 키워드를 정리해 넣으면 이후 적합도 분석·자소서 작성에 활용됩니다.
 - 붙여넣은 공고 원문의 구조화(회사명/직무/마감일/키워드 추출)는 AI가 직접 수행한 뒤 `save_job_posting`으로 저장합니다.
+- `delete_job_posting`은 연결된 지원 상태·적합도 분석·면접 준비를 함께 삭제합니다. 연결된 자기소개서는 삭제하지 않고 공고 연결만 해제합니다.
 
 ---
 
@@ -147,10 +157,11 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
-| `save_fit_analysis` | AI가 도출한 적합도 분석 결과 저장(같은 공고에 다시 저장하면 갱신) | `job_id`(필수), `score?`(0~100), `summary?`, `strengths?`, `gaps?`, `matched_keywords?`, `missing_keywords?`, `recommendations?` | 저장된 `FitAnalysisRecord` | 공고와 사용자 정보를 비교 분석한 결과를 저장할 때 | ✏️ |
+| `save_fit_analysis` | AI가 도출한 적합도 분석 결과 저장(같은 공고에 다시 저장하면 갱신) | `job_id`(필수), `score?`(0~100), `summary?`, `strengths?`, `gaps?`, `matched_keywords?`, `missing_keywords?`, `recommendations?` | 저장된 `FitAnalysisRecord` + `suggested_next_action` | 공고와 사용자 정보를 비교 분석한 결과를 저장할 때 | ✏️ |
 
 - `job_id`는 필수이며, 먼저 `save_job_posting`으로 공고가 저장되어 있어야 합니다.
 - 분석 자체는 AI가 수행하고, 이 도구는 결과만 저장합니다. 분석 전에는 반드시 [`get_application_context`](#get_application_context-)로 맥락을 가져오세요.
+- 저장 후 응답에는 "이 공고에 맞춘 자기소개서를 써드릴까요?" 선택지가 함께 제공됩니다. AI는 곧장 작성하지 말고 사용자가 "네"를 고른 경우에만 자기소개서 작성 흐름으로 이어갑니다.
 
 ---
 
@@ -173,7 +184,7 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | `rejected` | 불합격 |
 | `on_hold` | 보류 |
 
-> `document_passed`(서류 합격) 이상에서 면접 준비가 해금되며, 상태 변경 응답에 면접 준비 제안 힌트가 함께 돌아옵니다.
+> `document_passed`(서류 합격) 이상에서는 상태 변경 응답에 면접 준비 제안 힌트가 함께 돌아옵니다. 사용자가 요청하면 그 전에도 공고 기준 면접 준비 자료를 저장할 수 있습니다.
 
 ---
 
@@ -181,7 +192,7 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
-| `save_interview_prep` | 예상 질문·꼬리 질문·STAR 답변 가이드·1분 자기소개 초안 등 면접 준비 자료 저장(같은 공고면 갱신) | `job_id`(필수), `questions?`, `star_guides?`, `self_introduction?`, `notes?` | 저장된 `InterviewPrepRecord`(질문 수 포함) | 보통 서류 합격 후, AI가 생성한 면접 자료를 저장할 때 | ✏️ |
+| `save_interview_prep` | 예상 질문·꼬리 질문·STAR 답변 가이드·1분 자기소개 초안 등 면접 준비 자료 저장(같은 공고면 갱신) | `job_id`(필수), `questions?`, `star_guides?`, `self_introduction?`, `notes?` | 저장된 `InterviewPrepRecord`(질문 수 포함) | 사용자가 공고 기준 면접 준비를 요청했을 때 | ✏️ |
 
 입력 구조(`InterviewPrepInputSchema`):
 
@@ -197,9 +208,11 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
 | `export_cover_letter` | 자기소개서를 Markdown 또는 인쇄용 HTML 파일로 데이터 폴더 `exports/`에 저장 | `cover_letter_id`, `format?`(`md`(기본)/`html`) | `{ path, filename, content }` | 사용자가 "자소서 파일로 받고 싶어"라고 할 때 | ✏️ |
+| `export_resume` | 저장된 이력서·경력기술서 등 문서를 Markdown 또는 인쇄용 HTML 파일로 `exports/`에 저장 | `document_id`, `format?`(`md`(기본)/`html`) | `{ path, filename, content }` | 공고 맞춤 이력서를 `add_resume`로 저장한 뒤 "이력서 파일로 받고 싶어"라고 할 때 | ✏️ |
+| `export_profile` | 프로필·경력·프로젝트·보유 기술을 한 장의 이력서 형식으로 모아 Markdown 또는 인쇄용 HTML 파일로 `exports/`에 저장 | `format?`(`md`(기본)/`html`) | `{ path, filename, content }` | 사용자가 "내 프로필을 이력서로 뽑아줘"라고 할 때 | ✏️ |
 
 - HTML은 인쇄용으로, 브라우저에서 PDF로 저장할 수 있습니다.
-- 대시보드의 Documents 페이지에서 직접 다운로드할 수도 있습니다.
+- 대시보드의 Documents·Profile 페이지에서 직접 다운로드할 수도 있습니다.
 
 ---
 
@@ -229,7 +242,7 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 | --- | --- | --- | --- | --- | --- |
 | `get_workflow_guide` | 표준 워크플로우의 단계별 안내 + 그 작업의 **전문가 실행 절차(EOP)**·적용할 플레이북·저장 전 검증기 순서 반환 | `workflow_id?` | 단일 워크플로우 Markdown(EOP·플레이북/검증기 순서 포함) 또는 전체 목록(`{ id, title, trigger }[]`) | 커리어 작업을 시작하기 직전 | ✅ |
 
-`workflow_id` 값: `onboarding`, `analyze_job`, `write_cover_letter`, `manage_application_status`, `prepare_interview`. 생략하면 전체 목록을 돌려줍니다. `analyze_job`/`write_cover_letter`/`prepare_interview`/`onboarding`은 해당 작업의 EOP 본문과 `get_playbook`·`get_verifier` 호출 순서(`career_route`)를 함께 돌려줍니다.
+`workflow_id` 값: `onboarding`, `analyze_job`, `write_cover_letter`, `write_career_description`, `manage_application_status`, `prepare_interview`. 생략하면 전체 목록을 돌려줍니다. `analyze_job`/`write_cover_letter`/`write_career_description`/`prepare_interview`/`onboarding`은 해당 작업의 EOP 본문과 `get_playbook`·`get_verifier` 호출 순서(`career_route`)를 함께 돌려줍니다.
 
 ---
 
@@ -267,7 +280,7 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
-| `get_writing_style_guide` | "AI 티 안 나는" 한국어 글쓰기 규칙 반환 | 없음 | `{ guide }` (작성 규칙 + 저장 전 자가 점검) | 자기소개서·자기 PR·지원 메일 등 사람이 쓴 듯한 글을 작성하기 직전 | ✅ |
+| `get_writing_style_guide` | "AI 티 안 나는" 한국어 글쓰기 규칙 반환 | `doc_type?`(career_description·resume·portfolio면 구조 보존 보정 추가) | `{ guide }` (작성 규칙 + 저장 전 자가 점검) | 자기소개서·자기 PR·지원 메일·경력기술서 등 사람이 쓴 듯한 글을 작성하기 직전 | ✅ |
 
 번역투·클리셰·기계적 병렬·상투적 연결어·균일한 문장 리듬 같은 AI-tell을 제거하면서, 사실·수치·고유명사는 그대로 보존하도록 안내합니다. `write_cover_letter` / `analyze_job` 워크플로우의 작성 단계에서 함께 적용합니다. (규칙 출처: `epoko77-ai/im-not-ai`, MIT.)
 
@@ -283,6 +296,7 @@ CareerMate를 최신 버전으로 유지하기 위한 유지보수 도구입니
 | `update_careermate` | 설치 폴더에 `careermate@latest`를 npm으로 설치해 최신 버전으로 업데이트 | 없음 | 업데이트 결과(`{ ok, message, manual? }`) | 사용자가 명시적으로 "업데이트해줘"라고 할 때만 | ✏️ |
 
 - `check_for_update`는 확인만 하며 데이터를 변경하지 않습니다. 새 버전이 있으면 `update_careermate`로 적용하세요.
+- 사용자가 "업데이트해줘", "CareerMate 업데이트해줘", "최신으로 올려줘"처럼 적용을 명시하면 `update_careermate`를 바로 호출합니다. 이 도구가 최신 버전 확인도 함께 하므로 별도 확인 질문은 필요 없습니다.
 - `update_careermate` 성공 후에는 적용을 위해 AI 앱(또는 MCP 연결) **재시작**이 필요합니다. 재시작 시 데이터베이스는 자동 마이그레이션되어 기존 데이터가 보존됩니다.
 - 자동 설치가 막히면(개발 모드·비표준 설치) 직접 칠 명령(`manual`)을 안내합니다.
 
@@ -312,7 +326,7 @@ CareerMate를 최신 버전으로 유지하기 위한 유지보수 도구입니
 | `fit_analysis` | (`job_id` 제공 시) 대상 공고의 이전 적합도 분석(`FitAnalysisRecord` 또는 `null`) |
 | `related_history` | 같은 회사/직무 관련 이전 기록 배열 — 각 항목 `{ job, application, fit_analysis }` |
 | `writing_preferences` | 자소서 작성 선호 — `{ preferred_tone, emphasis_points[] }` |
-| `recommended_route` | 맥락 기반 추천 워크플로우 id(`analyze_job`/`write_cover_letter`/`prepare_interview`/`onboarding`) 또는 `null`. `get_workflow_guide`의 `workflow_id`로 그대로 사용 |
+| `recommended_route` | 맥락 기반 추천 워크플로우 id(`analyze_job`/`write_cover_letter`/`prepare_interview`/`onboarding`) 또는 `null`. 공고 중심 맥락이 아닌 `write_career_description`은 사용자 요청에 따라 직접 선택한다. `get_workflow_guide`의 `workflow_id`로 그대로 사용 |
 | `verifier_sequence` | 추천 경로에서 저장 직전 적용할 검증기 id 배열(Career-OS) |
 | `next_tool` | 다음에 부를 도구(보통 `get_workflow_guide`) 또는 `null` |
 

package/docs/START_WORKFLOW.md

@@ -1,6 +1,6 @@
 # CareerMate 시작 런북 (연결 직후 AI용)
 
-설치·연결(`INSTALL.md`)이 끝난 직후, AI(당신)가 사용자를 빠르게 생산적으로 만들기 위해 따라가는 런북입니다. 도구는 정해진 순서로 호출하고, 매 단계 무엇을 하고 있는지 쉬운 한국어로 설명하세요. MCP·job_id 같은 기술 용어는 노출하지 마세요. 확실하지 않은 정보는 지어내지 말고 사용자에게 확인하세요.
+설치·연결(`INSTALL.md`)이 끝난 직후, AI(당신)가 사용자를 빠르게 생산적으로 만들기 위해 따라가는 런북입니다. 도구는 정해진 순서로 호출하고, 매 단계 무엇을 하고 있는지 사용자의 언어로 쉽게 설명하세요. MCP·job_id 같은 기술 용어는 노출하지 마세요. 확실하지 않은 정보는 지어내지 말고 사용자에게 확인하세요.
 
 > 핵심 원칙: **분석과 글쓰기는 당신(AI)이 수행하고, CareerMate는 데이터를 제공·보관**합니다. 공고 분석이나 자기소개서 작성 전에는 항상 `get_application_context`를 먼저 호출해 근거 데이터를 가져오세요.
 
@@ -19,7 +19,7 @@
 
 ### 2. 프로필 수집 및 저장 — `save_profile`
 
-- 사용자가 올린 이력서/자기소개서 파일 또는 직접 알려준 내용을 바탕으로 프로필을 구조화합니다.
+- 사용자가 올린 이력서/경력기술서/포트폴리오/자기소개서 파일 또는 직접 알려준 내용을 바탕으로 프로필을 구조화합니다.
 - 정리 항목: 이름, 연락처, 한 줄 소개(`headline`), 요약(`summary`), 희망 직무(`desired_roles`), 희망 근무 조건(`desired_conditions`).
 - **글쓰기 선호도**를 함께 물어보세요: 선호 문체(`preferred_tone`, 예: "담백하고 구체적")와 강조 포인트(`emphasis_points`). 이 두 값은 이후 자기소개서 품질에 직접 영향을 줍니다.
 - `save_profile`로 저장합니다. 전달한 필드만 갱신되고 나머지는 유지됩니다(부분 저장 안전). 한두 개만 바꿀 때도 그대로 `save_profile`을 다시 호출하면 됩니다.

package/docs/SUPPORTED_AI_APPS.md

@@ -31,6 +31,19 @@ CareerMate는 LLM이 없는 **로컬 MCP 도구**입니다. *내 컴퓨터에서
 ### 동작하지 않는 것
 **ChatGPT · Gemini · Claude의 웹·모바일 앱은 안 됩니다.** 클라우드에서 실행되어 **원격 URL 기반 MCP만** 지원하므로, 내 컴퓨터의 로컬 stdio 서버에 직접 닿을 수 없습니다.
 
+### 첫 사용 마찰 — 도구 사전허용 (자동)
+`careermate init`은 **연결한 클라이언트에만**(감지된/`--client`로 지정한 것) 커리어 데이터 도구를 미리 허용해, 첫 사용 때 도구마다 뜨는 승인 프롬프트를 없앱니다. **민감/파괴 4개(`read_document`·`update_careermate`·`delete_cover_letter`·`delete_job_posting`)는 어느 클라이언트에서도 자동승인하지 않고 그때그때 확인**을 받습니다. `--no-allow-tools`로 전체를 끌 수 있습니다.
+
+| 앱 | 사전허용 방식 | 쓰는 파일 |
+|---|---|---|
+| **Claude Code** | `permissions.allow` + 서버 신뢰(`enabledMcpjsonServers`) | 작업 폴더 `.claude/settings.local.json` |
+| **Codex CLI** | 서버 도구 자동승인(`default_tools_approval_mode = "auto"`) + 민감 4개만 `approval_mode = "prompt"` | `~/.codex/config.toml` |
+| **Cursor (≥3.6)** | `mcpAllowlist`에 SAFE 도구만(`"careermate:<tool>"`) | `~/.cursor/permissions.json` |
+| **Gemini CLI · Antigravity** | (자동 안 함) — 도구별 사전허용이 없고 서버 단위 일괄 신뢰만 있어, 민감 도구까지 자동승인되는 걸 피하려고 **첫 사용 1회 "허용"**만 받습니다 | — |
+| **Claude Desktop "채팅"** | (자동 안 함) — 앱이 세션 UI에서 "항상 허용"으로 기억 | — |
+
+> 폴더를 처음 "신뢰"하는 1회 다이얼로그(Claude Code의 폴더 신뢰, Codex의 워크스페이스 신뢰)는 클라이언트가 강제하는 보안 게이트라 사라지지 않습니다 — 한 번만 승인하면 됩니다.
+
 ---
 
 ## 구독·준비물 (2026)

package/docs/WORKFLOWS.md

@@ -8,23 +8,25 @@ CareerMate는 내부에 LLM을 두지 않는다. 분석과 작성은 사용자
 
 - 연결 직후 AI가 따라가는 시작 런북은 [시작 런북](./START_WORKFLOW.md)을 참고한다.
 - 설치·연결 절차는 [설치 런북](../INSTALL.md)(또는 [지원 앱·설치 레퍼런스](./SUPPORTED_AI_APPS.md))을 참고한다.
-- MCP 도구 31종의 입출력 명세는 코드(`packages/mcp-tools/src/tools.ts`)에 정의되어 있으며, AI는 각 도구의 `inputSchema`로 직접 확인할 수 있다.
+- MCP 도구의 입출력 명세는 코드(`packages/mcp-tools/src/tools.ts`)에 정의되어 있으며, AI는 각 도구의 `inputSchema`로 직접 확인할 수 있다.
 
-## 워크플로우 5종 개요
+## 워크플로우 7종 개요 (핵심 6 + build_personal_brand)
 
 | id | 제목 | 핵심 목적 |
 | --- | --- | --- |
 | `onboarding` | 온보딩 (첫 셋업) | 프로필·이력서·자기소개서를 등록하고 대시보드를 연다. |
 | `analyze_job` | 공고 분석 (적합도 분석) | 공고를 읽어 프로필과 비교하고, 공고·적합도 분석을 저장한 뒤 자기소개서 작성을 제안한다. |
 | `write_cover_letter` | 자기소개서 작성 | 특정 공고에 맞춘 자기소개서를 사용자 확인을 거쳐 작성·버전 저장한다. |
+| `write_career_description` | 경력기술서 작성 | 프로필·이력서·경력·프로젝트·스킬을 근거로 실제 제출 가능한 경력기술서를 작성·저장한다. |
 | `manage_application_status` | 지원 상태 관리 | 지원 진행 상황(8단계)을 업데이트하고 다음 행동을 제안한다. |
-| `prepare_interview` | 면접 준비 | 서류 합격 이후 예상 질문·STAR 답변·1분 자기소개를 준비·저장한다. |
+| `prepare_interview` | 면접 준비 | 공고 기준 예상 질문·STAR 답변·1분 자기소개를 준비·저장한다. |
+| `build_personal_brand` | 퍼스널 브랜드 (LinkedIn·포트폴리오) | LinkedIn 프로필·포트폴리오 같은 자기표현 자산을 직무에 맞춰 작성·최적화한다(이력서 임포트와 분리된 선택 작업). |
 
 ## 공통 원칙
 
 - **추측 금지**: 저장된 실제 경험·성과만 사용한다. 없는 경험을 지어내지 않으며, 빈칸이나 확인이 필요한 부분은 표시해 사용자에게 묻는다.
 - **사용자 확인 우선**: 큰 작업(자기소개서 작성 등)을 진행하기 전에 대상·강조점·톤·분량을 확인한다.
-- **쉬운 한국어 전달**: 분석·결과를 사용자에게 설명할 때는 기술 용어를 빼고 쉬운 한국어로 전달한다.
+- **쉬운 전달(사용자 언어)**: 분석·결과를 사용자에게 설명할 때는 기술 용어를 빼고 사용자의 언어로 쉽게 전달한다.
 - **로컬 전용**: 모든 데이터는 로컬에만 저장된다.
 
 ---
@@ -38,7 +40,7 @@ CareerMate는 내부에 LLM을 두지 않는다. 분석과 작성은 사용자
 **단계:**
 
 1. `get_onboarding_status`를 호출해 현재 등록 상태(`has_profile`, `has_resume`, `has_cover_letter`, `has_experience`, `has_skills`, `profile_completeness`, `next_steps`)를 확인한다.
-2. 비어 있는 항목을 사용자에게 쉬운 한국어로 안내하고, 이력서/자기소개서 파일 업로드 또는 정보 입력을 요청한다.
+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_experience`·`add_project`·`add_skill`로 저장한다 — 각 도구는 배열을 받으므로 파악한 항목을 한 번에 모아 넘긴다(항목마다 반복 호출하지 않는다). 같은 항목을 다시 넣어도 중복 없이 갱신된다(완성도의 `has_experience`/`has_skills`에 반영).
@@ -73,9 +75,9 @@ get_onboarding_status
 3. **비교/분석** — 공고 요구사항과 사용자 경력/스킬/프로젝트를 비교한다. 일치하는 강점(`strengths`)과 부족한 부분(`gaps`), 매칭 키워드(`matched_keywords`)와 누락 키워드(`missing_keywords`)를 도출하고, 종합 적합도 점수(`score` 0~100)와 요약(`summary`), 지원 전략 제안(`recommendations`)을 정리한다. **없는 경험을 지어내지 않는다.**
 4. **공고 저장** — 아직 저장되지 않은 공고라면 `save_job_posting`으로 공고를 저장하고 `job_id`를 확보한다.
 5. **분석 저장** — 도출한 분석 결과를 `save_fit_analysis`로 저장한다(`job_id`, `score`, `summary`, `strengths`, `gaps`, `matched_keywords`, `missing_keywords`, `recommendations`).
-6. **사용자 설명** — 분석 결과를 사용자에게 쉬운 한국어로 설명한다(잘 맞는 점, 보완할 점, 추천 전략). 기술 용어는 빼고 전달한다.
-7. **자소서 제안** — "이 공고에 맞춘 자기소개서를 써드릴까요?"라고 자기소개서 작성을 제안한다.
-8. **동의 시 자소서 저장** — 사용자가 동의하면 적합도 분석과 글쓰기 선호를 반영해 자기소개서를 작성하고 `save_cover_letter_version`으로 저장한다(`job_id` 연결, `note`에 작성 의도 요약).
+6. **사용자 설명** — 분석 결과를 사용자의 언어로 쉽게 설명한다(잘 맞는 점, 보완할 점, 추천 전략). 기술 용어는 빼고 전달한다.
+7. **자소서 선택 제안** — 분석 뒤 곧장 자기소개서를 쓰지 말고 "이 공고에 맞춘 자기소개서를 써드릴까요?"라고 묻고 선택지를 제시한다: ① "네, 이 공고에 맞춘 자기소개서를 써줘" ② "아니요, 분석만 저장해줘".
+8. **동의 시 자소서 저장** — 사용자가 ①을 선택하면 자기소개서를 작성하기 직전 `get_writing_style_guide`로 "AI 티 안 나는 글쓰기 규칙"을 가져와, 적합도 분석·글쓰기 선호와 함께 반영해 자기소개서를 작성하고 `save_cover_letter_version`으로 저장한다(`job_id` 연결, `note`에 작성 의도 요약). ②를 선택하면 자소서 작성 없이 멈추고 저장 결과와 대시보드 확인만 안내한다.
 9. **지원 건 열기** — `open_application`으로 해당 지원 건을 열어 사용자가 결과를 확인하게 하고, 지원 상태 변경(예: 지원 예정/지원 완료)을 제안한다.
 
 **도구 호출 순서 요약(정식 흐름):**
@@ -86,9 +88,9 @@ get_onboarding_status
   → (비교/분석: strengths·gaps·키워드·score·summary·recommendations)
   → save_job_posting                  # 미저장 공고일 때만, job_id 확보
   → save_fit_analysis                 # job_id 연결
-  → (사용자에게 쉬운 한국어로 설명)
-  → (자기소개서 작성 제안)
-  → save_cover_letter_version         # 사용자 동의 시에만, job_id·note
+  → (사용자의 언어로 쉽게 설명)
+  → (자기소개서 작성 여부 선택지 제안)
+  → save_cover_letter_version         # 사용자가 "네"를 선택한 경우에만, job_id·note
   → open_application                  # 결과 확인 + 상태 변경 제안
 ```
 
@@ -106,16 +108,18 @@ get_onboarding_status
 
 1. `get_application_context`(가능하면 `job_id` 포함)를 호출해 프로필·경력·프로젝트·스킬·기존 자기소개서·이전 적합도 분석·글쓰기 선호(`preferred_tone`, `emphasis_points`)를 가져온다.
 2. 작성 전에 대상 공고, 강조할 포인트, 톤, 분량을 사용자에게 확인한다(확인 없이 큰 작업을 진행하지 않는다).
-3. 저장된 실제 경험·성과만으로 자기소개서를 작성한다. 빈칸이나 확인이 필요한 부분은 추측하지 말고 표시해 사용자에게 묻는다.
-4. 완성본을 `save_cover_letter_version`으로 저장한다(기존 자기소개서면 `cover_letter_id`, 새로 만들면 `title`, 공고용이면 `job_id`, 변경 요약은 `note`, `source=ai`).
-5. 사용자가 원하면 `export_cover_letter`로 파일로 내보내고, 추가 수정 요청이 있으면 새 버전으로 다시 저장한다.
-6. 저장 결과를 쉬운 한국어로 알리고, 지원 상태 업데이트(`update_application_status`)나 면접 준비 등 다음 단계를 제안한다.
+3. `get_writing_style_guide`를 호출해 "AI 티 안 나는 글쓰기 규칙"(번역투·클리셰·기계적 병렬·상투적 연결어·균일한 문장 리듬 제거)을 가져온다.
+4. 저장된 실제 경험·성과만으로 자기소개서를 작성하되, 위 글쓰기 규칙을 적용해 사람이 쓴 듯 자연스럽게 쓴다(사실·수치·고유명사는 그대로). 빈칸이나 확인이 필요한 부분은 추측하지 말고 표시해 사용자에게 묻는다.
+5. 완성본을 `save_cover_letter_version`으로 저장한다(기존 자기소개서면 `cover_letter_id`, 새로 만들면 `title`, 공고용이면 `job_id`, 변경 요약은 `note`, `source=ai`).
+6. 사용자가 원하면 `export_cover_letter`로 파일로 내보내고, 추가 수정 요청이 있으면 새 버전으로 다시 저장한다.
+7. 저장 결과를 사용자의 언어로 알리고, 지원 상태 업데이트(`update_application_status`)나 면접 준비 등 다음 단계를 제안한다.
 
 **도구 호출 순서 요약:**
 
 ```
 get_application_context               # job_id 있으면 함께 전달
   → (대상·강조점·톤·분량 확인)
+  → get_writing_style_guide           # 작성 직전, AI 티 안 나는 글쓰기 규칙
   → save_cover_letter_version         # cover_letter_id 또는 title, job_id, note, source=ai
   → export_cover_letter (선택)
   → (다음 단계 제안: update_application_status 등)
@@ -123,7 +127,41 @@ get_application_context               # job_id 있으면 함께 전달
 
 ---
 
-## 4. manage_application_status — 지원 상태 관리
+## 4. write_career_description — 경력기술서 작성
+
+프로필·이력서·경력·프로젝트·스킬을 근거로 실제 제출 가능한 경력기술서를 작성하고 문서함에 저장하는 흐름.
+
+**트리거:** 사용자가 "경력기술서 써줘 / 경력기술서 만들어줘 / 내 경력 정리해줘"라고 요청할 때.
+
+**단계:**
+
+1. `get_onboarding_status`로 준비 상태를 확인하고, `get_profile`·`get_resumes`·`get_experiences`·`get_projects`·`get_skills`를 호출해 기존 프로필, 이력서, 경력기술서(`kind=career_description`), 경력, 프로젝트, 기술스택을 모두 확인한다.
+2. 사용자가 파일 경로를 주면 `read_document`로 읽고, 인입 폴더를 사용했다면 `read_inbox`로 본문을 읽는다. 이미 저장된 자료와 새 파일을 비교해 중복·상충되는 사실은 표시하고 추측하지 않는다.
+3. `get_workflow_guide({ workflow_id: "write_career_description" })`가 안내하는 전문가 절차를 따른다. 작성 직전 `get_playbook({ domain: "resume" })`와 `get_playbook({ domain: "ats" })`를 받아 실제 경력기술서 형식과 ATS 친화성을 적용한다.
+4. 작성 전에 목적을 확인한다: 범용 마스터본인지, 특정 직무/공고용인지, 신입/무경력이라 프로젝트·교육·활동 중심 역량기술서로 쓸지, 분량과 톤은 어떻게 할지 묻는다.
+5. 경력기술서는 자기소개서처럼 서사로 쓰지 않는다. 제목, 핵심 요약, 핵심 역량, 경력/프로젝트별 역할·기간·도구·문제·행동·성과를 표나 불릿 중심으로 정리한다. 수치·회사명·기간·직책은 저장된 사실만 쓰고, 없는 성과 수치는 만들지 않는다.
+6. 무경력/비개발자라면 경력을 날조하지 말고 교육·프로젝트·운영 경험·업무 도구·협업 경험·성과 증거 중심의 "역량기술서"로 구성한다.
+7. 저장 직전 `get_verifier({ id: "truthfulness" })`, `get_verifier({ id: "consistency" })`, `get_verifier({ id: "ats-compat" })`를 받아 AI가 직접 점검하고, 허위·상충·키워드 누락을 고친다.
+8. 완성본을 `add_resume`으로 저장한다(`kind=career_description`, `source=ai`, title은 사용 목적이 드러나게 작성, tags에 직무/용도 키워드 포함). 대표 문서로 삼아도 되는지 확인된 경우에만 `is_primary=true`를 쓴다.
+9. 저장 결과를 사용자의 언어로 알리고, 문서 탭에서 확인할 수 있음을 안내한다. 특정 공고용으로 작성했다면 이어서 자기소개서나 면접 준비를 제안한다.
+
+**도구 호출 순서 요약:**
+
+```
+get_onboarding_status
+  → get_profile / get_resumes / get_experiences / get_projects / get_skills
+  → read_document | read_inbox (사용자가 파일을 준 경우)
+  → get_workflow_guide({ workflow_id: "write_career_description" })
+  → get_playbook({ domain: "resume" }) / get_playbook({ domain: "ats" })
+  → (목적·대상 직무·분량 확인)
+  → (경력기술서 작성: 요약·역량·경력/프로젝트·성과)
+  → get_verifier({ id: "truthfulness" }) / get_verifier({ id: "consistency" }) / get_verifier({ id: "ats-compat" })
+  → add_resume(kind=career_description, source=ai)
+```
+
+---
+
+## 5. manage_application_status — 지원 상태 관리
 
 지원 진행 상황(8단계)을 업데이트하고 상태에 맞는 다음 행동을 제안하는 흐름.
 
@@ -133,7 +171,7 @@ get_application_context               # job_id 있으면 함께 전달
 
 1. 필요하면 `get_application_context` 또는 `get_job_posting`으로 대상 지원 건과 공고를 확인한다.
 2. 적절한 상태로 `update_application_status`를 호출한다. 8단계: `draft`(작성 중), `planned`(지원 예정), `applied`(지원 완료), `document_passed`(서류 합격), `interview`(면접 진행), `final_passed`(최종 합격), `rejected`(불합격), `on_hold`(보류). 변경 사유는 `note`에 남긴다.
-3. 변경 결과를 사용자에게 쉬운 한국어로 알린다.
+3. 변경 결과를 사용자의 언어로 쉽게 알린다.
 4. 상태에 맞는 다음 단계를 제안한다:
    - `applied` → 결과 기다리기 안내
    - `document_passed` / `interview` → 면접 준비(`prepare_interview`) 제안
@@ -141,7 +179,7 @@ get_application_context               # job_id 있으면 함께 전달
    - `rejected` / `on_hold` → 회고 또는 다른 공고 탐색 제안
 5. 필요하면 `open_application`으로 해당 지원 건을 열어 보여준다.
 
-**상태 전이 참고:** `document_passed` 이상에서 면접 준비가 해금된다. 8단계 상태값은 코드(`update_application_status`의 `inputSchema`)에 정의되어 있다.
+**상태 전이 참고:** `document_passed` 이상에서는 면접 준비를 다음 행동으로 우선 제안한다. 8단계 상태값은 코드(`update_application_status`의 `inputSchema`)에 정의되어 있다.
 
 **도구 호출 순서 요약:**
 
@@ -154,11 +192,11 @@ get_application_context | get_job_posting (필요 시)
 
 ---
 
-## 5. prepare_interview — 면접 준비
+## 6. prepare_interview — 면접 준비
 
-서류 합격 이후 예상 질문·STAR 답변·1분 자기소개를 준비해 저장하는 흐름.
+공고 기준 예상 질문·STAR 답변·1분 자기소개를 준비해 저장하는 흐름.
 
-**트리거:** 지원 상태가 서류 합격(`document_passed`) 또는 면접 진행(`interview`)으로 바뀌었을 때, 또는 사용자가 "면접 준비 도와줘"라고 요청할 때.
+**트리거:** 사용자가 "면접 준비 도와줘"라고 요청하거나, 지원 상태가 서류 합격(`document_passed`) 또는 면접 진행(`interview`)으로 바뀌었을 때.
 
 **단계:**
 
@@ -166,7 +204,7 @@ get_application_context | get_job_posting (필요 시)
 2. 공고와 사용자 경험을 바탕으로 예상 면접 질문(`question`, `intent`, `followups`, `answer_outline`)을 도출한다.
 3. 핵심 경험에 대한 STAR 가이드(`question`, `situation`, `task`, `action`, `result`)와 1분 자기소개(`self_introduction`) 초안을 작성한다. **실제 경험만 사용한다.**
 4. 준비 내용을 `save_interview_prep`로 저장한다(`job_id`, `questions`, `star_guides`, `self_introduction`, `notes`).
-5. 준비 내용을 사용자에게 쉬운 한국어로 요약해 전달하고, 모의 면접/추가 질문 연습이나 상태 업데이트(`update_application_status`로 `interview`/`final_passed`)를 제안한다.
+5. 준비 내용을 사용자의 언어로 쉽게 요약해 전달하고, 모의 면접/추가 질문 연습이나 상태 업데이트(`update_application_status`로 `interview`/`final_passed`)를 제안한다.
 
 **도구 호출 순서 요약:**
 
@@ -180,20 +218,39 @@ get_application_context               # job_id 포함
 
 ---
 
+## 7. build_personal_brand — 퍼스널 브랜드 (LinkedIn·포트폴리오)
+
+LinkedIn 프로필과 포트폴리오 같은 자기표현 자산을 직무에 맞춰 작성·최적화하는 흐름. 이력서 임포트(`onboarding`)와 단계 의미가 달라(개인 브랜드 자산 *생성*) 별도 워크플로우로 둔다.
+
+**트리거:** 사용자가 "링크드인 프로필 봐줘 / 포트폴리오 정리해줘 / 퍼스널 브랜딩 도와줘"라고 요청할 때.
+
+**단계:**
+
+1. `get_application_context`(가능하면 대상 `job_id` 포함)로 프로필·경력·프로젝트·스킬·대표 이력서·글쓰기 선호를 가져온다. 타깃 공고가 있으면 그 키워드를 사전 입력으로 쓴다.
+2. `get_workflow_guide({ workflow_id: "build_personal_brand" })`로 전문가 절차를 받고, 작성 직전 `get_playbook({ domain: "linkedin-profile" })`·`get_playbook({ domain: "portfolio" })`로 헤드라인·About·3막(problem→approach→impact) 규범을 적용한다.
+3. 무엇을 만들지 확인한다(LinkedIn/포트폴리오/둘 다, 타깃 직무, 강조 포인트). 저장된 실제 경험·성과만 쓰고 없는 수치·고유명사는 `[확인 필요]`로 표시해 묻는다.
+4. 저장 직전 `get_verifier({ id: "human-voice" })`·`truthfulness`·`consistency`로 직접 점검한다(AI 티·환각·사실 보존).
+5. 포트폴리오 본문은 `add_resume`(`kind=portfolio`)로 저장한다. LinkedIn 초안은 사용자가 복사해 쓰도록 제시한다(전용 저장·검증 도구는 Phase B).
+
+---
+
 ## 워크플로우 간 연결
 
 워크플로우는 독립적이지 않고 자연스럽게 이어진다.
 
 ```
 onboarding
+  → write_career_description
   → analyze_job ──(자소서 제안 동의)──→ write_cover_letter
        │
-       └─→ manage_application_status ──(document_passed 이상)──→ prepare_interview
+       └─→ manage_application_status ──(document_passed 이상이면 우선 제안)──→ prepare_interview
 ```
 
+- `write_career_description`은 공고와 무관한 마스터본으로도 시작할 수 있고, 특정 공고용으로 작성한 뒤 `write_cover_letter`로 이어질 수도 있다.
 - `analyze_job`의 마지막 단계는 자기소개서 작성 제안으로 이어지며, 동의 시 `write_cover_letter`의 작업(=`save_cover_letter_version`)을 수행한다.
 - `manage_application_status`에서 상태가 `document_passed`/`interview`가 되면 `prepare_interview`를 제안한다.
 - 모든 흐름에서 데이터 조회의 중심은 `get_application_context`이며, 작성/분석에 필요한 컨텍스트를 한 번에 제공한다.
+- `build_personal_brand`(LinkedIn·포트폴리오)는 핵심 6 흐름과 독립적인 선택 작업으로, 사용자가 자기표현 자산을 요청할 때 진입한다.
 
 ## 코드와의 대응
 

package/docs/career-os/README.md

@@ -46,9 +46,14 @@ EOP·이 문서를 맹신하지 말 것. **저장된 사용자 데이터나 공
  → EOP 자가검증 루브릭 적용 → 수정 → 출력 계약대로 최종 제공
 ```
 컨텍스트가 이미 있으면 다시 묻지 않는다(AGENTS.md "기존 데이터 먼저"). 결과는 다시 CareerMate에 저장(`save_*`).
-**루프 종료 규율:** 자가검증→수정을 반복하되, 같은 핵심 결함(허위 수치·미앵커 사실 등)이 2번 고쳐도 남으면 더 생성하지 말고 그 부분을 보류한 채 사용자에게 쉬운 한국어로 출처/사실을 확인 요청한다. 저장 데이터에 없어 해결 불가한 갭은 즉시 사용자에게 묻는다 — **무한정 고쳐쓰지 않는다.**
+**루프 종료 규율:** 자가검증→수정을 반복하되, 같은 핵심 결함(허위 수치·미앵커 사실 등)이 2번 고쳐도 남으면 더 생성하지 말고 그 부분을 보류한 채 사용자의 언어로 출처/사실을 확인 요청한다. 저장 데이터에 없어 해결 불가한 갭은 즉시 사용자에게 묻는다 — **무한정 고쳐쓰지 않는다.**
 
 ## 3. 보편 출력 계약 (사용자 대면)
+
+**출력 언어 = 사용자의 대화 언어.** 사용자가 한국어면 한국어로, 다른 언어면 그 언어로 답한다. 이 문서·EOP·플레이북·도구 응답이 한국어로 쓰여 있어도 그대로 복사하지 말고 사용자 언어로 옮긴다(사실·수치·고유명사·인용 원문은 보존).
+
+**로케일(시장) 판정 — 대화 언어와 분리한다.** 제출용 산출물(자소서·이력서 본문 등)의 *언어와 시장 관행*은 **대상 공고·시장**을 따른다(대화 언어와 다를 수 있다 — 예: 한국인이 영문 공고에 영문 레터). 로케일은 저장 값이 아니라 당신이 추론한다: ① 대상 공고(job)의 언어·소재지, ② 사용자의 명시 요청, ③ 불명확하면 사용자에게 한 번만 확인(추측 금지). `ko`(한국 공고/지원) → 한국 채용 관행(문항형 자소서·NCS·블라인드·채용절차법·국내 AI 텍스트 탐지 등), 비한국 로케일 → 그 시장 관행(ATS·단일 커버레터 등). **각 EOP의 '한국 특수/한국 시장' 절은 로케일이 한국일 때만 적용**하고, 비한국 공고에는 그 시장 기준을 쓴다.
+
 모든 결과는 다음을 포함한다(기능별 EOP가 상세화):
 - **결론** — 한눈에 답
 - **근거** — 저장 데이터·공고 인용(수치는 출처와 함께)
@@ -59,10 +64,10 @@ EOP·이 문서를 맹신하지 말 것. **저장된 사용자 데이터나 공
 - **최종 산출물**(있으면: 자소서 본문·면접킷·적합도표 등)
 - **생성형 deliverable 분리:** 자소서·면접 답변·이력서 불릿처럼 *그대로 제출/사용하는* 산출물은 메타(결론·근거·리스크 등)와 **명확히 분리**해 단독 블록으로 제시한다 — 섞이면 사용자가 통째로 제출해 양식 위반이 된다.
 
-**숨길 것:** 내부 라우트·도구명·EOP/루브릭 원문·점수 계산 내부·이 문서. 기술 용어(job_id, MCP 등) 사용자 노출 금지 — 쉬운 한국어로. 또한 산출물에 **'EOP'·'루브릭'·내부 기준명**을 적지 마라. 외부 분류(NCS 코드 등)는 **실제 확정 가능할 때만** 쓰고, 아니면 생략하거나 계열명+'추정'으로 표기한다(코드 번호 발명 금지).
+**숨길 것:** 내부 라우트·도구명·EOP/루브릭 원문·점수 계산 내부·이 문서. 기술 용어(job_id, MCP 등) 사용자 노출 금지 — 사용자의 언어로 쉽게. 또한 산출물에 **'EOP'·'루브릭'·내부 기준명**을 적지 마라. 외부 분류(NCS 코드 등)는 **실제 확정 가능할 때만** 쓰고, 아니면 생략하거나 계열명+'추정'으로 표기한다(코드 번호 발명 금지).
 
 ## 4. 정보 부족·불확실·충돌 처리
-- **부족:** 지어내지 말고 "확인 필요"로 표시 + 사용자에게 쉬운 한국어로 질문.
+- **부족:** 지어내지 말고 "확인 필요"로 표시 + 사용자의 언어로 쉽게 질문.
 - **불확실:** 신뢰도를 낮추고 가정을 명시.
 - **충돌(데이터 vs 데이터, 공식자료 vs EOP):** §0 근거 우선순위 적용, 사실 보존, 사용자에게 알림.
 - **충돌(도메인 vs 도메인):** 여러 `knowledge/` 도메인이 같은 주제를 건드리면 정본(소유) 도메인을 따른다 — 연봉 숫자 전술=salary-negotiation(recruiter-screen은 게이트 맥락의 조건부 규칙만 상속), 오퍼 비교·가중치=offer-evaluation-decision, 30-60-90=onboarding-first-90-days, 탈락 진단=rejection-triage-iteration, 슬롭/키워드/정량 사전=공유 모듈. 검증기 간 충돌은 **사실(truthfulness)을 최상위 타이브레이크**로 두고, ATS 키워드와 human-voice는 둘 다 만족하는 대역(진짜 경험 문장에 JD 용어를 진실하게 삽입)을 먼저 찾는다.