devcoach 0.3.6__tar.gz → 0.3.9__tar.gz

devcoach-0.3.9/.github/scripts/export_backup.py

@@ -0,0 +1,138 @@
+"""Anonymize a devcoach backup zip for safe public sharing.
+
+Replacements applied to lessons.json:
+  - Absolute paths (/root/username/...)        → /home/user/...
+  - Repository owner prefix (owner/repo)       → developer/repo
+  - Commit hashes (full 40-char SHA-1)         → random 40-char hex
+
+Usage:
+    python .github/scripts/anonymize_backup.py <input.zip> [output.zip]
+
+If output.zip is omitted the anonymized file is written next to the input
+with "-anon" appended to the stem (e.g. devcoach-backup-anon.zip).
+"""
+
+import json
+import re
+import secrets
+import sys
+import zipfile
+from pathlib import Path
+
+
+SHA1_RE = re.compile(r"\b[0-9a-f]{40}\b", re.IGNORECASE)
+REPO_USER_RE = re.compile(r"^[^/\s]+/")
+
+ANON_REPO_PREFIX = "developer/"
+
+
+def _random_sha1() -> str:
+    return secrets.token_hex(20)
+
+
+def _anonymize_path(path: str) -> str:
+    """Replace username in any absolute path /root/username/... → /home/user/..."""
+    parts = path.split("/")
+    # Absolute path: ['', '<root>', '<username>', ...]
+    if len(parts) >= 3 and parts[0] == "" and parts[1] and parts[2]:
+        parts[1] = "home"
+        parts[2] = "user"
+    return "/".join(parts)
+
+
+def _has_personal_path(value: str) -> bool:
+    """True if value contains an absolute path whose username is not 'user'."""
+    parts = value.split("/")
+    return (
+        len(parts) >= 3
+        and parts[0] == ""
+        and parts[1] != ""
+        and parts[2] not in ("", "user")
+        and "/" in value[1:]  # at least one slash after the leading one
+    )
+
+
+def anonymize_lesson(lesson: dict, original_hashes: set[str]) -> dict:
+    out = dict(lesson)
+
+    if out.get("folder"):
+        out["folder"] = _anonymize_path(out["folder"])
+
+    if out.get("repository"):
+        out["repository"] = REPO_USER_RE.sub(ANON_REPO_PREFIX, out["repository"])
+
+    if out.get("commit_hash"):
+        original_hashes.add(out["commit_hash"].lower())
+        out["commit_hash"] = _random_sha1()
+
+    if out.get("task_context"):
+        ctx = out["task_context"]
+
+        def _replace_hash(m: re.Match) -> str:
+            original_hashes.add(m.group().lower())
+            return _random_sha1()
+
+        ctx = SHA1_RE.sub(_replace_hash, ctx)
+        tokens = ctx.split()
+        ctx = " ".join(_anonymize_path(t) if _has_personal_path(t) else t for t in tokens)
+        out["task_context"] = ctx
+
+    return out
+
+
+def anonymize_zip(src: Path, dst: Path) -> None:
+    original_hashes: set[str] = set()
+
+    with zipfile.ZipFile(src) as zin, zipfile.ZipFile(dst, "w", zipfile.ZIP_DEFLATED) as zout:
+        for name in zin.namelist():
+            if name == "learning-state.md":
+                continue  # personal coaching narrative — excluded from anon export
+
+            raw = zin.read(name)
+
+            if name == "lessons.json":
+                lessons = json.loads(raw.decode())
+                lessons = [anonymize_lesson(l, original_hashes) for l in lessons]
+                raw = json.dumps(lessons, indent=2, ensure_ascii=False).encode()
+
+            zout.writestr(name, raw)
+
+    print(f"Anonymized backup written to: {dst}")
+    _verify(dst, original_hashes)
+
+
+def _verify(path: Path, original_hashes: set[str]) -> None:
+    with zipfile.ZipFile(path) as z:
+        lessons = json.loads(z.read("lessons.json").decode())
+    issues: list[str] = []
+    for lesson in lessons:
+        for field in ("folder", "repository", "commit_hash", "task_context"):
+            val = lesson.get(field) or ""
+            if _has_personal_path(val):
+                issues.append(f"  {lesson['id']}.{field}: personal path still present")
+            for match in SHA1_RE.finditer(val):
+                if match.group().lower() in original_hashes:
+                    issues.append(f"  {lesson['id']}.{field}: original SHA-1 hash still present")
+    if issues:
+        print("Verification warnings:")
+        for w in issues:
+            print(w)
+    else:
+        print(f"Verification passed ({len(lessons)} lessons, no personal data detected).")
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        sys.exit(f"Usage: python {sys.argv[0]} <input.zip> [output.zip]")
+
+    src = Path(sys.argv[1])
+    if not src.exists():
+        sys.exit(f"File not found: {src}")
+
+    dst = Path(sys.argv[2]) if len(sys.argv) > 2 else src.with_stem(src.stem + "-anon")
+
+    anonymize_zip(src, dst)
+
+
+if __name__ == "__main__":
+    main()

{devcoach-0.3.6 → devcoach-0.3.9}/.github/scripts/take_screenshots.py

@@ -27,6 +27,14 @@ PAGES = [
     ("settings", "/settings"),
 ]
 
+LESSON_PAGES = [
+    ("lesson-docker-layer-cache", "/lessons/lesson-docker-layer-cache-001"),
+    ("lesson-postgresql-explain-analyze", "/lessons/lesson-postgresql-explain-analyze-001"),
+    ("lesson-git-interactive-rebase", "/lessons/lesson-git-interactive-rebase-001"),
+    ("lesson-ci-cd-pipeline-stages", "/lessons/lesson-ci-cd-pipeline-stages-001"),
+    ("lesson-redis-cache-stampede", "/lessons/lesson-redis-cache-stampede-001"),
+]
+
 def restore_db() -> None:
     result = subprocess.run(
         ["devcoach", "restore", str(BACKUP_ZIP)],
@@ -55,25 +63,16 @@ def take_screenshots(server_proc: subprocess.Popen) -> None:
     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()
+        for scheme in ("light", "dark"):
+            ctx = browser.new_context(viewport=VIEWPORT, color_scheme=scheme)
+            page = ctx.new_page()
+            for name, path in PAGES + LESSON_PAGES:
+                page.goto(f"{BASE_URL}{path}")
+                page.wait_for_load_state("networkidle")
+                out = SCREENSHOTS_DIR / f"{name}-{scheme}.png"
+                page.screenshot(path=str(out))
+                print(f"  saved {out}")
+            ctx.close()
 
         browser.close()
 

{devcoach-0.3.6 → devcoach-0.3.9}/.github/workflows/ci.yml

@@ -117,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:
@@ -149,14 +149,47 @@ 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 and blocks PR merge
-  # if the quality gate fails. Requires Automatic Analysis to be DISABLED on
-  # sonarcloud.io (Administration → Analysis Method).
+  # 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() && (needs.bump.result == 'success' || needs.bump.result == 'skipped') && needs.test.result == 'success'
+    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
@@ -169,12 +202,7 @@ jobs:
       - 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@v6
-        env:
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-      - uses: sonarsource/sonarqube-quality-gate-action@v1
-        if: github.event_name == 'pull_request'
-        timeout-minutes: 5
+      - uses: sonarsource/sonarqube-scan-action@v8
         env:
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
 
@@ -198,12 +226,12 @@ jobs:
           python-version: "3.12"
       - run: uv sync --group docs
       - run: uv run mkdocs build
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: site/
       - name: Deploy to GitHub Pages
         id: deploy
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5
 
   # ── Publish ─────────────────────────────────────────────────────────────
   # Runs when a tag is present: either created by the bump job (workflow_dispatch)

{devcoach-0.3.6 → devcoach-0.3.9}/.github/workflows/ruff-autofix.yml

@@ -7,7 +7,6 @@ on:
 
 permissions:
   contents: write
-  pull-requests: write
 
 jobs:
   autofix:
@@ -29,16 +28,12 @@ jobs:
       - name: Run ruff format
         run: uv run ruff format src/ tests/
 
-      - name: Open PR if there are changes
-        uses: peter-evans/create-pull-request@v7
-        with:
-          commit-message: "style: apply ruff auto-fixes"
-          title: "style: ruff auto-fix"
-          body: |
-            Automated style fixes applied by `ruff check --fix` and `ruff format`.
-
-            This PR was opened automatically by the **Ruff auto-fix** workflow.
-            Review the diff, then merge or close.
-          branch: ruff/autofix
-          delete-branch: true
-          labels: style
+      - name: Commit and push if there are changes
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --staged --quiet && echo "No changes." || (
+            git commit -m "style: apply ruff auto-fixes [skip ci]" &&
+            git push
+          )

{devcoach-0.3.6 → devcoach-0.3.9}/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.6 → devcoach-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devcoach
-Version: 0.3.6
+Version: 0.3.9
 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,7 +232,7 @@ 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)
@@ -259,9 +258,9 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 
 ## Screenshots
 
-| Knowledge map | Lesson history | Settings |
-|:---:|:---:|:---:|
-| ![Knowledge map](docs/screenshots/knowledge-map-light.png) | ![Lessons](docs/screenshots/lessons-dark.png) | ![Settings](docs/screenshots/settings-dark.png) |
+|                       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) |
 
 ---
 
@@ -270,7 +269,7 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 ### Recommended — no permanent install needed
 
 ```bash
-uvx devcoach
+uvx devcoach mcp   # starts the MCP server directly
 ```
 
 ### Permanent install
@@ -287,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
 
 ---
 
@@ -322,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...
 ```
 
@@ -341,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) |
@@ -387,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"]
     }
   }
 }
@@ -429,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.6 → devcoach-0.3.9}/README.md

@@ -1,7 +1,7 @@
 # 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)
@@ -27,9 +27,9 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 
 ## Screenshots
 
-| Knowledge map | Lesson history | Settings |
-|:---:|:---:|:---:|
-| ![Knowledge map](docs/screenshots/knowledge-map-light.png) | ![Lessons](docs/screenshots/lessons-dark.png) | ![Settings](docs/screenshots/settings-dark.png) |
+|                       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) |
 
 ---
 
@@ -38,7 +38,7 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 ### Recommended — no permanent install needed
 
 ```bash
-uvx devcoach
+uvx devcoach mcp   # starts the MCP server directly
 ```
 
 ### Permanent install
@@ -55,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
 
 ---
 
@@ -90,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...
 ```
 
@@ -109,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) |
@@ -155,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"]
     }
   }
 }
@@ -197,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.6 → devcoach-0.3.9}/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.6 → devcoach-0.3.9}/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