argus-decision-mcp 1.2.0 → 1.3.0

package/dist/lib/localize-result.js

@@ -0,0 +1,120 @@
+import { resolveResponseLocale } from './surfaces.js';
+const KO_ERRORS = {
+    INVALID_INPUT: { message: '입력값이 올바르지 않습니다.', recovery: '오류가 표시된 인자를 고친 뒤 같은 도구를 다시 호출하세요. 사용자가 정해야 할 값은 추측하지 마세요.' },
+    INVALID_LOCALE: { message: '지원하지 않는 언어입니다.', recovery: 'locale에는 "ko" 또는 "en"을 사용하세요.' },
+    ALREADY_CLOSED: { message: '이미 진행 중이거나 닫힌 결정입니다.', recovery: '실제 결과를 기록하려면 argus_resolve를 사용하세요. 닫힌 결정은 다시 열지 않습니다.' },
+    CAPTURE_NOT_FOUND: { message: '일치하는 내부 메모를 찾지 못했습니다.', recovery: '전제 문장을 text에 직접 전달하세요.' },
+    AMBIGUOUS_REF: { message: '여러 내부 메모와 일치해 대상을 정할 수 없습니다.', recovery: '전제 문장을 text에 직접 전달하세요.' },
+    PROVENANCE_REQUIRED: { message: '문장의 출처를 확인해야 합니다.', recovery: '사용자가 쓴 문장이면 user_stated, AI가 제기한 문장이면 ai_surfaced와 원문을 전달하세요.' },
+    PREMISES_REQUIRED: { message: '추가할 전제가 없습니다.', recovery: 'text, kind, external, load_bearing, source를 포함한 전제 1~5개를 전달하세요.' },
+    PREMISE_ID_COLLISION: { message: '다른 전제가 같은 식별자를 사용하고 있습니다.', recovery: '전제 문장을 조금 다르게 표현한 뒤 다시 추가하세요.' },
+    PREMISE_CAP: { message: '이 결정에서 추적할 수 있는 전제 수를 넘었습니다.', recovery: '기존 전제 하나를 정리하거나, 덜 중요한 전제를 핵심 전제에 합치세요.' },
+    AMEND_NEEDS_REF: { message: '수정할 전제 번호와 작업이 필요합니다.', recovery: 'argus_patterns view="decision_context"로 목록을 확인한 뒤 ref와 action을 전달하세요.' },
+    AMEND_NEEDS_TEXT: { message: '수정된 전제 문장이 필요합니다.', recovery: '사용자의 표현을 그대로 text에 전달하세요. 다시 요약하지 마세요.' },
+    PREMISE_RETIRED: { message: '이미 닫힌 전제라 수정할 수 없습니다.', recovery: '기존 기록은 그대로 두고 필요한 경우 새 전제를 추가하세요.' },
+    RESOLVE_NEEDS_REF: { message: '답을 닫을 미결 질문 번호가 필요합니다.', recovery: 'argus_patterns view="decision_context"로 목록을 확인한 뒤 ref를 전달하세요.' },
+    STILL_OPEN_NEEDS_REF: { message: '열어둘 미결 질문 번호가 필요합니다.', recovery: 'argus_patterns view="decision_context"로 목록을 확인한 뒤 ref를 전달하세요.' },
+    NOT_AN_OPEN_QUESTION: { message: '이 항목은 미결 질문이 아니라 전제입니다.', recovery: '전제는 argus_capture action="update_fact"로 현실과 다시 확인하고, 미결 질문만 사용자의 말로 닫으세요.' },
+    RESOLVE_NEEDS_DECISION: { message: '미결 질문은 사용자가 직접 내린 판단으로만 닫을 수 있습니다.', recovery: '사용자에게 판단을 물어 decision에 그대로 전달하세요. 아직 결정하지 못했다면 열린 채로 둘 수 있습니다.' },
+    RECEIPT_NEEDS_ID: { message: '판단 영수증을 불러올 결정 id가 필요합니다.', recovery: '결정 id를 전달하세요.' },
+    RECEIPT_NOT_FOUND: { message: '해당 결정의 판단 영수증을 찾지 못했습니다.', recovery: 'argus_patterns view="all"에서 id를 확인하거나 먼저 예측을 저장하세요.' },
+    PREMISES_NEEDS_ID: { message: '전제를 불러올 결정 id가 필요합니다.', recovery: '결정 id를 전달하세요.' },
+    NOT_RECHECKABLE: { message: '이 항목은 현실과 재확인할 전제가 아니라 사용자가 답할 미결 질문입니다.', recovery: 'argus_capture action="answer_question"에 사용자의 판단을 그대로 전달하세요.' },
+    RECHECK_NEEDS_ASSERTION: { message: '이전 기준과 비교할 수 있는 확인 결과가 필요합니다.', recovery: '수치 사실이면 numeric_value를, 문장형 사실이면 changed=true/false를 명시하세요.' },
+    TOO_LARGE: { message: '문서가 처리 가능한 크기를 넘었습니다.', recovery: '판단에 가장 중요한 부분만 검수하거나 문서를 나누세요.' },
+    READ_FAILED: { message: '문서 파일을 읽지 못했습니다.', recovery: '절대 경로를 확인하거나 문서 내용을 text에 붙여 넣으세요.' },
+    EXTRACT_FAILED: { message: '문서에서 텍스트를 추출하지 못했습니다.', recovery: '문서 내용을 text에 붙여 넣거나 markdown/txt로 변환하세요.' },
+    EMPTY: { message: '검수할 수 있는 문서 내용이 없습니다.', recovery: '20자 이상의 text 또는 읽을 수 있는 file_path를 전달하세요.' },
+    OUTCOME_REQUIRED: { message: '현실에서 실제로 어떻게 됐는지 결과가 필요합니다.', recovery: '사용자에게 결과를 물어 outcome에 전달하세요. 결과를 추론하지 마세요.' },
+    PREMATURE_SETTLE: { message: '아직 확인일이 되지 않았습니다.', recovery: '확인일까지 기다리거나 일정이 바뀌었다면 확인일을 수정하세요.' },
+    WHAT_HAPPENED_REQUIRED: { message: '실제로 일어난 일을 기록해야 합니다.', recovery: '사용자에게 실제 결과를 물어 what_happened에 그대로 전달하세요.' },
+    DEFER_DATE_REQUIRED: { message: '다시 확인할 날짜가 필요합니다.', recovery: '사용자에게 날짜를 물어 defer_to에 YYYY-MM-DD로 전달하세요. 더는 중요하지 않다면 argus_capture action="close"를 사용하세요.' },
+    NOT_CONNECTED: { message: '이 터미널은 Argus 계정과 연결돼 있지 않습니다.', recovery: '웹 설정에서 동기화 토큰을 발급하고 MCP 설정의 ARGUS_TOKEN에 넣으세요.' },
+    SYNC_FAILED: { message: 'Argus 계정과 동기화하지 못했습니다.', recovery: '네트워크와 ARGUS_API_URL을 확인한 뒤 다시 시도하세요. 로컬 기록은 영향을 받지 않습니다.' },
+    TEXT_REQUIRED: { message: '기록할 문장이 필요합니다.', recovery: '사용자의 문장을 고치거나 요약하지 말고 그대로 text에 전달하세요.' },
+    SEAL_INVALID: { message: '다시 쓴 예측 문장의 길이가 맞지 않습니다 (8~400자).', recovery: '사용자에게 예측 문장을 8~400자로 다시 물어 그대로 저장하세요.' },
+    INTERNAL_ERROR: { message: '내부 오류가 발생했습니다.', recovery: '같은 작업을 다시 시도하세요. 반복되면 MCP 서버 로그를 확인하세요.' },
+    UNKNOWN_TOOL: { message: '알 수 없는 도구입니다.', recovery: 'tools/list에 나온 정확한 도구 이름을 사용하세요.' },
+};
+export const LOCALIZED_ERROR_CODES = new Set(Object.keys(KO_ERRORS));
+/** Translate one Zod issue into a Korean, actionable reason. Keeps the English
+ *  argument NAME (models and users see arg names in English), but says in Korean
+ *  WHY it failed — the piece the generic message threw away. */
+function koReason(issue) {
+    const unit = issue.origin === 'string' ? '자' : issue.origin === 'array' ? '개' : '';
+    switch (issue.code) {
+        case 'too_small':
+            if (issue.origin === 'string')
+                return `너무 짧습니다 (최소 ${issue.minimum}자)`;
+            if (issue.origin === 'array')
+                return `항목이 부족합니다 (최소 ${issue.minimum}개)`;
+            return `너무 작습니다 (최소 ${issue.minimum}${unit})`;
+        case 'too_big':
+            if (issue.origin === 'string')
+                return `너무 깁니다 (최대 ${issue.maximum}자)`;
+            if (issue.origin === 'array')
+                return `항목이 너무 많습니다 (최대 ${issue.maximum}개)`;
+            return `너무 큽니다 (최대 ${issue.maximum}${unit})`;
+        case 'invalid_type':
+            return issue.expected === undefined ? '형식이 올바르지 않습니다' : `필수이거나 형식이 올바르지 않습니다 (${issue.expected} 필요)`;
+        case 'invalid_value':
+        case 'invalid_enum_value':
+            return '허용되지 않는 값입니다';
+        case 'unrecognized_keys':
+            return '알 수 없는 항목입니다';
+        case 'invalid_format':
+        case 'invalid_string':
+            return '형식이 올바르지 않습니다 (예: 날짜는 YYYY-MM-DD)';
+        default:
+            return '값을 확인해 주세요';
+    }
+}
+/** Korean INVALID_INPUT that NAMES each offending argument and why. */
+function localizeInvalidInput(fields) {
+    if (!fields.length)
+        return KO_ERRORS.INVALID_INPUT;
+    const parts = fields.slice(0, 4).map((f) => `${f.field === '(root)' ? '요청' : f.field}: ${koReason(f)}`);
+    return {
+        message: `입력값이 올바르지 않습니다 — ${parts.join(', ')}.`,
+        recovery: '위에 표시된 인자를 고친 뒤 같은 도구를 다시 호출하세요. 사용자가 정해야 할 값은 추측하지 마세요.',
+    };
+}
+const REPRESENTATIVE_FIELDS = [
+    'decision', 'predicate', 'what_happened', 'finding', 'text', 'question',
+    'human_judgment', 'note', 'title', 'biggest_worry',
+];
+function responseLocale(args) {
+    const sample = REPRESENTATIVE_FIELDS
+        .map((key) => args[key])
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .join('\n');
+    const dir = typeof args['argus_dir'] === 'string' ? args['argus_dir'] : null;
+    return resolveResponseLocale(dir, sample);
+}
+/**
+ * Dispatch-level locale safety net. Tool handlers retain precise English
+ * diagnostics for development, while every Korean MCP call receives a Korean
+ * user surface even on validation, guard, and rare failure paths.
+ */
+export function localizeToolResult(args, result) {
+    if (!result.isError || responseLocale(args) !== 'ko')
+        return result;
+    const sc = result.structuredContent;
+    if (!sc || sc['ok'] !== false)
+        return result;
+    const code = String(sc['error_code'] ?? 'INTERNAL_ERROR');
+    const copy = code === 'INVALID_INPUT' && Array.isArray(sc['invalid_fields'])
+        ? localizeInvalidInput(sc['invalid_fields'])
+        : KO_ERRORS[code] ?? {
+            message: '요청을 처리하지 못했습니다.',
+            recovery: '입력값과 현재 결정 상태를 확인한 뒤 다시 시도하세요.',
+        };
+    const localized = {
+        ...sc,
+        message: copy.message,
+        ...(copy.recovery ? { recovery: copy.recovery } : {}),
+    };
+    result.structuredContent = localized;
+    result.content = [{ type: 'text', text: JSON.stringify(localized, null, 2) }];
+    return result;
+}

package/dist/lib/localized-message.js

@@ -0,0 +1,13 @@
+import { resolveResponseLocale } from './surfaces.js';
+/**
+ * Resolve one user-facing MCP sentence with the same precedence used by tool
+ * surfaces: explicit config first, then representative user text, then host
+ * locale. Machine tokens, ids, enum values, and tool names remain unchanged.
+ */
+export function localizedMessage(argusDir, sample, copy) {
+    return resolveResponseLocale(argusDir, sample) === 'ko' ? copy.ko : copy.en;
+}
+/** Pair a localized error message with its actionable recovery sentence. */
+export function localizedErrorCopy(argusDir, sample, copy) {
+    return resolveResponseLocale(argusDir, sample) === 'ko' ? copy.ko : copy.en;
+}

package/dist/lib/premises.js

@@ -123,8 +123,6 @@ export function groupDuePremises(due) {
     }
     return [...byText.values()];
 }
-/** The living-premises summary a receipt renders from (plan v5 §3.3): the
- *  premise set is canonical — headline = first active load-bearing premise. */
 export function receiptPremisesInfo(entry) {
     const list = entry?.premises ?? [];
     if (list.length === 0)

package/dist/lib/push-account.js

@@ -15,6 +15,7 @@
  *     ARGUS_TOKEN    argus_pat_… (issued in the webapp; same token as `argus push`)
  *     ARGUS_API_URL  optional, defaults to https://argus.voyage
  */
+import { resolveAccountApiUrl, resolveAccountToken } from '../a0/account-credentials.js';
 const TIMEOUT_MS = 5000;
 /**
  * Resolve the account API base, enforcing https so the Bearer token never
@@ -23,7 +24,7 @@ const TIMEOUT_MS = 5000;
  * returns null → callers skip the send rather than leak the token over http.
  */
 function resolveApiBase() {
-    const raw = (process.env.ARGUS_API_URL || 'https://argus.voyage').replace(/\/+$/, '');
+    const raw = resolveAccountApiUrl().replace(/\/+$/, '');
     try {
         const u = new URL(raw);
         const localhost = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '::1';
@@ -37,7 +38,7 @@ function resolveApiBase() {
 }
 /** Pull the account's receipts (the sync's read side). No token ⇒ empty. */
 export async function fetchAccountReceipts() {
-    const token = (process.env.ARGUS_TOKEN || '').trim();
+    const token = resolveAccountToken();
     if (!token || !token.startsWith('argus_pat_'))
         return { ok: false, reason: 'no_token', receipts: [] };
     const base = resolveApiBase();
@@ -63,7 +64,7 @@ export async function fetchAccountReceipts() {
     }
 }
 export async function pushToAccount(payload) {
-    const token = (process.env.ARGUS_TOKEN || '').trim();
+    const token = resolveAccountToken();
     if (!token)
         return { synced: false, reason: 'no_token' }; // local-only (default)
     if (!token.startsWith('argus_pat_'))

package/dist/lib/review/extract-core.js

@@ -9,9 +9,13 @@
  * data pdf.js / jszip already handed back (text items, slide XML strings), so it
  * runs identically in both runtimes.
  */
+import { stableId } from './ids.js';
 /** Hard caps shared by both extractors. */
 export const MAX_UNITS = 400;
 export const PAGE_CAP = 120;
+/** Target size for a PDF paragraph unit — keeps anchors granular instead of one
+ *  page-sized blob (pdf.js emits no blank lines, so we split by size + headings). */
+export const PDF_PARA_CHARS = 1200;
 /** Same y-tolerance the original single-column reconstructor used. */
 const Y_TOL = 3;
 function partOf(it) {
@@ -195,6 +199,118 @@ export function groupBlocks(lines) {
     return blocks;
 }
 // ==========================================================================
+// PDF unit segmentation — shared by both extractors (browser + Node).
+// ==========================================================================
+/**
+ * Recognize a numbered/keyword section header in one reconstructed PDF line.
+ * Conservative on purpose — requires a structural marker (section number, roman
+ * numeral, or a known heading word) AND a short length, so running prose is never
+ * mislabeled a heading. Returns the header text, or null for body.
+ *
+ * NOTE: a plain \b after a Korean keyword never fires (Korean chars aren't \w),
+ * so an explicit boundary lookahead is used instead — else "제 3 장", "부록 A"
+ * would be missed.
+ */
+export function pdfHeadingTitle(text) {
+    const t = text.trim();
+    if (t.length < 2 || t.length > 50)
+        return null;
+    if (t.split(/\s+/).length > 10)
+        return null;
+    if (/[.。!?…]$/.test(t) && !/^\d+(\.\d+)*\.?$/.test(t.split(/\s+/)[0]))
+        return null;
+    const marked = /^(제\s*\d+\s*(장|절|부)|chapter\s+\d+|section\s+\d+|appendix|부록|요약|개요|executive\s+summary)(?=\s|$|[:·.)])/i.test(t) ||
+        /^\d+(\.\d+){0,3}[.)]?\s+\S/.test(t) ||
+        /^[Ⅰ-Ⅹ]+\.\s+\S/.test(t) ||
+        /^[IVX]+\.\s+\S/.test(t);
+    return marked ? t : null;
+}
+/**
+ * Turn one page's reconstructed lines into units. pdf.js emits no blank lines
+ * between paragraphs, so a naive groupBlocks collapsed the ENTIRE page into one
+ * unit — burying every heading and leaving findings only a bare page number.
+ * Segmenting per line lets a heading line become its own unit (with a
+ * section_path anchor) and keeps paragraph units granular (~PDF_PARA_CHARS).
+ * Pushes onto `units`, returns the running section title, and calls `onCap` when
+ * the shared MAX_UNITS ceiling is hit.
+ */
+export function emitPdfUnits(lines, page, units, sectionIn, onCap, maxUnits = MAX_UNITS, paraCharTarget = PDF_PARA_CHARS) {
+    let currentSection = sectionIn;
+    let para = [];
+    // Flush the accumulated paragraph. Returns false only when the unit ceiling is
+    // hit (caller stops); true means "kept going" (pushed, or nothing to push).
+    const flush = () => {
+        const text = para.join(' ').replace(/\s+/g, ' ').trim();
+        para = [];
+        if (text.length < 2)
+            return true;
+        if (units.length >= maxUnits) {
+            onCap();
+            return false;
+        }
+        units.push({
+            unit_id: stableId('u', 'pdf', page, text.slice(0, 40)),
+            kind: 'paragraph',
+            text,
+            source_anchor: currentSection ? { page, section_path: [currentSection] } : { page },
+            confidence: 0.8,
+        });
+        return true;
+    };
+    for (const line of lines) {
+        const lt = line.trim();
+        if (!lt) {
+            if (!flush())
+                return currentSection;
+            continue;
+        }
+        const heading = pdfHeadingTitle(lt);
+        if (heading) {
+            if (!flush())
+                return currentSection;
+            if (units.length >= maxUnits) {
+                onCap();
+                return currentSection;
+            }
+            currentSection = heading;
+            units.push({
+                unit_id: stableId('u', 'pdf', page, heading.slice(0, 40)),
+                kind: 'heading',
+                text: heading,
+                source_anchor: { page, section_path: [heading] },
+                confidence: 0.7,
+            });
+            continue;
+        }
+        // A tabular row (reconstructPage joins detected cells with ' | ') becomes its
+        // own unit — so a finding can cite a specific table row, and detected_structure
+        // counts the table instead of burying it inside a paragraph.
+        if (/\S \| \S/.test(lt)) {
+            if (!flush())
+                return currentSection;
+            if (units.length >= maxUnits) {
+                onCap();
+                return currentSection;
+            }
+            units.push({
+                unit_id: stableId('u', 'pdf', page, lt.slice(0, 40)),
+                kind: 'table',
+                text: lt,
+                source_anchor: currentSection ? { page, section_path: [currentSection] } : { page },
+                confidence: 0.75,
+            });
+            continue;
+        }
+        para.push(lt);
+        if (para.join(' ').length >= paraCharTarget) {
+            if (!flush())
+                return currentSection;
+        }
+    }
+    flush();
+    return currentSection;
+}
+// ==========================================================================
 // PPTX slide XML — pure string parsing (jszip already gave us the XML text).
 // ==========================================================================
 /** Extract one joined string per <a:p> paragraph from slide XML. */

package/dist/lib/review/extract-file-node.js

@@ -10,26 +10,74 @@
  */
 import fs from 'fs';
 import { stableId } from './ids.js';
-import { MAX_UNITS, PAGE_CAP, reconstructPage, groupBlocks, paragraphsFromSlideXml, slideNum, } from './extract-core.js';
+import { MAX_UNITS, PAGE_CAP, reconstructPage, emitPdfUnits, paragraphsFromSlideXml, slideNum, } from './extract-core.js';
+function classifyExtractError(e, kind) {
+    const name = e?.name ?? '';
+    const m = String(e?.message ?? e ?? '').toLowerCase();
+    if (name === 'PasswordException' || m.includes('password')) {
+        return { note: '이 PDF는 암호로 보호되어 있어 열 수 없습니다. 암호를 해제해 다시 저장한 뒤 검수하세요.', error_kind: 'encrypted' };
+    }
+    if (name === 'InvalidPDFException' || m.includes('invalid pdf') || m.includes('missing pdf')) {
+        return { note: 'PDF 파일이 손상된 것 같습니다. 원본을 다시 받아 검수하거나 본문을 붙여넣으세요.', error_kind: 'corrupt' };
+    }
+    if (m.includes('end of central directory') || m.includes("can't find") || m.includes('corrupted zip') || m.includes('not a zip')) {
+        return { note: '파일이 손상됐거나 형식이 올바르지 않습니다 (열 수 없는 문서 구조).', error_kind: 'corrupt' };
+    }
+    const label = kind === 'pdf' ? 'PDF' : kind === 'docx' ? 'Word 문서' : kind === 'pptx' ? '슬라이드' : kind === 'hwpx' ? '한글 문서' : '문서';
+    return { note: `이 ${label}에서 내용을 읽지 못했습니다. 파일이 손상됐거나 형식이 확장자와 다를 수 있습니다.`, error_kind: 'unknown' };
+}
 /** Extract a binary document at `filePath`. Only pdf/docx/pptx are handled here;
- *  text formats are read directly by the caller (review.ts). */
+ *  text formats are read directly by the caller (review.ts). Never throws — a
+ *  corrupt/encrypted/empty file returns an honest quality:'unsupported' + reason. */
 export async function extractFileFromPath(filePath, kind) {
-    const buf = fs.readFileSync(filePath);
-    if (kind === 'docx')
-        return extractDocx(buf);
-    if (kind === 'pptx')
-        return extractPptx(buf);
-    if (kind === 'pdf')
-        return extractPdf(buf);
-    return { text: '', quality: 'unsupported' };
+    if (kind !== 'docx' && kind !== 'pptx' && kind !== 'pdf' && kind !== 'hwpx') {
+        return { text: '', quality: 'unsupported' };
+    }
+    let buf;
+    try {
+        buf = fs.readFileSync(filePath);
+    }
+    catch {
+        return { text: '', quality: 'unsupported', note: '파일을 읽지 못했습니다.', error_kind: 'unknown' };
+    }
+    if (buf.length === 0) {
+        return { text: '', quality: 'unsupported', note: '빈 파일입니다 (0바이트).', error_kind: 'empty' };
+    }
+    try {
+        if (kind === 'docx')
+            return await extractDocx(buf);
+        if (kind === 'pptx')
+            return await extractPptx(buf);
+        if (kind === 'hwpx')
+            return await extractHwpx(buf);
+        return await extractPdf(buf);
+    }
+    catch (e) {
+        const { note, error_kind } = classifyExtractError(e, kind);
+        return { text: '', quality: 'unsupported', note, error_kind };
+    }
 }
 // --------------------------------------------------------------------------
 // DOCX — mammoth to raw text.
 // --------------------------------------------------------------------------
 async function extractDocx(buf) {
     const mammoth = await import('mammoth');
-    const { value, messages } = await mammoth.extractRawText({ buffer: buf });
-    const text = (value || '').trim();
+    // Markdown (not raw text) so Word headings/lists/tables survive into the same
+    // markdown-aware ingest path (parity with the browser extractor). convertToMarkdown
+    // exists at runtime (mammoth 1.x) but is missing from the shipped types.
+    const toMarkdown = mammoth.convertToMarkdown;
+    let messages = [];
+    let text = '';
+    if (toMarkdown) {
+        const r = await toMarkdown({ buffer: buf });
+        messages = r.messages;
+        text = stripDocxMarkdownNoise(r.value || '');
+    }
+    if (text.length < 40) {
+        const raw = await mammoth.extractRawText({ buffer: buf });
+        text = (raw.value || '').trim();
+        messages = raw.messages;
+    }
     const lost = messages.some((m) => m.type === 'warning');
     return {
         text,
@@ -37,6 +85,16 @@ async function extractDocx(buf) {
         note: lost ? '일부 표/이미지 서식은 텍스트로 변환되지 않았습니다.' : undefined,
     };
 }
+/** Clean mammoth markdown: drop embedded image data-URIs, unescape the
+ *  backslash escapes mammoth adds to punctuation (else a heading reads
+ *  "1\. 개요"), and collapse blank runs. */
+function stripDocxMarkdownNoise(md) {
+    return md
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+        .replace(/\\([\\`*_{}[\]()#+\-.!>~|])/g, '$1')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
 // --------------------------------------------------------------------------
 // PPTX — a zip of slide XML; pull <a:t> runs per <a:p>, keep slide order.
 // --------------------------------------------------------------------------
@@ -105,6 +163,74 @@ async function extractPptx(buf) {
     return { text: units.map((u) => u.text).join('\n'), units, quality: 'medium', ...caps };
 }
 // --------------------------------------------------------------------------
+// HWPX — Hancom OWPML: a zip of Contents/sectionN.xml. Text runs live in <hp:t>
+// grouped by <hp:p> paragraphs. Walk runs + paragraph closings in document order
+// so each paragraph becomes a line (parity with the browser extractor). Old
+// binary .hwp is a CFB blob with no Node parser — degrade honestly.
+// --------------------------------------------------------------------------
+async function extractHwpx(buf) {
+    const JSZip = (await import('jszip')).default;
+    const zip = await JSZip.loadAsync(buf);
+    const sectionPaths = Object.keys(zip.files)
+        .filter((p) => /^Contents\/section\d+\.xml$/i.test(p))
+        .sort((a, b) => hwpxSectionNum(a) - hwpxSectionNum(b));
+    if (!sectionPaths.length) {
+        return {
+            text: '', quality: 'unsupported', error_kind: 'corrupt',
+            note: '한글 문서 구조를 찾지 못했습니다. 구버전 .hwp이거나 파일이 손상됐을 수 있습니다 — HWPX로 다시 저장하거나 본문을 붙여넣으세요.',
+        };
+    }
+    const lines = [];
+    for (const path of sectionPaths) {
+        const xml = await zip.files[path].async('string');
+        lines.push(...hwpxParagraphs(xml));
+        if (lines.length >= MAX_UNITS)
+            break;
+    }
+    const text = lines.join('\n').trim();
+    if (text.length < 40) {
+        return { text: '', quality: 'low', note: '한글 문서에서 텍스트를 거의 찾지 못했습니다 (이미지 위주일 수 있습니다).' };
+    }
+    return { text, quality: 'medium', note: text.length < 400 ? '추출된 텍스트가 적습니다. 핵심 본문은 붙여넣으면 더 정확합니다.' : undefined };
+}
+function hwpxSectionNum(p) {
+    return parseInt(/section(\d+)/i.exec(p)?.[1] ?? '0', 10);
+}
+function hwpxParagraphs(xml) {
+    const lines = [];
+    let cur = '';
+    const re = /<(?:\w+:)?t\b[^>]*>([\s\S]*?)<\/(?:\w+:)?t>|<\/(?:\w+:)?p>/g;
+    let m;
+    while ((m = re.exec(xml))) {
+        if (m[1] !== undefined) {
+            cur += decodeXmlEntities(m[1]);
+        }
+        else {
+            const line = cur.replace(/\s+/g, ' ').trim();
+            if (line)
+                lines.push(line);
+            cur = '';
+        }
+    }
+    const tail = cur.replace(/\s+/g, ' ').trim();
+    if (tail)
+        lines.push(tail);
+    return lines;
+}
+function decodeXmlEntities(s) {
+    return s
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => codePoint(parseInt(h, 16)))
+        .replace(/&#(\d+);/g, (_, d) => codePoint(parseInt(d, 10)))
+        .replace(/&amp;/g, '&');
+}
+function codePoint(n) {
+    return Number.isFinite(n) && n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : '';
+}
+// --------------------------------------------------------------------------
 // PDF — pdf.js (legacy Node build, main-thread), column-aware line rebuild.
 // --------------------------------------------------------------------------
 async function extractPdf(buf) {
@@ -119,6 +245,7 @@ async function extractPdf(buf) {
     let capped = false;
     let multiColumn = false;
     let hasTable = false;
+    let currentSection = null;
     for (let p = 1; p <= pageCount; p++) {
         if (units.length >= MAX_UNITS) {
             capped = true;
@@ -132,23 +259,12 @@ async function extractPdf(buf) {
             multiColumn = true;
         if (layout.hasTable)
             hasTable = true;
-        const blocks = groupBlocks(layout.lines);
-        for (const block of blocks) {
-            if (units.length >= MAX_UNITS) {
-                capped = true;
-                break;
-            }
-            const t = block.trim();
-            if (t.length < 2)
-                continue;
-            units.push({
-                unit_id: stableId('u', 'pdf', p, t.slice(0, 40)),
-                kind: 'paragraph',
-                text: t,
-                source_anchor: { page: p },
-                confidence: 0.8,
-            });
-        }
+        // Line-level segmentation (see extract-core.emitPdfUnits): pdf.js emits no
+        // blank lines, so a whole page used to collapse into one unit with every
+        // heading buried. This splits per line — headings become their own units.
+        currentSection = emitPdfUnits(layout.lines, p, units, currentSection, () => { capped = true; });
+        if (capped)
+            break;
     }
     const caps = {
         pages_total: doc.numPages,

package/dist/lib/review/index.js

@@ -11,7 +11,7 @@
 export * from './schema.js';
 export { ingest } from './ingest.js';
 export { scoreReviewability } from './reviewability.js';
-export { LENSES, getLens, ALL_LENS_IDS, LENS_VERSION } from './lenses.js';
+export { LENSES, getLens, ALL_LENS_IDS, LENS_VERSION, lensLabel } from './lenses.js';
 export { routeLenses, applies } from './routing.js';
 export { buildExtractionPrompt, buildLensPrompt, buildSynthesisPrompt, renderUnits } from './prompts.js';
 export { receiptToMarkdown } from './render.js';