knowme-careerforge-skill 0.0.6 → 0.0.7

package/ARCHITECTURE.md

@@ -213,4 +213,8 @@ Tests use temporary directories and cover sparse/invalid facts, multiple educati
 
 Discovery metadata, activated instructions and conditional resources have separate loading costs. Keep development governance in `AGENT.md` and detailed runtime rules in `references/`. Package verification must cover dependencies and execution from outside the source checkout, separately from source-tree tests and Agent behavior evaluation.
 
-The current initializer has unresolved packaging and partial-success gaps; native-platform compatibility is not established by copying a prompt or passing local PDF tests. See [Agent Skills design review](docs/dev/AGENT_SKILLS_DESIGN_REVIEW.md) for evidence, target boundaries and acceptance criteria, and `AGENT.md` section 7 for maintenance rules.
+The initializer now copies runtime package metadata for full bundles, reports dependency preparation separately, and returns a nonzero exit on platform failures. Source installations retain package-lock.json when available; npm archives omit it and require npm install rather than npm ci. Cursor/Windsurf adapters now point to a project-local `.knowme/skills/knowme-careerforge` bundle; Gemini configuration points to its sibling runtime bundle by absolute entrypoint. Windsurf replaces its managed block on subsequent installs. Native-platform compatibility is not established by copying a prompt or passing local PDF tests. See [Agent Skills design review](docs/dev/AGENT_SKILLS_DESIGN_REVIEW.md) for evidence, target boundaries and acceptance criteria, and `AGENT.md` section 7 for maintenance rules.
+
+Runtime readiness is exposed by `browser-engine.js --check-runtime` (READY/UNVERIFIED); it does not certify a resume. `forge.py --summary` provides compact stdout with the canonical manifest path while retaining full on-disk diagnostics and the existing default JSON interface.
+
+For interactive layout selection, `search-template.py --summary` exposes only the top three IDs, names, scores and layouts. Full `--json` output and the programmatic ranking interface are unchanged. Source-to-claim review in `references/01-evidence-mining.md` remains an Agent responsibility and is distinct from deterministic profile/PDF text consistency.

package/README.md

@@ -46,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.
 
 ---
@@ -97,21 +97,24 @@ knowme list
 
 ---
 
-### Option B: Direct Agent Integration
+### Platform entrypoints and runtime resources
 
-| 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/` |
+| 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` |
+
+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. User input and artifact lifecycle
 
-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.
+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).
 
@@ -121,7 +124,7 @@ Each forge invocation writes snapshots, Master, Variant, canvas, QA and manifest
 
 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.
 
-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.
+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.
 
 ---
 

package/README.zh-CN.md

@@ -46,7 +46,7 @@ knowme-careerforge-skill
 真实经历与证据   工程化定制交付
 ```
 
-- **KnowMe（自我认知与证据挖掘引擎）**：帮助候选人深入认知自我，系统梳理真实经历与可验证的代码/项目证据（L1~L3 分级），提炼真正具备竞争壁垒的优势点。
+- **KnowMe（自我认知与证据挖掘引擎）**：帮助候选人深入认知自我，系统梳理用户提供的真实经历与辅助材料，提炼真正具备竞争壁垒的优势点。
 - **CareerForge（职业定位与简历工程引擎）**：将候选人的真实优势精准对齐目标岗位（JD），以 **HTML 中间工作区（Intermediate Canvas）** 与 **Design Tokens（设计系统变量）** 为工作场进行微调排版，最终通过 Playwright 无头浏览器导出确定性、像素级的矢量 PDF。
 
 ---
@@ -99,21 +99,24 @@ 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. 用户信息与资料生命周期
 
-当前功能依靠用户描述、已有简历和明确提供的支持材料，由宿主 Agent 组织与定制内容；不支持代码仓库分析回填。目标岗位即可开始，JD 可选。
+当前功能依靠用户描述、已有简历和明确提供的支持材料，由宿主 Agent 组织与定制内容；不支持代码仓库分析回填。目标岗位即可开始收集资料，JD 可选；没有候选人材料时先提问并等待，不生成演示履历。
 
 Draft 保留不完整资料，Master 保存本次已知事实，Variant 记录来源 Master 的摘要并派生岗位表达。缺失值省略或 null，不补示例姓名、默认荣誉和任意指标。完整规则见 [资料与验收契约](references/07-artifact-contract.md)。
 
@@ -123,7 +126,7 @@ Draft 保留不完整资料，Master 保存本次已知事实，Variant 记录
 
 打印模式会检查所有页面，再解析最终 PDF 的每页尺寸与文本。PASS 表示本次检查通过；FAIL 是检查失败；UNVERIFIED 是浏览器/依赖等导致无法验收；DRAFT 只表示草稿准备完成。自动检查不等同于事实核实或通用 ATS 认证。
 
-需要 Python 3.9+、Node.js 22.13+ 和 npm 运行依赖。运行 `npm install`；没有系统 Chromium 时使用 `npx playwright install chromium`。
+在安装目录按 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` 精简终端输出，内部快照与诊断仍保留。
 
 ---
 

package/SKILL.md

@@ -4,46 +4,68 @@ description: Create or refine a tailored resume from user descriptions, existing
 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
+  version: 0.0.7
 ---
 
 # KnowMe CareerForge
 
-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.
+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.
 
-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.
+## 1. Start from the conversation
 
-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.
+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: “请发已有简历，或告诉我姓名、最近一段工作经历（公司、时间、做了什么、用过哪些技术）；已有的信息不用重复。”
 
-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.
+- **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.
 
-## Preserve the artifact lifecycle
+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.
 
-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.
+## 2. Compose once, choose a layout
 
-- 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.
+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.
 
-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.
+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.
+
+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.
+
+## 3. Prepare runtime, generate
+
+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.
+
+After there is sufficient candidate material, and before the first PDF build, run:
 
 ```bash
-# 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
+node <skill-root>/scripts/rendering/browser-engine.js --check-runtime
+```
+
+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.
 
-# Incomplete input: return a draft, without a verified PDF claim.
-python3 <skill-root>/scripts/pipeline/forge.py --profile-json <draft.json> --draft --quiet
+For a new resume, keep internal files under `workspace/` and publish only the readable deliverables under `resume/` (or the user's chosen locations):
 
-# 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
+```bash
+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
 ```
 
-## Assemble and inspect
+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
+python3 <skill-root>/scripts/rendering/render-pdf.py <edited-resume.html> <new-resume.pdf> --expected-pages 1 --quiet
+```
+
+## 4. Inspect and deliver
+
+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.
+
+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.
+
+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 `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).
+Use one concise delivery shape across hosts, adapting only language and filenames:
 
-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.
+> 已生成简历： [PDF](<current PDF path>) · [可编辑 HTML](<current HTML path>)。模板：<templateUsed>。<One useful gap or actual inspection limitation, if any.>
 
-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.
+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,3 +1,3 @@
 # KnowMe CareerForge
 
-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.
+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.

package/agents/codex/knowme-careerforge.yaml

@@ -1,22 +1,6 @@
 name: knowme-careerforge
 description: An agent-native skill for self-discovery, career positioning, and tailored resume engineering.
-version: 0.0.6
+version: 0.0.7
 entrypoint: SKILL.md
-tools:
-  - name: forge
-    command: python3 scripts/pipeline/forge.py
-  - name: search-template
-    command: python3 scripts/template/search-template.py
-  - name: analyze-jd
-    command: python3 scripts/evidence/analyze-jd.py
-  - name: instantiate-resume
-    command: python3 scripts/template/instantiate-resume.py
-  - name: validate-resume
-    command: python3 scripts/validation/validate-resume.py
-  - name: render-pdf
-    command: python3 scripts/rendering/render-pdf.py
 rules:
-  - "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."
+  - "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."

package/agents/cursor/knowme-careerforge.mdc

@@ -5,4 +5,4 @@ alwaysApply: false
 
 # KnowMe CareerForge
 
-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.
+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.

package/agents/gemini/knowme-careerforge.json

@@ -1,6 +1,6 @@
 {
   "name": "knowme-careerforge",
   "description": "An agent-native skill for self-discovery, career positioning, and tailored resume engineering.",
-  "instructions": "Execute the 6-stage KnowMe CareerForge workflow: Know Me (L1~L3 evidence) -> Define -> Understand (JD signals) -> Position -> Forge (HTML canvas & tokens) -> Review (Dual QA & PDF export).",
+  "instructions": "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.",
   "entrypoint": "SKILL.md"
 }

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.6
+version: 0.0.7
 schema: 1.0
 entrypoint: SKILL.md
 tags:

package/agents/windsurf/knowme-careerforge.rules

@@ -1,3 +1,3 @@
 # KnowMe CareerForge
 
-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.
+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.

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

@@ -70,6 +70,25 @@ function copyDirRecursive(src, dest) {
         }
     }
 }
+function copyRuntimeBundle(rootDir, destination) {
+    fs.mkdirSync(destination, { recursive: true });
+    for (const directory of ['scripts', 'src', 'references']) {
+        copyDirRecursive(path.join(rootDir, directory), path.join(destination, directory));
+    }
+    for (const file of ['SKILL.md', 'skill.json', 'package.json']) {
+        fs.copyFileSync(path.join(rootDir, file), path.join(destination, file));
+    }
+    // npm archives omit package-lock.json; source checkouts can retain a locked install.
+    const lock = path.join(rootDir, 'package-lock.json');
+    const installedLock = path.join(destination, 'package-lock.json');
+    if (fs.existsSync(lock))
+        fs.copyFileSync(lock, installedLock);
+    else
+        fs.rmSync(installedLock, { force: true });
+    console.log(`Runtime files copied -> ${destination}`);
+    console.log(`Prepare dependencies in that directory: npm ${fs.existsSync(lock) ? 'ci' : 'install'} --omit=dev`);
+    console.log('Then run: node scripts/rendering/browser-engine.js --check-runtime');
+}
 function runInit(options) {
     const rootDir = findPackageRoot(__dirname);
     const projectDir = options.projectDir ? path.resolve(options.projectDir) : process.cwd();
@@ -85,82 +104,82 @@ function runInit(options) {
     console.log(`  Target Project: ${projectDir}`);
     console.log(`  Platforms     : ${targetPlatforms.join(', ')}`);
     console.log('==============================================================');
+    let failures = 0;
     for (const plat of targetPlatforms) {
         try {
             switch (plat) {
                 case 'claude': {
                     const claudeDir = path.join(homeDir, '.claude', 'skills', 'knowme-careerforge');
-                    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}`);
+                    copyRuntimeBundle(rootDir, claudeDir);
+                    console.log(`[✓] Claude Code Skill files installed -> ${claudeDir}`);
                     break;
                 }
                 case 'codex': {
                     const codexDir = path.join(homeDir, '.codex', 'skills', 'knowme-careerforge');
-                    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'));
+                    copyRuntimeBundle(rootDir, codexDir);
                     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'));
                     }
-                    console.log(`[✓] Codex Native Skill fully bundled -> ${codexDir}`);
+                    console.log(`[✓] Codex Native Skill files installed -> ${codexDir}`);
                     break;
                 }
                 case 'cursor': {
                     const cursorRulesDir = path.join(projectDir, '.cursor', 'rules');
                     fs.mkdirSync(cursorRulesDir, { recursive: true });
+                    const runtimeDir = path.join(projectDir, '.knowme', 'skills', 'knowme-careerforge');
+                    copyRuntimeBundle(rootDir, runtimeDir);
                     const mdcContent = fs.readFileSync(path.join(rootDir, 'agents', 'cursor', 'knowme-careerforge.mdc'), 'utf-8');
-                    fs.writeFileSync(path.join(cursorRulesDir, 'knowme-careerforge.mdc'), mdcContent, 'utf-8');
+                    fs.writeFileSync(path.join(cursorRulesDir, 'knowme-careerforge.mdc'), mdcContent + `\nRuntime entry: ${JSON.stringify(path.join(runtimeDir, 'SKILL.md'))}\n`, 'utf-8');
                     console.log(`[✓] Cursor MDC Rule configured -> ${path.join(cursorRulesDir, 'knowme-careerforge.mdc')}`);
                     break;
                 }
                 case 'windsurf': {
                     const windsurfRulePath = path.join(projectDir, '.windsurfrules');
+                    const runtimeDir = path.join(projectDir, '.knowme', 'skills', 'knowme-careerforge');
+                    copyRuntimeBundle(rootDir, runtimeDir);
                     const ruleContent = fs.readFileSync(path.join(rootDir, 'agents', 'windsurf', 'knowme-careerforge.rules'), 'utf-8');
-                    fs.appendFileSync(windsurfRulePath, `\n\n${ruleContent}`, 'utf-8');
+                    const begin = '<!-- knowme-careerforge:start -->';
+                    const end = '<!-- knowme-careerforge:end -->';
+                    const previous = fs.existsSync(windsurfRulePath) ? fs.readFileSync(windsurfRulePath, 'utf-8') : '';
+                    const block = `${begin}\n${ruleContent}\nRuntime entry: ${JSON.stringify(path.join(runtimeDir, 'SKILL.md'))}\n${end}`;
+                    const managed = /<!-- knowme-careerforge:start -->[\s\S]*?<!-- knowme-careerforge:end -->/;
+                    fs.writeFileSync(windsurfRulePath, managed.test(previous) ? previous.replace(managed, () => block) : previous + `\n\n${block}\n`, 'utf-8');
                     console.log(`[✓] Windsurf Rule configured -> ${windsurfRulePath}`);
                     break;
                 }
                 case 'gemini': {
                     const geminiDir = path.join(homeDir, '.gemini', 'skills');
                     fs.mkdirSync(geminiDir, { recursive: true });
-                    const geminiJson = fs.readFileSync(path.join(rootDir, 'agents', 'gemini', 'knowme-careerforge.json'), 'utf-8');
-                    fs.writeFileSync(path.join(geminiDir, 'knowme-careerforge.json'), geminiJson, 'utf-8');
+                    const runtimeDir = path.join(geminiDir, 'knowme-careerforge');
+                    copyRuntimeBundle(rootDir, runtimeDir);
+                    const geminiConfig = JSON.parse(fs.readFileSync(path.join(rootDir, 'agents', 'gemini', 'knowme-careerforge.json'), 'utf-8'));
+                    geminiConfig.entrypoint = path.join(runtimeDir, 'SKILL.md');
+                    fs.writeFileSync(path.join(geminiDir, 'knowme-careerforge.json'), JSON.stringify(geminiConfig, null, 2) + '\n', 'utf-8');
                     console.log(`[✓] Gemini CLI Skill configured -> ${path.join(geminiDir, 'knowme-careerforge.json')}`);
                     break;
                 }
                 case 'opencode': {
                     const opencodeDir = path.join(projectDir, '.opencode', 'skills', 'knowme-careerforge');
-                    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}`);
+                    copyRuntimeBundle(rootDir, opencodeDir);
+                    console.log(`[✓] OpenCode Skill files installed -> ${opencodeDir}`);
                     break;
                 }
                 default:
+                    failures += 1;
                     console.log(`[!] Unknown platform: ${plat}. Supported: ${SUPPORTED_PLATFORMS.join(', ')}`);
             }
         }
         catch (err) {
+            failures += 1;
             const msg = err instanceof Error ? err.message : String(err);
             console.error(`[✗] Failed to initialize ${plat}: ${msg}`);
         }
     }
-    console.log('\n[✓] Skill setup complete. You can now use knowme-careerforge in your agent workflows!');
+    if (failures) {
+        process.exitCode = 1;
+        console.error(`[✗] ${failures} platform setup(s) failed.`);
+    }
+    else {
+        console.log('Configuration and runtime files installed. Prepare dependencies and check runtime before generating PDFs; host discovery must be verified separately.');
+    }
 }

package/dist/cli/src/index.js

@@ -58,11 +58,11 @@ function getVersion(rootDir) {
         const pkgJson = path.join(rootDir, 'package.json');
         if (require('fs').existsSync(pkgJson)) {
             const data = JSON.parse(require('fs').readFileSync(pkgJson, 'utf-8'));
-            return data.version || '0.0.6';
+            return data.version || '0.0.7';
         }
     }
     catch { }
-    return '0.0.6';
+    return '0.0.7';
 }
 function showHelp() {
     console.log(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowme-careerforge-skill",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "An agent-native skill for self-discovery, career positioning, and tailored resume engineering.",
   "main": "dist/cli/src/index.js",
   "bin": {

package/references/01-evidence-mining.md

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

package/references/02-career-goal.md

@@ -6,7 +6,7 @@
 
 ## 1. Professional Seniority Signals
 
-Identify candidate level and calibrate narrative depth accordingly:
+Use these archetypes to guide questions, not to infer facts. Years alone do not establish seniority, ownership or proficiency. Preserve the user’s stated role and responsibility; omit unsupported claims from the following illustrative patterns.
 
 | Seniority Tier | Core Value Proposition | Key Narrative Signals | Section Priority |
 |:---|:---|:---|:---|
@@ -19,6 +19,8 @@ Identify candidate level and calibrate narrative depth accordingly:
 
 ## 2. Role Archetypes Knowledge Base (`src/knowledge/roles/*.json`)
 
+Read a role profile only for a specific positioning question after candidate facts are available. `mustHaveSkills`, `niceToHaveSkills` and `evidenceSignals` describe hiring expectations and question topics; they are never defaults for personal skills, mechanisms or accomplishments. A generic role name may cover several seniority levels.
+
 The skill ships with 9+ structured role profiles:
 - `ai-agent-engineer.json`: LLM Orchestration, RAG, Tool Calling, VectorDB, Prompt Engineering
 - `frontend.json`: React/Vue/Next.js, Web Vitals, Design Systems, State Management
@@ -31,7 +33,7 @@ The skill ships with 9+ structured role profiles:
 
 ## 3. Core Value Proposition Formulation
 
-Synthesize the 15~25 word Value Proposition headline following this formula:
+If useful, write a short headline from supplied facts. The following formula is optional: omit years, strengths or impact when unknown. The example is fictional and must never fill a candidate record.
 $$\text{Value Proposition} = [\text{Target Role}] + [\text{Years/Domain Focus}] + [\text{Top 2 Signature Strengths}] + [\text{Concrete Impact Deliverable}]$$
 
 *Example*:

package/references/03-jd-analysis.md

@@ -21,24 +21,12 @@ python3 scripts/evidence/analyze-jd.py --jd "path/to/jd.md" --json
 
 ## 2. Keyword Density & Highlighting Rules
 
-In `workspace/resume.html`, inject JD keywords to pass ATS automated screening while remaining natural for human reviewers:
+Use JD terms only where the candidate has supplied matching experience. Keywords select or emphasize existing facts; they do not add skills to a Master or Variant. A technology named only by the vacancy remains a gap to discuss.
 
-- **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.
+Prefer a few relevant, readable terms over repetition. There is no project-validated universal ATS keyword-density threshold. Do not claim automated screening success from keyword counts.
 
----
-
-## 3. FAB (Feature-Advantage-Benefit) Bullet Engineering
-
-Structure every project bullet point using the FAB formula:
+## 3. Writing useful bullets
 
-```
-┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
-│  Feature (技术动作)│ ────> │ Advantage (技术优势)│ ────> │  Benefit (业务价值) │
-│ Exact tech & tool │       │ Architectural gain│     │ Quantified impact│
-└─────────────────┘       └─────────────────┘       └─────────────────┘
-```
+Describe the supplied action and its context. Add the method and outcome only when the user provided them. FAB is an optional editing aid, not a requirement that every duty acquire an invented business impact.
 
-*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**).
+For example, if the only fact is “optimized order queries”, a faithful rewrite is “Optimized order queries for the ecommerce service” only if that service context was supplied. Do not infer indexing, Redis caching, P99 latency or traffic multiples. Preserve “participated” versus “led”, and ask for consequential missing mechanisms instead of writing them as facts.

package/references/04-template-selection.md

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

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

@@ -12,3 +12,16 @@ The pipeline isolates each run and records artifact hashes in manifest.json. Use
 `forge.py` 和 `instantiate-resume.py` 支持 `--font-preset system|arial-unicode`，默认保留系统字体。`arial-unicode` 显式使用本机 Arial Unicode MS；没有该字体时字体验收失败并返回 UNVERIFIED，不保证跨机器可用，也不自动下载字体。字体选择只改变画布样式，不改变 Master 事实，并记录在 Variant 的 source.fontPreset 和运行清单中。
 
 中文 PDF 若文本验收失败，检查 QA 每页的 missingCodepoints、missingFragments 与 extractedRadicals。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。
+
+## What each check can actually establish
+
+| Evidence | What it supports | What it cannot establish |
+| --- | --- | --- |
+| Original user material compared with rewritten claims | Fidelity to supplied facts | Independent verification of the user's history |
+| Master/Variant hashes and bound text | Run provenance and rendering consistency | That Agent-written profile claims came from the user |
+| Current PDF page/text/layout checks | Technical PDF acceptance | Complete optional information, ideal design or universal ATS support |
+| Every page of the final PDF viewed | Actual visual appearance of those pages | Authenticity of the candidate's achievements |
+
+Inspect the PDF itself using the host's PDF viewer or an available PDF-to-image tool, not a screen-media HTML preview. If no such tool is available, say the PDF's visual review is incomplete; keep the technical PASS distinction. Do not install a second rendering system just to repeat checks the pipeline already performed.
+
+When a font mapping warning occurs, read the reported missing fragments/codepoints and compare with the source text and page appearance. A warning is a diagnostic clue, not a diagnosis or an automatic reason to force a specific font. Use an available explicit font only as a justified retry; preserve facts and recheck the new PDF. After the current export and review pass, deliver rather than creating more copies or rerunning unchanged checks.

package/references/07-artifact-contract.md

@@ -62,3 +62,22 @@
 当前分页契约要求每个 `.resume-page` 对应一个 A4 页面，`--expected-pages` 为 1 或 2 的上限。一页文档可用上限 2；两页文档需由 Agent 显式建立两个页面容器。单个超高容器自然流入多页会被拒绝，不猜测浏览器分页后每页应有的内容。
 
 输入文档的来源说明保存在 Master 的 source.suppliedSource 中，包括 synthetic-simulation 等原始标签。它是来源元数据，不是新增候选人事实。字体预设单独记录为 Variant.source.fontPreset；不得把字体修订误记为事实变更。
+
+## 简短输入与交付入口
+
+Agent 可直接整理裸 profile；只填写用户提供的值，删除未知字段及不需要的章节。以下尖括号仅说明字段含义，不能作为候选人数据执行：
+
+```json
+{
+  "basics": {"name": "<用户姓名>", "title": "<目标岗位>"},
+  "skills": [{"category": "<分组>", "items": ["<用户提供的技能>"]}],
+  "experience": [{"company": "<公司>", "role": "<实际职务>",
+    "startDate": "<开始时间>", "endDate": "<结束时间>",
+    "bullets": [{"text": "<用户提供的职责或成果>"}]}],
+  "education": [{"degree": "<学历>", "field": "<专业>"}]
+}
+```
+
+姓名和至少一个实质章节是当前 PDF 输入门槛；联系方式、学校、专业和日期允许未知。`missingFields` 仅列出 basics.name/title/email/phone 的缺失，空列表不表示所有字段完整，更不证明事实真实。
+
+`forge.py --summary` 仅精简终端报告，包含当前状态、模板、错误、仅 html/pdf 的 outputs 和 manifest 路径；默认及 `--quiet` 仍保留完整 JSON。完整 manifest 与 QA 始终落盘。正常交付用 `--output resume/resume.pdf --html-output resume/resume.html` 创建验收副本；内部运行历史不作为用户默认交付清单。失败时副本可能仍为旧版本，不能据此报告本次成功。Draft 不使用这些验收副本选项。

package/scripts/pipeline/forge.py

@@ -111,6 +111,7 @@ def main():
     parser.add_argument('--expected-pages', type=int, choices=(1, 2), default=1)
     parser.add_argument('--auto-heal', action='store_true')
     parser.add_argument('--quiet', '-q', action='store_true')
+    parser.add_argument('--summary', action='store_true', help='Compact report with manifest path; full diagnostics stay on disk')
     args = parser.parse_args()
     report = {'schemaVersion': '1.0', 'runId': uuid.uuid4().hex, 'status': 'RUNNING',
               'stage': 'input', 'errors': [], 'warnings': [], 'checks': {}, 'outputs': {}}
@@ -264,7 +265,16 @@ def main():
                 report.update(status='FAIL', outputs={})
                 report['errors'].append('Could not persist manifest: ' + str(error))
                 exit_code = 1
-        print(json.dumps(report, ensure_ascii=False, indent=None if args.quiet else 2))
+        emitted = report
+        if args.summary:
+            emitted = {key: report[key] for key in ('runId', 'status', 'stage', 'templateUsed', 'fontPreset', 'errors', 'warnings', 'outputs') if key in report}
+            emitted['outputs'] = {}
+            if report['status'] in ('PASS', 'DRAFT'):
+                emitted['outputs']['html'] = str(Path(args.html_output).resolve()) if report['status'] == 'PASS' and args.html_output else report['outputs']['htmlCanvas']
+            if report['status'] == 'PASS':
+                emitted['outputs']['pdf'] = str(Path(args.output).resolve()) if args.output else report['outputs']['pdfDelivery']
+            emitted['manifest'] = str(run / 'manifest.json') if run else None
+        print(json.dumps(emitted, ensure_ascii=False, indent=None if args.quiet else 2))
     return exit_code
 
 

package/scripts/rendering/browser-engine.js

@@ -148,6 +148,37 @@ async function dependencies() {
   return { pw, PDFDocument, pdfjs };
 }
 
+// Readiness does not generate candidate artifacts or certify a resume.
+async function checkRuntime() {
+  const result = { status: 'UNVERIFIED', stage: 'runtime', errors: [], checks: {} };
+  const version = process.versions.node.split('.').map(Number);
+  if (version[0] < 22 || (version[0] === 22 && version[1] < 13)) {
+    result.errors.push('Node.js 22.13+ is required');
+  }
+  for (const [name, candidates] of [
+    ['playwright', ['playwright', 'playwright-core']],
+    ['pdf-lib', ['pdf-lib']],
+    ['pdfjs-dist', ['pdfjs-dist/legacy/build/pdf.mjs']]
+  ]) {
+    const available = candidates.some(candidate => {
+      try { require.resolve(candidate); return true; } catch { return false; }
+    });
+    result.checks[name] = available ? 'AVAILABLE' : 'MISSING';
+    if (!available) result.errors.push(`Missing dependency: ${name}`);
+  }
+  if (!result.errors.length) {
+    let browser;
+    try {
+      const deps = await dependencies();
+      browser = await launchBrowser(deps.pw);
+      result.checks.browser = browser.version();
+      result.status = 'READY';
+    } catch (error) { result.errors.push(error.message); }
+    finally { if (browser) await browser.close(); }
+  }
+  return result;
+}
+
 async function systemBrowsers() {
   const home = require('node:os').homedir();
   const candidates = [
@@ -335,6 +366,17 @@ async function run(html, { expectedPages = 1, autoHeal = false, outputPdf } = {}
 }
 
 async function cli(args = process.argv.slice(2), defaults = {}) {
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    process.stdout.write('Usage: browser-engine.js <resume.html> [--output <resume.pdf>] [--expected-pages 1|2] [--auto-heal]\n       browser-engine.js --check-runtime\n');
+    process.exitCode = 0;
+    return;
+  }
+  if (args.length === 1 && args[0] === '--check-runtime') {
+    const result = await checkRuntime();
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exitCode = result.status === 'READY' ? 0 : 2;
+    return result;
+  }
   let html = 'workspace/resume.html';
   const options = { ...defaults };
   const positional = [];

package/scripts/template/search-template.py

@@ -382,6 +382,7 @@ def main():
     parser.add_argument("--engine", "-e", default="hybrid", choices=["hybrid", "weighted", "bm25"], help="Scoring engine")
     parser.add_argument("--json", action="store_true", help="Output raw JSON array")
     
+    parser.add_argument("--summary", action="store_true", help="Compact JSON with the top three ranked layouts; no full metadata")
     args = parser.parse_args()
     target_role = args.named_role or args.role
     if not target_role:
@@ -396,6 +397,14 @@ def main():
         engine=args.engine
     )
     
+    if args.summary:
+        print(json.dumps({"totalMatches": len(results), "candidates": [
+            {"id": item["id"], "name": item.get("name"), "score": item["matchScore"],
+             "layout": item.get("layout", {})}
+            for item in results[:3]
+        ]}, ensure_ascii=False, indent=2))
+        return
+
     if args.json:
         print(json.dumps(results, ensure_ascii=False, indent=2))
         return

package/skill.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/skill.json",
   "name": "knowme-careerforge",
   "displayName": "KnowMe CareerForge",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "An agent-native skill for self-discovery, career positioning, and tailored resume engineering. Know yourself. Define your direction. Forge your opportunity.",
   "author": "Miles <https://github.com/Max-Samson>",
   "license": "MIT",
@@ -38,10 +38,11 @@
     "writing-assistant"
   ],
   "installation": {
-    "claude": "cp -r knowme-careerforge-skill ~/.claude/skills/knowme-careerforge",
-    "codex": "cp -r knowme-careerforge-skill ~/.codex/skills/knowme-careerforge",
-    "cursor": "cp SKILL.md .cursor/rules/knowme-careerforge.mdc",
-    "windsurf": "cat SKILL.md >> .windsurfrules",
-    "opencode": "cp -r knowme-careerforge-skill ~/.opencode/skills/knowme-careerforge"
+    "claude": "knowme init --ai claude",
+    "codex": "knowme init --ai codex",
+    "cursor": "knowme init --ai cursor",
+    "windsurf": "knowme init --ai windsurf",
+    "gemini": "knowme init --ai gemini",
+    "opencode": "knowme init --ai opencode"
   }
 }

package/src/knowledge/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.6",
+  "version": "0.0.7",
   "totalRoles": 9,
   "totalTemplates": 10,
   "roles": [

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

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

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

@@ -6,7 +6,7 @@
 
 ## 1. Professional Seniority Signals
 
-Identify candidate level and calibrate narrative depth accordingly:
+Use these archetypes to guide questions, not to infer facts. Years alone do not establish seniority, ownership or proficiency. Preserve the user’s stated role and responsibility; omit unsupported claims from the following illustrative patterns.
 
 | Seniority Tier | Core Value Proposition | Key Narrative Signals | Section Priority |
 |:---|:---|:---|:---|
@@ -19,6 +19,8 @@ Identify candidate level and calibrate narrative depth accordingly:
 
 ## 2. Role Archetypes Knowledge Base (`src/knowledge/roles/*.json`)
 
+Read a role profile only for a specific positioning question after candidate facts are available. `mustHaveSkills`, `niceToHaveSkills` and `evidenceSignals` describe hiring expectations and question topics; they are never defaults for personal skills, mechanisms or accomplishments. A generic role name may cover several seniority levels.
+
 The skill ships with 9+ structured role profiles:
 - `ai-agent-engineer.json`: LLM Orchestration, RAG, Tool Calling, VectorDB, Prompt Engineering
 - `frontend.json`: React/Vue/Next.js, Web Vitals, Design Systems, State Management
@@ -31,7 +33,7 @@ The skill ships with 9+ structured role profiles:
 
 ## 3. Core Value Proposition Formulation
 
-Synthesize the 15~25 word Value Proposition headline following this formula:
+If useful, write a short headline from supplied facts. The following formula is optional: omit years, strengths or impact when unknown. The example is fictional and must never fill a candidate record.
 $$\text{Value Proposition} = [\text{Target Role}] + [\text{Years/Domain Focus}] + [\text{Top 2 Signature Strengths}] + [\text{Concrete Impact Deliverable}]$$
 
 *Example*:

package/src/references/03-jd-analysis.md

@@ -21,24 +21,12 @@ python3 scripts/evidence/analyze-jd.py --jd "path/to/jd.md" --json
 
 ## 2. Keyword Density & Highlighting Rules
 
-In `workspace/resume.html`, inject JD keywords to pass ATS automated screening while remaining natural for human reviewers:
+Use JD terms only where the candidate has supplied matching experience. Keywords select or emphasize existing facts; they do not add skills to a Master or Variant. A technology named only by the vacancy remains a gap to discuss.
 
-- **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.
+Prefer a few relevant, readable terms over repetition. There is no project-validated universal ATS keyword-density threshold. Do not claim automated screening success from keyword counts.
 
----
-
-## 3. FAB (Feature-Advantage-Benefit) Bullet Engineering
-
-Structure every project bullet point using the FAB formula:
+## 3. Writing useful bullets
 
-```
-┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
-│  Feature (技术动作)│ ────> │ Advantage (技术优势)│ ────> │  Benefit (业务价值) │
-│ Exact tech & tool │       │ Architectural gain│     │ Quantified impact│
-└─────────────────┘       └─────────────────┘       └─────────────────┘
-```
+Describe the supplied action and its context. Add the method and outcome only when the user provided them. FAB is an optional editing aid, not a requirement that every duty acquire an invented business impact.
 
-*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**).
+For example, if the only fact is “optimized order queries”, a faithful rewrite is “Optimized order queries for the ecommerce service” only if that service context was supplied. Do not infer indexing, Redis caching, P99 latency or traffic multiples. Preserve “participated” versus “led”, and ask for consequential missing mechanisms instead of writing them as facts.

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

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

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

@@ -12,3 +12,16 @@ The pipeline isolates each run and records artifact hashes in manifest.json. Use
 `forge.py` 和 `instantiate-resume.py` 支持 `--font-preset system|arial-unicode`，默认保留系统字体。`arial-unicode` 显式使用本机 Arial Unicode MS；没有该字体时字体验收失败并返回 UNVERIFIED，不保证跨机器可用，也不自动下载字体。字体选择只改变画布样式，不改变 Master 事实，并记录在 Variant 的 source.fontPreset 和运行清单中。
 
 中文 PDF 若文本验收失败，检查 QA 每页的 missingCodepoints、missingFragments 与 extractedRadicals。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。
+
+## What each check can actually establish
+
+| Evidence | What it supports | What it cannot establish |
+| --- | --- | --- |
+| Original user material compared with rewritten claims | Fidelity to supplied facts | Independent verification of the user's history |
+| Master/Variant hashes and bound text | Run provenance and rendering consistency | That Agent-written profile claims came from the user |
+| Current PDF page/text/layout checks | Technical PDF acceptance | Complete optional information, ideal design or universal ATS support |
+| Every page of the final PDF viewed | Actual visual appearance of those pages | Authenticity of the candidate's achievements |
+
+Inspect the PDF itself using the host's PDF viewer or an available PDF-to-image tool, not a screen-media HTML preview. If no such tool is available, say the PDF's visual review is incomplete; keep the technical PASS distinction. Do not install a second rendering system just to repeat checks the pipeline already performed.
+
+When a font mapping warning occurs, read the reported missing fragments/codepoints and compare with the source text and page appearance. A warning is a diagnostic clue, not a diagnosis or an automatic reason to force a specific font. Use an available explicit font only as a justified retry; preserve facts and recheck the new PDF. After the current export and review pass, deliver rather than creating more copies or rerunning unchanged checks.

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

@@ -62,3 +62,22 @@
 当前分页契约要求每个 `.resume-page` 对应一个 A4 页面，`--expected-pages` 为 1 或 2 的上限。一页文档可用上限 2；两页文档需由 Agent 显式建立两个页面容器。单个超高容器自然流入多页会被拒绝，不猜测浏览器分页后每页应有的内容。
 
 输入文档的来源说明保存在 Master 的 source.suppliedSource 中，包括 synthetic-simulation 等原始标签。它是来源元数据，不是新增候选人事实。字体预设单独记录为 Variant.source.fontPreset；不得把字体修订误记为事实变更。
+
+## 简短输入与交付入口
+
+Agent 可直接整理裸 profile；只填写用户提供的值，删除未知字段及不需要的章节。以下尖括号仅说明字段含义，不能作为候选人数据执行：
+
+```json
+{
+  "basics": {"name": "<用户姓名>", "title": "<目标岗位>"},
+  "skills": [{"category": "<分组>", "items": ["<用户提供的技能>"]}],
+  "experience": [{"company": "<公司>", "role": "<实际职务>",
+    "startDate": "<开始时间>", "endDate": "<结束时间>",
+    "bullets": [{"text": "<用户提供的职责或成果>"}]}],
+  "education": [{"degree": "<学历>", "field": "<专业>"}]
+}
+```
+
+姓名和至少一个实质章节是当前 PDF 输入门槛；联系方式、学校、专业和日期允许未知。`missingFields` 仅列出 basics.name/title/email/phone 的缺失，空列表不表示所有字段完整，更不证明事实真实。
+
+`forge.py --summary` 仅精简终端报告，包含当前状态、模板、错误、仅 html/pdf 的 outputs 和 manifest 路径；默认及 `--quiet` 仍保留完整 JSON。完整 manifest 与 QA 始终落盘。正常交付用 `--output resume/resume.pdf --html-output resume/resume.html` 创建验收副本；内部运行历史不作为用户默认交付清单。失败时副本可能仍为旧版本，不能据此报告本次成功。Draft 不使用这些验收副本选项。

package/src/templates/common/canvas-bindings.css

@@ -1,5 +1,5 @@
 /* Binding components shared by the ten fact-free canvas.html layouts.
-   Loaded after the preview stylesheet; scoped so previews stay unchanged. */
+   Loaded after each template stylesheet for both gallery and candidate output. */
 .bound-canvas {
   font-family: var(--resume-font-body, var(--primitive-font-sans));
   font-size: var(--resume-font-size-body, 9.2pt);
@@ -15,7 +15,7 @@
 .bound-canvas .contact-item { white-space: pre-wrap; }
 .bound-canvas .resume-section { margin-bottom: var(--resume-space-section, 12pt); }
 .bound-canvas .section-title { font-size: var(--resume-font-size-h2, 12pt); margin-bottom: 6pt; }
-.bound-canvas .item-header { display: flex; flex-wrap: wrap; gap: 3pt 8pt; align-items: baseline; }
+.bound-canvas .item-header { display: flex; flex-wrap: wrap; gap: 3pt 8pt; align-items: baseline; justify-content: flex-start; }
 .bound-canvas .date-range { white-space: normal; margin-left: auto; }
 .bound-canvas .role-badge, .bound-canvas .tech-tag { white-space: normal; }
 .bound-canvas .experience-item, .bound-canvas .project-item, .bound-canvas .education-item {

package/src/templates/minimal/README.md

@@ -4,7 +4,7 @@
 
 - **版式风格**：单栏线性流 (Single-Column Linear Flow)
 - **视觉色系**：极客蓝 (`#2563eb`) + 板岩灰阶 (`#0f172a`, `#334155`)
-- **ATS 评级**：Tier 1 (Optimal - 100% 完美解析)
+- **ATS 评级**：Tier 1（设计意图，不代表第三方 ATS 认证）
 - **目标页数**：严格 1 页 (支持微调扩展至 2 页)
 - **核心 Tokens**：
   - `--resume-space-section`: `11pt` (默认)
@@ -19,3 +19,5 @@
 - `metadata.json`：模板选择与布局元数据。
 
 在项目根目录运行 `python3 scripts/build/build-gallery.py` 生成画廊。预览与实际简历共用实例化器及完整 CSS 链；生成的 HTML 位于 `output/templates_gallery/`，不回写到模板源目录。
+
+学历、专业和机构由公共绑定样式相邻排列，只有实际日期向右对齐；学校或日期未知时不以占位文字补齐。资料较少时应保留合理留白，不为填满高密度版式添加经历。