more more more more more fixes

stuchain · stuchain · commit 3e40ab4505ff · 2026-03-09T23:24:32.000+02:00
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -40,7 +40,7 @@ Before opening a PR, ensure:
 - [ ] **Docs**: Updated for user-facing changes
 - [ ] **Lint**: `ruff check src/` passes
 - [ ] **Types**: `mypy src/ --ignore-missing-imports` passes (or known issues documented)
-- [ ] **Changelog**: Updated in `docs/release/changelog.md` for notable changes
+- [ ] **Changelog**: Updated in `docs/release/CHANGELOG.md` for notable changes
 
 ## Coding Standards
 
@@ -51,12 +51,18 @@ Before opening a PR, ensure:
 
 See [Coding Standards](https://github.com/stuchain/CuePoint/blob/main/docs/development/coding-standards.md).
 
+**Documentation:** [docs/README.md](https://github.com/stuchain/CuePoint/blob/main/docs/README.md) — single entry point for all docs.
+
 ## Contribution Flow
 
 1. Fork the repo
 2. Create a branch (`git checkout -b feature/your-feature`)
 3. Implement changes
 4. Run tests: `python scripts/run_tests.py --all`
-5. Open a PR with the checklist above## Documentation- **Start here**: [docs/README.md](https://github.com/stuchain/CuePoint/blob/main/docs/README.md)
+5. Open a PR with the checklist above
+
+## Documentation
+
+- **Start here**: [docs/README.md](https://github.com/stuchain/CuePoint/blob/main/docs/README.md)
 - **Architecture**: [docs/development/architecture.md](https://github.com/stuchain/CuePoint/blob/main/docs/development/architecture.md)
 - **Match rules**: [docs/development/match-rules-and-scoring.md](https://github.com/stuchain/CuePoint/blob/main/docs/development/match-rules-and-scoring.md)
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -11,7 +11,7 @@
 ## Docs
 
 - [ ] Docs updated for user-facing changes
-- [ ] Changelog updated in `docs/release/changelog.md` (if notable)
+- [ ] Changelog updated in `docs/release/CHANGELOG.md` (if notable)
 
 ## Checklist
 
diff --git a/.github/TECHNICAL_ANALYSIS.md b/.github/TECHNICAL_ANALYSIS.md
@@ -4,12 +4,12 @@ This document explains how CuePoint works under the hood. It is written for tech
 
 ## High-level architecture
 
-CuePoint is a shared core pipeline surfaced through two interfaces:
+CuePoint exposes **two tools** from the start screen:
 
-- **Core pipeline**: parsing, query generation, search, scoring, and export.
-- **Interfaces**: GUI and CLI both call the same services (`ProcessorService`).
+- **inKey** — Rekordbox playlist → Beatport metadata enrichment. Shared core pipeline (parsing, query generation, search, scoring, export) surfaced through GUI and CLI. Both call the same services (`ProcessorService`).
+- **inCrate** — Inventory from full Rekordbox collection, discovery (Beatport genre charts from library artists, new releases from labels), and Beatport playlist creation. Orchestration: `InventoryService`, `IncrateDiscoveryService`, and `src/cuepoint/incrate/` (inventory DB, discovery, playlist writer, enrichment).
 
-Primary orchestration happens in `src/cuepoint/services/processor_service.py`, which:
+Primary orchestration for **inKey** happens in `src/cuepoint/services/processor_service.py`, which:
 
 1. Normalizes track inputs.
 2. Generates search queries.
@@ -174,7 +174,7 @@ Settings are mapped from nested YAML into a flat `SETTINGS` dict and are read by
 
 **CLI**
 
-- Entry point in `main.py`, with CLI logic in `src/cuepoint/cli/cli_processor.py`.
+- Entry point: run from project root as `python main.py` (root `main.py` delegates to `src/main.py`). CLI logic in `src/cuepoint/cli/cli_processor.py`.
 - Accepts `--xml`, `--playlist`, `--out`, and other flags.
 - Writes outputs to the configured output directory.
 
diff --git a/.lycheeignore b/.lycheeignore
@@ -23,8 +23,12 @@ file://.*/docs/policy/telemetry\.md
 file://.*/docs/release/link
 file://.*/docs/security/Security_Incident_Response\.md
 file://.*/docs/operations/Release/
+# Exported Beatport API HTML (local asset paths from export, not repo paths)
+file:///S:/static/
+file:///S:/v4/
 
-# Beatport external URLs: timeout in CI or example/placeholder URLs that 404
+# Beatport external URLs: timeout in CI or example/placeholder URLs that 404/403
 https://accounts.beatport.com/developer/request-api-key
 https://beatport.com/track/x/1
 https://api.beatport.com/v4
+https://support.beatport.com/hc/en-us/articles/4414997837716-Terms-and-Conditions#api
diff --git a/README.md b/README.md
@@ -71,6 +71,7 @@
   <li><strong>Caching</strong>: request caching to speed up repeated runs</li>
   <li><strong>Audit logging</strong>: query and candidate logs for verification</li>
   <li><strong>GUI + CLI</strong>: run via desktop UI or command line</li>
+  <li><strong>inCrate</strong>: inventory from Rekordbox, discover Beatport genre charts and new releases from labels, build a Beatport playlist</li>
 </ul>
 
 <h2>How to run</h2>
diff --git a/docs/README.md b/docs/README.md
@@ -41,6 +41,8 @@ For contributors: setup, architecture, extending the codebase.
 | [Common Dev Errors](development/common-errors.md) | Dev environment troubleshooting |
 | [Coding Standards](development/coding-standards.md) | Formatting, linting, typing |
 | [Remediation notes](development/remediation-notes.md) | Archive of one-off fix notes |
+| [Feature designs (inCrate)](feature/README.md) | inCrate: inventory, discovery, Beatport playlists — spec and implementation order |
+| [inCrate spec](incrate-spec.md) | inCrate requirements and decisions |
 
 ---
 
@@ -74,4 +76,4 @@ Release and ops docs (checklists, runbooks, changelog policy, signing guides): [
 
 ---
 
-*Last updated: 2026-02-03*
+*Last updated: 2026-03-09*
diff --git a/docs/development/architecture.md b/docs/development/architecture.md
@@ -60,10 +60,11 @@ Input (Rekordbox XML) → Parse → Query Generation → Search → Match/Score
 
 ## Code Reading Guide
 
-1. Start at `src/main.py` (CLI) or `src/gui_app.py` (GUI)
-2. Follow `CLIProcessor` or GUI controller into `ProcessorService`
-3. Trace `ProcessorService.process_track()` → `MatcherService.find_best_match()` → `core/matcher.best_beatport_match()`
-4. For Beatport data flow: `beatport_service.fetch_track_data()` → `data/beatport.parse_track_page()`
+1. **Entry points**: CLI is run from **project root** as `python main.py` (root `main.py` delegates to `src/main.py`). GUI: `src/gui_app.py` or `run_gui.bat` / `run_gui.command` / `run_gui.sh` from root.
+2. Start at `src/main.py` (CLI) or `src/gui_app.py` (GUI).
+3. Follow `CLIProcessor` or GUI controller into `ProcessorService`.
+4. Trace `ProcessorService.process_track()` → `MatcherService.find_best_match()` → `core/matcher.best_beatport_match()`.
+5. For Beatport data flow: `BeatportService` (in `services/beatport_service.py`) uses `data/beatport.py` and `data/beatport_search.py`; `beatport_service.fetch_track_data()` → `data/beatport.parse_track_page()`.
 
 ## Related Docs
 
diff --git a/docs/development/developer-setup.md b/docs/development/developer-setup.md
@@ -70,8 +70,8 @@ python scripts/run_tests.py --unit
 # Run all tests (unit, integration, system)
 python scripts/run_tests.py --all
 
-# Run CLI with sample XML
-python src/main.py --xml src/tests/fixtures/rekordbox/minimal.xml --playlist "Test Playlist" --out test
+# Run CLI with sample XML (from project root)
+python main.py --xml src/tests/fixtures/rekordbox/minimal.xml --playlist "Test Playlist" --out test
 
 # Run GUI
 python src/gui_app.py
diff --git a/docs/features/README.md b/docs/features/README.md
@@ -30,3 +30,4 @@ This folder documents **all** features of the CuePoint app—large and small. Ea
 | CLI | [cli-and-arguments.md](cli-and-arguments.md) | CLI processor, all arguments, migrate |
 | Reliability | [reliability-and-performance.md](reliability-and-performance.md) | Retry, circuit breaker, guardrails |
 | Support | [support-and-diagnostics.md](support-and-diagnostics.md) | Support bundle, log viewer, crash handler |
+| inCrate | [incrate.md](incrate.md) | Inventory, discovery (charts + new releases), Beatport playlist |
diff --git a/docs/features/incrate.md b/docs/features/incrate.md
@@ -0,0 +1,21 @@
+# inCrate
+
+inCrate is CuePoint’s second tool: a music-digging workflow that uses your Rekordbox collection to discover new music on Beatport and build a Beatport playlist.
+
+## What inCrate does
+
+1. **Inventory** — Build a queryable index from your full Rekordbox collection (artist, title, remix/version, label). Optionally enrich missing labels using the same Beatport matching flow as inKey.
+2. **Charts** — Discover Beatport genre charts published in the past month where the chart author is one of your library artists, and add whole charts to a playlist.
+3. **New releases** — For each label in your inventory, find releases from the last 30 days on Beatport and add them to the same playlist.
+4. **Beatport playlist** — Create or use a Beatport playlist per run (e.g. date-based name like `feb26` or `2025-02-26`) and add discovered tracks to it.
+
+## Where it lives in the app
+
+From the CuePoint start screen you can choose **inKey** (metadata enrichment) or **inCrate** (inventory and discovery). inCrate uses its own UI flow: inventory, discovery (charts + new releases), and playlist creation.
+
+## Implementation and design
+
+- **Requirements and decisions:** [inCrate spec](../incrate-spec.md)
+- **Implementation order and detailed design:** [Feature implementation designs (inCrate)](../feature/README.md) — phases 1–5 (inventory, Beatport API, discovery, playlist/auth, UI).
+
+Core code areas: `src/cuepoint/incrate/` (inventory, discovery, playlist writer, enrichment), `InventoryService`, `IncrateDiscoveryService`, Beatport API client and playlist auth as described in the spec and feature docs.
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -24,7 +24,7 @@
 
 ## System Requirements
 
-- **macOS**: 10.15 (Catalina) or later
+- **macOS**: macOS 12+ (Monterey or later)
 - **Windows**: Windows 10 or later
 - **Linux**: Modern Linux distribution with GTK support
 - **RAM**: 4GB minimum, 8GB recommended
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
@@ -2,6 +2,8 @@
 
 Get started with CuePoint in 5 minutes!
 
+Open CuePoint and choose **inKey** for Rekordbox metadata enrichment (or **inCrate** for inventory and Beatport discovery). This guide covers **inKey**.
+
 ## Step 1: Import Your Collection
 
 1. Open CuePoint
diff --git a/docs/guides/fix-pyside6-macos.md b/docs/guides/fix-pyside6-macos.md
@@ -124,7 +124,7 @@ python3 -c "from PySide6.QtWidgets import QApplication; print('✓ PySide6 OK')"
 ```bash
 python3 --version
 ```
-PySide6 requires Python 3.8+. If you have an older version, update Python.
+PySide6 requires Python 3.11+. If you have an older version, update Python.
 
 ### Check which Python pip is using:
 ```bash
diff --git a/docs/guides/install-macos.md b/docs/guides/install-macos.md
@@ -63,7 +63,7 @@ linked against **OpenSSL** (recommended for a proper, distributable app environm
 
 ## Prerequisites
 
-### Python 3.7 or later
+### Python 3.11 or later
 
 **Check if Python is installed:**
 ```bash
@@ -74,7 +74,7 @@ python3 --version
 
 #### Method 1: Official Python Installer
 1. Visit https://www.python.org/downloads/
-2. Download Python 3.x for macOS
+2. Download Python 3.11 or newer for macOS
 3. Run the installer
 4. Make sure to check "Add Python to PATH" during installation
 
@@ -145,10 +145,9 @@ After installation, you can run the GUI:
 ### Option 1: Double-click `run_gui.command`
 (Make it executable first: `chmod +x run_gui.command`)
 
-### Option 2: From Terminal
+### Option 2: From Terminal (from project root)
 ```bash
-cd src
-python3 gui_app.py
+python3 src/gui_app.py
 ```
 
 ### Option 3: Using the shell script
@@ -163,7 +162,7 @@ python3 gui_app.py
 - Make sure Python is in your PATH
 
 ### "pip3: command not found"
-- Python 3.4+ should include pip3
+- Python 3.11+ includes pip3
 - Try: `python3 -m ensurepip --upgrade`
 
 ### "Permission denied" errors
diff --git a/docs/how-to-run.md b/docs/how-to-run.md
@@ -10,15 +10,15 @@ Use one of the paths below depending on how you want to run CuePoint.
 
 ## Build locally
 
-1. Install Python 3.8+.
+1. Install Python 3.11+.
 2. Install dependencies:
 
 ```bash
 pip install -r requirements.txt
 playwright install chromium
 ```
 
-3. Run the CLI:
+3. Run the CLI (from project root):
 
 ```bash
 python main.py --xml collection.xml --playlist "My Playlist" --auto-research
diff --git a/docs/index.md b/docs/index.md
@@ -2,6 +2,8 @@
 
 **Start here:** [README.md](README.md) is the main documentation index (user docs, developer docs, release, compliance).
 
+CuePoint offers two tools: **inKey** (Beatport metadata enrichment for Rekordbox playlists) and **inCrate** (inventory from your collection, discover Beatport charts and new releases, build a Beatport playlist).
+
 Quick links:
 
 - [Getting started](getting-started/quick-start.md)
diff --git a/docs/policy/changelog-policy.md b/docs/policy/changelog-policy.md
@@ -4,7 +4,7 @@ How to update the changelog.
 
 ## Location
 
-`docs/release/changelog.md`
+`docs/release/CHANGELOG.md`
 
 ## Format
 
diff --git a/docs/release/CHANGELOG.md b/docs/release/CHANGELOG.md
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Step 10 implementation: Final Configuration & Release Readiness
 - Comprehensive Step 10 validation script
-- changelog.md for tracking all changes
+- CHANGELOG.md for tracking all changes
 
 ## [1.0.0] - 2024-12-14
 
diff --git a/docs/release/guides/release-communication-templates.md b/docs/release/guides/release-communication-templates.md
@@ -38,7 +38,7 @@ Templates for communicating releases to users and stakeholders.
 {Any special upgrade instructions}
 
 ### Full Changelog
-See [CHANGELOG.md](https://github.com/StuChain/CuePoint/blob/main/CHANGELOG.md) for complete list of changes.
+See [CHANGELOG.md](https://github.com/stuchain/CuePoint/blob/main/docs/release/CHANGELOG.md) for complete list of changes.
 
 ---
 
@@ -75,7 +75,7 @@ If you have CuePoint installed, the app will automatically check for updates on
 
 ## Feedback
 
-We'd love to hear your feedback! Please report any issues or suggestions on our [GitHub Issues](https://github.com/StuChain/CuePoint/issues) page.
+We'd love to hear your feedback! Please report any issues or suggestions on our [GitHub Issues](https://github.com/stuchain/CuePoint/issues) page.
 
 ---
 
diff --git a/docs/release/guides/step-10-manual-steps-guide.md b/docs/release/guides/step-10-manual-steps-guide.md
@@ -646,13 +646,13 @@ This guide provides detailed, step-by-step instructions for all manual steps in
      git push origin main
      ```
 
-3. **Update CHANGELOG.md**
-   - Edit `CHANGELOG.md`
+3. **Update docs/release/CHANGELOG.md**
+   - Edit `docs/release/CHANGELOG.md`
    - Move items from `[Unreleased]` to `[1.0.0]`
    - Add release date
    - Commit:
      ```bash
-     git add CHANGELOG.md
+     git add docs/release/CHANGELOG.md
      git commit -m "Update CHANGELOG for v1.0.0"
      git push origin main
      ```
diff --git a/docs/release/guides/step-10-no-signing-guide.md b/docs/release/guides/step-10-no-signing-guide.md
@@ -201,7 +201,7 @@ python scripts/check_performance.py
 - Verify these files exist:
   - ✅ README.md
   - ✅ PRIVACY_NOTICE.md
-  - ✅ CHANGELOG.md
+  - ✅ docs/release/CHANGELOG.md
   - ✅ THIRD_PARTY_LICENSES.txt
 
 ---
@@ -236,8 +236,8 @@ python scripts/check_performance.py
 **Status**: Already created (automated)
 
 **What you do**:
-- Verify CHANGELOG.md exists and is updated
-- Run: `python scripts/validate_release_notes.py --file CHANGELOG.md`
+- Verify docs/release/CHANGELOG.md exists and is updated
+- Run: `python scripts/validate_release_notes.py --file docs/release/CHANGELOG.md`
 
 **Expected**: Validation passes
 
@@ -318,12 +318,12 @@ python scripts/check_performance.py
      git push origin main
      ```
 
-3. **Update CHANGELOG.md**:
+3. **Update docs/release/CHANGELOG.md**:
    - Move items from `[Unreleased]` to `[1.0.0]`
    - Add release date: `## [1.0.0] - 2024-12-16`
    - Commit:
      ```bash
-     git add CHANGELOG.md
+     git add docs/release/CHANGELOG.md
      git commit -m "Update CHANGELOG for v1.0.0"
      git push origin main
      ```
diff --git a/docs/release/ops-index.md b/docs/release/ops-index.md
@@ -44,7 +44,7 @@ This index links to all operational documentation for CuePoint post-launch suppo
 | --- | --- |
 | [Release Strategy](release-strategy.md) | Release types and cadence |
 | [Release Schedule](release-schedule.md) | Planned release dates |
-| [Changelog](changelog.md) | Version history |
+| [Changelog](CHANGELOG.md) | Version history |
 | [Release Notes Template](release-notes-template.md) | Template for release notes |
 | [Release Announcement Template](release-announcement-template.md) | Template for announcements |
 
diff --git a/docs/release/release-deployment-runbook.md b/docs/release/release-deployment-runbook.md
@@ -26,7 +26,7 @@ This runbook provides step-by-step instructions for deploying a CuePoint release
 
 ### 1. Prepare Release Notes
 
-- Update `docs/release/changelog.md` with all changes
+- Update `docs/release/CHANGELOG.md` with all changes
 - Use [Release Notes Template](release-notes-template.md)
 - Include: highlights, fixes, known issues
 
diff --git a/docs/release/release-notes-template.md b/docs/release/release-notes-template.md
@@ -57,7 +57,7 @@ Thank you to all contributors who made this release possible:
 
 ## Full Changelog
 
-For a complete list of changes, see the [changelog](changelog.md).
+For a complete list of changes, see the [changelog](CHANGELOG.md).
 
 ## Download
 
diff --git a/docs/release/release-schedule.md b/docs/release/release-schedule.md
@@ -4,6 +4,8 @@
 
 This document outlines the planned release schedule for CuePoint. The schedule is subject to change based on development progress, critical issues, and user feedback.
 
+For the current release plan and dates, see [Release Strategy](release-strategy.md) and [GitHub Releases](https://github.com/stuchain/CuePoint/releases). The 2025 schedule below is kept for reference; 2026 schedule TBD.
+
 ## 2025 Release Schedule
 
 ### Q1 2025
@@ -271,7 +273,7 @@ The release schedule may be adjusted based on:
 - [Release Strategy](release-strategy.md)
 - [Release Deployment Runbook](release-deployment-runbook.md)
 - [Rollback](rollback.md)
-- [Changelog](changelog.md)
+- [Changelog](CHANGELOG.md)
 
 ## Last Updated
 
diff --git a/docs/release/release-strategy.md b/docs/release/release-strategy.md
@@ -221,7 +221,7 @@ CuePoint follows [Semantic Versioning](https://semver.org) (SemVer):
 - [Release Schedule](release-schedule.md)
 - [Release Deployment Runbook](release-deployment-runbook.md)
 - [Rollback](rollback.md)
-- [Changelog](changelog.md)
+- [Changelog](CHANGELOG.md)
 
 ## Last Updated
 
diff --git a/docs/release/rollback.md b/docs/release/rollback.md
@@ -42,7 +42,7 @@ When a release is broken (critical bug, security issue, or failed installs), fol
 - [ ] Create hotfix branch from the **last good** release tag (e.g. `git checkout -b hotfix/1.2.4 v1.2.3`).
 - [ ] Apply the minimal fix; run tests.
 - [ ] Bump version (e.g. to `1.2.4`) in `src/cuepoint/version.py` and sync (e.g. `scripts/sync_version.py`).
-- [ ] Update `docs/release/changelog.md` with the fix and version.
+- [ ] Update `docs/release/CHANGELOG.md` with the fix and version.
 - [ ] Create and push tag (e.g. `v1.2.4`).
 - [ ] Let CI build, sign, and run release workflow.
 - [ ] After release is published, regenerate appcast so the new version is the latest entry.
diff --git a/docs/user-guide/features.md b/docs/user-guide/features.md
