@yottameta/yotta-dev-mcp-plugin 0.2.0 → 0.2.1

package/.agents/plugins/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
       "interface": {
         "displayName": "元开 yotta-dev-mcp",

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Developer Tools",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
       "interface": {
         "displayName": "元开 yotta-dev-mcp",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-dev-mcp-plugin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "YuanKai (yotta-dev-mcp) Agent Plugin: deterministic local development tools over stdio MCP.",
   "license": "MIT",
   "repository": {

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "yotta-dev-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "YuanKai (yotta-dev-mcp) - deterministic local development tools exposed over stdio MCP: repo_map, system_model, architecture_review, impact_analysis, verify_change, self_test, run_adapter, find_code, compress_output, review_code, review_diff, mcp_doctor, scan_secrets, scan_dependencies, check_publish_readiness, run_checks, scaffold_skill and workflow_state. Reads an optional .yotta/architecture.json contract plus .yotta/verification.json policy for architecture reviews, change impact cones and the L0-L5 evidence ledger. Optional explicit adapters integrate import-linter, dependency-cruiser and Repomix without auto-install or network access. Python 3.8+ standard library, offline by default; writes and command execution require explicit flags.",
   "author": {
     "name": "YottaMeta",

package/skills/yotta-dev-mcp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-dev-mcp
 description: 元开（yotta-dev-mcp）—— 本地、确定性的开发工具 MCP，把只读默认的开发能力暴露为 stdio MCP server：repo_map / system_model / architecture_review / impact_analysis / verify_change / self_test / run_adapter / find_code / compress_output / review_code / review_diff / mcp_doctor / scan_secrets / scan_dependencies / check_publish_readiness / run_checks / scaffold_skill / workflow_state。触发：让 AI 在陌生项目里先做结构盘点、构建系统模型或架构契约（.yotta/architecture.json）、按契约评审架构、分析改动影响锥与回归面、按验证阶梯产出证据账本、对元开自身做完整性 / 反证自测、探测或显式运行 import-linter / dependency-cruiser / Repomix 可选适配器、定位代码、评审改动、扫描密钥/依赖、检查发布就绪、运行白名单检查、生成脚手架或读取 .workflow 状态时；或用户说 元开 / 开发能力 MCP / yotta-dev-mcp / 代码库地图 / 系统模型 / 架构契约 / 架构评审 / 影响分析 / 验证账本 / 反证自测 / 代码评审 MCP / 适配器 等。边界：Python 3.8+ 标准库、离线默认；除 run_checks（显式 allow_execute）、verify_change 的 L2-L4 策略检查（显式 allow_execute）与 self_test 的测试子集（显式 allow_execute）、run_adapter 的 action=run（显式 allow_execute）、scaffold_skill / workflow_state 的显式 apply 外均为只读；不上传源码、不自动修改、不提交、不联网查询包是否存在、不自动安装或下载适配器。
-version: 0.2.0
+version: 0.2.1
 license: MIT
 ---
 
@@ -45,7 +45,7 @@ python scripts/yotta_dev_mcp.py
 
 | 工具 | 用途 | 写入 |
 |---|---|---|
-| `repo_map` | 模块、导入、入口点地图 | 否 |
+| `repo_map` | 模块、导入、入口点地图；支持 `from . import X` / 别名 / 包，忽略临时与探针目录 | 否 |
 | `system_model` | 系统模型：模块、依赖、入口、测试映射、配置与数据归属；附带契约分层，输出 PASS / FAIL / UNKNOWN | 否 |
 | `architecture_review` | 按契约评审依赖规则、边界可见性与数据归属；critical / high 判 FAIL，medium / low 只告警 | 否 |
 | `impact_analysis` | 变更影响锥：直接消费者、受影响层 / 边界 / 存储 / 不变量、映射测试、风险分级与回滚探针 | 否 |
@@ -54,10 +54,10 @@ python scripts/yotta_dev_mcp.py
 | `run_adapter` | 探测或显式运行 import-linter / dependency-cruiser / Repomix；固定 argv、项目内 cwd、有界输出与哈希 | 仅 action=run + 显式 allow_execute |
 | `find_code` | 符号 / 文本定位，结果有上限 | 否 |
 | `compress_output` | 保留错误与首尾的长输出压缩 | 否 |
-| `review_code` | 规则化代码评审，带行号与建议 | 否 |
+| `review_code` | 规则化代码评审，带行号与建议；忽略 `.workflow` / `scratch` / `_probe` 等临时目录 | 否 |
 | `review_diff` | 只评审 diff 的新增行 | 否 |
-| `mcp_doctor` | 技能版本与 MCP JSON 配置体检 | 否 |
-| `scan_secrets` | 密钥 / 凭据 / 高熵令牌扫描（强制脱敏） | 否 |
+| `mcp_doctor` | 技能版本与多宿主 MCP 配置体检；返回 coverage，只列 server 名，不含 command / env | 否 |
+| `scan_secrets` | 密钥 / 凭据 / 高熵令牌扫描（强制脱敏；路径 / 哈希 / 文件名噪声过滤） | 否 |
 | `scan_dependencies` | 依赖清单、lockfile、来源与 typosquat 启发式检查 | 否 |
 | `check_publish_readiness` | 版本四件、发布文件、仓库与 publishConfig 检查 | 否 |
 | `run_checks` | 白名单测试 / lint / compile 并返回结构化摘要 | 仅显式 allow_execute |
@@ -77,5 +77,6 @@ python scripts/yotta_dev_mcp.py
 
 ## 当前版本
 
+- v0.2.1（2026-09-25）：缺陷修复批次——`mcp_doctor` 改为多宿主 / 多根 / JSON+JSONC+TOML 子集发现并返回 coverage；`self_test(mode="installed")` 按精简分发副本 / npm / plugin / r0 形态判断 banner；`repo_map` 修复 `from . import X` 解析；`scan_secrets` 过滤路径 / 哈希 / 文件名噪声；`review_code` / `repo_map` 忽略 `.workflow` / `scratch` / `_probe` 等临时目录。
 - v0.2.0（2026-09-25）：新增 `system_model`、`architecture_review`、`impact_analysis`、`verify_change`、`self_test`、`run_adapter`，以及 `.yotta/architecture.json` 与可选 `.yotta/verification.json` 契约（版本 1）；工具总数 18，原 12 个工具行为不变。
 - v0.1.1：品牌显示名统一为「元开」；功能与 12 个工具不变。

package/skills/yotta-dev-mcp/references/tools.md

@@ -14,6 +14,12 @@ Input:
 
 Output: `root`, `modules`, `imports`, `entrypoints`, `truncated`.
 
+Python imports include absolute, `from .X import Y`, `from . import X`,
+`as` aliases, packages and multi-name forms. Temporary / agent-state
+directories (`.workflow`, `.codex`, `.cursor`, `.claude`, `.agents`,
+`scratch`, `_probe`, `probe`, `sandbox`, `debug`, `.tmp`) and probe/temp
+file names are ignored by default.
+
 ## system_model
 
 Input:
@@ -201,14 +207,36 @@ Input:
 
 Only added lines are reviewed. Output: `files`, `findings`, `truncated`.
 
+`review_code` uses the same default ignore set as `repo_map`: agent state
+directories, scratch / probe / sandbox / debug directories and probe/temp
+file names do not flood the result. `review_diff` only reviews added lines,
+so it is unaffected by directory traversal.
+
 ## mcp_doctor
 
 Input:
 
 - `skills_dirs` (optional array).
 - `config_paths` (optional array).
-
-Output: `skills`, `mcp_configs`, `issues`, `checked_skills`, `checked_configs`.
+- `include_defaults` (optional boolean): when `config_paths` is supplied, also
+  scan the built-in host registry instead of explicit-only scope.
+
+Output: `skills`, `mcp_configs`, `coverage`, `skills_coverage`, `issues`,
+`coverage_gaps`, `unknown_hosts`, `summary`, `scope`, `checked_skills`,
+`checked_configs`, `checked_hosts`.
+
+Discovery is tiered and environment-aware: verified hosts include Codex
+(`$CODEX_HOME/config.toml`, JSON fallbacks), Cursor, WorkBuddy
+(`~/.workbuddy/mcp.json` plus `connectors/*/mcp.json`), OpenCode
+(`$XDG_CONFIG_HOME/opencode/opencode.jsonc|json`), Claude Code, Windsurf,
+Continue, Gemini, Qwen, Trae, Comate, CodeBuddy, Kimi, Kiro, VS Code and Zed;
+additional hosts are best-effort candidates and are reported as
+`unverified` when absent. JSON, JSONC and a narrow TOML `[mcp_servers.*]`
+subset are parsed; YAML is reported as `unsupported`, never silently skipped.
+Only server names are returned; commands, args and env values are never
+included. `summary.all_clear` is true only for a fully covered, issue-free
+default scan; always read `coverage_confidence` before treating it as
+all-clear.
 
 ## scan_secrets
 
@@ -218,6 +246,11 @@ Input: `path` or `text`, optional `max_findings`, optional `include_git_history`
 Output: `findings` with `path`, `line`, `rule`, `severity`, redacted `evidence`,
 `suggestion`; `truncated`.
 
+High-entropy findings apply a narrow noise filter for absolute paths,
+URL / `file://` percent-encoded paths, common binary/source/document
+suffixes and hash-context hex values (SHA-1/256/512, MD5, checksum, digest,
+integrity). Credential-name, AWS-key and private-key rules are not relaxed.
+
 ## scan_dependencies
 
 Input: `path`.

package/skills/yotta-dev-mcp/scripts/dev_common.py

@@ -10,7 +10,14 @@ from pathlib import Path
 IGNORE_DIRS = {
     ".git", ".hg", ".svn", "node_modules", "__pycache__", ".venv", "venv",
     "dist", "build", ".next", ".nuxt", ".cache", ".tmp", ".tmp2",
+    ".workflow", ".codex", ".cursor", ".claude", ".agents",
+    "scratch", "_scratch", "_probe", "probe", "probes",
+    "sandbox", ".sandbox", "debug", "_debug",
 }
+IGNORE_TEMP_FILE_RE = re.compile(
+    r"(?i)^(?:probe[_-].*|_probe[_-].*|scratch[_-].*|_scratch[_-].*|tmp_.*|temp_.*|.*_tmp)"
+    r"\.(?:py|js|jsx|mjs|cjs|ts|tsx|sh|ps1|go|rs|java|kt|kts|rb|php)$"
+)
 SOURCE_EXTS = {
     ".py", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".sh", ".ps1",
     ".go", ".rs", ".java", ".kt", ".kts", ".rb", ".php",
@@ -54,7 +61,9 @@ VERIFY_REQUIRED_SOURCE_FILES = (
     "references/tools.md", "references/adapters.md",
     "references/architecture-contract.md", "assets/banner.png",
 )
-VERIFY_REQUIRED_INSTALLED_FILES = ("SKILL.md", "assets/banner.png")
+VERIFY_REQUIRED_INSTALLED_FILES = ("SKILL.md",)
+VERIFY_REQUIRED_INSTALLED_ASSETS = ("assets/banner.png",)
+LEAN_INSTALL_MARKERS = ("_icon.png",)
 VERIFY_WRITE_GATES = (
     ("run_checks", "allow_execute"),
     ("scaffold_skill", "apply"),
@@ -94,13 +103,15 @@ def _read_text(path):
     return data.decode("utf-8", errors="replace")
 
 
-def _iter_files(root, extensions=None, max_files=5000, all_files=False):
+def _iter_files(root, extensions=None, max_files=5000, all_files=False, ignore_temp=True):
     root = Path(root)
     extensions = set(extensions or TEXT_EXTS)
     count = 0
     for current, dirs, files in os.walk(str(root)):
         dirs[:] = sorted(d for d in dirs if d not in IGNORE_DIRS)
         for name in sorted(files):
+            if ignore_temp and IGNORE_TEMP_FILE_RE.match(name):
+                continue
             path = Path(current) / name
             if path.is_symlink():
                 continue

package/skills/yotta-dev-mcp/scripts/dev_engine.py

@@ -26,12 +26,22 @@ from dev_common import (
     _frontmatter_name, _frontmatter_version, source_exts,
 )
 from dev_impact import impact_analysis as _impact_analysis_impl
+from dev_mcp_doctor import (
+    default_config_paths as _default_config_paths_impl,
+    default_skill_dirs as _default_skill_dirs_impl,
+    mcp_doctor as _mcp_doctor_impl,
+)
 from dev_verify import verify_change as _verify_change_impl
 from dev_selftest import self_test
-from dev_model import _repo_map_js, _repo_map_python, system_model as _system_model_impl
+from dev_model import (
+    _classify_python_import,
+    _repo_map_js,
+    _repo_map_python,
+    system_model as _system_model_impl,
+)
 from dev_rules import REVIEW_RULES
 
-VERSION = "0.2.0"
+VERSION = "0.2.1"
 
 
 
@@ -54,6 +64,7 @@ def repo_map(path, max_files=2000):
     if len(files) > max_files:
         truncated = True
         files = files[:max_files]
+    module_set = {_rel(root, file_path) for file_path in files}
     for file_path in files:
         rel = _rel(root, file_path)
         try:
@@ -63,7 +74,11 @@ def repo_map(path, max_files=2000):
         language = _language(file_path)
         modules.append({"path": rel, "language": language, "lines": len(text.splitlines())})
         if file_path.suffix.lower() == ".py":
-            imports.extend(_repo_map_python(file_path, rel))
+            for raw in _repo_map_python(file_path, rel):
+                _, target = _classify_python_import(
+                    raw["target"], rel, module_set, relative=raw.get("relative", False)
+                )
+                imports.append({"source": rel, "target": target, "line": raw["line"]})
         elif file_path.suffix.lower() in (".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx"):
             imports.extend(_repo_map_js(file_path, rel))
         if (
@@ -274,81 +289,19 @@ def review_diff(diff_text=None, path=None, base=None, max_findings=200):
 
 
 def _default_skill_dirs():
-    home = Path.home()
-    candidates = [
-        home / ".codex" / "skills",
-        home / ".claude" / "skills",
-        home / ".cursor" / "skills",
-        home / ".config" / "opencode" / "skills",
-    ]
-    codex_home = os.environ.get("CODEX_HOME")
-    if codex_home:
-        candidates.insert(0, Path(codex_home) / "skills")
-    claude_home = os.environ.get("CLAUDE_CONFIG_DIR")
-    if claude_home:
-        candidates.insert(0, Path(claude_home) / "skills")
-    xdg_home = os.environ.get("XDG_CONFIG_HOME")
-    if xdg_home:
-        candidates.insert(0, Path(xdg_home) / "opencode" / "skills")
-    return candidates
+    return _default_skill_dirs_impl()
 
 
 def _default_config_paths():
-    home = Path.home()
-    return [
-        home / ".codex" / "config.json",
-        home / ".codex" / "mcp.json",
-        home / ".config" / "opencode" / "opencode.json",
-        home / ".claude" / "settings.json",
-        home / ".cursor" / "mcp.json",
-    ]
-
-
-def mcp_doctor(skills_dirs=None, config_paths=None):
-    skills = []
-    issues = []
-    for directory in (skills_dirs or _default_skill_dirs()):
-        root = Path(directory)
-        if not root.is_dir():
-            continue
-        for child in sorted(root.iterdir(), key=lambda item: item.name):
-            skill_file = child / "SKILL.md"
-            if not child.is_dir() or not skill_file.is_file():
-                continue
-            try:
-                text = _read_text(skill_file)
-            except (OSError, ValueError) as exc:
-                issues.append("%s: %s" % (skill_file, exc))
-                continue
-            skills.append({
-                "name": _frontmatter_name(text) or child.name,
-                "version": _frontmatter_version(text),
-                "path": str(skill_file),
-            })
-    mcp_configs = []
-    for config_path in (config_paths or _default_config_paths()):
-        path = Path(config_path)
-        if not path.is_file():
-            continue
-        try:
-            payload = json.loads(_read_text(path))
-        except Exception as exc:  # noqa: BLE001
-            issues.append("%s: %s" % (path, exc))
-            continue
-        servers = payload.get("mcpServers") if isinstance(payload, dict) else None
-        mcp_configs.append({
-            "path": str(path),
-            "servers": sorted(servers.keys()) if isinstance(servers, dict) else [],
-        })
-    skills.sort(key=lambda item: (item["name"], item["path"]))
-    mcp_configs.sort(key=lambda item: item["path"])
-    return {
-        "skills": skills,
-        "mcp_configs": mcp_configs,
-        "issues": issues,
-        "checked_skills": len(skills),
-        "checked_configs": len(mcp_configs),
-    }
+    return _default_config_paths_impl()
+
+
+def mcp_doctor(skills_dirs=None, config_paths=None, include_defaults=None):
+    return _mcp_doctor_impl(
+        skills_dirs=skills_dirs,
+        config_paths=config_paths,
+        include_defaults=include_defaults,
+    )
 
 
 SECRET_KEY_RE = re.compile(
@@ -357,6 +310,35 @@ SECRET_KEY_RE = re.compile(
 AWS_KEY_RE = re.compile(r"\bAKIA[0-9A-Z]{16}\b")
 PRIVATE_KEY_RE = re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----")
 HIGH_ENTROPY_RE = re.compile(r"[A-Za-z0-9_+/=\-]{32,}")
+HASH_CONTEXT_RE = re.compile(r"(?i)(sha1|sha256|sha512|hash|checksum|digest|integrity)")
+HEX_TOKEN_RE = re.compile(r"^[0-9a-fA-F]+$")
+PATH_HINT_RE = re.compile(r"(?i)(?:[a-z]:[\\/]|\\\\|https?://|file://)")
+URL_HINT_RE = re.compile(r"(?i)(?:file|https?)://")
+PERCENT_ESCAPE_RE = re.compile(r"%[0-9A-Fa-f]{2}")
+HASH_PREFIX_RE = re.compile(r"(?i)^(?:sha1|sha256|sha512|md5)[=:]([0-9a-fA-F]{32,128})$")
+FILE_SUFFIX_RE = re.compile(
+    r"(?i)\.(exe|dll|sys|py|js|ts|tsx|json|md|txt|log|whl|tar|gz|zip|png|jpg|jpeg|svg)"
+)
+
+
+def _high_entropy_noise(line, token, start, end):
+    """Return True for common non-secret high-entropy noise."""
+    if HASH_PREFIX_RE.match(token):
+        return True
+    if PERCENT_ESCAPE_RE.search(token) and URL_HINT_RE.search(line):
+        return True
+    if start > 0 and line[start - 1] == "%":
+        return True
+    if HEX_TOKEN_RE.match(token) and len(token) in (32, 40, 64, 128) and HASH_CONTEXT_RE.search(line):
+        return True
+    window = line[max(0, start - 16):min(len(line), end + 16)]
+    if PATH_HINT_RE.search(window):
+        return True
+    if URL_HINT_RE.search(line) and PERCENT_ESCAPE_RE.search(window):
+        return True
+    if FILE_SUFFIX_RE.match(line[end:end + 8]):
+        return True
+    return False
 
 
 def _entropy(value):
@@ -385,7 +367,9 @@ def scan_secrets(path=None, text=None, max_findings=200, include_git_history=Fal
         root = Path(path)
         if not root.exists():
             raise ValueError("路径不存在: %s" % path)
-        files = [root] if root.is_file() else list(_iter_files(root, all_files=True))
+        files = [root] if root.is_file() else list(
+            _iter_files(root, all_files=True, ignore_temp=False)
+        )
         base = root.parent if root.is_file() else root
         for file_path in files:
             try:
@@ -421,7 +405,11 @@ def scan_secrets(path=None, text=None, max_findings=200, include_git_history=Fal
                 })
             for match in HIGH_ENTROPY_RE.finditer(line):
                 token = match.group(0)
-                if _entropy(token) >= 4.0 and not PRIVATE_KEY_RE.search(line):
+                if (
+                    _entropy(token) >= 4.0
+                    and not PRIVATE_KEY_RE.search(line)
+                    and not _high_entropy_noise(line, token, match.start(), match.end())
+                ):
                     findings.append({
                         "path": rel, "line": line_no, "rule": "high-entropy-token",
                         "severity": "medium", "evidence": _redact(token),
@@ -1083,6 +1071,8 @@ def main():
     doctor = sub.add_parser("mcp-doctor")
     doctor.add_argument("--skills-dir", action="append")
     doctor.add_argument("--config", action="append")
+    doctor.add_argument("--include-defaults", action="store_true",
+                        help="scan built-in host registry in addition to --config paths")
     args = parser.parse_args()
     if args.command == "repo-map":
         result = repo_map(args.path)
@@ -1126,7 +1116,11 @@ def main():
     elif args.command == "review-code":
         result = review_code(args.path)
     elif args.command == "mcp-doctor":
-        result = mcp_doctor(skills_dirs=args.skills_dir, config_paths=args.config)
+        result = mcp_doctor(
+            skills_dirs=args.skills_dir,
+            config_paths=args.config,
+            include_defaults=args.include_defaults,
+        )
     else:
         parser.print_help()
         return 2

package/skills/yotta-dev-mcp/scripts/dev_mcp_doctor.py

@@ -0,0 +1,768 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""Broad, read-only MCP client config discovery for mcp_doctor.
+
+The module deliberately separates discovery from parsing:
+
+* a declarative host registry describes candidate paths, formats and keys;
+* parsers only extract server names (never commands, args or env values);
+* every registry entry appears in a coverage report, so a caller can never
+  mistake "the one file I happened to parse" for "all configs are healthy".
+
+Python 3.8+ standard library only. No network, no writes.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import glob
+import json
+import os
+import re
+from pathlib import Path
+
+from dev_common import _frontmatter_name, _frontmatter_version, _read_text
+
+VERSION = 1
+DEFAULT_MAX_CONFIG_BYTES = 2_000_000
+DEFAULT_MAX_CONFIGS = 500
+DEFAULT_MAX_SKILL_DIRS = 120
+
+DEFAULT_JSON_KEYS = ("mcpServers", "mcp", "servers", "context_servers")
+DEFAULT_TOML_KEYS = ("mcp_servers",)
+
+
+def _host(host_id, label, candidates, formats=("json",), server_keys=None,
+          tier="verified", note="", exclude=()):
+    return {
+        "id": host_id,
+        "label": label,
+        "candidates": list(candidates),
+        "formats": list(formats),
+        "server_keys": list(server_keys or DEFAULT_JSON_KEYS),
+        "tier": tier,
+        "note": note,
+        "exclude": list(exclude),
+    }
+
+
+def _builtin_hosts():
+    """A broad, tiered registry.
+
+    ``verified`` means the path/format is documented or directly observed.
+    ``unverified`` means the path is a best-effort candidate: if it exists it
+    is parsed, but a missing file is reported as a coverage gap instead of
+    being silently treated as "not installed".
+    """
+    return [
+        _host(
+            "codex", "Codex",
+            [
+                "{codex_home}/config.toml",
+                "{home}/.codex/config.toml",
+                "{codex_home}/config.json",
+                "{codex_home}/mcp.json",
+                "{home}/.codex/config.json",
+                "{home}/.codex/mcp.json",
+            ],
+            formats=("toml", "json"),
+            server_keys=("mcp_servers",) + DEFAULT_JSON_KEYS,
+        ),
+        _host(
+            "claude-code", "Claude Code",
+            [
+                "{claude_config_dir}/settings.json",
+                "{home}/.claude/settings.json",
+                "{home}/.claude.json",
+                "{cwd}/.mcp.json",
+            ],
+        ),
+        _host(
+            "cursor", "Cursor",
+            ["{home}/.cursor/mcp.json", "{cwd}/.cursor/mcp.json"],
+        ),
+        _host(
+            "opencode", "OpenCode",
+            [
+                "{xdg_config_home}/opencode/opencode.jsonc",
+                "{xdg_config_home}/opencode/opencode.json",
+                "{home}/.config/opencode/opencode.jsonc",
+                "{home}/.config/opencode/opencode.json",
+                "{cwd}/opencode.jsonc",
+                "{cwd}/opencode.json",
+            ],
+            formats=("jsonc", "json"),
+            server_keys=("mcp", "mcpServers", "servers"),
+        ),
+        _host(
+            "workbuddy", "WorkBuddy",
+            [
+                "{home}/.workbuddy/mcp.json",
+                "{home}/.workbuddy/connectors/*/mcp.json",
+            ],
+            exclude=("**/connectors-marketplace/**",),
+        ),
+        _host(
+            "windsurf", "Windsurf",
+            [
+                "{home}/.codeium/windsurf/mcp_config.json",
+                "{home}/.codeium/windsurf/mcp.json",
+            ],
+        ),
+        _host(
+            "continue", "Continue",
+            ["{home}/.continue/config.json", "{home}/.continue/config.yaml"],
+            formats=("json", "yaml"),
+        ),
+        _host(
+            "gemini", "Gemini CLI",
+            ["{home}/.gemini/settings.json", "{home}/.gemini/mcp.json"],
+        ),
+        _host(
+            "qwen", "Qwen Code",
+            ["{home}/.qwen/settings.json", "{home}/.qwen/mcp.json"],
+        ),
+        _host(
+            "trae", "Trae Code CLI",
+            ["{home}/.traecli/mcp.json", "{home}/.trae/mcp.json"],
+        ),
+        _host(
+            "trae-cn", "Trae IDE",
+            ["{home}/.trae-cn/mcp.json"],
+        ),
+        _host(
+            "comate", "Comate",
+            ["{home}/.comate/mcp.json", "{home}/.comate/settings.json"],
+        ),
+        _host(
+            "codebuddy", "CodeBuddy Code",
+            ["{home}/.codebuddy/mcp.json", "{home}/.codebuddy/settings.json"],
+        ),
+        _host(
+            "kimi", "Kimi Code CLI",
+            ["{home}/.kimi/mcp.json", "{home}/.kimi/settings.json"],
+        ),
+        _host(
+            "kiro", "Kiro",
+            ["{home}/.kiro/mcp.json", "{home}/.kiro/settings.json"],
+        ),
+        _host(
+            "vscode", "VS Code",
+            [
+                "{cwd}/.vscode/mcp.json",
+                "{env:APPDATA}/Code/User/mcp.json",
+                "{xdg_config_home}/Code/User/mcp.json",
+            ],
+        ),
+        _host(
+            "zed", "Zed",
+            [
+                "{xdg_config_home}/zed/settings.json",
+                "{home}/.config/zed/settings.json",
+            ],
+            server_keys=("context_servers", "mcpServers", "mcp", "servers"),
+        ),
+        _host(
+            "goose", "Goose",
+            ["{xdg_config_home}/goose/config.yaml", "{home}/.config/goose/config.yaml"],
+            formats=("yaml",),
+            note="Goose YAML is reported as unsupported, never silently skipped.",
+        ),
+        # The following paths are useful best-effort candidates but are not
+        # claimed as verified. If they are missing they show up as coverage
+        # gaps, which keeps "all_clear" honest.
+        _host("cline", "Cline", ["{home}/.cline/mcp.json", "{home}/.config/cline/mcp.json"], tier="unverified"),
+        _host("roo-code", "Roo Code", ["{home}/.roo/mcp.json", "{home}/.config/roo/mcp.json"], tier="unverified"),
+        _host("amp", "Amp", ["{home}/.config/amp/settings.json"], tier="unverified"),
+        _host("lm-studio", "LM Studio", ["{home}/.lmstudio/mcp.json", "{home}/.cache/lm-studio/mcp.json"], tier="unverified"),
+        _host("jetbrains", "JetBrains", ["{cwd}/.idea/mcp.json", "{home}/.config/JetBrains/*/mcp.json"], tier="unverified"),
+        _host("warp", "Warp", ["{home}/.warp/mcp.json"], tier="unverified"),
+        _host("5ire", "5ire", ["{home}/.5ire/mcp.json"], tier="unverified"),
+        _host("witsy", "Witsy", ["{home}/.witsy/mcp.json"], tier="unverified"),
+        _host("enconvo", "Enconvo", ["{home}/.enconvo/mcp.json"], tier="unverified"),
+        _host("chatwise", "ChatWise", ["{home}/.chatwise/mcp.json"], tier="unverified"),
+        _host("jan", "Jan", ["{home}/.jan/mcp.json"], tier="unverified"),
+        _host("msty", "Msty", ["{home}/.msty/mcp.json"], tier="unverified"),
+        _host("boltai", "BoltAI", ["{home}/.boltai/mcp.json"], tier="unverified"),
+        _host("copilot-cli", "GitHub Copilot CLI", ["{home}/.copilot/mcp-config.json"], tier="unverified"),
+        _host("factory-droid", "Factory Droid", ["{home}/.factory/mcp.json"], tier="unverified"),
+        _host("qoder", "Qoder", ["{home}/.qoder/mcp.json"], tier="unverified"),
+        _host("lingma", "Lingma", ["{home}/.lingma/mcp.json"], tier="unverified"),
+        # Hosts with no verified config path are still surfaced as named gaps.
+        _host("windsurf-cascade", "Windsurf Cascade", [], tier="unverified",
+              note="config path not verified; use config_paths to add it explicitly"),
+        _host("cursor-cli", "Cursor CLI", [], tier="unverified",
+              note="config path not verified; Cursor desktop config is covered by the cursor host"),
+    ]
+
+
+def _builtin_skill_hosts():
+    """Skill directories aligned with the installer host map."""
+    return [
+        _host("codex", "Codex", ["{codex_home}/skills", "{home}/.codex/skills"]),
+        _host("claude", "Claude Code", ["{claude_config_dir}/skills", "{home}/.claude/skills"]),
+        _host("cursor", "Cursor", ["{home}/.cursor/skills", "{home}/.agents/skills"]),
+        _host("opencode", "OpenCode", ["{xdg_config_home}/opencode/skills", "{home}/.config/opencode/skills"]),
+        _host("gemini", "Gemini CLI", ["{home}/.gemini/skills", "{home}/.agents/skills"]),
+        _host("goose", "Goose", ["{home}/.config/goose/skills", "{home}/.agents/skills"]),
+        _host("amp", "Amp", ["{home}/.config/agents/skills", "{home}/.agents/skills"]),
+        _host("windsurf", "Windsurf", ["{home}/.codeium/windsurf/skills"]),
+        _host("workbuddy", "WorkBuddy", ["{home}/.workbuddy/skills"]),
+        _host("kiro", "Kiro", ["{home}/.kiro/skills"]),
+        _host("trae", "Trae Code CLI", ["{home}/.traecli/skills"]),
+        _host("trae-cn", "Trae IDE", ["{home}/.trae-cn/skills"]),
+        _host("qwen", "Qwen Code", ["{home}/.qwen/skills"]),
+        _host("comate", "Comate", ["{home}/.comate/skills"]),
+        _host("codebuddy", "CodeBuddy Code", ["{home}/.codebuddy/skills"]),
+        _host("kimi", "Kimi Code CLI", ["{home}/.kimi/skills"]),
+        _host("agents", "AGENTS.md", ["{home}/.agents/skills"]),
+    ]
+
+
+def _environment(environ, home):
+    env = dict(environ or {})
+    return {
+        "home": str(home),
+        "cwd": "",
+        "codex_home": env.get("CODEX_HOME") or str(Path(home) / ".codex"),
+        "xdg_config_home": env.get("XDG_CONFIG_HOME") or str(Path(home) / ".config"),
+        "claude_config_dir": env.get("CLAUDE_CONFIG_DIR") or str(Path(home) / ".claude"),
+        "environ": env,
+    }
+
+
+def _expand_candidate(pattern, home, cwd, environ):
+    roots = [Path(home)]
+    for name in ("USERPROFILE", "HOME"):
+        value = environ.get(name) if environ else None
+        if not value:
+            continue
+        candidate = Path(value)
+        if _normalise_path(candidate) not in {_normalise_path(item) for item in roots}:
+            roots.append(candidate)
+
+    results = []
+    skipped = None
+    for root in roots:
+        values = _environment(environ, root)
+        values["cwd"] = str(cwd)
+
+        def replace(match, values=values):
+            token = match.group(1)
+            if token in values and token != "environ":
+                return values[token]
+            if token.startswith("env:"):
+                return values["environ"].get(token[4:], "")
+            return match.group(0)
+
+        expanded = re.sub(r"\{([^{}]+)\}", replace, pattern)
+        if re.search(r"\{[^{}]+\}", expanded):
+            skipped = "unresolved-placeholder:" + pattern
+            continue
+        if any(char in expanded for char in "*?["):
+            results.extend(Path(item) for item in glob.glob(expanded, recursive=True))
+        else:
+            results.append(Path(expanded))
+    if not results and skipped:
+        return [], skipped
+    return sorted(set(results), key=lambda item: _normalise_path(item)), None
+
+
+def _normalise_path(path):
+    try:
+        return str(Path(path).resolve())
+    except OSError:
+        return str(path)
+
+
+def _excluded(path, patterns):
+    text = str(path).replace("\\", "/")
+    return any(fnmatch.fnmatch(text, pattern.replace("\\", "/")) for pattern in patterns)
+
+
+def _strip_jsonc_comments(text):
+    out = []
+    index = 0
+    in_string = False
+    quote = ""
+    escaped = False
+    while index < len(text):
+        char = text[index]
+        if in_string:
+            out.append(char)
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == quote:
+                in_string = False
+            index += 1
+            continue
+        if char in ('"', "'"):
+            in_string = True
+            quote = char
+            out.append(char)
+            index += 1
+            continue
+        if char == "/" and index + 1 < len(text) and text[index + 1] == "/":
+            index += 2
+            while index < len(text) and text[index] not in "\r\n":
+                index += 1
+            continue
+        if char == "/" and index + 1 < len(text) and text[index + 1] == "*":
+            index += 2
+            while index + 1 < len(text) and not (text[index] == "*" and text[index + 1] == "/"):
+                index += 1
+            index += 2
+            continue
+        out.append(char)
+        index += 1
+    return "".join(out)
+
+
+def _strip_jsonc_trailing_commas(text):
+    out = []
+    index = 0
+    in_string = False
+    quote = ""
+    escaped = False
+    while index < len(text):
+        char = text[index]
+        if in_string:
+            out.append(char)
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == quote:
+                in_string = False
+            index += 1
+            continue
+        if char in ('"', "'"):
+            in_string = True
+            quote = char
+            out.append(char)
+            index += 1
+            continue
+        if char == ",":
+            lookahead = index + 1
+            while lookahead < len(text) and text[lookahead].isspace():
+                lookahead += 1
+            if lookahead < len(text) and text[lookahead] in "}]":
+                index += 1
+                continue
+        out.append(char)
+        index += 1
+    return "".join(out)
+
+
+def _strip_jsonc(text):
+    return _strip_jsonc_trailing_commas(_strip_jsonc_comments(text))
+
+
+def _collect_json_servers(payload, keys):
+    if not isinstance(payload, dict):
+        return [], "", "top-level-json-value-is-not-an-object"
+    names = set()
+    used = []
+    for key in keys:
+        if key not in payload:
+            continue
+        value = payload.get(key)
+        if not isinstance(value, dict):
+            return [], key, "mcp-key-is-not-an-object"
+        used.append(key)
+        if key == "mcp" and isinstance(value.get("servers"), dict):
+            names.update(str(name) for name in value["servers"].keys())
+        else:
+            names.update(str(name) for name in value.keys())
+    return sorted(names), ",".join(used), None
+
+
+def _parse_toml_servers(text):
+    names = set()
+    section = None
+    inline_value = False
+    saw_root = False
+    header_re = re.compile(
+        r"^\s*\[\s*mcp_servers\s*\.\s*(?:\"([^\"]+)\"|'([^']+)'|([A-Za-z0-9_.-]+))\s*\]\s*(?:#.*)?$"
+    )
+    root_re = re.compile(r"^\s*\[\s*mcp_servers\s*\]\s*(?:#.*)?$")
+    for line in text.splitlines():
+        match = header_re.match(line)
+        if match:
+            names.add(next(group for group in match.groups() if group is not None))
+            section = "child"
+            continue
+        if root_re.match(line):
+            saw_root = True
+            section = "root"
+            continue
+        if section == "root" and re.match(r"^\s*[A-Za-z0-9_.-]+\s*=", line):
+            inline_value = True
+    if inline_value:
+        return [], "mcp_servers", "toml-inline-mcp-servers-not-supported"
+    if names:
+        return sorted(names), "mcp_servers", None
+    if saw_root:
+        return [], "mcp_servers", None
+    return [], "", None
+
+
+def _parse_config(path, fmt, keys, max_bytes):
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        return {"ok": False, "kind": "error", "reason": "%s: %s" % (path, exc)}
+    if size > max_bytes:
+        return {
+            "ok": False,
+            "kind": "unsupported",
+            "reason": "%s: file exceeds max_config_bytes=%d" % (path, max_bytes),
+        }
+    try:
+        text = _read_text(path)
+    except (OSError, ValueError) as exc:
+        return {"ok": False, "kind": "error", "reason": "%s: %s" % (path, exc)}
+    suffix = path.suffix.lower()
+    if fmt in ("yaml", "yml") or suffix in (".yaml", ".yml"):
+        return {"ok": False, "kind": "unsupported", "reason": "%s: yaml-not-supported" % path}
+    if fmt == "toml" or suffix == ".toml":
+        servers, key, reason = _parse_toml_servers(text)
+        if reason:
+            return {"ok": False, "kind": "unsupported", "reason": "%s: %s" % (path, reason)}
+        return {"ok": True, "format": "toml", "key": key, "servers": servers}
+    if fmt == "jsonc" or suffix == ".jsonc":
+        text = _strip_jsonc(text)
+        parse_format = "jsonc"
+    else:
+        parse_format = "json"
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        return {
+            "ok": False,
+            "kind": "error",
+            "reason": "%s: json parse error at line %d column %d: %s" % (
+                path, exc.lineno, exc.colno, exc.msg),
+        }
+    servers, key, reason = _collect_json_servers(payload, keys)
+    if reason:
+        return {"ok": False, "kind": "unsupported", "reason": "%s: %s" % (path, reason)}
+    return {"ok": True, "format": parse_format, "key": key, "servers": servers}
+
+
+def _read_json_array_or_pathsep(value):
+    if not value:
+        return []
+    text = str(value).strip()
+    if text.startswith("["):
+        try:
+            payload = json.loads(text)
+            return [str(item) for item in payload] if isinstance(payload, list) else []
+        except json.JSONDecodeError:
+            return []
+    return [item for item in text.split(os.pathsep) if item]
+
+
+def _custom_hosts(environ, home, cwd):
+    hosts = []
+    registry_path = environ.get("YOTTA_DEV_MCP_CONFIG_REGISTRY")
+    if registry_path:
+        path = Path(registry_path)
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            payload = None
+        if isinstance(payload, dict) and isinstance(payload.get("hosts"), list):
+            for index, item in enumerate(payload["hosts"]):
+                if not isinstance(item, dict) or not item.get("id"):
+                    continue
+                hosts.append(_host(
+                    str(item["id"]),
+                    str(item.get("label") or item["id"]),
+                    [str(value) for value in item.get("candidates", [])],
+                    formats=item.get("formats") or ("json",),
+                    server_keys=item.get("server_keys") or DEFAULT_JSON_KEYS,
+                    tier="custom",
+                    note=str(item.get("note") or "custom-registry"),
+                ))
+    extra = _read_json_array_or_pathsep(environ.get("YOTTA_DEV_MCP_CONFIG_PATHS"))
+    if extra:
+        hosts.append(_host("custom-paths", "Custom config paths", extra, tier="custom",
+                           note="from YOTTA_DEV_MCP_CONFIG_PATHS"))
+    return hosts
+
+
+def _custom_skill_hosts(environ):
+    extra = _read_json_array_or_pathsep(environ.get("YOTTA_DEV_MCP_SKILL_DIRS"))
+    if not extra:
+        return []
+    return [_host("custom-skills", "Custom skill paths", extra, tier="custom",
+                  note="from YOTTA_DEV_MCP_SKILL_DIRS")]
+
+
+def default_config_paths(home=None, cwd=None, environ=None):
+    home = Path(home) if home is not None else Path.home()
+    cwd = Path(cwd) if cwd is not None else Path.cwd()
+    environ = dict(environ if environ is not None else os.environ)
+    paths = []
+    for host in _builtin_hosts():
+        for pattern in host["candidates"]:
+            expanded, _ = _expand_candidate(pattern, home, cwd, environ)
+            paths.extend(expanded)
+    return sorted(set(paths), key=lambda item: str(item))
+
+
+def default_skill_dirs(home=None, cwd=None, environ=None):
+    home = Path(home) if home is not None else Path.home()
+    cwd = Path(cwd) if cwd is not None else Path.cwd()
+    environ = dict(environ if environ is not None else os.environ)
+    paths = []
+    for host in _builtin_skill_hosts():
+        for pattern in host["candidates"]:
+            expanded, _ = _expand_candidate(pattern, home, cwd, environ)
+            paths.extend(expanded)
+    return sorted(set(paths), key=lambda item: str(item))
+
+
+def _scan_skills(hosts, home, cwd, environ, max_skill_dirs):
+    skills = []
+    coverage = []
+    seen = {}
+    for host in hosts:
+        found = []
+        candidate_paths = []
+        skipped = []
+        for pattern in host["candidates"]:
+            expanded, reason = _expand_candidate(pattern, home, cwd, environ)
+            if reason:
+                skipped.append(reason)
+                continue
+            for path in expanded:
+                candidate_paths.append(_normalise_path(path))
+                if path.is_dir():
+                    found.append(path)
+        for root in found[:max_skill_dirs]:
+            try:
+                children = sorted(root.iterdir(), key=lambda item: item.name)
+            except OSError:
+                continue
+            for child in children:
+                skill_file = child / "SKILL.md"
+                if not child.is_dir() or not skill_file.is_file():
+                    continue
+                try:
+                    text = _read_text(skill_file)
+                except (OSError, ValueError):
+                    continue
+                key = _normalise_path(skill_file)
+                entry = seen.get(key)
+                if entry is None:
+                    entry = {
+                        "name": _frontmatter_name(text) or child.name,
+                        "version": _frontmatter_version(text),
+                        "path": key,
+                        "hosts": [host["id"]],
+                    }
+                    seen[key] = entry
+                    skills.append(entry)
+                elif host["id"] not in entry["hosts"]:
+                    entry["hosts"].append(host["id"])
+        if found:
+            status = "checked"
+        elif skipped:
+            status = "missing"
+        elif host["tier"] == "unverified":
+            status = "unverified"
+        else:
+            status = "missing"
+        coverage.append({
+            "host": host["id"],
+            "label": host["label"],
+            "tier": host["tier"],
+            "status": status,
+            "candidate_paths": sorted(set(candidate_paths)),
+            "checked_paths": sorted(set(_normalise_path(path) for path in found)),
+            "count": sum(1 for item in seen.values() if host["id"] in item["hosts"]),
+            "reason": host.get("note", ""),
+        })
+    return skills, coverage
+
+
+def mcp_doctor(skills_dirs=None, config_paths=None, include_defaults=None,
+               home=None, cwd=None, environ=None, max_configs=DEFAULT_MAX_CONFIGS,
+               max_config_bytes=DEFAULT_MAX_CONFIG_BYTES, include_unverified=True):
+    home = Path(home) if home is not None else Path.home()
+    cwd = Path(cwd) if cwd is not None else Path.cwd()
+    environ = dict(environ if environ is not None else os.environ)
+
+    config_scope = "default"
+    skills_scope = "default"
+    default_coverage_skipped = False
+
+    if skills_dirs:
+        skill_hosts = [_host("explicit", "Explicit skill dirs", [str(item) for item in skills_dirs],
+                             tier="custom", note="from skills_dirs")]
+        skills_scope = "explicit"
+    else:
+        skill_hosts = _builtin_skill_hosts() + _custom_skill_hosts(environ)
+
+    if config_paths and include_defaults is not True:
+        hosts = [_host("explicit", "Explicit config paths", [str(item) for item in config_paths],
+                       formats=("json", "jsonc", "toml", "yaml"),
+                       server_keys=DEFAULT_JSON_KEYS + DEFAULT_TOML_KEYS,
+                       tier="custom", note="from config_paths")]
+        config_scope = "explicit"
+        default_coverage_skipped = True
+    else:
+        hosts = _builtin_hosts() + _custom_hosts(environ, home, cwd)
+        if config_paths:
+            hosts.append(_host("explicit", "Explicit config paths",
+                               [str(item) for item in config_paths],
+                               formats=("json", "jsonc", "toml", "yaml"),
+                               server_keys=DEFAULT_JSON_KEYS + DEFAULT_TOML_KEYS,
+                               tier="custom", note="from config_paths"))
+            config_scope = "default+explicit"
+
+    if not include_unverified:
+        hosts = [host for host in hosts if host["tier"] != "unverified"]
+
+    configs = []
+    coverage = []
+    issues = []
+    coverage_gaps = []
+    seen_paths = {}
+    for host in hosts:
+        checked = []
+        unsupported = []
+        errors = []
+        candidate_paths = []
+        skipped = []
+        seen_host_paths = set()
+        for pattern in host["candidates"]:
+            expanded, reason = _expand_candidate(pattern, home, cwd, environ)
+            if reason:
+                skipped.append(reason)
+                continue
+            for path in expanded:
+                if _excluded(path, host.get("exclude", ())):
+                    continue
+                candidate_paths.append(_normalise_path(path))
+                if not path.is_file():
+                    continue
+                normalised = _normalise_path(path)
+                if normalised in seen_host_paths:
+                    continue
+                seen_host_paths.add(normalised)
+                if len(checked) + len(unsupported) + len(errors) >= max_configs:
+                    break
+                formats = host["formats"] or ("json",)
+                selected = formats[0] if len(formats) == 1 else None
+                parsed = _parse_config(path, selected, host["server_keys"], max_config_bytes)
+                if parsed.get("ok"):
+                    item = {
+                        "host": host["id"],
+                        "path": _normalise_path(path),
+                        "format": parsed["format"],
+                        "key": parsed.get("key", ""),
+                        "servers": parsed.get("servers", []),
+                    }
+                    key = item["path"]
+                    existing = seen_paths.get(key)
+                    if existing is None:
+                        seen_paths[key] = item
+                        configs.append(item)
+                    elif host["id"] not in existing.get("also_hosts", []):
+                        existing.setdefault("also_hosts", []).append(host["id"])
+                    checked.append(item)
+                elif parsed.get("kind") == "unsupported":
+                    unsupported.append(parsed["reason"])
+                    issues.append(parsed["reason"])
+                else:
+                    errors.append(parsed["reason"])
+                    issues.append(parsed["reason"])
+        if checked and not unsupported and not errors:
+            status = "checked"
+        elif checked:
+            status = "checked-with-gaps"
+        elif unsupported:
+            status = "unsupported"
+        elif errors:
+            status = "error"
+        elif skipped:
+            status = "missing"
+        elif host["tier"] == "unverified":
+            status = "unverified"
+        else:
+            status = "missing"
+        coverage.append({
+            "host": host["id"],
+            "label": host["label"],
+            "tier": host["tier"],
+            "status": status,
+            "candidate_paths": sorted(set(candidate_paths)),
+            "checked_paths": sorted(set(item["path"] for item in checked)),
+            "unsupported_paths": sorted(set(item.split(":", 1)[0] for item in unsupported)),
+            "error_paths": sorted(set(item.split(":", 1)[0] for item in errors)),
+            "configs": checked,
+            "servers": sorted(set(name for item in checked for name in item["servers"])),
+            "reason": unsupported[0] if unsupported else (errors[0] if errors else host.get("note", "")),
+        })
+        if status == "unverified":
+            coverage_gaps.append("%s: config path/format not verified" % host["id"])
+        if unsupported or errors:
+            coverage_gaps.append("%s: unsupported or unreadable config file(s)" % host["id"])
+        if skipped and host["tier"] in ("unverified", "custom"):
+            coverage_gaps.append("%s: skipped candidates (%s)" % (host["id"], ", ".join(skipped)))
+
+    skills, skills_coverage = _scan_skills(skill_hosts, home, cwd, environ, DEFAULT_MAX_SKILL_DIRS)
+    for entry in skills_coverage:
+        if entry["status"] == "unverified":
+            coverage_gaps.append("skills/%s: skill directory not verified" % entry["host"])
+
+    configs.sort(key=lambda item: item["path"])
+    coverage.sort(key=lambda item: item["host"])
+    skills.sort(key=lambda item: (item["name"], item["path"]))
+    skills_coverage.sort(key=lambda item: item["host"])
+    issues = sorted(set(issues))
+    coverage_gaps = sorted(set(coverage_gaps))
+
+    counts = {
+        "checked_hosts": sum(1 for item in coverage if item["status"].startswith("checked")),
+        "missing_hosts": sum(1 for item in coverage if item["status"] == "missing"),
+        "unsupported_hosts": sum(1 for item in coverage if item["status"] == "unsupported"),
+        "error_hosts": sum(1 for item in coverage if item["status"] == "error"),
+        "unverified_hosts": sum(1 for item in coverage if item["status"] == "unverified"),
+    }
+    unknown_hosts = [item["host"] for item in coverage if item["status"] == "unverified"]
+    checked_scope_clear = not issues and not counts["unsupported_hosts"] and not counts["error_hosts"]
+    full_coverage = not unknown_hosts and config_scope == "default" and not coverage_gaps
+    all_clear = bool(full_coverage and checked_scope_clear)
+    summary = dict(counts)
+    summary.update({
+        "hosts_total": len(coverage),
+        "configs_found": len(configs),
+        "servers_total": len(set(name for item in configs for name in item["servers"])),
+        "all_clear": all_clear,
+        "checked_scope_clear": checked_scope_clear,
+        "full_coverage": full_coverage,
+        "coverage_confidence": "full" if full_coverage else "partial",
+        "issues": len(issues),
+    })
+    return {
+        "skills": skills,
+        "mcp_configs": configs,
+        "coverage": coverage,
+        "skills_coverage": skills_coverage,
+        "unknown_hosts": sorted(unknown_hosts),
+        "coverage_gaps": coverage_gaps,
+        "issues": issues,
+        "summary": summary,
+        "scope": config_scope,
+        "skills_scope": skills_scope,
+        "default_coverage_skipped": default_coverage_skipped,
+        "checked_skills": len(skills),
+        "checked_configs": len(configs),
+        "checked_hosts": counts["checked_hosts"],
+    }

package/skills/yotta-dev-mcp/scripts/dev_model.py

@@ -30,9 +30,14 @@ def _resolve_python_import(source_rel, node):
         if node.level > 1:
             parts = parts[:-(node.level - 1)] if len(parts) >= node.level - 1 else []
         prefix = "/".join(parts)
+        if not node.module:
+            return [
+                (prefix + "/" + alias.name.replace(".", "/")).strip("/")
+                for alias in node.names
+            ]
         module = node.module or ""
         target = (prefix + "/" + module.replace(".", "/")).strip("/")
-        return [target + ".py" if target else source_rel]
+        return [target] if target else [source_rel]
     if node.module:
         return [node.module]
     return []
@@ -47,7 +52,12 @@ def _repo_map_python(path, rel):
     for node in ast.walk(tree):
         if isinstance(node, (ast.Import, ast.ImportFrom)):
             for target in _resolve_python_import(rel, node):
-                imports.append({"source": rel, "target": target, "line": getattr(node, "lineno", 1)})
+                imports.append({
+                    "source": rel,
+                    "target": target,
+                    "line": getattr(node, "lineno", 1),
+                    "relative": isinstance(node, ast.ImportFrom) and bool(node.level),
+                })
     return imports
 
 def _repo_map_js(path, rel):
@@ -77,7 +87,7 @@ def _resolve_relative_module(raw_target, source_rel, module_set, root=None):
         return base, "file"
     return None, None
 
-def _classify_python_import(raw_target, source_rel, module_set):
+def _classify_python_import(raw_target, source_rel, module_set, relative=False):
     if raw_target.endswith(".py"):
         if raw_target in module_set:
             return "internal", raw_target
@@ -91,7 +101,7 @@ def _classify_python_import(raw_target, source_rel, module_set):
         for candidate in (base + ".py", base + "/__init__.py"):
             if candidate in module_set:
                 return "internal", candidate
-    return "external", raw_target
+    return ("unresolved" if relative else "external"), raw_target
 
 def _classify_js_import(raw_target, source_rel, module_set, root=None):
     if raw_target.startswith("."):
@@ -265,19 +275,21 @@ def system_model(path, max_files=2000, contract_file=None):
         suffix = file_path.suffix.lower()
         if suffix == ".py":
             raw_imports = _repo_map_python(file_path, rel)
-            classifier = lambda raw: _classify_python_import(raw, rel, module_set)  # noqa: E731
         elif suffix in JS_EXTS:
             raw_imports = _repo_map_js(file_path, rel)
-            classifier = lambda raw: _classify_js_import(raw, rel, module_set, root)  # noqa: E731
         else:
             raw_imports = []
-            classifier = None
         module_imports = []
         for raw in raw_imports:
             target_raw = raw["target"]
             if target_raw == rel:
                 continue
-            kind, target = classifier(target_raw)
+            if suffix == ".py":
+                kind, target = _classify_python_import(
+                    target_raw, rel, module_set, relative=raw.get("relative", False)
+                )
+            else:
+                kind, target = _classify_js_import(target_raw, rel, module_set, root)
             entry = {
                 "source": rel,
                 "target": target,

package/skills/yotta-dev-mcp/scripts/dev_selftest.py

@@ -15,7 +15,8 @@ from pathlib import Path
 
 from dev_architecture import architecture_review
 from dev_common import (
-    EVIDENCE_LIMIT, VERIFY_REQUIRED_INSTALLED_FILES,
+    EVIDENCE_LIMIT, LEAN_INSTALL_MARKERS, VERIFY_REQUIRED_INSTALLED_ASSETS,
+    VERIFY_REQUIRED_INSTALLED_FILES,
     VERIFY_REQUIRED_SOURCE_FILES, VERIFY_WRITE_GATES, _frontmatter_version,
     _read_text,
 )
@@ -44,6 +45,9 @@ def _function_default(source_text, function_name, parameter_name):
 def _string_constant(node):
     return isinstance(node, ast.Constant) and isinstance(node.value, str)
 
+def _is_lean_install(root):
+    return any((root / marker).is_file() for marker in LEAN_INSTALL_MARKERS)
+
 def _protocol_tool_contracts(source_text):
     tree = ast.parse(source_text)
     function = None
@@ -380,8 +384,14 @@ def self_test(path, mode="auto", allow_execute=False, timeout=120):
         else:
             mode = "source"
 
-    required = (VERIFY_REQUIRED_SOURCE_FILES if mode == "source"
-                else VERIFY_REQUIRED_INSTALLED_FILES)
+    if mode == "source":
+        required = list(VERIFY_REQUIRED_SOURCE_FILES)
+    else:
+        required = list(VERIFY_REQUIRED_INSTALLED_FILES)
+        # Lean distribution strips assets/ by platform policy; only require
+        # the banner when the copy is not lean or it already ships assets/.
+        if not _is_lean_install(root) or (root / "assets").is_dir():
+            required.extend(VERIFY_REQUIRED_INSTALLED_ASSETS)
     missing = [rel for rel in required if not (root / rel).is_file()]
     files_check = {
         "id": "files",

package/skills/yotta-dev-mcp/scripts/yotta_dev_mcp.py

@@ -386,14 +386,24 @@ def mcp_tools():
         {
             "name": "mcp_doctor",
             "description": (
-                "Inspect installed skills and MCP JSON configuration files for "
-                "versions and obvious configuration issues. Read-only."
+                "Broad, read-only health check for installed skills and MCP client "
+                "configuration. Discovers Codex, Cursor, WorkBuddy, OpenCode, Claude "
+                "Code and other known hosts (plus project-level configs), parses JSON, "
+                "JSONC and a narrow TOML subset, and always returns a coverage report "
+                "with checked / missing / unsupported / unverified hosts. Only server "
+                "names are returned; commands, args and env values are never included. "
+                "A clean result applies only to the covered scope: read coverage and "
+                "coverage_confidence before treating it as all-clear."
             ),
             "inputSchema": {
                 "type": "object",
                 "properties": {
                     "skills_dirs": {"type": "array", "items": {"type": "string"}},
                     "config_paths": {"type": "array", "items": {"type": "string"}},
+                    "include_defaults": {
+                        "type": "boolean",
+                        "description": "Also scan the built-in host registry when config_paths is supplied",
+                    },
                 },
                 "additionalProperties": False,
             },

package/skills/yotta-dev-mcp/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/YottaMeta/yotta-dev-mcp",
     "source": "github"
   },
-  "version": "0.2.0",
+  "version": "0.2.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@yottameta/yotta-dev-mcp",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "transport": {
         "type": "stdio"
       }