hazo_auth 5.1.37 → 5.1.38

package/README.md

@@ -547,347 +547,355 @@ cookie_domain = .example.com
 
 Before using `hazo_auth`, you need to create the required database tables. The package supports both **PostgreSQL** (for production) and **SQLite** (for local development/testing).
 
-### PostgreSQL Setup
+The v5.x schema consists of **9 tables**:
 
-Run the following SQL scripts in your PostgreSQL database:
+| Table | Purpose |
+|-------|---------|
+| `hazo_users` | User accounts and profile data |
+| `hazo_refresh_tokens` | Refresh, password-reset, and email-verification tokens |
+| `hazo_roles` | Role definitions (e.g. `super_user`, `firm_admin`) |
+| `hazo_permissions` | Permission definitions |
+| `hazo_role_permissions` | Role → permission assignments (composite PK) |
+| `hazo_scopes` | Unified hierarchical multi-tenancy with firm branding |
+| `hazo_user_scopes` | User → scope membership with scope-specific role (replaces `hazo_user_roles`) |
+| `hazo_invitations` | Invitations to onboard new users into existing scopes |
+| `hazo_user_relationships` | Managed sub-profile parent/child links (shared-device support) |
 
-#### 1. Create the Profile Source Enum Type
+> **Removed in v5.0:** the legacy `hazo_org` and `hazo_scopes_l1..l7` tables are gone. The unified `hazo_scopes` table replaces them with an arbitrary-depth `parent_id` hierarchy. The `hazo_user_roles` table is also gone — roles are now assigned per-scope on `hazo_user_scopes.role_id`.
 
-```sql
--- Enum type for profile picture source
-CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+### Quickest path: use the CLI
 
--- Note: hazo_enum_scope_types was removed in v5.0
--- The unified hazo_scopes table uses a TEXT "level" column instead
+For SQLite development databases, the canonical schema (in `src/lib/schema/sqlite_schema.ts`) ships with the package and can be applied via the CLI:
+
+```bash
+npx hazo_auth init-db    # Create/recreate the SQLite database with full schema
+npx hazo_auth schema     # Print the canonical schema SQL (does not modify DB)
 ```
 
-#### 2. Create the Organization Table (Multi-Tenancy)
+For PostgreSQL or PostgREST deployments, run the script below.
+
+### PostgreSQL Setup
 
 ```sql
--- Organization table for multi-tenancy (create before hazo_users)
-CREATE TABLE hazo_org (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    name TEXT NOT NULL,
-    parent_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    user_limit INTEGER NOT NULL DEFAULT 0,
-    active BOOLEAN NOT NULL DEFAULT TRUE,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    created_by UUID,  -- Will reference hazo_users after it's created
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_by UUID
-);
+-- ============================================================
+-- hazo_auth canonical PostgreSQL schema (v5.x)
+-- ============================================================
 
-CREATE INDEX idx_hazo_org_parent_org_id ON hazo_org(parent_org_id);
-CREATE INDEX idx_hazo_org_root_org_id ON hazo_org(root_org_id);
-CREATE INDEX idx_hazo_org_active ON hazo_org(active);
-```
+SET search_path TO public;
 
-#### 3. Create the Users Table
+-- 1. Enum types
+CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+CREATE TYPE hazo_enum_user_status AS ENUM ('PENDING', 'ACTIVE', 'BLOCKED');
+CREATE TYPE hazo_enum_user_scope_status_type AS ENUM ('INVITED', 'ACTIVE', 'SUSPENDED', 'DEPARTED');
+CREATE TYPE hazo_enum_invitation_status AS ENUM ('PENDING', 'ACCEPTED', 'EXPIRED', 'REVOKED');
 
-```sql
--- Main users table
+-- 2. Users
 CREATE TABLE hazo_users (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT,                                   -- NULL for OAuth-only users
+    password_hash TEXT,                                 -- NULL for OAuth-only users
     name TEXT,
     email_verified BOOLEAN NOT NULL DEFAULT FALSE,
-    is_active BOOLEAN NOT NULL DEFAULT TRUE,
     login_attempts INTEGER NOT NULL DEFAULT 0,
     last_logon TIMESTAMP WITH TIME ZONE,
     profile_picture_url TEXT,
     profile_source hazo_enum_profile_source_enum,
     mfa_secret TEXT,
-    url_on_logon TEXT,
-    user_type TEXT,                                       -- Optional user categorization
-    google_id TEXT UNIQUE,                                -- Google OAuth ID
-    auth_providers TEXT DEFAULT 'email',                  -- 'email', 'google', or 'email,google'
-    org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    url_on_logon TEXT,                                  -- per-user post-login redirect
+    google_id TEXT UNIQUE,                              -- Google OAuth ID
+    auth_providers TEXT DEFAULT 'email',                -- 'email', 'google', or 'email,google'
+    user_type TEXT,                                     -- optional categorisation
+    app_user_data JSONB,                                -- consumer-app JSON blob
+    status hazo_enum_user_status NOT NULL DEFAULT 'ACTIVE',
+    managed_by_user_id UUID REFERENCES hazo_users(id) ON DELETE SET NULL,
+    pin_hash TEXT,                                      -- simple PIN auth on shared devices
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-
--- Indexes
 CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
+CREATE INDEX idx_hazo_users_status ON hazo_users(status);
 CREATE INDEX idx_hazo_users_user_type ON hazo_users(user_type);
 CREATE UNIQUE INDEX idx_hazo_users_google_id ON hazo_users(google_id);
-CREATE INDEX idx_hazo_users_org_id ON hazo_users(org_id);
-CREATE INDEX idx_hazo_users_root_org_id ON hazo_users(root_org_id);
-
--- Add FK constraints to hazo_org after hazo_users exists
-ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_created_by
-    FOREIGN KEY (created_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
-ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_changed_by
-    FOREIGN KEY (changed_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
-```
-
-**Note:** The `url_on_logon` field is used to store a custom redirect URL for users after successful login. This allows per-user customization of post-login navigation.
-
-#### 4. Create the Refresh Tokens Table
+CREATE INDEX idx_hazo_users_managed_by ON hazo_users(managed_by_user_id);
 
-```sql
--- Refresh tokens table (used for password reset, email verification, etc.)
+-- 3. Refresh tokens (also used for password reset / email verification)
 CREATE TABLE hazo_refresh_tokens (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
     token_hash TEXT NOT NULL,
-    token_type TEXT NOT NULL,
+    token_type TEXT NOT NULL DEFAULT 'refresh',
     expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-
--- Index for token lookups
 CREATE INDEX idx_hazo_refresh_tokens_user_id ON hazo_refresh_tokens(user_id);
 CREATE INDEX idx_hazo_refresh_tokens_token_type ON hazo_refresh_tokens(token_type);
-```
-
-#### 5. Create the Permissions Table
 
-```sql
--- Permissions table for RBAC
-CREATE TABLE hazo_permissions (
+-- 4. Roles
+CREATE TABLE hazo_roles (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    permission_name TEXT NOT NULL UNIQUE,
-    description TEXT,
+    role_name TEXT NOT NULL UNIQUE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-```
-
-#### 6. Create the Roles Table
 
-```sql
--- Roles table for RBAC
-CREATE TABLE hazo_roles (
+-- 5. Permissions
+CREATE TABLE hazo_permissions (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    role_name TEXT NOT NULL UNIQUE,
+    permission_name TEXT NOT NULL UNIQUE,
+    description TEXT,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-```
 
-#### 7. Create the Role-Permissions Junction Table
-
-```sql
--- Junction table linking roles to permissions
+-- 6. Role-permission assignments (composite PK, no id column)
 CREATE TABLE hazo_role_permissions (
     role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
     permission_id UUID NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     PRIMARY KEY (role_id, permission_id)
 );
 
--- Indexes for lookups
-CREATE INDEX idx_hazo_role_permissions_role_id ON hazo_role_permissions(role_id);
-CREATE INDEX idx_hazo_role_permissions_permission_id ON hazo_role_permissions(permission_id);
-```
-
-#### 8. Create the User-Roles Junction Table
-
-```sql
--- Junction table linking users to roles
-CREATE TABLE hazo_user_roles (
-    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (user_id, role_id)
-);
-
--- Indexes for lookups
-CREATE INDEX idx_hazo_user_roles_user_id ON hazo_user_roles(user_id);
-CREATE INDEX idx_hazo_user_roles_role_id ON hazo_user_roles(role_id);
-```
-
-### Complete PostgreSQL Setup Script
-
-For convenience, here's the complete SQL script to create all tables at once:
-
-```sql
--- ============================================
--- hazo_auth Database Setup Script (PostgreSQL)
--- ============================================
-
--- 1. Create enum types
-CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
--- Note: hazo_enum_scope_types was removed in v5.0 (uses unified hazo_scopes table)
-
--- 2. Create organization table (multi-tenancy)
-CREATE TABLE hazo_org (
+-- 7. Unified scope hierarchy (firms, divisions, departments, ... with branding)
+CREATE TABLE hazo_scopes (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    parent_id UUID REFERENCES hazo_scopes(id) ON DELETE CASCADE,
     name TEXT NOT NULL,
-    parent_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    user_limit INTEGER NOT NULL DEFAULT 0,
-    active BOOLEAN NOT NULL DEFAULT TRUE,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    created_by UUID,
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_by UUID
-);
-CREATE INDEX idx_hazo_org_parent_org_id ON hazo_org(parent_org_id);
-CREATE INDEX idx_hazo_org_root_org_id ON hazo_org(root_org_id);
-CREATE INDEX idx_hazo_org_active ON hazo_org(active);
-
--- 3. Create users table
-CREATE TABLE hazo_users (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT,
-    name TEXT,
-    email_verified BOOLEAN NOT NULL DEFAULT FALSE,
-    is_active BOOLEAN NOT NULL DEFAULT TRUE,
-    login_attempts INTEGER NOT NULL DEFAULT 0,
-    last_logon TIMESTAMP WITH TIME ZONE,
-    profile_picture_url TEXT,
-    profile_source hazo_enum_profile_source_enum,
-    mfa_secret TEXT,
-    url_on_logon TEXT,
-    user_type TEXT,
-    google_id TEXT UNIQUE,
-    auth_providers TEXT DEFAULT 'email',
-    org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    level TEXT NOT NULL,                                -- descriptive label e.g. 'HQ', 'Division'
+    logo_url TEXT,
+    primary_color TEXT,
+    secondary_color TEXT,
+    tagline TEXT,
+    slug TEXT,                                          -- URL-friendly identifier
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
-CREATE INDEX idx_hazo_users_user_type ON hazo_users(user_type);
-CREATE UNIQUE INDEX idx_hazo_users_google_id ON hazo_users(google_id);
-CREATE INDEX idx_hazo_users_org_id ON hazo_users(org_id);
-CREATE INDEX idx_hazo_users_root_org_id ON hazo_users(root_org_id);
-
--- Add FK constraints to hazo_org after hazo_users exists
-ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_created_by
-    FOREIGN KEY (created_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
-ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_changed_by
-    FOREIGN KEY (changed_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
-
--- 4. Create refresh tokens table
-CREATE TABLE hazo_refresh_tokens (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+CREATE INDEX idx_hazo_scopes_parent ON hazo_scopes(parent_id);
+CREATE INDEX idx_hazo_scopes_level ON hazo_scopes(level);
+CREATE INDEX idx_hazo_scopes_slug ON hazo_scopes(slug);
+
+-- 7a. Reserved system scopes
+INSERT INTO hazo_scopes (id, parent_id, name, level)
+VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system')
+ON CONFLICT (id) DO NOTHING;
+INSERT INTO hazo_scopes (id, parent_id, name, level)
+VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default')
+ON CONFLICT (id) DO NOTHING;
+
+-- 8. User-scope membership (replaces v4.x hazo_user_roles)
+CREATE TABLE hazo_user_scopes (
     user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    token_hash TEXT NOT NULL,
-    token_type TEXT NOT NULL,
-    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
-);
-CREATE INDEX idx_hazo_refresh_tokens_user_id ON hazo_refresh_tokens(user_id);
-CREATE INDEX idx_hazo_refresh_tokens_token_type ON hazo_refresh_tokens(token_type);
-
--- 4. Create permissions table
-CREATE TABLE hazo_permissions (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    permission_name TEXT NOT NULL UNIQUE,
-    description TEXT,
+    scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    root_scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    status hazo_enum_user_scope_status_type NOT NULL DEFAULT 'ACTIVE',
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (user_id, scope_id)
 );
+CREATE INDEX idx_hazo_user_scopes_scope ON hazo_user_scopes(scope_id);
+CREATE INDEX idx_hazo_user_scopes_root ON hazo_user_scopes(root_scope_id);
+CREATE INDEX idx_hazo_user_scopes_role ON hazo_user_scopes(role_id);
 
--- 5. Create roles table
-CREATE TABLE hazo_roles (
+-- 9. Invitations
+CREATE TABLE hazo_invitations (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    role_name TEXT NOT NULL UNIQUE,
+    email_address TEXT NOT NULL,
+    token TEXT NOT NULL UNIQUE,
+    scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    root_scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    invited_by UUID REFERENCES hazo_users(id) ON DELETE SET NULL,
+    status hazo_enum_invitation_status NOT NULL DEFAULT 'PENDING',
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    accepted_at TIMESTAMP WITH TIME ZONE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
-
--- 6. Create role-permissions junction table
-CREATE TABLE hazo_role_permissions (
-    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    permission_id UUID NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
+CREATE INDEX idx_hazo_invitations_email ON hazo_invitations(email_address);
+CREATE INDEX idx_hazo_invitations_token ON hazo_invitations(token);
+CREATE INDEX idx_hazo_invitations_scope ON hazo_invitations(scope_id);
+CREATE INDEX idx_hazo_invitations_status ON hazo_invitations(status);
+CREATE INDEX idx_hazo_invitations_expires ON hazo_invitations(expires_at);
+
+-- 10. Managed sub-profile relationships (parent/child accounts on shared devices)
+CREATE TABLE hazo_user_relationships (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    parent_user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    child_user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    relationship_type TEXT NOT NULL DEFAULT 'parent',
+    can_view_progress BOOLEAN NOT NULL DEFAULT TRUE,
+    can_edit_profile BOOLEAN NOT NULL DEFAULT TRUE,
+    can_delete BOOLEAN NOT NULL DEFAULT FALSE,
+    is_self BOOLEAN NOT NULL DEFAULT FALSE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (role_id, permission_id)
+    UNIQUE (parent_user_id, child_user_id)
 );
-CREATE INDEX idx_hazo_role_permissions_role_id ON hazo_role_permissions(role_id);
-CREATE INDEX idx_hazo_role_permissions_permission_id ON hazo_role_permissions(permission_id);
+CREATE INDEX idx_hazo_user_relationships_parent ON hazo_user_relationships(parent_user_id);
+CREATE INDEX idx_hazo_user_relationships_child ON hazo_user_relationships(child_user_id);
 
--- 7. Create user-roles junction table
-CREATE TABLE hazo_user_roles (
-    user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (user_id, role_id)
-);
-CREATE INDEX idx_hazo_user_roles_user_id ON hazo_user_roles(user_id);
-CREATE INDEX idx_hazo_user_roles_role_id ON hazo_user_roles(role_id);
+-- 11. Built-in firm_admin role (used when a user creates their first firm)
+INSERT INTO hazo_roles (id, role_name)
+VALUES (gen_random_uuid(), 'firm_admin')
+ON CONFLICT (role_name) DO NOTHING;
 ```
 
 ### SQLite Setup (for local development)
 
-For local development and testing, you can use SQLite. The SQLite schema is slightly different (no UUID type, TEXT used instead):
+The SQLite version of the schema. Equivalent to running `npx hazo_auth init-db` and identical to `src/lib/schema/sqlite_schema.ts`.
 
 ```sql
--- ============================================
--- hazo_auth Database Setup Script (SQLite)
--- ============================================
+-- ============================================================
+-- hazo_auth canonical SQLite schema (v5.x)
+-- ============================================================
 
--- Users table
+-- Users
 CREATE TABLE IF NOT EXISTS hazo_users (
-    id TEXT PRIMARY KEY,
-    email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT NOT NULL,
-    name TEXT,
-    email_verified INTEGER NOT NULL DEFAULT 0,
-    is_active INTEGER NOT NULL DEFAULT 1,
-    login_attempts INTEGER NOT NULL DEFAULT 0,
-    last_logon TEXT,
-    profile_picture_url TEXT,
-    profile_source TEXT,
-    mfa_secret TEXT,
-    url_on_logon TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id TEXT PRIMARY KEY,
+  email_address TEXT NOT NULL UNIQUE,
+  password_hash TEXT,
+  name TEXT,
+  email_verified INTEGER DEFAULT 0,
+  login_attempts INTEGER DEFAULT 0,
+  last_logon TEXT,
+  profile_picture_url TEXT,
+  profile_source TEXT CHECK(profile_source IN ('gravatar', 'custom', 'predefined')),
+  mfa_secret TEXT,
+  url_on_logon TEXT,
+  google_id TEXT UNIQUE,
+  auth_providers TEXT DEFAULT 'email',
+  user_type TEXT,
+  app_user_data TEXT,
+  status TEXT DEFAULT 'ACTIVE' CHECK(status IN ('PENDING', 'ACTIVE', 'BLOCKED')),
+  managed_by_user_id TEXT REFERENCES hazo_users(id) ON DELETE SET NULL,
+  pin_hash TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
+CREATE INDEX IF NOT EXISTS idx_hazo_users_email ON hazo_users(email_address);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_google_id ON hazo_users(google_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_status ON hazo_users(status);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_managed_by ON hazo_users(managed_by_user_id);
 
--- Refresh tokens table
+-- Refresh tokens
 CREATE TABLE IF NOT EXISTS hazo_refresh_tokens (
-    id TEXT PRIMARY KEY,
-    user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    token_hash TEXT NOT NULL,
-    token_type TEXT NOT NULL,
-    expires_at TEXT NOT NULL,
-    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  token TEXT NOT NULL UNIQUE,
+  token_type TEXT DEFAULT 'refresh',
+  expires_at TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
+CREATE INDEX IF NOT EXISTS idx_hazo_refresh_tokens_user ON hazo_refresh_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_refresh_tokens_token ON hazo_refresh_tokens(token);
 
--- Permissions table
-CREATE TABLE IF NOT EXISTS hazo_permissions (
-    id TEXT PRIMARY KEY,
-    permission_name TEXT NOT NULL UNIQUE,
-    description TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+-- Roles
+CREATE TABLE IF NOT EXISTS hazo_roles (
+  id TEXT PRIMARY KEY,
+  role_name TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
--- Roles table
-CREATE TABLE IF NOT EXISTS hazo_roles (
-    id TEXT PRIMARY KEY,
-    role_name TEXT NOT NULL UNIQUE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+-- Permissions
+CREATE TABLE IF NOT EXISTS hazo_permissions (
+  id TEXT PRIMARY KEY,
+  permission_name TEXT NOT NULL UNIQUE,
+  description TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
--- Role-permissions junction table
+-- Role-permission assignments (composite PK, no id column)
 CREATE TABLE IF NOT EXISTS hazo_role_permissions (
-    role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    permission_id TEXT NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now')),
-    PRIMARY KEY (role_id, permission_id)
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  permission_id TEXT NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (role_id, permission_id)
 );
 
--- User-roles junction table
-CREATE TABLE IF NOT EXISTS hazo_user_roles (
-    user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now')),
-    PRIMARY KEY (user_id, role_id)
+-- Unified scope hierarchy (firms, divisions, departments, ... with branding)
+CREATE TABLE IF NOT EXISTS hazo_scopes (
+  id TEXT PRIMARY KEY,
+  parent_id TEXT REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  level TEXT NOT NULL,
+  logo_url TEXT,
+  primary_color TEXT,
+  secondary_color TEXT,
+  tagline TEXT,
+  slug TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_parent ON hazo_scopes(parent_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_level ON hazo_scopes(level);
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_slug ON hazo_scopes(slug);
+
+-- Reserved system scopes
+INSERT OR IGNORE INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system', datetime('now'), datetime('now'));
+INSERT OR IGNORE INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default', datetime('now'), datetime('now'));
+
+-- User-scope membership (replaces v4.x hazo_user_roles)
+CREATE TABLE IF NOT EXISTS hazo_user_scopes (
+  user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  root_scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  status TEXT DEFAULT 'ACTIVE' CHECK (status IN ('INVITED', 'ACTIVE', 'SUSPENDED', 'DEPARTED')),
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (user_id, scope_id)
+);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_scope ON hazo_user_scopes(scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_root ON hazo_user_scopes(root_scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_role ON hazo_user_scopes(role_id);
+
+-- Invitations
+CREATE TABLE IF NOT EXISTS hazo_invitations (
+  id TEXT PRIMARY KEY,
+  email_address TEXT NOT NULL,
+  token TEXT NOT NULL UNIQUE,
+  scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  root_scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  invited_by TEXT REFERENCES hazo_users(id) ON DELETE SET NULL,
+  status TEXT NOT NULL DEFAULT 'PENDING' CHECK(status IN ('PENDING', 'ACCEPTED', 'EXPIRED', 'REVOKED')),
+  expires_at TEXT NOT NULL,
+  accepted_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_email ON hazo_invitations(email_address);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_token ON hazo_invitations(token);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_scope ON hazo_invitations(scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_status ON hazo_invitations(status);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_expires ON hazo_invitations(expires_at);
+
+-- Managed sub-profile relationships
+CREATE TABLE IF NOT EXISTS hazo_user_relationships (
+  id TEXT PRIMARY KEY,
+  parent_user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  child_user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  relationship_type TEXT NOT NULL DEFAULT 'parent',
+  can_view_progress INTEGER DEFAULT 1,
+  can_edit_profile INTEGER DEFAULT 1,
+  can_delete INTEGER DEFAULT 0,
+  is_self INTEGER DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(parent_user_id, child_user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_relationships_parent ON hazo_user_relationships(parent_user_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_relationships_child ON hazo_user_relationships(child_user_id);
+
+-- Built-in firm_admin role (used when a user creates their first firm)
+INSERT OR IGNORE INTO hazo_roles (id, role_name, created_at, changed_at)
+VALUES (
+  lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)),2) || '-' || substr('89ab',abs(random()) % 4 + 1, 1) || substr(hex(randomblob(2)),2) || '-' || hex(randomblob(6))),
+  'firm_admin',
+  datetime('now'),
+  datetime('now')
 );
 ```
 
@@ -2147,19 +2155,14 @@ scope_cache_max_entries = 5000
 
 ### Database Setup
 
-HRBAC requires additional database tables. Run the scope consolidation migration:
+As of v5.0, the HRBAC tables — `hazo_scopes`, `hazo_user_scopes`, and `hazo_invitations` — are part of the **core schema** in [Database Setup](#database-setup), so if you ran the canonical PostgreSQL/SQLite script (or `npx hazo_auth init-db`) they already exist. No additional setup is required to enable HRBAC at the database level.
+
+If you're upgrading from v4.x, run the consolidation migration to drop the legacy `hazo_org`, `hazo_scopes_l1..l7`, and `hazo_user_roles` tables and create the new schema in place:
 
 ```bash
 npm run migrate migrations/009_scope_consolidation.sql
 ```
 
-This creates:
-- `hazo_scopes` - Unified scope hierarchy with branding support
-- `hazo_user_scopes` - User-scope-role assignments
-- `hazo_invitations` - User invitation flow
-
-See `SETUP_CHECKLIST.md` for full PostgreSQL and SQLite scripts.
-
 ### Using hazo_get_auth with Scope Options
 
 When HRBAC is enabled, you can check scope access alongside permissions:

package/SETUP_CHECKLIST.md

@@ -334,69 +334,179 @@ mkdir -p data
 
 The SQLite database will be created automatically on first use if using hazo_connect's SQLite adapter.
 
+**Recommended:** Run the canonical SQLite schema via the CLI. This is the single source of truth and creates ALL required tables (mirrors `src/lib/schema/sqlite_schema.ts`):
+
+```bash
+npx hazo_auth init-db          # Create/recreate the SQLite database with full schema
+npx hazo_auth schema           # Print the canonical schema SQL (does not modify DB)
+```
+
 **Manual creation (if needed):**
 ```bash
-# Create database with initial schema
+# Create database with the full v5.x schema (all tables, including scopes + relationships)
 cat << 'EOF' | sqlite3 data/hazo_auth.sqlite
+-- ============================================================
+-- hazo_auth canonical SQLite schema (v5.x)
+-- Mirrors src/lib/schema/sqlite_schema.ts
+-- ============================================================
+
+-- Users table (status enum + managed sub-profile support)
 CREATE TABLE IF NOT EXISTS hazo_users (
-    id TEXT PRIMARY KEY,
-    email_address TEXT NOT NULL UNIQUE,
-    password_hash TEXT,
-    name TEXT,
-    email_verified INTEGER NOT NULL DEFAULT 0,
-    status TEXT DEFAULT 'ACTIVE' CHECK(status IN ('PENDING', 'ACTIVE', 'BLOCKED')),
-    login_attempts INTEGER NOT NULL DEFAULT 0,
-    last_logon TEXT,
-    profile_picture_url TEXT,
-    profile_source TEXT CHECK(profile_source IN ('gravatar', 'custom', 'predefined')),
-    mfa_secret TEXT,
-    url_on_logon TEXT,
-    google_id TEXT UNIQUE,
-    auth_providers TEXT DEFAULT 'email',
-    user_type TEXT,
-    app_user_data TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id TEXT PRIMARY KEY,
+  email_address TEXT NOT NULL UNIQUE,
+  password_hash TEXT,
+  name TEXT,
+  email_verified INTEGER DEFAULT 0,
+  login_attempts INTEGER DEFAULT 0,
+  last_logon TEXT,
+  profile_picture_url TEXT,
+  profile_source TEXT CHECK(profile_source IN ('gravatar', 'custom', 'predefined')),
+  mfa_secret TEXT,
+  url_on_logon TEXT,
+  google_id TEXT UNIQUE,
+  auth_providers TEXT DEFAULT 'email',
+  user_type TEXT,
+  app_user_data TEXT,
+  status TEXT DEFAULT 'ACTIVE' CHECK(status IN ('PENDING', 'ACTIVE', 'BLOCKED')),
+  managed_by_user_id TEXT REFERENCES hazo_users(id) ON DELETE SET NULL,
+  pin_hash TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
+CREATE INDEX IF NOT EXISTS idx_hazo_users_email ON hazo_users(email_address);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_google_id ON hazo_users(google_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_status ON hazo_users(status);
+CREATE INDEX IF NOT EXISTS idx_hazo_users_managed_by ON hazo_users(managed_by_user_id);
+
+-- Refresh tokens (also used for password reset / email verification tokens)
 CREATE TABLE IF NOT EXISTS hazo_refresh_tokens (
-    id TEXT PRIMARY KEY,
-    user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    token_hash TEXT NOT NULL,
-    token_type TEXT NOT NULL,
-    expires_at TEXT NOT NULL,
-    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  token TEXT NOT NULL UNIQUE,
+  token_type TEXT DEFAULT 'refresh',
+  expires_at TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
-CREATE TABLE IF NOT EXISTS hazo_permissions (
-    id TEXT PRIMARY KEY,
-    permission_name TEXT NOT NULL UNIQUE,
-    description TEXT,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
-);
+CREATE INDEX IF NOT EXISTS idx_hazo_refresh_tokens_user ON hazo_refresh_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_refresh_tokens_token ON hazo_refresh_tokens(token);
 
+-- Roles
 CREATE TABLE IF NOT EXISTS hazo_roles (
-    id TEXT PRIMARY KEY,
-    role_name TEXT NOT NULL UNIQUE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+  id TEXT PRIMARY KEY,
+  role_name TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 
+-- Permissions
+CREATE TABLE IF NOT EXISTS hazo_permissions (
+  id TEXT PRIMARY KEY,
+  permission_name TEXT NOT NULL UNIQUE,
+  description TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- Role-permission assignments (composite PK, no id column)
 CREATE TABLE IF NOT EXISTS hazo_role_permissions (
-    role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    permission_id TEXT NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now')),
-    PRIMARY KEY (role_id, permission_id)
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  permission_id TEXT NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (role_id, permission_id)
 );
 
-CREATE TABLE IF NOT EXISTS hazo_user_roles (
-    user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
-    role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
-    created_at TEXT NOT NULL DEFAULT (datetime('now')),
-    changed_at TEXT NOT NULL DEFAULT (datetime('now')),
-    PRIMARY KEY (user_id, role_id)
+-- Unified scopes table (hierarchical multi-tenancy with firm branding)
+-- v5.0+ replaces hazo_org and hazo_scopes_l1..l7 with a single self-referencing table
+CREATE TABLE IF NOT EXISTS hazo_scopes (
+  id TEXT PRIMARY KEY,
+  parent_id TEXT REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  level TEXT NOT NULL,
+  logo_url TEXT,
+  primary_color TEXT,
+  secondary_color TEXT,
+  tagline TEXT,
+  slug TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_parent ON hazo_scopes(parent_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_level ON hazo_scopes(level);
+CREATE INDEX IF NOT EXISTS idx_hazo_scopes_slug ON hazo_scopes(slug);
+
+-- Reserved system scopes
+INSERT OR IGNORE INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system', datetime('now'), datetime('now'));
+
+INSERT OR IGNORE INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default', datetime('now'), datetime('now'));
+
+-- User-scope assignments (membership model with scope-specific roles)
+-- NOTE: replaces the old hazo_user_roles table from v4.x
+CREATE TABLE IF NOT EXISTS hazo_user_scopes (
+  user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  root_scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  status TEXT DEFAULT 'ACTIVE' CHECK (status IN ('INVITED', 'ACTIVE', 'SUSPENDED', 'DEPARTED')),
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now')),
+  PRIMARY KEY (user_id, scope_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_scope ON hazo_user_scopes(scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_root ON hazo_user_scopes(root_scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_scopes_role ON hazo_user_scopes(role_id);
+
+-- Invitations (onboard new users into existing scopes)
+CREATE TABLE IF NOT EXISTS hazo_invitations (
+  id TEXT PRIMARY KEY,
+  email_address TEXT NOT NULL,
+  token TEXT NOT NULL UNIQUE,
+  scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  root_scope_id TEXT NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+  role_id TEXT NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+  invited_by TEXT REFERENCES hazo_users(id) ON DELETE SET NULL,
+  status TEXT NOT NULL DEFAULT 'PENDING' CHECK(status IN ('PENDING', 'ACCEPTED', 'EXPIRED', 'REVOKED')),
+  expires_at TEXT NOT NULL,
+  accepted_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  changed_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_email ON hazo_invitations(email_address);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_token ON hazo_invitations(token);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_scope ON hazo_invitations(scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_status ON hazo_invitations(status);
+CREATE INDEX IF NOT EXISTS idx_hazo_invitations_expires ON hazo_invitations(expires_at);
+
+-- Managed sub-profile relationships (parent/child accounts on shared devices)
+CREATE TABLE IF NOT EXISTS hazo_user_relationships (
+  id TEXT PRIMARY KEY,
+  parent_user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  child_user_id TEXT NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  relationship_type TEXT NOT NULL DEFAULT 'parent',
+  can_view_progress INTEGER DEFAULT 1,
+  can_edit_profile INTEGER DEFAULT 1,
+  can_delete INTEGER DEFAULT 0,
+  is_self INTEGER DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(parent_user_id, child_user_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_user_relationships_parent ON hazo_user_relationships(parent_user_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_user_relationships_child ON hazo_user_relationships(child_user_id);
+
+-- Built-in firm_admin role (used when a user creates their first firm)
+INSERT OR IGNORE INTO hazo_roles (id, role_name, created_at, changed_at)
+VALUES (
+  lower(hex(randomblob(4)) || '-' || hex(randomblob(2)) || '-4' || substr(hex(randomblob(2)),2) || '-' || substr('89ab',abs(random()) % 4 + 1, 1) || substr(hex(randomblob(2)),2) || '-' || hex(randomblob(6))),
+  'firm_admin',
+  datetime('now'),
+  datetime('now')
 );
 EOF
 ```
@@ -404,82 +514,53 @@ EOF
 **Verify SQLite database:**
 ```bash
 sqlite3 data/hazo_auth.sqlite ".tables"
-# Expected: hazo_users hazo_refresh_tokens hazo_permissions hazo_roles hazo_role_permissions hazo_user_roles
+# Expected (9 tables):
+#   hazo_users hazo_refresh_tokens hazo_roles hazo_permissions hazo_role_permissions
+#   hazo_scopes hazo_user_scopes hazo_invitations hazo_user_relationships
 ```
 
+> **v4.x → v5.x:** the legacy `hazo_org`, `hazo_scopes_l1..l7`, and `hazo_user_roles` tables have been removed. Roles are now assigned per-scope via `hazo_user_scopes.role_id`. If upgrading, run `migrations/009_scope_consolidation.sql` first.
+
 ### Option B: PostgreSQL (Production)
 
-Run this SQL script in your PostgreSQL database:
+Run this SQL script in your PostgreSQL database. It creates the full v5.x schema, including the unified `hazo_scopes` model, `hazo_user_scopes`, `hazo_invitations`, and `hazo_user_relationships`.
 
-**Important:** Run the entire script in order. The enum type must be created before the table that uses it.
+**Important:** Run the entire script in order — enum types and parent tables must be created before tables that depend on them.
 
 ```sql
--- Ensure we're in the public schema (or your target schema)
+-- ============================================================
+-- hazo_auth canonical PostgreSQL schema (v5.x)
+-- Single source of truth for production deployments
+-- ============================================================
+
 SET search_path TO public;
 
--- Create enum types (drop first if they exist to avoid conflicts)
-DROP TYPE IF EXISTS hazo_enum_profile_source_enum CASCADE;
+-- 1. Enum types
 CREATE TYPE hazo_enum_profile_source_enum AS ENUM ('gravatar', 'custom', 'predefined');
+CREATE TYPE hazo_enum_user_status AS ENUM ('PENDING', 'ACTIVE', 'BLOCKED');
+CREATE TYPE hazo_enum_user_scope_status_type AS ENUM ('INVITED', 'ACTIVE', 'SUSPENDED', 'DEPARTED');
+CREATE TYPE hazo_enum_invitation_status AS ENUM ('PENDING', 'ACCEPTED', 'EXPIRED', 'REVOKED');
 
-DROP TYPE IF EXISTS hazo_enum_scope_types CASCADE;
-CREATE TYPE hazo_enum_scope_types AS ENUM (
-    'hazo_scopes_l1', 'hazo_scopes_l2', 'hazo_scopes_l3',
-    'hazo_scopes_l4', 'hazo_scopes_l5', 'hazo_scopes_l6', 'hazo_scopes_l7'
-);
-
-DROP TYPE IF EXISTS hazo_enum_notify_chain_status CASCADE;
-CREATE TYPE hazo_enum_notify_chain_status AS ENUM ('draft', 'published', 'inactive');
-
-DROP TYPE IF EXISTS hazo_enum_notify_email_type CASCADE;
-CREATE TYPE hazo_enum_notify_email_type AS ENUM ('system', 'user');
-
-DROP TYPE IF EXISTS hazo_enum_group_type CASCADE;
-CREATE TYPE hazo_enum_group_type AS ENUM ('support', 'peer', 'group');
-
-DROP TYPE IF EXISTS hazo_enum_group_role CASCADE;
-CREATE TYPE hazo_enum_group_role AS ENUM ('client', 'staff', 'owner', 'admin', 'member');
-
-DROP TYPE IF EXISTS hazo_enum_chat_type CASCADE;
-CREATE TYPE hazo_enum_chat_type AS ENUM ('chat', 'field', 'project', 'support', 'general');
-
--- Create organization table (multi-tenancy) - MUST be created before hazo_users
-CREATE TABLE hazo_org (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    name TEXT NOT NULL,
-    parent_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    user_limit INTEGER NOT NULL DEFAULT 0,              -- 0 = unlimited
-    active BOOLEAN NOT NULL DEFAULT TRUE,
-    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    created_by UUID,                                    -- FK added after hazo_users exists
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_by UUID                                     -- FK added after hazo_users exists
-);
-CREATE INDEX idx_hazo_org_parent_org_id ON hazo_org(parent_org_id);
-CREATE INDEX idx_hazo_org_root_org_id ON hazo_org(root_org_id);
-CREATE INDEX idx_hazo_org_active ON hazo_org(active);
-CREATE INDEX idx_hazo_org_name ON hazo_org(name);
-
--- Create users table
+-- 2. Users (status enum + managed sub-profile support)
 CREATE TABLE hazo_users (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     email_address TEXT NOT NULL UNIQUE,
     password_hash TEXT,                                 -- NULL for OAuth-only users
     name TEXT,
     email_verified BOOLEAN NOT NULL DEFAULT FALSE,
-    status TEXT NOT NULL DEFAULT 'ACTIVE',              -- 'PENDING', 'ACTIVE', or 'BLOCKED'
     login_attempts INTEGER NOT NULL DEFAULT 0,
     last_logon TIMESTAMP WITH TIME ZONE,
     profile_picture_url TEXT,
     profile_source hazo_enum_profile_source_enum,
     mfa_secret TEXT,
     url_on_logon TEXT,
-    user_type TEXT,                                     -- Optional user categorization
-    app_user_data TEXT,                                 -- Custom JSON data for consuming apps
     google_id TEXT UNIQUE,                              -- Google OAuth ID
     auth_providers TEXT DEFAULT 'email',                -- 'email', 'google', or 'email,google'
-    org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
-    root_org_id UUID REFERENCES hazo_org(id) ON DELETE SET NULL,
+    user_type TEXT,                                     -- Optional user categorization
+    app_user_data JSONB,                                -- Custom JSON data for consuming apps
+    status hazo_enum_user_status NOT NULL DEFAULT 'ACTIVE',
+    managed_by_user_id UUID REFERENCES hazo_users(id) ON DELETE SET NULL,  -- managed sub-profiles
+    pin_hash TEXT,                                      -- simple PIN auth on shared devices
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
@@ -487,71 +568,142 @@ CREATE INDEX idx_hazo_users_email ON hazo_users(email_address);
 CREATE INDEX idx_hazo_users_status ON hazo_users(status);
 CREATE INDEX idx_hazo_users_user_type ON hazo_users(user_type);
 CREATE UNIQUE INDEX idx_hazo_users_google_id ON hazo_users(google_id);
-CREATE INDEX idx_hazo_users_org_id ON hazo_users(org_id);
-CREATE INDEX idx_hazo_users_root_org_id ON hazo_users(root_org_id);
+CREATE INDEX idx_hazo_users_managed_by ON hazo_users(managed_by_user_id);
 
--- Add FK constraints to hazo_org now that hazo_users exists
-ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_created_by
-    FOREIGN KEY (created_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
-ALTER TABLE hazo_org ADD CONSTRAINT fk_hazo_org_changed_by
-    FOREIGN KEY (changed_by) REFERENCES hazo_users(id) ON DELETE SET NULL;
-
--- Create refresh tokens table
+-- 3. Refresh tokens (also used for password reset / email verification)
 CREATE TABLE hazo_refresh_tokens (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
     token_hash TEXT NOT NULL,
-    token_type TEXT NOT NULL,
+    token_type TEXT NOT NULL DEFAULT 'refresh',         -- 'refresh' | 'password_reset' | 'email_verification'
     expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
 CREATE INDEX idx_hazo_refresh_tokens_user_id ON hazo_refresh_tokens(user_id);
 CREATE INDEX idx_hazo_refresh_tokens_token_type ON hazo_refresh_tokens(token_type);
 
--- Create permissions table
-CREATE TABLE hazo_permissions (
+-- 4. Roles
+CREATE TABLE hazo_roles (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    permission_name TEXT NOT NULL UNIQUE,
-    description TEXT,
+    role_name TEXT NOT NULL UNIQUE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
 
--- Create roles table
-CREATE TABLE hazo_roles (
+-- 5. Permissions
+CREATE TABLE hazo_permissions (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    role_name TEXT NOT NULL UNIQUE,
+    permission_name TEXT NOT NULL UNIQUE,
+    description TEXT,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
 );
 
--- Create role-permissions junction table
+-- 6. Role-permission assignments (composite PK, NO id column)
 CREATE TABLE hazo_role_permissions (
     role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
     permission_id UUID NOT NULL REFERENCES hazo_permissions(id) ON DELETE CASCADE,
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     PRIMARY KEY (role_id, permission_id)
 );
-CREATE INDEX idx_hazo_role_permissions_role_id ON hazo_role_permissions(role_id);
-CREATE INDEX idx_hazo_role_permissions_permission_id ON hazo_role_permissions(permission_id);
 
--- Create user-roles junction table
-CREATE TABLE hazo_user_roles (
+-- 7. Unified scopes (hierarchical multi-tenancy with firm branding)
+--    v5.0+ replaces the old hazo_org and hazo_scopes_l1..l7 tables.
+CREATE TABLE hazo_scopes (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    parent_id UUID REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    level TEXT NOT NULL,                                -- descriptive label e.g. 'HQ', 'Division', 'Team'
+    logo_url TEXT,
+    primary_color TEXT,
+    secondary_color TEXT,
+    tagline TEXT,
+    slug TEXT,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+CREATE INDEX idx_hazo_scopes_parent ON hazo_scopes(parent_id);
+CREATE INDEX idx_hazo_scopes_level ON hazo_scopes(level);
+CREATE INDEX idx_hazo_scopes_slug ON hazo_scopes(slug);
+
+-- 7a. Reserved system scopes
+INSERT INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000000', NULL, 'Super Admin', 'system', NOW(), NOW())
+ON CONFLICT (id) DO NOTHING;
+
+INSERT INTO hazo_scopes (id, parent_id, name, level, created_at, changed_at)
+VALUES ('00000000-0000-0000-0000-000000000001', NULL, 'System', 'default', NOW(), NOW())
+ON CONFLICT (id) DO NOTHING;
+
+-- 8. User-scope assignments (membership model with scope-specific roles)
+--    Replaces the v4.x hazo_user_roles table.
+CREATE TABLE hazo_user_scopes (
     user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    root_scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
     role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    status hazo_enum_user_scope_status_type NOT NULL DEFAULT 'ACTIVE',
     created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
     changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
-    PRIMARY KEY (user_id, role_id)
+    PRIMARY KEY (user_id, scope_id)
+);
+CREATE INDEX idx_hazo_user_scopes_scope ON hazo_user_scopes(scope_id);
+CREATE INDEX idx_hazo_user_scopes_root ON hazo_user_scopes(root_scope_id);
+CREATE INDEX idx_hazo_user_scopes_role ON hazo_user_scopes(role_id);
+
+-- 9. Invitations (onboard new users into existing scopes)
+CREATE TABLE hazo_invitations (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    email_address TEXT NOT NULL,
+    token TEXT NOT NULL UNIQUE,
+    scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    root_scope_id UUID NOT NULL REFERENCES hazo_scopes(id) ON DELETE CASCADE,
+    role_id UUID NOT NULL REFERENCES hazo_roles(id) ON DELETE CASCADE,
+    invited_by UUID REFERENCES hazo_users(id) ON DELETE SET NULL,
+    status hazo_enum_invitation_status NOT NULL DEFAULT 'PENDING',
+    expires_at TIMESTAMP WITH TIME ZONE NOT NULL,
+    accepted_at TIMESTAMP WITH TIME ZONE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+CREATE INDEX idx_hazo_invitations_email ON hazo_invitations(email_address);
+CREATE INDEX idx_hazo_invitations_token ON hazo_invitations(token);
+CREATE INDEX idx_hazo_invitations_scope ON hazo_invitations(scope_id);
+CREATE INDEX idx_hazo_invitations_status ON hazo_invitations(status);
+CREATE INDEX idx_hazo_invitations_expires ON hazo_invitations(expires_at);
+
+-- 10. Managed sub-profile relationships (parent/child accounts on shared devices)
+CREATE TABLE hazo_user_relationships (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    parent_user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    child_user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+    relationship_type TEXT NOT NULL DEFAULT 'parent',
+    can_view_progress BOOLEAN NOT NULL DEFAULT TRUE,
+    can_edit_profile BOOLEAN NOT NULL DEFAULT TRUE,
+    can_delete BOOLEAN NOT NULL DEFAULT FALSE,
+    is_self BOOLEAN NOT NULL DEFAULT FALSE,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    UNIQUE (parent_user_id, child_user_id)
 );
-CREATE INDEX idx_hazo_user_roles_user_id ON hazo_user_roles(user_id);
-CREATE INDEX idx_hazo_user_roles_role_id ON hazo_user_roles(role_id);
+CREATE INDEX idx_hazo_user_relationships_parent ON hazo_user_relationships(parent_user_id);
+CREATE INDEX idx_hazo_user_relationships_child ON hazo_user_relationships(child_user_id);
+
+-- 11. Built-in firm_admin role (used when a user creates their first firm)
+INSERT INTO hazo_roles (id, role_name, created_at, changed_at)
+VALUES (gen_random_uuid(), 'firm_admin', NOW(), NOW())
+ON CONFLICT (role_name) DO NOTHING;
 ```
 
+> **Migrating from v4.x?** The legacy `hazo_org`, `hazo_scopes_l1..l7`, and `hazo_user_roles` tables have been removed. Run `migrations/009_scope_consolidation.sql` against your existing database — it drops the old tables and creates the new schema in place.
+
 **Verify PostgreSQL tables:**
 ```sql
-SELECT table_name FROM information_schema.tables WHERE table_name LIKE 'hazo_%';
--- Expected: 6 tables listed
+SELECT table_name FROM information_schema.tables
+WHERE table_schema = 'public' AND table_name LIKE 'hazo_%'
+ORDER BY table_name;
+-- Expected (9 tables):
+--   hazo_invitations, hazo_permissions, hazo_refresh_tokens, hazo_role_permissions,
+--   hazo_roles, hazo_scopes, hazo_users, hazo_user_relationships, hazo_user_scopes
 ```
 
 **Grant access to admin user:**
@@ -565,16 +717,19 @@ GRANT USAGE ON SCHEMA public TO your_admin_user;
 -- Grant all privileges on all hazo_* tables
 GRANT ALL PRIVILEGES ON TABLE hazo_users TO your_admin_user;
 GRANT ALL PRIVILEGES ON TABLE hazo_refresh_tokens TO your_admin_user;
-GRANT ALL PRIVILEGES ON TABLE hazo_permissions TO your_admin_user;
 GRANT ALL PRIVILEGES ON TABLE hazo_roles TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_permissions TO your_admin_user;
 GRANT ALL PRIVILEGES ON TABLE hazo_role_permissions TO your_admin_user;
-GRANT ALL PRIVILEGES ON TABLE hazo_user_roles TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_scopes TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_invitations TO your_admin_user;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_relationships TO your_admin_user;
 
--- Grant usage on the enum type
+-- Grant usage on enum types
 GRANT USAGE ON TYPE hazo_enum_profile_source_enum TO your_admin_user;
-
--- Grant privileges on sequences (if using SERIAL instead of UUID, though not needed for UUID)
--- GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO your_admin_user;
+GRANT USAGE ON TYPE hazo_enum_user_status TO your_admin_user;
+GRANT USAGE ON TYPE hazo_enum_user_scope_status_type TO your_admin_user;
+GRANT USAGE ON TYPE hazo_enum_invitation_status TO your_admin_user;
 
 -- Optional: Grant privileges on future tables (if you plan to add more hazo_* tables)
 ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL PRIVILEGES ON TABLES TO your_admin_user;
@@ -598,7 +753,7 @@ GRANT SELECT ON TABLE hazo_users TO anon;
 GRANT SELECT ON TABLE hazo_permissions TO anon;
 GRANT SELECT ON TABLE hazo_roles TO anon;
 GRANT SELECT ON TABLE hazo_role_permissions TO anon;
-GRANT SELECT ON TABLE hazo_user_roles TO anon;
+GRANT SELECT ON TABLE hazo_scopes TO anon;
 
 -- Grant full access to authenticated users (adjust based on your RLS policies)
 GRANT ALL PRIVILEGES ON TABLE hazo_users TO authenticated;
@@ -606,30 +761,39 @@ GRANT ALL PRIVILEGES ON TABLE hazo_refresh_tokens TO authenticated;
 GRANT ALL PRIVILEGES ON TABLE hazo_permissions TO authenticated;
 GRANT ALL PRIVILEGES ON TABLE hazo_roles TO authenticated;
 GRANT ALL PRIVILEGES ON TABLE hazo_role_permissions TO authenticated;
-GRANT ALL PRIVILEGES ON TABLE hazo_user_roles TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_scopes TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_scopes TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_invitations TO authenticated;
+GRANT ALL PRIVILEGES ON TABLE hazo_user_relationships TO authenticated;
 
--- Grant usage on enum type
+-- Grant usage on enum types
 GRANT USAGE ON TYPE hazo_enum_profile_source_enum TO anon, authenticated;
+GRANT USAGE ON TYPE hazo_enum_user_status TO anon, authenticated;
+GRANT USAGE ON TYPE hazo_enum_user_scope_status_type TO anon, authenticated;
+GRANT USAGE ON TYPE hazo_enum_invitation_status TO anon, authenticated;
 ```
 
 **Checklist:**
 - [ ] Database created (SQLite file or PostgreSQL)
 - [ ] All enum types created (PostgreSQL only):
   - [ ] `hazo_enum_profile_source_enum`
-  - [ ] `hazo_enum_scope_types`
-  - [ ] `hazo_enum_notify_chain_status`
-  - [ ] `hazo_enum_notify_email_type`
-  - [ ] `hazo_enum_group_type`
-  - [ ] `hazo_enum_group_role`
-  - [ ] `hazo_enum_chat_type`
-- [ ] All core tables exist:
-  - [ ] `hazo_org` (multi-tenancy - must be created before hazo_users)
-  - [ ] `hazo_users` (with status, google_id, auth_providers, app_user_data, org_id, root_org_id, user_type fields)
+  - [ ] `hazo_enum_user_status`
+  - [ ] `hazo_enum_user_scope_status_type`
+  - [ ] `hazo_enum_invitation_status`
+- [ ] All core tables exist (9 total):
+  - [ ] `hazo_users` (with `status`, `google_id`, `auth_providers`, `app_user_data`, `user_type`, `managed_by_user_id`, `pin_hash` fields)
   - [ ] `hazo_refresh_tokens`
-  - [ ] `hazo_permissions`
   - [ ] `hazo_roles`
-  - [ ] `hazo_role_permissions`
-  - [ ] `hazo_user_roles`
+  - [ ] `hazo_permissions`
+  - [ ] `hazo_role_permissions` (composite PK, no `id` column)
+  - [ ] `hazo_scopes` (unified hierarchy with branding + `slug`)
+  - [ ] `hazo_user_scopes` (composite PK on `user_id`, `scope_id`)
+  - [ ] `hazo_invitations`
+  - [ ] `hazo_user_relationships` (managed sub-profile parent/child links)
+- [ ] Reserved system scopes inserted:
+  - [ ] `00000000-0000-0000-0000-000000000000` (Super Admin)
+  - [ ] `00000000-0000-0000-0000-000000000001` (System / non-multi-tenancy default)
+- [ ] `firm_admin` role inserted into `hazo_roles`
 
 ---
 
@@ -1439,7 +1603,9 @@ application_permission_list_defaults = admin_user_management,admin_role_manageme
 
 ### Step 7.3: Create HRBAC Database Tables
 
-**Recommended:** Run the scope consolidation migration which creates all required tables:
+> **Note (v5.0+):** `hazo_scopes`, `hazo_user_scopes`, and `hazo_invitations` are now part of the **core schema** in Phase 3. If you ran the canonical SQLite or PostgreSQL script there (or `npx hazo_auth init-db`), these tables already exist — you can skip ahead to Step 7.4. The scripts below are kept for upgrades from v4.x or for partial recovery.
+
+**Upgrading from v4.x?** Run the consolidation migration which drops the legacy tables (`hazo_org`, `hazo_scopes_l1..l7`, `hazo_user_roles`) and creates the new schema:
 
 ```bash
 npm run migrate migrations/009_scope_consolidation.sql

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_auth",
-  "version": "5.1.37",
+  "version": "5.1.38",
   "description": "Zero-config authentication UI components for Next.js with RBAC, OAuth, scope-based multi-tenancy, and invitations",
   "keywords": [
     "authentication",