fix(docs): gate GitHub Pages deployment

[konard]

Fixes #26

Summary

• Keeps the Docs workflow building Sphinx docs on pushes and pull requests.
• Gates configure-pages, upload-pages-artifact, and deploy-pages on vars.DEPLOY_GITHUB_PAGES == 'true'.
• Adds a notice-only skip step on push to main when Pages deployment has not been opted in.
• Documents the required Pages source setting and DEPLOY_GITHUB_PAGES=true repository variable.
• Adds workflow regression coverage and a changelog fragment.

Reproduction

Before the workflow fix, python -m pytest tests/test_workflows.py::test_docs_workflow_deploys_pages_only_when_opted_in -q failed because the docs workflow had no skip step and deployed Pages on every push to main.

Verification

• python -m pytest tests/test_workflows.py::test_docs_workflow_deploys_pages_only_when_opted_in -q
• python -m pytest tests/test_workflows.py -q
• python -m pytest
• ruff check .
• ruff format --check .
• mypy src/ (passes with existing local warnings about Python 3.9 config support and deprecated --strict-concatenate under Python 3.14)
• python scripts/check_file_size.py
• git diff --check
• PyYAML parse of .github/workflows/docs.yml

[konard]

Working session summary

Implemented and pushed the fix to PR #30: #30

Changed:

• Gated GitHub Pages configure/upload/deploy in docs.yml behind vars.DEPLOY_GITHUB_PAGES == 'true'.
• Added a notice-only skip step for main pushes when deployment is not opted in.
• Updated README setup docs and added a changelog fragment.
• Added regression coverage in tests/test_workflows.py.
• Removed the auto-generated .gitkeep placeholder from the PR diff.

Verified locally:

• python -m pytest
• ruff check .
• ruff format --check .
• mypy src/
• python scripts/check_file_size.py
• git diff --check
• PyYAML parse of .github/workflows/docs.yml

PR #30 is marked ready for review. Latest GitHub runs for commit ddc0b6f passed: Docs 28671934909, CI/CD Pipeline 28671934893. Working tree is clean.

---

This summary was automatically extracted from the AI working session output.

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Model: GPT-5.5
• Provider: OpenAI
• Public pricing estimate: $3.202647

📊 Context and tokens usage:

• 101.9K / 200K (51%) input tokens, 15.7K / 128K (12%) output tokens

Total: (101.9K + 1.5M cached) input tokens, 15.7K output tokens, $3.202647 cost

🤖 Models used:

• Tool: OpenAI Codex
• Requested: gpt-5.5
• Thinking level: max (~31999 tokens)
• Model: GPT-5.5 (gpt-5.5)

📎 Log file uploaded as Gist (1409KB)

• View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

🎉 Auto-merged

This pull request has been automatically merged by hive-mind.

• All CI checks have passed

---

Auto-merged by hive-mind with --auto-merge flag