TenantAtlas/specs/241-support-diagnostic-pack/spec.md

Feature Specification: Support Diagnostic Pack

Feature Branch: 241-support-diagnostic-pack
Created: 2026-04-25
Status: Draft
Input: User description: "Support Diagnostic Pack"

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

• Problem: Support and troubleshooting work still requires manual context gathering across workspace, tenant, ProviderConnection, OperationRun, Finding, StoredReport, TenantReview, review artifacts, and audit history before the real issue can be addressed.
• Today's failure: A founder or support-capable operator must reconstruct the case by hand, which slows first response, increases the chance of oversharing sensitive provider context, and leaves later AI-assisted support without a safe canonical input layer.
• User-visible improvement: An entitled operator can open one deterministic, redacted diagnostic bundle for a tenant or one operation run and immediately see the current issue, freshness, and the right canonical records to inspect next.
• Smallest enterprise-capable version: A read-only, derived diagnostic bundle contract for tenant context and OperationRun context that references existing canonical records, applies first-class redaction and access checks, and writes audit entries for bundle generation without creating a new persisted support-pack entity.
• Explicit non-goals: No external ticketing or helpdesk integration, no support-desk product, no unrestricted raw payload export or download, no broad log export pipeline, no AI chatbot or autonomous AI support behavior, and no application implementation in this preparation artifact.
• Permanent complexity imported: One derived support-diagnostic bundle contract, one deterministic ordering and redaction policy, two bounded action entry points, and focused unit and feature coverage for authorization, redaction, and reference continuity.
• Why now: Self-Service Tenant Onboarding & Connection Readiness already exists as Spec 240, so the next supportability bottleneck is founder-led troubleshooting. This slice is the next recommended candidate, directly reduces manual support work, and reuses strong existing foundations that are already in the repo.
• Why not local: Page-local exports or copy helpers on one tenant or run page would duplicate truth, drift labels and redaction behavior, and still fail to provide one reusable support-safe contract across support workflows.
• Approval class: Core Enterprise
• Red flags triggered: Two red flags apply: it sounds like a foundation/support layer, and it touches more than one surface. Defense: the first slice is tightly limited to tenant context and OperationRun context, introduces no persistence, composes existing record truth instead of inventing a helpdesk framework, and explicitly defers broader support product work.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • /admin/t/{tenant} as the first tenant-context entry point for a tenant-scoped support diagnostic bundle
  • /admin/operations/{run} as the first OperationRun-context entry point for a run-scoped support diagnostic bundle
  • Existing related destinations reached from the bundle, including tenant findings, provider connection detail, tenant review detail, review-pack detail when present, and audit-log event detail
• Data Ownership: No new support_diagnostic_packs truth is introduced. The bundle is derived from existing canonical records. Source truth remains on workspace, tenant, OperationRun, ProviderConnection, Finding, StoredReport, TenantReview, ReviewPack when present, and AuditLog references tied to the same authorized scope.
• RBAC: Workspace membership is required, and both entry surfaces stay in the tenant-admin /admin plane. Tenant entitlement is required before any tenant-owned record is resolved. A dedicated tenant-role capability support_diagnostics.view in the canonical capability registry and tenant role map gates bundle generation and bundle viewing on both entry surfaces. The tenantless operation viewer only offers the action when the referenced run resolves to an entitled tenant scope in this slice; workspace-owned or system-plane runs remain out of scope. Existing per-record permissions still govern whether linked canonical records may be opened after the bundle is shown.

For canonical-view specs, the spec MUST define:

• Not applicable as a primary scope because the first slice adds support-diagnostic actions to existing tenant and operation-detail surfaces rather than introducing a new canonical collection page.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): header actions, diagnostic summaries, related-record links, evidence and report references, audit drill-throughs
• Systems touched: canonical operation related links, governance run explanation summaries, provider reason translation, existing resource detail routes, and audit-log detail resolution
• Existing pattern(s) to extend: existing operation related-link behavior, existing humanized operation explanation behavior, existing tenant-safe related-record routing, and existing audit-log navigation
• Shared contract / presenter / builder / renderer to reuse: OperationRunLinks, GovernanceRunDiagnosticSummaryBuilder, ProviderReasonTranslator, and existing tenant-safe record viewers for findings, provider connections, tenant reviews, review packs, and audit-log events
• Why the existing shared path is sufficient or insufficient: The existing paths are sufficient for labels, links, and run explanation language, but they do not yet assemble one support-safe cross-record bundle with deterministic ordering and redaction.
• Allowed deviation and why: One new derived bundle assembler is allowed, but it may only compose existing truth and existing shared helpers. Parallel page-local link builders, raw payload embedding, or a second support-summary dialect are not allowed.
• Consistency impact: Operation labels, related-record labels, provider explanation wording, redaction messaging, and audit-reference semantics must stay aligned with existing shared helpers so support workflows do not develop a local vocabulary.
• Review focus: Reviewers must verify that the bundle reuses shared link and explanation paths, does not duplicate record truth, and never embeds raw provider payloads or bundle-local provider-specific semantics by default.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: yes, for deep-link and explanation reuse only
• Shared OperationRun UX contract/layer reused: OperationRunLinks for tenant-safe operation routing and existing governance-run summary builders for run explanation language
• Delegated start/completion UX behaviors: tenant-safe Open operation and related-record link semantics are reused; queued toast, browser event, dedupe-or-blocked messaging, artifact-link creation beyond existing links, and queued DB notifications are N/A in this slice
• Local surface-owned behavior that remains: a read-only Open support diagnostics action from the tenant dashboard or operation detail surface
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: provider connection descriptors, provider reason translation, translated provider error excerpts, and redaction boundaries around provider-owned diagnostics
• Neutral platform terms preserved or introduced: support diagnostic bundle, tenant context, operation context, provider connection, related record, support summary, redaction reason, audit reference
• Provider-specific semantics retained and why: Microsoft-specific permission, consent, or provider failure reasons may appear only as translated excerpts inside provider-owned sub-sections when they are genuinely needed to explain the current issue.
• Why this does not deepen provider coupling accidentally: The bundle contract remains provider-neutral and references provider specifics only through existing provider-owned descriptors and reason translators. It does not introduce provider-shaped primary fields as platform-core truth.
• Follow-up path: none in this slice; later support or AI features can build on the same neutral bundle contract

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Tenant dashboard support diagnostic action	yes	Native Filament + shared primitives	header actions, diagnostic summaries, related links	page, action, preview	yes	Existing tenant dashboard action-surface exemption remains; this slice adds one bounded support action rather than reclassifying the dashboard as a queue
Monitoring operation detail support diagnostic action	yes	Native Filament + shared diagnostics primitives	operation detail, related links, audit drill-through	detail, action, preview	no	Extends the existing diagnostic surface instead of creating a second operation-detail dialect

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

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
Tenant dashboard support diagnostic action	Secondary Context Surface	An operator decides they need help or escalation for one tenant and wants a support-safe case summary before leaving the tenant workflow	Tenant identity, bundle freshness, provider connection state, latest relevant run or finding pressure, and a visible redaction boundary	Redacted section detail plus canonical links to runs, findings, reviews, reports, and audit events	Not primary because support is follow-up to tenant work, not the tenant’s daily decision queue	Follows tenant troubleshooting and escalation flow	Removes manual search across operations, provider, findings, reviews, and audit pages
Monitoring operation detail support diagnostic action	Tertiary Evidence / Diagnostics Surface	An operator is already inspecting one run and needs a support-safe summary they can act on or escalate	Run outcome, dominant issue, related record references, freshness, and a visible redaction boundary	Redacted section detail plus canonical links to provider, findings, review artifacts, and audit history	Not primary because operation detail is already a drill-in evidence surface	Follows monitoring drill-in workflow	Removes cross-page reconstruction from a single failed or degraded run

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

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
Tenant dashboard support diagnostic action	Dashboard / Overview / Actions	Tenant troubleshooting support entry point	Open the redacted tenant diagnostic bundle	Explicit header action opens a read-only support-diagnostic preview	forbidden	Existing tenant links remain secondary; bundle links live inside the preview	none	/admin/t/{tenant}	/admin/t/{tenant}	Active workspace, active tenant, bundle freshness, redaction notice	Support diagnostics / Support diagnostic bundle	Current issue summary, top related records, and redaction boundary	dashboard_exception - tenant dashboard already has a documented action-surface exemption; this action remains bounded and read-only
Monitoring operation detail support diagnostic action	Record / Detail / Actions	Canonical diagnostic detail support entry point	Open the redacted run diagnostic bundle	Existing operation detail page plus one explicit support-diagnostic action	forbidden	Existing related links remain secondary and continue to use the canonical operation surface	none	/admin/operations	/admin/operations/{run}	Workspace context, active tenant context when present, operation identifier, redaction notice	Support diagnostics / Support diagnostic bundle	Dominant issue, related records, freshness, and redaction boundary	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

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
Tenant dashboard support diagnostic action	Workspace manager or support-capable tenant operator	Decide whether the tenant case can be escalated or troubleshot with one support-safe bundle	Dashboard action + read-only preview	Do I have enough support-safe context for this tenant without opening raw provider diagnostics?	Tenant identity, workspace context, provider connection state, latest relevant run summary, active finding pressure, latest report or review references, and redaction notice	Full related records remain on their native pages; raw payloads and unrestricted logs stay excluded	connection health, run freshness, finding pressure, report freshness, review availability	None	Open support diagnostics, open canonical related record links	none
Monitoring operation detail support diagnostic action	Workspace manager or support-capable operator	Decide whether one operation case has enough support-safe context for follow-up or escalation	Detail action + read-only preview	What is the current operation issue, what related records matter, and what is safe to share or reuse for support?	Humanized run summary, related provider and tenant references, current finding or review references, audit references, and redaction notice	Full diagnostics remain on canonical run, finding, provider, review, or audit pages; raw payloads stay excluded	execution outcome, provider connection state, artifact freshness, related finding pressure	None	Open support diagnostics, open canonical related record links	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: yes
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: Support work starts too late because someone must first gather the relevant tenant, provider, run, finding, report, review, and audit context by hand.
• Existing structure is insufficient because: Existing pages explain local truth, but no current path assembles one support-safe, deterministic bundle across tenant and OperationRun context while enforcing redaction and deny-as-not-found behavior first.
• Narrowest correct implementation: Add one derived bundle contract for tenant and OperationRun contexts only, with references to existing canonical records, deterministic ordering, redaction, and audit logging. Do not persist the bundle, build a helpdesk product, or add a generic export framework.
• Ownership cost: Maintain one derived bundle schema, one deterministic redaction policy, one audit event family for bundle usage, and focused unit and feature coverage for authorization and reference continuity.
• Alternative intentionally rejected: A persisted SupportDiagnosticPack entity and broad raw-export pipeline were rejected as too heavy, and page-local copy/export helpers were rejected as too narrow and drift-prone.
• Release truth: current-release truth

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Unit, Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: Unit coverage proves deterministic section ordering, redaction behavior, and canonical reference shaping. Feature coverage proves tenant and OperationRun entry points, deny-as-not-found isolation, capability enforcement, and canonical related-link continuity without introducing browser or heavy-governance breadth.
• New or expanded test families: A focused support-diagnostics unit family plus targeted feature coverage for tenant-context and operation-context actions and authorization boundaries
• Fixture / helper cost impact: Moderate. Tests can reuse existing workspace, tenant, OperationRun, ProviderConnection, Finding, StoredReport, TenantReview, ReviewPack, and AuditLog fixtures, but must add explicit redaction and inaccessible-reference cases.
• Heavy-family visibility / justification: none
• Special surface test profile: standard-native-filament + monitoring-state-page
• Standard-native relief or required special coverage: Ordinary feature coverage is sufficient, with explicit assertions for redaction markers, stable ordering, 404 versus 403 semantics, canonical related-link reuse, and the absence of new run-creating or provider-backed side effects when diagnostics are opened.
• Reviewer handoff: Reviewers must confirm that no raw provider payloads or secrets appear in the bundle, that unauthorized cross-workspace or cross-tenant access is treated as not found, that entitled-but-uncapable users receive authorization failure, that canonical links and labels stay aligned with existing support helpers, and that opening diagnostics creates no new OperationRun or provider-backed side effect.
• Budget / baseline / trend impact: Low-to-moderate increase in narrow unit and feature coverage only; no new browser or heavy-governance baseline is expected.
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/SupportDiagnostics/SupportDiagnosticBundleBuilderTest.php tests/Unit/Support/SupportDiagnostics/SupportDiagnosticBundleRedactionTest.php
  • cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/SupportDiagnostics/TenantSupportDiagnosticActionTest.php tests/Feature/SupportDiagnostics/OperationRunSupportDiagnosticActionTest.php tests/Feature/SupportDiagnostics/SupportDiagnosticAuthorizationTest.php tests/Feature/SupportDiagnostics/SupportDiagnosticAuditTest.php

User Scenarios & Testing (mandatory)

User Story 1 - Open a tenant support-safe bundle (Priority: P1)

As a workspace manager or support-capable operator, I want one tenant-scoped diagnostic bundle so I can start support without manually gathering records across multiple pages.

Why this priority: This is the first support workflow compression win. If tenant context still has to be rebuilt by hand, the feature has not reduced founder-led support work.

Independent Test: Can be fully tested by opening a tenant-scoped support diagnostic bundle from the tenant dashboard with seeded provider, finding, report, review, and audit records and verifying that the bundle is redacted, deterministic, and linked to canonical records only.

Acceptance Scenarios:

1. Given an entitled operator opens support diagnostics for a tenant with an unhealthy provider connection, recent failed run, open findings, and a recent tenant review, When the bundle renders, Then it shows one redacted tenant summary with canonical references to the provider connection, most relevant operation run, related findings, latest stored reports, tenant review or review pack when present, and relevant audit references.
2. Given the current user is not a member of the workspace or is not entitled to the tenant, When they try to open the tenant bundle, Then the system responds as not found and does not reveal whether the tenant has provider issues, findings, or support history.
3. Given the current user is entitled to the tenant but lacks the support-diagnostics capability, When they try to open the tenant bundle, Then the system denies the action as an authorization failure without revealing additional diagnostic detail.

---

User Story 2 - Open a run-centered support-safe bundle (Priority: P1)

As a support-capable operator already inspecting a run, I want a run-centered diagnostic bundle that uses the same operation explanation language as Monitoring so I can diagnose or escalate one case quickly.

Why this priority: A large share of support work begins with one suspicious run. If run context still requires cross-page reconstruction, the first-response workflow remains too slow.

Independent Test: Can be fully tested by opening an operation-scoped support diagnostic bundle from the canonical operation detail surface and verifying that the bundle reuses existing humanized run summaries, canonical related links, and redaction rules.

Acceptance Scenarios:

1. Given an entitled operator opens support diagnostics for a failed or degraded operation run, When the bundle renders, Then it reuses the existing humanized operation explanation, includes the related provider connection, related finding, related stored report, related tenant review or review pack when present, and relevant audit references, and keeps those references canonical rather than duplicating record truth.
2. Given the operation context contains sensitive provider response data or raw payload excerpts, When the bundle renders, Then those values are excluded by default and replaced with explicit redaction markers or translated high-level reasons.

---

User Story 3 - Rely on deterministic, redacted support summaries (Priority: P2)

As a product owner preparing later AI-assisted support, I want support diagnostic bundles to be deterministic and machine-readable so later support tooling can reuse them without widening access or depending on ad-hoc summaries.

Why this priority: Deterministic structure is what makes the first slice reusable later without adding a second translation layer or unsafe copy-and-paste support flow.

Independent Test: Can be fully tested by generating the same authorized bundle repeatedly against unchanged source truth and verifying stable section order, stable reference order, and stable redaction behavior.

Acceptance Scenarios:

1. Given the same authorized tenant or run input and unchanged source truth, When the bundle is generated multiple times, Then the same sections, reference order, and redaction outcomes appear in the same order every time.
2. Given a related record becomes missing or inaccessible after the first generation, When the bundle is generated again, Then the summary marks that record as missing or inaccessible without leaking details from the inaccessible record.

Edge Cases

• A tenant may have no provider connection, no recent operation run, or no current tenant review; the bundle must still render a truthful support summary with explicit missing, not yet observed, or not available states.
• A run may reference a stored report that has no dedicated viewer surface. The bundle must reference the canonical record identity and freshness without inventing a new report page.
• A run may reference a review pack or tenant review that has expired, been deleted, or is no longer accessible; the bundle must degrade gracefully and preserve deny-as-not-found boundaries.
• Provider error detail may exist only in raw payload context. The bundle must prefer translated high-level reason semantics and a redaction marker instead of echoing raw payload content.
• Workspace-level audit events may exist without a tenant-bound detail record. The bundle must include only audit references that are valid for the authorized scope and primary context.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no new Microsoft Graph calls, no new destructive workflow, and no new queued support-processing pipeline. Bundle generation is a read-only supportability action. If implementation writes no OperationRun, it must still write AuditLog entries for bundle generation and any explicit copy or share action using redacted metadata only.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): This feature introduces one bounded derived bundle contract because current tenant and operation pages still force manual reconstruction for support. No new persistence, status family, or support-desk domain entity is added. The design stays aligned with derive-before-persist and explicit-before-generic by composing existing records instead of creating a generalized support framework.

Constitution alignment (XCUT-001): This feature is cross-cutting across operation links, explanation summaries, provider reason translation, evidence or review viewers, and audit drill-through. It must extend the existing shared paths instead of creating page-local support-link or support-summary dialects.

Constitution alignment (PROV-001): The support diagnostic bundle contract stays provider-neutral. Provider-specific content remains contextual inside provider-owned translated sections and must not become new platform-core fields in the bundle.

Constitution alignment (TEST-GOV-001): Proof stays in focused unit and feature coverage. No heavy-governance or browser lane is justified for the first slice. Fixture cost must remain explicit and limited to real support contexts using existing models.

Constitution alignment (OPS-UX): Existing OperationRun lifecycle rules, summary_counts, and notification rules remain unchanged. The feature reuses OperationRun summaries and links only; it does not add a new operation type or change run-state ownership.

Constitution alignment (OPS-UX-START-001): The feature reuses OperationRunLinks for tenant-safe URL resolution and existing operation labels. It does not add queued toasts, dedupe messaging, lifecycle notifications, or run-enqueued browser events.

Constitution alignment (RBAC-UX): The affected authorization plane is the tenant-admin /admin plane, including tenant-context routes and the canonical tenantless operation detail viewer. Non-members or non-entitled users must receive 404. The new support_diagnostics.view gate is tenant-role scoped through the canonical tenant capability registry and role map, and the run-context action is only in scope when the referenced run resolves to an entitled tenant. Entitled members lacking that capability must receive 403. Server-side authorization must run before any bundle section resolves a tenant-owned record. Linked canonical destinations continue to enforce their own authorization rules.

Constitution alignment (OPS-EX-AUTH-001): Not applicable.

Constitution alignment (BADGE-001): No new badge family is required. Existing status and reason semantics remain authoritative.

Constitution alignment (UI-FIL-001): The feature must use native Filament page or header actions and read-only summary sections or infolist-style presentation. Local replacement markup for status semantics or redaction language is intentionally avoided.

Constitution alignment (UI-NAMING-001): The target object is the support diagnostic bundle. Primary operator-facing verbs remain Open support diagnostics, Open operation, Open finding, Open provider connection, and related canonical record labels. Implementation-first terms such as payload blob, Graph response, or raw JSON must stay out of primary labels.

Constitution alignment (DECIDE-001): The affected surfaces remain secondary or tertiary support and diagnostics contexts. The feature must not create a new decision queue or a new support-desk surface.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): Each affected surface keeps exactly one primary inspect or open model. The support-diagnostic action is read-only, secondary to the existing tenant or operation surface, and must not compete with mutation or add redundant View actions.

Constitution alignment (ACTSURF-001 - action hierarchy): The support-diagnostic action is a contextual read-only action. It must stay separated from mutation and dangerous actions and must not turn into a mixed catch-all support menu.

Constitution alignment (OPSURF-001): Default-visible content must stay operator-first: summary, freshness, related record references, and redaction state first; raw diagnostics remain on the original canonical pages.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): Direct mapping from one existing page is insufficient because support context spans multiple canonical records. The derived bundle replaces manual reconstruction, not existing truth. Tests must prove business outcomes: safe first-response context, safe redaction, and safe authorization boundaries.

Constitution alignment (Filament Action Surfaces): The Action Surface Contract remains satisfied. Each affected surface adds one explicit read-only support-diagnostic action, keeps one primary inspect model, adds no redundant View action, and adds no destructive placement changes. The tenant dashboard keeps its existing exemption for broader dashboard retrofit work.

Constitution alignment (UX-001 — Layout & Information Architecture): Any preview or detail presentation for the bundle must use summary-first sections, explicit redaction messaging, and one clear path back to the canonical records. The feature does not add create or edit screens.

Functional Requirements

• FR-241-001 Context coverage: The system MUST allow an entitled operator to generate a support diagnostic bundle for at least two first-slice contexts: one tenant context and one specific OperationRun context.
• FR-241-002 Canonical truth reuse: The bundle MUST reference existing canonical records for workspace, tenant, OperationRun, ProviderConnection, Finding, StoredReport, TenantReview, ReviewPack when present, and AuditLog references, instead of duplicating their full truth into a new persisted support record.
• FR-241-003 Tenant summary shape: A tenant-context bundle MUST include a deterministic redacted summary covering tenant identity, workspace scope, provider connection health, most relevant recent operation context, relevant active findings, latest stored-report freshness, tenant-review or review-pack references when present, and audit references relevant to the same scope.
• FR-241-004 Operation summary shape: An OperationRun-context bundle MUST reuse existing humanized operation summary language, include related provider and artifact references when present, include relevant findings or review artifacts when present, and include audit references tied to the same run or immediate follow-up.
• FR-241-005 Deterministic ordering: For the same authorized input and unchanged source truth, the bundle MUST emit the same section order, same reference order, and same redaction outcomes.
• FR-241-006 Redaction first: Sensitive raw provider payloads, secrets, tokens, full response bodies, and unrestricted log excerpts MUST be excluded by default. When exclusion happens, the bundle MUST show explicit redaction markers or translated high-level reasons instead of silent omission.
• FR-241-007 Access checks first: Workspace membership, tenant entitlement, and support-diagnostics capability checks MUST run before any tenant-owned bundle section is resolved.
• FR-241-008 404 versus 403 boundaries: Non-members and non-entitled users MUST receive deny-as-not-found behavior. Entitled users lacking the support-diagnostics capability MUST receive authorization failure. Inaccessible related records inside an otherwise allowed bundle MUST degrade safely without revealing protected record details.
• FR-241-009 Canonical link continuity: Bundle links and record labels MUST reuse existing canonical navigation and explanation helpers so the bundle uses the same record names and destination meaning as the rest of the product.
• FR-241-010 Freshness and completeness cues: The bundle MUST show freshness, missing-data, or stale-data cues for included references so support workflows can distinguish fresh context from incomplete or absent context.
• FR-241-011 Auditability: Bundle generation and any explicit bundle copy or share action in scope MUST write audit entries that record actor, scope, primary context, and redaction mode without storing excluded raw payload content.
• FR-241-012 No new support-pack persistence: The first slice MUST NOT create a persisted SupportDiagnosticPack entity, a support queue, or a broad export pipeline.
• FR-241-013 Later AI readiness: The bundle contract MUST remain machine-readable and support-safe so later AI-assisted support can consume the same contract without requiring broader access.
• FR-241-014 Graceful missing-reference handling: If a referenced canonical record is missing, expired, or inaccessible, the bundle MUST identify that state explicitly and continue rendering the remaining authorized context.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Tenant dashboard support diagnostics	App\Filament\Pages\TenantDashboard	Open support diagnostics (read-only, capability-gated)	n/a	none	none	none added	Open support diagnostics	n/a	yes	Existing tenant dashboard exemption remains; this slice adds one bounded support action only
Monitoring operation detail support diagnostics	App\Filament\Pages\Operations\TenantlessOperationRunViewer	Open support diagnostics (read-only, capability-gated)	Existing operation detail remains the primary inspect model	none	none	n/a	Open support diagnostics	n/a	yes	No new destructive action, no redundant View action, no action-group catch-all

Key Entities (include if feature involves data)

• Support Diagnostic Bundle: A derived, read-only support-safe envelope for one tenant context or one operation context.
• Diagnostic Reference Set: The typed set of canonical record references included in the bundle, such as tenant, operation, provider connection, finding, stored report, tenant review, review pack, and audit reference.
• Redaction Marker: An explicit indicator that a sensitive value or raw payload section was intentionally excluded and why.
• Diagnostic Context Slice: The bounded entry context for one bundle generation request, either tenant context or OperationRun context.

Assumptions & Dependencies

• Spec 240 Self-Service Tenant Onboarding & Connection Readiness already exists on its own feature branch and remains the immediately preceding supportability milestone.
• Existing OperationRun, Finding, ProviderConnection, StoredReport, TenantReview, ReviewPack, AuditLog, and operator explanation foundations are mature enough to support a derived bundle without introducing new persistence.
• Existing operation explanation and related-link helpers remain the authoritative path for run wording and canonical navigation continuity.
• StoredReport currently acts as canonical evidence truth without a dedicated general-purpose report viewer; the first slice therefore references report identity and freshness instead of inventing a new report surface.
• Product Usage & Adoption Telemetry and Operational Controls & Feature Flags remain deferred because they either depend on onboarding and readiness behavior landing first or require new greenfield control and telemetry infrastructure that this slice intentionally avoids.

Risks

• Over-including provider diagnostics would create unnecessary data-exposure risk and undermine tenant or workspace isolation.
• Under-including context would push support users back to manual reconstruction and fail the workflow-compression goal.
• A page-local implementation on only one surface could drift from shared operation or provider language and create inconsistent support summaries.
• Deterministic bundle ordering must not accidentally depend on incidental query order or uncontrolled related-record selection.

Open Questions

• None for the first slice. Follow-up questions about external ticket attachment, persistent support requests, or AI-assisted support behavior are explicitly deferred.

Non-Goals

• Add an external ticketing or helpdesk integration.
• Create a support-desk product or support queue inside TenantPilot.
• Allow unrestricted raw provider payload export or download.
• Build a broad log export pipeline.
• Add an AI chatbot, autonomous AI support behavior, or agentic triage flow.
• Introduce a persisted support-pack entity in the first slice.

Success Criteria (mandatory)

Measurable Outcomes

• SC-241-001: In acceptance review, an entitled operator can open a tenant or operation support diagnostic bundle and identify the current issue, the authorized scope, and the next canonical records to inspect within 30 seconds without manually searching across more than one additional product surface.
• SC-241-002: In validation scenarios, 100% of covered tenant and operation bundle cases exclude sensitive raw provider payloads by default while still surfacing the relevant related-record references and freshness cues.
• SC-241-003: In validation scenarios, 100% of unauthorized cross-workspace or cross-tenant bundle attempts return not found, and 100% of entitled-but-uncapable attempts return authorization failure.
• SC-241-004: In deterministic regression coverage, repeated generation of the same unchanged authorized bundle produces the same section order, same reference order, and same redaction markers.