# User Management and Platform Administrator Operations

## Authorization model

The existing `users.platform_role` field is the only platform-role authority. Its approved value is `platform_admin`. Platform role is independent from `tenant_memberships`; tenant access still requires one active membership using an existing `TenantRole` value (`tenant_admin`, `messaging`, `finance`, `support`, `auditor`, or `read_only`). Platform administration never implies tenant access.

Users have an external ULID `public_id` and an `active` or `disabled` account status. Disabled users retain memberships and history, cannot authenticate, and cannot resolve platform or tenant workspaces. Disabling or resetting a password rotates the remember token and removes database-backed sessions.

## First platform administrator

Run the command from an authenticated production shell. Do not place a password in command arguments or shell history.

```text
php artisan gateway:user:create-platform-admin
```

The command prompts for name, normalized email, password, and password confirmation. Password input is hidden, hashed before persistence, never echoed, and excluded from audit metadata. An existing email fails safely without changing that user. The command creates no tenant membership.

After provisioning, use the existing `/login` page. A platform administrator without memberships lands on `/platform`; an administrator with tenant memberships may use the workspace selector. Pricing and User Management appear in platform navigation.

## User lifecycle

Only an active authenticated platform administrator can open `/platform/users` or mutate users. The UI provides server-paginated inventory, indexed prefix search, user creation, platform-role management, account enable/disable, membership management, and protected password reset. It renders public IDs only.

User deletion is not an operational lifecycle action. Disable access instead. Memberships remain for history, and membership removal sets the existing membership to `inactive` without deleting tenant data.

## Last-administrator protection

Role revocation and disable operations lock the affected user and active administrator set transactionally. The last active `platform_admin` cannot be revoked or disabled. Disabled administrators do not count as recovery administrators. Provision or grant a second active administrator before rotating the original account.

## Password provisioning and reset

This milestone intentionally adds no email invitation or public password-reset flow. A platform administrator may set a temporary password using the protected CSRF form. The password is confirmed, validated with the current Laravel password policy, hashed, never displayed afterward, and omitted from logs and audits. Existing database sessions are invalidated. Communicate temporary credentials through an approved secure channel outside the application.

## Audit trail

`DatabaseAuditLogger` records user creation, enable/disable, platform-role grant/revoke, membership creation/role change/disable, password reset, and command bootstrap events. Metadata uses actor and subject public IDs and tenant public IDs. Passwords, hashes, session identifiers, credentials, and secrets are never recorded.

## Deployment

1. Back up the database.
2. Deploy the approved code without generated review assets.
3. Run `php artisan migrate --force`.
4. Run `php artisan optimize:clear` and rebuild approved caches/assets.
5. Run `php artisan gateway:user:create-platform-admin` from a secure interactive shell.
6. Sign in through `/login` and verify `/platform`, User Management, and Pricing.
7. Verify an ordinary tenant user receives 403 for platform routes.
8. Verify an existing tenant administrator can still sign in and reaches only assigned tenant workspaces.

Rollback the application first, then roll back the user-management migration only if no operational process depends on user public IDs or disabled status. Rollback removes only the added user fields/indexes; it does not delete users or memberships. Preserve an audited database backup before rollback.

## Explicit exclusions

There is no public registration, email invitation, MFA, SSO, public user API, Commercial Enforcement, wallet debit integration, SMS charging, Payments, Billing, Plans, or Invoices in this milestone.