knowme-careerforge-skill 0.0.4 → 0.0.7

package/README.md

@@ -1,28 +1,27 @@
-# KnowMe CareerForge
+<div align="center">
+
+# 🎯 KnowMe CareerForge
 
 <p align="center">
-  <a href="README.zh-CN.md">🇨🇳 简体中文</a> | 
-  <a href="README.md">🇺🇸 English</a>
+  <strong>认识自己，明确方向，锻造属于你的职业机会。</strong><br>
+  <em>Know Yourself. Define Your Direction. Forge Your Opportunity.</em>
 </p>
 
 <p align="center">
-  <a href="https://github.com/Max-Samson/knowme-careerforge-skill/releases"><img src="https://img.shields.io/github/v/release/Max-Samson/knowme-careerforge-skill?style=for-the-badge&color=blue" alt="GitHub Release"></a>
-  <img src="https://img.shields.io/badge/role_profiles-9_standard-green?style=for-the-badge" alt="9 Role Profiles">
-  <img src="https://img.shields.io/badge/templates-4_baseline_A4-purple?style=for-the-badge" alt="4 Baseline A4 Templates">
-  <img src="https://img.shields.io/badge/python-3.9+-yellow?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.9+">
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/Max-Samson/knowme-careerforge-skill?style=for-the-badge&color=green" alt="License: MIT"></a>
+  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/语言-🇨🇳_简体中文-0284C7?style=flat" alt="简体中文"></a>
+  <a href="README.md"><img src="https://img.shields.io/badge/Language-🇺🇸_English-4F46E5?style=flat" alt="English"></a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/knowme-careerforge-skill"><img src="https://img.shields.io/npm/v/knowme-careerforge-skill?style=flat-square&logo=npm&label=npm" alt="npm package"></a>
-  <a href="https://github.com/Max-Samson/knowme-careerforge-skill/stargazers"><img src="https://img.shields.io/github/stars/Max-Samson/knowme-careerforge-skill?style=flat-square&logo=github" alt="GitHub stars"></a>
-  <img src="https://img.shields.io/badge/architecture-HTML%20Intermediate%20Canvas%20%2B%20Design%20Tokens-blue?style=flat-square" alt="HTML Intermediate Canvas">
+  <a href="https://www.npmjs.com/package/knowme-careerforge-skill"><img src="https://img.shields.io/npm/v/knowme-careerforge-skill?style=flat&logo=npm&logoColor=white&color=CB3837" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/Node.js-%3E%3D22.13-339933?style=flat&logo=nodedotjs&logoColor=white" alt="Node.js">
+  <img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript">
+  <img src="https://img.shields.io/badge/Python-3.9+-3776AB?style=flat&logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/Playwright-A4_PDF-2EAD33?style=flat&logo=playwright&logoColor=white" alt="Playwright">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-6B7280?style=flat" alt="MIT License"></a>
 </p>
 
-> **Know Yourself. Define Your Direction. Forge Your Opportunity.**
->
-> *An agent-native skill for self-discovery, career positioning, and tailored resume engineering.*
-
+</div>
 ---
 
 ## 1. What is KnowMe CareerForge?
@@ -47,7 +46,7 @@ Self Discovery  Tailored Career Story
 & Evidence      & Engineering Delivery
 ```
 
-- **KnowMe (Self-Discovery & Evidence Engine)**: Helps candidates discover who they are, uncover their verifiable career evidence (L1~L3), and map their true competitive strengths.
+- **KnowMe (Self-Discovery & Evidence Engine)**: Helps candidates discover who they are, organize their supplied career experience and supporting material, and map their true competitive strengths.
 - **CareerForge (Career Positioning & Resume Engineering)**: Translates genuine strengths into targeted positioning for specific job opportunities, tailoring high-impact content inside an **HTML Intermediate Working Canvas** with **Design Tokens**, and delivering deterministic, pixel-perfect PDFs via Playwright.
 
 ---
@@ -98,56 +97,40 @@ knowme list
 
 ---
 
-### Option B: Direct Agent Integration
+### Platform entrypoints and runtime resources
+
+| Platform | Entry location | Configuration command |
+| --- | --- | --- |
+| Claude Code | `~/.claude/skills/knowme-careerforge/SKILL.md` | `knowme init --ai claude` |
+| Codex | `~/.codex/skills/knowme-careerforge/SKILL.md` | `knowme init --ai codex` |
+| Cursor | `.cursor/rules/knowme-careerforge.mdc` | `knowme init --ai cursor` |
+| Windsurf | Managed block in `.windsurfrules` | `knowme init --ai windsurf` |
+| Gemini | `~/.gemini/skills/knowme-careerforge.json` | `knowme init --ai gemini` |
+| OpenCode | `.opencode/skills/knowme-careerforge/SKILL.md` | `knowme init --ai opencode` |
 
-| Platform | Target Configuration Path | Setup Command |
-| :--- | :--- | :--- |
-| **Cursor** | `.cursor/rules/knowme-careerforge.mdc` | `cp SKILL.md .cursor/rules/knowme-careerforge.mdc` |
-| **Claude Code** | `~/.claude/skills/knowme-careerforge/` | `cp -r knowme-careerforge-skill ~/.claude/skills/` |
-| **Codex** | `~/.codex/skills/knowme-careerforge/` | `cp -r knowme-careerforge-skill ~/.codex/skills/` |
-| **Windsurf** | `.windsurfrules` | `cat agents/windsurf/knowme-careerforge.rules >> .windsurfrules` |
-| **OpenCode** | `.opencode/skills/knowme-careerforge/` | `cp -r knowme-careerforge-skill ~/.opencode/skills/` |
+Cursor/Windsurf reference a project-local `.knowme/skills/knowme-careerforge/` runtime; Gemini configuration points to its sibling runtime directory. Each routes to the same SKILL.md workflow. File installation does not certify host discovery or behavior. Copying a prompt alone is insufficient. Rerun init after relocating an installation to refresh entry paths.
 
 ---
 
-## 4. The 3 Operational Modes
+## 4. User input and artifact lifecycle
 
-```text
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ Mode A: Target-Role Mode                                                    │
-│ User specifies a career direction (e.g., "Senior AI Agent Engineer").       │
-│ ▶ Agent loads role skill tree, extracts matching evidence, builds variant.  │
-├─────────────────────────────────────────────────────────────────────────────┤
-│ Mode B: JD-Specific Mode                                                    │
-│ User pastes a concrete Job Description (JD).                                │
-│ ▶ Agent runs analyze-jd.py, performs gap analysis, highlights hiring keys.  │
-├─────────────────────────────────────────────────────────────────────────────┤
-│ Mode C: Repo-to-Resume Mode                                                 │
-│ User supplies a GitHub repository / codebase / project notes.               │
-│ ▶ Agent inspects code/config files, grades evidence into L1~L3, builds FAB. │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+The host Agent organizes user descriptions, existing resume material and explicitly supplied supporting evidence. Repository-to-resume extraction is not supported. A target role starts intake; a JD is optional. Without candidate material, ask and wait rather than generating an example.
 
----
+Draft retains incomplete information, Master preserves supplied facts, and Variant records its source Master hash for a target role. Missing values stay omitted/null; sample people, default honors and invented metrics never fill gaps. See the [artifact and acceptance contract](references/07-artifact-contract.md).
 
-## 5. End-to-End Execution Workflow
+## 5. Isolated runs and final acceptance
 
-```text
-  Know (Evidence L1~3) ──> Define (Goal) ──> Understand (JD Signals) ──> Position (Strategy) ──> Forge (HTML Canvas) ──> Review (Dual QA)
-```
+Each forge invocation writes snapshots, Master, Variant, canvas, QA and manifest to `workspace/runs/<runId>/`. Only an accepted fresh PDF is published. Failed manifests never identify an old output as delivery. Optional `--output` and `--html-output` create verified copies.
+
+Checks run in print mode across every page, then parse the final PDF's page dimensions and extracted text. PASS means current checks passed; FAIL means a check failed; UNVERIFIED means inspection could not complete; DRAFT means draft preparation only. Automated checks do not certify factual truth or every ATS.
 
-1. **[KnowMe] Evidence Mapping**: Candidate experience is analyzed and strictly categorized into L1 (Code/Config proven), L2 (Module/Dependency inferred), and L3 (Contextual inference).
-2. **[Define & Understand] Signal Extraction**: The target JD is parsed to extract must-have competencies and hiring signals.
-3. **[Position] Strategy Formulation**: Gap analysis maps real candidate evidence to target JD requirements.
-4. **[CareerForge] Template Search & Assembly**: The best HTML template is chosen using multi-criteria BM25 ranking (`search-template.py`) and instantiated to `workspace/resume.html`.
-5. **[Review & Dual QA] Self-Healing**: Layout box model height overflow and ATS textual readability tests run automatically. If an overflow is detected, CSS spacing tokens are auto-calibrated.
-6. **[PDF Export] Deterministic Output**: Playwright renders pixel-perfect `workspace/resume.pdf` with `@media print` A4 rules.
+Prepare dependencies in the installed runtime as instructed by init (`npm ci --omit=dev` with a lockfile, otherwise `npm install --omit=dev`), then run `node scripts/rendering/browser-engine.js --check-runtime`. Python 3.9+, Node.js 22.13+ and Chromium are required. READY is runtime readiness, not resume acceptance. Deliver one current PDF and editable HTML by default; `forge.py --summary` keeps stdout concise while retaining internal snapshots and diagnostics.
 
 ---
 
 ## 6. Token Self-Healing & Visual Tuning Cheat Sheet
 
-All visual parameters are concentrated in `:root` variables inside `workspace/resume.html`:
+All visual parameters are concentrated in `:root` variables inside the current run’s `resume.html`:
 
 | CSS Token | Default | Compact (1-Page Squeeze) | Relaxed (2-Page Flow) | Purpose |
 | :--- | :--- | :--- | :--- | :--- |
@@ -174,24 +157,24 @@ All visual parameters are concentrated in `:root` variables inside `workspace/re
 ## 8. CLI & Script Reference
 
 ```bash
-# 1. Search best template for target role
-knowme search "AI Agent Engineer" --style "two-column-split"
+# 1. One-shot resume engineering pipeline (user facts -> canvas -> QA -> PDF)
+knowme forge --profile-json candidate.json --role "AI Agent Engineer" --template modern --quiet
 
-# 2. Analyze a target Job Description
-python3 scripts/evidence/analyze-jd.py --jd examples/ai-engineer/jd.md
+# 2. Search best template for target role (hybrid engine)
+knowme search --role "AI Agent Engineer" --engine hybrid
 
-# 3. Instantiate Intermediate Working Canvas
-python3 scripts/template/instantiate-resume.py --template modern --keywords "Python,LLM,RAG" --output workspace/resume.html
+# 3. Prepare an incomplete draft without PDF delivery
+knowme forge --profile-json draft.json --draft
 
 # 4. Validate working canvas layout & ATS compliance
-knowme validate
+knowme validate /path/to/current-run/resume.html --json
 
 # 5. Render deterministic pixel-perfect PDF
-python3 scripts/rendering/render-pdf.py workspace/resume.html workspace/resume.pdf
+knowme render --input workspace/resume.html --output output/resume.pdf
 
 # 6. Build & view static HTML Template Gallery
 knowme gallery
-
+```
 ---
 
 ## Automated Test Suite
@@ -208,8 +191,8 @@ python3 scripts/build/run-all-tests.py
 This package is ready to be built, tested, and published to the NPM Registry:
 
 ```bash
-# 1. Automated release preparation & verification
-npm run release -- 0.0.1
+# 1. Automated release preparation & verification (e.g. patch/minor/major)
+npm run release -- <version>
 
 # 2. Publish to public NPM registry
 npm publish --access public

package/README.zh-CN.md

@@ -1,30 +1,27 @@
-# KnowMe CareerForge
+<div align="center">
+
+# 🎯 KnowMe CareerForge
 
 <p align="center">
-  <a href="README.zh-CN.md">🇨🇳 简体中文</a> | 
-  <a href="README.md">🇺🇸 English</a>
+  <strong>认识自己，明确方向，锻造属于你的职业机会。</strong><br>
+  <em>Know Yourself. Define Your Direction. Forge Your Opportunity.</em>
 </p>
 
 <p align="center">
-  <a href="https://github.com/Max-Samson/knowme-careerforge-skill/releases"><img src="https://img.shields.io/github/v/release/Max-Samson/knowme-careerforge-skill?style=for-the-badge&color=blue" alt="GitHub Release"></a>
-  <img src="https://img.shields.io/badge/岗位画像-9套标准画像-green?style=for-the-badge" alt="9 Role Profiles">
-  <img src="https://img.shields.io/badge/A4模板-4套黄金基准-purple?style=for-the-badge" alt="4 Baseline A4 Templates">
-  <img src="https://img.shields.io/badge/python-3.9+-yellow?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.9+">
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/Max-Samson/knowme-careerforge-skill?style=for-the-badge&color=green" alt="License: MIT"></a>
+  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/语言-🇨🇳_简体中文-0284C7?style=flat" alt="简体中文"></a>
+  <a href="README.md"><img src="https://img.shields.io/badge/Language-🇺🇸_English-4F46E5?style=flat" alt="English"></a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/knowme-careerforge-skill"><img src="https://img.shields.io/npm/v/knowme-careerforge-skill?style=flat-square&logo=npm&label=npm" alt="npm package"></a>
-  <a href="https://github.com/Max-Samson/knowme-careerforge-skill/stargazers"><img src="https://img.shields.io/github/stars/Max-Samson/knowme-careerforge-skill?style=flat-square&logo=github" alt="GitHub stars"></a>
-  <img src="https://img.shields.io/badge/核心架构-HTML中间修改场%20%2B%20Design%20Tokens-blue?style=flat-square" alt="HTML Intermediate Canvas">
+  <a href="https://www.npmjs.com/package/knowme-careerforge-skill"><img src="https://img.shields.io/npm/v/knowme-careerforge-skill?style=flat&logo=npm&logoColor=white&color=CB3837" alt="npm package"></a>
+  <img src="https://img.shields.io/badge/Node.js-%3E%3D22.13-339933?style=flat&logo=nodedotjs&logoColor=white" alt="Node.js">
+  <img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript">
+  <img src="https://img.shields.io/badge/Python-3.9+-3776AB?style=flat&logo=python&logoColor=white" alt="Python">
+  <img src="https://img.shields.io/badge/Playwright-A4_PDF-2EAD33?style=flat&logo=playwright&logoColor=white" alt="Playwright">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/开源协议-MIT-6B7280?style=flat" alt="License: MIT"></a>
 </p>
 
-> **认识自己，明确方向，锻造属于你的职业机会。**
->
-> *Know Yourself. Define Your Direction. Forge Your Opportunity.*
->
-> *面向主流 AI Agent 的自我认知、职业定位与岗位定制简历工程 Skill。*
-
+</div>
 ---
 
 ## 1. 什么是 KnowMe CareerForge？
@@ -49,7 +46,7 @@ knowme-careerforge-skill
 真实经历与证据   工程化定制交付
 ```
 
-- **KnowMe（自我认知与证据挖掘引擎）**：帮助候选人深入认知自我，系统梳理真实经历与可验证的代码/项目证据（L1~L3 分级），提炼真正具备竞争壁垒的优势点。
+- **KnowMe（自我认知与证据挖掘引擎）**：帮助候选人深入认知自我，系统梳理用户提供的真实经历与辅助材料，提炼真正具备竞争壁垒的优势点。
 - **CareerForge（职业定位与简历工程引擎）**：将候选人的真实优势精准对齐目标岗位（JD），以 **HTML 中间工作区（Intermediate Canvas）** 与 **Design Tokens（设计系统变量）** 为工作场进行微调排版，最终通过 Playwright 无头浏览器导出确定性、像素级的矢量 PDF。
 
 ---
@@ -102,56 +99,40 @@ knowme list
 
 ---
 
-### 方式 B：Agent 平台原生手动配置
+### 平台入口与运行资源
 
-| 平台 | 目标注入路径 | 配置方法 |
-| :--- | :--- | :--- |
-| **Cursor** | `.cursor/rules/knowme-careerforge.mdc` | `cp SKILL.md .cursor/rules/knowme-careerforge.mdc` |
-| **Claude Code** | `~/.claude/skills/knowme-careerforge/` | `cp -r knowme-careerforge-skill ~/.claude/skills/` |
-| **Codex** | `~/.codex/skills/knowme-careerforge/` | `cp -r knowme-careerforge-skill ~/.codex/skills/` |
-| **Windsurf** | `.windsurfrules` | `cat agents/windsurf/knowme-careerforge.rules >> .windsurfrules` |
-| **OpenCode** | `.opencode/skills/knowme-careerforge/` | `cp -r knowme-careerforge-skill ~/.opencode/skills/` |
+| 平台 | 入口位置 | 配置命令 |
+| --- | --- | --- |
+| Claude Code | `~/.claude/skills/knowme-careerforge/SKILL.md` | `knowme init --ai claude` |
+| Codex | `~/.codex/skills/knowme-careerforge/SKILL.md` | `knowme init --ai codex` |
+| Cursor | `.cursor/rules/knowme-careerforge.mdc` | `knowme init --ai cursor` |
+| Windsurf | `.windsurfrules` 的托管块 | `knowme init --ai windsurf` |
+| Gemini | `~/.gemini/skills/knowme-careerforge.json` | `knowme init --ai gemini` |
+| OpenCode | `.opencode/skills/knowme-careerforge/SKILL.md` | `knowme init --ai opencode` |
+
+Cursor/Windsurf 的运行资源位于项目 `.knowme/skills/knowme-careerforge/`，配置中写入准确入口；Gemini 配置指向同级运行目录。所有入口引用同一个 SKILL.md 工作流。安装完成表示文件已准备，宿主发现与实际行为需分别验证；不应只复制提示文件就认为工具可运行。移动安装目录后重新运行 init 更新路径。
 
 ---
 
-## 4. 三大运行模式 (Operational Modes)
+## 4. 用户信息与资料生命周期
 
-```text
-┌─────────────────────────────────────────────────────────────────────────────┐
-│ 模式 A：目标岗位模式 (Target-Role Mode)                                       │
-│ 用户指定职业发展方向（如“资深 AI Agent 研发工程师”）。                       │
-│ ▶ Agent 加载岗位能力树，从经历库中提取强匹配证据，派生对应 Resume Variant。  │
-├─────────────────────────────────────────────────────────────────────────────┤
-│ 模式 B：具体 JD 定制模式 (JD-Specific Mode)                                 │
-│ 用户粘贴具体的招聘需求 (Job Description)。                                   │
-│ ▶ Agent 运行 analyze-jd.py 执行差距分析，提取加分项并高亮核心招聘信号。     │
-├─────────────────────────────────────────────────────────────────────────────┤
-│ 模式 C：代码库到经历挖掘模式 (Repo-to-Resume Mode)                           │
-│ 用户提供 GitHub 仓库链接、代码目录或工程笔记。                              │
-│ ▶ Agent 审查源码与配置文件，判定 L1~L3 证据等级，重塑为高质量 FAB 论据。    │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
+当前功能依靠用户描述、已有简历和明确提供的支持材料，由宿主 Agent 组织与定制内容；不支持代码仓库分析回填。目标岗位即可开始收集资料，JD 可选；没有候选人材料时先提问并等待，不生成演示履历。
 
----
+Draft 保留不完整资料，Master 保存本次已知事实，Variant 记录来源 Master 的摘要并派生岗位表达。缺失值省略或 null，不补示例姓名、默认荣誉和任意指标。完整规则见 [资料与验收契约](references/07-artifact-contract.md)。
 
-## 5. 端到端执行工作流 (The 6-Stage Workflow)
+## 5. 独立运行与最终验收
 
-```text
-  Know (证据分级) ──> Define (明确目标) ──> Understand (洞察JD) ──> Position (制定策略) ──> Forge (HTML修改场) ──> Review (双重QA)
-```
+每次 forge 在 `workspace/runs/<runId>/` 保存输入快照、Master、Variant、画布、QA 和运行清单。通过验收后才写入本次 PDF；失败的清单不会返回旧文件作为交付。可以用 `--output` 和 `--html-output` 指定已验收副本位置。
 
-1. **[KnowMe] 证据挖掘**：分析候选人代码库与真实经历，严格划分为 L1 (代码配置直证)、L2 (模块依赖推断) 与 L3 (合理解读)。
-2. **[Define & Understand] 信号提取**：解析目标 JD，提取必备项、加分项与团队招聘风格。
-3. **[Position] 优势对齐**：差距分析匹配真实证据，规划模块优先级。
-4. **[CareerForge] 模板检索与组装**：通过多维打分引擎检索最佳模板，实例化生成 `workspace/resume.html`。
-5. **[Review & Dual QA] 闭环自愈**：无头浏览器检测 DOM 高度溢出与 ATS 文本流，自愈调校 CSS 间距 Tokens。
-6. **[PDF Export] 确定性渲染**：通过 Playwright 导出无损矢量 `workspace/resume.pdf`。
+打印模式会检查所有页面，再解析最终 PDF 的每页尺寸与文本。PASS 表示本次检查通过；FAIL 是检查失败；UNVERIFIED 是浏览器/依赖等导致无法验收；DRAFT 只表示草稿准备完成。自动检查不等同于事实核实或通用 ATS 认证。
+
+在安装目录按 init 提示准备依赖（有锁文件时 `npm ci --omit=dev`，否则 `npm install --omit=dev`），再运行 `node scripts/rendering/browser-engine.js --check-runtime`。需要 Python 3.9+、Node.js 22.13+ 与可用 Chromium。运行预检 READY 不表示简历已验收。默认只交付一个版本的 PDF 和可编辑 HTML；`forge.py --summary` 精简终端输出，内部快照与诊断仍保留。
 
 ---
 
 ## 6. CSS Design Tokens 调优与自愈速查表
 
-所有排版参数均集中在 `workspace/resume.html` 的 `:root` 变量中，可进行全局即时微调：
+所有排版参数均集中在当前运行目录的 `resume.html` 的 `:root` 变量中，可进行全局即时微调：
 
 | CSS Token 变量名 | 默认推荐值 | 紧凑模式 (单页微调) | 宽松模式 (双页饱满) | 调优核心作用 |
 | :--- | :--- | :--- | :--- | :--- |
@@ -178,24 +159,24 @@ knowme list
 ## 8. CLI 命令参考
 
 ```bash
-# 1. 智能检索最匹配的 HTML 简历模板
-knowme search "AI Agent Engineer" --style "two-column-split"
+# 1. 一键全流程装配管线（用户资料 -> HTML画布 -> 打印与PDF验收）
+knowme forge --profile-json candidate.json --role "AI Agent Engineer" --template modern --quiet
 
-# 2. 深度解析目标 JD 文本与技能词频
-python3 scripts/evidence/analyze-jd.py --jd examples/ai-engineer/jd.md
+# 2. 智能检索最匹配的 HTML 简历模板（混合评分引擎）
+knowme search --role "AI Agent Engineer" --engine hybrid
 
-# 3. 实例化 HTML 中间工作区并注入关键词高亮
-python3 scripts/template/instantiate-resume.py --template modern --keywords "Python,LLM,RAG,FastAPI" --output workspace/resume.html
+# 3. 从不完整资料生成草稿，不声明 PDF 已验收
+knowme forge --profile-json draft.json --draft
 
-# 4. 运行布局结构、Design Tokens 与文字密度验证
-knowme validate
+# 4. 运行布局结构、Design Tokens 与 ATS 双重质检
+knowme validate /path/to/current-run/resume.html --json
 
 # 5. 确定性导出无损矢量 A4 PDF
-python3 scripts/rendering/render-pdf.py workspace/resume.html workspace/resume.pdf
+knowme render --input workspace/resume.html --output output/resume.pdf
 
 # 6. 编译生成可视化模板画廊
 knowme gallery
-
+```
 ---
 
 ## 自动化测试与持续集成
@@ -212,8 +193,8 @@ python3 scripts/build/run-all-tests.py
 本项目已配置为标准的 NPM Package，支持一键编译、测试与发布：
 
 ```bash
-# 1. 执行发布前自动化测试与打包预检
-npm run release -- 0.0.1
+# 1. 执行发布前自动化版本对齐、测试与打包预检
+npm run release -- <version>
 
 # 2. 发布至公共 NPM 注册表
 npm publish --access public

package/SKILL.md

@@ -1,168 +1,71 @@
 ---
 name: knowme-careerforge
-displayName: KnowMe CareerForge
-description: An agent-native skill for self-discovery, career positioning, and tailored resume engineering. Analyzes candidate evidence, maps strengths to target JDs, crafts tailored resumes inside an HTML Intermediate Canvas, self-heals layout/ATS, and exports pixel-perfect PDFs.
-version: 0.0.4
+description: Create or refine a tailored resume from user descriptions, existing resume material and an optional target JD. Use when the user wants to draft a resume, tailor it to a role, edit an existing resume canvas, or export a verified resume PDF.
+license: MIT
+compatibility: Requires Python 3.9+, Node.js 22.13+, the npm dependencies declared by this project, and Chromium for print/PDF checks. Explicit local font presets require the named font.
+metadata:
+  version: 0.0.7
 ---
 
-# KnowMe CareerForge — Agent Reasoning Contract & Execution Specification
+# KnowMe CareerForge
 
-> **"Know Yourself. Define Your Direction. Forge Your Opportunity."**
-> 
-> *Core Mission: The goal is not to make the candidate look better than they are. The goal is to make their real strengths visible to the right opportunity.*
+Create a readable resume from the user's descriptions, existing resume and explicitly supplied material. The host Agent selects and rewrites facts; tools bind templates and check printing. Repository mining and automatic repo-to-resume backfill are not supported. Development tasks use AGENT.md; making a resume does not require reading development docs or tool source code.
 
----
+## 1. Start from the conversation
 
-## 1. Operating Rules & Core Constraints
-
-When this skill is activated, you are NOT a generic text generator. You act as a coordinated council of 6 specialized personas:
-1. **Career Researcher**: Discovers user facts, codebase architectures, and verifiable achievements.
-2. **Career Strategist**: Analyzes target JDs and formulates career positioning strategy.
-3. **Evidence Analyst**: Strictly enforces L1~L3 evidence classification and eliminates hallucinations.
-4. **Resume Writer**: Crafts high-impact FAB (Feature-Advantage-Benefit) bullet points.
-5. **Resume Designer**: Calibrates CSS Design Tokens within the HTML canvas.
-6. **Resume Reviewer**: Executes automated layout, overflow, and ATS Dual-QA tests.
-
-### Non-Negotiable Invariants:
-- **Evidence-First (Anti-Hallucination)**: Every single claim on the resume MUST be grounded in candidate facts. Never invent unverified revenue numbers, false company tenures, or fake degrees.
-- **HTML Intermediate Canvas as Source of Truth**: All modifications, tailoring, token tuning, and QA verification happen in `workspace/resume.html`. Never output raw unformatted text or bypass the HTML canvas.
-- **Deterministic Rendering**: The final PDF (`workspace/resume.pdf`) is exported via multi-strategy auto-discovery renderers only after passing Dual QA with 100% compliance.
-- **Quiet Execution Protocol (Strict Chat Invariant)**:
-  - **DO NOT** print hundreds of lines of raw HTML, full CSS stylesheets, or intermediate scratchpad python scripts to the user chat.
-  - Execute tool scripts silently in the background.
-  - Final response contract: One-line Value Proposition + Top 3 Grounded Evidence Highlights + Direct Output File Paths (`workspace/resume.pdf` and `workspace/resume.html`).
-
-### Reference Manuals (L3 Domain Rules):
-- **Stage 1 (Know Me)**: `references/01-evidence-mining.md`
-- **Stage 2 (Define Goal)**: `references/02-career-goal.md`
-- **Stage 3 (Understand JD)**: `references/03-jd-analysis.md`
-- **Stage 4 (Position & Select)**: `references/04-template-selection.md`
-- **Stage 5 (Forge Canvas)**: `references/05-html-canvas-tokens.md`
-- **Stage 6 (Review & QA)**: `references/06-qa-and-rendering.md`
-
-*See `AGENT.md` for strict editorial standards and `ARCHITECTURE.md` for system architecture.*
+Reuse information already given. A target role is sufficient to start the conversation, not to invent a candidate. A JD is optional. Decide whether candidate material exists before reading references, inspecting templates or checking runtime. With no material, a sufficient first response is: “请发已有简历，或告诉我姓名、最近一段工作经历（公司、时间、做了什么、用过哪些技术）；已有的信息不用重复。”
 
----
+- **Only a role, no candidate material:** ask for an existing resume or a short description of recent work, dates and technologies. Then wait. Do not build sample resumes, inspect every reference, or create test profiles while awaiting an answer. If a host task list is used, mark intake as awaiting input using the host’s supported state; drafting and rendering depend on it and remain pending. A TODO reminder does not unlock them. Do not create a task list just to run this simple workflow.
+- **Usable facts supplied:** organize them directly. Missing optional contact, school or date fields do not require a Draft detour. Ask only consequential follow-ups; proceed with known facts when the user wants a result. If experience is known but the name is missing, ask just for the name needed for PDF delivery, or prepare an unnamed Draft if requested.
+- **Draft requested or delivery input insufficient:** use `--draft` for an explicitly requested partial canvas. Label it DRAFT; do not promise a verified PDF.
+- **Existing canvas edited:** preserve those edits and validate/render that canvas to a new revision path; do not overwrite it from an older profile.
 
-## 2. Input & Content Intelligence Layer (Repo-to-Resume Modes)
-
-Identify the user's input scenario and select the corresponding mode:
-
-```text
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│ Input Modes & Evidence Mining Pipeline                                          │
-├─────────────────────────────────────────────────────────────────────────────────┤
-│ Mode A: Codebase / Repo-to-Resume Mode                                          │
-│   User provides a project directory or Git repo (or runs in current workspace)  │
-│   ➔ Run `python3 scripts/evidence/extract-evidence.py --repo .`                 │
-│   ➔ Extract tech stacks, frameworks, Docker/CI-CD, Git commits, and author info │
-├─────────────────────────────────────────────────────────────────────────────────┤
-│ Mode B: JD-Specific Mode                                                        │
-│   User provides a target Job Description (text or file)                         │
-│   ➔ Run `python3 scripts/evidence/analyze-jd.py --jd "path/to/jd.txt"`          │
-│   ➔ Extract Must-Have skills, Nice-to-Haves, hiring signals, and priority words │
-├─────────────────────────────────────────────────────────────────────────────────┤
-│ Mode C: Target-Role Mode                                                        │
-│   User specifies a direction (e.g. "AI Agent Engineer", "Senior Architect")     │
-│   ➔ Match against `src/knowledge/roles/*.json` knowledge profiles               │
-└─────────────────────────────────────────────────────────────────────────────────┘
-```
+Preserve employers, dates, qualifications, metrics and ownership exactly in meaning. “Participated” cannot become “led”; a target Java role does not prove Java experience. Role knowledge and JD keywords are prompts for questions, never evidence of skills. Do not add common tools, proficiency, implementation mechanisms, projects or outcomes merely because they sound plausible. Gallery `sample-profile.json` is fictional and never candidate input. If a user explicitly requests a fictional example, label it separately and keep it out of their fact record.
 
-### Collecting Candidate Information:
-1. **Basic Info**: Name, Contact (Email, Phone, Location, GitHub). If missing from user prompt, auto-detect from Git / `package.json` / `evidence-master.json` or prompt briefly.
-2. **L1~L3 Evidence Classification**:
-   - **Level 1 (Direct Code/Config Evidence)**: Verified by code files, configuration files (`package.json`, `Dockerfile`, `go.mod`, `Cargo.toml`), API contracts, or Git commits.
-   - **Level 2 (Structural/Dependency Evidence)**: Deduced from directory structure, tech stack dependencies, and architectural patterns.
-   - **Level 3 (Contextual Inference)**: Reasonable contextual deduction (MUST use conservative phrasing, e.g., *"Participated in the design and implementation of..."*).
-   - **Unsupported**: Facts not present in candidate records. **NEVER WRITE INTO RESUME**.
+## 2. Compose once, choose a layout
 
----
+Before composing, read [the source-to-claim rules](references/01-evidence-mining.md) once and check the rewritten claims against the original user material. Comparing a generated profile with its own PDF does not check factual fidelity. Keep a single editable profile of supplied facts. Read [the artifact contract](references/07-artifact-contract.md) for its short input example and lifecycle. The pipeline creates Master/Variant snapshots; the user need not write JSON or receive every snapshot. Master means this run's known facts, not that every optional field is complete.
 
-## 3. The 6-Stage Deterministic Workflow
-
-You MUST execute the following 6 stages in exact sequence:
-
-```text
-┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
-│ 1. KNOW ME   │ ──> │ 2. DEFINE    │ ──> │ 3. UNDERSTAND    │
-│ Evidence L1~3│     │ Career Goal  │     │ JD & Signals     │
-└──────────────┘     └──────────────┘     └──────────────────┘
-                                                    │
-                                                    ▼
-┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
-│ 6. REVIEW/QA │ <── │ 5. CAREER    │ <── │ 4. POSITION      │
-│ Dual QA & PDF│     │ FORGE HTML   │     │ Strategy & Map   │
-└──────────────┘     └──────────────┘     └──────────────────┘
-```
+Write short, concrete bullets. A useful default is a brief optional summary, compact skill groups, and evidence in work/project entries. Do not repeat the same achievement in summary, work and an invented project. A project section is optional: add one only when supplied project detail adds something distinct. Metrics and technical mechanisms appear only when supplied; duties without metrics remain valid. Follow the user's requested level of detail.
 
-### Option 1: Fast One-Shot Unified Execution (Recommended)
-You can run the full end-to-end pipeline in a single command:
-```bash
-python3 scripts/pipeline/forge.py --repo . --role "<Target Role>" --jd "<path/to/jd.txt>" --template "<minimal|modern|executive|classic>" --quiet
-```
-Or via CLI:
-```bash
-knowme forge --repo . --role "<Target Role>" --template modern --quiet
-```
+Read [template guidance](references/04-template-selection.md) when choosing a template. Honor an explicit choice; otherwise choose for actual content length and hierarchy, or omit `--template` for ranked selection. Do not hardcode minimal because the role is backend. State the actual `templateUsed` in delivery. Each template has one structural source, `canvas.html`; previews bind fictional data through the same renderer.
 
-### Option 2: Step-by-Step Granular Execution
+## 3. Prepare runtime, generate
 
-#### Step 1: Extract Evidence (Know Me)
-```bash
-python3 scripts/evidence/extract-evidence.py --repo . --output workspace/evidence-master.json --quiet
-```
+Use the absolute SKILL.md path already returned by the host to resolve `<skill-root>`. The model name does not determine the installation directory: a Gemini model may be running through a host that resolves `.claude/skills`. If unavailable, inspect the host's configured skill location; do not recursively search the home directory. Candidate files belong in the user's workspace, never the installation directory.
 
-#### Step 2 & 3: JD & Target Analysis (Understand)
-```bash
-python3 scripts/evidence/analyze-jd.py --jd "path/to/jd.txt"
-```
+After there is sufficient candidate material, and before the first PDF build, run:
 
-#### Step 4: Search & Select Template (Position)
 ```bash
-python3 scripts/template/search-template.py "<Target Role>" --style "<minimal|modern|executive|classic>" --target-pages 1
+node <skill-root>/scripts/rendering/browser-engine.js --check-runtime
 ```
 
-#### Step 5: Instantiate Intermediate HTML Working Canvas (CareerForge)
-```bash
-python3 scripts/template/instantiate-resume.py --template <template_id> --profile workspace/evidence-master.json --keywords "Python,LLM,RAG,FastAPI" --output workspace/resume.html
-```
+READY only checks runtime availability, not resume quality. If unavailable, use its diagnostics and the installed package.json to prepare dependencies once under the host's permission rules. With a lockfile use `npm ci --omit=dev`; otherwise use `npm install --omit=dev`, in `<skill-root>`. Do not guess and install packages one error at a time. If package.json or required bundled scripts are absent, the installation is incomplete: repair it from the project package rather than synthesizing a manifest or installing guessed dependencies. Chromium is also required. If setup is blocked, report UNVERIFIED and offer a requested Draft; do not repeatedly run the full pipeline unchanged.
+
+For a new resume, keep internal files under `workspace/` and publish only the readable deliverables under `resume/` (or the user's chosen locations):
 
-#### Step 6: Review, Dual QA & PDF Export
 ```bash
-# 1. Run Layout QA (DOM height & overflow validation)
-python3 scripts/validation/validate-resume.py --html workspace/resume.html --expected-pages 1
+python3 <skill-root>/scripts/pipeline/forge.py --profile-json workspace/profile.json --workspace workspace/runs --role "<target role>" --output resume/resume.pdf --html-output resume/resume.html --summary
 ```
-# 2. If overflow occurs, tune CSS tokens in workspace/resume.html:
-#    - Reduce --resume-space-section (e.g., 11pt -> 9.5pt)
-#    - Reduce --resume-font-size-body (e.g., 9.2pt -> 9.0pt)
+
+Add `--template <chosen-id>` for an explicit layout. Drafts use `--draft` without PDF/copy flags; return the exact HTML path reported. Each invocation isolates its artifacts. A successful preflight need not be repeated on contact or wording updates unless the environment changes. Read the returned status and paths; never guess `workspace/resume.pdf` or treat a previous copy as this run's success. Full diagnostics remain in the returned manifest; open them only when needed. Fix a reported cause before retrying.
+
+For existing edited HTML:
 
 ```bash
-# 3. Deterministic PDF Export via Multi-Strategy Auto-Discovery:
-python3 scripts/rendering/render-pdf.py workspace/resume.html workspace/resume.pdf --quiet
+python3 <skill-root>/scripts/rendering/render-pdf.py <edited-resume.html> <new-resume.pdf> --expected-pages 1 --quiet
 ```
 
----
+## 4. Inspect and deliver
 
-## 4. Final Response Delivery Contract (Strict Template)
+Check rewritten content against the user's input before rendering. After tool acceptance, inspect the final PDF visually on every page: hierarchy, small type, excessive whitespace, dense skills, duplication and education/date alignment. An HTML screenshot or PDF file size does not prove final PDF appearance. If visual tools are unavailable, disclose that limitation. After an accepted result and the completed visual/content review, stop. Do not perform another identical export, measure file size as extra QA, or create another named copy. Read [canvas tuning](references/05-html-canvas-tokens.md) only for layout edits and [QA diagnostics](references/06-qa-and-rendering.md) for failures.
 
-Once `workspace/resume.pdf` is generated, deliver your final response strictly in this clear, professional structure:
+PASS requires this PDF's page, text and layout checks. It does not certify truth, persuasive design or universal ATS compatibility. Do not shrink sparse resumes, fabricate content to fill the page, silently remove facts, or relax checks to pass. Preserve failures for diagnosis; do not delete run history as cosmetic cleanup. Font extraction failures require inspecting diagnostics and an available font choice, not altering candidate text.
 
-```markdown
-### 🎯 Career Positioning & Value Proposition
-> **[Candidate Name] · [Target Role Title]**
-> *[15~25 words Core Value Proposition highlighting key strengths]*
+Default delivery: link PDF and editable HTML, name the template, and briefly note useful remaining gaps. Do not repeat the entire resume, dump QA tables, or link input/Master/Variant/manifest unless requested or needed to explain failure. FAIL/UNVERIFIED must identify the concrete blocker; DRAFT must remain clearly labeled.
 
----
+Use one concise delivery shape across hosts, adapting only language and filenames:
 
-### 🛡️ Top Grounded Evidence Highlights (L1/L2)
-1. **[Key Domain / Architecture]**: [Action Verb + Grounded Achievement + Metrics] *(Evidence: [Source])*
-2. **[Core Tech Stack]**: [Engineered feature with exact frameworks] *(Evidence: [Source])*
-3. **[Delivery & Impact]**: [System stability / CI-CD / Performance metric] *(Evidence: [Source])*
+> 已生成简历： [PDF](<current PDF path>) · [可编辑 HTML](<current HTML path>)。模板：<templateUsed>。<One useful gap or actual inspection limitation, if any.>
 
----
-
-### 📄 Final Verified Deliverables
-- **PDF Resume (Deterministic A4)**: `workspace/resume.pdf` (Passed 100% Dual QA)
-- **HTML Working Canvas**: `workspace/resume.html` (Design Tokens Calibrated)
-- **Master Profile JSON**: `workspace/evidence-master.json` (Traceable Evidence底座)
-```
+Return one current version by default, not several template alternatives or separate analysis reports. For an update, patch only the requested fields in the current working profile/canvas, retain the selected template and public filenames unless the user asks to change them, and publish the newly accepted revision; keep previous runs internal. When blocked, give the blocker and the single next action instead of a success-shaped delivery. Keep progress updates about observable work, not a running commentary of every file read or schema decision.

package/agents/claude/knowme-careerforge.md

@@ -1,18 +1,3 @@
----
-description: An agent-native skill for self-discovery, career positioning, and tailored resume engineering.
-globs: ["workspace/*", "src/**/*", "scripts/**/*", "references/*"]
----
+# KnowMe CareerForge
 
-# KnowMe CareerForge — Claude Code Skill
-
-> *"Know Yourself. Define Your Direction. Forge Your Opportunity."*
-
-When activated, follow the 6-Stage Deterministic Workflow and Quiet Execution Protocol (see `AGENT.md` and `ARCHITECTURE.md`):
-
-1. **Evidence Mining (repo-to-resume)**: Extract codebase facts via `python3 scripts/evidence/extract-evidence.py --repo .` or run one-shot `python3 scripts/pipeline/forge.py` (see `references/01-evidence-mining.md`).
-2. **Define Goal & Archetype**: Establish target seniority tier and capability matrix (see `references/02-career-goal.md`).
-3. **Understand Target**: Analyze target JD via `python3 scripts/evidence/analyze-jd.py` (see `references/03-jd-analysis.md`).
-4. **Template Search**: Match template via `python3 scripts/template/search-template.py` (see `references/04-template-selection.md`).
-5. **Intermediate Canvas**: Instantiate `workspace/resume.html` via `python3 scripts/template/instantiate-resume.py` and calibrate CSS design tokens (see `references/05-html-canvas-tokens.md`).
-6. **Review & Dual QA**: Run `python3 scripts/validation/validate-resume.py` and export `workspace/resume.pdf` via `python3 scripts/rendering/render-pdf.py` (see `references/06-qa-and-rendering.md`).
-7. **Quiet Delivery**: Execute silently in background; deliver concise executive summary and final file path (`workspace/resume.pdf`).
+Read SKILL.md at the installed skill root and follow it as the single runtime workflow. Resolve its scripts and references from that directory, not the candidate workspace. Load supporting references only when the current step needs them. Do not load AGENT.md or architecture documents to make a resume.