feat: comprehensive codebase improvements for production readiness

This major refactor enhances marksman.nvim's robustness, performance, and maintainability while preserving full backward compatibility.
The plugin now provides better error handling, memory management, and user experience improvements.

Author: alexekdahl

CONTRIBUTING.md

@@ -0,0 +1,254 @@
+# Contributing to Marksman.nvim
+
+Thank you for your interest in contributing to Marksman.nvim! This document provides guidelines for contributing to this project.
+
+## Getting Started
+
+1. **Fork the repository** and clone your fork locally
+2. **Create a new branch** for your feature or bug fix
+3. **Test your changes** thoroughly
+4. **Submit a pull request** with a clear description
+
+## Development Setup
+
+### Prerequisites
+- Neovim >= 0.8.0
+- Git
+- Lua 5.1+ (for testing outside Neovim)
+
+### Code Quality Tools
+```bash
+# Install luacheck for linting
+luarocks install luacheck
+
+# Install stylua for formatting
+cargo install stylua
+
+# Run linting
+luacheck lua/
+
+# Run formatting
+stylua lua/
+```
+
+## Code Style
+
+### Lua Style Guidelines
+- Use **snake_case** for functions and variables
+- Use **PascalCase** for classes/modules
+- **Indent with tabs** (width: 4)
+- **Line length**: 100 characters max
+- **Use meaningful variable names**
+
+### Documentation
+- Add **JSDoc-style comments** for public functions
+- Include **@param** and **@return** annotations
+- Document **complex logic** with inline comments
+
+Example:
+```lua
+---Add a mark at the current cursor position
+---@param name string|nil Optional mark name (auto-generated if nil)
+---@param description string|nil Optional mark description
+---@return table result Result with success, message, and mark_name
+function M.add_mark(name, description)
+    -- Implementation here
+end
+```
+
+## Project Structure
+
+```
+lua/marksman/
+├── init.lua      -- Main plugin entry point
+├── storage.lua   -- Mark persistence and project management
+├── ui.lua        -- Floating window and interface
+└── utils.lua     -- Utilities and validation
+```
+
+## Contribution Types
+
+### Bug Fixes
+1. **Create an issue** describing the bug
+2. **Include reproduction steps** and expected behavior
+3. **Write a test case** if applicable
+4. **Fix the bug** and ensure tests pass
+
+### New Features
+1. **Discuss the feature** in an issue first
+2. **Ensure it aligns** with the plugin's focused scope
+3. **Write comprehensive documentation**
+4. **Add configuration options** if needed
+
+### Documentation
+- **Fix typos** and improve clarity
+- **Add examples** for complex features
+- **Update README** with new functionality
+
+## Testing Guidelines
+
+### Manual Testing
+- Test with **multiple projects**
+- Verify **mark persistence** across sessions
+- Test **edge cases** (empty files, special characters)
+- Check **memory usage** with large mark sets
+
+### Test Scenarios
+1. **Basic Operations**:
+   - Add/delete/rename marks
+   - Jump to marks
+   - Search functionality
+
+2. **Project Switching**:
+   - Marks isolated per project
+   - Correct project detection
+
+3. **Error Handling**:
+   - Invalid file paths
+   - Corrupted storage files
+   - Memory limits
+
+4. **UI Testing**:
+   - Window sizing and positioning
+   - Keyboard navigation
+   - Search and filtering
+
+## Performance Considerations
+
+### Memory Efficiency
+- **Lazy load modules** when possible
+- **Clean up resources** on plugin disable
+- **Cache strategically** with expiration
+- **Debounce operations** to reduce I/O
+
+### Code Patterns
+```lua
+-- Good: Lazy loading
+local function get_storage()
+    if not storage then
+        storage = require("marksman.storage")
+    end
+    return storage
+end
+
+-- Good: Error handling
+local ok, result = pcall(function()
+    -- Potentially failing operation
+end)
+if not ok then
+    notify("Operation failed: " .. tostring(result), vim.log.levels.ERROR)
+    return false
+end
+```
+
+## Error Handling
+
+### Guidelines
+- **Always handle errors** gracefully
+- **Provide meaningful messages** to users
+- **Log technical details** for debugging
+- **Fallback to safe defaults** when possible
+
+### Error Message Format
+```lua
+-- User-facing: Clear and actionable
+notify("Cannot add mark: file is not readable", vim.log.levels.WARN)
+
+-- Debug: Technical details
+notify("Failed to save marks: " .. tostring(err), vim.log.levels.ERROR)
+```
+
+## Configuration Design
+
+### Principles
+- **Sensible defaults** that work out of the box
+- **Granular options** for customization
+- **Backward compatibility** when possible
+- **Validation** for user inputs
+
+### Example Configuration
+```lua
+require("marksman").setup({
+    -- Core functionality
+    max_marks = 100,
+    auto_save = true,
+    
+    -- UI preferences
+    minimal = false,
+    silent = false,
+    
+    -- Performance tuning
+    debounce_ms = 500,
+    
+    -- Customization
+    keymaps = { ... },
+    highlights = { ... },
+})
+```
+
+## Pull Request Process
+
+### Before Submitting
+1. **Test thoroughly** on your system
+2. **Run linting** and fix issues
+3. **Update documentation** if needed
+4. **Rebase on main** branch
+
+### PR Description Template
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactoring
+
+## Testing
+Describe how you tested the changes
+
+## Breaking Changes
+List any breaking changes (if applicable)
+
+## Checklist
+- [ ] Code follows style guidelines
+- [ ] Self-review completed
+- [ ] Documentation updated
+- [ ] Tests pass
+```
+
+## Review Process
+
+### What We Look For
+- **Code quality** and maintainability
+- **Performance impact**
+- **User experience** improvements
+- **Documentation completeness**
+- **Test coverage**
+
+### Response Time
+- Initial review: 2-3 business days
+- Follow-up reviews: 1-2 business days
+- Simple fixes: Same day
+
+## Getting Help
+
+### Communication Channels
+- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: Questions and general discussion
+- **Pull Request Comments**: Code-specific discussions
+
+### Response Guidelines
+- Be **respectful** and constructive
+- **Ask questions** if requirements are unclear
+- **Provide context** for your suggestions
+
+## Recognition
+
+Contributors are recognized in:
+- **README.md** contributors section
+- **Release notes** for significant contributions
+- **GitHub repository** contributor graphs
+
+Thank you for helping make Marksman.nvim better! 🚀