devcoach 0.3.9__tar.gz → 0.3.10__tar.gz

{devcoach-0.3.9 → devcoach-0.3.10}/.gitignore

@@ -197,6 +197,8 @@ cython_debug/
 # Claude Code
 .claude/
 .playwright-mcp/
+.playwright-cli/
+config.example.json
 
 # Cursor
 #  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to

{devcoach-0.3.9 → devcoach-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devcoach
-Version: 0.3.9
+Version: 0.3.10
 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
@@ -245,12 +245,35 @@ Description-Content-Type: text/markdown
 
 ## How it works
 
-| Step | What happens |
-|------|-------------|
-| You complete a task with Claude | Claude finishes the work as normal |
-| devcoach checks your knowledge map | Finds a topic where you have room to grow, related to what you just did |
-| A lesson appears at the end of the response | Calibrated to your level (junior / mid / senior), never repeated |
-| You mark it know / don't know | Confidence scores update, shaping future lessons |
+```mermaid
+flowchart TD
+    A([Task completed]) --> B[Check rate limit]
+    B -->|denied| Z([Silent])
+    B -->|allowed| D
+
+    subgraph loop["coaching loop"]
+        D[Select topic & depth]
+        E[Compose & deliver]
+        G[log_lesson]
+    end
+
+    D -->|nothing| Z
+    D -->|found| E
+    E --> G
+    G --> F([Done])
+    G -.->|prompts| U(["You: ✅ ❌ ⏭"])
+
+    style loop fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+    classDef user   fill:#F5EDE3,stroke:#D4A27F,color:#1E1E1E
+
+    class B,D,E,G action
+    class A,F,Z term
+    class U user
+```
+
+→ [Full decision flow: session startup · lesson selection · depth calibration](https://ultimaphoenix.github.io/dev-coach/how-it-works/)
 
 Everything runs **locally**. No data leaves your machine. One SQLite file at `~/.devcoach/coaching.db`.
 

{devcoach-0.3.9 → devcoach-0.3.10}/README.md

@@ -14,12 +14,35 @@
 
 ## How it works
 
-| Step | What happens |
-|------|-------------|
-| You complete a task with Claude | Claude finishes the work as normal |
-| devcoach checks your knowledge map | Finds a topic where you have room to grow, related to what you just did |
-| A lesson appears at the end of the response | Calibrated to your level (junior / mid / senior), never repeated |
-| You mark it know / don't know | Confidence scores update, shaping future lessons |
+```mermaid
+flowchart TD
+    A([Task completed]) --> B[Check rate limit]
+    B -->|denied| Z([Silent])
+    B -->|allowed| D
+
+    subgraph loop["coaching loop"]
+        D[Select topic & depth]
+        E[Compose & deliver]
+        G[log_lesson]
+    end
+
+    D -->|nothing| Z
+    D -->|found| E
+    E --> G
+    G --> F([Done])
+    G -.->|prompts| U(["You: ✅ ❌ ⏭"])
+
+    style loop fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+    classDef user   fill:#F5EDE3,stroke:#D4A27F,color:#1E1E1E
+
+    class B,D,E,G action
+    class A,F,Z term
+    class U user
+```
+
+→ [Full decision flow: session startup · lesson selection · depth calibration](https://ultimaphoenix.github.io/dev-coach/how-it-works/)
 
 Everything runs **locally**. No data leaves your machine. One SQLite file at `~/.devcoach/coaching.db`.
 

devcoach-0.3.10/docs/how-it-works.md

@@ -0,0 +1,102 @@
+# How it works
+
+devcoach is a silent technical coach that hooks into every Claude response.
+The diagrams below show the three main flows: session startup, the coaching loop,
+and how a lesson topic is selected.
+
+---
+
+## Session startup
+
+At the start of each Claude session devcoach checks whether the user is set up,
+loads prior coaching context, and primes lesson selection before any task is done.
+
+```mermaid
+flowchart LR
+    A([Start]) --> B{First run?}
+    B -- yes --> C[Detect stack]
+    C --> D[Confirm topics\n& groups]
+    D --> E[Save profile]
+    B -- no --> F[Load profile\n& notebook]
+    E & F --> G([Ready])
+
+    subgraph onboarding["onboarding"]
+        C
+        D
+        E
+    end
+
+    style onboarding fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+
+    class C,D,E,F action
+    class A,G term
+```
+
+---
+
+## Coaching loop
+
+After every technical task Claude evaluates whether to deliver a lesson.
+The loop is silent when nothing is worth teaching or when the rate limit is reached.
+
+```mermaid
+flowchart TD
+    A([Task completed]) --> B[Check rate limit]
+    B -->|denied| Z([Silent])
+    B -->|allowed| D
+
+    subgraph loop["coaching loop"]
+        D[Select topic & depth]
+        E[Compose & deliver]
+        G[log_lesson]
+    end
+
+    D -->|nothing| Z
+    D -->|found| E
+    E --> G
+    G --> F([Done])
+    G -.->|prompts| U(["You: ✅ ❌ ⏭"])
+
+    style loop fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+    classDef user   fill:#F5EDE3,stroke:#D4A27F,color:#1E1E1E
+
+    class B,D,E,G action
+    class A,F,Z term
+    class U user
+```
+
+---
+
+## Lesson selection
+
+When a teachable concept is found, devcoach walks this priority list from top to bottom
+and picks the first match. Depth is then calibrated to the per-topic confidence score.
+
+| Priority | Trigger | Condition |
+|:---:|---|---|
+| ① | Notebook follow-up | The coaching notebook flagged an angle relevant to the current task |
+| ② | Profile pitfall | A pitfall committed or avoided on a profile topic |
+| ③ | Profile pattern | An interesting pattern on a profile topic worth formalising |
+| ④ | Off-profile pitfall | A pitfall on a topic prominent in the task but absent from the profile |
+| ⑤ | Knowledge gap | A profile topic with confidence < 5 |
+| ⑥ | Deep-dive | A profile topic at confidence 4–6, not yet mastered |
+
+First match wins. No match → silent.
+
+---
+
+## Depth calibration
+
+The lesson level is determined by the confidence score for the **specific topic being taught**,
+adjusted by observations in the coaching notebook.
+
+| Confidence | Level | Lesson angle |
+|---|---|---|
+| 0 – 3 | Junior | Introduce correct practice, explain from scratch, use analogies |
+| 4 – 6 | Mid | Explain the why, mention trade-offs and alternatives |
+| 7 – 9 | Senior | Edge cases, historical context, architectural implications |
+| 10 | Cutting-edge | Latest developments — ignores level floor and taught-topics filter |

{devcoach-0.3.9 → devcoach-0.3.10}/docs/index.md

@@ -9,29 +9,34 @@ Everything runs **locally**. No data leaves your machine. One SQLite file at `~/
 ## How it works
 
 ```mermaid
-sequenceDiagram
-    actor User
-    participant Claude as Claude (AI)
-    participant devcoach as devcoach (MCP)
-
-    User->>+Claude: Complete a technical task
-    Claude-->>User: Work completed normally
-
-    Claude->>devcoach: check rate-limit + profile + taught topics
-    devcoach-->>Claude: knowledge map · lesson history · coaching notebook
-
-    Claude->>Claude: select topic · calibrate depth · compose lesson
-
-    Claude->>devcoach: log_lesson(id, topic, level, body, …)
-    Claude-->>-User: Response + 🎓 lesson at the bottom
-
-    User->>+Claude: ✅ know · ❌ don't know · ⏭ skip
-    Claude->>devcoach: submit_feedback → confidence ±1
-    Claude->>Claude: update coaching notebook if warranted
-    Claude-->>-User: acknowledged
+flowchart TD
+    A([Task completed]) --> B[Check rate limit]
+    B -->|denied| Z([Silent])
+    B -->|allowed| D
+
+    subgraph loop["coaching loop"]
+        D[Select topic & depth]
+        E[Compose & deliver]
+        G[log_lesson]
+    end
+
+    D -->|nothing| Z
+    D -->|found| E
+    E --> G
+    G --> F([Done])
+    G -.->|prompts| U(["You: ✅ ❌ ⏭"])
+
+    style loop fill:none,stroke:#AAAAAA,stroke-dasharray:5 5,color:#757575
+    classDef action fill:#D4E4D8,stroke:#8BAF96,color:#1E1E1E
+    classDef term   fill:#E8E8E4,stroke:#AAAAAA,color:#1E1E1E
+    classDef user   fill:#F5EDE3,stroke:#D4A27F,color:#1E1E1E
+
+    class B,D,E,G action
+    class A,F,Z term
+    class U user
 ```
 
-See [How it works](how-it-works.md) for the full decision flow.
+→ [Full decision flow: session startup · lesson selection · depth calibration](how-it-works.md)
 
 ---
 

{devcoach-0.3.9 → devcoach-0.3.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devcoach"
-version = "0.3.9"
+version = "0.3.10"
 description = "A local MCP server that acts as a progressive technical coach for Claude Code and Claude Desktop"
 readme = "README.md"
 requires-python = ">=3.12"

{devcoach-0.3.9 → devcoach-0.3.10}/sonar-project.properties

@@ -2,7 +2,7 @@ sonar.projectKey=UltimaPhoenix_dev-coach
 sonar.organization=ultimaphoenix
 
 sonar.projectName=devcoach
-sonar.projectVersion=0.3.9
+sonar.projectVersion=0.3.10
 
 sonar.sources=src
 sonar.tests=tests

{devcoach-0.3.9 → devcoach-0.3.10}/src/devcoach/mcp/server.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from typing import Literal
 
 from fastmcp import Context, FastMCP
+from mcp.types import ToolAnnotations
 
 from devcoach.core import coach, db
 from devcoach.core.detect import detect_stack
@@ -29,7 +30,9 @@ mcp = FastMCP(
 # ── MCP Tools ─────────────────────────────────────────────────────────────
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True, openWorldHint=False)
+)
 async def log_lesson(
     ctx: Context,
     id: str,
@@ -107,7 +110,9 @@ async def log_lesson(
     return lesson
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True, openWorldHint=False)
+)
 async def update_knowledge(ctx: Context, topic: str, delta: int) -> int:
     """Adjust the confidence score for a topic by delta (e.g. +1 or -1).
 
@@ -122,7 +127,11 @@ async def update_knowledge(ctx: Context, topic: str, delta: int) -> int:
         raise
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(
+        readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False
+    )
+)
 def get_lessons(
     period: Literal["today", "week", "month", "year", "all"] | None = None,
     category: str | None = None,
@@ -173,7 +182,9 @@ def get_lessons(
         return []
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True, openWorldHint=False)
+)
 async def star_lesson(ctx: Context, lesson_id: str, starred: bool) -> bool:
     """Set the starred (favourite) flag on a lesson to the given value.
 
@@ -192,7 +203,9 @@ async def star_lesson(ctx: Context, lesson_id: str, starred: bool) -> bool:
         return False
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True, openWorldHint=False)
+)
 async def delete_lesson(ctx: Context, lesson_id: str) -> bool:
     """Permanently delete a lesson by ID.
 
@@ -209,7 +222,9 @@ async def delete_lesson(ctx: Context, lesson_id: str) -> bool:
         return False
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True, openWorldHint=False)
+)
 async def submit_feedback(
     ctx: Context, lesson_id: str, feedback: Literal["know", "dont_know", "clear"]
 ) -> bool:
@@ -244,7 +259,9 @@ async def submit_feedback(
         return False
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True, openWorldHint=False)
+)
 async def add_topic(
     ctx: Context, topic: str, confidence: int = 5, group: str | None = None
 ) -> bool:
@@ -267,7 +284,9 @@ async def add_topic(
         return False
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True, openWorldHint=False)
+)
 async def remove_topic(ctx: Context, topic: str) -> bool:
     """Remove a topic from the knowledge map entirely.
 
@@ -284,7 +303,9 @@ async def remove_topic(ctx: Context, topic: str) -> bool:
         return False
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True, openWorldHint=False)
+)
 async def add_group(ctx: Context, name: str) -> bool:
     """Create a new (initially empty) knowledge group.
 
@@ -305,7 +326,9 @@ async def add_group(ctx: Context, name: str) -> bool:
         return False
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=True, idempotentHint=True, openWorldHint=False)
+)
 async def remove_group(ctx: Context, name: str) -> bool:
     """Delete a knowledge group. Topics in the group move to Other.
 
@@ -322,7 +345,9 @@ async def remove_group(ctx: Context, name: str) -> bool:
         return False
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=False, idempotentHint=True, openWorldHint=False)
+)
 def update_settings(key: Literal["max_per_day", "min_gap_minutes"], value: str) -> Settings:
     """Update a coaching setting.
 
@@ -345,7 +370,9 @@ def update_settings(key: Literal["max_per_day", "min_gap_minutes"], value: str)
         return db.get_settings(conn)
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=False, idempotentHint=False, openWorldHint=True)
+)
 def open_ui(port: int = 7860) -> str:
     """Launch the devcoach web dashboard in the background.
 
@@ -363,7 +390,9 @@ def open_ui(port: int = 7860) -> str:
     return f"devcoach UI starting at http://localhost:{port}"
 
 
-@mcp.tool
+@mcp.tool(
+    annotations=ToolAnnotations(destructiveHint=True, idempotentHint=False, openWorldHint=False)
+)
 async def complete_onboarding(
     ctx: Context,
     topics: dict[str, int],

{devcoach-0.3.9 → devcoach-0.3.10}/tests/test_mcp_server.py

@@ -479,6 +479,12 @@ class TestCompleteOnboarding:
         _run(server.complete_onboarding(mock_ctx, topics={"python": 7}))
         mock_ctx.info.assert_called_once()
 
+    def test_exception_returns_empty_profile(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = _run(server.complete_onboarding(mock_ctx, topics={"python": 7}))
+        assert result.knowledge == []
+        assert result.groups == []
+
 
 # ── Resources ──────────────────────────────────────────────────────────────
 
@@ -557,6 +563,151 @@ class TestPrompt:
         assert any(word in result.lower() for word in ("lesson", "coach", "devcoach", "knowledge"))
 
 
+# ── Tools — delete_lesson ─────────────────────────────────────────────────
+
+
+class TestDeleteLesson:
+    def test_found_returns_true(self, mock_ctx):
+        result = _run(server.delete_lesson(mock_ctx, "lesson-sqlite3-row-factory-001"))
+        assert result is True
+
+    def test_not_found_returns_false_and_logs_warning(self, mock_ctx):
+        result = _run(server.delete_lesson(mock_ctx, "nonexistent-id"))
+        assert result is False
+        mock_ctx.warning.assert_called_once()
+
+    def test_exception_returns_false_and_logs_error(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = _run(server.delete_lesson(mock_ctx, "any-id"))
+        assert result is False
+        mock_ctx.error.assert_called_once()
+
+
+# ── Exception paths ────────────────────────────────────────────────────────
+
+
+class TestExceptionPaths:
+    """Cover all exception-handler branches that return safe fallbacks."""
+
+    def test_log_lesson_usage_defaults_exception_falls_back(self, mock_ctx):
+        with patch(
+            "devcoach.core.db.get_usage_defaults", side_effect=sqlite3.OperationalError("err")
+        ):
+            result = _run(
+                server.log_lesson(
+                    mock_ctx,
+                    id="exc-log-001",
+                    timestamp=datetime.now(UTC).isoformat(),
+                    topic_id="exc_topic",
+                    categories=["test"],
+                    title="Exc test",
+                    level="mid",
+                    summary="exc summary",
+                )
+            )
+        assert result.id == "exc-log-001"
+
+    def test_update_knowledge_exception_raises_and_logs_error(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            with pytest.raises(sqlite3.OperationalError):
+                _run(server.update_knowledge(mock_ctx, "python", 1))
+        mock_ctx.error.assert_called_once()
+
+    def test_get_lessons_exception_returns_empty_list(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.get_lessons()
+        assert result == []
+
+    def test_star_lesson_exception_returns_false(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = _run(server.star_lesson(mock_ctx, "any-id", starred=True))
+        assert result is False
+        mock_ctx.error.assert_called_once()
+
+    def test_submit_feedback_exception_returns_false(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = _run(server.submit_feedback(mock_ctx, "any-id", "know"))
+        assert result is False
+        mock_ctx.error.assert_called_once()
+
+    def test_add_topic_exception_returns_false(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = _run(server.add_topic(mock_ctx, "new_topic", 5))
+        assert result is False
+        mock_ctx.error.assert_called_once()
+
+    def test_remove_topic_exception_returns_false(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = _run(server.remove_topic(mock_ctx, "python"))
+        assert result is False
+        mock_ctx.error.assert_called_once()
+
+    def test_add_group_exception_returns_false(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = _run(server.add_group(mock_ctx, "SomeGroup"))
+        assert result is False
+        mock_ctx.error.assert_called_once()
+
+    def test_remove_group_exception_returns_false(self, mock_ctx):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = _run(server.remove_group(mock_ctx, "SomeGroup"))
+        assert result is False
+        mock_ctx.error.assert_called_once()
+
+    def test_profile_resource_exception_returns_error_dict(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.profile_resource()
+        assert "error" in result
+
+    def test_settings_resource_exception_returns_error_dict(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.settings_resource()
+        assert "error" in result
+
+    def test_recent_lessons_resource_exception_returns_error_list(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.recent_lessons_resource()
+        assert isinstance(result, list)
+        assert "error" in result[0]
+
+    def test_stats_resource_exception_returns_error_dict(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.stats_resource()
+        assert "error" in result
+
+    def test_taught_topics_resource_exception_returns_empty_list(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.taught_topics_resource()
+        assert result == []
+
+    def test_rate_limit_resource_exception_returns_not_allowed(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.rate_limit_resource()
+        assert result["allowed"] is False
+
+    def test_context_resource_exception_returns_error_dict(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.context_resource()
+        assert "error" in result
+
+    def test_onboarding_resource_exception_returns_error_dict(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.onboarding_resource()
+        assert "error" in result
+
+    def test_lesson_resource_exception_returns_error_dict(self):
+        with patch.object(db, "connection", side_effect=sqlite3.OperationalError("err")):
+            result = server.lesson_resource("any-id")
+        assert "error" in result
+
+    def test_devcoach_instructions_exception_returns_fallback(self):
+        with patch(
+            "devcoach.mcp.server.importlib.resources.files", side_effect=Exception("not found")
+        ):
+            result = server.devcoach_instructions()
+        assert "unavailable" in result
+
+
 # ── Entry point ────────────────────────────────────────────────────────────
 
 

{devcoach-0.3.9 → devcoach-0.3.10}/uv.lock

@@ -443,7 +443,7 @@ wheels = [
 
 [[package]]
 name = "devcoach"
-version = "0.3.8"
+version = "0.3.9"
 source = { editable = "." }
 dependencies = [
     { name = "fastapi" },

devcoach-0.3.9/docs/how-it-works.md

@@ -1,112 +0,0 @@
-# How it works
-
-devcoach is a silent technical coach that hooks into every Claude response.
-The diagrams below show the three main flows: session startup, the coaching loop,
-and how a lesson topic is selected.
-
----
-
-## Session startup
-
-At the start of each Claude session devcoach checks whether the user is set up,
-loads prior coaching context, and primes lesson selection before any task is done.
-
-```mermaid
-flowchart TD
-    A([Session starts]) --> B[Read devcoach://onboarding]
-    B --> C{needs_onboarding?}
-    C -- Yes --> D{Existing backup\nto restore?}
-    D -- Yes --> E[Restore backup\n→ mark onboarding done]
-    D -- No --> F[Detect stack\nautomatically or manually]
-    F --> G[Confirm topics + confidence\nPropose groups]
-    G --> H[complete_onboarding]
-    E & H --> I
-    C -- No --> I[Read ~/.devcoach/learning-state.md]
-    I --> J{Notebook\nnon-empty?}
-    J -- Yes --> K[Load patterns, hypotheses\nand recommended angles]
-    J -- No --> L[No prior context\nstart fresh]
-    K & L --> M([Ready to coach])
-```
-
----
-
-## Coaching loop
-
-After every technical task Claude evaluates whether to deliver a lesson.
-The loop is silent when nothing is worth teaching or when the rate limit is reached.
-
-```mermaid
-flowchart TD
-    A([Technical task\ncompleted]) --> B[Read devcoach://rate-limit]
-    B --> C{Allowed?}
-    C -- No\nnormal task --> Z([Silent —\nno lesson])
-    C -- No\nexplicit request --> D
-    C -- Yes --> D[Read profile\ntaught topics\ncoaching notebook]
-    D --> E[Analyse task for\nteachable concepts]
-    E --> F[Select topic\nsee Lesson selection]
-    F --> G{Topic\nfound?}
-    G -- No --> Z
-    G -- Yes --> H[Compose lesson\ncalibrate depth per-topic]
-    H --> I[log_lesson to MCP]
-    I --> J([Lesson appears\nat end of response])
-    J --> K{User\nfeedback}
-    K -- ✅ know --> L{Confidence\nbelow level band?}
-    L -- Yes --> M[submit_feedback\nconfidence +1]
-    L -- No --> N[Skip — already calibrated]
-    K -- ❌ don't know --> O[submit_feedback\nconfidence −1]
-    K -- ⏭ skip --> P[No change]
-    M & N & O & P --> Q{New observation\nworth saving?}
-    Q -- Yes --> R[Write ~/.devcoach/\nlearning-state.md]
-    Q -- No --> S
-    R --> S([Loop ends])
-```
-
----
-
-## Lesson selection
-
-When a teachable concept is found, devcoach picks the highest-priority angle
-and calibrates the lesson level to the **per-topic** confidence score — not an average.
-
-```mermaid
-flowchart TD
-    A([Concepts identified\nin current task]) --> B{Notebook flags\na follow-up angle\nrelevant to this task?}
-    B -- Yes --> P1["① Deliver notebook\nfollow-up"]
-
-    B -- No --> C{Pitfall on a\nprofile topic?}
-    C -- Yes --> P2["② Profile pitfall"]
-
-    C -- No --> D{Interesting pattern\non a profile topic?}
-    D -- Yes --> P3["③ Profile pattern"]
-
-    D -- No --> E{Off-profile concept\nprominent in task?}
-    E -- Yes --> P4["④ Off-profile pitfall"]
-
-    E -- No --> F{Profile topic with\nconfidence < 5?}
-    F -- Yes --> P5["⑤ Knowledge gap"]
-
-    F -- No --> G{Profile topic at\nconfidence 4–6?}
-    G -- Yes --> P6["⑥ Deep-dive"]
-
-    G -- No --> Z([Nothing to teach\n— stay silent])
-
-    P1 & P2 & P3 & P4 & P5 & P6 --> L[Check taught-topics\nno repeats]
-    L --> M{Already taught\nor confidence ≥ 10?}
-    M -- Already taught\nnot confidence 10 --> Z
-    M -- OK or\nconfidence = 10 --> N[Calibrate level\nper-topic confidence]
-    N --> O([Compose and\ndeliver lesson])
-```
-
----
-
-## Depth calibration
-
-The lesson level is determined by the confidence score for the **specific topic being taught**,
-adjusted by observations in the coaching notebook.
-
-| Confidence | Level | Lesson angle |
-|---|---|---|
-| 0 – 3 | Junior | Introduce correct practice, explain from scratch, use analogies |
-| 4 – 6 | Mid | Explain the why, mention trade-offs and alternatives |
-| 7 – 9 | Senior | Edge cases, historical context, architectural implications |
-| 10 | Cutting-edge | Latest developments — ignores level floor and taught-topics filter |