source-kb 0.2.4__tar.gz

source_kb-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 source-kb contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

source_kb-0.2.4/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: source-kb
+Version: 0.2.4
+Summary: Auto-generate structured knowledge base documents from source code. Supports AI agent mode (skill-based) and standalone CLI.
+License-Expression: MIT
+Keywords: knowledge-base,documentation,code-analysis,llm,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: filelock>=3.12.0
+Provides-Extra: skeleton
+Requires-Dist: tree-sitter<0.22.0,>=0.21.0; extra == "skeleton"
+Requires-Dist: tree-sitter-languages>=1.10.0; extra == "skeleton"
+Provides-Extra: rag
+Requires-Dist: chromadb>=0.4.0; extra == "rag"
+Provides-Extra: full
+Requires-Dist: chromadb>=0.4.0; extra == "full"
+Requires-Dist: tree-sitter<0.22.0,>=0.21.0; extra == "full"
+Requires-Dist: tree-sitter-languages>=1.10.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# source-kb
+
+English | [中文](README.md)
+
+Auto-generate structured knowledge base documents from source code, build vector indexes, and support RAG retrieval.
+
+## Features
+
+- **CLI toolchain**: skeleton extraction, prompt rendering, intelligent splitting, quality validation, vector indexing — all standalone Python scripts
+- **Platform-agnostic**: works in Kiro / Cursor / Claude Code / Windsurf / any AI Agent
+- **LLM-agnostic**: without an Agent, use engine with any OpenAI-compatible API (Anthropic / OpenAI / DeepSeek / Ollama / vLLM, etc.)
+- **Intelligent subagent splitting**: semantic grouping by business domain (LLM-based) or package-aware greedy algorithm (code-based)
+- **Two-phase generation**: outline first, then expand — eliminates information isolation between shards
+- **Method-level source injection**: prioritized by complexity (high=full body / medium=first 20 lines / low=signature only)
+- **Real-time quality validation**: each subagent output is verified immediately, with automatic retry on failure
+- **Document deduplication**: LLM-powered post-merge dedup (internal redundancy + cross-doc ownership)
+- **Module doc distillation**: summarize multiple microservice docs into domain-level documentation
+- Any language support via preset system (java-spring built-in)
+- Source code access through git remote (multi-repo & monorepo)
+- Lightweight self-built RAG engine (ChromaDB + pluggable embedding)
+- Auto-publish docs to source repo knowledge branch
+
+## Quick Start
+
+### Option 1: Skill Mode (recommended)
+
+Install the CLI toolchain:
+
+```bash
+pip install source-kb[full]
+```
+
+Clone the presets repo into your project:
+
+```bash
+git clone https://github.com/anthropics/source-kb-presets.git
+cp -r source-kb-presets/skills ./skills
+cp -r source-kb-presets/presets ./presets
+cp -r source-kb-presets/examples ./examples
+```
+
+Then talk to your AI Agent (Kiro / Claude Code / Cursor / Windsurf):
+
+```
+Please read skills/kb-init/SKILL.md and follow the steps to initialize the knowledge base.
+```
+
+Or add the guide to your project rules file (`.kiro/steering/`, `.cursorrules`, `.claude/CLAUDE.md`, etc.). See [Getting Started](docs/getting-started.md).
+
+**Non-Java project?** Works the same way. Configure `kb-project.yaml` with the `generic` preset:
+
+```bash
+# Use generic preset (works for any language)
+source-kb extract --repo .source-cache/my-app --preset generic --output knowledge/my-app
+```
+
+> The generic preset uses path-based rules + regex parser for file classification — no tree-sitter required. For higher accuracy, create a custom preset following `presets/java-spring/` as reference.
+
+### Option 2: CLI Mode (no Agent, requires LLM API config)
+
+```bash
+pip install source-kb[full]
+
+export LLM_BASE_URL="https://api.anthropic.com"
+export LLM_MODEL="claude-sonnet-4-6"
+export LLM_API_KEY="sk-xxx"
+source-kb extract --repo .source-cache/my-app --preset java-spring --summary --output knowledge/my-app
+source-kb index --kb my-app
+```
+
+> Full guide: [Getting Started](docs/getting-started.md).
+
+## CLI Quick Reference
+
+```bash
+# Skeleton extraction
+source-kb extract --repo .source-cache/xxx --preset java-spring --summary --output knowledge/xxx
+
+# Prompt rendering
+source-kb render --template presets/java-spring/templates/subagent-business.md --module xxx --kb yyy --doc-type business-logic --mode readwrite
+
+# File list extraction
+source-kb file-list --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --preset java-spring --doc-type business-logic --output knowledge/xxx/.meta/file-lists/business-logic.txt
+
+# Coverage validation
+source-kb validate coverage check --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --docs-dir knowledge/xxx --type service
+
+# Index & search
+source-kb index --kb my-project
+source-kb search --kb my-project "query"
+```
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| kb-init | Generate all docs from source + build index |
+| kb-audit | Compare docs vs source, fix inconsistencies |
+| kb-sync | Detect git changes, incrementally update docs and index |
+| kb-search | Vector retrieval + contextual answers |
+
+Skill files are Agent operation guides — no platform-specific instructions.
+
+## Requirements
+
+- Python 3.10~3.12 (⚠️ 3.13 not supported — tree-sitter-languages has no prebuilt wheel)
+- Git
+- Embedding backend (Ollama / OpenAI-compatible / DashScope / ChromaDB built-in)
+
+## Installation
+
+```bash
+# Basic install (CLI toolchain)
+pip install source-kb
+
+# Full install (skeleton parsing + vector index)
+pip install source-kb[full]
+
+# Skeleton parsing only (tree-sitter)
+pip install source-kb[skeleton]
+
+# Vector index only (ChromaDB)
+pip install source-kb[rag]
+```
+
+Verify installation:
+
+```bash
+source-kb --version
+source-kb --help
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — Installation, configuration, first run
+- [Configuration Reference](docs/configuration.md) — Full kb-project.yaml field reference
+- [Custom Presets](docs/custom-presets.md) — Create and customize language presets
+- [Preset Development](docs/presets.md) — Built-in preset internals
+- [Design Document](docs/design-v5.md) — Architecture design and technical decisions
+- [CLI vs Agent Mode](docs/cli-vs-agent-mode-analysis.md) — Two modes compared

source_kb-0.2.4/README.en.md

@@ -0,0 +1,140 @@
+# source-kb
+
+English | [中文](README.md)
+
+Auto-generate structured knowledge base documents from source code, build vector indexes, and support RAG retrieval.
+
+## Features
+
+- **CLI toolchain**: skeleton extraction, prompt rendering, intelligent splitting, quality validation, vector indexing — all standalone Python scripts
+- **Platform-agnostic**: works in Kiro / Cursor / Claude Code / Windsurf / any AI Agent
+- **LLM-agnostic**: without an Agent, use engine with any OpenAI-compatible API (Anthropic / OpenAI / DeepSeek / Ollama / vLLM, etc.)
+- **Intelligent subagent splitting**: semantic grouping by business domain (LLM-based) or package-aware greedy algorithm (code-based)
+- **Two-phase generation**: outline first, then expand — eliminates information isolation between shards
+- **Method-level source injection**: prioritized by complexity (high=full body / medium=first 20 lines / low=signature only)
+- **Real-time quality validation**: each subagent output is verified immediately, with automatic retry on failure
+- **Document deduplication**: LLM-powered post-merge dedup (internal redundancy + cross-doc ownership)
+- **Module doc distillation**: summarize multiple microservice docs into domain-level documentation
+- Any language support via preset system (java-spring built-in)
+- Source code access through git remote (multi-repo & monorepo)
+- Lightweight self-built RAG engine (ChromaDB + pluggable embedding)
+- Auto-publish docs to source repo knowledge branch
+
+## Quick Start
+
+### Option 1: Skill Mode (recommended)
+
+Install the CLI toolchain:
+
+```bash
+pip install source-kb[full]
+```
+
+Clone the presets repo into your project:
+
+```bash
+git clone https://github.com/anthropics/source-kb-presets.git
+cp -r source-kb-presets/skills ./skills
+cp -r source-kb-presets/presets ./presets
+cp -r source-kb-presets/examples ./examples
+```
+
+Then talk to your AI Agent (Kiro / Claude Code / Cursor / Windsurf):
+
+```
+Please read skills/kb-init/SKILL.md and follow the steps to initialize the knowledge base.
+```
+
+Or add the guide to your project rules file (`.kiro/steering/`, `.cursorrules`, `.claude/CLAUDE.md`, etc.). See [Getting Started](docs/getting-started.md).
+
+**Non-Java project?** Works the same way. Configure `kb-project.yaml` with the `generic` preset:
+
+```bash
+# Use generic preset (works for any language)
+source-kb extract --repo .source-cache/my-app --preset generic --output knowledge/my-app
+```
+
+> The generic preset uses path-based rules + regex parser for file classification — no tree-sitter required. For higher accuracy, create a custom preset following `presets/java-spring/` as reference.
+
+### Option 2: CLI Mode (no Agent, requires LLM API config)
+
+```bash
+pip install source-kb[full]
+
+export LLM_BASE_URL="https://api.anthropic.com"
+export LLM_MODEL="claude-sonnet-4-6"
+export LLM_API_KEY="sk-xxx"
+source-kb extract --repo .source-cache/my-app --preset java-spring --summary --output knowledge/my-app
+source-kb index --kb my-app
+```
+
+> Full guide: [Getting Started](docs/getting-started.md).
+
+## CLI Quick Reference
+
+```bash
+# Skeleton extraction
+source-kb extract --repo .source-cache/xxx --preset java-spring --summary --output knowledge/xxx
+
+# Prompt rendering
+source-kb render --template presets/java-spring/templates/subagent-business.md --module xxx --kb yyy --doc-type business-logic --mode readwrite
+
+# File list extraction
+source-kb file-list --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --preset java-spring --doc-type business-logic --output knowledge/xxx/.meta/file-lists/business-logic.txt
+
+# Coverage validation
+source-kb validate coverage check --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --docs-dir knowledge/xxx --type service
+
+# Index & search
+source-kb index --kb my-project
+source-kb search --kb my-project "query"
+```
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| kb-init | Generate all docs from source + build index |
+| kb-audit | Compare docs vs source, fix inconsistencies |
+| kb-sync | Detect git changes, incrementally update docs and index |
+| kb-search | Vector retrieval + contextual answers |
+
+Skill files are Agent operation guides — no platform-specific instructions.
+
+## Requirements
+
+- Python 3.10~3.12 (⚠️ 3.13 not supported — tree-sitter-languages has no prebuilt wheel)
+- Git
+- Embedding backend (Ollama / OpenAI-compatible / DashScope / ChromaDB built-in)
+
+## Installation
+
+```bash
+# Basic install (CLI toolchain)
+pip install source-kb
+
+# Full install (skeleton parsing + vector index)
+pip install source-kb[full]
+
+# Skeleton parsing only (tree-sitter)
+pip install source-kb[skeleton]
+
+# Vector index only (ChromaDB)
+pip install source-kb[rag]
+```
+
+Verify installation:
+
+```bash
+source-kb --version
+source-kb --help
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — Installation, configuration, first run
+- [Configuration Reference](docs/configuration.md) — Full kb-project.yaml field reference
+- [Custom Presets](docs/custom-presets.md) — Create and customize language presets
+- [Preset Development](docs/presets.md) — Built-in preset internals
+- [Design Document](docs/design-v5.md) — Architecture design and technical decisions
+- [CLI vs Agent Mode](docs/cli-vs-agent-mode-analysis.md) — Two modes compared

source_kb-0.2.4/README.md

@@ -0,0 +1,139 @@
+# source-kb
+
+[English](README.en.md) | 中文
+
+从源码自动生成结构化知识库文档，构建向量索引，支持 RAG 检索。
+
+## 特性
+
+- **CLI 工具链**：骨架提取、prompt 渲染、智能拆分、质量校验、向量索引 — 全部是独立的 Python 脚本
+- **不绑定任何 AI 平台**：在 Kiro / Cursor / Claude Code / Windsurf / 任何 Agent 中使用
+- **不绑定任何 LLM**：无 Agent 环境时通过 engine 调用任意 OpenAI 兼容接口（Anthropic / OpenAI / DeepSeek / Ollama / vLLM 等）
+- **智能子代理拆分**：按业务域语义分组（LLM 智能拆分）或包感知贪心算法（代码规则拆分）
+- **两阶段生成**：分片场景下先生成 outline 再展开，消除信息隔离
+- **方法级精准注入**：按复杂度分级注入源码（high=完整/medium=前20行/low=签名）
+- **实时质量校验**：每个子代理完成后立即验证，失败自动重试
+- **文档去重优化**：合并后 LLM 自动去重（内部冗余 + 跨文档归属）
+- **Module 文档萃取**：从多个微服务文档汇总为领域级文档
+- 支持任意语言（通过 preset 预设系统，内置 java-spring）
+- 源码通过 git remote 读取，支持 multi-repo 和 monorepo
+- 自建轻量 RAG 引擎（ChromaDB + 可插拔 embedding）
+- 文档自动发布到源码仓库 knowledge 分支
+
+## 快速开始
+
+### 方式一：Skill 模式（推荐）
+
+安装 CLI 工具包：
+
+```bash
+pip install source-kb[full]
+```
+
+克隆 presets 仓库到你的项目中：
+
+```bash
+git clone https://github.com/anthropics/source-kb-presets.git
+cp -r source-kb-presets/skills ./skills
+cp -r source-kb-presets/presets ./presets
+cp -r source-kb-presets/examples ./examples
+```
+
+在 AI Agent（Kiro / Claude Code / Cursor / Windsurf）中直接对话：
+
+```
+请读取 skills/kb-init/SKILL.md，按里面的流程为我初始化知识库。
+```
+
+或将操作指南加入项目规则文件（`.kiro/steering/`、`.cursorrules`、`.claude/CLAUDE.md` 等），详见 [快速开始](docs/getting-started.md)。
+
+**非 Java 项目？** 同样支持。配置 `kb-project.yaml` 时选择 `generic` preset：
+
+```bash
+# 使用 generic preset（适用于任意语言）
+source-kb extract --repo .source-cache/my-app --preset generic --output knowledge/my-app
+```
+
+> generic preset 使用路径规则 + regex 解析器分类文件，无需 tree-sitter。如需更高精度，可参考 `presets/java-spring/` 创建自定义 preset。
+
+### 方式二：CLI 模式（无 Agent 环境，需配置 LLM API）
+
+```bash
+pip install source-kb[full]
+
+export LLM_BASE_URL="https://api.anthropic.com"
+export LLM_MODEL="claude-sonnet-4-6"
+export LLM_API_KEY="sk-xxx"
+source-kb extract --repo .source-cache/my-app --preset java-spring --summary --output knowledge/my-app
+source-kb index --kb my-app
+```
+
+> 完整指南见 [快速开始](docs/getting-started.md)。
+
+## CLI 工具速查
+
+```bash
+# 骨架提取
+source-kb extract --repo .source-cache/xxx --preset java-spring --summary --output knowledge/xxx
+
+# Prompt 渲染
+source-kb render --template presets/java-spring/templates/subagent-business.md --module xxx --kb yyy --doc-type business-logic --mode readwrite
+
+# 文件清单提取
+source-kb file-list --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --preset java-spring --doc-type business-logic --output knowledge/xxx/.meta/file-lists/business-logic.txt
+
+# 覆盖率校验
+source-kb validate coverage check --skeleton knowledge/xxx/.meta/skeleton/skeleton.json --docs-dir knowledge/xxx --type service
+
+# 索引构建与检索
+source-kb index --kb my-project
+source-kb search --kb my-project "查询词"
+```
+
+## Skill 说明
+
+| Skill | 用途 |
+|-------|------|
+| kb-init | 从源码生成全部文档 + 构建索引 |
+| kb-audit | 逐章节对比文档与源码，修复不一致 |
+| kb-sync | 检测 git 变动，增量更新文档和索引 |
+| kb-search | 向量检索 + 上下文回答 |
+
+Skill 文件是 Agent 的操作指南，不包含任何平台特定指令。
+
+## 环境要求
+
+- Python 3.10~3.12（⚠️ 3.13 不支持，tree-sitter-languages 无预编译 wheel）
+- Git
+- Embedding 后端（Ollama / OpenAI 兼容 / DashScope / ChromaDB 内置）
+
+## 安装
+
+```bash
+# 基础安装（CLI 工具链）
+pip install source-kb
+
+# 完整安装（骨架解析 + 向量索引）
+pip install source-kb[full]
+
+# 仅骨架解析（tree-sitter）
+pip install source-kb[skeleton]
+
+# 仅向量索引（ChromaDB）
+pip install source-kb[rag]
+```
+
+验证安装：
+
+```bash
+source-kb --version
+source-kb --help
+```
+
+## 文档
+
+- [快速开始](docs/getting-started.md) — 安装、配置、首次运行
+- [配置参考](docs/configuration.md) — kb-project.yaml 完整字段说明
+- [设计文档](docs/design-v5.md) — 架构设计与技术决策
+- [CLI vs Agent 模式](docs/cli-vs-agent-mode-analysis.md) — 两种模式对比
+- [Preset 开发](docs/presets.md) — 自定义语言预设指南

source_kb-0.2.4/cli/__init__.py

@@ -0,0 +1,50 @@
+"""source-kb — unified CLI entry point.
+
+Usage:
+    source-kb <command> [options]
+    source-kb --help
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import pkgutil
+import sys
+
+
+def _discover_commands(subparsers: argparse._SubParsersAction) -> None:
+    """Auto-discover and register all command modules in cli.commands."""
+    import cli.commands as cmd_pkg
+
+    for finder, name, _ in pkgutil.iter_modules(cmd_pkg.__path__):
+        module = importlib.import_module(f"cli.commands.{name}")
+        if hasattr(module, "register"):
+            module.register(subparsers)
+
+
+def main(argv: list[str] | None = None) -> None:
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+    from core import __version__
+
+    parser = argparse.ArgumentParser(
+        prog="source-kb",
+        description="Auto-generate structured knowledge base documents from source code.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command")
+    _discover_commands(subparsers)
+
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        parser.print_help()
+        sys.exit(1)

source_kb-0.2.4/cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m cli"""
+
+from cli import main
+
+main()

source_kb-0.2.4/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command registry — modules here are auto-discovered by the entry point."""

source_kb-0.2.4/cli/commands/anchor_fix.py

@@ -0,0 +1,47 @@
+"""source-kb anchor-fix — Fix broken cross-document anchor links."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("anchor-fix", help="Fix broken cross-document anchor links")
+    p.add_argument("--module-dir", required=True, help="Module documentation directory")
+    p.add_argument("--dry-run", action="store_true", help="Report without fixing")
+    p.add_argument("--threshold", type=float, default=0.8, help="Fuzzy match threshold (0.0-1.0)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.anchor_fix import fix_anchors
+
+    module_dir = Path(args.module_dir)
+    if not module_dir.is_dir():
+        print(f"Error: directory not found: {module_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    result = fix_anchors(
+        module_dir,
+        dry_run=args.dry_run,
+        similarity_threshold=args.threshold,
+    )
+
+    mode = " (dry-run)" if args.dry_run else ""
+    print(f"Anchor fix{mode}: scanned {result.files_scanned} files, checked {result.links_checked} links")
+    if result.links_fixed or result.links_degraded:
+        print(f"  Fixed: {result.links_fixed}, Degraded: {result.links_degraded}")
+        for d in result.details:
+            action = "fixed" if d["action"] == "fixed" else "degraded"
+            print(f"  [{action}] {d['file']}: {d['old_link']} -> {d['new_link']}")
+    else:
+        print("  All links valid.")
+
+    print(json.dumps({
+        "status": "ok", "files_scanned": result.files_scanned,
+        "links_checked": result.links_checked, "links_fixed": result.links_fixed,
+        "links_degraded": result.links_degraded,
+    }, ensure_ascii=False), file=sys.stderr)

source_kb-0.2.4/cli/commands/audit.py

@@ -0,0 +1,18 @@
+"""source-kb audit — Low-confidence classification audit."""
+
+from __future__ import annotations
+
+import argparse
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("audit", help="Low-confidence classification audit")
+    p.add_argument("--skeleton", required=True, help="Skeleton JSON path")
+    p.add_argument("--preset", required=True, help="Preset name")
+    p.add_argument("--threshold", type=float, default=0.7, help="Confidence threshold (default: 0.7)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton import cmd_audit
+    cmd_audit(args)

source_kb-0.2.4/cli/commands/diff_doc.py

@@ -0,0 +1,52 @@
+"""source-kb diff-doc — Compare document against skeleton."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("diff-doc", help="Compare document against skeleton for inconsistencies")
+    p.add_argument("--doc-path", required=True, help="Path to markdown document")
+    p.add_argument("--skeleton-path", required=True, help="Path to skeleton JSON or directory")
+    p.add_argument("--doc-type", help="Document type for specific comparison rules")
+    p.add_argument("--output", help="Output JSON path (default: stdout)")
+    p.set_defaults(func=run)
+
+
+def run(args: argparse.Namespace) -> None:
+    from core.skeleton.diff_doc import diff_doc
+
+    doc_path = Path(args.doc_path)
+    skeleton_path = Path(args.skeleton_path)
+
+    if not doc_path.exists():
+        print(f"Error: document not found: {doc_path}", file=sys.stderr)
+        sys.exit(1)
+    if not skeleton_path.exists():
+        print(f"Error: skeleton not found: {skeleton_path}", file=sys.stderr)
+        sys.exit(1)
+
+    result = diff_doc(doc_path, skeleton_path, doc_type=args.doc_type)
+
+    output = {
+        "doc_type": result.doc_type,
+        "doc_items": result.doc_items_count,
+        "skeleton_items": result.skeleton_items_count,
+        "missing": result.missing_count,
+        "stale": result.stale_count,
+        "findings": result.to_json(),
+    }
+
+    output_json = json.dumps(output, ensure_ascii=False, indent=2)
+    if args.output:
+        Path(args.output).write_text(output_json, encoding="utf-8")
+        print(f"Written to: {args.output}")
+    else:
+        print(output_json)
+
+    print(json.dumps({"status": "ok", "missing": result.missing_count,
+                      "stale": result.stale_count}, ensure_ascii=False), file=sys.stderr)