careermate 0.1.0

package/README.md

@@ -0,0 +1,256 @@
+# CareerMate
+
+**MCP 우선(MCP-first) 로컬 커리어 관리 도구.** 내 컴퓨터에서 동작하는 AI 에이전트(Claude Desktop·Claude Code·Codex 등)를 인터페이스로 쓰고, CareerMate는 당신의 커리어 데이터를 **이 컴퓨터에만** 저장한 뒤 MCP로 노출합니다.
+
+---
+
+## 핵심 철학
+
+- **MCP 우선** — 새 앱 사용법을 익힐 필요가 없습니다. 내 컴퓨터에서 동작하는 AI 에이전트(Claude Desktop·Claude Code·Codex 등 로컬 MCP 클라이언트)와 대화하면, 그 AI가 CareerMate의 로컬 MCP 도구를 호출해 당신의 커리어 DB를 읽고 씁니다.
+- **로컬 우선** — 모든 데이터는 당신의 컴퓨터에만 저장됩니다(`~/.careermate`). 외부 서버로 전송하지 않습니다. 대시보드 웹 서버는 `127.0.0.1`(이 컴퓨터)에만 연결됩니다.
+- **LLM 비내장** — CareerMate 안에는 AI가 들어 있지 않습니다. 분석·글쓰기 같은 “생각하는 일”은 **당신의 AI**가 하고, CareerMate는 데이터를 **안전하게 보관·조회**하는 역할만 합니다.
+
+> 쉽게 말해: 당신의 AI가 “두뇌”, CareerMate는 그 두뇌가 꺼내 쓰는 “커리어 서랍장”입니다.
+
+---
+
+## 무엇을 하나요?
+
+프로필·이력서·자기소개서·채용공고·지원 현황·면접 준비를 로컬 SQLite에 구조화해 저장하고, AI 어시스턴트가 MCP 도구로 그 데이터를 읽고 씁니다. 전형적인 흐름은 이렇습니다.
+
+1. 프로필·이력서 등록 → 2. 채용공고 저장·파싱 → 3. 적합도(핏) 분석 → 4. 맞춤 자기소개서 작성·버전 관리 → 5. 지원 상태 관리 → 6. 면접 준비
+
+언제든 대시보드를 열어 저장된 데이터를 눈으로 확인할 수 있습니다. 자세한 단계별 런북은 [`docs/START_WORKFLOW.md`](docs/START_WORKFLOW.md)를 참고하세요.
+
+---
+
+## 주요 기능
+
+- **AI와 대화로 모든 작업** — MCP 도구 24개로 온보딩·프로필·이력서·자소서·공고·핏 분석·지원 상태·면접 준비·AI 티 안 나는 글쓰기까지 처리.
+- **지원 상태 8단계 관리** — `draft`(작성 중) · `planned`(지원 예정) · `applied`(지원 완료) · `document_passed`(서류 합격) · `interview`(면접 진행) · `final_passed`(최종 합격) · `rejected`(불합격) · `on_hold`(보류). `document_passed` 이상에서 면접 준비가 해금됩니다.
+- **자기소개서 버전 관리** — 공고별로 자소서 버전을 쌓고 타임라인으로 비교, 파일로 내보내기.
+- **채용공고 파싱** — 붙여넣은 공고 텍스트를 구조화해 저장.
+- **로컬 대시보드** — 프레임워크·CDN 없는 바닐라 JS로 만든 7페이지 웹 화면(다크모드 지원).
+- **데이터 내보내기/삭제** — Settings 페이지에서 직접.
+
+---
+
+## 구성
+
+두 개의 로컬 프로세스가 같은 데이터베이스를 공유합니다.
+
+| 프로세스 | 실행 | 역할 |
+| --- | --- | --- |
+| **대시보드 웹 서버** | `npm start` | `http://127.0.0.1:4319` — 내 데이터를 눈으로 확인·관리. `127.0.0.1`에만 바인딩. |
+| **MCP 서버** | `npm run mcp` | stdio 기반. 보통 AI 클라이언트가 자동 실행. 도구 24개 제공. |
+
+---
+
+## 빠른 시작
+
+### 요구사항
+
+- **Node.js >= 22.5.0** — 내장 `node:sqlite`를 사용하므로 컴파일러나 네이티브 빌드가 **필요 없습니다**.
+- 버전 확인:
+  ```bash
+  node --version
+  ```
+  `v22.5.0` 미만이거나 명령을 찾지 못하면 https://nodejs.org 에서 최신 LTS를 설치하세요.
+
+### 1) 설치
+
+빌드 단계가 없습니다. TypeScript는 `tsx`로 바로 실행됩니다.
+
+```bash
+npm install
+```
+
+### 2) 대시보드 실행
+
+```bash
+npm start
+```
+
+- 기본 주소는 `http://127.0.0.1:4319` 이며 브라우저가 자동으로 열립니다.
+- 포트가 사용 중이면 자동으로 다음 빈 포트로 폴백하니, 터미널에 출력된 실제 주소를 확인하세요.
+- 종료는 터미널에서 `Ctrl+C`.
+
+### 3) 데모 데이터로 둘러보기(선택)
+
+빈 화면이 낯설다면 예시 데이터를 넣어 기능을 미리 체험할 수 있습니다.
+
+```bash
+npm run seed
+```
+
+### 4) AI(MCP)에 연결
+
+CareerMate는 **내 컴퓨터에서 로컬 stdio MCP 서버를 띄울 수 있는 AI**에서 동작합니다. (ChatGPT·Gemini의 웹/앱은 클라우드에서 동작해 로컬 stdio MCP 서버에 직접 연결할 수 없습니다.)
+
+v1에서 권장하는 연결 방식은 셋입니다. 아래 순서대로 골라 쓰세요.
+
+#### ① Claude Desktop 연결 (.mcpb 원클릭)
+
+터미널·Node 없이 가장 간단하게 붙이는 **하나의 연결 방법**입니다. `dist/careermate.mcpb`(`npm run build:mcpb`로 생성)를 더블클릭하거나 Claude Desktop의 **Settings → Extensions**로 끌어다 놓고, Claude Desktop을 재시작합니다.
+
+#### ② Claude Code
+
+CareerMate 폴더에서 Claude Code를 실행한 뒤, 이렇게 시켜 주세요.
+
+```
+CareerMate를 설치하고 설정해줘. INSTALL.md를 따라 진행해줘.
+```
+
+Claude Code가 [`INSTALL.md`](INSTALL.md) 런북을 따라 프로젝트 범위 `.mcp.json`을 쓰고 MCP 서버를 등록합니다. 첫 실행 시 프로젝트 서버에 대한 **일회성 승인**만 눌러 주면 됩니다.
+
+#### ③ Codex (OpenAI Codex CLI)
+
+CareerMate 폴더에서 Codex를 실행한 뒤, 같은 프롬프트로 시작합니다.
+
+```
+CareerMate를 설치하고 설정해줘. INSTALL.md를 따라 진행해줘.
+```
+
+Codex가 `~/.codex/config.toml`에 MCP 서버를 등록합니다. 연결은 Codex 안에서 `/mcp` 명령으로 확인하세요.
+
+> **기타 MCP 클라이언트(Cursor 등)** — Cursor·Cline·Windsurf 같은 로컬 stdio MCP 클라이언트는 `npm run init`(또는 `npm run init -- --print`)으로 등록할 수 있습니다.
+
+연결 후 AI 클라이언트를 **완전히 재시작**하고, `get_onboarding_status`를 호출해 달라고 시켜 연결을 검증하세요. 자세한 절차는 AI용 런북 **[`INSTALL.md`](INSTALL.md)**와 사람용 설치 가이드 **[`docs/INSTALL_AND_USAGE.md`](docs/INSTALL_AND_USAGE.md)**를 참고하세요.
+
+> **가장 간단한 길 — npx:** `careermate`가 npm에 게시되어 클론 없이 `npx -y careermate init` 한 줄로 등록됩니다. 소스 폴더에서 작업 중이면 `npm install` 후 `npm run init`을 써도 됩니다.
+
+---
+
+## 대시보드 7페이지
+
+| 페이지 | 설명 |
+| --- | --- |
+| **Home** | 현재 상태·다음 할 일 한눈에. |
+| **Profile** | 프로필, 경력(experiences), 프로젝트, 스킬 관리. |
+| **Jobs** | 저장한 채용공고 목록과 상세(공고 내용·핏 분석). |
+| **Applications** | 지원 현황을 8단계 상태로 보는 칸반 보드. |
+| **Documents** | 자기소개서 버전 타임라인과 이력서. |
+| **Interview** | 면접 준비 자료(`document_passed` 이상에서 해금). |
+| **Settings** | 데이터 내보내기·삭제, 환경 정보. |
+
+다크모드를 지원합니다.
+
+---
+
+## MCP 도구 한눈에 (24개)
+
+| 분류 | 도구 |
+| --- | --- |
+| 온보딩 | `get_onboarding_status` · `start_onboarding` |
+| 프로필 | `save_profile` · `get_profile` · `update_profile` |
+| 이력서 | `add_resume` · `get_resumes` |
+| 자기소개서 | `add_cover_letter` · `get_cover_letters` · `save_cover_letter_version` · `export_cover_letter` |
+| 채용공고 | `save_job_posting` · `get_job_posting` · `list_jobs` · `parse_job_posting` |
+| 핵심 컨텍스트 | **`get_application_context`** (지원에 필요한 맥락을 한 번에 모아줌) |
+| 핏 분석 | `save_fit_analysis` |
+| 지원 상태 | `update_application_status` |
+| 면접 준비 | `save_interview_prep` |
+| 글쓰기 | `get_writing_style_guide` (AI 티 안 나는 한국어 글쓰기 규칙) |
+| 대시보드/활동 | `open_dashboard` · `open_application` · `list_recent_activity` · `get_workflow_guide` |
+
+이 도구들 위에 5종의 워크플로우(`onboarding`, `analyze_job`, `write_cover_letter`, `manage_application_status`, `prepare_interview`)가 정의되어 있어, AI가 단계별로 자연스럽게 안내합니다.
+
+---
+
+## 프로젝트 구조
+
+```
+CareerMate/
+├─ apps/
+│  ├─ web/            # 대시보드 + 로컬 API 서버 (npm start)
+│  └─ mcp/            # MCP stdio 서버 (npm run mcp)
+├─ packages/
+│  ├─ shared/         # 공용 타입·zod 스키마·유틸
+│  ├─ db/             # node:sqlite DB 접근·스키마·마이그레이션
+│  ├─ core/           # 도메인 유스케이스
+│  ├─ mcp-tools/      # MCP 도구 24개 정의
+│  ├─ exporters/      # 내보내기(자소서 등)
+│  ├─ parsers/        # 채용공고 파싱
+│  ├─ prompts/        # 프롬프트·안내 문구
+│  └─ workflows/      # 워크플로우 5종
+├─ install-page/      # 설치 안내 페이지
+├─ docs/              # 문서
+├─ scripts/           # migrate / seed / doctor / test 등
+└─ package.json
+```
+
+- **스택**: TypeScript(ESM), 무빌드 실행(`tsx`), 내장 `node:sqlite`(네이티브 컴파일 없음), `zod`, `@modelcontextprotocol/sdk`. 대시보드는 프레임워크·CDN 없는 바닐라 JS + 자체 CSS 디자인 시스템.
+- **데이터 저장소**: 12개 테이블(profile, experiences, projects, skills, documents, cover_letters, cover_letter_versions, jobs, fit_analyses, applications, interview_preps, activities). 두 프로세스(대시보드·MCP)가 **같은 SQLite DB**를 공유합니다.
+
+---
+
+## npm 스크립트
+
+| 스크립트 | 설명 |
+| --- | --- |
+| `npm install` | 의존성 설치 (빌드 없음) |
+| `npm start` | 대시보드 웹 서버 실행 |
+| `npm run dev` | 대시보드 실행 (파일 변경 시 자동 재시작) |
+| `npm run mcp` | MCP 서버 실행 (stdio) |
+| `npm run migrate` | DB 생성/업그레이드 |
+| `npm run doctor` | 설치/환경 점검 |
+| `npm run seed` | 예시 데이터 삽입 |
+| `npm test` | E2E 테스트 실행 |
+| `npm run test:ui` | Playwright UI 스모크 테스트 |
+| `npm run typecheck` | 타입 검사 (`tsc --noEmit`) |
+
+---
+
+## 데이터 위치 & 환경변수
+
+- 기본 폴더: `~/.careermate` (Windows: `%USERPROFILE%\.careermate`).
+  - `careermate.sqlite` — 데이터베이스 파일
+  - `exports/` — 내보낸 파일
+  - `backups/` — 백업
+  - `uploads/` — 업로드 파일
+  - `server.json` — 실행 중 핸드셰이크 정보
+- 환경변수로 동작을 바꿀 수 있습니다.
+  - `CAREERMATE_DATA_DIR` — 데이터 폴더 위치 변경
+  - `CAREERMATE_PORT` — 대시보드 포트 고정
+  - `CAREERMATE_NO_OPEN` — 시작 시 브라우저 자동 열기 끄기
+
+---
+
+## 보안 / 프라이버시
+
+- **로컬 전용 바인딩** — 대시보드 서버는 `127.0.0.1`(loopback)에만 바인딩되어 외부에서 접근할 수 없습니다.
+- **DNS 리바인딩 차단** — Host 허용목록으로 검증.
+- **변경 요청 보호** — CSRF 세션 토큰(HTML `meta`로 주입), 외부 Origin 차단.
+- **정적 파일 보호** — 경로 traversal(상위 폴더 탈출) 차단.
+- **본문 크기 제한** — 요청 본문 8MB 제한.
+- **민감 정보 비노출** — 이력서·자기소개서 본문은 로그나 에러 응답에 노출되지 않습니다.
+- **외부 전송 없음** — MCP 서버는 네트워크 호출을 하지 않으며, 모든 데이터는 당신의 컴퓨터에만 남습니다. 내보내기·삭제는 대시보드 **Settings**에서 직접 할 수 있습니다.
+
+---
+
+## 문서
+
+- [`INSTALL.md`](INSTALL.md) — AI 어시스턴트가 따라가는 설치·연결 런북(소스 직접 실행 기준).
+- [`AGENTS.md`](AGENTS.md) — Codex용 영속 지침. / [`CLAUDE.md`](CLAUDE.md) — Claude Code용 영속 지침.
+- [`docs/SUPPORTED_AI_APPS.md`](docs/SUPPORTED_AI_APPS.md) — 지원하는 AI 앱과 연결 방식 정리.
+- [`docs/INSTALL_AND_USAGE.md`](docs/INSTALL_AND_USAGE.md) — 사람용 두 트랙 설치(.mcpb 원클릭 / 터미널)와 설치 후 사용법.
+- [`docs/START_WORKFLOW.md`](docs/START_WORKFLOW.md) — 등록부터 면접 준비까지 단계별 작업 런북.
+- [`docs/TODO.md`](docs/TODO.md) — 남은 작업과 v1 범위 밖 항목.
+
+---
+
+## 테스트
+
+```bash
+npm test        # E2E 테스트 (보안·업무흐름·MCP stdio·대시보드↔MCP 동일 DB 양방향)
+npm run test:ui # 대시보드 페이지 렌더 스모크 (Playwright)
+npm run typecheck
+```
+
+기타 유용한 스크립트: `npm run migrate`(DB 생성/업그레이드), `npm run seed`(예시 데이터), `npm run doctor`(설치·환경 점검).
+
+---
+
+## 라이선스
+
+MIT.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,40 @@
+# Third-Party Notices
+
+CareerMate에 포함된 일부 콘텐츠는 제3자 오픈소스에서 파생되었습니다. 해당 라이선스 고지를 아래에 보존합니다.
+
+---
+
+## im-not-ai (한국어 "AI 티 안 나는 글쓰기" 분류)
+
+- 출처: `epoko77-ai/im-not-ai` ("AI가 쓴 글이 아닌 것처럼 윤문해주는 스킬")
+- 라이선스: MIT
+- 사용 범위: `packages/prompts/src/humanize.ts`의 `HUMANIZE_WRITING_GUIDE`는 위 프로젝트의
+  한국어 AI-tell 분류(번역투·기계적 병렬·클리셰·상투적 연결어·균일한 문장 리듬 등)를
+  자기소개서·커리어 글쓰기용으로 압축·각색한 파생 저작물입니다. 원문을 그대로 복제하지 않았습니다.
+
+원본 라이선스(MIT) 전문:
+
+```
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+> 참고: 원 저장소의 정확한 저작권자 표기(`Copyright (c) <year> <holder>`)를 확인해
+> 위 전문 상단에 그대로 채워 넣는 것을 권장합니다.

package/apps/mcp/src/index.ts

@@ -0,0 +1,66 @@
+/**
+ * CareerMate MCP server (stdio).
+ *
+ * Launched by the AI client (Claude Desktop, ChatGPT, Cursor, …). It registers
+ * every CareerMate tool and talks to the SAME local SQLite database the
+ * dashboard uses, so anything the AI writes appears in the dashboard instantly,
+ * and anything the user edits in the dashboard is visible to the AI.
+ *
+ * Nothing here calls out to the network. All reasoning stays in the user's AI.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { getDb, getDataDir } from '@careermate/db';
+import { TOOLS, toCallToolResult } from '@careermate/mcp-tools';
+
+const APP_VERSION = '0.1.0';
+
+async function main(): Promise<void> {
+  // Ensure the DB is created/migrated before serving any tool call.
+  getDb();
+
+  const server = new McpServer(
+    { name: 'careermate', version: APP_VERSION },
+    {
+      instructions:
+        'CareerMate는 사용자의 로컬 커리어 데이터베이스입니다. 공고 분석이나 자기소개서 작성 전에는 항상 get_application_context를 먼저 호출해 사용자 정보를 가져오고, 결과는 save_fit_analysis / save_cover_letter_version 등으로 다시 저장하세요. 분석과 작성은 당신(AI)이 수행하고, CareerMate는 데이터를 제공·보관합니다. 모든 데이터는 사용자 로컬에만 저장됩니다.',
+    },
+  );
+
+  for (const tool of TOOLS) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: {
+          title: tool.title,
+          readOnlyHint: tool.readOnly ?? false,
+          openWorldHint: false,
+        },
+      },
+      async (args: unknown) => {
+        try {
+          const result = await tool.handler(args ?? {});
+          return toCallToolResult(result);
+        } catch (err) {
+          // Never leak document bodies; return a safe message.
+          const message = err instanceof Error ? err.message : '도구 실행 중 오류가 발생했습니다.';
+          return toCallToolResult({ text: message, isError: true });
+        }
+      },
+    );
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // IMPORTANT: never write to stdout — it is the MCP transport. Logs go to stderr.
+  console.error(`[careermate-mcp] 연결됨 · 도구 ${TOOLS.length}개 · 데이터: ${getDataDir()}`);
+}
+
+main().catch((err) => {
+  console.error('[careermate-mcp] 시작 실패:', err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/apps/web/DESIGN_GUIDE.md

@@ -0,0 +1,105 @@
+# CareerMate 대시보드 — 디자인 가이드 (안티-AI-슬롭 규칙집)
+
+이 문서는 CareerMate 웹 대시보드의 **디자인 원칙과 컨벤션**입니다. `UI_CONTRACT.md`가 "페이지를 *어떻게* 짜는가(컴포넌트·API 계약)"라면, 이 문서는 "결과물이 *어떻게 보여야 하는가*"를 규정합니다. **새 화면을 만들거나 기존 화면을 고치기 전에 반드시 읽고**, 마지막의 감사 체크리스트로 자가 점검하세요.
+
+근거: Anthropic `frontend-design`/`interface-design` 스킬, Linear·Vercel(Geist)·Notion·Stripe·shadcn 디자인 가이드, Refactoring UI, Polaris, NN/g. (출처는 맨 아래.)
+
+> 북극성: **"누가 봐도 AI가 만든 것 같다"의 반대.** 차분하고 밀도 있고, 정보가 먼저 오고, 장식이 아니라 위계로 말한다. Linear/Notion/Raycast의 절제.
+
+---
+
+## 0. AI 슬롭 5대 증상 (이 프로젝트에서 실제로 발견된 것)
+
+1. **제목 중복** — 같은 단어가 사이드바 active + 상단바 + 페이지 `<h1>`로 3번.
+2. **버튼 중복** — 동일한 1차 액션("공고 추가")이 상단바 + 페이지헤더 + 빈 상태에 동시에.
+3. **필러 설명문** — 제목을 그대로 풀어 쓴 "…를 한눈에 보고 …확인/관리하세요".
+4. **반복 보일러플레이트** — "ChatGPT/Claude에게 …하면 자동으로 저장됩니다"가 화면마다.
+5. **과한 카드화** — 빈 상태 하나도 카드로 감싸고, 카드 안에 카드.
+
+이 5가지가 보이면 슬롭입니다. 아래 규칙으로 제거합니다.
+
+---
+
+## 1. 핵심 규칙 (Rulebook)
+
+1. **제목은 한 곳에만 — 상단바.** 현재 화면 제목은 **앱 셸 상단바**가 한 번만 표시한다(사이드바 active는 위치 표시일 뿐, 콘텐츠에서 제목을 반복하지 않는다). 인덱스 페이지(채용공고/지원현황/문서/면접/프로필)에는 in-content `PageHead` `<h1>`·설명을 **두지 않고** 곧장 콘텐츠로 시작. 예외: 상세(`jobs/:id`)는 회사명을 in-content `<h1>`으로 가진다(nav가 못 보여주는 콘텐츠).
+2. **1차 액션은 한 개, 한 곳(상단바 `ctx.setActions`).** `PageHead({actions})`·빈 상태의 중복 버튼 금지. 리스트가 비었을 때만 빈 상태에 생성 CTA를 두고, 그 핸들러는 상단바와 동일.
+3. **필러 설명 금지.** 설명 줄은 *수치·제약·상태·자명하지 않은 이유*를 말할 때만 허용. 제목을 바꿔 말하면 삭제. **"한눈에" 금지.**
+4. **설정/MCP 안내는 단 한 곳(홈 '시작하기' 카드)에만.** 빈 상태는 화면별 **고유 한 문장**. "ChatGPT/Claude에게 …저장됩니다" 반복·`MCP_HINT` 공용 상수 금지.
+5. **위계는 타이포·여백으로, 박스로 X.** 단일 빈 상태/단일 블록을 `.card`로 감싸지 않는다. 카드는 **반복·선택 가능한 객체**(공고 행, 자소서, 보드 카드)에만. **카드 in 카드 금지.**
+6. **악센트(인디고)는 절제.** 1차 버튼·링크·포커스 링·active nav에만. **장식용 보라 그라데이션 금지** (`.sidebar__logo`, `.progress__bar`의 `135deg accent→#7c3aed`는 평면 `var(--accent)`로). 코드에 raw hex 금지 — 색은 CSS 변수로만.
+7. **버튼 라벨은 동사+명사, 흐름 내내 일관.** 모달 저장 버튼은 `저장`이 아니라 **`공고 저장`/`경력 저장`**. 생성 라벨과 성공 토스트의 명사가 일치(`공고 저장`→`공고를 저장했습니다`). 맨동사는 `취소`·`닫기`·`복사`만.
+8. **인덱스 페이지는 툴바+행으로 직행.** 설명 헤더 블록은 settings/profile/온보딩/상세에만. 상세(`jobs/:id`)의 회사명 `<h1>`은 nav가 못 보여주는 *콘텐츠*이므로 유일한 정당한 예외.
+9. **숫자 열은 우정렬 + `.tnum`.** 적합도 점수·파일 크기 등은 `text-align:right`로 자릿수를 정렬.
+10. **여백은 스케일에 스냅.** 4/8/12/16/24/32. 페이지 모듈의 일회성 인라인 px(`'9px'`, `'8px 0'`, `'440px'`…) 금지 — `.stack-*`/`.gap-*`/`.mt-*` 유틸 또는 토큰 사용.
+
+---
+
+## 2. 감사 체크리스트 (커밋 전 grep)
+
+```
+한눈에                         → 0건이어야 함 (필러 설명 시그니처)
+확인하세요|관리하세요|관리하고   → 제목 재진술 설명이면 삭제
+ChatGPT/Claude|자동으로 저장     → 최대 1건(홈 시작하기 카드)
+MCP_HINT                        → 삭제 (화면별 고유 문구로)
+공고 추가 (단일 1차 라벨)        → 한 화면에 1번만
+Btn('저장'                      → 동사+명사로 (공고 저장 등)
+linear-gradient (styles.css)    → 장식 보라 그라데이션 2건 제거
+#7c3aed / pages 내 raw hex       → CSS 변수로
+Card( 가 EmptyState( 를 감쌈     → 카드 제거
+class:'card' in card body        → 카드 in 카드 제거
+PageHead( (인덱스 페이지)        → 제거 (상단바 제목으로 충분; 홈 인사·jobs 상세만 허용)
+```
+
+추가 육안 테스트(페이지마다):
+- **눈 가늘게 뜨기 테스트**: 채워진 인디고 버튼은 정확히 1개. 2개가 경쟁하면 하나를 ghost로 강등.
+- **h1 개수**: 인덱스 0개(사이드바가 제목) / 상세·설정·프로필 1개. h1→h3 건너뜀 없음.
+- **빈 상태 형태**: 제목 + 고유 한 문장 + (있다면) 버튼 1개. 검색결과 없음은 '필터 초기화'지 생성 CTA가 아님.
+
+---
+
+## 3. 페이지 셸 컨벤션 (제목·액션의 단일 출처)
+
+- **제목** = 상단바(`#topbar-title`). `app.js`가 nav 라벨로 한 번 설정하며, 콘텐츠 안에서 이를 반복하지 않는다(인덱스 페이지 in-content `PageHead` 제거). 상세 페이지는 `ctx.setTitle()`로 맥락(회사명 등)을 덮어쓴다.
+- **1차 액션** = 상단바 `#topbar-actions`(`ctx.setActions([...])`), 우측 정렬. 화면당 최대 1개의 `btn--primary`.
+- **PageHead 사용처**: 홈(인사 배너), 프로필·설정(h1 + 진짜 상태 줄), 공고 상세(회사명 in-content 헤더). 그 외 인덱스 페이지에서는 사용하지 않음.
+- 모든 라우트에서 이전 페이지 액션이 새지 않도록 `clear(actionsEl)` 유지(이미 됨).
+
+---
+
+## 4. 마이크로카피 규칙 (예시 포함)
+
+- **길이 예산**: 페이지 제목 ≤ 약 12자(명사구) · 버튼 2~4단어 · 빈 상태 본문 한 문장 ≤ 약 40자 · 에러는 "무엇이 왜 + 어떻게"를 한 문장.
+- **빈 상태(화면별 고유, MCP 설명 없이)**
+  - 채용공고: `저장된 공고가 없어요` / `관심 있는 채용공고를 추가해 적합도와 진행 상태를 관리해 보세요.` · CTA `공고 추가`
+  - 적합도(상세): `적합도 분석 전이에요` / `이 공고와 내 프로필을 비교한 분석 결과가 여기에 표시됩니다.`
+  - 자기소개서: `아직 자기소개서가 없어요` / `작성하거나 붙여넣어 버전과 함께 보관하세요.` · CTA `새 자기소개서`
+  - 면접: `면접 준비 자료가 아직 없어요` / `예상 질문과 1분 자기소개를 정리해 두면 한곳에서 연습할 수 있어요.`
+  - 문서: `저장된 문서가 없어요` / `이력서·경력기술서·포트폴리오 텍스트를 보관하세요.` · CTA `문서 추가`
+  - 검색결과 없음: `조건에 맞는 항목이 없어요` + `필터 초기화` (생성 CTA 아님)
+- **버튼·토스트 일치**: `공고 저장`→`공고를 저장했습니다`. 에러는 제품 보이스로(`회사와 직무를 입력해야 저장할 수 있어요.`), 막연한 `오류` 금지.
+- **자격 미달 상태**(면접 단계 전, 분석 전)는 가짜 CTA 대신 차분한 설명 한 줄, 버튼 없음.
+
+---
+
+## 5. 패턴별 지침
+
+- **페이지 헤더**: 인덱스는 헤더 없이 툴바+리스트로 직행. 설명 줄은 수치/상태만(`면접 준비 대상 ${n}곳`처럼).
+- **버튼 위계**: 화면당 `btn--primary` 1개. 보조는 `btn--ghost`/텍스트. 상세 페이지의 `수정`은 상단바 1개만, `삭제`는 위험 액션이므로 보조/케밥으로.
+- **리스트/테이블**: 1px 하단 헤어라인, 균일 패딩, 숫자 열 우정렬+`.tnum`, 클릭 행 ≥44px. 가능하면 `ListRow` 프리미티브 재사용.
+- **빈 상태**: `EmptyState` 컴포넌트만(카드로 감싸지 않음). 제목+한 문장+버튼≤1.
+- **카드/과카드화**: `.card`는 반복·선택 객체에만. 단일 빈 상태·프로필 하위 항목·모달 내부 행은 카드로 감싸지 말고 `.stack-*`+`.divider`로 구분. 카드 in 카드 금지.
+- **여백·타이포·색**: 인라인 px → 유틸/토큰(4/8/12/16/24/32). 3단계 텍스트 램프(`--text`/`--text-secondary`/`--text-tertiary`) 유지. heading weight ≤ 650 유지(이미 됨). 보라 그라데이션 제거, 악센트는 평면.
+- **폰트**: Pretendard를 **self-host**(`/fonts/PretendardVariable.woff2` + `@font-face`)해 시스템 폴백이 아니라 의도한 서체가 모든 기기에서 항상 렌더되게 한다. *선언만 하고 로드 안 하면 결국 Segoe UI·맑은 고딕 같은 시스템 기본(=제네릭)으로 떨어진다 — "디폴트는 인프라에 숨는다".* Inter/Roboto/Arial 같은 "AI 디폴트 폰트"는 1차 서체·폴백 어디에도 쓰지 않는다.
+
+---
+
+## 출처
+- Anthropic `frontend-design` 스킬 — <https://raw.githubusercontent.com/anthropics/skills/main/skills/frontend-design/SKILL.md>
+- Anthropic `claude-code` frontend-design 플러그인 — <https://raw.githubusercontent.com/anthropics/claude-code/main/plugins/frontend-design/skills/frontend-design/SKILL.md>
+- `interface-design` principles — <https://raw.githubusercontent.com/Dammyjay93/interface-design/main/.claude/skills/interface-design/references/principles.md>
+- awesome-design-md: Linear / Vercel(Geist) / Notion / Stripe DESIGN.md — <https://github.com/VoltAgent/awesome-design-md>
+- Geist Button — <https://vercel.com/geist/button> · Polaris Page actions — <https://polaris-react.shopify.com/components/page-actions>
+- Reverse engineering Linear (Header) — <https://pustelto.com/blog/reverse-engineer-linear-1-header/>
+- NN/g Headlines & Page Titles — <https://www.nngroup.com/articles/microcontent-how-to-write-headlines-page-titles-and-subject-lines/>
+- Refactoring UI 요약 · Impeccable slop catalogue — <https://impeccable.style/slop/>

package/apps/web/UI_CONTRACT.md

@@ -0,0 +1,44 @@
+# CareerMate dashboard — page module contract
+
+> **먼저 `DESIGN_GUIDE.md`(디자인 원칙·안티-AI-슬롭 규칙)를 읽으세요.** 이 문서는 *어떻게 짜는가*(컴포넌트·API), `DESIGN_GUIDE.md`는 *어떻게 보여야 하는가*(위계·카피·셸 컨벤션)를 규정합니다.
+
+Read this + `DESIGN_GUIDE.md` + `apps/web/public/pages/home.js` (the reference implementation) before writing any page. Every page must look and behave like home.js. No frameworks, no build, no CDN. Korean-first. **XSS-safe: never use innerHTML with user/DB content — `el()` puts strings into textContent. Render document/cover-letter bodies as text inside a `.doc-preview` element (CSS already does `white-space: pre-wrap`).**
+
+## File shape
+Create `apps/web/public/pages/<name>.js`:
+```js
+import { el, get, post, put, del, icon, navigate, Card, Badge, Btn, IconBtn, Stat,
+  EmptyState, Chips, Field, Input, Textarea, Select, PageHead, openModal, closeModal,
+  confirmDialog, toast, toastOk, toastError, copyText, downloadUrl, fmtDate, fmtRelative,
+  scoreClass, mount, meta } from '/lib.js';
+
+export async function render(ctx) {
+  // fetch data, build a root node, then:  mount(ctx.view, root);
+  // set page actions in the topbar:  ctx.setActions([Btn(...)]);
+  // after any mutation that changes counts: await ctx.refreshNav();
+}
+```
+`ctx = { view, params, setTitle(str), setActions(node|nodes), navigate, refreshNav }`. `params` are the path segments after the page id (e.g. `#/jobs/abc` → params=['abc']).
+
+## lib.js component API (use these — do not hand-roll styles)
+- `el(tag, props, ...children)` — props: class, text, value, placeholder, type, href, disabled, dataset:{}, style:{}, attrs:{}, onClick/onInput/onChange/onSubmit/onKeydown. children: strings (safe text) or nodes; null/false ignored; arrays flattened.
+- `icon(name, cls?)` → svg. Names: home,user,briefcase,layers,file,mic,settings,plus,edit,trash,copy,download,external,check,sparkle,clock,link,lock,search,inbox,target,info,chevronRight.
+- API: `get(path)`, `post(path,body)`, `put(path,body)`, `del(path)` → parsed JSON; throw Error(message) on failure (wrap mutations in try/catch + toastError).
+- Components: `Card({title,sub,actions,body,clickable,onClick})`, `Stat({label,value,hint,iconName})`, `Badge(statusCode,label)`, `Btn(label,{icon,variant,sm,onClick,type,disabled,title})` (variant: primary|ghost|danger), `IconBtn(name,{onClick,title,variant})`, `EmptyState({iconName,title,body,action})`, `Chips(items,{accent})`, `ListRow({leading,title,sub,trailing,onClick})` (dense list row — leading node + title/sub + right-aligned trailing node(s); becomes clickable when onClick is set), `CheckRow({done,label,onClick})` (onboarding checklist row — hollow dot + accent link when todo, green check + strikethrough when done), `Field(label,control,hint)`, `Input(props)`, `Textarea(props)`, `Select(options,props)` where options=[{value,label,selected}], `PageHead({title,desc,actions})`.
+- Overlays: `openModal({title, body, footer, size})` — body is a node or `(close)=>node`; footer is `(close)=>node|nodes`; size 'lg' optional. `closeModal()`. `confirmDialog({title,message,confirmLabel,danger})` → Promise<boolean>.
+- Feedback: `toast(msg,{title,type})`, `toastOk(msg)`, `toastError(err)`.
+- Utils: `copyText(str)`, `downloadUrl(url)` (GET file download), `fmtDate(iso)`, `fmtRelative(iso)`, `scoreClass(score)` → 'score-strong|score-mid|score-weak|muted', `mount(view, ...nodes)`, `meta()` → {statuses:[{value,label}], document_kinds:[{value,label}]}.
+
+## CSS classes available (styles.css) — reuse, don't invent
+Layout: `.stack-2/.stack-3/.stack-4` (vertical gap), `.grid .grid--2/3/4`, `.flex .between .center .wrap .gap-2/3/4 .ml-auto`, `.divider`, `.mt-2..4 .mb-2..4`.
+Surfaces: `.card .card__head .card__body`, `.stat`, `.callout .callout--privacy`, `.doc-preview`, `.kv`(dt/dd), `.timeline .tl-item .tl-item__rail .tl-item__dot .tl-item__line .tl-item__body` (+`.is-current`), `.board .board__col .board__col-head .board__cards .board-card` (kanban).
+Lists/feed/pipeline (prefer the `ListRow`/`CheckRow` helpers over these classes): `.list-row .list-row__lead(.--chip) .list-row__dot .list-row__main .list-row__title .list-row__sub .list-row__trail`, `.pipebar .pipebar__seg` + `.pipefunnel .pipefunnel__tile .pipefunnel__label .pipefunnel__dot .pipefunnel__value .pipefunnel__conv` (application funnel), `.check-row(.is-done) .check-row__dot .check-row__icon .check-row__label(.is-link)`, `.feed-group .feed-item .feed-item__icon .feed-item__body .feed-item__text .feed-item__time`, `.firstrun-hero` (day-one single-card canvas).
+Bits: `.badge .badge--<status>`, `.chip .chip--accent .chips`, `.btn ...`, `.input .textarea .select .field`, `.progress .progress__bar`, `.tabs .tab .is-active`, `.table`, `.empty`, `.muted .text-sm .text-secondary .strong .truncate .tnum`, score colors `.score-strong/.score-mid/.score-weak`.
+Status codes (for Badge + classes): draft(작성 중), planned(지원 예정), applied(지원 완료), document_passed(서류 합격), interview(면접 진행), final_passed(최종 합격), rejected(불합격), on_hold(보류).
+
+## Conventions
+- Build forms with Field+Input/Textarea/Select inside `openModal`; submit → post/put → toastOk → closeModal → re-render the page (re-run render or refetch+remount) → `ctx.refreshNav()` if counts changed.
+- Always provide a friendly empty state (see home.js) with an action.
+- Tables/rows that navigate use `class:'is-clickable'` + onClick navigate.
+- Dense, calm, real-product feel. Avoid emoji-heavy or flashy "AI" styling.
+- Tabs: render a `.tabs` bar; clicking re-renders the panel; keep selected tab in a local variable (or in `location.hash` query if you prefer, but local is fine).

package/apps/web/public/app.js

@@ -0,0 +1,118 @@
+// =============================================================================
+// CareerMate dashboard shell — hash router, sidebar, and page orchestration.
+// Page modules live in /pages/*.js and export `render(ctx)`. They receive a ctx
+// with { view, params, setTitle, setActions, refreshNav } and fill the view.
+// =============================================================================
+import { el, icon, get, navigate, toastError, Spinner, clear } from '/lib.js';
+
+const ROUTES = [
+  { id: 'home', label: '홈', icon: 'home', module: '/pages/home.js' },
+  { id: 'profile', label: '프로필', icon: 'user', module: '/pages/profile.js' },
+  { id: 'jobs', label: '채용공고', icon: 'briefcase', module: '/pages/jobs.js', countKey: 'jobs' },
+  { id: 'applications', label: '지원 현황', icon: 'layers', module: '/pages/applications.js', countKey: 'active_applications' },
+  { id: 'documents', label: '문서', icon: 'file', module: '/pages/documents.js', countKey: 'cover_letters' },
+  { id: 'interview', label: '면접 준비', icon: 'mic', module: '/pages/interview.js', countKey: 'interview_pending' },
+  { id: 'settings', label: '설정', icon: 'settings', module: '/pages/settings.js' },
+];
+
+const view = document.getElementById('view');
+const navEl = document.getElementById('nav');
+const titleEl = document.getElementById('topbar-title');
+const actionsEl = document.getElementById('topbar-actions');
+const moduleCache = new Map();
+
+function parseHash() {
+  const raw = location.hash.replace(/^#\/?/, '');
+  const segments = raw.split('/').filter(Boolean);
+  return { page: segments[0] || 'home', params: segments.slice(1) };
+}
+
+function renderNav(counts = {}) {
+  clear(navEl);
+  navEl.append(el('div', { class: 'nav__label' }, '워크스페이스'));
+  const { page } = parseHash();
+  for (const r of ROUTES) {
+    if (r.id === 'settings') navEl.append(el('div', { class: 'nav__label' }, '시스템'));
+    const count = r.countKey ? counts[r.countKey] : null;
+    navEl.append(el('a', {
+      class: `nav__item${page === r.id ? ' is-active' : ''}`,
+      href: `#/${r.id}`,
+    }, icon(r.icon), el('span', {}, r.label),
+      count ? el('span', { class: 'nav__badge tnum' }, String(count)) : null));
+  }
+}
+
+async function refreshNav() {
+  try {
+    const summary = await get('/api/summary');
+    renderNav(summary.counts);
+  } catch {
+    renderNav();
+  }
+}
+
+async function loadModule(path) {
+  if (moduleCache.has(path)) return moduleCache.get(path);
+  const mod = await import(path);
+  moduleCache.set(path, mod);
+  return mod;
+}
+
+let renderToken = 0;
+async function route() {
+  const token = ++renderToken;
+  const { page, params } = parseHash();
+  const def = ROUTES.find((r) => r.id === page) || ROUTES[0];
+
+  // active nav state
+  navEl.querySelectorAll('.nav__item').forEach((n) => n.classList.toggle('is-active', n.getAttribute('href') === `#/${def.id}`));
+  titleEl.textContent = def.label;
+  clear(actionsEl);
+  view.scrollTop = 0;
+  window.scrollTo(0, 0);
+
+  const ctx = {
+    view,
+    params,
+    setTitle: (t) => { titleEl.textContent = t; },
+    setActions: (nodes) => { clear(actionsEl); [].concat(nodes).filter(Boolean).forEach((n) => actionsEl.append(n)); },
+    navigate,
+    refreshNav,
+  };
+
+  clear(view);
+  view.append(Spinner());
+  try {
+    const mod = await loadModule(def.module);
+    if (token !== renderToken) return; // a newer navigation superseded this one
+    clear(view);
+    await mod.render(ctx);
+  } catch (err) {
+    if (token !== renderToken) return;
+    clear(view);
+    view.append(el('div', { class: 'card' }, el('div', { class: 'card__body' },
+      el('h3', { style: { marginBottom: '8px' } }, '페이지를 불러오지 못했습니다'),
+      el('p', { class: 'text-secondary' }, err instanceof Error ? err.message : String(err)))));
+    toastError(err);
+  }
+}
+
+function initTheme() {
+  const saved = localStorage.getItem('cf-theme');
+  if (saved === 'light' || saved === 'dark') document.documentElement.dataset.theme = saved;
+}
+
+async function boot() {
+  initTheme();
+  // Show data location in the footer (privacy: user can always see where data lives).
+  try {
+    const h = await get('/api/health');
+    document.getElementById('foot-path').textContent = h.data_dir;
+    document.getElementById('foot-path').title = h.data_dir;
+  } catch { /* ignore */ }
+  await refreshNav();
+  window.addEventListener('hashchange', route);
+  await route();
+}
+
+boot();