Merge feature/framework-improvements into integration

## Merged Changes

### From framework-improvements:
- ✅ framework_docs → knowledge_base rename (complete)
- ✅ Installation failures fix (docstring + dependencies)
- ✅ MCP URL fix (agiletec-inc)
- ✅ README translation workflow
- ✅ CLAUDE.md with UV rules

### From integration (preserved):
- ✅ PM Agent improvements (dynamic token calculation)
- ✅ PM modules relocation
- ✅ Docs cleanup

## Conflict Resolution Strategy

**Installer & Components**: Adopted framework-improvements
- Reason: knowledge_base rename + installation fixes are critical

**PM Agent**: Preserved integration version
- Reason: Latest improvements (dynamic token, modular architecture)

## Result

Integration branch now contains:
- All installation fixes from PR #447
- Latest PM Agent improvements
- Unified MCP gateway (airis-mcp-gateway)
- Complete knowledge_base migration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.github/workflows/translation-sync.yml

@@ -0,0 +1,96 @@
+name: Auto-translate README
+
+on:
+  push:
+    branches: [master, main]
+    paths:
+      - 'README.md'
+  pull_request:
+    paths:
+      - 'README.md'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  translate:
+    name: Translate README to Multiple Languages
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Translate README to Chinese
+      uses: 3ru/gpt-translate@v1.1.11
+      with:
+        apikey: ${{ secrets.OPENAI_API_KEY }}
+        inputFiles: 'README.md'
+        outputFiles: 'README-zh.md'
+        targetLanguage: 'Simplified Chinese'
+
+    - name: Translate README to Japanese
+      uses: 3ru/gpt-translate@v1.1.11
+      with:
+        apikey: ${{ secrets.OPENAI_API_KEY }}
+        inputFiles: 'README.md'
+        outputFiles: 'README-ja.md'
+        targetLanguage: 'Japanese'
+
+    - name: Check for changes
+      id: check_changes
+      run: |
+        if git diff --quiet HEAD -- README-zh.md README-ja.md; then
+          echo "No translation changes detected"
+          echo "has_changes=false" >> $GITHUB_OUTPUT
+        else
+          echo "Translation changes detected"
+          echo "has_changes=true" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Commit translations
+      if: steps.check_changes.outputs.has_changes == 'true'
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        git add README-zh.md README-ja.md
+        git commit -m "chore: auto-translate README to ZH/JA
+
+        🤖 Generated with [GPT-Translate](https://github.com/3ru/gpt-translate)
+
+        Co-Authored-By: GitHub Actions <noreply@github.com>"
+
+    - name: Push changes
+      if: steps.check_changes.outputs.has_changes == 'true' && github.event_name == 'push'
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: ${{ github.ref }}
+
+    - name: Create Pull Request
+      if: steps.check_changes.outputs.has_changes == 'true' && github.event_name == 'pull_request'
+      uses: peter-evans/create-pull-request@v6
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        commit-message: "chore: auto-translate README to ZH/JA"
+        title: "🌐 Auto-translate README updates"
+        body: |
+          ## 🤖 Automated Translation Update
+
+          This PR contains automated translations of README.md updates.
+
+          **Changes:**
+          - ✅ README-zh.md (Simplified Chinese)
+          - ✅ README-ja.md (Japanese)
+
+          **Translation powered by:**
+          - [GPT-Translate](https://github.com/3ru/gpt-translate)
+          - OpenAI GPT-4
+
+          Please review the translations for accuracy before merging.
+        branch: chore/auto-translate-readme
+        delete-branch: true

CLAUDE.md

@@ -0,0 +1,134 @@
+# CLAUDE.md
+
+Project-specific instructions for Claude Code when working with SuperClaude Framework.
+
+## 🐍 Python Environment Rules
+
+**CRITICAL**: This project uses **UV** for all Python operations.
+
+### Required Commands
+
+```bash
+# ❌ WRONG - Never use these
+python -m pytest
+pip install package
+python script.py
+
+# ✅ CORRECT - Always use UV
+uv run pytest
+uv pip install package
+uv run python script.py
+```
+
+### Why UV?
+
+- **Fast**: 10-100x faster than pip
+- **Reliable**: Lock file ensures reproducibility
+- **Clean**: No system Python pollution
+- **Standard**: Project convention for consistency
+
+### Common Operations
+
+```bash
+# Run tests
+uv run pytest tests/ -v
+
+# Install dependencies
+uv pip install -r requirements.txt
+
+# Run specific script
+uv run python scripts/analyze_workflow_metrics.py
+
+# Create virtual environment (if needed)
+uv venv
+```
+
+### Integration with Docker
+
+When using Docker for development:
+```bash
+# Inside Docker container
+docker compose exec workspace uv run pytest
+```
+
+## 📂 Project Structure
+
+```
+SuperClaude_Framework/
+├── superclaude/           # Framework source
+│   ├── commands/          # Slash commands
+│   ├── agents/            # Agent personas
+│   ├── modes/             # Behavior modes
+│   ├── framework/         # Core principles/rules/flags
+│   ├── business/          # Business analysis patterns
+│   └── research/          # Research configurations
+├── setup/                 # Installation system
+│   ├── components/        # Installable components
+│   │   ├── knowledge_base.py       # Framework knowledge
+│   │   ├── behavior_modes.py       # Mode definitions
+│   │   ├── agent_personas.py       # Agent definitions
+│   │   ├── slash_commands.py       # Command registration
+│   │   └── mcp_integration.py      # External tool integration
+│   └── core/              # Installation logic
+└── tests/                 # Test suite
+```
+
+## 🔧 Development Workflow
+
+### Running Tests
+
+```bash
+# All tests
+uv run pytest
+
+# Specific test file
+uv run pytest tests/test_cli_smoke.py -v
+
+# With coverage
+uv run pytest --cov=superclaude --cov-report=html
+```
+
+### Code Quality
+
+```bash
+# Linting (if configured)
+uv run ruff check .
+
+# Type checking (if configured)
+uv run mypy superclaude/
+
+# Formatting (if configured)
+uv run ruff format .
+```
+
+## 📦 Component Architecture
+
+SuperClaude uses **Responsibility-Driven Design**. Each component has a single, clear responsibility:
+
+- **knowledge_base**: Framework knowledge initialization
+- **behavior_modes**: Execution mode definitions
+- **agent_personas**: AI agent personality definitions
+- **slash_commands**: CLI command registration
+- **mcp_integration**: External tool integration
+
+## 🚀 Contributing
+
+When making changes:
+
+1. Create feature branch: `git checkout -b feature/your-feature`
+2. Make changes with tests: `uv run pytest`
+3. Commit with conventional commits: `git commit -m "feat: description"`
+4. Push and create PR: Small, reviewable PRs preferred
+
+## 📝 Documentation
+
+- Root documents: `PLANNING.md`, `KNOWLEDGE.md`, `TASK.md`
+- User guides: `docs/user-guide/`
+- Development docs: `docs/Development/`
+- Research reports: `docs/research/`
+
+## 🔗 Related
+
+- Global rules: `~/.claude/CLAUDE.md` (workspace-level)
+- MCP servers: Unified gateway via `airis-mcp-gateway`
+- Framework docs: Auto-installed to `~/.claude/superclaude/`

README-ja.md

@@ -261,6 +261,38 @@ pip install --break-system-packages SuperClaude
 
 <div align="center">
 
+## 🔬 **深層リサーチ機能**
+
+SuperClaude v4.2は、自律的、適応的、知的なWeb調査を可能にする包括的な深層リサーチ機能を導入しました。
+
+### 🎯 **適応型計画**
+3つのインテリジェント戦略：**計画優先**（明確なクエリの直接実行）、**意図計画**（曖昧なリクエストの明確化）、**統合**（協調的な計画改善、デフォルト）
+
+### 🔄 **マルチホップ推論**
+最大5回の反復検索：エンティティ拡張、概念深化、時系列進行、因果チェーン
+
+### 📊 **品質スコアリング**
+信頼性ベースの検証：情報源の信頼性評価(0.0-1.0)、カバレッジ完全性追跡、統合一貫性評価
+
+### 🧠 **ケースベース学習**
+クロスセッション・インテリジェンス：パターン認識と再利用、戦略最適化、成功したクエリ保存
+
+### **リサーチコマンド使用法**
+
+```bash
+/sc:research "AI最新動向 2024"
+/sc:research "量子コンピューティング" --depth exhaustive
+```
+
+### **統合ツール・オーケストレーション**
+複数ツールのインテリジェント調整：**Tavily MCP**（Web検索）、**Playwright MCP**（コンテンツ抽出）、**Sequential MCP**（推論合成）、**Serena MCP**（メモリ永続化）、**Context7 MCP**（技術ドキュメント）
+
+</div>
+
+---
+
+<div align="center">
+
 ## 📚 **ドキュメント**
 
 ### **🇯🇵 SuperClaude完全日本語ガイド**
@@ -317,7 +349,7 @@ pip install --break-system-packages SuperClaude
 </td>
 <td valign="top">
 
-- ✨ [**ベストプラクティス**](docs/reference/quick-start-practices.md)  
+- ✨ [**ベストプラクティス**](docs/getting-started/quick-start.md)
   *プロのコツとパターン*
 
 - 📓 [**サンプル集**](docs/reference/examples-cookbook.md)  

README-zh.md

@@ -261,6 +261,38 @@ pip install --break-system-packages SuperClaude
 
 <div align="center">
 
+## 🔬 **深度研究能力**
+
+SuperClaude v4.2引入了全面的深度研究能力，实现自主、自适应和智能的网络研究。
+
+### 🎯 **自适应规划**
+三种智能策略：**规划优先**（直接执行）、**意图规划**（澄清模糊请求）、**统一规划**（协作细化，默认）
+
+### 🔄 **多跳推理**
+最多5次迭代搜索：实体扩展、概念深化、时序进展、因果链
+
+### 📊 **质量评分**
+基于置信度的验证：来源可信度评估(0.0-1.0)、覆盖完整性跟踪、综合连贯性评估
+
+### 🧠 **案例学习**
+跨会话智能：模式识别和重用、策略优化、成功查询保存
+
+### **研究命令使用**
+
+```bash
+/sc:research "AI最新发展 2024"
+/sc:research "量子计算突破" --depth exhaustive
+```
+
+### **集成工具编排**
+智能协调多个工具：**Tavily MCP**（网页搜索）、**Playwright MCP**（内容提取）、**Sequential MCP**（推理合成）、**Serena MCP**（记忆持久化）、**Context7 MCP**（技术文档）
+
+</div>
+
+---
+
+<div align="center">
+
 ## 📚 **Documentation**
 
 ### **Complete Guide to SuperClaude**
@@ -317,7 +349,7 @@ pip install --break-system-packages SuperClaude
 </td>
 <td valign="top">
 
-- ✨ [**最佳实践**](docs/reference/quick-start-practices.md)  
+- ✨ [**最佳实践**](docs/getting-started/quick-start.md)
   *专业技巧和模式*
 
 - 📓 [**示例手册**](docs/reference/examples-cookbook.md)  

docs/Development/translation-workflow.md

@@ -0,0 +1,183 @@
+# README Auto-Translation Workflow
+
+## 概要
+
+SuperClaudeは **GPT-Translate** を使用して、READMEの自動翻訳を実現しています。
+
+## 🎯 仕組み
+
+```mermaid
+graph LR
+    A[README.md更新] --> B[GitHub Actions起動]
+    B --> C[GPT-4で翻訳]
+    C --> D[README-zh.md]
+    C --> E[README-ja.md]
+    D --> F[自動コミット]
+    E --> F
+    F --> G[PR作成 or Push]
+```
+
+## 🔧 セットアップ
+
+### 1. OpenAI APIキーの設定
+
+GitHub リポジトリの Settings → Secrets → Actions で以下を追加:
+
+```
+Name: OPENAI_API_KEY
+Value: sk-proj-xxxxxxxxxxxxx
+```
+
+### 2. ワークフローの動作
+
+**自動起動トリガー:**
+- `README.md` が更新されたとき (master/mainブランチ)
+- Pull Requestで `README.md` が変更されたとき
+- 手動実行 (workflow_dispatch)
+
+**動作:**
+1. README.md を GPT-4 で翻訳
+2. README-zh.md (簡体字中国語) を生成
+3. README-ja.md (日本語) を生成
+4. 変更があれば自動コミット
+5. masterブランチなら直接Push、PRなら新規PR作成
+
+## 📊 コスト見積もり
+
+| ファイルサイズ | GPT-4 Token数 | 推定コスト |
+|:-------------:|:-------------:|:----------:|
+| 5KB README    | ~3,000 tokens | ~$0.03     |
+| 10KB README   | ~6,000 tokens | ~$0.06     |
+| 20KB README   | ~12,000 tokens| ~$0.12    |
+
+**月間コスト見積もり:**
+- README更新頻度: 月10回
+- 1回あたり: $0.06 (2言語翻訳)
+- **月額: 約$0.60 (¥90)**
+
+## 🛡️ セキュリティ
+
+**APIキー保護:**
+- GitHub Secrets で暗号化保存
+- ワークフローログには表示されない
+- Pull Requestからはforkでアクセス不可
+
+**権限管理:**
+```yaml
+permissions:
+  contents: write      # 翻訳ファイルのコミット用
+  pull-requests: write # PR作成用
+```
+
+## 🔄 使用方法
+
+### 自動翻訳 (推奨)
+
+README.mdを更新してコミット・プッシュするだけ:
+
+```bash
+# README.md を編集
+vim README.md
+
+# コミット
+git add README.md
+git commit -m "docs: update README"
+git push origin main
+
+# → GitHub Actionsが自動的に翻訳を実行
+```
+
+### 手動実行
+
+GitHub UI から:
+1. Actions タブを開く
+2. "Auto-translate README" を選択
+3. "Run workflow" をクリック
+
+### ローカルテスト
+
+翻訳品質を事前確認する場合:
+
+```bash
+# GPT-Translateをローカルで実行
+npm install -g gpt-translate
+export OPENAI_API_KEY="sk-proj-xxxxx"
+
+gpt-translate --input README.md --output README-zh.md --lang "Simplified Chinese"
+gpt-translate --input README.md --output README-ja.md --lang "Japanese"
+```
+
+## 📝 翻訳品質チェック
+
+**自動翻訳後の確認ポイント:**
+
+1. **技術用語の正確性**
+   - フレームワーク名、コマンド名が正しいか
+   - コードブロックが保持されているか
+
+2. **マークダウン構造**
+   - 見出しレベルが一致しているか
+   - リンクが正しく変換されているか
+
+3. **ニュアンス**
+   - 文脈に合った翻訳か
+   - 自然な表現か
+
+**修正が必要な場合:**
+- 自動翻訳後に手動で微調整
+- 次回の翻訳時にその修正が維持されるよう考慮
+
+## 🚫 トラブルシューティング
+
+### エラー: "OPENAI_API_KEY not found"
+
+**原因:** GitHub Secretsが設定されていない
+
+**解決策:**
+```bash
+# リポジトリ設定を確認
+Settings → Secrets and variables → Actions → New repository secret
+```
+
+### エラー: "Translation failed"
+
+**原因:** OpenAI API レート制限
+
+**解決策:**
+- 数分待ってから再実行
+- API使用量を確認: https://platform.openai.com/usage
+
+### 翻訳品質が低い
+
+**原因:** プロンプトが最適化されていない
+
+**改善策:**
+```yaml
+# .github/workflows/translation-sync.yml
+with:
+  apikey: ${{ secrets.OPENAI_API_KEY }}
+  inputFiles: 'README.md'
+  outputFiles: 'README-zh.md'
+  targetLanguage: 'Simplified Chinese'
+  prompt: 'Translate this technical documentation accurately, preserving all code blocks and technical terms.'
+```
+
+## 🔗 関連リンク
+
+- [GPT-Translate GitHub](https://github.com/3ru/gpt-translate)
+- [OpenAI API Documentation](https://platform.openai.com/docs)
+- [GitHub Actions Documentation](https://docs.github.com/actions)
+
+## 📊 翻訳統計
+
+現在の翻訳実績は GitHub Actions の Workflows タブから確認できます:
+
+```
+Repository → Actions → Auto-translate README → 実行履歴
+```
+
+**確認できる情報:**
+- 翻訳実行回数
+- 成功/失敗率
+- 実行時間
+- 翻訳されたファイルサイズ

setup/cli/commands/install.py

@@ -138,7 +138,7 @@ def get_components_to_install(
     # Explicit components specified
     if args.components:
         if "all" in args.components:
-            components = ["framework_docs", "commands", "agents", "modes", "mcp"]
+            components = ["knowledge_base", "commands", "agents", "modes", "mcp"]
         else:
             components = args.components
 
@@ -302,7 +302,7 @@ def select_framework_components(
 
     try:
         # Framework components (excluding MCP-related ones)
-        framework_components = ["framework_docs", "modes", "commands", "agents"]
+        framework_components = ["knowledge_base", "modes", "commands", "agents"]
 
         # Create component menu
         component_options = []
@@ -334,9 +334,9 @@ def select_framework_components(
         selections = menu.display()
 
         if not selections:
-            # Default to framework_docs if nothing selected
+            # Default to knowledge_base if nothing selected
-            logger.info("No components selected, defaulting to framework_docs")
+            logger.info("No components selected, defaulting to knowledge_base")
-            selected_components = ["framework_docs"]
+            selected_components = ["knowledge_base"]
         else:
             selected_components = []
             all_components = framework_components
@@ -354,7 +354,7 @@ def select_framework_components(
 
     except Exception as e:
         logger.error(f"Error in framework component selection: {e}")
-        return ["framework_docs"]  # Fallback to framework_docs
+        return ["knowledge_base"]  # Fallback to knowledge_base
 
 
 def interactive_component_selection(

setup/components/__init__.py

@@ -1,15 +1,24 @@
-"""Component implementations for SuperClaude installation system"""
+"""
+Component Directory
 
-from .framework_docs import FrameworkDocsComponent
+Each module defines an installable responsibility unit:
-from .commands import CommandsComponent
+- knowledge_base: Framework knowledge initialization
-from .mcp import MCPComponent
+- behavior_modes: Execution mode definitions
-from .agents import AgentsComponent
+- agent_personas: AI agent personality definitions
-from .modes import ModesComponent
+- slash_commands: CLI command registration
+- mcp_integration: External tool integration via MCP
+"""
+
+from .knowledge_base import KnowledgeBaseComponent
+from .behavior_modes import BehaviorModesComponent
+from .agent_personas import AgentPersonasComponent
+from .slash_commands import SlashCommandsComponent
+from .mcp_integration import MCPIntegrationComponent
 
 __all__ = [
-    "FrameworkDocsComponent",
+    "KnowledgeBaseComponent",
-    "CommandsComponent",
+    "BehaviorModesComponent",
-    "MCPComponent",
+    "AgentPersonasComponent",
-    "AgentsComponent",
+    "SlashCommandsComponent",
-    "ModesComponent",
+    "MCPIntegrationComponent",
 ]

setup/components/agent_personas.py

@@ -1,5 +1,8 @@
 """
-Agents component for SuperClaude specialized AI agents installation
+Agent Personas Component
+
+Responsibility: Defines AI agent personalities and role-based behaviors.
+Provides specialized personas for different task types.
 """
 
 from typing import Dict, List, Tuple, Optional, Any
@@ -9,7 +12,7 @@ from ..core.base import Component
 from setup import __version__
 
 
-class AgentsComponent(Component):
+class AgentPersonasComponent(Component):
     """SuperClaude specialized AI agents component"""
 
     def __init__(self, install_dir: Optional[Path] = None):
@@ -133,7 +136,7 @@ class AgentsComponent(Component):
 
     def get_dependencies(self) -> List[str]:
         """Get component dependencies"""
-        return ["framework_docs"]
+        return ["knowledge_base"]
 
     def update(self, config: Dict[str, Any]) -> bool:
         """

setup/components/behavior_modes.py

@@ -1,5 +1,8 @@
 """
-Modes component for SuperClaude behavioral modes
+Behavior Modes Component
+
+Responsibility: Defines and manages execution modes for Claude behavior.
+Controls how Claude responds to different contexts and user intent.
 """
 
 from typing import Dict, List, Tuple, Optional, Any
@@ -10,7 +13,7 @@ from setup import __version__
 from ..services.claude_md import CLAUDEMdService
 
 
-class ModesComponent(Component):
+class BehaviorModesComponent(Component):
     """SuperClaude behavioral modes component"""
 
     def __init__(self, install_dir: Optional[Path] = None):
@@ -149,7 +152,7 @@ class ModesComponent(Component):
 
     def get_dependencies(self) -> List[str]:
         """Get dependencies"""
-        return ["framework_docs"]
+        return ["knowledge_base"]
 
     def update(self, config: Dict[str, Any]) -> bool:
         """

setup/components/knowledge_base.py

@@ -0,0 +1,418 @@
+"""
+Knowledge Base Component for SuperClaude
+
+Responsibility: Provides structured knowledge initialization for the framework.
+Manages framework knowledge documents (principles, rules, flags, research config, business patterns).
+These files form the foundation of Claude's understanding of the SuperClaude framework.
+"""
+
+from typing import Dict, List, Tuple, Optional, Any
+from pathlib import Path
+import shutil
+
+from ..core.base import Component
+from ..services.claude_md import CLAUDEMdService
+from setup import __version__
+
+
+class KnowledgeBaseComponent(Component):
+    """
+    Knowledge Base Component
+
+    Responsibility: Initialize and maintain SuperClaude's knowledge base.
+    Installs framework knowledge documents that guide Claude's behavior and decision-making.
+    """
+
+    def __init__(self, install_dir: Optional[Path] = None):
+        """Initialize knowledge base component"""
+        super().__init__(install_dir)
+
+    def get_metadata(self) -> Dict[str, str]:
+        """Get component metadata"""
+        return {
+            "name": "knowledge_base",
+            "version": __version__,
+            "description": "SuperClaude knowledge base (principles, rules, flags, patterns)",
+            "category": "knowledge",
+        }
+
+    def is_reinstallable(self) -> bool:
+        """
+        Framework docs should always be updated to latest version.
+        SuperClaude-related documentation should always overwrite existing files.
+        """
+        return True
+
+    def validate_prerequisites(
+        self, installSubPath: Optional[Path] = None
+    ) -> Tuple[bool, List[str]]:
+        """
+        Check prerequisites for framework docs component (multi-directory support)
+
+        Returns:
+            Tuple of (success: bool, error_messages: List[str])
+        """
+        from ..utils.security import SecurityValidator
+
+        errors = []
+
+        # Check if all source directories exist
+        for source_dir in self._get_source_dirs():
+            if not source_dir.exists():
+                errors.append(f"Source directory not found: {source_dir}")
+
+        # Check if all required framework files exist
+        missing_files = []
+        for source, _ in self.get_files_to_install():
+            if not source.exists():
+                missing_files.append(str(source.relative_to(Path(__file__).parent.parent.parent / "superclaude")))
+
+        if missing_files:
+            errors.append(f"Missing component files: {missing_files}")
+
+        # Check write permissions to install directory
+        has_perms, missing = SecurityValidator.check_permissions(
+            self.install_dir, {"write"}
+        )
+        if not has_perms:
+            errors.append(f"No write permissions to {self.install_dir}: {missing}")
+
+        # Validate installation target
+        is_safe, validation_errors = SecurityValidator.validate_installation_target(
+            self.install_component_subdir
+        )
+        if not is_safe:
+            errors.extend(validation_errors)
+
+        # Validate files individually (each file with its own source dir)
+        for source, target in self.get_files_to_install():
+            # Get the appropriate base source directory for this file
+            source_parent = source.parent
+
+            # Validate source path
+            is_safe, msg = SecurityValidator.validate_path(source, source_parent)
+            if not is_safe:
+                errors.append(f"Invalid source path {source}: {msg}")
+
+            # Validate target path
+            is_safe, msg = SecurityValidator.validate_path(target, self.install_component_subdir)
+            if not is_safe:
+                errors.append(f"Invalid target path {target}: {msg}")
+
+            # Validate file extension
+            is_allowed, msg = SecurityValidator.validate_file_extension(source)
+            if not is_allowed:
+                errors.append(f"File {source}: {msg}")
+
+        if not self.file_manager.ensure_directory(self.install_component_subdir):
+            errors.append(
+                f"Could not create install directory: {self.install_component_subdir}"
+            )
+
+        return len(errors) == 0, errors
+
+    def get_metadata_modifications(self) -> Dict[str, Any]:
+        """Get metadata modifications for SuperClaude"""
+        return {
+            "framework": {
+                "version": __version__,
+                "name": "superclaude",
+                "description": "AI-enhanced development framework for Claude Code",
+                "installation_type": "global",
+                "components": ["knowledge_base"],
+            },
+            "superclaude": {
+                "enabled": True,
+                "version": __version__,
+                "profile": "default",
+                "auto_update": False,
+            },
+        }
+
+    def _install(self, config: Dict[str, Any]) -> bool:
+        """Install knowledge base component"""
+        self.logger.info("Installing SuperClaude knowledge base...")
+
+        return super()._install(config)
+
+    def _post_install(self) -> bool:
+        # Create or update metadata
+        try:
+            metadata_mods = self.get_metadata_modifications()
+            self.settings_manager.update_metadata(metadata_mods)
+            self.logger.info("Updated metadata with framework configuration")
+
+            # Add component registration to metadata (with file list for sync)
+            self.settings_manager.add_component_registration(
+                "knowledge_base",
+                {
+                    "version": __version__,
+                    "category": "documentation",
+                    "files_count": len(self.component_files),
+                    "files": list(self.component_files),  # Track for sync/deletion
+                },
+            )
+
+            self.logger.info("Updated metadata with knowledge base component registration")
+
+            # Migrate any existing SuperClaude data from settings.json
+            if self.settings_manager.migrate_superclaude_data():
+                self.logger.info(
+                    "Migrated existing SuperClaude data from settings.json"
+                )
+        except Exception as e:
+            self.logger.error(f"Failed to update metadata: {e}")
+            return False
+
+        # Create additional directories for other components
+        additional_dirs = ["commands", "backups", "logs"]
+        for dirname in additional_dirs:
+            dir_path = self.install_dir / dirname
+            if not self.file_manager.ensure_directory(dir_path):
+                self.logger.warning(f"Could not create directory: {dir_path}")
+
+        # Update CLAUDE.md with framework documentation imports
+        try:
+            manager = CLAUDEMdService(self.install_dir)
+            manager.add_imports(self.component_files, category="Framework Documentation")
+            self.logger.info("Updated CLAUDE.md with framework documentation imports")
+        except Exception as e:
+            self.logger.warning(
+                f"Failed to update CLAUDE.md with framework documentation imports: {e}"
+            )
+            # Don't fail the whole installation for this
+
+        return True
+
+    def uninstall(self) -> bool:
+        """Uninstall knowledge base component"""
+        try:
+            self.logger.info("Uninstalling SuperClaude knowledge base component...")
+
+            # Remove framework files
+            removed_count = 0
+            for filename in self.component_files:
+                file_path = self.install_component_subdir / filename
+                if self.file_manager.remove_file(file_path):
+                    removed_count += 1
+                    self.logger.debug(f"Removed {filename}")
+                else:
+                    self.logger.warning(f"Could not remove {filename}")
+
+            # Update metadata to remove knowledge base component
+            try:
+                if self.settings_manager.is_component_installed("knowledge_base"):
+                    self.settings_manager.remove_component_registration("knowledge_base")
+                    metadata_mods = self.get_metadata_modifications()
+                    metadata = self.settings_manager.load_metadata()
+                    for key in metadata_mods.keys():
+                        if key in metadata:
+                            del metadata[key]
+
+                    self.settings_manager.save_metadata(metadata)
+                    self.logger.info("Removed knowledge base component from metadata")
+            except Exception as e:
+                self.logger.warning(f"Could not update metadata: {e}")
+
+            self.logger.success(
+                f"Framework docs component uninstalled ({removed_count} files removed)"
+            )
+            return True
+
+        except Exception as e:
+            self.logger.exception(f"Unexpected error during knowledge base uninstallation: {e}")
+            return False
+
+    def get_dependencies(self) -> List[str]:
+        """Get component dependencies (knowledge base has none)"""
+        return []
+
+    def update(self, config: Dict[str, Any]) -> bool:
+        """
+        Sync knowledge base component (overwrite + delete obsolete files).
+        No backup needed - SuperClaude source files are always authoritative.
+        """
+        try:
+            self.logger.info("Syncing SuperClaude knowledge base component...")
+
+            # Get previously installed files from metadata
+            metadata = self.settings_manager.load_metadata()
+            previous_files = set(
+                metadata.get("components", {})
+                .get("knowledge_base", {})
+                .get("files", [])
+            )
+
+            # Get current files from source
+            current_files = set(self.component_files)
+
+            # Files to delete (were installed before, but no longer in source)
+            files_to_delete = previous_files - current_files
+
+            # Delete obsolete files
+            deleted_count = 0
+            for filename in files_to_delete:
+                file_path = self.install_component_subdir / filename
+                if file_path.exists():
+                    try:
+                        file_path.unlink()
+                        deleted_count += 1
+                        self.logger.info(f"Deleted obsolete file: {filename}")
+                    except Exception as e:
+                        self.logger.warning(f"Could not delete {filename}: {e}")
+
+            # Install/overwrite current files (no backup)
+            success = self.install(config)
+
+            if success:
+                # Update metadata with current file list
+                self.settings_manager.add_component_registration(
+                    "knowledge_base",
+                    {
+                        "version": __version__,
+                        "category": "documentation",
+                        "files_count": len(current_files),
+                        "files": list(current_files),  # Track installed files
+                    },
+                )
+
+                self.logger.success(
+                    f"Framework docs synced: {len(current_files)} files, {deleted_count} obsolete files removed"
+                )
+            else:
+                self.logger.error("Framework docs sync failed")
+
+            return success
+
+        except Exception as e:
+            self.logger.exception(f"Unexpected error during knowledge base sync: {e}")
+            return False
+
+    def validate_installation(self) -> Tuple[bool, List[str]]:
+        """Validate knowledge base component installation"""
+        errors = []
+
+        # Check if all framework files exist
+        for filename in self.component_files:
+            file_path = self.install_component_subdir / filename
+            if not file_path.exists():
+                errors.append(f"Missing framework file: {filename}")
+            elif not file_path.is_file():
+                errors.append(f"Framework file is not a regular file: {filename}")
+
+        # Check metadata registration
+        if not self.settings_manager.is_component_installed("knowledge_base"):
+            errors.append("Knowledge base component not registered in metadata")
+        else:
+            # Check version matches
+            installed_version = self.settings_manager.get_component_version("knowledge_base")
+            expected_version = self.get_metadata()["version"]
+            if installed_version != expected_version:
+                errors.append(
+                    f"Version mismatch: installed {installed_version}, expected {expected_version}"
+                )
+
+        # Check metadata structure
+        try:
+            framework_config = self.settings_manager.get_metadata_setting("framework")
+            if not framework_config:
+                errors.append("Missing framework configuration in metadata")
+            else:
+                required_keys = ["version", "name", "description"]
+                for key in required_keys:
+                    if key not in framework_config:
+                        errors.append(f"Missing framework.{key} in metadata")
+        except Exception as e:
+            errors.append(f"Could not validate metadata: {e}")
+
+        return len(errors) == 0, errors
+
+    def _get_source_dirs(self):
+        """Get source directories for framework documentation files"""
+        # Assume we're in superclaude/setup/components/framework_docs.py
+        # Framework files are organized in superclaude/{framework,business,research}
+        project_root = Path(__file__).parent.parent.parent
+        return [
+            project_root / "superclaude" / "framework",
+            project_root / "superclaude" / "business",
+            project_root / "superclaude" / "research",
+        ]
+
+    def _get_source_dir(self):
+        """Get source directory (compatibility method, returns first directory)"""
+        dirs = self._get_source_dirs()
+        return dirs[0] if dirs else None
+
+    def _discover_component_files(self) -> List[str]:
+        """
+        Discover framework .md files across multiple directories
+
+        Returns:
+            List of relative paths (e.g., ['framework/flags.md', 'business/examples.md'])
+        """
+        all_files = []
+        project_root = Path(__file__).parent.parent.parent / "superclaude"
+
+        for source_dir in self._get_source_dirs():
+            if not source_dir.exists():
+                self.logger.warning(f"Source directory not found: {source_dir}")
+                continue
+
+            # Get directory name relative to superclaude/
+            dir_name = source_dir.relative_to(project_root)
+
+            # Discover .md files in this directory
+            files = self._discover_files_in_directory(
+                source_dir,
+                extension=".md",
+                exclude_patterns=["README.md", "CHANGELOG.md", "LICENSE.md"],
+            )
+
+            # Add directory prefix to each file
+            for file in files:
+                all_files.append(str(dir_name / file))
+
+        return all_files
+
+    def get_files_to_install(self) -> List[Tuple[Path, Path]]:
+        """
+        Return list of files to install from multiple source directories
+
+        Returns:
+            List of tuples (source_path, target_path)
+        """
+        files = []
+        project_root = Path(__file__).parent.parent.parent / "superclaude"
+
+        for relative_path in self.component_files:
+            source = project_root / relative_path
+            # Install to superclaude/ subdirectory structure
+            target = self.install_component_subdir / relative_path
+            files.append((source, target))
+
+        return files
+
+    def get_size_estimate(self) -> int:
+        """Get estimated installation size"""
+        total_size = 0
+
+        for source, _ in self.get_files_to_install():
+            if source.exists():
+                total_size += source.stat().st_size
+
+        # Add overhead for settings.json and directories
+        total_size += 10240  # ~10KB overhead
+
+        return total_size
+
+    def get_installation_summary(self) -> Dict[str, Any]:
+        """Get installation summary"""
+        return {
+            "component": self.get_metadata()["name"],
+            "version": self.get_metadata()["version"],
+            "files_installed": len(self.component_files),
+            "framework_files": self.component_files,
+            "estimated_size": self.get_size_estimate(),
+            "install_directory": str(self.install_dir),
+            "dependencies": self.get_dependencies(),
+        }

setup/components/mcp_integration.py

@@ -1,5 +1,8 @@
 """
-MCP component for MCP server integration
+MCP Integration Component
+
+Responsibility: Integrates Model Context Protocol for external tool access.
+Manages connections to specialized MCP servers and capabilities.
 """
 
 import os
@@ -15,7 +18,7 @@ from setup import __version__
 from ..core.base import Component
 
 
-class MCPComponent(Component):
+class MCPIntegrationComponent(Component):
     """MCP servers integration component"""
 
     def __init__(self, install_dir: Optional[Path] = None):
@@ -941,7 +944,7 @@ class MCPComponent(Component):
 
     def get_dependencies(self) -> List[str]:
         """Get dependencies"""
-        return ["framework_docs"]
+        return ["knowledge_base"]
 
     def update(self, config: Dict[str, Any]) -> bool:
         """Update MCP component"""

setup/components/slash_commands.py

@@ -1,5 +1,8 @@
 """
-Commands component for SuperClaude slash command definitions
+Slash Commands Component
+
+Responsibility: Registers and manages slash commands for CLI interactions.
+Provides custom command definitions and execution logic.
 """
 
 from typing import Dict, List, Tuple, Optional, Any
@@ -9,7 +12,7 @@ from ..core.base import Component
 from setup import __version__
 
 
-class CommandsComponent(Component):
+class SlashCommandsComponent(Component):
     """SuperClaude slash commands component"""
 
     def __init__(self, install_dir: Optional[Path] = None):
@@ -180,7 +183,7 @@ class CommandsComponent(Component):
 
     def get_dependencies(self) -> List[str]:
         """Get dependencies"""
-        return ["framework_docs"]
+        return ["knowledge_base"]
 
     def update(self, config: Dict[str, Any]) -> bool:
         """

setup/core/installer.py

@@ -149,7 +149,7 @@ class Installer:
 
         # Framework components are ALWAYS updated to latest version
         # These are SuperClaude implementation files, not user configurations
-        framework_components = {'framework_docs', 'agents', 'commands', 'modes', 'core', 'mcp'}
+        framework_components = {'knowledge_base', 'agents', 'commands', 'modes', 'core', 'mcp'}
 
         if component_name in framework_components:
             # Always update framework components to latest version

superclaude/cli/commands/install.py

@@ -149,7 +149,7 @@ def _run_installation(
             verbose=verbose,
             quiet=False,
             yes=True,  # Always non-interactive
-            components=["framework_docs", "modes", "commands", "agents"],  # Full install (mcp integrated into airis-mcp-gateway)
+            components=["knowledge_base", "modes", "commands", "agents"],  # Full install (mcp integrated into airis-mcp-gateway)
             no_backup=False,
             list_components=False,
             diagnose=False,