Use Markdown for installer and manual docs

[olilarkin]

Summary

This switches the TemplateProject installer text and manual sources to Markdown.

Pandoc is now the renderer for generated distribution files:

• macOS installer RTF files from installer/*.md
• Windows installer TXT files from installer/*.md with CRLF line endings
• Manual PDF from manual/TemplateProject manual.md using Pandoc with Typst as the PDF engine

The checked-in LaTeX/PDF manual placeholder is replaced by Markdown source. Packaging keeps generated RTF/TXT/PDF output under build directories and includes the generated PDF manual in both the macOS DMG and Windows installer/archive.

Review feedback addressed

• Removed the hand-rolled Markdown/PDF parser in favor of Pandoc.
• CI installs Pandoc and Typst before validating generated docs.
• Windows PowerShell validation enables native command failure handling.
• Windows installer readme entry matching is less brittle.
• Windows generated TXT files use CRLF endings.
• macOS packaging paths touched by installer resources are quoted.
• prepare_installer_docs.py derives the product name from the project directory instead of hardcoding TemplateProject.
• Earlier release-native archive-name and Windows CLAP-source fixes are included in this PR.

CI and build impact

• macOS packaging generates installer RTF resources under build-mac/installer/resources before productbuild.
• macOS packaging generates build-mac/manual/TemplateProject manual.pdf and copies that PDF into the DMG folder.
• Windows packaging generates Inno-compatible TXT files under build-win/installer-docs before running Inno Setup.
• Windows packaging generates build-win/manual/TemplateProject manual.pdf and includes that PDF in the installer/archive.
• macOS and Windows CI validate that the generated docs and generated manual PDF exist before building.

Release validation

• v0.0.0-test5 Release Native workflow passed: https://github.com/iPlug2/iPlug2OOS/actions/runs/25990651803
• Draft release assets uploaded:
  • TemplateProject-v0.0.0-mac.dmg
  • TemplateProject-v0.0.0-mac-dSYMs.zip
  • TemplateProject-v0.0.0-win.zip
  • TemplateProject-v0.0.0-win-pdbs.zip

Local validation

• python3 TemplateProject/scripts/prepare_installer_docs.py all
• file 'TemplateProject/build-mac/manual/TemplateProject manual.pdf' 'TemplateProject/build-win/manual/TemplateProject manual.pdf' TemplateProject/build-mac/installer/resources/license.rtf TemplateProject/build-win/installer-docs/readme-win.txt
• python3 -m py_compile TemplateProject/scripts/prepare_installer_docs.py TemplateProject/scripts/update_installer-win.py TemplateProject/scripts/makezip-win.py
• bash -n TemplateProject/scripts/makeinstaller-mac.sh
• bash -n TemplateProject/scripts/makedist-mac.sh
• git diff --check

[claude]

Code Review: [codex] Use Markdown for installer and manual docs

Overview

This PR replaces binary/RTF installer documents and the LaTeX/PDF manual placeholder with Markdown sources, generating installer-compatible RTF (macOS) and plain TXT (Windows) files at build time via a new prepare_installer_docs.py script. The approach is a clear maintainability win: Markdown is diff-friendly, human-readable, and a much lower barrier for plugin developers to customise their docs.

---

Positives

• Clean single-responsibility script with clear separation between parsing, escaping, and output.
• RTF Unicode escaping is correctly implemented, including the signed-integer conversion for codepoints >= 32768 per the RTF spec.
• write_text() centralises makedirs so callers cannot forget it.
• CI validation steps confirm generated artefacts exist before the build proceeds, guarding against a broken script silently producing an empty installer.
• The update_installer-win.py match string change to DestName: "readme.txt" is more specific and less fragile than the old Source: "readme" broad match.
• Generated directories (build-mac/, build-win/) are already covered by the /build-/ gitignore pattern, so no new entries are needed.

---

Issues and Suggestions

1. PowerShell CI step lacks error propagation (minor)

In .github/workflows/build-win.yml, the Validate step runs python scripts/prepare_installer_docs.py win inside pwsh. PowerShell does NOT stop on non-zero exit codes from external processes by default. If the script fails, the Test-Path checks that follow will catch missing files -- but a Python traceback could be swallowed and make debugging harder.

Suggestion: add $ErrorActionPreference = 'Stop' as the first line of that run block.

2. .md manual installed as end-user artefact (UX concern)

The Inno Setup .iss and makedist-mac.sh now ship "TemplateProject manual.md" directly to end users and create a Start Menu shortcut pointing to it. On Windows, .md has no default file association on most machines -- double-clicking the shortcut will either prompt "Open with..." or silently fail. PDF was user-friendly here.

Options to consider:

• Keep PDF as the shipped artefact and generate it from Markdown via pandoc during release builds.
• Ship the .md but drop the Start Menu shortcut, since non-technical users cannot open it easily.
• At minimum, add a note in the template README warning plugin developers about this trade-off.

3. Hardcoded PRODUCT_NAME in prepare_installer_docs.py (minor)

PRODUCT_NAME = "TemplateProject" (line 12) is only used for the optional installer background image filename. When duplicate.py creates a new plugin, if it only renames files/directories without patching all string occurrences inside script bodies, this constant could be missed. Consider deriving it at runtime: PRODUCT_NAME = os.path.basename(PROJECT_DIR).

4. Italic regex can match mid-word underscores (minor)

The regex r"([^_]+)" will incorrectly strip underscores from snake_case identifiers or file paths in installer text. If a plugin developer writes a license or readme with technical paths or variable names, the text could be silently corrupted. A comment noting this limitation would help.

5. Setext-style headings not handled

The converter only strips ATX headings (# Heading). CommonMark also supports setext headings (text underlined with === or ---). Not a problem with the current .md files, but worth documenting as a known limitation in the script.

6. Missing newline at EOF additions confirmed

Several files previously missing a trailing newline (TemplateProject.iss, makedist-win.bat, makeinstaller-mac.sh) have it added here. Good hygiene.

---

Summary

The core approach is solid and the implementation is clean. The two things most worth addressing before merge are the PowerShell error propagation (an easy one-liner fix) and the end-user UX of shipping a raw .md file with a Start Menu shortcut (a product decision about what format end users should receive). The rest are minor polish items.

Review generated with Claude Sonnet 4.6

[claude]

Code Review — PR #24: Use Markdown for installer and manual docs

Overview

This PR replaces binary/proprietary RTF and LaTeX/PDF installer sources with human-readable Markdown files, generating the installer-facing RTF/TXT files at packaging time via a new Python helper. It's a well-motivated change that reduces merge conflicts and makes docs editable without specialist tools. The approach is sound and the implementation is generally clean.

---

Bugs / Issues

1. Windows CI step may silently swallow Python errors

- name: Validate installer docs
  shell: pwsh
  run: |
    cd ${{matrix.project}}
    python scripts/prepare_installer_docs.py win   # ← no exit-code guard
    if (!(Test-Path "build-win\installer-docs\license.txt")) { throw "..." }

Unlike the macOS step (which has set -eo pipefail), the pwsh shell does not automatically stop on a non-zero exit code. If the Python script fails, execution continues to the Test-Path checks, which would only catch the secondary symptom (missing files) rather than the root error message. Add an explicit check:

python scripts/prepare_installer_docs.py win
if ($LASTEXITCODE -ne 0) { exit 1 }

Or set $ErrorActionPreference = "Stop" at the top of the step.

---

2. Shipping a .md file as the user-facing manual is poor UX on Windows

; TemplateProject.iss
Source: "..\manual\TemplateProject manual.md"; DestDir: "{app}"
Name: "{group}\User guide"; Filename: "{app}\TemplateProject manual.md"

Windows has no default handler for .md files. Clicking "User guide" in the Start Menu will likely open a file-association dialog. For a template this is tolerable, but it should be called out prominently so downstream developers remember to replace it with a PDF or HTML file (and update the .iss accordingly) before shipping.

---

3. PRODUCT_NAME is hardcoded in prepare_installer_docs.py

PRODUCT_NAME = "TemplateProject"

This constant is used only for the background image lookup. When duplicate.py creates a new plugin, this string must be updated in the copied script — otherwise the background image is silently skipped with no warning. Either:

• Derive PRODUCT_NAME from the project directory name at runtime, or
• At minimum, add a comment directing developers to update it.

---

Code Quality Notes

4. RTF font table missing family designation

r"{\fonttbl{\f0 Helvetica;}}",

The RTF spec recommends a font family keyword for reliable fallback rendering. Prefer:

r"{\fonttbl{\f0\fswiss Helvetica;}}",

This is cosmetic on macOS but good practice.

---

5. markdown_to_plain_text handles only a subset of Markdown

The converter covers ATX headings, bold, italic, inline code, inline links, and unordered lists. It does not handle:

• Numbered lists (1. item)
• Setext-style headings (Heading\n=======)
• Horizontal rules (---)
• Block quotes (> )

For the current Markdown sources (which are all simple), this is fine. A brief docstring noting the intentional scope would prevent future contributors from adding unsupported syntax and wondering why output looks wrong.

---

6. rtf_escape passes through bare \n characters

elif codepoint <= 0x7f:
    escaped.append(char)

A \n character (codepoint 10) passes through unescaped. In practice this cannot happen since plain_text_to_rtf splits on lines before calling rtf_escape, but the function is not safe to call on multi-line strings. An assert "\n" not in text or a note in the docstring would prevent future misuse.

---

What's Done Well

• release-native.yml bug fix (name=archive_name:: → archive_name=) is correct and important; the old set-output format was deprecated.
• makedist-win.bat error handling for prepare_installer_docs.py is properly guarded with ERRORLEVEL check.
• update_installer-win.py pattern change (Source: "readme' → DestName: "readme.txt") is more precise and less fragile.
• write_text creates output directories automatically, so packaging scripts don't need to pre-create build-mac/installer/resources or build-win/installer-docs.
• LF line endings forced in write_text — correct choice for cross-platform consistency.
• makeinstaller-mac.sh now correctly passes --resources to productbuild and cleans up the generated resources directory afterward.

---

Summary

The three items to address before merging:

1. Add PowerShell exit-code guard in the Windows CI step.
2. Call out (README or .iss comment) that the .md manual must be replaced with a rendered document before shipping a real product.
3. Make PRODUCT_NAME self-describing or derive it dynamically so duplication doesn't silently leave a wrong value.

The rest are minor polish items. Overall this is a clean improvement to developer ergonomics.

[claude]

Code Review — PR #24: Use Markdown for installer and manual docs

Overall this is a well-motivated improvement: Markdown is much easier to maintain than hand-edited RTF/LaTeX, and the generated approach is clean. A few issues are worth addressing before merging.

---

Positive Changes

• Replacing hand-crafted RTF with Markdown source is a big DX win.
• The CI validation steps (checking generated files exist before building) are a good addition.
• Bonus bugfix: the GITHUB_OUTPUT syntax correction in release-native.yml (name=archive_name:: → archive_name=) was broken and is now fixed.
• Error handling added to makedist-win.bat for the new Python step and for Inno Setup.
• Cleanup of generated resources/ dir in makeinstaller-mac.sh is correct.

---

Issues

Potential Bug — Windows TXT line endings

scripts/prepare_installer_docs.py, write_text function:

with open(path, "w", encoding="utf-8", newline="\n") as output_file:

Unix line endings (\n) are used for all output files, including the Windows .txt files fed to Inno Setup. The Inno Setup wizard renders these with RichEdit or Notepad-style viewers that require \r\n; files with bare \n may display as a single run-on line. The write_text function should use newline="\r\n" for .txt targets (or accept an argument), or the build_win_docs function should pass the appropriate ending.

Potential Bug — Underscore italic regex over-matches

markdown_to_plain_text:

line = re.sub(r"_([^_]+)_", r"\1", line)

This will strip underscores from snake_case_identifiers and URLs containing underscores (e.g., some_long_url_path). Markdown italic with underscores is only valid when surrounded by non-word characters. Consider:

line = re.sub(r"(?<!\w)_([^_]+)_(?!\w)", r"\1", line)

Minor — Unrelated changes bundled in PR

Two changes appear unrelated to the Markdown migration:

1. TemplateProject.clap → TemplateProject_x64.clap in TemplateProject.iss — looks like a filename fix for the actual CLAP build output.
2. The GITHUB_OUTPUT syntax fix in release-native.yml.

Both are good fixes but worth calling out explicitly in the PR description (or splitting into a separate PR) so reviewers can audit them independently.

Minor — Unquoted shell variables

makeinstaller-mac.sh:

rm -r $RESOURCES_DIR

The new variable $RESOURCES_DIR (and the pre-existing $PKG_DIR) should be quoted to handle paths with spaces:

rm -r "$RESOURCES_DIR"

Minor — markdown_to_plain_text gaps

The Markdown-to-plain-text converter doesn't handle a few common patterns that could appear in real-world content:

• Setext-style headings (=== / --- underlines)
• Blockquotes (> )
• Horizontal rules (---, ***, ___) — currently passed through as-is
• Ordered list markers (1. item) — only unordered lists (-, *, +) are normalised

For a template these won't matter much, but users duplicating this template to make a real plugin may hit them.

Minor — update_installer-win.py inconsistent indentation

The pre-existing 1-space indentation in the if/else block around lines 53–56 is continued by the new code. While this is a pre-existing issue, the new lines conform to it rather than fixing it, so py_compile passes but the style remains unusual. Worth a note if you ever touch the file again.

---

Summary

Severity	Issue
Should fix	Windows .txt files written with \n — may display incorrectly in Inno Setup wizard
Should fix	_underscore_ italic regex matches inside snake_case words
Nice to have	Quote $RESOURCES_DIR and $PKG_DIR in shell scripts
Informational	Unrelated fixes bundled (CLAP filename, GITHUB_OUTPUT) — fine to keep but worth noting
Informational	Markdown converter misses setext headers, blockquotes, HRs

The core approach is sound. Addressing the line-ending issue and the underscore regex would make this production-ready.

[claude]

Code Review

Overview

This PR is a solid quality-of-life improvement: switching binary/opaque RTF/LaTeX/PDF files to Markdown as the source of truth for installer docs and the user manual. The CI validation additions are a nice touch. A few things worth discussing before merging.

---

Bugs / Issues

1. _italic_ regex strips underscores in identifiers and paths

In prepare_installer_docs.py, the pattern:

line = re.sub(r"_([^_]+)_", r"\1", line)

will incorrectly strip underscores from words like build_mac_docs or readme-win-demo.txt. The same pattern appears in markdown_inline_to_text. Consider requiring word-boundary chars around the underscores, or simply omitting that variant — **bold** and *italic* cover nearly all real-world use.

2. pdf_text silently corrupts non-CP1252 characters

def pdf_text(text):
    text = text.encode("cp1252", "replace").decode("cp1252")

Characters outside the CP1252 range are silently replaced with ?. This will affect any plugin author who puts a non-ASCII character in their manual (e.g. a © or a ™). At minimum, use errors="xmlcharrefreplace" so the substitution is visible, or log a warning when replacements occur.

3. PRODUCT_NAME is hardcoded at the top of prepare_installer_docs.py

PRODUCT_NAME = "TemplateProject"

When duplicate.py creates a new project by substituting "TemplateProject" throughout the tree, this constant will be updated correctly — but if someone edits the script and adds a string literal "TemplateProject" elsewhere, it'll be silently wrong. Worth a comment pointing to duplicate.py as the mechanism that updates this.

4. update_installer-win.py — match pattern is brittle

The match changed from:

if 'Source: "readme' in line:

to:

if 'DestName: "readme.txt"' in line:

The new pattern works for the current template but will silently skip the substitution if the .iss file is ever reformatted. A regex anchored to the full line pattern would be more robust.

---

Moderate Concerns

5. Hand-rolled PDF generator

write_pdf / write_markdown_pdf implement a raw PDF 1.4 serialiser from scratch (~130 lines). This works for simple text but has real limitations:

• Only embeds standard Type 1 fonts (Helvetica / Helvetica-Bold). Behaviour is viewer-dependent if these aren't substituted correctly.
• No Unicode support beyond CP1252 — a significant limitation for international plugin developers.
• Tables, block quotes, nested lists, setext-style headings (===/---), and horizontal rules are not handled.

pandoc (widely available, already used by many CI environments) can convert Markdown → PDF in one command and handles all of the above. If pandoc is too heavy a dependency, reportlab is a pure-Python alternative. The current approach will be hard to maintain as the manual format evolves.

6. build_mac_docs calls os.makedirs inside the background-copy block

if os.path.exists(background):
    os.makedirs(target_dir, exist_ok=True)   # ← inside the if
    shutil.copy2(background, ...)

write_text (called just above) already creates target_dir via os.makedirs, so this call is actually redundant and harmless — but it looks like a logic error on first read. Either remove it or hoist it above the if.

---

Minor Points

• readme-win.md contains BLAH BLAH BLAH placeholder body text — probably intentional for a template, but worth a comment so it doesn't ship by accident.
• The release-native.yml fix (deprecated name=archive_name:: → archive_name=) is a correct bonus bug-fix for a broken $GITHUB_OUTPUT directive. Worth calling out explicitly in the PR description.
• macOS CI step uses set -eo pipefail; Windows CI PowerShell step has no equivalent $ErrorActionPreference = 'Stop'. If cd or python fail silently on Windows, the step could pass with a false positive.
• The makeinstaller-mac.sh now removes RESOURCES_DIR after the build. If the build fails mid-way, the partially-generated resources are cleaned up on the next run anyway (since prepare_installer_docs.py overwrites them), so this is fine — just worth being aware of.

---

What's Working Well

• Removing binary RTF/PDF/TeX from version control is the right call — diffs are now human-readable.
• CI validation of generated files before the build is a good pattern.
• The markdown_to_plain_text and RTF generators are clean and readable for what they do.
• Error handling in makedist-win.bat (checking %ERRORLEVEL% after each key step) is a nice improvement over the previous silent-failure pattern.

Overall this is a good direction. Addressing the _italic_ regex bug (#1) and the CP1252 silent data loss (#2) would be the most important fixes before merging.

[claude]

Code Review: Use Markdown for installer and manual docs

Overview: This PR replaces binary/compiled distribution artefacts (RTF, PDF, LaTeX) with Markdown sources and a Python script to generate installer-ready formats at build time. It also bundles several unrelated bug fixes.

Bug Fixes (three real ones, worth calling out)

• GitHub Actions output syntax (release-native.yml): echo "name=archive_name::..." used the deprecated set-output prefix form, which was silently broken. Correctly fixed.
• AAX install path (makeinstaller-mac.sh): Old code had double double-quotes around the path string, causing the shell to see two words. Fixed correctly.
• CLAP filename (TemplateProject.iss): TemplateProject.clap → TemplateProject_x64.clap. This is a convention change — worth a note in the PR description so downstream projects know to rename their artefacts.

prepare_installer_docs.py

Clean and well-structured overall. A few observations:

Minor — require_tool("pandoc") fires on every run_pandoc call. pandoc_convert is called in a loop, so shutil.which runs multiple times unnecessarily. Moving the check to the top of each build_*_docs function would be cleaner.

Minor — write_text dirname edge case. os.makedirs(os.path.dirname(path), exist_ok=True) will raise FileNotFoundError if path has no directory component (dirname returns ""). All current callers pass full paths so it is safe in practice, but a guard (if dirname: os.makedirs(dirname, ...)) makes the contract explicit.

Key question — does distribution.xml reference the RTF resources? The script now passes --resources "${RESOURCES_DIR}" to productbuild, which bundles the resources directory. However, the distribution.xml heredoc in makeinstaller-mac.sh is not modified in this PR. That template needs elements like <license file="license.rtf"/>, <readme file="readme-mac.rtf"/>, <welcome file="intro.rtf"/> for the RTFs to actually appear in the macOS installer UI. If those elements are already present, great — but it is worth confirming, since the generated RTFs would otherwise be bundled but never displayed.

CI Workflows

Action version pinning. Both pandoc/actions/setup@v1 and typst-community/setup-typst@v5 are pinned by major-version tag rather than a commit SHA. For a template that projects copy and then maintain independently, pinning to a specific patch version or SHA is safer against tag mutations. Low risk for a template, but worth noting.

Redundant check (macOS validate step). test -f "manual/${{matrix.project}} manual.md" verifies a static file that always exists after checkout — it is not a generated artefact and does not add meaningful coverage.

update_installer-win.py

The regex-based detection of the readme entry replaces a fragile substring check and is a clear improvement. The two-regex approach (source line shape + DestName sentinel) is precise and readable.

Shell Scripts — makeinstaller-mac.sh

The systematic quoting of all variable expansions is correct and overdue. Cleanup of ${RESOURCES_DIR} at the end is appropriate since productbuild has already bundled the contents before the rm.

Content Notes

readme-win.md retains the "BLAH BLAH BLAH" placeholder — consistent with the existing RTF and right for a template. The license.md preserves the existing disclaimer text. The Markdown manual stub is minimal but appropriate.

Summary

Solid work. The Markdown-first approach is the right call for maintainability, and the three embedded bug fixes are real improvements that benefit any project derived from this template. The main open question before merging: does distribution.xml already reference the RTF files by name? If not, the macOS installer screens will not display them despite being correctly generated and bundled. Everything else is minor or stylistic.

[claude]

Code Review: Use Markdown for installer and manual docs

Overall this is a well-executed improvement. Switching from binary RTF/LaTeX to editable Markdown dramatically lowers the barrier for updating installer text and documentation. The CI validation, CRLF handling, and shell quoting work are all solid. A few things worth addressing:

---

Bugs fixed (worth calling out)

• CLAP source name (TemplateProject.iss): TemplateProject.clap → TemplateProject_x64.clap — this was a real breakage, good catch.
• GitHub Actions output syntax (release-native.yml): echo "name=archive_name::$ARCHIVE_NAME" → echo "archive_name=$ARCHIVE_NAME" — the old name= prefix syntax is deprecated and silently broken on current runners.
• AAX path double-quoting (makeinstaller-mac.sh): ""/Library/Application Support/Avid/Audio/Plug-Ins"" → proper single-quoted path. The original would have passed a malformed path to pkgbuild.
• productbuild --resources (makeinstaller-mac.sh): Previously called without --resources, so the RTF installer resources weren't being referenced. The new RESOURCES_DIR wiring is correct.

---

Issues

1. CI action version pinning (security)

uses: pandoc/actions/setup@v1
uses: typst-community/setup-typst@v5

Both use floating version tags rather than SHA pins. A malicious push to those tags would silently run arbitrary code in CI with full repository access. Recommend pinning to specific commit SHAs:

uses: pandoc/actions/setup@v1.0.0   # replace with sha: ...
uses: typst-community/setup-typst@v5.0.0

Or at minimum document why floating tags are acceptable here.

2. write_text with a bare filename

def write_text(path, text, newline="\n"):
  os.makedirs(os.path.dirname(path), exist_ok=True)

If path has no directory component (e.g. "foo.txt"), os.path.dirname returns "" and os.makedirs("", exist_ok=True) raises FileNotFoundError. In practice all callers pass full paths so this won't trigger, but it's a footgun. A safer guard:

parent = os.path.dirname(path)
if parent:
    os.makedirs(parent, exist_ok=True)

3. Temp file left behind on pandoc_convert failure

def pandoc_plain_text(source_path, target_path, newline="\n"):
  temp_path = target_path + ".tmp"
  pandoc_convert(source_path, temp_path, "plain", ["--wrap=none"])
  try:
    ...
  finally:
    if os.path.exists(temp_path):
      os.remove(temp_path)

If pandoc_convert itself raises (pandoc not found, non-zero exit), the finally block is never reached and the temp file persists. Move the try/finally to wrap the pandoc_convert call too:

try:
    pandoc_convert(source_path, temp_path, "plain", ["--wrap=none"])
    text = read_text(temp_path).strip() + "\n"
    write_text(target_path, text, newline=newline)
finally:
    if os.path.exists(temp_path):
        os.remove(temp_path)

4. Redundant require_tool("typst") in build_manual_pdf

def build_manual_pdf(build_dir_name):
  require_tool("typst")   # checked here
  ...
  run_pandoc([...])       # run_pandoc -> require_tool("pandoc") checked here

typst is invoked by pandoc as a subprocess (--pdf-engine=typst), not directly by this script. The explicit require_tool("typst") check gives a clearer error message than pandoc would, which is good — but the comment above require_tool (or at least the logic) could note that it's an indirect dependency. Minor nit.

---

Suggestions

.gitignore for generated output

The generated files under build-mac/installer/resources/, build-mac/manual/, build-win/installer-docs/, and build-win/manual/ should be in .gitignore to prevent accidental commits. If they're already covered by existing rules, please confirm.

intro.md email address

The original intro.rtf had contact@acmeinc.com; the new intro.md has support@acmeinc.com. That looks intentional but is worth confirming since it's a template that plugin authors will copy.

Regex in update_installer-win.py

The new is_readme_entry using two separate regexes is much more robust than 'Source: "readme' in line. One tiny suggestion: compile both regexes at module level (already done) and add a brief comment explaining why two checks are needed (to match only the [Files] readme entry and not other readme-named sources).

---

What's good

• pandoc_plain_text properly strips and re-adds a final newline, avoiding trailing-whitespace issues.
• $ErrorActionPreference = 'Stop' + $PSNativeCommandUseErrorActionPreference = $true on Windows correctly catches Python failures in PowerShell.
• Shell variable quoting across makeinstaller-mac.sh is thorough and correct.
• PRODUCT_NAME = os.path.basename(PROJECT_DIR) in prepare_installer_docs.py cleanly derives the product name from context rather than hardcoding.
• The CI validation checks that both the generated artifacts and the Markdown source exist, which catches misconfiguration in either direction.

---

Summary: Address the action SHA pinning (security) and the write_text/temp-file issues before merging. The rest are minor nits. The overall approach is sound and the implementation is clean.