docs(agents): add AGENTS.md, knowledge base, and Copilot context

.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+<!-- This file exists so GitHub Copilot continues to discover repository custom instructions. -->
+<!-- All project guidelines live in AGENTS.md at the repository root. -->
+See [AGENTS.md](../AGENTS.md) for project overview, setup, commands, coding conventions, testing, CI/CD, pull request workflow, and AI agent context.

.github/instructions/ci-cd.instructions.md

@@ -0,0 +1,35 @@
+---
+applyTo: ".github/workflows/**"
+name: webrtc-core CI/CD
+description: Use when analyzing or changing GitHub Actions workflows or semantic-release publish configuration.
+---
+
+# CI/CD Instructions — webrtc-core
+
+Read the current files under `.github/workflows/` before analyzing or modifying CI configuration.
+
+## Pipeline (GitHub Actions)
+
+- **Pull requests:** `.github/workflows/pull-request-checks.yml` — checkout, Node (see workflow for version), `yarn install`, `yarn test:lint`, `yarn test:coverage` (Jest).
+- **Main branch:** `.github/workflows/npm-publish.yml` — `yarn build`, then `npx semantic-release` with registry tokens from GitHub secrets (never log or commit tokens).
+
+Node version in workflows should stay aligned with `.nvmrc` when you change either.
+
+## Release
+
+- semantic-release runs on **`main`** after merge (publish workflow).
+- Next version comes from **conventional commit** types on merged commits.
+- Publishes `@webex/webrtc-core` to the npm public registry.
+- Release may update generated files (`CHANGELOG.md`, `package.json`, lockfile) via semantic-release plugins.
+
+## Failure triage
+
+- **Lint or Jest failure in a PR** — fix code or tests; do not rerun hoping for green.
+- **Infra failure** (runner, registry, transient network) — rerun after infra is healthy.
+- **Release failure on main** — treat as an incident; do not publish locally without coordination.
+
+## Safety
+
+- Never expose or log CI secrets (`CI_TOKEN`, `NPM_TOKEN`, `GITHUB_TOKEN`).
+- Only rerun for infrastructure failures, not code failures.
+- Do not run `yarn release` / `semantic-release` locally unless intentionally publishing with team approval.

.github/instructions/code-review.instructions.md

@@ -0,0 +1,26 @@
+---
+applyTo: "src/**/*.ts"
+name: webrtc-core Code Review
+description: Use when reviewing or preparing changes under src/ — correctness, public API, PeerConnection lifecycle, local streams, events, and media-effects integration.
+---
+
+# Code Review Instructions — webrtc-core
+
+When reviewing changes in `src/`:
+
+## Priorities
+
+1. Correctness — edge cases, error paths handled (especially getUserMedia, track lifecycle, constraint handling).
+2. Public API — additions/removals in `src/index.ts` noted with semver impact.
+3. Browser quirks — adapter, permissions API differences (Firefox/Safari), fake-device test assumptions.
+4. Event contracts — no silent removal/rename of typed events on streams and `PeerConnection`.
+5. Media effects integration — changes to effect processors and effect lifecycle handling must stay consistent with `@webex/web-media-effects` contracts.
+
+## Checks
+
+- JSDoc present on all new/modified functions, classes, methods (enforced by ESLint).
+- No `any` without documented reason.
+- No swallowed errors without explicit justification.
+- Unit tests (`*.spec.ts`) added/updated for behavioral changes; consider Karma integration tests for real-browser capture paths when behavior is browser-specific.
+- Comments explain *why*, not *what*. No ticket IDs or dates in code comments.
+- No secrets, absolute paths, `.pem`, or `.env` values in the diff.

.github/instructions/testing.instructions.md

@@ -0,0 +1,44 @@
+---
+applyTo: "src/**/*.spec.ts"
+name: webrtc-core Unit Tests
+description: Use when writing or reviewing Jest unit tests co-located with source under src/.
+---
+
+# Testing Instructions — webrtc-core (Jest)
+
+When writing or reviewing **unit** tests in `src/**/*.spec.ts`:
+
+## Framework
+
+- Jest + ts-jest use the jsdom environment. Authoritative versions and options live in `package.json` and `jest.config.js`; check those files instead of assuming versions here.
+- Co-located `*.spec.ts` files alongside source.
+- Mocks: `src/mocks/` (RTCPeerConnection, MediaStream, navigator, etc.).
+
+## Integration tests (Karma + Mocha)
+
+- Browser integration tests use **`*.integration-test.ts`** and Karma (`karma.conf.js`).
+- `yarn test` uses the `test:*` pattern and includes all four Karma integration scripts. Run individual test scripts when you do not want to run browser integration tests.
+- Run local integration tests with `yarn test:integration:chrome`; the local Karma configuration always launches Chrome through Puppeteer.
+- The Firefox, Edge, and Safari scripts select their named browser matrices only when `SAUCE=true` and valid Sauce Labs credentials are provided. Without Sauce, those scripts also launch local Chrome and must not be treated as validation in the named browser.
+- The checked-in pull request workflow runs Jest coverage, not Karma. Run relevant Karma tests locally when changing browser capture, permissions, or media behavior.
+
+## Patterns
+
+- `describe` blocks named after the module/class under test.
+- `it` blocks with descriptive scenario + expected outcome.
+- `expect.assertions(n)` for async tests when the repo already uses it in that file.
+- Mock at boundaries (`jest.mock` for factories and stubs under `src/mocks/`).
+- `clearMocks: true` in `jest.config.js` clears mock calls, instances, contexts, and results before each test. It does not restore changed implementations or return values; tests that replace them must restore or reset them explicitly.
+
+## Naming
+
+- Files: **`kebab-case.spec.ts`** next to `kebab-case.ts`.
+- Prefer **`should …`** phrasing for new tests unless extending a file with an established style.
+- Integration files: **`*.integration-test.ts`** (see `src/media.integration-test.ts`).
+
+## Rules
+
+- GitHub Actions / team CI results are authoritative over local-only runs when they disagree.
+- Bug fixes should include or extend a regression test when behavior changed.
+- Tests must be independent — no shared mutable state between tests.
+- Allowed hooks: `beforeAll`, `beforeEach`, `afterAll`, `afterEach` (ESLint `jest/no-hooks`).

.github/pull_request_template.md

@@ -1,5 +1,5 @@
 ## Description
-<!-- Provide a summary of the changes you are making, including any relevant JIRAs and screenshots. -->
+<!-- Explain what changed and why. Link a relevant public issue and add verified test evidence or screenshots when applicable. -->
 
 ## This change implements...
 - [ ] A new feature

.github/skills/pr-description/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pr-description
+description: Draft accurate webrtc-core pull request descriptions from the repository template and committed changes. Use when creating, updating, or reviewing a PR description for this repository.
+---
+
+# PR Description
+
+Create a concise PR description that helps reviewers understand the change and verify it.
+
+## Sources
+
+Read these before drafting:
+
+1. `.github/pull_request_template.md`
+2. The complete committed branch diff against the PR base branch
+3. Branch commits
+4. Test output supplied by the author or produced in the current session
+5. Linked public issues or design context when available
+
+Repository files and observed test results are authoritative. Do not invent motivation, test evidence, issue links, screenshots, or compatibility claims.
+
+## Workflow
+
+1. Confirm the PR base branch. Use `main` when no other base is specified.
+2. Review the complete diff, not only the latest commit.
+3. Check `git status`. If uncommitted changes exist, warn the author and exclude them from the PR description until they are committed.
+4. Identify the change type and whether public API, browser behavior, media lifecycle, or compatibility changes.
+5. Before drafting the final description, ask what manual testing was performed. Request the tested scenario, browser when relevant, and result. If no manual testing was needed, ask the author to confirm why.
+6. Ask only for other facts that cannot be derived, such as a public issue link, screenshots, or the GAI usage category.
+7. Produce the completed repository template without removing headings or policy checkboxes.
+
+## Description Rules
+
+- Start with one to three bullets explaining what changed and why.
+- Describe the behavior or developer outcome rather than listing files.
+- Link a relevant public issue when available.
+- Add a short `Testing` subsection under `Description` with commands and manual checks that actually ran.
+- Mention breaking changes, migration steps, public API impact, dependency pin changes, or downstream version bumps only when the diff requires it.
+- Include screenshots only for visible UI changes.
+- Keep unchecked boxes when the answer is unknown.
+- Never mark the test certification checkbox without evidence.
+- Never choose a GAI disclosure category for the author.
+- Do not add a dedicated risk assessment section.
+
+## Output
+
+Return the proposed PR description as one Markdown block that can be pasted into GitHub.
+
+After the block, list unresolved author questions separately. Do not place placeholders such as `TBD` inside an otherwise final description.

.gitignore

@@ -3,3 +3,5 @@ dist
 .idea/
 coverage/
 .scannerwork/
+docs/temp/
+docs/api-reference/