Cloud2BR · brown9804 · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.yml
@@ -2,11 +2,18 @@ name: Build Desktop Artifacts
 
 on:
   workflow_dispatch:
+    inputs:
+      tag_name:
+        description: Version tag to build and publish, for example v0.0.2
+        required: true
+        type: string
+      release_name:
+        description: Optional release title override
+        required: false
+        type: string
   push:
     tags:
       - 'v*'
-  release:
-    types: [published]
 
 permissions:
   contents: write
@@ -79,7 +86,7 @@ jobs:
           if-no-files-found: error
 
   publish:
-    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch' || github.event_name == 'release'
+    if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
     needs: build
     runs-on: ubuntu-latest
     steps:
@@ -95,17 +102,18 @@ jobs:
       - name: Compute release tag
         id: release_meta
         run: |
-          if [[ "${GITHUB_EVENT_NAME}" == "release" ]]; then
-            TAG_NAME="${{ github.event.release.tag_name }}"
+          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+            TAG_NAME="${{ github.event.inputs.tag_name }}"
+            RELEASE_NAME="${{ github.event.inputs.release_name }}"
             echo "tag_name=${TAG_NAME}" >> "$GITHUB_OUTPUT"
-            echo "release_name=Docs Foundry ${TAG_NAME}" >> "$GITHUB_OUTPUT"
+            if [[ -n "${RELEASE_NAME}" ]]; then
+              echo "release_name=${RELEASE_NAME}" >> "$GITHUB_OUTPUT"
+            else
+              echo "release_name=Docs Foundry ${TAG_NAME}" >> "$GITHUB_OUTPUT"
+            fi
           elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
             echo "tag_name=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
             echo "release_name=Docs Foundry ${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
-          else
-            TAG_NAME="manual-${GITHUB_RUN_NUMBER}"
-            echo "tag_name=${TAG_NAME}" >> "$GITHUB_OUTPUT"
-            echo "release_name=Docs Foundry ${TAG_NAME}" >> "$GITHUB_OUTPUT"
           fi
 
       - name: Delete existing release if present

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -40,7 +40,7 @@ This Code of Conduct is adapted from the [Contributor Covenant](https://www.cont
 
 <!-- START BADGE -->
 <div align="center">
-  <img src="https://img.shields.io/badge/Total%20views-3-limegreen" alt="Total views">
+  <img src="https://img.shields.io/badge/Total%20views-0-limegreen" alt="Total views">
   <p>Refresh Date: 2026-04-13</p>
 </div>
 <!-- END BADGE -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -82,7 +82,7 @@ Open an issue on GitHub with reproduction steps. Include OS, app version, and an
 
 <!-- START BADGE -->
 <div align="center">
-  <img src="https://img.shields.io/badge/Total%20views-3-limegreen" alt="Total views">
+  <img src="https://img.shields.io/badge/Total%20views-0-limegreen" alt="Total views">
   <p>Refresh Date: 2026-04-13</p>
 </div>
 <!-- END BADGE -->
diff --git a/README.md b/README.md
@@ -10,19 +10,96 @@ Last updated: 2026-02-25
 
 > DocFoundry is an open-source **Electron** desktop app for writing and previewing Markdown documentation with a live split-pane editor, local folder tree, safe local saves, container-only development for contributors, and installable binaries for macOS, Windows, and Linux.
 
+
+<details>
+<summary>Table of contents</summary>
+
+- [What's included](#whats-included)
+- [Repository tree](#project-structure)
+- [Roadmap](#roadmap)
+- [Mode 1: Container-only development](#mode-1-container-only-development)
+- [Mode 2: End-user desktop app install](#mode-2-end-user-desktop-app-install)
+- [GitHub Pages](#github-pages)
+- [Pipelines included](#pipelines-included)
+- [Quality & Testing](#quality--testing)
+
+</details>
+
 ## What's included
 
 > DocFoundry ships multi-tab editing, split-pane live preview, a command palette, workspace-wide search, in-file find and replace, a document outline, file operations (create, rename, delete), auto-save, HTML export, zen mode, resizable panes, a keyboard shortcuts overlay, a status bar (word count, reading time, cursor position), breadcrumbs, and full Markdown rendering (headings, bold/italic, lists, task lists, tables, code blocks, blockquotes, images, links, horizontal rules, strikethrough, highlight, footnotes). The app includes unsaved-change protection on close, a file watcher for external changes, native menus with keyboard accelerators, and a secure architecture (contextIsolation, no nodeIntegration, validated file paths).
 
 For the full changelog and per-version details, see [Releases](https://github.com/Cloud2BR/docs-foundry/releases).
 
+> [!NOTE]
+> Desktop releases are published when you push a `v*` tag or when you manually run `.github/workflows/release-desktop.yml` with a `tag_name` input.
+
+<details>
+<summary>Expand repository tree</summary>
+
+```text
+DocFoundry/
+├── src/
+│   ├── main.js               # Electron main process (IPC, menu, file watcher)
+│   ├── preload.js            # Secure IPC bridge (contextBridge)
+│   ├── lib/
+│   │   └── workspace-path.js # Secure path validation
+│   └── renderer/
+│       ├── index.html        # Desktop app shell (welcome + workspace)
+│       ├── styles.css        # Full UI styling
+│       ├── renderer.js       # Tabs, palette, search, outline, editor logic
+│       └── markdown.js       # Shared Markdown→HTML parser (UMD)
+├── build/
+│   ├── icon.svg              # App icon source
+│   └── generate-icons.sh     # SVG to PNG/ICO/ICNS converter
+├── docs/
+│   ├── .nojekyll
+│   ├── index.html            # GitHub Pages overview page
+│   ├── downloads.html        # Download/install guide backed by GitHub Releases
+│   ├── roadmap.html          # Public roadmap view on GitHub Pages
+│   └── feedback.html         # Public feedback page routed to a separate GitHub repo
+├── tests/
+│   ├── smoke.test.mjs        # Structure, security, and feature-surface tests
+│   ├── markdown.test.mjs     # Markdown parser tests
+│   └── workspace-path.test.mjs # Path validation tests
+├── scripts/
+│   └── setup.sh              # OS detection and Docker validation
+├── .github/
+│   ├── PULL_REQUEST_TEMPLATE.md
+│   ├── ISSUE_TEMPLATE/
+│   │   ├── bug_report.md
+│   │   └── feature_request.md
+│   └── workflows/
+│       ├── deploy-pages.yml
+│       ├── release-desktop.yml
+│       ├── auto-fill-pr.yml
+│       ├── update-md-date.yml
+│       ├── update_date.py
+│       ├── use-visitor-counter.yml
+│       └── cleanup-pages-history.yml
+├── Dockerfile.dev            # Container dev image (node:20-bookworm)
+├── Makefile                  # setup, dev, lint, format, test, package targets
+├── vitest.config.mjs         # Vitest configuration
+├── eslint.config.mjs         # ESLint flat config (v9+)
+├── .prettierrc               # Prettier configuration
+├── CONTRIBUTING.md
+├── CODE_OF_CONDUCT.md
+├── SECURITY.md
+├── LICENSE
+└── README.md
+```
+
+</details>
+
 ## Roadmap
 
-> Git change indicators and diff view, broken-link checks and link autocomplete, PDF export, scroll sync between editor and preview, drag-and-drop file and image support, Mermaid diagram rendering, spell check.
+Live roadmap page: [Docs Foundry Roadmap](https://cloud2br.github.io/docs-foundry/roadmap.html)
+Product feedback page: [Docs Foundry Feedback](https://cloud2br.github.io/docs-foundry/feedback.html)
 
-## Two operating modes
+> [!IMPORTANT]
+> The feedback page prepopulates requests in the GitHub Pages UI and routes them into [Cloud2BR/docs-foundry-feedback](https://github.com/Cloud2BR/docs-foundry-feedback). The production flow opens a prefilled issue there and lets that repo process it with a GitHub Actions intake workflow after submission.
 
-### Mode 1: Container-only development
+## Mode 1: Container-only development
 
 > This mode is for maintainers and contributors who do not want local Node.js or npm installation.
 
@@ -42,47 +119,23 @@ For the full changelog and per-version details, see [Releases](https://github.co
 - Builds the dev image.
 - Installs project dependencies only inside the container.
 
-### Mode 2: End-user desktop app install
+## Mode 2: End-user desktop app install
 
 > This mode is for users who just want to install and run DocFoundry.
 
 - macOS outputs: `.dmg` (recommended), `.zip` (advanced/manual fallback)
 - Windows outputs: `NSIS installer`, `.zip`
 - Linux outputs: `AppImage`, `.deb`, `.tar.gz`
 
-Build artifacts go to `release/`.
-
-#### macOS — "damaged and can't be opened" (Gatekeeper)
-
-DocFoundry is unsigned (no Apple Developer certificate). Use the `.dmg` first when downloading from GitHub Releases. macOS quarantines apps downloaded from the internet. If you open the `.zip` build and macOS blocks it, run this once after downloading:
-
-```bash
-xattr -cr /Applications/DocFoundry.app
-```
-
-Or if you extracted from the ZIP before moving to Applications:
-
-```bash
-xattr -cr /path/to/DocFoundry.app
-```
-
-Then double-click the app normally.
-
-#### Windows — SmartScreen warning
-
-Click **More info → Run anyway** on the SmartScreen prompt. This appears because the installer is not signed with a code-signing certificate.
+Build artifacts go to [`release/`](https://github.com/Cloud2BR/docs-foundry/releases)
 
-## Build binaries
+| Platform | Release files | Recommended install path | First-run notes | Build command |
+|---|---|---|---|---|
+| macOS | `.dmg`, `.zip` | Download the `.dmg` from GitHub Releases and drag `DocFoundry.app` into `Applications`. Use the `.zip` only as a fallback. | The app is unsigned, so Gatekeeper may block the ZIP build. If macOS says the app is damaged, run `xattr -cr /Applications/DocFoundry.app` after moving it to `Applications`, or run `xattr -cr /path/to/DocFoundry.app` on the extracted app bundle before opening it. | `make package-mac` |
+| Windows | `NSIS installer`, `.zip` | Use the NSIS installer for the normal install flow. Use the ZIP when you want a manual or portable-style extraction. | Windows SmartScreen may show a warning because the installer is not code-signed. Click **More info → Run anyway** to continue. | `make package-win` |
+| Linux | `AppImage`, `.deb`, `.tar.gz` | Use the package format that matches your environment: `AppImage` for portable use, `.deb` for Debian/Ubuntu installs, or `.tar.gz` for manual extraction. | `AppImage` usually needs `chmod +x` before running. For `.deb`, install with `sudo apt install ./DocFoundry.deb` or the generated filename in `release/`. Linux packaging is intended to run from the container workflow. | `make package-linux` |
 
-### From host machine
-
-- make package
-- make package-mac
-- make package-win
-
-### Linux package build from container
-
-- make package-linux
+For a local multi-platform packaging pass from a compatible host environment, use `make package`.
 
 ## GitHub Pages
 
@@ -97,64 +150,14 @@ This repo includes a Pages workflow in `.github/workflows/deploy-pages.yml` and
 ## Pipelines included
 
 - `.github/workflows/deploy-pages.yml`: deploys GitHub Pages.
-- `.github/workflows/release-desktop.yml`: builds desktop binaries on macOS, Windows, Linux and publishes on tags.
+- `.github/workflows/release-desktop.yml`: builds desktop binaries on macOS, Windows, Linux and publishes a tagged GitHub Release on `v*` tags or manual dispatch with `tag_name`.
 - `.github/workflows/update-md-date.yml`: updates README date automatically.
 - `.github/workflows/use-visitor-counter.yml`: updates README visitor badge.
 - `.github/workflows/cleanup-pages-history.yml`: cleans old Pages workflow runs.
 
-## Project structure
-
-```
-DocFoundry/
-├── src/
-│   ├── main.js              # Electron main process (IPC, menu, file watcher)
-│   ├── preload.js           # Secure IPC bridge (contextBridge)
-│   ├── lib/
-│   │   └── workspace-path.js # Secure path validation
-│   └── renderer/
-│       ├── index.html       # Desktop app shell (welcome + workspace)
-│       ├── styles.css       # Full UI styling
-│       ├── renderer.js      # Tabs, palette, search, outline, editor logic
-│       └── markdown.js      # Shared Markdown→HTML parser (UMD)
-├── build/
-│   ├── icon.svg             # App icon source
-│   └── generate-icons.sh   # SVG → PNG/ICO/ICNS converter
-├── tests/
-│   ├── smoke.test.mjs       # Structure, security & feature-surface tests
-│   ├── markdown.test.mjs    # Markdown parser tests
-│   └── workspace-path.test.mjs # Path validation tests
-├── docs/
-│   └── index.html           # GitHub Pages landing & download page
-├── scripts/
-│   └── setup.sh             # OS detection & Docker validation
-├── .github/
-│   ├── PULL_REQUEST_TEMPLATE.md
-│   ├── ISSUE_TEMPLATE/
-│   │   ├── bug_report.md
-│   │   └── feature_request.md
-│   └── workflows/
-│       ├── deploy-pages.yml
-│       ├── release-desktop.yml
-│       ├── auto-fill-pr.yml
-│       ├── update-md-date.yml
-│       ├── update_date.py
-│       ├── use-visitor-counter.yml
-│       └── cleanup-pages-history.yml
-├── Dockerfile.dev            # Container dev image (node:20-bookworm)
-├── Makefile                  # setup, dev, lint, format, test, package targets
-├── vitest.config.mjs         # Vitest configuration
-├── eslint.config.mjs         # ESLint flat config (v9+)
-├── .prettierrc               # Prettier configuration
-├── CONTRIBUTING.md
-├── CODE_OF_CONDUCT.md
-├── SECURITY.md
-├── LICENSE
-└── README.md
-```
-
 ## Quality & Testing
 
-Run code quality checks and tests inside the container:
+> Run code quality checks and tests inside the container:
 
 ```
 make lint       # ESLint
@@ -164,7 +167,7 @@ make test       # Vitest
 
 <!-- START BADGE -->
 <div align="center">
-  <img src="https://img.shields.io/badge/Total%20views-3-limegreen" alt="Total views">
+  <img src="https://img.shields.io/badge/Total%20views-0-limegreen" alt="Total views">
   <p>Refresh Date: 2026-04-13</p>
 </div>
 <!-- END BADGE -->
diff --git a/SECURITY.md b/SECURITY.md
@@ -37,7 +37,7 @@ If you discover a security vulnerability in DocFoundry, please report it respons
 
 <!-- START BADGE -->
 <div align="center">
-  <img src="https://img.shields.io/badge/Total%20views-3-limegreen" alt="Total views">
+  <img src="https://img.shields.io/badge/Total%20views-0-limegreen" alt="Total views">
   <p>Refresh Date: 2026-04-13</p>
 </div>
 <!-- END BADGE -->