ci: add docs bundle build and publish workflow for frontend

[Andreas-Garcia]

Description

Adds infrastructure to build and publish a JSON docs bundle from this repo for consumption by the Audiometa frontend. The frontend uses the bundle at build time to render the /docs section (SEO/AEO). A demo web app is available at audiometa.themusictree.org.

Key changes:

• scripts/build_docs_bundle.py: Builds publish/docs-bundle.json from selected Markdown files in docs/ (see DOC_SLUGS), rewrites internal links to /docs/<slug>, and outputs a JSON object keyed by slug with title and content per doc.
• .github/workflows/publish-docs-bundle.yml: Runs the script and commits publish/docs-bundle.json when it changes. Triggers on: push to tags v*, pushes touching docs/** or scripts/build_docs_bundle.py, and workflow_dispatch.
• publish/README.md: Documents the bundle, rebuild steps (local and CI), and the demo URL.
• README.md: Adds a “Try it” line linking to the demo web app at audiometa.themusictree.org.

Related Issues

None.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring (no functional changes)
• Performance improvement
• Test addition/update
• CI/CD or infrastructure change

Pre-PR Checklist

Code Quality

• Removed commented-out code
• No hardcoded credentials, API keys, or secrets
• Ran pre-commit hooks: pre-commit run --all-files

Tests

• All tests pass: pytest
• Coverage meets threshold (≥85%): pytest --cov=audiometa --cov-report=term-missing --cov-fail-under=85
• New features have corresponding tests
• Bug fixes include regression tests

Documentation

• Updated docstrings for new functions/classes (only when needed)
• Updated README if adding new features or changing behavior
• Updated CONTRIBUTING.md if changing development workflow
• Added/updated type hints where appropriate

Git Hygiene

• Commit messages follow the commit message convention
• No merge conflicts with target branch
• Branch is up to date with target branch
• No accidental commits (large files, secrets, personal configs)

Breaking Changes

• This PR includes breaking changes
• Breaking changes are clearly documented below
• Migration path is provided (if applicable)

Breaking Changes Description

N/A

Testing Instructions

How to Test

1. From repo root, run python3 scripts/build_docs_bundle.py and confirm publish/docs-bundle.json is created/updated with entries for the docs in DOC_SLUGS.
2. Confirm internal .md links in bundle content are rewritten to /docs/<slug> (e.g. (METADATA_FORMATS.md) → (/docs/metadata-formats)).
3. Trigger the workflow manually (Actions → Publish docs bundle → Run workflow) or push a change under docs/ and verify the job runs and commits publish/docs-bundle.json only when the file changes.

Test Results

Additional Context

• The workflow uses contents: write so it can push the updated bundle back to the repo.
• Docs included in the bundle are defined in DOC_SLUGS in scripts/build_docs_bundle.py (e.g. METADATA_FORMATS.md, METADATA_FIELD_GUIDE.md, etc.).

Checklist for Reviewers

• Code follows project conventions and style
• Logic is sound and well-structured
• Error handling is appropriate
• CI tests pass on all platforms and Python versions
• Test coverage is adequate for the changes
• Public API changes are documented
• Breaking changes are clearly marked and documented
• All review comments are addressed
• No unresolved discussions