TenantAtlas/specs/247-plans-entitlements-billing-readiness/quickstart.md

Quickstart: Plans, Entitlements & Billing Readiness

Date: 2026-04-27
Branch: 247-plans-entitlements-billing-readiness

This quickstart is the intended reviewer flow after implementation. It stays bounded to the first slice described in the spec.

Prerequisites

1. Start the local platform stack.
   • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail up -d
2. Ensure one workspace member has workspace_settings.manage, one workspace owner can complete onboarding, one reporting operator can manage review packs, and one platform user has platform.directory.view.
3. Seed or factory-create:
   • one workspace with no entitlement overrides
   • one workspace at or above the managed-tenant activation limit
   • one managed-tenant onboarding draft in the target workspace
   • one tenant and one tenant review capable of review-pack generation

Scenario 1: Configure workspace commercial truth

1. Open /admin/settings/workspace as a workspace manager.
2. Confirm the page shows a Plan profile selector and the two first-slice entitlement controls.
3. Save a plan profile with no overrides.
4. Confirm the page shows:
   • the effective managed-tenant limit
   • whether review-pack generation is enabled
   • source labels pointing to the plan profile
   • current managed-tenant usage
5. Add an explicit override and rationale for one entitlement.
6. Save again and confirm the effective source switches to workspace override and the rationale is visible.
7. Reset the override and confirm the effective value returns to the plan-profile default.

Scenario 2: Gate managed-tenant onboarding activation

1. Open /admin/onboarding/{onboardingDraft} for a workspace that is within limit.
2. Confirm the completion step shows the current active managed-tenant usage and allows Complete onboarding.
3. Repeat with a workspace at or above its limit.
4. Confirm:
   • the completion action remains visible for an otherwise authorized actor
   • the action explains why onboarding is blocked
   • no tenant activation occurs
5. Repeat with a workspace override that raises the limit and confirm the source label changes to workspace override.

Scenario 3: Gate review-pack generation without creating a run

1. Use a workspace where review-pack generation is enabled.
2. Trigger generation from each current entry family:
   • tenant dashboard review-pack card
   • review register export action
   • tenant review detail export action
   • review-pack list header generate action
   • review-pack detail regenerate action
3. Confirm the current queued-start UX remains unchanged when allowed.
4. Switch to a workspace where review-pack generation is disabled.
5. Repeat the same actions and confirm:
   • each surface shows the same entitlement-based reason
   • no new ReviewPack row is created
   • no new OperationRun row is created
   • existing View and Download access to already-generated review packs still works under current artifact permissions

Scenario 4: Inspect the read-only system summary

1. Open /system/directory/workspaces/{workspace} as a platform user with platform.directory.view.
2. Confirm the page shows:
   • the effective plan profile
   • both entitlement decisions
   • source labels
   • override rationale when present
   • last changed attribution
3. Confirm there are no mutation controls on the system page.

RBAC and Plane Semantics Checks

1. Access admin-plane entitlement surfaces as a non-member or wrong-workspace actor and confirm 404.
2. Access the same surfaces as a workspace member lacking the relevant capability and confirm 403.
3. Access the action as an otherwise authorized actor whose workspace is not entitled and confirm a truthful business-state block instead of 403 or 404.
4. Access the system page as an admin-plane actor and confirm wrong-plane behavior does not leak workspace entitlement truth.

Targeted Validation Commands

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Entitlements/WorkspaceEntitlementResolverTest.php tests/Unit/Entitlements/WorkspacePlanProfileCatalogTest.php

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Settings/WorkspaceEntitlementsSettingsPageTest.php tests/Feature/Onboarding/ManagedTenantOnboardingEntitlementTest.php

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPacks/ReviewPackEntitlementEnforcementTest.php tests/Feature/System/Directory/ViewWorkspaceEntitlementsTest.php

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Out of Scope Confirmations

While validating this slice, confirm that the implementation does not add or imply:

• checkout or invoice UI
• payment-provider credentials or adapters
• customer-account, subscription, or contract records
• trial, grace-period, suspension, or renewal lifecycle states
• broader entitlement matrices outside the two first-slice keys