hawk-digital-environments
diff --git a/‎CLAUDE.md‎
Lines changed: 8 additions & 0 deletions b/‎CLAUDE.md‎
Lines changed: 8 additions & 0 deletions
diff --git a/‎_changelog/next-upgrade.md‎
Lines changed: 14 additions & 9 deletions b/‎_changelog/next-upgrade.md‎
Lines changed: 14 additions & 9 deletions
diff --git a/‎_changelog/next.md‎
Lines changed: 1 addition & 1 deletion b/‎_changelog/next.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎…2-GettingStarted/1-Local Installation.md‎ ‎…GettingStarted/100-Local-Installation.md‎_documentation/2-GettingStarted/1-Local Installation.md renamed to _documentation/100-GettingStarted/100-Local-Installation.md
Lines changed: 23 additions & 22 deletions b/‎…2-GettingStarted/1-Local Installation.md‎ ‎…GettingStarted/100-Local-Installation.md‎_documentation/2-GettingStarted/1-Local Installation.md renamed to _documentation/100-GettingStarted/100-Local-Installation.md
Lines changed: 23 additions & 22 deletions
@@ -0,0 +1,8 @@
+# HAWKI Project
+
+## Docker / Local Development
+
+All commands run inside Docker via `bin/env`. Never call `php`, `composer`, `phpunit`, `node`, or `npm` directly on the host.
+
+For the full command reference (container lifecycle, testing, code style, artisan, composer, docs, production builds), see:
+`_documentation/2-GettingStarted/2-Local Docker Installation.md` — section **"The `bin/env` command reference"**
@@ -2,9 +2,14 @@
 
 ## Overview
 
-[//]: # (Briefly describe what makes this upgrade different from a routine update)
-
-[//]: # (and why manual intervention is required.)
+> **BEWARE**
+>
+> This upgrade introduces **LOTS of breaking changes**! If you have customized HAWKI to match your needs, we strongly recommend to **NOT UPGRADE** to this version. Version %%VERSION%% lays the foundation for a new major version; v3.0, and cleans up many legacy APIs and code paths. If you have custom code that depended on those, it will break after upgrading. However, we still have a lot to refactor,
+> so we can not guarantee that the versions until v3.0 will not break your custom code again. Therefore, if you have custom code, we recommend to **stay on your current version** until v3.0 is released and then upgrade directly to v3.0.
+>
+> **v3.0 is expected to be released in Q3 2026.**
+>
+> If you have not customized HAWKI, you can safely upgrade to this version. Follow the steps below to ensure a smooth upgrade.
 
 ## Steps
 
@@ -123,12 +128,12 @@ php artisan ai:config:sync
 
 The following classes have been removed. Update any custom code that references them:
 
-| Removed | Replacement |
-|---|---|
-| `FileConverterFactory` | Inject `FileConverterInterface` directly; call `isAvailable()` to check if a converter is configured |
-| `AttachmentService` / `AttachmentFactory` | `AttachmentRepository` |
-| `MessageHandlerFactory` | Resolve `PrivateMessageHandler` / `GroupMessageHandler` from the Laravel service container |
-| `ExternalCommunicationCheck` middleware | `ExternalAccessMiddleware` or `AppAccessMiddleware` — configure feature toggles in `config/external_access.php` |
+| Removed                                   | Replacement                                                                                                     |
+|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
+| `FileConverterFactory`                    | Inject `FileConverterInterface` directly; call `isAvailable()` to check if a converter is configured            |
+| `AttachmentService` / `AttachmentFactory` | `AttachmentRepository`                                                                                          |
+| `MessageHandlerFactory`                   | Resolve `PrivateMessageHandler` / `GroupMessageHandler` from the Laravel service container                      |
+| `ExternalCommunicationCheck` middleware   | `ExternalAccessMiddleware` or `AppAccessMiddleware` — configure feature toggles in `config/external_access.php` |
 
 ## 8. Update custom code reading `AiModel` attributes
 
 
@@ -15,7 +15,7 @@
 - Added the **SyncLog system** for real-time synchronization of server-side state changes. Supports both incremental and full sync strategies with entity-specific handlers (rooms, messages, users, members, invitations, AI models, etc.). Provides a REST API endpoint and broadcasts events via WebSocket, enabling clients to stay in sync efficiently.
 - Added **User Keychain** — a secure per-user storage system for cryptographic key material and configuration data. Supports symmetric, asymmetric, and hybrid crypto value types with dedicated Eloquent casts. Includes REST endpoints for managing keychain values.
 - Added **message threading support**. Messages can now belong to threads via `thread_id` and `has_thread` columns. Thread parent tracking is handled automatically via event listeners. Existing messages are backfilled via migrations.
-- Added **System Prompt management** via `SystemPromptProvider`. Supports multiple prompt types (DEFAULT, SUMMARY, IMPROVEMENT, NAME) with locale-aware resolution and caching.
+- Added **System Prompt management** via `SystemPromptRepository`. Supports multiple prompt types (DEFAULT, SUMMARY, IMPROVEMENT, NAME) with locale-aware resolution.
 - Added **locale-aware AI model descriptions**: administrators can now provide human-readable descriptions for each AI model in multiple languages. Users see descriptions in their preferred locale automatically via the new `/api/v1/ai-model-descriptions` endpoint.
 - Added **AI model flags**: models can now be tagged with status flags (e.g. experimental, deprecated) that carry a label, description, and color code for display in the frontend. Flags are managed server-side and exposed via `/api/v1/ai-model-flags`.
 - Introduced the **Frontend Migrations system** — a structured mechanism for managing schema and data migrations on the client side. Applied migrations are tracked per user in the database, ensuring each migration runs exactly once across deployments. Exposed via `/api/v1/migrations`.
 
@@ -5,10 +5,10 @@ sidebar_position: 1
 # Local Installation
 
 This chapter of the documentation focuses on setting up and running HAWKI 2.0 on your local system. If you prefer to
-create a local Docker environment follow [Local Docker Installation](2-Local%20Docker%20Installation.md)
+create a local Docker environment follow [Local Docker Installation](200-Local-Docker-Installation.md)
 
 > *Although we strongly recommend that you first test HAWKI on your local device before deploying it on the server, If
-you want to skip this please read the ["Deployment"](../5-Deployment/1-Apache%20Server.md) chapter*
+you want to skip this please read the ["Deployment"](../300-Deployment/100-Apache-Server.md) chapter*
 
 ---
 
@@ -52,23 +52,21 @@ Ensure that you have the basic PHP modules, node and composer to run HAWKI on yo
 
 2. **Install Dependencies**
 
-
 Now that you have the project files on your machine, navigate to the project folder and run:
 
    ```
    php hawki init
    ```
 
 This command will:
+
 - Create `.env` file from `.env.example`
 - Set up required configuration files
 - Install Composer dependencies
 - Install npm packages
 - Create storage symlinks
 - Generate application keys and security salts
 
-
-
 Alternatively, if you can install dependencies and prepare the project manually:
 
 1. Locate the `.env.example` file in the root directory. Rename it to `.env` by removing the .example extension.
@@ -83,7 +81,7 @@ At this point the dependency packages should be installed. `node_modules` and `v
 
 
 
-><details> 
+> <details> 
 ><summary>Tip! Continue to next steps with "-all" flag</summary>
 > For a complete guided setup process use the flag "-all" to automatically proceed to next steps:
 > ```
@@ -99,10 +97,10 @@ At this point the dependency packages should be installed. `node_modules` and `v
 ### Configuration
 
 To configure the environment variable open `.env` file in the root directory.
-For a complete guide to environment variables please refer to [.env section](../3-architecture/10-dot%20Env.md) of the
+For a complete guide to environment variables please refer to [.env section](../200-Configuration/100-dot-Env.md) of the
 documentation.
 
-><details>
+> <details>
 ><summary>Use HAWKI CLI for step-by-step configuration</summary>
 >
 >You can also configure your environment variables using the HAWKI CLI interactive setup
@@ -119,7 +117,7 @@ documentation.
 
 **General**
 
->If you have used HAWKI CLI to initialize the project in the previous step, some attributes like Keys and Salts must have been automatically filled.
+> If you have used HAWKI CLI to initialize the project in the previous step, some attributes like Keys and Salts must have been automatically filled.
 >
 >Moreover, some of the attributes have already default values, which do not necessarily need be changed.
 
@@ -134,11 +132,11 @@ APP_URL="http://127.0.0.1:8000"     //for local dev, change the port if needed
 
 **AI Connection**
 
-In AI Connection section you can add your API Keys and URLs. 
+In AI Connection section you can add your API Keys and URLs.
 To start you need to have at least one API key to establish connection with one the AI providers (
-[OpenAI](https://platform.openai.com/docs/quickstart), 
-[GWDG](https://docs.hpc.gwdg.de/index.html), 
-[Google](https://ai.google.dev/), 
+[OpenAI](https://platform.openai.com/docs/quickstart),
+[GWDG](https://docs.hpc.gwdg.de/index.html),
+[Google](https://ai.google.dev/),
 [OpenWebUI](https://openwebui.com/))
 
 Add your API key in one of the following:
@@ -155,6 +153,7 @@ alternatively you can host your own model using [Ollama](https://ollama.com/). T
 ```
 OLLAMA_ACTIVE=true
 ```
+
 then navigate to `config/model_lists/ollama_models.php` and add your model attributes in the following structure:
 
 ```
@@ -182,10 +181,10 @@ After adding or editing a model in the config file, sync it to the database:
 php hawki models sync --force
 ```
 
->Before hosting models, make sure your system has the minimum required resources.
+> Before hosting models, make sure your system has the minimum required resources.
 
->**IMPORTANT**
-> 
+> **IMPORTANT**
+>
 >Currently, HAWKI is configured to use Gemini models’ native web search tool. If you want to disable the Google provider, make sure to add the following environment variables to disable the default web search model:
 >``` 
 ># Deactivte Google Models
@@ -221,7 +220,6 @@ In `/storage/app/` open the previously created `test_users.json` and add a profi
 ]
 ```
 
-
 ### DATABASE
 
 To store chat data, HAWKI requires a database connection. This documentation employs MySQL, but selection depends on your usage and specific requirements.
@@ -239,7 +237,6 @@ DB_USERNAME= root       // Database username
 DB_PASSWORD= root       // Database password
 ```
 
-
 Run database migrations by navigating to the project directory and executing:
 
 ```
@@ -253,6 +250,7 @@ php hawki migrate --fresh
 ```
 
 Alternatively, you can use artisan commands:
+
 ```
 php artisan migrate
 // or
@@ -313,19 +311,18 @@ php artisan storage:link
 
 You should be able to see the storage shortcut inside the public folder.
 
->Please note that after changing the structure of your files in the storage folder you may need to recreate the virtual link:
+> Please note that after changing the structure of your files in the storage folder you may need to recreate the virtual link:
 
 ```
 sudo rm -rf public/storage
 php artisan storage:link
 ```
 
-
 ## Broadcasting & Workers
 
 HAWKI uses [Laravel Reverb](https://reverb.laravel.com/) for real-time communication between client and server for broadcasting messages in th Groupchat Rooms.
 
->**If you don't wish to test broadcasting on you local machine skip this step.**
+> **If you don't wish to test broadcasting on you local machine skip this step.**
 
 
 In order to establish a connection to Reverb, a set of Reverb "application" credentials must be exchanged between the client and server. These credentials are configured on the server and are used to verify the request from the client. You may define these credentials using the following environment variables:
@@ -353,6 +350,7 @@ php artisan reverb:start
 ```
 
 In the terminal you should see:
+
 ```
 Starting server on 0.0.0.0:8080 (127.0.0.1). 
 ```
@@ -368,6 +366,7 @@ Test workers by running the following commands in separate terminals:
 ```
 php artisan queue:work
 ```
+
 ```
 php artisan queue:work --queue=message_broadcast
 ```
@@ -384,7 +383,7 @@ If you do not uncomment the FILE_CONVERTER variables in .env file, HAWKI turns o
 If you prefer to use HAWKI FIle Converter, and you are not using the docker deployment you can host the converter separately from the project.
 For more information refer to the [File Converter Repo](https://github.com/hawk-digital-environments/hawki-toolkit-file-converter) of this documentation.
 
-> **Further reading:** For a detailed explanation of how the conversion pipeline works and how to add a custom converter, see [File Conversion](../3-architecture/7.1-File%20Conversion.md).
+> **Further reading:** For a detailed explanation of how the conversion pipeline works and how to add a custom converter, see [File Conversion](../500-Backend/700-Storage-and-Files/100-File-Converter.md).
 
 ### Optional dependencies
 
@@ -439,6 +438,7 @@ php hawki run -dev
 ```
 
 The HAWKI CLI `run -dev` command starts:
+
 - PHP (artisan) development server
 - npm development server with hot-reloading
 - Reverb websocket server (if configured)
@@ -458,6 +458,7 @@ php hawki stop
 ```
 
 This command finds and terminates:
+
 - PHP Artisan processes
 - Node.js/npm processes
 - Queue workers