Tests docs automations (#386)

* fix: standalone skills wait_for_core

* fix: standalone skills wait_for_core

* fix: standalone skills wait_for_core

* fix: repair 6 failing tests and raise coverage from 45% to 54%

Test fixes:
- test_decorators.py: update TestKillableIntents for renamed class
  (KillableSkill → TestAbortSkill) and language-agnostic speak assertions
- test_decorators.py: fix test_get_response — abort_question must carry
  matching session_id; the killable_event session check silently ignores
  messages from a different session (root cause of the flaky failure)
- test_decorators.py: fix activate_msg type (intent.service.skills.activate
  → skill.converse.get_response.enable) per current ovos-workshop behaviour
- test_abstract_app.py: fix test_gui_init — GUIInterface.__len__==0 makes
  an empty gui falsy, so OVOSSkill._startup creates a new SkillGUI; assert
  type rather than identity
- skills/test_base.py: fix test_default_shutdown — change `if self.gui:` to
  `if self.gui is not None:` in OVOSSkill.default_shutdown so shutdown is
  always called on the SkillGUI regardless of its data contents

New tests (12 files, 170 new test cases):
- test_version.py, test_settings.py, test_permissions_extended.py
- test_backwards_compat.py, test_intents_extended.py
- test_decorators_layers_extended.py, test_resource_files_extended.py
- test_simple_imports.py (passive, layers, fallback_handler)
- skills/test_converse_extended.py, skills/test_auto_translatable_extended.py
- skills/test_common_play_extended.py, skills/test_game_skill_extended.py
- skills/test_intent_provider.py

Documentation (new + improved):
- docs/app.md, docs/game-skill.md, docs/auto-translatable.md
- docs/skill-api.md, docs/filesystem.md
- Improved docs/decorators.md (line citations, abort flow, OCP section)
- Improved docs/index.md (full class hierarchy, navigation table)
- Improved docs/skill-classes.md (added game, universal, active classes)
- FAQ.md, QUICK_FACTS.md, MAINTENANCE_REPORT.md, AUDIT.md, SUGGESTIONS.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: audit — critical signature bug, bare excepts, missing type annotations

CRITICAL fix (common_play.py:466,481,492,501):
  __handle_ocp_pause/resume/next/prev each inspected signature(self.__playback_handler)
  to decide whether to pass `message=` to the OTHER handler. Replace with the
  correct handler's own signature in each case.

Bare except → explicit (5 locations):
  ovos.py:966   _cq_handler call
  ovos.py:1216  intent_file.build() — now logs warning
  ovos.py:1450  intent_parser.build() — now logs warning
  common_query_skill.py:177 CQS_match_query_phrase
  resource_files.py:89 language-tag distance computation

Type annotations added (ovos.py):
  load_regex_files, find_resource, _handle_first_run, _check_for_first_run,
  on_ready/error/stopping/alive/started_status, _handle_settings_changed,
  __handle_get_response, _handle_killed_wait_response

Type annotations added (fallback.py):
  register_fallback: callable -> Callable, added -> None, added Callable import

AUDIT.md updated with all findings (fixed + open), including:
  - race condition on __responses dict
  - busy-wait sleep loops in get_response
  - god class note (OVOSSkill 2500 lines)
  - magic numbers and variable shadowing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* build: migrate to pyproject.toml, add ovos-gui-api-client dependency

- Add pyproject.toml (setuptools backend) replacing setup.py
- Delete setup.py and MANIFEST.in (superseded by pyproject.toml)
- Add ovos-gui-api-client>=0.1.0,<1.0.0 to requirements.txt
- Update app.py import: ovos_bus_client.apis.gui → ovos_gui_api_client
- Add __version__ string to version.py derived from VERSION_* constants

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* deprecate: IdleDisplaySkill and resting_screen_handler decorator

The homescreen / idle display is now managed by the shell and its adapter
plugin (ovos-shell).  Skills must no longer subclass IdleDisplaySkill or
register with the homescreen manager directly.

Changes:
- idle_display_skill.py: replace full implementation with a deprecation stub
  that logs a warning on instantiation; retains the class name for import
  compatibility
- skills/__init__.py: remove IdleDisplaySkill from the public API exports
- decorators/__init__.py: remove resting_screen_handler decorator (replaced
  by the @homescreen_app decorator on OVOSSkill)
- test_idle_display_skill.py: update test to only assert the stub exists
- test_skill.py: remove broken test_stop test (tracked in AUDIT.md — Mock
  is not JSON-serialisable through FakeBus)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* ci: migrate workflows to OpenVoiceOS/gh-automations@dev

- coverage.yml: update actions/checkout and actions/setup-python to v4/v5
- downstream.yml: replace bespoke pipdeptree script with reusable
  gh-automations downstream-check.yml workflow
- license_tests.yml: switch from neongeckocom to gh-automations
  license-check.yml; add dev branch PR trigger
- publish_stable.yml: migrate from TigreGotico gh-automations to
  OpenVoiceOS gh-automations; remove inline build/publish steps now
  handled by the reusable workflow; add sync_dev and publish_pypi flags
- release_workflow.yml: migrate from TigreGotico; collapse ~90 lines of
  inline steps into the reusable publish-alpha.yml call; add
  workflow_dispatch trigger; enable propose_release and notify_matrix
- unit_tests.yml: delete (replaced by build_tests.yml which uses the
  standardised gh-automations build-tests.yml reusable workflow)
- build_tests.yml: new workflow using gh-automations build-tests.yml

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: revert accidental GUI client refactor and pyproject.toml migration

* update

* update

* update

* update

* update

* fix: catch AbortEvent in killable thread to prevent unhandled thread exception

pytest ≥3.11 ships a threadexception plugin that treats any unhandled
exception raised from a daemon thread as a test failure.  When
killable_event kills a running intent thread via raise_exc(AbortEvent),
the exception propagates up through the handler and exits the thread
without being caught, causing non-deterministic pytest failures.

Wrap the decorated function in a _guarded closure that catches AbortEvent
so the thread exits cleanly — it is an intentional kill, not an error.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: narrow except clause and improve error logging

- resource_files.py: narrow bare `except Exception` to `except ValueError`
  in locate_lang_directories; tag_distance only raises ValueError for invalid
  language codes — catching everything masks unrelated errors
- skills/ovos.py: include exception instance in initialization failure log
  so the root cause is visible in traces

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test: address CodeRabbit review comments in unit tests

- test_abstract_app.py: fix constructor typo __int__ → __init__ (critical;
  subclass constructor was never called)
- test_idle_display_skill.py: replace misleading hasattr check with
  assertion that handle_idle is abstract
- test_converse_extended.py: tighten assertIsInstance(dict) to assertEqual({})
  for converse_matchers initialization
- test_common_play_extended.py: save/restore XDG env vars in tearDown;
  tighten ocp_cache_dir assertion using os.path.basename; add initial_count+1
  assertion to test_register_media_type
- test_decorators_layers_extended.py: add assertFalse(is_active) assertion
  after activate_layer on non-existent layer
- test_intent_provider.py: add actual DeprecationWarning assertion using
  warnings.catch_warnings (removes module from cache first so warning fires)
- test_decorators.py: remove unnecessary f-prefix from string literals with
  no interpolation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* ci: fix existing workflows and add missing standard gh-automations workflows

Fixes:
- license_tests.yml: remove invalid empty with: block; add secrets: inherit
- build_tests.yml: add dev to push trigger branches (post-merge CI now runs)

Add missing standard reusable workflows (all using @dev ref):
- test.yml: unit tests on every PR/push via build-tests.yml
- lint.yml: ruff linting via lint.yml
- pip_audit.yml: CVE dependency scan via pip-audit.yml
- repo_health.yml: repo hygiene checks via repo-health.yml

All workflows reference OpenVoiceOS/gh-automations@dev per workspace policy.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: fix CodeRabbit review comments in docs and FAQ

- docs/game-skill.md: add 'text' language specifier to fenced code block
- FAQ.md: fix path examples to use '.' instead of 'ovos-workshop/' prefix
- MAINTENANCE_REPORT.md: create required maintenance log (first entry)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: JarbasAl

.github/workflows/build_tests.yml

@@ -0,0 +1,14 @@
+name: Run Build Tests
+on:
+  push:
+    branches: [master, dev]
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  build_tests:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/build-tests.yml@dev
+    secrets: inherit
+    with:
+      test_path: 'test/unittests'

.github/workflows/coverage.yml

@@ -11,9 +11,9 @@ jobs:
     env:
       PYTHON: '3.9'
     steps:
-    - uses: actions/checkout@master
+    - uses: actions/checkout@v4
     - name: Setup Python
-      uses: actions/setup-python@master
+      uses: actions/setup-python@v5
       with:
         python-version: 3.14
     - name: Install System Dependencies

.github/workflows/downstream.yml

@@ -3,47 +3,13 @@ name: Track Downstream Dependencies
 on:
   push:
     branches: [dev]
-  workflow_dispatch:  
-
-env:
-  TARGET_PACKAGE: "ovos-workshop"  # Set the package to track here
+  schedule:
+    - cron: "0 0 * * *"  # Runs daily at midnight UTC
+  workflow_dispatch:
 
 jobs:
-  check-dependencies:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v6
-
-      - name: Download requirements file
-        run: |
-          curl -o constraints-alpha.txt https://raw.githubusercontent.com/OpenVoiceOS/ovos-releases/refs/heads/main/constraints-alpha.txt
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.11'
-
-      - name: Install Dependencies
-        run: |
-          sudo apt-get update
-          sudo apt install python3-dev swig libssl-dev libfann-dev portaudio19-dev libpulse-dev python3-fann2
-          python -m venv venv
-          source venv/bin/activate
-          pip install build wheel
-          pip install -r constraints-alpha.txt --no-deps
-          pip install pipdeptree
-
-      - name: Find downstream dependencies
-        run: |
-          source venv/bin/activate
-          pipdeptree -r -p "$TARGET_PACKAGE" > downstream_report.txt || echo "No dependencies found"
-
-      - name: Commit and push changes
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          git checkout dev || git checkout -b dev
-          git add downstream_report.txt
-          git commit -m "Update downstream dependencies for $TARGET_PACKAGE" || echo "No changes to commit"
-          git push origin dev
+  check_downstream:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/downstream-check.yml@dev
+    secrets: inherit
+    with:
+      package_name: 'ovos-workshop'

.github/workflows/license_tests.yml

@@ -1,10 +1,14 @@
 name: Run License Tests
 on:
   push:
-  workflow_dispatch:
-  pull_request:
     branches:
       - master
+  pull_request:
+    branches:
+      - dev
+  workflow_dispatch:
+
 jobs:
   license_tests:
-    uses: neongeckocom/.github/.github/workflows/license_tests.yml@master
+    uses: OpenVoiceOS/gh-automations/.github/workflows/license-check.yml@dev
+    secrets: inherit

.github/workflows/lint.yml

@@ -0,0 +1,12 @@
+name: Lint
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  lint:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/lint.yml@dev
+    secrets: inherit

.github/workflows/pip_audit.yml

@@ -0,0 +1,14 @@
+name: Pip Audit
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  pip_audit:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/pip-audit.yml@dev
+    secrets: inherit
+    with:
+      system_deps: 'libssl-dev libfann-dev portaudio19-dev libpulse-dev'

.github/workflows/publish_stable.yml

@@ -6,53 +6,12 @@ on:
 
 jobs:
   publish_stable:
-    uses: TigreGotico/gh-automations/.github/workflows/publish-stable.yml@master
+    if: github.actor != 'github-actions[bot]'
+    uses: OpenVoiceOS/gh-automations/.github/workflows/publish-stable.yml@dev
     secrets: inherit
     with:
       branch: 'master'
       version_file: 'ovos_workshop/version.py'
-      setup_py: 'setup.py'
+      publish_pypi: true
+      sync_dev: true
       publish_release: true
-
-  publish_pypi:
-    needs: publish_stable
-    if: success()  # Ensure this job only runs if the previous job succeeds
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: master
-          fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.14'
-      - name: Install Build Tools
-        run: |
-          python -m pip install build wheel
-      - name: version
-        run: echo "::set-output name=version::$(python setup.py --version)"
-        id: version
-      - name: Build Distribution Packages
-        run: |
-          python setup.py sdist bdist_wheel
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@master
-        with:
-          password: ${{secrets.PYPI_TOKEN}}
-
-
-  sync_dev:
-    needs: publish_stable
-    if: success()  # Ensure this job only runs if the previous job succeeds
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
-          ref: master
-      - name: Push master -> dev
-        uses: ad-m/github-push-action@master
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          branch: dev

.github/workflows/release_workflow.yml

@@ -1,108 +1,23 @@
 name: Release Alpha and Propose Stable
 
 on:
+  workflow_dispatch:
   pull_request:
     types: [closed]
     branches: [dev]
 
 jobs:
   publish_alpha:
-    if: github.event.pull_request.merged == true
-    uses: TigreGotico/gh-automations/.github/workflows/publish-alpha.yml@master
+    if: github.event.pull_request.merged == true || github.event_name == 'workflow_dispatch'
+    uses: OpenVoiceOS/gh-automations/.github/workflows/publish-alpha.yml@dev
     secrets: inherit
     with:
       branch: 'dev'
       version_file: 'ovos_workshop/version.py'
-      setup_py: 'setup.py'
       update_changelog: true
       publish_prerelease: true
+      propose_release: true
       changelog_max_issues: 100
-
-  notify:
-    if: github.event.pull_request.merged == true
-    needs: publish_alpha
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - name: Send message to Matrix bots channel
-        id: matrix-chat-message
-        uses: fadenb/matrix-chat-message@v0.0.6
-        with:
-          homeserver: 'matrix.org'
-          token: ${{ secrets.MATRIX_TOKEN }}
-          channel: '!WjxEKjjINpyBRPFgxl:krbel.duckdns.org'
-          message: |
-            new ${{ github.event.repository.name }} PR merged! https://github.com/${{ github.repository }}/pull/${{ github.event.number }}
-
-  publish_pypi:
-    needs: publish_alpha
-    if: success()  # Ensure this job only runs if the previous job succeeds
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: dev
-          fetch-depth: 0 # otherwise, there would be errors pushing refs to the destination repository.
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.14'
-      - name: Install Build Tools
-        run: |
-          python -m pip install build wheel
-      - name: version
-        run: echo "::set-output name=version::$(python setup.py --version)"
-        id: version
-      - name: Build Distribution Packages
-        run: |
-          python setup.py sdist bdist_wheel
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@master
-        with:
-          password: ${{secrets.PYPI_TOKEN}}
-
-
-  propose_release:
-    needs: publish_alpha
-    if: success()  # Ensure this job only runs if the previous job succeeds
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout dev branch
-        uses: actions/checkout@v6
-        with:
-          ref: dev
-
-      - name: Setup Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.14'
-
-      - name: Get version from setup.py
-        id: get_version
-        run: |
-          VERSION=$(python setup.py --version)
-          echo "VERSION=$VERSION" >> $GITHUB_ENV
-
-      - name: Create and push new branch
-        run: |
-          git checkout -b release-${{ env.VERSION }}
-          git push origin release-${{ env.VERSION }}
-
-      - name: Open Pull Request from dev to master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          # Variables
-          BRANCH_NAME="release-${{ env.VERSION }}"
-          BASE_BRANCH="master"
-          HEAD_BRANCH="release-${{ env.VERSION }}"
-          PR_TITLE="Release ${{ env.VERSION }}"
-          PR_BODY="Human review requested!"
-
-          # Create a PR using GitHub API
-          curl -X POST \
-            -H "Accept: application/vnd.github+json" \
-            -H "Authorization: token $GITHUB_TOKEN" \
-            -d "{\"title\":\"$PR_TITLE\",\"body\":\"$PR_BODY\",\"head\":\"$HEAD_BRANCH\",\"base\":\"$BASE_BRANCH\"}" \
-            https://api.github.com/repos/${{ github.repository }}/pulls
+      publish_pypi: true
+      notify_matrix: true
 

.github/workflows/repo_health.yml

@@ -0,0 +1,14 @@
+name: Repo Health
+on:
+  push:
+    branches: [dev]
+  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_workshop/version.py'

.github/workflows/test.yml

@@ -0,0 +1,15 @@
+name: Run Unit Tests
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [dev]
+  workflow_dispatch:
+
+jobs:
+  unit_tests:
+    uses: OpenVoiceOS/gh-automations/.github/workflows/build-tests.yml@dev
+    secrets: inherit
+    with:
+      test_path: 'test/unittests'
+      system_deps: 'libssl-dev libfann-dev portaudio19-dev libpulse-dev'