Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
188 commits
Select commit Hold shift + click to select a range
926ca36
Initial commit: Ghidra MCP plugin and Python bridge server
Aug 30, 2025
a6fa758
Merge branch 'main' of github.com:bethington/ghidra-mcp
Aug 30, 2025
8d038f8
Update to Ghidra 11.4.2 and add deployment automation
Aug 30, 2025
62eb56b
Add new MCP tools: get_function_jump_target_addresses and create_label
Sep 16, 2025
e44b5dd
Add Core Data Type Tools for Ghidra MCP
Sep 16, 2025
6e41835
Upgrade Java runtime to version 21
Sep 23, 2025
1f00e65
Complete package rename and comprehensive test suite overhaul
Sep 23, 2025
4cd195d
feat: comprehensive project modernization and quality improvements
Sep 23, 2025
32d16bb
feat: add comprehensive GitHub Actions release workflows
Sep 24, 2025
fb36487
fix: enhance zip file handling in GitHub Actions workflows
Sep 24, 2025
0f2b313
fix: enhance release workflow debugging and file handling
Sep 24, 2025
ae4d6e6
feat: Implement calling convention support and major project cleanup
Sep 30, 2025
e92dbdf
feat: v1.3.0 - code review fixes, cleanup, and new tooling
bethington Oct 10, 2025
66815de
feat: v1.5.1 - Batch operations, ROADMAP documentation, and project c…
bethington Oct 10, 2025
b5cf238
feat: Auto-detect version in deploy-to-ghidra.ps1 script
bethington Oct 10, 2025
61d0af7
docs: comprehensive documentation review and v1.5.1 alignment
bethington Oct 10, 2025
e4b7292
docs: update DOCUMENTATION_INDEX to reflect v1.5.1 structure
bethington Oct 10, 2025
792294a
docs: remove project-specific research file
bethington Oct 10, 2025
701dc4d
docs: rewrite UNIFIED_ANALYSIS_PROMPT for Claude 4.5 optimization
bethington Oct 10, 2025
b9789f9
feat(v1.6.0): Add validation tools, enhance search, reorganize docume…
bethington Oct 10, 2025
2fb74fd
docs: add optimized function documentation prompts
bethington Oct 11, 2025
ed13979
feat(v1.6.1): Performance fixes - event flushing and per-endpoint tim…
bethington Oct 11, 2025
752f357
docs: rewrite function documentation workflow for improved clarity
bethington Oct 11, 2025
c765204
feat(v1.6.3): Fix batch_rename_variables timeout with event suppression
bethington Oct 11, 2025
8c90abd
Release v1.7.3: Fix disassemble_bytes transaction commit
bethington Oct 13, 2025
d29f33f
feat(v1.8.0): Add comprehensive reverse engineering documentation suite
bethington Oct 16, 2025
dcd0c17
chore: Reorganize project structure for better maintainability
bethington Oct 16, 2025
023bb77
feat: Add reverse engineering utility scripts
bethington Oct 16, 2025
f11fe95
chore: Update version to 1.8.0 across all project files
bethington Oct 16, 2025
d37c9d4
chore: Update GhidraMCPPlugin @PluginInfo to v1.8.0
bethington Oct 16, 2025
891eddc
feat: Define __d2edicall calling convention for EDI-based context pas…
bethington Oct 24, 2025
5c37bb2
docs: Record __d2edicall installation in x86win.cspec
bethington Oct 24, 2025
de08e85
docs: Document successful __d2edicall application to BuildNearbyRooms…
bethington Oct 24, 2025
112fdb6
docs: Add __d2edicall to function documentation workflow
bethington Oct 24, 2025
8b609c3
docs: Reorganize project structure and consolidate documentation
bethington Oct 25, 2025
76ef5a0
chore: Bump version to 1.8.1
bethington Oct 25, 2025
3c81ac5
fix: Update remaining version references from 1.8.0 to 1.8.1
bethington Oct 25, 2025
a4294d8
docs: Add comprehensive version update checklist
bethington Oct 25, 2025
75e3177
docs: Update CLAUDE.md with current project information
bethington Oct 25, 2025
aab8ef7
docs: Fix prompt tool usage patterns to avoid retries
bethington Oct 26, 2025
fe7d912
Release v1.9.2: Documentation organization and production readiness
bethington Nov 7, 2025
a861f1f
Add comprehensive project documentation and tools
bethington Nov 7, 2025
dc07167
Complete comprehensive data analysis of Game.exe
bethington Nov 7, 2025
c26e0ba
docs: Improve FUNCTION_DOC_WORKFLOW_V2.md with variable renaming guid…
bethington Nov 8, 2025
dcbeb1a
docs: Improve FUNCTION_DOC_WORKFLOW_V2.md with explicit variable rena…
bethington Nov 8, 2025
3e48409
docs: CRITICAL FIX - Document Ghidra variable renaming limitation
bethington Nov 8, 2025
3c1f631
Fix analyze_function_completeness to detect undefined types
bethington Nov 8, 2025
a36ff30
feat: Enhance completeness tool with plate comment structure validation
bethington Nov 8, 2025
5c8f488
feat: Add Hungarian notation validation to completeness tool
bethington Nov 8, 2025
72a4820
Release v1.9.3: Documentation organization and workflow enhancements
bethington Nov 14, 2025
cbcf991
docs: Add DATA_TYPE_INVESTIGATION_WORKFLOW.md prompt
bethington Nov 21, 2025
6b49aac
docs: Add paragraph-long quick reference for data type investigation …
bethington Nov 21, 2025
9571e6b
feat: Add autonomous workflow system with Ghidra process management
bethington Nov 26, 2025
a73428e
feat: Add auto-recovery, session persistence, and logging to workflows
bethington Nov 26, 2025
6293ac3
Add parallel function processing and workflow modules
bethington Dec 2, 2025
17310c0
feat: Add program management tools and enhanced documentation workflows
bethington Dec 3, 2025
92cec6a
feat: Add Function Hash Index for cross-binary documentation propagation
bethington Dec 4, 2025
55315f5
docs: Update documentation for v1.9.4 Function Hash Index tools
bethington Dec 4, 2025
4a445d9
docs: Fix incorrect tool references in workflow documentation
bethington Dec 4, 2025
8fc5763
docs: Fix incorrect tool references across all prompts documentation
bethington Dec 4, 2025
7d839c8
docs: Fix remaining old tool name references across project
bethington Dec 4, 2025
3c962be
feat: Add Ghidra scripts and enhanced function listing for cross-bina…
bethington Dec 4, 2025
5027af6
docs: Add Phase 0 Type Audit Pre-Check to FUNCTION_DOC_WORKFLOW_V2.md
bethington Dec 4, 2025
61eb825
Add make_request function to fix MCP program management tools
bethington Dec 4, 2025
49b2891
feat: Add hash-based function renaming and callee propagation system
bethington Dec 9, 2025
b9434d1
refactor: Add critical reverse engineering analysis phases to FUNCTIO…
bethington Dec 9, 2025
9fd49fc
Streamline function doc workflow V2, add Hungarian notation ref, data…
bethington Dec 10, 2025
a734376
Consolidate FUNCTION_DOC_WORKFLOW_V2.md - reduce from 228 to 120 lines
bethington Dec 10, 2025
0c2ca7e
Add FUNCTION_DOC_WORKFLOW_V4 with Haiku subtask delegation
bethington Dec 10, 2025
70689be
Update all scripts and tools to use FUNCTION_DOC_WORKFLOW_V4
bethington Dec 10, 2025
f0962a5
Add MCP error detection to functions-process.ps1 and cleanup generate…
bethington Dec 10, 2025
d6b7fde
Add workflow milestone tracking to functions-process.ps1
bethington Dec 10, 2025
36a13a9
Add V5.1 workflow with parallel external analysis
bethington Dec 10, 2025
6d11ea7
feat: Add multi-program support to read endpoints
bethington Dec 10, 2025
a99fd58
Fix PowerShell type coercion bug in functions-process.ps1, add genera…
bethington Dec 11, 2025
0c90c1e
Add .gitignore for generated Ghidra scripts and -CleanupScripts option
bethington Dec 11, 2025
9c89c78
Add -ReuseSession for token-efficient Claude calls
bethington Dec 11, 2025
c17d29e
Enable -ReuseSession by default for token savings
bethington Dec 11, 2025
d3e49da
Simplify session reuse: use -NoSessionReuse flag instead of bool
bethington Dec 11, 2025
de71b07
Add library/runtime functions as valid name patterns
bethington Dec 11, 2025
bda72f8
Add unprocessed names as valid + create validation script
bethington Dec 11, 2025
a4a43d4
Convert validate-function-names to Python script
bethington Dec 11, 2025
5ae2f94
Add Python validation script usage to naming docs
bethington Dec 11, 2025
0939fb3
Fix validation script to use list_functions_enhanced JSON endpoint
bethington Dec 11, 2025
2fc3975
Simplify validation tool section in naming docs
bethington Dec 11, 2025
dc83109
Disable session reuse by default + fix MCP error false positives
bethington Dec 11, 2025
03a4d09
Add automatic cleanup of ~/.claude/ session files when using -Session…
bethington Dec 11, 2025
a509ce8
Enable session reuse by default with automatic cleanup
bethington Dec 11, 2025
67d464e
Add compact workflow prompt and improve output parsing
bethington Dec 12, 2025
9e8c9ed
Major refactor: Add cross-version matching, Docker support, and compr…
bethington Jan 2, 2026
9ef9a0c
docs: Add star reminder and related projects to README
bethington Jan 29, 2026
e4a34c5
ci: update deprecated GitHub Actions to latest versions
bethington Feb 3, 2026
743dd12
Merge pull request #2 from bethington/fix/update-deprecated-actions
bethington Feb 4, 2026
2dbb455
fix: bind HTTP server to localhost + add configurable decompile timeout
bethington Feb 3, 2026
eea55bf
Update author to Ben Ethington, fix Ghidra 12.0.2 compatibility, add …
bethington Feb 3, 2026
9e35fc9
chore: env config, accurate changelog, deploy script improvements
bethington Feb 4, 2026
8a0406b
chore: update all Ghidra version references from 11.4.2 to 12.0.2
bethington Feb 4, 2026
fd30c86
Fix Update-TodoFile to match by address for duplicate function names
bethington Feb 4, 2026
89abf7a
Update Ghidra version to 12.0.2 in Dockerfile and project docs
bethington Feb 4, 2026
53e8e30
fix: correct Ghidra 12.0.2 download date + add missing FileSystem.jar
bethington Feb 4, 2026
43cbcf4
Fix integration tests to match current API behavior
bethington Feb 4, 2026
a714d6b
Update remaining 11.4.2 references to 12.0.2 in punit docs
bethington Feb 4, 2026
b5a0500
Apply code formatting to test_phase3_datatypes.py
bethington Feb 4, 2026
2786e63
Add non-destructive integration tests and fix CI workflow
bethington Feb 4, 2026
1a81b1c
Fix CI: Download Ghidra JARs for Java build
bethington Feb 4, 2026
a8d22b5
fix: skip integration tests in CI, fix release workflow
bethington Feb 4, 2026
d281f72
fix: add missing JARs and skip integration tests in build.yml
bethington Feb 4, 2026
af8b4e5
fix: use version-agnostic glob for build artifact copy
bethington Feb 4, 2026
b7440ee
Merge pull request #4 from bethington/fix/ci-java-tests-ghidra-jars
bethington Feb 4, 2026
10df7c5
fix: remove hardcoded path from copy-ghidra-libs.bat, read from .env
bethington Feb 4, 2026
c62d96c
feat: add save_program, exit_ghidra, delete_function, create_memory_b…
heeen Feb 7, 2026
d2a89ff
fix: script execution bugs β€” args support, OSGi path resolution, JSON…
heeen Feb 10, 2026
1a380f7
feat: add fuzzy function matching and structured diff for cross-binar…
heeen Feb 10, 2026
e9741a7
Merge pull request #11 from heeen/feat/new-endpoints
bethington Feb 11, 2026
1364b63
Merge pull request #12 from heeen/fix/script-execution-bugs
bethington Feb 11, 2026
a256392
Merge pull request #13 from heeen/feat/fuzzy-function-matching
bethington Feb 11, 2026
eef8770
feat: Phase 1 - Add memory operations (read_memory, search_memory_str…
bethington Feb 11, 2026
7e07417
Merge pull request #15 from bethington/feature/phase1-multi-binary-me…
bethington Feb 11, 2026
6ff83df
feat: Phase 2 - UI Navigation & Bookmark tools
bethington Feb 11, 2026
0762f0a
Merge pull request #16 from bethington/feature/phase2-ui-navigation-a…
bethington Feb 11, 2026
bc0e252
feat: Phase 3 - Control Flow & Analysis tools
bethington Feb 11, 2026
680b5ae
Merge pull request #17 from bethington/feature/phase3-control-flow-ex…
bethington Feb 11, 2026
0e9556c
refactor(setup): unify setup/deploy flow and apply Maven/PowerShell b…
Pandoriaantje Feb 14, 2026
c237892
Merge pull request #18 from Pandoriaantje/main
bethington Feb 15, 2026
8cc8584
fix(ci): install Ghidra JARs to Maven repository instead of lib/ (#23)
bethington Feb 20, 2026
0c59b04
fix: use semantic version sorting for Ghidra directory detection (#21)
bethington Feb 20, 2026
987304a
docs: add troubleshooting section and verify instructions (#22)
bethington Feb 20, 2026
f3f8a62
build: establish pom.xml as single source of truth for versions (#20)
Pandoriaantje Feb 20, 2026
ab78ae7
chore: bump version to 2.0.1 (#24)
bethington Feb 20, 2026
ee04053
fix(docker): correct Ghidra 12.0.2 release date (#25)
bethington Feb 20, 2026
4f34627
fix(docker): install Ghidra JARs to Maven before build (#26)
bethington Feb 20, 2026
27bf353
feat(headless): add /run_analysis endpoint for auto-analysis (#27)
bethington Feb 20, 2026
6e8a4e8
feat(headless): add /health endpoint for container health checks
bethington Feb 20, 2026
99ea115
chore(docker): update healthcheck to use /health endpoint
bethington Feb 20, 2026
cf1c1ab
Merge pull request #28 from bethington/feature/health-endpoint
bethington Feb 20, 2026
354486c
feat: add Ghidra 12.0.3 support (#29)
bethington Feb 20, 2026
ffc59d2
feat: add pagination support for decompile/disassemble functions (#30)
bethington Feb 20, 2026
439ea7c
chore: release v2.0.2 (#31)
bethington Feb 20, 2026
97ffd9a
Add shared Ghidra server enhancement plan
bethington Feb 21, 2026
3497f71
feat: implement Phase 1 shared Ghidra server support
bethington Feb 21, 2026
0ae655c
feat: implement password authentication for shared server
bethington Feb 21, 2026
e2681c7
feat: add Phase 2 repository browsing endpoints
bethington Feb 21, 2026
5432a61
feat: v3.0.0 β€” MCP tool improvements, workflows, shared server, orpha…
bethington Feb 25, 2026
fd2050f
chore: release v3.0.0 β€” documentation audit and API reference cleanup
bethington Feb 25, 2026
69777f3
docs: add headless endpoint count (172) across all documentation
bethington Feb 25, 2026
26511a2
feat: Add Linux installation support
bethington Feb 25, 2026
30c79b9
fix: remove duplicate headless server line in README
bethington Feb 25, 2026
b7ba3fd
fix: make release workflow use dynamic tool counts from source
bethington Feb 25, 2026
7b72dbc
fix: drop Python 3.8/3.9 from CI matrix (#39)
heeen Feb 27, 2026
3059c37
feat: deployment automation, SSA variable handling, and batch workflo…
bethington Feb 27, 2026
37d6f55
Merge branch 'main' of github.com:bethington/ghidra-mcp
bethington Feb 27, 2026
7877750
feat: add Tools > GhidraMCP server control menu, bump to v3.1.0
bethington Feb 27, 2026
99c41bd
fix: completeness checker accuracy for ordinals, storage types, and H…
bethington Feb 27, 2026
2992f7f
fix: add Help.jar to all CI workflows
bethington Feb 27, 2026
712d32a
chore: add CLAUDE.local.md to .gitignore
bethington Feb 27, 2026
7b1bfd5
fix: cherry-pick bug fixes from PR #38
bethington Feb 27, 2026
7cc8711
chore: bump to v3.2.0, centralize version management
bethington Feb 27, 2026
fa2eefd
fix: rewrite auto-release and pre-release workflows
bethington Feb 27, 2026
fd0d818
test: add project consistency test suite (31 tests)
bethington Feb 27, 2026
450578c
fix: add get_plate_comment endpoint, improve completeness checker
bethington Feb 27, 2026
9d0fc64
feat: completeness checker improvements, batch endpoint, multi-window…
bethington Feb 27, 2026
96ba897
fix: version consistency audit for v3.2.0 release
bethington Feb 27, 2026
99f2b00
feat: add 16 server version control endpoints to GUI plugin
bethington Feb 28, 2026
71f6cff
feat: v4.0.0 service layer refactor β€” extract shared business logic
bethington Feb 28, 2026
ed807e7
fix: rewrite version control endpoints to use Ghidra project API
bethington Feb 28, 2026
c7cd536
feat: migrate plugin to FrontEnd (Project Manager) β€” works without Co…
bethington Feb 28, 2026
37ad3c6
feat: add project/tool management endpoints and MCP tools
bethington Feb 28, 2026
accb6eb
fix: patch FrontEndTool.xml with explicit INCLUDE for plugin auto-load
bethington Feb 28, 2026
74a2290
fix: EDT dispatch for launch_codebrowser, fix deploy version detection
bethington Feb 28, 2026
14f8414
feat: programmatic server authentication, replace SendKeys with Clien…
bethington Feb 28, 2026
efdb6a0
feat: auto-login via ModuleInitializer, fix extension install
bethington Mar 1, 2026
01d56bc
feat: add self-improving RE analysis loop (/re-loop)
bethington Mar 1, 2026
3d943a8
fix: version consistency audit for v4.0.0 release
bethington Mar 1, 2026
7a7ec98
chore: update RE loop state (19 functions, 7 iterations)
bethington Mar 1, 2026
03d22db
feat: add goto_address endpoint for CodeBrowser navigation
bethington Mar 1, 2026
c67f379
feat: server-side checkout visibility + bulk terminate
bethington Mar 1, 2026
2f303d3
feat: batch_apply_documentation endpoint, community cache, Ghidra scr…
bethington Mar 1, 2026
d0a366d
chore: update RE loop state (75 functions, 20 iterations, multi-binary)
bethington Mar 1, 2026
703feb0
feat: universal program parameter + RE loop improvements (v4.1.0)
bethington Mar 1, 2026
4b61cee
feat: add community function name data for D2Common and Fog DLLs
bethington Mar 1, 2026
7342e21
chore: update RE loop state (140 functions, 33 iterations, 4 binaries)
bethington Mar 1, 2026
e8a44e0
feat: add community function name data for D2CMP, D2gfx, D2Lang, D2Wi…
bethington Mar 2, 2026
7a37842
feat: v4.2.0 β€” knowledge DB integration, EndpointRegistry, BSim scrip…
bethington Mar 2, 2026
e3844dc
chore: update RE loop state (787 functions, 158 iterations, D2Common …
bethington Mar 2, 2026
8f1d14e
chore: release prep v4.2.0 - add BSim scripts, fix release docs
bethington Mar 2, 2026
4840162
fix: correct endpoint counts and release workflow counting
bethington Mar 2, 2026
42c0dd1
fix: remove project-specific RE data from tracking, fix null pointer …
bethington Mar 2, 2026
3d115b7
fix: enumerate all CodeBrowser instances in FrontEndProgramProvider (…
bethington Mar 2, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions .env.template
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Environment variables for GhidraMCP
# Copy this file to .env and customize for your environment
# .env is gitignored β€” your local settings stay local

# =============================================================================
# Ghidra Installation
# =============================================================================

# Path to your Ghidra installation directory
# Used by deploy-to-ghidra.ps1 and copy-ghidra-libs scripts
# Examples:
# Windows: GHIDRA_PATH=C:\ghidra_12.0.3_PUBLIC
# Linux: GHIDRA_PATH=/opt/ghidra_12.0.3_PUBLIC
# macOS: GHIDRA_PATH=/Applications/ghidra_12.0.3_PUBLIC
GHIDRA_PATH=

# =============================================================================
# Server Configuration
# =============================================================================

# Ghidra MCP plugin HTTP server (the Java side)
GHIDRA_SERVER_URL=http://127.0.0.1:8089/

# MCP bridge server (the Python side, SSE transport only)
MCP_HOST=127.0.0.1
MCP_PORT=8081

# =============================================================================
# Development Settings
# =============================================================================

# Logging level: DEBUG, INFO, WARNING, ERROR
GHIDRA_MCP_LOG_LEVEL=INFO

# Decompile timeout in seconds (default: 60)
# Increase for complex functions
DECOMPILE_TIMEOUT=60

# =============================================================================
# Knowledge Database (Optional β€” RE-Universe PostgreSQL + pgvector)
# =============================================================================
# Used by knowledge DB MCP tools (store_function_knowledge, query_knowledge_context, etc.)
# The bridge gracefully degrades if the DB is unreachable.
# KNOWLEDGE_DB_HOST=10.0.10.30
# KNOWLEDGE_DB_PORT=5432
# KNOWLEDGE_DB_NAME=bsim
# KNOWLEDGE_DB_USER=ben
# KNOWLEDGE_DB_PASSWORD=
321 changes: 321 additions & 0 deletions .github/MARKDOWN_NAMING_GUIDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,321 @@
# Markdown File Naming Best Practices

> **Standards for naming markdown files** in the Ghidra MCP project.

---

## πŸ“‹ Best Practices Summary

### βœ… Standard Conventions

1. **Use kebab-case** (lowercase with hyphens) for most files
- βœ… `getting-started.md`
- ❌ `GETTING_STARTED.md`

2. **Reserve UPPERCASE** for special files only
- βœ… `README.md` - Entry point documentation
- βœ… `CHANGELOG.md` - Version history (industry standard)
- βœ… `CONTRIBUTING.md` - Contribution guide (GitHub standard)
- βœ… `LICENSE.md` - License file (legal document)

3. **Use descriptive, readable names**
- βœ… `binary-analysis-guide.md`
- ❌ `BAG.md`

4. **Keep it concise** (under 40 characters)
- βœ… `structure-discovery-guide.md`
- ⚠️ `comprehensive-structure-discovery-master-guide-with-examples.md` (too long)

5. **Avoid special characters**
- βœ… `api-reference.md`
- ❌ `api_reference.md` (use hyphens, not underscores)
- ❌ `api reference.md` (no spaces)

6. **Use singular form** unless plural is standard
- βœ… `error-code.md`
- ❌ `error-codes.md` (unless documenting multiple)

---

## πŸ”„ Recommended Renames

### Root Level Files

| Current Name | Recommended Name | Reason | Priority |
|--------------|------------------|--------|----------|
| **Keep As-Is (Industry Standards)** ||||
| `README.md` | βœ… Keep | GitHub/industry standard | - |
| `CHANGELOG.md` | βœ… Keep | Industry standard | - |
| `CONTRIBUTING.md` | βœ… Keep | GitHub standard | - |
| `LICENSE` | βœ… Keep | Legal standard | - |
| **Project Core** ||||
| `START_HERE.md` | `getting-started.md` | More descriptive, kebab-case | High |
| `CLAUDE.md` | `ai-assistant-guide.md` | Generic, descriptive | Medium |
| `DOCUMENTATION_INDEX.md` | `docs-index.md` | Shorter, kebab-case | High |
| `PROJECT_STRUCTURE.md` | `project-structure.md` | Consistent casing | Medium |
| **Configuration** ||||
| `NAMING_CONVENTIONS.md` | `naming-conventions.md` | Kebab-case | Medium |
| `MAVEN_VERSION_MANAGEMENT.md` | `maven-guide.md` | Shorter, clearer | Low |
| **Reports** ||||
| `ORGANIZATION_SUMMARY.md` | `reports/organization-summary.md` | Move to reports/, kebab-case | High |
| `PROJECT_CLEANUP_SUMMARY.md` | `reports/cleanup-summary.md` | Move to reports/, shorter | High |
| `QUICKWIN_COMPLETION_REPORT.md` | `reports/quickwin-report.md` | Move to reports/, shorter | High |
| `SESSION_SUMMARY_BINARY_ANALYSIS.md` | `reports/binary-analysis-session.md` | Move to reports/, clearer order | High |
| `CLEANUP_FINAL_REPORT.md` | `reports/cleanup-final.md` | Move to reports/, shorter | High |
| `VERSION_FIX_COMPLETE.md` | `reports/version-fix-complete.md` | Move to reports/, kebab-case | High |
| `VERSION_MANAGEMENT_COMPLETE.md` | `reports/version-management-complete.md` | Move to reports/, kebab-case | High |
| `VERSION_MANAGEMENT_STRATEGY.md` | `reports/version-management-strategy.md` | Move to reports/, kebab-case | High |
| **Improvements** ||||
| `IMPROVEMENTS.md` | `improvements.md` | Kebab-case | Low |
| `IMPROVEMENTS_QUICK_REFERENCE.md` | `improvements-quick-ref.md` | Shorter, kebab-case | Medium |
| `MCP_TOOLS_IMPROVEMENTS.md` | `mcp-tools-improvements.md` | Kebab-case | Medium |
| `GAME_EXE_IMPROVEMENTS.md` | `game-exe-improvements.md` | Kebab-case | Medium |

---

## πŸ“‚ Directory-Specific Naming

### docs/ Directory

**Pattern**: `<topic>-<type>.md`

Examples:
- `api-reference.md` βœ…
- `development-guide.md` βœ…
- `troubleshooting-guide.md` βœ…
- `error-codes.md` βœ…

### docs/guides/ Directory

**Pattern**: `<subject>-guide.md` or `<subject>-<action>.md`

Examples:
- `ordinal-restoration-guide.md` βœ…
- `structure-discovery-guide.md` βœ…
- `register-reuse-fix.md` βœ…

### docs/analysis/ Directory

**Pattern**: `<binary-name>-analysis.md`

Examples:
- `game-exe-analysis.md` βœ…
- `d2client-analysis.md` βœ…
- `storm-library-analysis.md` βœ…

### docs/reports/ Directory

**Pattern**: `<topic>-report.md` or `<topic>-<date>.md`

Examples:
- `cleanup-report.md` βœ…
- `performance-report-2025-11.md` βœ…
- `organization-summary.md` βœ…

---

## 🎯 Implementation Plan

### Phase 1: Critical Renames (High Priority)

**Impact**: Improves discoverability and consistency

```bash
# Move reports to docs/reports/
mv ORGANIZATION_SUMMARY.md docs/reports/organization-summary.md
mv PROJECT_CLEANUP_SUMMARY.md docs/reports/cleanup-summary.md
mv QUICKWIN_COMPLETION_REPORT.md docs/reports/quickwin-report.md
mv SESSION_SUMMARY_BINARY_ANALYSIS.md docs/reports/binary-analysis-session.md
mv CLEANUP_FINAL_REPORT.md docs/reports/cleanup-final.md
mv VERSION_FIX_COMPLETE.md docs/reports/version-fix-complete.md
mv VERSION_MANAGEMENT_COMPLETE.md docs/reports/version-management-complete.md
mv VERSION_MANAGEMENT_STRATEGY.md docs/reports/version-management-strategy.md

# Rename core files
mv START_HERE.md getting-started.md
mv DOCUMENTATION_INDEX.md docs-index.md
```

### Phase 2: Consistency Updates (Medium Priority)

**Impact**: Consistent naming across project

```bash
# Rename to kebab-case
mv CLAUDE.md ai-assistant-guide.md
mv PROJECT_STRUCTURE.md project-structure.md
mv NAMING_CONVENTIONS.md naming-conventions.md
mv IMPROVEMENTS_QUICK_REFERENCE.md improvements-quick-ref.md
mv MCP_TOOLS_IMPROVEMENTS.md mcp-tools-improvements.md
mv GAME_EXE_IMPROVEMENTS.md game-exe-improvements.md
```

### Phase 3: Reference Updates (Required after renaming)

**Action items**:
1. Update all internal links in markdown files
2. Update references in code/scripts
3. Update VSCode settings
4. Update .gitignore patterns
5. Update CI/CD paths

---

## πŸ“ Naming Rules by File Type

### Documentation Files

| Type | Pattern | Example |
|------|---------|---------|
| Guide | `<topic>-guide.md` | `installation-guide.md` |
| Reference | `<topic>-reference.md` | `api-reference.md` |
| Tutorial | `<topic>-tutorial.md` | `quickstart-tutorial.md` |
| Index | `<category>-index.md` | `docs-index.md` |

### Analysis Files

| Type | Pattern | Example |
|------|---------|---------|
| Binary | `<name>-analysis.md` | `game-exe-analysis.md` |
| Component | `<name>-<component>.md` | `d2client-ui-analysis.md` |
| Overview | `<topic>-overview.md` | `architecture-overview.md` |

### Report Files

| Type | Pattern | Example |
|------|---------|---------|
| Status | `<topic>-status.md` | `project-status.md` |
| Summary | `<topic>-summary.md` | `cleanup-summary.md` |
| Report | `<topic>-report.md` | `performance-report.md` |
| Dated | `<topic>-YYYY-MM.md` | `milestone-2025-11.md` |

### Configuration Files

| Type | Pattern | Example |
|------|---------|---------|
| Standards | `<topic>-conventions.md` | `naming-conventions.md` |
| Config Guide | `<tool>-guide.md` | `maven-guide.md` |
| Setup | `<topic>-setup.md` | `environment-setup.md` |

---

## βœ… Checklist for New Files

Before creating a new markdown file:

- [ ] Use kebab-case (lowercase with hyphens)
- [ ] Keep name under 40 characters
- [ ] Make it descriptive and searchable
- [ ] Follow directory-specific patterns
- [ ] Avoid abbreviations unless widely known
- [ ] Check for similar existing files
- [ ] Add to appropriate index file
- [ ] Use `.md` extension (not `.markdown`)

---

## πŸ” Special Cases

### When to Use UPPERCASE

**ONLY for these standard files**:
- `README.md` - Primary documentation entry
- `CHANGELOG.md` - Version history (Keep-a-Changelog standard)
- `CONTRIBUTING.md` - Contribution guidelines (GitHub standard)
- `LICENSE` or `LICENSE.md` - Legal license file
- `CODE_OF_CONDUCT.md` - Community standards (GitHub standard)
- `SECURITY.md` - Security policies (GitHub standard)

### When to Use Underscores

**AVOID** underscores in markdown files. Use hyphens instead.

Exception: Generated files that must match tool conventions.

### When to Use Numbers

**Prefix with zero** for ordering:
- βœ… `01-introduction.md`
- βœ… `02-installation.md`
- βœ… `03-usage.md`

**Date suffixes**:
- βœ… `report-2025-11-06.md`
- ❌ `report-11-6-2025.md`

---

## πŸ“Š Impact Analysis

### Benefits of Standardization

1. **Improved Discoverability**
- Files easier to find with predictable patterns
- Better IDE autocomplete

2. **Consistency**
- Uniform appearance in file listings
- Professional presentation

3. **Maintainability**
- Clear naming conventions for contributors
- Reduced confusion

4. **SEO/Search**
- Better search results with descriptive names
- Easier to remember and share

### Migration Effort

| Phase | Files Affected | Effort | Risk |
|-------|----------------|--------|------|
| Phase 1 | 8 reports | 1-2 hours | Low |
| Phase 2 | 6 core files | 2-3 hours | Medium |
| Phase 3 | Link updates | 3-4 hours | Medium |
| **Total** | **14 files** | **6-9 hours** | **Low-Medium** |

---

## πŸš€ Migration Strategy

### Safe Renaming Process

1. **Create branch**
```bash
git checkout -b standardize-markdown-names
```

2. **Rename files** (preserves history)
```bash
git mv OLD_NAME.md new-name.md
```

3. **Update references**
- Search and replace in all markdown files
- Update scripts and code references
- Update documentation indexes

4. **Test**
- Verify all links work
- Check CI/CD pipelines
- Test local builds

5. **Commit and PR**
```bash
git commit -m "refactor: standardize markdown file naming conventions"
```

---

## πŸ“š References

- [GitHub Documentation Standards](https://docs.github.com/en/communities)
- [Keep a Changelog](https://keepachangelog.com/)
- [Semantic File Names](https://semver.org/)
- [Markdown Guide](https://www.markdownguide.org/basic-syntax/)

---

**Last Updated**: November 6, 2025
**Version**: 1.0.0
**Status**: Proposed Standard
Loading