TenantAtlas/specs/286-ui-copy-ia-localization-neutralization/tasks.md

---
description: "Task list for UI Copy, IA & Localization Neutralization"
---

# Tasks: UI Copy, IA & Localization Neutralization

**Input**: Design documents from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/`  
**Prerequisites**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/plan.md` (required), `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/spec.md` (required), `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/checklists/requirements.md` (required), `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/research.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/data-model.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/contracts/ui-copy-ia-localization-neutralization.logical.openapi.yaml`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/quickstart.md`

**Review Artifact**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/checklists/requirements.md` is the outcome-of-record for the review outcome class, workflow outcome, and test-governance outcome. If implementation widens into route/slug/class renaming, auth-provider wording changes, RBAC vocabulary changes, or broader provider-surface cleanup, update that artifact before continuing.

**Tests**: Required (Pest) for runtime behavior changes. Keep proof in the existing `confidence` lane plus one bounded `browser` smoke only because this slice changes rendered operator-facing copy, shared shell labels, chooser semantics, and helper-text disclosure on existing admin surfaces.  
**Operations**: No new `OperationRun`, queue, remote call, or background workflow is introduced.  
**RBAC**: Workspace and managed-environment entitlement behavior remains unchanged. Reuse existing policy and capability seams; do not add raw capability strings or role-name checks.  
**Shared Pattern Reuse**: Reuse `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/localization.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/localization.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/baseline-compare.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/baseline-compare.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/ChooseTenant.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Workspaces/ManagedTenantsLanding.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantDashboard.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/OperateHub/OperateHubShell.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Navigation/CanonicalNavigationContext.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/PolicyResource.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/PolicyResource/Pages/ViewPolicy.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/PolicyResource/RelationManagers/VersionsRelationManager.php`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php`. Do not add a new localization framework, alias-only translation layer, route/slug rename, or provider-cleanup sweep.  
**Filament / Panel Guardrails**: Filament remains v5 on Livewire v4. Provider registration remains unchanged in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/bootstrap/providers.php`. No new globally-searchable resource, no new panel, and no asset-strategy change are allowed in this slice.  
**Organization**: Tasks are grouped by user story so chooser/registry copy, dashboard/shell copy, and provider-neutral helper copy remain independently testable after the shared glossary is settled.  
**Review Outcome**: `acceptable-special-case`  
**Workflow Outcome**: `keep`  
**Test-governance Outcome**: `keep`

## Test Governance Checklist

- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
- [x] New or changed tests stay in the smallest honest family, and any browser addition remains explicit and bounded.
- [x] Shared helpers, widgets, translation catalogs, and environment context defaults stay cheap by default.
- [x] Planned validation commands cover the change without pulling in unrelated lane cost.
- [x] Surface test profile stays explicit: `standard-native-filament` for page-title and localization output, `global-context-shell` for shell labels and chooser flow.
- [x] Dominant CTA, diagnostics-second ordering, secondary provider detail, and no duplicate visible scope summary are verified explicitly on the chooser, landing, dashboard, shell, and pinned US3 helper surfaces.
- [x] Any material budget, baseline, trend, or escalation note is recorded in the active feature package or PR close-out.

## Phase 1: Setup (Shared Context)

**Purpose**: Lock the bounded glossary slice, explicit non-goals, and proving lanes before runtime edits begin.

- [x] T001 Review the bounded slice, explicit non-goals, completed-spec guardrails, and repo-fit outcome in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/spec.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/plan.md`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/checklists/requirements.md`
- [x] T002 [P] Review the glossary decisions, key-family replacement rules, and provider-detail boundary in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/research.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/data-model.md`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/contracts/ui-copy-ia-localization-neutralization.logical.openapi.yaml`
- [x] T003 [P] Confirm the focused Sail/Pest validation commands and bounded browser smoke in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/quickstart.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Localization/`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Filament/`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Browser/`

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Settle the shared environment-first glossary and bounded provider-detail rule before user-story implementation starts.

**Critical**: No user-story work should begin until this phase is complete.

- [x] T004 [P] Inventory the in-scope tenant-first and default-visible provider-first strings across `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/localization.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/localization.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/baseline-compare.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/baseline-compare.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/ChooseTenant.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Workspaces/ManagedTenantsLanding.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantDashboard.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/OperateHub/OperateHubShell.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Navigation/CanonicalNavigationContext.php`, and the in-scope widget views so later story work reuses one glossary only
- [x] T005 [P] Add or extend bounded guard coverage in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/EnvironmentCopyNeutralizationGuardTest.php` for in-scope default-visible strings such as `tenant scope`, `select tenant`, `all tenants`, `managed tenants`, and `restore to Microsoft Intune`, while explicitly excluding auth-provider copy like `Sign in with Microsoft`
- [x] T006 Canonically replace the in-scope translation-key family and only the local display labels/test IDs owned by the enumerated surfaces with environment-first names in the smallest shared seams first, without adding alias keys or broad repo-wide grep bans

**Checkpoint**: The glossary inventory, guard boundaries, and canonical replacement rules are fixed before surface-specific story work begins.

---

## Phase 3: User Story 1 - Choose an environment with environment-first language (Priority: P1)

**Goal**: Let workspace operators choose and open environments from chooser/registry surfaces whose copy matches the current workspace-first route model.

**Independent Test**: Open the chooser and managed-environment landing pages and verify the titles, empty states, CTAs, and supporting text use environment-first wording in English and German while the routes stay unchanged.

### Tests for User Story 1

- [x] T007 [P] [US1] Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Localization/EnvironmentContextTerminologyTest.php` for chooser and landing titles, empty states, search placeholders, and selection actions in English and German

### Implementation for User Story 1

- [x] T008 [US1] Replace the in-scope chooser and landing glossary keys in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/localization.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/localization.php` so `tenant_*` admin-shell terms become `environment_*` equivalents
- [x] T009 [US1] Apply the new glossary to `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/ChooseTenant.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/choose-tenant.blade.php` so the chooser title, CTA, empty state, and search placeholder become environment-first without changing the route slug
- [x] T010 [US1] Apply the same glossary to `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/Workspaces/ManagedTenantsLanding.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/workspaces/managed-tenants-landing.blade.php` so the registry title and opening affordances say `Managed environments` instead of `Managed tenants`

**Checkpoint**: User Story 1 is independently functional when chooser and registry surfaces no longer teach tenant-first admin nouns.

---

## Phase 4: User Story 2 - Stay oriented inside environment-scoped admin surfaces (Priority: P1)

**Goal**: Let operators confirm the active environment through consistent dashboard, shell, and navigation labels once they enter an environment-scoped page.

**Independent Test**: Open an environment dashboard and one shared operate-hub page, then verify the dashboard heading, context chips, shell scope label, and return affordance all use the same environment-first glossary.

### Tests for User Story 2

- [x] T011 [P] [US2] Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Filament/EnvironmentContextSurfaceCopyTest.php` for dashboard heading keys, shell scope labels, registry return links, and workspace widget environment labels

### Implementation for User Story 2

- [x] T012 [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Pages/TenantDashboard.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/widgets/dashboard/tenant-dashboard-context-chips.blade.php` so headings and chips speak about the selected environment
- [x] T013 [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/OperateHub/OperateHubShell.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Support/Navigation/CanonicalNavigationContext.php` so shell scope labels and registry back links become environment-first while route targets stay unchanged
- [x] T014 [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/widgets/workspace/workspace-needs-attention.blade.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/widgets/workspace/workspace-recent-operations.blade.php` so directly rendered environment labels become environment-first without widening shared workspace overview payload contracts

**Checkpoint**: User Story 2 is independently functional when the shell and dashboard no longer make operators reinterpret environment routes as tenant routes.

---

## Phase 5: User Story 3 - Read provider actions with neutral default copy and explicit provider detail (Priority: P2)

**Goal**: Let operators read a neutral environment-first default action/helper path on the bounded restore/capture/baseline-compare surfaces while still preserving provider-specific secondary detail.

**Independent Test**: Open one in-scope restore/capture or baseline-compare entry surface and verify the default-visible headline/helper text is neutralized while provider-specific secondary detail remains explicit and auth-provider wording stays unchanged.

### Tests for User Story 3

- [x] T015 [P] [US3] Extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Filament/Localization/PolicyInventoryLocalizationTest.php` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Feature/Guards/EnvironmentCopyNeutralizationGuardTest.php` for the exact `PolicyResource`, `ViewPolicy`, `VersionsRelationManager`, and `baseline-compare-landing` helper surfaces, plus the explicit exclusion of auth-provider labels
- [x] T016 [P] [US3] Add or extend `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/tests/Browser/Spec286EnvironmentCopyNeutralizationSmokeTest.php` for the chooser-to-environment path plus the pinned policy-detail/helper and baseline-compare summary surfaces

### Implementation for User Story 3

- [x] T017 [US3] Update the bounded provider-neutral helper strings in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/localization.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/localization.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/en/baseline-compare.php`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/lang/de/baseline-compare.php` so `PolicyResource`, `ViewPolicy`, `VersionsRelationManager`, and `baseline-compare-landing` stop using provider-first nouns as their default-visible headings or helper text where a platform noun is sufficient
- [x] T018 [US3] Reuse `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/PolicyResource.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/PolicyResource/Pages/ViewPolicy.php`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/app/Filament/Resources/PolicyResource/RelationManagers/VersionsRelationManager.php`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php` so provider detail stays secondary and no auth-provider wording is changed

**Checkpoint**: User Story 3 is independently functional when provider-neutral helper text no longer dominates the first operator decision on the bounded action surfaces.

---

## Phase 6: Polish & Cross-Cutting Validation

**Purpose**: Run the canonical proof commands, format touched files, and keep any discovered spillover explicit instead of absorbing it into this slice.

- [x] T019 Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Localization/EnvironmentContextTerminologyTest.php tests/Feature/Filament/EnvironmentContextSurfaceCopyTest.php tests/Feature/Filament/Localization/PolicyInventoryLocalizationTest.php tests/Feature/Guards/EnvironmentCopyNeutralizationGuardTest.php` exactly as recorded in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/plan.md` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/quickstart.md`
- [x] T020 Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec286EnvironmentCopyNeutralizationSmokeTest.php` exactly as recorded in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/plan.md` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/286-ui-copy-ia-localization-neutralization/quickstart.md`
- [x] T021 Run `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- [x] T022 Review the touched localization files, page classes, shell helpers, widget views, pinned policy/baseline-compare helper surfaces, and the review artifact to confirm no route/slug/class/capability changed, chooser and landing still keep one dominant CTA, dashboard/shell remain orientation-first, provider detail stays secondary, no duplicate visible scope summary was introduced, no auth-provider wording was neutralized, and any broader provider-surface cleanup was recorded as follow-up instead of absorbed here

---

## Dependencies & Execution Order

### Phase Dependencies

- **Phase 1 (Setup)**: no dependencies; start immediately.
- **Phase 2 (Foundational)**: depends on Phase 1 and blocks all user stories until glossary and guard boundaries are settled.
- **Phase 3 (US1)**: depends on Phase 2 and delivers the first environment-first operator surface increment.
- **Phase 4 (US2)**: depends on Phase 2 and should follow US1 because shell and dashboard copy should consume the final chooser vocabulary.
- **Phase 5 (US3)**: depends on Phase 2 and is safest after US1 and US2 because provider-neutral helper copy should align with the final environment-first glossary.
- **Phase 6 (Polish)**: depends on all implemented stories.

### User Story Dependencies

- **US1 (P1)**: first independently testable increment once the glossary and guard boundaries exist.
- **US2 (P1)**: independently testable after Phase 2, but should merge after US1 because shell and dashboard labels must not diverge from chooser vocabulary.
- **US3 (P2)**: independently testable after Phase 2, but should merge after US1 and US2 because helper text should inherit the final platform nouns.

### Within Each User Story

- Write the listed Pest coverage first and make it fail for the intended gap before runtime implementation.
- Reuse the existing localization and shell seams before adding any new helper.
- Re-run the narrowest relevant validation command after each story checkpoint before moving to the next story.

---

## Parallel Execution Examples

### Phase 1

- T002 and T003 can run in parallel after T001 confirms the bounded slice.

### Phase 2

- T004 and T005 can run in parallel while T006 finalizes the canonical replacement rule.

### User Story 1

- T007 can run alongside any last Phase 2 cleanup.
- T008 can proceed before T009 and T010 finish wiring the glossary into page classes and views.

### User Story 2

- T011 can run alongside the first US1 validation.
- T012 and T014 can proceed in parallel before T013 finalizes the shared shell labels.

### User Story 3

- T015 and T016 can run in parallel because they cover feature and browser proof separately.
- T017 can proceed before T018 finalizes the bounded helper-text consumers.

---

## Implementation Strategy

### Suggested MVP Scope

- MVP = **Phase 2 + US1 + US2**. The product becomes semantically coherent once the chooser, registry, dashboard, and shell all teach the same environment-first admin vocabulary.

### Incremental Delivery

1. Complete Phase 1 and Phase 2.
2. Deliver US1 and validate the chooser/registry surfaces.
3. Deliver US2 and validate the dashboard/shell surfaces.
4. Deliver US3 and validate the bounded provider-neutral helper text plus browser smoke.
5. Finish with Phase 6 validation, formatting, and explicit spillover review.

### Team Strategy

1. Settle the glossary and guard boundaries before changing multiple shared surfaces.
2. Parallelize test authoring inside each story before converging on the shared localization files.
3. Serialize merges around `localization.php`, `TenantDashboard.php`, and `OperateHubShell.php` because they are the most likely merge hotspots for this slice.

---

## Explicit Follow-Ups / Out of Scope

- broader route/slug/class renaming remains a separate follow-up
- broader provider-owned surface cleanup remains a separate follow-up
- auth-provider wording changes remain out of scope
- website localization and customer-review localization remain out of scope for this package
- no-legacy enforcement and broader guard-pack work remain in Spec `287`

## Close-out Notes

- 2026-05-10: Manual integrated-browser investigation found a live runtime issue on the `Capture snapshot` action where the Livewire request fires but the Filament action modal host remains empty. That behavior is treated as discovered out-of-scope runtime debt for Spec `286` and is intentionally not part of this package's copy / IA / localization acceptance scope.
- Spec `286` closes on the bounded environment-first copy, IA, and localization neutralization surfaces plus the targeted Pest validations defined above.