chore: housekeeping — examples pin, doc fixes, import cleanup

.github/copilot-instructions.md

@@ -151,7 +151,7 @@ assert github_token
 
 ```python
 # In __init__.py
-__version__ = "0.6.1"  # Bump for every release
+__version__ = "0.7.2"  # Bump for every release
 
 # In action.py - print version at startup
 print(f"📋 QuantEcon Style Guide Checker v{__version__}")
@@ -162,7 +162,7 @@ print(f"📋 QuantEcon Style Guide Checker v{__version__}")
 **CRITICAL: Always run tests before any release!**
 
 1. Make changes
-2. **Run full test suite**: `pytest tests/ -v`
+2. **Run full test suite**: `uv run pytest tests/ -v`
 3. **Verify all tests pass** (except LLM integration tests which require API keys)
 4. Update `__version__` in `style_checker/__init__.py`
 5. **Update prompt versions** if any prompts were modified:
@@ -172,7 +172,7 @@ print(f"📋 QuantEcon Style Guide Checker v{__version__}")
 6. Update `CHANGELOG.md` (move Unreleased to new version)
 7. Commit: "Release vX.Y.Z - Description"
 8. Create GitHub release: `gh release create vX.Y.Z --title "..." --notes "..."`
-9. Update floating tag: `git tag -f v0.3 && git push origin v0.3 --force`
+9. Update floating tag (current minor, e.g. `v0.7`): `git tag -f vX.Y && git push origin vX.Y --force`
 10. Push main branch: `git push origin main`
 
 **Never skip testing** - it catches regressions and ensures quality.

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - **Bumped GitHub Actions to Node 24-compatible versions** — GitHub forces Node 24 as the default runner runtime from 2026-06-02 (Node 20 fully removed 2026-09-16). Updated `actions/checkout@v4→v5` and `astral-sh/setup-uv@v3→v7` in `action.yml` and CI; the docs workflow now uses `actions/setup-node@v4→v6` (Node 22), `actions/upload-pages-artifact@v3→v5`, and `actions/deploy-pages@v4→v5`. Resolves #16.
+- **Bumped example workflows to `@v0.7`** — `examples/style-guide-comment.yml` and `examples/style-guide-weekly.yml` pinned the action at the long-stale `@v0.3`; they now track the current `v0.7` release line, matching the `docs/user/*` snippets.
 
 ## [0.7.2] - 2026-02-16
 

CONTRIBUTING.md

@@ -1,209 +1,79 @@
 # Contributing to QuantEcon Style Guide Checker
 
-Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+Thank you for your interest in contributing! 🎉
 
-## Development Setup
+> **📖 Full developer guide:** The complete, up-to-date guide — development
+> setup, adding rules and categories, testing, and the release process — lives
+> in [`docs/developer/contributing.md`](docs/developer/contributing.md). This
+> page is a quick summary.
 
-### Prerequisites
+## Quick Start
 
-- Python 3.11+
-- Git
-- GitHub account
-
-### Local Development
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/QuantEcon/action-style-guide.git
-   cd action-style-guide
-   ```
-
-2. **Create virtual environment**
-   ```bash
-   python -m venv venv
-   source venv/bin/activate  # On Windows: venv\Scripts\activate
-   ```
-
-3. **Install dependencies**
-   ```bash
-   pip install -r requirements.txt
-   pip install -r requirements-dev.txt  # If available
-   ```
-
-4. **Set up API keys**
-   ```bash
-   export ANTHROPIC_API_KEY="your-key"  # For Claude Sonnet 4.5
-   export GITHUB_TOKEN="your-token"     # For GitHub API
-   ```
-
-## Testing Locally
-
-### Test Single Lecture Review
+The project uses [uv](https://docs.astral.sh/uv/) to manage Python, the
+virtualenv, and dependencies.
 
 ```bash
-python -m style_checker.main \
-  --mode single \
-  --lectures-path lectures/ \
-  --repository owner/repo \
-  --comment-body "@qe-style-checker lecture-name" \
-  --create-pr false
-```
+git clone https://github.com/QuantEcon/action-style-guide.git
+cd action-style-guide
 
-### Test Bulk Review
+# uv reads pyproject.toml + uv.lock and creates a .venv automatically.
+# --all-extras installs PyGithub (action) + pytest/ruff (dev).
+uv sync --all-extras
 
-```bash
-python -m style_checker.main \
-  --mode bulk \
-  --lectures-path lectures/ \
-  --repository owner/repo \
-  --create-pr false
+# Run commands via `uv run` (no need to activate the venv):
+uv run qestyle --version
+uv run pytest tests/
 ```
 
-## Adding New Features
-
-### Adding New Style Rules
-
-Rules are now organized in category-specific files in `style_checker/rules/`:
-
-1. Edit the appropriate rules file (e.g., `style_checker/rules/writing-rules.md`)
-2. Add rule following the existing Markdown format:
-   ```markdown
-   ## Rule Title
-
-   **Description**: Clear explanation of what the rule checks
-
-   **Why**: Rationale for this rule
-
-   **Good**:
-   ```python
-   # Good example
-   ```
-
-   **Bad**:
-   ```python
-   # Bad example
-   ```
-   ```
-
-3. Rules are grouped into 8 categories:
-   - writing, math, code, jax, figures, references, links, admonitions
-
-4. If needed, update corresponding prompt file in `style_checker/prompts/`
-
-5. Test with sample lectures
-
-### Adding New LLM Providers
-
-The action currently uses Claude Sonnet 4.5 via the Anthropic API. The provider logic is in `style_checker/reviewer.py`.
+Prefer pip? `pip install -e ".[dev,action]"` uses the same dependency manifest.
 
-To switch or add a provider:
-1. Update the API client setup in `AnthropicProvider.__init__()`
-2. Adjust model name and parameters as needed
-3. Update `requirements.txt` with new dependencies
-4. Test with real lecture files
+To run against real lectures, set your API keys first:
 
-### Improving Prompts
-
-The action uses a focused prompts architecture:
-- **Prompts** (`style_checker/prompts/*.md`): Concise instructions for the LLM
-- **Rules** (`style_checker/rules/*.md`): Detailed specifications with examples
-
-To improve:
-- Edit the appropriate prompt or rules file
-- Test with various lecture types
-- Ensure Markdown output format is maintained
-- Validate against all rule categories
-
-## Code Style
-
-- Follow PEP 8
-- Use type hints
-- Add docstrings to all functions/classes
-- Keep functions focused and small
-- Comment complex logic
-
-## Pull Request Process
-
-1. **Fork the repository**
-2. **Create feature branch**
-   ```bash
-   git checkout -b feature/your-feature-name
-   ```
-
-3. **Make changes**
-   - Write clean, documented code
-   - Add tests if applicable
-   - Update documentation
+```bash
+export ANTHROPIC_API_KEY="your-key"   # Claude (Anthropic)
+export GITHUB_TOKEN="your-token"      # GitHub API
+```
 
-4. **Test thoroughly**
-   - Test locally with real lectures
-   - Verify PR creation works
-   - Check all output formats
+## Adding Style Rules
 
-5. **Commit with clear messages**
-   ```bash
-   git commit -m "feat: add feature description"
-   ```
+Rules live in `style_checker/rules/*.md` and are read directly by the LLM — **no
+code change is needed** to add a rule to an existing category. Adding a whole new
+category also requires updating `VALID_CATEGORIES`
+(`style_checker/categories.py`) and `RULE_EVALUATION_ORDER`
+(`style_checker/reviewer.py`); the test suite fails loudly if those drift. See
+the [full guide](docs/developer/contributing.md#adding-new-rules) for the rule
+format and details.
 
-6. **Push and create PR**
-   ```bash
-   git push origin feature/your-feature-name
-   ```
+## Pull Requests
 
-7. **PR Requirements**
-   - Clear description of changes
-   - Reference any related issues
-   - Include test results
-   - Update README if needed
+1. Fork the repository and create a feature branch:
+   `git checkout -b feature/your-feature-name`
+2. Make your changes; add tests where it makes sense.
+3. Run the suite: `uv run pytest tests/`
+4. Commit using conventional commits (below) and open a PR with a clear
+   description that references any related issues.
 
-## Commit Message Format
+### Commit Message Format
 
-Use conventional commits:
+Use [conventional commits](https://www.conventionalcommits.org/):
 
 - `feat:` New feature
 - `fix:` Bug fix
 - `docs:` Documentation changes
-- `style:` Code style changes (formatting)
+- `style:` Code style / formatting
 - `refactor:` Code refactoring
 - `test:` Adding tests
 - `chore:` Maintenance tasks
 
 ## Reporting Issues
 
-When reporting issues, include:
-
-1. **Description** of the problem
-2. **Steps to reproduce**
-3. **Expected behavior**
-4. **Actual behavior**
-5. **Environment details** (OS, Python version, etc.)
-6. **Relevant logs** or error messages
+Include: a description of the problem, steps to reproduce, expected vs. actual
+behavior, environment details (OS, Python version), and any relevant logs or
+error messages.
 
 ## Suggesting Enhancements
 
-For feature requests:
-
-1. **Use case**: Why is this needed?
-2. **Proposed solution**: How should it work?
-3. **Alternatives considered**: Other approaches?
-4. **Implementation ideas**: Technical approach?
-
-## Style Guide Rules
-
-When adding or modifying style guide rules:
-
-1. **Clear and specific**: Rules should be unambiguous
-2. **Actionable**: Include examples of correct/incorrect usage
-3. **Categorized properly**: Use one of the 8 categories (writing, math, code, jax, figures, references, links, admonitions)
-4. **Typed correctly**: 
-   - `rule`: Actionable, automatically applied
-   - `style`: Advisory, requires human judgment
-   - `migrate`: Legacy pattern modernization
-
-## Questions?
-
-- Open a discussion on GitHub
-- Check existing issues and PRs
-- Review the documentation
+Open a GitHub discussion or issue describing the use case, your proposed
+solution, and any alternatives you considered.
 
 Thank you for contributing! 🎉

examples/style-guide-comment.yml

@@ -32,7 +32,8 @@ jobs:
             })
 
       - name: Run style guide checker
-        uses: QuantEcon/action-style-guide@v0.3
+        id: run-checker
+        uses: QuantEcon/action-style-guide@v0.7
         with:
           mode: 'single'
           lectures-path: 'lectures/'

examples/style-guide-weekly.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: Run bulk style guide review
-        uses: QuantEcon/action-style-guide@v0.3
+        uses: QuantEcon/action-style-guide@v0.7
         id: review
         with:
           mode: 'bulk'

style_checker/github_handler.py

@@ -11,6 +11,7 @@
 from github import Github, GithubException
 from datetime import datetime
 
+from . import __version__
 from .categories import VALID_CATEGORIES
 
 
@@ -298,7 +299,6 @@ def format_detailed_report(self, review_result: Dict[str, Any], lecture_name: st
         Returns:
             Detailed markdown report with all violations (wrapped in <details>)
         """
-        from . import __version__
 
         # Wrap in collapsible details block
         report = f"<details>\n<summary><b>📊 Detailed Style Review Report</b> (click to expand)</summary>\n\n"
@@ -374,7 +374,6 @@ def format_applied_fixes_report(self, review_result: Dict[str, Any], lecture_nam
         Returns:
             Detailed markdown report of applied fixes (wrapped in <details>)
         """
-        from . import __version__
 
         fix_log = review_result.get('fix_log', [])
         original_content = review_result.get('original_content', '')
@@ -445,7 +444,6 @@ def format_style_suggestions_report(self, review_result: Dict[str, Any], lecture
         Returns:
             Open markdown report of style suggestions (NOT collapsible - visible by default)
         """
-        from . import __version__
 
         style_violations = review_result.get('style_violations', [])
 
@@ -508,7 +506,6 @@ def format_pr_body(self, review_result: Dict[str, Any], lecture_name: str) -> st
         Returns:
             Concise PR body with summary
         """
-        from . import __version__
 
         body = f"## 📋 Style Guide Review: {lecture_name}\n\n"
         body += f"This PR addresses style guide compliance issues found in the `{lecture_name}` lecture.\n\n"