chore(repo): update docs and refs to main (#1578)

## 🔍 Description

* Update docs and guides for contributors
* `main` was referenced as the default branch. Change to `master`.

Author: mandarini

.cursorrules

@@ -30,9 +30,11 @@ This monorepo contains 6 JavaScript/TypeScript libraries previously maintained a
 
 ### Testing
 - Test all: `nx run-many --target=test --all`
-- Test specific: `nx test auth-js`
-- Test affected: `nx affected --target=test`
+- Test specific: `nx test auth-js` (some packages may have special targets like `nx test:auth auth-js` or `nx test:storage storage-js`)
+- Test affected: `nx affected --target=test` (recommended for efficiency)
 - Integration tests: `nx run-many --target=test:integration --all`
+- Watch mode: `nx test <package> --watch`
+- Coverage: `nx test <package> --coverage`
 
 ### Code Quality
 - Lint all: `nx run-many --target=lint --all`
@@ -109,10 +111,12 @@ packages/core/[library-name]/
 
 ## Important Notes
 
-- **Different Default Branches**: Original repos used either `master` or `main` - be aware when referencing history
+- **Current Default Branch**: `master` (confirmed current default branch)
+- **Original Branch Differences**: Original repos used either `master` or `main` - be aware when referencing history
 - **Package Names**: All packages maintain original npm names (@supabase/[package-name])
 - **Shared Code**: Extract common patterns (HTTP client, error handling) to shared packages when identified
-- **Docker Required**: Integration tests for auth-js and storage-js require Docker to be running
+- **Docker Required**: Integration tests for auth-js, functions-js, postgrest-js, and storage-js require Docker to be running
+- **Special Test Commands**: Some packages may use special test targets (check individual package READMEs)
 
 ## Release Process
 
@@ -156,7 +160,10 @@ The `*` is replaced with actual version during release.
 
 1. Always consider the monorepo structure - changes might affect multiple packages
 2. Use Nx commands rather than npm/yarn directly for workspace operations
-3. Suggest running affected tests, not all tests, for better performance
-4. Remember that all packages version together in fixed mode
-5. Consider Docker requirements for integration tests
-6. Maintain backward compatibility at all costs
+3. Suggest running affected tests (`nx affected --target=test`), not all tests, for better performance
+4. Remember that all packages version together in fixed mode - no independent versioning
+5. Consider Docker requirements for integration tests (auth-js, functions-js, postgrest-js, storage-js)
+6. Maintain backward compatibility at all costs - breaking changes require special process
+7. Check for special test commands in package READMEs (some may use `test:auth`, `test:storage`, etc.)
+8. Always suggest conventional commit format with proper scope
+9. Prefer `nx affected` commands over `nx run-many` for efficiency

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -91,7 +91,7 @@ body:
       options:
         - label: Follow our [Code of Conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md)
           required: true
-        - label: Read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/main/CONTRIBUTING.md).
+        - label: Read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/master/CONTRIBUTING.md).
           required: true
         - label: Read the [docs](https://supabase.com/docs/reference/javascript/introduction).
           required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -40,7 +40,7 @@ body:
       options:
         - label: Follow our [Code of Conduct](https://github.com/supabase/.github/blob/main/CODE_OF_CONDUCT.md)
           required: true
-        - label: Read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/main/CONTRIBUTING.md).
+        - label: Read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/master/CONTRIBUTING.md).
           required: true
         - label: Read the [docs](https://supabase.com/docs/reference/javascript/introduction).
           required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -29,7 +29,7 @@ Closes #(issue_number) <!-- If applicable -->
 
 <!-- Ensure all items are checked before submitting -->
 
-- [ ] I have read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/main/CONTRIBUTING.md)
+- [ ] I have read the [Contributing Guidelines](https://github.com/supabase/supabase-js/blob/master/CONTRIBUTING.md)
 - [ ] My PR title follows the [conventional commit format](https://www.conventionalcommits.org/): `<type>(<scope>): <description>`
 - [ ] I have run `npx nx format` to ensure consistent code formatting
 - [ ] I have added tests for new functionality (if applicable)

.github/workflows/main-ci-release.yml

@@ -34,18 +34,17 @@ jobs:
       contents: read
 
   # ==========================================
-  # CANARY RELEASE (only on main, after all CI passes)
+  # CANARY RELEASE (only on master, after all CI passes)
   # ==========================================
 
   release-canary:
     name: Release Canary
     runs-on: ubuntu-latest
     needs: [ci-core, ci-supabase-js, ci-auth-js-node18]
-    # Only run on main branch pushes, and only if all CI jobs succeeded
+    # Only run on master branch pushes, and only if all CI jobs succeeded
     if: |
-      github.ref == 'refs/heads/main' &&
-      github.event_name == 'push'
-      &&
+      github.ref == 'refs/heads/master' &&
+      github.event_name == 'push' &&
       needs.ci-core.result == 'success' &&
       needs.ci-supabase-js.result == 'success' &&
       needs.ci-auth-js-node18.result == 'success'

CLAUDE.md

@@ -57,14 +57,14 @@ Every change must maintain full backward compatibility. The migration itself int
 
 Uses automated canary releases with batched stable releases:
 
-- **Canary**: Every commit to main → prerelease (e.g., `2.80.1-canary.0`) with `canary` dist-tag
+- **Canary**: Every commit to master → prerelease (e.g., `2.80.1-canary.0`) with `canary` dist-tag
 - **Stable**: Manual promotion of validated canary to `latest` dist-tag
 - **Fixed Versioning**: All packages share identical version numbers (e.g., all at 2.80.0)
 - **Version Line**: Continuing with v2.x.x to maintain ecosystem stability
 
 **Three Release Workflows:**
 
-1. **Canary** (`.github/workflows/main-ci-release.yml`) - Automated on every main commit
+1. **Canary** (`.github/workflows/main-ci-release.yml`) - Automated on every master commit
 2. **Stable** (`.github/workflows/release-stable.yml`) - Manual by repository owners
 3. **Preview** (`.github/workflows/preview-release.yml`) - PR-based testing via pkg.pr.new
 
@@ -129,7 +129,7 @@ nx test auth-js                          # Test specific package
 nx test postgrest-js                     # Test specific package
 nx test functions-js                     # Test specific package
 nx test realtime-js                      # Test specific package
-nx test storage-js                       # Test specific package
+nx test storage-js                       # Test specific package (may use special test:storage target)
 nx test supabase-js                      # Test specific package
 nx affected --target=test                # Test only affected (recommended)
 nx test auth-js --watch                  # Watch mode
@@ -138,14 +138,14 @@ nx test supabase-js --coverage           # Test with coverage
 
 **Docker Requirements:**
 
-| Package      | Docker Required | Infrastructure                  |
-| ------------ | --------------- | ------------------------------- |
-| auth-js      | ✅ Yes          | GoTrue + PostgreSQL             |
-| functions-js | ✅ Yes          | Deno relay (testcontainers)     |
-| postgrest-js | ✅ Yes          | PostgREST + PostgreSQL          |
-| storage-js   | ✅ Yes          | Storage API + PostgreSQL + Kong |
-| realtime-js  | ❌ No           | Mock WebSockets                 |
-| supabase-js  | ❌ No           | Unit tests only                 |
+| Package      | Docker Required | Infrastructure                  | Special Commands |
+| ------------ | --------------- | ------------------------------- | ---------------- |
+| auth-js      | ✅ Yes          | Auth Server + Postgres          | May use `nx test:auth auth-js` |
+| functions-js | ✅ Yes          | Deno relay (testcontainers)     | Standard `nx test functions-js` |
+| postgrest-js | ✅ Yes          | PostgREST + PostgreSQL          | Standard `nx test postgrest-js` |
+| storage-js   | ✅ Yes          | Storage API + PostgreSQL + Kong | May use `nx test:storage storage-js` |
+| realtime-js  | ❌ No           | Mock WebSockets                 | Standard `nx test realtime-js` |
+| supabase-js  | ❌ No           | Unit tests only                 | Standard `nx test supabase-js` |
 
 > **📖 See [TESTING.md](docs/TESTING.md) for complete testing guide and troubleshooting**
 
@@ -262,36 +262,31 @@ Tests run against multiple environments:
 - Requires Docker for integration tests (GoTrue + PostgreSQL)
 - Complex session management logic
 - Security-critical - extra review care needed
-- Default branch: **master**
 - See [auth-js README](packages/core/auth-js/README.md) for details
 
 ### realtime-js
 
 - WebSocket-based, timing-sensitive
 - Mock time in tests when possible
 - No Docker required (uses mock WebSockets)
-- Default branch: **master**
 - See [realtime-js README](packages/core/realtime-js/README.md) for details
 
 ### storage-js
 
 - Requires Docker for integration tests (Storage API + PostgreSQL + Kong)
 - File handling varies by platform
-- Default branch: **main**
 - See [storage-js README](packages/core/storage-js/README.md) for details
 
 ### postgrest-js
 
 - Pure HTTP client, easiest to test
 - Requires Docker for integration tests (PostgREST + PostgreSQL)
-- Default branch: **master**
 - See [postgrest-js README](packages/core/postgrest-js/README.md) for details
 
 ### functions-js
 
 - Simplest library, minimal dependencies
 - Uses testcontainers for Deno relay
-- Default branch: **main**
 - See [functions-js README](packages/core/functions-js/README.md) for details
 
 ## Code Style Guidelines
@@ -316,10 +311,13 @@ Tests run against multiple environments:
 
 ## Important Context
 
-### Branch Differences
+### Branch Information
 
-Original repositories use different default branches:
+**Current Repository:**
+- **Default branch**: `master` (confirmed current default)
+- **Repository URL**: `github.com/supabase/supabase-js`
 
+**Original Repository Branches** (for historical reference):
 - **master**: auth-js, postgrest-js, realtime-js, supabase-js
 - **main**: functions-js, storage-js
 
@@ -487,10 +485,10 @@ cat docs/TESTING.md
 1. **Ensure branch is up to date:**
 
    ```bash
-   git checkout main
-   git pull upstream main
+   git checkout master
+   git pull upstream master
    git checkout your-feature-branch
-   git rebase main
+   git rebase master
    ```
 
 2. **Run all necessary checks:**
@@ -643,7 +641,7 @@ nx test auth-js --testFile=GoTrueClient.test.ts
 **Canary Releases (Automated)**:
 
 ```bash
-# Triggered automatically on every commit to main
+# Triggered automatically on every commit to master
 git commit -m "fix(auth): resolve token issue"
 # → Automatic CI: nx release --tag=canary --yes
 # → Published: 2.80.1-canary.0 to 'canary' dist-tag
@@ -741,14 +739,16 @@ _No user-facing changes in this release._
 
 ## When Providing Code Suggestions
 
-1. **Consider Monorepo Impact**: Changes might affect multiple packages - always check
-2. **Use Nx Commands**: Prefer `nx` over direct `npm` for workspace operations
-3. **Suggest Affected Testing**: `nx affected --target=test` over full test suite
-4. **Respect Fixed Versioning**: All packages version together
-5. **Maintain Compatibility**: Never introduce breaking changes
-6. **Extract Shared Code**: Identify patterns that could be shared
-7. **Follow Conventions**: Use existing patterns and structures
-8. **Document Changes**: Update JSDoc and READMEs when changing APIs
+1. **Consider Monorepo Impact**: Changes might affect multiple packages - always check dependencies
+2. **Use Nx Commands**: Always prefer `nx` over direct `npm` for workspace operations
+3. **Suggest Affected Testing**: Use `nx affected --target=test` over full test suite for efficiency
+4. **Respect Fixed Versioning**: All packages version together - no independent versioning
+5. **Maintain Compatibility**: Never introduce breaking changes without proper process
+6. **Check Testing Requirements**: Be aware of Docker requirements for integration tests
+7. **Extract Shared Code**: Identify patterns that could be shared across packages
+8. **Follow Conventions**: Use existing patterns and structures within each library
+9. **Document Changes**: Update JSDoc and READMEs when changing public APIs
+10. **Use Conventional Commits**: Always suggest proper commit format with scope
 
 ## Quick Decision Tree
 

CONTRIBUTING.md

@@ -2,7 +2,11 @@
 
 Thank you for your interest in contributing to the Supabase JavaScript client libraries! This guide will help you get started with contributing to the Supabase JS monorepo.
 
-> **📣 Coming from a separate repository?** The `supabase-js` repository has been converted into a monorepo and all other Supabase JS libraries have been absorbed into it. If you previously contributed to `auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, or `functions-js`, please read our **[Migration Guide](docs/MIGRATION.md)** to understand the new structure, workflow changes, and command mappings.
+> **Repository Structure Changed:** This repository has been restructured as a monorepo. **All libraries, including `supabase-js`, are now under `packages/core/`**. If you previously contributed to `supabase-js`, `auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, or `functions-js`, please read our **[Migration Guide](docs/MIGRATION.md)** to understand:
+>
+> - Where your code moved (everything is now in `packages/core/<library-name>/`)
+> - How commands changed (`npm test` → `npx nx test <library-name>`)
+> - New workflow with Nx
 
 ## 📋 Table of Contents
 
@@ -56,7 +60,7 @@ Thank you for your interest in contributing to the Supabase JavaScript client li
 
 ### Making Changes
 
-1. **Create a new branch** from `main`:
+1. **Create a new branch** from `master`:
 
    ```bash
    git checkout -b feature/your-feature-name
@@ -186,13 +190,13 @@ ci(release): add preview package generation
 
 ### Before Submitting
 
-1. **Ensure your branch is up to date** with `main`:
+1. **Ensure your branch is up to date** with `master`:
 
    ```bash
-   git checkout main
-   git pull upstream main
+   git checkout master
+   git pull upstream master
    git checkout your-branch
-   git rebase main
+   git rebase master
    ```
 
 2. **Run the full test suite**:
@@ -283,7 +287,7 @@ npx nx test <package> --coverage
 We automatically generate TypeScript API documentation that is used by the main [Supabase documentation site](https://supabase.com/docs). The process works as follows:
 
 1. **TypeDoc generates JSON specifications** from TypeScript source code
-2. **GitHub Actions publishes** these specs to GitHub Pages on every push to `main`
+2. **GitHub Actions publishes** these specs to GitHub Pages on every push to `master`
 3. **Main Supabase repository** uses these JSON files to generate the official API docs via `make` commands
 
 #### Available Documentation Commands

README.md

@@ -1,8 +1,38 @@
-# Supabase JS Client Libraries
+<br />
+<p align="center">
+  <a href="https://supabase.io">
+        <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/supabase-logo-wordmark--dark.svg">
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/supabase-logo-wordmark--light.svg">
+      <img alt="Supabase Logo" width="300" src="https://raw.githubusercontent.com/supabase/supabase/master/packages/common/assets/images/logo-preview.jpg">
+    </picture>
+  </a>
+
+  <h1 align="center">Supabase JS Client Libraries</h1>
+
+  <p align="center">
+    <a href="https://supabase.com/docs/guides/getting-started">Guides</a>
+    ·
+    <a href="https://supabase.com/docs/reference/javascript/introduction">Reference Docs</a>
+  </p>
+</p>
 
-_The Supabase JS monorepo containing all the Supabase JavaScript client libraries._
+<div align="center">
+
+[![pkg.pr.new](https://pkg.pr.new/badge/supabase/supabase-js)](https://pkg.pr.new/~/supabase/supabase-js)
 
-> **📣 Coming from our old repositories?** The `supabase-js` repository has been converted into a monorepo and all other client libraries have been absorbed into it. If you previously contributed to individual repositories like `auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, or `functions-js`, please see our **[Migration Guide](./docs/MIGRATION.md)** to learn about the new structure and workflows.
+</div>
+
+> **For contributors: Repository Structure Changed**
+>
+> This repository has been restructured as a monorepo. All libraries, including `supabase-js` itself, have moved to `packages/core/`:
+>
+> | What You're Looking For | Where It Is Now              |
+> | ----------------------- | ---------------------------- |
+> | Main supabase-js code   | `packages/core/supabase-js/` |
+> | Other libraries         | `packages/core/*/`           |
+>
+> Read the **[Migration Guide](./docs/MIGRATION.md)** to learn more.
 
 ## 📦 Libraries
 
@@ -17,6 +47,15 @@ This monorepo contains the complete suite of Supabase JavaScript client librarie
 | **[@supabase/storage-js](./packages/core/storage-js)**     | File storage client                      |
 | **[@supabase/functions-js](./packages/core/functions-js)** | Edge Functions client                    |
 
+> **💡 Note for Package Users:** If you install and use these packages, **nothing has changed**. Continue installing packages normally:
+>
+> ```bash
+> npm install @supabase/supabase-js
+> npm install @supabase/auth-js
+> ```
+>
+> The monorepo structure **only affects contributors**. This is how we develop and maintain the code, not how you use it.
+
 ## 🚀 Quick Start
 
 ### Installation