TenantAtlas/specs/366-management-report-layout-branded-report-themes-v1/spec.md

Feature Specification: Spec 366 - Management Report Layout & Branded Report Themes v1

Feature Branch: 366-management-report-layout-branded-report-themes-v1
Created: 2026-06-08
Status: Draft / Ready for implementation
Input: User-provided draft "Spec 366 - Management Report Layout & Branded Report Themes v1"

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

• Problem: The rendered Review Pack report is repo-real after Specs 356 and 357, but it still needs a management-ready report layout and bounded co-branding treatment so MSPs can use it as a customer-facing governance artifact without hiding limitations, evidence state, or TenantPilot source truth.
• Today's failure: A stakeholder can open a rendered report, but the report can still read too much like an admin/detail output or appendix-first renderer instead of a polished management report. Branding is controller-local text only, profile layout hierarchy is not yet a first-class report contract, and print/readability expectations are not locked by a dedicated Spec 366 gate.
• User-visible improvement: MSP and customer stakeholders can open a report and immediately see prepared-by/prepared-for identity, report profile, readiness state, KPI/decision strip, executive story, key risks, evidence basis, accepted risks, appendix hierarchy, and mandatory disclosures in a print-friendly layout.
• Smallest enterprise-capable version: Productize the existing rendered-report route with profile-aware layout ordering, a bounded derived report theme contract, repo-backed KPI strip, improved report canvas/print hierarchy, localized dominant copy, and focused Unit/Feature/Browser validation.
• Explicit non-goals: No report engine rewrite, no second renderer, no Review Pack ZIP contract change, no native PDF package, no logo upload UI, no report theme CRUD, no scheduled delivery, no public/customer portal, no AI summary, no framework-specific compliance report, no hiding mandatory disclosures.
• Permanent complexity imported: One bounded report theme resolver or equivalent derived view-model shape, additional profile-aware layout fields, partialized report Blade only where it reduces review risk, localized report copy, focused Unit/Feature/Browser tests, and screenshot artifacts.
• Why now: Specs 356 and 357 established the HTML report, static profile registry, disclosure policy, and profile-aware safety boundary. The next sellability gap is report productization: layout, co-branding, print readiness, and management presentation.
• Why not local: Leaving branding and layout as scattered controller/view decisions would make it hard to prove that profile changes, print output, and mandatory disclosures stay consistent across report states.
• Approval class: Workflow Compression / Core Enterprise.
• Red flags triggered: New derived resolver/view-model, customer-facing report surface, profile-aware visual hierarchy. Defense: the resolver is non-persisted, bounded to the existing Review Pack rendered-report family, and justified by current profile/disclosure/report states already implemented in Specs 356 and 357.
• Score: Nutzen: 3 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 3 | Wiederverwendung: 1 | Gesamt: 12/12
• Decision: approve as a bounded productization spec over the existing rendered-report route.

Candidate Selection Gate

• Selected candidate: Management Report Layout & Branded Report Themes v1.
• Source: Direct user-provided Spec 366 draft, aligned with the open report/productization trajectory after Specs 355, 356, and 357.
• Why selected: It is the next narrow report productization slice after the profile/disclosure policy exists. It improves customer/MSP usefulness without introducing delivery, portal, PDF, AI, or compliance-framework scope.
• Close alternatives deferred:
  • Scheduled Report Delivery Foundation v1: deferred because report layout/truth must be stable before delivery approvals or send ledgers.
  • Compliance Report Profile Foundation v1 and NIS2/CIS reports: deferred because framework-specific semantics would expand beyond the current report profile/disclosure base.
  • Customer Portal Report Consumption Boundary: deferred because the authenticated admin report must be customer-safe and print-ready first.
  • Private AI/HITL Report Review Preparation: deferred until the report profile, disclosure, layout, and delivery approval foundations are stable.
• Completed-spec guardrail result:
  • specs/356-review-pack-pdf-html-renderer-v1/ contains completed tasks and validation signals; it is historical context only.
  • specs/357-report-profiles-disclosure-policy-v1/ contains completed tasks and validation signals; it is historical context only.
  • specs/365-operations-ui-operator-actions-regression-gate/ is unrelated completed/immediate predecessor context for platform action maturity and is not modified.
  • No existing specs/366-management-report-layout-branded-report-themes-v1/ package existed before this prep.
• Roadmap relationship: Report/productization follow-through on top of Review Pack rendered report, profile, disclosure, and platform sellable smoke work.
• Smallest viable slice: Authenticated rendered report layout/theme productization only.
• Gate result: PASS.

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • Existing authenticated rendered Review Pack report URL generated by ReviewPackService::generateRenderedReportUrl()
  • Existing Review Pack detail route that opens the rendered report
  • Existing Environment Review detail route that opens the current rendered report
• Data Ownership: Existing workspace/managed-environment-owned review_packs, environment_reviews, evidence snapshot truth, and report summary payloads. No new table or independent persisted theme/profile entity is introduced.
• RBAC: Existing workspace membership, managed-environment entitlement, ReviewPackPolicy, Capabilities::REVIEW_PACK_VIEW, and current rendered-report authorization stay authoritative.

For this workspace-scope report:

• Default filter behavior when tenant-context is active: N/A. This is an existing signed rendered-report route over a concrete Review Pack; it must not introduce new environment query-context behavior.
• Explicit entitlement checks preventing cross-tenant leakage: The rendered report must keep existing deny-as-not-found behavior for non-members or wrong environment/workspace, and 403 for members missing review-pack view capability.

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
• New modal/drawer/wizard/action added
• New table/form added
• New report state presentation added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write N/A - no reachable UI surface impact plus rationale)

• Route/page/surface:
  • apps/platform/app/Http/Controllers/ReviewPackRenderedReportController.php
  • apps/platform/resources/views/review-packs/rendered-report.blade.php
  • existing rendered report links from EnvironmentReviewResource and ReviewPackResource
• Current or new page archetype: Existing rendered review report / review-pack detail supporting surface. UI audit references include docs/ui-ux-enterprise-audit/page-reports/ui-042-review-pack-detail.md and docs/ui-ux-enterprise-audit/page-reports/ui-099-rendered-review-report.md.
• Design depth: Strategic / customer-facing report surface.
• Repo-truth level: repo-verified existing route and rendered-report family.
• Existing pattern reused: Specs 356/357 rendered-report route, ReportProfileRegistry, ReportDisclosurePolicy, ReviewPackOutputResolutionGuidance, review-pack authorization, current report view tests, and Spec 357 browser smoke conventions.
• New pattern required: Bounded report theme/layout contract only. No general design system or reporting framework.
• Screenshot required: yes. Implementation must save report-state screenshots under specs/366-management-report-layout-branded-report-themes-v1/artifacts/screenshots/.
• Page audit required: update ui-099-rendered-review-report.md if the report hierarchy materially changes; otherwise record a proportional no-update rationale in close-out.
• Customer-safe review required: yes. The rendered report is customer-facing when the profile is customer-facing.
• Dangerous-action review required: no. Report actions are read-only/print/download/navigation; any new mutating action is out of scope.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md - no update needed; UI-099 remains P1 Strategic Surface and now has evidence.
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md - no update needed; no new unresolved group.
  • docs/ui-ux-enterprise-audit/unresolved-pages.md - no update needed; UI-099 is not unresolved.
  • N/A - no reachable UI surface impact
• Coverage artifact decision: Implementation must update the rendered-report page report/design coverage if the visual hierarchy or customer-safe report contract materially changes. If the change is contained to the existing report archetype and page-report guidance remains accurate, close-out must record why no coverage file changed.
• No-impact rationale when applicable: N/A.

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): evidence/report viewer, status/readiness messaging, print/report toolbar, artifact links, customer-safe disclosure.
• Systems touched:
  • ReportProfileRegistry
  • ReportDisclosurePolicy
  • ReviewPackOutputResolutionGuidance
  • ReviewPackOutputReadiness
  • ReviewPackService::generateRenderedReportUrl()
  • ReviewPackRenderedReportController
  • rendered report Blade template and localization files
• Existing pattern(s) to extend: current rendered-report payload, profile/disclosure policy, customer-safe Review Pack handoff, current read-only report toolbar.
• Shared contract / presenter / builder / renderer to reuse: Reuse ReportProfileRegistry, ReportDisclosurePolicy, existing Review Pack summary payloads, and current authorization/download link seams first.
• Why the existing shared path is sufficient or insufficient: Existing paths are sufficient for profile resolution, disclosure, readiness, signed URL generation, and base HTML rendering. They are insufficient for an explicit report theme/layout contract and management-ready section ordering.
• Allowed deviation and why: Add one bounded ReportThemeResolver or equivalent local view-model method if controller-local branding/layout fields become too hard to test or duplicate. Do not add persistence, CRUD, upload, or global theme registry.
• Consistency impact: Profile labels, audience labels, readiness warnings, disclosure footer, source metadata, and co-branding slots must stay consistent between route output, print output, and browser screenshots.
• Review focus: Verify the layout does not bypass disclosure policy or profile fail-closed behavior, and that branding never changes report truth.

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?: no
• Shared OperationRun UX contract/layer reused: N/A
• Delegated start/completion UX behaviors: N/A
• Local surface-owned behavior that remains: N/A
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception required?: none. Existing Review Pack generation and OperationRun associations must not be changed by this spec.

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?: no
• Boundary classification: N/A
• Seams affected: N/A
• Neutral platform terms preserved or introduced: report, profile, audience, readiness, evidence basis, review pack, managed environment, workspace.
• Provider-specific semantics retained and why: Provider-specific details remain only in existing report payload sections when already profile/disclosure-safe. No provider calls or provider-specific theme rules are introduced.
• Why this does not deepen provider coupling accidentally: The report uses stored Review Pack/review/evidence truth only and does not inspect Graph/provider runtime state.
• Follow-up path: none.

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
Rendered report toolbar	yes	Existing custom Blade report chrome	report viewer, print, artifact links	report route, toolbar, print CSS	yes - UI-EX-001: Legitimate Custom Surface Exception	Toolbar remains outside print canvas
Report canvas cover/state/KPI/executive layout	yes	Existing custom Blade report canvas	status messaging, evidence/report viewer	report canvas, profile layout	yes - UI-EX-001: Legitimate Custom Surface Exception	Customer-facing strategic report surface
Report appendix/disclosure footer	yes	Existing custom Blade report sections	evidence/report viewer, mandatory disclosure	section ordering, footer	yes - UI-EX-001: Legitimate Custom Surface Exception	Disclosure policy remains authoritative
Co-branding/theme slots	yes	Derived text presentation	report identity / customer artifact	cover/footer	no	No upload UI or persisted theme

UI-EX-001 Legitimate Custom Surface Exception

• Exception type: UI-EX-001: Legitimate Custom Surface Exception.
• Product reason: The rendered report is a customer-facing, print-oriented governance artifact. It must express cover identity, readiness, KPI/decision strip, executive story, profile-aware appendix hierarchy, disclosures, and print behavior in a layout that ordinary Filament CRUD/detail/table primitives do not express cleanly.
• Smallest custom behavior required: Keep one local Blade report canvas and toolbar/print treatment for the existing rendered-report route, with profile-aware section ordering and text-only co-branding slots. Do not create a general design system, second report renderer, theme editor, native PDF stack, or customer portal.
• What remains standardized: Authorization, workspace/environment entitlement, Review Pack launch links, owner surfaces, policy checks, profile resolution, disclosure policy, localization, and validation stay on existing Laravel/Filament/Review Pack paths. Report actions stay read-only navigation/download/print and must not introduce destructive or mutating action semantics.
• State owner: ReviewPackRenderedReportController owns the derived report payload for this route; ReportProfileRegistry owns effective profile/layout inputs; ReportDisclosurePolicy owns mandatory disclosure and safety limitations; the Blade view owns presentation and print CSS only.
• Proof / review evidence: Implementation tasks T012, T046-T053, and T058-T060 must validate report hierarchy, print-toolbar behavior, screenshots, no JS/console errors, no text overlap, accessibility/focus basics, and UI coverage update or no-update rationale.
• Spread control: Custom layout remains bounded to resources/views/review-packs/rendered-report.blade.php and optional local partials for reviewability. Any repeated UI primitive, status/badge semantics, or broader report-layout framework must stop and update spec/plan first.

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
Rendered report cover/state/KPI area	Primary Decision Surface for report consumption	Customer/MSP reads the report to decide whether it is shareable and what needs attention	prepared by/for, profile, readiness, KPI/decision strip, executive summary, evidence state, next action	appendix, technical posture, source metadata	Primary because the report must stand alone in review meetings	Follows Review Pack rendered-report profile/disclosure workflow	Reduces need to inspect admin pages to understand report state
Supporting appendix	Tertiary Evidence / Diagnostics	Auditor or technical reader needs proof/context after the management story	concise appendix heading and availability	section completeness, source metadata, evidence/operation references	Secondary unless profile is auditor_appendix	Follows profile-aware disclosure	Keeps executive reports readable while retaining proof

Audience-Aware Disclosure (mandatory when operator-facing surfaces are changed)

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
Customer executive rendered report	customer-read-only, operator-MSP	report identity, customer-safe readiness, KPI strip, executive summary, key risks, evidence basis, disclosures	limited or absent	raw JSON and internal rationale absent	Review next action / print / download through existing toolbar	technical appendix minimized, raw/internal fields hidden	Hero states the blocker once; sections add evidence only
Customer technical rendered report	customer-read-only, operator-MSP	readiness, evidence basis, technical posture summary, risks, accepted risks, disclosures	structured technical sections	raw payloads absent	Review evidence or follow next action	internal-only warnings and raw diagnostics hidden	Profile layout decides detail level
Internal MSP rendered report	operator-MSP, support-platform	internal warning, operator summary, blockers, evidence/readiness, disclosures	allowed structured diagnostics	raw/support evidence still not primary	Review limitations / open source detail	raw JSON, secrets, provider payloads	Internal label prevents customer-safe overclaiming
Auditor appendix rendered report	auditor-controlled, operator-MSP	evidence basis, section completeness, operation/source references, disclosure	structured appendix	raw payloads absent by default	Review evidence basis	legal attestation and compliance certification absent	Appendix prominence is profile-owned

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
Rendered report	Report / Artifact Viewer	Custom Surface / customer-safe report viewer	Print report, open review detail, download review pack	Authenticated signed report URL	N/A	Toolbar outside report canvas	N/A - no destructive actions	Review Pack list/detail	rendered report URL from ReviewPackService	workspace, managed environment, profile, audience	Governance review report	readiness, limitations, evidence basis, generated/source metadata, disclosure	UI-EX-001: Legitimate Custom Surface Exception - custom print/report canvas is bounded to the existing Specs 356/357 rendered-report route because native CRUD/detail primitives do not express the customer-facing report artifact layout

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
Rendered report	MSP operator, customer stakeholder, controlled auditor	Decide whether report can be shared and what top risks/actions matter	Report viewer	Is this report shareable, what does it say, and what should happen next?	report identity, profile/audience, readiness hero, KPI strip, executive summary, risks/decisions, evidence basis, disclosures	appendix, source metadata, technical posture	readiness, evidence completeness, customer-safe boundary, disclosure proof, generated/source metadata	read-only	Print report, open review detail, open review pack detail, download review pack	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no. Theme/layout output is derived from existing Review Pack, Environment Review, workspace, managed environment, report profile, and disclosure policy truth.
• New persisted entity/table/artifact?: no.
• New abstraction?: yes, a bounded derived report theme/layout contract. The concrete implementation may be a ReportThemeResolver or a controller-local view-model shape if that is narrower.
• New enum/state/reason family?: no new persisted state. Derived layout modes may map directly from existing ReportProfileRegistry profile keys.
• New cross-domain UI framework/taxonomy?: no. This is a local rendered-report productization contract.
• Current operator problem: MSP/customer reports need a stable, testable management layout and co-branding contract that cannot hide limitations or evidence state.
• Existing structure is insufficient because: The current controller/view can render base report output, but controller-local branding/layout decisions are hard to test as a reusable report contract and do not yet guarantee profile-aware hierarchy, KPI strip, or print/theme constraints for Spec 366.
• Narrowest correct implementation: Add one derived theme/layout contract for text-only theme slots and layout metadata, then render through the existing report route/view. Prefer a controller-local view-model if it is narrower; create a ReportThemeResolver only if it reduces duplication and improves proof without becoming a general theme framework.
• Ownership cost: One Unit test family for theme/layout derivation, Feature tests for rendered output, one bounded Browser smoke with screenshots, and localization maintenance.
• Alternative intentionally rejected: Persisted theme records, logo upload, theme editor, new report engine, or a generalized report layout framework.
• Release truth: Current-release productization on existing report artifacts.

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, Browser.
• Validation lane(s): fast-feedback for derived theme/layout tests, confidence for rendered-report route and safety tests, browser for report visual/print smoke.
• Why this classification and these lanes are sufficient: Unit tests prove deterministic theme/profile derivation; Feature tests prove authorization, route output, disclosure, print CSS, no ZIP mutation, no provider calls, and no raw/localization leakage; Browser smoke proves the real rendered report hierarchy, screenshots, and print-toolbar behavior.
• New or expanded test families:
  • Spec366ReportThemeContractTest
  • Spec366RenderedReportLayoutTest
  • Spec366ManagementReportLayoutSmokeTest
• Fixture / helper cost impact: Reuse existing Review Pack rendered-report fixtures from Specs 356/357 where possible. Add only explicit Spec366 helper states for profile variants and ready/limited/internal reports.
• Heavy-family visibility / justification: One explicit Browser smoke because this is a customer-facing visual/print report.
• Special surface test profile: shared-detail-family / report-viewer / customer-facing artifact surface.
• Standard-native relief or required special coverage: Special browser coverage required for report hierarchy, print CSS, screenshots, and no raw leakage.
• Reviewer handoff: Reviewers must verify that mandatory disclosures render in every profile, branding is text-only/repo-backed, customer-executive appendix stays secondary, and internal/limited reports cannot look customer-safe.
• Budget / baseline / trend impact: One bounded browser smoke file and screenshot artifacts. No broad browser family.
• Escalation needed: document-in-feature if optional logo/accent is not repo-backed and is deferred; follow-up-spec for theme CRUD, scheduled delivery, native PDF, customer portal, AI, or framework-specific reports.
• Active feature PR close-out entry: Guardrail + Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/Support/ReviewPacks/Spec366ReportThemeContractTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ReviewPack/Spec366RenderedReportLayoutTest.php --compact
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec366ManagementReportLayoutSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec356
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec357
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ReviewPack
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentReview
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Read a management-ready report first page (Priority: P1)

As an MSP operator or customer stakeholder, I can open the rendered report and understand within seconds who prepared it, who it is for, whether it is shareable, what the top status is, and what the primary next action or limitation is.

Why this priority: This is the core sellability gap. If the first page is not management-ready and honest, delivery, portal, AI, or framework reports would only amplify the problem.

Independent Test: Render a customer-safe report and a limited report through the existing signed URL and assert the cover/state/KPI/executive sections appear before appendix/detail content, with mandatory disclosures still visible.

Acceptance Scenarios:

1. Given a current customer-safe Review Pack with a customer_executive profile, When an entitled user opens the rendered report, Then the report shows prepared by, prepared for, generated by, profile/audience, readiness hero, KPI/decision strip, management summary, and disclosure footer.
2. Given a limited report, When an entitled user opens it, Then the state hero says it is limited or not externally shareable and does not show customer-safe success copy.
3. Given any report, When the report renders, Then no raw JSON, localization keys, secret-like fields, provider payloads, or internal-only rationale appear as default-visible customer content.

User Story 2 - Use profile-aware report hierarchy (Priority: P1)

As an operator, I can choose or open the effective report profile and get the correct layout hierarchy for customer executive, customer technical, internal MSP review, or auditor appendix use.

Why this priority: Spec 357 made profiles real; Spec 366 must make those profiles visibly meaningful in report layout rather than just metadata labels.

Independent Test: Render all implemented profiles and verify section order and appendix prominence match the profile contract.

Acceptance Scenarios:

1. Given customer_executive, When the report renders, Then management summary, KPI strip, risks/decisions, evidence coverage, next actions, and disclosure precede any minimal appendix.
2. Given customer_technical, When the report renders, Then evidence basis, permission posture, baseline drift, operations health, risks, and accepted risks are more visible while customer-safe restrictions still apply.
3. Given internal_msp_review, When the report renders, Then internal warnings and operator limitations are prominent.
4. Given auditor_appendix, When the report renders, Then evidence basis, section completeness, source metadata, and appendix content are more prominent without becoming a legal attestation.

User Story 3 - Show controlled co-branding without weakening truth (Priority: P2)

As an MSP, I can show a text-only co-branded report identity using existing workspace/environment truth, while TenantPilot source metadata and mandatory limitations remain visible.

Why this priority: MSPs need the artifact to feel deliverable, but branding must remain presentation, not product truth.

Independent Test: Render reports for workspace/environment fixtures with and without workspace/environment names and verify text co-branding falls back safely and never removes TenantPilot-generated metadata or readiness/disclosure blocks.

Acceptance Scenarios:

1. Given workspace and managed-environment names exist, When the report renders, Then it shows prepared by workspace/MSP, prepared for environment/customer, and generated by TenantPilot.
2. Given optional logo/accent fields are not repo-backed, When implementation is performed, Then no upload UI, image storage, theme table, or fake logo/accent appears.
3. Given a limited or internal report, When branding renders, Then branding does not hide warnings, evidence state, profile/audience, source metadata, or non-certification disclosure.

User Story 4 - Print and screenshot the report safely (Priority: P2)

As an operator, I can print or screenshot the report for review meetings without printing admin toolbar actions, app shell artifacts, or hidden unsafe content.

Why this priority: The report is intended for meetings and customer delivery, so print behavior and screenshot proof are part of the product contract.

Independent Test: Browser smoke renders profile variants, simulates print CSS where supported, verifies toolbar hidden from print canvas, asserts no JavaScript errors, and saves screenshots under the Spec 366 artifact folder.

Acceptance Scenarios:

1. Given the report toolbar is visible on screen, When print mode is active, Then toolbar and screen-only controls are hidden while the report canvas and disclosure footer remain visible.
2. Given a browser smoke run, When screenshots are captured, Then screenshots for customer executive ready/limited, internal MSP, customer technical, auditor appendix, and print view are stored under the Spec 366 artifacts path.
3. Given a small/mobile-ish viewport, When the report renders, Then text remains readable and sections stack without overlapping.

Functional Requirements

• FR-366-001: The rendered report MUST present a management-ready first screen with report identity, readiness/state hero, KPI/decision strip, executive summary, evidence basis, and next action or limitation.
• FR-366-002: Report toolbar actions MUST remain outside the report canvas and MUST be hidden in print.
• FR-366-003: The state hero MUST distinguish customer-safe, limited, internal-only, output-not-ready, and external-sharing-blocked states without false safe language.
• FR-366-004: The KPI/decision strip MUST use only repo-backed values from existing Review Pack/review/evidence/report payloads; unsupported metrics MUST be omitted or shown as not measured/not available.
• FR-366-005: The executive summary MUST be management-friendly and MUST NOT expose raw state keys, implementation field names, provider payload terms, or localization keys as dominant copy.
• FR-366-006: The layout MUST adapt to the effective ReportProfileRegistry profile for customer_executive, customer_technical, internal_msp_review, and auditor_appendix.
• FR-366-007: The report MUST render text co-branding slots: prepared by, prepared for, generated by, generated at, report profile, and report audience.
• FR-366-008: Optional logo/accent/footer organization styling MUST be used only if repo-backed safe fields already exist; otherwise it MUST be deferred without adding persistence or upload UI.
• FR-366-009: Mandatory disclosures from ReportDisclosurePolicy MUST remain visible in every profile and print output.
• FR-366-010: Customer executive reports MUST keep appendix and technical detail secondary unless disclosure policy requires prominent limitations.
• FR-366-011: Internal MSP and auditor appendix reports MAY expose more structured technical context, but raw JSON, secrets, fingerprints, provider payloads, and stack traces MUST remain hidden by default.
• FR-366-012: Existing Review Pack ZIP/download behavior MUST remain unchanged.
• FR-366-013: The rendered report MUST remain read-only and MUST NOT create, mutate, queue, deliver, approve, or send report artifacts.
• FR-366-014: The rendered report route MUST keep existing authorization, current-export guard, expiry guard, and workspace/environment entitlement behavior.
• FR-366-015: Implementation MUST not perform live provider/Graph calls while rendering theme, layout, or report content.
• FR-366-016: Dominant report copy MUST be localized in EN and DE where new strings are introduced.

Non-Functional Requirements

• NFR-366-001: Enterprise visual quality - report output MUST pass the Spec 366 screenshot set without text overlap, preserve first-screen scanability for audience/readiness/evidence basis, remain print-legible, and either update ui-099-rendered-review-report.md or record a no-update rationale.
• NFR-366-002: Deterministic rendering - same report/profile/theme input produces stable structure.
• NFR-366-003: Accessibility - semantic headings, readable labels, keyboard-accessible toolbar controls, and no text overlap.
• NFR-366-004: Print-friendly - toolbar hidden, disclosure visible, page breaks avoid broken cards/sections where practical.
• NFR-366-005: Conservative customer-safe behavior - uncertain readiness must render limitations rather than safe/shareable claims.
• NFR-366-006: No runtime expansion - no migrations, packages, env vars, queues, scheduler, storage topology, or panel provider changes are expected.

Data / Truth Source Requirements

• Existing Review Pack summary payloads, Environment Review state, Evidence Snapshot state, ReportProfileRegistry, and ReportDisclosurePolicy remain the report truth inputs.
• Branding is presentation only and derived from existing workspace/managed-environment values.
• TenantPilot source metadata, generated timestamp, profile/audience, readiness/limitation state, and non-certification disclosure must remain visible.
• Internal rationale and raw payloads must not be promoted into customer-safe report truth.

Edge Cases

• Missing workspace name falls back to TenantPilot or a safe prepared-by label.
• Missing managed-environment/customer name falls back to the existing environment/report label without exposing internal IDs as primary copy.
• Unknown or placeholder report profile continues to fail closed through ReportProfileRegistry fallback behavior.
• Evidence missing/partial/stale states make limitations visible near the top.
• Customer-facing profiles requested for internal/PII output remain limited or blocked and cannot appear customer-safe.
• Metrics with no repo-backed source are omitted or shown as not measured, never faked as zero.
• Print mode hides toolbar but keeps disclosure and source metadata visible.

Acceptance Criteria

• AC-366-001: Customer executive report first screen shows management-ready identity, state hero, KPI strip, executive summary, evidence basis, and disclosure footer.
• AC-366-002: Profile variants produce visibly different hierarchy while preserving mandatory disclosure output.
• AC-366-003: Prepared by / prepared for / generated by / generated at are visible and use repo-backed values or safe fallbacks.
• AC-366-004: Limited/internal reports never render as customer-safe or externally approved.
• AC-366-005: Toolbar is outside the report canvas and hidden by print CSS.
• AC-366-006: Review Pack ZIP/download contract remains unchanged.
• AC-366-007: No new persistence, upload UI, profile CRUD, scheduled delivery, customer portal, AI, native PDF package, or compliance framework report is introduced.
• AC-366-008: Focused Unit, Feature, Browser, Spec356, Spec357, ReviewPack, EnvironmentReview, Pint, and diff validation commands are planned and pass during implementation close-out.
• AC-366-009: Browser screenshots are captured or an explicit repo-based reason is documented for any missing screenshot state.

Success Criteria

• SC-366-001: A reviewer can identify report audience, shareability/readiness, top management summary, and evidence basis within the first visible report screen.
• SC-366-002: All implemented profiles render without JavaScript/console errors in the bounded browser smoke.
• SC-366-003: Tests prove no visible localization keys, raw JSON, stack traces, secrets, fingerprints, provider payloads, or false certification/shareability copy appear in default report output.
• SC-366-004: Required screenshots show customer executive ready, customer executive limited, internal MSP, customer technical, auditor appendix, print view, and toolbar-hidden print behavior.

Out of Scope

• Native server-side PDF package or PDF generation stack.
• Report profile CRUD or persisted report themes.
• Logo upload, image storage, theme editor, or white-label portal.
• Scheduled delivery, email/Teams sending, approval workflow, send ledger, or public links.
• AI-generated narratives or HITL review.
• NIS2, BSI, CIS, or other framework-specific report semantics.
• Customer portal report consumption.
• Review Pack ZIP contract changes.
• New OperationRun semantics.

Follow-up Spec Candidates

• Spec 367 - Scheduled Report Delivery Foundation v1.
• Spec 368 - Compliance Report Profile Foundation v1.
• Spec 369 - NIS2 / BSI Readiness Report v1.
• Spec 370 - CIS Baseline Report v1.
• Spec 371 - Customer Portal Report Consumption Boundary.
• Spec 372 - Private AI/HITL Report Review Preparation.

Assumptions

• Specs 356 and 357 are committed and stable on the current branch.
• The existing authenticated rendered report route, profile registry, disclosure policy, and Review Pack authorization remain the baseline.
• Workspace and managed-environment names are sufficient for text co-branding in v1.
• Optional logo/accent fields are not assumed to exist; they remain deferred unless implementation verifies safe repo-backed fields.
• The feature can be completed without migrations, new packages, env vars, queues, scheduler changes, storage changes, or Filament asset registration.

Open Questions

None blocking. Optional logo/accent support is intentionally treated as repo-backed-only and otherwise deferred.