fix(ci): fix release automation — add version_toml, gate PyPI publish (#987)

* docs: add terminal output examples and success indicators to quick start

Enhanced the Quick Start section with:
- "What You'll See" sections showing example terminal output for each command
- Clear success indicators to help users verify things are working
- Structured subsections for Installation, Collect, Learn, and Evaluate

This addresses Phase 1 quick wins from documentation review (task a4441ff):
highest value improvements that help users know when things are working correctly.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* docs: fix stars rendering and add new feature documentation

Fix critical markdown rendering issue where "software **adapt**er" displayed
with literal stars instead of bold formatting. Update package documentation
with comprehensive coverage of new features: episode segmentation, recording
catalog, advanced search, and screenshot automation.

Changes:
- Fix: Remove nested bold formatting causing stars to render literally
- Add: Screenshot autogeneration script (450 lines, Playwright-based)
- Add: Episode segmentation documentation (ML package)
- Add: Recording catalog system documentation (viewer package)
- Add: Advanced search documentation (viewer package)
- Add: Component library reference (viewer package)
- Add: Comprehensive change summary (DOCS_UPDATE_SUMMARY.md)
- Update: Viewer documentation (+148% expansion, 136→336 lines)
- Update: ML documentation (+79% expansion, 155→277 lines)

Files modified:
- docs/index.md (fix stars issue)
- docs/design/landing-page-strategy.md (fix stars issue)
- docs/packages/viewer.md (add new features)
- docs/packages/ml.md (add episode segmentation)

Files created:
- docs/_scripts/generate_docs_screenshots.py (screenshot automation)
- docs/_scripts/README.md (script documentation)
- docs/DOCS_UPDATE_SUMMARY.md (comprehensive summary)

This addresses user-reported issues with documentation quality and ensures
all January 2026 features are properly documented with examples, schemas,
and usage patterns.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(ci): fix release automation — add version_toml config, gate PyPI publish

Two issues fixed:

1. Missing [tool.semantic_release] version_toml config — semantic-release
   created tags but never updated pyproject.toml, so poetry kept building
   v1.0.0 while tags were at v1.0.4.

2. Build step ran when no release was made — now gated on
   steps.release.outputs.released == 'true'.

- Add [tool.semantic_release] section with version_toml pointing to pyproject.toml
- Add id: release to PSR step so outputs are accessible
- Sync pyproject.toml version to 1.0.4 (matches latest tag)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: abrichr

.github/workflows/release-and-publish.yml

@@ -38,14 +38,15 @@ jobs:
 
       - name: Python Semantic Release
         if: steps.check_skip.outputs.skip != 'true'
+        id: release
         uses: python-semantic-release/python-semantic-release@v10.5.3
         with:
           github_token: ${{ secrets.ADMIN_TOKEN }}
           git_committer_name: "OpenAdapt Bot"
           git_committer_email: "bot@openadapt.ai"
 
       - name: Build and publish to PyPI
-        if: steps.check_skip.outputs.skip != 'true'
+        if: steps.check_skip.outputs.skip != 'true' && steps.release.outputs.released == 'true'
         env:
           PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
         run: |

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openadapt"
-version = "1.0.0"
+version = "1.0.4"
 description = "GUI automation with ML - record, train, deploy, evaluate"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -91,3 +91,13 @@ testpaths = ["tests"]
 filterwarnings = [
     "ignore::DeprecationWarning",
 ]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+commit_message = "{version}\n\nAutomatically generated by python-semantic-release"
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "refactor", "style", "test"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]