devcoach 0.3.5__tar.gz → 0.3.8__tar.gz

devcoach-0.3.8/.github/scripts/take_screenshots.py

@@ -0,0 +1,110 @@
+"""Take devcoach UI screenshots for documentation.
+
+Flow:
+  1. Restore DB from .github/scripts/fixtures/devcoach-backup.zip via `devcoach restore`
+  2. Start `devcoach ui` on a fixed port
+  3. Capture light + dark screenshots of each page
+  4. Stop the server
+"""
+
+import signal
+import subprocess
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+SCREENSHOTS_DIR = Path("docs/screenshots")
+FIXTURES_DIR = Path(".github/scripts/fixtures")
+BACKUP_ZIP = FIXTURES_DIR / "devcoach-backup.zip"
+PORT = 7862
+BASE_URL = f"http://localhost:{PORT}"
+VIEWPORT = {"width": 1440, "height": 900}
+
+PAGES = [
+    ("knowledge-map", "/"),
+    ("lessons", "/lessons"),
+    ("settings", "/settings"),
+]
+
+def restore_db() -> None:
+    result = subprocess.run(
+        ["devcoach", "restore", str(BACKUP_ZIP)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    print(result.stdout.strip())
+
+
+def wait_for_server(url: str, timeout: int = 30) -> None:
+    for _ in range(timeout):
+        try:
+            urllib.request.urlopen(url, timeout=1)
+            return
+        except Exception:
+            time.sleep(1)
+    raise TimeoutError(f"Server at {url} did not start within {timeout}s")
+
+
+def take_screenshots(server_proc: subprocess.Popen) -> None:
+    from playwright.sync_api import sync_playwright
+
+    SCREENSHOTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch()
+
+        ctx = browser.new_context(viewport=VIEWPORT, color_scheme="light")
+        page = ctx.new_page()
+        for name, path in PAGES:
+            page.goto(f"{BASE_URL}{path}")
+            page.wait_for_load_state("networkidle")
+            out = SCREENSHOTS_DIR / f"{name}-light.png"
+            page.screenshot(path=str(out))
+            print(f"  saved {out}")
+        ctx.close()
+
+        ctx = browser.new_context(viewport=VIEWPORT, color_scheme="dark")
+        page = ctx.new_page()
+        for name, path in PAGES:
+            page.goto(f"{BASE_URL}{path}")
+            page.wait_for_load_state("networkidle")
+            out = SCREENSHOTS_DIR / f"{name}-dark.png"
+            page.screenshot(path=str(out))
+            print(f"  saved {out}")
+        ctx.close()
+
+        browser.close()
+
+    server_proc.send_signal(signal.SIGTERM)
+    server_proc.wait(timeout=10)
+
+
+def main() -> None:
+    if not BACKUP_ZIP.exists():
+        sys.exit(f"Backup not found: {BACKUP_ZIP}")
+
+    print(f"Restoring DB from {BACKUP_ZIP}…")
+    restore_db()
+
+    print(f"Starting devcoach UI on port {PORT}…")
+    proc = subprocess.Popen(
+        ["devcoach", "ui", "--port", str(PORT)],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+    try:
+        wait_for_server(BASE_URL)
+        print("Taking screenshots…")
+        take_screenshots(proc)
+    except Exception:
+        proc.terminate()
+        raise
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

{devcoach-0.3.5 → devcoach-0.3.8}/.github/workflows/ci.yml

@@ -1,8 +1,17 @@
 name: CI
 
+run-name: >-
+  ${{ github.event_name == 'workflow_dispatch'
+    && format('CI — New release ({0})', inputs.version != '' && inputs.version || inputs.bump)
+    || (startsWith(github.ref, 'refs/tags/v')
+    && format('CI — New release ({0})', github.ref_name)
+    || (github.event_name == 'pull_request'
+    && format('CI - PR {0}', github.event.pull_request.title)
+    || format('CI — {0}', github.event.head_commit.message))) }}
+
 # Covers three scenarios:
 #
-#  1. Push to main / pull request  →  lint + test + build
+#  1. Push to main / pull request  →  lint + test + build + sonar + pages
 #  2. Tag push (v*)                →  lint + test + build + publish + GitHub Release
 #  3. workflow_dispatch (Release)  →  bump version → tag → lint + test + build + publish + GitHub Release
 #
@@ -70,12 +79,14 @@ jobs:
           echo "version=$NEXT" >> "$GITHUB_OUTPUT"
           echo "tag=v$NEXT"    >> "$GITHUB_OUTPUT"
 
-      - name: Bump version in pyproject.toml
-        run: sed -i 's/^version = ".*"/version = "${{ steps.ver.outputs.version }}"/' pyproject.toml
+      - name: Bump version in pyproject.toml and sonar-project.properties
+        run: |
+          sed -i 's/^version = ".*"/version = "${{ steps.ver.outputs.version }}"/' pyproject.toml
+          sed -i 's/^sonar.projectVersion=.*/sonar.projectVersion=${{ steps.ver.outputs.version }}/' sonar-project.properties
 
       - name: Commit and tag
         run: |
-          git add pyproject.toml
+          git add pyproject.toml sonar-project.properties
           git commit -m "chore: bump version to ${{ steps.ver.outputs.version }}"
           git tag "${{ steps.ver.outputs.tag }}"
           git push --atomic origin main "${{ steps.ver.outputs.tag }}"
@@ -106,7 +117,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v6
         with:
@@ -115,7 +126,8 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv sync --group dev
-      - run: uv run pytest tests/ -v --tb=short
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short
 
   # ── Build ───────────────────────────────────────────────────────────────
   build:
@@ -137,6 +149,90 @@ jobs:
           path: dist/
           retention-days: 7
 
+  # ── Coverage comment on PR ──────────────────────────────────────────────
+  # Posts (and updates) a coverage summary comment on every PR push.
+  # Reads the .coverage file generated by pytest-cov — no extra deps needed.
+  coverage:
+    name: Coverage comment
+    needs: [bump]
+    if: >
+      github.event_name == 'pull_request'
+      && (needs.bump.result == 'success' || needs.bump.result == 'skipped')
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+      - name: Run tests with coverage
+        run: uv run pytest tests/ --cov=src/devcoach --cov-report=xml
+      - uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ github.token }}
+          MINIMUM_GREEN: 90
+          MINIMUM_ORANGE: 80
+
+  # ── SonarCloud scan + quality gate ─────────────────────────────────────
+  # CI-based analysis: feeds coverage.xml to SonarCloud.
+  # Skipped on pull_request events — SONAR_TOKEN is not available to PR
+  # workflows (GitHub restricts secret access). Runs on main / tags / dispatch
+  # where the token is available.
+  # Requires Automatic Analysis to be DISABLED on sonarcloud.io
+  # (Administration → Analysis Method).
+  sonar:
+    name: SonarCloud scan
+    needs: [bump, test]
+    if: >
+      always()
+      && github.event_name != 'pull_request'
+      && (needs.bump.result == 'success' || needs.bump.result == 'skipped')
+      && needs.test.result == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.bump.outputs.tag || github.ref }}
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+      - run: uv sync --group dev
+      - name: Run tests with coverage
+        run: uv run pytest tests/ -v --tb=short --cov=src/devcoach --cov-report=xml
+      - uses: sonarsource/sonarqube-scan-action@v7
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+
+  # ── GitHub Pages ────────────────────────────────────────────────────────
+  # Builds MkDocs site and deploys to GitHub Pages on every push to main.
+  pages:
+    name: Deploy docs to GitHub Pages
+    needs: [bump, build]
+    if: always() && needs.build.result == 'success' && github.ref == 'refs/heads/main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+      - run: uv sync --group docs
+      - run: uv run mkdocs build
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site/
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v5
+
   # ── Publish ─────────────────────────────────────────────────────────────
   # Runs when a tag is present: either created by the bump job (workflow_dispatch)
   # or pushed directly (git push origin v1.2.3).

{devcoach-0.3.5 → devcoach-0.3.8}/.github/workflows/ruff-autofix.yml

@@ -30,7 +30,7 @@ jobs:
         run: uv run ruff format src/ tests/
 
       - name: Open PR if there are changes
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@v8
         with:
           commit-message: "style: apply ruff auto-fixes"
           title: "style: ruff auto-fix"

devcoach-0.3.8/.github/workflows/update-screenshots.yml

@@ -0,0 +1,39 @@
+name: Update documentation screenshots (GitHub Pages)
+
+on:
+  workflow_dispatch:
+
+jobs:
+  screenshots:
+    name: Take and commit screenshots
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install devcoach
+        run: uv sync
+
+      - name: Install Playwright + Chromium
+        run: |
+          uv pip install playwright
+          uv run playwright install chromium --with-deps
+
+      - name: Restore DB and take screenshots
+        run: uv run python .github/scripts/take_screenshots.py
+
+      - name: Commit screenshots
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/screenshots/
+          git diff --staged --quiet && echo "No changes." || (
+            git commit -m "docs: update screenshots [skip ci]" &&
+            git push
+          )

{devcoach-0.3.5 → devcoach-0.3.8}/CLAUDE.md

@@ -9,7 +9,7 @@ based on the user's knowledge map, the rate limit, and what has already been tau
 
 Repo: https://github.com/UltimaPhoenix/dev-coach
 PyPI package name: `devcoach`
-End-user command: `uvx devcoach`
+End-user command: `uvx devcoach` (CLI) / `uvx devcoach mcp` (MCP server)
 
 ---
 
@@ -240,7 +240,7 @@ npx @modelcontextprotocol/inspector devcoach
   "mcpServers": {
     "devcoach": {
       "command": "uvx",
-      "args": ["devcoach"]
+      "args": ["devcoach", "mcp"]
     }
   }
 }
@@ -252,7 +252,8 @@ npx @modelcontextprotocol/inspector devcoach
 
 - Follow **Uncle Bob's Clean Code** principles
 - Follow **PEP** standards
-- Linting and formatting enforced by **ruff** — run `uv run ruff check src/ tests/` and `uv run ruff format src/ tests/` before committing
+- Linting and formatting enforced by **ruff** — run `uv run ruff check src/ tests/` and `uv run ruff format src/ tests/` before committing. **All ruff checks must pass before committing.**
+- Test coverage must stay **at or above 80%** — run `uv run pytest --cov=src/devcoach --cov-fail-under=80` to verify. Do not merge code that drops total coverage below this threshold.
 - No external dependencies beyond `fastmcp` and `pydantic`
 - `db.py` exposes only pure functions — no business logic
 - `coach.py` never imports from `server.py` (one-way dependency)

{devcoach-0.3.5 → devcoach-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devcoach
-Version: 0.3.5
+Version: 0.3.8
 Summary: A local MCP server that acts as a progressive technical coach for Claude Code and Claude Desktop
 Project-URL: Homepage, https://github.com/UltimaPhoenix/dev-coach
 Project-URL: Repository, https://github.com/UltimaPhoenix/dev-coach
@@ -216,12 +216,11 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Education
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Requires-Dist: fastapi>=0.110
 Requires-Dist: fastmcp>=2.0
 Requires-Dist: jinja2>=3.1
@@ -233,8 +232,11 @@ Description-Content-Type: text/markdown
 # devcoach
 
 [![PyPI](https://img.shields.io/github/v/release/UltimaPhoenix/dev-coach?label=PyPI)](https://pypi.org/project/devcoach/)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/devcoach/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://pypi.org/project/devcoach/)
 [![CI](https://github.com/UltimaPhoenix/dev-coach/actions/workflows/ci.yml/badge.svg)](https://github.com/UltimaPhoenix/dev-coach/actions/workflows/ci.yml)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=coverage)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-purple)](https://ultimaphoenix.github.io/dev-coach/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
 **Progressive technical coaching, directly in Claude.** After every task you complete with Claude Code or Claude Desktop, devcoach delivers a short, targeted lesson based on what you already know — no generic tutorials, no repeated topics.
@@ -254,12 +256,20 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 
 ---
 
+## Screenshots
+
+|                       Knowledge map                       | Lesson history | Settings |
+|:---------------------------------------------------------:|:---:|:---:|
+| ![Knowledge map](docs/screenshots/knowledge-map-dark.png) | ![Lessons](docs/screenshots/lessons-dark.png) | ![Settings](docs/screenshots/settings-dark.png) |
+
+---
+
 ## Installation
 
 ### Recommended — no permanent install needed
 
 ```bash
-uvx devcoach
+uvx devcoach mcp   # starts the MCP server directly
 ```
 
 ### Permanent install
@@ -276,7 +286,7 @@ devcoach install
 
 Restart Claude Code or Claude Desktop after installing.
 
-> **Requirements:** [uv](https://docs.astral.sh/uv/) · Python 3.11+ · Claude Code or Claude Desktop
+> **Requirements:** [uv](https://docs.astral.sh/uv/) · Python 3.12+ · Claude Code or Claude Desktop
 
 ---
 
@@ -311,7 +321,7 @@ Claude: [does the work]
 
 **Structured concurrency with asyncio.TaskGroup**
 
-TaskGroup (Python 3.11+) is the modern replacement for bare gather() calls.
+TaskGroup (Python 3.12+) is the modern replacement for bare gather() calls.
 Unlike gather(), it cancels sibling tasks automatically when one raises...
 ```
 
@@ -330,13 +340,16 @@ devcoach feedback lesson-python-taskgroup-001 dont_know # need to revisit —
 
 | Command | Description |
 |---------|-------------|
+| `devcoach` | Show all available commands |
+| `devcoach mcp` | Start the MCP server (stdio) for Claude Code / Claude Desktop |
 | `devcoach setup` | Run the onboarding wizard in the terminal |
 | `devcoach install` | Register with Claude Code / Claude Desktop |
 | `devcoach profile` | Show your knowledge map with confidence bars |
 | `devcoach stats` | Overview: lesson counts, weakest/strongest topics |
 | `devcoach lessons` | Browse lesson history with filters |
 | `devcoach lesson <id>` | Show a single lesson in full |
-| `devcoach star <id>` | Toggle starred flag |
+| `devcoach star <id>` | Mark a lesson as starred (favourite) |
+| `devcoach unstar <id>` | Remove the starred mark from a lesson |
 | `devcoach feedback <id> <know\|dont_know\|clear>` | Record comprehension |
 | `devcoach set max_per_day <n>` | Max lessons in a 24-hour window (default 2) |
 | `devcoach set min_gap_minutes <n>` | Minimum minutes between lessons (default 240) |
@@ -376,7 +389,7 @@ devcoach implements the [MCP 2025-11-25 spec](https://modelcontextprotocol.io/sp
     "devcoach": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["devcoach"]
+      "args": ["devcoach", "mcp"]
     }
   }
 }
@@ -418,7 +431,7 @@ git tag v1.2.3
 git push origin v1.2.3
 ```
 
-The pipeline will lint, test across Python 3.11–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.
+The pipeline will lint, test across Python 3.12–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.
 
 > **First-time PyPI setup:** configure a Trusted Publisher on PyPI for `UltimaPhoenix/dev-coach` (environment: `pypi`, workflow: `ci.yml`). No API token required after that.
 

{devcoach-0.3.5 → devcoach-0.3.8}/README.md

@@ -1,8 +1,11 @@
 # devcoach
 
 [![PyPI](https://img.shields.io/github/v/release/UltimaPhoenix/dev-coach?label=PyPI)](https://pypi.org/project/devcoach/)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/devcoach/)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://pypi.org/project/devcoach/)
 [![CI](https://github.com/UltimaPhoenix/dev-coach/actions/workflows/ci.yml/badge.svg)](https://github.com/UltimaPhoenix/dev-coach/actions/workflows/ci.yml)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
+[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=coverage)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-purple)](https://ultimaphoenix.github.io/dev-coach/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
 
 **Progressive technical coaching, directly in Claude.** After every task you complete with Claude Code or Claude Desktop, devcoach delivers a short, targeted lesson based on what you already know — no generic tutorials, no repeated topics.
@@ -22,12 +25,20 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 
 ---
 
+## Screenshots
+
+|                       Knowledge map                       | Lesson history | Settings |
+|:---------------------------------------------------------:|:---:|:---:|
+| ![Knowledge map](docs/screenshots/knowledge-map-dark.png) | ![Lessons](docs/screenshots/lessons-dark.png) | ![Settings](docs/screenshots/settings-dark.png) |
+
+---
+
 ## Installation
 
 ### Recommended — no permanent install needed
 
 ```bash
-uvx devcoach
+uvx devcoach mcp   # starts the MCP server directly
 ```
 
 ### Permanent install
@@ -44,7 +55,7 @@ devcoach install
 
 Restart Claude Code or Claude Desktop after installing.
 
-> **Requirements:** [uv](https://docs.astral.sh/uv/) · Python 3.11+ · Claude Code or Claude Desktop
+> **Requirements:** [uv](https://docs.astral.sh/uv/) · Python 3.12+ · Claude Code or Claude Desktop
 
 ---
 
@@ -79,7 +90,7 @@ Claude: [does the work]
 
 **Structured concurrency with asyncio.TaskGroup**
 
-TaskGroup (Python 3.11+) is the modern replacement for bare gather() calls.
+TaskGroup (Python 3.12+) is the modern replacement for bare gather() calls.
 Unlike gather(), it cancels sibling tasks automatically when one raises...
 ```
 
@@ -98,13 +109,16 @@ devcoach feedback lesson-python-taskgroup-001 dont_know # need to revisit —
 
 | Command | Description |
 |---------|-------------|
+| `devcoach` | Show all available commands |
+| `devcoach mcp` | Start the MCP server (stdio) for Claude Code / Claude Desktop |
 | `devcoach setup` | Run the onboarding wizard in the terminal |
 | `devcoach install` | Register with Claude Code / Claude Desktop |
 | `devcoach profile` | Show your knowledge map with confidence bars |
 | `devcoach stats` | Overview: lesson counts, weakest/strongest topics |
 | `devcoach lessons` | Browse lesson history with filters |
 | `devcoach lesson <id>` | Show a single lesson in full |
-| `devcoach star <id>` | Toggle starred flag |
+| `devcoach star <id>` | Mark a lesson as starred (favourite) |
+| `devcoach unstar <id>` | Remove the starred mark from a lesson |
 | `devcoach feedback <id> <know\|dont_know\|clear>` | Record comprehension |
 | `devcoach set max_per_day <n>` | Max lessons in a 24-hour window (default 2) |
 | `devcoach set min_gap_minutes <n>` | Minimum minutes between lessons (default 240) |
@@ -144,7 +158,7 @@ devcoach implements the [MCP 2025-11-25 spec](https://modelcontextprotocol.io/sp
     "devcoach": {
       "type": "stdio",
       "command": "uvx",
-      "args": ["devcoach"]
+      "args": ["devcoach", "mcp"]
     }
   }
 }
@@ -186,7 +200,7 @@ git tag v1.2.3
 git push origin v1.2.3
 ```
 
-The pipeline will lint, test across Python 3.11–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.
+The pipeline will lint, test across Python 3.12–3.13, build, publish to PyPI via OIDC Trusted Publishing, and create a GitHub Release automatically.
 
 > **First-time PyPI setup:** configure a Trusted Publisher on PyPI for `UltimaPhoenix/dev-coach` (environment: `pypi`, workflow: `ci.yml`). No API token required after that.
 

{devcoach-0.3.5 → devcoach-0.3.8}/docs/cli.md

@@ -1,15 +1,38 @@
 # CLI reference
 
-## Global
+## Overview
+
+Running `devcoach` with no arguments prints a help panel listing every available command:
 
 ```
-devcoach <command> [options]
+devcoach
 ```
 
 All commands operate on `~/.devcoach/coaching.db`. No network access required.
 
 ---
 
+## MCP server
+
+### `devcoach mcp`
+
+Start the stdio MCP server for Claude Code or Claude Desktop. This is what you put in your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "devcoach": {
+      "command": "uvx",
+      "args": ["devcoach", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+---
+
 ## Knowledge map
 
 ### `devcoach profile`
@@ -117,13 +140,24 @@ devcoach lesson lesson-python-generators-001
 
 ### `devcoach star <id>`
 
-Toggle the starred (favourite) flag on a lesson.
+Mark a lesson as starred (favourite).
 
 ```bash
 devcoach star lesson-python-generators-001
 # → Lesson lesson-python-generators-001 → ★ starred
 ```
 
+### `devcoach unstar <id>`
+
+Remove the starred mark from a lesson.
+
+```bash
+devcoach unstar lesson-python-generators-001
+# → Lesson lesson-python-generators-001 → ☆ unstarred
+```
+
+Both commands are idempotent — calling them when the lesson is already in the target state is safe.
+
 ### `devcoach feedback <id> <value>`
 
 Record whether you understood a lesson. Adjusts knowledge confidence.
@@ -191,7 +225,7 @@ Followed by optional group assignment and rate-limit settings.
 
 ### `devcoach install`
 
-Register the devcoach MCP server in Claude's config files.
+Register the devcoach MCP server (`devcoach mcp`) in Claude's config files.
 
 ```bash
 devcoach install                  # both Claude Code + Claude Desktop

devcoach-0.3.8/docs/favicon.svg

@@ -0,0 +1 @@
+../src/devcoach/web/static/favicon.svg

{devcoach-0.3.5 → devcoach-0.3.8}/docs/getting-started.md

@@ -3,25 +3,35 @@
 ## Prerequisites
 
 - [uv](https://docs.astral.sh/uv/) (recommended) or pip
-- Python 3.11+
+- Python 3.12+
 - Claude Code or Claude Desktop
 
 ---
 
 ## 1. Install
 
-### One-time run (no permanent install)
+devcoach is published on [PyPI](https://pypi.org/project/devcoach/) and can be installed with any Python package manager.
+
+### One-time run — no install needed
 
 ```bash
-uvx devcoach
+uvx devcoach mcp
 ```
 
-### Permanent install
+`uvx` fetches the latest release from PyPI and runs it in an isolated environment. Nothing is left behind.
+
+### Permanent install with uv (recommended)
 
 ```bash
 uv tool install devcoach
 ```
 
+### Permanent install with pip
+
+```bash
+pip install devcoach
+```
+
 ---
 
 ## 2. Register with Claude