Agents.md stuff

Author: alan-george-lk

.github/workflows/ci.yml

@@ -8,9 +8,9 @@ on:
   push:
     branches: ["main"]
 
-concurrency:
-  group: ci-${{ github.ref }}
-  # cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+# concurrency:
+#   group: ci-${{ github.ref }}
+#   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 permissions:
   contents: read
@@ -21,7 +21,7 @@ jobs:
   # Compute once which path groups changed; every other job references these
   # outputs. dorny/paths-filter handles PR base diff, push base diff, and
   # empty results on non-diff events (workflow_dispatch); the `if:` guards
-  # below explicitly opt non-PR events back into running everything.
+  # below explicitly opt manual runs back into running everything.
   changes:
     name: Detect changes
     runs-on: ubuntu-latest
@@ -77,6 +77,7 @@ jobs:
               - .github/workflows/ci.yml
               - .github/workflows/generate-docs.yml
               - .github/workflows/publish-docs.yml
+              - "!AGENTS.md"
             quality:
               - src/**
               - include/**
@@ -95,14 +96,14 @@ jobs:
   builds:
     name: Builds
     needs: changes
-    if: ${{ needs.changes.outputs.builds == 'true' || github.event_name != 'pull_request' }}
+    if: ${{ needs.changes.outputs.builds == 'true' || github.event_name == 'workflow_dispatch' }}
     uses: ./.github/workflows/builds.yml
     secrets: inherit
 
   tests:
     name: Tests
     needs: changes
-    if: ${{ needs.changes.outputs.tests == 'true' || github.event_name != 'pull_request' }}
+    if: ${{ needs.changes.outputs.tests == 'true' || github.event_name == 'workflow_dispatch' }}
     uses: ./.github/workflows/tests.yml
     secrets: inherit
 
@@ -119,11 +120,11 @@ jobs:
   quality-checks:
     name: Quality Checks
     needs: changes
-    if: ${{ needs.changes.outputs.quality == 'true' || github.event_name != 'pull_request' }}
+    if: ${{ needs.changes.outputs.quality == 'true' || github.event_name == 'workflow_dispatch' }}
     uses: ./.github/workflows/quality-checks.yml
 
   generate-docs:
     name: Generate Docs
     needs: changes
-    if: ${{ needs.changes.outputs.docs == 'true' || github.event_name != 'pull_request' }}
+    if: ${{ needs.changes.outputs.docs == 'true' || github.event_name == 'workflow_dispatch' }}
     uses: ./.github/workflows/generate-docs.yml

AGENTS.md

@@ -373,3 +373,38 @@ When adding new client facing functionality, add benchmarking to understand the
 - A single participant cannot subscribe to its own tracks as "remote." Testing sender/receiver requires two separate room connections with distinct identities.
 - macOS dylibs require `install_name_tool` fixups for `@rpath` — the CMakeLists.txt handles this automatically. Do not manually adjust RPATH unless you understand the implications.
 - When consuming the installed SDK, use `-DLIVEKIT_LOCAL_SDK_DIR=/path/to/sdk` to point cmake at a local install instead of downloading a release tarball.
+
+### CI Workflow Structure
+
+`ci.yml` is the PR-review aggregator. It computes path changes once with
+`dorny/paths-filter` and conditionally calls reusable workflows for the
+expensive stages. Manual `workflow_dispatch` runs intentionally opt back into
+all filtered stages; normal pull requests and pushes use the path filters.
+
+- `.github/workflows/ci.yml` — Top-level PR/push/manual aggregator and path
+  filter owner.
+- `.github/workflows/builds.yml` — Reusable SDK and example-collection build
+  matrix.
+- `.github/workflows/tests.yml` — Reusable unit/integration test matrix.
+- `.github/workflows/quality-checks.yml` — Reusable `clang-format` and
+  `clang-tidy` checks.
+- `.github/workflows/generate-docs.yml` — Reusable Doxygen docs validation.
+- `.github/workflows/license_check.yml` — Cheap license check, run on every CI
+  invocation.
+- `.github/workflows/pin_check.yml` — Cheap action pin check, run on every CI
+  invocation.
+- `.github/workflows/docker-images.yml` — Docker image build/publish workflow,
+  outside PR-review aggregation.
+- `.github/workflows/docker-validate.yml` — Docker image validation workflow,
+  outside PR-review aggregation.
+
+When adding or renaming files that affect a CI stage, update the matching
+`ci.yml` `changes` filter in the same PR. For example, new build scripts,
+CMake files, package manifests, or reusable build workflows should be added to
+the `builds` filter; test-only helpers to `tests`; formatting/static-analysis
+configuration to `quality`; and docs generation inputs to `docs`.
+
+Keep broad agent guidance files such as `AGENTS.md` out of the expensive
+`builds`, `tests`, `quality`, and `docs` filters unless they start affecting
+generated docs or build artifacts. An `AGENTS.md`-only change should not trigger
+those stages; only the always-on cheap checks should run.