Tenant Migration Skill
Audit and execute the full migration checklist when cloning an existing Movemental tenant platform (the source, e.g. alan-hirsch) to create a new tenant deployment (the target, e.g. brad-brisco).
Context
This is a multi-tenant thought leader platform. Each tenant is:
- A separate Git repo/deployment sharing the same codebase structure
- Scoped to one
organizations row in a shared Supabase database via TENANT_ORG_ID
- Visually differentiated via
globals.css CSS variables and tenant.config.ts
The source repo (alan-hirsch) is the reference implementation. New tenants clone the repo, then must change every tenant-specific surface. This skill audits what's been done and what remains.
Execution Steps
Phase 1: Database & Org Identity (Supabase MCP)
Use the Supabase MCP (project vhaiiiykcukrlyvwlgip, public schema) to verify:
Organization row exists:
SELECT id, name, slug, description FROM organizations WHERE slug = '<target-slug>';
If missing, report that the org must be created first. Do NOT create it automatically.
TENANT_ORG_ID matches:
- Read
.env.local.example for the documented TENANT_ORG_ID
- Confirm it matches the org row's
id
Content scoped to this org:
SELECT 'books' AS type, count(*) FROM books WHERE organization_id = '<org-id>'
UNION ALL SELECT 'articles', count(*) FROM articles WHERE organization_id = '<org-id>'
UNION ALL SELECT 'courses', count(*) FROM courses WHERE organization_id = '<org-id>'
UNION ALL SELECT 'podcast_episodes', count(*) FROM podcast_episodes WHERE organization_id = '<org-id>'
UNION ALL SELECT 'videos', count(*) FROM videos WHERE organization_id = '<org-id>';
Report counts. Zero counts for enabled content types are warnings.
Storage buckets: Check if the tenant has a storage folder:
SELECT name FROM storage.buckets WHERE name LIKE '%media%';
Note: tenant images typically live under media-library/<tenant-slug>/ in Supabase Storage.
Vector store (if AI features enabled): Check if OPENAI_VECTOR_STORE_ID is documented or if the org has corpus content:
SELECT count(*) FROM book_chapters WHERE book_id IN (SELECT id FROM books WHERE organization_id = '<org-id>');
Phase 2: Tenant Config Audit
Read and audit src/lib/config/tenant.config.ts:
Name/identity fields — Must NOT reference the source tenant:
name, tagline, description, copyright
logo.text, logo.imageUrl, logo.markLightUrl, logo.markDarkUrl
about.heading, about.leadSentence, about.body, about.credentials
contact.email, contact.speakingNote
search.placeholder (should not say "Search Alan's...")
newsletter.headline, newsletter.subline, newsletter.leadMagnet
quote.text, quote.cite
Feature flags — features.* should reflect what the new tenant actually has:
- If
features.books === true, there must be books in the DB for this org
- If
features.courses === true, there must be courses
- If
features.chat === true, AI/agent infrastructure must be configured
- If
features.assessments === true, assessment records must exist
- If
features.podcasts === true, podcast episodes must exist
Chat config — All chat strings reference source tenant's name/voice:
chat.welcomeMessage, chat.disclaimer, chat.featuredSubline
chat.firstMessageHost, chat.assistantLabel
chat.floatingDocsAriaLabel
Themes/pathways — These are deeply tenant-specific:
themes[] slugs, titles, descriptions, coverImages
frameworks.items[] slugs and descriptions
pathwayCta.* content
home.router.options[] and home.router.ctas[]
Organizations/partners — organizations.items[] must be the new tenant's partners, not the source's
Pricing — pricing.plans[] may differ per tenant
Author profile (EEAT) — authorProfile.* must reflect the new author
Hero — hero.* heading, subheading, CTAs, imageUrl, backgroundImageUrl
Content type descriptions — contentTypes.* descriptions reference source tenant's domain
Home page sections — home.* section copy
Phase 3: Environment Variables
Read .env.local.example and verify:
TENANT_ORG_ID — Must be the new tenant's org UUID
DATABASE_URL — Same shared Supabase instance
NEXT_PUBLIC_SUPABASE_URL / NEXT_PUBLIC_SUPABASE_ANON_KEY — Same project
OPENAI_API_KEY / OPENAI_MODEL — If chat enabled
OPENAI_VECTOR_STORE_ID — Tenant-specific vector store for RAG
AI_LAB_AGENT_URL / AI_LAB_AGENT_API_KEY — If using external agent
STRIPE_SECRET_KEY / NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — Tenant-specific Stripe account
SENTRY_DSN / SENTRY_PROJECT — Tenant-specific Sentry project
COURSE_PREVIEW_HMAC_SECRET — Must match studio if using course preview
Phase 4: Codebase Grep for Source Tenant Leaks
Search the entire src/ directory for hardcoded references to the source tenant:
Grep for: "Alan Hirsch", "alan-hirsch", "alanhirsch", "Alan's", "mDNA", "APEST", "Forgotten Ways", "5Q", "Reframation"
Exclude:
tenant.config.ts (that's the config file itself)
node_modules/, .next/, _docs/
- Comments in generated files
Any hits in components, pages, or services are violations that must be fixed.
Phase 5: Middleware & Auth
Read src/middleware.ts and verify:
- Protected route patterns still make sense for the new tenant
- No hardcoded paths specific to the source tenant
Phase 6: Vercel Deployment
Check for Vercel project linkage:
.vercel/project.json — Should reference the new tenant's Vercel project
- Environment variables must be set in Vercel dashboard for all required vars
Output Format
Generate a structured migration report:
# Tenant Migration Report: [source] → [target]
## Status Summary
- Database org: [PASS/FAIL/MISSING]
- Tenant config: [X/Y fields migrated]
- Env vars: [CONFIGURED/NEEDS ATTENTION]
- Source tenant leaks: [N violations found]
- Middleware/auth: [PASS/NEEDS REVIEW]
- Vercel deployment: [LINKED/NOT LINKED]
## Critical (must fix before launch)
1. ...
## Warnings (should fix)
1. ...
## Passed
1. ...
## Recommended Next Steps
1. ...
Important Rules
- Never modify the Drizzle schema for migration purposes
- Never create database rows without explicit user approval
- Use Supabase MCP for all database queries — do not guess structure
- If MCP is unavailable, report what you can from code inspection alone and note which DB checks were skipped
- Visual theming (globals.css) and image assets are out of scope — handle those separately via
/color-audit, /asset-match, or manual design work
- The tenant.config.ts + .env.local are the two files that MUST change for every migration — everything else is structural
- Run
/tenant-check after migration to verify no hardcoded strings leaked through
1---2name: tenant-migrate3description: Audit and execute multi-tenant platform migration — determines what's needed when cloning a fully-built Movemental tenant (e.g. alan-hirsch) to bootstrap a new one (e.g. brad-brisco). Inspects Supabase via MCP, audits tenant config, env vars, feature flags, storage buckets, database org row, codebase leaks, middleware, and Vercel deployment. Does NOT handle visual theming (globals.css) or image assets — those are separate concerns. Use when onboarding a new thought leader onto the platform.4user-invocable: true5allowed-tools: Read, Grep, Glob, Bash, Agent, WebSearch, TodoWrite, mcp__supabase__execute_sql, mcp__supabase__list_tables, mcp__supabase__get_project, mcp__supabase__list_projects6metadata:7 source: https://skillmd.com/skills/joshuashepherd/tenant-migrate8---910# Tenant Migration Skill1112Audit and execute the full migration checklist when cloning an existing Movemental tenant platform (the **source**, e.g. `alan-hirsch`) to create a new tenant deployment (the **target**, e.g. `brad-brisco`).1314## Context1516This is a **multi-tenant thought leader platform**. Each tenant is:17- A separate Git repo/deployment sharing the same codebase structure18- Scoped to one `organizations` row in a shared Supabase database via `TENANT_ORG_ID`19- Visually differentiated via `globals.css` CSS variables and `tenant.config.ts`2021The source repo (alan-hirsch) is the reference implementation. New tenants clone the repo, then must change every tenant-specific surface. This skill audits what's been done and what remains.2223## Execution Steps2425### Phase 1: Database & Org Identity (Supabase MCP)2627Use the Supabase MCP (project `vhaiiiykcukrlyvwlgip`, `public` schema) to verify:28291. **Organization row exists**:30 ```sql31 SELECT id, name, slug, description FROM organizations WHERE slug = '<target-slug>';32 ```33 If missing, report that the org must be created first. Do NOT create it automatically.34352. **TENANT_ORG_ID matches**:36 - Read `.env.local.example` for the documented `TENANT_ORG_ID`37 - Confirm it matches the org row's `id`38393. **Content scoped to this org**:40 ```sql41 SELECT 'books' AS type, count(*) FROM books WHERE organization_id = '<org-id>'42 UNION ALL SELECT 'articles', count(*) FROM articles WHERE organization_id = '<org-id>'43 UNION ALL SELECT 'courses', count(*) FROM courses WHERE organization_id = '<org-id>'44 UNION ALL SELECT 'podcast_episodes', count(*) FROM podcast_episodes WHERE organization_id = '<org-id>'45 UNION ALL SELECT 'videos', count(*) FROM videos WHERE organization_id = '<org-id>';46 ```47 Report counts. Zero counts for enabled content types are warnings.48494. **Storage buckets**: Check if the tenant has a storage folder:50 ```sql51 SELECT name FROM storage.buckets WHERE name LIKE '%media%';52 ```53 Note: tenant images typically live under `media-library/<tenant-slug>/` in Supabase Storage.54555. **Vector store** (if AI features enabled): Check if `OPENAI_VECTOR_STORE_ID` is documented or if the org has corpus content:56 ```sql57 SELECT count(*) FROM book_chapters WHERE book_id IN (SELECT id FROM books WHERE organization_id = '<org-id>');58 ```5960### Phase 2: Tenant Config Audit6162Read and audit `src/lib/config/tenant.config.ts`:63641. **Name/identity fields** — Must NOT reference the source tenant:65 - `name`, `tagline`, `description`, `copyright`66 - `logo.text`, `logo.imageUrl`, `logo.markLightUrl`, `logo.markDarkUrl`67 - `about.heading`, `about.leadSentence`, `about.body`, `about.credentials`68 - `contact.email`, `contact.speakingNote`69 - `search.placeholder` (should not say "Search Alan's...")70 - `newsletter.headline`, `newsletter.subline`, `newsletter.leadMagnet`71 - `quote.text`, `quote.cite`72732. **Feature flags** — `features.*` should reflect what the new tenant actually has:74 - If `features.books === true`, there must be books in the DB for this org75 - If `features.courses === true`, there must be courses76 - If `features.chat === true`, AI/agent infrastructure must be configured77 - If `features.assessments === true`, assessment records must exist78 - If `features.podcasts === true`, podcast episodes must exist79803. **Chat config** — All chat strings reference source tenant's name/voice:81 - `chat.welcomeMessage`, `chat.disclaimer`, `chat.featuredSubline`82 - `chat.firstMessageHost`, `chat.assistantLabel`83 - `chat.floatingDocsAriaLabel`84854. **Themes/pathways** — These are deeply tenant-specific:86 - `themes[]` slugs, titles, descriptions, coverImages87 - `frameworks.items[]` slugs and descriptions88 - `pathwayCta.*` content89 - `home.router.options[]` and `home.router.ctas[]`90915. **Organizations/partners** — `organizations.items[]` must be the new tenant's partners, not the source's92936. **Pricing** — `pricing.plans[]` may differ per tenant94957. **Author profile (EEAT)** — `authorProfile.*` must reflect the new author96978. **Hero** — `hero.*` heading, subheading, CTAs, imageUrl, backgroundImageUrl98999. **Content type descriptions** — `contentTypes.*` descriptions reference source tenant's domain10010110. **Home page sections** — `home.*` section copy102103### Phase 3: Environment Variables104105Read `.env.local.example` and verify:1061071. `TENANT_ORG_ID` — Must be the new tenant's org UUID1082. `DATABASE_URL` — Same shared Supabase instance1093. `NEXT_PUBLIC_SUPABASE_URL` / `NEXT_PUBLIC_SUPABASE_ANON_KEY` — Same project1104. `OPENAI_API_KEY` / `OPENAI_MODEL` — If chat enabled1115. `OPENAI_VECTOR_STORE_ID` — Tenant-specific vector store for RAG1126. `AI_LAB_AGENT_URL` / `AI_LAB_AGENT_API_KEY` — If using external agent1137. `STRIPE_SECRET_KEY` / `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` — Tenant-specific Stripe account1148. `SENTRY_DSN` / `SENTRY_PROJECT` — Tenant-specific Sentry project1159. `COURSE_PREVIEW_HMAC_SECRET` — Must match studio if using course preview116117### Phase 4: Codebase Grep for Source Tenant Leaks118119Search the entire `src/` directory for hardcoded references to the source tenant:120121```122Grep for: "Alan Hirsch", "alan-hirsch", "alanhirsch", "Alan's", "mDNA", "APEST", "Forgotten Ways", "5Q", "Reframation"123```124125Exclude:126- `tenant.config.ts` (that's the config file itself)127- `node_modules/`, `.next/`, `_docs/`128- Comments in generated files129130Any hits in components, pages, or services are violations that must be fixed.131132### Phase 5: Middleware & Auth133134Read `src/middleware.ts` and verify:135- Protected route patterns still make sense for the new tenant136- No hardcoded paths specific to the source tenant137138### Phase 6: Vercel Deployment139140Check for Vercel project linkage:141- `.vercel/project.json` — Should reference the new tenant's Vercel project142- Environment variables must be set in Vercel dashboard for all required vars143144## Output Format145146Generate a structured migration report:147148```markdown149# Tenant Migration Report: [source] → [target]150151## Status Summary152- Database org: [PASS/FAIL/MISSING]153- Tenant config: [X/Y fields migrated]154- Env vars: [CONFIGURED/NEEDS ATTENTION]155- Source tenant leaks: [N violations found]156- Middleware/auth: [PASS/NEEDS REVIEW]157- Vercel deployment: [LINKED/NOT LINKED]158159## Critical (must fix before launch)1601. ...161162## Warnings (should fix)1631. ...164165## Passed1661. ...167168## Recommended Next Steps1691. ...170```171172## Important Rules173174- **Never modify the Drizzle schema** for migration purposes175- **Never create database rows** without explicit user approval176- **Use Supabase MCP** for all database queries — do not guess structure177- **If MCP is unavailable**, report what you can from code inspection alone and note which DB checks were skipped178- **Visual theming (globals.css) and image assets are out of scope** — handle those separately via `/color-audit`, `/asset-match`, or manual design work179- **The tenant.config.ts + .env.local are the two files that MUST change** for every migration — everything else is structural180- **Run `/tenant-check` after migration** to verify no hardcoded strings leaked through