# Quickstart: Inventory Coverage Truth (177)

## Goal

Implement the Spec 177 truth correction without changing inventory-sync execution semantics or adding persistence.

The implementation is complete when:
- the inventory KPI header no longer shows a misleading unqualified coverage percentage,
- the coverage page answers tenant coverage truth first,
- inventory-sync run detail shows per-type results in human-readable form,
- and run continuity is RBAC-safe.

## Suggested Implementation Order

1. Add the derived runtime contract and resolver under `app/Support/Inventory`.
2. Add unit tests for basis-run selection, `Unknown` derivation, and follow-up classification.
3. Refactor `InventoryKpiHeader` to consume the new resolver and switch to count-based summary facts.
4. Refactor `InventoryCoverage` to consume the same resolver and move capability metadata into secondary treatment.
5. Add the inventory-sync run detail section and its custom Blade view.
6. Extend RBAC and feature tests for safe continuity and truthful rendering.
7. Run Pint and the focused Sail test pack.

## Verification Workflow

### Unit and focused feature tests

Run the smallest focused set first:

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH"
cd /Users/ahmeddarrazi/Documents/projects/TenantAtlas
vendor/bin/sail artisan test --compact tests/Unit/Support/Inventory/TenantCoverageTruthResolverTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/InventoryCoverageTableTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php
vendor/bin/sail artisan test --compact tests/Feature/Operations/TenantlessOperationRunViewerTest.php
vendor/bin/sail artisan test --compact tests/Feature/Inventory/RunInventorySyncJobTest.php
vendor/bin/sail bin pint --dirty --format agent
```

### Manual operator walkthrough

1. Open the inventory items list for a tenant with a recent inventory-sync run.
2. Confirm the header shows count-based coverage truth, not `Coverage %`.
3. Open the coverage page and verify the summary cites the basis run and the per-type table leads with coverage state and follow-up.
4. Open the cited inventory-sync run and verify the new per-type coverage section renders without opening raw JSON.
5. Verify a user without access to the run sees safe explanatory guidance instead of a dead-end link.

## Out-of-Scope Guardrails

Do not do any of the following in this slice:
- add a new coverage table or materialized summary artifact
- rewrite `InventorySyncService` or `RunInventorySyncJob`
- introduce restore-readiness or compare-readiness semantics into coverage
- add a first-class stale coverage state family
- add page-local badge mappings or local semantic color logic

## Completion Checklist

- Count-based KPI summary shipped
- Coverage page is tenant-truth-first
- Capability metadata is visibly secondary
- Run detail has human-readable per-type coverage
- Safe continuity works for both authorized and unauthorized viewers
- Focused tests and Pint pass