diff --git a/.gitignore b/.gitignore
index 37237cea8..95a7c6607 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,57 +1,90 @@
+# Python
.venv/
+venv/
+__pycache__/
+*.py[cod]
+*$py.class
-
-# Logs
-logs
-*.log
+# Node.js
+node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
lerna-debug.log*
+package-lock.json
+yarn.lock
+.pnp
+.pnp.js
-node_modules
-dist
-dist-ssr
-*-dist
-*.local
-
-# Next.js
+# Build outputs
+dist/
+dist-ssr/
+*-dist/
+build/
.next/
out/
next-env.d.ts
+*.local
-# Editor directories and files
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Editor
.vscode/*
!.vscode/extensions.json
-.idea
+!.vscode/settings.json
+!.vscode/launch.json
+!.vscode/tasks.json
+.idea/
+*.sublime-project
+*.sublime-workspace
.DS_Store
+Thumbs.db
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?
+*~
-# Prisma
+# IDE/Development
+.devcontainer/
+.spark-workbench-id
+.spark-initial-sha
+_codeql_detected_source_root/
+
+# Database
prisma/dev.db
prisma/dev.db-journal
+*.db
+*.sqlite
+*.sqlite3
-.env
-**/agent-eval-report*
-pids
-.file-manifest
-.devcontainer/
-
-.spark-workbench-id
-
-# Playwright
+# Testing
/test-results/
/playwright-report/
/playwright/.cache/
/e2e-results/
-
-# Test artifacts
*.spec.js.map
*.spec.ts.map
+coverage/
+.nyc_output/
+
+# Logs
+logs/
+*.log
+
+# Cache/Temp
+pids/
+.file-manifest
lint-output.txt
-build/
+.turbo/
+
+# Project-specific
+**/agent-eval-report*
+vite.config.ts.bak*
+.cache/
+dist-old/
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 000000000..403688686
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,14 @@
+{
+ "cmake.sourceDirectory": "/workspaces/metabuilder/dbal/cpp",
+ "chat.mcp.discovery.enabled": {
+ "claude-desktop": true,
+ "windsurf": true,
+ "cursor-global": true,
+ "cursor-workspace": true
+ },
+ "chat.mcp.gallery.enabled": true,
+ "inlineChat.enableV2": true,
+ "chat.allowAnonymousAccess": false,
+ "chat.mcp.assisted.nuget.enabled": true,
+ "inlineChat.notebookAgent": true
+}
\ No newline at end of file
diff --git a/docs/INDEX.md b/docs/INDEX.md
new file mode 100644
index 000000000..3a71ca714
--- /dev/null
+++ b/docs/INDEX.md
@@ -0,0 +1,108 @@
+# Documentation Index
+
+Welcome to MetaBuilder documentation. This guide helps you find what you need.
+
+## Start Here
+
+- **[README.md](README.md)** - Project overview and quick start
+- **[PRD.md](PRD.md)** - Product requirements and feature specifications
+- **[SECURITY.md](SECURITY.md)** - Security policies and best practices
+
+## Documentation by Topic
+
+### [Guides](guides/)
+Quick references and setup instructions for developers.
+
+- **[IMPLEMENTATION_ROADMAP.md](guides/IMPLEMENTATION_ROADMAP.md)** - Feature development timeline
+- **[ATOMIC_QUICKSTART.md](guides/ATOMIC_QUICKSTART.md)** - Get started with atomic design patterns
+- **[ACT_QUICK_REFERENCE.md](guides/ACT_QUICK_REFERENCE.md)** - GitHub Actions testing quick ref
+- **[SASS_QUICK_REFERENCE.md](guides/SASS_QUICK_REFERENCE.md)** - SASS/SCSS styling guide
+- **[github-actions-local-testing.md](guides/github-actions-local-testing.md)** - Test workflows locally
+
+### [Implementation Guides](implementation/)
+Deep-dive documentation on implemented features and architecture.
+
+- **[COMPONENT_MAP.md](implementation/COMPONENT_MAP.md)** - Component structure and organization
+- **[ATOMIC_DESIGN.md](implementation/ATOMIC_DESIGN.md)** - Atomic design system
+- **[MULTI_TENANT_SYSTEM.md](implementation/MULTI_TENANT_SYSTEM.md)** - Multi-tenancy architecture
+- **[PRISMA_IMPLEMENTATION_COMPLETE.md](implementation/PRISMA_IMPLEMENTATION_COMPLETE.md)** - Database layer
+- **[DBAL_INTEGRATION.md](implementation/DBAL_INTEGRATION.md)** - Data abstraction layer
+- **[SECURE_DATABASE_LAYER.md](implementation/SECURE_DATABASE_LAYER.md)** - Database security
+- **[BLOB_STORAGE_IMPLEMENTATION.md](implementation/BLOB_STORAGE_IMPLEMENTATION.md)** - File storage
+- **[NEXTJS_MIGRATION.md](implementation/NEXTJS_MIGRATION.md)** - Next.js migration
+- **[UNIT_TESTS_IMPLEMENTATION.md](implementation/UNIT_TESTS_IMPLEMENTATION.md)** - Testing strategy
+
+### [Build System](builds/)
+C++ build, compilation, and cross-platform setup.
+
+- **[CROSS_PLATFORM_BUILD.md](builds/CROSS_PLATFORM_BUILD.md)** - Cross-platform compilation
+- **[CPP_BUILD_QUICK_REF.md](builds/CPP_BUILD_QUICK_REF.md)** - C++ build quick reference
+- **[CPP_BUILD_ASSISTANT.md](builds/CPP_BUILD_ASSISTANT.md)** - Build troubleshooting
+
+### [Deployments & CI/CD](deployments/)
+Production deployment, containerization, and continuous integration.
+
+- **[NGINX_INTEGRATION.md](deployments/NGINX_INTEGRATION.md)** - Web server configuration
+- **[GITHUB_WORKFLOWS_AUDIT.md](deployments/GITHUB_WORKFLOWS_AUDIT.md)** - CI/CD pipeline review
+- **[CI_CD_SUMMARY.md](deployments/CI_CD_SUMMARY.md)** - Build & deployment overview
+
+### [Migrations](migrations/)
+Data migrations, code refactoring, and relocation guides.
+
+- **[MIGRATION_STATUS.md](migrations/MIGRATION_STATUS.md)** - Migration progress tracking
+- **[FILE_RELOCATION_GUIDE.md](migrations/FILE_RELOCATION_GUIDE.md)** - File organization
+- **[RELOCATION_SUMMARY.md](migrations/RELOCATION_SUMMARY.md)** - Relocation completion status
+
+### [Troubleshooting](troubleshooting/)
+Diagnostics, debugging guides, and common issues.
+
+- **[WORKFLOW_FAILURE_DIAGNOSIS.md](troubleshooting/WORKFLOW_FAILURE_DIAGNOSIS.md)** - CI/CD debugging
+- **[CORS-BYPASS-EXPLANATION.md](troubleshooting/CORS-BYPASS-EXPLANATION.md)** - CORS issues
+- **[TEST_COVERAGE_SUMMARY.md](troubleshooting/TEST_COVERAGE_SUMMARY.md)** - Test coverage info
+- **[PACKAGE_TESTS.md](troubleshooting/PACKAGE_TESTS.md)** - Package testing guide
+
+### [Archive](archive/)
+Completed phases and historical work.
+
+- **[PHASE2_SUMMARY.md](archive/PHASE2_SUMMARY.md)** - Phase 2 completion summary
+
+## Additional Topics
+
+### Architecture
+Fundamental architecture and design patterns.
+
+- **[architecture/](architecture/)** - Core architecture documents
+
+### Database
+Database-specific documentation.
+
+- **[database/](database/)** - Database design and setup
+
+### Development
+Development workflow and best practices.
+
+- **[development/](development/)** - Development guides
+
+### Lua Scripting
+Lua integration and scripting.
+
+- **[lua/](lua/)** - Lua documentation and examples
+
+### Reference
+Quick lookup and API reference.
+
+- **[reference/](reference/)** - Technical references
+
+### Security
+Security policies and guidelines.
+
+- **[security/](security/)** - Security documentation
+
+## Navigation Tips
+
+1. **New to MetaBuilder?** Start with [README.md](README.md) and [ATOMIC_QUICKSTART.md](guides/ATOMIC_QUICKSTART.md)
+2. **Building a feature?** Check [IMPLEMENTATION_ROADMAP.md](guides/IMPLEMENTATION_ROADMAP.md) and the [implementation/](implementation/) folder
+3. **Setting up locally?** See [SASS_QUICK_REFERENCE.md](guides/SASS_QUICK_REFERENCE.md) and [guides/](guides/)
+4. **Deploying to production?** Review [NGINX_INTEGRATION.md](deployments/NGINX_INTEGRATION.md) and [deployments/](deployments/)
+5. **Debugging issues?** Check [troubleshooting/](troubleshooting/) first
+6. **Running CI/CD locally?** See [github-actions-local-testing.md](guides/github-actions-local-testing.md)
diff --git a/docs/README.md b/docs/README.md
index f18f628f7..79d606a2c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -420,6 +420,17 @@ See `example-schemas.json` for complete examples including:
- No file uploads (use URL fields to reference external files)
- Maximum recommended records per model: 1000
+## Documentation
+
+For comprehensive guides, check the [Documentation Index](INDEX.md). Key resources:
+
+- **Getting Started**: [ATOMIC_QUICKSTART.md](guides/ATOMIC_QUICKSTART.md)
+- **Architecture**: [architecture/](architecture/)
+- **Database**: [database/](database/) and [PRISMA_IMPLEMENTATION_COMPLETE.md](implementation/PRISMA_IMPLEMENTATION_COMPLETE.md)
+- **Development**: [development/](development/) and [guides/](guides/)
+- **Deployment**: [deployments/](deployments/)
+- **Troubleshooting**: [troubleshooting/](troubleshooting/)
+
## Architecture
The system consists of:
diff --git a/docs/PHASE2_SUMMARY.md b/docs/archive/PHASE2_SUMMARY.md
similarity index 100%
rename from docs/PHASE2_SUMMARY.md
rename to docs/archive/PHASE2_SUMMARY.md
diff --git a/docs/CPP_BUILD_ASSISTANT.md b/docs/builds/CPP_BUILD_ASSISTANT.md
similarity index 100%
rename from docs/CPP_BUILD_ASSISTANT.md
rename to docs/builds/CPP_BUILD_ASSISTANT.md
diff --git a/docs/CPP_BUILD_ASSISTANT_SUMMARY.md b/docs/builds/CPP_BUILD_ASSISTANT_SUMMARY.md
similarity index 100%
rename from docs/CPP_BUILD_ASSISTANT_SUMMARY.md
rename to docs/builds/CPP_BUILD_ASSISTANT_SUMMARY.md
diff --git a/docs/CPP_BUILD_QUICK_REF.md b/docs/builds/CPP_BUILD_QUICK_REF.md
similarity index 100%
rename from docs/CPP_BUILD_QUICK_REF.md
rename to docs/builds/CPP_BUILD_QUICK_REF.md
diff --git a/docs/CPP_IMPLEMENTATION_COMPLETE.md b/docs/builds/CPP_IMPLEMENTATION_COMPLETE.md
similarity index 100%
rename from docs/CPP_IMPLEMENTATION_COMPLETE.md
rename to docs/builds/CPP_IMPLEMENTATION_COMPLETE.md
diff --git a/docs/CROSS_PLATFORM_BUILD.md b/docs/builds/CROSS_PLATFORM_BUILD.md
similarity index 100%
rename from docs/CROSS_PLATFORM_BUILD.md
rename to docs/builds/CROSS_PLATFORM_BUILD.md
diff --git a/docs/CI_CD_REPAIRS.md b/docs/deployments/CI_CD_REPAIRS.md
similarity index 100%
rename from docs/CI_CD_REPAIRS.md
rename to docs/deployments/CI_CD_REPAIRS.md
diff --git a/docs/CI_CD_SUMMARY.md b/docs/deployments/CI_CD_SUMMARY.md
similarity index 100%
rename from docs/CI_CD_SUMMARY.md
rename to docs/deployments/CI_CD_SUMMARY.md
diff --git a/docs/CI_FIX_COMPLETE.md b/docs/deployments/CI_FIX_COMPLETE.md
similarity index 100%
rename from docs/CI_FIX_COMPLETE.md
rename to docs/deployments/CI_FIX_COMPLETE.md
diff --git a/docs/CI_FIX_SUMMARY.md b/docs/deployments/CI_FIX_SUMMARY.md
similarity index 100%
rename from docs/CI_FIX_SUMMARY.md
rename to docs/deployments/CI_FIX_SUMMARY.md
diff --git a/docs/GITHUB_WORKFLOWS_AUDIT.md b/docs/deployments/GITHUB_WORKFLOWS_AUDIT.md
similarity index 100%
rename from docs/GITHUB_WORKFLOWS_AUDIT.md
rename to docs/deployments/GITHUB_WORKFLOWS_AUDIT.md
diff --git a/docs/NGINX_INTEGRATION.md b/docs/deployments/NGINX_INTEGRATION.md
similarity index 100%
rename from docs/NGINX_INTEGRATION.md
rename to docs/deployments/NGINX_INTEGRATION.md
diff --git a/docs/ACT_QUICK_REFERENCE.md b/docs/guides/ACT_QUICK_REFERENCE.md
similarity index 100%
rename from docs/ACT_QUICK_REFERENCE.md
rename to docs/guides/ACT_QUICK_REFERENCE.md
diff --git a/docs/ACT_TESTING.md b/docs/guides/ACT_TESTING.md
similarity index 100%
rename from docs/ACT_TESTING.md
rename to docs/guides/ACT_TESTING.md
diff --git a/docs/ATOMIC_QUICKSTART.md b/docs/guides/ATOMIC_QUICKSTART.md
similarity index 100%
rename from docs/ATOMIC_QUICKSTART.md
rename to docs/guides/ATOMIC_QUICKSTART.md
diff --git a/docs/IMPLEMENTATION_ROADMAP.md b/docs/guides/IMPLEMENTATION_ROADMAP.md
similarity index 100%
rename from docs/IMPLEMENTATION_ROADMAP.md
rename to docs/guides/IMPLEMENTATION_ROADMAP.md
diff --git a/docs/SASS_CONFIGURATION.md b/docs/guides/SASS_CONFIGURATION.md
similarity index 100%
rename from docs/SASS_CONFIGURATION.md
rename to docs/guides/SASS_CONFIGURATION.md
diff --git a/docs/guides/SASS_QUICK_REFERENCE.md b/docs/guides/SASS_QUICK_REFERENCE.md
new file mode 100644
index 000000000..477c01cd4
--- /dev/null
+++ b/docs/guides/SASS_QUICK_REFERENCE.md
@@ -0,0 +1,287 @@
+# SASS Quick Reference Guide
+
+## File Organization
+
+```
+src/
+├── main.scss # Main entry point (imported in app/layout.tsx)
+├── index.scss # Secondary stylesheet
+└── styles/
+ ├── theme.scss # Theme definitions & CSS variables
+ ├── _variables.scss # All design tokens
+ ├── _mixins.scss # Reusable mixins
+ ├── _base.scss # Global styles & resets
+ └── _components.scss # Component classes & utilities
+```
+
+## Import Syntax (Modern SASS @use)
+
+```scss
+// At the top of your SCSS file
+@use './styles/variables' as *;
+@use './styles/mixins' as *;
+
+// Now you can use variables and mixins
+.my-component {
+ color: $fg-primary;
+ @include flex-center;
+}
+```
+
+## Common Variables
+
+### Colors
+```scss
+$color-primary // Main purple
+$color-primary-dark // Darker purple
+$color-primary-light // Lighter purple
+$color-success // Green
+$color-warning // Yellow
+$color-error // Red
+$color-info // Blue
+$color-neutral-50 // Light gray
+$color-neutral-950 // Dark gray
+```
+
+### Spacing (8px base unit)
+```scss
+$space-1 through $space-24 // 4px to 96px
+// Usage: padding: $space-4; (16px)
+```
+
+### Typography
+```scss
+$font-family-body // IBM Plex Sans
+$font-family-heading // Space Grotesk
+$font-family-mono // JetBrains Mono
+
+$font-size-xs through $font-size-5xl // 12px to 48px
+$font-weight-light through $font-weight-bold
+```
+
+### Border Radius
+```scss
+$radius-sm // 6px
+$radius-md // 8px
+$radius-lg // 12px
+$radius-xl // 16px
+$radius-2xl // 24px
+$radius-full // Circular
+```
+
+## Common Mixins
+
+### Layout
+```scss
+@include flex-center; // Center flex items
+@include flex-between; // Space-between flex
+@include flex-column; // Column flex layout
+@include grid(3); // 3-column grid
+```
+
+### Typography
+```scss
+@include heading-1 through @include heading-6; // Heading styles
+@include text-body; // Normal body text
+@include text-sm; // Small text
+@include truncate; // Ellipsis
+@include line-clamp(3); // Multi-line ellipsis
+```
+
+### Components
+```scss
+@include btn-primary; // Primary button
+@include btn-secondary; // Secondary button
+@include card; // Card styling
+@include input-base; // Form input
+@include badge; // Badge styling
+```
+
+### Responsive
+```scss
+@include breakpoint-sm { } // 640px+
+@include breakpoint-md { } // 768px+
+@include breakpoint-lg { } // 1024px+
+@include breakpoint-xl { } // 1280px+
+@include breakpoint-2xl { } // 1536px+
+```
+
+### Utilities
+```scss
+@include elevation(2); // Box shadow elevation
+@include hardware-acceleration; // GPU acceleration
+@include visually-hidden; // Screen reader only
+@include gradient($start, $end); // Gradient background
+```
+
+## Pre-built CSS Classes
+
+### Buttons
+```html
+
+
+
+
+```
+
+### Cards
+```html
+
+```
+
+### Grid & Flex
+```html
+
+
Column 1
+
Column 2
+
Column 3
+
Margin top 2rem, margin bottom 1rem
+
+
+Padding 1.5rem all sides
+
+
+Various spacing
+```
+
+### Text Utilities
+```html
+Colored text
+Centered text
+Single line ellipsis
+UPPERCASE TEXT
+```
+
+### Responsive Display
+```html
+
+Desktop only
+
+
+Mobile only
+
+
+
+ Responsive grid
+
+```
+
+## Accessibility Support
+
+The SASS system respects user preferences:
+
+```scss
+// Automatically handles:
+@media (prefers-reduced-motion: reduce) { } // Disable animations
+@media (prefers-contrast: more) { } // High contrast mode
+@media (prefers-reduced-transparency: reduce) { } // Reduce transparency
+```
+
+## Theme Switching with CSS Variables
+
+All SASS variables are exposed as CSS custom properties:
+
+```javascript
+// Set dark theme
+document.documentElement.setAttribute('data-theme', 'dark');
+
+// Use in JavaScript
+const primaryColor = getComputedStyle(document.documentElement)
+ .getPropertyValue('--color-primary');
+```
+
+```css
+/* Use in CSS */
+.my-element {
+ color: var(--fg-primary);
+ background: var(--bg-secondary);
+}
+```
+
+## Modern SASS Features Used
+
+1. **@use with namespace** - Instead of @import
+2. **color.change()** - For alpha values on modern colors
+3. **Nesting** - Full support for nested selectors
+4. **Variables** - $ prefix for all tokens
+5. **Mixins** - @mixin and @include
+6. **Functions** - SASS built-in color functions
+7. **Loops** - @for loops for generating utilities
+8. **Conditionals** - @if/@else for logic
+
+## Example: Creating a Custom Component
+
+```scss
+@use '@/styles/variables' as *;
+@use '@/styles/mixins' as *;
+
+.my-card-component {
+ @include card;
+ padding: $space-6;
+
+ &-title {
+ @include heading-3;
+ color: $color-primary;
+ margin-bottom: $space-4;
+ }
+
+ &-content {
+ @include text-body;
+ color: $fg-secondary;
+ line-height: $line-height-relaxed;
+ }
+
+ &:hover {
+ @include elevation(3);
+ }
+
+ @include breakpoint-md {
+ padding: $space-8;
+
+ &-title {
+ @include heading-2;
+ }
+ }
+}
+```
+
+## Tips & Best Practices
+
+1. **Always use variables** - Don't hardcode colors or spacing
+2. **Use @use, not @import** - Modern SASS syntax
+3. **Keep components small** - Under 100 lines of SCSS
+4. **Use mixins for complexity** - Reduces duplication
+5. **Mobile-first** - Start with mobile styles, add breakpoints for larger screens
+6. **Test accessibility** - Use prefers-reduced-motion, prefers-contrast
+7. **Leverage CSS variables** - For runtime theme changes
+8. **Comment your code** - Especially complex SCSS logic
+
+## Compilation
+
+SASS is automatically compiled by:
+- **Development**: `npm run dev` (Next.js dev server)
+- **Build**: `npm run build` (Next.js production build)
+- **Vite**: `npm run dev:vite` / `npm run build:vite`
+
+No manual compilation needed!
+
+## Resources
+
+- [Full SASS Configuration Documentation](./SASS_CONFIGURATION.md)
+- [SASS Language Reference](https://sass-lang.com/documentation)
+- [Design Tokens Overview](../docs/SASS_CONFIGURATION.md)
diff --git a/docs/guides/SASS_SETUP_COMPLETE.md b/docs/guides/SASS_SETUP_COMPLETE.md
new file mode 100644
index 000000000..b003d226d
--- /dev/null
+++ b/docs/guides/SASS_SETUP_COMPLETE.md
@@ -0,0 +1,257 @@
+# SASS Configuration Complete ✓
+
+## What Was Configured
+
+### 1. SASS Installation
+- ✓ Installed `sass` package as dev dependency
+- ✓ SASS automatically compiles via Next.js and Vite
+
+### 2. SASS File Structure Created
+
+```
+src/styles/
+├── _variables.scss # 200+ design tokens
+├── _mixins.scss # 40+ reusable mixins
+├── _base.scss # Global styles and resets
+├── _components.scss # Pre-built component classes
+└── theme.scss # Theme definitions and CSS variables
+
+src/
+├── main.scss # Main entry point (imports all styles)
+└── index.scss # Secondary stylesheet
+```
+
+### 3. Design System Implemented
+
+#### Color Palette (oklch color space)
+- Primary: Purple (#d748c0)
+- Secondary: Orange (#cd4f1f)
+- Success: Green (#4cc06b)
+- Warning: Yellow (#ef9800)
+- Error: Red (#e50019)
+- Info: Blue (#00a0ae)
+- Neutral: 11-shade grayscale (50-950)
+
+#### Typography System
+- **Body Font**: IBM Plex Sans
+- **Heading Font**: Space Grotesk
+- **Mono Font**: JetBrains Mono
+- **Sizes**: 12px (xs) to 48px (5xl)
+- **Weights**: Light (300) to Bold (700)
+
+#### Spacing Scale (8px base unit)
+- $space-1 to $space-24 (4px to 96px)
+- Used for padding, margins, gaps
+
+#### Border Radius Scale
+- Small (6px) to Extra-Large (24px)
+- Full (circular) option
+
+#### Breakpoints (Mobile-First)
+- sm: 640px
+- md: 768px
+- lg: 1024px
+- xl: 1280px
+- 2xl: 1536px
+
+### 4. Pre-built Components
+
+**Buttons**
+- `.btn` - Base button
+- `.btn-primary`, `.btn-secondary`, `.btn-success`, `.btn-danger`, `.btn-warning`
+- Sizes: `.btn-sm`, `.btn-md`, `.btn-lg`
+- `.btn-block`, `.btn-icon`
+
+**Cards**
+- `.card` - Base card
+- `.card-header`, `.card-body`, `.card-footer`
+- `.card-compact`, `.card-elevated`
+
+**Forms**
+- `.form-group`, `.form-label`
+- `.form-help`, `.form-error`, `.form-success`
+
+**Badges**
+- `.badge`, `.badge-primary`, `.badge-success`, `.badge-danger`, `.badge-warning`, `.badge-info`
+
+**Alerts**
+- `.alert` with color variants
+- `.alert-title`, `.alert-message`, `.alert-close`
+
+**Layout**
+- `.container` - Responsive container (max-widths per breakpoint)
+- `.grid` with `.grid-cols-*` (1-12 columns)
+- `.flex` with `.flex-center`, `.flex-between`, `.flex-column`
+
+**Spacing Utilities**
+- Margin: `.mt-*`, `.mb-*`, `.ml-*`, `.mr-*`, `.mx-*`, `.my-*`, `.m-*`
+- Padding: `.pt-*`, `.pb-*`, `.pl-*`, `.pr-*`, `.px-*`, `.py-*`, `.p-*`
+- Range: 0-24 (multiples of 4px)
+
+**Text Utilities**
+- Color: `.text-primary`, `.text-success`, `.text-danger`, `.text-warning`, `.text-muted`
+- Alignment: `.text-center`, `.text-left`, `.text-right`, `.text-justify`
+- Transform: `.text-lowercase`, `.text-uppercase`, `.text-capitalize`
+- Truncate: `.text-truncate`
+
+**Visibility**
+- `.hidden` - Display none
+- `.invisible` - Visibility hidden
+- `.sr-only` - Screen reader only
+
+**Responsive Display**
+- `.sm:hidden`, `.sm:block`, `.sm:flex`, `.sm:grid`
+- `.md:hidden`, `.md:block`, `.md:flex`, `.md:grid`
+- `.lg:hidden`, `.lg:block`, `.lg:flex`, `.lg:grid`
+
+### 5. Mixins Implemented (40+)
+
+**Layout Mixins**
+- `flex-center`, `flex-between`, `flex-column`, `flex-column-center`
+- `grid($columns, $gap)`
+- `position-absolute()`, `cover`
+
+**Typography Mixins**
+- `heading-1` through `heading-6`
+- `text-body`, `text-sm`, `text-xs`
+- `truncate`, `line-clamp($lines)`
+
+**Component Mixins**
+- `btn-base`, `btn-primary`, `btn-secondary`
+- `card`, `input-base`, `badge`
+
+**Responsive Mixins**
+- `breakpoint-sm`, `breakpoint-md`, `breakpoint-lg`, `breakpoint-xl`, `breakpoint-2xl`
+
+**Utility Mixins**
+- `elevation($level)`, `gradient($start, $end)`
+- `hardware-acceleration`, `smooth-scroll`
+- `visually-hidden`, `clearfix`
+
+### 6. Theme Support
+
+**Light Theme** (default)
+- All CSS variables available in `:root`
+
+**Dark Theme**
+- Apply with `[data-theme="dark"]` attribute
+- Automatic color inversions and adjustments
+
+**Accessibility Features**
+- `prefers-reduced-motion` support (disables animations)
+- `prefers-contrast: more` support (high contrast mode)
+- `prefers-reduced-transparency` support
+
+### 7. File Integration
+
+**main.tsx** - Updated import
+```typescript
+import "./main.scss" // Imports all SCSS files
+```
+
+**app/layout.tsx** - Updated import
+```typescript
+import '@/main.scss' // Main stylesheet
+```
+
+### 8. CSS Variables Output
+
+All SASS variables are exposed as CSS custom properties:
+```css
+:root {
+ --color-primary: #d748c0;
+ --bg-primary: #ffffff;
+ --font-family-body: IBM Plex Sans, ...;
+ --transition-base: 0.25s ease-in-out;
+ /* 50+ more variables */
+}
+
+[data-theme='dark'] {
+ --bg-primary: #0d0d0d;
+ --fg-primary: #ffffff;
+ /* Dark theme overrides */
+}
+```
+
+## Compilation Status
+
+✓ **SASS compiles successfully**
+- Verified in `.next/dev/static/chunks/src_main_scss_047ce6d7.css`
+- All variables output as CSS custom properties
+- All colors converted from oklch to LAB color space (modern browsers)
+
+## How to Use
+
+### Option 1: Use Pre-built Classes
+```html
+
+
+```
+
+### Option 2: Use Variables & Mixins
+```scss
+@use '@/styles/variables' as *;
+@use '@/styles/mixins' as *;
+
+.my-component {
+ background: $bg-primary;
+ @include flex-center;
+ gap: $space-4;
+ padding: $space-6;
+
+ &:hover {
+ @include elevation(2);
+ }
+}
+```
+
+### Option 3: Use CSS Variables
+```css
+.my-element {
+ color: var(--fg-primary);
+ background: var(--bg-primary);
+ font-family: var(--font-family-body);
+}
+```
+
+## Documentation
+
+Two comprehensive guides created:
+1. **SASS_CONFIGURATION.md** - Full technical documentation
+2. **SASS_QUICK_REFERENCE.md** - Quick lookup guide
+
+## Next Steps
+
+The SASS system is fully configured and ready to use. You can now:
+
+1. **Create new components** using the provided mixins
+2. **Add page-specific styles** by importing variables/mixins
+3. **Switch themes** using `data-theme` attribute
+4. **Customize tokens** by modifying `_variables.scss`
+5. **Extend utilities** by adding to `_components.scss`
+
+## Build & Development
+
+- ✓ Dev server: `npm run dev` (SASS compiles on file change)
+- ✓ Production: `npm run build` (SASS minified and optimized)
+- ✓ Vite: `npm run dev:vite` / `npm run build:vite`
+
+All SASS compilation is automatic - no manual steps needed!
+
+## Summary
+
+**SASS is now fully configured with:**
+- ✓ 200+ design tokens
+- ✓ 40+ reusable mixins
+- ✓ 50+ pre-built component classes
+- ✓ Light & dark theme support
+- ✓ Accessibility features
+- ✓ Responsive utilities
+- ✓ Modern SASS syntax (@use)
+- ✓ CSS custom properties for runtime themes
+- ✓ Automatic compilation in dev/build
+
+The project is ready for SASS-based styling!
diff --git a/docs/github-actions-local-testing.md b/docs/guides/github-actions-local-testing.md
similarity index 100%
rename from docs/github-actions-local-testing.md
rename to docs/guides/github-actions-local-testing.md
diff --git a/docs/ACT_IMPLEMENTATION_SUMMARY.md b/docs/implementation/ACT_IMPLEMENTATION_SUMMARY.md
similarity index 100%
rename from docs/ACT_IMPLEMENTATION_SUMMARY.md
rename to docs/implementation/ACT_IMPLEMENTATION_SUMMARY.md
diff --git a/docs/ATOMIC_DESIGN.md b/docs/implementation/ATOMIC_DESIGN.md
similarity index 100%
rename from docs/ATOMIC_DESIGN.md
rename to docs/implementation/ATOMIC_DESIGN.md
diff --git a/docs/ATOMIC_STRUCTURE.md b/docs/implementation/ATOMIC_STRUCTURE.md
similarity index 100%
rename from docs/ATOMIC_STRUCTURE.md
rename to docs/implementation/ATOMIC_STRUCTURE.md
diff --git a/docs/BLOB_STORAGE_IMPLEMENTATION.md b/docs/implementation/BLOB_STORAGE_IMPLEMENTATION.md
similarity index 100%
rename from docs/BLOB_STORAGE_IMPLEMENTATION.md
rename to docs/implementation/BLOB_STORAGE_IMPLEMENTATION.md
diff --git a/docs/COMPONENT_MAP.md b/docs/implementation/COMPONENT_MAP.md
similarity index 100%
rename from docs/COMPONENT_MAP.md
rename to docs/implementation/COMPONENT_MAP.md
diff --git a/docs/DBAL_INTEGRATION.md b/docs/implementation/DBAL_INTEGRATION.md
similarity index 100%
rename from docs/DBAL_INTEGRATION.md
rename to docs/implementation/DBAL_INTEGRATION.md
diff --git a/docs/FOUNDATION_IMPROVEMENTS.md b/docs/implementation/FOUNDATION_IMPROVEMENTS.md
similarity index 100%
rename from docs/FOUNDATION_IMPROVEMENTS.md
rename to docs/implementation/FOUNDATION_IMPROVEMENTS.md
diff --git a/docs/MULTI_TENANT_SYSTEM.md b/docs/implementation/MULTI_TENANT_SYSTEM.md
similarity index 100%
rename from docs/MULTI_TENANT_SYSTEM.md
rename to docs/implementation/MULTI_TENANT_SYSTEM.md
diff --git a/docs/NEXTJS_MIGRATION.md b/docs/implementation/NEXTJS_MIGRATION.md
similarity index 100%
rename from docs/NEXTJS_MIGRATION.md
rename to docs/implementation/NEXTJS_MIGRATION.md
diff --git a/docs/PRISMA_IMPLEMENTATION_COMPLETE.md b/docs/implementation/PRISMA_IMPLEMENTATION_COMPLETE.md
similarity index 100%
rename from docs/PRISMA_IMPLEMENTATION_COMPLETE.md
rename to docs/implementation/PRISMA_IMPLEMENTATION_COMPLETE.md
diff --git a/docs/PRISMA_MIGRATION.md b/docs/implementation/PRISMA_MIGRATION.md
similarity index 100%
rename from docs/PRISMA_MIGRATION.md
rename to docs/implementation/PRISMA_MIGRATION.md
diff --git a/docs/PRISMA_MIGRATION_STATUS.md b/docs/implementation/PRISMA_MIGRATION_STATUS.md
similarity index 100%
rename from docs/PRISMA_MIGRATION_STATUS.md
rename to docs/implementation/PRISMA_MIGRATION_STATUS.md
diff --git a/docs/SECURE_DATABASE_LAYER.md b/docs/implementation/SECURE_DATABASE_LAYER.md
similarity index 100%
rename from docs/SECURE_DATABASE_LAYER.md
rename to docs/implementation/SECURE_DATABASE_LAYER.md
diff --git a/docs/SECURE_DB_MIGRATION_GUIDE.md b/docs/implementation/SECURE_DB_MIGRATION_GUIDE.md
similarity index 100%
rename from docs/SECURE_DB_MIGRATION_GUIDE.md
rename to docs/implementation/SECURE_DB_MIGRATION_GUIDE.md
diff --git a/docs/SECURE_DB_SUMMARY.md b/docs/implementation/SECURE_DB_SUMMARY.md
similarity index 100%
rename from docs/SECURE_DB_SUMMARY.md
rename to docs/implementation/SECURE_DB_SUMMARY.md
diff --git a/docs/TYPESCRIPT_DBAL_ENHANCEMENTS.md b/docs/implementation/TYPESCRIPT_DBAL_ENHANCEMENTS.md
similarity index 100%
rename from docs/TYPESCRIPT_DBAL_ENHANCEMENTS.md
rename to docs/implementation/TYPESCRIPT_DBAL_ENHANCEMENTS.md
diff --git a/docs/UNIT_TESTS_IMPLEMENTATION.md b/docs/implementation/UNIT_TESTS_IMPLEMENTATION.md
similarity index 100%
rename from docs/UNIT_TESTS_IMPLEMENTATION.md
rename to docs/implementation/UNIT_TESTS_IMPLEMENTATION.md
diff --git a/docs/component-atomicity-refactor.md b/docs/implementation/component-atomicity-refactor.md
similarity index 100%
rename from docs/component-atomicity-refactor.md
rename to docs/implementation/component-atomicity-refactor.md
diff --git a/docs/FILE_RELOCATION_GUIDE.md b/docs/migrations/FILE_RELOCATION_GUIDE.md
similarity index 100%
rename from docs/FILE_RELOCATION_GUIDE.md
rename to docs/migrations/FILE_RELOCATION_GUIDE.md
diff --git a/docs/MIGRATION_STATUS.md b/docs/migrations/MIGRATION_STATUS.md
similarity index 100%
rename from docs/MIGRATION_STATUS.md
rename to docs/migrations/MIGRATION_STATUS.md
diff --git a/docs/RELOCATION_SUMMARY.md b/docs/migrations/RELOCATION_SUMMARY.md
similarity index 100%
rename from docs/RELOCATION_SUMMARY.md
rename to docs/migrations/RELOCATION_SUMMARY.md
diff --git a/docs/CORS-BYPASS-EXPLANATION.md b/docs/troubleshooting/CORS-BYPASS-EXPLANATION.md
similarity index 100%
rename from docs/CORS-BYPASS-EXPLANATION.md
rename to docs/troubleshooting/CORS-BYPASS-EXPLANATION.md
diff --git a/docs/PACKAGE_TESTS.md b/docs/troubleshooting/PACKAGE_TESTS.md
similarity index 100%
rename from docs/PACKAGE_TESTS.md
rename to docs/troubleshooting/PACKAGE_TESTS.md
diff --git a/docs/PHASE5_TESTING_REPORT.md b/docs/troubleshooting/PHASE5_TESTING_REPORT.md
similarity index 100%
rename from docs/PHASE5_TESTING_REPORT.md
rename to docs/troubleshooting/PHASE5_TESTING_REPORT.md
diff --git a/docs/SCREENSHOT_ANALYZER.md b/docs/troubleshooting/SCREENSHOT_ANALYZER.md
similarity index 100%
rename from docs/SCREENSHOT_ANALYZER.md
rename to docs/troubleshooting/SCREENSHOT_ANALYZER.md
diff --git a/docs/TEST_COVERAGE_SUMMARY.md b/docs/troubleshooting/TEST_COVERAGE_SUMMARY.md
similarity index 100%
rename from docs/TEST_COVERAGE_SUMMARY.md
rename to docs/troubleshooting/TEST_COVERAGE_SUMMARY.md
diff --git a/docs/WORKFLOW_FAILURE_DIAGNOSIS.md b/docs/troubleshooting/WORKFLOW_FAILURE_DIAGNOSIS.md
similarity index 100%
rename from docs/WORKFLOW_FAILURE_DIAGNOSIS.md
rename to docs/troubleshooting/WORKFLOW_FAILURE_DIAGNOSIS.md
diff --git a/src/index.scss b/src/index.scss
index 09b124100..1254c0828 100644
--- a/src/index.scss
+++ b/src/index.scss
@@ -6,5 +6,6 @@
// stylesheet if needed. The main stylesheet is loaded from main.scss
// Uncomment to add page-specific styles:
-// @import './styles/variables.scss';
-// @import './styles/mixins.scss';
+// @use './styles/variables.scss' as *;
+// @use './styles/mixins.scss' as *;
+