knowme-careerforge-skill 0.0.7 → 0.0.8

package/src/knowledge/templates.json

@@ -316,6 +316,63 @@
         "--resume-space-section"
       ]
     },
+    {
+      "id": "editorial",
+      "name": "Editorial · 经历叙事",
+      "version": "1.0.0",
+      "style": "single-column-editorial",
+      "roleCategory": "professional",
+      "description": "经历优先，左侧章节索引与右侧正文对齐；适合已有连续工作经历的候选人。",
+      "layout": {
+        "type": "single-column",
+        "targetPages": 1,
+        "maxPages": 1,
+        "density": "balanced"
+      },
+      "visualStyle": {
+        "tone": "editorial-readable",
+        "accentColor": "#254665",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "professional",
+        "consultant"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/editorial",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-border",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-tag-bg",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-page-padding",
+        "--resume-space-bullet",
+        "--resume-space-header-bottom",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
+    },
     {
       "id": "executive",
       "name": "Executive Modern Split",
@@ -370,6 +427,7 @@
         "--resume-font-size-body",
         "--resume-font-size-meta",
         "--resume-font-size-name",
+        "--resume-font-size-target",
         "--resume-font-size-title",
         "--resume-left-col-width",
         "--resume-line-height-body",
@@ -378,6 +436,65 @@
         "--resume-space-section"
       ]
     },
+    {
+      "id": "graduate",
+      "name": "Graduate · 校园起点",
+      "version": "1.0.0",
+      "style": "single-column-education-first",
+      "roleCategory": "early-career",
+      "description": "教育与项目优先，宽松单栏；适合应届生、实习申请和较少工作经历。",
+      "layout": {
+        "type": "single-column",
+        "targetPages": 1,
+        "maxPages": 1,
+        "density": "balanced"
+      },
+      "visualStyle": {
+        "tone": "editorial-readable",
+        "accentColor": "#0f766e",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "graduate",
+        "intern",
+        "应届",
+        "实习"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/graduate",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-border",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-tag-bg",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-page-padding",
+        "--resume-space-bullet",
+        "--resume-space-header-bottom",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
+    },
     {
       "id": "international-flow",
       "name": "International Text Flow",
@@ -567,6 +684,63 @@
         "--resume-space-section"
       ]
     },
+    {
+      "id": "project-focus",
+      "name": "Project Focus · 项目实践",
+      "version": "1.0.0",
+      "style": "single-column-project-first",
+      "roleCategory": "portfolio",
+      "description": "项目优先，项目条目以细边线分隔；适合项目证据比工作履历更突出的候选人。",
+      "layout": {
+        "type": "single-column",
+        "targetPages": 1,
+        "maxPages": 1,
+        "density": "balanced"
+      },
+      "visualStyle": {
+        "tone": "editorial-readable",
+        "accentColor": "#334155",
+        "fontFamily": "System Sans-Serif"
+      },
+      "atsScoreTier": "tier-1-optimal",
+      "supportedRoles": [
+        "project-engineer",
+        "portfolio"
+      ],
+      "languages": [
+        "zh-CN",
+        "en-US"
+      ],
+      "customizableTokens": [
+        "--resume-font-size-body",
+        "--resume-line-height-body",
+        "--resume-space-section",
+        "--resume-space-item",
+        "--resume-space-bullet",
+        "--resume-color-accent"
+      ],
+      "directory": "src/templates/project-focus",
+      "detectedTokens": [
+        "--resume-color-accent",
+        "--resume-color-border",
+        "--resume-color-muted",
+        "--resume-color-primary",
+        "--resume-color-secondary",
+        "--resume-color-tag-bg",
+        "--resume-font-body",
+        "--resume-font-size-body",
+        "--resume-font-size-h2",
+        "--resume-font-size-meta",
+        "--resume-font-size-name",
+        "--resume-font-size-target",
+        "--resume-line-height-body",
+        "--resume-page-padding",
+        "--resume-space-bullet",
+        "--resume-space-header-bottom",
+        "--resume-space-item",
+        "--resume-space-section"
+      ]
+    },
     {
       "id": "startup-generalist",
       "name": "Startup Generalist Cards",

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

@@ -1,15 +1,60 @@
-# Turn supplied facts into resume claims
+# Expand supplied experience into strong resume content
 
 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.
 
 ## 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.
+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 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.
+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.
@@ -25,6 +70,38 @@ These are isolated editing examples, not candidate material or a profile to exec
 
 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.

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

@@ -4,22 +4,22 @@
 
 ---
 
-## 1. Professional Seniority Signals
+## 1. Position from demonstrated scope
 
-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.
+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 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.
+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
@@ -31,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 |
 
-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}]$$
+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/src/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;
@@ -30,3 +32,11 @@ Prefer a few relevant, readable terms over repetition. There is no project-valid
 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.
 
 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.
+
+## 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.
+
+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/src/references/04-template-selection.md

@@ -1,9 +1,12 @@
 # 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 ten current IDs below are directory IDs accepted by the pipeline; metadata describes design intent, not visual or ATS certification.
+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 |
@@ -23,8 +26,10 @@ python3 <skill-root>/scripts/template/search-template.py "<target role>" --targe
 
 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 ten designs were visually compared if only one was rendered.
+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.
 
 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.
 
 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.
+
+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/src/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。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。

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

@@ -1,15 +1,15 @@
-# QA and final rendering
+# PDF generation, QA and final rendering
 
 Validation and rendering use scripts/rendering/browser-engine.js. Inspect print media after fonts settle, every page container and visible content boundary; generate a fresh PDF and parse every page for A4 portrait dimensions, allowed page count and extractable content matching the canvas.
 
 PASS requires the actual checks to complete. Missing browser/dependencies or timeout is UNVERIFIED (exit 2), a failed check is FAIL (exit 1). JSON mode uses the same exit rules. Do not use an estimate or an existing PDF as proof. Export verified bytes through a temporary file and atomic replacement; failed export retains the previous file.
 
-The pipeline isolates each run and records artifact hashes in manifest.json. Use its current PASS output paths, not shared default filenames. Factual and visual review remain Agent responsibilities; text extraction does not certify every ATS. See 07-artifact-contract.md for the complete lifecycle.
+The pipeline isolates each run and returns accepted artifact hashes. Default staging is temporary; only explicit --keep-workspace/--workspace retains a manifest. Use this invocation’s PASS output paths, not the existence of a shared default filename. A null manifest in clean mode is expected. Factual and visual review remain Agent responsibilities; text extraction does not certify every ATS. See 07-artifact-contract.md for the complete lifecycle.
 
 
 ## 本地字体与缺字诊断
 
-`forge.py` 和 `instantiate-resume.py` 支持 `--font-preset system|arial-unicode`，默认保留系统字体。`arial-unicode` 显式使用本机 Arial Unicode MS；没有该字体时字体验收失败并返回 UNVERIFIED，不保证跨机器可用，也不自动下载字体。字体选择只改变画布样式，不改变 Master 事实，并记录在 Variant 的 source.fontPreset 和运行清单中。
+`forge.py --profile-json` 和 `instantiate-resume.py` 支持 `--font-preset system|arial-unicode`，默认保留系统字体。`arial-unicode` 显式使用本机 Arial Unicode MS；没有该字体时字体验收失败并返回 UNVERIFIED，不保证跨机器可用，也不自动下载字体。字体选择只改变画布样式，不改变 Master 事实，并记录在 Variant 的 source.fontPreset 和运行清单中。
 
 中文 PDF 若文本验收失败，检查 QA 每页的 missingCodepoints、missingFragments 与 extractedRadicals。部首字符可能来自字体字码映射差异，也可能存在真实缺字；不能仅凭这种提示放行。可选用本机可用字体、创建新运行并重新检查，不改写姓名/经历来绕过问题，也不把部首字符全部忽略。
 
@@ -22,6 +22,40 @@ The pipeline isolates each run and records artifact hashes in manifest.json. Use
 | 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.
+Keep PDF inspection images and helper scripts in system temporary storage, clean your own temporary files afterward, and leave only the delivery pair in the output directory. 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.
+When a font mapping warning occurs, read the failure report’s diagnostics (or archived QA when retention was requested) for 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.
+
+## Production commands (HTML/PDF requests only)
+
+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
+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.
+
+For a new resume, pass the prepared JSON through stdin. Default clean mode leaves only `resume/resume.html` and `resume/resume.pdf` (or explicit output paths). Do not create profile, analysis, QA, process or history files unless the user requests them:
+
+```bash
+python3 <skill-root>/scripts/pipeline/forge.py --profile-json - --role "<target role>" --template <chosen-id>
+```
+
+Send the JSON with the command tool's stdin support or `subprocess.run(..., input=json.dumps(profile, ensure_ascii=False), text=True)`; do not interpolate candidate text into a shell command. If the host requires a file, use its temporary-file facility and remove only that newly created input after the command; never delete supplied files.
+
+Choose one layout before building. Do not render all search candidates for comparison unless requested. If an actual visual defect requires a different template, fix the cause and replace the same delivery pair rather than creating named versions. A selected accepted result is already a deliverable: do not rerun merely to obtain another copy.
+
+Drafts use `--draft` and return only `resume/draft.html` by default; they never update the current PDF. Read the exact returned status and paths. A successful preflight need not be repeated on contact or wording updates unless the environment changes. Clean mode reports `manifest: null`: it is intentional, not a missing-file error. Do not search for a run directory or reconstruct deleted diagnostics.
+
+For updates, read the current HTML, apply only the requested changes **in memory**, then submit the full edited HTML to the same pipeline through stdin:
+
+```bash
+python3 <skill-root>/scripts/pipeline/forge.py --html-input -
+```
+
+Use explicit output paths if the current pair is elsewhere. Do not overwrite the current HTML before validation: the pipeline stages the edit and publishes both files only after acceptance, preserving the old pair on ordinary failures. The report labels this `existing-canvas`, meaning the supplied structure/fonts are preserved, not that a new template was selected. Do not rebuild a profile from rendered text or create backup/version files to make a contact edit.
+
+Use returned diagnostics first; retry only after changing the identified cause. Only when the user requests archives or a specific unresolved failure requires full diagnostic retention, add `--keep-workspace`. An explicit `--workspace <dir>` also retains runs for compatibility with archived workflows. These options deliberately create extra files and are not part of normal resume production. Default temporary intermediates are cleaned on success and failure; existing user files and old archives are never swept or deleted.

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

@@ -23,7 +23,7 @@
 
 `profile` 的字段定义见 `src/knowledge/resume-schema.json`；脚本 `scripts/contracts/profile.py` 是归一化与封装契约的实现。脚本输出时附加 `profileSha256` 和 `missingFields`。摘要用于发现资料版本变化，不证明用户陈述真实性。手动修改封装资料后，应重新生成摘要或移除旧摘要再读入；不能保留不匹配的摘要。
 
-兼容旧版的裸 profile JSON，按调用者明确提供的 Master 事实输入处理。封装为 Draft 的输入必须加 `--draft` 才能生成草稿；复核后由 Agent 显式整理为 Master，不由工具自动升级。Variant 的语义改写与事实选择仍由宿主 Agent 完成；当前脚本保留所有输入条目，只处理显式基础信息覆盖、岗位标题及展示装配。
+兼容旧版的裸 profile JSON，按调用者明确提供的 Master 事实输入处理。封装为 Draft 的输入必须加 `--draft` 才能生成草稿；复核后由 Agent 显式整理为 Master，不由工具自动升级。Variant 的语义改写与事实选择仍由宿主 Agent 完成；当前脚本保留所有输入条目，只处理显式基础信息覆盖、岗位标题及展示装配。Agent 应先根据用户目标组织、扩写和选择本次展示内容，再提交 profile；此时 Master 是本次提交内容的事实快照，不代表保存了用户全部原始材料。原始对话或用户文件仍是核对依据，不从该快照的省略推断用户没有其他经历。完整事实库与显式选择清单尚未实现，不宣称管线自动完成岗位定制。
 
 ## 缺失值
 
@@ -33,13 +33,27 @@
 - 缺失联系方式和目标岗位记录为待补信息。正式交付至少需要非空姓名及实质内容，打印与 PDF 验收进一步判断内容有效性。
 - 旧版 L1/L2/L3 元数据可保留；用户陈述不因为来自对话就自动降级为“参与”。
 
-## 每次运行独立
+## 独立运行与产物保留
 
-`forge --profile-json <file>` 在 `workspace/runs/<唯一运行ID>/` 下创建私有目录，包含 `input.json` 原始输入快照、`master.json`、`variant.json`、`resume.html`、`qa.json`、通过验收后写入的 `resume.pdf` 和 `manifest.json`。Draft 运行保存 `draft.json` 和草稿画布，不生成正式 PDF。
+运行隔离不等于永久保存每次运行。默认模式在系统私有临时目录中完成输入快照、Master/Variant、模板装配及完整 QA；正常成功或失败后清理本次临时目录。默认不会在用户目录创建 `workspace/`、隐藏事实档案或历史快照。
 
-`--workspace` 仅改变运行目录的父目录，不复用已有运行。失败现场保留供诊断，不自动删除或继续使用其他运行的文件。目录包含个人资料，不提交到 Git；可由用户按需删除。测试必须使用临时目录。
+| 调用模式 | 用户目录新增产物 | 终端结果 |
+| --- | --- | --- |
+| 默认 `--profile-json -` | `resume/resume.html`、`resume/resume.pdf` | 简短报告，`retention: temporary`、`manifest: null`，仅当前交付路径及摘要 |
+| 默认 `--draft` | `resume/draft.html` | DRAFT，仅 HTML，不修改已有 PDF |
+| `--html-input -` | 验收后的当前 HTML/PDF 对 | 复用同一 QA 与发布机制，`templateUsed: existing-canvas`，不重建事实档案 |
+| `--keep-workspace` | `workspace/runs/<runId>/` 完整归档 | `retention: archived`，默认完整报告；可用 `--summary` |
+| 显式 `--workspace <dir>` | 指定父目录下的完整归档 | 保留原有归档行为，等同显式开启保留 |
+
+`--profile-json` 接受已有文件或 `-`（从 stdin 读取 JSON）。`--html-input` 接受已有画布或 `-`（从 stdin 读取 HTML），与 profile 输入互斥；不能同时传岗位、模板、字体或基础字段覆盖参数，相关修改应先在画布中完成。文件输入只读；输出路径不得与输入文件冲突。为了更新同一份简历，读取当前 HTML 并在内存中修改后通过 stdin 提交，避免提前破坏当前交付。
+
+默认输出可由 `--output`、`--html-output` 显式指定；只指定一项时，另一项使用相同主文件名与对应扩展名。归档模式不指定输出副本时，交付路径仍在归档目录。Draft 支持 `--html-output`，拒绝 PDF `--output`。
+
+只有完成本次完整验收的 HTML/PDF 才一起准备发布；普通复制或替换失败回滚，目标锁阻止两个本工具进程交错写入。跨文件发布不具备操作系统崩溃下的事务保证。默认不读取旧文件判定成功，也不创建 `latest.json` 等额外成功标记；当前调用状态、输出路径及摘要是交付依据。不要擅自删除遗留锁。
+
+归档模式保存原有输入、Master/Variant 或 Draft、HTML、QA、manifest 和通过验收的 PDF；HTML 输入不生成虚假的 Master/Variant，保存输入 HTML 与检查记录。失败现场仅在归档模式保留。纯净模式返回错误和必要诊断（含文本失败的缺字片段/码点、DOM 失败的页码/选择器/边界及 PDF 页数/尺寸；DOM 每类问题最多返回 20 条并附总数，不输出完整 DOM 正文），不返回已删除临时文件作为产物；需要深入诊断时显式保留下一次运行。进程被强制终止可能留下系统临时文件，不承诺强制终止时自动清理。
 
-`--html-output` 和 `--output` 是可选的已验收副本路径。先在独立运行中完成验证，再一起准备副本；写入失败时回滚普通错误，目标锁阻止两个本工具进程交错写入。跨文件复制不具备操作系统崩溃下的事务保证，因此运行目录和 manifest 始终是交付判据。发现遗留锁时报告冲突，不擅自删除其他运行的锁。
+清理范围仅为本次工具创建的临时目录，不删除用户输入、旧版 `workspace/`、用户指定的记录文件或已有交付文件。目录中已有内容不会因升级而被“清空”。资料属于用户隐私，不提交到 Git。
 
 ## 运行与检查状态
 
@@ -51,7 +65,7 @@
 | FAIL | 1 | 输入、绑定、布局、PDF 内容或输出写入不符合要求 |
 | UNVERIFIED | 2 | 浏览器、依赖、超时或检查协议故障，无法完成验收 |
 
-`manifest.json` 包含 `runId`、`stage`、`errors`、`warnings`、`checks`、`outputs`。失败的 `outputs` 为空，即使目录或显式输出位置存在旧 PDF，也不能返回它作为本次交付。只有 PASS 的清单记录本次输出路径及 HTML/PDF SHA-256。JSON 模式与人读模式使用同一退出语义。
+归档模式的 `manifest.json` 包含 `runId`、`stage`、`errors`、`warnings`、`checks`、`outputs`。失败的 `outputs` 为空，即使目录或显式输出位置存在旧 PDF，也不能返回它作为本次交付。PASS 报告记录本次 HTML/PDF 输出路径及 SHA-256；DRAFT 可记录 HTML 路径与摘要，但不表示 PDF 通过。JSON 模式与人读模式使用同一退出语义。
 
 ## 打印与最终 PDF
 
@@ -80,4 +94,4 @@ Agent 可直接整理裸 profile；只填写用户提供的值，删除未知字
 
 姓名和至少一个实质章节是当前 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 不使用这些验收副本选项。
+默认纯净模式已经返回简短报告；`--summary` 在归档模式下精简终端报告。`--quiet` 只控制 JSON 格式，不决定是否留存文件。需要完整历史的旧调用应显式传 `--workspace` 或 `--keep-workspace`；没有这些参数的调用改为纯净输出，不再默认保存完整报告。失败的 outputs 始终为空，不能把路径下残留的旧 PDF 当成本次成功。

package/src/templates/academic-research/canvas.html

@@ -11,10 +11,11 @@
 <main>
 <!-- resume:basics -->
 <!-- resume:summary -->
-<!-- resume:education --><!-- resume:certifications -->
+<!-- resume:education -->
 <!-- resume:skills -->
 <!-- resume:experience -->
 <!-- resume:projects -->
+<!-- resume:certifications -->
 </main>
 </div>
 </body>

package/src/templates/classic/canvas.html

@@ -14,7 +14,8 @@
 <tr><td><!-- resume:skills --></td></tr>
 <tr><td><!-- resume:experience --></td></tr>
 <tr><td><!-- resume:projects --></td></tr>
-<tr><td><!-- resume:education --><!-- resume:certifications --></td></tr>
+<tr><td><!-- resume:education --></td></tr>
+<tr><td><!-- resume:certifications --></td></tr>
 </tbody></table>
 </div>
 </body>