Codebase overhaul

.cursor/rules/comments.mdc

@@ -0,0 +1,35 @@
+---
+alwaysApply: true
+---
+
+# Comment Guidelines
+
+## Good Comments (Human-style)
+- Explain WHY, not WHAT
+- Document non-obvious behavior or edge cases
+- Warn about performance implications or side effects
+- Explain business logic that isn't clear from code
+
+Examples:
+```javascript
+// transfer, not copy; sender buffer detaches
+// satisfies: check shape; keep literals  
+// keep multibyte across chunks
+// timingSafeEqual throws on length mismatch
+```
+
+## Bad Comments (AI-style)
+- Don't explain what the code literally does
+- Don't add changelog-style comments in code
+- Don't comment every line or obvious operations
+
+Avoid:
+```javascript
+// Prevent duplicate initialization
+// Check if project is already loaded  
+// Mark as initializing to prevent race conditions
+// (changed from blah to blah)
+```
+
+## Rule
+Only add comments when there's genuinely non-obvious behavior, performance considerations, or business logic that needs context. Code should be self-documenting through naming and structure.

.cursor/rules/handling-uncertainty.mdc

@@ -0,0 +1,21 @@
+---
+alwaysApply: true
+---
+
+# Handling Uncertainty
+
+## Principle
+If you can't confidently respond due to missing context, data access, or ambiguity (multiple interpretations), report it instead of guessing. Seek clarification to avoid errors.
+
+Apply when: query lacks details, no access to info/tools, or unclear intent.
+
+## How to Report
+1. **Description**: Why uncertain and what you need.
+2. **Questions**: 1-3 targeted ones.
+3. **Assumptions** (opt.): State if proceeding; omit otherwise.
+
+Direct and concise.
+
+**Assumptions**: None.
+
+Builds transparency.

.cursor/rules/readability.mdc

@@ -0,0 +1,9 @@
+---
+alwaysApply: true
+---
+
+# Readability First
+
+Optimize code for AI agents to understand and modify.
+
+Never abbreviate. `event` not `e`, `element` not `el`. If it's easy to read, it's correct. In this case, "config" is better than "configuration" because it's shorter and is **still very readable**. "El" is not very readable.

.cursor/rules/separation-of-concerns.mdc

@@ -0,0 +1,52 @@
+---
+alwaysApply: true
+---
+
+# Separation of Concerns
+
+## Core Principle
+
+Each file should have one single purpose/responsibility. Related functionality should be grouped together, unrelated functionality should be separated.
+
+## Good Separation
+
+- One file per major concern (auth, validation, data transformation)
+- Group related utilities together
+- Extract shared logic into dedicated files
+- Keep API routes focused on their specific endpoint logic
+
+Examples:
+
+```javascript
+// ✅ Good: Each file has clear responsibility
+/lib/rate-limit.ts          // Rate limiting utilities
+/lib/validation.ts          // Input validation schemas
+/lib/freesound-api.ts       // External API integration
+/api/sounds/search/route.ts // Route handler only
+```
+
+## Bad Mixing of Concerns
+
+Avoid cramming multiple responsibilities into one file:
+
+```javascript
+// ❌ Bad: Route file doing everything
+/api/sounds/search/route.ts
+- Rate limiting logic
+- Validation schemas
+- API transformation
+- External API calls
+- Response formatting
+- Error handling utilities
+```
+
+## When to Separate
+
+- File is getting long (>500 lines)
+- Multiple distinct responsibilities in one file
+- Logic could be reused elsewhere
+- Complex utilities that distract from main purpose
+
+## Rule
+
+One file, one responsibility. Extract shared concerns into focused utility files

.cursor/rules/ultracite.mdc

@@ -6,7 +6,7 @@ alwaysApply: true
 
 # Project Context
 
-Ultracite enforces strict type safety, accessibility standards, and consistent code quality for JavaScript/TypeScript projects using Biome's lightning-fast formatter and linter.
+Ultracite enforces strict type safety, accessibility standards, and consistent code quality for JavaScript/TypeScript projects using Biome's formatter.
 
 ## Key Principles
 
@@ -43,7 +43,6 @@ Ultracite enforces strict type safety, accessibility standards, and consistent c
 ### React and JSX Best Practices
 
 - Don't import `React` itself.
-- Don't define React components inside other components.
 - Don't use both `children` and `dangerouslySetInnerHTML` props on the same element.
 - Don't insert comments as text nodes.
 - Use `<>...</>` instead of `<Fragment>...</Fragment>`.

.cursor/rules/writing-scannable-code.mdc

@@ -0,0 +1,53 @@
+---
+alwaysApply: true
+---
+
+# Scannable Code Guidelines/Separating Concerns.
+
+## Core Principle
+
+Code should be scannable through proper abstraction, not comments. Use variables and helper functions to make intent clear at a glance.
+
+## Good Scannable Code
+
+- Extract complex logic into well-named variables
+- Create helper functions for multi-step operations
+- Use descriptive names that explain intent
+
+Examples:
+
+```javascript
+// ✅ Scannable: Intent is clear from variable names
+const isValidUser = user.isActive && user.hasPermissions;
+const shouldProcessPayment = amount > 0 && !order.isPaid;
+
+// ✅ Scannable: Complex logic extracted to helper
+const searchParams = buildFreesoundSearchParams({ query, filters, pagination });
+const transformedResults = transformFreesoundResults({ rawResults });
+```
+
+## Bad Unscannable Code
+
+Avoid:
+
+```javascript
+// ❌ Hard to scan: What does this condition mean?
+if (type === "effects" || !type) {
+  params.append("filter", "duration:[* TO 30.0]");
+  params.append("filter", `avg_rating:[${min_rating} TO *]`);
+  if (commercial_only) {
+    params.append("filter", 'license:("Attribution" OR "Creative Commons 0")');
+  }
+}
+
+// ❌ Hard to scan: Complex ternary
+const sortParam = query
+  ? sort === "score"
+    ? "score"
+    : `${sort}_desc`
+  : `${sort}_desc`;
+```
+
+## Rule
+
+Make code scannable by extracting intent into variables and helper functions. If you need to think about what code does, extract it. The reader should understand the flow without diving into implementation details.

.github/CODE_OF_CONDUCT.md

@@ -17,23 +17,23 @@ diverse, inclusive, and healthy community.
 Examples of behavior that contributes to a positive environment for our
 community include:
 
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes,
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
   and learning from the experience
-* Focusing on what is best not just for us as individuals, but for the overall
+- Focusing on what is best not just for us as individuals, but for the overall
   community
 
 Examples of unacceptable behavior include:
 
-* The use of sexualized language or imagery, and sexual attention or advances of
+- The use of sexualized language or imagery, and sexual attention or advances of
   any kind
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or email address,
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
   without their explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Enforcement Responsibilities

.github/CONTRIBUTING.md

@@ -98,11 +98,11 @@ If you're unsure whether your idea falls into the preview category, feel free to
 
    ```bash
    # Database (matches docker-compose.yaml)
-   DATABASE_URL="postgresql://opencut:opencutthegoat@localhost:5432/opencut"
+   DATABASE_URL="postgresql://opencut:opencut@localhost:5432/opencut"
 
    # Generate a secure secret for Better Auth
    BETTER_AUTH_SECRET="your-generated-secret-here"
-   NEXT_PUBLIC_BETTER_AUTH_URL="http://localhost:3000"
+   NEXT_PUBLIC_SITE_URL="http://localhost:3000"
 
    # Redis (matches docker-compose.yaml)
    UPSTASH_REDIS_REST_URL="http://localhost:8079"

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,6 +1,6 @@
 name: Bug report
 description: Create a report to help us improve
-title: '[BUG] '
+title: "[BUG] "
 labels: bug
 body:
   - type: input
@@ -15,7 +15,7 @@ body:
     id: Browser
     attributes:
       label: Browser
-      description:  Please enter the browser on which you encountered the bug.
+      description: Please enter the browser on which you encountered the bug.
       placeholder: e.g. Chrome 137, Firefox 137, Safari 17
     validations:
       required: true
@@ -67,4 +67,4 @@ body:
 
         Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
     validations:
-      required: false
+      required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,6 +1,6 @@
 name: Feature request
 description: Suggest an idea for OpenCut
-title: '[FEATURE] '
+title: "[FEATURE] "
 labels: enhancement
 body:
   - type: markdown
@@ -39,4 +39,4 @@ body:
 
         Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
     validations:
-      required: false
+      required: false

.github/SECURITY.md

@@ -25,4 +25,4 @@ Please do not report security vulnerabilities through public GitHub issues.
 - We will provide a detailed response within 5 business days
 - We will keep you updated on our progress
 
-Thank you for helping keep OpenCut secure! 
+Thank you for helping keep OpenCut secure!

.github/SUPPORT.md

@@ -3,21 +3,25 @@
 Thanks for using OpenCut! If you need help, here are your options:
 
 ## Documentation
+
 - Check our [README](../README.md) for basic setup instructions
 - Review the [Contributing Guidelines](CONTRIBUTING.md) for development setup
 
 ## Issues
+
 - **Bug reports**: Use the bug report template
 - **Feature requests**: Use the feature request template
 - **Questions**: Use GitHub Discussions for general questions
 
 ## Community
+
 - Join our discussions on GitHub
 - Follow the [Code of Conduct](CODE_OF_CONDUCT.md)
 
 ## Response Times
+
 - Issues are typically triaged within 2-3 business days
 - Feature requests may take longer to evaluate
 - Security issues are handled with priority
 
-We appreciate your patience and contributions to making OpenCut better! 
+We appreciate your patience and contributions to making OpenCut better!