Re-audit of docs and so many updates

Author: Genevieve Nuebel

docs/Adding-a-New-API-Version.md

@@ -2,7 +2,7 @@
 
 **Document Purpose**: Step-by-step guide for adding support for a new API version (e.g., `v20300101`) to the mx-platform-node repository.
 
-**Last Updated**: January 27, 2026  
+**Last Updated**: January 28, 2026  
 **Time to Complete**: 30-45 minutes  
 **Prerequisites**: Familiarity with the multi-version architecture (see [Multi-Version-SDK-Flow.md](Multi-Version-SDK-Flow.md))
 
@@ -146,7 +146,7 @@ This ensures when multiple versions are generated, changelog entries appear in o
 
 ### 2.3 Update on-push-master.yml
 
-This workflow automatically triggers publish and release jobs when version directories are pushed to master.
+This workflow automatically triggers publish and release jobs when version directories are pushed to master. Since individual version jobs use conditional `if` statements based on path changes, you need to add new conditional jobs for your new version.
 
 **Location 1: Path trigger**
 
@@ -164,34 +164,56 @@ on:
 
 This ensures the workflow triggers when changes to your version directory are pushed to master.
 
-**Location 2: Publish job matrix**
+**Location 2: Add publish job for new version**
 
-In the `publish` job's strategy matrix, add your version entry:
+Add a new publish job for your version (copy and modify the existing v20250224 jobs):
 
 ```yaml
-strategy:
-  matrix:
-    version:
-      - api_version: v20111101
-      - api_version: v20250224
-      - api_version: v20300101    # NEW
-  fail-fast: false
+publish-v20300101:
+  runs-on: ubuntu-latest
+  needs: [check-skip-publish, gate-v20250224-complete]    # Gate waits for previous version
+  if: needs.check-skip-publish.outputs.skip_publish == 'false' && contains(github.event.head_commit.modified, 'v20300101')
+  uses: ./.github/workflows/publish.yml@master
+  with:
+    version_directory: v20300101
+  secrets: inherit
 ```
 
-**Location 3: Release job matrix**
+**Location 3: Add release job for new version**
 
-In the `release` job's strategy matrix, add your version entry (mirror the publish matrix):
+Add a new release job for your version:
 
 ```yaml
-strategy:
-  matrix:
-    version:
-      - api_version: v20111101
-      - api_version: v20250224
-      - api_version: v20300101    # NEW
-  fail-fast: false
+release-v20300101:
+  runs-on: ubuntu-latest
+  needs: [check-skip-publish, publish-v20300101]
+  if: needs.check-skip-publish.outputs.skip_publish == 'false' && contains(github.event.head_commit.modified, 'v20300101')
+  uses: ./.github/workflows/release.yml@master
+  with:
+    version_directory: v20300101
+  secrets: inherit
 ```
 
+**Location 4: Add gate job for previous version**
+
+Add a new gate job after the previous version's release to handle serial ordering:
+
+```yaml
+gate-v20250224-complete:
+  runs-on: ubuntu-latest
+  needs: [check-skip-publish, release-v20250224]
+  if: always() && needs.check-skip-publish.outputs.skip_publish == 'false'
+  steps:
+    - name: Gate complete - ready for v20300101
+      run: echo "v20250224 release workflow complete (or skipped)"
+```
+
+**Important Notes**:
+- Each publish job depends on the **previous version's gate job** to maintain serial ordering
+- Each release job depends on its corresponding publish job
+- Gate jobs use the `always()` condition so they run even when intermediate jobs are skipped
+- This prevents npm registry race conditions and ensures correct behavior whether one or multiple versions are modified
+
 ### 2.4 Verify Workflow Syntax
 
 Check that your YAML is valid for all three modified files:
@@ -367,8 +389,9 @@ Use this checklist to verify you've completed all steps:
 - [ ] Updated `.github/workflows/openapi-generate-and-push.yml` with version-to-config mapping in Setup job
 - [ ] Updated `.github/changelog_manager.rb` with new version in `API_VERSION_ORDER` array
 - [ ] Updated `.github/workflows/on-push-master.yml` path triggers with `v20300101/**`
-- [ ] Updated `.github/workflows/on-push-master.yml` publish job matrix with new version
-- [ ] Updated `.github/workflows/on-push-master.yml` release job matrix with new version
+- [ ] Updated `.github/workflows/on-push-master.yml` with new publish job for v20300101
+- [ ] Updated `.github/workflows/on-push-master.yml` with new release job for v20300101
+- [ ] Updated `.github/workflows/on-push-master.yml` with new gate job for previous version (v20250224)
 - [ ] Verified workflow YAML syntax is valid for all three modified files
 - [ ] Updated root `README.md` with new API version table entry
 - [ ] Updated root `README.md` with installation example for new version

docs/Multi-Version-SDK-Flow.md

@@ -20,44 +20,47 @@ Each version is independently generated, tested, published to npm, and released
 1. **Separate Directories**: Each API version in its own directory (`v20111101/`, `v20250224/`)
 2. **Reusable Workflows**: `workflow_call` passes version info to publish/release jobs
 3. **One Config Per Version**: `config-v20111101.yml`, `config-v20250224.yml`, etc.
-4. **Matrix Parallelization**: All versions generate/publish simultaneously
+4. **Single Entrypoint for Publishing**: All paths lead through `on-push-master.yml` for serial, controlled publishing
 5. **Safety First**: Skip-publish flags and path-based triggers prevent accidents
 
 ---
 
-## Three Ways Things Happen
+## Two Paths to Publishing
 
-### 🤖 Flow 1: Automatic (Upstream Triggers)
-OpenAPI spec changes → `openapi-generate-and-push.yml` runs → SDK generated, published, released
+Both paths follow the same publishing mechanism: commit changes to master → `on-push-master.yml` handles serial publish/release.
+
+### 🤖 Path 1: Automatic (Upstream Triggers)
+OpenAPI spec changes → `openapi-generate-and-push.yml` generates SDK → commits to master → `on-push-master.yml` publishes and releases
 
 **When**: OpenAPI repository sends `repository_dispatch` with API versions  
 **Who**: Automated, no human intervention  
-**Result**: All specified versions generated in parallel, committed, published, released in single workflow
+**What Happens**:
+1. `openapi-generate-and-push.yml` generates all specified versions in parallel
+2. All generated files committed to master
+3. `on-push-master.yml` automatically triggered by the push
+4. `on-push-master.yml` handles serial publish/release with version gating
 
 **Key Details**: See [Workflow-and-Configuration-Reference.md](Workflow-and-Configuration-Reference.md#flow-1-automatic-multi-version-generation-repository-dispatch)
 
-### 👨‍💻 Flow 2: Manual (Developer Triggers)
-Developer runs `generate.yml` → SDK generated → PR created → Developer merges → Auto-publish triggers
+### 👨‍💻 Path 2: Manual (Developer Triggers)
+Developer runs `generate.yml` → SDK generated in feature branch → PR created → code review & approval → merge to master → `on-push-master.yml` publishes and releases
 
 **When**: Developer clicks "Run workflow" on `generate.yml`  
 **Who**: Developer (controls version selection and bump strategy)  
 **Inputs**:
 - `api_version`: Choose `v20111101` or `v20250224`
 - `version_bump`: Choose `skip`, `minor`, or `patch`
 
-**Result**: SDK generated in feature branch, PR created for review, auto-publishes on merge
+**What Happens**:
+1. `generate.yml` generates SDK in feature branch
+2. PR created for code review
+3. Developer (or team) reviews and approves
+4. PR merged to master
+5. `on-push-master.yml` automatically triggered by the merge
+6. `on-push-master.yml` handles serial publish/release with version gating
 
 **Key Details**: See [Workflow-and-Configuration-Reference.md](Workflow-and-Configuration-Reference.md#flow-2-manual-multi-version-generation-workflow-dispatch)
 
-### 🔄 Flow 3: Auto-Publish (Master Push)
-Changes pushed to `v20111101/**` or `v20250224/**` → `on-push-master.yml` runs → Publishes and releases
-
-**When**: Any commit to master with version directory changes  
-**Who**: Triggered automatically, can be skipped with `[skip-publish]` flag  
-**Safety**: Only affected version(s) published (no cross-version interference)
-
-**Key Details**: See [Workflow-and-Configuration-Reference.md](Workflow-and-Configuration-Reference.md#flow-3-auto-publish-trigger-with-path-based-matrix-execution-on-push-masteryml)
-
 ---
 
 ## Visual Flows
@@ -68,28 +71,27 @@ Changes pushed to `v20111101/**` or `v20250224/**` → `on-push-master.yml` runs
 sequenceDiagram
     participant OpenAPI as OpenAPI<br/>Repository
     participant GH as GitHub<br/>Actions
-    participant Gen as generate_publish<br/>_release.yml
+    participant Gen as openapi-generate-<br/>and-push.yml
+    participant Push as Push to<br/>Master
+    participant OnPush as on-push-<br/>master.yml
     participant npm as npm<br/>Registry
     participant GHRel as GitHub<br/>Releases
 
     OpenAPI->>GH: Changes to v20111101.yml<br/>and v20250224.yml<br/>(repository_dispatch)
     GH->>+Gen: Trigger workflow
     Gen->>Gen: Matrix: Generate both versions<br/>in parallel
-    Gen->>Gen: Commit to master<br/>Update CHANGELOG.md
+    Gen->>Push: Commit to master<br/>Update CHANGELOG.md
     deactivate Gen
 
-    rect rgba(0, 255, 0, .1)
-        note right of Gen: Parallel Publishing
-        par publish v20111101
-            npm->>npm: npm publish v2.0.1
-        and publish v20250224
-            npm->>npm: npm publish v3.0.1
-        and release v20111101
-            GHRel->>GHRel: Create tag v2.0.1
-        and release v20250224
-            GHRel->>GHRel: Create tag v3.0.1
-        end
-    end
+    Push->>+OnPush: Push event triggers
+    OnPush->>OnPush: Check skip-publish flag
+    OnPush->>OnPush: Serial: v20111101 publish
+    OnPush->>npm: npm publish v2.x.x
+    OnPush->>GHRel: Create tag v2.x.x
+    OnPush->>OnPush: Serial: v20250224 publish
+    OnPush->>npm: npm publish v3.x.x
+    OnPush->>GHRel: Create tag v3.x.x
+    deactivate OnPush
 ```
 
 ### Manual Flow
@@ -100,7 +102,8 @@ sequenceDiagram
     participant GH as GitHub<br/>Actions
     participant Gen as generate.yml
     participant Review as Code<br/>Review
-    participant Auto as on-push-<br/>master.yml
+    participant Merge as Merge to<br/>Master
+    participant OnPush as on-push-<br/>master.yml
     participant npm as npm
     participant GHRel as GitHub
 
@@ -110,44 +113,16 @@ sequenceDiagram
     deactivate Gen
 
     Review->>Review: Review & Approve
-    Review->>Review: Merge PR to master
-
-    GH->>+Auto: on-push-master.yml
-    Auto->>npm: Publish selected version
-    Auto->>GHRel: Create release
-    deactivate Auto
+    Review->>Merge: Merge PR to master
+
+    Merge->>+OnPush: Push event triggers
+    OnPush->>OnPush: Check skip-publish flag
+    OnPush->>OnPush: Serial: publish<br/>& release
+    OnPush->>npm: npm publish
+    OnPush->>GHRel: Create release
+    deactivate OnPush
 ```
 
-### Auto-Publish Flow
-
-```mermaid
-sequenceDiagram
-    participant Push as Git Push
-    participant Auto as on-push-<br/>master.yml
-    participant skip as check-skip-<br/>publish
-    participant pub as publish.yml
-    participant rel as release.yml
-    participant gate as gate-<br/>v20111101
-    participant npm as npm
-    participant GHRel as GitHub
-
-    Push->>+Auto: Push to master<br/>(v20111101/** changed)
-    Auto->>skip: Check skip-publish flag
-    skip-->>Auto: skip_publish: false
-    Auto->>pub: publish-v20111101
-    pub->>npm: npm publish v2.x.x
-    Auto->>rel: release-v20111101
-    rel->>GHRel: Create tag v2.x.x
-    rel-->>gate: Release complete
-    gate->>gate: Gate always runs<br/>(even if v20111101 skipped)
-    note right of gate: Unblocks v20250224<br/>when only v20250224 changed
-    gate-->>Auto: Gate complete
-    Auto->>pub: publish-v20250224<br/>(skipped - not modified)
-    deactivate Auto
-```
-
-**Key Feature**: The `gate-v20111101-complete` job uses `always()` to run even when intermediate jobs are skipped, ensuring v20250224 can publish when only v20250224 is modified.
-
 ---
 
 ## Common Tasks
@@ -175,9 +150,9 @@ sequenceDiagram
 |------|---------|---------|
 | `.github/workflows/openapi-generate-and-push.yml` | Automatic generation from upstream API changes | OpenAPI repo |
 | `.github/workflows/generate.yml` | Manual generation with version selection | Developer |
-| `.github/workflows/on-push-master.yml` | Auto-publish trigger with path-based matrix | Any master push |
-| `.github/workflows/publish.yml` | Publishes SDK to npm | publish_release & on-push-master |
-| `.github/workflows/release.yml` | Creates GitHub release | publish_release & on-push-master |
+| `.github/workflows/on-push-master.yml` | Publishes and releases SDKs on master push | Both automatic & manual flows |
+| `.github/workflows/publish.yml` | Publishes SDK to npm | on-push-master |
+| `.github/workflows/release.yml` | Creates GitHub release | on-push-master |
 | `.github/version.rb` | Bumps version in config files | Workflows |
 | `.github/clean.rb` | Removes old generated files | Workflows |
 | `openapi/config-v20111101.yml` | Config for v20111101 generation | openapi-generate-and-push & generate |
@@ -215,12 +190,15 @@ If OpenAPI repo doesn't send new version in payload, the system doesn't break:
 
 | Feature | What It Does | When It Helps |
 |---------|-------------|--------------|
+| **Serial publishing** | Each version publishes sequentially to npm (v20111101 then v20250224) | Prevents npm registry conflicts and race conditions |
 | **Path-based triggers** | Only publish if `v20111101/**` or `v20250224/**` changed | Prevents false publishes from doc-only changes |
 | **[skip-publish] flag** | Skip publish/release for this commit | During directory migrations or refactors |
-| **Matrix conditionals** | Each version publishes only if its path changed | Prevents unintended version bumps |
+| **Conditional jobs** | Each version's jobs only run if their paths changed | Prevents unintended version bumps |
 | **Version validation** | Major version must match API version | Prevents semantic versioning violations |
 | **Config file validation** | Workflow fails if config doesn't exist | Catches typos early |
 
+**Note on Serial Publishing**: We chose explicit job sequences over matrix strategies to ensure safety. See [Workflow-and-Configuration-Reference.md - Architecture Decision section](Workflow-and-Configuration-Reference.md#architecture-decision-serial-publishing-with-conditional-jobs) for detailed reasoning.
+
 ---
 
 ## Environment Variables & Secrets

docs/Troubleshooting-Guide.md

@@ -259,7 +259,7 @@ fatal: A release with this tag already exists
    ```
 4. If not present, update workflow from latest template
 
-**Technical Details**: See [Workflow-and-Configuration-Reference.md](Workflow-and-Configuration-Reference.md#step-3-gate-job---unblock-v20250224-publishing) for full gate job implementation details.
+**Technical Details**: See [Workflow-and-Configuration-Reference.md](Workflow-and-Configuration-Reference.md#step-3-gate-job---unblock-v20250224-publishing) in the "Publishing via on-push-master.yml" section for full gate job implementation details.
 
 ---