docs: clarify main branch reference semantics

Author: majin.nathan

docs/src/format/table/branch_tag.md

@@ -17,7 +17,9 @@ Branch names must follow these validation rules:
 4. Cannot contain `..` or `\`
 5. Segments must contain only alphanumeric characters, `.`, `-`, `_`
 6. Cannot end with `.lock`
-7. Cannot be named `main` (reserved for main branch)
+7. Cannot be named `main` (reserved for the default branch)
+
+`main` is a virtual name for the default branch. It may appear in API reference contexts as an alias for the default branch, but no branch metadata file named `main.json` is created.
 
 ### Branch Metadata Path
 
@@ -38,7 +40,7 @@ Each branch metadata file is a JSON file with the following fields:
 
 | JSON Key         | Type   | Optional | Description                                                                    |
 |------------------|--------|----------|--------------------------------------------------------------------------------|
-| `parentBranch`   | string | Yes      | Name of the branch this was created from. `null` indicates branched from main. |
+| `parentBranch`   | string | Yes      | Name of the branch this was created from. `null` indicates branched from the default branch. |
 | `parentVersion`  | number |          | Version number of the parent branch at the time this branch was created.       |
 | `createAt`       | number |          | Unix timestamp (seconds since epoch) when the branch was created.              |
 | `manifestSize`   | number |          | Size of the initial manifest file in bytes.                                    |
@@ -117,7 +119,7 @@ Each tag file is a JSON file with the following fields:
 
 | JSON Key        | Type   | Optional | Description                                                              |
 |-----------------|--------|----------|--------------------------------------------------------------------------|
-| `branch`        | string | Yes      | Branch name being tagged. `null` or absent indicates main branch.        |
+| `branch`        | string | Yes      | Branch name being tagged. `null` or absent indicates the default branch. |
 | `version`       | number |          | Version number being tagged within that branch.                          |
 | `createdAt`     | string | Yes      | RFC 3339 timestamp for when the tag was first created.                  |
 | `updatedAt`     | string | Yes      | RFC 3339 timestamp for the latest tag reference update.                 |

docs/src/guide/tags_and_branches.md

@@ -20,6 +20,8 @@ The `reference` parameter (used in `create`, `update`, and `checkout_version`) a
   - `("experiment", 3)` means version 3 on the experiment branch
   - `("branch-name", None)` means the latest version on that branch
 
+In reference contexts, `"main"` is an alias for the default branch and is equivalent to `None`.
+
 !!! note
 
     Creating or deleting tags does not generate new dataset versions.
@@ -77,7 +79,7 @@ The `reference` parameter works the same as for Tags (see above).
 
     Each branch maintains its own linear version history, so version numbers may overlap across branches. Use `(branch_name, version_number)` tuples as global identifiers for operations like `checkout_version` and `tags.create`.
 
-    "main" is a reserved branch name. Lance uses "main" to identify the default branch.
+    `"main"` is reserved for the default branch. Use `"main"` or `None` when referring to the default branch in reference tuples or checkout APIs, but choose a different name when creating, deleting, or updating branches.
 
 ### Create and checkout branches
 ```python
@@ -99,6 +101,8 @@ ds.tags.create("experiment-rc", ("experiment", None))
 experiment_rc = ds.checkout_version("experiment-rc")
 # Checkout the latest version of the experimental branch by tuple
 experiment_latest = ds.checkout_version(("experiment", None))
+# Checkout the latest version of the default branch explicitly
+main_latest = ds.checkout_version(("main", None))
 
 # Create a new branch from a tag
 new_experiment = ds.create_branch("new-experiment", "experiment-rc")

docs/src/quickstart/versioning.md

@@ -95,6 +95,8 @@ For advanced tag operations (e.g., tagging versions on specific branches), see [
 
 Branches manage parallel lines of dataset evolution. You can create branches from existing versions or tags, read and write to them independently, and checkout different branches.
 
+`main` refers to the default branch in checkout and reference APIs, but it is reserved and cannot be used as the name of a new branch.
+
 ```python
 # Create branch from current latest version
 experiment_branch = ds.create_branch("experiment")