knowme-careerforge-skill 0.0.4 → 0.0.7

package/dist/scripts/validation/validate-ats.js

@@ -1,173 +1,11 @@
 #!/usr/bin/env ts-node
 "use strict";
-/**
- * KnowMe CareerForge — ATS Text Flow & Heading Hierarchy Inspector
- * 验证 HTML 简历中的关键文本可提取性、标头层级规范与 ATS 机器解析友好度。
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateAts = validateAts;
-const playwright_1 = require("playwright");
-const path = __importStar(require("path"));
-const fs = __importStar(require("fs"));
-const STANDARD_SECTION_HEADERS = [
-    '工作经历', '工作经验', 'work experience', 'experience',
-    '项目经历', '核心项目', 'projects', 'key projects',
-    '专业技能', '核心技能', 'skills', 'technical skills',
-    '教育背景', '教育经历', 'education',
-    '核心领导力', '重大经历', '资质与证书', '求职意向'
-];
-async function validateAts(htmlPath) {
-    const absoluteHtml = path.resolve(htmlPath);
-    if (!fs.existsSync(absoluteHtml)) {
-        throw new Error(`HTML file not found: ${absoluteHtml}`);
-    }
-    const browser = await playwright_1.chromium.launch({ headless: true });
-    const page = await browser.newPage();
-    await page.goto(`file://${absoluteHtml}`, { waitUntil: 'networkidle' });
-    const rawData = await page.evaluate(() => {
-        const nameEl = document.querySelector('.candidate-name') || document.querySelector('h1');
-        const candidateName = nameEl ? nameEl.textContent?.trim() || null : null;
-        const bodyText = document.body.innerText || '';
-        const emailMatch = bodyText.match(/[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+/);
-        const phoneMatch = bodyText.match(/1[3-9]\d{9}|\+?\d{1,4}[-\s]?\d{7,11}/);
-        const headings = Array.from(document.querySelectorAll('h1, h2, h3, h4')).map(h => ({
-            level: h.tagName.toLowerCase(),
-            text: h.textContent?.replace(/[\s\n]+/g, ' ').trim() || ''
-        }));
-        return {
-            candidateName,
-            email: emailMatch ? emailMatch[0] : null,
-            phone: phoneMatch ? phoneMatch[0] : null,
-            headings,
-            totalTextLength: bodyText.trim().length
-        };
-    });
-    await browser.close();
-    const warnings = [];
-    const errors = [];
-    if (!rawData.candidateName) {
-        errors.push('Candidate name (.candidate-name or h1) could not be extracted');
-    }
-    if (!rawData.email) {
-        warnings.push('No valid email address pattern detected in text flow');
-    }
-    if (!rawData.phone) {
-        warnings.push('No standard mobile phone pattern detected in text flow');
-    }
-    const validatedHeadings = rawData.headings.map(h => {
-        const textClean = h.text.toLowerCase();
-        const isStandard = STANDARD_SECTION_HEADERS.some(sh => textClean.includes(sh.toLowerCase()));
-        return {
-            ...h,
-            isStandard
-        };
-    });
-    const nonStdHeadings = validatedHeadings.filter(h => !h.isStandard && h.level === 'h2');
-    if (nonStdHeadings.length > 0) {
-        warnings.push(`Non-standard section headings detected: ${nonStdHeadings.map(h => `"${h.text}"`).join(', ')}`);
-    }
-    const status = errors.length > 0 ? 'FAIL' : warnings.length > 0 ? 'WARN' : 'PASS';
-    return {
-        status,
-        candidateName: rawData.candidateName,
-        detectedContacts: {
-            email: rawData.email,
-            phone: rawData.phone
-        },
-        headingsFound: validatedHeadings,
-        totalTextLength: rawData.totalTextLength,
-        warnings,
-        errors
-    };
-}
-async function main() {
-    const args = process.argv.slice(2);
-    let htmlPath = 'workspace/resume.html';
-    let jsonOutput = false;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--html' || args[i] === '-i') {
-            htmlPath = args[i + 1];
-            i++;
-        }
-        else if (args[i] === '--json') {
-            jsonOutput = true;
-        }
-        else if (!args[i].startsWith('-')) {
-            htmlPath = args[i];
-        }
-    }
-    try {
-        const result = await validateAts(htmlPath);
-        if (jsonOutput) {
-            console.log(JSON.stringify(result, null, 2));
-            process.exit(result.status === 'FAIL' ? 1 : 0);
-        }
-        console.log('======================================================');
-        console.log(`  KnowMe CareerForge — ATS Compliance QA: [${result.status}]`);
-        console.log(`  Candidate Name : ${result.candidateName || 'NOT FOUND'}`);
-        console.log(`  Phone Extracted: ${result.detectedContacts.phone || 'NOT DETECTED'}`);
-        console.log(`  Email Extracted: ${result.detectedContacts.email || 'NOT DETECTED'}`);
-        console.log(`  Text Extracted : ${result.totalTextLength} characters`);
-        console.log('------------------------------------------------------');
-        console.log('  Headings Structure:');
-        for (const h of result.headingsFound) {
-            const mark = h.isStandard ? '[✓]' : '[?]';
-            console.log(`    ${mark} <${h.level}> ${h.text}`);
-        }
-        if (result.warnings.length > 0) {
-            console.log('\n[!] Warnings:');
-            for (const w of result.warnings) {
-                console.log(`  - ⚠️  ${w}`);
-            }
-        }
-        if (result.errors.length > 0) {
-            console.log('\n[✗] Errors:');
-            for (const e of result.errors) {
-                console.log(`  - ✗ ${e}`);
-            }
-        }
-        console.log('======================================================');
-        process.exit(result.status === 'FAIL' ? 1 : 0);
-    }
-    catch (err) {
-        const errorMsg = err instanceof Error ? err.message : String(err);
-        console.error(`[✗] ATS Validation Failed: ${errorMsg}`);
-        process.exit(1);
-    }
-}
-if (require.main === module) {
-    main();
+/** Basic text availability is part of the same final-PDF acceptance gate. */
+const engine = require("../rendering/engine-loader");
+function validateAts(htmlPath, expectedPages = 1, options = {}) {
+    return engine.run(htmlPath, { ...options, expectedPages });
 }
+if (require.main === module)
+    engine.cli();

package/dist/scripts/validation/validate-layout.d.ts

@@ -1,24 +1,3 @@
 #!/usr/bin/env ts-node
-/**
- * KnowMe CareerForge — Playwright DOM Layout & Overflow Inspector
- * 基于无头浏览器真实渲染计算 DOM 盒模型高度，检测单页/双页物理 A4 溢出与孤行。
- */
-interface LayoutValidationResult {
-    status: 'PASS' | 'OVERFLOW';
-    expectedPages: number;
-    totalPagesFound: number;
-    pageDetails: Array<{
-        pageIndex: number;
-        actualHeightPx: number;
-        allowedHeightPx: number;
-        isOverflow: boolean;
-        overflowDeltaPx: number;
-    }>;
-    overflowSections: Array<{
-        selector: string;
-        bottomPx: number;
-        overflowByPx: number;
-    }>;
-}
-export declare function validateLayout(htmlPath: string, expectedPages?: number): Promise<LayoutValidationResult>;
-export {};
+import type { EngineOptions, EngineResult } from '../rendering/browser-engine';
+export declare function validateLayout(htmlPath: string, expectedPages?: number, options?: EngineOptions): Promise<EngineResult>;

package/dist/scripts/validation/validate-layout.js

@@ -1,164 +1,10 @@
 #!/usr/bin/env ts-node
 "use strict";
-/**
- * KnowMe CareerForge — Playwright DOM Layout & Overflow Inspector
- * 基于无头浏览器真实渲染计算 DOM 盒模型高度，检测单页/双页物理 A4 溢出与孤行。
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateLayout = validateLayout;
-const playwright_1 = require("playwright");
-const path = __importStar(require("path"));
-const fs = __importStar(require("fs"));
-async function validateLayout(htmlPath, expectedPages = 1) {
-    const absoluteHtml = path.resolve(htmlPath);
-    if (!fs.existsSync(absoluteHtml)) {
-        throw new Error(`HTML file not found: ${absoluteHtml}`);
-    }
-    const browser = await playwright_1.chromium.launch({ headless: true });
-    const context = await browser.newContext({
-        viewport: { width: 794, height: 1123 }, // A4 at 96 DPI
-        deviceScaleFactor: 1
-    });
-    const page = await context.newPage();
-    await page.goto(`file://${absoluteHtml}`, { waitUntil: 'networkidle' });
-    await page.evaluateHandle('document.fonts.ready');
-    // A4 标准高度 (297mm in pixels at 96 DPI ~= 1122.5px)
-    const A4_HEIGHT_PX = 1122.5;
-    const evaluation = await page.evaluate((allowedHeight) => {
-        const pages = Array.from(document.querySelectorAll('.resume-page'));
-        const details = pages.map((p, idx) => {
-            const rect = p.getBoundingClientRect();
-            const actualHeight = Math.ceil(rect.height);
-            const isOverflow = actualHeight > allowedHeight + 2; // 2px 浮点容差
-            return {
-                pageIndex: idx + 1,
-                actualHeightPx: actualHeight,
-                allowedHeightPx: allowedHeight,
-                isOverflow,
-                overflowDeltaPx: isOverflow ? Math.ceil(actualHeight - allowedHeight) : 0
-            };
-        });
-        const overflowSections = [];
-        if (details.some(d => d.isOverflow)) {
-            const items = Array.from(document.querySelectorAll('.experience-item, .project-item, .skills-content, .resume-section'));
-            for (const item of items) {
-                const rect = item.getBoundingClientRect();
-                if (rect.bottom > allowedHeight) {
-                    overflowSections.push({
-                        selector: item.className ? `.${item.className.split(' ').join('.')}` : item.tagName.toLowerCase(),
-                        bottomPx: Math.ceil(rect.bottom),
-                        overflowByPx: Math.ceil(rect.bottom - allowedHeight)
-                    });
-                }
-            }
-        }
-        return {
-            totalPagesFound: pages.length || 1,
-            pageDetails: details.length ? details : [{
-                    pageIndex: 1,
-                    actualHeightPx: Math.ceil(document.body.getBoundingClientRect().height),
-                    allowedHeightPx: allowedHeight,
-                    isOverflow: document.body.getBoundingClientRect().height > allowedHeight + 2,
-                    overflowDeltaPx: Math.max(0, Math.ceil(document.body.getBoundingClientRect().height - allowedHeight))
-                }],
-            overflowSections
-        };
-    }, A4_HEIGHT_PX);
-    await browser.close();
-    const hasOverflow = evaluation.pageDetails.some(p => p.isOverflow) || evaluation.totalPagesFound > expectedPages;
-    return {
-        status: hasOverflow ? 'OVERFLOW' : 'PASS',
-        expectedPages,
-        totalPagesFound: evaluation.totalPagesFound,
-        pageDetails: evaluation.pageDetails,
-        overflowSections: evaluation.overflowSections
-    };
-}
-async function main() {
-    const args = process.argv.slice(2);
-    let htmlPath = 'workspace/resume.html';
-    let expectedPages = 1;
-    let jsonOutput = false;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--html' || args[i] === '-i') {
-            htmlPath = args[i + 1];
-            i++;
-        }
-        else if (args[i] === '--expected-pages' || args[i] === '-p') {
-            expectedPages = parseInt(args[i + 1], 10) || 1;
-            i++;
-        }
-        else if (args[i] === '--json') {
-            jsonOutput = true;
-        }
-        else if (!args[i].startsWith('-')) {
-            htmlPath = args[i];
-        }
-    }
-    try {
-        const result = await validateLayout(htmlPath, expectedPages);
-        if (jsonOutput) {
-            console.log(JSON.stringify(result, null, 2));
-            process.exit(result.status === 'PASS' ? 0 : 1);
-        }
-        console.log('======================================================');
-        console.log(`  KnowMe CareerForge — Layout QA: ${result.status}`);
-        console.log(`  HTML Path      : ${htmlPath}`);
-        console.log(`  Expected Pages : ${result.expectedPages} | Pages Found: ${result.totalPagesFound}`);
-        console.log('------------------------------------------------------');
-        for (const p of result.pageDetails) {
-            const fitText = p.isOverflow ? `[✗ OVERFLOW by ${p.overflowDeltaPx}px]` : `[✓ FIT] (Overflow: ${p.overflowDeltaPx}px)`;
-            console.log(`  Page ${p.pageIndex}: ${p.actualHeightPx}px / ${p.allowedHeightPx}px ${fitText}`);
-        }
-        if (result.overflowSections.length > 0) {
-            console.log('\n[!] Offending Overflow Elements:');
-            for (const el of result.overflowSections.slice(0, 3)) {
-                console.log(`  - Element "${el.selector}" exceeds A4 baseline by ${el.overflowByPx}px (Bottom: ${el.bottomPx}px)`);
-            }
-            console.log('\n💡 Recommendation: Reduce --resume-space-section by 1~2pt or reduce --resume-font-size-body by 0.2pt in <style>.');
-        }
-        console.log('======================================================');
-        process.exit(result.status === 'PASS' ? 0 : 1);
-    }
-    catch (err) {
-        const errorMsg = err instanceof Error ? err.message : String(err);
-        console.error(`[✗] Layout Validation Failed: ${errorMsg}`);
-        process.exit(1);
-    }
-}
-if (require.main === module) {
-    main();
+const engine = require("../rendering/engine-loader");
+function validateLayout(htmlPath, expectedPages = 1, options = {}) {
+    return engine.run(htmlPath, { ...options, expectedPages });
 }
+if (require.main === module)
+    engine.cli();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowme-careerforge-skill",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "description": "An agent-native skill for self-discovery, career positioning, and tailored resume engineering.",
   "main": "dist/cli/src/index.js",
   "bin": {
@@ -13,7 +13,10 @@
     "scripts",
     "agents",
     "SKILL.md",
-    "skill.json"
+    "skill.json",
+    "references",
+    "AGENT.md",
+    "ARCHITECTURE.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -31,7 +34,8 @@
     "build:gallery": "python3 scripts/build/build-gallery.py",
     "release": "python3 scripts/build/release.py",
     "version:sync": "python3 scripts/build/sync-version.py",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm test",
+    "pretest": "npm run build"
   },
   "keywords": [
     "career-forge",
@@ -55,8 +59,15 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "playwright": "^1.49.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "pdf-lib": "^1.17.1",
+    "pdfjs-dist": "^5.4.624",
+    "playwright": "^1.62.1"
+  },
+  "engines": {
+    "node": ">=22.13.0"
   }
 }

package/references/01-evidence-mining.md

@@ -0,0 +1,35 @@
+# Turn supplied facts into resume claims
+
+Read this when composing or materially rewriting candidate content. Compare with the user's original messages or supplied resume, not just an Agent-generated profile. Tools verify that profile text survives rendering; they cannot establish that the profile was faithful in the first place.
+
+## Compose, then check against the source
+
+1. Identify supplied facts and the target role separately. Treat role/JD knowledge as requirements to compare, not personal qualifications. Do not read role profiles for a straightforward rewrite; consult them only for a specific positioning question.
+2. Write a concise draft of the content. Every skill, responsibility, mechanism, result and level of proficiency must be supported by supplied material. Professional editing can improve order and clarity without increasing ownership, scope or certainty.
+3. Before saving the profile, compare the claims with the original source. Remove unsupported additions; ask only when a consequential ambiguity prevents a useful result. Keep this comparison internal, without a separate report or approval round. If helpful for a nontrivial rewrite, the existing bullet `evidenceSource` string can record a short source quotation; it is not printed and is not an independent verification claim.
+
+Check each changed dimension: **technology · ownership · scope · mechanism · result · certainty**. A target title can go in the job objective; it cannot change an actual employment title, create years of experience in another stack, or become an item in skills.
+
+## Concrete rewrite boundaries
+
+These are isolated editing examples, not candidate material or a profile to execute.
+
+| Supplied statement | Faithful treatment | Unsupported addition |
+| --- | --- | --- |
+| Worked with Node.js and NestJS; wants a Java role | Keep the actual stack; use Java only in the target title until the user supplies Java skills | Add Java/Git to skills, or describe the period as Java experience |
+| Participated in Redis and message-queue work | Keep “participated” and the unnamed message queue | Led architecture; Kafka/RocketMQ; cache prewarming; payment/event pipelines |
+| Optimized queries; response time decreased about 40% under high concurrency | Retain that result and its qualification in the strongest relevant work bullet | Average/P99, 20ms, QPS, indexing or SQL execution-plan changes not supplied |
+| Developed order, user and payment modules | Describe the modules in the work entry | Invent a separately named high-concurrency project, new project dates or a “core owner” role |
+| Used Spring Boot and MySQL | List those technologies or the supplied use case | Expert JVM/JUC knowledge, deep index internals, distributed transactions |
+| Bachelor degree and a major, without school/dates | Include the two known education fields; omit unknown fields | Guess a university, dates, GPA or claim that all education data is complete |
+
+Do not turn a suggested outcome into a required ingredient of every bullet. A duty without a metric remains valid. One supplied project can be developed into a project entry when actual context and contributions are available; do not duplicate the same work as a second achievement just to fill a section. Keep a brief summary distinct from detailed work bullets.
+
+## Continue safely across turns
+
+- User acceptance such as “use this version” authorizes progressing with known facts. It does not retroactively support a skill or achievement introduced by the Agent. Correct your unsupported additions before export; explain a material correction briefly instead of silently preserving it.
+- When real candidate material arrives after an explicitly requested fictional example, build the candidate profile from that material. Reusing the layout is fine; filling over a fictional profile risks leaving invented skills and achievements behind.
+- On a contact-only update, change only those fields and necessary resulting layout. Do not rewrite summary/skills/projects, change template, add qualifications or re-ask the whole questionnaire. If continuing in a new session, use the prior current profile/canvas and ask only if the current revision is genuinely ambiguous.
+- Supplied wording may be strengthened only by stronger supplied facts; do not weaken explicit ownership merely because the source is chat. Conflicting dates or roles require a focused clarification or omission of the disputed claim, not guessing.
+
+Use Draft for a requested partial canvas, not simply because optional fields are missing. Master preserves this run's known facts and does not certify their external truth. Missing values remain omitted/null. See 07-artifact-contract.md for data shapes and tool states.

package/references/02-career-goal.md

@@ -0,0 +1,40 @@
+# Reference Manual 02: Career Goal Definition & Role Archetypes
+
+> **"Know Yourself. Define Your Direction. Forge Your Opportunity."**
+
+---
+
+## 1. Professional Seniority Signals
+
+Use these archetypes to guide questions, not to infer facts. Years alone do not establish seniority, ownership or proficiency. Preserve the user’s stated role and responsibility; omit unsupported claims from the following illustrative patterns.
+
+| Seniority Tier | Core Value Proposition | Key Narrative Signals | Section Priority |
+|:---|:---|:---|:---|
+| **Junior (1~3 Years)** | Rapid learning, solid coding standards, reliable task delivery | Clean code, unit test coverage, framework fluency, bug resolution | Skills → Projects → Experience → Education |
+| **Mid-Level (3~5 Years)** | Independent ownership, feature architecture, performance optimization | End-to-end module ownership, database tuning, API design, CI/CD | Experience → Projects → Skills → Education |
+| **Senior / Lead (5~8+ Years)** | System architecture, technical leadership, cross-system trade-offs | Distributed systems, high availability, mentoring, business impact | Experience → Projects → Architecture → Skills |
+| **Principal / Architect** | Technical vision, organizational strategy, governance, ROI | Architecture governance, multi-team alignment, technology selection | Experience → Leadership → Architecture → Patents |
+
+---
+
+## 2. Role Archetypes Knowledge Base (`src/knowledge/roles/*.json`)
+
+Read a role profile only for a specific positioning question after candidate facts are available. `mustHaveSkills`, `niceToHaveSkills` and `evidenceSignals` describe hiring expectations and question topics; they are never defaults for personal skills, mechanisms or accomplishments. A generic role name may cover several seniority levels.
+
+The skill ships with 9+ structured role profiles:
+- `ai-agent-engineer.json`: LLM Orchestration, RAG, Tool Calling, VectorDB, Prompt Engineering
+- `frontend.json`: React/Vue/Next.js, Web Vitals, Design Systems, State Management
+- `java-backend.json`: Spring Boot, JVM tuning, Distributed Caching, Message Queues
+- `node-fullstack.json`: TypeScript, Node.js runtime, GraphQL, Cloud Native
+- `architect.json`: Distributed Systems, Domain-Driven Design, High Concurrency, Cloud Architecture
+- `product-manager.json`: PRD, User Research, Data Analysis, Roadmapping, Growth
+
+---
+
+## 3. Core Value Proposition Formulation
+
+If useful, write a short headline from supplied facts. The following formula is optional: omit years, strengths or impact when unknown. The example is fictional and must never fill a candidate record.
+$$\text{Value Proposition} = [\text{Target Role}] + [\text{Years/Domain Focus}] + [\text{Top 2 Signature Strengths}] + [\text{Concrete Impact Deliverable}]$$
+
+*Example*:
+> **Senior AI Agent Engineer** with 5+ years building scalable LLM orchestration & enterprise RAG pipelines, delivering 40% latency reduction across multi-agent production workflows.

package/references/03-jd-analysis.md

@@ -0,0 +1,32 @@
+# Reference Manual 03: Job Description (JD) Analysis & Keyword Extraction
+
+> **"Understand the hiring manager's unstated pain point to align your verified strengths."**
+
+---
+
+## 1. Automated JD Signal Parsing Protocol
+
+Execute the JD analyzer to extract structured requirements:
+```bash
+python3 scripts/evidence/analyze-jd.py --jd "path/to/jd.md" --json
+```
+
+### Signal Extraction Dimensions:
+1. **Target Role & Seniority Tier**: Extracted from title and years of experience requirements;
+2. **Must-Have Skills (Hard Constraints)**: Top technical stacks and non-negotiable architectural competencies;
+3. **Nice-to-Have Skills (Differentiators)**: Emerging tools, cloud certifications, domain bonuses;
+4. **Hiring Pain Points**: High-frequency verbs indicating immediate business challenges (e.g., "reduce latency", "overhaul legacy monolithic service", "establish CI/CD").
+
+---
+
+## 2. Keyword Density & Highlighting Rules
+
+Use JD terms only where the candidate has supplied matching experience. Keywords select or emphasize existing facts; they do not add skills to a Master or Variant. A technology named only by the vacancy remains a gap to discuss.
+
+Prefer a few relevant, readable terms over repetition. There is no project-validated universal ATS keyword-density threshold. Do not claim automated screening success from keyword counts.
+
+## 3. Writing useful bullets
+
+Describe the supplied action and its context. Add the method and outcome only when the user provided them. FAB is an optional editing aid, not a requirement that every duty acquire an invented business impact.
+
+For example, if the only fact is “optimized order queries”, a faithful rewrite is “Optimized order queries for the ecommerce service” only if that service context was supplied. Do not infer indexing, Redis caching, P99 latency or traffic multiples. Preserve “participated” versus “led”, and ask for consequential missing mechanisms instead of writing them as facts.

package/references/04-template-selection.md

@@ -0,0 +1,30 @@
+# Template selection and readable composition
+
+Select for the candidate's actual amount of content, strongest evidence and explicit preference. A backend title alone does not determine the layout. The ten current IDs below are directory IDs accepted by the pipeline; metadata describes design intent, not visual or ATS certification.
+
+| ID | Structure | Review before choosing |
+| --- | --- | --- |
+| minimal | Single column | Straight reading order; sparse content needs breathing room rather than compression |
+| international-flow | Single column | Consider for linear prose; inspect language and line lengths |
+| modern | Sidebar, 32:68 | Keep side content short; check narrow-column wrapping |
+| creative-tech | Sidebar, 28:72 | Use only when the visual emphasis suits the user |
+| data-analyst | Sidebar, 30:70 | Do not invent metrics to match the template name |
+| executive | Banner and split columns | Needs suitable supplied leadership evidence; a title does not confer it |
+| classic | Structured table | Check sparse fields and reading order |
+| compact-dense | Dense two columns | For substantial supplied content; avoid for a short career description |
+| academic-research | Dense single column | Research content must actually be supplied |
+| startup-generalist | Modular cards | Check block balance with the actual sections |
+
+Use the existing search when no template was selected:
+
+```bash
+python3 <skill-root>/scripts/template/search-template.py "<target role>" --target-pages 1 --summary
+```
+
+The summary returns the top three candidates with IDs and layout metadata; the existing `--json` option returns all metadata only when needed. For a simple, sparse resume, prefer a readable single-column structure from the table over a dense sidebar just because it has a higher role score. Do not load every template source or build a gallery for a single resume.
+
+The pipeline also ranks automatically if `--template` is omitted. Ranking does not inspect the final PDF's aesthetics. Inspect the selected output and report `templateUsed`; do not claim that all ten designs were visually compared if only one was rendered.
+
+For experienced candidates, work evidence should be easy to find. Keep skill lists compact; avoid paragraphs claiming proficiency in every role keyword. A summary and a project section are optional, and should not repeat the same achievement. For sparse profiles, preserve honest whitespace, use a simple layout and ask for useful details only when needed. Do not fill a page with generic qualities or fabricated projects. For dense profiles, edit repetition before reducing type size or spacing.
+
+Each template maintains `canvas.html`, `style.css`, `metadata.json`, `README.md` and a fictional `sample-profile.json`. Gallery previews use the same instantiator, combining common/base.css, template style.css and common/canvas-bindings.css. Read source only for a needed layout edit; never load gallery sample content to assemble candidate facts. Token tuning is described in 05-html-canvas-tokens.md. Multiple PDF pages require explicit page containers, regardless of metadata's maximum page count.

package/references/05-html-canvas-tokens.md

@@ -0,0 +1,12 @@
+# HTML canvas and tokens
+
+Instantiate an empty canvas.html skeleton with explicit user facts. canvas.html is the sole maintained structure. Gallery previews bind explicit fictional sample-profile.json through the same instantiator and full CSS chain; sample data must never serve as default candidate facts. Shared normalization accepts omitted/null optional fields and rejects invalid types. Failed binding must preserve old output and return nonzero.
+
+Tune the run's HTML with CSS variables for section/item/bullet spacing and body typography. Preserve manually edited content rather than regenerating stale profile data. Auto-healing cannot remove facts or reduce body font below 8.8pt. Validate in print mode, inspect all pages and verify the actual PDF before delivery. See 07-artifact-contract.md.
+
+
+## 本地字体与缺字诊断
+
+`forge.py` 和 `instantiate-resume.py` 支持 `--font-preset system|arial-unicode`，默认保留系统字体。`arial-unicode` 显式使用本机 Arial Unicode MS；没有该字体时字体验收失败并返回 UNVERIFIED，不保证跨机器可用，也不自动下载字体。字体选择只改变画布样式，不改变 Master 事实，并记录在 Variant 的 source.fontPreset 和运行清单中。
+
+中文 PDF 若文本验收失败，检查 QA 每页的 missingCodepoints、missingFragments 与 extractedRadicals。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。

package/references/06-qa-and-rendering.md

@@ -0,0 +1,27 @@
+# QA and final rendering
+
+Validation and rendering use scripts/rendering/browser-engine.js. Inspect print media after fonts settle, every page container and visible content boundary; generate a fresh PDF and parse every page for A4 portrait dimensions, allowed page count and extractable content matching the canvas.
+
+PASS requires the actual checks to complete. Missing browser/dependencies or timeout is UNVERIFIED (exit 2), a failed check is FAIL (exit 1). JSON mode uses the same exit rules. Do not use an estimate or an existing PDF as proof. Export verified bytes through a temporary file and atomic replacement; failed export retains the previous file.
+
+The pipeline isolates each run and records artifact hashes in manifest.json. Use its current PASS output paths, not shared default filenames. Factual and visual review remain Agent responsibilities; text extraction does not certify every ATS. See 07-artifact-contract.md for the complete lifecycle.
+
+
+## 本地字体与缺字诊断
+
+`forge.py` 和 `instantiate-resume.py` 支持 `--font-preset system|arial-unicode`，默认保留系统字体。`arial-unicode` 显式使用本机 Arial Unicode MS；没有该字体时字体验收失败并返回 UNVERIFIED，不保证跨机器可用，也不自动下载字体。字体选择只改变画布样式，不改变 Master 事实，并记录在 Variant 的 source.fontPreset 和运行清单中。
+
+中文 PDF 若文本验收失败，检查 QA 每页的 missingCodepoints、missingFragments 与 extractedRadicals。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。
+
+## What each check can actually establish
+
+| Evidence | What it supports | What it cannot establish |
+| --- | --- | --- |
+| Original user material compared with rewritten claims | Fidelity to supplied facts | Independent verification of the user's history |
+| Master/Variant hashes and bound text | Run provenance and rendering consistency | That Agent-written profile claims came from the user |
+| Current PDF page/text/layout checks | Technical PDF acceptance | Complete optional information, ideal design or universal ATS support |
+| Every page of the final PDF viewed | Actual visual appearance of those pages | Authenticity of the candidate's achievements |
+
+Inspect the PDF itself using the host's PDF viewer or an available PDF-to-image tool, not a screen-media HTML preview. If no such tool is available, say the PDF's visual review is incomplete; keep the technical PASS distinction. Do not install a second rendering system just to repeat checks the pipeline already performed.
+
+When a font mapping warning occurs, read the reported missing fragments/codepoints and compare with the source text and page appearance. A warning is a diagnostic clue, not a diagnosis or an automatic reason to force a specific font. Use an available explicit font only as a justified retry; preserve facts and recheck the new PDF. After the current export and review pass, deliver rather than creating more copies or rerunning unchanged checks.