Add runnable guides and improve SEO checks

[AliMuhammadOfficial]

Pull Request

Summary

Improves the documentation’s usability, search visibility, AI discoverability, and version navigation.

Observable changes include:

• Adds complete, runnable examples throughout the core guides.
• Expands the CLI and public Python API reference.
• Normalizes page descriptions to 150–160 characters for search snippets.
• Enforces exactly one H1 heading per documentation page.
• Removes duplicate Open Graph and Twitter metadata.
• Adds regression coverage for SEO structure and the Mike version switcher.
• Confirms version navigation preserves the current page when possible and falls back safely when a page is unavailable.

Change type

• Bug fix
• Backward-compatible feature
• Breaking change
• Documentation
• Test or internal maintenance
• Security-sensitive change handled through a private advisory

Compatibility

No Python API, CLI, YAML/TOML, checkpoint, durable-run-data, provider, or tool protocol contracts are changed.

• Version impact: patch
• Deprecation or migration path: None required.
• Rollback or persisted-data impact: No persisted-data impact. Roll back by reverting the documentation commit or publishing a superseding patch release.

Verification

• Regression or behavior tests added or updated
• uv sync --locked --group dev
• uv run python scripts/check_versions.py
• uv run python -m pytest — 893 passed, 13 deselected
• uv run python -m ruff check .
• uv run python -m ruff format --check src/
• uv run python -m pyright — 0 errors and 0 warnings
• uv run python -m mkdocs build --strict
• uv run python scripts/check_docs.py — 403 exports and 40 examples verified
• git diff --check
• All newly added runnable Python examples passed syntax and import validation

Documentation and release notes

• Public docstrings and reference pages match the implementation
• Guides, examples, README, and site_docs/llms.txt reviewed and updated where needed
• [Unreleased] changelog entry added
• Security, configuration, and release documentation reviewed where needed

Reviewer notes

The documentation remains release-tag controlled:

• Pull requests and main validate documentation without replacing published versions.
• Only an immutable v* release tag deploys documentation.
• Stable releases update the X.Y documentation version and the latest alias.
• The deployment workflow runs mike set-default --push latest.
• The configured version switcher uses Mike with latest as the default alias.
• Existing /llms.txt, sitemap, robots metadata, canonical URLs, and version manifests were audited.
• Social-card rendering relies on Cairo libraries installed by GitHub Actions. The non-social strict documentation build passes locally on Windows.

This change does not authorize bypassing required checks, reviews, protected environments, or the release process.