chore(docs): move documentation to main repository

.github/workflows/deploy-docs.yml

@@ -0,0 +1,20 @@
+name: Deploy documentation
+on:
+  push:
+    branches:
+      - main
+      - 2.x
+
+jobs:
+  trigger:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger documentation deployment
+        uses: octokit/request-action@v2.0.0
+        with:
+          route: POST /repos/:owner/:repo/dispatches
+          owner: tempestphp
+          repo: tempest-docs
+          event_type: deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

bun.lock

@@ -3,18 +3,18 @@
   "workspaces": {
     "": {
       "devDependencies": {
-        "@types/bun": "1.2.19",
-        "bumpp": "10.2.1",
-        "dprint": "0.50.1",
-        "typescript": "5.8.3",
+        "@types/bun": "latest",
+        "bumpp": "^10.0.1",
+        "dprint": "^0.50.0",
+        "typescript": "^5.7.3",
         "unbuild": "^3.3.1",
         "vite-plugin-tempest": "workspace:*",
-        "vitest": "3.2.4",
+        "vitest": "^3.2.3",
       },
     },
     "packages/vite-plugin-tempest": {
       "name": "vite-plugin-tempest",
-      "version": "1.5.0",
+      "version": "1.6.0",
       "dependencies": {
         "@innocenzi/utils": "^0.3.0",
         "picocolors": "^1.1.1",
@@ -192,7 +192,7 @@
 
     "@trysound/sax": ["@trysound/sax@0.2.0", "", {}, "sha512-L7z9BgrNEcYyUYtF+HaEfiS5ebkh9jXqbszz7pC0hRBPaatV0XjSD3+eHrpqFemQfgwiFF0QPIarnIihIDn7OA=="],
 
-    "@types/bun": ["@types/bun@1.2.19", "", { "dependencies": { "bun-types": "1.2.19" } }, "sha512-d9ZCmrH3CJ2uYKXQIUuZ/pUnTqIvLDS0SK7pFmbx8ma+ziH/FRMoAq5bYpRG7y+w1gl+HgyNZbtqgMq4W4e2Lg=="],
+    "@types/bun": ["@types/bun@1.2.20", "", { "dependencies": { "bun-types": "1.2.20" } }, "sha512-dX3RGzQ8+KgmMw7CsW4xT5ITBSCrSbfHc36SNT31EOUg/LA9JWq0VDdEXDRSe1InVWpd2yLUM1FUF/kEOyTzYA=="],
 
     "@types/chai": ["@types/chai@5.2.2", "", { "dependencies": { "@types/deep-eql": "*" } }, "sha512-8kB30R7Hwqf40JPiKhVzodJs2Qc1ZJ5zuT3uzw5Hq/dhNCl3G3l83jfpdI1e20BP348+fV7VIL/+FxaXkqBmWg=="],
 
@@ -236,7 +236,7 @@
 
     "bumpp": ["bumpp@10.2.1", "", { "dependencies": { "ansis": "^4.1.0", "args-tokenizer": "^0.3.0", "c12": "^3.1.0", "cac": "^6.7.14", "escalade": "^3.2.0", "jsonc-parser": "^3.3.1", "package-manager-detector": "^1.3.0", "semver": "^7.7.2", "tinyexec": "^1.0.1", "tinyglobby": "^0.2.14", "yaml": "^2.8.0" }, "bin": { "bumpp": "bin/bumpp.mjs" } }, "sha512-Dhgao1WhrcMg+1R3GU+57e6grUNNIGORN53YllDFurNEVGWmkD/z63R3xX4Sl9IqEw//1/UxbrvmK8V1pcJDHw=="],
 
-    "bun-types": ["bun-types@1.2.19", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-uAOTaZSPuYsWIXRpj7o56Let0g/wjihKCkeRqUBhlLVM/Bt+Fj9xTo+LhC1OV1XDaGkz4hNC80et5xgy+9KTHQ=="],
+    "bun-types": ["bun-types@1.2.20", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-pxTnQYOrKvdOwyiyd/7sMt9yFOenN004Y6O4lCcCUoKVej48FS5cvTw9geRaEcB9TsDZaJKAxPTVvi8tFsVuXA=="],
 
     "c12": ["c12@3.1.0", "", { "dependencies": { "chokidar": "^4.0.3", "confbox": "^0.2.2", "defu": "^6.1.4", "dotenv": "^16.6.1", "exsolve": "^1.0.7", "giget": "^2.0.0", "jiti": "^2.4.2", "ohash": "^2.0.11", "pathe": "^2.0.3", "perfect-debounce": "^1.0.0", "pkg-types": "^2.2.0", "rc9": "^2.1.2" }, "peerDependencies": { "magicast": "^0.3.5" }, "optionalPeers": ["magicast"] }, "sha512-uWoS8OU1MEIsOv8p/5a82c3H31LsWVR5qiyXVfBNOzfffjUWtPnhAb4BYI2uG2HfGmZmFjCtui5XNWaps+iFuw=="],
 

docs/0-getting-started/01-introduction.md

@@ -0,0 +1,193 @@
+---
+title: Introduction
+description: "Tempest is a framework for PHP development, designed to get out of your way. Its core philosophy is to help you focus on your application code, without being bothered hand-holding the framework."
+---
+
+Tempest's goal is to make you more productive when building web and console apps in PHP. It handles all the boilerplate parts of such projects for you, so that you can focus on what matters the most: writing application code.
+
+People using Tempest say it's the sweet spot between the robustness of Symfony and the eloquence of Laravel. It feels lightweight and close to vanilla PHP; and yet powerful and feature-rich. On this page, you'll read what sets Tempest apart as a framework for modern PHP development. If you're already convinced, you can head over to the [installation page](../0-getting-started/02-installation.md) and get started with Tempest.
+
+## Vision
+
+Tempest's vision can be summarized like this: **it's a community-driven, modern PHP framework that gets out of your way and dares to think outside the box**. Let's dissect that vision in depth.
+
+### Community driven
+
+Tempest started out as an educational project, without the intention for it to be something real. People picked up on it, though, and it was only after a strong community had formed that we considered making it something real.
+
+Currently, there are three core members dedicating a lot of their time to Tempest, as well as over [50 additional contributors](https://github.com/tempestphp/tempest-framework). We have an active [Discord server](/discord) with close to 400 members.
+
+Tempest isn't a solo project and never has been. It is a new framework and has a way to go compared to Symfony or Laravel, but there already is significant momentum and will only keep growing.
+
+### Embracing modern PHP
+
+The benefit of starting from scratch like Tempest did is having a clean slate. Tempest embraced modern PHP features from the start, and its goal is to keep doing this in the future by shipping built-in upgraders whenever breaking changes happen (think of it as Laravel Shift, but built into the framework).
+
+Just to name a couple of examples, Tempest uses property hooks:
+
+```php
+interface DatabaseMigration
+{
+    public string $name {
+        get;
+    }
+
+    public function up(): ?QueryStatement;
+
+    public function down(): ?QueryStatement;
+}
+```
+
+Attributes:
+
+```php
+final class BookController
+{
+    #[Get('/books/{book}')]
+    public function show(Book $book): Response { /* … */ }
+}
+```
+
+Proxy objects:
+
+```php
+use Tempest\Container\Proxy;
+
+final readonly class BookController
+{
+    public function __construct(
+        #[Proxy] private SlowDependency $slowDependency,
+    ) { /* … */ }
+}
+```
+
+And a lot more.
+
+### Getting out of your way
+
+A core part of Tempest's philosophy is that it wants to "get out of your way" as best as possible. For starters, Tempest is designed to structure your project code however you want, without making any assumptions or forcing conventions on you. You can prefer a classic MVC application, DDD or hexagonal design, microservices, or something else; Tempest works with any project structure out of the box without any configuration.
+
+Behind Tempest's flexibility is one of its most powerful features: [discovery](../internals/discovery). Discovery gives Tempest a great number of insights into your codebase, without any handholding. Discovery handles routing, console commands, view components, event listeners, command handlers, middleware, schedules, migrations, and more.
+
+```php
+final class ConsoleCommandDiscovery implements Discovery
+{
+    use IsDiscovery;
+
+    public function __construct(
+        private readonly ConsoleConfig $consoleConfig,
+    ) {}
+
+    public function discover(DiscoveryLocation $location, ClassReflector $class): void
+    {
+        foreach ($class->getPublicMethods() as $method) {
+            if ($consoleCommand = $method->getAttribute(ConsoleCommand::class)) {
+                $this->discoveryItems->add($location, [$method, $consoleCommand]);
+            }
+        }
+    }
+
+    public function apply(): void
+    {
+        foreach ($this->discoveryItems as [$method, $consoleCommand]) {
+            $this->consoleConfig->addCommand($method, $consoleCommand);
+        }
+    }
+}
+```
+
+Discovery makes Tempest truly understand your codebase so that you don't have to explain the framework how to use it. Of course, discovery is heavily optimized for local development and entirely cached in production, so there's no performance overhead. Even better: discovery isn't just a core framework feature, you're encouraged to write your own project-specific discovery classes wherever they make sense. That's the Tempest way.
+
+Besides Discovery, Tempest is designed to be extensible. You'll find that any part of the framework can be replaced and hooked into by implementing an interface and plugging it into the container. No fighting the framework, Tempest gets out of your way.
+
+```php
+use Tempest\View\ViewRenderer;
+
+$container->singleton(ViewRenderer::class, $myCustomViewRenderer);
+```
+
+### Thinking outside the box
+
+Finally, since Tempest originated as an educational project, many Tempest features dare to rethink the things we've gotten used to. For example, [console commands](../1-essentials/04-console-commands), which in Tempest are designed to be very similar to controller actions:
+
+```php
+final readonly class BooksCommand
+{
+    use HasConsole;
+
+    public function __construct(
+        private BookRepository $repository,
+    ) {}
+
+    #[ConsoleCommand]
+    public function find(?string $initial = null): void
+    {
+        $book = $this->search(
+            'Find your book',
+            $this->repository->find(...),
+        );
+    }
+
+    #[ConsoleCommand(middleware: [CautionMiddleware::class])]
+    public function delete(string $title, bool $verbose = false): void 
+    { /* … */ }
+}
+```
+
+Or what about [Tempest's ORM](../1-essentials/03-database), which aims to have truly decoupled models:
+
+```php
+use Tempest\Validation\Rules\Length;
+use App\Author;
+
+final class Book
+{
+    #[Length(min: 1, max: 120)]
+    public string $title;
+
+    public ?Author $author = null;
+
+    /** @var \App\Chapter[] */
+    public array $chapters = [];
+}
+```
+
+```php
+final class BookRepository
+{
+    public function findById(int $id): Book
+    {
+        return query(Book::class)
+            ->select()
+            ->with('chapters', 'author')
+            ->where('id = ?', $id)
+            ->first();
+    }
+}
+```
+
+Then there's our view engine, which embraces the most original template engine of all time: HTML;
+
+```html
+<x-base :title="$this->seo->title">
+    <ul>
+        <li :foreach="$this->books as $book">
+            {{ $book->title }}
+
+            <span :if="$this->showDate($book)">
+                <x-tag>
+                    {{ $book->publishedAt }}
+                </x-tag>
+            </span>
+        </li>
+    </ul>
+</x-base>
+```
+
+## Getting started
+
+Are you intrigued? Want to give Tempest a try? Head over to [the next chapter](../0-getting-started/02-installation.md) to learn about how to get started with Tempest.
+
+If you want to become part of our community, you're more than welcome to [join our Discord server](/discord), and to check out [Tempest on GitHub](https://github.com/tempestphp/tempest-framework).
+
+Enjoy!

docs/0-getting-started/02-installation.md

@@ -0,0 +1,136 @@
+---
+title: Installation
+description: Tempest can be installed as a standalone PHP project, as well as a package within existing projects. The framework modules can also be installed individually, including in projects built on other frameworks.
+---
+
+## Prerequisites
+
+Tempest requires PHP [8.4+](https://www.php.net/downloads.php) and [Composer](https://getcomposer.org/) to be installed. Optionally, you may install either [Bun](https://bun.sh) or [Node](https://nodejs.org) if you chose to bundle front-end assets.
+
+For a better experience, it is recommended to have a complete development environment, such as [ServBay](https://www.servbay.com), [Herd](https://herd.laravel.com/docs), or [Valet](https://laravel.com/docs/valet). However, Tempest can serve applications using PHP's built-in server just fine.
+
+Once the prerequisites are installed, you can chose your installation method. Tempest can be a [standalone application](#creating-a-tempest-application), or be added [in an existing project](#tempest-as-a-package)—even one built on top of another framework.
+
+## Creating a Tempest application
+
+To get started with a new Tempest project, you may use {`tempest/app`} as the starting point. The `composer create-project` command will scaffold it for you:
+
+```sh
+{:hl-keyword:composer:} create-project tempest/app {:hl-type:my-app:}
+{:hl-keyword:cd:} {:hl-type:my-app:}
+```
+
+If you have a dedicated development environment, you may then access your application by opening `{txt}https://my-app.test` in your browser. Otherwise, you may use PHP's built-in server:
+
+```sh
+{:hl-keyword:php:} tempest serve
+{:hl-comment:PHP 8.4.5 Development Server (http://localhost:8000) started:}
+```
+
+### Scaffolding front-end assets
+
+Optionally, you may install a basic front-end scaffolding that includes [Vite](https://vite.dev/) and [Tailwind CSS](https://tailwindcss.com/). To do so, run the Vite installer and follow through the wizard:
+
+```sh
+{:hl-keyword:php:} tempest install vite --tailwind
+```
+
+The assets created by this wizard, `main.entrypoint.ts` and `main.entrypoint.css`, are automatically discovered by Tempest. You can serve them using the [`<x-vite-tags />`](../1-essentials/03-views#x-vite-tags) component in your templates.
+
+You may then [run the front-end development server](../1-essentials/04-asset-bundling#running-the-development-server), which will serve your assets on-the-fly:
+
+```bash
+{:hl-keyword:npm:} run dev
+```
+
+## Tempest as a package
+
+If you already have a project, you can opt to install {`tempest/framework`} as a standalone package. You could do this in any project; it could already contain code, or it could be an empty project.
+
+```sh
+{:hl-keyword:composer:} require tempest/framework
+```
+
+Installing Tempest this way will give you access to the Tempest console, `./vendor/bin/tempest`. Optionally, you can choose to install Tempest's entry points in your project. To do so, you may run the framework installer:
+
+```txt
+{:hl-keyword:./vendor/bin/tempest:} install framework
+```
+
+This installer will prompt you to install the following files into your project:
+
+- `public/index.php` — the web application entry point
+- `tempest` – the console application entry point
+- `.env.example` – a clean example of a `.env` file
+- `.env` – the real environment file for your local installation
+
+You can choose which files you want to install, and you can always rerun the `install` command at a later point in time.
+
+## Project structure
+
+Tempest won't impose any file structure on you: one of its core features is that it will scan all project and package code for you, and will automatically discover any files the framework needs to know about.
+
+For instance, Tempest is able to differentiate between a controller method and a console command by looking at the code, instead of relying on naming conventions or configuration files.
+
+:::info
+This concept is called [discovery](../4-internals/02-discovery), and is one of Tempest's most powerful features.
+:::
+
+The following project structures work the same way in Tempest, without requiring any specific configuration:
+
+```txt
+.                                    .
+└── src                              └── src
+    ├── Authors                          ├── Controllers
+    │   ├── Author.php                   │   ├── AuthorController.php
+    │   ├── AuthorController.php         │   └── BookController.php
+    │   └── authors.view.php             ├── Models
+    ├── Books                            │   ├── Author.php
+    │   ├── Book.php                     │   ├── Book.php
+    │   ├── BookController.php           │   └── Chapter.php
+    │   ├── Chapter.php                  ├── Services
+    │   └── books.view.php               │   └── PublisherGateway.php
+    ├── Publishers                       └── Views
+    │   └── PublisherGateway.php             ├── authors.view.php
+    └── Support                              ├── books.view.php
+        └── x-base.view.php                  └── x-base.view.php
+```
+
+## About discovery
+
+Discovery works by scanning your project code, and looking at each file and method individually to determine what that code does. In production environments, [Tempest will cache the discovery process](../4-internals/02-discovery#discovery-in-production), avoiding any performance overhead.
+
+As an example, Tempest is able to determine which methods are controller methods based on their route attributes, such as `#[Get]` or `#[Post]`:
+
+```php app/BlogPostController.php
+use Tempest\Router\Get;
+use Tempest\Http\Response;
+use Tempest\View\View;
+
+final readonly class BlogPostController
+{
+    #[Get('/blog')]
+    public function index(): View
+    { /* … */ }
+
+    #[Get('/blog/{post}')]
+    public function show(Post $post): Response
+    { /* … */ }
+}
+```
+
+Likewise, it is able to detect console commands based on the `#[ConsoleCommand]` attribute:
+
+```php app/RssSyncCommand.php
+use Tempest\Console\HasConsole;
+use Tempest\Console\ConsoleCommand;
+
+final readonly class RssSyncCommand
+{
+    use HasConsole;
+
+    #[ConsoleCommand('rss:sync')]
+    public function __invoke(bool $force = false): void
+    { /* … */ }
+}
+```