careermate 0.1.0

package/packages/shared/src/enums.ts

@@ -0,0 +1,103 @@
+/**
+ * CareerMate — shared enums and human-facing labels.
+ *
+ * These value sets are the single source of truth for both the MCP server
+ * (used by ChatGPT/Claude/Gemini) and the local web dashboard. Labels are in
+ * Korean because the primary audience is Korean job seekers; codes are stable
+ * machine values that must never change once persisted.
+ */
+
+/** Application lifecycle. Drives the Applications board in the dashboard. */
+export const APPLICATION_STATUSES = [
+  'draft', // 작성 중
+  'planned', // 지원 예정
+  'applied', // 지원 완료
+  'document_passed', // 서류 합격
+  'interview', // 면접 진행
+  'final_passed', // 최종 합격
+  'rejected', // 불합격
+  'on_hold', // 보류
+] as const;
+
+export type ApplicationStatus = (typeof APPLICATION_STATUSES)[number];
+
+export const APPLICATION_STATUS_LABELS: Record<ApplicationStatus, string> = {
+  draft: '작성 중',
+  planned: '지원 예정',
+  applied: '지원 완료',
+  document_passed: '서류 합격',
+  interview: '면접 진행',
+  final_passed: '최종 합격',
+  rejected: '불합격',
+  on_hold: '보류',
+};
+
+/** Ordered columns for the kanban-style Applications board. */
+export const APPLICATION_BOARD_ORDER: ApplicationStatus[] = [
+  'draft',
+  'planned',
+  'applied',
+  'document_passed',
+  'interview',
+  'final_passed',
+  'on_hold',
+  'rejected',
+];
+
+/** Reaching this status unlocks interview-prep prompting in the workflow. */
+export const INTERVIEW_UNLOCK_STATUSES: ApplicationStatus[] = [
+  'document_passed',
+  'interview',
+  'final_passed',
+];
+
+/** Stored document kinds (resumes and career descriptions). Cover letters live in their own tables. */
+export const DOCUMENT_KINDS = ['resume', 'career_description', 'portfolio', 'other'] as const;
+export type DocumentKind = (typeof DOCUMENT_KINDS)[number];
+
+export const DOCUMENT_KIND_LABELS: Record<DocumentKind, string> = {
+  resume: '이력서',
+  career_description: '경력기술서',
+  portfolio: '포트폴리오',
+  other: '기타 문서',
+};
+
+/** Where a piece of content originated — used to show provenance and protect privacy. */
+export const CONTENT_SOURCES = ['manual', 'upload', 'ai', 'edit'] as const;
+export type ContentSource = (typeof CONTENT_SOURCES)[number];
+
+export const CONTENT_SOURCE_LABELS: Record<ContentSource, string> = {
+  manual: '직접 입력',
+  upload: '파일 업로드',
+  ai: 'AI 생성',
+  edit: '직접 수정',
+};
+
+/** Activity feed entry types (list_recent_activity). */
+export const ACTIVITY_TYPES = [
+  'profile_updated',
+  'resume_added',
+  'cover_letter_added',
+  'cover_letter_version_saved',
+  'job_saved',
+  'fit_analysis_saved',
+  'application_status_changed',
+  'interview_prep_saved',
+  'document_exported',
+] as const;
+export type ActivityType = (typeof ACTIVITY_TYPES)[number];
+
+/** Entity kinds referenced by activities and deep links. */
+export const ENTITY_TYPES = [
+  'profile',
+  'experience',
+  'project',
+  'skill',
+  'document',
+  'cover_letter',
+  'job',
+  'application',
+  'fit_analysis',
+  'interview_prep',
+] as const;
+export type EntityType = (typeof ENTITY_TYPES)[number];

package/packages/shared/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @careermate/shared — single source of truth for types, enums, and zod schemas
+ * shared by the DB layer, core use-cases, HTTP API, and MCP server.
+ */
+export * from './enums.ts';
+export * from './schemas.ts';
+
+/** Short, URL-safe, sortable-ish id. Avoids a uuid dependency. */
+export function newId(prefix = ''): string {
+  const rnd = Math.random().toString(36).slice(2, 10);
+  const time = Date.now().toString(36);
+  return `${prefix}${time}${rnd}`;
+}
+
+/** Current timestamp as ISO-8601 string (stored verbatim in SQLite). */
+export function now(): string {
+  return new Date().toISOString();
+}

package/packages/shared/src/schemas.ts

@@ -0,0 +1,398 @@
+/**
+ * CareerMate — zod schemas + inferred TypeScript types.
+ *
+ * Two layers per entity:
+ *  - `*Input`  : what the MCP tools / HTTP API accept from the AI or dashboard.
+ *  - `*Record` : the persisted shape returned from the DB (adds id + timestamps).
+ *
+ * JSON-ish nested fields (achievements, tech, strengths…) are stored as JSON
+ * text columns in SQLite and parsed back into arrays/objects by the repositories.
+ */
+import { z } from 'zod';
+import {
+  APPLICATION_STATUSES,
+  ACTIVITY_TYPES,
+  CONTENT_SOURCES,
+  DOCUMENT_KINDS,
+  ENTITY_TYPES,
+} from './enums.ts';
+
+const isoDateTime = z.string();
+const id = z.string();
+
+const baseRecord = {
+  id,
+  created_at: isoDateTime,
+  updated_at: isoDateTime,
+};
+
+/* ------------------------------------------------------------------ Profile */
+
+export const LinkSchema = z.object({
+  label: z.string().min(1),
+  url: z.string().min(1),
+});
+export type Link = z.infer<typeof LinkSchema>;
+
+export const ProfileInputSchema = z.object({
+  name: z.string().min(1).optional(),
+  email: z.string().optional(),
+  phone: z.string().optional(),
+  location: z.string().optional(),
+  headline: z.string().optional().describe('한 줄 소개 / 직무 타이틀'),
+  summary: z.string().optional().describe('자기소개 요약'),
+  desired_roles: z.array(z.string()).optional().describe('희망 직무'),
+  desired_conditions: z.string().optional().describe('희망 근무 조건 (연봉, 지역, 근무형태 등)'),
+  preferred_tone: z.string().optional().describe('자기소개서 선호 문체 (예: 담백하고 구체적)'),
+  emphasis_points: z.array(z.string()).optional().describe('강조하고 싶은 핵심 포인트'),
+  links: z.array(LinkSchema).optional().describe('포트폴리오/깃허브/링크드인 등'),
+});
+export type ProfileInput = z.infer<typeof ProfileInputSchema>;
+
+export const ProfileRecordSchema = z.object({
+  ...baseRecord,
+  name: z.string().nullable(),
+  email: z.string().nullable(),
+  phone: z.string().nullable(),
+  location: z.string().nullable(),
+  headline: z.string().nullable(),
+  summary: z.string().nullable(),
+  desired_roles: z.array(z.string()),
+  desired_conditions: z.string().nullable(),
+  preferred_tone: z.string().nullable(),
+  emphasis_points: z.array(z.string()),
+  links: z.array(LinkSchema),
+});
+export type ProfileRecord = z.infer<typeof ProfileRecordSchema>;
+
+/* --------------------------------------------------------------- Experience */
+
+export const ExperienceInputSchema = z.object({
+  company: z.string().min(1),
+  role: z.string().optional(),
+  employment_type: z.string().optional().describe('정규직/계약직/인턴/프리랜서 등'),
+  start_date: z.string().optional().describe('YYYY-MM 또는 YYYY-MM-DD'),
+  end_date: z.string().optional().describe('재직 중이면 비워두기'),
+  is_current: z.boolean().optional(),
+  description: z.string().optional(),
+  achievements: z.array(z.string()).optional().describe('성과/업적 (정량 지표 권장)'),
+  tech: z.array(z.string()).optional().describe('사용 기술/도구'),
+  order_index: z.number().optional(),
+});
+export type ExperienceInput = z.infer<typeof ExperienceInputSchema>;
+
+export const ExperienceRecordSchema = z.object({
+  ...baseRecord,
+  company: z.string(),
+  role: z.string().nullable(),
+  employment_type: z.string().nullable(),
+  start_date: z.string().nullable(),
+  end_date: z.string().nullable(),
+  is_current: z.boolean(),
+  description: z.string().nullable(),
+  achievements: z.array(z.string()),
+  tech: z.array(z.string()),
+  order_index: z.number(),
+});
+export type ExperienceRecord = z.infer<typeof ExperienceRecordSchema>;
+
+/* ------------------------------------------------------------------ Project */
+
+export const ProjectInputSchema = z.object({
+  name: z.string().min(1),
+  role: z.string().optional(),
+  description: z.string().optional(),
+  highlights: z.array(z.string()).optional(),
+  tech: z.array(z.string()).optional(),
+  url: z.string().optional(),
+  start_date: z.string().optional(),
+  end_date: z.string().optional(),
+  order_index: z.number().optional(),
+});
+export type ProjectInput = z.infer<typeof ProjectInputSchema>;
+
+export const ProjectRecordSchema = z.object({
+  ...baseRecord,
+  name: z.string(),
+  role: z.string().nullable(),
+  description: z.string().nullable(),
+  highlights: z.array(z.string()),
+  tech: z.array(z.string()),
+  url: z.string().nullable(),
+  start_date: z.string().nullable(),
+  end_date: z.string().nullable(),
+  order_index: z.number(),
+});
+export type ProjectRecord = z.infer<typeof ProjectRecordSchema>;
+
+/* -------------------------------------------------------------------- Skill */
+
+export const SkillInputSchema = z.object({
+  name: z.string().min(1),
+  category: z.string().optional().describe('언어/프레임워크/툴/소프트스킬 등'),
+  level: z.string().optional().describe('상/중/하 또는 자유 서술'),
+  years: z.number().optional(),
+  order_index: z.number().optional(),
+});
+export type SkillInput = z.infer<typeof SkillInputSchema>;
+
+export const SkillRecordSchema = z.object({
+  ...baseRecord,
+  name: z.string(),
+  category: z.string().nullable(),
+  level: z.string().nullable(),
+  years: z.number().nullable(),
+  order_index: z.number(),
+});
+export type SkillRecord = z.infer<typeof SkillRecordSchema>;
+
+/* ----------------------------------------------------------------- Document */
+
+export const DocumentInputSchema = z.object({
+  kind: z.enum(DOCUMENT_KINDS),
+  title: z.string().min(1),
+  content: z.string().describe('Markdown 또는 일반 텍스트 본문'),
+  source: z.enum(CONTENT_SOURCES).optional(),
+  is_primary: z.boolean().optional().describe('대표 문서 여부'),
+  tags: z.array(z.string()).optional(),
+});
+export type DocumentInput = z.infer<typeof DocumentInputSchema>;
+
+export const DocumentRecordSchema = z.object({
+  ...baseRecord,
+  kind: z.enum(DOCUMENT_KINDS),
+  title: z.string(),
+  content: z.string(),
+  source: z.enum(CONTENT_SOURCES),
+  is_primary: z.boolean(),
+  tags: z.array(z.string()),
+});
+export type DocumentRecord = z.infer<typeof DocumentRecordSchema>;
+
+/* -------------------------------------------------------------- CoverLetter */
+
+export const CoverLetterInputSchema = z.object({
+  title: z.string().min(1),
+  job_id: z.string().optional().describe('특정 공고에 연결할 경우'),
+  is_primary: z.boolean().optional(),
+  content: z.string().optional().describe('초기 버전 본문 (있으면 v1로 저장)'),
+  source: z.enum(CONTENT_SOURCES).optional(),
+  note: z.string().optional().describe('초기 버전 메모'),
+});
+export type CoverLetterInput = z.infer<typeof CoverLetterInputSchema>;
+
+export const CoverLetterVersionInputSchema = z.object({
+  cover_letter_id: z.string().optional().describe('기존 자기소개서에 새 버전 추가 시'),
+  title: z.string().optional().describe('새 자기소개서를 만들 때 제목'),
+  job_id: z.string().optional(),
+  content: z.string().min(1),
+  note: z.string().optional().describe('이 버전의 변경 요약 (예: 지원동기 보강)'),
+  source: z.enum(CONTENT_SOURCES).optional(),
+  set_current: z.boolean().optional().describe('이 버전을 현재 버전으로 지정 (기본 true)'),
+});
+export type CoverLetterVersionInput = z.infer<typeof CoverLetterVersionInputSchema>;
+
+export const CoverLetterVersionRecordSchema = z.object({
+  id,
+  cover_letter_id: z.string(),
+  version_no: z.number(),
+  content: z.string(),
+  note: z.string().nullable(),
+  source: z.enum(CONTENT_SOURCES),
+  created_at: isoDateTime,
+});
+export type CoverLetterVersionRecord = z.infer<typeof CoverLetterVersionRecordSchema>;
+
+export const CoverLetterRecordSchema = z.object({
+  ...baseRecord,
+  title: z.string(),
+  job_id: z.string().nullable(),
+  is_primary: z.boolean(),
+  current_version_id: z.string().nullable(),
+  version_count: z.number(),
+  current_content: z.string().nullable(),
+  versions: z.array(CoverLetterVersionRecordSchema).optional(),
+});
+export type CoverLetterRecord = z.infer<typeof CoverLetterRecordSchema>;
+
+/* --------------------------------------------------------------------- Job */
+
+export const JobInputSchema = z.object({
+  company: z.string().min(1),
+  position: z.string().min(1).describe('직무/포지션명'),
+  url: z.string().optional(),
+  location: z.string().optional(),
+  employment_type: z.string().optional(),
+  description: z.string().optional().describe('공고 원문 또는 정리된 텍스트'),
+  requirements: z.array(z.string()).optional().describe('자격요건/우대사항 핵심'),
+  keywords: z.array(z.string()).optional().describe('핵심 키워드'),
+  deadline: z.string().optional().describe('마감일 YYYY-MM-DD'),
+  source: z.string().optional().describe('출처 (사람인/원티드/직접 입력 등)'),
+});
+export type JobInput = z.infer<typeof JobInputSchema>;
+
+export const JobRecordSchema = z.object({
+  ...baseRecord,
+  company: z.string(),
+  position: z.string(),
+  url: z.string().nullable(),
+  location: z.string().nullable(),
+  employment_type: z.string().nullable(),
+  description: z.string().nullable(),
+  requirements: z.array(z.string()),
+  keywords: z.array(z.string()),
+  deadline: z.string().nullable(),
+  source: z.string().nullable(),
+});
+export type JobRecord = z.infer<typeof JobRecordSchema>;
+
+/* ------------------------------------------------------------- FitAnalysis */
+
+export const FitAnalysisInputSchema = z.object({
+  job_id: z.string().describe('분석 대상 공고 ID'),
+  score: z.number().min(0).max(100).optional().describe('종합 적합도 0~100'),
+  summary: z.string().optional().describe('한두 문단 요약'),
+  strengths: z.array(z.string()).optional().describe('강점 / 잘 맞는 부분'),
+  gaps: z.array(z.string()).optional().describe('부족한 부분 / 보완 필요'),
+  matched_keywords: z.array(z.string()).optional(),
+  missing_keywords: z.array(z.string()).optional(),
+  recommendations: z.array(z.string()).optional().describe('자기소개서/지원 전략 제안'),
+});
+export type FitAnalysisInput = z.infer<typeof FitAnalysisInputSchema>;
+
+export const FitAnalysisRecordSchema = z.object({
+  ...baseRecord,
+  job_id: z.string(),
+  score: z.number().nullable(),
+  summary: z.string().nullable(),
+  strengths: z.array(z.string()),
+  gaps: z.array(z.string()),
+  matched_keywords: z.array(z.string()),
+  missing_keywords: z.array(z.string()),
+  recommendations: z.array(z.string()),
+});
+export type FitAnalysisRecord = z.infer<typeof FitAnalysisRecordSchema>;
+
+/* ------------------------------------------------------------- Application */
+
+export const ApplicationInputSchema = z.object({
+  job_id: z.string(),
+  status: z.enum(APPLICATION_STATUSES).optional(),
+  resume_id: z.string().optional(),
+  cover_letter_id: z.string().optional(),
+  applied_at: z.string().optional(),
+  notes: z.string().optional(),
+});
+export type ApplicationInput = z.infer<typeof ApplicationInputSchema>;
+
+export const ApplicationStatusUpdateSchema = z.object({
+  job_id: z.string().optional(),
+  application_id: z.string().optional(),
+  status: z.enum(APPLICATION_STATUSES),
+  note: z.string().optional().describe('상태 변경 사유/메모'),
+});
+export type ApplicationStatusUpdate = z.infer<typeof ApplicationStatusUpdateSchema>;
+
+export const ApplicationRecordSchema = z.object({
+  ...baseRecord,
+  job_id: z.string(),
+  status: z.enum(APPLICATION_STATUSES),
+  resume_id: z.string().nullable(),
+  cover_letter_id: z.string().nullable(),
+  applied_at: z.string().nullable(),
+  notes: z.string().nullable(),
+});
+export type ApplicationRecord = z.infer<typeof ApplicationRecordSchema>;
+
+/* ----------------------------------------------------------- InterviewPrep */
+
+export const StarGuideSchema = z.object({
+  question: z.string(),
+  situation: z.string().optional(),
+  task: z.string().optional(),
+  action: z.string().optional(),
+  result: z.string().optional(),
+});
+export type StarGuide = z.infer<typeof StarGuideSchema>;
+
+export const InterviewQuestionSchema = z.object({
+  question: z.string(),
+  intent: z.string().optional().describe('질문 의도'),
+  followups: z.array(z.string()).optional().describe('예상 꼬리 질문'),
+  answer_outline: z.string().optional().describe('답변 가이드/핵심 포인트'),
+});
+export type InterviewQuestion = z.infer<typeof InterviewQuestionSchema>;
+
+export const InterviewPrepInputSchema = z.object({
+  job_id: z.string(),
+  questions: z.array(InterviewQuestionSchema).optional(),
+  star_guides: z.array(StarGuideSchema).optional(),
+  self_introduction: z.string().optional().describe('1분 자기소개 초안'),
+  notes: z.string().optional().describe('면접 후기/메모'),
+});
+export type InterviewPrepInput = z.infer<typeof InterviewPrepInputSchema>;
+
+export const InterviewPrepRecordSchema = z.object({
+  ...baseRecord,
+  job_id: z.string(),
+  questions: z.array(InterviewQuestionSchema),
+  star_guides: z.array(StarGuideSchema),
+  self_introduction: z.string().nullable(),
+  notes: z.string().nullable(),
+});
+export type InterviewPrepRecord = z.infer<typeof InterviewPrepRecordSchema>;
+
+/* ----------------------------------------------------------------- Activity */
+
+export const ActivityRecordSchema = z.object({
+  id,
+  type: z.enum(ACTIVITY_TYPES),
+  entity_type: z.enum(ENTITY_TYPES).nullable(),
+  entity_id: z.string().nullable(),
+  summary: z.string(),
+  created_at: isoDateTime,
+});
+export type ActivityRecord = z.infer<typeof ActivityRecordSchema>;
+
+/* ----------------------------------------------------- Aggregates / context */
+
+export const OnboardingStatusSchema = z.object({
+  completed: z.boolean(),
+  has_profile: z.boolean(),
+  has_resume: z.boolean(),
+  has_cover_letter: z.boolean(),
+  has_experience: z.boolean(),
+  has_skills: z.boolean(),
+  has_job: z.boolean(),
+  profile_completeness: z.number().describe('0~100 프로필 완성도'),
+  next_steps: z.array(z.string()).describe('지금 해야 할 다음 단계 안내'),
+});
+export type OnboardingStatus = z.infer<typeof OnboardingStatusSchema>;
+
+/** The one-shot context bundle the AI pulls before analyzing a job or writing. */
+export const ApplicationContextSchema = z.object({
+  profile: ProfileRecordSchema.nullable(),
+  primary_resume: DocumentRecordSchema.nullable(),
+  resumes: z.array(DocumentRecordSchema),
+  experiences: z.array(ExperienceRecordSchema),
+  projects: z.array(ProjectRecordSchema),
+  skills: z.array(SkillRecordSchema),
+  cover_letters: z.array(CoverLetterRecordSchema),
+  recent_applications: z.array(ApplicationRecordSchema),
+  job: JobRecordSchema.nullable(),
+  fit_analysis: FitAnalysisRecordSchema.nullable(),
+  related_history: z
+    .array(
+      z.object({
+        job: JobRecordSchema,
+        application: ApplicationRecordSchema.nullable(),
+        fit_analysis: FitAnalysisRecordSchema.nullable(),
+      }),
+    )
+    .describe('같은 회사/직무 관련 이전 기록'),
+  writing_preferences: z.object({
+    preferred_tone: z.string().nullable(),
+    emphasis_points: z.array(z.string()),
+  }),
+});
+export type ApplicationContext = z.infer<typeof ApplicationContextSchema>;

package/packages/workflows/src/definitions.ts

@@ -0,0 +1,107 @@
+/**
+ * @careermate/workflows — definitions.ts
+ *
+ * Step-by-step workflows the AI should follow, encoded as DATA + helper text.
+ * Each step references concrete MCP tool names so the AI knows exactly which
+ * tool to call. Korean-first (read by the AI and surfaced to users).
+ */
+
+export interface WorkflowDefinition {
+  /** Stable machine id. */
+  id: string;
+  /** Human-facing title (Korean). */
+  title: string;
+  /** One-line description of what this workflow accomplishes. */
+  description: string;
+  /** When the AI should start this workflow (natural-language trigger). */
+  trigger: string;
+  /** Ordered steps; each references the concrete MCP tool(s) to call. */
+  steps: string[];
+}
+
+export const WORKFLOWS: WorkflowDefinition[] = [
+  {
+    id: 'onboarding',
+    title: '온보딩 (첫 셋업)',
+    description:
+      '사용자가 처음 연결했을 때 프로필·이력서·자기소개서를 등록하고 대시보드를 여는 흐름.',
+    trigger:
+      '사용자가 처음 CareerMate에 연결했거나, "시작하자 / 셋업해줘 / 프로필 등록"이라고 요청할 때.',
+    steps: [
+      '`get_onboarding_status`를 호출해 현재 등록 상태(has_profile, has_resume, has_cover_letter, has_experience, has_skills, profile_completeness, next_steps)를 확인한다.',
+      '비어 있는 항목을 사용자에게 쉬운 한국어로 안내하고, 이력서/자기소개서 파일 업로드 또는 정보 입력을 요청한다.',
+      '수집한 정보를 구조화해 `save_profile`로 저장한다(이름·연락처·headline·summary·desired_roles·desired_conditions, 그리고 글쓰기 선호인 preferred_tone과 emphasis_points 포함). 파일 출처는 source=upload, 직접 입력은 manual.',
+      '업로드한 이력서/경력기술서/포트폴리오 본문을 `add_resume`로 저장한다(kind·title 지정, 대표 문서는 is_primary=true).',
+      '기존 자기소개서가 있으면 `add_cover_letter`로 저장한다(없으면 나중에 작성 가능함을 안내).',
+      '`open_dashboard`를 호출해 사용자가 자기 데이터를 확인하게 한다.',
+      '다시 `get_onboarding_status`로 완성도를 확인하고, 다음 단계(공고 분석 등)를 제안한다.',
+    ],
+  },
+  {
+    id: 'analyze_job',
+    title: '공고 분석 (적합도 분석)',
+    description:
+      '채용 공고를 읽어 사용자 프로필과 비교하고, 공고와 적합도 분석을 저장한 뒤 자기소개서 작성을 제안하는 핵심 흐름.',
+    trigger:
+      '사용자가 채용 공고 링크나 본문을 붙여넣거나 "이 공고 분석해줘 / 나랑 잘 맞아?"라고 물을 때.',
+    steps: [
+      '공고 원문(붙여넣은 텍스트 또는 링크 내용)을 읽고 company, position, requirements, keywords, deadline 등 핵심 정보를 정리한다.',
+      '`get_application_context`를 호출해 한 번에 프로필·대표 이력서·경력·프로젝트·스킬·기존 자기소개서·최근 지원 현황·이전 적합도 분석·같은 회사/직무 관련 기록·글쓰기 선호(preferred_tone, emphasis_points)를 가져온다. (분석 대상 공고가 이미 저장돼 있으면 job_id도 함께 전달한다.)',
+      '공고 요구사항과 사용자 경력/스킬/프로젝트를 비교한다: 일치하는 강점(strengths)과 부족한 부분(gaps), 매칭 키워드(matched_keywords)와 누락 키워드(missing_keywords)를 도출하고, 종합 적합도 점수(score 0~100)와 요약(summary), 지원 전략 제안(recommendations)을 정리한다. 없는 경험을 지어내지 않는다.',
+      '아직 저장되지 않은 공고라면 `save_job_posting`으로 공고를 저장하고 job_id를 확보한다.',
+      '도출한 분석 결과를 `save_fit_analysis`로 저장한다(job_id, score, summary, strengths, gaps, matched_keywords, missing_keywords, recommendations).',
+      '분석 결과를 사용자에게 쉬운 한국어로 설명한다(잘 맞는 점, 보완할 점, 추천 전략). 기술 용어는 빼고 전달한다.',
+      '"이 공고에 맞춘 자기소개서를 써드릴까요?"라고 자기소개서 작성을 제안한다.',
+      '사용자가 동의하면 자기소개서를 작성하기 직전에 `get_writing_style_guide`를 호출해 "AI 티 안 나는 글쓰기 규칙"을 가져온다.',
+      '적합도 분석·글쓰기 선호와 글쓰기 규칙을 함께 반영해 자기소개서를 작성하고(번역투·클리셰·기계적 병렬 제거, 사실·수치는 그대로), `save_cover_letter_version`으로 저장한다(job_id 연결, note에 작성 의도 요약).',
+      '`open_application`으로 해당 지원 건을 열어 사용자가 결과를 확인하게 하고, 지원 상태 변경(예: 지원 예정/지원 완료)을 제안한다.',
+    ],
+  },
+  {
+    id: 'write_cover_letter',
+    title: '자기소개서 작성',
+    description:
+      '특정 공고에 맞춘 자기소개서를 사용자 확인을 거쳐 작성하고 버전으로 저장하는 흐름.',
+    trigger:
+      '사용자가 "자기소개서 써줘 / 이 공고용 자소서 만들어줘"라고 요청하거나, 공고 분석 후 작성 제안에 동의했을 때.',
+    steps: [
+      '`get_application_context`(가능하면 job_id 포함)를 호출해 프로필·경력·프로젝트·스킬·기존 자기소개서·이전 적합도 분석·글쓰기 선호(preferred_tone, emphasis_points)를 가져온다.',
+      '작성 전에 대상 공고, 강조할 포인트, 톤, 분량을 사용자에게 확인한다(확인 없이 큰 작업을 진행하지 않는다).',
+      '`get_writing_style_guide`를 호출해 "AI 티 안 나는 글쓰기 규칙"(번역투·클리셰·기계적 병렬·상투적 연결어·균일한 문장 리듬 제거)을 가져온다.',
+      '저장된 실제 경험·성과만으로 자기소개서를 작성하되, 위 글쓰기 규칙을 적용해 사람이 쓴 듯 자연스럽게 쓴다(사실·수치·고유명사는 그대로). 빈칸이나 확인이 필요한 부분은 추측하지 말고 표시해 사용자에게 묻는다.',
+      '완성본을 `save_cover_letter_version`으로 저장한다(기존 자기소개서면 cover_letter_id, 새로 만들면 title, 공고용이면 job_id, 변경 요약은 note, source=ai).',
+      '사용자가 원하면 `export_cover_letter`로 파일로 내보내고, 추가 수정 요청이 있으면 새 버전으로 다시 저장한다.',
+      '저장 결과를 쉬운 한국어로 알리고, 지원 상태 업데이트(`update_application_status`)나 면접 준비 등 다음 단계를 제안한다.',
+    ],
+  },
+  {
+    id: 'manage_application_status',
+    title: '지원 상태 관리',
+    description:
+      '지원 진행 상황(8단계)을 업데이트하고 상태에 맞는 다음 행동을 제안하는 흐름.',
+    trigger:
+      '사용자가 "지원했어 / 서류 합격했어 / 면접 잡혔어 / 떨어졌어"처럼 진행 상황을 알리거나 상태 변경을 요청할 때.',
+    steps: [
+      '필요하면 `get_application_context` 또는 `get_job_posting`으로 대상 지원 건과 공고를 확인한다.',
+      '적절한 상태로 `update_application_status`를 호출한다. 8단계: draft(작성 중), planned(지원 예정), applied(지원 완료), document_passed(서류 합격), interview(면접 진행), final_passed(최종 합격), rejected(불합격), on_hold(보류). 변경 사유는 note에 남긴다.',
+      '변경 결과를 사용자에게 쉬운 한국어로 알린다.',
+      '상태에 맞는 다음 단계를 제안한다: applied → 결과 기다리기 안내, document_passed/interview → 면접 준비(prepare_interview) 제안, final_passed → 축하 및 마무리, rejected/on_hold → 회고 또는 다른 공고 탐색 제안.',
+      '필요하면 `open_application`으로 해당 지원 건을 열어 보여준다.',
+    ],
+  },
+  {
+    id: 'prepare_interview',
+    title: '면접 준비',
+    description:
+      '서류 합격 이후 예상 질문·STAR 답변·1분 자기소개를 준비해 저장하는 흐름.',
+    trigger:
+      '지원 상태가 서류 합격(document_passed) 또는 면접 진행(interview)으로 바뀌었을 때, 또는 사용자가 "면접 준비 도와줘"라고 요청할 때.',
+    steps: [
+      '`get_application_context`(job_id 포함)를 호출해 공고, 프로필, 경력/프로젝트, 적합도 분석(강점·갭), 자기소개서를 가져온다.',
+      '공고와 사용자 경험을 바탕으로 예상 면접 질문(question, intent, followups, answer_outline)을 도출한다.',
+      '핵심 경험에 대한 STAR 가이드(question, situation, task, action, result)와 1분 자기소개(self_introduction) 초안을 작성한다. 실제 경험만 사용한다.',
+      '준비 내용을 `save_interview_prep`로 저장한다(job_id, questions, star_guides, self_introduction, notes).',
+      '준비 내용을 사용자에게 쉬운 한국어로 요약해 전달하고, 모의 면접/추가 질문 연습이나 상태 업데이트(`update_application_status`로 interview/final_passed)를 제안한다.',
+    ],
+  },
+];

package/packages/workflows/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @careermate/workflows — public entry point.
+ *
+ * Re-exports the workflow data plus helpers to look up a single workflow and
+ * render it as readable Korean markdown (used in docs and MCP tool descriptions).
+ */
+export { WORKFLOWS } from './definitions.ts';
+export type { WorkflowDefinition } from './definitions.ts';
+
+import { WORKFLOWS, type WorkflowDefinition } from './definitions.ts';
+
+/** Look up a single workflow by id. Returns undefined if the id is unknown. */
+export function getWorkflow(id: string): WorkflowDefinition | undefined {
+  return WORKFLOWS.find((w) => w.id === id);
+}
+
+/**
+ * Render a workflow as a readable Korean markdown block. Used in documentation
+ * and as MCP tool descriptions so the AI can read the full step list inline.
+ * Returns undefined if the id is unknown.
+ */
+export function renderWorkflowMarkdown(id: string): string | undefined {
+  const wf = getWorkflow(id);
+  if (!wf) return undefined;
+
+  const lines: string[] = [];
+  lines.push(`# ${wf.title}`);
+  lines.push('');
+  lines.push(wf.description);
+  lines.push('');
+  lines.push(`**트리거:** ${wf.trigger}`);
+  lines.push('');
+  lines.push('## 단계');
+  wf.steps.forEach((step, i) => {
+    lines.push(`${i + 1}. ${step}`);
+  });
+  lines.push('');
+  return lines.join('\n');
+}