knowme-careerforge-skill 0.0.6 → 0.0.8

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.8
 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.8';
         }
     }
     catch { }
-    return '0.0.6';
+    return '0.0.8';
 }
 function showHelp() {
     console.log(`
@@ -75,30 +75,34 @@ Usage:
 
 Commands:
   forge                 Isolated user facts -> variant -> canvas -> verified PDF
-  render                Multi-strategy deterministic A4 PDF export
+  render                Diagnostic PDF export; use forge for paired delivery
   init                  Install and configure Skill for AI Agent platforms (cursor, claude, codex, windsurf, gemini, opencode)
   list                  Display all available role profiles and HTML templates
   search <role>         Search and rank templates for a specific role (e.g. knowme search "AI Agent Engineer")
-  validate              Validate working canvas HTML layout & ATS compliance
+  validate              Diagnostic print/PDF checks; does not publish a delivery pair
   gallery               Build & refresh static HTML template gallery
   test                  Run full automated test suite
   help                  Show this help message
 
 Options (for forge):
-  --profile-json <file> User/Agent prepared facts or Master document
-  --workspace <dir>    Parent for isolated run directories (default: workspace/runs)
+  --profile-json <file> Facts file, or - for JSON on stdin
+  --html-input <file>  Existing edited HTML, or - for HTML on stdin
+  --keep-workspace     Retain diagnostic archive (default: temporary staging)
+  --workspace <dir>    Explicit archive parent; enables retention
   --draft              Create a draft canvas without PDF delivery
   --role <title>        Target role title
   --jd <file|text>      Target job description
-  --template, -t <id>   Template ID (minimal, modern, executive, classic, academic-research, international-flow, creative-tech, compact-dense, startup-generalist, data-analyst)
+  --template, -t <id>   Template ID (minimal, modern, executive, classic, academic-research, international-flow, creative-tech, compact-dense, startup-generalist, data-analyst, editorial, graduate, project-focus)
   --name <name>         Candidate name override
-  --output, -o <path>   Optional verified PDF copy (default: isolated run)
+  --output, -o <path>   Verified PDF destination (default: resume/resume.pdf)
   --font-preset <name>  system or arial-unicode (requires local Arial Unicode MS)
-  --auto-heal           Enable heuristic token auto-healing to eliminate A4 height overflow
-  --quiet, -q           Quiet execution (compact JSON output)
+  --auto-heal           Attempt bounded spacing/type tuning; unresolved overflow fails
+  --html-output <path> HTML destination (default: beside the PDF)
+  --summary            Compact report; default in clean mode
+  --quiet, -q           Single-line JSON; does not change file retention
 Examples:
   knowme forge --profile-json candidate.json --role "AI Agent Engineer" --template modern
-  knowme render workspace/resume.html workspace/resume.pdf
+  knowme forge --html-input -  # Supply complete edited HTML on stdin
   knowme init --ai codex
   knowme init --all
 `);
@@ -119,8 +123,9 @@ function main() {
             break;
         }
         case 'extract': {
-            console.error('Repository-to-resume extraction is not supported. Use user-provided facts with forge --profile-json.');
-            process.exitCode = 1;
+            const scriptPath = path.join(rootDir, 'scripts', 'evidence', 'extract-evidence.py');
+            const proc = child_process.spawnSync('python3', [scriptPath, ...args.slice(1)], { stdio: 'inherit' });
+            process.exitCode = proc.status || 1;
             break;
         }
         case 'render': {
@@ -203,9 +208,12 @@ function main() {
         case 'help':
         case '--help':
         case '-h':
-        default:
             showHelp();
             break;
+        default:
+            console.error(`Unknown command: ${command}. Run knowme help for supported commands.`);
+            process.exitCode = 1;
+            break;
     }
 }
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knowme-careerforge-skill",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "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,112 @@
-# Organize user-supplied facts
+# Expand supplied experience into strong resume content
 
-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. Use a relevant role profile when it helps expose an ability already supported by the material; skip it for a straightforward wording or contact edit.
+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 when a consequential ambiguity affects correctness or when a focused answer would materially improve the strongest evidence; otherwise deliver the supported draft. 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.
+
+## Expand meaning, not the candidate's history
+
+The Agent is an editor and reasoning partner. Do more than copy the input: organize scattered facts, resolve supplied relationships, explain what an action demonstrates, and make the strongest evidence easy to read. More words are useful only when they add supported meaning.
+
+Distinguish three operations:
+
+| Operation | Treatment |
+| --- | --- |
+| Professional expression | Freely improve sentence structure, terminology, grouping and emphasis while preserving meaning. |
+| Supported ability synthesis | Name a bounded ability demonstrated by the described action. Implementing an API can support “API development experience”; it does not establish distributed architecture expertise. Avoid “expert”, “proficient” or broad mastery without corresponding input. |
+| New historical detail | Ask or present it as an optional question outside the resume. Do not assert an unprovided implementation, business setting, ownership, scale, result or metric. |
+
+Use any suitable writing pattern, leaving unsupported parts out:
+
+- **Delivery:** supplied responsibility + object/module + supplied implementation or collaboration context.
+- **Problem solving:** supplied problem + personal action + known mechanism + observed result, if available.
+- **Technical practice:** supplied technology + actual use + demonstrated, bounded capability.
+- **Transferable ability:** concrete action + underlying problem-solving ability relevant to the target, without relabeling the original stack.
+- **Leadership:** actual decision/coordination scope + personal action + supplied outcome. Seniority and target titles do not supply leadership evidence.
+
+Do not fill every slot or force every bullet into FAB. Split a dense description when it contains distinct contributions; combine fragments when they describe the same achievement. Skills should summarize practice at the supported level, not become a catalog of the role profile.
+
+### Examples: input → useful expansion
+
+These examples illustrate reasoning, not reusable candidate facts.
+
+- Input: “用 Node.js/NestJS 写了订单创建和状态查询接口。”
+  Resume: “基于 Node.js / NestJS 开发订单创建与状态查询接口。”
+  The input is already specific: a shorter sentence is better than adding “完成后端接口开发” to repeat it. Ability summary, if useful elsewhere: “具备 Node.js / NestJS 后端接口开发经验。” Prefer the concrete bullet when space is limited; do not repeat both mechanically. Do not add payment consistency, high concurrency or independent ownership.
+- Input: “用 Python 做了内部文档问答，文档向量化后检索，再交给大模型回答。”
+  Resume: “使用 Python 实现内部文档问答，将文档向量化、相关内容检索与大模型回答生成串联为 RAG 问答流程。”
+  This names a mechanism the user actually described. It does not establish LangChain, a particular vector database, reranking, agent planning or production scale.
+- Input: “参与 Redis 缓存开发，把热点商品信息放缓存，减少重复查数据库。”
+  Resume: “参与商品信息缓存开发，使用 Redis 缓存热点商品数据，减少重复数据库查询。”
+  Do not add cache-hit rate, distributed locks, cache penetration protection or a percentage improvement.
+- Input: “做过 Agent，用过 LangGraph。”
+  Safe current version: “具有基于 LangGraph 的 Agent 开发经历。”
+  High-value question: “这个 Agent 完成什么任务？你实现了哪些节点、工具或流程？” Do not expand into multi-agent orchestration or autonomous planning without an answer.
+
+## Ask for information that changes the writing
+
+Prefer a focused question about the strongest relevant experience: what problem, what personal contribution, what concrete method, what observable change? Select the missing dimension with the highest value; do not require a fixed interview sequence or numeric results. User feedback, completed delivery, reduced manual work or resolved failures can be useful outcomes when supplied.
+
+If the user wants an immediate result, write the supported version now and optionally mention the most valuable missing detail. If the user wants deeper expansion, use their answer to strengthen the draft. Do not block usable content on optional details or put unconfirmed placeholders into the final resume. Ambiguous ownership or conflicting critical facts warrant clarification; routine phrasing does not require approval.
+
+## 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.
+
+## Editorial review: make each sentence earn its place
+
+Use these criteria to revise a substantive draft, not as a mandatory user-visible checklist or a fixed number of revision passes. Stop when the material is clear, useful and faithful; do not rewrite repeatedly for synonyms.
+
+| Question | Editing action |
+| --- | --- |
+| What new information does the added phrase convey? | Remove restatements such as “开发接口，完成接口开发工作” and generic claims such as “展现优秀技术能力”. |
+| Can a reader identify the candidate's action? | Prefer a concrete action and object to “深度赋能 / 全面推动 / 闭环落地”. Preserve the supplied ownership level. |
+| Are method and result actually connected in the source? | Combine related facts, but do not attach a team's result to the candidate's action without support. |
+| Does a number retain its meaning? | Preserve approximate qualifiers, measurement scope, baseline and time period when given. Do not turn average latency into P99 or a team result into a personal result. |
+| Is the strongest evidence easy to find? | Put the most relevant contribution early within its entry. Keep job chronology legible rather than moving dates or mixing employers for keyword emphasis. |
+| Is the summary doing different work from the detail? | Summarize a supported pattern of practice; leave its specific achievement in one primary location. Omit the summary when it only duplicates a short entry. |
+
+### Compose sections according to the available evidence
+
+- **Summary:** optional, usually a compact statement of actual practice and distinctive scope. No invented years, self-ratings or promise of future impact. A target role belongs in the objective when it differs from actual experience.
+- **Skills:** group supplied technologies by meaningful use where possible, such as “后端开发：Node.js / NestJS（订单接口）”. Mentioned-only tools may remain tools; do not add use cases or expertise. Avoid repeating every technology in both a long summary and multiple skill paragraphs.
+- **Experience:** give useful context once, then distinct contributions. Do not manufacture a separate project from each duty. A named project inside an employer can be developed when the source supports its context and contribution.
+- **Projects:** prioritize distinct supplied work. Preserve its nature: course exercise, personal prototype, internal tool and production service are different settings. Do not silently promote one into another.
+
+Choose wording and section labels for the user's language. Preserve recognizable technology names; avoid literal translation of English action-verb formulas into inflated Chinese. Do not enforce an English word-count target on Chinese summaries. Sparse material may justify a few polished bullets; rich material may justify fuller entries. Neither a fixed bullet count nor a full page is a content-quality target.
+
+### Rich input: organize distinct evidence rather than inflate it
+
+Fictional source: “给内部客服做过 Python 文档问答。我的部分是把文档分段、向量化、检索，再把相关内容交给模型回答。还整理了 30 个常见问题，检查回答有没有文档依据，发现问题后调整分段。没有统计准确率。”
+
+Possible resume entry:
+- “参与内部客服文档问答开发，使用 Python 实现文档分段、向量化、检索与上下文组装，为模型回答提供相关文档内容。”
+- “整理 30 个常见问题，检查回答的文档依据，并根据发现的问题调整文档分段。”
+
+The two bullets show application implementation and evaluation practice. They do not claim automated evaluation, a specific retrieval library, accuracy improvement or ownership of the whole application. A separate summary is optional, not another copy of these bullets. Here “参与” reflects the explicitly limited personal scope; do not apply it to users who explicitly owned the whole project.
+
+## 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

@@ -4,21 +4,23 @@
 
 ---
 
-## 1. Professional Seniority Signals
+## 1. Position from demonstrated scope
 
-Identify candidate level and calibrate narrative depth accordingly:
+Use the user's actual responsibility and target to choose emphasis. Years and titles provide context, not proof of seniority. The same candidate may have strong implementation evidence but limited leadership evidence; express each at its supported level.
 
-| Seniority Tier | Core Value Proposition | Key Narrative Signals | Section Priority |
-|:---|:---|:---|:---|
-| **Junior (1~3 Years)** | Rapid learning, solid coding standards, reliable task delivery | Clean code, unit test coverage, framework fluency, bug resolution | Skills → Projects → Experience → Education |
-| **Mid-Level (3~5 Years)** | Independent ownership, feature architecture, performance optimization | End-to-end module ownership, database tuning, API design, CI/CD | Experience → Projects → Skills → Education |
-| **Senior / Lead (5~8+ Years)** | System architecture, technical leadership, cross-system trade-offs | Distributed systems, high availability, mentoring, business impact | Experience → Projects → Architecture → Skills |
-| **Principal / Architect** | Technical vision, organizational strategy, governance, ROI | Architecture governance, multi-team alignment, technology selection | Experience → Leadership → Architecture → Patents |
+| Supplied evidence | Useful emphasis | Possible leading section |
+| --- | --- | --- |
+| Course, personal or internship projects | Concrete implementation and problem solving; preserve the project setting | Relevant projects or education |
+| Delivered modules or features | Personal contribution, methods and actual delivery scope | Work experience |
+| System decisions and cross-service trade-offs | What was decided, why, and the user's actual authority | Relevant work or projects |
+| Team coordination or organizational responsibility | Actual coordination scope, decisions and observed outcomes | Work experience |
 
----
+These are editorial options, not an automatic section order or a requirement to create “Architecture”, “Leadership” or “Patents” sections. Use the strongest supplied evidence first within a clear career narrative.
 
 ## 2. Role Archetypes Knowledge Base (`src/knowledge/roles/*.json`)
 
+Read the relevant role profile when positioning or ability expansion would improve supplied candidate material. Treat its section order as a suggestion; demonstrated strengths and the target audience determine the actual hierarchy. `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
@@ -29,10 +31,30 @@ The skill ships with 9+ structured role profiles:
 
 ---
 
-## 3. Core Value Proposition Formulation
+## 3. Write a useful summary when the evidence warrants one
+
+Select a supported pattern of work plus a distinctive context or responsibility. Mention a result only when it adds information beyond the detailed entry. A short profile does not need a summary. Do not fill a formula with years, strengths and impact that the source does not provide.
+
+Fictional source: “用 Python 做过内部文档问答，自己做了文档检索与模型回答衔接，也整理常见问题检查回答依据。”
+
+Possible summary: “具有 Python 文档问答应用开发经验，实践覆盖检索与模型回答衔接、基于常见问题的回答检查。”
+
+Detailed bullets should then supply the concrete implementation and checking work. This source does not justify “资深 Agent 架构师”, “端到端多智能体平台” or a quantified improvement. For a single short project, prefer its concrete bullets and omit this summary.
+
+## 4. Use role templates as reasoning aids
+
+Choose one relevant role, then connect each promising `evidenceSignals` topic to an actual user action. Classify it as direct support, transferable support, or unknown. Develop only supported topics into resume prose. `mustHaveSkills` describes the archetype, not a universal hiring requirement or a personal qualification; a supplied JD and the candidate's facts take precedence.
+
+For AI Agent engineering, consider the following angles only when the user describes related work:
+
+| Supplied work | Ability that may be expressed | Detail worth asking about |
+| --- | --- | --- |
+| Implemented workflow nodes and branches | Workflow orchestration implementation | Actual state transitions and personal scope |
+| Connected a model to external tools | Tool integration | Tool purpose, argument handling, failure behavior actually implemented |
+| Retrieved documents for model answers | RAG application development | Retrieval steps, corpus, evaluation if performed |
+| Compared answers against a test set | Model/application evaluation practice | Evaluation criteria and observed findings |
+| Deployed and maintained an application | Application delivery and maintenance | Actual users, operational responsibility, observed issues |
 
-Synthesize the 15~25 word Value Proposition headline following this formula:
-$$\text{Value Proposition} = [\text{Target Role}] + [\text{Years/Domain Focus}] + [\text{Top 2 Signature Strengths}] + [\text{Concrete Impact Deliverable}]$$
+These angles do not require all candidates to have all five capabilities. A simple LLM API application need not be promoted into a multi-agent system. Use the same method for frontend, backend, product and other roles: domain knowledge helps interpret actual work, not manufacture experience.
 
-*Example*:
-> **Senior AI Agent Engineer** with 5+ years building scalable LLM orchestration & enterprise RAG pipelines, delivering 40% latency reduction across multi-agent production workflows.
+For a transition, show the original stack honestly and foreground reusable problem-solving evidence. A role objective may name the destination; actual job titles and historical projects retain their identities. For experienced candidates with strong work evidence, place that evidence before a long skills catalog; for students, relevant projects or education may lead.

package/references/03-jd-analysis.md

@@ -11,6 +11,8 @@ Execute the JD analyzer to extract structured requirements:
 python3 scripts/evidence/analyze-jd.py --jd "path/to/jd.md" --json
 ```
 
+The analyzer is a heuristic helper, not a semantic certification. `detectedSkills` lists recognized technologies, including those adjacent to Chinese text. `mustHaveSkills` and `niceToHaveSkills` classify explicit requirement markers or headings only; unclassified and conflicting skills remain in `detectedSkills` without being assigned a priority. Inspect the original JD before making a positioning decision.
+
 ### Signal Extraction Dimensions:
 1. **Target Role & Seniority Tier**: Extracted from title and years of experience requirements;
 2. **Must-Have Skills (Hard Constraints)**: Top technical stacks and non-negotiable architectural competencies;
@@ -21,24 +23,20 @@ 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. Writing useful bullets
 
-## 3. FAB (Feature-Advantage-Benefit) Bullet Engineering
+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.
 
-Structure every project bullet point using the FAB formula:
+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.
 
-```
-┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
-│  Feature (技术动作)│ ────> │ Advantage (技术优势)│ ────> │  Benefit (业务价值) │
-│ Exact tech & tool │       │ Architectural gain│     │ Quantified impact│
-└─────────────────┘       └─────────────────┘       └─────────────────┘
-```
+## 4. Tailor the argument, not just the keywords
+
+Before rendering, form an internal mapping: requirement → supplied experience → direct/transferable/unsupported → placement or question. This need not become a saved artifact. Read the original JD for scope, seniority and business problems; the heuristic parser cannot establish those meanings reliably.
+
+Choose the strongest supported evidence for the most relevant requirements. Reorder bullets within entries, expand a relevant terse contribution, and compress repetition or less relevant detail while preserving useful chronology. A gap remains a gap; do not compensate by adding a skill list copied from the JD. Without a JD, use the user's target and an appropriate role archetype as a provisional editorial lens, not as a specific employer's requirements.
 
-*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**).
+Check whether the tailored version actually changes the emphasis and evidence selection. Changing only the target title or bolding keywords is insufficient when the user asked for substantive tailoring. The pipeline's `--jd` option supplies search/highlighting hints; semantic tailoring is the host Agent's responsibility before submitting the profile.

package/references/04-template-selection.md

@@ -1,43 +1,35 @@
-# Reference Manual 04: Template Selection & Layout Geometries
+# Template selection and readable composition
+
+Select for the candidate's actual amount of content, strongest evidence and explicit preference. A backend title alone does not determine the layout. The thirteen current IDs below are directory IDs accepted by the pipeline; metadata describes design intent, not visual or ATS certification.
+
+| ID | Structure | Review before choosing |
+| --- | --- | --- |
+| editorial | Single column with section rail | Experience first; medium-length professional histories |
+| graduate | Single column, education first | Students and internships; preserve actual project setting |
+| project-focus | Single column, projects first | Distinct project evidence; do not duplicate employment bullets |
+| minimal | Single column | Straight reading order; sparse content needs breathing room rather than compression |
+| international-flow | Single column | Consider for linear prose; inspect language and line lengths |
+| modern | Sidebar, 32:68 | Keep side content short; check narrow-column wrapping |
+| creative-tech | Sidebar, 28:72 | Use only when the visual emphasis suits the user |
+| data-analyst | Sidebar, 30:70 | Do not invent metrics to match the template name |
+| executive | Banner and split columns | Needs suitable supplied leadership evidence; a title does not confer it |
+| classic | Structured table | Check sparse fields and reading order |
+| compact-dense | Dense two columns | For substantial supplied content; avoid for a short career description |
+| academic-research | Dense single column | Research content must actually be supplied |
+| startup-generalist | Modular cards | Check block balance with the actual sections |
+
+Use the existing search when no template was selected:
 
-> **"Layout geometry determines information hierarchy. Select the composition that earns the candidate's strongest evidence."**
-
----
-
-## 1. Core Template Matrix (Baseline 4)
-
-| Template ID | Layout Geometry | Tone & Accent | Target Roles | Density | ATS Tier |
-|:---|:---|:---|:---|:---|:---|
-| `minimal` (`minimal-tech`) | Single-Column Linear Flow | Geek Minimal (Tech Blue `#2563eb`) | Backend, AI/LLM, Systems, DevOps, Fullstack | High | Tier 1 (Optimal) |
-| `modern` (`modern-split-sidebar`) | Two-Column Split (32:68 Dark Sidebar) | Deep Navy (`#254665`) + Sky Blue (`#38bdf8`) | AI Agent, Frontend, Fullstack, Mobile | Balanced | Tier 1 (Optimal) |
-| `executive` (`executive-split`) | Hero Banner + Two-Column (33:67 Split) | Executive Slate (`#1e293b`) + Teal (`#0f766e`) | Tech Director, Architect, PM, CTO | Balanced | Tier 1 (Optimal) |
-| `classic` (`table-structured`) | 6-Column Structured Grid Table | Corporate Blue (`#1d4ed8`) + Slate | Enterprise, Fintech, Hardware, State-Owned | High | Tier 1 (Optimal) |
-
----
-
-## 2. Template Search Engine (`scripts/template/search-template.py`)
-
-Search for the optimal template via CLI:
 ```bash
-# Hybrid Search (Default Recommended)
-python3 scripts/template/search-template.py "AI Agent Engineer" --style "two-column-split" --target-pages 1
-
-# BM25 Keyword Search
-python3 scripts/template/search-template.py "Distributed Architect" --engine bm25 --json
-
-# Weighted Multi-Criteria Rule Search
-python3 scripts/template/search-template.py "Frontend Engineer" --engine weighted
+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.
 
----
+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 designs were visually compared if only one was rendered.
 
-## 3. Instantiating the Intermediate HTML Canvas
+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.
 
-```bash
-python3 scripts/template/instantiate-resume.py --template modern --profile workspace/evidence-master.json --keywords "Python,LLM,RAG,FastAPI" --output workspace/resume.html
-```
+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.
 
-*The instantiator automatically inlines `src/templates/common/base.css` + `src/templates/{template}/style.css` into a single self-contained HTML file.*
+Choose one suitable layout from metadata before production; search results are suggestions, not a queue of templates to render. Compare multiple rendered alternatives only on request or to address a concrete visual defect. Keep experiments outside the candidate directory. A successful current output already exists at the delivery paths; do not run the same input/layout again solely to publish another copy.

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

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