Introduce a GitHub Actions workflow to scan docs and notebooks for staleness. The workflow runs on push and PRs to main, checks out full git history, uses Python 3.12, installs pydantic and pyyaml, and runs a read-only staleness report and an optional policy check using .github/tools/docs_and_notebooks_check.py with tools/staleness_config.yml. Results (JSON/MD) are uploaded as the staleness-report artifact. Workflow is limited to content read permissions and has a 10-minute timeout.

Rename OUTPUT_FILENAME from 'nb_docs_status' to 'docs_nb_checks' and use it for the default --out-dir (tmp/docs_nb_checks). Update the README to show the check command as a fenced code block and clarify allowlist behavior. Update .gitignore to ignore the new tmp/docs_nb_checks path.

Ensure DLC metadata is JSON-serializable by converting date/datetime fields to ISO strings and preserving exclude_none behavior. Uses pydantic v2 API (model_dump(mode="json", exclude_none=True)) and falls back to pydantic v1 via json.loads(meta.json(...)). Adds a docstring and clarifying comments. This prevents json.dumps from failing when writing .ipynb files and keeps compatibility across pydantic versions.

Update docs-and-notebooks tool to use nbformat for reading/writing notebooks, validate .ipynb files, and detect whether notebooks are normalized. Add notebook_is_normalized helper and ensure write_ipynb_meta uses nbformat.writes/validate. Introduce a new policy field require_notebook_normalized (and add it to the report config defaults) and enforce it to emit violations when notebooks are not normalized. Also update CI job to install nbformat and pin pydantic, and update the script header notes to list the new dependency. These changes let CI detect invalid or non-normalized notebooks and reduce formatting churn when normalizing files.

Add a local pre-commit hook 'dlc-docs-notebooks-check' that runs .github/tools/docs_and_notebooks_check.py to check DLC docs and notebooks for staleness, validate nbformat, and perform normalization. The hook targets Jupyter and Markdown files, passes filenames to the script, and declares additional dependencies (pydantic>=2,<3, pyyaml, nbformat>=5).

Update references and examples in .github/tools/docs_and_notebooks_tool_README.md: change config reference to .github/tools/docs_and_notebooks_report_config.yml, update report output paths to tmp/docs_nb_checks/..., simplify the example 'check' command, and replace usages of tools/staleness.py with .github/tools/docs_and_notebooks_check.py in the update/example commands. Also tidy the 'Writes' section formatting.

Only set last_metadata_updated when an actual file write will occur (not unconditionally). For notebooks and markdown files the metadata stamping and merge now happen only when write is performed; when not writing, the in-memory record.meta is still updated so warnings and reports remain accurate. Rename the summary/report field and related text from "git_stale" to "content_stale" and adjust wording from "last_git_updated" to "last_git_touched / last_content_updated". A new import (from curses import meta) was also added.

Build the desired metadata without mutating last_metadata_updated and use a base "desired_base" when comparing/merging. Only set meta.last_metadata_updated (and produce the final merged metadata) if an actual file write will occur. Apply the same logic to both notebooks and markdown frontmatter, simplify variable names, and remove redundant in-branch rec.meta assignments so the record is consistently updated once at the end.

Drop an unused/errant `from curses import meta` import and remove a redundant pre-metadata call to `write_ipynb_meta`. Notebooks are now written once after merging/updating DLC metadata (comment updated accordingly), reducing unnecessary I/O and avoiding potential name conflicts.

Pass an explicit "HEAD" ref to git log calls and add --fixed-strings to the grep invocation. This prevents Git from misinterpreting the path or commit selector ordering and ensures the META_COMMIT_MARKER is treated as a literal string (not a regex). Changes applied to git_last_touched and git_last_content_updated to make commit/date lookups more robust.

Add a reusable _git_log_date helper to build git log args and return parsed dates, and make git_last_touched delegate to it. Improve _parse_git_iso_date to handle plain ISO dates and trailing Z timezone markers. Update git_last_content_updated to call the new helper with grep/invert-grep args to skip META_COMMIT_MARKER and fall back to raw last-touched date when needed.

Clarify README language around metadata commits and notebook normalization: explicitly note git correctly reports rewritten files as “updated now”, require ack flag text capitalization, add a warning about future changes to the metadata-commit marker, rephrase allowlists line to indicate they are currently empty, promote the notebook note to IMPORTANT and reword for clarity, and make minor troubleshooting wording/capitalization tweaks.

Enforce pydantic v2 APIs and tighten frontmatter parsing/validation and error reporting. Changes include:

- Require pydantic>=2 and nbformat>=5 in docs.
- read_md_frontmatter now returns an optional error string and reports unterminated or non-mapping frontmatter.
- Propagate frontmatter parse errors into scan/update flows (mark invalid_metadata and add explicit error codes).
- read_ipynb_meta returns the raw DLC metadata and preserves presence flag; notebook metadata handling clarified.
- Use model_dump(mode='json') / model_validate everywhere (remove pydantic v1 fallbacks).
- Simplify meta_to_jsonable to assume pydantic v2 output.
- Add future-date validation for last_content_updated/last_metadata_updated/last_verified and report errors.
- Improve enforcement logic to treat invalid metadata separately from missing metadata and to avoid false passes.
- Fail-safe handling in update mode when frontmatter is invalid; adjust report header and JSON output path writing.
- Minor whitespace/cleanup and reordering of strict_mode evaluation.

Overall this makes metadata parsing more strict, yields clearer diagnostics for frontmatter issues, and migrates code paths to pydantic v2.

Adapt tests to recent API changes: replace SUGGESTED_META_COMMIT_MESSAGE with SUGGESTED_TAGGED_COMMIT, and update calls to read_md_frontmatter to unpack a third return value (fm, body, _). Keeps tests aligned with the tool's renamed constant and modified function signature.

…b-report