careermate 0.0.3 → 0.0.5

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

@@ -15,9 +15,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {
   ProfileInputSchema,
-  ExperienceInputSchema,
-  ProjectInputSchema,
-  SkillInputSchema,
+  ExperienceBatchInputSchema,
+  ProjectBatchInputSchema,
+  SkillBatchInputSchema,
   JobInputSchema,
   FitAnalysisInputSchema,
   CoverLetterVersionInputSchema,
@@ -50,9 +50,9 @@ import {
   getApplicationContext,
   saveProfile,
   addResume,
-  addExperience,
-  addProject,
-  addSkill,
+  addExperiences,
+  addProjects,
+  addSkills,
   saveJobPosting,
   saveFitAnalysis,
   saveCoverLetterVersion,
@@ -82,6 +82,8 @@ import { resolveDashboardUrl, openInBrowser, openInFileManager } from './bridge.
 import { getUpdateStatus, getUpdateStatusAsync, runSelfUpdate } from './update.ts';
 
 const STATUS_LIST = APPLICATION_STATUSES.map((s) => `${s}(${APPLICATION_STATUS_LABELS[s]})`).join(', ');
+const DELETE_CONFIRMATION = 'DELETE';
+const DASHBOARD_URL = 'http://127.0.0.1:4319';
 
 /** List real, user-dropped files in the inbox (skips hidden/OS/office-lock cruft). */
 function listInboxFiles(dir: string): { name: string; path: string }[] {
@@ -278,9 +280,19 @@ export const TOOLS: ToolDef[] = [
           `더 깐깐하게 보길 원하면 "엄격하게 봐줘"라고 하거나 대시보드 설정에서 엄격 모드를 켤 수 있어요(이력서 본문에 없는 수치까지 차단).`;
       }
       if (upd.update_available) {
-        text += `\n\n🆕 새 버전 v${upd.latest} 사용 가능 (현재 v${upd.current}). 사용자가 원하면 update_careermate 도구로 업데이트하세요.`;
+        text += `\n\n새 버전 v${upd.latest}이 나왔습니다(현재 v${upd.current}). 사용자가 원하면 바로 업데이트를 진행하세요. 업데이트 후에는 AI 앱 또는 MCP 연결을 재시작해야 적용됩니다.`;
       }
-      return ok(text, { ...s, verify_strict: strict, update: upd });
+      return ok(text, {
+        ...s,
+        verify_strict: strict,
+        update: upd,
+        suggested_next_action: upd.update_available
+          ? {
+              prompt: `새 버전 v${upd.latest}이 나왔습니다. 지금 업데이트할까요?`,
+              next_tool: 'update_careermate',
+            }
+          : null,
+      });
     },
   },
 
@@ -343,11 +355,12 @@ export const TOOLS: ToolDef[] = [
     name: 'add_experience',
     title: '경력 추가',
     description:
-      '구조화된 경력(직장 단위)을 별도 항목으로 저장합니다. 이력서 본문(add_resume)과 달리, 회사·직무·기간·성과를 필드로 나눠 저장해 적합도 분석/자소서 작성 시 정밀하게 활용됩니다. company는 필수이며, achievements에는 정량 지표가 담긴 성과를, tech에는 사용 기술을 배열로 넣으세요. 온보딩 완성도(get_onboarding_status)의 has_experience를 채우려면 이 도구로 1건 이상 추가해야 합니다.',
-    inputSchema: ExperienceInputSchema.shape,
+      '구조화된 경력(직장 단위)을 저장합니다. 이력서에서 파악한 경력을 experiences 배열에 한 번에 담아 호출하세요(한 건이어도 배열로 — 항목마다 도구를 반복 호출하지 마세요). 이력서 본문(add_resume)과 달리 회사·직무·기간·성과를 필드로 나눠 저장해 적합도 분석/자소서 작성 시 정밀하게 활용됩니다. 각 항목은 company가 필수이며, achievements에는 정량 지표가 담긴 성과를, tech에는 사용 기술을 배열로 넣으세요. 같은 회사·직무·입사일(start_date)이 일치하면 갱신되고 중복 생성되지 않으니 여러 번 저장해도 안전합니다. 온보딩 완성도(get_onboarding_status)의 has_experience를 채우려면 1건 이상 추가하세요.',
+    inputSchema: ExperienceBatchInputSchema.shape,
     handler: (args) => {
-      const exp = addExperience(args);
-      return ok(`경력 '${exp.company}${exp.role ? ` · ${exp.role}` : ''}'을(를) 추가했습니다.`, exp);
+      const { records, created, updated } = addExperiences(args.experiences);
+      const names = records.map((e) => `${e.company}${e.role ? ` · ${e.role}` : ''}`).join(', ');
+      return ok(`경력 ${records.length}건을 저장했습니다 (신규 ${created} · 갱신 ${updated}): ${names}`, records);
     },
   },
   {
@@ -367,11 +380,12 @@ export const TOOLS: ToolDef[] = [
     name: 'add_project',
     title: '프로젝트 추가',
     description:
-      '대표 프로젝트를 별도 항목으로 저장합니다. name은 필수이며, highlights(핵심 성과)와 tech(사용 기술)를 배열로 넣으면 자소서·면접 준비에서 근거로 활용됩니다. url에 결과물 링크를 넣을 수 있습니다.',
-    inputSchema: ProjectInputSchema.shape,
+      '대표 프로젝트를 저장합니다. projects 배열에 여러 개를 한 번에 담아 호출하세요(한 개여도 배열로 — 항목마다 반복 호출하지 마세요). 각 항목은 name이 필수이며, highlights(핵심 성과)와 tech(사용 기술)를 배열로 넣으면 자소서·면접 준비에서 근거로 활용됩니다. url에 결과물 링크를 넣을 수 있습니다. 같은 이름의 프로젝트는 갱신되고 중복 생성되지 않으니 여러 번 저장해도 안전합니다.',
+    inputSchema: ProjectBatchInputSchema.shape,
     handler: (args) => {
-      const prj = addProject(args);
-      return ok(`프로젝트 '${prj.name}'을(를) 추가했습니다.`, prj);
+      const { records, created, updated } = addProjects(args.projects);
+      const names = records.map((p) => p.name).join(', ');
+      return ok(`프로젝트 ${records.length}건을 저장했습니다 (신규 ${created} · 갱신 ${updated}): ${names}`, records);
     },
   },
   {
@@ -391,11 +405,12 @@ export const TOOLS: ToolDef[] = [
     name: 'add_skill',
     title: '기술스택 추가',
     description:
-      '보유 기술스택을 별도 항목으로 저장합니다. name은 필수이며, category(언어/프레임워크/툴/소프트스킬 등)·level·years로 숙련도를 함께 기록하면 공고 키워드 매칭이 정확해집니다. 온보딩 완성도의 has_skills를 채우려면 이 도구로 1건 이상 추가해야 합니다. 여러 개면 도구를 반복 호출하세요.',
-    inputSchema: SkillInputSchema.shape,
+      '보유 기술스택을 저장합니다. 여러 개를 skills 배열에 한 번에 담아 호출하세요(한 개여도 배열로 — 기술마다 도구를 반복 호출하지 마세요). 각 항목은 name이 필수이며, category(언어/프레임워크/툴/소프트스킬 등)·level·years로 숙련도를 함께 기록하면 공고 키워드 매칭이 정확해집니다. 같은 이름의 기술은 갱신되고 중복 생성되지 않으니 여러 번 저장해도 안전합니다. 온보딩 완성도의 has_skills를 채우려면 1개 이상 추가하세요.',
+    inputSchema: SkillBatchInputSchema.shape,
     handler: (args) => {
-      const skill = addSkill(args);
-      return ok(`기술 '${skill.name}'을(를) 추가했습니다.`, skill);
+      const { records, created, updated } = addSkills(args.skills);
+      const names = records.map((s) => s.name).join(', ');
+      return ok(`기술 ${records.length}개를 저장했습니다 (신규 ${created} · 갱신 ${updated}): ${names}`, records);
     },
   },
   {
@@ -448,6 +463,32 @@ export const TOOLS: ToolDef[] = [
       }
     },
   },
+  {
+    name: 'delete_cover_letter',
+    title: '자기소개서 삭제',
+    description:
+      '사용자가 저장된 자기소개서 삭제를 명확히 요청했을 때만 사용합니다. 먼저 get_cover_letters로 전체 목록 또는 공고별 목록을 확인하고, 삭제할 항목을 사용자가 확인한 뒤 호출하세요. 삭제하면 해당 자기소개서의 모든 버전이 함께 삭제되며 되돌릴 수 없습니다. confirm에는 DELETE를 넣으세요.',
+    inputSchema: {
+      cover_letter_id: z.string(),
+      confirm: z.string().describe('삭제 확인값. 정확히 DELETE를 넣어야 삭제됩니다.'),
+    },
+    handler: (args) => {
+      if (args?.confirm !== DELETE_CONFIRMATION) {
+        return fail('삭제하려면 confirm에 DELETE를 넣어 다시 호출하세요.');
+      }
+      const cl = coverLetterRepo.get(args.cover_letter_id, false);
+      if (!cl) return fail('자기소개서를 찾을 수 없습니다.');
+      const removed = coverLetterRepo.remove(cl.id);
+      if (!removed) return fail('자기소개서를 삭제하지 못했습니다.');
+      const user_message = `'${cl.title}' 자기소개서를 삭제했어요. 연결된 지원 기록에서는 자기소개서 연결만 비워뒀습니다.`;
+      return ok(user_message, {
+        deleted: true,
+        cover_letter_id: cl.id,
+        title: cl.title,
+        user_message,
+      });
+    },
+  },
 
   /* ------------------------------------------------------------------ jobs */
   {
@@ -458,7 +499,15 @@ export const TOOLS: ToolDef[] = [
     inputSchema: JobInputSchema.shape,
     handler: (args) => {
       const { job } = saveJobPosting(args);
-      return ok(`'${job.company} · ${job.position}' 공고를 저장했습니다. (job_id: ${job.id})`, job);
+      const user_message = `'${job.company} · ${job.position}' 공고를 저장했어요.`;
+      return ok(user_message, {
+        ...job,
+        user_message,
+        suggested_next_action: {
+          prompt: '이 공고와 내 프로필을 비교해 적합도를 분석할까요?',
+          next_workflow: 'analyze_job',
+        },
+      });
     },
   },
   {
@@ -469,7 +518,7 @@ export const TOOLS: ToolDef[] = [
     readOnly: true,
     handler: (args) => {
       const job = jobRepo.get(args.job_id);
-      if (!job) return fail(`공고를 찾을 수 없습니다: ${args.job_id}`);
+      if (!job) return fail('공고를 찾을 수 없습니다.');
       return ok(`${job.company} · ${job.position}`, {
         job: jobWithMeta(job),
         fit: fitRepo.getByJob(job.id),
@@ -490,6 +539,38 @@ export const TOOLS: ToolDef[] = [
       return ok(`공고 ${jobs.length}건`, jobs);
     },
   },
+  {
+    name: 'delete_job_posting',
+    title: '채용공고 삭제',
+    description:
+      '사용자가 저장된 채용공고 삭제를 명확히 요청했을 때만 사용합니다. 먼저 list_jobs로 전체 공고 목록을 확인하고, 삭제할 공고를 사용자가 확인한 뒤 호출하세요. 삭제하면 연결된 지원 상태·적합도 분석·면접 준비가 함께 삭제됩니다. 연결된 자기소개서는 삭제하지 않고 공고 연결만 해제합니다. confirm에는 DELETE를 넣으세요.',
+    inputSchema: {
+      job_id: z.string(),
+      confirm: z.string().describe('삭제 확인값. 정확히 DELETE를 넣어야 삭제됩니다.'),
+    },
+    handler: (args) => {
+      if (args?.confirm !== DELETE_CONFIRMATION) {
+        return fail('삭제하려면 confirm에 DELETE를 넣어 다시 호출하세요.');
+      }
+      const job = jobRepo.get(args.job_id);
+      if (!job) return fail('공고를 찾을 수 없습니다.');
+      const detachedCoverLetters = coverLetterRepo.listByJob(job.id).length;
+      const removed = jobRepo.remove(job.id);
+      if (!removed) return fail('공고를 삭제하지 못했습니다.');
+      const detachedNote = detachedCoverLetters
+        ? ` 연결된 자기소개서 ${detachedCoverLetters}건은 삭제하지 않고 공고 연결만 해제했습니다.`
+        : '';
+      const user_message = `'${job.company} · ${job.position}' 공고를 삭제했어요. 연결된 지원 상태, 적합도 분석, 면접 준비도 함께 정리했습니다.${detachedNote}`;
+      return ok(user_message, {
+        deleted: true,
+        job_id: job.id,
+        company: job.company,
+        position: job.position,
+        detached_cover_letters: detachedCoverLetters,
+        user_message,
+      });
+    },
+  },
 
   /* ----------------------------------------------------- application context */
   {
@@ -517,8 +598,8 @@ export const TOOLS: ToolDef[] = [
         ctx.job ? `대상 공고: ${ctx.job.company} · ${ctx.job.position}` : '대상 공고 없음',
         ctx.writing_preferences.preferred_tone ? `선호 문체: ${ctx.writing_preferences.preferred_tone}` : '',
         recommended_route
-          ? `💡 다음 단계: get_workflow_guide({ workflow_id: "${recommended_route}" })로 전문가 실행 절차(EOP)와 적용할 플레이북·검증 순서를 받아 적용하세요(즉답 금지).`
-          : '💡 커리어 작업을 시작하려면 get_workflow_guide로 전문가 실행 절차와 검증 순서를 먼저 받으세요.',
+          ? `내부 안내: 사용자에게는 도구명이나 ID를 말하지 말고, 먼저 get_workflow_guide({ workflow_id: "${recommended_route}" })로 실행 절차와 검증 순서를 받은 뒤 쉬운 말로 안내하세요.`
+          : '내부 안내: 사용자에게는 도구명을 말하지 말고, 먼저 get_workflow_guide로 실행 절차와 검증 순서를 받은 뒤 쉬운 말로 안내하세요.',
       ].filter(Boolean).join('\n');
       return ok(summary, enriched);
     },
@@ -532,7 +613,34 @@ export const TOOLS: ToolDef[] = [
     handler: (args) => {
       try {
         const fit = saveFitAnalysis(args);
-        return ok(`적합도 분석을 저장했습니다${fit.score != null ? ` (${fit.score}점)` : ''}.`, fit);
+        const suggested_next_action = {
+          prompt: '이 공고에 맞춘 자기소개서를 써드릴까요?',
+          options: [
+            {
+              label: '네, 이 공고에 맞춘 자기소개서를 써줘',
+              next_workflow: 'write_cover_letter',
+            },
+            {
+              label: '아니요, 분석만 저장해줘',
+              next_workflow: null,
+            },
+          ],
+        };
+        const user_message = `적합도 분석을 저장했어요${fit.score != null ? ` (${fit.score}점)` : ''}. 자세한 결과는 대시보드에서도 확인할 수 있습니다: ${DASHBOARD_URL}`;
+        return ok(
+          [
+            user_message,
+            '',
+            '사용자에게 다음 선택지를 보여주세요:',
+            '1. 네, 이 공고에 맞춘 자기소개서를 써줘',
+            '2. 아니요, 분석만 저장해줘',
+          ].join('\n'),
+          {
+            ...fit,
+            user_message,
+            suggested_next_action,
+          },
+        );
       } catch (e) {
         return fail(e instanceof Error ? e.message : '저장 실패');
       }
@@ -552,9 +660,21 @@ export const TOOLS: ToolDef[] = [
     handler: (args) => {
       try {
         const res = updateApplicationStatus(args.job_id, args.status, args.note);
+        const user_message =
+          `지원 상태를 '${APPLICATION_STATUS_LABELS[args.status as keyof typeof APPLICATION_STATUS_LABELS]}'(으)로 바꿨어요.` +
+          (res.hint ? `\n\n${res.hint}` : '');
         return ok(
-          `상태를 '${APPLICATION_STATUS_LABELS[args.status as keyof typeof APPLICATION_STATUS_LABELS]}'(으)로 변경했습니다.${res.hint ? `\n\n💡 ${res.hint}` : ''}`,
-          res,
+          user_message,
+          {
+            ...res,
+            user_message,
+            suggested_next_action: res.hint
+              ? {
+                  prompt: res.hint,
+                  next_workflow: 'prepare_interview',
+                }
+              : null,
+          },
         );
       } catch (e) {
         return fail(e instanceof Error ? e.message : '변경 실패');
@@ -572,7 +692,8 @@ export const TOOLS: ToolDef[] = [
     handler: (args) => {
       try {
         const prep = saveInterviewPrep(args);
-        return ok(`면접 준비 자료를 저장했습니다 (질문 ${prep.questions.length}개).`, prep);
+        const user_message = `면접 준비 자료를 저장했어요. 예상 질문 ${prep.questions.length}개가 준비되어 있습니다.`;
+        return ok(user_message, { ...prep, user_message });
       } catch (e) {
         return fail(e instanceof Error ? e.message : '저장 실패');
       }
@@ -789,17 +910,27 @@ export const TOOLS: ToolDef[] = [
     name: 'check_for_update',
     title: '업데이트 확인',
     description:
-      'CareerMate에 새 버전이 있는지 npm 레지스트리에서 지금 확인합니다(공개 버전 정보만 GET하며 사용자 데이터는 전송하지 않습니다). 현재 버전·최신 버전·업데이트 가능 여부를 돌려줍니다. 사용자가 "최신이야?/업데이트 있어?"라고 묻거나, get_onboarding_status가 새 버전을 알릴 때 호출하세요. 실제 적용은 update_careermate로 합니다.',
+      'CareerMate에 새 버전이 있는지 npm 레지스트리에서 지금 확인합니다(공개 버전 정보만 GET하며 사용자 데이터는 전송하지 않습니다). 현재 버전·최신 버전·업데이트 가능 여부를 돌려줍니다. 사용자가 "최신이야?/업데이트 있어?"라고 묻거나, get_onboarding_status가 새 버전을 알릴 때 호출하세요. 확인만 하고 설치는 하지 않습니다. 사용자가 "업데이트해줘/최신으로 올려줘"처럼 명시적으로 요청하면 update_careermate를 호출하세요.',
     inputSchema: {},
     readOnly: true,
     handler: async () => {
       const u = await getUpdateStatusAsync();
       if (u.latest === null) return ok('업데이트 확인에 실패했습니다(오프라인이거나 일시적 오류). 잠시 후 다시 시도하세요.', u);
+      const user_message = u.update_available
+        ? `새 버전 v${u.latest}이 나왔어요. 현재 버전은 v${u.current}입니다. 원하시면 지금 업데이트할 수 있습니다.`
+        : `최신 버전입니다 (v${u.current}).`;
       return ok(
-        u.update_available
-          ? `새 버전 v${u.latest} 사용 가능 (현재 v${u.current}). update_careermate로 업데이트할 수 있습니다.`
-          : `최신 버전입니다 (v${u.current}).`,
-        u,
+        user_message,
+        {
+          ...u,
+          user_message,
+          suggested_next_action: u.update_available
+            ? {
+                prompt: '지금 CareerMate를 업데이트할까요?',
+                next_tool: 'update_careermate',
+              }
+            : null,
+        },
       );
     },
   },
@@ -807,12 +938,12 @@ export const TOOLS: ToolDef[] = [
     name: 'update_careermate',
     title: 'CareerMate 업데이트',
     description:
-      'CareerMate를 최신 버전으로 업데이트합니다(설치 폴더에 npm으로 careermate@latest 설치). 사용자가 명시적으로 "업데이트해줘"라고 할 때만 호출하세요. 성공하면 적용을 위해 AI 앱(또는 MCP 연결) 재시작이 필요하며, 재시작 시 데이터베이스는 자동 마이그레이션되어 기존 데이터가 보존됩니다. 자동 설치가 막히면(개발 모드·비표준 설치) 직접 칠 명령을 안내합니다.',
+      'CareerMate를 최신 버전으로 업데이트합니다(설치 폴더에 npm으로 careermate@latest 설치). 사용자가 명시적으로 "업데이트해줘", "CareerMate 업데이트해줘", "최신으로 올려줘"라고 할 때 호출하세요. 이 도구가 최신 버전 확인도 함께 하므로 별도 확인 질문 없이 실행해도 됩니다. 성공하면 적용을 위해 AI 앱(또는 MCP 연결) 재시작이 필요하며, 재시작 시 데이터베이스는 자동 마이그레이션되어 기존 데이터는 보존됩니다. 자동 설치가 막히면(개발 모드·비표준 설치) 직접 칠 명령을 안내합니다.',
     inputSchema: {},
     handler: async () => {
       const r = await runSelfUpdate();
       if (!r.ok) return fail(`${r.message}${r.manual ? `\n\n직접 실행: ${r.manual}` : ''}`);
-      return ok(r.message, r);
+      return ok(r.message, { ...r, user_message: r.message });
     },
   },
 ];

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

@@ -325,6 +325,6 @@ export async function runSelfUpdate(): Promise<UpdateResult> {
     ok: true,
     from,
     to: latest,
-    message: `careermate를 ${latest ? `v${latest}` : '최신 버전'}(으)로 업데이트했습니다. 적용하려면 AI 앱(또는 MCP 연결)을 재시작하세요. 재시작 시 데이터베이스는 자동으로 마이그레이션되며 기존 데이터는 보존됩니다.`,
+    message: `CareerMate를 ${latest ? `v${latest}` : '최신 버전'}(으)로 업데이트했습니다. 적용하려면 AI 앱(또는 MCP 연결)을 재시작하세요. 재시작 시 데이터베이스는 자동으로 마이그레이션되며 기존 데이터는 보존됩니다.`,
   };
 }

package/packages/prompts/src/onboarding.ts

@@ -17,7 +17,7 @@ export const ONBOARDING_PROMPT = `이제 CareerMate에 연결되었습니다.
 - 이름, 연락처, 한 줄 소개(headline), 자기소개 요약(summary), 희망 직무(desired_roles), 희망 근무 조건(desired_conditions)을 정리합니다.
 - 글쓰기 선호도 함께 물어보세요: 선호 문체(preferred_tone, 예: "담백하고 구체적")와 강조하고 싶은 핵심 포인트(emphasis_points). 이 정보는 이후 자기소개서 작성에 그대로 활용됩니다.
 - 정리한 내용을 \`save_profile\`로 저장하세요. 파일에서 읽어온 정보는 source를 'upload', 사용자가 말로 알려준 정보는 'manual'로 표시하세요.
-- 경력·프로젝트·스킬 정보가 있으면 \`add_experience\`·\`add_project\`·\`add_skill\`로 각각 저장하세요(경력 achievements는 가능하면 정량 지표 포함). 이 항목들은 온보딩 완성도(has_experience/has_skills)에 반영됩니다.
+- 경력·프로젝트·스킬 정보가 있으면 \`add_experience\`·\`add_project\`·\`add_skill\`로 저장하세요. 각 도구는 배열을 받으니 파악한 항목을 한 번에 모아 넘기세요(항목마다 반복 호출하지 마세요). 같은 항목을 다시 넣어도 중복 없이 갱신됩니다(경력 achievements는 가능하면 정량 지표 포함). 이 항목들은 온보딩 완성도(has_experience/has_skills)에 반영됩니다.
 - 확실하지 않은 정보는 지어내지 말고 사용자에게 확인하세요.
 
 # 3단계 — 이력서 등록

package/packages/prompts/src/system.ts

@@ -37,17 +37,25 @@ CareerMate는 사용자의 컴퓨터에서 동작하는 로컬 커리어 관리
 
 6. 사용자에게는 쉬운 한국어로 알립니다.
    - "MCP", "툴 호출", "job_id" 같은 기술 용어는 사용자에게 직접 노출하지 마세요. "공고를 저장했어요", "적합도를 분석했어요"처럼 일상적인 표현으로 진행 상황을 알리세요.
+   - 도구 응답에 \`user_message\`가 있으면 사용자에게 보고할 때 그 문장을 우선 활용하세요. \`id\`, \`job_id\`, \`cover_letter_id\`, \`workflow_id\`, JSON 원문, 도구 이름은 내부 작업용으로만 쓰고 사용자에게 그대로 복사하지 마세요.
+   - 도구 응답에 \`suggested_next_action\`이 있으면 다음 행동을 강요하지 말고 선택지로 제안하세요.
    - 무엇을 했고, 무엇을 알게 되었고, 다음에 무엇을 할 수 있는지 짧고 명확하게 전달하세요.
 
 7. 다음 단계를 먼저 제안합니다.
    - 작업이 끝나면 자연스러운 다음 행동을 제안하세요. 예: 공고 분석 후 → "이 공고에 맞춘 자기소개서를 써드릴까요?", 자기소개서 저장 후 → "지원 상태를 '지원 완료'로 바꿀까요?", 상태가 '서류 합격'이 되면 → "면접 준비를 도와드릴까요?".
+   - 공고 분석 후에는 곧장 자기소개서를 쓰지 말고, 반드시 선택지를 보여주세요: "1. 네, 이 공고에 맞춘 자기소개서를 써줘" / "2. 아니요, 분석만 저장해줘". 사용자가 1번을 고른 경우에만 자기소개서 작성 흐름으로 이어갑니다.
    - \`get_onboarding_status\`의 next_steps나 \`open_dashboard\`/\`open_application\`을 활용해 사용자를 다음 행동으로 안내하세요.
 
-8. 글은 AI 티 안 나게 씁니다.
+8. 업데이트 요청은 명확하게 처리합니다.
+   - 사용자가 "최신이야?", "업데이트 있어?"처럼 확인만 요청하면 \`check_for_update\`를 호출하고 결과를 쉬운 말로 알려주세요.
+   - 사용자가 "업데이트해줘", "CareerMate 업데이트해줘", "최신으로 올려줘"처럼 적용을 명시하면 \`update_careermate\`를 바로 호출하세요. 이 도구가 최신 버전 확인도 함께 합니다.
+   - 업데이트 성공 후에는 적용하려면 AI 앱 또는 MCP 연결을 재시작해야 한다고 안내하세요. 사용자 커리어 데이터는 로컬에 보존되고, npm에는 공개 버전 정보 확인/설치 요청만 나갑니다.
+
+9. 글은 AI 티 안 나게 씁니다.
    - 자기소개서·자기 PR·지원 메일 등 사람이 쓴 듯한 글을 작성하기 직전에는 \`get_writing_style_guide\`를 호출해 글쓰기 규칙을 가져오고 그대로 적용하세요.
    - 번역투, "열정을 가지고/귀사의 발전에 기여" 같은 클리셰, 기계적 병렬(첫째·둘째·셋째), 상투적 연결어, 균일한 문장 리듬을 피하고 담백하고 구체적으로 씁니다. 단, 사실·수치·고유명사는 절대 바꾸거나 지어내지 않습니다.
 
-9. 전문가 절차로 만들고, 저장 전 당신이 자가검증합니다.
+10. 전문가 절차로 만들고, 저장 전 당신이 자가검증합니다.
    - 공고 분석·자소서·면접 자료처럼 사용자 대면 결과를 만들기 전에는, 즉답하지 말고 \`get_workflow_guide\`(workflow_id 지정)를 먼저 호출해 그 작업의 전문가 실행 절차(EOP)와 적용할 플레이북·검증기 순서를 받으세요. 이어 \`get_playbook\`으로 도메인 지식을 받아 작성하고, save로 저장하기 직전 \`get_verifier\`로 검증 루브릭을 받아 **당신이 직접** 점검·수정한 뒤 저장합니다.
    - CareerMate는 슬롭 밀도·키워드 매칭처럼 셀 수 있는 항목만 보조로 돕고, 의미 판단(이 글이 질문에 답하는가·톤이 맞는가)은 당신이 합니다. 사실·수치·고유명사는 그대로 보존합니다.
 

package/packages/shared/src/enums.ts

@@ -6,6 +6,7 @@
  * Korean because the primary audience is Korean job seekers; codes are stable
  * machine values that must never change once persisted.
  */
+import { conflict } from './errors.ts';
 
 /** Application lifecycle. Drives the Applications board in the dashboard. */
 export const APPLICATION_STATUSES = [
@@ -84,8 +85,12 @@ export function canTransitionStatus(from: ApplicationStatus, to: ApplicationStat
 /** Throw a clear, user-facing (Korean) error when a status transition is not allowed. */
 export function assertStatusTransition(from: ApplicationStatus, to: ApplicationStatus): void {
   if (!canTransitionStatus(from, to)) {
-    throw new Error(
-      `'${APPLICATION_STATUS_LABELS[from]}'에서 '${APPLICATION_STATUS_LABELS[to]}'(으)로는 상태를 바꿀 수 없습니다.`,
+    const suffix =
+      to === 'draft'
+        ? ` ('${APPLICATION_STATUS_LABELS[from]}' 단계의 지원은 작성 중(미추적)으로 되돌릴 수 없습니다. 초기 단계로 옮기려면 '지원 예정'을 선택하세요.)`
+        : '';
+    throw conflict(
+      `'${APPLICATION_STATUS_LABELS[from]}'에서 '${APPLICATION_STATUS_LABELS[to]}'(으)로는 상태를 바꿀 수 없습니다.${suffix}`,
     );
   }
 }

package/packages/shared/src/errors.ts

@@ -0,0 +1,33 @@
+/**
+ * Domain errors whose message is written as user-facing Korean guidance.
+ *
+ * The split matters at the HTTP boundary: an *expected* domain failure (공고 없음,
+ * 금지된 상태 전환, 저장 게이트 차단 …) should reach the dashboard with its real
+ * message and an accurate status code, exactly like the MCP layer already relays
+ * `e.message` via `fail(...)`. An *unexpected* internal error (a SQLite fault, a
+ * bug) must stay an opaque 500 so we never leak internals. Plain `Error` can't be
+ * told apart from the latter, so user-facing failures throw `CareerMateError` and
+ * the HTTP layer maps only those to `httpStatus` + message.
+ */
+export class CareerMateError extends Error {
+  constructor(
+    message: string,
+    /** HTTP status the dashboard should return (404 not-found, 409 conflict, 400 validation). */
+    readonly httpStatus = 400,
+    /** Optional machine-readable code for the client. */
+    readonly code?: string,
+  ) {
+    super(message);
+    this.name = 'CareerMateError';
+  }
+}
+
+/** The requested record does not exist (HTTP 404). */
+export function notFound(message: string): CareerMateError {
+  return new CareerMateError(message, 404, 'not_found');
+}
+
+/** The action conflicts with the record's current lifecycle state (HTTP 409). */
+export function conflict(message: string): CareerMateError {
+  return new CareerMateError(message, 409, 'conflict');
+}

package/packages/shared/src/index.ts

@@ -4,6 +4,7 @@
  */
 export * from './enums.ts';
 export * from './schemas.ts';
+export * from './errors.ts';
 export { APP_VERSION, BUNDLED } from './build-info.ts';
 
 /** Short, URL-safe, sortable-ish id. Avoids a uuid dependency. */

package/packages/shared/src/schemas.ts

@@ -72,8 +72,32 @@ const reqBody = z
   .string()
   .max(MAX_BODY)
   .refine((s) => s.trim().length > 0, { message: EMPTY_MSG });
-/** Bounded array of bounded strings. */
-const strList = z.array(z.string().max(MAX_ITEM)).max(MAX_ITEMS);
+/**
+ * Coerce a stray scalar into a string array. MCP/LLM clients routinely serialize
+ * array arguments as a *string* — a JSON-encoded array (`'["Java","Spring"]'`) or
+ * a comma/newline-separated list (`'Java, Spring'`) — instead of a real array. The
+ * SDK then rejects the whole tool call with "Expected array, received string", so
+ * a single mis-serialized field (keywords, requirements, strengths, tech, tags…)
+ * fails the entire save. Absorb those shapes here; real arrays and non-strings
+ * pass straight through. The emitted JSON schema still advertises `array`, so the
+ * client is still told the correct shape — this only rescues the cases it ignores.
+ */
+function toStrList(v: unknown): unknown {
+  if (typeof v !== 'string') return v;
+  const s = v.trim();
+  if (!s) return [];
+  if (s.startsWith('[')) {
+    try {
+      const parsed = JSON.parse(s);
+      if (Array.isArray(parsed)) return parsed;
+    } catch {
+      /* not valid JSON — fall through to delimiter split */
+    }
+  }
+  return s.split(/[\n,]/).map((x) => x.trim()).filter(Boolean);
+}
+/** Bounded array of bounded strings; tolerant of stringified inputs (see toStrList). */
+const strList = z.preprocess(toStrList, z.array(z.string().max(MAX_ITEM)).max(MAX_ITEMS));
 
 const baseRecord = {
   id,
@@ -151,6 +175,16 @@ export const ExperienceRecordSchema = z.object({
 });
 export type ExperienceRecord = z.infer<typeof ExperienceRecordSchema>;
 
+/** Batch input: add several experiences in one MCP call (one item → array of one). */
+export const ExperienceBatchInputSchema = z.object({
+  experiences: z
+    .array(ExperienceInputSchema)
+    .min(1)
+    .max(MAX_ITEMS)
+    .describe('추가할 경력 목록(한 건이어도 배열로). 같은 회사·직무·입사일은 갱신되고 중복 생성되지 않습니다.'),
+});
+export type ExperienceBatchInput = z.infer<typeof ExperienceBatchInputSchema>;
+
 /* ------------------------------------------------------------------ Project */
 
 export const ProjectInputSchema = z.object({
@@ -180,6 +214,16 @@ export const ProjectRecordSchema = z.object({
 });
 export type ProjectRecord = z.infer<typeof ProjectRecordSchema>;
 
+/** Batch input: add several projects in one MCP call (one item → array of one). */
+export const ProjectBatchInputSchema = z.object({
+  projects: z
+    .array(ProjectInputSchema)
+    .min(1)
+    .max(MAX_ITEMS)
+    .describe('추가할 프로젝트 목록(한 개여도 배열로). 같은 이름의 프로젝트는 갱신되고 중복 생성되지 않습니다.'),
+});
+export type ProjectBatchInput = z.infer<typeof ProjectBatchInputSchema>;
+
 /* -------------------------------------------------------------------- Skill */
 
 export const SkillInputSchema = z.object({
@@ -201,6 +245,16 @@ export const SkillRecordSchema = z.object({
 });
 export type SkillRecord = z.infer<typeof SkillRecordSchema>;
 
+/** Batch input: add several skills in one MCP call (one item → array of one). */
+export const SkillBatchInputSchema = z.object({
+  skills: z
+    .array(SkillInputSchema)
+    .min(1)
+    .max(MAX_ITEMS)
+    .describe('추가할 기술스택 목록(한 개여도 배열로). 같은 이름의 기술은 갱신되고 중복 생성되지 않습니다.'),
+});
+export type SkillBatchInput = z.infer<typeof SkillBatchInputSchema>;
+
 /* ----------------------------------------------------------------- Document */
 
 export const DocumentInputSchema = z.object({

package/packages/workflows/src/definitions.ts

@@ -33,7 +33,7 @@ export const WORKFLOWS: WorkflowDefinition[] = [
       '파일 입력 분기: ① 사용자가 "파일이 있다"고 하면 `open_inbox`로 인입 폴더를 열어 파일을 넣게 하고, "다 넣었다"고 하면 `read_inbox`로 본문을 읽는다(pdf·이미지는 read_inbox가 경로만 주므로 클라이언트의 파일 읽기로 직접 읽는다). ② 사용자가 파일 경로를 직접 알려주면 `read_document`로 읽는다. ③ "없다/직접 입력/텍스트로 붙여넣기"면 폴더를 열지 말고 받은 텍스트를 그대로 쓴다. (묻지도 않고 open_inbox로 폴더를 자동으로 열지 않는다.)',
       '수집한 정보를 구조화해 `save_profile`로 저장한다(이름·연락처·headline·summary·desired_roles·desired_conditions, 그리고 글쓰기 선호인 preferred_tone과 emphasis_points 포함). 파일 출처는 source=upload, 직접 입력은 manual.',
       '업로드한 이력서/경력기술서/포트폴리오 본문을 `add_resume`로 저장한다(kind·title 지정, 대표 문서는 is_primary=true).',
-      '경력·프로젝트·스킬이 파악되면 `add_experience`·`add_project`·`add_skill`로 각각 저장한다(완성도의 has_experience/has_skills에 반영).',
+      '경력·프로젝트·스킬이 파악되면 `add_experience`·`add_project`·`add_skill`로 저장한다 — 각 도구는 배열을 받으므로 파악한 항목을 한 번에 모아 넘긴다(항목마다 반복 호출하지 않는다). 같은 항목을 다시 넣어도 중복 없이 갱신된다(완성도의 has_experience/has_skills에 반영).',
       '기존 자기소개서가 있으면 `save_cover_letter_version`으로 저장한다(title+content면 v1로 저장, 없으면 나중에 작성 가능함을 안내).',
       '`open_dashboard`를 호출해 사용자가 자기 데이터를 확인하게 한다.',
       '다시 `get_onboarding_status`로 완성도를 확인하고, 다음 단계(공고 분석 등)를 제안한다.',
@@ -53,8 +53,8 @@ export const WORKFLOWS: WorkflowDefinition[] = [
       '아직 저장되지 않은 공고라면 `save_job_posting`으로 공고를 저장하고 job_id를 확보한다.',
       '도출한 분석 결과를 `save_fit_analysis`로 저장한다(job_id, score, summary, strengths, gaps, matched_keywords, missing_keywords, recommendations).',
       '분석 결과를 사용자에게 쉬운 한국어로 설명한다(잘 맞는 점, 보완할 점, 추천 전략). 기술 용어는 빼고 전달한다.',
-      '"이 공고에 맞춘 자기소개서를 써드릴까요?"라고 자기소개서 작성을 제안한다.',
-      '사용자가 동의하면 자기소개서를 작성하기 직전에 `get_writing_style_guide`를 호출해 "AI 티 안 나는 글쓰기 규칙"을 가져온다.',
+      '분석 뒤 곧장 자기소개서를 쓰지 말고, "이 공고에 맞춘 자기소개서를 써드릴까요?"라고 묻고 선택지를 제시한다: ① "네, 이 공고에 맞춘 자기소개서를 써줘" ② "아니요, 분석만 저장해줘".',
+      '사용자가 ①을 선택하면 자기소개서를 작성하기 직전에 `get_writing_style_guide`를 호출해 "AI 티 안 나는 글쓰기 규칙"을 가져온다. ②를 선택하면 자소서 작성 없이 멈추고 저장 결과와 대시보드 확인만 안내한다.',
       '적합도 분석·글쓰기 선호와 글쓰기 규칙을 함께 반영해 자기소개서를 작성하고(번역투·클리셰·기계적 병렬 제거, 사실·수치는 그대로), `save_cover_letter_version`으로 저장한다(job_id 연결, note에 작성 의도 요약).',
       '`open_application`으로 해당 지원 건을 열어 사용자가 결과를 확인하게 하고, 지원 상태 변경(예: 지원 예정/지원 완료)을 제안한다.',
     ],