Add a fail_if_metadata_sync_needed policy flag and utilities to detect/collect files whose embedded metadata last_content_updated differs from the computed git content date. New helpers: record_needs_metadata_sync() (skips non-md/ipynb and meta.ignore), collect_metadata_sync_targets() (returns sorted unique paths), and build_metadata_sync_command() (emits a ready-to-run python command to update targets using --set-content-date-from-git and --ack-meta-commit-marker). The enforce() flow now emits violations for out-of-sync md/ipynb files when the flag is enabled.

Introduce actionable metadata-sync guidance for maintainers: rename SCHEMA_VERSION to REPORT_SCHEMA_VERSION, restrict ToolConfig.version to 1, and add metadata_sync_targets and metadata_sync_command to the Report model. Add build_git_add_command helper and mark records requiring metadata sync (metadata_sync_needed) so summaries include that count. Extend markdown output and CLI to show which files need metadata updates and to print suggested commands (sync command, git add and commit) for applying fixes locally.

Update the GitHub Actions workflow to only run docs and notebook staleness checks for changed .md/.markdown/.ipynb files. Adds a step to collect changed docs into tmp/docs_nb_checks/changed_docs.txt and expose the count via outputs; conditionally runs the report and optional policy check only when there are changed files, passing the files as --targets to the checker. Adds a no-op step when no docs changed and uploads the changed_docs.txt alongside other artifacts. Also renames the job to reflect the new behavior to reduce unnecessary scanning and noise.

Introduce shared pytest fixtures (repo, cfg) and import Callable to reduce repetition of tmp_path/git init logic across tests. Refactor many tests to use the new fixtures and ToolConfig factory, and add/adjust tests covering target validation and scanning edge cases (several validate_requested_targets variations, scan_files with invalid only-targets, and main returning 2 for invalid selector). Overall this centralizes repo/config setup and adds coverage for target handling behavior.

as it is unused

tools/docs_and_notebooks_check.py: Return False from record_needs_metadata_sync when computed timestamp is None to avoid triggering sync for files with no computed last_content_updated. Also import shlex and quote paths in build_metadata_sync_command so generated shell commands are safe for paths with spaces/special chars.

Expand and clarify the --targets argument help strings in tools/docs_and_notebooks_check.py for the update and normalize subcommands. The updated messages document that --targets accepts exact files, directories, and glob patterns (with examples) and note that both '/' and '\\' path separators are accepted. This is a documentation-only change to improve user guidance; no functional behavior is altered.

…bCut/DeepLabCut into cy/docs-versioning-tweaks

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…m/DeepLabCut/DeepLabCut into cy/docs-versioning-tweaks"

This reverts commit 46fdb04, reversing
changes made to 6d3b1be.

Introduce TypedDict-based types for FileKind and TargetSpec (with TargetKind) and tighten type annotations across functions (compile_target_specs, target_spec_matches_path, target_matches). Replace PurePosixPath-based glob matching with fnmatch.fnmatchcase only to ensure consistent, shell-style pattern behavior across platforms and remove unused imports. Minor cleanups: import TypedDict and update variable type hints for better static checking and readability.

Add parameterized tests covering both markdown and notebook files to verify metadata sync behavior. test_metadata_sync_warning_populates_report_targets_and_command creates a file with an out-of-date embedded last_content_updated, commits a newer git date, and asserts the record gets a metadata_sync_needed warning, that metadata_sync_targets and metadata_sync_command are populated (and include the target and --set-content-date-from-git flag), and that the rendered markdown includes guidance. test_enforce_fails_when_metadata_sync_needed_is_configured asserts that when fail_if_metadata_sync_needed=True an out-of-sync file is reported as a policy violation. These tests ensure reporting and enforcement handle embedded vs git-derived content dates correctly.