knowme-careerforge-skill 0.0.2 → 0.0.6

package/src/knowledge/templates.json

@@ -1,5 +1,68 @@
 {
   "templates": [
+    {
+      "id": "academic-research",
+      "name": "Academic Research Flow",
+      "version": "1.0.0",
+      "style": "single-column-academic",
+      "roleCategory": "research-algorithm",
+      "layout": {
+        "type": "single-column",
+        "targetPages": 1,
+        "maxPages": 2,
+        "density": "ultra"
+      },
+      "visualStyle": {
+        "tone": "oxford-navy",
+        "accentColor": "#1e3a8a",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "ai-agent-engineer",
+        "algorithm-engineer",
+        "research-scientist",
+        "data-scientist",
+        "nlp-engineer",
+        "cv-engineer",
+        "phd-candidate",
+        "postdoc"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/academic-research",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-accent-bg",
+        "--resume-color-border",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-tag-bg",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-page-padding",
+        "--resume-space-bullet",
+        "--resume-space-header-bottom",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
+    },
     {
       "id": "classic",
       "name": "Table Structured Modern",
@@ -33,6 +96,9 @@
       "customizableTokens": [
         "--resume-font-size-body",
         "--resume-cell-padding",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
         "--resume-color-accent",
         "--resume-color-label-bg"
       ],
@@ -51,9 +117,203 @@
         "--resume-font-size-meta",
         "--resume-font-size-title",
         "--resume-line-height-body",
-        "--resume-page-min-height",
         "--resume-page-padding",
-        "--resume-page-width"
+        "--resume-space-bullet",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
+    },
+    {
+      "id": "compact-dense",
+      "name": "Compact Dense Grid",
+      "version": "1.0.0",
+      "style": "two-column-dense",
+      "roleCategory": "engineering-senior",
+      "layout": {
+        "type": "two-column-dense",
+        "targetPages": 1,
+        "maxPages": 1,
+        "density": "ultra"
+      },
+      "visualStyle": {
+        "tone": "steel-blue",
+        "accentColor": "#0369a1",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "architect",
+        "backend",
+        "frontend",
+        "fullstack",
+        "cpp-systems",
+        "java-backend",
+        "devops",
+        "tech-lead"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/compact-dense",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-accent-bg",
+        "--resume-color-border",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-tag-bg",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-page-padding",
+        "--resume-space-bullet",
+        "--resume-space-header-bottom",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
+    },
+    {
+      "id": "creative-tech",
+      "name": "Creative Tech Split",
+      "version": "1.0.0",
+      "style": "two-column-split",
+      "roleCategory": "frontend-creative",
+      "layout": {
+        "type": "two-column-sidebar",
+        "targetPages": 1,
+        "maxPages": 1,
+        "sidebarRatio": "28:72",
+        "density": "balanced"
+      },
+      "visualStyle": {
+        "tone": "tech-violet",
+        "accentColor": "#7c3aed",
+        "sidebarBg": "#faf5ff",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "frontend",
+        "ui-ux-engineer",
+        "creative-technologist",
+        "web-architect",
+        "design-system-engineer",
+        "node-fullstack"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-sidebar-width",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/creative-tech",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-accent-light",
+        "--resume-color-border",
+        "--resume-color-indigo",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-sidebar-bg",
+        "--resume-color-sidebar-border",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-sidebar-width",
+        "--resume-space-bullet",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
+    },
+    {
+      "id": "data-analyst",
+      "name": "Data Analyst Metric Stream",
+      "version": "1.0.0",
+      "style": "two-column-metrics",
+      "roleCategory": "data-analytics",
+      "layout": {
+        "type": "two-column-sidebar",
+        "targetPages": 1,
+        "maxPages": 1,
+        "sidebarRatio": "30:70",
+        "density": "high"
+      },
+      "visualStyle": {
+        "tone": "amber-cyan",
+        "accentColor": "#0891b2",
+        "sidebarBg": "#f0fdfa",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "data-analyst",
+        "data-scientist",
+        "bi-engineer",
+        "growth-architect",
+        "data-engineer",
+        "machine-learning-engineer"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-sidebar-width",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/data-analyst",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-accent-dark",
+        "--resume-color-accent-light",
+        "--resume-color-border",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-sidebar-bg",
+        "--resume-color-sidebar-border",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-sidebar-width",
+        "--resume-space-bullet",
+        "--resume-space-item",
+        "--resume-space-section"
       ]
     },
     {
@@ -113,13 +373,73 @@
         "--resume-font-size-title",
         "--resume-left-col-width",
         "--resume-line-height-body",
-        "--resume-page-min-height",
-        "--resume-page-width",
         "--resume-space-bullet",
         "--resume-space-item",
         "--resume-space-section"
       ]
     },
+    {
+      "id": "international-flow",
+      "name": "International Text Flow",
+      "version": "1.0.0",
+      "style": "single-column-flow",
+      "roleCategory": "international-remote",
+      "layout": {
+        "type": "single-column",
+        "targetPages": 1,
+        "maxPages": 2,
+        "density": "balanced"
+      },
+      "visualStyle": {
+        "tone": "neutral-slate",
+        "accentColor": "#334155",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "frontend",
+        "backend",
+        "fullstack",
+        "ai-agent-engineer",
+        "product-manager",
+        "engineering-manager",
+        "remote-specialist"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/international-flow",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-accent-bg",
+        "--resume-color-border",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-tag-bg",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-page-padding",
+        "--resume-space-bullet",
+        "--resume-space-header-bottom",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
+    },
     {
       "id": "minimal",
       "name": "Minimal Tech",
@@ -175,9 +495,7 @@
         "--resume-font-size-name",
         "--resume-font-size-target",
         "--resume-line-height-body",
-        "--resume-page-min-height",
         "--resume-page-padding",
-        "--resume-page-width",
         "--resume-space-bullet",
         "--resume-space-header-bottom",
         "--resume-space-item",
@@ -243,13 +561,75 @@
         "--resume-font-size-name",
         "--resume-font-size-target",
         "--resume-line-height-body",
-        "--resume-page-min-height",
-        "--resume-page-width",
         "--resume-sidebar-width",
         "--resume-space-bullet",
         "--resume-space-item",
         "--resume-space-section"
       ]
+    },
+    {
+      "id": "startup-generalist",
+      "name": "Startup Generalist Cards",
+      "version": "1.0.0",
+      "style": "modular-cards",
+      "roleCategory": "startup-growth",
+      "layout": {
+        "type": "modular-cards",
+        "targetPages": 1,
+        "maxPages": 1,
+        "density": "high"
+      },
+      "visualStyle": {
+        "tone": "emerald-green",
+        "accentColor": "#059669",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "fullstack",
+        "indie-hacker",
+        "startup-cto",
+        "growth-engineer",
+        "product-engineer",
+        "frontend",
+        "backend"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/startup-generalist",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-accent-bg",
+        "--resume-color-border",
+        "--resume-color-card-bg",
+        "--resume-color-card-border",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-tag-bg",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-page-padding",
+        "--resume-space-bullet",
+        "--resume-space-header-bottom",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
     }
   ]
 }

package/src/references/01-evidence-mining.md

@@ -0,0 +1,5 @@
+# Organize user-supplied facts
+
+Use the user's descriptions, prior resume and explicitly supplied supporting material. Repository scanning is not a supported candidate input mode. Reuse known information; ask progressive follow-up questions only for consequential gaps. Do not invent dates, employers, degrees or metrics, or weaken stated ownership solely because it came from chat.
+
+Store incomplete information as Draft and reviewed supplied facts as Master. Derive role-specific Variant content without changing the Master. Unknown values remain omitted/null. Follow the shared lifecycle and error rules in 07-artifact-contract.md.

package/src/references/02-career-goal.md

@@ -0,0 +1,38 @@
+# Reference Manual 02: Career Goal Definition & Role Archetypes
+
+> **"Know Yourself. Define Your Direction. Forge Your Opportunity."**
+
+---
+
+## 1. Professional Seniority Signals
+
+Identify candidate level and calibrate narrative depth accordingly:
+
+| 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`)
+
+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
+
+Synthesize the 15~25 word Value Proposition headline following this formula:
+$$\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/src/references/03-jd-analysis.md

@@ -0,0 +1,44 @@
+# 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
+
+In `workspace/resume.html`, inject JD keywords to pass ATS automated screening while remaining natural for human reviewers:
+
+- **Primary Stack (Top 3~5 Keywords)**: Wrap with `<strong>` tags inside bullet points where evidence exists;
+- **Technology Badges**: Place in `.tech-tags` or `.tech-badge` spans;
+- **Density Control**: Maintain keyword density around 2.5%~4.0% of total words to prevent ATS keyword stuffing penalties.
+
+---
+
+## 3. FAB (Feature-Advantage-Benefit) Bullet Engineering
+
+Structure every project bullet point using the FAB formula:
+
+```
+┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
+│  Feature (技术动作)│ ────> │ Advantage (技术优势)│ ────> │  Benefit (业务价值) │
+│ Exact tech & tool │       │ Architectural gain│     │ Quantified impact│
+└─────────────────┘       └─────────────────┘       └─────────────────┘
+```
+
+*Before (Weak)*: Worked on database and improved query performance.  
+*After (FAB Standard)*: Refactored PostgreSQL indexing and introduced Redis multi-tier caching (**Feature**), cutting P99 query latency from 850ms to 45ms (**Advantage**), supporting 10x traffic spike during peak sales (**Benefit**).

package/src/references/04-template-selection.md

@@ -0,0 +1,43 @@
+# Reference Manual 04: Template Selection & Layout Geometries
+
+> **"Layout geometry determines information hierarchy. Select the composition that earns the candidate's strongest evidence."**
+
+---
+
+## 1. Core Template Matrix (Baseline 4)
+
+| Template ID | Layout Geometry | Tone & Accent | Target Roles | Density | ATS Tier |
+|:---|:---|:---|:---|:---|:---|
+| `minimal` (`minimal-tech`) | Single-Column Linear Flow | Geek Minimal (Tech Blue `#2563eb`) | Backend, AI/LLM, Systems, DevOps, Fullstack | High | Tier 1 (Optimal) |
+| `modern` (`modern-split-sidebar`) | Two-Column Split (32:68 Dark Sidebar) | Deep Navy (`#254665`) + Sky Blue (`#38bdf8`) | AI Agent, Frontend, Fullstack, Mobile | Balanced | Tier 1 (Optimal) |
+| `executive` (`executive-split`) | Hero Banner + Two-Column (33:67 Split) | Executive Slate (`#1e293b`) + Teal (`#0f766e`) | Tech Director, Architect, PM, CTO | Balanced | Tier 1 (Optimal) |
+| `classic` (`table-structured`) | 6-Column Structured Grid Table | Corporate Blue (`#1d4ed8`) + Slate | Enterprise, Fintech, Hardware, State-Owned | High | Tier 1 (Optimal) |
+
+---
+
+## 2. Template Search Engine (`scripts/template/search-template.py`)
+
+Search for the optimal template via CLI:
+```bash
+# Hybrid Search (Default Recommended)
+python3 scripts/template/search-template.py "AI Agent Engineer" --style "two-column-split" --target-pages 1
+
+# BM25 Keyword Search
+python3 scripts/template/search-template.py "Distributed Architect" --engine bm25 --json
+
+# Weighted Multi-Criteria Rule Search
+python3 scripts/template/search-template.py "Frontend Engineer" --engine weighted
+```
+
+### Search Scoring Formulation (Weighted Scorer):
+$$\text{Score} = (\text{RoleMatch} \times 0.35) + (\text{StyleMatch} \times 0.25) + (\text{ATSTier} \times 0.20) + (\text{PageFit} \times 0.10) + (\text{Density} \times 0.10)$$
+
+---
+
+## 3. Instantiating the Intermediate HTML Canvas
+
+```bash
+python3 scripts/template/instantiate-resume.py --template modern --profile workspace/evidence-master.json --keywords "Python,LLM,RAG,FastAPI" --output workspace/resume.html
+```
+
+*The instantiator automatically inlines `src/templates/common/base.css` + `src/templates/{template}/style.css` into a single self-contained HTML file.*

package/src/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/src/references/06-qa-and-rendering.md

@@ -0,0 +1,14 @@
+# 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。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。

package/src/references/07-artifact-contract.md

@@ -0,0 +1,64 @@
+# 资料、运行与验收契约
+
+## Draft / Master / Variant
+
+这三个值表示资料用途，不是质量评分，也不表示已独立核实事实。
+
+| kind | 用途 | 约束 |
+| --- | --- | --- |
+| draft | 用户资料尚不完整的草稿 | 可缺姓名及经历；仅生成草稿画布，不能报告 PDF 已验收 |
+| master | 用户或 Agent 整理的完整事实集合 | 每次运行只保存新快照，不反写输入；完整指保留本次已知事实，不强制具备所有可选字段 |
+| variant | 为目标岗位派生的展示资料 | 记录来源 Master 的 profileSha256；岗位标题只修改 Variant，不回写 Master；不能作为下一份 Master 隐式导入 |
+
+标准文档形状为：
+
+```json
+{
+  "schemaVersion": "1.0",
+  "kind": "master",
+  "profile": {"basics": {"name": "候选人姓名"}},
+  "source": {"type": "user-input"}
+}
+```
+
+`profile` 的字段定义见 `src/knowledge/resume-schema.json`；脚本 `scripts/contracts/profile.py` 是归一化与封装契约的实现。脚本输出时附加 `profileSha256` 和 `missingFields`。摘要用于发现资料版本变化，不证明用户陈述真实性。手动修改封装资料后，应重新生成摘要或移除旧摘要再读入；不能保留不匹配的摘要。
+
+兼容旧版的裸 profile JSON，按调用者明确提供的 Master 事实输入处理。封装为 Draft 的输入必须加 `--draft` 才能生成草稿；复核后由 Agent 显式整理为 Master，不由工具自动升级。Variant 的语义改写与事实选择仍由宿主 Agent 完成；当前脚本保留所有输入条目，只处理显式基础信息覆盖、岗位标题及展示装配。
+
+## 缺失值
+
+- 可选字段省略或 null 均表示未知，空白字符串归为 null，不生成占位候选人事实。
+- null 的数组归为空数组；数组中的空白/null 项省略。未知字段和错误类型拒绝，不能悄悄丢失可能重要的资料。
+- 教育经历、项目和工作经历为独立数组，按输入顺序完整处理；无教育描述不补“优秀毕业生”等默认荣誉。
+- 缺失联系方式和目标岗位记录为待补信息。正式交付至少需要非空姓名及实质内容，打印与 PDF 验收进一步判断内容有效性。
+- 旧版 L1/L2/L3 元数据可保留；用户陈述不因为来自对话就自动降级为“参与”。
+
+## 每次运行独立
+
+`forge --profile-json <file>` 在 `workspace/runs/<唯一运行ID>/` 下创建私有目录，包含 `input.json` 原始输入快照、`master.json`、`variant.json`、`resume.html`、`qa.json`、通过验收后写入的 `resume.pdf` 和 `manifest.json`。Draft 运行保存 `draft.json` 和草稿画布，不生成正式 PDF。
+
+`--workspace` 仅改变运行目录的父目录，不复用已有运行。失败现场保留供诊断，不自动删除或继续使用其他运行的文件。目录包含个人资料，不提交到 Git；可由用户按需删除。测试必须使用临时目录。
+
+`--html-output` 和 `--output` 是可选的已验收副本路径。先在独立运行中完成验证，再一起准备副本；写入失败时回滚普通错误，目标锁阻止两个本工具进程交错写入。跨文件复制不具备操作系统崩溃下的事务保证，因此运行目录和 manifest 始终是交付判据。发现遗留锁时报告冲突，不擅自删除其他运行的锁。
+
+## 运行与检查状态
+
+| status | 退出码 | 意义 |
+| --- | --- | --- |
+| RUNNING | 不作为最终结果 | 已开始但未完成，不能交付 |
+| DRAFT | 0 | 草稿准备完成，无 PDF 验收承诺 |
+| PASS | 0 | 本次指定检查及最终 PDF 验收通过 |
+| FAIL | 1 | 输入、绑定、布局、PDF 内容或输出写入不符合要求 |
+| UNVERIFIED | 2 | 浏览器、依赖、超时或检查协议故障，无法完成验收 |
+
+`manifest.json` 包含 `runId`、`stage`、`errors`、`warnings`、`checks`、`outputs`。失败的 `outputs` 为空，即使目录或显式输出位置存在旧 PDF，也不能返回它作为本次交付。只有 PASS 的清单记录本次输出路径及 HTML/PDF SHA-256。JSON 模式与人读模式使用同一退出语义。
+
+## 打印与最终 PDF
+
+布局与导出共用 `scripts/rendering/browser-engine.js`，以 print 媒体模式等待字体，检查所有页面容器与内容边界。再生成新的 PDF，解析所有页，检查 A4 纵向尺寸、页数上限、逐页可提取文本与正文覆盖。最终写入的是通过验收的 PDF 字节，使用临时文件原子替换，不接受旧输出文件作为生成成功的证据。
+
+自动调优不得增加当前间距，正文字号不降至 8.8pt 以下；调优失败保留原画布，不删改事实来强行过关。浏览器不可用不得用字数/盒模型估算替代 PASS。PDF 文本提取通过不代表所有 ATS 对多栏阅读顺序的解释一致；事实与视觉仍需 Agent 复核。
+
+当前分页契约要求每个 `.resume-page` 对应一个 A4 页面，`--expected-pages` 为 1 或 2 的上限。一页文档可用上限 2；两页文档需由 Agent 显式建立两个页面容器。单个超高容器自然流入多页会被拒绝，不猜测浏览器分页后每页应有的内容。
+
+输入文档的来源说明保存在 Master 的 source.suppliedSource 中，包括 synthetic-simulation 等原始标签。它是来源元数据，不是新增候选人事实。字体预设单独记录为 Variant.source.fontPreset；不得把字体修订误记为事实变更。