# Implementation Plan: Workspace Foundation & Managed Tenant Onboarding Unification (v1)

**Branch**: `068-workspace-foundation-v1` | **Date**: 2026-02-01 | **Spec**: ./spec.md
**Input**: Feature specification from `specs/068-workspace-foundation-v1/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.

## Summary

Unify managed tenant onboarding behind a single canonical admin “front door” and ensure managed-tenant management stays tenantless (no tenant-in-tenant URLs).

Repo alignment note: in this codebase, “Managed tenants” are represented by the existing `App\\Models\\Tenant` model and are managed via `App\\Filament\\Resources\\TenantResource` (which already opts out of tenancy scoping via `protected static bool $isScopedToTenant = false`).

## Technical Context

specs/068-workspace-foundation-v1/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
└── tasks.md             # Phase 2 output (generated by /speckit.tasks)
**Project Type**: Laravel web application
**Performance Goals**: N/A (routing + RBAC UX change)
**Constraints**:
```text
app/
├── Filament/
│   ├── Pages/
│   │   ├── ChooseTenant.php
│   │   ├── NoAccess.php
│   │   └── (new) ManagedTenants/*
│   └── Resources/
│       └── TenantResource.php
├── Models/
│   └── Tenant.php
├── Providers/
│   ├── AuthServiceProvider.php
│   └── Filament/AdminPanelProvider.php
├── Services/
│   └── Auth/RoleCapabilityMap.php
└── Support/
    ├── Auth/Capabilities.php
    └── Middleware/DenyNonMemberTenantAccess.php

routes/web.php

tests/
├── Feature/
└── Unit/
```

**Structure Decision**: Laravel web application, implemented primarily in `app/Filament/*` and `app/Support/Auth/*`.

## Phase 0 — Outline & Research

Output: `research.md`

- Filament tenancy: confirm best-practice approach for tenantless pages and redirects inside a tenancy-enabled panel.
- Routing: confirm how to implement `/admin/new` redirect in a way that respects authentication and avoids route conflicts.
- RBAC-UX: confirm patterns to preserve 404 vs 403 semantics for managed-tenant actions and pages.

## Phase 1 — Design & Contracts

Outputs: `data-model.md`, `contracts/*`, `quickstart.md`

- Data model: reuse the existing `Tenant` model to represent a “managed tenant”.
- Session state: “Open” stores the selected tenant in session only (no DB persistence).
- Contracts: no new external API or OpenAPI contracts expected for v1.

## Phase 2 — Planning (Implementation Steps)

This plan is executed via `tasks.md` (generated by `/speckit.tasks`). Implementation sequence:

1. Add canonical onboarding entry: `/admin/managed-tenants/onboarding`.
2. Add legacy redirect: `/admin/new` → canonical onboarding.
3. Ensure managed-tenant CRUD remains tenantless (no `/admin/t/{tenant}` required).
4. Implement “Open” behavior:
    - If active: select tenant in session and redirect to a stable tenantless destination (e.g. `/admin/managed-tenants/current`).
   - If archived: show status screen instead of selecting/redirecting.
5. Add/align capability registry entries and role mapping.
6. Add/extend Pest tests for redirects and 404/403 semantics.