Add Windows packaging & installer support

Add Windows installation and packaging support: introduce scripts/install_windows.ps1 for Windows installs and scripts/prepare_windows_packaging.py to generate Scoop manifest and a winget submission helper. Add packaging artifacts (packaging/scoop/lore-book.json, packaging/winget/submission-1.3.0.md) and a windows smoke CI workflow (.github/workflows/windows-smoke.yml). Update release workflow to build a local sdist and prepare/commit Windows packaging artifacts during release. Update docs/README/site install pages to document Windows install options and use the Python launcher. Small CLI tweaks: recommend using "python -m pip" for upgrades and add cross-platform clipboard detection (PowerShell Get-Clipboard, pwsh, pbpaste, xclip) for relic capture.

Author: CptPlastic

.github/workflows/release.yml

@@ -49,6 +49,20 @@ jobs:
             --version "${{ inputs.version }}" \
             --github-output "$GITHUB_OUTPUT"
 
+      - name: Build local sdist for packaging hashes
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --sdist
+
+      - name: Prepare Windows packaging artifacts
+        id: windows_packaging
+        run: |
+          python scripts/prepare_windows_packaging.py \
+            --version "${{ steps.prep.outputs.version }}" \
+            --repo "${{ github.repository }}" \
+            --sdist-file "dist/lore_book-${{ steps.prep.outputs.version }}.tar.gz" \
+            --github-output "$GITHUB_OUTPUT"
+
       - name: Validate tag does not already exist
         run: |
           if git rev-parse -q --verify "refs/tags/${{ steps.prep.outputs.tag }}" >/dev/null; then
@@ -64,7 +78,7 @@ jobs:
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add src/lore/__init__.py CHANGELOG.md
+          git add src/lore/__init__.py CHANGELOG.md packaging/scoop/lore-book.json packaging/winget/submission-${{ steps.prep.outputs.version }}.md
           git commit -m "chore(release): ${{ steps.prep.outputs.version }}"
           git tag "${{ steps.prep.outputs.tag }}"
           git push origin HEAD

.github/workflows/windows-smoke.yml

@@ -0,0 +1,48 @@
+name: Windows Smoke
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+concurrency:
+  group: windows-smoke-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  smoke:
+    runs-on: windows-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package
+        shell: pwsh
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install .
+
+      - name: Run smoke checks
+        shell: pwsh
+        run: |
+          lore version
+
+          $testRepo = Join-Path $env:RUNNER_TEMP "lore-smoke-project"
+          New-Item -ItemType Directory -Path $testRepo -Force | Out-Null
+          Set-Location $testRepo
+
+          lore init .
+          lore add facts "windows smoke memory"
+          lore trust refresh --dry-run
+          lore export --format chronicle
+
+          if (-not (Test-Path (Join-Path $testRepo "CHRONICLE.md"))) {
+            throw "CHRONICLE.md was not generated"
+          }

README.md

@@ -99,6 +99,52 @@ Exports are atomic — a crash mid-write never leaves a partial file.
 pip install lore-book
 ```
 
+### Windows (recommended)
+
+Use the Python launcher so the command works consistently across Windows setups:
+
+```powershell
+py -m pip install --upgrade lore-book
+```
+
+If you prefer isolated CLI installs, `pipx` is the smoothest option on Windows:
+
+```powershell
+py -m pip install --user pipx
+py -m pipx ensurepath
+pipx install lore-book
+```
+
+If you are installing from this repository, use the bootstrap script:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1
+```
+
+Optional modes:
+
+```powershell
+# Force plain pip install mode
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1 -Mode pip
+
+# Install from local source path via pipx
+powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1 -SourcePath .
+```
+
+### Windows package managers
+
+`pipx install lore-book` remains the easiest path for most users.
+
+This repo now generates Windows packaging artifacts during release:
+
+- Scoop manifest: `packaging/scoop/lore-book.json`
+- winget submission helper: `packaging/winget/submission-<version>.md`
+
+After each release, use these to publish:
+
+1. Submit `packaging/scoop/lore-book.json` to your Scoop bucket repository.
+2. Use `packaging/winget/submission-<version>.md` to open/update a PR in `microsoft/winget-pkgs`.
+
 For local development:
 
 ```sh
@@ -145,7 +191,7 @@ Preview locally:
 
 ```sh
 cd docs
-python3 -m http.server 8000
+python -m http.server 8000
 ```
 
 Then open:
@@ -218,7 +264,7 @@ lore relic capture --git-diff --title "Pre-deploy changes"
 # Capture the last N commits (messages + diffs)
 lore relic capture --git-log 5 --title "Sprint 12 wrap-up"
 
-# Read from clipboard (macOS: pbpaste, Linux: xclip)
+# Read from clipboard (Windows: PowerShell Get-Clipboard, macOS: pbpaste, Linux: xclip)
 lore relic capture --clipboard --title "Slack thread on rate limiting"
 
 # Pipe anything in

docs/index.html

@@ -148,10 +148,14 @@ <h3>Distill</h3>
     <!-- ══ INCANTATIONS ══ -->
     <section class="parchment">
       <h2><span class="rune">🜏</span> Incantations</h2>
+      <h3>Install on Windows (easy path)</h3>
+      <div class="incantation"><span class="comment"># Use pipx for a clean CLI install</span><br><span class="cmd">py -m pip install --user pipx</span><br><span class="cmd">py -m pipx ensurepath</span><br><span class="cmd">pipx install lore-book</span></div>
+      <h3>Install from this repo on Windows</h3>
+      <div class="incantation"><span class="cmd">powershell -ExecutionPolicy Bypass -File .\scripts\install_windows.ps1</span></div>
       <h3>Install via Homebrew</h3>
       <div class="incantation"><span class="comment"># Bind the tap</span><br><span class="cmd">brew tap</span> <span class="arg">cptplastic/lore-book</span><br><span class="cmd">brew install</span> <span class="arg">lore-book</span></div>
       <h3>Install via pip</h3>
-      <div class="incantation"><span class="cmd">pip install</span> <span class="arg">lore-book</span></div>
+      <div class="incantation"><span class="cmd">python -m pip install</span> <span class="arg">lore-book</span></div>
       <h3>Cast your first spells</h3>
       <div class="incantation"><span class="comment"># Record a decision</span><br><span class="cmd">lore add</span> <span class="arg">decisions</span> <span class="arg">"Use PostgreSQL — we need JSONB and row-level locking"</span><br><br><span class="comment"># Record a fact</span><br><span class="cmd">lore add</span> <span class="arg">facts</span> <span class="arg">"Auth service is the sole issuer of JWTs — never bypass it"</span><br><br><span class="comment"># Publish to all AI instruction files</span><br><span class="cmd">lore export</span></div>
     </section>

packaging/scoop/lore-book.json

@@ -0,0 +1,30 @@
+{
+  "version": "1.3.0",
+  "description": "The spellbook for your codebase - chronicle decisions, context, and lessons your AI tools can read.",
+  "homepage": "https://github.com/CptPlastic/lore-book",
+  "license": "FSL-1.1-MIT",
+  "depends": "python",
+  "architecture": {
+    "64bit": {
+      "url": "https://files.pythonhosted.org/packages/source/l/lore-book/lore-book-1.3.0.tar.gz",
+      "hash": "cd09aab4053883dcce462876144ca1547fc25b38fe8e9179e758316aa08d2f47"
+    }
+  },
+  "checkver": "https://pypi.org/pypi/lore-book/json",
+  "autoupdate": {
+    "architecture": {
+      "64bit": {
+        "url": "https://files.pythonhosted.org/packages/source/l/lore-book/lore-book-$version.tar.gz"
+      }
+    }
+  },
+  "pre_install": [
+    "$pkg = \"lore-book==1.3.0\"",
+    "python -m pip install --user --upgrade $pkg",
+    "Set-Content -Path \"$dir\\lore.cmd\" -Value \"@echo off`r`npython -m lore.cli %*\" -Encoding Ascii"
+  ],
+  "pre_uninstall": [
+    "python -m pip uninstall -y lore-book"
+  ],
+  "bin": "lore.cmd"
+}

packaging/winget/submission-1.3.0.md

@@ -0,0 +1,26 @@
+# winget submission helper for lore-book 1.3.0
+
+Generated: 2026-03-25
+
+## Package metadata
+
+- PackageIdentifier: CptPlastic.LoreBook
+- PackageVersion: 1.3.0
+- Publisher: CptPlastic
+- PackageName: lore-book
+- License: FSL-1.1-MIT
+- InstallerUrl: https://files.pythonhosted.org/packages/source/l/lore-book/lore-book-1.3.0.tar.gz
+- InstallerSha256: cd09aab4053883dcce462876144ca1547fc25b38fe8e9179e758316aa08d2f47
+
+## Notes
+
+`lore-book` is a Python CLI package. A direct winget installer is not auto-published from this repo.
+Use this file as the source of truth for opening/updating a PR in `microsoft/winget-pkgs`.
+
+## Recommended submission flow
+
+1. Install wingetcreate.
+2. Create or update a manifest for `CptPlastic.LoreBook` using the URL/hash above.
+3. Open a PR in `microsoft/winget-pkgs`.
+
+Reference repository: https://github.com/CptPlastic/lore-book

scripts/install_windows.ps1

@@ -0,0 +1,64 @@
+[CmdletBinding()]
+param(
+    [ValidateSet("pipx", "pip")]
+    [string]$Mode = "pipx",
+    [string]$SourcePath
+)
+
+$ErrorActionPreference = "Stop"
+
+function Test-Command {
+    param([Parameter(Mandatory = $true)][string]$Name)
+    return [bool](Get-Command $Name -ErrorAction SilentlyContinue)
+}
+
+function Invoke-Py {
+    param([Parameter(Mandatory = $true)][string[]]$Args)
+    if (Test-Command "py") {
+        & py @Args
+        return
+    }
+    if (Test-Command "python") {
+        & python @Args
+        return
+    }
+    throw "Python was not found. Install Python 3.10+ from https://www.python.org/downloads/windows/ and re-run this script."
+}
+
+Write-Host "[lore/windows] Bootstrap starting (mode=$Mode)"
+
+if ($Mode -eq "pipx") {
+    Write-Host "[lore/windows] Installing/upgrading pip + pipx"
+    Invoke-Py -Args @("-m", "pip", "install", "--user", "--upgrade", "pip", "pipx")
+
+    Write-Host "[lore/windows] Ensuring pipx path"
+    Invoke-Py -Args @("-m", "pipx", "ensurepath")
+
+    if ([string]::IsNullOrWhiteSpace($SourcePath)) {
+        Write-Host "[lore/windows] Installing lore-book from PyPI via pipx"
+        Invoke-Py -Args @("-m", "pipx", "install", "--force", "lore-book")
+    }
+    else {
+        Write-Host "[lore/windows] Installing lore-book from source path: $SourcePath"
+        Invoke-Py -Args @("-m", "pipx", "install", "--force", $SourcePath)
+    }
+
+    Write-Host "[lore/windows] Verifying CLI"
+    Invoke-Py -Args @("-m", "pipx", "run", "--spec", "lore-book", "lore", "version")
+}
+else {
+    if ([string]::IsNullOrWhiteSpace($SourcePath)) {
+        Write-Host "[lore/windows] Installing lore-book from PyPI via pip"
+        Invoke-Py -Args @("-m", "pip", "install", "--user", "--upgrade", "lore-book")
+    }
+    else {
+        Write-Host "[lore/windows] Installing lore-book from source path: $SourcePath"
+        Invoke-Py -Args @("-m", "pip", "install", "--user", "--upgrade", $SourcePath)
+    }
+
+    Write-Host "[lore/windows] Verifying package import"
+    Invoke-Py -Args @("-c", "import lore; print(f'lore {lore.__version__}')")
+}
+
+Write-Host "[lore/windows] Install complete."
+Write-Host "[lore/windows] If 'lore' is not recognized yet, open a new terminal session."