codebase overhaul (#697)

.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.