# Quickstart: GUID Context Resolver & Human-Readable Reference Presentation

## Goal

Implement a shared reference-resolution and rendering layer that makes supported references display as label-first, context-second, and technical-ID-last across findings, snapshots, operation runs, assignments, and related-context sections.

## Preconditions

1. Work on branch `132-guid-context-resolver`.
2. Ensure Sail is running:

```bash
vendor/bin/sail up -d
```

3. Review the current shared navigation and rendering entry points:
   - `app/Support/Navigation/RelatedNavigationResolver.php`
   - `app/Support/Navigation/CrossResourceNavigationMatrix.php`
   - `app/Support/Navigation/RelatedContextEntry.php`
   - `resources/views/filament/infolists/entries/related-context.blade.php`
   - `app/Support/OperationRunLinks.php`
   - `app/Services/Directory/EntraGroupLabelResolver.php`

## Implementation Sequence

1. Add the shared reference contracts under `app/Support/References/`.
2. Implement the resolver registry and fallback resolver.
3. Add core internal resolvers for policy, policy version, baseline profile, baseline snapshot, operation run, and backup set.
4. Add governance and provider-backed resolvers for role definitions, groups, principals, and assignment-like targets that are already surfaced.
5. Upgrade the shared renderers with compact and detailed variants while keeping technical IDs secondary.
6. Refactor target surfaces to consume resolved references instead of ad hoc label or GUID formatting.
7. Preserve originating tenant meaning when a tenant-context source links to a canonical workspace destination by carrying visible filters, context badges, or source-context metadata where relevant.
8. Normalize operator-facing copy across labels, helper text, link labels, empty states, and degraded-state messaging.
9. Add unit and feature tests, then run focused verification.

## Verification

Run focused tests for the new support layer and target surfaces:

```bash
vendor/bin/sail artisan test --compact --filter=Reference
vendor/bin/sail artisan test --compact --filter=Finding
vendor/bin/sail artisan test --compact --filter=BaselineSnapshot
vendor/bin/sail artisan test --compact --filter=OperationRun
```

Run formatting after code changes:

```bash
vendor/bin/sail bin pint --dirty --format agent
```

## Expected Outcome

- Supported references no longer render GUIDs as primary visible text on target surfaces.
- Unresolved, missing, partially resolved, and inaccessible states are visibly distinct.
- Canonical links remain authorization-aware and non-ambiguous.
- Canonical workspace destinations reached from tenant-context sources preserve visible tenant meaning where relevant.
- Operator-facing copy remains domain-consistent across labels, helper text, link text, empty states, and degraded-state messaging.
- Existing related-context consumers and future surfaces can reuse the same shared reference semantics.