diff --git a/AGENTS.md b/explanations/AGENTS.md
similarity index 100%
rename from AGENTS.md
rename to explanations/AGENTS.md
diff --git a/BETTER_AUTH_IMPLEMENTATION_SUMMARY.md b/explanations/BETTER_AUTH_IMPLEMENTATION_SUMMARY.md
similarity index 100%
rename from BETTER_AUTH_IMPLEMENTATION_SUMMARY.md
rename to explanations/BETTER_AUTH_IMPLEMENTATION_SUMMARY.md
diff --git a/BLACKBOX.md b/explanations/BLACKBOX.md
similarity index 100%
rename from BLACKBOX.md
rename to explanations/BLACKBOX.md
diff --git a/CHANGELOG_NOVEMBER_DECEMBER_2025.md b/explanations/CHANGELOG_NOVEMBER_DECEMBER_2025.md
similarity index 100%
rename from CHANGELOG_NOVEMBER_DECEMBER_2025.md
rename to explanations/CHANGELOG_NOVEMBER_DECEMBER_2025.md
diff --git a/CLERK_BILLING_MIGRATION.md b/explanations/CLERK_BILLING_MIGRATION.md
similarity index 100%
rename from CLERK_BILLING_MIGRATION.md
rename to explanations/CLERK_BILLING_MIGRATION.md
diff --git a/CLERK_BILLING_MIGRATION_SUMMARY.md b/explanations/CLERK_BILLING_MIGRATION_SUMMARY.md
similarity index 100%
rename from CLERK_BILLING_MIGRATION_SUMMARY.md
rename to explanations/CLERK_BILLING_MIGRATION_SUMMARY.md
diff --git a/CLERK_BILLING_QUICK_REFERENCE.md b/explanations/CLERK_BILLING_QUICK_REFERENCE.md
similarity index 100%
rename from CLERK_BILLING_QUICK_REFERENCE.md
rename to explanations/CLERK_BILLING_QUICK_REFERENCE.md
diff --git a/CLERK_BILLING_SETUP_CHECKLIST.md b/explanations/CLERK_BILLING_SETUP_CHECKLIST.md
similarity index 100%
rename from CLERK_BILLING_SETUP_CHECKLIST.md
rename to explanations/CLERK_BILLING_SETUP_CHECKLIST.md
diff --git a/DEPLOYMENT_CHECKLIST.md b/explanations/DEPLOYMENT_CHECKLIST.md
similarity index 100%
rename from DEPLOYMENT_CHECKLIST.md
rename to explanations/DEPLOYMENT_CHECKLIST.md
diff --git a/ERROR_DETECTION_IMPROVEMENTS.md b/explanations/ERROR_DETECTION_IMPROVEMENTS.md
similarity index 100%
rename from ERROR_DETECTION_IMPROVEMENTS.md
rename to explanations/ERROR_DETECTION_IMPROVEMENTS.md
diff --git a/MIGRATION_STATUS.md b/explanations/MIGRATION_STATUS.md
similarity index 100%
rename from MIGRATION_STATUS.md
rename to explanations/MIGRATION_STATUS.md
diff --git a/MULTI_FRAMEWORK_IMPLEMENTATION.md b/explanations/MULTI_FRAMEWORK_IMPLEMENTATION.md
similarity index 100%
rename from MULTI_FRAMEWORK_IMPLEMENTATION.md
rename to explanations/MULTI_FRAMEWORK_IMPLEMENTATION.md
diff --git a/PLAN.md b/explanations/PLAN.md
similarity index 100%
rename from PLAN.md
rename to explanations/PLAN.md
diff --git a/POLAR_QUICK_START.md b/explanations/POLAR_QUICK_START.md
similarity index 100%
rename from POLAR_QUICK_START.md
rename to explanations/POLAR_QUICK_START.md
diff --git a/POLAR_STACK_AUTH_INTEGRATION_SUMMARY.md b/explanations/POLAR_STACK_AUTH_INTEGRATION_SUMMARY.md
similarity index 100%
rename from POLAR_STACK_AUTH_INTEGRATION_SUMMARY.md
rename to explanations/POLAR_STACK_AUTH_INTEGRATION_SUMMARY.md
diff --git a/POLAR_TOKEN_FIX_SUMMARY.md b/explanations/POLAR_TOKEN_FIX_SUMMARY.md
similarity index 100%
rename from POLAR_TOKEN_FIX_SUMMARY.md
rename to explanations/POLAR_TOKEN_FIX_SUMMARY.md
diff --git a/PRODUCTION_AUTH_FIX.md b/explanations/PRODUCTION_AUTH_FIX.md
similarity index 100%
rename from PRODUCTION_AUTH_FIX.md
rename to explanations/PRODUCTION_AUTH_FIX.md
diff --git a/README_CONVEX.md b/explanations/README_CONVEX.md
similarity index 100%
rename from README_CONVEX.md
rename to explanations/README_CONVEX.md
diff --git a/README_SANDBOX_PERSISTENCE.md b/explanations/README_SANDBOX_PERSISTENCE.md
similarity index 100%
rename from README_SANDBOX_PERSISTENCE.md
rename to explanations/README_SANDBOX_PERSISTENCE.md
diff --git a/ROADMAP.md b/explanations/ROADMAP.md
similarity index 100%
rename from ROADMAP.md
rename to explanations/ROADMAP.md
diff --git a/SANDBOX_PERSISTENCE_CHANGES.md b/explanations/SANDBOX_PERSISTENCE_CHANGES.md
similarity index 100%
rename from SANDBOX_PERSISTENCE_CHANGES.md
rename to explanations/SANDBOX_PERSISTENCE_CHANGES.md
diff --git a/SANDBOX_PERSISTENCE_IMPLEMENTATION.md b/explanations/SANDBOX_PERSISTENCE_IMPLEMENTATION.md
similarity index 100%
rename from SANDBOX_PERSISTENCE_IMPLEMENTATION.md
rename to explanations/SANDBOX_PERSISTENCE_IMPLEMENTATION.md
diff --git a/SEO_IMPROVEMENTS.md b/explanations/SEO_IMPROVEMENTS.md
similarity index 100%
rename from SEO_IMPROVEMENTS.md
rename to explanations/SEO_IMPROVEMENTS.md
diff --git a/STACK_AUTH_MIGRATION_COMPLETE.md b/explanations/STACK_AUTH_MIGRATION_COMPLETE.md
similarity index 100%
rename from STACK_AUTH_MIGRATION_COMPLETE.md
rename to explanations/STACK_AUTH_MIGRATION_COMPLETE.md
diff --git a/START_HERE.md b/explanations/START_HERE.md
similarity index 100%
rename from START_HERE.md
rename to explanations/START_HERE.md
diff --git a/TEST_VERIFICATION.md b/explanations/TEST_VERIFICATION.md
similarity index 100%
rename from TEST_VERIFICATION.md
rename to explanations/TEST_VERIFICATION.md
diff --git a/TODO.md b/explanations/TODO.md
similarity index 100%
rename from TODO.md
rename to explanations/TODO.md