diff --git a/.github/scripts/verify-code-references.sh b/.github/scripts/verify-code-references.sh
index 223ead52e..92fcbe3be 100755
--- a/.github/scripts/verify-code-references.sh
+++ b/.github/scripts/verify-code-references.sh
@@ -182,6 +182,22 @@ echo ""
 
 if [[ $EXIT_CODE -eq 0 ]]; then
     echo -e "${GREEN}✓ All code references are valid!${NC}"
+
+    # If in PR comment mode, write success message to file
+    if [[ -n "${COMMENT_FILE}" ]]; then
+        cat > "${COMMENT_FILE}" <<EOF
+## ✓ Code Reference Verification Passed
+
+All code references in the documentation have been verified successfully!
+
+**Total references checked:** ${TOTAL_REFS}
+**Valid references:** ${VALID_REFS}
+
+The documentation is in sync with the codebase on the \`develop\` branch.
+EOF
+        echo ""
+        echo "PR success comment written to: ${COMMENT_FILE}"
+    fi
 else
     echo -e "${RED}✗ Some code references are invalid. Please update the documentation.${NC}"
 
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 84a6cd3ba..e9a706d9a 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -57,16 +57,16 @@ jobs:
         run: |
           bash .github/scripts/verify-code-references.sh --pr-comment /tmp/pr-comment.md
           if [ -f /tmp/pr-comment.md ]; then
-            echo "has_errors=true" >> $GITHUB_OUTPUT
+            echo "has_comment=true" >> $GITHUB_OUTPUT
             echo "Comment file created, will post to PR"
             cat /tmp/pr-comment.md
           else
-            echo "has_errors=false" >> $GITHUB_OUTPUT
-            echo "No errors found, no comment needed"
+            echo "has_comment=false" >> $GITHUB_OUTPUT
+            echo "No comment file created"
           fi
 
-      - name: Comment PR on verification failure
-        if: github.event_name == 'pull_request' && steps.verify-pr.outputs.has_errors == 'true'
+      - name: Comment PR with verification results
+        if: github.event_name == 'pull_request' && steps.verify-pr.outputs.has_comment == 'true'
         uses: thollander/actions-comment-pull-request@v3
         with:
           file-path: /tmp/pr-comment.md
diff --git a/website/docs/developers/documentation-guidelines.md b/website/docs/developers/documentation-guidelines.md
index 6f0a10825..e6d74a625 100644
--- a/website/docs/developers/documentation-guidelines.md
+++ b/website/docs/developers/documentation-guidelines.md
@@ -35,10 +35,10 @@ https://github.com/o1-labs/mina-rust/blob/develop/path/to/file.rs#LStartLine-LEn
 
 Here's a real example from the zkApps documentation:
 
-<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic.rs#L3588-L3592 -->
+<!-- CODE_REFERENCE: ledger/src/scan_state/transaction_logic/valid.rs#L80-L83-->
 
-```rust reference title="ledger/src/scan_state/transaction_logic.rs"
-https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic.rs#L3588-L3592
+```rust reference title="ledger/src/scan_state/transaction_logic/valid.rs"
+https://github.com/o1-labs/mina-rust/blob/develop/ledger/src/scan_state/transaction_logic/valid.rs#L80-L83
 ```
 
 ### Components explained