fix: address review feedback and reorder release workflow

- Add Artifact.variant to deprecation list in CHANGELOG.md
- Add Artifact.variant to deprecation table in stability.md
- Restore Artifact.variant migration guide section
- Reorder release workflow: TestPyPI verification before merge to main

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: teng-lin

CHANGELOG.md

@@ -72,6 +72,7 @@ See [Migration Guide](docs/stability.md#migrating-from-v02x-to-v030) for upgrade
 
 - **`Source.source_type`** - Use `.kind` property instead (returns `SourceType` str enum)
 - **`Artifact.artifact_type`** - Use `.kind` property instead (returns `ArtifactType` str enum)
+- **`Artifact.variant`** - Use `.kind`, `.is_quiz`, or `.is_flashcards` instead
 - **`SourceFulltext.source_type`** - Use `.kind` property instead
 - **`StudioContentType`** - Use `ArtifactType` (str enum) for user-facing code
 

docs/releasing.md

@@ -28,9 +28,9 @@ Release Plan for vX.Y.Z:
 4. Commit changes
 5. ⏸️ CONFIRM: Create PR to main?
 6. Wait for CI to pass on PR
-7. Merge PR to main
-8. ⏸️ CONFIRM: Publish to TestPyPI?
-9. Verify TestPyPI package
+7. ⏸️ CONFIRM: Publish to TestPyPI?
+8. Verify TestPyPI package
+9. Merge PR to main
 10. ⏸️ CONFIRM: Create and push tag vX.Y.Z?
 11. Wait for PyPI publish
 12. Create GitHub release
@@ -173,23 +173,6 @@ Proceed with release preparation?
   - Type checking
   - Unit and integration tests (Python 3.10-3.14, all platforms)
 
-### Merge to Main
-
-- [ ] Once CI passes, merge the PR:
-  ```bash
-  gh pr merge --squash --delete-branch
-  ```
-- [ ] Pull latest main (in main repo or update worktree):
-  ```bash
-  git checkout main && git pull origin main
-  ```
-
-### E2E Tests on Main (Optional)
-
-- [ ] Go to **Actions** → **Nightly E2E**
-- [ ] Click **Run workflow**, select `main` branch
-- [ ] Wait for E2E tests to pass
-
 ---
 
 ## Package Verification
@@ -200,7 +183,7 @@ Proceed with release preparation?
 
 - [ ] **⏸️ CONFIRM:** Ask user "Ready to publish to TestPyPI?"
 - [ ] Go to **Actions** → **Publish to TestPyPI**
-- [ ] Click **Run workflow**
+- [ ] Click **Run workflow**, select the **release/X.Y.Z** branch
 - [ ] Wait for upload to complete
 - [ ] Verify package appears: https://test.pypi.org/project/notebooklm-py/
 
@@ -212,10 +195,24 @@ Proceed with release preparation?
 - [ ] Click **Run workflow** with **source**: `testpypi`
 - [ ] Wait for all tests to pass (unit, integration, E2E)
 - [ ] If verification fails:
-  1. Create a new release branch with bumped patch version
-  2. Fix issues
-  3. Create new PR
-  4. Merge and re-run **Publish to TestPyPI**
+  1. Fix issues in the release worktree
+  2. Bump patch version in `pyproject.toml`
+  3. Update `CHANGELOG.md` with fix
+  4. Commit, push, and re-run **Publish to TestPyPI**
+
+---
+
+## Merge to Main
+
+- [ ] Once TestPyPI verification passes, merge the PR:
+  ```bash
+  gh pr merge --squash --delete-branch
+  ```
+- [ ] Pull latest main (in main repo):
+  ```bash
+  cd /path/to/notebooklm-py
+  git pull origin main
+  ```
 
 ---
 

docs/stability.md

@@ -117,6 +117,7 @@ The following are deprecated and will be removed in **v0.4.0**:
 |------------|-------------|-------|
 | `Source.source_type` | `Source.kind` | Returns `SourceType` str enum |
 | `Artifact.artifact_type` | `Artifact.kind` | Returns `ArtifactType` str enum |
+| `Artifact.variant` | `Artifact.kind` | Use `.is_quiz` / `.is_flashcards` |
 | `SourceFulltext.source_type` | `SourceFulltext.kind` | Returns `SourceType` str enum |
 | `StudioContentType` | `ArtifactType` | Str enum for user-facing code |
 
@@ -183,6 +184,27 @@ if artifact.kind == "audio":
 **Available `ArtifactType` values:**
 `AUDIO`, `VIDEO`, `REPORT`, `QUIZ`, `FLASHCARDS`, `MIND_MAP`, `INFOGRAPHIC`, `SLIDE_DECK`, `DATA_TABLE`, `UNKNOWN`
 
+#### 3. `Artifact.variant` → `Artifact.kind` or helpers
+
+**Before (deprecated):**
+```python
+if artifact.artifact_type == 4 and artifact.variant == 2:  # ⚠️ Deprecated
+    print("This is a quiz")
+```
+
+**After (recommended):**
+```python
+# Option 1: Use .kind
+if artifact.kind == ArtifactType.QUIZ:
+    print("This is a quiz")
+
+# Option 2: Use helper properties
+if artifact.is_quiz:
+    print("This is a quiz")
+if artifact.is_flashcards:
+    print("These are flashcards")
+```
+
 #### Why These Changes?
 
 1. **Stability**: The `.kind` property abstracts internal integer codes that Google may change