docs: clarify breaking changes in documentation for TorrentPier 3.0

- Updated CLAUDE.md, UPGRADE_GUIDE.md, src/Cache/README.md, and src/Database/README.md to consistently use "breaking changes" terminology.
- Enhanced src/Whoops/README.md to reflect integration with the new architecture.
- Improved error handling in DatabaseErrorHandler.php to ensure robustness against null inspector and frame conditions.

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-TorrentPier is a BitTorrent tracker engine written in PHP, designed for hosting BitTorrent communities with forum functionality. The project is undergoing a major 3.0 rewrite, transitioning from legacy code to modern PHP practices. **Backward compatibility is not a priority** - the focus is on moving forward with clean, modern architecture.
+TorrentPier is a BitTorrent tracker engine written in PHP, designed for hosting BitTorrent communities with forum functionality. The project is undergoing a major 3.0 rewrite, transitioning from legacy code to modern PHP practices. **Backward compatibility is not supported in 3.0** - legacy APIs will break and are not maintained as the focus is on moving forward with clean, modern architecture.
 
 ## Technology Stack & Architecture
 

UPGRADE_GUIDE.md

@@ -368,7 +368,7 @@ php vendor/bin/phinx status
 
 ## 🗄️ Database Layer Migration
 
-TorrentPier 3.0 has completely replaced its legacy database layer (SqlDb/Dbs) with a modern implementation using Nette Database. **Breaking Change**: This migration requires code updates for the new API.
+TorrentPier 3.0 has completely replaced its legacy database layer (SqlDb/Dbs) with a modern implementation using Nette Database. **Breaking changes**: This migration requires code updates for the new API.
 
 ### Code Changes Required
 
@@ -498,7 +498,7 @@ if (!$result) {
 
 ## 💾 Unified Cache System Migration
 
-TorrentPier 3.0 has replaced its legacy Cache and Datastore systems with a modern unified implementation using Nette Caching. **Breaking Change**: This migration requires updating your cache-related code.
+TorrentPier 3.0 has replaced its legacy Cache and Datastore systems with a modern unified implementation using Nette Caching. **Breaking changes**: This migration requires updating your cache-related code.
 
 ### Code Changes Required
 

src/Cache/README.md

@@ -1,14 +1,13 @@
 # Unified Cache System
 
-A modern, unified caching solution for TorrentPier 3.0 that uses **Nette Caching** internally. **Breaking Change**: This replaces the legacy Cache and Datastore APIs and requires code migration.
+A modern, unified caching solution for TorrentPier 3.0 that uses **Nette Caching** internally. **Breaking changes**: This replaces the legacy Cache and Datastore APIs and requires code migration.
 
 ## Overview
 
 The Unified Cache System addresses the complexity and duplication in TorrentPier's caching architecture by:
 
 - **Unifying** Cache and Datastore systems into a single, coherent solution
-- **Modernizing** the codebase with Nette's advanced caching features
+- **Modernizing** the caching layer with Nette's advanced features and breaking changes for better architecture
-- **Modernizing** the caching layer with breaking changes for better architecture
 - **Reducing** complexity and maintenance overhead
 - **Improving** performance with efficient singleton pattern and advanced features
 

src/Database/README.md

@@ -1,6 +1,6 @@
 # TorrentPier Database Layer
 
-This directory contains the new database layer for TorrentPier 3.0 that uses Nette Database internally. **Breaking Change**: This replaces the legacy SqlDb interface and requires code migration.
+This directory contains the new database layer for TorrentPier 3.0 that uses Nette Database internally. **Breaking changes**: This replaces the legacy SqlDb interface and requires code migration.
 
 ## Overview
 

src/Whoops/DatabaseErrorHandler.php

@@ -34,6 +34,11 @@ class DatabaseErrorHandler extends Handler implements HandlerInterface
         }
 
         $inspector = $this->getInspector();
+
+        if (!$inspector) {
+            return Handler::DONE;
+        }
+
         $exception = $inspector->getException();
 
         // Add database information to the exception frames
@@ -77,8 +82,16 @@ class DatabaseErrorHandler extends Handler implements HandlerInterface
      */
     private function addDatabaseContextToFrames($inspector): void
     {
+        if (!$inspector) {
+            return;
+        }
+
         $frames = $inspector->getFrames();
 
+        if (!$frames || empty($frames)) {
+            return;
+        }
+
         foreach ($frames as $frame) {
             $frameData = [];
 
@@ -138,10 +151,15 @@ class DatabaseErrorHandler extends Handler implements HandlerInterface
     private function addDatabaseInfoAsFrameComments(array $databaseInfo): void
     {
         $inspector = $this->getInspector();
+
+        if (!$inspector) {
+            return;
+        }
+
         $frames = $inspector->getFrames();
 
         // Find the first frame and add database info as comments
-        if (!empty($frames)) {
+        if (!empty($frames) && is_array($frames) && isset($frames[0])) {
             $firstFrame = $frames[0];
             $firstFrame->addComment('=== Database Information ===', '');
 

src/Whoops/README.md

@@ -125,7 +125,8 @@ The enhanced handlers maintain security by:
 ## Integration with TorrentPier 3.0
 
 All enhancements are:
+
 - **Integrated** with the new TorrentPier 3.0 architecture
 - **Modern** - designed for the rewritten codebase
 - **Optional** - only activated in debug mode
-- **Safe** - no security implications for production use
+- **Safe** - no security implications for production use