feat: add Boehm 1981 research note, update release workflows, restructure docs index

.flowr/viz/generate-flowviz-data.py

@@ -239,8 +239,6 @@ def main() -> int:
     js = "window.FLOWVIZ_DATA = " + json.dumps(bundle, indent=2, sort_keys=True) + ";\n"
     OUT_FILE.write_text(js, encoding="utf-8")
 
-    print(f"Wrote {OUT_FILE}")
-    print(f"Flows: {', '.join(sorted(flows.keys()))}")
     return 0
 
 

.github/workflows/pypi-publish.yml

@@ -7,19 +7,18 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Tag to publish (e.g. v8.0.0+20260430)"
+        description: "Tag to publish (e.g. v8.0.0+20260501)"
         required: true
         type: string
 
 permissions:
-  contents: read
+  contents: write
+  id-token: write
 
 jobs:
   build:
     name: Build distribution
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
 
     steps:
       - name: Checkout code
@@ -73,8 +72,6 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     environment: pypi
-    permissions:
-      id-token: write  # required for OIDC trusted publisher
 
     steps:
       - name: Download dist artifacts
@@ -87,11 +84,9 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
 
   release:
-    name: Update GitHub Release
+    name: Create GitHub Release
     runs-on: ubuntu-latest
     needs: publish
-    permissions:
-      contents: write  # required to create/edit a release
 
     steps:
       - name: Checkout code
@@ -105,7 +100,7 @@ jobs:
           name: dist
           path: dist/
 
-      - name: Create or update GitHub Release
+      - name: Create GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}

.github/workflows/tag-release.yml

@@ -1,16 +1,19 @@
 name: Tag Release
 
 on:
-  push:
-    branches: [main]
-    paths: [pyproject.toml]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. 8.0.0)"
+        required: true
+        type: string
 
 permissions:
   contents: write
 
 jobs:
   tag:
-    name: Create version tag
+    name: Create version tag and trigger publish
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -21,57 +24,54 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v4.1.1
 
-      - name: Extract version from pyproject.toml
-        id: version
+      - name: Validate version matches pyproject.toml
         run: |
-          # Extract semver core (major.minor.patch) from pyproject.toml
-          VERSION=$(grep '^version' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
-          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
-          # Build metadata (+YYYYMMDD) is appended at tag time, not stored in pyproject.toml
-          echo "tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+          ACTUAL=$(grep '^version' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
+          if [ "$ACTUAL" != "${{ inputs.version }}" ]; then
+            echo "Version mismatch: pyproject.toml has '$ACTUAL', input was '${{ inputs.version }}'"
+            echo "Update pyproject.toml before releasing, or use the correct version."
+            exit 1
+          fi
 
       - name: Check if tag already exists
         id: check
         run: |
-          if git ls-remote --tags origin "refs/tags/v${{ steps.version.outputs.version }}" | grep -q .; then
+          if git ls-remote --tags origin "refs/tags/v${{ inputs.version }}+*" | grep -q .; then
             echo "exists=true" >> "$GITHUB_OUTPUT"
           else
             echo "exists=false" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Abort (tag already exists)
+        if: steps.check.outputs.exists == 'true'
+        run: |
+          echo "Tag v${{ inputs.version }}+* already exists. Delete it first or bump the version."
+          exit 1
+
       - name: Install uv
-        if: steps.check.outputs.exists == 'false'
         uses: astral-sh/setup-uv@c0c76fcf76c37099e6a452584d04b015240faefc # v4.0.0
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
 
       - name: Set up Python 3.13
-        if: steps.check.outputs.exists == 'false'
         run: uv python install 3.13
 
       - name: Install dependencies
-        if: steps.check.outputs.exists == 'false'
         run: uv sync --locked --all-extras --dev && uv pip install -e .
 
       - name: Run release-check
-        if: steps.check.outputs.exists == 'false'
         run: uv run task release-check
 
       - name: Create and push tag
-        if: steps.check.outputs.exists == 'false'
         env:
           GIT_AUTHOR_NAME: github-actions[bot]
           GIT_AUTHOR_EMAIL: github-actions[bot]@users.noreply.github.com
           GIT_COMMITTER_NAME: github-actions[bot]
           GIT_COMMITTER_EMAIL: github-actions[bot]@users.noreply.github.com
         run: |
           DATE=$(date +%Y%m%d)
-          TAG="v${{ steps.version.outputs.version }}+${DATE}"
+          TAG="v${{ inputs.version }}+${DATE}"
           git tag "$TAG"
           git push origin "$TAG"
           echo "Created tag $TAG at $(git rev-parse HEAD)"
-
-      - name: Skip (tag already exists)
-        if: steps.check.outputs.exists == 'true'
-        run: echo "Tag ${{ steps.version.outputs.tag }} already exists — skipping."