v5.1.0

5.1.0 (2026-02-23)

Features

• commitcraft: add gitleaks GitHub Actions CI workflow setup (65f2596)
• commitcraft: multi-ecosystem support (#4) (96807f2)

v5.0.0

What's Changed

• Learn 8 code quality improvement patterns by @randynov in #2
• refactor(commitcraft): migrate to skill-based workflow architecture by @randynov in #3

New Contributors

• @randynov made their first contribution in #2

Full Changelog: v4.2.0...v5.0.0

v4.2.0 - SwiftHAL v2.1 with Staff-Level Refactoring

✨ Features

SwiftHAL v2.1

• Visual TUI with architecture insights: Risk distribution histogram, architecture hotspots grouped by directory, files needing attention, well-factored files, and comprehensive project health metrics
• Smart summary output: Default format shows high-risk and well-factored files with intelligent filtering (use --verbose for all files)
• ArgumentParser CLI: Professional declarative CLI with automatic --help generation, dual path support (--path flag + positional argument)
• Staff-level refactoring: Type-safe MetricKey enum with KeyPath mapping, RiskThresholds/DifficultyThresholds structs eliminating magic numbers, Swift naming conventions throughout

Summarizer

• Multi-model evaluation system: Corpus caching, LM Studio parser improvements, Patient Reported Outcome sample for evals
• Improved LLM consistency: Debug logging and better prompts

CommitCraft

• CHANGELOG automation: Automatic update on commits with conventional format parsing

🐛 Bug Fixes

SwiftHAL

• Fixed compiler warnings (unused variables)
• CI compatibility with Swift 5.9+ (lowered tools version from 6.2)
• Updated to macos-latest runner (resolves deprecation warning)

Summarizer

• Mail rule From filter for better targeting
• Multi-model eval support with LM Studio parser
• Handle None values in digest rendering

CommitCraft

• Working directory detection in Claude Code
• macOS compatibility and uninstall safety

📚 Documentation

SwiftHAL

• Complete Homebrew packaging guide (TODO-HOMEBREW.md)
• Updated README with v2.1 feature descriptions, positional args, --verbose behavior
• Marked swifthal-req.md as historical document

Summarizer

• Mail rule updates: use 'contains' + document IMAP seen flag bug

Project

• Backfilled CHANGELOG with missing commits

🔧 Other Changes

• Emoji-only tag format for Summarizer
• Relaxed validation and removed prompt examples in Summarizer
• Test file verification for CHANGELOG automation

---

SwiftHAL Binary Included:

• SwiftHAL (18MB) - Release binary for macOS (arm64)
• Compatible with macOS 13+ (Ventura and later)
• Install: cp SwiftHAL /usr/local/bin/hal

Installation:
See SwiftHAL README for full installation instructions.

v4.1.0 - M3U8 Video Downloader & CHANGELOG Automation

This release adds M3U8 video downloading capabilities and implements automated CHANGELOG maintenance.

What's New

• M3U8/HLS video stream downloader with parallel segment downloads and smart retry logic
• Complete CHANGELOG.md with all project history (backfilled 12 releases)
• Automated CHANGELOG maintenance - [Unreleased] section updates automatically with each commit

See CHANGELOG.md for complete details.

Full Changelog: v4.0.1...v4.1.0

v4.0.1 - Developer-First README

📚 Documentation

Restructure README for Developer-First Experience

Goal: Transform README from Summarizer-heavy documentation into a balanced, choose-your-own-adventure guide that helps curious developers succeed quickly.

Major improvements:

• Complexity indicators: 🟢 Easy (5 min) | 🟡 Medium (10 min) | 🔴 Advanced (30 min)
• "Pick Your Path" Quick Start: Three clear paths based on developer goals and time commitment
  • ExtensionAuditor: Instant gratification (zero deps, 30 seconds to CSV)
  • CommitCraft: Best for developers (one install, works everywhere)
  • Summarizer: Most powerful (full setup guide linked)
• Balanced tool coverage: All three tools get equal representation
• Philosophy section: Added Larry Wall's three great virtues with concrete examples
  • Laziness: Automate tedious tasks
  • Impatience: Get results immediately
  • Hubris: Build tools others want to use

Content streamlined:

• Removed 100+ lines of Summarizer-specific details (now in docs/SETUP.md)
• Condensed Testing section to show all three tools
• Condensed Development section (removed tool-specific details)
• Line count: 290 → 270 lines (7% reduction, 100% more useful)

Developer experience optimized:

1. Clone repo → Read README
2. See ExtensionAuditor is 🟢 5 minutes
3. Run python3 ExtensionAuditor/extension-auditor.py
4. Get CSV output in 30 seconds
5. Feel accomplished → Explore other tools ✓

Sections restructured:

• Tools: Added "Get started" quick commands for each tool
• Quick Start: Three progressive paths (easy/medium/advanced)
• Testing: Examples for all three tools (not just one)
• Development: Condensed, focuses on conventions not specifics
• Philosophy: NEW - explains virtues that influenced design

---

Files Changed

• README.md: 117 insertions, 136 deletions
  • Add complexity indicators and time estimates
  • Replace generic quick start with pick-your-path guide
  • Add Philosophy section with Larry Wall's virtues
  • Balance coverage across all three tools

---

Upgrade Notes

No breaking changes. README is now more helpful for new developers.

For existing users: No action needed. This is purely documentation improvement.

---

🤖 Generated with Claude Code

v4.0.0 - CommitCraft Architecture Simplification & Automated Releases

🚨 Breaking Changes

CommitCraft: Architecture simplified to 2-tier system

• Old workflow: Install globally → Run per-repo setup → Commands work
• New workflow: Install globally → Commands work everywhere immediately
• Removed:
  • commitcraft-init.sh - Per-repo installer no longer needed
  • post-checkout hook - No git hook-based discovery
  • Git template directory setup
  • Shell alias auto-configuration
• Impact: Existing users need to re-run ./commitcraft-install.sh to update. Local .claude/ directories are no longer used—commands reference ~/.claude/scripts/ directly.

---

✨ Features

CommitCraft: Add automated release command with semantic versioning

• New /commitcraft-release command for automated GitHub releases
• Auto-detects version bump from conventional commits (BREAKING CHANGE/feat/fix)
• Generates structured release notes with categorized sections
• Integrates with GitHub CLI (gh) for release publishing
• Includes commitcraft-release-analyze.sh for version analysis and validation
• Comprehensive user guide at docs/commitcraft-release.md (390 lines)

CommitCraft: Add development workflow enhancement toolkit

• New CommitCraft system for propagating Claude Code enhancements across repositories
• /commitcraft-push command for AI-assisted commits with security scanning
• Pre-commit analysis with secret detection, sync status, and large file warnings
• TUI installer with hash-based state detection and delta diffs
• Comprehensive documentation with setup guides and extension patterns

ExtensionAuditor: Add Chrome extension security scanner

• Cross-platform tool for analyzing installed browser extensions
• Hybrid approach: local manifests + web enrichment
• Generates CRXplorer-compatible CSV for security analysis
• Zero external dependencies (Python stdlib only)
• Professional output with progress tracking

---

📚 Documentation

CommitCraft Documentation Overhaul

• README.md: Rewrite for 2-tier architecture (-50% complexity, 337 lines)
• docs/commitcraft-release.md: Complete user guide with troubleshooting (390 lines)
• docs/commitcraft-push.md: Updated workflow without per-repo setup
• docs/adding-tools.md: Rewritten for global-only pattern (493 lines)
• Main README.md: Add strategy/goals section with contributing guidelines
• Update repository structure diagrams to reflect current files

---

🔧 Other Changes

CommitCraft: Installer improvements

• Remove git template directory setup (no longer used)
• Remove shell alias prompts (manual configuration via shell-aliases file)
• Fix obsolete script references (install-hooks.sh → commitcraft-install.sh)
• Keep cleanup logic for users upgrading from v3.x
• Update file counts: 2 scripts + 2 commands (previously showed 1 command)

---

📝 Upgrade Instructions

For CommitCraft Users (v3.x → v4.0.0)

Breaking change: Architecture simplified. Follow these steps:

1. Pull latest code:

   cd ~/Code/AppletScriptorium
   git pull

2. Re-run installer:

   cd CommitCraft
   ./commitcraft-install.sh

   This updates ~/.claude/ with new commands and removes obsolete hooks.

3. Clean up local directories (optional):

   # In any repo where you previously ran commitcraft-init
   rm -rf .claude/

   Local .claude/ directories are no longer used. Commands now reference ~/.claude/scripts/ directly.

4. Test commands:

   # Commands work immediately in any repository
   /commitcraft-push
   /commitcraft-release

What changed:

• ✗ No more per-repo setup required
• ✗ No git hooks for passive discovery
• ✓ Commands work in all repos after single global install
• ✓ Simpler, faster workflow

---

🎯 What's New in v4.0.0

Major improvements:

• Simpler setup: One install, works everywhere (no per-repo configuration)
• Automated releases: New /commitcraft-release command with semver detection
• Better docs: Strategy/goals, comprehensive guides, troubleshooting
• New tools: ExtensionAuditor for browser security scanning

Files changed: 12 files, 1,420 insertions, 678 deletions

Key additions:

• commitcraft-release-analyze.sh - Release version analysis script
• commitcraft-release.md - Automated release command
• docs/commitcraft-release.md - Release command user guide

Key deletions:

• commitcraft-init.sh - No longer needed (2-tier architecture)
• post-checkout - No longer needed (no git hooks)

---

🙏 Credits

All commits co-authored by Claude Code.

🤖 Generated with Claude Code

v3.1.0 - Interactive Python Selection & LLM-Based Insights

🚨 Breaking Changes

• Mail Rule Configuration: Users must re-run ./setup-mail-rule.sh to regenerate Mail rule script with new Python selection
  • Previous Mail scripts used dynamic which python3 detection (could select wrong Python)
  • New Mail scripts use user-selected Python path configured during setup
  • Action required: Run ./setup-mail-rule.sh to interactively select and configure Python installation

✨ Features

Interactive Python Selection with User-Friendly UI

• Problem fixed: ModuleNotFoundError when Mail rule auto-selected wrong Python installation (e.g., miniconda without dependencies)
• New setup experience:
  • Detects all Python installations (system, Homebrew, Miniconda, Anaconda)
  • Automatically verifies dependencies against Summarizer/requirements.txt
  • Groups display by status: ✓ Ready to use / ○ Needs setup / ⚠ Not recommended
  • Uses plain language names: "Miniconda Python 3.12" instead of /Users/you/miniconda/bin/python3
  • Detects PEP 668 restrictions on Python 3.14+ to prevent incompatible selections
  • Offers automated dependency installation via pip (with confirmation)
  • Option to install Python 3.11 via Homebrew when no suitable Python exists
  • Smart default selection: press Enter to use recommended ready-to-use Python

LLM-Based Cross-Article Insights

• Intelligent pattern detection: Replaced regex-based pattern matching with LLM analysis
  • Identifies emerging themes across articles
  • Detects methodological patterns and research approaches
  • Highlights knowledge gaps and underexplored areas
• Improved executive summary:
  • Better decimal preservation in sentence splitting (e.g., "11.2 months")
  • Increased word limit to 40 for complete findings
• Publisher metadata fallback: Articles without title sources now use publisher field from alert data

Bullet Validation with Retry

• Validates 4-bullet structure with required labels:
  • KEY FINDING, TACTICAL WIN [tag], MARKET SIGNAL [tag], CONCERN
• Retries once on validation failure (max 2 attempts per article)
• Ensures consistent summary format across all articles

🐛 Bug Fixes

Test Suite Alignment

• Fixed 9 test failures caused by recent code changes
• Updated mocks for content-type header checking (binary detection)
• Added topic parameter support in test fixtures
• Updated assertions to match 4-bullet validation requirements
• All 43 tests now passing

Documentation Accuracy

• Fixed dependencies: Added missing python-dotenv to requirements.txt
• Fixed SMTP env vars: Corrected help text to use SMTP_* (not GMAIL_*)
• Removed obsolete: Cleaned up Playwright references (not used in current codebase)
• Line endings: Added .gitattributes to enforce Unix LF for scripts

📚 Documentation

LM Studio Configuration

• Added clear LM Studio setup section to SETUP.md
• Documented Ollama as optional fallback (not required)
• Clarified configuration priority and backend fallback behavior
• Added LM Studio troubleshooting section

Mail Rule Setup

• Updated CLAUDE.md with new interactive Python selection process
• Documented PEP 668 detection and handling
• Added guidance for dependency installation

🔧 Changes Since v3.0.0

5 commits:

1. Interactive Python selection with user-friendly UI
2. Test suite fixes (9 → 0 failures)
3. Documentation cleanup (SMTP config notes)
4. Documentation alignment with code implementation
5. Digest formatting improvements and LLM-based insights

Files changed: 13 files, +567 insertions, -98 deletions

Key files:

• setup-mail-rule.sh - Complete rewrite of Python detection and selection
• Summarizer/templates/process-alert.scpt - Use {{PYTHON_PATH}} template variable
• digest_renderer.py - LLM-based cross-article insights
• summarizer.py - Bullet validation with retry logic
• config.py - Cross-article insights prompt, increased token limit
• CLAUDE.md, README.md, SETUP.md, TROUBLESHOOTING.md - Comprehensive updates

📝 Upgrade Instructions

For Existing Users

1. Re-run Mail rule setup (required):

   cd /path/to/AppletScriptorium
   git pull
   ./setup-mail-rule.sh

2. Select your Python installation:

   • Look for installations marked with ✓ (ready to use)
   • Press Enter to use the recommended option
   • Or select a different number if needed

3. Install missing dependencies if prompted:

   • Script will offer to auto-install via pip
   • Or install manually: python3 -m pip install --user -r Summarizer/requirements.txt

For New Users

Follow the standard setup in docs/SETUP.md - the new interactive Python selection will guide you through configuration automatically.

✅ Benefits

• Reliable Python detection: No more ModuleNotFoundError from wrong Python selection
• User-friendly setup: Non-technical users can easily select correct Python installation
• Smarter insights: LLM-based cross-article analysis replaces brittle regex patterns
• Better quality: Bullet validation ensures consistent summary structure
• Accurate docs: All documentation now matches actual implementation

v3.0.0 - Binary Content Support & Topic Threading

🚨 Breaking Changes

• Configuration: .env now uses standardized SMTP_* variable names instead of GMAIL_* prefixes
  • GMAIL_SMTP_USER → SMTP_USERNAME
  • GMAIL_APP_PASSWORD → SMTP_PASSWORD
  • GMAIL_SMTP_HOST → SMTP_HOST
  • GMAIL_SMTP_PORT → SMTP_PORT
  • Added: SMTP_FROM_EMAIL, ALERT_DIGEST_EMAIL
  • Action required: Update your .env file to use new variable names

🐛 Bug Fixes

Binary Content Handling

• Root cause: PDF and EPUB files were downloaded as binary and sent to LM Studio as malformed text, causing HTTP 400 errors
• Fix: Added Content-Type detection and URL transformation logic
  • PDF files: Strip .pdf extension to fetch HTML version
  • EPUB files: Strip /epub suffix to fetch HTML version
  • Fall back to Markdown extraction for remaining binaries
• Evidence:
  • PDF (cureus.com): 2.3MB binary → 236KB HTML ✓
  • EPUB (frontiersin.org): 1.8MB binary → 427KB HTML ✓

LM Studio Error Diagnostics

• Log prompt size (chars + estimated tokens) before each request
• Capture first 200 chars of HTTP error response body
• Include detailed error context in exception messages

✨ Features

Topic Threading

• Alert topic now flows through complete pipeline: AppleScript → CLI → Email
• Added --topic CLI parameter
• Email subject now includes topic: "Google Alert Intelligence: {topic} — {date}"
• Digest titles (HTML/text) display topic

Emoji Tags

• Tactical Win tags now have emoji indicators (matching Market Signal style):
  • [🚀 SHIP NOW] - Quick win available immediately
  • [🗺️ ROADMAP] - Requires planning/multi-step effort
  • [👀 WATCH] - Early signal, no action yet

Tag Normalization

• Added automatic tag formatting with case-insensitive regex
• Handles variations: [Urgent] → [🔴 URGENT], [ship now] → [🚀 SHIP NOW]
• Ensures consistent emoji formatting in all summaries

📚 Documentation

• Updated .env.template with standardized SMTP variables
• Added clear guidance for ALERT_DIGEST_EMAIL configuration
• Documented LM Studio as primary backend with optional Ollama fallback

🔧 Changes Since v2.3.1

Full changelog (7 commits):

• Binary content detection and HTML fallback
• Topic threading through complete pipeline
• Emoji indicators for Tactical Win tags
• Tag normalization for consistent formatting
• SMTP email delivery (replaced UI automation)
• Ollama health detection and auto-recovery
• Debug logging improvements

Files changed: 10 files, +442 insertions, -76 deletions

v2.3.2

Livin' off borrowed time, the clock ticks faster

v2.3.1 — Documentation Audit & Accuracy Fix

Overview

This release focuses on documentation accuracy and consistency. We've conducted a comprehensive audit of all user-facing documentation and corrected discrepancies between docs and the actual codebase implementation.

🔧 What's Fixed

Documentation Corrections

• Fixed npm package name: Corrected url-to-markdown-cli → url-to-markdown-cli-tool across all installation docs (SETUP.md, README.md)
• Added missing module references: Documented urltomd_fetcher.py, jina_fetcher.py, and markdown_cleanup.py in repository structure
• Documented run_workflow.sh: Added usage guide for the sequential workflow script as alternative to parallel CLI processing
• Removed dead references: Eliminated reference to non-existent PRD file

Architecture Documentation Updates

• Updated workflow diagram to reflect current url-to-md + Jina fallback strategy (replaced Playwright references)
• Updated deployment docs to reference url-to-md/Jina instead of Playwright for Cloudflare bypass
• Updated troubleshooting guide to reflect current tooling and dependencies

Code Cleanup

• Deleted obsolete test scripts referencing removed Playwright dependency:
  • scripts/debug-playwright-headed.py
  • scripts/test-jina-cli.sh
  • scripts/test-jina-feasibility.py
  • scripts/test-jina-real-articles.py
  • scripts/test-playwright-comparison.py

📋 Changes

Files Modified:

• CLAUDE.md
• README.md
• docs/SETUP.md
• docs/TROUBLESHOOTING.md
• docs/workflow-diagram.mmd
• AGENTS.md
• Summarizer/deploy/README.md

Files Deleted: 5 obsolete test scripts

✅ Benefits

• Accurate onboarding: Users get the correct npm package name on first install
• Complete module reference: Developers can now find all pipeline modules documented
• Current architecture: Documentation accurately reflects url-to-md + Jina fallback strategy (not Playwright)
• Reduced confusion: Removed dead PRD references and obsolete test scripts

📝 Notes for Users

• No code changes—documentation only
• Ensure you have url-to-markdown-cli-tool installed (not url-to-markdown-cli) for Cloudflare-protected sites
• run_workflow.sh is available as an alternative to python3 -m Summarizer.cli run for sequential processing