.dockerignore

@@ -1,7 +1,9 @@
 node_modules/
+apps/platform/node_modules/
 dist/
 build/
 vendor/
+apps/platform/vendor/
 coverage/
 .git/
 .DS_Store
@@ -18,12 +20,19 @@ Dockerfile*
 *.tmp
 *.swp
 public/build/
+apps/platform/public/build/
 public/hot/
+apps/platform/public/hot/
 public/storage/
+apps/platform/public/storage/
 storage/framework/
+apps/platform/storage/framework/
 storage/logs/
+apps/platform/storage/logs/
 storage/debugbar/
+apps/platform/storage/debugbar/
 storage/*.key
+apps/platform/storage/*.key
 /references/
 .idea/
 .vscode/

.github/agents/copilot-instructions.md

@@ -2,6 +2,12 @@ # TenantAtlas Development Guidelines
 
 Auto-generated from all feature plans. Last updated: 2025-12-22
 
+## Relocation override
+- The authoritative Laravel application root is `apps/platform`.
+- Human-facing commands should use `cd apps/platform && ...`.
+- Repo-root tooling may delegate via `./scripts/platform-sail` when it cannot set a nested working directory.
+- If any generated technology note below conflicts with the current repo, trust `apps/platform/composer.json`, `apps/platform/package.json`, and the live Laravel application metadata over stale generated entries.
+
 ## Active Technologies
 - PHP 8.4.15 + Laravel 12, Filament v4, Livewire v3 (feat/005-bulk-operations)
 - PostgreSQL (app), SQLite in-memory (tests) (feat/005-bulk-operations)
@@ -141,6 +147,8 @@ ## Active Technologies
 - PostgreSQL with existing tenant-owned `backup_sets`, `backup_items`, `policy_versions`, and restore wizard input state; JSON-backed `metadata`, `snapshot`, `assignments`, and `scope_tags`; no schema change planned (176-backup-quality-truth)
 - PHP 8.4, Laravel 12, Blade, Filament v5, Livewire v4 + Filament v5, Livewire v4, Pest v4, Laravel Sail, existing `DashboardKpis`, `NeedsAttention`, `BackupSetResource`, `BackupScheduleResource`, `BackupQualityResolver`, `BackupQualitySummary`, `ScheduleTimeService`, shared badge infrastructure, and existing RBAC helpers (180-tenant-backup-health)
 - PostgreSQL with existing tenant-owned `backup_sets`, `backup_items`, and `backup_schedules` records plus existing JSON-backed backup metadata; no schema change planned (180-tenant-backup-health)
+- PHP 8.4.15, Laravel 12, Blade, Livewire v4, Filament v5.2.x, Tailwind CSS v4, Vite 7 + `laravel/framework`, `filament/filament`, `livewire/livewire`, `laravel/sail`, `laravel-vite-plugin`, `tailwindcss`, `vite`, `pestphp/pest`, `drizzle-kit`, PostgreSQL, Redis, Docker Compose (182-platform-relocation)
+- PostgreSQL, Redis, filesystem storage under the Laravel app `storage/` tree, plus existing Vite build artifacts in `public/build`; no new database persistence planned (182-platform-relocation)
 
 - PHP 8.4.15 (feat/005-bulk-operations)
 
@@ -160,8 +168,8 @@ ## Code Style
 PHP 8.4.15: Follow standard conventions
 
 ## Recent Changes
+- 182-platform-relocation: Added PHP 8.4.15, Laravel 12, Blade, Livewire v4, Filament v5.2.x, Tailwind CSS v4, Vite 7 + `laravel/framework`, `filament/filament`, `livewire/livewire`, `laravel/sail`, `laravel-vite-plugin`, `tailwindcss`, `vite`, `pestphp/pest`, `drizzle-kit`, PostgreSQL, Redis, Docker Compose
 - 180-tenant-backup-health: Added PHP 8.4, Laravel 12, Blade, Filament v5, Livewire v4 + Filament v5, Livewire v4, Pest v4, Laravel Sail, existing `DashboardKpis`, `NeedsAttention`, `BackupSetResource`, `BackupScheduleResource`, `BackupQualityResolver`, `BackupQualitySummary`, `ScheduleTimeService`, shared badge infrastructure, and existing RBAC helpers
 - 176-backup-quality-truth: Added PHP 8.4, Laravel 12, Blade, Filament v5, Livewire v4 + Filament v5, Livewire v4, Pest v4, Laravel Sail, existing `BackupSetResource`, `BackupItemsRelationManager`, `PolicyVersionResource`, `RestoreRunResource`, `CreateRestoreRun`, `AssignmentBackupService`, `VersionService`, `PolicySnapshotService`, `RestoreRiskChecker`, `BadgeRenderer`, `PolicySnapshotModeBadge`, `EnterpriseDetailBuilder`, and existing RBAC helpers
-- 181-restore-safety-integrity: Added PHP 8.4, Laravel 12, Blade, Filament v5, Livewire v4 + Filament v5, Livewire v4, Pest v4, Laravel Sail, existing `RestoreRunResource`, `RestoreService`, `RestoreRiskChecker`, `RestoreDiffGenerator`, `OperationRunResource`, `TenantlessOperationRunViewer`, shared badge infrastructure, and existing RBAC or write-gate helpers
 <!-- MANUAL ADDITIONS START -->
 <!-- MANUAL ADDITIONS END -->

.github/copilot-instructions.md

@@ -40,7 +40,7 @@ ## 3) Panel setup defaults
 - Assets policy:
   - Panel-only assets: register via panel config.
   - Shared/plugin assets: register via `FilamentAsset::register()`.
-  - Deployment must include `php artisan filament:assets`.
+  - Deployment must include `cd apps/platform && php artisan filament:assets`.
 
 Sources:
 - https://filamentphp.com/docs/5.x/panel-configuration
@@ -254,7 +254,7 @@ ## Testing
   - Source: https://filamentphp.com/docs/5.x/testing/testing-actions — “Testing actions”
 
 ## Deployment / Ops
-- [ ] `php artisan filament:assets` is included in the deployment process when using registered assets.
+- [ ] `cd apps/platform && php artisan filament:assets` is included in the deployment process when using registered assets.
   - Source: https://filamentphp.com/docs/5.x/advanced/assets — “The FilamentAsset facade”
 
 === foundation rules ===
@@ -292,7 +292,7 @@ ## Application Structure & Architecture
 - Do not change the application's dependencies without approval.
 
 ## Frontend Bundling
-- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `vendor/bin/sail npm run build`, `vendor/bin/sail npm run dev`, or `vendor/bin/sail composer run dev`. Ask them.
+- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `cd apps/platform && ./vendor/bin/sail npm run build`, `cd apps/platform && ./vendor/bin/sail npm run dev`, or `cd apps/platform && ./vendor/bin/sail composer run dev`. Ask them.
 
 ## Replies
 - Be concise in your explanations - focus on what's important rather than explaining obvious details.
@@ -372,28 +372,29 @@ ## Enums
 ## Laravel Sail
 
 - This project runs inside Laravel Sail's Docker containers. You MUST execute all commands through Sail.
-- Start services using `vendor/bin/sail up -d` and stop them with `vendor/bin/sail stop`.
+- The canonical application working directory is `apps/platform`. Repo-root launchers such as MCP or VS Code tasks may use `./scripts/platform-sail`, but that helper is compatibility-only.
-- Open the application in the browser by running `vendor/bin/sail open`.
+- Start services using `cd apps/platform && ./vendor/bin/sail up -d` and stop them with `cd apps/platform && ./vendor/bin/sail stop`.
-- Always prefix PHP, Artisan, Composer, and Node commands with `vendor/bin/sail`. Examples:
+- Open the application in the browser by running `cd apps/platform && ./vendor/bin/sail open`.
-    - Run Artisan Commands: `vendor/bin/sail artisan migrate`
+- Always prefix PHP, Artisan, Composer, and Node commands with `cd apps/platform && ./vendor/bin/sail`. Examples:
-    - Install Composer packages: `vendor/bin/sail composer install`
+    - Run Artisan Commands: `cd apps/platform && ./vendor/bin/sail artisan migrate`
-    - Execute Node commands: `vendor/bin/sail npm run dev`
+    - Install Composer packages: `cd apps/platform && ./vendor/bin/sail composer install`
-    - Execute PHP scripts: `vendor/bin/sail php [script]`
+    - Execute Node commands: `cd apps/platform && ./vendor/bin/sail npm run dev`
-- View all available Sail commands by running `vendor/bin/sail` without arguments.
+    - Execute PHP scripts: `cd apps/platform && ./vendor/bin/sail php [script]`
+- View all available Sail commands by running `cd apps/platform && ./vendor/bin/sail` without arguments.
 
 === tests rules ===
 
 ## Test Enforcement
 
 - Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
-- Run the minimum number of tests needed to ensure code quality and speed. Use `vendor/bin/sail artisan test --compact` with a specific filename or filter.
+- Run the minimum number of tests needed to ensure code quality and speed. Use `cd apps/platform && ./vendor/bin/sail artisan test --compact` with a specific filename or filter.
 
 === laravel/core rules ===
 
 ## Do Things the Laravel Way
 
-- Use `vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
+- Use `cd apps/platform && ./vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
-- If you're creating a generic PHP class, use `vendor/bin/sail artisan make:class`.
+- If you're creating a generic PHP class, use `cd apps/platform && ./vendor/bin/sail artisan make:class`.
 - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.
 
 ### Database
@@ -404,7 +405,7 @@ ### Database
 - Use Laravel's query builder for very complex database operations.
 
 ### Model Creation
-- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `vendor/bin/sail artisan make:model`.
+- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `cd apps/platform && ./vendor/bin/sail artisan make:model`.
 
 ### APIs & Eloquent Resources
 - For APIs, default to using Eloquent API Resources and API versioning unless existing API routes do not, then you should follow existing application convention.
@@ -428,10 +429,10 @@ ### Configuration
 ### Testing
 - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
 - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
-- When creating tests, make use of `vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
+- When creating tests, make use of `cd apps/platform && ./vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
 
 ### Vite Error
-- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `vendor/bin/sail npm run build` or ask the user to run `vendor/bin/sail npm run dev` or `vendor/bin/sail composer run dev`.
+- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `cd apps/platform && ./vendor/bin/sail npm run build` or ask the user to run `cd apps/platform && ./vendor/bin/sail npm run dev` or `cd apps/platform && ./vendor/bin/sail composer run dev`.
 
 === laravel/v12 rules ===
 
@@ -460,7 +461,7 @@ ### Models
 ## Livewire
 
 - Use the `search-docs` tool to find exact version-specific documentation for how to write Livewire and Livewire tests.
-- Use the `vendor/bin/sail artisan make:livewire [Posts\CreatePost]` Artisan command to create new components.
+- Use the `cd apps/platform && ./vendor/bin/sail artisan make:livewire [Posts\CreatePost]` Artisan command to create new components.
 - State should live on the server, with the UI reflecting it.
 - All Livewire requests hit the Laravel backend; they're like regular HTTP requests. Always validate form data and run authorization checks in Livewire actions.
 
@@ -504,8 +505,8 @@ ## Testing Livewire
 
 ## Laravel Pint Code Formatter
 
-- You must run `vendor/bin/sail bin pint --dirty` before finalizing changes to ensure your code matches the project's expected style.
+- You must run `cd apps/platform && ./vendor/bin/sail bin pint --dirty` before finalizing changes to ensure your code matches the project's expected style.
-- Do not run `vendor/bin/sail bin pint --test`, simply run `vendor/bin/sail bin pint` to fix any formatting issues.
+- Do not run `cd apps/platform && ./vendor/bin/sail bin pint --test`, simply run `cd apps/platform && ./vendor/bin/sail bin pint` to fix any formatting issues.
 
 === pest/core rules ===
 
@@ -514,7 +515,7 @@ ### Testing
 - If you need to verify a feature is working, write or update a Unit / Feature test.
 
 ### Pest Tests
-- All tests must be written using Pest. Use `vendor/bin/sail artisan make:test --pest {name}`.
+- All tests must be written using Pest. Use `cd apps/platform && ./vendor/bin/sail artisan make:test --pest {name}`.
 - You must not remove any tests or test files from the tests directory without approval. These are not temporary or helper files - these are core to the application.
 - Tests should test all of the happy paths, failure paths, and weird paths.
 - Tests live in the `tests/Feature` and `tests/Unit` directories.
@@ -527,9 +528,9 @@ ### Pest Tests
 
 ### Running Tests
 - Run the minimal number of tests using an appropriate filter before finalizing code edits.
-- To run all tests: `vendor/bin/sail artisan test --compact`.
+- To run all tests: `cd apps/platform && ./vendor/bin/sail artisan test --compact`.
-- To run all tests in a file: `vendor/bin/sail artisan test --compact tests/Feature/ExampleTest.php`.
+- To run all tests in a file: `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ExampleTest.php`.
-- To filter on a particular test name: `vendor/bin/sail artisan test --compact --filter=testName` (recommended after making a change to a related file).
+- To filter on a particular test name: `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=testName` (recommended after making a change to a related file).
 - When the tests relating to your changes are passing, ask the user if they would like to run the entire test suite to ensure everything is still passing.
 
 ### Pest Assertions

.gitignore

@@ -15,19 +15,30 @@
 /.zed
 /auth.json
 /node_modules
+/apps/platform/node_modules
 dist/
 build/
 coverage/
 /public/build
+/apps/platform/public/build
 /public/hot
+/apps/platform/public/hot
 /public/storage
+/apps/platform/public/storage
 /storage/*.key
+/apps/platform/storage/*.key
 /storage/pail
+/apps/platform/storage/pail
 /storage/framework
+/apps/platform/storage/framework
 /storage/logs
+/apps/platform/storage/logs
 /storage/debugbar
+/apps/platform/storage/debugbar
 /vendor
+/apps/platform/vendor
 /bootstrap/cache
+/apps/platform/bootstrap/cache
 Homestead.json
 Homestead.yaml
 Thumbs.db
@@ -35,3 +46,5 @@ Thumbs.db
 /tests/Browser/Screenshots
 *.tmp
 *.swp
+/apps/platform/.env
+/apps/platform/.env.*

.npmignore

@@ -1,8 +1,11 @@
 dist/
 build/
 public/build/
+apps/platform/public/build/
 node_modules/
+apps/platform/node_modules/
 vendor/
+apps/platform/vendor/
 *.log
 .env
 .env.*

.prettierignore

@@ -2,12 +2,19 @@ node_modules/
 dist/
 build/
 public/build/
+apps/platform/public/build/
 public/hot/
+apps/platform/public/hot/
 public/storage/
+apps/platform/public/storage/
 coverage/
 vendor/
+apps/platform/vendor/
+apps/platform/node_modules/
 storage/
+apps/platform/storage/
 bootstrap/cache/
+apps/platform/bootstrap/cache/
 package-lock.json
 yarn.lock
 pnpm-lock.yaml

Agents.md

@@ -318,12 +318,13 @@ ## Security
 ## Commands
 
 ### Sail (preferred locally)
-- `./vendor/bin/sail up -d`
+- `cd apps/platform && ./vendor/bin/sail up -d`
-- `./vendor/bin/sail down`
+- `cd apps/platform && ./vendor/bin/sail down`
-- `./vendor/bin/sail composer install`
+- `cd apps/platform && ./vendor/bin/sail composer install`
-- `./vendor/bin/sail artisan migrate`
+- `cd apps/platform && ./vendor/bin/sail artisan migrate`
-- `./vendor/bin/sail artisan test`
+- `cd apps/platform && ./vendor/bin/sail artisan test`
-- `./vendor/bin/sail artisan` (general)
+- `cd apps/platform && ./vendor/bin/sail artisan` (general)
+- Root helper for tooling only: `./scripts/platform-sail ...`
 
 ### Drizzle (local DB tooling, if configured)
 - Use only for local/dev workflows.
@@ -335,10 +336,10 @@ ### Drizzle (local DB tooling, if configured)
 (Agents should confirm the exact script names in `package.json` before suggesting them.)
 
 ### Non-Docker fallback (only if needed)
-- `composer install`
+- `cd apps/platform && composer install`
-- `php artisan serve`
+- `cd apps/platform && php artisan serve`
-- `php artisan migrate`
+- `cd apps/platform && php artisan migrate`
-- `php artisan test`
+- `cd apps/platform && php artisan test`
 
 ### Frontend/assets/tooling (if present)
 - `pnpm install`
@@ -352,11 +353,11 @@ ## Where to look first
 - `.specify/`
 - `AGENTS.md`
 - `README.md`
-- `app/`
+- `apps/platform/app/`
-- `database/`
+- `apps/platform/database/`
-- `routes/`
+- `apps/platform/routes/`
-- `resources/`
+- `apps/platform/resources/`
-- `config/`
+- `apps/platform/config/`
 
 ---
 
@@ -433,7 +434,7 @@ ## 3) Panel setup defaults
 - Assets policy:
   - Panel-only assets: register via panel config.
   - Shared/plugin assets: register via `FilamentAsset::register()`.
-  - Deployment must include `php artisan filament:assets`.
+  - Deployment must include `cd apps/platform && php artisan filament:assets`.
 
 Sources:
 - https://filamentphp.com/docs/5.x/panel-configuration
@@ -670,7 +671,7 @@ ## Testing
 
 ## Deployment / Ops
 
-- [ ] `php artisan filament:assets` is included in the deployment process when using registered assets.
+- [ ] `cd apps/platform && php artisan filament:assets` is included in the deployment process when using registered assets.
   - Source: https://filamentphp.com/docs/5.x/advanced/assets — “The FilamentAsset facade”
 
 === foundation rules ===
@@ -720,7 +721,7 @@ ## Application Structure & Architecture
 
 ## Frontend Bundling
 
-- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `vendor/bin/sail npm run build`, `vendor/bin/sail npm run dev`, or `vendor/bin/sail composer run dev`. Ask them.
+- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `cd apps/platform && ./vendor/bin/sail npm run build`, `cd apps/platform && ./vendor/bin/sail npm run dev`, or `cd apps/platform && ./vendor/bin/sail composer run dev`. Ask them.
 
 ## Documentation Files
 
@@ -812,28 +813,28 @@ ## PHPDoc Blocks
 # Laravel Sail
 
 - This project runs inside Laravel Sail's Docker containers. You MUST execute all commands through Sail.
-- Start services using `vendor/bin/sail up -d` and stop them with `vendor/bin/sail stop`.
+- Start services using `cd apps/platform && ./vendor/bin/sail up -d` and stop them with `cd apps/platform && ./vendor/bin/sail stop`.
-- Open the application in the browser by running `vendor/bin/sail open`.
+- Open the application in the browser by running `cd apps/platform && ./vendor/bin/sail open`.
-- Always prefix PHP, Artisan, Composer, and Node commands with `vendor/bin/sail`. Examples:
+- Always prefix PHP, Artisan, Composer, and Node commands with `cd apps/platform && ./vendor/bin/sail`. Examples:
-    - Run Artisan Commands: `vendor/bin/sail artisan migrate`
+    - Run Artisan Commands: `cd apps/platform && ./vendor/bin/sail artisan migrate`
-    - Install Composer packages: `vendor/bin/sail composer install`
+    - Install Composer packages: `cd apps/platform && ./vendor/bin/sail composer install`
-    - Execute Node commands: `vendor/bin/sail npm run dev`
+    - Execute Node commands: `cd apps/platform && ./vendor/bin/sail npm run dev`
-    - Execute PHP scripts: `vendor/bin/sail php [script]`
+    - Execute PHP scripts: `cd apps/platform && ./vendor/bin/sail php [script]`
-- View all available Sail commands by running `vendor/bin/sail` without arguments.
+- View all available Sail commands by running `cd apps/platform && ./vendor/bin/sail` without arguments.
 
 === tests rules ===
 
 # Test Enforcement
 
 - Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
-- Run the minimum number of tests needed to ensure code quality and speed. Use `vendor/bin/sail artisan test --compact` with a specific filename or filter.
+- Run the minimum number of tests needed to ensure code quality and speed. Use `cd apps/platform && ./vendor/bin/sail artisan test --compact` with a specific filename or filter.
 
 === laravel/core rules ===
 
 # Do Things the Laravel Way
 
-- Use `vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
+- Use `cd apps/platform && ./vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
-- If you're creating a generic PHP class, use `vendor/bin/sail artisan make:class`.
+- If you're creating a generic PHP class, use `cd apps/platform && ./vendor/bin/sail artisan make:class`.
 - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.
 
 ## Database
@@ -846,7 +847,7 @@ ## Database
 
 ### Model Creation
 
-- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `vendor/bin/sail artisan make:model`.
+- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `cd apps/platform && ./vendor/bin/sail artisan make:model`.
 
 ### APIs & Eloquent Resources
 
@@ -877,11 +878,11 @@ ## Testing
 
 - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
 - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
-- When creating tests, make use of `vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
+- When creating tests, make use of `cd apps/platform && ./vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
 
 ## Vite Error
 
-- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `vendor/bin/sail npm run build` or ask the user to run `vendor/bin/sail npm run dev` or `vendor/bin/sail composer run dev`.
+- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `cd apps/platform && ./vendor/bin/sail npm run build` or ask the user to run `cd apps/platform && ./vendor/bin/sail npm run dev` or `cd apps/platform && ./vendor/bin/sail composer run dev`.
 
 === laravel/v12 rules ===
 
@@ -912,15 +913,15 @@ ### Models
 
 # Laravel Pint Code Formatter
 
-- You must run `vendor/bin/sail bin pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style.
+- You must run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style.
-- Do not run `vendor/bin/sail bin pint --test --format agent`, simply run `vendor/bin/sail bin pint --format agent` to fix any formatting issues.
+- Do not run `cd apps/platform && ./vendor/bin/sail bin pint --test --format agent`, simply run `cd apps/platform && ./vendor/bin/sail bin pint --format agent` to fix any formatting issues.
 
 === pest/core rules ===
 
 ## Pest
 
-- This project uses Pest for testing. Create tests: `vendor/bin/sail artisan make:test --pest {name}`.
+- This project uses Pest for testing. Create tests: `cd apps/platform && ./vendor/bin/sail artisan make:test --pest {name}`.
-- Run tests: `vendor/bin/sail artisan test --compact` or filter: `vendor/bin/sail artisan test --compact --filter=testName`.
+- Run tests: `cd apps/platform && ./vendor/bin/sail artisan test --compact` or filter: `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=testName`.
 - Do NOT delete tests without approval.
 - CRITICAL: ALWAYS use `search-docs` tool for version-specific Pest documentation and updated code examples.
 - IMPORTANT: Activate `pest-testing` every time you're working with a Pest or testing-related task.

GEMINI.md

@@ -156,12 +156,13 @@ ## Security
 ## Commands
 
 ### Sail (preferred locally)
-- `./vendor/bin/sail up -d`
+- `cd apps/platform && ./vendor/bin/sail up -d`
-- `./vendor/bin/sail down`
+- `cd apps/platform && ./vendor/bin/sail down`
-- `./vendor/bin/sail composer install`
+- `cd apps/platform && ./vendor/bin/sail composer install`
-- `./vendor/bin/sail artisan migrate`
+- `cd apps/platform && ./vendor/bin/sail artisan migrate`
-- `./vendor/bin/sail artisan test`
+- `cd apps/platform && ./vendor/bin/sail artisan test`
-- `./vendor/bin/sail artisan` (general)
+- `cd apps/platform && ./vendor/bin/sail artisan` (general)
+- Root helper for tooling only: `./scripts/platform-sail ...`
 
 ### Drizzle (local DB tooling, if configured)
 - Use only for local/dev workflows.
@@ -173,10 +174,10 @@ ### Drizzle (local DB tooling, if configured)
 (Agents should confirm the exact script names in `package.json` before suggesting them.)
 
 ### Non-Docker fallback (only if needed)
-- `composer install`
+- `cd apps/platform && composer install`
-- `php artisan serve`
+- `cd apps/platform && php artisan serve`
-- `php artisan migrate`
+- `cd apps/platform && php artisan migrate`
-- `php artisan test`
+- `cd apps/platform && php artisan test`
 
 ### Frontend/assets/tooling (if present)
 - `pnpm install`
@@ -190,11 +191,11 @@ ## Where to look first
 - `.specify/`
 - `AGENTS.md`
 - `README.md`
-- `app/`
+- `apps/platform/app/`
-- `database/`
+- `apps/platform/database/`
-- `routes/`
+- `apps/platform/routes/`
-- `resources/`
+- `apps/platform/resources/`
-- `config/`
+- `apps/platform/config/`
 
 ---
 
@@ -271,7 +272,7 @@ ## 3) Panel setup defaults
 - Assets policy:
   - Panel-only assets: register via panel config.
   - Shared/plugin assets: register via `FilamentAsset::register()`.
-  - Deployment must include `php artisan filament:assets`.
+  - Deployment must include `cd apps/platform && php artisan filament:assets`.
 
 Sources:
 - https://filamentphp.com/docs/5.x/panel-configuration
@@ -508,7 +509,7 @@ ## Testing
 
 ## Deployment / Ops
 
-- [ ] `php artisan filament:assets` is included in the deployment process when using registered assets.
+- [ ] `cd apps/platform && php artisan filament:assets` is included in the deployment process when using registered assets.
   - Source: https://filamentphp.com/docs/5.x/advanced/assets — “The FilamentAsset facade”
 
 === foundation rules ===
@@ -558,7 +559,7 @@ ## Application Structure & Architecture
 
 ## Frontend Bundling
 
-- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `vendor/bin/sail npm run build`, `vendor/bin/sail npm run dev`, or `vendor/bin/sail composer run dev`. Ask them.
+- If the user doesn't see a frontend change reflected in the UI, it could mean they need to run `cd apps/platform && ./vendor/bin/sail npm run build`, `cd apps/platform && ./vendor/bin/sail npm run dev`, or `cd apps/platform && ./vendor/bin/sail composer run dev`. Ask them.
 
 ## Documentation Files
 
@@ -650,28 +651,28 @@ ## PHPDoc Blocks
 # Laravel Sail
 
 - This project runs inside Laravel Sail's Docker containers. You MUST execute all commands through Sail.
-- Start services using `vendor/bin/sail up -d` and stop them with `vendor/bin/sail stop`.
+- Start services using `cd apps/platform && ./vendor/bin/sail up -d` and stop them with `cd apps/platform && ./vendor/bin/sail stop`.
-- Open the application in the browser by running `vendor/bin/sail open`.
+- Open the application in the browser by running `cd apps/platform && ./vendor/bin/sail open`.
-- Always prefix PHP, Artisan, Composer, and Node commands with `vendor/bin/sail`. Examples:
+- Always prefix PHP, Artisan, Composer, and Node commands with `cd apps/platform && ./vendor/bin/sail`. Examples:
-    - Run Artisan Commands: `vendor/bin/sail artisan migrate`
+    - Run Artisan Commands: `cd apps/platform && ./vendor/bin/sail artisan migrate`
-    - Install Composer packages: `vendor/bin/sail composer install`
+    - Install Composer packages: `cd apps/platform && ./vendor/bin/sail composer install`
-    - Execute Node commands: `vendor/bin/sail npm run dev`
+    - Execute Node commands: `cd apps/platform && ./vendor/bin/sail npm run dev`
-    - Execute PHP scripts: `vendor/bin/sail php [script]`
+    - Execute PHP scripts: `cd apps/platform && ./vendor/bin/sail php [script]`
-- View all available Sail commands by running `vendor/bin/sail` without arguments.
+- View all available Sail commands by running `cd apps/platform && ./vendor/bin/sail` without arguments.
 
 === tests rules ===
 
 # Test Enforcement
 
 - Every change must be programmatically tested. Write a new test or update an existing test, then run the affected tests to make sure they pass.
-- Run the minimum number of tests needed to ensure code quality and speed. Use `vendor/bin/sail artisan test --compact` with a specific filename or filter.
+- Run the minimum number of tests needed to ensure code quality and speed. Use `cd apps/platform && ./vendor/bin/sail artisan test --compact` with a specific filename or filter.
 
 === laravel/core rules ===
 
 # Do Things the Laravel Way
 
-- Use `vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
+- Use `cd apps/platform && ./vendor/bin/sail artisan make:` commands to create new files (i.e. migrations, controllers, models, etc.). You can list available Artisan commands using the `list-artisan-commands` tool.
-- If you're creating a generic PHP class, use `vendor/bin/sail artisan make:class`.
+- If you're creating a generic PHP class, use `cd apps/platform && ./vendor/bin/sail artisan make:class`.
 - Pass `--no-interaction` to all Artisan commands to ensure they work without user input. You should also pass the correct `--options` to ensure correct behavior.
 
 ## Database
@@ -684,7 +685,7 @@ ## Database
 
 ### Model Creation
 
-- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `vendor/bin/sail artisan make:model`.
+- When creating new models, create useful factories and seeders for them too. Ask the user if they need any other things, using `list-artisan-commands` to check the available options to `cd apps/platform && ./vendor/bin/sail artisan make:model`.
 
 ### APIs & Eloquent Resources
 
@@ -715,11 +716,11 @@ ## Testing
 
 - When creating models for tests, use the factories for the models. Check if the factory has custom states that can be used before manually setting up the model.
 - Faker: Use methods such as `$this->faker->word()` or `fake()->randomDigit()`. Follow existing conventions whether to use `$this->faker` or `fake()`.
-- When creating tests, make use of `vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
+- When creating tests, make use of `cd apps/platform && ./vendor/bin/sail artisan make:test [options] {name}` to create a feature test, and pass `--unit` to create a unit test. Most tests should be feature tests.
 
 ## Vite Error
 
-- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `vendor/bin/sail npm run build` or ask the user to run `vendor/bin/sail npm run dev` or `vendor/bin/sail composer run dev`.
+- If you receive an "Illuminate\Foundation\ViteException: Unable to locate file in Vite manifest" error, you can run `cd apps/platform && ./vendor/bin/sail npm run build` or ask the user to run `cd apps/platform && ./vendor/bin/sail npm run dev` or `cd apps/platform && ./vendor/bin/sail composer run dev`.
 
 === laravel/v12 rules ===
 
@@ -750,15 +751,15 @@ ### Models
 
 # Laravel Pint Code Formatter
 
-- You must run `vendor/bin/sail bin pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style.
+- You must run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent` before finalizing changes to ensure your code matches the project's expected style.
-- Do not run `vendor/bin/sail bin pint --test --format agent`, simply run `vendor/bin/sail bin pint --format agent` to fix any formatting issues.
+- Do not run `cd apps/platform && ./vendor/bin/sail bin pint --test --format agent`, simply run `cd apps/platform && ./vendor/bin/sail bin pint --format agent` to fix any formatting issues.
 
 === pest/core rules ===
 
 ## Pest
 
-- This project uses Pest for testing. Create tests: `vendor/bin/sail artisan make:test --pest {name}`.
+- This project uses Pest for testing. Create tests: `cd apps/platform && ./vendor/bin/sail artisan make:test --pest {name}`.
-- Run tests: `vendor/bin/sail artisan test --compact` or filter: `vendor/bin/sail artisan test --compact --filter=testName`.
+- Run tests: `cd apps/platform && ./vendor/bin/sail artisan test --compact` or filter: `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=testName`.
 - Do NOT delete tests without approval.
 - CRITICAL: ALWAYS use `search-docs` tool for version-specific Pest documentation and updated code examples.
 - IMPORTANT: Activate `pest-testing` every time you're working with a Pest or testing-related task.

README.md

@@ -9,11 +9,18 @@
 
 ## TenantPilot setup
 
-- Local dev (Sail-first):
+- Platform app root: `apps/platform`
-  - Start stack: `./vendor/bin/sail up -d`
+- Repo-root ownership: specs, docs, scripts, editor config, agent config, orchestration, and `docker-compose.yml`
-  - Init DB: `./vendor/bin/sail artisan migrate --seed`
+- App-root ownership: Laravel runtime, tests, Vite assets, public entrypoints, `composer.json`, `package.json`, `drizzle.config.ts`, and app-local `.env*`
-  - Tests: `./vendor/bin/sail artisan test`
+- Local dev (Sail-first, canonical workflow):
-  - Policy sync: `./vendor/bin/sail artisan intune:sync-policies`
+  - Install: `cd apps/platform && composer install`
+  - Env bootstrap: `cd apps/platform && cp .env.example .env`
+  - Start stack: `cd apps/platform && ./vendor/bin/sail up -d`
+  - Generate app key: `cd apps/platform && ./vendor/bin/sail artisan key:generate`
+  - Init DB: `cd apps/platform && ./vendor/bin/sail artisan migrate --seed`
+  - Tests: `cd apps/platform && ./vendor/bin/sail artisan test --compact`
+  - Policy sync: `cd apps/platform && ./vendor/bin/sail artisan intune:sync-policies`
+- Compatibility helper for tooling that cannot set a nested working directory: `./scripts/platform-sail ...`
 - Filament admin: `/admin` (seed user `test@example.com`, set password via factory or `artisan tinker`).
 - Microsoft Graph (Intune) env vars:
   - `GRAPH_TENANT_ID`
@@ -25,10 +32,17 @@ ## TenantPilot setup
     - **Missing permissions?** Scope tags will show as "Unknown (ID: X)" - add `DeviceManagementRBAC.Read.All`
 - Deployment (Dokploy, staging → production):
   - Containerized deploy; ensure Postgres + Redis are provisioned (see `docker-compose.yml` for local baseline).
+  - Run application commands from `apps/platform`, including `php artisan filament:assets`.
   - Run migrations on staging first, validate backup/restore flows, then promote to production.
   - Ensure queue workers are running for jobs (e.g., policy sync) after deploy.
   - Keep secrets/env in Dokploy, never in code.
 
+## Platform relocation rollout notes
+
+- Open branches that still touch legacy root app paths should merge `dev` first, then remap file moves from `app/`, `bootstrap/`, `config/`, `database/`, `lang/`, `public/`, `resources/`, `routes/`, `storage/`, and `tests/` into `apps/platform/...`.
+- Keep using merge-based catch-up on shared feature branches; do not rebase long-lived shared branches just to absorb the relocation.
+- VS Code tasks and MCP launchers now delegate through `./scripts/platform-sail` from the repo root. Human-facing docs remain `apps/platform`-first.
+
 ## Bulk operations (Feature 005)
 
 - Bulk actions are available in Filament resource tables (Policies, Policy Versions, Backup Sets, Restore Runs).
@@ -39,8 +53,23 @@ ### Troubleshooting
 
 - **Progress stuck on “Queued…”** usually means the queue worker is not running (or not processing the queue you expect).
   - Prefer using the Sail/Docker worker (see `docker-compose.yml`) rather than starting an additional local `php artisan queue:work`.
-  - Check worker status/logs: `./vendor/bin/sail ps` and `./vendor/bin/sail logs -f queue`.
+  - Check worker status/logs: `cd apps/platform && ./vendor/bin/sail ps` and `cd apps/platform && ./vendor/bin/sail logs -f queue`.
 - **Exit code 137** for `queue:work` typically means the process was killed (often OOM). Increase Docker memory/limits or run the worker inside the container.
+- **Moved app but old commands still fail** usually means the command is still being run from repo root. Switch to `cd apps/platform && ...` or use `./scripts/platform-sail ...` only for tooling that cannot set `cwd`.
+
+## Rollback checklist
+
+1. Revert the relocation commit or merge on your feature branch instead of hard-resetting shared history.
+2. Preserve any local app env overrides before switching commits: `cp apps/platform/.env /tmp/tenantatlas.platform.env.backup` if needed.
+3. Stop local containers and clean generated artifacts: `cd apps/platform && ./vendor/bin/sail down -v`, then remove `apps/platform/vendor`, `apps/platform/node_modules`, `apps/platform/public/build`, and `apps/platform/public/hot` if they need a clean rebuild.
+4. After rollback, restore the matching env file for the restored topology and rerun the documented setup flow for that commit.
+5. Notify owners of open feature branches that the topology changed so they can remap outstanding work before the next merge from `dev`.
+
+## Deployment unknowns
+
+- Dokploy build context for a repo-root compose file plus an app-root Laravel runtime still needs staging confirmation.
+- Production web, queue, and scheduler working directories must be verified explicitly after the move; do not assume repo root and app root behave interchangeably.
+- Any Dokploy volume mounts or storage persistence paths that previously targeted repo-root `storage/` must be reviewed against `apps/platform/storage/`.
 
 ### Configuration
 
@@ -64,7 +93,7 @@ ## Graph Contract Registry & Drift Guard
   - Sanitizes `$select`/`$expand` to allowed fields; logs warnings on trim.
   - Derived @odata.type values within the family are accepted for preview/restore routing.
   - Capability fallback: on 400s related to select/expand, retries without those clauses and surfaces warnings.
-- Drift check: `php artisan graph:contract:check [--tenant=]` runs lightweight probes against contract endpoints to detect capability/shape issues; useful in staging/CI (prod optional).
+- Drift check: `cd apps/platform && php artisan graph:contract:check [--tenant=]` runs lightweight probes against contract endpoints to detect capability/shape issues; useful in staging/CI (prod optional).
 - If Graph returns capability errors, TenantPilot downgrades safely, records warnings/audit entries, and avoids breaking preview/restore flows.
 
 ## Policy Settings Display

apps/platform/.env.example

@@ -3,6 +3,8 @@ APP_ENV=local
 APP_KEY=
 APP_DEBUG=true
 APP_URL=http://localhost
+SAIL_FILES=../../docker-compose.yml
+TENANTATLAS_REPO_ROOT=../..
 
 APP_LOCALE=en
 APP_FALLBACK_LOCALE=en
@@ -21,11 +23,12 @@ LOG_DEPRECATIONS_CHANNEL=null
 LOG_LEVEL=debug
 
 DB_CONNECTION=pgsql
-DB_HOST=127.0.0.1
+DB_HOST=pgsql
 DB_PORT=5432
+FORWARD_DB_PORT=55432
 DB_DATABASE=tenantatlas
 DB_USERNAME=root
-DB_PASSWORD=
+DB_PASSWORD=postgres
 
 SESSION_DRIVER=database
 SESSION_LIFETIME=120
@@ -43,7 +46,7 @@ CACHE_STORE=database
 MEMCACHED_HOST=127.0.0.1
 
 REDIS_CLIENT=phpredis
-REDIS_HOST=127.0.0.1
+REDIS_HOST=redis
 REDIS_PASSWORD=null
 REDIS_PORT=6379