docs(ci): polish GitHub workflows, templates, and release-note structure

.github/DISCUSSIONS_GUIDE.md

@@ -0,0 +1,13 @@
+# Discussions Guide
+
+Use GitHub Discussions for community threads that are not actionable bugs.
+
+Categories:
+- `Ideas`: product ideas and enhancement proposals.
+- `Q&A`: usage questions and troubleshooting help.
+- `Show and tell` (Showcase): share workflows, screenshots, and setups.
+
+Direct links:
+- Ideas: https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/ideas
+- Q&A: https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/q-a
+- Showcase (Show and tell): https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/show-and-tell

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -38,6 +38,15 @@ body:
     validations:
       required: true
 
+  - type: input
+    id: device_model
+    attributes:
+      label: Device model
+      description: Hardware used when issue happened
+      placeholder: "MacBook Pro M3 / iPad Pro 13-inch (M5) / iPhone 16 Pro"
+    validations:
+      required: true
+
   - type: textarea
     id: repro
     attributes:
@@ -77,6 +86,15 @@ body:
     validations:
       required: true
 
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots or recordings
+      description: Attach screenshots/screen recordings or paste links.
+      placeholder: "Drag files here or paste links."
+    validations:
+      required: true
+
   - type: textarea
     id: additional
     attributes:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,20 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Questions / Discussions
-    url: https://github.com/h3pdesign/Neon-Vision-Editor/discussions
-    about: Please ask questions here if it's not a bug or feature request.
+  - name: Discussions - Ideas
+    url: https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/ideas
+    about: Product ideas and enhancement concepts.
+  - name: Discussions - Q&A
+    url: https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/q-a
+    about: Usage questions and troubleshooting.
+  - name: Discussions - Showcase
+    url: https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/show-and-tell
+    about: Share workflows, screenshots, and setups.
+  - name: Roadmap
+    url: https://github.com/h3pdesign/Neon-Vision-Editor/issues/49
+    about: Review current roadmap items.
+  - name: Known issues
+    url: https://github.com/h3pdesign/Neon-Vision-Editor/issues/50
+    about: Check known issues before opening a new bug.
+  - name: Contributing fast track
+    url: https://github.com/h3pdesign/Neon-Vision-Editor/issues/51
+    about: Start with newcomer-friendly tasks.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -37,6 +37,14 @@ body:
     validations:
       required: true
 
+  - type: input
+    id: device_model
+    attributes:
+      label: Device model (if relevant)
+      placeholder: "MacBook Pro M3 / iPad Pro 13-inch (M5) / iPhone 16 Pro"
+    validations:
+      required: true
+
   - type: textarea
     id: problem
     attributes:
@@ -45,6 +53,18 @@ body:
     validations:
       required: true
 
+  - type: textarea
+    id: repro_or_current_flow
+    attributes:
+      label: Current flow (repro of the gap)
+      description: How does the current flow behave today?
+      placeholder: |
+        1. Open ...
+        2. Try ...
+        3. Observe limitation ...
+    validations:
+      required: true
+
   - type: textarea
     id: proposal
     attributes:
@@ -53,6 +73,14 @@ body:
     validations:
       required: true
 
+  - type: textarea
+    id: expected_behavior
+    attributes:
+      label: Expected behavior
+      description: Describe the expected end-user behavior after implementation.
+    validations:
+      required: true
+
   - type: textarea
     id: acceptance
     attributes:
@@ -87,3 +115,12 @@ body:
       description: What else did you try?
     validations:
       required: false
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Mockups / screenshots / references
+      description: Attach visuals or links to illustrate the request.
+      placeholder: "Drag files here or paste links."
+    validations:
+      required: false

.github/pull_request_template.md

@@ -3,6 +3,7 @@
 - What changed:
 - Why:
 - Scope: Bugfix / Feature / Docs / Release
+- Linked issue/milestone:
 
 ## Validation
 
@@ -25,4 +26,5 @@
 ## Risk
 
 - Risk level: Low / Medium / High
+- User-facing risk:
 - Rollback plan:

Neon Vision Editor.xcodeproj/project.pbxproj

@@ -361,7 +361,7 @@
 				CODE_SIGNING_ALLOWED = YES;
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 468;
+				CURRENT_PROJECT_VERSION = 469;
 				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = CS727NF72U;
 				ENABLE_APP_SANDBOX = YES;
@@ -444,7 +444,7 @@
 				CODE_SIGNING_ALLOWED = YES;
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 468;
+				CURRENT_PROJECT_VERSION = 469;
 				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = CS727NF72U;
 				ENABLE_APP_SANDBOX = YES;

README.md

@@ -47,12 +47,33 @@
 - Quick install: [GitHub Releases](https://github.com/h3pdesign/Neon-Vision-Editor/releases), [App Store](https://apps.apple.com/de/app/neon-vision-editor/id6758950965), [TestFlight](https://testflight.apple.com/join/YWB2fGAP)
 - Need help quickly: [Troubleshooting](#troubleshooting) | [FAQ](#faq) | [Known Issues](#known-issues)
 
-### 30-Second Quickstart (Source Build)
+### Start in 60s (Source Build)
 
 1. `git clone https://github.com/h3pdesign/Neon-Vision-Editor.git`
 2. `cd Neon-Vision-Editor`
 3. `xcodebuild -project "Neon Vision Editor.xcodeproj" -scheme "Neon Vision Editor" -destination 'platform=macOS,name=My Mac' build`
-4. `open "Neon Vision Editor.xcodeproj"` and run the app in Xcode.
+4. `open "Neon Vision Editor.xcodeproj"` and run, then use `Cmd+P` for Quick Open.
+
+| For | Not For |
+|---|---|
+| Fast native editing across macOS, iOS, iPadOS | Full IDE workflows with deep refactoring/debugger stacks |
+| Markdown writing and script/config edits with highlighting | Teams that require complete Intel Mac validation today |
+| Users who want low overhead and quick file access | Users expecting full desktop-IDE parity on iPhone |
+
+## Table of Contents
+
+- [Start Here](#start-here)
+- [Release Channels](#release-channels)
+- [Download Metrics](#download-metrics)
+- [Project Docs](#project-docs)
+- [Features](#features)
+- [Platform Matrix](#platform-matrix)
+- [Roadmap (Near Term)](#roadmap-near-term)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+- [Changelog](#changelog)
+- [Contributing Quickstart](#contributing-quickstart)
+- [Support & Feedback](#support--feedback)
 
 ## Release Channels
 
@@ -530,7 +551,7 @@ shasum -a 256 <downloaded-file>
 
 ## Build from source
 
-If you already completed the [30-Second Quickstart (Source Build)](#30-second-quickstart-source-build), you can open and run directly from Xcode.
+If you already completed the [Start in 60s (Source Build)](#start-in-60s-source-build), you can open and run directly from Xcode.
 
 ```bash
 git clone https://github.com/h3pdesign/Neon-Vision-Editor.git
@@ -564,7 +585,10 @@ scripts/ci/build_platform_matrix.sh
 ## Support & Feedback
 
 - Questions and ideas: [GitHub Discussions](https://github.com/h3pdesign/Neon-Vision-Editor/discussions)
-- Known issues: [label:known-issue](https://github.com/h3pdesign/Neon-Vision-Editor/issues?q=is%3Aissue%20is%3Aopen%20label%3Aknown-issue)
+- Discussions categories: [Ideas](https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/ideas) | [Q&A](https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/q-a) | [Showcase](https://github.com/h3pdesign/Neon-Vision-Editor/discussions/categories/show-and-tell)
+- Project board (Now / Next / Later): [Roadmap Hub #49](https://github.com/h3pdesign/Neon-Vision-Editor/issues/49)
+- Known issues: [Known Issues Hub #50](https://github.com/h3pdesign/Neon-Vision-Editor/issues/50)
+- Contributing fast track: [Contributing Hub #51](https://github.com/h3pdesign/Neon-Vision-Editor/issues/51)
 - Feature requests: [label:enhancement](https://github.com/h3pdesign/Neon-Vision-Editor/issues?q=is%3Aissue%20is%3Aopen%20label%3Aenhancement)
 
 ## Git hooks

release/RELEASE_NOTES_TEMPLATE.md

@@ -0,0 +1,34 @@
+# Release Notes Template
+
+Use this exact structure for each release section in `CHANGELOG.md`.
+
+```md
+## [vX.Y.Z] - YYYY-MM-DD
+
+### Hero Screenshot
+- ![vX.Y.Z hero screenshot](docs/images/<hero-image>.png)
+
+### Why Upgrade
+- <user-facing reason 1>
+- <user-facing reason 2>
+- <user-facing reason 3>
+
+### Highlights
+- <major enhancement>
+- <major enhancement>
+
+### Fixes
+- <important bug fix>
+- <important bug fix>
+
+### Breaking changes
+- None.
+
+### Migration
+- None.
+```
+
+Rules:
+- Keep `Why Upgrade` to at least 3 concise bullets.
+- Always include exactly one hero screenshot in the `Hero Screenshot` section.
+- If no breaking changes or migration steps exist, keep `None.` entries.

release/TestFlight-Upload-Checklist.md

@@ -30,6 +30,13 @@
 - Fill export compliance if prompted.
 - Add internal testers and release notes.
 - For external testing: submit Beta App Review.
+- Follow release-notes structure from `release/RELEASE_NOTES_TEMPLATE.md`:
+  - Hero screenshot
+  - Why Upgrade (3 bullets)
+  - Highlights
+  - Fixes
+  - Breaking changes
+  - Migration
 
 ## 7) If export/upload fails
 - `No provider associated with App Store Connect user`: fix Apple ID account/provider access in Xcode Accounts.

scripts/ci/release_notes_quality_gate.sh

@@ -29,6 +29,34 @@ if grep -nEi "\\bTODO\\b" "${SECTION_FILE}" >/dev/null; then
   exit 1
 fi
 
+echo "Validating release notes structure..."
+required_headings=(
+  "### Hero Screenshot"
+  "### Why Upgrade"
+  "### Highlights"
+  "### Fixes"
+  "### Breaking changes"
+  "### Migration"
+)
+for heading in "${required_headings[@]}"; do
+  if ! grep -nF "${heading}" "${SECTION_FILE}" >/dev/null; then
+    echo "Release notes for ${TAG} are missing required heading: ${heading}" >&2
+    exit 1
+  fi
+done
+
+hero_block="$(awk '/^### Hero Screenshot/{flag=1; next} /^### /{flag=0} flag {print}' "${SECTION_FILE}")"
+if ! printf '%s\n' "${hero_block}" | grep -Eq '!\[[^]]*\]\([^)]*\)'; then
+  echo "Release notes for ${TAG} need a hero screenshot markdown image under '### Hero Screenshot'." >&2
+  exit 1
+fi
+
+why_upgrade_count="$(awk '/^### Why Upgrade/{flag=1; next} /^### /{flag=0} flag && /^- /{count++} END{print count+0}' "${SECTION_FILE}")"
+if (( why_upgrade_count < 3 )); then
+  echo "Release notes for ${TAG} require at least 3 bullets under '### Why Upgrade'." >&2
+  exit 1
+fi
+
 echo "Validating README What's New heading..."
 mapfile -t RELEASE_TAGS < <(grep -E '^## \[v[^]]+\] - [0-9]{4}-[0-9]{2}-[0-9]{2}$' CHANGELOG.md | sed -E 's/^## \[(v[^]]+)\].*$/\1/')
 PREV_TAG=""

scripts/prepare_release_docs.py

@@ -48,12 +48,20 @@ def add_changelog_section(changelog: str, tag: str, date: str) -> str:
     heading = f"## [{tag}] - {date}"
     template = (
         f"{heading}\n\n"
-        "### Added\n"
+        "### Hero Screenshot\n"
+        "- ![TODO hero screenshot](docs/images/TODO-release-hero.png)\n\n"
+        "### Why Upgrade\n"
+        "- TODO\n"
+        "- TODO\n"
         "- TODO\n\n"
-        "### Improved\n"
+        "### Highlights\n"
         "- TODO\n\n"
-        "### Fixed\n"
+        "### Fixes\n"
         "- TODO\n\n"
+        "### Breaking changes\n"
+        "- None.\n\n"
+        "### Migration\n"
+        "- None.\n\n"
     )
     first_release = re.search(r"^## \[", changelog, flags=re.M)
     if not first_release: