docs: update the docs for the PHP 8.1 update

README.md

@@ -31,7 +31,7 @@ This path is designed for developers who want both a fast start and a clearer un
 
 The current Quantum 3.x baseline requires:
 
-- PHP 8.0 or newer
+- PHP 8.1 or newer
 - Composer
 - PHP extensions: `pdo`, `curl`, `json`, `simplexml`, `fileinfo`, `openssl`, `bcmath`
 

v3.0/cli/code-generation.md

@@ -150,18 +150,50 @@ This is another example where `qt` generates project state, not just source file
 
 ## OpenAPI resource generation
 
-Quantum also includes:
+Say you generated an API module from the `DefaultApi` or `DemoApi` template and want a page where you can read and try the API. Run:
 
 ```bash
 php qt install:openapi Api
 ```
 
-From the upstream `OpenApiCommand`, this command can:
+Then open `/api/docs` for the Swagger UI page. The specification itself is served at `/api/spec`. Both routes sit under the module's route prefix, so a module with another prefix serves them there.
+
+The command:
+
+- publishes the Swagger UI resources into the public assets directory, and creates that folder when it is missing
+- adds an `openapi` route group with the `docs` and `spec` routes to the module's routes when it has none
+- creates the module's `resources/openapi/` directory, and `resources/` when the module has none
+- generates `spec.json` from the controllers in the module's `Controllers/OpenApi` folder
+
+The API templates ship that folder with the documentation already written as PHP attributes. `OpenApiController` describes the API and its security scheme, and each operation is an attribute on an abstract controller method:
+
+```php
+use OpenApi\Attributes as OA;
+
+abstract class OpenApiMainController extends OpenApiController
+{
+    #[OA\Get(
+        path: '/Api',
+        tags: ['Api'],
+        summary: 'Get status of Api',
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Successful response',
+                content: new OA\JsonContent(
+                    type: 'object',
+                    properties: [
+                        new OA\Property(property: 'status', type: 'string', example: 'success'),
+                    ]
+                )
+            ),
+        ]
+    )]
+    abstract public function index();
+}
+```
 
-- publish OpenAPI UI resources into the public assets directory
-- update the target module routes for OpenAPI endpoints when needed
-- create the module `resources/openapi/` directory
-- generate an OpenAPI `spec.json` file from controller annotations
+Documentation written as `@OA\...` docblock annotations is only read when `doctrine/annotations` is installed, and the framework no longer requires it. Without it `install:openapi` fails with `Required @OA\PathItem() not found`. Convert the annotations to attributes, or require `doctrine/annotations` in your application.
 
 So `qt` is also able to generate API documentation resources, not only application scaffolding.
 

v3.0/installation.md

@@ -6,7 +6,7 @@ This guide walks you through installing and running a new Quantum PHP project.
 
 Make sure your environment includes:
 
-* **PHP 8.0+**;
+* **PHP 8.1+**;
 * **PHP extensions**:
   * PDO
   * curl
@@ -19,7 +19,7 @@ Make sure your environment includes:
 
 Optional framework features may require additional extensions or packages such as `redis`, `memcached`, `zip`, `dom`, or `twig/twig`.
 
-Practical note: run `php -v` to check your PHP version before you start. Quantum needs PHP 8.0 or newer.
+Practical note: run `php -v` to check your PHP version before you start. Quantum needs PHP 8.1 or newer.
 
 ### Installation Steps
 

v3.0/packages/console/built-in-commands.md

@@ -113,7 +113,7 @@ Publishes DebugBar assets into `public/assets/DebugBar/Resources`.
 
 Publishes Swagger UI assets if needed, injects an `openapi` route group into the module route file when missing, and writes `resources/openapi/spec.json` for the target module.
 
-Use it only after the module exists and has OpenAPI-annotated controllers in `Controllers/OpenApi`.
+Use it only after the module exists and has controllers with OpenAPI attributes in `Controllers/OpenApi`. See [OpenAPI resource generation](../../cli/code-generation.md#openapi-resource-generation) for what it produces and how the documentation is written.
 
 ### `install:toolkit <username> <password>`
 

v3.0/packages/tracer/contracts.md

@@ -15,6 +15,8 @@ $handler->setup($logger);
 
 `handleError()` converts enabled PHP errors into `ErrorException`.
 
+A deprecation (`E_DEPRECATED` or `E_USER_DEPRECATED`) is the exception. It only warns about a future PHP version, often from a library you do not control, so it should not stop the request. `handleError()` logs it with `warning()` as `<message> in <file>:<line>` and returns `true`, and the script goes on. When no logger is set, the deprecation is ignored.
+
 Suppressed or masked severities are ignored (`false` return), so `@` suppression still works.
 
 ## Severity mapping contract

v3.0/packages/tracer/overview.md

@@ -25,7 +25,8 @@ $handler->setup($logger);
 After setup:
 
 - enabled PHP errors become `ErrorException` instances
-- uncaught throwables are routed by runtime (`cli` or web)
+- deprecations are [logged as warnings](contracts.md#error-conversion-contract) instead, and the script goes on
+- uncaught throwables are routed by app type (console or web)
 - web requests return HTTP 500 for uncaught exceptions
 - production web requests log the exception before rendering the response