specs/051-entra-group-directory-cache/quickstart.md

@@ -5,20 +5,38 @@ ## Goal
 
 ## Prerequisites
 - Graph integration configured (client credentials / app-only)
-- Queue worker running for jobs
-- Scheduler/cron running for periodic sync (if enabled)
+- 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. Start “Sync Groups”.
-3. Check the run status until it completes.
-4. Browse “Directory → Groups” and confirm search + detail work.
+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
-- Enable scheduled sync for tenants/environment.
-- Verify runs appear without manual initiation.
+- 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`

specs/051-entra-group-directory-cache/tasks.md

@@ -132,7 +132,7 @@ ## Phase 6: Polish & Cross-Cutting Concerns
 
 - [x] T033 [P] Run formatting on changed files with vendor/bin/pint --dirty
 - [x] T034 Run targeted Pest suite for this feature (e.g., php artisan test tests/Feature/DirectoryGroups and tests/Unit/DirectoryGroups)
-- [ ] T035 Validate operator workflow against specs/051-entra-group-directory-cache/quickstart.md
+- [x] T035 Validate operator workflow against specs/051-entra-group-directory-cache/quickstart.md
 
 ---