# Quickstart: Entra Group Directory Cache (Groups v1)

## Goal
Populate a tenant-scoped cache of Entra ID groups (metadata only) via background sync runs, enabling safe UI rendering without live directory calls.

## Prerequisites
- Graph integration configured (client credentials / app-only)
- Database migrated (feature migrations applied)
- Queue worker running for jobs (required for sync)
- Scheduler/cron running for periodic sync (optional, if enabled)

### Local (Sail) quick commands

- Bring containers up: `./vendor/bin/sail up -d`
- Run migrations: `./vendor/bin/sail artisan migrate`
- Run the queue worker (separate terminal): `./vendor/bin/sail artisan queue:work`
- Run the scheduler loop (separate terminal, optional): `./vendor/bin/sail artisan schedule:work`

## Operator workflow (manual)
1. Switch into a tenant workspace.
2. Go to **Directory → Group Sync Runs**.
3. Click **Sync Groups** (creates/reuses a run and dispatches a background job).
4. Open the run and wait for status to complete.
5. Go to **Directory → Groups** and confirm list/search/detail are populated from the cache.

Notes
- Search is cached-only and typically requires at least 2 characters.
- If the cache is empty, the Groups list will be empty until a sync completes.

## Scheduled sync
- Ensure the scheduler is running (cron or `schedule:work`).
- Verify **Directory → Group Sync Runs** shows runs with empty Initiator (scheduled).
- The dispatcher command is `tenantpilot:directory-groups:dispatch` (configured to run every minute).

## Verification
- UI pages that show group IDs render using cached data only.
- Unresolved IDs show a clear fallback.
- Groups not seen for >90 days are eventually purged.

Suggested validation checks
- `./vendor/bin/sail artisan migrate:status | grep entra_group`
- `./vendor/bin/sail artisan schedule:list | grep directory-groups`