chore(repo): update docs

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

CLAUDE.md

@@ -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          | GoTrue + PostgreSQL             | 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**
 
@@ -311,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
 
@@ -736,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
 

README.md

@@ -6,9 +6,11 @@
 
 _The Supabase JS monorepo containing all the Supabase JavaScript client libraries._
 
-> **IMPORTANT: Repository Structure Changed**
+> **⚠️ IMPORTANT FOR CONTRIBUTORS: Repository Structure Changed**
 >
-> This repository has been restructured as a monorepo. **All libraries, including `supabase-js` itself, have moved to `packages/core/`**:
+> **If you use these packages:** Nothing changed. Continue installing and using them as normal.
+>
+> **If you contribute to these packages:** 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 |
 > |------------------------|-----------------|
@@ -17,10 +19,10 @@ _The Supabase JS monorepo containing all the Supabase JavaScript client librarie
 > | Database library code | `packages/core/postgrest-js/` |
 > | Other libraries | `packages/core/*/` |
 >
-> **If you contributed to ANY of these repositories before**, please read our **[Migration Guide](./docs/MIGRATION.md)** to understand:
+> **If you contributed before**, read the **[Migration Guide](./docs/MIGRATION.md)** to learn:
 >
 > - Where your code moved
-> - How commands changed (e.g., `npm test` → `npx nx test supabase-js`)
+> - How commands changed (example: `npm test` → `npx nx test supabase-js`)
 > - How to update your development workflow
 
 ## 📦 Libraries
@@ -36,6 +38,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

WARP.md

@@ -27,7 +27,8 @@ This monorepo replaces the following individual repositories:
 
 ### Important Notes
 
-- **Default Branches**: Original repos use different default branches (master vs main). Check each library's original repo for reference.
+- **Current Default Branch**: `master` (confirmed current default branch)
+- **Original Branch Differences**: Original repos used different default branches (master vs main). Check each library's original repo for reference.
 - **Package Names**: All packages maintain their original npm names (@supabase/[package-name])
 - **Zero Breaking Changes**: This migration maintains full backward compatibility for consumers
 - **Shared Code**: Common patterns (HTTP client, error handling) should be extracted to shared packages when identified
@@ -95,11 +96,11 @@ nx affected --target=build
 nx run-many --target=test --all
 
 # Run tests for a specific library
-nx test auth-js
+nx test auth-js                  # May also use: nx test:auth auth-js
 nx test postgrest-js
 nx test functions-js
 nx test realtime-js
-nx test storage-js
+nx test storage-js               # May also use: nx test:storage storage-js
 nx test supabase-js
 
 # Run only affected tests (recommended during development)
@@ -114,14 +115,14 @@ nx test auth-js --coverage
 
 **Docker Requirements for Integration Tests:**
 
-| Package      | Docker Required | Notes                           |
-| ------------ | --------------- | ------------------------------- |
-| auth-js      | ✅ Yes          | Requires GoTrue + PostgreSQL    |
-| functions-js | ✅ Yes          | Uses testcontainers for Deno    |
-| postgrest-js | ✅ Yes          | Requires PostgREST + PostgreSQL |
-| storage-js   | ✅ Yes          | Requires Storage API + Kong     |
-| realtime-js  | ❌ No           | Uses mock WebSockets            |
-| supabase-js  | ❌ No           | Unit tests only                 |
+| Package      | Docker Required | Notes                           | Special Commands |
+| ------------ | --------------- | ------------------------------- | ---------------- |
+| auth-js      | ✅ Yes          | Requires GoTrue + PostgreSQL    | May use `nx test:auth auth-js` |
+| functions-js | ✅ Yes          | Uses testcontainers for Deno    | Standard `nx test functions-js` |
+| postgrest-js | ✅ Yes          | Requires PostgREST + PostgreSQL | Standard `nx test postgrest-js` |
+| storage-js   | ✅ Yes          | Requires Storage API + Kong     | May use `nx test:storage storage-js` |
+| realtime-js  | ❌ No           | Uses mock WebSockets            | Standard `nx test realtime-js` |
+| supabase-js  | ❌ No           | Unit tests only                 | Standard `nx test supabase-js` |
 
 ### Code Quality
 
@@ -554,8 +555,10 @@ packages/core/[library]/
 - **Run affected commands** to save time (`nx affected --target=test`)
 - **Use interactive commit tool** (`npm run commit`)
 - **Format code** before committing (`nx format`)
-- **Read package READMEs** for library-specific details
+- **Read package READMEs** for library-specific details and special test commands
 - **Check documentation** in `docs/` for comprehensive guides
+- **Check for Docker requirements** before running integration tests
+- **Use conventional commit format** with proper scope
 
 ### Don'ts ❌
 
@@ -564,6 +567,7 @@ packages/core/[library]/
 - **Don't hardcode internal versions** (use `*` protocol)
 - **Don't test everything** when only some packages changed (use `nx affected`)
 - **Don't make breaking changes** without discussion and proper commit format
+- **Don't assume all packages use standard test commands** (check for special targets)
 
 ## Troubleshooting