garotm - final cleanup before first release.

Author: garotm

.github/workflows/release.yml

@@ -101,6 +101,28 @@ jobs:
           if-no-files-found: warn
           retention-days: 30
 
+      # ── Extract changelog entry for this tag ────────────────────────────────
+      - name: Extract changelog body
+        if: startsWith(github.ref, 'refs/tags/')
+        id: changelog
+        shell: pwsh
+        run: |
+          $tag = "${{ github.ref_name }}"          # e.g. v0.2.0
+          $version = $tag.TrimStart('v')            # e.g. 0.2.0
+          $content = Get-Content CHANGELOG.md -Raw
+
+          # Match the section for this version: from "## [X.Y.Z]" to the next "## ["
+          $pattern = "(?s)## \[$version\][^\n]*\n(.*?)(?=\n## \[|\z)"
+          if ($content -match $pattern) {
+            $body = $Matches[1].Trim()
+          } else {
+            $body = "See [CHANGELOG.md](https://github.com/fleXRPL/sift/blob/main/CHANGELOG.md) for details."
+          }
+
+          # Write to a file to avoid multiline output quoting issues
+          $body | Out-File -FilePath release-notes.txt -Encoding utf8
+          Write-Host "Extracted release notes for $version"
+
       # ── GitHub Release (tags only) ───────────────────────────────────────────
       - name: Create GitHub Release
         if: startsWith(github.ref, 'refs/tags/')
@@ -109,6 +131,6 @@ jobs:
           files: |
             src-tauri/target/release/bundle/nsis/*.exe
             src-tauri/target/release/bundle/msi/*.msi
-          generate_release_notes: true
+          body_path: release-notes.txt
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -39,41 +39,75 @@ Full guides live in **[docs/](docs/README.md)**:
 
 ### Prerequisites
 
-- [Rust](https://www.rust-lang.org/tools/install) (latest stable)
-- [Node.js](https://nodejs.org/) (v18+)
-- [WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) (included on most Windows 10/11 systems)
+- [Rust](https://www.rust-lang.org/tools/install) (latest stable — run `rustup update stable`)
+- [Node.js](https://nodejs.org/) v18+
+- [Ollama](https://ollama.com/) running locally with a compatible model (e.g. `ollama run gemma4:26b`)
+- [WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) (pre-installed on most Windows 10/11 systems)
 
 ### Clone, install, run
 
 ```bash
 git clone https://github.com/fleXRPL/sift.git
 cd sift
-npm install && npm install --prefix frontend && npm install --prefix backend
-npm run dev
+node sift.mjs deps    # installs all npm dependencies (root + frontend + backend)
+node sift.mjs check   # pre-flight: verifies Node, Rust, Ollama, and configured model
+node sift.mjs run     # starts Tauri dev shell + Vite + backend in one command
 ```
 
-See [docs/QUICKSTART.md](docs/QUICKSTART.md) for a step-by-step checklist.
+See [docs/QUICKSTART.md](docs/QUICKSTART.md) for the full step-by-step checklist.
+
+### `sift.mjs` CLI reference
+
+| Command | What it does |
+| ------- | ------------ |
+| `node sift.mjs run` | Start the full dev stack (Tauri + Vite + backend) |
+| `node sift.mjs check` | Pre-flight check: Node, Rust, deps, Ollama, model |
+| `node sift.mjs deps` | Install all npm dependencies |
+| `node sift.mjs debug` | Start with verbose logging |
+| `node sift.mjs stop` | Kill all running dev processes |
+| `node sift.mjs package` | Bundle the backend into a Windows sidecar `.exe` |
 
 ### Tests and CI
 
 ```bash
-npm test
+npm test                        # run all backend + frontend tests
+npm test --prefix backend       # backend only (Jest)
+npm test --prefix frontend      # frontend only (Vitest)
 ```
 
-Continuous integration is defined in [`.github/workflows/ci.yml`](.github/workflows/ci.yml) (backend, frontend, Rust `cargo check`). Details: [docs/TESTING.md](docs/TESTING.md).
+Continuous integration runs on every push and PR via [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — covers backend (Jest), frontend (Vitest + build), and Rust (`cargo check`). Details: [docs/TESTING.md](docs/TESTING.md).
+
+### Creating a release
+
+Push a version tag to trigger the automated Windows installer build:
+
+```bash
+# 1. Bump version in tauri.conf.json, Cargo.toml, and package.json (keep in sync)
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+GitHub Actions builds a signed NSIS `.exe` installer on `windows-latest` and attaches it to a GitHub Release automatically. See [docs/BUILD-AND-RELEASE.md](docs/BUILD-AND-RELEASE.md) for full details, manual build steps, and code-signing setup.
 
 ---
 
 ## Project structure
 
 ```text
 sift/
-├── .github/        # GitHub Actions workflows
+├── .cursor/
+│   ├── rules/      # Cursor coding rules (TypeScript, Rust, security, testing)
+│   └── skills/     # On-demand healthcare skills (PHI, HIPAA, EMR, CDSS)
+├── .github/
+│   ├── workflows/ci.yml       # CI: backend, frontend, cargo check
+│   └── workflows/release.yml  # Release: Windows NSIS installer on version tag
 ├── docs/           # Documentation (start at docs/README.md)
 ├── frontend/       # Vite + React + Tailwind UI
 ├── backend/        # Node orchestrator (Express, SQLite, ingest, LLM client)
-├── src-tauri/      # Tauri host: tray, folder watch → POST /api/ingest
-├── img/            # Brand assets (e.g. icon source for Tauri)
+├── src-tauri/      # Tauri host: tray, folder watch, sidecar lifecycle
+├── samples/        # Sample FHIR, HL7, and PDF files for manual testing
+├── img/            # Brand assets (icon source for Tauri)
+├── sift.mjs        # Developer CLI (run / check / deps / debug / stop / package)
 └── data/           # Local SQLite (sift.db), created at runtime
 ```
 
@@ -88,7 +122,3 @@ See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md). Testing strategy and CI expect
 ## 📜 License
 
 Distributed under the **MIT License**. See `LICENSE` for more information.
-
----
-
-**Windows release:** build the Node sidecar with `npm run package --prefix backend` (requires `pkg`), place `llama-server` next to the app per `docs/Transform-Summary.md`, then add `externalBin` entries in `src-tauri/tauri.conf.json` before bundling.

docs/BUILD-AND-RELEASE.md

@@ -74,28 +74,127 @@ src-tauri/target/release/bundle/nsis/Sift_<version>_x64-setup.exe
 
 ---
 
-## GitHub Actions — automated Windows release
+## CI — `cargo check` and the sidecar stub
+
+Tauri's build script validates that every `externalBin` entry exists on disk with the correct
+target-triple suffix before compiling — even during `cargo check`. Because the real backend
+binary is only produced in the release workflow (on Windows), CI would fail if it ran
+`cargo check` against an empty `binaries/` directory.
+
+The `tauri-host` job in `ci.yml` works around this by creating a zero-byte stub before
+`cargo check` runs:
+
+```yaml
+- name: Create sidecar stub for cargo check
+  run: |
+    mkdir -p src-tauri/binaries
+    touch src-tauri/binaries/sift-backend-x86_64-unknown-linux-gnu
+    chmod +x src-tauri/binaries/sift-backend-x86_64-unknown-linux-gnu
+```
 
-Workflow: [`.github/workflows/release.yml`](../.github/workflows/release.yml)
+Tauri's build script only checks existence, not content, so the type-check passes cleanly.
+The real binary is built and verified only in `release.yml` on `windows-latest`.
+
+---
+
+## Release workflow
+
+Sift uses a **release branch** pattern: all feature work lands on `main`, a
+dedicated `release/vX.Y.Z` branch is used to finalise the changelog and bump
+versions, that branch is PR'd back to `main`, and the tag is pushed only after
+the PR merges. This keeps the changelog reviewed and the tag pointing at a clean,
+deliberate commit.
+
+### Step-by-step release process
+
+#### 1. Finish feature work on `main`
+
+Merge all feature PRs to `main` as normal. CI must be green before proceeding.
+
+#### 2. Create a release branch
+
+```bash
+git checkout main && git pull origin main
+git checkout -b release/v0.2.0
+```
+
+#### 3. Bump versions (keep all three in sync)
+
+| File | Field |
+| ---- | ----- |
+| `src-tauri/tauri.conf.json` | `"version"` |
+| `src-tauri/Cargo.toml` | `version` |
+| Root `package.json` | `"version"` |
+
+#### 4. Update `CHANGELOG.md`
+
+Move items from `## [Unreleased]` into a new versioned section:
 
-### Triggering a release
+```markdown
+## [0.2.0] — YYYY-MM-DD
 
-Push a version tag:
+### Added
+- …
+
+### Fixed
+- …
+
+### Changed
+- …
+```
+
+Add the comparison link at the bottom:
+
+```markdown
+[0.2.0]: https://github.com/fleXRPL/sift/compare/v0.1.0...v0.2.0
+```
+
+Update the `[Unreleased]` link to point from the new tag:
+
+```markdown
+[Unreleased]: https://github.com/fleXRPL/sift/compare/v0.2.0...HEAD
+```
+
+#### 5. Commit and push the release branch
 
 ```bash
+git add CHANGELOG.md src-tauri/tauri.conf.json src-tauri/Cargo.toml package.json
+git commit -m "chore: release v0.2.0"
+git push origin release/v0.2.0
+```
+
+#### 6. Open a PR: `release/v0.2.0 → main`
+
+- Title: `chore: release v0.2.0`
+- Body: paste the new CHANGELOG section as context for reviewers
+- Wait for CI to pass, get approval, then **Squash and merge**
+
+#### 7. Pull `main` locally and tag
+
+```bash
+git checkout main && git pull origin main
 git tag v0.2.0
 git push origin v0.2.0
 ```
 
+Pushing the tag triggers `release.yml` automatically.
+
+---
+
+## GitHub Actions — automated Windows release
+
+Workflow: [`.github/workflows/release.yml`](../.github/workflows/release.yml)
+
 The `release.yml` workflow runs on `windows-latest` and:
 
 1. Installs Node 18 + all npm deps
 2. Builds frontend (`vite build`)
 3. Bundles backend sidecar with `pkg` → `src-tauri/binaries/`
 4. Verifies the `.exe` exists and prints its size
 5. Runs `npx tauri build` (with `CI=false`)
-6. Uploads the NSIS `.exe` as a **GitHub Release asset** (auto-generated release notes)
-7. Also saves the installer as a workflow **artifact** (30-day retention) for non-tag builds
+6. Extracts the matching `CHANGELOG.md` section for the tag version
+7. Creates a **GitHub Release** with the changelog body and attaches the NSIS `.exe`
+8. Also saves the installer as a workflow **artifact** (30-day retention)
 
 ### Manual test build (no tag needed)