Release Candidate v5.20.1

.agent/rules/code-style.md

@@ -8,6 +8,12 @@ trigger: always_on
 
 In Python, I want you to use the latest type syntax (`type | None`) instead of `Optional`. I also want you to use a single space (`=`) around the equals sign (`=`) in function argument calls. It's important to use double quotation marks (`"`) instead of single quotations (`'`). And finally, we want to always use trailing commas in multi-line function declarations and calls. There's never a reason to write `unittest.main()` manually, we have a script for running tests. Never use inline imports inside of functions (use file header even in tests), and always use `from ... import ...` syntax at the top of the file.
 
+#### Comments
+
+- For new code, avoid comments unless the logic is genuinely complex or the block is long
+- When editing existing code, prefer updating comments over deleting them
+- Comments should start with a lowercase letter, except in documentation or where grammar requires it
+
 #### Error Handling
 
 Never use generic `ValueError`, `AssertionError`, or bare `Exception` for raising errors. Always use the structured exceptions from `util.errors` (`ValidationError`, `NotFoundError`, `AuthorizationError`, `ExternalServiceError`, `RateLimitError`, `ConfigurationError`, `InternalError`). Each raise must include an error code from `util.error_codes`. When re-raising from a caught exception, always use `raise ... from e` to preserve the chain. When calling external services (LLMs, image APIs, web fetchers), always guard against empty/null/empty-array responses with `ExternalServiceError`.

.agent/rules/tooling.md

@@ -12,27 +12,27 @@ trigger: always_on
 
 ### Database Migrations
 
-- Ask the user to run `./tools/db_generate_migration.sh -y` to generate new Alembic migrations (auto-generates based on model changes)
-- Ask the user to run `./tools/db_apply_migration.sh` to apply migrations to database (only with user's approval)
-- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration.sh`
+- Ask the user to run `./tools/db_generate_migration -y` to generate new Alembic migrations (auto-generates based on model changes)
+- Ask the user to run `./tools/db_apply_migration` to apply migrations to database (only with user's approval)
+- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration`
 
 ### Development Workflow
 
 - Use `pipenv install --dev` and `pipenv run python src/main.py --dev` for development server (includes hot reload, verbose logging, dev API key)
-- Use `pipenv run pre-commit run --all-files --show-diff-on-failure` for code quality checks
+- For code quality checks, run tools directly on changed Python files: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
+- For version bumps, run `./tools/bump_version {major|minor|patch}`; major and minor bumps reset lower version segments, and the script updates both project config and API docs
 - Use `pipenv install` and `pipenv run python src/main.py` for production runs
 - For all other operations like testing, always run inside of `pipenv`
 
 ### Code Quality
 
-- Always run linting before commits: `pipenv run pre-commit run`
+- Always run linting on changed Python files before commits: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
 - All scripts handle environment setup automatically (PYTHONPATH, .env files)
 
 ### Project Structure
 
-- All scripts are in `tools` directory and use common `messages.sh` for colored output
+- All scripts are in `tools` directory and use common `messages` for colored output
 - Scripts validate project root location and fail safely if run from wrong directory
-- Version is managed through `pyproject.toml` in project root
 - You can see other rules in `.cursor` directory, if you need those rules
 - You can see the CI/CD pipeline in `.github/workflows` directory
 - You can see the API docs in `docs/` directory (keep it updated!)

.claude/CLAUDE.md

@@ -8,6 +8,12 @@
 
 In Python, I want you to use the latest type syntax (`type | None`) instead of `Optional`. I also want you to use a single space (`=`) around the equals sign (`=`) in function argument calls. It's important to use double quotation marks (`"`) instead of single quotations (`'`). And finally, we want to always use trailing commas in multi-line function declarations and calls. There's never a reason to write `unittest.main()` manually, we have a script for running tests. Never use inline imports inside of functions (use file header even in tests), and always use `from ... import ...` syntax at the top of the file.
 
+### Comments
+
+- For new code, avoid comments unless the logic is genuinely complex or the block is long
+- When editing existing code, prefer updating comments over deleting them
+- Comments should start with a lowercase letter, except in documentation or where grammar requires it
+
 ## Error Handling
 
 Never use generic `ValueError`, `AssertionError`, or bare `Exception` for raising errors. Always use the structured exceptions from `util.errors` (`ValidationError`, `NotFoundError`, `AuthorizationError`, `ExternalServiceError`, `RateLimitError`, `ConfigurationError`, `InternalError`). Each raise must include an error code from `util.error_codes`. When re-raising from a caught exception, always use `raise ... from e` to preserve the chain. When calling external services (LLMs, image APIs, web fetchers), always guard against empty/null/empty-array responses with `ExternalServiceError`.
@@ -20,27 +26,27 @@ Never use generic `ValueError`, `AssertionError`, or bare `Exception` for raisin
 
 ## Database Migrations
 
-- Ask the user to run `./tools/db_generate_migration.sh -y` to generate new Alembic migrations (auto-generates based on model changes)
-- Ask the user to run `./tools/db_apply_migration.sh` to apply migrations to database (only with user's approval)
-- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration.sh`
+- Ask the user to run `./tools/db_generate_migration -y` to generate new Alembic migrations (auto-generates based on model changes)
+- Ask the user to run `./tools/db_apply_migration` to apply migrations to database (only with user's approval)
+- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration`
 
 ## Development Workflow
 
 - Use `pipenv install --dev` and `pipenv run python src/main.py --dev` for development server (includes hot reload, verbose logging, dev API key)
-- Use `pipenv run pre-commit run --all-files --show-diff-on-failure` for code quality checks
+- For code quality checks, run tools directly on changed Python files: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
+- For version bumps, run `./tools/bump_version {major|minor|patch}`; major and minor bumps reset lower version segments, and the script updates both project config and API docs
 - Use `pipenv install` and `pipenv run python src/main.py` for production runs
 - For all other operations like testing, always run inside of `pipenv`
 
 ## Code Quality
 
-- Always run linting before commits: `pipenv run pre-commit run`
+- Always run linting on changed Python files before commits: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
 - All scripts handle environment setup automatically (PYTHONPATH, .env files)
 
 ## Project Structure
 
-- All scripts are in `tools` directory and use common `messages.sh` for colored output
+- All scripts are in `tools` directory and use common `messages` for colored output
 - Scripts validate project root location and fail safely if run from wrong directory
-- Version is managed through `pyproject.toml` in project root
 - You can see other rules in `.cursor` directory, if you need those rules
 - You can see the CI/CD pipeline in `.github/workflows` directory
 - You can see the API docs in `docs/` directory (keep it updated!)

.cursor/rules/tooling.mdc

@@ -1,6 +1,6 @@
 ---
 description:
-globs: *.py, *.sh
+globs: *.py, tools/*
 alwaysApply: true
 ---
 ## MANDATORY PROJECT RULES
@@ -13,27 +13,27 @@ alwaysApply: true
 
 ### Database Migrations
 
-- Ask the user to run `./tools/db_generate_migration.sh -y` to generate new Alembic migrations (auto-generates based on model changes)
-- Ask the user to run `./tools/db_apply_migration.sh` to apply migrations to database (only with user's approval)
-- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration.sh`
+- Ask the user to run `./tools/db_generate_migration -y` to generate new Alembic migrations (auto-generates based on model changes)
+- Ask the user to run `./tools/db_apply_migration` to apply migrations to database (only with user's approval)
+- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration`
 
 ### Development Workflow
 
 - Use `pipenv install --dev` and `pipenv run python src/main.py --dev` for development server (includes hot reload, verbose logging, dev API key)
-- Use `pipenv run pre-commit run --all-files --show-diff-on-failure` for code quality checks
+- For code quality checks, run tools directly on changed Python files: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
+- For version bumps, run `./tools/bump_version {major|minor|patch}`; major and minor bumps reset lower version segments, and the script updates both project config and API docs
 - Use `pipenv install` and `pipenv run python src/main.py` for production runs
 - For all other operations like testing, always run inside of `pipenv`
 
 ### Code Quality
 
-- Always run linting before commits: `pipenv run pre-commit run`
+- Always run linting on changed Python files before commits: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
 - All scripts handle environment setup automatically (PYTHONPATH, .env files)
 
 ### Project Structure
 
-- All scripts are in `tools` directory and use common `messages.sh` for colored output
+- All scripts are in `tools` directory and use common `messages` for colored output
 - Scripts validate project root location and fail safely if run from wrong directory
-- Version is managed through `pyproject.toml` in project root
 - You can see other rules in `.cursor` directory, if you need those rules
 - You can see the CI/CD pipeline in `.github/workflows` directory
 - You can see the API docs in `docs/` directory (keep it updated!)

.windsurf/rules/rules.md

@@ -4,6 +4,12 @@
 
 In Python, I want you to use the latest type syntax (`type | None`) instead of `Optional`. I also want you to use a single space (`=`) around the equals sign (`=`) in function argument calls. It's important to use double quotation marks (`"`) instead of single quotations (`'`). And finally, we want to always use trailing commas in multi-line function declarations and calls. There's never a reason to write `unittest.main()` manually, we have a script for running tests. Never use inline imports inside of functions (use file header even in tests), and always use `from ... import ...` syntax at the top of the file.
 
+### Comments
+
+- For new code, avoid comments unless the logic is genuinely complex or the block is long
+- When editing existing code, prefer updating comments over deleting them
+- Comments should start with a lowercase letter, except in documentation or where grammar requires it
+
 ### Error Handling
 
 Never use generic `ValueError`, `AssertionError`, or bare `Exception` for raising errors. Always use the structured exceptions from `util.errors` (`ValidationError`, `NotFoundError`, `AuthorizationError`, `ExternalServiceError`, `RateLimitError`, `ConfigurationError`, `InternalError`). Each raise must include an error code from `util.error_codes`. When re-raising from a caught exception, always use `raise ... from e` to preserve the chain. When calling external services (LLMs, image APIs, web fetchers), always guard against empty/null/empty-array responses with `ExternalServiceError`.
@@ -20,26 +26,26 @@ Never use generic `ValueError`, `AssertionError`, or bare `Exception` for raisin
 
 ### Database Migrations
 
-- Ask the user to run `./tools/db_generate_migration.sh -y` to generate new Alembic migrations (auto-generates based on model changes)
-- Ask the user to run `./tools/db_apply_migration.sh` to apply migrations to database (only with user's approval)
-- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration.sh`
+- Ask the user to run `./tools/db_generate_migration -y` to generate new Alembic migrations (auto-generates based on model changes)
+- Ask the user to run `./tools/db_apply_migration` to apply migrations to database (only with user's approval)
+- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration`
 
 ### Development Workflow
 
 - Use `pipenv install --dev` and `pipenv run python src/main.py --dev` for development server (includes hot reload, verbose logging, dev API key)
-- Use `pipenv run pre-commit run --all-files --show-diff-on-failure` for code quality checks
+- For code quality checks, run tools directly on changed Python files: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
+- For version bumps, run `./tools/bump_version {major|minor|patch}`; major and minor bumps reset lower version segments, and the script updates both project config and API docs
 - Use `pipenv install` and `pipenv run python src/main.py` for production runs
 - For all other operations like testing, always run inside of `pipenv`
 
 ### Code Quality
 
-- Always run linting before commits: `pipenv run pre-commit run`
+- Always run linting on changed Python files before commits: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
 - All scripts handle environment setup automatically (PYTHONPATH, .env files)
 
 ### Project Structure
 
-- All scripts are in `tools` directory and use common `messages.sh` for colored output
+- All scripts are in `tools` directory and use common `messages` for colored output
 - Scripts validate project root location and fail safely if run from wrong directory
-- Version is managed through `pyproject.toml` in project root
 - You can see the CI/CD pipeline in `.github/workflows` directory
 - You can see the API docs in `docs/` directory (keep it updated!)

AGENTS.md

@@ -4,6 +4,12 @@
 
 In Python, I want you to use the latest type syntax (`type | None`) instead of `Optional`. I also want you to use a single space (`=`) around the equals sign (`=`) in function argument calls. It's important to use double quotation marks (`"`) instead of single quotations (`'`). And finally, we want to always use trailing commas in multi-line function declarations and calls. There's never a reason to write `unittest.main()` manually, we have a script for running tests. Never use inline imports inside of functions (use file header even in tests), and always use `from ... import ...` syntax at the top of the file.
 
+### Comments
+
+- For new code, avoid comments unless the logic is genuinely complex or the block is long
+- When editing existing code, prefer updating comments over deleting them
+- Comments should start with a lowercase letter, except in documentation or where grammar requires it
+
 ### Error Handling
 
 Never use generic `ValueError`, `AssertionError`, or bare `Exception` for raising errors. Always use the structured exceptions from `util.errors` (`ValidationError`, `NotFoundError`, `AuthorizationError`, `ExternalServiceError`, `RateLimitError`, `ConfigurationError`, `InternalError`). Each raise must include an error code from `util.error_codes`. When re-raising from a caught exception, always use `raise ... from e` to preserve the chain. When calling external services (LLMs, image APIs, web fetchers), always guard against empty/null/empty-array responses with `ExternalServiceError`.
@@ -20,27 +26,27 @@ Never use generic `ValueError`, `AssertionError`, or bare `Exception` for raisin
 
 ### Database Migrations
 
-- Ask the user to run `./tools/db_generate_migration.sh -y` to generate new Alembic migrations (auto-generates based on model changes)
-- Ask the user to run `./tools/db_apply_migration.sh` to apply migrations to database (only with user's approval)
-- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration.sh`
+- Ask the user to run `./tools/db_generate_migration -y` to generate new Alembic migrations (auto-generates based on model changes)
+- Ask the user to run `./tools/db_apply_migration` to apply migrations to database (only with user's approval)
+- Always check if model imports in `src/db/alembic/env.py` are up to date before running `db_generate_migration`
 
 ### Development Workflow
 
 - Use `pipenv install --dev` and `pipenv run python src/main.py --dev` for development server (includes hot reload, verbose logging, dev API key)
-- Use `pipenv run pre-commit run --all-files --show-diff-on-failure` for code quality checks
+- For code quality checks, run tools directly on changed Python files: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
+- For version bumps, run `./tools/bump_version {major|minor|patch}`; major and minor bumps reset lower version segments, and the script updates both project config and API docs
 - Use `pipenv install` and `pipenv run python src/main.py` for production runs
 - For all other operations like testing, always run inside of `pipenv`
 
 ### Code Quality
 
-- Always run linting before commits: `pipenv run pre-commit run`
+- Always run linting on changed Python files before commits: `pipenv run ruff check --fix <files>` and `pipenv run python tools/check_spacing.py --fix <files>`
 - All scripts handle environment setup automatically (PYTHONPATH, .env files)
 
 ### Project Structure
 
-- All scripts are in `tools` directory and use common `messages.sh` for colored output
+- All scripts are in `tools` directory and use common `messages` for colored output
 - Scripts validate project root location and fail safely if run from wrong directory
-- Version is managed through `pyproject.toml` in project root
 - You can see other rules in `.cursor` directory, if you need those rules
 - You can see the CI/CD pipeline in `.github/workflows` directory
 - You can see the API docs in `docs/` directory (keep it updated!)