add WIP issues and user story around multi-platform release

Author: betsalel-williamson

docs/issues/01_fix-windows-build-failure.md

@@ -0,0 +1,21 @@
+---
+title: "CI/CD: Build fails on Windows runner due to non-portable `mkdir -p` command"
+labels: bug, ci/cd, chore
+---
+
+### What is happening?
+
+The `npm run build` command fails on the Windows runner in our release workflow. The log shows the error: `A subdirectory or file -p already exists.`
+
+This indicates that the `bash` environment on the Windows runner is not correctly interpreting the `mkdir -p lib` command. Instead of treating `-p` as a flag, it's attempting to create a directory named `-p`.
+
+### Why is this a problem?
+
+This is a critical bug that completely blocks our automated release process. We cannot produce Windows binaries until this is fixed. It violates our **Comprehensive Automation** principle, as our pipeline is not reliable across all target platforms.
+
+### What is the solution?
+
+We must replace the non-portable `mkdir -p` command with a guaranteed cross-platform equivalent from the Node.js ecosystem.
+
+1.  Add the `mkdirp` package as a `devDependency` to `package.json`.
+2.  Update the `build` script in `package.json` to use the `mkdirp lib` command instead of `mkdir -p lib`.

docs/issues/02_macos-gatekeeper-warning.md

@@ -0,0 +1,49 @@
+---
+title: "macOS Release: Binary is blocked by Gatekeeper as from an 'unverified developer'"
+labels: enhancement, build, documentation
+---
+
+### What is happening?
+
+When a user on macOS downloads and tries to run the `template-engine-v...-macos` executable from a GitHub release, they receive a security warning:
+
+> "Apple could not verify 'template-engine-...' is free of malware..."
+
+This is the expected behavior of **macOS Gatekeeper**. Because the application is not signed with a paid Apple Developer ID certificate and has not been notarized by Apple, the operating system treats it as untrusted by default.
+
+### Why is this a problem?
+
+This creates a significant barrier to adoption for macOS users. It makes the tool seem untrustworthy and requires users to know the specific security workarounds to even run the application.
+
+### What is the solution?
+
+There is a two-part solution: a necessary short-term fix and a correct long-term enhancement.
+
+#### Short-Term Solution (Immediate Priority)
+
+We must provide clear instructions to the user. This involves updating the `README.md` to add a section explaining the warning and the standard, safe procedure to run the application.
+
+**Proposed `README.md` addition:**
+
+```markdown
+### Note for macOS Users
+
+When you first run the `template-engine-macos` executable, you may see a security warning from macOS stating that the developer cannot be verified. This is expected behavior for applications that are not notarized through the Apple App Store.
+
+To run the application, you must grant it a one-time security exception:
+1.  Right-click (or Ctrl-click) the `template-engine-macos` file and select "Open".
+2.  You will see the same warning, but this time it will include an "Open" button. Click "Open".
+
+You will only need to do this once. After you grant this exception, you can run the executable normally by double-clicking it or calling it from your terminal.
+```
+
+#### Long-Term Solution (Future User Story)
+
+To remove the warning entirely, the application must be officially signed and notarized by Apple. This is a complex process that involves:
+
+1. Enrolling in the paid Apple Developer Program.
+2. Generating a "Developer ID Application" certificate.
+3. Updating the `release.yml` workflow to use this certificate (stored as a secret) to sign the macOS binary.
+4. Adding a step to submit the signed binary to Apple's notarization service and "staple" the resulting ticket to the executable.
+
+This should be tracked as a separate, future enhancement.

docs/user_stories/tooling_and_ci/20_implement-cross-platform-build-scripts.md

@@ -0,0 +1,18 @@
+# Story 20: Implement Cross-Platform Reliable Build Scripts
+
+- **Project**: `template-engine-ts`
+- **Status**: `todo`
+- **As an** Engineering Team,
+- **I want to** use build scripts that are fully cross-platform compatible,
+- **so that** our CI/CD pipeline runs reliably on all operating systems (Linux, macOS, Windows) without platform-specific errors.
+
+## Acceptance Criteria
+
+- The `npm run build` command must execute successfully on a clean checkout on Windows, macOS, and Linux runners.
+- Native shell commands with known platform inconsistencies (like `mkdir -p`) must be replaced with cross-platform equivalents from the Node.js ecosystem (e.g., `mkdirp`).
+- The CI pipeline must not produce any shell-specific errors related to file or directory creation.
+
+## Metrics for Success
+
+- **Primary Metric**: "Change Failure Rate for the CI pipeline is reduced to 0% for build-script-related issues."
+- **Secondary Metrics**: "Developer time spent debugging platform-specific CI failures is reduced."