steam-idle-bot 1.0.0__tar.gz

steam_idle_bot-1.0.0/.coveragerc

@@ -0,0 +1,10 @@
+[run]
+branch = True
+source = .
+omit =
+  venv/*
+  tests/*
+
+[report]
+skip_covered = True
+show_missing = True

steam_idle_bot-1.0.0/.env.example

@@ -0,0 +1,66 @@
+# Steam Idle Bot configuration via environment variables
+# Copy to .env and fill in your values. Do NOT commit the filled .env.
+
+# Required credentials
+USERNAME=your_steam_username
+PASSWORD=your_steam_password
+
+# Optional: Steam Web API key
+STEAM_API_KEY=
+
+# Optional: authenticated Steam browser cookies for community page scraping
+# Use JSON, for example:
+# STEAM_WEB_COOKIES={"steamLoginSecure":"...","sessionid":"...","steamCountry":"..."}
+STEAM_WEB_COOKIES={}
+
+# Game settings
+# Accepts JSON list (recommended) or CSV list
+GAME_APP_IDS=[570,730]
+FILTER_TRADING_CARDS=true
+FILTER_COMPLETED_CARD_DROPS=true
+EXCLUDE_APP_IDS=[]
+USE_OWNED_GAMES=true
+MAX_GAMES_TO_IDLE=30
+# Seconds between re-running the game-selection pipeline while idling (min 10)
+REFRESH_INTERVAL_SECONDS=600
+# Write a JSON/Markdown checkpoint every N minutes while idling (0 disables)
+CHECKPOINT_MINUTES=0
+# Stop idling after N minutes (0 runs until interrupted)
+DURATION_MINUTES=0
+# Re-scrape card counts this many seconds after stopping, to catch lagging badge updates (0 disables)
+POST_RUN_VERIFY_SECONDS=0
+
+# Idling backend
+# python: current steam.client backend
+# steam_utility: delegates idling to ../steam-utility-multiplataform (or STEAM_UTILITY_PATH)
+IDLING_BACKEND=python
+STEAM_UTILITY_PATH=
+
+# Logging
+LOG_LEVEL=INFO
+
+# Performance tuning
+API_TIMEOUT=10
+# Base delay (seconds) between Steam API calls. Auto-increases on HTTP 429.
+# Raise it (e.g. 2.0) for very large libraries to avoid throttling.
+RATE_LIMIT_DELAY=1.0
+
+# Trading-card cache
+ENABLE_CARD_CACHE=true
+CARD_CACHE_PATH=.cache/trading_cards.json
+CARD_CACHE_TTL_DAYS=30
+# No-drop cache: games confirmed without remaining card drops are skipped on
+# future runs (a finished game never regains drops). Gated by ENABLE_CARD_CACHE.
+DROP_CACHE_PATH=.cache/no_drop_cards.json
+DROP_CACHE_TTL_DAYS=90
+
+# Browser cookie recovery: if the configured STEAM_WEB_COOKIES are not a valid
+# community session (e.g. a store-only/expired token), pull fresh cookies from a
+# browser you're logged into Steam with. Set the browser or leave "auto".
+AUTO_BROWSER_COOKIES=true
+BROWSER_COOKIES_BROWSER=auto
+
+# Filtering controls
+# Optional: cap number of card checks; keep commented to disable
+# MAX_CHECKS=100
+SKIP_FAILURES=false

steam_idle_bot-1.0.0/.githooks/pre-commit

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Prevent committing local secrets or environment-specific files
+
+set -euo pipefail
+
+# Block committing config.py explicitly
+if git diff --cached --name-only | grep -qE '^config\.py$'; then
+  echo "Error: Refusing to commit config.py (contains secrets)." >&2
+  echo "Tip: Keep credentials in config.py (not tracked) or use env vars." >&2
+  exit 1
+fi
+
+# Basic sanity: prevent large accidentally added venv or cache
+if git diff --cached --name-only | grep -qE '(^|/)__pycache__/|(^|/)venv/|(^|/)\.vscode/'; then
+  echo "Warning: You are staging cache/venv/.vscode files. Please unstage them." >&2
+  echo "Run: git restore --staged <paths>" >&2
+  exit 1
+fi
+
+exit 0

steam_idle_bot-1.0.0/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github: bernardopg
+ko_fi: bernardopg
+buy_me_a_coffee: wctwom9emu

steam_idle_bot-1.0.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    allow:
+      - dependency-type: "all"

steam_idle_bot-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Principle of least privilege for GITHUB_TOKEN
+permissions:
+  contents: read
+
+# Cancel previous runs of the same ref to save minutes
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up UV
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache UV
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml', '**/uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint (ruff)
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Type-check (mypy)
+        run: uv run mypy src
+
+      - name: Install xvfb
+        run: sudo apt-get update && sudo apt-get install -y xvfb
+
+      - name: Run tests (pytest + coverage)
+        env:
+          # Minimal credentials for Settings model in tests when needed
+          USERNAME: test_user
+          PASSWORD: test_pass
+          DISPLAY: ":99"
+        run: |
+          Xvfb :99 -screen 0 1024x768x24 &
+          sleep 1
+          uv run pytest -q --cov=src/steam_idle_bot --cov-report=xml --cov-fail-under=85
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage-xml-${{ matrix.python-version }}
+          path: coverage.xml
+          retention-days: 7

steam_idle_bot-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,206 @@
+# Tag-triggered release: re-verifies the tagged commit, builds distributable
+# artifacts, and publishes a GitHub Release with notes pulled straight from
+# CHANGELOG.md. The maintainer prepares the release by hand (bump
+# pyproject.toml, move [Unreleased] to a dated version section — see
+# RELEASING.md) and pushes a `vX.Y.Z` tag; this workflow never mutates the
+# repo, it only validates and ships what was already committed.
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to (re-)release, e.g. v1.0.0"
+        required: true
+
+# Least privilege by default; only the publish job elevates to contents:write.
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # ---- Re-verify the tagged commit before shipping anything from it ----
+  verify:
+    name: Verify version & test suite
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
+
+      - name: Verify tag matches pyproject.toml version
+        id: version
+        run: |
+          set -euo pipefail
+          ref="${{ inputs.tag || github.ref_name }}"
+          tag_version="${ref#v}"
+          pyproject_version=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          if [ "$tag_version" != "$pyproject_version" ]; then
+            echo "::error::Tag $ref (version $tag_version) does not match pyproject.toml version $pyproject_version"
+            exit 1
+          fi
+          echo "version=$pyproject_version" >> "$GITHUB_OUTPUT"
+
+      - name: Set up UV
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint (ruff)
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Type-check (mypy)
+        run: uv run mypy src
+
+      - name: Install xvfb
+        run: sudo apt-get update && sudo apt-get install -y xvfb
+
+      - name: Run tests
+        env:
+          USERNAME: test_user
+          PASSWORD: test_pass
+          DISPLAY: ":99"
+        run: |
+          Xvfb :99 -screen 0 1024x768x24 &
+          sleep 1
+          uv run pytest -q --cov=src/steam_idle_bot --cov-fail-under=85
+
+  # ---- Build the artifacts attached to the release ----
+  build:
+    name: Build distribution artifacts
+    needs: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
+
+      - name: Set up UV
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+
+      - name: Build Python package (sdist + wheel)
+        run: uv build
+
+      - name: Set up Node
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Build frontend
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build
+
+      - name: Package frontend build
+        run: |
+          set -euo pipefail
+          version="${{ needs.verify.outputs.version }}"
+          mkdir -p web-dist
+          (cd frontend/dist && zip -rq "../../web-dist/steam-idle-bot-web-${version}.zip" .)
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: release-dist
+          # Kept in separate dirs so the PyPI publish job can point twine at
+          # dist/ alone — it chokes on non-package files like the zip.
+          path: |
+            dist/
+            web-dist/
+          retention-days: 7
+
+  # ---- Publish the GitHub Release with changelog-derived notes ----
+  publish:
+    name: Publish GitHub Release
+    needs: [verify, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-dist
+
+      - name: Extract changelog section
+        run: |
+          set -euo pipefail
+          version="${{ needs.verify.outputs.version }}"
+          awk -v ver="$version" '
+            /^## \[/ {
+              if (found) exit
+              if ($0 ~ "^## \\[" ver "\\]") { found = 1; next }
+              next
+            }
+            found { print }
+          ' CHANGELOG.md > /tmp/release_notes.md
+          if [ ! -s /tmp/release_notes.md ]; then
+            echo "::error::No CHANGELOG.md section found for [$version]. Move [Unreleased] to [$version] - <date> before tagging (see RELEASING.md)."
+            exit 1
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ inputs.tag || github.ref_name }}
+          name: "v${{ needs.verify.outputs.version }}"
+          body_path: /tmp/release_notes.md
+          prerelease: ${{ contains(needs.verify.outputs.version, '-') }}
+          files: |
+            dist/*
+            web-dist/*
+
+  # ---- Publish the wheel/sdist to PyPI via Trusted Publishing (OIDC, no ----
+  # ---- stored secrets). Independent of the GitHub Release job so a not- ----
+  # ---- yet-configured PyPI trusted publisher never blocks the release. ----
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [verify, build]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/steam-idle-bot/${{ needs.verify.outputs.version }}/
+    permissions:
+      id-token: write # required for OIDC trusted publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: release-dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # v1.14.1
+        with:
+          packages-dir: dist/

steam_idle_bot-1.0.0/.github/workflows/static.yml

@@ -0,0 +1,86 @@
+# Build and deploy the documentation site to GitHub Pages.
+name: Deploy docs to Pages
+
+on:
+  # On pushes to main, build AND deploy. On pull requests, only build (validation):
+  # the protected github-pages environment permits `main` only, so the deploy job
+  # is skipped on PRs while the build job still catches broken layouts/assets.
+  push:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - ".github/workflows/static.yml"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "docs/**"
+      - ".github/workflows/static.yml"
+  workflow_dispatch:
+
+# Least privilege: only the deploy job needs pages/id-token.
+permissions:
+  contents: read
+
+# One deployment at a time; let in-flight production deploys finish.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # ---- Build the static site and validate the output ----
+  build:
+    name: Build site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Build site with Jekyll
+        uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1.0.13
+        with:
+          source: ./docs
+          destination: ./_site
+
+      - name: Validate build output
+        run: |
+          set -euo pipefail
+          test -f ./_site/index.html || { echo "::error::index.html missing from build"; exit 1; }
+          for asset in banner.svg architecture.svg pipeline.svg css/style.css; do
+            test -f "./_site/assets/$asset" || { echo "::error::missing asset: $asset"; exit 1; }
+          done
+          pages=$(find ./_site -name '*.html' | wc -l)
+          size=$(du -sh ./_site | cut -f1)
+          {
+            echo "### 📄 Docs site built"
+            echo ""
+            echo "- **HTML pages:** $pages"
+            echo "- **Total size:** $size"
+            echo "- **Assets verified:** banner · architecture · pipeline · stylesheet"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: "./_site"
+
+  # ---- Deploy the built artifact to GitHub Pages (main only) ----
+  deploy:
+    name: Deploy to Pages
+    needs: build
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

steam_idle_bot-1.0.0/.gitignore

@@ -0,0 +1,29 @@
+config.py
+.env
+.cache/
+__pycache__/
+venv/
+.vscode/
+.claude/
+.venv/
+.mypy_cache/
+.serena/
+
+# Python build/cache
+*.pyc
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+logs/
+*.log
+*.log.*
+*.egg-info/
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+
+# Local AI tooling caches
+.headroom/
+.tokensave/

steam_idle_bot-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

steam_idle_bot-1.0.0/BACKLOG.md

@@ -0,0 +1,159 @@
+# 📋 Product Backlog & Roadmap
+
+Living, scrum-style backlog for **Steam Idle Bot**. Tracks shipped work, the prioritized
+queue, known defects, and risks. Source of truth for "what's next"; narrative history lives
+in [`CHANGELOG.md`](CHANGELOG.md).
+
+---
+
+## Legend
+
+| Field | Values |
+|-------|--------|
+| **Status** | ✅ Done · 🟡 In progress · ⬜ Todo · 🧊 Icebox |
+| **Type** | ✨ Feature · 🐛 Bug · 🧱 Tech-debt · 📚 Docs · 🔐 Security · 🧪 Test |
+| **Impact** | 🟥 High · 🟧 Medium · 🟩 Low (user/operational value) |
+| **Effort** | `S` ≤½ day · `M` 1–3 days · `L` > 3 days |
+| **Priority** | `P0` now · `P1` next · `P2` soon · `P3` later — derived from impact ÷ effort |
+
+**Definition of Done:** code + tests green (`ruff` · `mypy` · `pytest` across 3.12–3.14),
+docs/CHANGELOG updated, no committed secrets/artifacts, reviewed & merged to `main`.
+
+**Cadence:** ~1-week sprints. Each closed sprint ships as a PR; backlog re-groomed at close.
+
+---
+
+## ✅ Shipped (sprints 1–5)
+
+> Delivered in PRs [#30](https://github.com/bernardopg/steam-idler-python/pull/30)–[#34](https://github.com/bernardopg/steam-idler-python/pull/34). Test suite grew 204 → 242.
+
+### Sprint 1 — Audit & hardening · PR #30
+- [x] 🐛 🟥 Rotate the log file (`RotatingFileHandler`, 10 MB × 3) — fixes unbounded 1 GB log growth
+- [x] 🐛 🟥 Live idle/session duration in the panel (was frozen at `0 min`)
+- [x] ✨ 🟧 Configurable `--refresh-interval-seconds` / `REFRESH_INTERVAL_SECONDS`
+- [x] 🐛 🟧 Tolerate malformed Steam `appdetails` payloads (e.g. app `2321720`)
+- [x] 📚 🟥 Correct inverted `eventemitter` dependency note in `CLAUDE.md`
+
+### Sprint 2 — Graceful shutdown · PR #31
+- [x] 🐛 🟥 `SIGINT`/`SIGTERM` graceful stop that still emits the session report
+
+### Sprint 3 — Privacy · PR #32
+- [x] 🔐 🟧 Consistent account-name redaction across both backends (`utils.redaction`)
+
+### Sprint 4 — Follow-ups · PR #33
+- [x] ✨ 🟧 Preflight warnings (Steam not running / no graphical session) for `steam_utility`
+- [x] 🐛 🟧 Backfill drained final card counts to `0` in the session report
+- [x] ✨ 🟧 steam-utility idle reconciliation (reuse / dedup / report via `/proc`)
+
+### Sprint 5 — Backlog close-out · PR #34
+- [x] ✨ 🟧 Checkpoint report mode (`--checkpoint-minutes` → JSON + Markdown) + `--duration-minutes`
+- [x] ✨ 🟩 Delayed post-run verification (`--post-run-verify-seconds`)
+- [x] ✨ 🟩 `--stop-app-ids` maintenance mode
+- [x] 🧪 🟧 run.sh signal-forwarding integration tests
+- [x] 📚 🟩 Document expected empty Badge-API card-drop responses
+
+### Sprint 6 — Full audit (2026-07-03)
+- [x] 🐛 🟥 Terminal color was silently disabled under `run.sh` (FIFO ≠ TTY → rich dropped ANSI). Fixed via `FORCE_COLOR=1` + ANSI-stripped run log
+- [x] ✨ 🟧 A2: exponential backoff + jitter on reconnect storms (10s → 5 min cap, reset on success)
+- [x] ✨ 🟩 Status panel reprinted every refresh so idle-time columns stay live
+- [x] 🧪 🟧 G1: CI coverage floor (`--cov-fail-under=85`; suite currently at 90%)
+- [x] 🧪 🟧 G2: `pytest-timeout` (120s, thread method — signal timeouts don't fire in gevent)
+- [x] 🧱 🟩 G3: `ruff check` + `ruff format --check` + `mypy` as CI gates (CI previously ran *only* pytest)
+- [x] ✨ 🟥 F1 groundwork: hatchling build system, `steam-idle-bot` entry point, full PyPI metadata
+- [x] 🧱 🟧 Bounded `DetailedLogger` outputs (last 500 append entries; 50 filtering snapshots)
+
+### Sprint 7 — Web UI (2026-07-03)
+- [x] ✨ 🟥 FastAPI + React web UI (`--web` / `run-web.sh`): live WebSocket dashboard, full settings
+      editor (.env persist, masked password), streamed logs, session report, Steam Guard dialog.
+      Emerald/dark-green minimalist theme. React 19 + Vite 8 + TS 6 + Tailwind 4; deps at latest.
+- [x] 🧪 🟧 20 backend tests (`test_webapi.py`) incl. React-form ⇄ `Settings` parity check
+
+---
+
+## 🎯 Product backlog (prioritized)
+
+### EPIC A — Reliability & resilience
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| A1 | 🧪 | Raise coverage on `client.py` (79%), `inventory.py` (80%), `games.py` (83%) | 🟧 | M | P2 | ⬜ |
+| A2 | ✨ | Exponential backoff + jitter on reconnect storms | 🟧 | S | — | ✅ |
+| A3 | 🧱 | Structured health metrics (uptime, reconnects, drops/hr) exposed to the panel | 🟩 | M | P3 | ⬜ |
+| A4 | 🐛 | Detect & recover from a silently-killed steam-utility child mid-session | 🟧 | M | P2 | ⬜ |
+
+### EPIC B — Card-drop accuracy
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| B1 | ✨ | Honor Steam's weekly 3-drop / playtime gate in the planner | 🟥 | L | P1 | ⬜ |
+| B2 | ✨ | Cross-check badge-API vs scraper counts; warn on divergence | 🟧 | M | P2 | ⬜ |
+| B3 | 🧱 | Cache TTL auto-tuning from observed drop cadence | 🟩 | M | P3 | 🧊 |
+
+### EPIC C — Backends & idling
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| C1 | ✨ | Multi-account / account-rotation support | 🟥 | L | P2 | 🧊 |
+| C2 | ✨ | Windows-native steam-utility process detection (no `/proc`) | 🟧 | M | P2 | ⬜ |
+| C3 | 🧱 | Formalize the backend `Protocol` and add a conformance test suite | 🟧 | S | P1 | ⬜ |
+
+### EPIC D — UX (terminal & GUI)
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| D1 | 🧱 | Split `gui.py` (1 359 lines, 93% covered) into view/controller modules | 🟧 | M | P2 | ⬜ |
+| D2 | ✨ | Live in-place terminal panel via `rich.live.Live` writing to `/dev/tty` (survives the run.sh FIFO redirect; falls back to periodic reprint when no TTY) | 🟩 | M | P3 | ⬜ |
+| D3 | ✨ | GUI: per-game drop progress bars + ETA | 🟩 | M | P3 | 🧊 |
+| D4 | 🧱 | Default `LOG_FILE` (`steam_card_idler.log`) should live under `logs/`, not the repo root | 🟩 | S | P2 | ⬜ |
+
+### EPIC E — Observability & reporting
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| E1 | ✨ | HTML/Markdown session summary with charts | 🟩 | M | P3 | ⬜ |
+| E2 | ✨ | Prometheus/JSON metrics endpoint for long-running hosts | 🟩 | M | P3 | 🧊 |
+
+### EPIC F — Packaging & distribution
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| F1 | ✨ | Publish to PyPI (`pipx install steam-idle-bot`) — packaging metadata + entry point shipped in Sprint 6; remaining: release workflow + first upload | 🟥 | S | P1 | 🟡 |
+| F2 | ✨ | Official Docker image + compose for headless 24/7 idling | 🟧 | M | P2 | ⬜ |
+| F3 | 📚 | Release automation (tagged builds, changelog extraction) | 🟧 | S | P2 | ⬜ |
+
+### EPIC G — Quality & testing
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| G1 | 🧪 | Enforce a coverage floor in CI (`--cov-fail-under=85`) | 🟧 | S | — | ✅ |
+| G2 | 🧪 | Add `pytest-timeout` to kill hung tests deterministically | 🟧 | S | — | ✅ |
+| G3 | 🧱 | `ruff check` + `ruff format --check` + `mypy` as CI gates | 🟩 | S | — | ✅ |
+
+### EPIC H — Security & privacy
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| H1 | 🔐 | Optional OS-keyring credential storage (drop plaintext `.env`) | 🟥 | M | P1 | ⬜ |
+| H2 | 🔐 | Redact steam_id/cookies/tokens in `DetailedLogger` JSON dumps (growth caps shipped in Sprint 6; redaction still open) | 🟧 | S | P1 | ⬜ |
+| H3 | 🔐 | Document & track the accepted `protobuf<4` advisory exceptions | 🟩 | S | P2 | ✅ |
+
+### EPIC I — Documentation
+| ID | Type | Item | Impact | Effort | Priority | Status |
+|----|------|------|:------:|:------:|:--------:|:------:|
+| I1 | 📚 | Architecture deep-dive page linked from the README diagrams | 🟧 | S | P2 | ⬜ |
+| I2 | 📚 | Troubleshooting matrix (auth failures, 429s, no drops) | 🟧 | S | P1 | ⬜ |
+| I3 | 📚 | Animated demo (asciinema/GIF) in the README | 🟩 | S | P3 | ⬜ |
+
+---
+
+## 🐛 Known defects / risks
+
+| ID | Severity | Description | Mitigation | Status |
+|----|:--------:|-------------|-----------|:------:|
+| R1 | 🟧 | steam-utility reconciliation is Linux-only (`/proc`) | No-op elsewhere; tracked as C2 | ⬜ |
+| R2 | 🟩 | `protobuf<4` pin blocks GHSA-8qvm-5x2c-j2w7 / GHSA-7gcm-g887-7qv7 | Accepted: only trusted Steam data deserialized | ✅ |
+| R3 | 🟧 | Card-drop scraping depends on a short-lived community cookie | Auto browser-cookie recovery; session verify | ✅ |
+| R4 | 🟩 | ~~GUI is largely untested~~ GUI now at 93% coverage (171 tests); remaining risk is the 1 359-line monolith | Tracked as D1 | ✅ |
+| R5 | 🟩 | `logs/` accumulates per-run artifacts (`runs/`, checkpoints, reports) with no retention policy beyond DetailedLogger caps | Periodic manual cleanup; candidate for a small janitor on startup | ⬜ |
+
+---
+
+## 📌 Next sprint candidate (groomed 2026-07-03)
+
+Top of queue by impact ÷ effort: **F1 finish** (release workflow + first PyPI upload),
+**C3** (backend conformance tests — `protocol.py` already exists, only the suite is missing),
+**H2** (redact logger dumps), **I2** (troubleshooting matrix), **D4** (default log into `logs/`).
+Next after that: **B1** (weekly drop-gate planner — highest-impact open feature) and **D1**
+(split `gui.py`).