# Quickstart: Workspace-first RBAC & Environment Access Scoping

## Purpose

Use this guide to review or implement Feature `285` once the prerequisite specs are present on the working branch.

## Preconditions

- Spec `280` is present on the branch and provides the workspace-first route or shell baseline.
- Spec `281` is present on the branch and provides provider-neutral target-scope baselines.
- Spec `283` is present on the branch and provides downstream provider capability context.
- The branch does not attempt to absorb Spec `284`, `286`, or `287` work.
- The implementation keeps Filament v5 on Livewire v4 and provider registration in `apps/platform/bootstrap/providers.php`.

If any of the first three prerequisites is missing, stop and land those dependencies first.

## Read order

1. `spec.md`
2. `plan.md`
3. `research.md`
4. `data-model.md`
5. `contracts/workspace-rbac-environment-access.logical.openapi.yaml`
6. `tasks.md`
7. `checklists/requirements.md`

## Implementation intent

- keep `WorkspaceMembership` as the sole role-bearing truth
- reinterpret or replace the current managed-environment membership semantics as a narrow access-scope overlay only
- retarget `CapabilityResolver`, `User`, `WorkspaceContext`, and the key environment-owned policies to one workspace-first access contract
- split operator-facing membership surfaces into workspace role management and managed-environment access-scope management
- preserve 404 for non-members or out-of-scope actors and 403 for in-scope members missing capability
- keep touched searchable-resource results and denied-access diagnostics aligned with the same shared access contract

## Review scenarios

### Scenario 1: Workspace role alone is sufficient when no explicit environment scope exists

- create a workspace with at least two managed environments
- add a user through workspace membership only
- confirm the user can open the allowed environment-owned resources that match their workspace role

### Scenario 2: Explicit environment scope narrows visibility without changing role

- keep the same workspace role
- add explicit access scope to only one managed environment
- confirm the allowed environment remains visible and a sibling environment becomes not found

### Scenario 3: Membership management surfaces no longer expose duplicate roles

- open the workspace membership surface and confirm role editing happens there
- open the retargeted managed-environment access-scope surface and confirm it manages visibility only

### Scenario 4: OperationRun access follows the same workspace-first rule

- confirm a workspace-bound run is viewable from workspace membership plus required capability
- confirm an environment-bound run is additionally narrowed by explicit environment scope when present

### Scenario 5: Search safety and denied-access diagnostics stay aligned

- confirm any touched searchable resource does not hint inaccessible managed environments to non-members or out-of-scope actors
- confirm denied-access logs explain the failed boundary without exposing raw provider data

### Scenario 6: Representative list and bulk preflight stay query-bounded

- confirm a representative environment-owned list, run list, and bulk-authorization preflight use the shared access contract without introducing avoidable N+1 membership or scope lookups

## Planned validation commands

```bash
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Unit/Auth/WorkspaceFirstCapabilityResolverTest.php tests/Unit/Auth/ManagedEnvironmentAccessScopeResolverTest.php)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/Auth/WorkspaceFirstManagedEnvironmentAccessTest.php tests/Feature/Rbac/ProviderConnectionWorkspaceFirstPolicyTest.php tests/Feature/Rbac/OperationRunWorkspaceFirstAuthorizationTest.php tests/Feature/Rbac/GovernanceArtifactsWorkspaceFirstAuthorizationTest.php tests/Feature/Filament/WorkspaceMembershipRoleManagementTest.php tests/Feature/Filament/ManagedEnvironmentAccessScopeManagementTest.php)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec285WorkspaceRbacEnvironmentAccessSmokeTest.php)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)
```

## Expected implementation boundaries

- no new role family
- no dual-write or compatibility fallback
- no new provider-boundary contract work
- no copy/localization sweep
- no cutover-wide guardrail enforcement bundle