docs: agentic rules and commands

.cursor/README.md

@@ -0,0 +1,75 @@
+# Cursor Rules & Commands
+
+The Tux project uses Cursor's rules and commands system to provide AI-assisted development with project-specific patterns and workflows.
+
+## Overview
+
+This directory contains:
+
+- **Rules** (`.mdc` files) - Project-specific coding patterns and standards
+- **Commands** (`.md` files) - Reusable workflows and task automation
+
+Rules are automatically applied by Cursor based on file patterns, while commands are invoked manually with the `/` prefix in Cursor chat.
+
+## Structure
+
+### Rules
+
+Rules are organized by domain in `.cursor/rules/`:
+
+- **`core/`** - Core project rules (tech stack, dependencies)
+- **`database/`** - Database layer patterns (models, migrations, controllers, services, queries)
+- **`modules/`** - Discord bot modules (cogs, commands, events, permissions, interactions)
+- **`testing/`** - Testing patterns (pytest, fixtures, markers, coverage, async)
+- **`docs/`** - Documentation rules (Zensical, writing standards, structure)
+- **`security/`** - Security patterns (secrets, validation, dependencies)
+- **`error-handling/`** - Error handling (patterns, logging, Sentry, user feedback)
+- **`ui/`** - UI components (Discord Components V2)
+- **`meta/`** - System documentation (Cursor rules/commands specifications)
+
+### Commands
+
+Commands are organized by category in `.cursor/commands/`:
+
+- **`code-quality/`** - Code quality workflows (lint, refactor, review)
+- **`testing/`** - Testing workflows (run tests, coverage, integration)
+- **`database/`** - Database workflows (migration, health, reset)
+- **`discord/`** - Discord bot workflows (create module, test command, sync)
+- **`security/`** - Security workflows (security review)
+- **`debugging/`** - Debugging workflows (debug issues)
+- **`error-handling/`** - Error handling workflows (add error handling)
+- **`documentation/`** - Documentation workflows (generate, update, serve)
+- **`development/`** - Development workflows (setup, docker)
+
+## Usage
+
+Rules are automatically applied by Cursor:
+
+- **Always Apply** - Rules with `alwaysApply: true` are active in every chat
+- **File-Scoped** - Rules with `globs` patterns apply when editing matching files
+- **Intelligent** - Rules with `description` are selected by Cursor based on context
+
+Commands are invoked manually:
+
+1. Type `/` in Cursor chat
+2. Select command from autocomplete list
+3. Command executes with current context
+
+Example: `/lint` runs the linting workflow
+
+## Quick Reference
+
+See [rules/rules.mdc](rules/rules.mdc) for a complete catalog of all rules and commands.
+
+## Contributing
+
+See the developer documentation for comprehensive guides on creating and maintaining rules/commands:
+
+- [Creating Cursor Rules Guide](../docs/content/developer/guides/creating-cursor-rules.md)
+- [Creating Cursor Commands Guide](../docs/content/developer/guides/creating-cursor-commands.md)
+
+## Resources
+
+- [Cursor Rules Documentation](https://cursor.com/docs/context/rules)
+- [Cursor Commands Documentation](https://cursor.com/docs/agent/chat/commands)
+- [AGENTS.md](../AGENTS.md)

.cursor/commands/code-quality/lint.md

@@ -0,0 +1,59 @@
+# Lint and Fix Code
+
+## Overview
+
+Run Tux project linters (ruff, basedpyright) and automatically fix issues according to project coding standards.
+
+## Steps
+
+1. **Run Linters**
+   - Format code: `uv run ruff format .`
+   - Fix auto-fixable issues: `uv run ruff check --fix .`
+   - Check types: `uv run basedpyright`
+   - Run all checks: `uv run dev all`
+2. **Identify Issues**
+   - Ruff linting violations (imports, style, complexity)
+   - Type errors from basedpyright
+   - Unused imports and variables
+   - Missing type hints (`Type | None` not `Optional[Type]`)
+   - NumPy docstring format violations
+3. **Apply Fixes**
+   - Auto-fix with ruff where possible
+   - Add type hints with strict typing
+   - Use `Type | None` convention
+   - Fix import organization (stdlib → third-party → local)
+   - Update docstrings to NumPy format
+4. **Verify Standards**
+   - 88 character line length
+   - snake_case for functions/variables
+   - PascalCase for classes
+   - UPPER_CASE for constants
+   - Absolute imports preferred
+
+## Error Handling
+
+If linting fails:
+
+- Review error messages carefully
+- Some issues may require manual fixes
+- Type errors may need code changes
+- Import organization can be auto-fixed
+
+## Lint Checklist
+
+- [ ] Ran `uv run ruff format .`
+- [ ] Ran `uv run ruff check --fix .`
+- [ ] Ran `uv run basedpyright`
+- [ ] Fixed all type errors
+- [ ] Added missing type hints
+- [ ] Used `Type | None` convention
+- [ ] Organized imports correctly
+- [ ] Updated docstrings to NumPy format
+- [ ] Verified naming conventions
+- [ ] Ran `uv run dev all` successfully
+
+## See Also
+
+- Related command: `/refactor`
+- Related command: `/review-existing-diffs`
+- Related rule: @core/tech-stack.mdc

.cursor/commands/code-quality/refactor.md

@@ -0,0 +1,58 @@
+# Refactor Code
+
+## Overview
+
+Refactor code to follow Tux project patterns, Discord.py best practices, and Python standards while maintaining functionality.
+
+## Steps
+
+1. **Code Quality Improvements**
+   - Extract reusable functions following DRY principle
+   - Eliminate code duplication across cogs
+   - Improve naming (snake_case, PascalCase, UPPER_CASE)
+   - Simplify nested async/await patterns
+2. **Discord.py Patterns**
+   - Use hybrid commands (slash + traditional)
+   - Implement proper command error handlers
+   - Use embeds from `tux.ui.embeds`
+   - Follow cog structure from `src/modules/`
+3. **Database Patterns**
+   - Use service layer for business logic
+   - Use controllers for database operations
+   - Never access database session directly
+   - Implement proper transaction handling
+4. **Python Best Practices**
+   - Add strict type hints
+   - Use NumPy docstring format
+   - Follow async/await patterns
+   - Keep files under 1600 lines
+
+## Error Handling
+
+During refactoring:
+
+- Run tests frequently to catch regressions
+- Use `uv run test quick` for fast feedback
+- Check for breaking changes
+- Verify all functionality still works
+
+## Refactor Checklist
+
+- [ ] Extracted reusable functions
+- [ ] Eliminated code duplication
+- [ ] Improved naming conventions
+- [ ] Simplified complex nested logic
+- [ ] Used proper Discord.py command patterns
+- [ ] Implemented service layer architecture
+- [ ] Added strict type hints
+- [ ] Updated to NumPy docstrings
+- [ ] Verified async/await patterns
+- [ ] Kept files under 1600 lines
+- [ ] Ran tests to verify functionality
+
+## See Also
+
+- Related command: `/lint`
+- Related command: `/write-unit-tests`
+- Related rule: @modules/cogs.mdc
+- Related rule: @database/controllers.mdc

.cursor/commands/code-quality/review-existing-diffs.md

@@ -0,0 +1,57 @@
+# Review Existing Diffs
+
+## Overview
+
+Perform quality pass on git diffs to ensure Tux project standards, test coverage, and documentation updates.
+
+## Steps
+
+1. **Scan Recent Changes**
+   - Check git status and pending commits
+   - Review modified files in `src/tux/`
+   - Note database model or migration changes
+   - Check for new commands or cogs
+2. **Tux-Specific Checks**
+   - Database: Run `uv run db status` if models changed
+   - Tests: Verify test files updated in `tests/`
+   - Docs: Check if `docs/content/` needs updates
+   - Scripts: Validate CLI commands in `scripts/`
+3. **Code Quality Signals**
+   - Run `uv run dev all` to check standards
+   - Verify type hints with basedpyright
+   - Check for TODOs or debug statements
+   - Ensure proper import organization
+4. **Documentation Updates**
+   - Update docstrings if API changed
+   - Add CHANGELOG.md entry if needed
+   - Update docs if user-facing changes
+   - Verify conventional commit format
+
+## Error Handling
+
+If review finds issues:
+
+- Fix issues before committing
+- Run `uv run dev all` after fixes
+- Re-run tests to verify
+- Update documentation if needed
+
+## Review Checklist
+
+- [ ] Ran `uv run dev all` successfully
+- [ ] Database migrations created if models changed
+- [ ] Tests added/updated for new functionality
+- [ ] Documentation updated for user-facing changes
+- [ ] No debug code or TODOs left in
+- [ ] Type hints pass basedpyright checks
+- [ ] Imports organized correctly
+- [ ] Files under 1600 lines
+- [ ] Conventional commit format used
+- [ ] CHANGELOG.md updated if needed
+
+## See Also
+
+- Related command: `/lint`
+- Related command: `/refactor`
+- Related command: `/write-unit-tests`
+- Related rule: @AGENTS.md

.cursor/commands/database/health.md

@@ -0,0 +1,47 @@
+# Database Health Check
+
+## Overview
+
+Check database connection and health status for the Tux PostgreSQL database.
+
+## Steps
+
+1. **Check Connection**
+   - Run `uv run db health`
+   - Verify connection to PostgreSQL database
+   - Check database URL configuration
+   - Verify environment variables are set
+
+2. **Verify Services**
+   - Ensure Docker services are running: `uv run docker up`
+   - Check PostgreSQL container status
+   - Verify database is accessible
+   - Check connection pool status
+
+3. **Diagnose Issues**
+   - Review connection errors in logs
+   - Check `.env` file for correct database URL
+   - Verify `POSTGRES_*` environment variables
+   - Check Docker container logs if using Docker
+
+4. **Test Operations**
+   - Verify database service can create sessions
+   - Test basic query execution
+   - Check migration status: `uv run db status`
+   - Verify models can be accessed
+
+## Checklist
+
+- [ ] Database connection successful
+- [ ] Environment variables configured correctly
+- [ ] Docker services running (if using Docker)
+- [ ] Database URL is valid
+- [ ] Connection pool working
+- [ ] Basic queries execute successfully
+- [ ] Migration status accessible
+
+## See Also
+
+- Related rule: @database/services.mdc
+- Related command: `/database-migration`
+- Related command: `/database-reset`

.cursor/commands/database/migration.md

@@ -0,0 +1,47 @@
+# Database Migration
+
+## Overview
+
+Create and apply Alembic database migrations for schema changes in the Tux project.
+
+## Steps
+
+1. **Create Migration**
+   - Run `uv run db migrate-dev "description of changes"`
+   - Review generated migration file in `src/tux/database/migrations/versions/`
+   - Verify upgrade and downgrade functions are correct
+   - Check for proper constraint naming
+
+2. **Review Migration**
+   - Ensure both `upgrade()` and `downgrade()` are implemented
+   - Verify all table/column operations are included
+   - Check index creation/dropping
+   - Validate enum type handling if applicable
+
+3. **Test Migration**
+   - Test upgrade: `uv run db push` (applies pending migrations)
+   - Test downgrade: Manually test rollback if needed
+   - Verify migration with `uv run db status`
+   - Run tests to ensure schema changes work
+
+4. **Apply Migration**
+   - Apply to development: `uv run db push`
+   - Check migration status: `uv run db status`
+   - Verify database health: `uv run db health`
+
+## Checklist
+
+- [ ] Migration file created with descriptive name
+- [ ] Both upgrade and downgrade functions implemented
+- [ ] All schema changes included (tables, columns, indexes, constraints)
+- [ ] Enum types handled correctly if applicable
+- [ ] Migration tested (upgrade and downgrade)
+- [ ] Tests pass with new schema
+- [ ] Migration applied to development database
+- [ ] Database health check passes
+
+## See Also
+
+- Related rule: @database/migrations.mdc
+- Related command: `/database-health`
+- Related command: `/database-reset`

.cursor/commands/database/reset.md

@@ -0,0 +1,49 @@
+# Database Reset
+
+## Overview
+
+Safely reset the database by dropping all tables and reapplying migrations from scratch. Use with caution - this will delete all data.
+
+## Steps
+
+1. **Backup Data (if needed)**
+   - Export important data if this is production
+   - Note any custom data that needs to be preserved
+   - Document current database state
+
+2. **Reset Database**
+   - Run `uv run db reset` for safe reset
+   - This drops all tables and reapplies all migrations
+   - Verify reset completed successfully
+   - Check database is in clean state
+
+3. **Verify Reset**
+   - Check migration status: `uv run db status`
+   - Verify all tables recreated
+   - Test basic database operations
+   - Run health check: `uv run db health`
+
+4. **Re-seed Data (if needed)**
+   - Restore any required seed data
+   - Verify test data is correct
+   - Run tests to ensure everything works
+
+## Warning
+
+⚠️ **This will delete all data in the database!** Only use in development or when you're certain you want to lose all data.
+
+## Checklist
+
+- [ ] Data backed up (if needed)
+- [ ] Database reset command executed
+- [ ] All migrations reapplied successfully
+- [ ] Database health check passes
+- [ ] Basic operations work correctly
+- [ ] Test data restored (if needed)
+- [ ] Tests pass with reset database
+
+## See Also
+
+- Related rule: @database/migrations.mdc
+- Related command: `/database-migration`
+- Related command: `/database-health`