ci: optimize Test Suite workflow and document free-tier rule

Workflow changes (.github/workflows/ci.yml):
- Add concurrency to cancel superseded runs on the same ref
- Enable uv dependency caching keyed on uv.lock
- Split lint into a dedicated job; gate test on lint via needs
- Split matrix: PRs run Linux x {3.11, 3.14} for fast feedback;
  push to main/nightly still runs the full 2-OS x 4-Python matrix
- Add fail-fast: false so all platforms surface failures together
- Add timeouts (lint: 5m, test: 20m) to bound runaway jobs
- Tighten GITHUB_TOKEN to contents: read

Docs (CONTRIBUTING.md):
- Add a short "Modifying CI Workflows" section so contributors know
  to stay within standard runners / no metered storage / no paid
  actions before touching .github/workflows/

All jobs continue to run on standard GitHub-hosted runners
(ubuntu-latest, windows-latest), keeping CI within the free tier.

Co-authored-by: Cursor <cursoragent@cursor.com>

.github/workflows/ci.yml

@@ -2,38 +2,74 @@ name: Test Suite
 
 on:
   push:
-    branches: [ main, nightly ]
+    branches: [main, nightly]
   pull_request:
-    branches: [ main, nightly ]
+    branches: [main, nightly]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y libolm-dev build-essential
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint with ruff
+        run: uv run ruff check nanobot --select F
+
   test:
+    needs: lint
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
     strategy:
+      fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: ${{ github.event_name == 'pull_request' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }}
-        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        python-version: ${{ github.event_name == 'pull_request' && fromJSON('["3.11","3.14"]') || fromJSON('["3.11","3.12","3.13","3.14"]') }}
 
     steps:
-    - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-    - name: Set up Python ${{ matrix.python-version }}
+      - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+        uses: actions/setup-python@v5
-      with:
+        with:
-        python-version: ${{ matrix.python-version }}
+          python-version: ${{ matrix.python-version }}
 
-    - name: Install uv
+      - name: Install uv
-      uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
 
-    - name: Install system dependencies (Linux)
+      - name: Install system dependencies (Linux)
-      if: runner.os == 'Linux'
+        if: runner.os == 'Linux'
-      run: sudo apt-get update && sudo apt-get install -y libolm-dev build-essential
+        run: sudo apt-get update && sudo apt-get install -y libolm-dev build-essential
 
-    - name: Install dependencies
+      - name: Install dependencies
-      run: uv sync --all-extras
+        run: uv sync --all-extras
 
-    - name: Lint with ruff
+      - name: Run tests
-      run: uv run ruff check nanobot --select F
+        run: uv run pytest tests/
-
-    - name: Run tests
-      run: uv run pytest tests/

CONTRIBUTING.md

@@ -134,6 +134,20 @@ In practice:
 - Prefer focused patches over broad rewrites
 - If a new abstraction is introduced, it should clearly reduce complexity rather than move it around
 
+## Modifying CI Workflows
+
+If your PR touches `.github/workflows/`, please keep the CI within
+GitHub Actions' free tier:
+
+- Use only standard GitHub-hosted runners (`ubuntu-latest`, `windows-latest`)
+- Avoid macOS runners, larger runners (`*-cores`, `*-xlarge`, `*-gpu`),
+  and self-hosted runners
+- Avoid uploading large artifacts or using long retention
+- Avoid paid Marketplace actions
+
+If your change genuinely needs to step outside this, please call it out
+explicitly in the PR description so it can be discussed before merge.
+
 ## Questions?
 
 If you have questions, ideas, or half-formed insights, you are warmly welcome here.