docs(structure): split README into focused documentation files

- Extract troubleshooting guide to TROUBLESHOOTING.md
- Move usage examples to USAGE_EXAMPLES.md for better discoverability
- Add custom specialty creation guide to CONTRIBUTIONS.md
- Create semantic commit message generator prompt in prompts/
- Streamline README.md by removing 200+ lines of content now in dedicated files
- Improve documentation navigation with clearer separation of concerns

.github/prompts/create-commit.msg.prompt.md

@@ -0,0 +1,43 @@
+---
+description: "VS Code Commit Generator: Analyzes git diff + project context to write semantic messages."
+---
+
+# Semantic Commit Message Generator (VS Code Edition)
+
+## Goal
+Analyze staged changes and synthesize a strictly formatted [Conventional Commit](https://www.conventionalcommits.org/) message.
+**Crucial Upgrade:** You must correlate the code changes (What) with the active session context (Why) retrieved from the workspace.
+
+## Phase 1: Context Retrieval (RAG)
+**Execute these lookups to ground your analysis:**
+1.  **Get the "What" (Code):**
+    * Run: `git diff --cached` (If empty, warn user to stage files first).
+2.  **Get the "Why" (Intent):**
+    * **Search Workspace:** Find the most recent `SESSION_SNAPSHOT*.md` in `documentation/project-history/`.
+    * **Search Workspace:** Look for `TODO` or `// RESTART NOTE` comments in the changed files themselves.
+    * *Reasoning:* A commit message is better if it says "feat(auth): enable TFA per session plan" rather than just "feat(auth): update config".
+
+## Phase 2: Change Analysis (Chain of Thought)
+*Reference: `.github/knowledge/example.CoT-Prompting.md`*
+
+Analyze the combined inputs (Diff + Session Context):
+1.  **Type Determination:**
+    * `feat`: New features (check against Session Snapshot "Achievements").
+    * `fix`: Bug fixes (check against Session Snapshot "Blockers").
+    * `chore`/`refactor`/`docs`: Maintenance/Refactoring/Documentation.
+2.  **Scope Identification:** Narrow to the specific module (e.g., `core`, `auth`, `docs`).
+3.  **Breaking Change Check:** Does this modify `compose.yaml` ports or volume paths? If yes, flag as `BREAKING CHANGE`.
+
+## Phase 3: Message Synthesis
+Draft the message using the **Conventional Commits** standard.
+
+**Format Template:**
+```text
+<type>(<scope>): <imperative summary (max 50 chars)>
+
+<blank line>
+
+- <bullet point connecting change to specific file>
+- <bullet point explaining the 'why' based on session context>
+
+<optional: Footer for BREAKING CHANGE or 'Ref: #IssueID'>

CONTRIBUTIONS.md

@@ -14,3 +14,34 @@ Want to contribute a specialty or improve existing modules?
 - Document in frontmatter
 - Include examples in workflows
 - Test with Frank.core independently
+
+## 🎨 Creating Custom Specialties
+
+Want to add your own domain expertise? Use the template:
+
+1. **Copy the template**:
+
+   ```bash
+   cp v6/specialties/specialty.TEMPLATE.instructions.md v6/specialties/specialty.legal.instructions.md
+   ```
+
+2. **Customize sections**:
+   - Replace placeholder text with your domain
+   - Define 2-5 expert personas
+   - Create 3-7 slash commands
+   - Document 2-5 key workflows
+   - Reference relevant skills
+
+3. **Test integration**:
+
+   Ensure your specialty works with Frank.core by loading it in a test environment:
+   ```plaintext
+   Load: v6/Frank.core.agent.md + v6/specialties/specialty.legal.instructions.md
+   ```
+
+4. **Share** (optional):
+
+   Your custom specialty can be shared with others - just distribute the file!
+
+**See**: [specialty.TEMPLATE.instructions.md](.github/specialties/specialty.TEMPLATE.instructions.md) for detailed guidance
+

README.md

@@ -12,11 +12,12 @@
 
 Load just the core for a friendly, mentoring assistant with universal capabilities:
 
-```
+```plaintext
 Load: v6/Frank.core.agent.md
 ```
 
 **You get**:
+
 - Upbeat, friendly, mentoring personality
 - 7 universal personas (Project Manager, Information Architect, Technical Writer, QA Analyst, Editor, Communications Lead, Business Analyst)
 - 8 base commands: `/quickstart`, `/create`, `/review`, `/refactor`, `/document`, `/communicate`, `/consult`, `/help`
@@ -25,7 +26,7 @@ Load: v6/Frank.core.agent.md
 
 Add advanced reasoning techniques for complex problem-solving:
 
-```
+```plaintext
 Load: 
 - v6/Frank.core.agent.md
 - v6/skills/style.cot.instructions.md (Chain-of-Thought)
@@ -40,7 +41,7 @@ Load:
 Load a specialty module for domain-specific expertise:
 
 **Frank for DevOps**:
-```
+```plaintext
 Load:
 - v6/Frank.core.agent.md
 - v6/specialties/specialty.devops.instructions.md
@@ -48,7 +49,7 @@ Commands: /docker, /ansible, /compose, /traefik
 ```
 
 **Frank for Data Analysis**:
-```
+```plaintext
 Load:
 - v6/Frank.core.agent.md
 - v6/specialties/specialty.data-analysis.instructions.md
@@ -56,20 +57,18 @@ Commands: /analyze, /query, /visualize, /model, /clean
 ```
 
 **Frank for IT Service Management**:
-```
+```plaintext
 Load:
 - v6/Frank.core.agent.md
 - v6/specialties/specialty.itil.instructions.md
 Commands: /ticket, /rca, /sop, /itil
 ```
 
-**See**: [All Available Specialties](#available-specialties)
-
 ### Option 4: Multi-Specialty Composition
 
 Combine multiple specialties for cross-domain expertise:
 
-```
+```plaintext
 Load:
 - v6/Frank.core.agent.md
 - v6/specialties/specialty.devops.instructions.md
@@ -84,30 +83,35 @@ Load:
 ## 🎯 Available Specialties
 
 ### DevOps & Site Reliability Engineering
+
 **File**: `specialty.devops.instructions.md`  
 **Commands**: `/docker`, `/ansible`, `/compose`, `/traefik`  
 **Expertise**: Container orchestration, infrastructure automation, Traefik routing, safe deployment strategies  
 **Use When**: Troubleshooting Docker/Compose, writing Ansible playbooks, designing IaC solutions
 
 ### Prompt Engineering & LLM Optimization
+
 **File**: `specialty.prompt-engineering.instructions.md`  
 **Commands**: `/optimize`, `/craft`, `/reason`, `/evaluate`, `/patterns`  
 **Expertise**: LLM optimization, C.R.A.F.T. framework mastery, reasoning technique integration  
 **Use When**: Creating production prompts, optimizing existing prompts, integrating CoT/ToT/RAG
 
 ### Data Analysis & Visualization
+
 **File**: `specialty.data-analysis.instructions.md`  
 **Commands**: `/analyze`, `/query`, `/visualize`, `/model`, `/clean`  
 **Expertise**: SQL, Python (Pandas, Matplotlib, Seaborn), statistical modeling, SCoT methodology  
 **Use When**: Analyzing datasets, writing queries, creating visualizations, statistical analysis
 
 ### Modern Endpoint Management
+
 **File**: `specialty.sccm.instructions.md`  
 **Commands**: `/sccm`, `/intune`, `/comanage`, `/package`, `/troubleshoot`  
 **Expertise**: SCCM/Intune, Co-management, compliance policies, Win32 app packaging  
 **Use When**: Managing endpoints, deploying apps, configuring compliance, migrating to Intune
 
 ### IT Service Management (ITIL v4)
+
 **File**: `specialty.itil.instructions.md`  
 **Commands**: `/ticket`, `/rca`, `/sop`, `/itil`  
 **Expertise**: Incident Management, Problem Management, Knowledge Management, ITIL v4 framework  
@@ -130,7 +134,7 @@ The copilot-instructions.md file pre-configures common loading patterns.
 
 In any Copilot Chat, use `#file` to reference:
 
-```
+```plaintext
 @workspace Load #file:v6/Frank.core.agent.md and #file:v6/specialties/specialty.devops.instructions.md
 
 Now help me troubleshoot this Docker Compose issue...
@@ -138,219 +142,41 @@ Now help me troubleshoot this Docker Compose issue...
 
 ### Method 3: Direct File Reference
 
-Copy the content you need directly into your chat context, or use VS Code's "Add to Chat" feature on the files.
+Copy the content you need directly into your LLM chat of choice.
 
 **See**: [copilot-instructions.md](copilot-instructions.md) for pre-configured patterns
 
 ---
 
-## 💡 Usage Examples
-
-### Example 1: Creating a Technical Document
-
-```
-User: "I need to create API documentation for our REST service"
-
-Frank (Core): "I'll guide you through creating comprehensive API documentation.
-Let me use the Technical Writer persona and Documentation workflow..."
-
-[Walks through structure, audience, content gathering, drafting]
-```
-
-### Example 2: DevOps Troubleshooting
-
-```
-User: "My Docker Compose stack won't start, getting network errors"
-
-Frank (Core + DevOps): "I'll help diagnose this. Triggering DevOps SRE persona.
-Let me gather diagnostics..."
-
-[Requests specific outputs, analyzes logs, proposes minimal fix with verification steps]
-```
-
-### Example 3: Data Analysis with Reasoning
-
-```
-User: "Analyze Q1 sales data and identify trends"
-
-Frank (Core + Data Analysis + CoT): "I'll analyze this using Structured Chain-of-Thought.
-
-## 1. Clarify & Define
-Your objective: Identify sales trends in Q1 data
-Key sources: sales table, customers table
-Success criteria: Actionable insights with visualizations
-
-## 2. Repository Check
-[Reviews existing scripts]
-
-## 3. Plan & Methodology
-[Outlines analytical steps]
-..."
-```
-
-### Example 4: Root Cause Analysis with ITIL
-
-```
-User: "Email server has been slow all week, need to find root cause"
-
-Frank (Core + ITIL): "I'll conduct a root cause analysis using ITIL Problem Management.
-Triggering Problem Manager persona with Tree-of-Thought analysis..."
-
-[Gathers timeline, generates hypotheses, evaluates evidence, documents RCA]
-```
-
-### Example 5: Multi-Specialty Composition
-
-```
-Load: Core + DevOps + Data Analysis
-
-User: "Help me analyze Docker container metrics and visualize resource usage"
-
-Frank: "This combines my DevOps and Data Analysis expertise.
-I'll use Docker diagnostic commands to gather metrics, then Python/Pandas for analysis..."
-
-[Bridges both domains seamlessly]
-```
-
----
-
-## 🎨 Creating Custom Specialties
-
-Want to add your own domain expertise? Use the template:
-
-1. **Copy the template**:
-   ```bash
-   cp v6/specialties/specialty.TEMPLATE.instructions.md v6/specialties/specialty.legal.instructions.md
-   ```
-
-2. **Customize sections**:
-   - Replace placeholder text with your domain
-   - Define 2-5 expert personas
-   - Create 3-7 slash commands
-   - Document 2-5 key workflows
-   - Reference relevant skills
-
-3. **Test integration**:
-   ```
-   Load: v6/Frank.core.agent.md + v6/specialties/specialty.legal.instructions.md
-   ```
-
-4. **Share** (optional):
-   Your custom specialty can be shared with others - just distribute the file!
-
-**See**: [specialty.TEMPLATE.instructions.md](specialties/specialty.TEMPLATE.instructions.md) for detailed guidance
-
----
-
 ## 🏗️ Design Principles
 
 ### 1. Portability First
+
 - **Zero environment coupling**: No hardcoded paths, no system-specific references
 - **Relative paths only**: All cross-references use `../skills/`, `../knowledge/` patterns
 - **"Pick up and go"**: Copy the v6/ folder to any system and it works
 
 ### 2. Modularity
+
 - **Core is self-sufficient**: Works alone without dependencies
 - **Skills enhance**: Add reasoning techniques as needed
 - **Specialties compose**: Load multiple domains without conflicts
 - **Knowledge is reference**: Shared examples available to all layers
 
 ### 3. Versioning
+
 - **All files tagged**: `version: 6.0` in frontmatter
 - **Compatibility tracked**: `compatibleWith: Frank.core v6+`
 - **Forward compatible**: v6+ notation allows future evolution
 
 ### 4. Multi-Specialty Support
+
 - **No command conflicts**: Each specialty uses domain-specific commands
 - **Shared skills**: Multiple specialties can reference same CoT/ToT/RAG modules
 - **Conflict resolution**: When overlaps exist, documentation explains disambiguation
 
 ---
 
-## 📊 Project Structure
-
-```
-v6/
-├── README.md                          ← You are here
-├── ARCHITECTURE.md                    ← Detailed architecture guide
-├── copilot-instructions.md            ← VS Code integration
-├── Frank.core.agent.md                ← Core personality (REQUIRED)
-├── skills/                            ← Reasoning techniques (OPTIONAL)
-│   ├── style.advanced-reasoning.instructions.md
-│   ├── style.cot.instructions.md
-│   ├── style.craft.instructions.md
-│   ├── style.markdown.instructions.md
-│   ├── style.mermaid.instructions.md
-│   ├── style.rag.instructions.md
-│   └── style.tot.instructions.md
-├── specialties/                       ← Domain expertise (OPTIONAL)
-│   ├── specialty.data-analysis.instructions.md
-│   ├── specialty.devops.instructions.md
-│   ├── specialty.itil.instructions.md
-│   ├── specialty.prompt-engineering.instructions.md
-│   ├── specialty.sccm.instructions.md
-│   └── specialty.TEMPLATE.instructions.md
-└── knowledge/                         ← Reference examples
-    ├── example.CoT-Prompting.md
-    ├── example.ITILv4.instructions.md
-    ├── example.Meta-Prompting.md
-    ├── example.RAG-Token.md
-    ├── example.ReAct.md
-    └── example.ToT-Prompting.md
-```
-
-**Total**: 23 files, ~5,600 lines, fully modular
-
----
-
-## 🔧 Troubleshooting
-
-### Frank isn't responding to specialty commands
-
-**Check**: Are you loading both Frank.core AND the specialty?
-```
-# Correct:
-Load: Frank.core.agent.md + specialty.devops.instructions.md
-
-# Incorrect (core alone doesn't have /docker):
-Load: Frank.core.agent.md
-```
-
-### Commands from multiple specialties conflict
-
-**Check**: Do the specialties actually conflict, or are they complementary?
-- `/docker` (DevOps) and `/analyze` (Data Analysis) don't conflict
-- If true conflict exists, specify domain: "Use DevOps /troubleshoot" vs "Use Data Analysis workflow"
-
-### Skills aren't being applied
-
-**Check**: Skills are passive references - specialties or core must explicitly invoke them
-- Frank.core references C.R.A.F.T. framework for prompt evaluation
-- specialty.prompt-engineering deeply integrates all skills
-- Loading skills alone without core/specialty won't trigger behaviors
-
-### Cross-references not working
-
-**Check**: All paths are relative from v6/ root
-- Correct: `../skills/style.cot.instructions.md`
-- Incorrect: `/skills/style.cot.instructions.md` or absolute paths
-
----
-
-## 🚀 Roadmap
-
-### v6.1 (Future)
-- [ ] Additional specialties: Security, Cloud Architecture, Database Design
-- [ ] Enhanced multi-specialty conflict resolution
-- [ ] Knowledge base expansion with more examples
-
-### v7.0 (Future)
-- [ ] Dynamic specialty loading based on conversation context
-- [ ] Auto-detection of required skills
-- [ ] Specialty versioning and compatibility matrix
-
----
-
 ## 📜 Version History
 
 ### v6.0 (April 2026)
@@ -377,25 +203,6 @@ Load: Frank.core.agent.md
 
 ---
 
-## 📞 Support
-
-**Documentation**:
-- Quick start: This file (README.md)
-- Architecture deep-dive: [ARCHITECTURE.md](ARCHITECTURE.md)
-- VS Code setup: [copilot-instructions.md](copilot-instructions.md)
-- Template guide: [specialty.TEMPLATE.instructions.md](specialties/specialty.TEMPLATE.instructions.md)
-
-**Need help**?
-- Review [ARCHITECTURE.md](ARCHITECTURE.md) for detailed patterns
-- Check individual specialty files for domain-specific guidance
-- Load `specialty.prompt-engineering.instructions.md` to optimize your own prompts
-
----
-
 ## 📄 License
 
 This is a personal AI assistant framework. Use, modify, and extend as needed for your projects.
-
----
-
-**Frank v6**: Modular. Portable. Composable. Pick up and go. 🚀

TROUBLESHOOTING.md

@@ -0,0 +1,50 @@
+# 📞 Support and Troubleshooting
+
+## Documentation
+
+- Quick start: This file (README.md)
+- Architecture deep-dive: [ARCHITECTURE.md](ARCHITECTURE.md)
+- VS Code setup: [copilot-instructions.md](copilot-instructions.md)
+- Template guide: [specialty.TEMPLATE.instructions.md](specialties/specialty.TEMPLATE.instructions.md)
+
+## Need help?
+
+- Review [ARCHITECTURE.md](ARCHITECTURE.md) for detailed patterns
+- Check individual specialty files for domain-specific guidance
+- Load `specialty.prompt-engineering.instructions.md` to optimize your own prompts
+
+## Troubleshooting
+
+### Frank isn't responding to specialty commands
+
+**Check**: Are you loading both Frank.core AND the specialty?
+
+```plaintext
+# Correct:
+Load: Frank.core.agent.md + specialty.devops.instructions.md
+
+# Incorrect (core alone doesn't have /docker):
+Load: Frank.core.agent.md
+```
+
+### Commands from multiple specialties conflict
+
+**Check**: Do the specialties actually conflict, or are they complementary?
+
+- `/docker` (DevOps) and `/analyze` (Data Analysis) don't conflict
+- If true conflict exists, specify domain: "Use DevOps /troubleshoot" vs "Use Data Analysis workflow"
+
+### Skills aren't being applied
+
+**Check**: Skills are passive references - specialties or core must explicitly invoke them
+
+- Frank.core references C.R.A.F.T. framework for prompt evaluation
+- specialty.prompt-engineering deeply integrates all skills
+- Loading skills alone without core/specialty won't trigger behaviors
+
+### Cross-references not working
+
+**Check**: All paths are relative from v6/ root
+
+- Correct: `../skills/style.cot.instructions.md`
+- Incorrect: `/skills/style.cot.instructions.md` or absolute paths

USAGE_EXAMPLES.md

@@ -0,0 +1,67 @@
+# 💡 Usage Examples
+
+## Example 1: Creating a Technical Document
+
+```plaintext
+User: "I need to create API documentation for our REST service"
+
+Frank (Core): "I'll guide you through creating comprehensive API documentation.
+Let me use the Technical Writer persona and Documentation workflow..."
+
+[Walks through structure, audience, content gathering, drafting]
+```
+
+## Example 2: DevOps Troubleshooting
+
+```plaintext
+User: "My Docker Compose stack won't start, getting network errors"
+
+Frank (Core + DevOps): "I'll help diagnose this. Triggering DevOps SRE persona.
+Let me gather diagnostics..."
+
+[Requests specific outputs, analyzes logs, proposes minimal fix with verification steps]
+```
+
+## Example 3: Data Analysis with Reasoning
+
+```plaintext
+User: "Analyze Q1 sales data and identify trends"
+
+Frank (Core + Data Analysis + CoT): "I'll analyze this using Structured Chain-of-Thought.
+
+## 1. Clarify & Define
+Your objective: Identify sales trends in Q1 data
+Key sources: sales table, customers table
+Success criteria: Actionable insights with visualizations
+
+## 2. Repository Check
+[Reviews existing scripts]
+
+## 3. Plan & Methodology
+[Outlines analytical steps]
+..."
+```
+
+## Example 4: Root Cause Analysis with ITIL
+
+```plaintext
+User: "Email server has been slow all week, need to find root cause"
+
+Frank (Core + ITIL): "I'll conduct a root cause analysis using ITIL Problem Management.
+Triggering Problem Manager persona with Tree-of-Thought analysis..."
+
+[Gathers timeline, generates hypotheses, evaluates evidence, documents RCA]
+```
+
+## Example 5: Multi-Specialty Composition
+
+```plaintext
+Load: Core + DevOps + Data Analysis
+
+User: "Help me analyze Docker container metrics and visualize resource usage"
+
+Frank: "This combines my DevOps and Data Analysis expertise.
+I'll use Docker diagnostic commands to gather metrics, then Python/Pandas for analysis..."
+
+[Bridges both domains seamlessly]
+```