OpenVoiceOS
diff --git a/‎.github/workflows/coverage.yml‎
Lines changed: 1 addition & 1 deletion b/‎.github/workflows/coverage.yml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.github/workflows/docs_check.yml‎
Lines changed: 13 additions & 0 deletions b/‎.github/workflows/docs_check.yml‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎.github/workflows/locale_check.yml‎
Lines changed: 14 additions & 0 deletions b/‎.github/workflows/locale_check.yml‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎.github/workflows/ovoscope.yml‎
Lines changed: 25 additions & 0 deletions b/‎.github/workflows/ovoscope.yml‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎.github/workflows/release_preview.yml‎
Lines changed: 13 additions & 0 deletions b/‎.github/workflows/release_preview.yml‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎.github/workflows/repo_health.yml‎
Lines changed: 14 additions & 0 deletions b/‎.github/workflows/repo_health.yml‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎.github/workflows/sync_translations.yml‎
Lines changed: 17 additions & 0 deletions b/‎.github/workflows/sync_translations.yml‎
Lines changed: 17 additions & 0 deletions
diff --git a/‎.github/workflows/type_check.yml‎
Lines changed: 14 additions & 0 deletions b/‎.github/workflows/type_check.yml‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎AUDIT.md‎
Lines changed: 5 additions & 0 deletions b/‎AUDIT.md‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎FAQ.md‎
Lines changed: 96 additions & 0 deletions b/‎FAQ.md‎
Lines changed: 96 additions & 0 deletions
@@ -14,7 +14,7 @@ jobs:
     with:
       system_deps: 'python3-dev swig libssl-dev portaudio19-dev libpulse-dev libfann-dev'
       install_extras: '.[mycroft,plugins,skills-essential,lgpl,test]'
-      test_path: 'test/'
+      test_path: 'test/unittests'
       coverage_source: 'ovos_core'
       deploy_pages: true
       gh_pages_branch: 'gh-pages'
@@ -0,0 +1,13 @@
+name: Docs Check
+
+on:
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  docs_check:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/docs-check.yml@dev
+    secrets: inherit
+    with:
+      pr_comment: true
@@ -0,0 +1,14 @@
+name: Locale Build Check
+
+on:
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  locale_check:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/locale-check.yml@dev
+    secrets: inherit
+    with:
+      locale_path: 'ovos_core/intent_services/locale'
+      pr_comment: true
@@ -0,0 +1,25 @@
+name: Ovoscope End-to-End Tests
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  ovoscope:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/ovoscope.yml@dev
+    secrets: inherit
+    with:
+      runner: "ubuntu-latest"
+      python_version: "3.11"
+      system_deps: "python3-dev swig libssl-dev portaudio19-dev libpulse-dev libfann-dev"
+      install_extras: "test"
+      test_path: "test/end2end/"
+      require_adapt: true
+      require_padatious: true
+      bus_coverage: true
+      bus_coverage_include: ""
+      bus_coverage_exclude: "^Thread-|^intents$|^skills$|^__core__$"
+      pr_comment: true
@@ -0,0 +1,13 @@
+name: Release Preview
+
+on:
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  release_preview:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/release-preview.yml@dev
+    secrets: inherit
+    with:
+      version_file: 'ovos_core/version.py'
@@ -0,0 +1,14 @@
+name: Repo Health
+
+on:
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  repo_health:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/repo-health.yml@dev
+    secrets: inherit
+    with:
+      version_file: 'ovos_core/version.py'
+      pr_comment: true
@@ -0,0 +1,17 @@
+name: Sync Translations
+
+on:
+  push:
+    branches: [dev]
+    paths:
+      - 'ovos_core/intent_services/locale/**'
+  workflow_dispatch:
+
+jobs:
+  sync_translations:
+    if: github.actor == 'gitlocalize-app[bot]' || github.event_name == 'workflow_dispatch'
+    uses: OpenVoiceOS/gh-automations/.github/workflows/sync-translations.yml@dev
+    secrets: inherit
+    with:
+      branch: 'dev'
+      locale_path: 'ovos_core/intent_services/locale'
@@ -0,0 +1,14 @@
+name: Type Check
+
+on:
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  type_check:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/type-check.yml@dev
+    secrets: inherit
+    with:
+      python_version: "3.11"
+      pr_comment: true
@@ -22,6 +22,11 @@
 - **Missing return type hints** across `skill_manager.py` (all 35 methods), `skill_installer.py`, `transformers.py` — all added.
 - **Missing docstrings** on `SkillsStore` methods — added.
 
+## Race Conditions (Fixed 2026-03-11)
+- **plugin_skills dict concurrent mutation** (skill_manager.py:585-603, 618-661) — `_unload_plugin_skill` and iteration methods were not guarded by `_plugin_skills_lock`, creating RuntimeError: dictionary changed size during iteration. FIXED: added lock guards and snapshot-before-iterate pattern.
+- **Busy-wait in fallback skill response collection** (fallback_service.py:122-125) — `_collect_fallback_skills` spun with `time.sleep(0.02)` on every utterance. FIXED: replaced with `threading.Event` signaling.
+- **Temporary Event object spam** (skill_manager.py:462) — `wait_for_intent_service` created one throwaway Event per 1-second retry. FIXED: reused `self._stop_event`.
+
 ## Known Open Issues (Tracked in SUGGESTIONS.md)
 - **S-001**: `_unload_on_network_disconnect/internet_disconnect/gui_disconnect` are stub methods — no implementation.
 - **S-002**: `handle_uninstall_skill` always returns "not implemented".
 
@@ -1,6 +1,70 @@
 
 # FAQ - ovos-core
 
+## CI / Testing
+
+### What end-to-end tests does ovos-core run?
+
+ovos-core uses **ovoscope** for end-to-end skill testing. Tests live in `test/end2end/` and run via the `ovoscope.yml` GitHub Actions workflow.
+
+The workflow:
+- Installs ovos-core with `[mycroft,plugins,skills-essential,lgpl,test]` extras
+- Runs all tests in `test/end2end/` using pytest
+- Tests Adapt, Padatious, fallback, converse, and stop pipeline behaviours
+- Posts a `🔌 Skill Tests (ovoscope)` section to PR comments
+- Generates a `🚌 Bus Coverage` report showing which bus messages were observed/asserted
+
+See [ovoscope documentation](https://github.com/TigreGotico/ovoscope) for framework details.
+
+### How do I run end-to-end tests locally?
+
+```bash
+# Install ovos-core with test extras
+uv pip install -e .[test]
+
+# Run end-to-end tests
+pytest test/end2end/ -v --timeout=60
+
+# With bus coverage tracking
+pytest test/end2end/ -v --ovoscope-bus-cov --ovoscope-bus-cov-verbose
+```
+
+### What is bus coverage?
+
+Bus coverage tracks which bus message types your tests observe and assert against. Unlike code coverage, it measures **behavioural coverage** — whether your tests exercise the full range of bus interactions a skill produces.
+
+The bus coverage report shows:
+- **Listeners**: Which message handlers were triggered (and how many times)
+- **Emitters**: Which messages were emitted during tests
+- **Assertions**: Which emitted messages were explicitly asserted in test expectations
+
+See `ovoscope/docs/ci-integration.md` for configuration details.
+
+---
+
+## How does `validate_skill` prevent installing incompatible skills?
+
+`SkillsStore.validate_skill()` (`skill_installer.py:226`) performs lightweight GitHub API validation (no auth required for public repos):
+
+1. URL must start with `https://github.com/`.
+2. The repository must exist (HTTP 200 from `api.github.com/repos/{owner}/{repo}/contents/`).
+3. The repo must contain `pyproject.toml` or `setup.cfg` — a bare `setup.py`-only repo is rejected as legacy packaging.
+4. `pyproject.toml`/`setup.cfg` must not reference `MycroftSkill` or `CommonPlaySkill` — those indicate an incompatible legacy skill.
+
+If GitHub is unreachable (network error or non-404 API error), the method returns `True` (fail-open) so transient outages do not block installs.
+
+---
+
+## Why does IntentService time out waiting at startup?
+
+If `wait_for_intent_service` raises `RuntimeError: IntentService did not become ready within 300 seconds`, the IntentService process is either not running or not connected to the messagebus. The timeout is configurable via `skills.intent_service_timeout` in `mycroft.conf` (seconds, default 300).
+
+## Why does converse/stop skip a skill that doesn't respond to the ping?
+
+Since 2026-03-12, `_collect_converse_skills` and `_collect_stop_skills` use `can_handle` default `False`. A skill that does not respond to the converse/stop ping within 0.5 s is excluded — it is not assumed to want to handle the utterance. This avoids stale listeners and unexpected behaviour when a skill process is unresponsive.
+
+---
+
 ## What is ovos-core?
 `ovos-core` is the central component of the OpenVoiceOS platform, responsible for skill management, intent parsing, and orchestration of the voice assistant's features. It is a fork of the original Mycroft AI core.
 
@@ -100,3 +164,35 @@ Set `intents.multilingual_matching: true` in `mycroft.conf`. If the primary lang
 ### What are utterance transformers?
 Plugins under the `opm.utterance_transformer` entry point that pre-process utterances before intent matching. Configured under `utterance_transformers` in `mycroft.conf`. Loaded by `UtteranceTransformersService` in `ovos_core/transformers.py`.
 
+---
+
+## Performance
+
+### What performance optimizations are in place?
+`ovos-core` includes several built-in optimizations:
+
+- **Thread-safe skill loading** — `_plugin_skills_lock` prevents concurrent dict mutation during `_load_plugin_skill()` and `_unload_plugin_skill()` (skill_manager.py:585-603)
+- **Safe iteration snapshots** — `send_skill_list()`, `deactivate_skill()`, `activate_skill()`, and `deactivate_except()` snapshot the plugin_skills dict inside the lock before iterating to prevent RuntimeError during concurrent modifications
+- **Event-based fallback signaling** — `_collect_fallback_skills()` uses `threading.Event` instead of busy-wait (fallback_service.py:122-125), reducing CPU usage on utterances reaching fallback
+- **Reusable stop event** — `wait_for_intent_service()` reuses `self._stop_event` instead of creating temporary Event objects (skill_manager.py:462)
+- **Pipeline matcher caching** — `get_pipeline_matcher()` uses module-level constants for migration map and pre-compiled regex (service.py:39-63, 237-238)
+- **Deferred thread spawning** — `create_daemon()` for metrics upload is guarded by config check; threads only spawn if `open_data.intent_urls` is configured (service.py:322, 352)
+- **Transformer plugin caching** — `UtteranceTransformersService`, `MetadataTransformersService`, and `IntentTransformersService` cache sorted plugins; cache is invalidated on `load_plugins()` (transformers.py)
+- **Fast blacklist lookup** — `_logged_skill_warnings` is a set (O(1) lookup) instead of list (skill_manager.py:111)
+- **Single blacklist read** — blacklist is read once before the plugin scan loop, not per-skill (skill_manager.py:363)
+
+### How can I measure ovos-core performance?
+Use the `Stopwatch` utility from `ovos_utils.metrics` to profile hot paths. Example:
+```python
+from ovos_utils.metrics import Stopwatch
+with Stopwatch("intent_match") as s:
+    match = self.intent_plugins.transform(match)
+LOG.info(f"Intent transform took {s.total} seconds")
+```
+
+### Why does my IntentService seem slow on startup?
+Common causes:
+- **No internet** — pipeline plugins that require network (e.g., OpenWeatherMap) may timeout. Set their timeout or disable them.
+- **Many skills** — each skill loads sequentially by default. Enable deferred loading: `skills.use_deferred_loading: true`
+- **Slow utterance transformers** — check that plugins are not making network calls in the critical path. Consider disabling unused ones.
+