Merge Mac Mini progress work into D2 card-generator trunk

Brings together two parallel tracks since 4070bfa:
- Local track (D1/D2): pydantic card schemas + CardGenerator Protocol +
  OllamaGenerator + Bedrock backend with concurrency and region fallback
- Mac Mini track: course material discovery workflow, progress summary,
  release metadata gating, release tooling, config hardening

Both branches shared no overlapping files by construction; this merge
is a true join of two independent feature streams.

# Conflicts:
#	.github/workflows/publish.yml
#	.gitignore

Author: taylaand

.github/workflows/ci.yml

@@ -51,6 +51,15 @@ jobs:
       - name: Audit dependencies for known vulnerabilities
         run: uv audit
 
+  release-consistency:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f # v4
+        with:
+          python-version: "3.12"
+      - run: python scripts/check-release-consistency.py
+
   test:
     runs-on: ubuntu-latest
     strategy:
@@ -61,5 +70,32 @@ jobs:
       - uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f # v4
         with:
           python-version: ${{ matrix.python-version }}
-      - run: uv sync --all-packages --extra dev --extra test
-      - run: uv run pytest --tb=short -m "not integration" --cov=packages --cov-report=term-missing
+      - run: uv sync --all-packages --group dev
+      - run: uv run pytest --tb=short -m "not integration and not e2e" --cov=packages --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f # v4
+        with:
+          python-version: "3.12"
+      - run: ./scripts/build-release.sh
+
+  install-smoke:
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - uses: astral-sh/setup-uv@e4db8464a088ece1b920f60402e813ea4de65b8f # v4
+        with:
+          python-version: "3.12"
+      - run: ./scripts/build-release.sh
+      - name: Install built wheel without optional extras
+        run: |
+          uv venv /tmp/studyctl-smoke
+          uv pip install --python /tmp/studyctl-smoke/bin/python dist/studyctl-*.whl
+      - name: Smoke-test installed CLI entry points
+        run: |
+          export PATH="/tmp/studyctl-smoke/bin:$PATH"
+          ./scripts/smoke-installed-cli.sh

.github/workflows/pre-release.yml

@@ -11,7 +11,55 @@ on:
         required: false
 
 jobs:
+  local-quality-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+
+      - name: Install workspace dependencies
+        run: uv sync --all-packages --group dev
+
+      - name: Release consistency
+        run: |
+          if [ "${GITHUB_REF_TYPE}" = "tag" ]; then
+            python scripts/check-release-consistency.py \
+              --tag "${GITHUB_REF_NAME}" \
+              --require-release-notes \
+              --allow-formula-lag
+          else
+            python scripts/check-release-consistency.py
+          fi
+
+      - name: Ruff
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Pyright
+        run: |
+          cd packages/agent-session-tools && uv run pyright src/
+          cd ../studyctl && uv run pyright src/
+
+      - name: Unit tests
+        run: uv run pytest --tb=short -m "not integration and not e2e" --cov=packages --cov-report=term-missing
+
+      - name: Build release package
+        run: ./scripts/build-release.sh
+
+      - name: Install smoke test
+        run: |
+          uv venv /tmp/studyctl-smoke
+          uv pip install --python /tmp/studyctl-smoke/bin/python dist/studyctl-*.whl
+          export PATH="/tmp/studyctl-smoke/bin:$PATH"
+          ./scripts/smoke-installed-cli.sh
+
   upgrade-path:
+    needs: local-quality-gate
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
@@ -91,7 +139,9 @@ jobs:
   # independently. To block publish on failure, add this as a required
   # status check in GitHub branch protection rules.
   gate:
-    needs: upgrade-path
+    needs:
+      - local-quality-gate
+      - upgrade-path
     runs-on: ubuntu-latest
     steps:
       - run: echo "Pre-release gate passed"

.github/workflows/publish.yml

@@ -24,48 +24,93 @@ permissions:
   contents: write
 
 jobs:
-  release:
+  quality-gate:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
-      - name: Generate changelog for release
-        uses: orhun/git-cliff-action@v4
-        id: changelog
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
         with:
-          config: cliff.toml
-          args: --latest --strip header
+          python-version: "3.12"
 
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          body: ${{ steps.changelog.outputs.content }}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install workspace dependencies
+        run: uv sync --all-packages --group dev
+
+      - name: Release consistency
+        run: |
+          python scripts/check-release-consistency.py \
+            --tag "${GITHUB_REF_NAME}" \
+            --require-release-notes \
+            --allow-formula-lag
+
+      - name: Ruff
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Pyright
+        run: |
+          cd packages/agent-session-tools && uv run pyright src/
+          cd ../studyctl && uv run pyright src/
+
+      - name: Unit tests
+        run: uv run pytest --tb=short -m "not integration and not e2e" --cov=packages --cov-report=term-missing
 
   build:
-    needs: release
+    needs: quality-gate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
 
       - name: Build package
         run: ./scripts/build-release.sh
 
+      - name: Smoke-test built wheel without optional extras
+        run: |
+          uv venv /tmp/studyctl-smoke
+          uv pip install --python /tmp/studyctl-smoke/bin/python dist/studyctl-*.whl
+          export PATH="/tmp/studyctl-smoke/bin:$PATH"
+          ./scripts/smoke-installed-cli.sh
+
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
           name: dist
           path: dist/
 
-  publish:
+  release:
     needs: build
     runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate changelog for release
+        uses: orhun/git-cliff-action@v4
+        id: changelog
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.content }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  publish:
+    needs:
+      - build
+      - release
+    runs-on: ubuntu-latest
     permissions:
       contents: read
       id-token: write  # OIDC for PyPI trusted publishing
@@ -118,6 +163,13 @@ jobs:
           sed -i '/^  url .*studyctl-/{n;s|sha256 ".*"|sha256 "'"${SHA}"'"|;}' Formula/studyctl.rb
           grep -A1 'url .*studyctl' Formula/studyctl.rb
 
+      - name: Verify formula consistency
+        run: |
+          python scripts/check-release-consistency.py \
+            --tag "${GITHUB_REF_NAME}" \
+            --require-release-notes \
+            --require-formula-current
+
       - name: Commit and push formula
         run: |
           VERSION="${GITHUB_REF_NAME#v}"

.gitignore

@@ -479,7 +479,9 @@ site/
 docs/internal/
 docs/local_repo_docs/
 docs/plans/
-docs/architecture/
+docs/architecture/*
+!docs/architecture/
+!docs/architecture/adapter-pattern-notebooklm.md
 
 # Demo recordings (large, local-only)
 demos/
@@ -502,3 +504,6 @@ docs/brainstorms/
 
 # Benchmark output (large regenerable artefacts — keep local)
 benchmarks/d2-output/
+
+# Stray mock path artefacts from tests that stringify MagicMock path objects
+<MagicMock id='*'>