TenantAtlas/specs/374-diagnostic-entry-point-support-diagnostics-consolidation/spec.md

Feature Specification: Spec 374 - Diagnostic Entry Point and Support Diagnostics Consolidation v1

Feature Branch: 374-diagnostic-entry-point-support-diagnostics-consolidation Created: 2026-06-12 Status: Draft Input: User-provided Spec 374 draft and repo-verified follow-up from completed Spec 373.

Candidate Selection Summary

• Selected candidate: Diagnostic Entry Point and Support Diagnostics Consolidation v1.
• Source: User-provided pasted note for Spec 374, using Spec 373 implementation results as immediate source truth.
• Why selected: Spec 373 productized Environment Diagnostics and the support diagnostics modal, but the remaining product ambiguity is entrypoint ownership: the visible operator path is Environment Dashboard -> More actions -> Open support diagnostics, while the direct /diagnostics page is a narrow repair-diagnostics utility. That ambiguity can make an empty repair page look like a broken diagnostic hub.
• Roadmap relationship: Supports the Product Scalability and Self-Service Foundation lane by making supportability and diagnostics calmer, discoverable, and honest without creating a broad diagnostic platform.
• Smallest viable slice: Define and productize the diagnostic entrypoint contract: Support Diagnostics is the official quick diagnostics entry; Environment Diagnostics is a secondary repair/deeplink surface; provider/permission/system/evidence/customer diagnostic questions remain owned by their existing or future surfaces.
• Deferred close alternatives:
  • UI Bloat Regression Guard: useful later, but too broad for the immediate entrypoint ambiguity.
  • Provider/Permission Diagnostics: completed or separately owned by Provider Connections, Required Permissions, and Spec 353 style guidance.
  • Evidence/System fixture reachability: fixture and auth coverage follow-up, not diagnostic IA.
  • Full Diagnostic Hub: explicitly out of scope because current repo truth has only two real diagnostic entry families.
• Completed-spec guardrail result:
  • Spec 373 has completed task markers, validation artifacts, browser evidence, and implementation close-out language in artifacts. Treat as completed context only.
  • Specs 370, 371, and 372 are consumed as completed context and are not rewritten.
  • No existing specs/374-diagnostic-entry-point-support-diagnostics-consolidation/ package existed before this preparation run.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Operators do not have one clearly documented official starting point for environment diagnostics. The support diagnostics modal is visible and useful, while the direct repair diagnostics page is narrow, hidden from navigation, and can look empty or generic if reached directly.
• Today's failure: An operator or implementer can mistake /diagnostics for a generic health hub, add provider/permission/system checks into the wrong route, or expose a prominent repair diagnostics action even when no supported repair case exists.
• User-visible improvement: The Environment Dashboard presents Support Diagnostics as the primary quick diagnostics path, any repair diagnostics entry is secondary and conditional, and the repair page clearly explains no-action or repair-only states.
• Smallest enterprise-capable version: Productize labels, descriptions, conditional entrypoint rules, no-action state, and documentation artifacts over existing routes and helpers. Do not add provider checks, new diagnostics backend logic, migrations, or new navigation.
• Explicit non-goals: No diagnostic hub, no Provider Connections redesign, no Required Permissions redesign, no System panel auth fix, no Evidence Snapshot reachability fix, no new Graph checks, no new repair logic, no OperationRun lifecycle work, no customer/auditor surface changes, and no UI bloat guard.
• Permanent complexity imported: One narrow entrypoint contract, focused feature/browser tests, and spec-local artifacts. No new persisted truth, enum/status family, provider framework, navigation branch, or generic diagnostic taxonomy.
• Why now: Spec 373 completed the diagnostic hierarchy inside the existing surfaces. The next smallest productization step is to clarify when operators should enter each surface so future work does not turn repair diagnostics into a catch-all hub.
• Why not local: Copy tweaks alone would not protect discoverability, route purpose, dashboard action hierarchy, ManagedEnvironmentLinks::diagnosticsUrl() usage, and deferred provider/permission/system boundaries together.
• Approval class: Workflow Compression.
• Red flags triggered: Multiple diagnostic surfaces and a consolidation theme. Defense: the scope is intentionally limited to existing entrypoints and documentation; it rejects a hub, framework, and new backend checks.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 1 | Gesamt: 11/12
• Decision: approve.

Spec Scope Fields (mandatory)

• Scope: workspace + managed-environment diagnostic entrypoints.
• Primary Routes / Surfaces:
  • /admin/workspaces/{workspace}/environments/{environment}
  • /admin/workspaces/{workspace}/environments/{environment}/diagnostics
  • Existing openSupportDiagnostics modal/action on Environment Dashboard and OperationRun detail contexts where already repo-backed
• Data Ownership: No ownership change. ManagedEnvironment remains the environment context; support diagnostics remains derived from existing stored workspace/environment/provider/operation/evidence/review/audit truth.
• RBAC:
  • Existing workspace membership and environment entitlement remain authoritative.
  • Existing support diagnostics capability gating remains authoritative.
  • Existing repair actions remain capability-gated, server-authorized, confirmation-gated, and audit-owned by current services.
  • Non-members remain deny-as-not-found; entitled members missing capability receive existing 403/disabled behavior.

For canonical or mixed context surfaces:

• Default filter behavior when tenant-context is active: N/A. This spec uses workspace/environment routes and does not introduce query-string context.
• Explicit entitlement checks preventing cross-tenant leakage: Existing route model binding, workspace middleware, environment context middleware, policies, and action authorization remain the only allowed entitlement paths.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• Existing modal/action presentation changed
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

No new navigation is planned. Dangerous-action behavior is still reviewed because the repair diagnostics page already contains destructive-like repair actions; the spec must preserve confirmation, authorization, and audit ownership without adding or changing repair behavior.

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact")

Route/page/surface	Page archetype	Design depth	Repo-truth level	Existing pattern reused	Screenshot/page audit need	Customer/dangerous review
Environment Dashboard diagnostic action area	Operator Surface / Environment Dashboard	Strategic Surface	repo-verified, browser-proven by Specs 371/373	Environment Dashboard More action pattern and support diagnostics action	after screenshot required if action label/placement changes	operator/support only; no new dangerous action
Support Diagnostics modal	Support / Diagnostics modal	Domain Pattern Surface	repo-verified, browser-proven by Spec 373	SupportDiagnosticBundleBuilder, redaction, contextual help, modal sections	after screenshot required if modal explanation changes	support-only; rendered as redacted support view while retaining internal default_redacted mode
Environment Diagnostics page	Tertiary Evidence / Diagnostics / Repair utility	Domain Pattern Surface	repo-verified, browser-proven by Spec 373	EnvironmentDiagnostics, Filament Page, existing repair actions	after screenshot required for no-action state and any repair state fixture available	existing repair actions must retain confirmation, capability gating, server authorization, and audit/service ownership
Provider/Permission diagnostics destinations	Provider / Integration, Configuration Surface	Deferred / existing completed context	repo-verified, completed Spec 353 context	Provider Connections and Required Permissions surfaces	no screenshot unless linked regression occurs	keep out of repair diagnostics route
System and Evidence diagnostics destinations	System / Evidence surfaces	Deferred	not available or separate surface truth	existing system/evidence surfaces	document deferred; no screenshot in this spec unless already reachable	not customer default diagnostics

Coverage files to review during implementation:

• docs/ui-ux-enterprise-audit/route-inventory.md
• docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md
• docs/ui-ux-enterprise-audit/page-reports/ui-012-environment-diagnostics.md
• docs/ui-ux-enterprise-audit/unresolved-pages.md only if the scoped modal/page remains unreachable

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes.
• Interaction class(es): diagnostic entrypoints, header/more actions, support diagnostics modal, status/no-action messaging, action links, technical-details disclosure.
• Systems touched: Environment Dashboard, Environment Diagnostics, support diagnostics modal/bundle, ManagedEnvironmentLinks::diagnosticsUrl(), EnvironmentDiagnostics::actionSurfaceDeclaration(), ActionSurfaceExemptions terminology if the canonical noun changes, UI audit artifacts, focused tests.
• Existing pattern(s) to extend: Spec 370 IA contract, Spec 373 diagnostic hierarchy, SupportDiagnosticBundleBuilder, existing support diagnostics actions, existing Filament action confirmation/RBAC helpers.
• Shared contract / presenter / builder / renderer to reuse: SupportDiagnosticBundleBuilder, ManagedEnvironmentLinks, OperationRunLinks for existing proof links, UiEnforcement, Capabilities, and existing Filament action/modal primitives.
• Why the existing shared path is sufficient or insufficient: The existing surfaces and builders already hold the truth. The missing piece is official entrypoint ownership and conditional discoverability, not another diagnostic abstraction.
• Allowed deviation and why: A page-local label or view-state helper is allowed only if it maps existing repair/no-action truth and does not become a generic diagnostic resolver.
• Consistency impact: Support Diagnostics, Repair Diagnostics, Provider/Permission Diagnostics, System Diagnostics, and customer review evidence must not share one vague "Diagnostics" mental model.
• Review focus: Confirm the implementation does not create a new diagnostic hub, does not promote /diagnostics to top-level navigation, and does not blend provider/permission readiness into repair diagnostics.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: No new OperationRun start/completion behavior. Existing support diagnostics may show existing OperationRun references only.
• Shared OperationRun UX contract/layer reused: Existing OperationRunLinks and canonical OperationRun detail URLs only when already present in bundle data.
• Delegated start/completion UX behaviors: N/A.
• Local surface-owned behavior that remains: Displaying existing operation context as support diagnostic evidence when repo-backed.
• Queued DB-notification policy: unchanged.
• Terminal notification path: unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: yes, presentation and routing semantics only.
• Boundary classification: mixed.
• Seams affected: diagnostic labels, provider/permission follow-up links, support-diagnostic bundle sections, managed-environment route helper usage.
• Neutral platform terms preserved or introduced: Support Diagnostics, Repair Diagnostics, Managed Environment, provider connection, required permissions, operation, evidence, system diagnostics.
• Provider-specific semantics retained and why: Microsoft/provider permission names and provider connection details may remain inside provider-owned destinations or lower support sections because they are real troubleshooting proof.
• Why this does not deepen provider coupling accidentally: The repair diagnostics route remains about TenantPilot membership/repair cases; provider readiness stays in provider/permission destinations and is explicitly deferred from /diagnostics.
• Follow-up path: Provider/Permission diagnostic productization remains a separate follow-up if fresh repo evidence shows a gap after Spec 353.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Environment Dashboard diagnostic entry	yes	Native Filament page/action/modal host	diagnostics entrypoint, support modal	page/action	no	existing surface only
Support Diagnostics modal purpose copy	yes	Filament modal + Blade content	support diagnostics, redaction, contextual help	modal/detail	no	existing modal only
Environment Diagnostics repair/no-action framing	yes	Filament page + Blade content	repair diagnostics, destructive repair actions	page/detail	no	existing route only
Provider/Permission/System/Evidence diagnostics	no direct change	N/A	deferred surfaces	none	no	documented as out of scope

Decision-First Surface Role

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Environment Dashboard diagnostic entry	Secondary Context Surface	Operator decides where to start diagnostics for this environment	primary quick path: Open support diagnostics; secondary repair path only when relevant	support bundle sections, repair diagnostics page	Secondary because dashboard remains the environment overview, not a diagnostic hub	starts from the operator's current environment page	avoids searching for hidden repair routes
Support Diagnostics modal	Tertiary Evidence / Diagnostics Surface	Operator/support decides what to inspect first	purpose, recommended first check, redaction/freshness, related context	provider/operation/evidence/audit references	Tertiary because it supports troubleshooting, not primary governance decisions	quick diagnostics from current environment/run context	reduces raw-section scanning
Environment Diagnostics page	Tertiary Evidence / Diagnostics Surface	Operator/support decides whether a repairable membership/access issue exists	repair-only purpose, action-needed/no-action/unavailable state, next action	individual blocker proof, technical repair context	Tertiary because it is a repair utility and may remain deeplink-only	focused repair diagnostic after support/dashboard signal	prevents false "generic diagnostics hub" expectations

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Environment Dashboard diagnostic entry	operator-MSP, support-platform	official quick entry and any conditional repair entry	short purpose descriptions	none on dashboard	Open support diagnostics	repair page link hidden or secondary unless repairable/repo-backed	dashboard owns only entrypoint decision
Support Diagnostics modal	operator-MSP, support-platform	recommended first check, purpose, redaction/freshness	lower diagnostic sections	redacted references and support context	open most relevant existing reference when available	raw provider payloads, secrets, unrestricted logs	summary owns first check; sections add proof
Environment Diagnostics page	operator-MSP, support-platform	repair/no-action state and recommended repair check	repair blocker details	technical repair context only if needed	existing repair action when blocker exists	raw IDs and unsupported checks	top state owns repair/no-action truth

UI/UX Surface Classification

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Environment Dashboard diagnostic entry	Utility / Diagnostic	Operator dashboard action area	Open support diagnostics	More action/modal	forbidden	More actions or secondary contextual placement	none added	N/A	/admin/workspaces/{workspace}/environments/{environment}	workspace + managed environment	Support Diagnostics	official diagnostic starting path	dashboard utility action
Support Diagnostics modal	Utility / Support	Support diagnostic modal	review first check or open reference	modal	forbidden	lower sections	none	source page	source page/action	workspace + managed environment/run context	Support Diagnostics	purpose, redaction, first check	support modal exemption
Environment Diagnostics page	Utility / Diagnostic	Repair diagnostics singleton	run existing repair or return to support diagnostics	same page	forbidden	contextual lower sections	header actions with confirmation/capability gating	N/A	/admin/workspaces/{workspace}/environments/{environment}/diagnostics	workspace + managed environment	Repair Diagnostics	repair/no-action state	singleton repair utility

Operator Surface Contract

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Environment Dashboard diagnostic entry	TenantPilot operator/support user	Choose the right diagnostic entrypoint	Secondary context action area	Where should I start for this environment?	Support Diagnostics as quick path; repair diagnostics if applicable	none on dashboard	supportability, repair availability	none added	Open support diagnostics	none added
Support Diagnostics modal	Support user/operator with capability	Decide what to inspect first	Tertiary support diagnostics	What should support check first?	recommended first check, purpose, redaction/freshness, related context	raw/support references below	support availability, freshness, redaction	read-only	Open existing reference if available	none
Environment Diagnostics page	TenantPilot operator/support user	Decide whether to run an existing repair action	Tertiary repair diagnostics	Are repairable environment access/membership issues active?	action-needed/no-action/unavailable state, impact, recommended repair check	detailed repair context below	repair availability, membership/access consistency	TenantPilot-only membership repair	Bootstrap owner / Merge duplicate access scopes when visible	existing repair actions only

Proportionality Review

• New source of truth?: no.
• New persisted entity/table/artifact?: no domain persistence. Spec-local artifacts are preparation and implementation evidence only.
• New abstraction?: no generic abstraction planned.
• New enum/state/reason family?: no persisted state family. Presentation labels such as official-entrypoint, secondary-entrypoint, and repair-only are documentation classifications, not runtime state.
• New cross-domain UI framework/taxonomy?: no. The diagnostic entrypoint matrix is a spec artifact and must not become a mandatory platform framework.
• Current operator problem: The product has multiple diagnostics-adjacent entrypoints, but their official roles are unclear.
• Existing structure is insufficient because: Existing surfaces answer diagnostic details once reached, but not which entrypoint should be used first or when /diagnostics should remain quiet/deeplink-only.
• Narrowest correct implementation: Clarify action labels, descriptions, conditional link/discoverability, no-action state, and artifacts over existing routes/actions.
• Ownership cost: Focused tests, browser smoke, screenshots, and a small entrypoint matrix.
• Alternative intentionally rejected: A diagnostic hub or provider-health framework. Current repo truth does not justify that breadth.
• Release truth: current-release productization of existing diagnostic surfaces.

Compatibility posture

This feature assumes the repo's pre-production posture. It introduces no migration, compatibility shim, legacy alias, backfill, or old-data preservation path.

Testing / Lane / Runtime Impact

• Test purpose / classification: Feature/Livewire for action visibility, labels, no-action/repair states, and modal content; Browser for actual dashboard entrypoint and route/modal reachability; static checks for preparation artifacts.
• Validation lane(s): confidence + browser + static diff/format checks.
• Why this classification and these lanes are sufficient: The behavior is UI entrypoint and copy hierarchy over existing DB-local truth. Feature/Livewire proves state and action contracts; Browser proves the entrypoint is findable and not visually competing.
• New or expanded test families: one bounded Spec 374 feature/browser family, or extension of existing Spec 373 diagnostic tests.
• Fixture / helper cost impact: Reuse existing smoke-login, workspace/environment, support diagnostics, and diagnostic repair fixtures. Do not add seeders or broaden smoke auth unless an established fixture already supports it.
• Heavy-family visibility / justification: Browser coverage is explicit and bounded because the source issue is discoverability and first-viewport productization.
• Special surface test profile: standard-native-filament for Environment Dashboard/action state; shared-detail-family for support diagnostics modal; exception-coded-surface for direct repair diagnostics page if fixture coverage is partial.
• Standard-native relief or required special coverage: ordinary feature coverage plus one browser smoke path.
• Reviewer handoff: Verify no new navigation/top-level hub, no provider/permission scope creep, existing destructive repair safety preserved, and no customer/auditor/raw leakage.
• Budget / baseline / trend impact: none expected beyond bounded browser smoke.
• Escalation needed: document-in-feature for fixture gaps; follow-up-spec for provider/permission diagnostics, evidence/system reachability, or UI bloat guard if recurring.
• Active feature PR close-out entry: Guardrail / Smoke Coverage.
• Planned validation commands:
  • git diff --check
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantDiagnosticsRepairsTest.php or the exact replacement Spec 374 repair-diagnostics test file
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=SupportDiagnostics
  • exact Spec 374 diagnostic-entry test file/filter if created; otherwise record why no DiagnosticEntry filter exists and run the concrete dashboard/support/repair tests that cover it
  • cd apps/platform && ./vendor/bin/sail pint --dirty if PHP changes
  • bounded browser smoke for Environment Dashboard diagnostic entry, support diagnostics modal, and Environment Diagnostics direct page

User Scenarios & Testing (mandatory)

User Story 1 - Start Diagnostics From The Environment Dashboard (Priority: P1)

An operator viewing an environment needs a clear first diagnostic entry. The dashboard should make Support Diagnostics the quick, visible path without adding competing buttons or implying that repair diagnostics is the default health hub.

Why this priority: The dashboard is the visible operator starting point and the current modal path is already repo-real.

Independent Test: Open the Environment Dashboard with an authorized fixture. Verify the More action exposes Open support diagnostics, its description/purpose is clear, and any repair diagnostics link is absent, secondary, or conditional according to repo-backed repair state.

Acceptance Scenarios:

1. Given an authorized operator is on Environment Dashboard, When they open diagnostic-related actions, Then Support Diagnostics is the clear quick diagnostic entrypoint.
2. Given no repairable diagnostics are active, When the dashboard renders, Then a repair diagnostics path is not promoted as a primary action.
3. Given a repairable diagnostic exists and the implementation adds a repair link, When the dashboard renders, Then the link is clearly secondary and labeled as repair diagnostics.

User Story 2 - Use Repair Diagnostics Without Generic-Hub Confusion (Priority: P2)

An operator who reaches /diagnostics should understand that the page is a repair diagnostics utility for supported membership/access issues, not a general provider, permission, system, or evidence diagnostics hub.

Why this priority: The direct page exists and is reachable by URL/helper, so no-action and repair states must be honest.

Independent Test: Open /admin/workspaces/{workspace}/environments/{environment}/diagnostics in no-action and repairable states. Verify the page labels itself around repair diagnostics, shows no-action copy when appropriate, and keeps existing repair action safety intact.

Acceptance Scenarios:

1. Given no supported repair issue is detected, When the direct diagnostics page renders, Then it states that no repair diagnostics are needed and points broader support context back to Support Diagnostics.
2. Given a duplicate-membership repair state exists, or an existing/synthetic missing-owner presentation path is exercised without adding new detection logic, When the page renders, Then the repair issue, impact, recommended action, and existing repair action are visible without implying broad health coverage.
3. Given the current actor lacks the required capability for a repair action, When the action is rendered or invoked, Then the existing disabled/403 behavior remains unchanged.

User Story 3 - Keep Deferred Diagnostics In Their Own Surfaces (Priority: P3)

An implementer needs a durable matrix that says where provider, permission, system, evidence, and customer review diagnostics belong so future work does not pile unrelated checks into Environment Diagnostics.

Why this priority: The biggest long-term risk is scope creep into a broad diagnostics hub.

Independent Test: Review diagnostic-entrypoint-matrix.md, source audit artifacts, and final diff. Provider/permission/system/evidence/customer items should be mapped to owned or deferred surfaces and should not create runtime scope in Spec 374.

Acceptance Scenarios:

1. Given a provider connection is blocked, When the matrix is reviewed, Then Provider Connections or Required Permissions are the destination, not Environment Repair Diagnostics.
2. Given Evidence Snapshot or System panel reachability is blocked, When implementation starts, Then the gap is documented as deferred rather than fixed in this spec.
3. Given a customer asks about review evidence, When entrypoint guidance is reviewed, Then Customer Review Workspace or Review Pack remains the destination, not support diagnostics.

Edge Cases

• ManagedEnvironmentLinks::diagnosticsUrl() may have no runtime caller. If so, document it as a deeplink utility or add exactly one secondary/conditional use if repo-backed and low-risk.
• A repo-backed repair value means an existing repair truth already available in this slice, currently duplicate membership for the current user, or a documented secondary deeplink utility decision. It does not authorize new missing-owner detection or new repair logic.
• Missing-owner repair detection is not currently repo-active because ManagedEnvironmentDiagnosticsService::tenantHasNoOwners() returns false; Spec 374 may preserve/test the existing presentation path but MUST NOT implement owner-detection or owner-recovery behavior.
• The current smoke fixture may only provide a no-action repair diagnostics state. Do not create a new seeder just for screenshots unless an existing browser fixture pattern already supports it.
• Support diagnostics may lack a specific recommended first check. Show a calm fallback rather than inventing likely cause.
• Repair diagnostics may have multiple blockers. Show one dominant repair path and demote secondary repair paths without hiding real blockers.
• Provider/permission/system/evidence issues may be discoverable from support diagnostics sections. They remain related context, not repair diagnostics responsibilities.

Requirements (mandatory)

Functional Requirements

• FR-374-001: Environment Dashboard MUST keep Support Diagnostics as the official quick diagnostic entrypoint for environment-near support cases.
• FR-374-002: Environment Dashboard MUST NOT promote the direct repair diagnostics page as a primary generic diagnostics hub.
• FR-374-003: If a repair diagnostics link is added from Environment Dashboard, it MUST be secondary, clearly labeled as repair diagnostics, and shown only when existing repair truth indicates value or when the matrix/source audit explicitly justifies one secondary deeplink utility.
• FR-374-004: Support Diagnostics modal MUST explain its purpose as quick support context and recommended first-check review before lower technical sections.
• FR-374-005: Environment Diagnostics page MUST frame itself as repair diagnostics for supported environment access or membership issues, not all environment health.
• FR-374-006: Environment Diagnostics no-action state MUST say no supported repair diagnostics are active and MUST direct broader support context to the Environment Dashboard support diagnostics entry.
• FR-374-007: Existing Environment Diagnostics repair actions MUST retain ->action(...), ->requiresConfirmation(), destructive/action styling where applicable, capability gating, server-side authorization, and audit/service ownership.
• FR-374-008: ManagedEnvironmentLinks::diagnosticsUrl() usage MUST be audited and documented as used, unused-retained, or adopted for one secondary repair diagnostics link.
• FR-374-009: Provider/Permission Diagnostics MUST remain mapped to Provider Connections, Required Permissions, or a future provider-readiness follow-up, not added to the repair diagnostics page.
• FR-374-010: System, Evidence, and Customer Review diagnostic needs MUST be mapped to their owned/deferred surfaces in the matrix and not implemented inside Spec 374.
• FR-374-011: The implementation MUST create/update diagnostic-entrypoint-matrix.md, source-audit-summary.md, affected-files.md, implementation-notes.md, browser report, screenshot index, validation report, and follow-up recommendations.
• FR-374-012: No new migrations, tables, persisted diagnostic truth, provider/Graph checks, OperationRun types, packages, panel providers, or top-level navigation entries MAY be introduced.
• FR-374-013: If runtime copy changes the canonical page noun from Environment Diagnostics toward Repair Diagnostics, action-surface declarations and exemptions MUST be audited and either updated consistently or documented as intentionally retained.

Non-Functional Requirements

• NFR-374-001: Page and modal rendering MUST remain DB-local and MUST NOT perform Graph/provider HTTP calls during render.
• NFR-374-002: Default-visible diagnostic copy MUST avoid secrets, raw provider payloads, unrestricted logs, raw credential values, and customer-unsafe debug detail.
• NFR-374-003: UI changes MUST reuse native Filament components or existing shared primitives before local Blade/Tailwind styling, and any local Blade/Tailwind change MUST document why it stays within existing Filament visual language.
• NFR-374-004: Browser proof MUST document blocked/unavailable states honestly rather than faking screenshots or fixture states.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions	Bulk Actions	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Environment Dashboard	apps/platform/app/Filament/Pages/EnvironmentDashboard.php	existing More actions including Open support diagnostics; optional secondary repair diagnostics link only if repo-backed	N/A	N/A	N/A	N/A	N/A	N/A	existing support diagnostics telemetry/audit preserved	no new primary diagnostic hub action
Support Diagnostics modal	apps/platform/resources/views/filament/modals/support-diagnostic-bundle.blade.php	source action opens modal	N/A	N/A	N/A	N/A	N/A	N/A	existing telemetry/audit preserved	read-only support modal
Environment Diagnostics	apps/platform/app/Filament/Pages/EnvironmentDiagnostics.php	existing Bootstrap owner, Merge duplicate access scopes when applicable	N/A	N/A	N/A	N/A	existing repair actions in header	N/A	existing service/audit ownership preserved	singleton repair diagnostics page

Key Entities

No new entities.

Existing records in scope as source/context only:

• Workspace: platform workspace scope.
• ManagedEnvironment: environment target for dashboard, support diagnostics, and repair diagnostics.
• OperationRun / ProviderConnection / Evidence / Review artifacts: existing related context inside support diagnostics or deferred surfaces only.

Success Criteria (mandatory)

Measurable Outcomes

• SC-374-001: In browser smoke, an authorized operator can open Support Diagnostics from Environment Dashboard and see the official quick diagnostic purpose.
• SC-374-002: In browser smoke or feature tests, Environment Diagnostics no-action state states repair-only/no-action semantics and does not imply broad health coverage.
• SC-374-003: Feature tests prove existing repair actions keep confirmation, capability gating, and server-side authorization.
• SC-374-004: diagnostic-entrypoint-matrix.md maps at least support quick context, repairable membership issue, no-owner state, duplicate membership, provider connection blocker, missing required permissions, evidence snapshot issue, system-level issue, and customer review evidence question.
• SC-374-005: Final diff contains no runtime changes to Provider Connections, Required Permissions, System panel auth, Evidence Snapshot reachability, OperationRun lifecycle, migrations, packages, or panel provider registration unless explicitly documented as an unavoidable bounded regression fix.

Risks

• Dashboard action copy could become too verbose or compete with primary environment decisions.
• Repair diagnostics could become more discoverable than its narrow scope justifies.
• Browser fixture may not cover a repair-blocker state.
• Provider/permission blockers may be tempting to include because they feel diagnostic, but they belong to separate surfaces.

Assumptions

• Spec 373 implementation results are the current repo truth on this branch.
• Environment Dashboard remains the primary operator starting surface for environment-near work.
• Support Diagnostics modal remains the official quick support context entry.
• Environment Diagnostics remains a direct route and can remain non-navigation/discoverability-limited.
• The product does not need a generic Diagnostic Hub in this slice.

Open Questions

• None blocking preparation.
• Implementation should verify whether ManagedEnvironmentLinks::diagnosticsUrl() remains unused and whether one conditional secondary link is justified.

Follow-up Spec Candidates

• Provider/Permission Diagnostic Productization, if fresh evidence shows Provider Connections or Required Permissions still fail as diagnostic destinations after Spec 353.
• Evidence/System browser fixture coverage, if browser reachability remains blocked and product priority warrants a fixture/auth spec.
• UI Bloat Regression Guard, if repeated surface work keeps adding diagnostic or support entrypoints without a shared review gate.
• Support Desk / PSA Handoff productization, separate from support diagnostics entrypoint semantics.