TenantAtlas/specs/325-screenshot-anchored-strategic-target-images/plan.md

# Plan: Spec 325 - Screenshot-Anchored Strategic Target Images & Experience Briefs

**Branch**: `325-screenshot-anchored-strategic-target-images` | **Date**: 2026-05-17 | **Spec**: `specs/325-screenshot-anchored-strategic-target-images/spec.md`

## Summary

Spec 325 creates screenshot-anchored target experience briefs and high-quality target image artifacts for a proportional 6-10 surface shortlist from Spec 323 strategic surfaces. The work is docs/image-only and updates UI audit coverage artifacts; it does not implement runtime UI or product behavior.

## Premium Visual Reference Plan Addendum

The user accepted four uploaded premium Tenantial images as the visual reference baseline. Implementation keeps the docs/image-only posture and adds those images under `docs/ui-ux-enterprise-audit/target-images/reference/spec-325-premium-reference/`.

The target PNG regeneration uses those references as visual calibration while preserving the existing Spec 325 content contract:

- dark premium shell is primary
- sidebar/topbar/context bar are part of the target direction
- dense enterprise panels and table/detail workbenches are preferred
- evidence, restore, governance, and operations proof paths are visible
- dangerous restore execution needs stronger safety treatment than the reference image's normal green action
- light variants remain support artifacts because Filament includes light mode by default
- concrete metrics and actions remain conceptual unless repo-verified

## Technical Context

- **Language/Version**: N/A - documentation and image artifacts only.
- **Primary Dependencies**: Spec 323 audit artifacts, Spec 324 guardrails, existing screenshots/page reports, `docs/brand/tenantial-brand-context.md`.
- **Storage**: Repository Markdown/image files only; no database storage.
- **Testing**: Static validation only.
- **Validation Lanes**: docs/static guard validation.
- **Target Platform**: Repository documentation review.
- **Project Type**: Laravel/Filament monorepo, but no application runtime code changes.
- **Performance Goals**: N/A.
- **Constraints**: No product runtime file changes; selected surfaces <= 10; target images must be screenshot-anchored and sidecar-documented.
- **Scale/Scope**: One bounded target-image preparation wave for P0/P1 strategic surfaces.

## Inputs

- `docs/ui-ux-enterprise-audit/strategic-surfaces.md`
- `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`
- `docs/ui-ux-enterprise-audit/page-reports/`
- `docs/ui-ux-enterprise-audit/screenshots/desktop/`
- `docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md`
- `docs/ui-ux-enterprise-audit/README.md`
- `docs/brand/tenantial-brand-context.md`
- `specs/323-tenantial-enterprise-ui-audit-foundation/`
- `specs/324-ui-productization-coverage-guardrails/`

## UI / Surface Guardrail Plan

- **Guardrail scope**: no operator-facing runtime surface change.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: N/A - source surfaces are referenced only as audit/documentation inputs.
- **No-impact class**: docs-only / image-artifact-only.
- **Native vs custom classification summary**: N/A.
- **Shared-family relevance**: documentation names later pattern needs; no runtime shared family changes.
- **State layers in scope**: none at runtime.
- **Audience modes in scope**: target guidance may cover customer/read-only, operator-MSP, auditor, support, and platform personas; no runtime modes changed.
- **Decision/diagnostic/raw hierarchy plan**: every target brief must describe decision-first defaults, diagnostics-second, support/raw-third where applicable.
- **Raw/support gating plan**: documented in briefs only.
- **One-primary-action / duplicate-truth control**: documented in briefs only.
- **Handling modes by drift class or surface**: report-only for target-image artifacts; future implementation specs must decide hard-stop/review/exception modes.
- **Repository-signal treatment**: report-only.
- **Special surface test profiles**: N/A.
- **Required tests or manual smoke**: static guard validation; optional image dimension checks.
- **Exception path and spread control**: none.
- **Active feature PR close-out entry**: N/A - docs/image-only.
- **UI/Productization coverage decision**: No UI surface impact; coverage registry artifacts updated because Spec 325 itself is a UI audit target-artifact update.
- **Coverage artifacts to update**: `docs/ui-ux-enterprise-audit/README.md`, `strategic-surfaces.md`, `grouped-follow-up-candidates.md`, `design-coverage-matrix.md` if target-image coverage is tracked, target brief/image/follow-up docs.
- **No-impact rationale**: Target artifacts guide future UI implementation but do not alter reachable UI.
- **Navigation / Filament provider-panel handling**: no runtime provider/panel/nav handling.
- **Screenshot or page-report need**: yes; every selected surface needs an existing screenshot/page report anchor or must be rejected/deferred.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, docs-only.
- **Systems touched**: UI audit documentation registry.
- **Shared abstractions reused**: Spec 323 audit artifacts and Spec 324 guardrail expectations.
- **New abstraction introduced? why?**: none at runtime; target-image docs identify future pattern needs only.
- **Why existing abstraction was sufficient or insufficient**: The audit registry is sufficient for target artifact tracking; runtime pattern code is deferred to Spec 326.
- **Bounded deviation / spread control**: Target images are explicitly not implementation truth and cannot be implemented blindly.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no runtime impact.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: N/A.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no runtime boundary touched.
- **Provider-owned seams**: N/A.
- **Platform-core seams**: N/A.
- **Neutral platform terms / contracts preserved**: briefs must preserve workspace, environment, provider, operation, evidence, and governance language.
- **Retained provider-specific semantics and why**: allowed only when repo/page report proves surface purpose is provider-specific.
- **Bounded extraction or follow-up path**: implementation lanes may later verify provider/onboarding pattern needs.

## Constitution Check

- Inventory-first: PASS - no inventory/snapshot runtime truth changes.
- Read/write separation: PASS - no writes to product runtime; target restore/dangerous-action briefs must document preview/confirmation/audit needs for later work.
- Graph contract path: PASS - no Graph calls.
- Deterministic capabilities: PASS - no capability code changes.
- RBAC-UX: PASS - no authorization changes; briefs must document customer-safe and capability assumptions.
- Workspace isolation: PASS - no runtime access changes; briefs must document workspace/environment context.
- Tenant isolation: PASS - no tenant queries or data changes.
- Run observability: PASS - no OperationRun changes.
- Automation: PASS - no queued/scheduled work.
- Data minimization: PASS - target briefs must avoid customer-visible diagnostics and fake claims.
- Test governance: PASS - docs/image-only static validation.
- Proportionality: PASS - 6-10 selected surfaces, not all 44.
- No premature abstraction: PASS - no runtime abstraction; pattern library deferred to Spec 326.
- Persisted truth: PASS - no database persistence; images are documentation artifacts.
- Behavioral state: PASS - no new runtime states/statuses.
- UI semantics: PASS - no runtime UI semantic framework.
- Shared pattern first: PASS - future pattern needs are grouped, not implemented ad hoc.
- Provider boundary: PASS - no provider core change.
- V1 explicitness / few layers: PASS - direct Markdown/image outputs.
- Spec discipline / bloat check: PASS - target-image wave is coherent and bounded.
- Filament-native UI: PASS - no Filament UI changes.
- UI/Productization coverage: PASS - active spec marks no runtime UI impact and updates audit artifacts.

## Project Structure

```text
specs/325-screenshot-anchored-strategic-target-images/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md

docs/ui-ux-enterprise-audit/
├── target-experience-briefs/
├── target-images/
│   ├── source/
│   ├── problem-annotations/
│   ├── target/
│   └── rejected/
└── follow-up-specs/
```

No files under `apps/platform/` should be changed by this spec.

## Implementation Phases

1. Read Spec 323 audit artifacts.
2. Confirm Spec 324 guardrail expectations.
3. Select 6-10 P0/P1 strategic surfaces.
4. Create strategic target image shortlist.
5. Handle rejected mockup remnants if present.
6. Create target-experience-briefs structure.
7. Create target-images structure.
8. Create target briefs anchored to screenshots/page reports.
9. Generate/create target images using screenshot-anchored prompts.
10. Create target image sidecars.
11. Document deferred strategic surfaces.
12. Update strategic-surfaces and coverage matrix.
13. Create follow-up implementation candidates.
14. Update README links.
15. Run validation.

## Risk Controls

- Do not create unanchored mockups.
- Do not create generic SaaS dashboards.
- Do not mock all 44 strategic rows.
- Do not imply runtime implementation.
- Mark repo-truth level for conceptual elements.
- Keep customer-safe surfaces free of raw diagnostics.
- Do not create fake feature claims.
- Do not change product runtime files.
- Regenerate or reject target images that fail visual review criteria.
- Document any image generation/dimension validation that is not run.

## Test Governance Check

- **Test purpose / classification by changed surface**: N/A - docs/image target artifacts only.
- **Affected validation lanes**: static documentation guard.
- **Why this lane mix is the narrowest sufficient proof**: The work changes Markdown/image files and audit artifacts only.
- **Narrowest proving commands**: `bash scripts/check-ui-productization-coverage HEAD`; `git diff --check`.
- **Fixture / helper / factory / seed / context cost risks**: none.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: N/A.
- **Closing validation and reviewer handoff**: verify no product runtime files changed and all target images have source/brief/sidecar coverage.
- **Budget / baseline / trend follow-up**: none.
- **Review-stop questions**: target-image grounding, false product truth, selected-surface proportionality, customer-safe disclosure, dangerous-action guardrails.
- **Escalation path**: none.
- **Active feature PR close-out entry**: N/A.
- **Why no dedicated follow-up spec is needed**: Spec 325 is the dedicated target-image wave; Spec 326 is the recommended later pattern-library follow-up.

## Validation

Required:

```bash
bash scripts/check-ui-productization-coverage HEAD
git diff --check
```

Optional:

```bash
bash -n scripts/check-ui-productization-coverage
find docs/ui-ux-enterprise-audit/target-images -type f
find docs/ui-ux-enterprise-audit/target-experience-briefs -type f
```

If image dimension validation is available, run an equivalent check and document dimensions. Runtime tests are not required because this is docs/image-only. Full Pest suite must not be run unless unrelated runtime files changed. Pint is not required unless PHP files changed.

## Readiness Criteria

Spec 325 is ready for implementation when `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` exist; the no-runtime posture is explicit; target brief/image/sidecar requirements are complete; selected-surface rules are bounded; coverage artifact updates are named; validation commands are listed; and no open questions block implementation.