careermate 0.1.1 → 0.1.2

package/apps/web/public/lib.js

@@ -10,6 +10,19 @@
 
 /* --------------------------------------------------------------- DOM helper */
 
+/**
+ * Neutralize script-capable URL schemes before they reach an href/src. Career
+ * data (profile links, job URLs) is user-controlled and can arrive via the MCP
+ * path with no CSRF gate, so a stored `javascript:…` link would execute when
+ * clicked. http(s)/mailto and scheme-less/relative URLs pass through unchanged;
+ * any other explicit scheme is replaced with a harmless '#'.
+ */
+export function safeUrl(v) {
+  const s = String(v).trim();
+  if (/^[a-z][a-z0-9+.-]*:/i.test(s)) return /^(https?:|mailto:)/i.test(s) ? s : '#';
+  return s;
+}
+
 /**
  * Create an element. `props` may include: class, id, type, value, placeholder,
  * href, title, disabled, dataset:{}, style:{}, attrs:{}, and on* event handlers
@@ -27,7 +40,19 @@ export function el(tag, props = {}, ...children) {
     else if (k === 'dataset') Object.assign(node.dataset, v);
     else if (k === 'style') Object.assign(node.style, v);
     else if (k === 'attrs') for (const [a, val] of Object.entries(v)) node.setAttribute(a, val);
+    else if (k === 'href' || k === 'src') node.setAttribute(k, safeUrl(v)); // block javascript:/data: URLs
     else if (k.startsWith('on') && typeof v === 'function') node.addEventListener(k.slice(2).toLowerCase(), v);
+    else if (k === 'activate' && typeof v === 'function') {
+      // Make a non-native element behave like a button for keyboard + AT users:
+      // role, focusability, and Enter/Space activation. Use this instead of a bare
+      // onClick on clickable <div>/<span> so they aren't mouse-only dead zones.
+      if (!node.getAttribute('role')) node.setAttribute('role', 'button');
+      if (node.getAttribute('tabindex') == null) node.setAttribute('tabindex', '0');
+      node.addEventListener('click', v);
+      node.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); v(e); }
+      });
+    }
     else if (k in node) { try { node[k] = v; } catch { node.setAttribute(k, v); } }
     else node.setAttribute(k, v);
   }
@@ -40,7 +65,6 @@ function appendChildren(node, children) {
     node.append(c instanceof Node ? c : document.createTextNode(String(c)));
   }
 }
-export function frag(...children) { const f = document.createDocumentFragment(); appendChildren(f, children); return f; }
 export function clear(node) { while (node.firstChild) node.removeChild(node.firstChild); return node; }
 export function mount(node, ...children) { clear(node); appendChildren(node, children); return node; }
 
@@ -94,19 +118,33 @@ const TOKEN = document.querySelector('meta[name="careermate-token"]')?.content |
 
 /** Call the JSON API. Throws Error(message) on non-2xx. */
 export async function api(method, path, body) {
-  const res = await fetch(path, {
-    method,
-    headers: {
-      'Content-Type': 'application/json',
-      ...(method !== 'GET' ? { 'x-careermate-token': TOKEN } : {}),
-    },
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
+  let res;
+  try {
+    res = await fetch(path, {
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(method !== 'GET' ? { 'x-careermate-token': TOKEN } : {}),
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+  } catch {
+    // Connection failure (server stopped, machine asleep) — never surface "Failed to fetch".
+    throw new Error('서버에 연결하지 못했어요. 대시보드가 실행 중인지 확인한 뒤 다시 시도해 주세요.');
+  }
   const text = await res.text();
-  const data = text ? JSON.parse(text) : {};
-  if (!res.ok) throw new Error(data.error || `요청 실패 (${res.status})`);
+  let data = {};
+  if (text) { try { data = JSON.parse(text); } catch { /* non-JSON error page */ } }
+  if (!res.ok) throw new Error(data.error || friendlyStatus(res.status));
   return data;
 }
+// Friendly fallback when the server didn't supply a message — never show a raw status code.
+function friendlyStatus(status) {
+  if (status === 404) return '요청한 항목을 찾을 수 없어요. 새로고침 후 다시 시도해 주세요.';
+  if (status === 403) return '권한 확인이 필요해요. 대시보드를 새로고침해 주세요.';
+  if (status >= 500) return '일시적인 오류가 발생했어요. 잠시 후 다시 시도해 주세요.';
+  return '요청을 처리하지 못했어요. 입력을 확인하고 다시 시도해 주세요.';
+}
 export const get = (p) => api('GET', p);
 export const post = (p, b) => api('POST', p, b);
 export const put = (p, b) => api('PUT', p, b);
@@ -134,6 +172,22 @@ export function scoreClass(score) {
   if (score >= 50) return 'score-mid';
   return 'score-weak';
 }
+/** Textarea (newline-separated) → trimmed array, empties dropped. */
+export function linesToArray(str) { return String(str || '').split('\n').map((s) => s.trim()).filter(Boolean); }
+/** CSV ("a, b, c") → trimmed array, empties dropped. */
+export function csvToArray(str) { return String(str || '').split(',').map((s) => s.trim()).filter(Boolean); }
+
+/**
+ * Application status code → saturated theme colour. Single source of truth so a
+ * colour means the same pipeline stage everywhere (home pipeline bar/dots,
+ * applications board dots, badges). MUST track the badge--{status} hues in CSS.
+ */
+export const STATUS_COLOR = {
+  draft: 'var(--slate)', planned: 'var(--blue)', applied: 'var(--violet)',
+  document_passed: 'var(--teal)', interview: 'var(--amber)',
+  final_passed: 'var(--green)', on_hold: 'var(--slate)', rejected: 'var(--red)',
+};
+export const statusColor = (code) => STATUS_COLOR[code] || 'var(--text-tertiary)';
 
 /* ---------------------------------------------------------------- routing */
 export function navigate(hash) { location.hash = hash.startsWith('#') ? hash : '#' + hash; }
@@ -149,17 +203,50 @@ export function Btn(label, { icon: ic, variant = '', sm, onClick, type, disabled
 export function IconBtn(name, { onClick, title, variant = 'ghost' } = {}) {
   return el('button', { class: `btn btn--${variant} icon-btn`, onClick, title, attrs: { 'aria-label': title || name } }, icon(name));
 }
+/**
+ * A footer button for async saves. While `action()` runs the button is disabled
+ * (so a slow local round-trip can't be double-clicked into duplicate records),
+ * and if it throws the message is shown in the modal's persistent `.modal__error`
+ * slot (not a transient toast) so the user sees why the save failed and can fix
+ * and retry. `action` should THROW on failure (validation or API) and is expected
+ * to call close()/reload() itself on success.
+ */
+export function SubmitBtn(label, action, { variant = 'primary', icon: ic } = {}) {
+  let busy = false;
+  const btn = Btn(label, {
+    variant,
+    icon: ic,
+    onClick: async () => {
+      if (busy) return;
+      busy = true;
+      btn.disabled = true;
+      const slot = btn.closest('.modal')?.querySelector('.modal__error');
+      if (slot) { slot.hidden = true; slot.textContent = ''; }
+      try {
+        await action();
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (slot) { slot.textContent = msg; slot.hidden = false; slot.scrollIntoView?.({ block: 'nearest' }); }
+        else toastError(e);
+      } finally {
+        busy = false;
+        btn.disabled = false;
+      }
+    },
+  });
+  return btn;
+}
 export function Card({ title, sub, actions, body, clickable, onClick } = {}) {
   const head = (title || actions) && el('div', { class: 'card__head' },
     title && el('h3', {}, title),
     sub && el('span', { class: 'sub' }, sub),
     actions && el('div', { class: 'right' }, ...[].concat(actions)),
   );
-  return el('div', { class: `card${clickable ? ' is-clickable' : ''}`, onClick },
+  return el('div', { class: `card${clickable ? ' is-clickable' : ''}`, activate: onClick },
     head, el('div', { class: 'card__body' }, ...[].concat(body || [])));
 }
-export function Stat({ label, value, hint, iconName }) {
-  return el('div', { class: 'stat' },
+export function Stat({ label, value, hint, iconName, onClick }) {
+  return el('div', { class: 'stat', activate: onClick },
     el('div', { class: 'stat__label' }, iconName && icon(iconName), label),
     el('div', { class: 'stat__value tnum' }, value),
     hint && el('div', { class: 'stat__hint' }, hint),
@@ -178,7 +265,7 @@ export function Chips(items, { accent } = {}) {
 }
 /** Dense list row: leading slot → title + muted sub → right-aligned trailing. */
 export function ListRow({ leading, title, sub, trailing, onClick } = {}) {
-  return el('div', { class: `list-row${onClick ? ' is-clickable' : ''}`, onClick },
+  return el('div', { class: `list-row${onClick ? ' is-clickable' : ''}`, activate: onClick },
     leading && el('div', { class: 'list-row__lead' }, leading),
     el('div', { class: 'list-row__main' },
       el('div', { class: 'list-row__title' }, title),
@@ -187,9 +274,11 @@ export function ListRow({ leading, title, sub, trailing, onClick } = {}) {
 }
 /** Onboarding checklist row: hollow dot (todo, links via onClick) or green check (done, struck through). */
 export function CheckRow({ done, label, onClick } = {}) {
-  return el('div', { class: `check-row${done ? ' is-done' : ''}` },
+  // Whole row is the activation target (bigger hit area + keyboard) when it's a todo.
+  const interactive = !done && typeof onClick === 'function';
+  return el('div', { class: `check-row${done ? ' is-done' : ''}`, activate: interactive ? onClick : undefined },
     done ? icon('check', 'check-row__icon') : el('span', { class: 'check-row__dot' }),
-    el('span', { class: `check-row__label${!done && onClick ? ' is-link' : ''}`, onClick: done ? null : onClick }, label));
+    el('span', { class: `check-row__label${interactive ? ' is-link' : ''}` }, label));
 }
 export function Field(label, control, hint) {
   return el('div', { class: 'field' }, label && el('label', {}, label), control, hint && el('div', { class: 'hint' }, hint));
@@ -222,6 +311,8 @@ export function toastOk(msg) { toast(msg, { type: 'success' }); }
 
 /* ------------------------------------------------------------------ modal */
 let modalRoot;
+let modalReturnFocus = null;
+const MODAL_FOCUSABLE = 'a[href],button:not([disabled]),input:not([disabled]),textarea:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
 function ensureModalRoot() {
   if (!modalRoot) {
     modalRoot = el('div', { class: 'modal-root' });
@@ -230,7 +321,11 @@ function ensureModalRoot() {
   }
   return modalRoot;
 }
-export function closeModal() { if (modalRoot) { modalRoot.classList.remove('is-open'); clear(modalRoot); } }
+export function closeModal() {
+  if (modalRoot) { modalRoot.classList.remove('is-open'); clear(modalRoot); }
+  // Return focus to whatever opened the modal so keyboard users aren't dumped at the page top.
+  if (modalReturnFocus) { try { modalReturnFocus.focus(); } catch { /* element gone */ } modalReturnFocus = null; }
+}
 /**
  * Open a modal. `render(close)` returns the modal body content. Provide title,
  * optional footer buttons via `footer(close)`. Returns nothing; call closeModal().
@@ -238,18 +333,36 @@ export function closeModal() { if (modalRoot) { modalRoot.classList.remove('is-o
 export function openModal({ title, body, footer, size }) {
   const root = ensureModalRoot();
   const close = closeModal;
+  modalReturnFocus = document.activeElement; // restored by closeModal
   const closeBtn = IconBtn('plus', { title: '닫기', onClick: close }); // rotated to look like ×
   closeBtn.style.transform = 'rotate(45deg)';
-  const modal = el('div', { class: `modal${size === 'lg' ? ' modal--lg' : ''}` },
-    el('div', { class: 'modal__head' }, el('h3', {}, title), el('div', { class: 'topbar__spacer' }), closeBtn),
+  const modal = el('div', {
+    class: `modal${size === 'lg' ? ' modal--lg' : ''}`,
+    attrs: { role: 'dialog', 'aria-modal': 'true', 'aria-labelledby': 'modal-title' },
+  },
+    el('div', { class: 'modal__head' }, el('h3', { id: 'modal-title' }, title), el('div', { class: 'topbar__spacer' }), closeBtn),
   );
+  // Focus trap: keep Tab / Shift+Tab inside the dialog instead of leaking to the page behind.
+  modal.addEventListener('keydown', (e) => {
+    if (e.key !== 'Tab') return;
+    const f = [...modal.querySelectorAll(MODAL_FOCUSABLE)].filter((x) => x.offsetParent !== null);
+    if (!f.length) return;
+    const first = f[0], last = f[f.length - 1];
+    if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+    else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+  });
   const bodyNode = el('div', { class: 'modal__body' });
   appendChildren(bodyNode, [typeof body === 'function' ? body(close) : body]);
   modal.append(bodyNode);
+  // Persistent inline error slot so a failed save shows a clear reason instead of
+  // relying on a 3.8s toast. Placed between body and footer (always visible). Any
+  // SubmitBtn inside the modal writes here — including inline editors in bodies
+  // that have no footer; see SubmitBtn.
+  modal.append(el('div', { class: 'modal__error', hidden: true, attrs: { role: 'alert', 'aria-live': 'assertive' } }));
   if (footer) modal.append(el('div', { class: 'modal__foot' }, ...[].concat(footer(close))));
   mount(root, el('div', { class: 'modal__scrim', onClick: close }), modal);
   root.classList.add('is-open');
-  setTimeout(() => bodyNode.querySelector('input,textarea,select,button')?.focus(), 30);
+  setTimeout(() => (bodyNode.querySelector('input,textarea,select') || modal.querySelector(MODAL_FOCUSABLE))?.focus(), 30);
 }
 /** Confirmation dialog. Returns a Promise<boolean>. */
 export function confirmDialog({ title = '확인', message, confirmLabel = '확인', danger } = {}) {
@@ -275,7 +388,6 @@ export function downloadUrl(url) {
   const a = el('a', { href: url, download: '' });
   document.body.append(a); a.click(); a.remove();
 }
-export function debounce(fn, ms = 250) { let t; return (...a) => { clearTimeout(t); t = setTimeout(() => fn(...a), ms); }; }
 
 /** Shared meta (statuses, document kinds) loaded once. */
 let _meta = null;

package/apps/web/public/pages/applications.js

@@ -2,16 +2,9 @@
 // (no horizontal scroll). Change a status inline to move an item between groups.
 import {
   el, get, put, navigate, EmptyState, Btn, ListRow,
-  Select, scoreClass, mount, toast, toastOk, toastError, meta,
+  Select, scoreClass, statusColor, mount, toast, toastOk, toastError, meta,
 } from '/lib.js';
 
-// status code → theme colour (matches the badge--{status} hues)
-const STATUS_COLOR = {
-  draft: 'var(--slate)', planned: 'var(--blue)', applied: 'var(--violet)',
-  document_passed: 'var(--teal)', interview: 'var(--amber)',
-  final_passed: 'var(--green)', on_hold: 'var(--slate)', rejected: 'var(--red)',
-};
-
 // deadline(YYYY-MM-DD) → "마감 D-7" / "마감 D-day" / "마감 지남" (null if absent/invalid)
 function ddayLabel(deadline) {
   if (!deadline) return null;
@@ -63,7 +56,7 @@ export async function render(ctx) {
   function StatusGroup(code, apps) {
     return el('div', {},
       el('div', { class: 'app-group__head' },
-        el('span', { class: 'app-group__dot', style: { background: STATUS_COLOR[code] || 'var(--text-tertiary)' } }),
+        el('span', { class: 'app-group__dot', style: { background: statusColor(code) } }),
         el('span', { class: 'app-group__title' }, labelByCode[code] || code),
         el('span', { class: 'app-group__count tnum' }, `${apps.length}건`)),
       el('div', {}, ...apps.map(AppRow)));

package/apps/web/public/pages/documents.js

@@ -1,7 +1,7 @@
 // Documents — cover letters (with version history) and résumés/other documents.
 // XSS-safe: all DB/user text rendered via el() textContent / .doc-preview (never innerHTML).
 import {
-  el, get, post, put, del, Card, Badge, Btn, IconBtn, EmptyState,
+  el, get, post, put, del, Card, Badge, Btn, IconBtn, SubmitBtn, EmptyState,
   Field, Input, Textarea, Select, openModal, confirmDialog,
   toastOk, toastError, copyText, downloadUrl, fmtRelative, mount, meta,
 } from '/lib.js';
@@ -9,7 +9,10 @@ import {
 const SOURCE_LABELS = { manual: '직접 입력', upload: '파일 업로드', ai: 'AI 생성', edit: '직접 수정' };
 const sourceLabel = (s) => SOURCE_LABELS[s] || s || '';
 
-let tab = 'cover'; // 'cover' | 'docs'
+// Module-scoped on purpose: remember the last-viewed tab ('cover' | 'docs') across
+// navigations so returning to Documents reopens where the user left off. The search
+// query is intentionally NOT persisted (it resets per visit).
+let tab = 'cover';
 
 export async function render(ctx) {
   const root = el('div', { class: 'stack-4' });
@@ -101,7 +104,7 @@ async function CoverLettersTab(reload) {
 function CoverRow(cl, reload) {
   const metaRow = el('div', { class: 'flex gap-2 wrap', style: { marginTop: '4px' } },
     el('span', { class: 'chip' }, `버전 ${cl.version_count}개`),
-    cl.is_primary ? Badge('final_passed', '대표') : null,
+    cl.is_primary ? Badge('accent', '대표') : null,
   );
 
   const actions = el('div', { class: 'flex gap-2 wrap' },
@@ -129,7 +132,7 @@ function CoverRow(cl, reload) {
 async function setPrimaryCover(id, reload) {
   try {
     await put(`/api/cover-letters/${id}/primary`, {});
-    toastOk('대표 자기소개서로 지정했습니다.');
+    toastOk('대표 자기소개서로 지정했어요.');
     await reload();
   } catch (err) { toastError(err); }
 }
@@ -143,45 +146,56 @@ async function removeCover(cl, reload) {
   if (!ok) return;
   try {
     await del(`/api/cover-letters/${cl.id}`);
-    toastOk('자기소개서를 삭제했습니다.');
+    toastOk('자기소개서를 삭제했어요.');
     await reload();
   } catch (err) { toastError(err); }
 }
 
-function openCoverCreate(reload) {
+async function openCoverCreate(reload) {
+  // Let the user PICK the job to link instead of typing an internal ID they've never seen.
+  let jobs = [];
+  try { ({ jobs } = await get('/api/jobs')); } catch { /* dropdown falls back to "연결 안 함" */ }
   const title = Input({ placeholder: '예: 백엔드 개발자 자기소개서', attrs: { maxlength: '200' } });
   const content = Textarea({ placeholder: '내용을 붙여넣으세요. 비워 두면 빈 자기소개서가 만들어집니다.', style: { minHeight: '200px' } });
-  const jobId = Input({ placeholder: '연결할 공고 ID (선택)' });
+  const jobPick = Select([
+    { value: '', label: '연결 안 함', selected: true },
+    ...jobs.map((j) => ({ value: j.id, label: `${j.company} · ${j.position}` })),
+  ]);
 
   openModal({
     title: '새 자기소개서',
     size: 'lg',
     body: el('div', { class: 'stack-3' },
       Field('제목 (필수)', title),
-      Field('내용 (선택)', content, '내용을 입력하면 v1 버전으로 저장됩니다.'),
-      Field('공고 ID (선택)', jobId, '특정 공고에 연결하려면 입력하세요.'),
+      Field('내용 (선택)', content, '내용을 입력하면 첫 버전으로 저장됩니다.'),
+      Field('연결할 공고 (선택)', jobPick,
+        jobs.length ? '특정 공고에 연결하면 그 공고 화면에서 함께 보여요.' : '저장된 공고가 아직 없어요.'),
     ),
     footer: (close) => [
       Btn('취소', { onClick: close }),
-      Btn('자기소개서 저장', { variant: 'primary', onClick: async () => {
+      SubmitBtn('자기소개서 저장', async () => {
         const t = title.value.trim();
-        if (!t) { toastError(new Error('제목을 입력해 주세요.')); title.focus(); return; }
-        try {
-          const body = { title: t, source: 'manual' };
-          if (content.value.trim()) body.content = content.value;
-          if (jobId.value.trim()) body.job_id = jobId.value.trim();
-          await post('/api/cover-letters', body);
-          toastOk('자기소개서를 추가했습니다.');
-          close();
-          await reload();
-        } catch (err) { toastError(err); }
-      } }),
+        if (!t) { title.focus(); throw new Error('제목을 입력해 주세요.'); }
+        const body = { title: t, source: 'manual' };
+        if (content.value.trim()) body.content = content.value;
+        if (jobPick.value) body.job_id = jobPick.value;
+        await post('/api/cover-letters', body);
+        toastOk('자기소개서를 추가했어요.');
+        close();
+        await reload();
+      }),
     ],
   });
 }
 
 async function openCoverDetail(id, reload) {
-  let data = (await get(`/api/cover-letters/${id}`)).cover_letter;
+  let data;
+  try {
+    data = (await get(`/api/cover-letters/${id}`)).cover_letter;
+  } catch (err) {
+    toastError(err);
+    return;
+  }
 
   openModal({
     title: data.title,
@@ -210,7 +224,7 @@ function CoverDetailBody(cl, { refresh }) {
   wrap.append(el('div', { class: 'flex between wrap gap-2' },
     el('div', { class: 'flex gap-2 wrap' },
       el('span', { class: 'chip' }, `버전 ${cl.version_count}개`),
-      cl.is_primary ? Badge('final_passed', '대표') : null,
+      cl.is_primary ? Badge('accent', '대표') : null,
     ),
     el('div', { class: 'flex gap-2 wrap' },
       Btn('MD 내보내기', { sm: true, variant: 'ghost', icon: 'download', onClick: () => downloadUrl(`/api/export/cover-letter/${cl.id}?format=md`) }),
@@ -277,7 +291,7 @@ function VersionItem(cl, v, { isCurrent, setPreview, refresh }) {
 async function makeCurrent(id, versionId, refresh) {
   try {
     await put(`/api/cover-letters/${id}/current-version`, { version_id: versionId });
-    toastOk('현재 버전을 변경했습니다.');
+    toastOk('현재 버전을 변경했어요.');
     await refresh();
   } catch (err) { toastError(err); }
 }
@@ -292,16 +306,14 @@ function EditNewVersion(cl, refresh) {
     Field('내용', content),
     Field('변경 메모 (선택)', note),
     el('div', { class: 'flex gap-2' },
-      Btn('새 버전으로 저장', { variant: 'primary', icon: 'check', onClick: async () => {
-        if (!content.value.trim()) { toastError(new Error('내용을 입력해 주세요.')); content.focus(); return; }
-        try {
-          await post(`/api/cover-letters/${cl.id}/versions`, {
-            content: content.value, note: note.value.trim() || undefined, source: 'edit',
-          });
-          toastOk('새 버전을 저장했습니다.');
-          await refresh();
-        } catch (err) { toastError(err); }
-      } }),
+      SubmitBtn('새 버전으로 저장', async () => {
+        if (!content.value.trim()) { content.focus(); throw new Error('내용을 입력해 주세요.'); }
+        await post(`/api/cover-letters/${cl.id}/versions`, {
+          content: content.value, note: note.value.trim() || undefined, source: 'edit',
+        });
+        toastOk('새 버전을 저장했어요.');
+        await refresh();
+      }, { icon: 'check' }),
       Btn('취소', { variant: 'ghost', onClick: () => { editor.style.display = 'none'; toggle.style.display = ''; } }),
     ),
   );
@@ -344,7 +356,7 @@ function DocRow(doc, kindLabels, m, reload) {
     el('div', { class: 'flex gap-2 wrap center' },
       el('span', { class: 'strong' }, doc.title),
       el('span', { class: 'chip' }, kindLabels[doc.kind] || doc.kind),
-      doc.is_primary ? Badge('final_passed', '대표') : null,
+      doc.is_primary ? Badge('accent', '대표') : null,
     ),
     el('span', { class: 'muted text-sm' }, fmtRelative(doc.updated_at)),
   );
@@ -363,7 +375,13 @@ function DocRow(doc, kindLabels, m, reload) {
 }
 
 async function openDocDetail(id, kindLabels, m, reload) {
-  const doc = (await get(`/api/documents/${id}`)).document;
+  let doc;
+  try {
+    doc = (await get(`/api/documents/${id}`)).document;
+  } catch (err) {
+    toastError(err);
+    return;
+  }
 
   openModal({
     title: doc.title,
@@ -371,7 +389,7 @@ async function openDocDetail(id, kindLabels, m, reload) {
     body: el('div', { class: 'stack-3' },
       el('div', { class: 'flex gap-2 wrap center' },
         el('span', { class: 'chip' }, kindLabels[doc.kind] || doc.kind),
-        doc.is_primary ? Badge('final_passed', '대표') : null,
+        doc.is_primary ? Badge('accent', '대표') : null,
         el('span', { class: 'chip' }, sourceLabel(doc.source)),
         el('span', { class: 'muted text-sm' }, `수정 ${fmtRelative(doc.updated_at)}`),
       ),
@@ -383,7 +401,7 @@ async function openDocDetail(id, kindLabels, m, reload) {
       Btn('삭제', { variant: 'danger', icon: 'trash', onClick: async () => {
         const ok = await confirmDialog({ title: '문서 삭제', message: `"${doc.title}"을(를) 삭제할까요?`, confirmLabel: '삭제', danger: true });
         if (!ok) return;
-        try { await del(`/api/documents/${doc.id}`); toastOk('문서를 삭제했습니다.'); close(); await reload(); }
+        try { await del(`/api/documents/${doc.id}`); toastOk('문서를 삭제했어요.'); close(); await reload(); }
         catch (err) { toastError(err); }
       } }),
       Btn('수정', { variant: 'primary', icon: 'edit', onClick: () => { close(); openDocEdit(doc, m, reload); } }),
@@ -392,7 +410,7 @@ async function openDocDetail(id, kindLabels, m, reload) {
 }
 
 function openDocCreate(reload) {
-  meta().then((m) => docForm(null, m, reload));
+  meta().then((m) => docForm(null, m, reload)).catch(toastError);
 }
 
 function openDocEdit(doc, m, reload) {
@@ -418,19 +436,17 @@ function docForm(doc, m, reload) {
     ),
     footer: (close) => [
       Btn('취소', { onClick: close }),
-      Btn('문서 저장', { variant: 'primary', onClick: async () => {
+      SubmitBtn('문서 저장', async () => {
         const t = title.value.trim();
-        if (!t) { toastError(new Error('제목을 입력해 주세요.')); title.focus(); return; }
-        if (!content.value.trim()) { toastError(new Error('내용을 입력해 주세요.')); content.focus(); return; }
+        if (!t) { title.focus(); throw new Error('제목을 입력해 주세요.'); }
+        if (!content.value.trim()) { content.focus(); throw new Error('내용을 입력해 주세요.'); }
         const body = { kind: kind.value, title: t, content: content.value, is_primary: primary.checked };
-        try {
-          if (doc) await put(`/api/documents/${doc.id}`, body);
-          else await post('/api/documents', { ...body, source: 'manual' });
-          toastOk(doc ? '문서를 수정했습니다.' : '문서를 추가했습니다.');
-          close();
-          await reload();
-        } catch (err) { toastError(err); }
-      } }),
+        if (doc) await put(`/api/documents/${doc.id}`, body);
+        else await post('/api/documents', { ...body, source: 'manual' });
+        toastOk(doc ? '문서를 수정했어요.' : '문서를 추가했어요.');
+        close();
+        await reload();
+      }),
     ],
   });
 }

package/apps/web/public/pages/home.js

@@ -5,16 +5,9 @@
 // the same "AI에게 보내면 저장됩니다" instruction across surfaces.
 import {
   el, get, icon, navigate, Card, Badge, Btn, EmptyState, ListRow, CheckRow,
-  Stat, PageHead, fmtDate, fmtRelative, scoreClass, mount,
+  Stat, PageHead, fmtDate, fmtRelative, scoreClass, STATUS_COLOR, statusColor, mount,
 } from '/lib.js';
 
-// status code → saturated theme colour. MUST track the badge--{status} hues so a
-// colour means the same stage in the pipeline bar, the badges, and the board.
-const STATUS_COLOR = {
-  draft: 'var(--slate)', planned: 'var(--blue)', applied: 'var(--violet)',
-  document_passed: 'var(--teal)', interview: 'var(--amber)',
-  final_passed: 'var(--green)', on_hold: 'var(--slate)', rejected: 'var(--red)',
-};
 const PIPE_ORDER = ['draft', 'planned', 'applied', 'document_passed', 'interview', 'final_passed', 'on_hold', 'rejected'];
 
 // activity type → icon + theme hue (soft tinted chip + coloured stroke)
@@ -84,6 +77,15 @@ function GettingStarted(o) {
     title: '시작하기',
     sub: `프로필 완성도 ${o.profile_completeness}%`,
     body: [
+      // The one place (per DESIGN_GUIDE rule 4) that teaches the core mental model:
+      // CareerMate stores; your own AI does the thinking. Without this, first-run users
+      // read the empty dashboard as a manual CRUD form and never find the real workflow.
+      el('div', { class: 'callout mb-3' },
+        icon('info'),
+        el('div', {},
+          el('div', { class: 'callout__title' }, '두뇌는 당신의 AI, 보관은 CareerMate'),
+          el('div', { class: 'callout__body' },
+            '공고 분석·자기소개서·면접 준비는 평소 쓰던 AI에게 말로 시키면, 결과가 이 대시보드에 쌓여요.'))),
       el('div', { class: 'progress' }, el('div', { class: 'progress__bar', style: { width: `${o.profile_completeness}%` } })),
       el('p', { class: 'text-secondary text-sm', style: { margin: '12px 0 8px' } },
         '완성할수록 AI의 적합도 분석과 자기소개서 품질이 좋아져요.'),
@@ -94,9 +96,8 @@ function GettingStarted(o) {
 
 /* ----------------------------------------------- KPI summary tiles (at-a-glance) */
 function StatTile(label, value, iconName, to) {
-  const tile = Stat({ label, value, iconName });
+  const tile = Stat({ label, value, iconName, onClick: () => navigate(to) });
   tile.classList.add('is-clickable');
-  tile.addEventListener('click', () => navigate(to));
   return tile;
 }
 function StatRow(counts) {
@@ -162,7 +163,7 @@ function Pipeline(breakdown) {
 
 /* ----------------------------------------------- action lane (what to do next) */
 function statusDot(status) {
-  return el('span', { class: 'list-row__dot', style: { background: STATUS_COLOR[status] || 'var(--text-tertiary)' } });
+  return el('span', { class: 'list-row__dot', style: { background: statusColor(status) } });
 }
 
 function ActionLane(interviewTodo, inProgress) {

package/apps/web/public/pages/interview.js

@@ -1,7 +1,7 @@
 // Interview — preparation materials for jobs that reached 서류 합격 or beyond.
 import {
-  el, get, put, icon, navigate, Card, Badge, Btn, EmptyState, Field, Input,
-  Textarea, openModal, closeModal, toastOk, toastError, copyText,
+  el, get, put, icon, navigate, Card, Badge, Btn, SubmitBtn, EmptyState, Field, Input,
+  Textarea, openModal, closeModal, toastOk, copyText,
   downloadUrl, mount,
 } from '/lib.js';
 
@@ -200,7 +200,7 @@ export async function render(ctx) {
       body: formBody,
       footer: (close) => [
         Btn('취소', { onClick: close }),
-        Btn('면접 준비 저장', { variant: 'primary', onClick: () => save(jobId) }),
+        SubmitBtn('면접 준비 저장', () => save(jobId)),
       ],
     });
 
@@ -216,15 +216,12 @@ export async function render(ctx) {
         self_introduction: introInput.value,
         notes: notesInput.value,
       };
-      try {
-        await put(`/api/jobs/${id}/interview`, payload);
-        closeModal();
-        toastOk('면접 준비를 저장했어요.');
-        await ctx.refreshNav();
-        await render(ctx);
-      } catch (err) {
-        toastError(err);
-      }
+      // Throws on failure so the SubmitBtn surfaces it inline.
+      await put(`/api/jobs/${id}/interview`, payload);
+      closeModal();
+      toastOk('면접 준비를 저장했어요.');
+      await ctx.refreshNav();
+      await render(ctx);
     }
   }
 }