Update GitHub Actions and add AI agent guidelines

This PR makes three key improvements to the repository's infrastructure
and development standards.

## Summary of Changes

1. **Updated deprecated GitHub Actions**: Upgraded actions/upload-artifact
   from v3 to v4 to avoid workflow failures after January 30th, 2025
2. **Fixed Python setup on macOS**: Switched to macos-13 runner to resolve
   Python 3.10.19 compatibility issues while maintaining Windows 7 support
3. **Introduced AI agent documentation**: Created comprehensive guidelines
   for commit messages and PR descriptions

## Context and Reasoning

### GitHub Actions Deprecation
GitHub is deprecating v3 of actions/upload-artifact starting January 30th,
2025. Workflows using v3 will fail after this date. The v4 API provides
significant performance improvements (up to 98% faster uploads) and continued
support. Updated both Windows and macOS artifact upload steps from v3 to v4.
No breaking changes affect this workflow since each artifact has a unique
name (one of v4's breaking changes is that you can't upload to the same
artifact name multiple times).

### macOS Runner and Python 3.10 Compatibility
Initial workflow failures on macOS were caused by Python 3.10.19 binaries
having a hard dependency on Homebrew's gettext library (libintl.8.dylib),
which isn't available on newer ARM64 macOS runners (macos-latest/macos-14).

Several workarounds were attempted:
- Installing gettext via Homebrew (already installed but not linked)
- Force linking gettext (linking failed in CI environment)
- Upgrading to Python 3.11 (would break Windows 7 support)

The correct solution: Switch from macos-latest to macos-13 (Intel x64).
The Python 3.10.19 gettext issue only affects ARM64 runners; the Intel-based
macos-13 runners work correctly with Python 3.10 out of the box.

Why maintaining Python 3.10 is critical:
- Python 3.10 is the last version to support Windows 7
- Python 3.9+ actively disallows installation on Windows 7
- Project explicitly requires Python 3.10 (Pipfile, README)
- Windows 7 support is important for the Eve Online user community

Also upgraded actions/setup-python from v3 to v5 for better compatibility
and moved checkout before setup-python (recommended order).

### AI Agent Guidelines
The project needed standardized guidelines for AI agents working on the
codebase. There was a tendency for automated commits to lack the "why"
context that makes git history valuable for debugging and understanding
code evolution.

Created two files:
- CLAUDE.md: Entry point that references AGENTS.md
- AGENTS.md: Comprehensive guidelines covering:
  * Why commit messages should focus on "why" not "what"
  * Benefits of detailed commit messages (understanding past intentions,
    helping other engineers, knowledge sharing)
  * Examples of bad vs good commit messages
  * PR description guidelines following the same principles
  * What to include in PR descriptions (summary, context, approach,
    trade-offs, testing, risks)

The "why" is often harder to infer than the "what" and requires explicit
documentation. Without it, future developers struggle to understand the
reasoning behind changes when debugging or modifying code.

## Testing

- No code changes that require runtime testing
- GitHub Actions workflow syntax is valid
- Documentation files are properly formatted markdown
- Workflow successfully runs on both windows-latest and macos-13

## Trade-offs and Risks

**Low risk overall**:

- **Artifact action update**: Backward compatible for our use case, no
  breaking changes apply
- **macOS runner change**: Using macos-13 (Intel) instead of macos-latest
  (ARM64) is acceptable given the Windows 7 requirement. macos-13 is still
  actively supported by GitHub Actions
- **Documentation**: Only adds guidelines, doesn't change existing code or
  processes

## Benefits

1. **Continued CI/CD operation**: Workflows won't fail after January 30th, 2025
2. **Performance improvement**: Faster artifact uploads in CI pipeline
3. **Platform compatibility**: Maintains Windows 7 support while fixing macOS builds
4. **Better git history**: AI agents will write more meaningful commit messages
5. **Improved PR reviews**: PR descriptions provide better context for reviewers
6. **Knowledge preservation**: Git log becomes a more valuable debugging resource

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: secondfry

.github/workflows/main.yml

@@ -13,16 +13,16 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [windows-latest, macos-latest]
+        os: [windows-latest, macos-13]
     steps:
+      - uses: actions/checkout@v3
+
       - name: Setup Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v5
         with:
           python-version: "3.10"
           architecture: x64
 
-      - uses: actions/checkout@v3
-
       - name: Download UPX [windows-latest]
         uses: i3h/download-release-asset@v1
         if: ${{ matrix.os == 'windows-latest' }}
@@ -52,23 +52,23 @@ jobs:
         run: python -m pipenv run build_win_installer.bat
 
       - name: Upload a Build Artifact [windows-latest]
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: ${{ matrix.os == 'windows-latest' }}
         with:
           name: shortcircuit.exe
           path: ./dist/shortcircuit.exe
 
-      - name: Additional dependencies [macos-latest]
-        if: ${{ matrix.os == 'macos-latest' }}
+      - name: Additional dependencies [macos-13]
+        if: ${{ matrix.os == 'macos-13' }}
         run: python -m pipenv install macholib
 
-      - name: Build [macos-latest]
-        if: ${{ matrix.os == 'macos-latest' }}
+      - name: Build [macos-13]
+        if: ${{ matrix.os == 'macos-13' }}
         run: python -m pipenv run ./build_mac_installer.sh
 
-      - name: Upload a Build Artifact [macos-latest]
-        uses: actions/upload-artifact@v3
-        if: ${{ matrix.os == 'macos-latest' }}
+      - name: Upload a Build Artifact [macos-13]
+        uses: actions/upload-artifact@v4
+        if: ${{ matrix.os == 'macos-13' }}
         with:
           name: shortcircuit.app.tar.gz
           path: ./dist/shortcircuit.app.tar.gz

AGENTS.md

@@ -0,0 +1,134 @@
+# Guidelines for AI Agents
+
+## Commit Message Guidelines
+
+### Focus on the "Why", Not Just the "What"
+
+When writing commit messages, **always explain why the change was made**, not just what was changed. The diff already shows what changed - the commit message should provide context and reasoning.
+
+### The Importance of "Why"
+
+The "why" is often harder to infer than the "what", and it requires proper documentation. Without it, future developers (including your future self) will struggle to understand:
+
+- **Contextual Background**: Why was this change necessary? What problem or feature was being addressed?
+- **Decision-Making Process**: What options were considered? Why was this particular solution chosen?
+- **Implications and Considerations**: What are the potential impacts or limitations of this change? Were there any trade-offs?
+
+### Benefits of Detailed Commit Messages
+
+1. **Knowing Past Intentions**: You won't remember every change you worked on in a few months or years. Detailed messages from the past help you understand your own reasoning and make better decisions.
+
+2. **Providing Context for Other Engineers**: Commit messages are a form of asynchronous communication. They help other engineers understand what was in your head when you made the change, especially if you're away or have left the team.
+
+3. **Looking Back at Accomplishments**: Running `git log --author=name` provides a clear chronological list of all your contributions with high fidelity.
+
+4. **Spreading Knowledge and Awareness**: Good commit messages help team members learn from each other and build awareness of what's being done, especially in remote-heavy environments.
+
+5. **Focusing Code Changes**: Writing a commit message forces you to think about the work. If you can't write a concise explanation of what you're doing and why, maybe you need to reconsider the change or break it into smaller logical pieces.
+
+6. **Information at Your Fingertips**: Git is at your fingertips throughout development. Having detailed information in commit messages is faster and more convenient than clicking through to external tickets or PRs.
+
+### How NOT to Write Commit Messages
+
+❌ **Bad**: Summarizing the changes
+```
+Update authentication logic
+```
+
+❌ **Bad**: Only linking to a ticket
+```
+Fix #123
+```
+
+The problem: These messages don't explain why the change was necessary. The diff shows what changed - you need to provide the context and reasoning.
+
+✅ **Good**: Explaining the reasoning
+```
+Fix race condition in authentication flow
+
+Users were occasionally getting logged out unexpectedly during page
+navigation. This was caused by the auth token refresh happening
+simultaneously with route changes, leading to a race condition where
+the old token would sometimes override the refreshed one.
+
+This change ensures token refresh completes before allowing navigation
+to proceed, preventing the race condition.
+```
+
+### Guidelines
+
+- Don't just link to tickets - that puts all the work on the reader to understand context
+- Explain the problem being solved and why this solution was chosen
+- Include relevant trade-offs or limitations if applicable
+- Write for your future self and other engineers who may need to maintain this code
+- Remember: the git log is a valuable learning resource and debugging tool
+
+## Pull Request Description Guidelines
+
+Pull request descriptions should follow the same principles as commit messages: **focus on the "why", not just the "what"**.
+
+### What to Include in PR Descriptions
+
+1. **Summary**: A concise overview of what the PR accomplishes and why it's needed
+2. **Context**: Background information about the problem being solved or feature being added
+3. **Approach**: Explanation of the solution chosen and why (especially if there were alternatives)
+4. **Trade-offs**: Any known limitations, compromises, or technical debt introduced
+5. **Testing**: How the changes were tested and what scenarios were covered
+6. **Risks**: Any potential impacts on existing functionality or deployment considerations
+
+### How NOT to Write PR Descriptions
+
+❌ **Bad**: Minimal description
+```
+Fix bug
+```
+
+❌ **Bad**: Only ticket reference
+```
+Fixes #456
+```
+
+❌ **Bad**: Just listing changes
+```
+- Updated auth.py
+- Modified login form
+- Added new test
+```
+
+The problem: These descriptions don't provide context or reasoning. Reviewers and future maintainers need to understand why the changes were necessary.
+
+✅ **Good**: Comprehensive description
+```
+Fix race condition in authentication flow
+
+## Summary
+Users were occasionally getting logged out unexpectedly during page navigation.
+This PR fixes the race condition by ensuring token refresh completes before
+navigation proceeds.
+
+## Context
+The issue occurred when the auth token refresh was triggered simultaneously
+with route changes. The old token would sometimes override the refreshed one,
+causing unexpected logouts.
+
+## Approach
+Added a mutex to ensure token refresh operations are atomic. Considered using
+a queue-based approach but opted for the mutex solution due to its simplicity
+and lower overhead.
+
+## Testing
+- Added unit tests for concurrent token refresh scenarios
+- Manually tested rapid page navigation while token refresh was occurring
+- Verified no performance regression with load testing
+
+## Risks
+Low risk - the mutex is only held briefly during token operations.
+```
+
+### Guidelines
+
+- Treat PR descriptions as documentation for the changes
+- Provide enough context that reviewers don't need to read every line of code to understand the change
+- Explain your decision-making process, especially for non-obvious solutions
+- Include test plan details so reviewers can verify the testing was thorough
+- Remember: PR descriptions complement commit messages - use both effectively

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md