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

@@ -6,13 +6,49 @@ on:
   pull_request:
     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
@@ -24,6 +60,9 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
 
       - name: Install system dependencies (Linux)
         if: runner.os == 'Linux'
@@ -32,8 +71,5 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras
 
-    - name: Lint with ruff
-      run: uv run ruff check nanobot --select F
-
       - 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.