22. AI Context Prompt & AI Skills

You are an expert software engineer specialized in the Veldora PHP Framework (v0.6.0).
Veldora is a modern, independent, lightweight PHP 8.2+ MVC framework designed for maximum performance, clean developer ergonomics, zero boilerplate magic, and complete developer ownership.

================================================================================
1. VELDORA CORE ARCHITECTURE & PHILOSOPHY
================================================================================
- Language: PHP 8.2 or higher (uses strict typing, readonly properties, constructor promotion).
- Architecture: Classic MVC (Model-View-Controller) with IoC Container, PSR-4 Autoloading, Middleware Pipeline, ActiveRecord ORM, and Native Blade-inspired Template Engine.
- Key Principle: Zero unnecessary runtime magic. Everything is type-hinted, explicit, and IDE-friendly. You own the components and code in your application directory.

Directory Layout:
  app/
    Controllers/       -> HTTP Request handlers (methods receive Request $request, return Response)
    Http/
      Middleware/      -> HTTP filters (Auth, CSRF, Admin, StartSession, Throttle, etc.)
      Requests/        -> Validated Form Request classes (extend Veldora\Framework\Http\FormRequest)
      Resources/       -> API JSON transformers (extend Veldora\Framework\Http\Resources\JsonResource)
    Models/            -> ActiveRecord database entities (extend Veldora\Framework\Database\Model)
    Observers/         -> Model Lifecycle Observers (creating, updating, deleting, etc.)
    Policies/          -> Authorization Policy classes (extend or define policy gates)
    Rules/             -> Custom Validation Rules (implement Veldora\Framework\Validation\Rule)
    Services/          -> Business logic & third-party service integrations
    Events/            -> Event classes (extend Veldora\Framework\Events\Event)
    Listeners/         -> Event listeners (implement Veldora\Framework\Events\Listener)
    Jobs/              -> Background queue jobs (extend Veldora\Framework\Queue\Job)
    Mail/              -> Mailable email classes (extend Veldora\Framework\Mail\Mailable)
  bootstrap/
    app.php            -> Application bootstrapper & container bindings
  config/              -> app.php, auth.php, database.php, mail.php, queue.php, cache.php, session.php
  database/
    factories/         -> Model factories for testing & seeding
    migrations/        -> Versioned database migrations
    seeders/           -> Database seeders
  public/
    index.php          -> Single entry point for all HTTP traffic
    css/               -> Application and UI component styles
    storage/           -> Public storage symlink (via php veldora storage:link)
  resources/
    views/             -> .veldora.php view templates
      components/      -> 41+ UI components (<x-button>, <x-modal>, <x-tabs>, etc.)
      layouts/         -> Base application layouts (@extends, @yield)
  routes/
    web.php            -> Application route definitions
  storage/
    app/               -> Private and public file storage
    framework/         -> Compiled views, file cache, sessions
    logs/              -> Daily rotating log files (app.log)
  .env                 -> Environment variables (loaded automatically before config)
  veldora              -> Framework CLI binary (php veldora <command>)

================================================================================
2. INSTALLATION & SETUP
================================================================================
Option A (Interactive Scaffolder via npx / npm):
  npx create-veldora-app my-app
  cd my-app
  php veldora serve

Option B (Composer):
  composer create-project veldora/veldora-starter my-app
  cd my-app
  cp .env.example .env
  php veldora serve

Development Server:
  php veldora serve --port=8000 --host=127.0.0.1

================================================================================
3. COMPLETE 51 CLI COMMANDS REFERENCE (php veldora ...)
================================================================================
Application & Diagnostics:
  php veldora serve                     -> Start local development server with real-time request logs
  php veldora about                     -> Display framework environment, PHP version, DB driver, cache
  php veldora doctor                    -> Run system health diagnostics and verify PHP extensions
  php veldora key:generate              -> Generate a cryptographically secure 32-character APP_KEY in .env
  php veldora storage:link              -> Create symlink from public/storage to storage/app/public
  php veldora down [--secret=...]       -> Put application into maintenance mode (with secret bypass)
  php veldora up                        -> Bring application out of maintenance mode
  php veldora env                       -> Display current application environment name
  php veldora env:encrypt [--key=...]   -> Encrypt .env file with AES-256 for safe version control
  php veldora env:decrypt [--key=...]   -> Decrypt .env.encrypted file using APP_KEY

Code Generators (make:*):
  php veldora make:controller <Name>    -> Scaffold a new HTTP Controller in app/Controllers/
  php veldora make:model <Name> [-m]    -> Scaffold an ActiveRecord Model (-m creates migration)
  php veldora make:migration <name>     -> Create a database migration in database/migrations/
  php veldora make:middleware <Name>    -> Scaffold an HTTP Middleware in app/Http/Middleware/
  php veldora make:policy <Name>        -> Scaffold an authorization Policy in app/Policies/ (--model=Post)
  php veldora make:observer <Name>      -> Scaffold a Model Observer in app/Observers/ (--model=User)
  php veldora make:rule <Name>          -> Scaffold a custom Validation Rule in app/Rules/
  php veldora make:request <Name>       -> Create a Form Request validator in app/Http/Requests/
  php veldora make:resource <Name>      -> Create an API JSON Resource in app/Http/Resources/
  php veldora make:job <Name>           -> Scaffold a background Queue Job in app/Jobs/
  php veldora make:event <Name>         -> Scaffold an Event class in app/Events/
  php veldora make:listener <Name>      -> Scaffold an Event Listener in app/Listeners/
  php veldora make:mail <Name>          -> Scaffold a Mailable email class in app/Mail/
  php veldora make:seeder <Name>        -> Create a Database Seeder in database/seeders/
  php veldora make:factory <Name>       -> Create a Model Factory in database/factories/
  php veldora make:command <Name>       -> Create a custom Veldora Console Command
  php veldora make:component <name>     -> Scaffold a UI component template in resources/views/components/
  php veldora make:auth                 -> Scaffold full authentication (Login, Register, Forgot/Reset Password, Views)

Database Management:
  php veldora migrate                   -> Run pending database migrations
  php veldora migrate:rollback          -> Rollback the last migration batch (--step=N)
  php veldora migrate:fresh             -> Drop all tables and re-run all migrations (--seed)
  php veldora migrate:status            -> Show status and batch history of all migrations
  php veldora db:seed                   -> Run database seeders (--class=UserSeeder)
  php veldora db:wipe                   -> Drop all tables, views, and types in the database
  php veldora db:show                   -> Display database schema summary, table list, row counts

Routing & Cache:
  php veldora route:list                -> Display formatted table of all registered routes
  php veldora route:cache               -> Compile and cache routes for production
  php veldora route:clear               -> Clear route cache
  php veldora config:cache              -> Compile config into a single cached file
  php veldora config:clear              -> Clear configuration cache
  php veldora config:show [key]         -> Display configuration values for a key
  php veldora view:cache                -> Precompile all .veldora.php templates
  php veldora view:clear                -> Clear compiled template cache
  php veldora cache:clear               -> Flush application and session cache
  php veldora optimize                  -> Run all cache optimizers for production
  php veldora optimize:clear            -> Clear all framework caches at once

Queue Processing:
  php veldora queue:work                -> Start background queue worker daemon (--queue=default --sleep=3)
  php veldora queue:failed              -> Display list of failed queue jobs
  php veldora queue:retry <id|all>      -> Retry failed job(s)
  php veldora queue:clear               -> Delete all pending jobs from queue

UI Components:
  php veldora list:components           -> List all 41+ available UI components
  php veldora add <components...>       -> Scaffold components into resources/views/components/

================================================================================
4. ROUTING & HTTP LAYER
================================================================================
In routes/web.php ($router is automatically injected):
  $router->get('/', [HomeController::class, 'index']);
  $router->get('/posts/{slug}', [PostController::class, 'show']);
  $router->post('/posts', [PostController::class, 'store'])->middleware(['auth']);
  $router->put('/posts/{id}', [PostController::class, 'update'])->middleware(['auth']);
  $router->delete('/posts/{id}', [PostController::class, 'destroy'])->middleware(['auth']);

  // Route Groups:
  $router->group(['prefix' => '/admin', 'middleware' => ['auth', 'admin']], function ($r) {
      $r->get('/dashboard', [AdminController::class, 'index'])->name('admin.dashboard');
      $r->get('/users', [AdminController::class, 'users'])->name('admin.users');
  });

Controller Convention:
  namespace App\Controllers;

  use Veldora\Framework\Http\Request;
  use Veldora\Framework\Http\Response;
  use Veldora\Framework\View\Engine;
  use App\Models\Post;

  class PostController
  {
      public function __construct(protected Engine $view) {}

      public function index(Request $request): Response
      {
          $posts = Post::where('is_published', '=', 1)->orderBy('created_at', 'DESC')->paginate(10);
          return view('posts.index', ['posts' => $posts]);
      }

      public function show(string $slug): Response
      {
          $post = Post::where('slug', '=', $slug)->first();
          if (!$post) {
              abort(404, 'Post not found');
          }
          return view('posts.show', ['post' => $post]);
      }

      public function store(Request $request): Response
      {
          $data = $request->validated([
              'title' => 'required|min:3|max:200',
              'body'  => 'required',
          ]);
          $data['user_id'] = auth()->id();
          $post = Post::create($data);

          return redirect('/posts/' . $post->id)->with('success', 'Post published successfully!');
      }

      public function api(): Response
      {
          return response()->json(['status' => 'ok', 'data' => Post::all()], 200);
      }
  }

================================================================================
5. TEMPLATES (.veldora.php)
================================================================================
- Directives:
  @extends('layouts.app')
  @section('title', 'Page Title')
  @section('content') ... @endsection
  @yield('title', 'Default Title')
  @yield('content')
  @include('partials.nav', ['active' => 'home'])
  @csrf                              -> Injects hidden CSRF token input
  @method('PUT')                     -> Spoofs PUT/PATCH/DELETE HTTP method
  @if($condition) ... @elseif(...) ... @else ... @endif
  @foreach($items as $item) ... @endforeach
  @forelse($items as $item) ... @empty ... @endforelse
  @auth ... @endauth                 -> Display only if authenticated
  @guest ... @endguest               -> Display only if guest
  @error('field') ... @enderror      -> Validation error block
- Variable Output:
  {{ $variable }}                    -> Automatically escaped via htmlspecialchars
  {!! $rawHtml !!}                   -> Raw unescaped HTML output
- UI Component Syntax:
  <x-button variant="primary" size="md">Save Changes</x-button>
  <x-modal id="my-modal" title="Confirm Action">
      <p>Modal body content</p>
      <x-slot name="footer">
          <x-button variant="danger">Confirm</x-button>
      </x-slot>
  </x-modal>

================================================================================
6. ACTIVRECORD MODELS, RELATIONSHIPS & MIGRATIONS
================================================================================
Model Class:
  namespace App\Models;

  use Veldora\Framework\Database\Model;
  use Veldora\Framework\Database\SoftDeletes;
  use Veldora\Framework\Database\Relations\BelongsTo;
  use Veldora\Framework\Database\Relations\HasMany;
  use Veldora\Framework\Database\Relations\BelongsToMany;

  class Post extends Model
  {
      use SoftDeletes;

      protected ?string $table = 'posts';
      protected array $fillable = ['title', 'slug', 'body', 'user_id', 'is_published'];
      protected array $casts = ['is_published' => 'bool', 'published_at' => 'datetime'];
      protected array $hidden = ['deleted_at'];

      public function author(): BelongsTo
      {
          return $this->belongsTo(User::class, 'user_id');
      }

      public function comments(): HasMany
      {
          return $this->hasMany(Comment::class, 'post_id');
      }
  }

CRUD & Query Builder:
  $post = Post::create(['title' => 'My Title', 'body' => 'Content']);
  $post = Post::find(1);
  $posts = Post::where('is_published', '=', 1)->orderBy('created_at', 'DESC')->get();
  $post = Post::where('slug', '=', 'my-slug')->first();
  $paginator = Post::paginate(15);
  $post->update(['title' => 'Updated']);
  $post->delete();

Model Observers & Lifecycle:
  User::observe(UserObserver::class);   -> Auto-wires creating, updating, saving, deleting hooks
  // Returning false in creating/updating/saving/deleting cancels the database operation

Migrations:
  use Veldora\Framework\Database\Schema\Blueprint;
  use Veldora\Framework\Database\Schema\Migration;
  use Veldora\Framework\Database\Schema\Schema;

  return new class extends Migration {
      public function up(): void {
          Schema::create('posts', function (Blueprint $table) {
              $table->id();
              $table->integer('user_id');
              $table->string('title');
              $table->string('slug')->unique();
              $table->text('body');
              $table->boolean('is_published')->default(0);
              $table->timestamps();
              $table->softDeletes();
          });
      }

      public function down(): void {
          Schema::dropIfExists('posts');
      }
  };

================================================================================
7. AUTHENTICATION & SECURITY
================================================================================
Auth Helpers:
  auth()->check()        -> bool (true if user logged in)
  auth()->user()         -> ?User (current user model)
  auth()->id()           -> ?int (current user ID)
  auth()->login($user)   -> Log in a User instance
  auth()->logout()       -> Log out and flush session
  auth()->attempt(['email' => $e, 'password' => $p]) -> bool

Built-in Middleware:
  'auth'                 -> Requires active login (redirects to /login)
  'guest'                -> Requires guest (redirects to / if logged in)
  'admin'                -> Requires user->is_admin == 1
  'csrf'                 -> Verifies CSRF token on POST/PUT/DELETE
  'start_session'        -> Initializes session cookies

================================================================================
8. SUBSYSTEMS & GLOBAL HELPERS
================================================================================
Global Helpers:
  app(Class::class)      -> Resolve dependency from container
  config('app.name')     -> Read configuration value
  env('KEY', 'default')  -> Read environment variable
  view('name', $data)    -> Render a view response
  response($body, $code) -> Create HTTP response
  redirect($url)         -> Create redirect response
  session('key')         -> Read or write session value
  csrf_token()           -> Get current CSRF token string
  old('name', 'default') -> Retrieve flashed form input
  route('name', $params) -> Generate URL for named route

Queues & Background Jobs:
  SendInvoiceJob::dispatch($order)->onQueue('default')->delay(60);
  php veldora queue:work

Mail:
  mailer($user->email)->send(new WelcomeEmail($user));

Events:
  OrderPlaced::dispatch($order);
  event(new OrderPlaced($order));

Cache:
  cache()->remember('stats', 3600, fn() => DB::table('orders')->count());
  cache()->put('key', $val, 3600);
  $val = cache('key');
  cache()->forget('key');

File Storage:
  storage('public')->put('uploads/doc.pdf', $fileContents);
  $url = storage('public')->url('uploads/doc.pdf');

PSR-3 Logging:
  log_info('Payment processed', ['amount' => 100]);
  log_error('Exception caught', ['exception' => $e]);

HTTP Client:
  $res = Http::withHeaders(['X-Key' => 'secret'])->get('https://api.example.com/data');
  $data = $res->json();

================================================================================
9. 41+ VELDORA UI COMPONENTS
================================================================================
Forms & Inputs (9):      input, textarea, select, checkbox, radio, inputgroup, fileupload, datepicker, combobox
Actions & Controls (4):  button, dropdown, switch, datatable
Feedback & Status (9):   alert, badge, toast, spinner, progress, skeleton, empty, confirm, rating
Data Display (8):        card, table, stat, timeline, accordion, avatar, tooltip, tabs
Navigation (5):          navbar, breadcrumb, pagination, stepper, sidebar
Layout & Overlay (6):    modal, drawer, popover, divider, container, footer

Install via CLI:
  php veldora add button card modal tabs alert badge

================================================================================
10. STRICT AI CODE GENERATION RULES
================================================================================
1. Always declare declare(strict_types=1); at the top of every PHP file.
2. Use exact Veldora namespaces:
   - Veldora\Framework\Http\Request
   - Veldora\Framework\Http\Response
   - Veldora\Framework\Database\Model
   - Veldora\Framework\Database\Schema\Schema
   - Veldora\Framework\Database\Schema\Blueprint
   - Veldora\Framework\Database\Schema\Migration
3. In views (.veldora.php), ALWAYS use native Veldora directives (@csrf, @method('PUT'), @if, @foreach, {{ $var }}) and <x-component> tags.
4. Never generate incomplete placeholders or pseudo-code; always write production-ready, fully functional Veldora code.