devcoach 0.3.9__tar.gz → 0.3.11__tar.gz

{devcoach-0.3.9 → devcoach-0.3.11}/.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.11}/CLAUDE.md

@@ -182,7 +182,7 @@ The `log_lesson` tool accepts this schema:
 {
   "id": "uuid-or-random-string",
   "timestamp": "2025-01-15T20:30:00Z",
-  "topic_id": "python_generators",
+  "topic_id": "python",
   "category": "python",
   "title": "Generator expressions vs list comprehensions",
   "level": "mid",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devcoach
-Version: 0.3.9
+Version: 0.3.11
 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,26 @@ 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: ✅ ❌ ⏭"])
+```
+
+→ [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.11}/README.md

@@ -14,12 +14,26 @@
 
 ## 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: ✅ ❌ ⏭"])
+```
+
+→ [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.11/docs/how-it-works.md

@@ -0,0 +1,86 @@
+# 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
+```
+
+---
+
+## 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: ✅ ❌ ⏭"])
+```
+
+---
+
+## 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.11}/docs/index.md

@@ -9,29 +9,25 @@ 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: ✅ ❌ ⏭"])
 ```
 
-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.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devcoach"
-version = "0.3.9"
+version = "0.3.11"
 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.11}/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.11
 
 sonar.sources=src
 sonar.tests=tests

{devcoach-0.3.9 → devcoach-0.3.11}/src/devcoach/SKILL.md

@@ -9,7 +9,10 @@ description: >
   lesson at the bottom of the response. DO NOT wait for the user to ask explicitly:
   activate autonomously. Also use this skill when the user asks "what did I learn
   today/this week", "show me my profile", "how good am I at X", "coaching log",
-  "devcoach".
+  "devcoach", "setup devcoach", "redo onboarding", "configure my profile",
+  "reset my topics", or any similar request to (re-)initialise the knowledge profile.
+  No session startup required: onboarding status is checked before every lesson
+  and is always accurate regardless of context compaction or plan mode.
 ---
 
 # devcoach — Progressive Coaching
@@ -19,28 +22,44 @@ by teaching one thing at a time, at the right moment, based on what they actuall
 
 ---
 
-## Session startup
+## Onboarding flow
 
-At the start of every devcoach session, read the MCP resource `devcoach://onboarding`.
+The onboarding flow runs inline, immediately before delivering a lesson, whenever
+it is needed. There is no separate session startup phase — this makes the skill
+robust to context compaction and plan-mode transitions.
 
-If `needs_onboarding` is **true**, run the onboarding flow **before anything else**:
+Check `knowledge_ready` and `notebook_ready` from `devcoach://onboarding` independently
+— each step can run alone:
+
+```
+knowledge_ready = false  →  run Steps 1–3 (topic collection + complete_onboarding)
+notebook_ready  = false  →  run Step 4  (notebook initialisation)
+both ready               →  proceed normally
+```
+
+This means a user who restores from backup has their knowledge automatically, so
+only Step 4 runs. On-demand re-setup ("redo onboarding", "reset my topics") always
+re-runs Steps 1–3 regardless of `knowledge_ready`.
 
 ### Step 1 — Offer to restore from backup
 Ask once: *"Do you have an existing devcoach backup to restore? If yes, provide the
 file path — otherwise I'll help you build your profile from scratch."*
 
-If a path is provided: call `restore` (CLI) with the file. When complete, call the
-MCP tool `complete_onboarding` with empty maps to mark setup as done
-(the restored profile is already in the DB). Skip the remaining steps.
+If a path is provided: call `restore` (CLI) with the file. The restore process
+brings back knowledge entries automatically — no further DB steps needed. Re-read
+`devcoach://onboarding` after restore; if `knowledge_ready` is now true, skip to
+Step 4. If `notebook_ready` is also true, proceed normally.
 
 ### Step 2 — Choose setup mode
 Ask: *"Would you like me to detect your tech stack automatically from this project,
 or set it up manually through a conversation?"*
 
 **Automatic mode:**
-- Read `detected_stack` from `devcoach://onboarding` and present those topics in a
-  clear list with their suggested confidence scores.
-- For each, ask the user to confirm or adjust: *"Looks right? Or enter 1–10."*
+- Read `devcoach://onboarding` and present a merged topic list: `detected_stack`
+  (auto-detected from project files) enriched with relevant entries from
+  `default_topics` (the project's default knowledge map).
+- Show each topic with its suggested confidence. Ask the user to confirm, adjust,
+  or remove each: *"Looks right? Or enter 1–10 to change it."*
 - After the list, ask: *"Anything else I missed? List any tools, languages,
   frameworks, or practices you work with regularly."* — add each with a confidence.
 
@@ -48,9 +67,9 @@ or set it up manually through a conversation?"*
 - Have a free-form conversation: *"Tell me about the technologies you work with
   day-to-day. For each one I'll ask how confident you are:
   1–3 = still learning · 4–6 = comfortable · 7–9 = strong · 10 = expert."*
-- Probe across domains: programming languages, frameworks, databases, infrastructure,
-  version control practices, branching strategies, CI/CD pipelines, testing,
-  architecture patterns, etc. Keep probing until the user says they're done.
+- Use `default_topics` as a domain checklist: probe areas the user hasn't mentioned
+  (languages, frameworks, databases, infrastructure, version control, CI/CD, testing,
+  architecture patterns, etc.). Keep probing until the user says they're done.
 
 ### Step 3 — Propose groups and save
 Once the full topic list is agreed:
@@ -66,18 +85,44 @@ Once the full topic list is agreed:
     "groups": { "Languages": ["lang_a"], "DevOps": ["tool_b"], "Version Control": ["practice_c"] }
   }
   ```
-- Confirm setup is complete and continue normally.
+- Confirm setup is complete and continue to Step 4.
 
 **Rule:** Never ask about groups during topic collection. Propose them only in
 Step 3 after all topics are known.
 
+### Step 4 — Initialise the coaching notebook
+
+Write `~/.devcoach/learning-state.md` with observations from this conversation.
+If the file already exists (returning user or post-restore), integrate new
+observations without overwriting prior entries.
+
+```markdown
+# devcoach — Coaching Notebook
+_Last updated: [ISO timestamp]_
+
+## Observations
+[User background, confidence style, or gaps noted during onboarding.
+Leave empty if nothing notable was observed.]
+
+## Recurring patterns
+[Leave empty — nothing observed yet.]
+
+## Recommended focus
+[Topics the user flagged as priorities or areas of uncertainty.]
+
+## Open hypotheses
+[Leave empty — nothing to track yet.]
+```
+
 ---
 
 ## Session context
 
-After the onboarding check, read the file `~/.devcoach/learning-state.md`.
+Before the first lesson in this context window, read `~/.devcoach/learning-state.md`
+if it exists and has not already been loaded. Use its content for all subsequent
+lessons in this window — do not re-read it on every lesson.
 
-If it exists and is non-empty, load it as your coaching context for this session:
+If it exists and is non-empty, load it as your coaching context:
 - Resume patterns and hypotheses you noted in previous sessions
 - Prioritise angles you flagged as still pending
 - Avoid re-covering ground you noted as absorbed
@@ -93,6 +138,8 @@ Do not mention this file to the user. It is an internal coaching tool.
 
 Always read these MCP resources before deciding to teach:
 
+- `devcoach://onboarding` — check `knowledge_ready` and `notebook_ready`; if either
+  is false, run the onboarding flow (see above) before delivering the lesson
 - `devcoach://rate-limit` — check `allowed`; if false, skip entirely
 - `devcoach://taught-topics` — never repeat a topic already in this list
 - `devcoach://profile` — use confidence scores to pick depth, and treat each topic
@@ -103,6 +150,10 @@ Always read these MCP resources before deciding to teach:
   - **Open hypotheses** relevant to the current task → watch for confirming/refuting evidence
   - **Recurring patterns** → use them to calibrate depth and angle, not just the confidence score
 
+If `devcoach://profile` returns an **empty knowledge map**, do not deliver a lesson.
+Run the onboarding flow first (Steps 1–3 of Session startup), then resume lesson
+delivery once `complete_onboarding` has been called.
+
 ---
 
 ## Lesson levels
@@ -146,6 +197,14 @@ Evaluate whether to append a lesson **after every technical response** that invo
 - DB queries, optimisations, migrations
 - Security, performance, scalability
 - CLI, scripting, automation
+- Completing a git commit — the commit is a natural unit-of-work checkpoint;
+  treat it as a **high-priority** lesson trigger
+
+**Commit checkpoint:** When a successful `git commit` is the trigger, the staged
+diff and commit message visible in the preceding Bash output are the primary
+teaching context — they capture exactly what was written and why. Use the changed
+code (not the commit mechanics themselves) as the basis for lesson selection,
+exactly as you would for any other code task.
 
 **Do not activate** for: pure factual questions, web searches, translations, creative
 writing, non-technical conversation.
@@ -288,7 +347,7 @@ Call `log_lesson` right after delivering the lesson, without waiting for feedbac
 {
   "id": "unique-slug-or-uuid",
   "timestamp": "2026-04-27T14:30:00Z",
-  "topic_id": "snake_case_identifier",
+  "topic_id": "topic",
   "categories": ["the_topic_category", "architecture"],
   "title": "Lesson title",
   "level": "junior|mid|senior",
@@ -298,45 +357,44 @@ Call `log_lesson` right after delivering the lesson, without waiting for feedbac
 }
 ```
 
+**`topic_id` naming:** use the single most characterizing word for the domain
+(e.g. `sqlite`, `python`, `docker`). For compound concepts with no single-word
+equivalent, keep the essential part — `ci_cd_pipeline_design` → `ci_cd`. Never
+more than 3 words.
+
 Git metadata (`project`, `repository`, `branch`, `commit_hash`, `folder`,
 `repository_platform`) is **auto-detected server-side**. Do not run git commands
 manually. Omitting these fields is correct and will not reduce lesson quality.
 
 `log_lesson` returns the saved `Lesson` object with all resolved fields.
 
-### Step 1b — Collect feedback interactively
+### Step 1b — Feedback is collected by log_lesson
 
-**Claude Code (CLI / IDE):** `AskUserQuestion` is available in your tool list.
-Call it immediately after `log_lesson` returns, before the user sends another message:
+`log_lesson` asks "Did that land?" via an interactive MCP elicitation prompt.
+The user selects know / don't know / skip directly in the client UI — no text
+parsing required.
 
-```
-question : "Did that land?"
-options  : ["✅ know — got it", "❌ don't know — need to revisit", "⏭️ skip"]
-```
+Read the `feedback` field of the returned `Lesson` object:
 
-Wait for the reply, then go to Step 2 with the result.
-Do **not** append the text prompt in the lesson body — `AskUserQuestion` replaces it.
+- `"know"` or `"dont_know"` → feedback was given and confidence was already
+  adjusted server-side. Go to Step 3 (starring). **Do not call `submit_feedback`.**
+- `null` / absent → elicitation was declined or not supported by this client.
+  Fall back: append the text prompt below, capture the reply in the next message
+  turn, then call `submit_feedback` manually (Step 2).
 
-**Claude Desktop / claude.ai web:** `AskUserQuestion` is not in your tool list.
-After the lesson body, end the response with this exact block — the interface will
-render the options as clickable buttons:
+**Fallback prompt (only when feedback is null):**
 
 Did that land?
 - ✅ know — got it
 - ❌ don't know — need to revisit
 - ⏭️ skip
 
-Keep labels short (≤ 5 words). Do not wrap in a blockquote or code fence — plain
-list format is what the client renders as buttons.
-When the user clicks or types a reply that matches feedback (know / don't know / skip,
-✅, ❌, 1 / 2 / 3), treat it as feedback before handling any new request in that message.
-
 ---
 
-### Step 2 — Record feedback and conditionally adjust confidence
+### Step 2 — Record feedback and conditionally adjust confidence (fallback only)
 
-When feedback is received (via `AskUserQuestion` reply or next-message fallback), call
-`submit_feedback` according to this table:
+When `log_lesson` returned `feedback: null` (elicitation declined or not supported),
+collect feedback via the fallback prompt and call `submit_feedback` according to this table:
 
 | User response | Condition | Action |
 |---|---|---|
@@ -466,10 +524,46 @@ When the user asks about their learning journey, use the MCP tools and resources
 
 ## 7. Dynamic calibration
 
-Every 10 lessons delivered, re-evaluate the profile:
-- If the user never showed gaps on X in 10 sessions → raise confidence via `update_knowledge`
-- If the user received 3+ lessons on the same topic → consider raising the level
-- If the user's questions on X become consistently more advanced → raise confidence by 2
+Triggered after every `log_lesson` where `total_lessons % 10 == 0`.
+
+**Step 1 — Fetch the window**
+
+Call `get_lessons()` (default `limit=10`, newest first) to get the last 10 lessons.
+Read `devcoach://profile` for the current knowledge map.
+
+**Step 2 — Per-topic signal analysis**
+
+Group the 10 lessons by `topic_id`. For each topic that appeared:
+
+| Signal | Condition | Action |
+|---|---|---|
+| Consistent mastery | All feedback `know`, no `dont_know` | `update_knowledge(topic, +1)` if confidence < 9 |
+| Persistent gap | 2+ lessons on same topic, any `dont_know` | `update_knowledge(topic, -1)` if confidence > 1 |
+| Recurring topic | 3+ lessons on same topic, mixed or no feedback | no confidence change — note in notebook |
+| New topic | `topic_id` absent from `devcoach://profile` | `add_topic` — see Step 3 |
+
+Apply at most **one** `update_knowledge` call per topic per calibration run.
+Never call `update_knowledge` on a topic with confidence 10 (already mastered).
+
+**Step 3 — New topic discovery**
+
+For each lesson whose `topic_id` is not in `devcoach://profile`:
+- 2+ lessons share this `topic_id` in the window → call `add_topic(topic_id, confidence=5)`;
+  assign it to the same group as the closest related existing topic, or `"Other"` if unclear.
+- Only 1 lesson on this `topic_id` → note under **Open hypotheses** in the notebook; do not add yet.
+
+**Step 4 — Update the coaching notebook**
+
+Read `~/.devcoach/learning-state.md`. Merge findings into the relevant sections:
+
+- **Recurring patterns** — append any `topic_id` that appeared 3+ times, with its count
+  and whether feedback was positive, negative, or absent.
+- **Recommended focus** — replace or append topics that had 2+ `dont_know` in the window.
+- **Open hypotheses** — add single-occurrence new topics not yet in the profile;
+  remove hypotheses confirmed (topic added) or disproved (not seen in 20+ subsequent lessons).
+
+Always update `_Last updated` to the current ISO timestamp.
+Never delete prior entries — integrate new observations alongside existing ones.
 
 ---
 
@@ -477,14 +571,16 @@ Every 10 lessons delivered, re-evaluate the profile:
 
 - **Never break the flow** of the main response — the lesson is always at the bottom
 - **Never mention** that you skipped a lesson due to rate limit
-- **Always read** `devcoach://rate-limit` before deciding to teach
-- **Always read** `devcoach://taught-topics` before selecting a lesson topic
-- **Always read** `devcoach://profile` to calibrate level and topic selection
+- **Always read before deciding to teach:** `devcoach://onboarding`,
+  `devcoach://rate-limit`, `devcoach://taught-topics`, `devcoach://profile`
+- Onboarding is checked before every lesson — no separate session startup.
+  Works correctly after context compaction and after plan-mode transitions.
 - The lesson should feel **natural and contextual**, not a mechanical add-on
 - If there is nothing interesting to teach → stay silent. Better nothing than forced.
-- In Claude Code: use `AskUserQuestion` after `log_lesson` — do not append the text prompt
-- In Claude Desktop / web: append the text prompt; capture reply in the next message turn
-- Never call `update_knowledge` directly after `log_lesson` — wait for feedback
-- `submit_feedback` handles the confidence delta; skip it entirely on no response
+- Feedback is handled inside `log_lesson` via MCP elicitation — only call
+  `submit_feedback` manually if `log_lesson` returned `feedback: null`
+- Never call `update_knowledge` directly after `log_lesson` — feedback handles the delta
 - Propose starring when `don't know` on mid/senior, or when the topic recurs 2+ times
 - Never star a lesson silently — always ask first
+- After each `log_lesson`, check `total_lessons` from `devcoach://rate-limit`;
+  when `total_lessons % 10 == 0`, run the dynamic calibration from section 7

{devcoach-0.3.9 → devcoach-0.3.11}/src/devcoach/cli/commands.py

@@ -369,10 +369,11 @@ def cmd_backup(args: argparse.Namespace) -> None:
 
     out_path = Path(args.output)
     out_path.write_bytes(data)
+    notebook_note = " + notebook" if db.LEARNING_STATE_PATH.exists() else ""
     console.print(
         f"[green]Backup saved:[/green] {out_path}  "
         f"([cyan]{lessons_count}[/cyan] lessons, "
-        f"[cyan]{knowledge_count}[/cyan] topics)"
+        f"[cyan]{knowledge_count}[/cyan] topics{notebook_note})"
     )
 
 
@@ -398,6 +399,8 @@ def cmd_restore(args: argparse.Namespace) -> None:
     if result["invalid"]:
         parts.append(f"[red]{result['invalid']}[/red] rejected (invalid)")
     console.print(f"[green]✓[/green] Lessons: {', '.join(parts)}")
+    if result["learning_state"]:
+        console.print("[green]✓[/green] Notebook restored")
 
 
 def _claude_desktop_config() -> Path:
@@ -543,6 +546,7 @@ def cmd_setup(_args: argparse.Namespace) -> None:
             db.set_setting(conn, "onboarding_completed", "1")
         console.print(
             f"[green]✓[/green] Restored: {result['topics']} topics, {result['lessons']} lessons"
+            + (", notebook" if result["learning_state"] else "")
         )
         console.print("[green]Setup complete![/green]")
         return

{devcoach-0.3.9 → devcoach-0.3.11}/src/devcoach/core/coach.py

@@ -50,10 +50,14 @@ def check_rate_limit(conn: sqlite3.Connection) -> RateLimitResult:
                 remaining = settings.min_gap_minutes - elapsed_minutes
                 gap_h, gap_m = divmod(settings.min_gap_minutes, 60)
                 rem_h, rem_m = divmod(int(remaining), 60)
+                if elapsed_minutes < 0:
+                    ago_text = f"in {-elapsed_minutes:.0f}m (future timestamp)"
+                else:
+                    ago_text = f"{elapsed_minutes:.0f}m ago"
                 return RateLimitResult(
                     allowed=False,
                     reason=(
-                        f"Too soon: last lesson {elapsed_minutes:.0f}m ago, "
+                        f"Too soon: last lesson {ago_text}, "
                         f"minimum interval is {gap_h}h {gap_m}m "
                         f"({rem_h}h {rem_m}m remaining)"
                     ),