ahmido aeef285d1d feat: implement spec 286 UI copy, IA & localization neutralization (#345 )

## Summary

Implements feature branch `286-ui-copy-ia-localization-neutralization`.

This change set:
- aligns chooser, managed-environment landing, dashboard, shell, and workspace context copy to environment-first terminology
- neutralizes the bounded policy and baseline helper copy called out by Spec 286
- adds focused feature, guard, and browser coverage plus the complete Spec 286 artifact set
- records the discovered `Capture snapshot` modal issue as out-of-scope runtime debt in the Spec 286 close-out notes

## Validation

- `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`
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec286EnvironmentCopyNeutralizationSmokeTest.php`
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`

## Notes

- Target branch: `platform-dev`
- Filament remains on v5 with Livewire v4.
- Provider registration remains unchanged in `apps/platform/bootstrap/providers.php`.
- No new destructive actions, asset strategy changes, or global-search posture changes are introduced in this slice.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #345

2026-05-09 23:29:11 +00:00

3.6 KiB

Raw Blame History

Research: UI Copy, IA & Localization Neutralization

Decision 1: `Environment` is the default operator noun

Use Environment on chooser, shell, dashboard, and default action copy.
Use Managed environment only where a registry or heading must distinguish the object from the workspace.
Do not keep tenant as an operator-visible default noun on the in-scope post-workspace-first admin surfaces.

Decision 2: Provider-specific names remain secondary unless the provider is the subject

Keep auth-provider wording such as Sign in with Microsoft unchanged.
Keep provider-specific detail such as Graph-specific helper text or explicit provider names only as secondary explanatory content.
Neutralize default-visible action/helper copy on the bounded restore/capture/baseline-compare entry surfaces where the platform noun is sufficient for the first operator decision.

Decision 3: `286` is copy and IA only, not a symbol-renaming slice

Do not rename routes, slugs, class names, model names, capability names, or database fields.
Internal tenant-shaped symbols may remain temporarily while operator-facing copy becomes environment-first.
Any need for symbol renaming belongs to a later guardrail or cleanup spec, not this package.

Decision 4: Canonical replacement beats aliasing for the in-scope key family

Replace in-scope translation keys and directly surfaced view-model labels that still encode tenant-first operator nouns.
Do not preserve alias keys for convenience where the key name itself remains a shared semantic contract.
Keep the replacement bounded to the confirmed admin surfaces in this package.

Decision 5: Stay out of adjacent specs

Do not absorb RBAC wording from Spec 285.
Do not absorb provider-capability or provider-identity work from Specs 281 and 283.
Do not absorb no-legacy enforcement from Spec 287.
Do not expand into website or customer-review localization already covered elsewhere.

Rejected Alternatives

Rejected: value-only translation updates without key cleanup

That would keep tenant-first semantics in shared key families and test contracts, which is the same drift in a different place.

Rejected: route or slug renaming in the same slice

That widens the package from copy/IA into deeper runtime cutover work and should be handled separately if still needed.

Rejected: repo-wide provider-neutral string sweep

The slot is explicitly bounded. Repo-wide cleanup would collapse multiple provider-owned and customer-facing follow-up lanes into one package.

Evidence Anchors

apps/platform/lang/en/localization.php still exposes tenant_scope, select_tenant, selected_tenant, no_tenant_selected, no_active_tenants, view_managed_tenants, workspace_wide_available, and tenant_title.
apps/platform/app/Filament/Pages/ChooseTenant.php still sets Choose tenant as the page title.
apps/platform/app/Filament/Pages/Workspaces/ManagedTenantsLanding.php still sets Managed tenants as the page title.
apps/platform/app/Support/OperateHub/OperateHubShell.php still exposes ManagedEnvironment scope and All tenants as shell labels.
apps/platform/app/Support/Navigation/CanonicalNavigationContext.php still exposes Back to tenant registry.
apps/platform/app/Filament/Pages/TenantDashboard.php still consumes localization.dashboard.tenant_title.

Implementation Boundary Summary

The package is implementation-ready for bounded operator-copy convergence.
It is not a prerequisite-unblocking package for routes, RBAC, or provider capabilities.
If implementation uncovers a genuine need for route or symbol renaming, stop and split that work into a follow-up spec.

3.6 KiB Raw Blame History