<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>

<p align="center">
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
</p>

## TenantPilot setup

- Local dev (Sail-first):
  - Start stack: `./vendor/bin/sail up -d`
  - Init DB: `./vendor/bin/sail artisan migrate --seed`
  - Tests: `./vendor/bin/sail artisan test`
  - Policy sync: `./vendor/bin/sail artisan intune:sync-policies`
- Filament admin: `/admin` (seed user `test@example.com`, set password via factory or `artisan tinker`).
- Microsoft Graph (Intune) env vars:
  - `GRAPH_TENANT_ID`
  - `GRAPH_CLIENT_ID`
  - `GRAPH_CLIENT_SECRET`
  - `GRAPH_SCOPE` (default `https://graph.microsoft.com/.default`)
  - Without these, the `NullGraphClient` runs in dry mode (no Graph calls).
  - **Required API Permissions**: See [docs/PERMISSIONS.md](docs/PERMISSIONS.md) for complete list
    - **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 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.

## Bulk operations (Feature 005)

- Bulk actions are available in Filament resource tables (Policies, Policy Versions, Backup Sets, Restore Runs).
- Destructive operations require type-to-confirm at higher thresholds (e.g. `DELETE`).
- Long-running bulk ops are queued; the bottom-right progress widget polls for active runs.

### 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`.
- **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.

### Configuration

- `TENANTPILOT_BULK_CHUNK_SIZE` (default `10`): job refresh/progress chunk size.
- `TENANTPILOT_BULK_POLL_INTERVAL_SECONDS` (default `3`): Livewire polling interval for the progress widget (clamped to 1–10s).

## Intune RBAC Onboarding Wizard

- Entry point: Tenant detail in Filament (`Setup Intune RBAC` in the ⋯ ActionGroup). Visible only for active tenants with `app_client_id`.
- Flow (synchronous, delegated):
  1) Configure Role (default Policy/Profile Manager), Scope (global or scope group), Group mode (create default `TenantPilot-Intune-RBAC` or pick existing security-enabled group). Review planned changes.
  2) Delegated admin login (short-lived token, **not** stored in DB/cache).
  3) Execute: resolve service principal, ensure/validate security group, ensure membership, ensure/create/patch Intune role assignment; persists IDs on tenant for idempotency; no queue.
  4) Post-verify: forces fresh token, runs canary reads (deviceConfigurations/deviceCompliancePolicies; CA canary only if feature enabled), updates health and warnings (scope-limited, CA disabled, manual assignment required).
- Safety/notes: least-privilege default, idempotent reruns, “already exists” treated as success. If service principal missing, run Admin consent first. Scope-limited setups may yield partial inventory/restore; warnings are surfaced in UI and health panel.

## Graph Contract Registry & Drift Guard

- Registry: `config/graph_contracts.php` defines per-type contracts (resource paths, allowed `$select`/`$expand`, @odata.type family, create/update methods, id field, hydration).
- Client behavior:
  - 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).
- If Graph returns capability errors, TenantPilot downgrades safely, records warnings/audit entries, and avoids breaking preview/restore flows.

## Policy Settings Display

- Policy detail pages render normalized settings instead of raw JSON:
  - OMA-URI/custom policies → path/value table
  - Settings Catalog → flattened key/value entries
  - Standard objects → labeled key/value view with metadata filtered
- Version detail pages show both pretty-printed JSON and normalized settings.
- Warnings surface malformed snapshots or @odata.type mismatches before restore.

## Policy JSON Viewer (Feature 002)

- **Location**: Policy View pages (`/admin/policies/{record}`)
- **Capability**: Pretty-printed JSON snapshot viewer with copy-to-clipboard
- **Settings Catalog Enhancement**: Dual-view tabs (Settings table + JSON viewer) for Settings Catalog policies
- **Features**:
  - Copy JSON to clipboard with success message
  - Large payload detection (>500 KB) with warning badge and auto-collapse
  - Dark mode support integrated with Filament design system
  - Browser native search (Cmd+F / Ctrl+F) for finding specific keys or values
  - Scrollable container with max height to prevent page overflow
- **Usage**: See `specs/002-filament-json/quickstart.md` for detailed examples and configuration
- **Performance**: Optimized for payloads up to 1 MB; auto-collapse improves initial render for large snapshots

## About Laravel

Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:

- [Simple, fast routing engine](https://laravel.com/docs/routing).
- [Powerful dependency injection container](https://laravel.com/docs/container).
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
- [Robust background job processing](https://laravel.com/docs/queues).
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).

Laravel is accessible, powerful, and provides tools required for large, robust applications.

## Learning Laravel

Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application.

If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.

## Laravel Sponsors

We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com).

### Premium Partners

- **[Vehikl](https://vehikl.com)**
- **[Tighten Co.](https://tighten.co)**
- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)**
- **[64 Robots](https://64robots.com)**
- **[Curotec](https://www.curotec.com/services/technologies/laravel)**
- **[DevSquad](https://devsquad.com/hire-laravel-developers)**
- **[Redberry](https://redberry.international/laravel-development)**
- **[Active Logic](https://activelogic.com)**

## Contributing

Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).

## Code of Conduct

In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).

## Security Vulnerabilities

If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.

## License

The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
