knowme-careerforge-skill 0.0.2 → 0.0.6

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?
@@ -110,44 +109,25 @@ knowme list
 
 ---
 
-## 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 is sufficient; a JD is optional.
 
----
+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.
+Requires Python 3.9+, Node.js 22.13+, npm runtime dependencies and Chromium. Run `npm install`; use `npx playwright install chromium` if no system Chromium is available.
 
 ---
 
 ## 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 +154,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 +188,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？
@@ -114,44 +111,25 @@ knowme list
 
 ---
 
-## 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 认证。
+
+需要 Python 3.9+、Node.js 22.13+ 和 npm 运行依赖。运行 `npm install`；没有系统 Chromium 时使用 `npx playwright install chromium`。
 
 ---
 
 ## 6. CSS Design Tokens 调优与自愈速查表
 
-所有排版参数均集中在 `workspace/resume.html` 的 `:root` 变量中，可进行全局即时微调：
+所有排版参数均集中在当前运行目录的 `resume.html` 的 `:root` 变量中，可进行全局即时微调：
 
 | CSS Token 变量名 | 默认推荐值 | 紧凑模式 (单页微调) | 宽松模式 (双页饱满) | 调优核心作用 |
 | :--- | :--- | :--- | :--- | :--- |
@@ -178,24 +156,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 +190,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,158 +1,49 @@
 ---
 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.2
+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.6
 ---
 
-# 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.*
+Use the user's descriptions, existing resume and supplied supporting material. The host Agent understands, selects and rewrites content. Repository mining and automatic repo-to-resume backfill are not supported input paths. Do not scan the current project to infer candidate facts.
 
----
-
-## 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`).
-
----
-
-## 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               │
-└─────────────────────────────────────────────────────────────────────────────────┘
-```
-
-### 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**.
-
----
+Reuse information already given and ask only useful follow-up questions. A target role is enough; a JD is optional. Make progress with sparse information when the user wants a draft. Do not impose a complete questionnaire or invent facts to fill empty fields. Preserve explicit user choices of language, template, page count and requested edit.
 
-## 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   │
-└──────────────┘     └──────────────┘     └──────────────────┘
-```
+Keep employers, dates, degrees, responsibilities, metrics and ownership faithful to the input. User statements are supplied facts; do not downgrade “led” to “participated” merely because the source is chat. Do not claim independent verification without doing it. Keep gaps and uncertainties outside the resume rather than writing invented placeholder achievements.
 
-### 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
-```
+For help developing or reviewing this Skill repository, use its development documentation; do not start a candidate intake or resume-generation workflow merely because the repository contains resume tools.
 
-### Option 2: Step-by-Step Granular Execution
+## Preserve the artifact lifecycle
 
-#### Step 1: Extract Evidence (Know Me)
-```bash
-python3 scripts/evidence/extract-evidence.py --repo . --output workspace/evidence-master.json --quiet
-```
+Read [the shared artifact and error contract](references/07-artifact-contract.md) before running the pipeline. Draft, Master and Variant describe different artifacts. They do not mean the same thing as PASS, FAIL or UNVERIFIED.
 
-#### Step 2 & 3: JD & Target Analysis (Understand)
-```bash
-python3 scripts/evidence/analyze-jd.py --jd "path/to/jd.txt"
-```
+- Prepare a Draft when information is incomplete. Unknown optional values are omitted or null, never sample candidate text.
+- Keep the user's facts in a Master; derive a Variant for a target role without overwriting the original facts. User-provided plain profile JSON remains supported. Users do not need to author JSON themselves.
+- Use an isolated run directory for each pipeline invocation. Read the returned manifest and exact output paths; never infer success from an existing workspace/resume.pdf.
+- When editing an existing canvas, preserve those edits and validate/render that canvas. Do not regenerate from an older profile and overwrite later content edits. Write a new output path for a new revision.
 
-#### Step 4: Search & Select Template (Position)
-```bash
-python3 scripts/template/search-template.py "<Target Role>" --style "<minimal|modern|executive|classic>" --target-pages 1
-```
+Resolve scripts and resources relative to this SKILL.md, regardless of current directory. Write candidate artifacts in the user's workspace. Tools require Python 3.9+, Node.js 22.13+ and installed npm runtime dependencies. Printing requires system Chromium or Playwright Chromium. Missing runtime means UNVERIFIED, not PASS.
 
-#### 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
-```
+# Assemble and verify Agent-prepared user facts in an isolated run directory.
+python3 <skill-root>/scripts/pipeline/forge.py --profile-json <master.json> --role "<target role>" --template minimal --quiet
 
-#### 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
-```
-# 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)
+# Incomplete input: return a draft, without a verified PDF claim.
+python3 <skill-root>/scripts/pipeline/forge.py --profile-json <draft.json> --draft --quiet
 
-```bash
-# 3. Deterministic PDF Export via Multi-Strategy Auto-Discovery:
-python3 scripts/rendering/render-pdf.py workspace/resume.html workspace/resume.pdf --quiet
+# Validate an existing edited canvas; export rechecks the final PDF.
+python3 <skill-root>/scripts/validation/validate-resume.py <resume.html> --expected-pages 1 --json
+python3 <skill-root>/scripts/rendering/render-pdf.py <resume.html> <new-resume.pdf> --expected-pages 1 --quiet
 ```
 
----
-
-## 4. Final Response Delivery Contract (Strict Template)
-
-Once `workspace/resume.pdf` is generated, deliver your final response strictly in this clear, professional structure:
-
-```markdown
-### 🎯 Career Positioning & Value Proposition
-> **[Candidate Name] · [Target Role Title]**
-> *[15~25 words Core Value Proposition highlighting key strengths]*
+## Assemble and inspect
 
----
-
-### 🛡️ 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])*
+Use `canvas.html` as the sole maintained template structure. Gallery previews bind explicit `sample-profile.json` through the same instantiator; never use gallery samples as candidate facts. All education, work and project entries are independent. Treat an injection error as failure; never deliver the untouched sample template. For template choice and token tuning, read [template guidance](references/04-template-selection.md) and [canvas guidance](references/05-html-canvas-tokens.md).
 
----
+Check facts against the input, inspect print layout and run [QA and rendering](references/06-qa-and-rendering.md). Automatic tuning may reduce spacing and font sizes within limits, but cannot replace content review. When fitting fails, adjust expression, select another layout or use the user's allowed page count. Do not silently delete facts. If PDF extraction reports font mapping differences, inspect missingCodepoints and extractedRadicals; an explicit available font preset such as `--font-preset arial-unicode` can be used in a new run. Never relax text checks or rewrite candidate facts to bypass a font failure.
 
-### 📄 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底座)
-```
+Report the actual result concisely with the produced file paths. PASS requires the current PDF's page, text and layout checks. FAIL or UNVERIFIED must explain the concrete error; DRAFT must be labeled as a draft. Basic PDF text checks are not universal ATS certification.

package/agents/claude/knowme-careerforge.md

@@ -1,17 +1,3 @@
----
-description: An agent-native skill for self-discovery, career positioning, and tailored resume engineering.
-globs: ["workspace/*", "src/**/*", "scripts/**/*"]
----
+# KnowMe CareerForge
 
-# KnowMe CareerForge — Claude Code Skill
-
-Know Yourself. Define Your Direction. Forge Your Opportunity.
-
-When activated, follow the Evidence-First & Quiet Execution Protocol (see `scripts/Agent.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`.
-2. **Understand Target**: Analyze target JD via `python3 scripts/evidence/analyze-jd.py`.
-3. **Template Search**: Match template (`python3 scripts/template/search-template.py`).
-4. **Intermediate Canvas**: Instantiate `workspace/resume.html` via `python3 scripts/template/instantiate-resume.py` and calibrate CSS design tokens.
-5. **Review & Dual QA**: Run `python3 scripts/validation/validate-resume.py`.
-6. **PDF Delivery**: Export `workspace/resume.pdf` via `python3 scripts/rendering/render-pdf.py`.
-7. **Quiet Delivery**: Execute silently in background; deliver concise executive summary and final file path (`workspace/resume.pdf`).
+Read the installed SKILL.md and references/07-artifact-contract.md. Use user-supplied facts, preserve Draft/Master/Variant separation and write each pipeline run into its own directory. Repository mining is not supported. Only the current PASS manifest identifies verified PDF delivery; never substitute an old workspace file after failure.

package/agents/codex/knowme-careerforge.yaml

@@ -1,12 +1,10 @@
 name: knowme-careerforge
 description: An agent-native skill for self-discovery, career positioning, and tailored resume engineering.
-version: 0.0.2
+version: 0.0.6
 entrypoint: SKILL.md
 tools:
   - name: forge
     command: python3 scripts/pipeline/forge.py
-  - name: extract-evidence
-    command: python3 scripts/evidence/extract-evidence.py
   - name: search-template
     command: python3 scripts/template/search-template.py
   - name: analyze-jd
@@ -18,7 +16,7 @@ tools:
   - name: render-pdf
     command: python3 scripts/rendering/render-pdf.py
 rules:
-  - "Execute tools silently in background (DO NOT print raw HTML, full CSS, or scripts in chat)."
-  - "Use workspace/resume.html as the sole Intermediate Working Canvas."
-  - "Deliver final concise summary and path to workspace/resume.pdf."
-  - "Reference scripts/Agent.md for complete toolchain conventions."
+  - "Execute tools silently in background with --quiet (DO NOT print raw HTML, full CSS, or scripts in chat)."
+  - "Use the current isolated run canvas and preserve Master/Variant lineage."
+  - "Deliver only the current PASS manifest outputs; report DRAFT, FAIL and UNVERIFIED accurately."
+  - "Reference AGENT.md, ARCHITECTURE.md, and references/01~06 for complete specifications."

package/agents/cursor/knowme-careerforge.mdc

@@ -1,13 +1,8 @@
 ---
-description: KnowMe CareerForge — Agent-native career positioning and resume engineering
-globs: ["workspace/*", "src/**/*", "scripts/**/*"]
+description: Resume drafting and verified delivery from user-provided facts
+alwaysApply: false
 ---
 
-# KnowMe CareerForge MDC Rules
+# KnowMe CareerForge
 
-1. **Evidence-First**: Never hallucinate ungrounded claims (strictly L1~L3 evidence).
-2. **Repo-to-Resume**: Extract codebase facts using `python3 scripts/evidence/extract-evidence.py --repo .` or run one-shot `python3 scripts/pipeline/forge.py`.
-3. **HTML Canvas**: Edit exclusively in `workspace/resume.html` Intermediate Working Canvas (`scripts/template/instantiate-resume.py`).
-4. **Quiet Protocol**: Execute scripts silently in background; do not output raw HTML, CSS, or scripts into the chat.
-5. **Deterministic PDF**: Validate via `python3 scripts/validation/validate-resume.py` and export via `python3 scripts/rendering/render-pdf.py`.
-6. **Architecture Guide**: Refer to `scripts/Agent.md` for toolchain domain specifications.
+Read the installed SKILL.md and references/07-artifact-contract.md. Use user-supplied facts, preserve Draft/Master/Variant separation and write each pipeline run into its own directory. Repository mining is not supported. Only the current PASS manifest identifies verified PDF delivery; never substitute an old workspace file after failure.

package/agents/opencode/skill.yaml

@@ -1,7 +1,7 @@
 name: knowme-careerforge
 displayName: KnowMe CareerForge
 description: An agent-native skill for self-discovery, career positioning, and tailored resume engineering.
-version: 0.0.2
+version: 0.0.6
 schema: 1.0
 entrypoint: SKILL.md
 tags:

package/agents/windsurf/knowme-careerforge.rules

@@ -1,13 +1,3 @@
-# KnowMe CareerForge — Windsurf Rules
-# Trigger: Career discovery, resume tailoring, JD analysis, repo-to-resume
+# KnowMe CareerForge
 
-When user requests resume tailoring, project analysis, or career positioning:
-1. Extract candidate facts using `python3 scripts/evidence/extract-evidence.py --repo .` or execute one-shot `python3 scripts/pipeline/forge.py`.
-2. Tag all experience items with Evidence Level (L1~L3 only, strictly anti-hallucination).
-3. Analyze target JD requirements using `python3 scripts/evidence/analyze-jd.py`.
-4. Recommend best template using `python3 scripts/template/search-template.py`.
-5. Instantiate `workspace/resume.html` using `python3 scripts/template/instantiate-resume.py` and calibrate CSS design tokens.
-6. Validate DOM fit and ATS compatibility using `python3 scripts/validation/validate-resume.py`.
-7. Export final deterministic PDF using `python3 scripts/rendering/render-pdf.py`.
-8. Execute silently in background; deliver concise executive summary and final file path (`workspace/resume.pdf`).
-9. Reference `scripts/Agent.md` for toolchain domain specifications.
+Read the installed SKILL.md and references/07-artifact-contract.md. Use user-supplied facts, preserve Draft/Master/Variant separation and write each pipeline run into its own directory. Repository mining is not supported. Only the current PASS manifest identifies verified PDF delivery; never substitute an old workspace file after failure.

package/dist/cli/src/commands/init.js

@@ -93,7 +93,10 @@ function runInit(options) {
                     fs.mkdirSync(claudeDir, { recursive: true });
                     copyDirRecursive(path.join(rootDir, 'scripts'), path.join(claudeDir, 'scripts'));
                     copyDirRecursive(path.join(rootDir, 'src'), path.join(claudeDir, 'src'));
+                    copyDirRecursive(path.join(rootDir, 'references'), path.join(claudeDir, 'references'));
                     fs.copyFileSync(path.join(rootDir, 'SKILL.md'), path.join(claudeDir, 'SKILL.md'));
+                    fs.copyFileSync(path.join(rootDir, 'AGENT.md'), path.join(claudeDir, 'AGENT.md'));
+                    fs.copyFileSync(path.join(rootDir, 'ARCHITECTURE.md'), path.join(claudeDir, 'ARCHITECTURE.md'));
                     fs.copyFileSync(path.join(rootDir, 'skill.json'), path.join(claudeDir, 'skill.json'));
                     console.log(`[✓] Claude Code Skill fully bundled -> ${claudeDir}`);
                     break;
@@ -103,7 +106,10 @@ function runInit(options) {
                     fs.mkdirSync(codexDir, { recursive: true });
                     copyDirRecursive(path.join(rootDir, 'scripts'), path.join(codexDir, 'scripts'));
                     copyDirRecursive(path.join(rootDir, 'src'), path.join(codexDir, 'src'));
+                    copyDirRecursive(path.join(rootDir, 'references'), path.join(codexDir, 'references'));
                     fs.copyFileSync(path.join(rootDir, 'SKILL.md'), path.join(codexDir, 'SKILL.md'));
+                    fs.copyFileSync(path.join(rootDir, 'AGENT.md'), path.join(codexDir, 'AGENT.md'));
+                    fs.copyFileSync(path.join(rootDir, 'ARCHITECTURE.md'), path.join(codexDir, 'ARCHITECTURE.md'));
                     fs.copyFileSync(path.join(rootDir, 'skill.json'), path.join(codexDir, 'skill.json'));
                     if (fs.existsSync(path.join(rootDir, 'agents', 'codex', 'knowme-careerforge.yaml'))) {
                         fs.copyFileSync(path.join(rootDir, 'agents', 'codex', 'knowme-careerforge.yaml'), path.join(codexDir, 'skill.yaml'));
@@ -139,7 +145,10 @@ function runInit(options) {
                     fs.mkdirSync(opencodeDir, { recursive: true });
                     copyDirRecursive(path.join(rootDir, 'scripts'), path.join(opencodeDir, 'scripts'));
                     copyDirRecursive(path.join(rootDir, 'src'), path.join(opencodeDir, 'src'));
+                    copyDirRecursive(path.join(rootDir, 'references'), path.join(opencodeDir, 'references'));
                     fs.copyFileSync(path.join(rootDir, 'SKILL.md'), path.join(opencodeDir, 'SKILL.md'));
+                    fs.copyFileSync(path.join(rootDir, 'AGENT.md'), path.join(opencodeDir, 'AGENT.md'));
+                    fs.copyFileSync(path.join(rootDir, 'ARCHITECTURE.md'), path.join(opencodeDir, 'ARCHITECTURE.md'));
                     fs.copyFileSync(path.join(rootDir, 'skill.json'), path.join(opencodeDir, 'skill.json'));
                     console.log(`[✓] OpenCode Skill fully bundled -> ${opencodeDir}`);
                     break;