From 660097dda84e8694242a62f90ce00ce0cca872d3 Mon Sep 17 00:00:00 2001
From: spbsoluble <1661003+spbsoluble@users.noreply.github.com>
Date: Fri, 7 Aug 2026 13:24:37 -0700
Subject: [PATCH 1/2] fix: pin doctooldotnet checkout to an explicit ref in
 generate-readme.yml

The "Checkout doctool action" step checked out keyfactor/doctooldotnet
with no ref, always running whatever is on its default branch. Every
push to an integration repo silently picks up whatever doctool bugs
landed since the last push, with no way to control or roll back the
version in use.

Keyfactor/akeyless-pam#11 hit this concretely: a known PamRenderer bug
duplicates sections in docs/<type>.md and drops the Extension
Mechanics/Configuration sections from README.md entirely. It's been
manually reverted twice already in that repo because every subsequent
push re-triggers the same regeneration.

Add a doctool-ref input (default: current doctooldotnet main HEAD, so
behavior is unchanged today) and pass it to the checkout step, so
picking up a doctool fix is a deliberate version bump instead of an
implicit side effect of the next push.
---
 .github/workflows/generate-readme.yml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/.github/workflows/generate-readme.yml b/.github/workflows/generate-readme.yml
index d6f7710..3e57537 100644
--- a/.github/workflows/generate-readme.yml
+++ b/.github/workflows/generate-readme.yml
@@ -1,6 +1,12 @@
 name: Generate README from templates and data files using doctool
 on:
   workflow_call:
+    inputs:
+      doctool-ref:
+        description: 'Git ref (tag/branch/commit) of keyfactor/doctooldotnet to run. Pinned to a known-good commit by default so doctool changes cannot silently alter generated docs; bump deliberately.'
+        type: string
+        required: false
+        default: '031c69536c678c149ac70c4408caf13306852f22'
     secrets:
       token:
         description: 'Secret token from caller workflow to approve readme'
@@ -23,6 +29,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           repository: keyfactor/doctooldotnet
+          ref: ${{ inputs.doctool-ref }}
           path: doctooldotnet
           token: ${{ secrets.token }}
           clean: false

From 4e1af086034515cb43f5c9a96ef207b252d2b0a1 Mon Sep 17 00:00:00 2001
From: spbsoluble <1661003+spbsoluble@users.noreply.github.com>
Date: Fri, 7 Aug 2026 13:33:22 -0700
Subject: [PATCH 2/2] fix: default doctool-ref to main, not a frozen commit

Keep doctooldotnet tracking main by default (today's actual behavior)
instead of freezing it at a specific commit. The doctool-ref input
stays available for any caller that wants to pin to a known-good
commit/tag for stability, but that's now opt-in rather than forced.
---
 .github/workflows/generate-readme.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/generate-readme.yml b/.github/workflows/generate-readme.yml
index 3e57537..3c6a06a 100644
--- a/.github/workflows/generate-readme.yml
+++ b/.github/workflows/generate-readme.yml
@@ -3,10 +3,10 @@ on:
   workflow_call:
     inputs:
       doctool-ref:
-        description: 'Git ref (tag/branch/commit) of keyfactor/doctooldotnet to run. Pinned to a known-good commit by default so doctool changes cannot silently alter generated docs; bump deliberately.'
+        description: 'Git ref (tag/branch/commit) of keyfactor/doctooldotnet to run. Defaults to main; override to pin to a specific commit/tag if needed.'
         type: string
         required: false
-        default: '031c69536c678c149ac70c4408caf13306852f22'
+        default: 'main'
     secrets:
       token:
         description: 'Secret token from caller workflow to approve readme'