knowme-careerforge-skill 0.0.1 → 0.0.2

package/scripts/Agent.md

@@ -0,0 +1,138 @@
+# KnowMe CareerForge — Scripts Architecture & Agent Execution Specification
+
+> **定位**：面向 AI Agent 与研发工程师的 `scripts/` 工具链架构规范、模块划分标准与执行契约手册。
+>
+> **版本**：v1.0.0-modular  
+> **核心原则**：Domain-Driven Modularization · Quiet Agent Execution · Deterministic Rendering · Zero-Dependency Python Core
+
+---
+
+## 1. 目录架构与模块职责划分 (Domain Architecture)
+
+为了保证脚本工具链的高内聚、低耦合与易维护性，`scripts/` 目录划分为 **6 大功能领域模块**：
+
+```text
+scripts/
+├── Agent.md                         # 本规范文档 (Source of Truth for Agent/Dev)
+│
+├── pipeline/                        # 【模块 1: 端到端统筹管线】
+│   └── forge.py                     # 一键端到端装配引擎 (One-Shot Pipeline: 挖掘 -> 装配 -> QA -> PDF)
+│
+├── evidence/                        # 【模块 2: 事实与证据挖掘 (repo-to-resume)】
+│   ├── extract-evidence.py          # 代码仓与 Git 事实挖掘器 (提取技术栈、架构信号、Git 贡献 -> L1~L3 证据链)
+│   └── analyze-jd.py                # 目标 JD 深度分析器 (提取职级、分类、必备/加分项、痛点关键词)
+│
+├── template/                        # 【模块 3: 模板检索与工作区装配】
+│   ├── search-template.py           # 多维加权打分搜索引擎 (BM25 + 岗位/风格/页数/密度推荐)
+│   └── instantiate-resume.py        # 模板装配与数据注入引擎 (CSS 内联单文件 + 结构化数据注入 + 关键词高亮)
+│
+├── validation/                      # 【模块 4: 双重 QA 自动化质检】
+│   ├── validate-resume.py           # 语义结构、Design Tokens 与字符密度轻量校验器
+│   ├── validate-layout.ts           # Playwright DOM 盒模型物理高度 (1122.5px A4) 溢出与孤行检测
+│   └── validate-ats.ts              # ATS 纯文本流解析、联系方式与 H1/H2 标头层级校验
+│
+├── rendering/                       # 【模块 5: 确定性 PDF 渲染导出】
+│   ├── render-pdf.py                # 跨平台自愈式 PDF 渲染调度器 (自动探测 Playwright 及全平台 Chromium/Edge/Brave)
+│   └── render-pdf.ts                # Playwright 驱动的无损矢量 A4 PDF 渲染器
+│
+└── build/                           # 【模块 6: 编译构建、测试与发布工具链】
+    ├── build-knowledge.py           # 岗位画像与模板知识库索引编译器 (生成 index.json & templates.json)
+    ├── build-gallery.py             # 静态交互式模板画廊生成器 (编译 output/templates_gallery/)
+    ├── run-all-tests.py             # 全链路自动化测试运行器 (discover & run tests/)
+    ├── sync-version.py              # 多清单版本号同步器 (package.json / pyproject.toml / skill.json / cli)
+    └── release.py                   # 自动化发布流水线引擎 (版本对齐 -> 编译 -> 测试 -> 打包预检)
+```
+---
+
+## 2. 脚本契约与 Agent 调用规范 (Execution Contracts)
+
+### 2.1 推荐调用模式：一键直达管线 (One-Shot Execution)
+
+AI Agent 响应用户求职定制需求时，**强烈推荐首选一键管线**：
+
+```bash
+# 静默全流程执行 (后台自动完成：代码仓扫描 -> 模板检索 -> 工作区注入 -> Dual QA -> PDF 导出)
+python3 scripts/pipeline/forge.py --repo . --role "<Target Role>" --jd "<path/to/jd.txt>" --template modern --quiet
+```
+* **CLI 等价形式**：`knowme forge --repo . --role "<Target Role>" --template modern --quiet`
+* **返回格式**：结构化 JSON，供 Agent 直接获取交付文件路径：
+  ```json
+  {
+    "status": "SUCCESS",
+    "htmlCanvas": "workspace/resume.html",
+    "pdfDelivery": "workspace/resume.pdf",
+    "evidenceProfile": "workspace/evidence-master.json",
+    "templateUsed": "modern"
+  }
+  ```
+
+---
+
+### 2.2 细粒度分步调用接口 (Granular Step-by-Step APIs)
+
+当 Agent 或用户需要分步微调、审查证据或调校 Design Tokens 时，按以下顺序执行：
+
+| 步骤 | 阶段 | 推荐命令 | 关键参数 | 产出物 |
+| :--- | :--- | :--- | :--- | :--- |
+| **Step 1** | **事实挖掘** | `python3 scripts/evidence/extract-evidence.py` | `--repo <dir>` `--name <name>` `--quiet` | `workspace/evidence-master.json` |
+| **Step 2** | **JD 解析** | `python3 scripts/evidence/analyze-jd.py` | `--jd <file>` 或 `--text "<str>"` `--json` | 提取必须技能与权重关键词 |
+| **Step 3** | **模板检索** | `python3 scripts/template/search-template.py` | `"<Role>"` `--style "<style>"` `--json` | 加权推荐模板列表 (Top 1) |
+| **Step 4** | **画布装配** | `python3 scripts/template/instantiate-resume.py` | `--template <id>` `--profile <json>` `--keywords <kw>` | `workspace/resume.html` (单文件内联) |
+| **Step 5** | **质检自愈** | `python3 scripts/validation/validate-resume.py` | `--html workspace/resume.html` `--expected-pages 1` | QA 诊断状态与溢出提示 |
+| **Step 6** | **PDF 导出** | `python3 scripts/rendering/render-pdf.py` | `workspace/resume.html` `workspace/resume.pdf` `--quiet` | `workspace/resume.pdf` (确定性矢量) |
+
+---
+
+## 3. Agent 对话降噪规范 (Strict Quiet Execution Protocol)
+
+为了杜绝对话框中出现几百行冗余代码或中间脚本，所有接入的 AI Agent 必须遵守以下铁律：
+
+1. **禁止在 Chat 中打印原始 HTML/CSS**：禁止将 `workspace/resume.html` 的数百行代码打印到对话框中；
+2. **禁止在 Chat 中编写现场临时脚本**：严禁现场生成临时验证脚本或修改场脚本，必须使用 `scripts/` 下既有的标准工具链；
+3. **静默执行原则**：调用脚本时统一添加 `--quiet` 或 `--json` 参数；
+4. **标准交付物格式**：
+   ```markdown
+   ### 🎯 职业定位与核心价值主张 (Core Value Proposition)
+   > **[姓名] · [目标岗位]**
+   > *[15~25字核心定位与价值阐述]*
+
+   ---
+
+   ### 🛡️ Top 3 真实证据链亮点 (L1/L2 级别可追溯事实)
+   1. **[业务方向/核心架构]**: [动词 + 可量化成果 + 证据来源]
+   2. **[核心技术栈工程化]**: [关键框架与工程规范落地]
+   3. **[交付与系统效能]**: [稳定性/CI-CD/性能指标]
+
+   ---
+
+   ### 📄 最终交付产物
+   - **PDF 终稿 (确定性 A4)**: `workspace/resume.pdf`
+   - **HTML 修改场 (Design Tokens)**: `workspace/resume.html`
+   - **证据事实底座**: `workspace/evidence-master.json`
+   ```
+
+---
+
+## 4. 后续开发与扩展规范 (Developer Standards)
+
+为保持工程整洁与跨平台稳定性，后续新增或修改脚本必须遵循以下标准：
+
+### 4.1 根路径自适应解析 (Root Path Resolution Standard)
+所有 Python 脚本**严禁使用硬编码相对路径**，必须通过自适应探测函数定位项目根目录：
+```python
+def get_project_root() -> Path:
+    curr = Path(__file__).resolve().parent
+    for _ in range(5):
+        if (curr / "SKILL.md").exists() or (curr / "package.json").exists():
+            return curr
+        curr = curr.parent
+    return Path.cwd()
+```
+
+### 4.2 零重型依赖原则 (Zero-Heavy-Dependency)
+* 核心运行脚本（`evidence/`、`template/`、`pipeline/`）**仅使用 Python 3.9+ 标准库**（`json`, `argparse`, `pathlib`, `re`, `subprocess` 等）；
+* 避免引入大型三方包（如 pandas、scikit-learn），保证轻量秒开与跨平台零安装成本。
+
+### 4.3 渲染与 QA 规范
+* A4 绝对高度基准固化为 `1122.5px` ($297\text{mm} \times 96\text{DPI} / 25.4$)；
+* 任何涉及排版验证与 PDF 导出的改动，必须通过 `scripts/build/run-all-tests.py` 全量测试套件验证。

package/scripts/{build-gallery.py → build/build-gallery.py}

@@ -7,8 +7,16 @@ KnowMe CareerForge — Template Gallery Builder
 import os, sys, json, re
 from pathlib import Path
 
+def get_project_root() -> Path:
+    curr = Path(__file__).resolve().parent
+    for _ in range(5):
+        if (curr / "SKILL.md").exists() or (curr / "package.json").exists():
+            return curr
+        curr = curr.parent
+    return Path.cwd()
+
 def build_gallery():
-    base_dir = Path(__file__).resolve().parent.parent
+    base_dir = get_project_root()
     templates_dir = base_dir / "src" / "templates"
     gallery_dir = base_dir / "output" / "templates_gallery"
     gallery_dir.mkdir(parents=True, exist_ok=True)
@@ -33,28 +41,30 @@ def build_gallery():
 
         try:
             meta = json.loads(meta_file.read_text(encoding="utf-8"))
-            html_raw = html_file.read_text(encoding="utf-8")
-            css_raw = css_file.read_text(encoding="utf-8")
+            html_content = html_file.read_text(encoding="utf-8")
+            css_content = css_file.read_text(encoding="utf-8")
 
-            # 生成单文件自包含预览页面
-            inlined_preview = html_raw.replace(
+            # 编译内联单文件独立预览页面
+            inlined_preview = html_content.replace(
                 '<link rel="stylesheet" href="style.css">',
-                f'<style>\n{css_raw}\n  </style>'
+                f'<style>\n{css_content}\n  </style>'
             )
 
-            preview_path = gallery_dir / f"{meta['id']}.html"
+            preview_path = gallery_dir / f"{t_dir.name}.html"
             preview_path.write_text(inlined_preview, encoding="utf-8")
 
             gallery_items.append({
-                "id": meta["id"],
-                "name": meta.get("name", meta["id"]),
-                "style": meta.get("style", "custom"),
+                "id": meta.get("id", t_dir.name),
+                "name": meta.get("name", t_dir.name),
+                "style": meta.get("style", "single-column"),
                 "category": meta.get("roleCategory", "engineering-ai"),
+                "tone": meta.get("visualStyle", {}).get("tone", "modern"),
                 "accent": meta.get("visualStyle", {}).get("accentColor", "#2563eb"),
-                "targetPages": meta.get("layout", {}).get("targetPages", 1),
+                "pages": meta.get("layout", {}).get("targetPages", 1),
                 "density": meta.get("layout", {}).get("density", "balanced"),
-                "supported": meta.get("supportedRoles", []),
-                "previewUrl": f"{meta['id']}.html"
+                "atsTier": meta.get("atsScoreTier", "tier-1-optimal"),
+                "previewFile": f"{t_dir.name}.html",
+                "supported": meta.get("supportedRoles", [])
             })
             print(f"[✓] Generated Gallery Preview -> {preview_path.name}")
         except Exception as e:
@@ -66,132 +76,149 @@ def build_gallery():
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>KnowMe CareerForge — 核心基准模板画廊</title>
+  <title>KnowMe CareerForge — HTML Resume Template Gallery</title>
   <style>
     :root {{
-      --bg: #0f172a;
-      --card-bg: #1e293b;
-      --border: #334155;
-      --accent: #38bdf8;
-      --text: #f8fafc;
-      --muted: #94a3b8;
+      --primary: #0f172a;
+      --secondary: #475569;
+      --accent: #2563eb;
+      --bg: #f8fafc;
+      --card-bg: #ffffff;
+      --border: #e2e8f0;
     }}
     * {{ box-sizing: border-box; margin: 0; padding: 0; }}
     body {{
-      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", sans-serif;
-      background: var(--bg);
-      color: var(--text);
-      padding: 32px 20px;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+      background-color: var(--bg);
+      color: var(--primary);
+      padding: 40px 20px;
+      line-height: 1.5;
     }}
-    .container {{
-      max-width: 1360px;
+    .gallery-container {{
+      max-width: 1200px;
       margin: 0 auto;
     }}
-    .header {{
+    header {{
       text-align: center;
-      margin-bottom: 32px;
+      margin-bottom: 40px;
+    }}
+    h1 {{
+      font-size: 28px;
+      font-weight: 800;
+      color: var(--primary);
+      margin-bottom: 8px;
+    }}
+    .subtitle {{
+      color: var(--secondary);
+      font-size: 15px;
     }}
-    h1 {{ font-size: 26px; color: var(--accent); margin-bottom: 8px; font-weight: 800; }}
-    p.subtitle {{ color: var(--muted); font-size: 14px; max-width: 680px; margin: 0 auto; line-height: 1.5; }}
     .grid {{
       display: grid;
-      grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
       gap: 24px;
     }}
     .card {{
       background: var(--card-bg);
       border: 1px solid var(--border);
       border-radius: 12px;
-      padding: 20px;
+      overflow: hidden;
+      box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.05);
+      transition: transform 0.2s, box-shadow 0.2s;
       display: flex;
       flex-direction: column;
-      gap: 16px;
-      box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.2);
+    }}
+    .card:hover {{
+      transform: translateY(-4px);
+      box-shadow: 0 12px 20px -3px rgba(0, 0, 0, 0.1);
     }}
     .card-header {{
+      padding: 16px 20px;
+      border-bottom: 1px solid var(--border);
+      background: #f1f5f9;
       display: flex;
       justify-content: space-between;
-      align-items: flex-start;
-      border-bottom: 1px solid var(--border);
-      padding-bottom: 12px;
+      align-items: center;
     }}
     .card-title {{
-      font-size: 18px;
+      font-size: 16px;
       font-weight: 700;
-      color: var(--text);
     }}
     .badge {{
       font-size: 11px;
-      padding: 3px 8px;
-      border-radius: 12px;
-      background: rgba(56, 189, 248, 0.15);
-      color: var(--accent);
-      border: 1px solid rgba(56, 189, 248, 0.3);
+      padding: 2px 8px;
+      border-radius: 9999px;
+      background: #e2e8f0;
+      color: var(--secondary);
+      font-weight: 600;
     }}
-    .meta-list {{
+    .badge.optimal {{
+      background: #dcfce7;
+      color: #166534;
+    }}
+    .preview-frame-wrapper {{
+      height: 380px;
+      overflow: hidden;
+      position: relative;
+      background: #e2e8f0;
+    }}
+    .preview-frame {{
+      width: 210mm;
+      height: 297mm;
+      transform: scale(0.35);
+      transform-origin: top left;
+      border: none;
+      pointer-events: none;
+      background: #fff;
+    }}
+    .card-body {{
+      padding: 16px 20px;
+      flex: 1;
       display: flex;
       flex-direction: column;
-      gap: 6px;
-      font-size: 13px;
-      color: var(--muted);
+      justify-content: space-between;
     }}
-    .meta-item strong {{
-      color: var(--text);
+    .meta-list {{
+      font-size: 13px;
+      color: var(--secondary);
+      margin-bottom: 12px;
+      line-height: 1.6;
     }}
-    .tags {{
+    .tag-container {{
       display: flex;
       flex-wrap: wrap;
-      gap: 6px;
-      margin-top: 4px;
+      gap: 4px;
+      margin-bottom: 16px;
     }}
     .tag {{
-      background: #334155;
       font-size: 11px;
+      background: #f1f5f9;
+      color: #334155;
       padding: 2px 6px;
       border-radius: 4px;
-      color: #e2e8f0;
-    }}
-    .frame-wrapper {{
-      width: 100%;
-      height: 480px;
-      border: 1px solid var(--border);
-      border-radius: 8px;
-      overflow: hidden;
-      background: #ffffff;
-      position: relative;
-    }}
-    iframe {{
-      width: 210mm;
-      height: 297mm;
-      border: none;
-      transform: scale(0.48);
-      transform-origin: top left;
-      position: absolute;
-      top: 0;
-      left: 0;
-      pointer-events: none;
     }}
     .btn {{
-      display: inline-block;
+      display: block;
       text-align: center;
+      padding: 8px 16px;
       background: var(--accent);
-      color: #0f172a;
-      padding: 10px 16px;
+      color: #fff;
+      text-decoration: none;
       border-radius: 6px;
+      font-weight: 600;
       font-size: 13px;
-      font-weight: 700;
-      text-decoration: none;
-      transition: opacity 0.2s;
+      transition: background 0.2s;
+    }}
+    .btn:hover {{
+      background: #1d4ed8;
     }}
-    .btn:hover {{ opacity: 0.9; }}
   </style>
 </head>
 <body>
-  <div class="container">
-    <div class="header">
-      <h1>KnowMe CareerForge — 核心基准模板画廊</h1>
-      <p class="subtitle">面向 AI Agent 的确定性 HTML 简历设计工作场。所有模板均遵循 A4 绝对印刷几何与 CSS Design Tokens 规范。</p>
-    </div>
+  <div class="gallery-container">
+    <header>
+      <h1>KnowMe CareerForge — Template Gallery</h1>
+      <p class="subtitle">A4 Deterministic HTML Resume Templates with Design Tokens Calibration</p>
+    </header>
     <div class="grid">
 """
 
@@ -200,21 +227,23 @@ def build_gallery():
         gallery_html += f"""
       <div class="card">
         <div class="card-header">
-          <div>
-            <div class="card-title">{item['name']}</div>
-            <div style="font-size: 12px; color: var(--muted); margin-top: 2px;">ID: <code>{item['id']}</code></div>
-          </div>
-          <span class="badge">{item['style']}</span>
+          <span class="card-title">{item['name']}</span>
+          <span class="badge optimal">ATS Tier 1</span>
         </div>
-        <div class="meta-list">
-          <div class="meta-item"><strong>类别：</strong>{item['category']} | <strong>页数：</strong>{item['targetPages']} 页 | <strong>密度：</strong>{item['density']}</div>
-          <div class="meta-item"><strong>支持岗位：</strong></div>
-          <div class="tags">{tags_html}</div>
+        <div class="preview-frame-wrapper">
+          <iframe class="preview-frame" src="{item['previewFile']}"></iframe>
         </div>
-        <div class="frame-wrapper">
-          <iframe src="{item['previewUrl']}"></iframe>
+        <div class="card-body">
+          <div class="meta-list">
+            <div><strong>Style:</strong> {item['style']}</div>
+            <div><strong>Target:</strong> {item['pages']} page(s) ({item['density']} density)</div>
+            <div><strong>Tone:</strong> {item['tone']}</div>
+          </div>
+          <div class="tag-container">
+            {tags_html}
+          </div>
+          <a class="btn" href="{item['previewFile']}" target="_blank">Open Full A4 Preview ↗</a>
         </div>
-        <a href="{item['previewUrl']}" target="_blank" class="btn">打开独立预览 (A4 全尺寸)</a>
       </div>
 """
 

package/scripts/{build-knowledge.py → build/build-knowledge.py}

@@ -7,8 +7,16 @@ KnowMe CareerForge — Knowledge & Template Index Compiler
 import sys, os, json, re
 from pathlib import Path
 
+def get_project_root() -> Path:
+    curr = Path(__file__).resolve().parent
+    for _ in range(5):
+        if (curr / "SKILL.md").exists() or (curr / "package.json").exists():
+            return curr
+        curr = curr.parent
+    return Path.cwd()
+
 def build_knowledge_index():
-    base_dir = Path(__file__).resolve().parent.parent
+    base_dir = get_project_root()
     knowledge_dir = base_dir / "src" / "knowledge"
     templates_dir = base_dir / "src" / "templates"
     

package/scripts/{release.py → build/release.py}

@@ -7,6 +7,14 @@ KnowMe CareerForge — Release & NPM Publishing Automation Script
 import sys, os, subprocess, json, re, argparse
 from pathlib import Path
 
+def get_project_root() -> Path:
+    curr = Path(__file__).resolve().parent
+    for _ in range(5):
+        if (curr / "SKILL.md").exists() or (curr / "package.json").exists():
+            return curr
+        curr = curr.parent
+    return Path.cwd()
+
 def run_command(cmd, cwd, desc):
     print(f"\n[+] {desc}...")
     proc = subprocess.run(cmd, shell=True, text=True, cwd=cwd, capture_output=True)
@@ -24,7 +32,7 @@ def main():
     parser.add_argument("--publish", action="store_true", help="Directly trigger npm publish --access public after verification")
 
     args = parser.parse_args()
-    base_dir = Path(__file__).resolve().parent.parent
+    base_dir = get_project_root()
 
     # 1. 确定版本号
     pkg_file = base_dir / "package.json"
@@ -47,23 +55,23 @@ def main():
 
     # 2. 同步多文件版本号
     if target_version != current_version or args.version:
-        sync_script = base_dir / "scripts" / "sync-version.py"
+        sync_script = base_dir / "scripts" / "build" / "sync-version.py"
         run_command(f"python3 {sync_script} {target_version}", base_dir, f"Synchronizing version to v{target_version}")
 
     # 3. 重新编译知识库索引
-    build_kb = base_dir / "scripts" / "build-knowledge.py"
+    build_kb = base_dir / "scripts" / "build" / "build-knowledge.py"
     run_command(f"python3 {build_kb}", base_dir, "Compiling Knowledge Base Index")
 
     # 4. 重新构建模板画廊
-    build_gal = base_dir / "scripts" / "build-gallery.py"
+    build_gal = base_dir / "scripts" / "build" / "build-gallery.py"
     run_command(f"python3 {build_gal}", base_dir, "Building HTML Template Gallery")
 
     # 5. 编译 TypeScript CLI 产物
     run_command("npm run build", base_dir, "Compiling TypeScript CLI (tsc -> dist/)")
 
     # 6. 运行全链路自动化测试套件
-    test_script = base_dir / "scripts" / "run-all-tests.py"
-    run_command(f"python3 {test_script}", base_dir, "Running Full-Chain Test Suites (21/21)")
+    test_script = base_dir / "scripts" / "build" / "run-all-tests.py"
+    run_command(f"python3 {test_script}", base_dir, "Running Full-Chain Test Suites")
 
     # 7. NPM 打包预检 (npm pack --dry-run)
     pack_output = run_command("npm pack --dry-run --json", base_dir, "Inspecting NPM Package Files")
@@ -71,8 +79,8 @@ def main():
     try:
         pack_data = json.loads(pack_output)
         if isinstance(pack_data, list) and len(pack_data) > 0:
-            files_count = pack_data[0].get("entryCount", "N/A")
-            unpacked_size = pack_data[0].get("unpackedSize", "N/A")
+            files_count = pack_data[0].get("entryCount", 0)
+            unpacked_size = pack_data[0].get("unpackedSize", 0)
             print(f"\n[📦 NPM Package Stats]: {files_count} files included, Unpacked Size: ~{round(unpacked_size / 1024, 1)} KB")
     except:
         pass
@@ -80,7 +88,7 @@ def main():
     # 8. 发布执行或指引
     print("\n" + "=" * 62)
     print(f"  [✓] Release Preparation for v{target_version} Completed!")
-    print("=" * 62)
+    print("==============================================================")
 
     if args.publish:
         print("\n[🚀 Triggering NPM Publish...]")
@@ -88,13 +96,9 @@ def main():
         print(f"\n🎉 Successfully published knowme-careerforge-skill@v{target_version} to NPM!")
     else:
         print("\nNext steps to publish your package to NPM:")
-        print("  1. Review Git status and commit changes:")
-        print(f"     git add . && git commit -m \"chore(release): bump version to v{target_version}\"")
-        print(f"     git tag v{target_version} && git push origin main --tags")
-        print("\n  2. Publish to NPM registry:")
-        print("     npm publish --access public")
-        print("\n  3. Verify on NPM:")
-        print(f"     npm view knowme-careerforge-skill@v{target_version}")
+        print(f"  1. Review packaged assets and git status.")
+        print(f"  2. Run: npm publish --access public\n")
+        print(f"  3. Verify with:")
         print(f"     npx knowme-careerforge-skill@{target_version} list\n")
 
 if __name__ == "__main__":

package/scripts/{run-all-tests.py → build/run-all-tests.py}

@@ -7,9 +7,17 @@ KnowMe CareerForge — Unified Full-Chain Test Runner
 import os, sys, unittest, time
 from pathlib import Path
 
+def get_project_root() -> Path:
+    curr = Path(__file__).resolve().parent
+    for _ in range(5):
+        if (curr / "SKILL.md").exists() or (curr / "package.json").exists():
+            return curr
+        curr = curr.parent
+    return Path.cwd()
+
 def run_all_test_suites():
     start_time = time.time()
-    base_dir = Path(__file__).resolve().parent.parent
+    base_dir = get_project_root()
     tests_dir = base_dir / "tests"
 
     print("==============================================================")