docs(README) Overhaul README

.cursor/rules/avoid-debug-loops.mdc

@@ -0,0 +1,57 @@
+---
+description: When stuck in debugging loops, break the cycle by minimizing to an MVP, removing debugging cruft, and documenting the issue completely for a fresh approach
+globs: *.py
+alwaysApply: false
+---
+# Avoid Debug Loops
+
+When debugging becomes circular and unproductive, follow these steps:
+
+## Detection
+- You have made multiple unsuccessful attempts to fix the same issue
+- You are adding increasingly complex code to address errors
+- Each fix creates new errors in a cascading pattern
+- You are uncertain about the root cause after 2-3 iterations
+
+## Action Plan
+
+1. **Pause and acknowledge the loop**
+   - Explicitly state that you are in a potential debug loop
+   - Review what approaches have been tried and failed
+
+2. **Minimize to MVP**
+   - Remove all debugging cruft and experimental code
+   - Revert to the simplest version that demonstrates the issue
+   - Focus on isolating the core problem without added complexity
+
+3. **Comprehensive Documentation**
+   - Provide a clear summary of the issue
+   - Include minimal but complete code examples that reproduce the problem
+   - Document exact error messages and unexpected behaviors
+   - Explain your current understanding of potential causes
+
+4. **Format for Portability**
+   - Present the problem in quadruple backticks for easy copying:
+
+````
+# Problem Summary
+[Concise explanation of the issue]
+
+## Minimal Reproduction Code
+```python
+# Minimal code example that reproduces the issue
+```
+
+## Error/Unexpected Output
+```
+[Exact error messages or unexpected output]
+```
+
+## Failed Approaches
+[Brief summary of approaches already tried]
+
+## Suspected Cause
+[Your current hypothesis about what might be causing the issue]
+````
+
+This format enables the user to easily copy the entire problem statement into a fresh conversation for a clean-slate approach.

.cursor/rules/dev-loop.mdc

@@ -3,35 +3,167 @@ description: QA every edit
 globs: *.py
 ---
 
-# First: QA Every edit
+# Development Process
 
-Run these commands between edits:
+## Project Stack
 
-Check typings:
+The project uses the following tools and technologies:
+
+- **uv** - Python package management and virtual environments
+- **ruff** - Fast Python linter and formatter
+- **py.test** - Testing framework
+  - **pytest-watcher** - Continuous test runner
+- **mypy** - Static type checking
+- **doctest** - Testing code examples in documentation
+
+## 1. Start with Formatting
+
+Format your code first:
 
 ```
-uv run mypy
+uv run ruff format .
 ```
 
-Lint:
+## 2. Run Tests
+
+Verify that your changes pass the tests:
+
+```
+uv run py.test
+```
+
+For continuous testing during development, use pytest-watcher:
+
+```
+# Watch all tests
+uv run ptw .
+
+# Watch and run tests immediately, including doctests
+uv run ptw . --now --doctest-modules
+
+# Watch specific files or directories
+uv run ptw . --now --doctest-modules src/libtmux/_internal/
+```
+
+## 3. Commit Initial Changes
+
+Make an atomic commit for your changes using conventional commits.
+Use `@git-commits.mdc` for assistance with commit message standards.
+
+## 4. Run Linting and Type Checking
+
+Check and fix linting issues:
+
+```
+uv run ruff check . --fix --show-fixes
+```
+
+Check typings:
 
 ```
-uv run ruff check . --fix; uv run ruff format .;
+uv run mypy
 ```
 
-Check tests:
+## 5. Verify Tests Again
+
+Ensure tests still pass after linting and type fixes:
 
 ```
 uv run py.test
 ```
 
-Between every edit, rerun:
-- Type checks
-- Lint
-- Tests
+## 6. Final Commit
+
+Make a final commit with any linting/typing fixes.
+Use `@git-commits.mdc` for assistance with commit message standards.
+
+## Development Loop Guidelines
+
+If there are any failures at any step due to your edits, fix them before proceeding to the next step.
+
+## Python Code Standards
+
+### Docstring Guidelines
+
+For `src/**/*.py` files, follow these docstring guidelines:
+
+1. **Use reStructuredText format** for all docstrings.
+   ```python
+   """Short description of the function or class.
+
+   Detailed description using reStructuredText format.
+
+   Parameters
+   ----------
+   param1 : type
+       Description of param1
+   param2 : type
+       Description of param2
+
+   Returns
+   -------
+   type
+       Description of return value
+   """
+   ```
+
+2. **Keep the main description on the first line** after the opening `"""`.
+
+3. **Use NumPy docstyle** for parameter and return value documentation.
+
+### Doctest Guidelines
+
+For doctests in `src/**/*.py` files:
+
+1. **Use narrative descriptions** for test sections rather than inline comments:
+   ```python
+   """Example function.
+
+   Examples
+   --------
+   Create an instance:
+
+   >>> obj = ExampleClass()
+
+   Verify a property:
+
+   >>> obj.property
+   'expected value'
+   """
+   ```
+
+2. **Move complex examples** to dedicated test files at `tests/examples/<path_to_module>/test_<example>.py` if they require elaborate setup or multiple steps.
+
+3. **Utilize pytest fixtures** via `doctest_namespace` for more complex test scenarios:
+   ```python
+   """Example with fixture.
+
+   Examples
+   --------
+   >>> # doctest_namespace contains all pytest fixtures from conftest.py
+   >>> example_fixture = getfixture('example_fixture')
+   >>> example_fixture.method()
+   'expected result'
+   """
+   ```
+
+4. **Keep doctests simple and focused** on demonstrating usage rather than comprehensive testing.
+
+5. **Add blank lines between test sections** for improved readability.
+
+6. **Test your doctests continuously** using pytest-watcher during development:
+   ```
+   # Watch specific modules for doctest changes
+   uv run ptw . --now --doctest-modules src/path/to/module.py
+   ```
 
-If there's any failures *due to the edits*, fix them first, then:
+### Pytest Testing Guidelines
 
-# When your edit is complete: Commit it
+1. **Use existing fixtures over mocks**:
+   - Use fixtures from conftest.py instead of `monkeypatch` and `MagicMock` when available
+   - For instance, if using libtmux, use provided fixtures: `server`, `session`, `window`, and `pane`
+   - Document in test docstrings why standard fixtures weren't used for exceptional cases
 
-Make an atomic commit for the edit, using conventional commits.
+2. **Preferred pytest patterns**:
+   - Use `tmp_path` (pathlib.Path) fixture over Python's `tempfile`
+   - Use `monkeypatch` fixture over `unittest.mock`

.cursor/rules/git-commits.mdc

@@ -2,81 +2,93 @@
 description: git-commits: Git commit message standards and AI assistance
 globs: git-commits: Git commit message standards and AI assistance | *.git/* .gitignore .github/* CHANGELOG.md CHANGES.md
 ---
-# Git Commit Standards
+# Optimized Git Commit Standards
 
-## Format
+## Commit Message Format
 ```
-type(scope[component]): concise description
+Component/File(commit-type[Subcomponent/method]): Concise description
 
-why: explanation of necessity/impact
-what: 
-- technical changes made
-- keep focused on single topic
+why: Explanation of necessity or impact.
+what:
+- Specific technical changes made
+- Focused on a single topic
 
-refs: #issue-number, breaking changes, links
+refs: #issue-number, breaking changes, or relevant links
 ```
 
-## Commit Types
-- `feat`: New features/enhancements
-- `fix`: Bug fixes
-- `refactor`: Code restructuring
-- `docs`: Documentation changes
-- `chore`: Maintenance tasks (deps, tooling)
-- `test`: Test-related changes
-- `style`: Code style/formatting
-
-## Guidelines
-- Subject line: max 50 chars
-- Body lines: max 72 chars
-- Use imperative mood ("Add" not "Added")
-- Single topic per commit
-- Blank line between subject and body
-- Mark breaking changes with "BREAKING:"
-- Use "See also:" for external links
-
-## AI Assistance in Cursor
-- Stage changes with `git add`
-- Use `@commit` to generate initial message
-- Review and adjust the generated message
-- Ensure it follows format above
-
-## Examples
-
-Good commit:
+## Component Patterns
+### General Code Changes
+```
+Component/File(feat[method]): Add feature
+Component/File(fix[method]): Fix bug
+Component/File(refactor[method]): Code restructure
 ```
-feat(subprocess[run]): Switch to unicode-only text handling
 
-why: Improve consistency and type safety in subprocess handling
-what:
-- BREAKING: Changed run() to use text=True by default
-- Removed console_to_str() helper and encoding logic
-- Simplified output handling
-- Updated type hints for better safety
+### Packages and Dependencies
+| Language   | Standard Packages                  | Dev Packages                  | Extras / Sub-packages                          |
+|------------|------------------------------------|-------------------------------|-----------------------------------------------|
+| General    | `lang(deps):`                      | `lang(deps[dev]):`            |                                               |
+| Python     | `py(deps):`                        | `py(deps[dev]):`              | `py(deps[extra]):`                            |
+| JavaScript | `js(deps):`                        | `js(deps[dev]):`              | `js(deps[subpackage]):`, `js(deps[dev{subpackage}]):` |
 
-refs: #485
-See also: https://docs.python.org/3/library/subprocess.html
+#### Examples
+- `py(deps[dev]): Update pytest to v8.1`
+- `js(deps[ui-components]): Upgrade Button component package`
+- `js(deps[dev{linting}]): Add ESLint plugin`
+
+### Documentation Changes
+Prefix with `docs:`
+```
+docs(Component/File[Subcomponent/method]): Update API usage guide
 ```
 
-Bad commit:
+### Test Changes
+Prefix with `tests:`
 ```
-updated some stuff and fixed bugs
+tests(Component/File[Subcomponent/method]): Add edge case tests
 ```
 
-Cursor Rules: Add development QA and git commit standards (#cursor-rules)
+## Commit Types Summary
+- **feat**: New features or enhancements
+- **fix**: Bug fixes
+- **refactor**: Code restructuring without functional change
+- **docs**: Documentation updates
+- **chore**: Maintenance (dependencies, tooling, config)
+- **test**: Test-related updates
+- **style**: Code style and formatting
+
+## General Guidelines
+- Subject line: Maximum 50 characters
+- Body lines: Maximum 72 characters
+- Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
+- Limit to one topic per commit
+- Separate subject from body with a blank line
+- Mark breaking changes clearly: `BREAKING:`
+- Use `See also:` to provide external references
+
+## AI Assistance Workflow in Cursor
+- Stage changes with `git add`
+- Use `@commit` to generate initial commit message
+- Review and refine generated message
+- Ensure adherence to these standards
+
+## Good Commit Example
+```
+Pane(feat[capture_pane]): Add screenshot capture support
 
-- Add dev-loop.mdc: QA process for code edits
-  - Type checking with mypy
-  - Linting with ruff
-  - Test validation with pytest
-  - Ensures edits are validated before commits
+why: Provide visual debugging capability
+what:
+- Implement capturePane method with image export
+- Integrate with existing Pane component logic
+- Document usage in Pane README
 
-- Add git-commits.mdc: Commit message standards
-  - Structured format with why/what sections
-  - Defined commit types and guidelines
-  - Examples of good/bad commits
-  - AI assistance instructions
+refs: #485
+See also: https://example.com/docs/pane-capture
+```
 
-Note: These rules help maintain code quality and commit history
-consistency across the project.
+## Bad Commit Example
+```
+fixed stuff and improved some functions
+```
 
-See also: https://docs.cursor.com/context/rules-for-ai
+These guidelines ensure clear, consistent commit histories, facilitating easier code review and maintenance.