feat: add City10 platform with Laravel 13, AI agents, 3D viewer, and LGPD compliance

Initial commit of the complete City10 virtual city simulation platform.

Backend (Laravel 13):
- REST API with Sanctum tokens and session-based web authentication
- Role-based access control (admin/user) with middleware protection
- AI agent CRUD with OpenRouter.ai integration restricted to free models
- Store management with 3D coordinates and AI shopkeeper assignment
- Versioned legal documents (Terms, Privacy, Cookies) with LGPD audit trail
- Math CAPTCHA on public forms and multi-language support (pt_BR, en, es)

Frontend:
- Responsive Blade templates with Tailwind CSS v4
- Three.js 3D city viewer with SSE chat streaming to AI agents
- Admin panel for store and user administration

Infrastructure:
- MariaDB/MySQL database with comprehensive migrations
- Database seeders for demo content and test accounts
- PHPUnit test suite and Laravel Pint code styling
- Vite build configuration with hot reload

app/Http/Controllers/Api/UserController.php

@@ -0,0 +1,107 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Validation\Rule;
+
+/**
+ * User management endpoints (admin only).
+ *
+ * Lists, creates, updates and deactivates accounts of the platform while
+ * exposing never the password hash or other sensitive material.
+ */
+class UserController extends Controller
+{
+    /**
+     * Paginated listing of user accounts with optional search.
+     */
+    public function index(Request $request): JsonResponse
+    {
+        $query = User::query()->orderBy('name');
+
+        if ($search = $request->query('search')) {
+            $query->where(function ($q) use ($search): void {
+                $q->where('name', 'like', "%{$search}%")
+                    ->orWhere('email', 'like', "%{$search}%");
+            });
+        }
+
+        if ($role = $request->query('role')) {
+            $query->where('role', $role);
+        }
+
+        return response()->json($query->paginate((int) $request->query('per_page', 15)));
+    }
+
+    /**
+     * Persist a new user account (admin provisioning).
+     */
+    public function store(Request $request): JsonResponse
+    {
+        $data = $request->validate([
+            'name' => ['required', 'string', 'max:120'],
+            'email' => ['required', 'email', 'max:255', Rule::unique('users', 'email')],
+            'password' => ['required', 'string', 'min:8'],
+            'role' => ['required', Rule::in([User::ROLE_ADMIN, User::ROLE_USER])],
+            'locale' => ['nullable', Rule::in(['pt_BR', 'en', 'es'])],
+            'is_active' => ['nullable', 'boolean'],
+        ]);
+
+        $user = User::create($data);
+
+        return response()->json($user, 201);
+    }
+
+    /**
+     * Return a single user account.
+     */
+    public function show(User $user): JsonResponse
+    {
+        return response()->json($user->load('stores:id,name,owner_id,is_open'));
+    }
+
+    /**
+     * Update an existing user account.
+     */
+    public function update(Request $request, User $user): JsonResponse
+    {
+        $data = $request->validate([
+            'name' => ['sometimes', 'string', 'max:120'],
+            'email' => ['sometimes', 'email', 'max:255', Rule::unique('users', 'email')->ignore($user->id)],
+            'password' => ['sometimes', 'string', 'min:8'],
+            'role' => ['sometimes', Rule::in([User::ROLE_ADMIN, User::ROLE_USER])],
+            'locale' => ['sometimes', Rule::in(['pt_BR', 'en', 'es'])],
+            'is_active' => ['sometimes', 'boolean'],
+        ]);
+
+        $user->fill($data);
+
+        if (! empty($data['password'])) {
+            $user->password = $data['password'];
+        }
+
+        $user->save();
+
+        return response()->json($user);
+    }
+
+    /**
+     * Soft-disable an account (keeps audit data intact).
+     *
+     * Prevents administrators from locking themselves out of the platform.
+     */
+    public function destroy(Request $request, User $user): JsonResponse
+    {
+        if ($user->id === $request->user()?->id) {
+            return response()->json(['message' => __('users.cannot_deactivate_self')], 422);
+        }
+
+        $user->update(['is_active' => false]);
+
+        return response()->json(['message' => __('users.deactivated')]);
+    }
+}