docs: improve documentation clarity and fix inconsistencies

[claudeaceae]

Summary

This PR improves the documentation by fixing inconsistencies and adding clarity around environment variable setup.

Changes Made

1. Fixed environment variable inconsistency

   • README.md previously used BETTER_AUTH_URL while CONTRIBUTING.md and .env.example use NEXT_PUBLIC_BETTER_AUTH_URL
   • Updated README.md to use the correct variable name

2. Added optional environment variables section

   • Separated required vs optional variables in both README.md and CONTRIBUTING.md
   • Documented Freesound API setup (for audio library feature)
   • Documented Cloudflare R2 and Modal transcription setup (for auto-captions feature)
   • Added links to setup instructions in apps/transcription/README.md

3. Fixed typo

   • Fixed "accoumt" → "account" in apps/transcription/README.md

Why These Changes?

These changes help new contributors:

• Avoid confusion about which environment variables are actually required
• Understand what optional features exist and how to enable them
• Get up and running faster with a minimal setup
• Know where to find additional documentation for advanced features

Addresses

This partially addresses issue #10 by improving the getting started documentation.

---

Note: All changes are documentation-only. No code changes included.

Summary by CodeRabbit

• Documentation
  • Added new environment variables for Marble Blog integration support
  • Introduced optional variables section for advanced features (Freesound, Cloudflare R2, Modal transcription)
  • Updated development setup documentation with clearer configuration examples
  • Fixed typo in transcription guide

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[netlify]

👷 Deploy request for appcut pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	f3bedbd

[vercel]

@claudeaceae is attempting to deploy a commit to the OpenCut OSS Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Walkthrough

Documentation files updated to clarify environment variables. Root README changes BETTER_AUTH_URL to NEXT_PUBLIC_BETTER_AUTH_URL and adds optional variables section for advanced features. Contributing guide receives new environment variable sections. Transcription README typo corrected.

Changes

Cohort / File(s)	Summary
Environment Variable Documentation .github/CONTRIBUTING.md, README.md	Added new environment variable sections for Marble Blog (MARBLE_WORKSPACE_KEY, NEXT_PUBLIC_MARBLE_API_URL) and optional advanced features (Freesound, Cloudflare R2, Modal transcription endpoints). Root README replaces BETTER_AUTH_URL with NEXT_PUBLIC_BETTER_AUTH_URL for local development.
Transcription Documentation apps/transcription/README.md	Fixed typo in step 5: "Modal accoumt" corrected to "Modal account".

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

• Changes are documentation-only with no code logic or control flow modifications
• Straightforward additions to environment variable sections and a single typo fix
• Minimal file spread with homogeneous, non-functional updates

Possibly related PRs

• fix: marble env keys in readme #403: Updates Marble Blog environment variable documentation (MARBLE_WORKSPACE_KEY, NEXT_PUBLIC_MARBLE_API_URL)
• Add BETTER_AUTH_SECRET and BETTER_AUTH_URL env vars to build job #318: Modifies BETTER_AUTH_URL usage in CI workflows, complementing the public/private variable distinction changes
• feat: add blog powered by marble #402: Adds Marble blog feature implementation, which these documentation updates support

Poem

🐰 Environment vars now clarified and bright,
Marble and Freesound in docs—what a delight!
BETTER_AUTH now wears its PUBLIC disguise,
Optional secrets help devs improvise,
One typo fixed (Modal's spelling now right)!

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers all key aspects: summary of changes, specific modifications made, rationale, and issue reference. However, it does not follow the repository's template structure with sections like Type of change, Testing, or Checklist.	Consider using the repository's standard PR description template with Type of change, How Has This Been Tested, and Checklist sections for consistency.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: improving documentation clarity and fixing inconsistencies, which aligns with the environment variable corrections and optional variables documentation added.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0173db9 and f3bedbd.

📒 Files selected for processing (3)

• .github/CONTRIBUTING.md
• README.md
• apps/transcription/README.md

🧰 Additional context used

🪛 Gitleaks (8.30.0)

.github/CONTRIBUTING.md

[high] 112-112: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

README.md

[high] 118-118: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

🔇 Additional comments (6)

apps/transcription/README.md (1)

38-38: Typo fix is correct.

The correction from "accoumt" to "account" in the step heading is appropriate and improves documentation clarity.

.github/CONTRIBUTING.md (2)

111-113: Verify that the example organization key is safe.

The Marble Blog environment variables are well-documented with appropriate context. However, static analysis flagged the example key at line 112 as a potential API key exposure.

Please confirm that MARBLE_WORKSPACE_KEY=cm6ytuq9x0000i803v0isidst is a safe, non-functional example value and not an actual working credential. If this is a real credential, it should be rotated immediately and the example should be replaced with a truly dummy value (e.g., cm6ytuq9x0000i803v0isidst-example or similar).

---

119-137: Well-structured optional variables documentation.

The new Optional Variables section clearly documents advanced features (Freesound, Cloudflare R2, Modal transcription) with helpful setup links and contextual references. The organization and inline comments explaining where to obtain credentials follow good documentation practices.

README.md (3)

111-111: Critical inconsistency fix: BETTER_AUTH_URL correction is good.

Updating BETTER_AUTH_URL to NEXT_PUBLIC_BETTER_AUTH_URL aligns the README with CONTRIBUTING.md and .env.example, resolving a significant point of confusion for new contributors. This is the key change addressing the PR's inconsistency objective.

---

117-118: Verify that the example organization key is safe.

The clarification that MARBLE_WORKSPACE_KEY is optional for local development is helpful. However, static analysis flagged the example value at line 118 as a potential API key exposure.

Please confirm that MARBLE_WORKSPACE_KEY=cm6ytuq9x0000i803v0isidst is a safe, non-functional example value (the same value appears in CONTRIBUTING.md at line 112). If this is a real credential, it should be rotated immediately and replaced with a truly dummy value.

---

125-143: Optional Variables section enhances contributor experience.

The new Optional Variables block clearly documents advanced features (Freesound, Cloudflare R2, Modal transcription) with helpful setup links and contextual guidance. The consistent structure across README.md and CONTRIBUTING.md provides clarity on which features are optional and how to enable them.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}