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

.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+# Copilot Instructions
+
+Read and follow the repository guidance in [../AGENTS.md](../AGENTS.md).

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

@@ -0,0 +1,40 @@
+---
+applyTo: '.github/workflows/**,release.config.js,package.json,rollup.config.js,typedoc.json'
+name: web-capabilities CI/CD
+description: Use when reviewing checks, builds, bundled worker source, documentation generation, package entry points, or semantic-release behavior.
+---
+
+# CI/CD Instructions
+
+## Pull-request checks
+
+- Read `.github/workflows/pull-request-checks.yml` before changing or describing CI.
+- Pull requests install with Yarn, then run `yarn test:lint`, `yarn test:prettier`, `yarn test:spelling`, `yarn transpile:validate`, `yarn build`, and `yarn test:coverage`.
+- Docs generation and the aggregate `yarn test` command are not current pull-request gates.
+- Do not claim a check is CI-enforced unless the workflow invokes it.
+
+## Build and package outputs
+
+- Rollup builds ESM and CommonJS JavaScript plus bundled TypeScript declarations from `src/index.ts`.
+- At build time, Rollup embeds `*.worker.js` into the bundle as a string (`rollup-plugin-string`). At runtime, the WASM probe creates a `Worker` from a Blob URL. The npm package does not ship a separate worker file on disk.
+- Keep `package.json` `main`, `module`, `types`, and `exports` aligned with Rollup outputs.
+- The npm package includes only `dist/**/*`.
+- The runtime dependency is `bowser`. Review any proposed runtime package as a compatibility and supply-chain change.
+- Generated API files belong under `docs/api/`. That directory is gitignored locally; semantic-release can still commit generated docs on release.
+- Cleanup must not delete maintained files under `docs/contributing/` or `docs/knowledge-base/`.
+
+## Release
+
+- Pushes to `main` install with Yarn, run `yarn build`, and invoke semantic-release.
+- Conventional Commits on `main` determine whether semantic-release publishes and which version increment applies.
+- The release configuration publishes to the public npm registry and commits configured release assets, including the `docs` directory.
+- The current release workflow builds but does not run tests or generate TypeDoc output. Document that gap accurately.
+- Treat changes to capability outcomes, probe classification, `src/index.ts`, exported signatures, entry points, declarations, or runtime dependencies as compatibility-sensitive.
+
+## Failure triage and safety
+
+- Fix deterministic lint, test, type, documentation, or build failures. Do not rerun them hoping for a different result.
+- Retry only failures supported by evidence of transient runner, registry, or network problems.
+- Treat a release failure on `main` as a coordinated delivery issue.
+- Never expose workflow tokens, npm credentials, or secret values.
+- Do not run semantic-release or npm publishing locally unless the user explicitly requests a coordinated release.

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

@@ -0,0 +1,29 @@
+---
+applyTo: 'src/**/*.ts,README.md,AGENTS.md,docs/knowledge-base/**/*.md'
+name: web-capabilities Code Review
+description: Use when reviewing capability checks, browser detection, system info, WASM runtime probing, worker lifecycle, public exports, tests, or architecture guidance.
+---
+
+# Code Review Instructions
+
+## Priorities
+
+1. `CapabilityState` stays correct. Return `UNKNOWN` when signals are missing instead of guessing.
+2. Keep `WebCapabilities.supportsWasm()` separate from `WasmRuntimeProbe.check()`. They answer different questions.
+3. Preserve probe cleanup: terminate the worker and revoke the Blob URL.
+4. Treat probe thresholds, check order, visibility handling, and reason codes as correctness-sensitive.
+5. Treat public exports and capability outcomes as compatibility-sensitive.
+6. Require tests when behavior changes at browser boundaries or in the WASM probe.
+
+## Checks
+
+- Prefer browser APIs and feature detection. Use `BrowserInfo` for version checks instead of new user-agent parsing.
+- Do not use the WASM availability helper as a stand-in for the async speed probe, or the other way around.
+- Keep the probe's one-result-per-page cache unless a test intentionally resets it.
+- Reject invalid worker measurements before classification.
+- Return `UNKNOWN` for background-tab and too-short timing cases instead of a false slow or fast result.
+- Keep `CpuInfo` deprecated behavior stable for existing callers.
+- Register and unregister `SystemInfo` pressure callbacks safely when the API is missing.
+- Keep JSDoc complete where ESLint requires it.
+- Verify documentation claims against source, tests, and configuration.
+- Do not add secrets, private URLs, real user-agent captures, or local absolute paths.

.github/instructions/testing.instructions.md

@@ -0,0 +1,35 @@
+---
+applyTo: 'src/**/*.spec.ts,src/**/*.worker.js'
+name: web-capabilities Tests
+description: Use when writing or reviewing co-located Jest tests and WASM worker benchmark behavior.
+---
+
+# Testing Instructions
+
+## Framework and location
+
+- Jest runs through `ts-jest` in the environment configured by `jest.config.js`. Check `package.json` and `jest.config.js` instead of pinning tool versions in guidance.
+- Keep tests next to source as `src/**/*.spec.ts`.
+- Import worker source through the same path the production code uses. `jest.config.js` applies a raw transform to `*.worker.js`.
+- Use `yarn test:unit` for focused runtime feedback and `yarn test:coverage` for the pull-request test command.
+- Run `yarn transpile:validate` when changing exports, public types, probe result shapes, or worker message contracts.
+
+## Test patterns
+
+- Name the top-level `describe` after the class or capability under test.
+- Use behavior-focused `it('should ...')` descriptions.
+- Reset `WasmRuntimeProbe` cached state in `beforeEach` when testing probe behavior.
+- Mock `Worker`, `URL.createObjectURL`, and `URL.revokeObjectURL` when exercising probe orchestration without running the real benchmark.
+- Stub browser globals such as `WebAssembly`, `RTCPeerConnection`, codec capabilities, and `document.visibilityState` explicitly for capability tests.
+- Assert full result objects or focused fields for `status`, `capability`, `reason`, and `measurements` where classification matters.
+- Keep tests independent. Avoid relying on execution order across spec files.
+
+## Required coverage by change type
+
+- Capability method changes: `CAPABLE`, `NOT_CAPABLE`, and `UNKNOWN` paths, including missing hardware or API signals.
+- Browser helper changes: version comparison helpers and browser or OS identification against controlled parser inputs.
+- System info changes: pressure observer support, callback registration, immediate callback when state already exists, and logical core count behavior.
+- WASM support changes: disabled runtime, missing worker support, worker start failure, timeout, runtime error, invalid measurements, and cleanup.
+- Probe classification changes: fast ratios, slow ratios, uncertain combinations, background tab, divide timing too short, and measurement rounding.
+- Public type changes: TypeScript validation plus runtime tests where behavior also changes.
+- Regression fixes: the smallest mock or stub setup that fails before the fix and passes after it.

.github/pull_request_template.md

@@ -1,28 +1,35 @@
 ## Description
+
 <!-- Provide a summary of the changes you are making, including any relevant JIRAs and screenshots. -->
 
 ## This change implements...
+
 - [ ] A new feature
 - [ ] A bug fix
 - [ ] Other (please specify):
 
 ## Is this a breaking change?
+
 - [ ] Yes
 - [ ] No
 
 ## I certify that...
+
 - [ ] All relevant unit and integration tests have passed and/or have been updated according to this change.
 
 ## Generative AI (GAI) Usage Disclosure
+
 [Reference: Cisco GAI Coding Guidelines](https://cisco.sharepoint.com/sites/AIML/SitePages/Practice-Guide---GAI-Coding.aspx)
 
 - [ ] **Cisco approved GAI tool/IDE was used for coding** - eg: VSCode, Cursor, Windsurf, Codex, Claude code
 - [ ] **No GAI** - Code was written entirely manually without GAI assistance
 
 **If a GAI tool/IDE was used then select the category that best describes GAI usage in this PR:**
-- [ ] **Manual Draft with GAI Refinement** - I/we created a draft manually that was non-substantively modified by GAI (e.g., refactoring was performed by GAI on manually written code) *(Default)*
+
+- [ ] **Manual Draft with GAI Refinement** - I/we created a draft manually that was non-substantively modified by GAI (e.g., refactoring was performed by GAI on manually written code) _(Default)_
 - [ ] **GAI Draft with Manual Customization** - GAI tool was used to create a draft that I/we subsequently customized or modified.
 - [ ] **GAI Generated Code** - Code was generated entirely by GAI
 
 **Additional GAI Usage Details (Optional):**
+
 <!-- Provide any additional context about GAI usage, tools used (e.g., Claude Code, Copilot, ChatGPT), or specific areas where GAI was applied -->

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

@@ -0,0 +1,74 @@
+---
+name: pr-description
+description: Draft accurate web-capabilities pull-request descriptions from the repository template, committed changes, and observed test evidence.
+---
+
+# PR Description
+
+Create a concise, reader-friendly pull-request description that helps reviewers understand why the change matters, what behavior changes, and how it was verified.
+
+## Sources
+
+Read these before drafting:
+
+1. `.github/pull_request_template.md`
+2. The complete committed diff against the pull-request base branch
+3. All branch commits
+4. Test output supplied by the author or produced in the current session
+5. Public issues or documentation linked by the author
+
+Repository files and observed results are authoritative. Do not invent motivation, test evidence, issue links, screenshots, browser compatibility, or release claims.
+
+## Workflow
+
+1. Confirm the base branch. Use `main` when no other base is specified.
+2. Review the complete branch diff, not only the latest commit.
+3. Check `git status`. If uncommitted changes exist, warn the author and exclude them from the pull-request description until committed.
+4. Identify effects on capability outcomes, browser detection, system info, WASM checks, runtime probe behavior, public exports, declarations, package formats, runtime dependencies, and release behavior.
+5. Ask what manual testing was performed. Request the browser scenario and result when relevant. If no manual testing was needed, ask the author to confirm why.
+6. Ask only for facts that cannot be derived, such as a public issue link, screenshots, or the Generative AI disclosure category.
+7. Produce the completed repository template without removing headings or policy checkboxes. Do not reproduce private-only links in newly drafted text.
+
+## Description rules
+
+- Under `Description`, start with two to four short bullets that explain the developer or user outcome.
+- Lead with why the change is useful, then explain what changed to achieve it.
+- Use plain language, active voice, and short sentences. Explain an unavoidable technical term the first time it appears.
+- Prefer outcomes such as “documentation commands cannot remove contributor guides” over implementation phrases such as “isolate generated output.”
+- Describe behavior and developer outcomes instead of listing changed files or repeating the diff.
+- Include implementation details only when they help a reviewer evaluate correctness or compatibility.
+- State important non-effects directly, such as “This does not change runtime behavior or the public API.”
+- Add a short `Testing` subsection under `Description` with only commands and manual checks that actually ran.
+- Summarize warnings or partial results in plain language and identify whether they existed before the change.
+- When manual testing was not needed, explain why in one sentence.
+- Call out capability outcome changes, browser detection changes, probe classification changes, public API impact, declaration changes, package compatibility, dependency changes, migration steps, or semantic-version impact only when supported by the diff.
+- Preserve the `This change implements...`, breaking-change, certification, and Generative AI sections.
+- Keep checkboxes unchecked when evidence or author input is missing.
+- Never mark the test certification checkbox without evidence.
+- Never select a Generative AI disclosure category for the author.
+- Do not add a dedicated risk section. Fold important compatibility or rollout notes into the description bullets when the diff requires them.
+- Use only public links in this public repository.
+
+## Wording example
+
+Avoid:
+
+> Preserve maintained documentation by isolating generated TypeDoc output and extend validation coverage.
+
+Prefer:
+
+> Keep generated API documentation separate from contributor guides so documentation commands cannot remove maintained content. Include the new guides in formatting and spell checks.
+
+For capability or probe changes, prefer:
+
+> Treat background-tab probe runs as inconclusive (`UNKNOWN`) instead of slow WASM.
+
+over:
+
+> Add `BACKGROUND_TAB` handling in `WasmRuntimeProbe.classify()`.
+
+## Output
+
+Return one Markdown block that can be pasted into GitHub.
+
+After the block, list unresolved author questions separately. Do not put `TBD` placeholders in an otherwise final description.

.github/workflows/pull-request-checks.yml

@@ -10,4 +10,8 @@ jobs:
           node-version: 22
       - run: yarn install
       - run: yarn test:lint
+      - run: yarn test:prettier
+      - run: yarn test:spelling
+      - run: yarn transpile:validate
+      - run: yarn build
       - run: yarn test:coverage

.gitignore

@@ -2,3 +2,4 @@ node_modules
 dist
 .idea/
 coverage/
+docs/api/