refactor: anti-pattern fixes and UI improvements

.claude/commands/commit.md

@@ -0,0 +1,8 @@
+Break up our uncommitted changes into smaller, descriptive commits, addressing any pre-commit hook issues as you go.
+
+Rules:
+- Each commit should be one logical change (one feature, one fix, one refactor)
+- Use conventional commit prefixes: feat:, fix:, refactor:, chore:, docs:, style:
+- Imperative mood, lowercase, no period
+- Never bundle unrelated changes
+- If pre-commit hooks fail, fix the issue and create a NEW commit (don't amend)

.claude/rules/api.md

@@ -0,0 +1,16 @@
+---
+paths:
+  - "src/routes/api/**/*.ts"
+---
+
+# API Route Rules
+
+- All API routes are `+server.ts` files returning JSON
+- Authenticated endpoints validate session cookie — return 401 if missing/invalid
+- Use Drizzle ORM for all queries — never raw SQL strings
+- IDs are UUIDs (text type), timestamps are Unix epoch integers
+- Follow existing patterns in the codebase for error responses
+- SMS inbound endpoint (`/api/sms/inbound`) must validate Twilio request signatures
+- Video serving endpoints must support Range headers (206 Partial Content)
+- Reference: docs/api.md for full endpoint documentation
+- Reference: docs/data-model.md for schema and relationships

.claude/rules/security.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "src/routes/api/**/*.ts"
+  - "src/lib/server/**/*.ts"
+---
+
+# Security Rules
+
+- Never hardcode secrets, API keys, or tokens — always use environment variables
+- Validate and sanitize all user input at API boundaries
+- Use parameterized queries only (Drizzle handles this — never bypass with raw SQL)
+- Error responses must not leak stack traces, file paths, or internal state
+- Twilio webhook endpoints must validate request signatures
+- Auth cookies: httpOnly, secure, sameSite=strict

.claude/rules/server.md

@@ -0,0 +1,14 @@
+---
+paths:
+  - "src/lib/server/**/*.ts"
+---
+
+# Server Module Rules
+
+- Server-only code lives in `src/lib/server/` — SvelteKit enforces this boundary
+- Database access: use Drizzle ORM schema from `src/lib/server/db/schema.ts`
+- Video downloads: pluggable provider system via `src/lib/server/providers/` + orchestration in `src/lib/server/video/`
+- SMS: Twilio SDK wrapper in `src/lib/server/sms/`
+- Push: web-push with VAPID keys via `src/lib/server/push.ts`
+- Auth: session management via signed httpOnly cookies
+- Never expose server modules to client code

.claude/rules/styling.md

@@ -0,0 +1,19 @@
+---
+paths:
+  - "src/**/*.svelte"
+  - "src/**/*.css"
+---
+
+# Styling Rules
+
+- Use CSS custom properties for ALL colors — `var(--bg-primary)`, `var(--text-secondary)`, etc.
+- NEVER hardcode color values like `#000`, `#fff`, `rgb()`, `rgba()` in component styles
+- Exception: `rgba(0,0,0,X)` / `rgba(255,255,255,X)` for overlays on video content only
+- Theme switches via `[data-theme]` attribute — styles must work in both light and dark mode
+- Mobile-first: base styles target `375px`, use `min-width` media queries to scale up
+- Max content width: `520px` centered
+- Touch targets: minimum `44px` x `44px`
+- Use `100dvh` not `100vh` for viewport height
+- Use spacing tokens: `--space-xs` through `--space-3xl`
+- Use radius tokens: `--radius-sm` through `--radius-full`
+- Full design system reference: docs/design-guidelines.md

.claude/rules/svelte.md

@@ -0,0 +1,16 @@
+---
+paths:
+  - "src/**/*.svelte"
+---
+
+# Svelte Component Rules
+
+- Use Svelte 5 runes exclusively: `$state`, `$props`, `$effect`, `$derived`, `$bindable`
+- NEVER use legacy patterns: `let` for reactive vars, `export let` for props, `$:` reactive blocks, `$$props`, `$$restProps`
+- Use `{#snippet}` blocks instead of `<slot>` for component composition
+- Component props: `let { prop1, prop2 } = $props()`
+- State: `let count = $state(0)` — not `let count = 0`
+- Derived values: `let doubled = $derived(count * 2)` — not `$: doubled = count * 2`
+- Event handlers: use `onclick={handler}` — not `on:click={handler}`
+- Scoped `<style>` block in every component — never import external CSS
+- All colors via CSS custom properties (`var(--token)`) — never hardcode hex

.claude/rules/testing.md

@@ -0,0 +1,16 @@
+---
+paths:
+  - "src/**/*.test.ts"
+  - "src/**/*.spec.ts"
+---
+
+# Testing Rules
+
+- Test framework: Vitest
+- Run tests: `npm run test`
+- Run with coverage: `npm run test:coverage`
+- Watch mode: `npm run test:watch`
+- Place test files alongside source files (co-located)
+- Use descriptive test names that explain the expected behavior
+- Prefer running single test files (`npx vitest run path/to/file.test.ts`) over the full suite
+- When fixing a bug, write a failing test first, then fix

.claude/settings.json

@@ -1,6 +1,46 @@
 {
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "attribution": {
     "commit": "",
     "pr": ""
+  },
+  "permissions": {
+    "allow": [
+      "Bash(npm run dev)",
+      "Bash(npm run build)",
+      "Bash(npm run test *)",
+      "Bash(npm run test)",
+      "Bash(npm run check *)",
+      "Bash(npm run check)",
+      "Bash(npm run lint *)",
+      "Bash(npm run lint)",
+      "Bash(npm run format *)",
+      "Bash(npm run format)",
+      "Bash(npx drizzle-kit *)",
+      "Bash(npx svelte-kit sync)",
+      "Bash(git status *)",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git branch *)",
+      "Bash(git checkout *)",
+      "Bash(git switch *)",
+      "Bash(git stash *)",
+      "Bash(git show *)"
+    ],
+    "deny": [
+      "Read(.env)",
+      "Edit(.env)",
+      "Read(.env.local)",
+      "Edit(.env.local)",
+      "Read(.env.production)",
+      "Edit(.env.production)",
+      "Read(data/**)"
+    ]
+  },
+  "enabledPlugins": {
+    "typescript-lsp@claude-plugins-official": true,
+    "svelte-skills@svelte-skills-kit": true
   }
 }

.claudeignore

@@ -0,0 +1,43 @@
+# Dependencies
+node_modules/
+
+# Build output
+.output/
+/.svelte-kit/
+/build/
+/dist/
+
+# Runtime data (DB + videos)
+/data/
+
+# Secrets
+.env
+.env.*
+!.env.example
+!.env.test
+*.pem
+*.key
+
+# Lock files (large, low signal)
+package-lock.json
+
+# Coverage & debug
+/coverage/
+/.codeql-db/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Editor
+.idea/
+.vscode/
+
+# Git internals
+.git/
+
+# Inspiration images (large binaries)
+docs/inspo/

.env.example

@@ -1,7 +1,13 @@
-# Session signing secret (generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
+# ============================================================================
+# SECURITY: Keep this file private. Never commit a filled-out .env to git.
+# ============================================================================
+
+# Session signing secret — REQUIRED, must be unique per instance
+# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 SESSION_SECRET=
 
-# Twilio
+# Twilio — credentials for SMS verification and inbound clip sharing
+# Keep these secret. Rotate if compromised.
 TWILIO_ACCOUNT_SID=
 TWILIO_AUTH_TOKEN=
 TWILIO_VERIFY_SERVICE_SID=
@@ -13,7 +19,8 @@ VERIFY_CHANNELS=sms
 # Set to "true" to bypass Twilio and auto-approve any verification code (dev/testing only)
 SMS_DEV_MODE=false
 
-# Web Push VAPID keys (generate with: npx web-push generate-vapid-keys)
+# Web Push VAPID keys — generate a unique pair per instance
+# Generate with: npx web-push generate-vapid-keys
 VAPID_PUBLIC_KEY=
 VAPID_PRIVATE_KEY=
 VAPID_SUBJECT=mailto:you@example.com
@@ -22,6 +29,24 @@ VAPID_SUBJECT=mailto:you@example.com
 # Must match the public URL users access (e.g. https://scrolly.example.com)
 PUBLIC_APP_URL=http://localhost:3000
 
-# iOS Shortcut (optional — iCloud link to a pre-built Shortcut for share sheet integration)
-# Create the shortcut manually, share via iCloud, and paste the link here
-SHORTCUT_ICLOUD_URL=
+# Data directory (optional — defaults to ./data)
+# DATA_DIR=./data
+
+# Giphy API key (optional — enables GIF search in comments)
+# Get one at https://developers.giphy.com/
+GIPHY_API_KEY=
+
+# Legal pages (optional — shown in SMS consent text on join/onboard screens)
+# Self-hosted operators should provide their own Terms and Privacy Policy URLs
+# Required by Twilio/CTIA for SMS verification compliance
+PUBLIC_TERMS_URL=
+PUBLIC_PRIVACY_URL=
+
+# Logging (optional — trace, debug, info, warn, error, fatal. Default: info)
+# LOG_LEVEL=info
+
+# Database backups (optional — number of daily backups to keep. Default: 7)
+# BACKUP_RETENTION_COUNT=7
+
+# Domain for Caddy HTTPS (used with docker-compose.caddy.yml)
+# DOMAIN=scrolly.example.com

.github/CODEOWNERS

@@ -1,10 +1,10 @@
 # Default owner for everything
-* @GraysonCAdams
+* @312-dev
 
 # Security-sensitive files
-/.github/workflows/ @GraysonCAdams
-/.github/codeql/ @GraysonCAdams
-/src/lib/server/auth/ @GraysonCAdams
-/src/lib/server/db/ @GraysonCAdams
-/Dockerfile @GraysonCAdams
-/SECURITY.md @GraysonCAdams
+/.github/workflows/ @312-dev
+/.github/codeql/ @312-dev
+/src/lib/server/auth/ @312-dev
+/src/lib/server/db/ @312-dev
+/Dockerfile @312-dev
+/SECURITY.md @312-dev

.github/ISSUE_TEMPLATE/bug_report.md

@@ -2,7 +2,7 @@
 name: Bug Report
 about: Report a bug to help us improve
 title: '[BUG] '
-labels: bug
+labels: 'type: bug', 'needs triage'
 ---
 
 ## Describe the Bug

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: true
 contact_links:
   - name: Security Vulnerability
-    url: https://github.com/graysoncadams/scrolly/security/advisories/new
+    url: https://github.com/312-dev/scrolly/security/advisories/new
     about: Report a security vulnerability privately

.github/ISSUE_TEMPLATE/feature_request.md

@@ -2,7 +2,7 @@
 name: Feature Request
 about: Suggest a new feature or improvement
 title: '[FEATURE] '
-labels: enhancement
+labels: 'type: feature', 'needs triage'
 ---
 
 ## Problem Statement

.github/release.yml

@@ -0,0 +1,14 @@
+changelog:
+  categories:
+    - title: "Features"
+      labels: ["enhancement", "feature"]
+    - title: "Bug Fixes"
+      labels: ["bug", "fix"]
+    - title: "Dependencies"
+      labels: ["dependencies"]
+    - title: "Documentation"
+      labels: ["documentation"]
+    - title: "Other Changes"
+      labels: ["*"]
+  exclude:
+    labels: ["skip-changelog"]

.github/workflows/ci.yml

@@ -1,11 +1,17 @@
+# NOTE: Branch protection should require the "ci" job to pass before merge.
+# Configure in GitHub: Settings > Branches > Branch protection rules > main
+#   - Require status checks: ci
+#   - Require branches to be up to date before merging
+
 name: CI
 
 on:
   push:
     branches: [main]
+    paths-ignore: ['docs/**', '*.md']
   pull_request:
     branches: [main]
-    paths-ignore: ['*.md']
+    paths-ignore: ['docs/**', '*.md']
   workflow_dispatch:
 
 concurrency:
@@ -22,16 +28,22 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: npm
 
       - name: Install dependencies
         run: npm ci
 
+      - name: Validate commit messages
+        if: github.event_name == 'pull_request'
+        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose
+
       - name: Lint (ratcheted)
         run: npm run lint:ci
 
@@ -41,12 +53,8 @@ jobs:
       - name: Type check
         run: npm run type-check
 
-      - name: Unit tests
-        run: npm run test
-
-      - name: Coverage report
+      - name: Tests with coverage
         run: npm run test:coverage
-        continue-on-error: true
 
       - name: Upload coverage
         if: always()

.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,28 @@
+name: Dependabot Auto-Merge
+
+on:
+  pull_request:
+    paths:
+      - 'package*.json'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Auto-merge patch and minor updates
+        if: steps.metadata.outputs.update-type != 'version-update:semver-major'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}