careermate 0.0.9 → 0.0.12

package/docs/FAQ.md

@@ -110,7 +110,7 @@ AI에게 "이 공고 저장하고 분석해줘"라고 하면서 URL이나 본문
 사용자 컴퓨터의 `~/.careermate`(Windows: `%USERPROFILE%\.careermate`)에만 저장됩니다.
 대시보드 **설정 > 데이터 저장 위치**에서 정확한 경로를 볼 수 있습니다. CareerMate가
 외부 서버로 개인 데이터를 보내는 일은 없습니다(외부 호출은 선택적 버전 확인과 공고
-검색 시 검색 키워드뿐).
+검색 시 검색 키워드·직무 조건뿐).
 
 ### AI와 대화하면 내 데이터는 어디로 가나요?
 CareerMate 도구의 응답(프로필·이력서·자소서 등)은 **당신이 연결한 AI 클라이언트**
@@ -127,6 +127,5 @@ CareerMate 도구의 응답(프로필·이력서·자소서 등)은 **당신이
 
 ---
 
-여기서 해결되지 않으면 [GitHub 이슈](https://github.com/osntak/careermate/issues)에 남겨
-주세요. **보안 문제**는 이슈가 아니라 [`../SECURITY.md`](../SECURITY.md)의 비공개 절차를
-이용해 주세요.
+여기서 해결되지 않으면 [이메일](mailto:osntak@gmail.com)로 문의해 주세요. 문의에는
+이름·연락처·자기소개서 본문 같은 개인정보를 붙여넣지 마세요.

package/docs/LOCAL_FIRST.md

@@ -0,0 +1,32 @@
+# Local-first data ownership
+
+CareerMate uses **local-first** to mean that the primary career workspace is owned by the user and stored on the user's machine.
+
+## Stored locally
+
+- SQLite database
+- profile, experience, project, and skill records
+- résumés, career descriptions, and cover-letter versions
+- saved job postings, application status, interview preparation, and timeline history
+- backups and exports
+- deterministic verification results
+
+These records are not uploaded to a CareerMate account or CareerMate-operated database.
+
+## Optional network activity
+
+Some features may use the network without changing the local-first model:
+
+- checking the npm registry for a newer CareerMate version
+- opening current installation documentation
+- searching supported public job-board endpoints using only the user's search keyword and job category (locally, CareerMate only records which postings it has already seen: board, posting id, date)
+- loading the public product website or demo
+- public-site analytics on `careermate.life`
+
+CareerMate must not attach locally stored résumé, profile, document, or application data to these requests.
+
+## Product language
+
+Do not describe CareerMate as fully offline. Prefer:
+
+> Your career database and documents stay on your computer. Optional discovery and update features may access the internet without sending your stored career data.

package/docs/MCP_TOOLS.md

@@ -12,11 +12,11 @@ CareerMate는 **MCP-우선** 로컬 커리어 관리 도구입니다. 사용자
 
 ## 읽기 전용(read-only) 표기 안내
 
-각 도구 항목의 **읽기전용** 열은 `tools.ts`의 `readOnly: true` 플래그를 그대로 반영합니다. 읽기전용 도구는 DB를 변경하지 않고 조회만 하며, 그 외 도구는 데이터를 생성·갱신하거나(쓰기) 브라우저를 여는 등의 부수효과를 가집니다.
+각 도구 항목의 **읽기전용** 열은 `tools.ts`의 `readOnly: true` 플래그를 그대로 반영합니다. 읽기전용 도구는 DB를 변경하지 않고 조회만 하며(예외: `search_jobs`는 공고를 처음 본 날짜를, `check_for_update`는 확인 결과를 로컬 캐시로 남긴다. 사용자 데이터는 바꾸지 않는다), 그 외 도구는 데이터를 생성·갱신하거나(쓰기) 브라우저를 여는 등의 부수효과를 가집니다.
 
 | 읽기전용(✅) 도구 | 쓰기/부수효과(✏️) 도구 |
 | --- | --- |
-| `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`, `prescreen_job`, `search_jobs`, `compare_offers`, `get_offer`, `get_application_context`, `list_recent_activity`, `get_followups`, `get_pipeline_stats`, `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`, `save_offer`, `export_cover_letter`, `export_resume`, `export_profile`, `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`, `prescreen_job`, `search_jobs`, `find_job_categories`, `get_job_search_preferences`, `compare_offers`, `get_offer`, `get_application_context`, `list_recent_activity`, `get_followups`, `get_pipeline_stats`, `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`, `set_job_search_preferences`, `save_job_posting`, `delete_job_posting`, `save_fit_analysis`, `update_application_status`, `save_interview_prep`, `save_offer`, `export_cover_letter`, `export_resume`, `export_profile`, `open_dashboard`, `open_application`, `update_careermate` |
 
 ---
 
@@ -141,7 +141,10 @@ AI 클라이언트가 연결되면 이 도구를 가장 먼저 호출해 상태
 
 | 도구 | 목적 | 주요 입력 | 반환 | 언제 호출 | 읽기전용 |
 | --- | --- | --- | --- | --- | --- |
-| `search_jobs` | 키워드로 무인증 공개 잡보드(원티드·점핏)에서 공고를 *가져옴*(저장은 안 함) | `keyword`(필수), `sources?`, `limit?`(기본 10) | `{ query, results[](회사·직무·url·지역·경력·기술·마감), providers[] }` | 사용자가 "○○ 공고 찾아줘"라고 할 때. 결과를 보여주고 **고른 것만** save_job_posting | ✅ |
+| `search_jobs` | 키워드나 직무 조건으로 무인증 공개 잡보드(원티드·점핏·리멤버·사람인)에서 공고를 *가져옴*(저장은 안 함). 여러 사이트의 같은 공고는 한 줄로 합침 | `keyword?`, `sources?`, `limit?`(사이트별, 기본 10, posted_since가 있으면 50, 최대 100), `remember_categories?`(["재무·회계·세무>회계결산"]), `saramin_categories?`(["322"]), `posted_since?`("today"·YYYY-MM-DD). keyword와 직무 조건을 모두 비우면 저장된 검색 조건 사용 | `{ query, results[](회사·직무·url·지역·경력·기술·마감·posted_at·first_seen_at·also_on, 사람인은 category_codes), providers[], filtered_out?, conditions, used_saved_preferences }` | "○○ 공고 찾아줘", "오늘 올라온 공고 보여줘". 결과를 보여주고 **고른 것만** save_job_posting. 원티드·점핏은 게시일이 없어 처음 본 날로 거름 | ✅ |
+| `find_job_categories` | 직무 이름을 리멤버 분류("상위>하위")와 사람인 직무 코드로 변환(내장 분류표, 외부 통신 없음). 모든 직군 | `query`(쉼표로 여러 개), `limit?`(기본 20) | `{ query, remember[], saramin[](code·name·group·kind) }` 관련도순 | search_jobs·set_job_search_preferences에 직무 조건을 넣기 전 | ✅ |
+| `get_job_search_preferences` | 저장된 공고 검색 조건 조회 | 없음 | `{ keyword, remember_categories, saramin_categories, updated_at }` | "내 검색 조건 뭐야?" | ✅ |
+| `set_job_search_preferences` | 자주 볼 공고 검색 조건 저장(준 필드만 갱신). 리멤버 분류는 내장 분류표로 검증 | `keyword?`, `remember_categories?`, `saramin_categories?` | 저장된 조건 | 사용자 직무를 find_job_categories로 찾고 확인받은 뒤 | ✏️ |
 | `save_job_posting` | 채용공고 저장(있으면 갱신). 저장 시 지원(application) 항목 자동 생성 | `company`, `position`(필수), `url?`, `location?`, `employment_type?`, `description?`, `requirements?`, `keywords?`, `deadline?`, `source?`, `questions?`(회사 지정 자소서 문항·글자수: `question`·`min_chars`·`max_chars`·`count_mode`), `schedule?`(전형 일정: `label`·`date`(YYYY-MM-DD) 필수·`time`(HH:MM)·`note`) | 저장된 `JobRecord`(`job_id` 포함) | 공고를 DB에 등록/갱신할 때 | ✏️ |
 | `get_job_posting` | 공고 1건 상세 조회 | `job_id` | `{ job, fit, application, cover_letters, interview }` | 한 공고의 분석·상태·자소서·면접 자료를 한 번에 볼 때 | ✅ |
 | `list_jobs` | 저장된 모든 공고를 지원 상태·적합도 점수와 함께 목록화 | 없음 | 공고 메타 포함 배열 | 전체 공고를 훑어볼 때 | ✅ |

package/docs/REVIEW_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,22 @@
+# Full Review Implementation Plan
+
+This document tracks the repository-wide improvements implemented after the 2026-08 full review.
+
+## Product definition
+
+CareerMate is local-first: the primary database, career records, generated documents, and core workflows are owned and stored on the user's machine. Optional network-backed features such as install guidance, update checks, analytics, and job-board search do not change that definition.
+
+## Delivery groups
+
+1. Data safety and lifecycle
+2. Provenance and human verification
+3. Backup, restore, and portability
+4. Provider validation and health
+5. Onboarding and diagnostics
+6. Workflow history and explainability
+7. Fit analysis quality and contradiction detection
+8. Front-end maintainability and accessibility
+9. CI, release, and security hardening
+10. Documentation and SEO
+
+Each group should be implemented as an independently reviewable commit or PR with tests and migration coverage where applicable.

package/docs/career-os/README.md

@@ -1,6 +1,6 @@
 # Career-OS — 외부 LLM 실행 진입점 (단일 입구)
 
-> ✅ **상태(2026-06): 이 라우팅·EOP 적용은 이제 런타임에 배선되어 있다(Phase B-1).** 연결된 AI는 `get_workflow_guide`로 작업별 실행 절차(EOP)와 적용할 플레이북·검증기 순서를 받고, `get_playbook`/`get_verifier`로 이 폴더의 지식을 실제로 받아 적용한다. `get_application_context`도 `recommended_route`·`verifier_sequence`·`next_tool`를 함께 돌려준다. 아직 구현하지 않은 범위(B-2: det 점수 계산·저장 게이트·마이그레이션)와 패키지 구조는 [`implementation/README.md`](https://github.com/osntak/careermate/blob/main/docs/career-os/implementation/README.md) 참고.
+> ✅ **상태(2026-06): 이 라우팅·EOP 적용은 이제 런타임에 배선되어 있다(Phase B-1).** 연결된 AI는 `get_workflow_guide`로 작업별 실행 절차(EOP)와 적용할 플레이북·검증기 순서를 받고, `get_playbook`/`get_verifier`로 이 폴더의 지식을 실제로 받아 적용한다. `get_application_context`도 `recommended_route`·`verifier_sequence`·`next_tool`를 함께 돌려준다. 아직 구현하지 않은 범위(B-2: det 점수 계산·저장 게이트·마이그레이션)와 패키지 구조는 [`implementation/README.md`](implementation/README.md) 참고.
 
 > **여기서 시작하라.** CareerMate는 수동적 지식이 아니라, 외부 AI가 사용자 대면 결과를 내기 전에 적용해야 하는
 > **실행형 플레이북(EOP)·검증 루브릭·라우팅·출력 계약**을 제공한다. 두뇌=외부 AI(당신), CareerMate=실행 기질(substrate). 내부 LLM 없음.
@@ -9,7 +9,7 @@
 > 보조(런타임 아님): `validation/`(리서치 출처 + 다중 LLM(cross-vendor) 검증 하니스) · `implementation/`(CareerMate 개발자용 Phase B 내부 설계).
 >
 > EOP(Expert Operating Procedure) = 한 기능을 *시니어 전문가처럼* 수행하는 실행 절차. 검증된 리서치(`validation/research/`)에 근거하고
-> [`validation/PROTOCOL.md`](https://github.com/osntak/careermate/blob/main/docs/career-os/validation/PROTOCOL.md)의 다중 LLM(cross-vendor) 교차검증으로 단단해진다.
+> [`validation/PROTOCOL.md`](validation/PROTOCOL.md)의 다중 LLM(cross-vendor) 교차검증으로 단단해진다.
 
 ## 0. 절대 원칙 — 근거 우선순위
 ```

package/package.json

@@ -1,18 +1,11 @@
 {
   "name": "careermate",
-  "version": "0.0.9",
+  "version": "0.0.12",
   "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.",
+  "description": "CareerMate — an MCP-first, local-first career workspace. Your career database and documents stay on your machine; optional discovery and update features may use the internet without sending stored career data.",
   "license": "MIT",
   "author": "CareerMate",
   "homepage": "https://careermate.life",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/osntak/careermate.git"
-  },
-  "bugs": {
-    "url": "https://github.com/osntak/careermate/issues"
-  },
   "keywords": [
     "career",
     "resume",
@@ -41,6 +34,8 @@
     "INSTALL.md",
     "THIRD_PARTY_NOTICES.md",
     "AGENTS.md",
+    "docs/LOCAL_FIRST.md",
+    "docs/REVIEW_IMPLEMENTATION_PLAN.md",
     "docs/career-os/README.md",
     "docs/career-os/eop",
     "docs/career-os/knowledge",
@@ -80,13 +75,13 @@
     "mammoth": "^1.12.0",
     "pdfjs-dist": "^6.0.0",
     "tsx": "^4.19.2",
-    "zod": "^3.24.1"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
-    "@types/node": "^22.10.0",
+    "@types/node": "^26.1.2",
     "esbuild": "^0.28.1",
     "playwright": "^1.60.0",
-    "typescript": "^5.7.2"
+    "typescript": "^7.0.2"
   }
 }

package/packages/core/src/data-health.ts

@@ -0,0 +1,161 @@
+import {
+  documentRepo,
+  experienceRepo,
+  projectRepo,
+  jobRepo,
+  fitRepo,
+  applicationRepo,
+} from '@careermate/db';
+
+export interface DataHealthIssue {
+  code: string;
+  severity: 'info' | 'warning' | 'error';
+  entity_type: string;
+  entity_id?: string;
+  message: string;
+}
+
+export interface DataHealthReport {
+  score: number;
+  checked_at: string;
+  counts: Record<string, number>;
+  issues: DataHealthIssue[];
+}
+
+function monthValue(value: string | null | undefined): number | null {
+  if (!value) return null;
+  const m = /^(\d{4})-(\d{2})/.exec(value);
+  if (!m) return null;
+  return Number(m[1]) * 12 + Number(m[2]);
+}
+
+function normalized(value: string | null | undefined): string {
+  return (value ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+export function getDataHealthReport(now = new Date()): DataHealthReport {
+  const experiences = experienceRepo.list();
+  const projects = projectRepo.list();
+  const documents = documentRepo.list();
+  const jobs = jobRepo.list();
+  const issues: DataHealthIssue[] = [];
+
+  for (const exp of experiences) {
+    const start = monthValue(exp.start_date);
+    const end = monthValue(exp.end_date);
+    if (start != null && end != null && end < start) {
+      issues.push({
+        code: 'experience_date_reversed',
+        severity: 'error',
+        entity_type: 'experience',
+        entity_id: exp.id,
+        message: `${exp.company} 경력의 종료일이 시작일보다 빠릅니다.`,
+      });
+    }
+    if (exp.is_current && exp.end_date) {
+      issues.push({
+        code: 'current_experience_has_end_date',
+        severity: 'warning',
+        entity_type: 'experience',
+        entity_id: exp.id,
+        message: `${exp.company} 경력이 재직 중이지만 종료일이 입력돼 있습니다.`,
+      });
+    }
+    if (!exp.role) {
+      issues.push({
+        code: 'experience_missing_role',
+        severity: 'warning',
+        entity_type: 'experience',
+        entity_id: exp.id,
+        message: `${exp.company} 경력에 직무/역할이 없습니다.`,
+      });
+    }
+  }
+
+  const seenProjects = new Map<string, string>();
+  for (const project of projects) {
+    const key = normalized(project.name);
+    const duplicate = seenProjects.get(key);
+    if (key && duplicate) {
+      issues.push({
+        code: 'duplicate_project_name',
+        severity: 'warning',
+        entity_type: 'project',
+        entity_id: project.id,
+        message: `같은 이름의 프로젝트가 중복돼 있습니다: ${project.name}`,
+      });
+    } else if (key) {
+      seenProjects.set(key, project.id);
+    }
+    const start = monthValue(project.start_date);
+    const end = monthValue(project.end_date);
+    if (start != null && end != null && end < start) {
+      issues.push({
+        code: 'project_date_reversed',
+        severity: 'error',
+        entity_type: 'project',
+        entity_id: project.id,
+        message: `${project.name} 프로젝트의 종료일이 시작일보다 빠릅니다.`,
+      });
+    }
+  }
+
+  const primaryDocs = documents.filter((doc) => doc.is_primary);
+  if (documents.length > 0 && primaryDocs.length === 0) {
+    issues.push({
+      code: 'missing_primary_document',
+      severity: 'warning',
+      entity_type: 'document',
+      message: '대표 이력서 또는 경력기술서가 지정되지 않았습니다.',
+    });
+  }
+
+  const nowDate = now.toISOString().slice(0, 10);
+  let staleDrafts = 0;
+  let jobsWithoutFit = 0;
+  for (const job of jobs) {
+    if (!fitRepo.getByJob(job.id)) jobsWithoutFit++;
+    const app = applicationRepo.getByJob(job.id);
+    if (app?.status === 'draft') {
+      const updated = String(app.updated_at ?? '').slice(0, 10);
+      if (updated && updated < nowDate) staleDrafts++;
+    }
+  }
+  if (jobsWithoutFit > 0) {
+    issues.push({
+      code: 'jobs_without_fit_analysis',
+      severity: 'info',
+      entity_type: 'job',
+      message: `적합도 분석이 없는 공고가 ${jobsWithoutFit}개 있습니다.`,
+    });
+  }
+  if (staleDrafts > 0) {
+    issues.push({
+      code: 'stale_draft_applications',
+      severity: 'info',
+      entity_type: 'application',
+      message: `후속 행동을 확인할 임시 지원 건이 ${staleDrafts}개 있습니다.`,
+    });
+  }
+
+  const penalty = issues.reduce((sum, issue) => {
+    if (issue.severity === 'error') return sum + 15;
+    if (issue.severity === 'warning') return sum + 7;
+    return sum + 2;
+  }, 0);
+
+  return {
+    score: Math.max(0, 100 - penalty),
+    checked_at: now.toISOString(),
+    counts: {
+      experiences: experiences.length,
+      projects: projects.length,
+      documents: documents.length,
+      jobs: jobs.length,
+      issues: issues.length,
+      errors: issues.filter((issue) => issue.severity === 'error').length,
+      warnings: issues.filter((issue) => issue.severity === 'warning').length,
+    },
+    issues,
+  };
+}

package/packages/core/src/fit-explain.ts

@@ -0,0 +1,63 @@
+import { fitRepo, jobRepo } from '@careermate/db';
+
+export interface ExplainableFitAnalysis {
+  job_id: string;
+  overall_score: number | null;
+  requirement_coverage: number | null;
+  evidence_strength: number;
+  matched_requirements: string[];
+  missing_requirements: string[];
+  strengths: string[];
+  risks: string[];
+  recommended_actions: string[];
+  explanation: string;
+}
+
+function ratio(matched: number, missing: number): number | null {
+  const total = matched + missing;
+  return total === 0 ? null : Math.round((matched / total) * 100);
+}
+
+export function getExplainableFitAnalysis(jobId: string): ExplainableFitAnalysis | null {
+  const job = jobRepo.get(jobId);
+  const fit = fitRepo.getByJob(jobId);
+  if (!job || !fit) return null;
+
+  const matched = fit.matched_keywords ?? [];
+  const missing = fit.missing_keywords ?? [];
+  const coverage = ratio(matched.length, missing.length);
+  const evidenceItems = (fit.strengths ?? []).filter((item) => item.trim().length > 0);
+  const evidenceStrength = Math.min(100, evidenceItems.length * 20 + matched.length * 5);
+  const risks = [
+    ...(fit.gaps ?? []),
+    ...missing.map((item) => `근거가 부족한 요구사항: ${item}`),
+  ];
+  const actions = fit.recommendations?.length
+    ? fit.recommendations
+    : missing.map((item) => `${item} 요구에 연결할 실제 경험 또는 학습 근거를 보완하세요.`);
+
+  const explanationParts = [
+    coverage == null
+      ? '요구사항 충족률을 계산할 수 있는 매칭 정보가 아직 없습니다.'
+      : `저장된 키워드 기준 요구사항 충족률은 ${coverage}%입니다.`,
+    evidenceStrength >= 70
+      ? '강점과 근거가 비교적 충분합니다.'
+      : evidenceStrength >= 40
+        ? '일부 근거는 있지만 지원 문서에서 더 구체적으로 연결할 필요가 있습니다.'
+        : '현재 분석에는 구체적인 경험 근거가 부족합니다.',
+    risks.length > 0 ? `확인할 위험 요소가 ${risks.length}개 있습니다.` : '명시된 주요 위험 요소는 없습니다.',
+  ];
+
+  return {
+    job_id: jobId,
+    overall_score: fit.score,
+    requirement_coverage: coverage,
+    evidence_strength: evidenceStrength,
+    matched_requirements: matched,
+    missing_requirements: missing,
+    strengths: fit.strengths ?? [],
+    risks,
+    recommended_actions: actions,
+    explanation: explanationParts.join(' '),
+  };
+}

package/packages/core/src/index.ts

@@ -7,5 +7,9 @@ export * from './context.ts';
 export * from './services.ts';
 export * from './summary.ts';
 export * from './jobsearch.ts';
+export * from './job-categories.ts';
 export * from './offers.ts';
+export * from './data-health.ts';
+export * from './fit-explain.ts';
+export * from './reuse-insights.ts';
 export * from './verify/index.ts';