fix(ci): post coverage to Codecov via bash uploader (excoveralls path)

The previous workflow used codecov/codecov-action@v5, which silently
failed in CI with:
  'Token required - not valid tokenless upload'

Codecov changed their policy in 2024 and now requires a token even
for public repos. The action needs either:
  - CODECOV_TOKEN secret set in repo Settings -> Secrets, OR
  - The Codecov GitHub App installed on the repo

This change uses the excoveralls-recommended path for Codecov:
'mix coveralls.json' (already running) + the official bash uploader
downloaded at runtime.

The bash uploader reads CODECOV_TOKEN from the env. The step
gracefully skips if the secret is unset (prints a notice with
the codecov.io setup URL) so the build doesn't fail.

Also added documentation in AGENTS.md explaining how to obtain
and configure the token, and clarifying why 'mix coveralls.post'
is NOT the right path (it posts to coveralls.io, not codecov.io).

Author: gilbertwong96

.github/workflows/ci.yml

@@ -86,15 +86,32 @@ jobs:
         # is enforced by the previous step.
         run: mix coveralls.json
 
-      - name: Upload coverage to Codecov
-        if: always()
-        uses: codecov/codecov-action@v5
-        with:
-          files: ./cover/excoveralls.json
-          flags: linux
-          # No token = Codecov uses its public GitHub App integration
-          # to pick up coverage from public repos without manual setup.
-          fail_ci_if_error: false
+      - name: Post coverage to Codecov
+        # Push the JSON to codecov.io using their bash uploader. This
+        # is the path recommended by excoveralls for Codecov (vs the
+        # GitHub Action, which now requires a token anyway).
+        #
+        # Requires CODECOV_TOKEN in repo Settings -> Secrets -> Actions.
+        # The repo token is at https://codecov.io/gh/gilbertwong96/ado_cli
+        # -> Settings -> Upload Token. The bash uploader reads it from
+        # the CODECOV_TOKEN env var.
+        #
+        # Skip the step if the secret is not set. We don't fail the
+        # build over missing coverage uploads — coverage is still
+        # available as an action artifact download.
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        run: |
+          if [ -z "$CODECOV_TOKEN" ]; then
+            echo "::notice::CODECOV_TOKEN not set — skipping Codecov upload."
+            echo "Add it at https://codecov.io/gh/gilbertwong96/ado_cli"
+            echo "to enable the coverage badge."
+            exit 0
+          fi
+          curl -Os https://uploader.codecov.io/latest/linux/codecov
+          chmod +x codecov
+          ./codecov --token "$CODECOV_TOKEN" --file ./cover/excoveralls.json
+        continue-on-error: true
 
       - name: Upload coverage artifact
         if: always()

AGENTS.md

@@ -39,6 +39,28 @@ Codecov dashboard; configuration lives in the `coveralls:` section of
 The local `mix ci` command is the source of truth — if it passes locally
 it will pass on CI. Never skip a check before pushing.
 
+## Coverage reporting (Codecov)
+
+Coverage is reported to Codecov via the official bash uploader. To enable
+it on CI, the user must add a `CODECOV_TOKEN` secret to the repo:
+
+  1. Visit https://codecov.io/gh/gilbertwong96/ado_cli
+  2. Sign in with the same GitHub account
+  3. Go to Settings -> Upload Token
+  4. Copy the token
+  5. In the GitHub repo: Settings -> Secrets and variables -> Actions
+     -> New repository secret
+  6. Name: `CODECOV_TOKEN`, Value: <paste token>
+
+The CI step that posts to Codecov is conditional on the secret being
+set, so it's safe to leave the repo in this state until the user is
+ready. When the secret is present, the codecov.io dashboard will start
+showing coverage data within a few minutes of a CI run.
+
+Note: `mix coveralls.post` is NOT the right path here — it posts to
+coveralls.io, not codecov.io. For Codecov, the canonical path is
+`mix coveralls.json` + the codecov bash uploader.
+
 ## Additional Quality Commands
 
 ```bash