devcoach 0.4.3 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=UltimaPhoenix_dev-coach&metric=coverage)](https://sonarcloud.io/summary/new_code?id=UltimaPhoenix_dev-coach)
 [![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen?logo=node.js)](https://nodejs.org/)
 [![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)
+[![License](https://img.shields.io/badge/license-AGPL%203.0-blue)](LICENSE)
 
 **Stay sharp while your AI does the work.**
 
@@ -512,8 +512,27 @@ CI lints, type-checks, tests (Node 24 & 26), builds, and publishes to npm via **
 
 ## License
 
-Copyright 2026 [UltimaPhoenix](https://github.com/UltimaPhoenix)
+Copyright (C) 2026 [UltimaPhoenix](https://github.com/UltimaPhoenix)
 
-Licensed under the [Apache License, Version 2.0](LICENSE). Free to use, modify, and distribute;
-commercial use and modifications must retain the license, copyright, and attribution notices and state
-any changes. You may not use the `devcoach` name or branding to endorse derived products without permission.
+devcoach is licensed under the [GNU Affero General Public License v3.0](LICENSE) (`AGPL-3.0-only`).
+You may use, modify, and distribute it — **provided that any modified version you distribute, or run
+as a network service, is also released as open source under the AGPL**. A separate **commercial
+license** is available for proprietary/closed use without AGPL's copyleft obligations —
+[open an issue](https://github.com/UltimaPhoenix/dev-coach/issues) to enquire.
+
+### Licensing FAQ
+
+> **devcoach is and stays 100% free** to download, install, and use — for everyone, forever, including
+> at work and on commercial projects. AGPL is *not* a price tag: you only ever pay if you want to ship
+> a **proprietary/closed derivative of devcoach itself** without complying with the AGPL.
+
+**Using devcoach does not put your code under the AGPL.** It runs as a separate process over
+stdio/MCP (`npx -y devcoach mcp`); talking to it at arm's length is not a derivative work — exactly
+like querying an AGPL-licensed database. Your own projects keep whatever license you choose.
+
+- ✅ *"I use devcoach inside Claude Code while building my closed-source startup app."* — Free. Your app stays proprietary, zero obligations.
+- ✅ *"My whole team installs devcoach to get coaching on our internal/commercial repos."* — Free. Using the unmodified tool at a company is fine.
+- ⚠️ *"I fork devcoach, add a feature, and publish the package or host its dashboard as a public service."* — You must release **your modified devcoach** source under the AGPL.
+- 💼 *"I want to embed devcoach in my paid product and keep my changes closed."* — You need a commercial license.
+
+Keep using devcoach as a tool/executable (not as an imported library) and the AGPL never reaches your own code.

package/assets/SKILL.md

@@ -22,14 +22,6 @@ by teaching one thing at a time, at the right moment, based on what they actuall
 
 ---
 
-## Plan-mode suppression
-
-If you are currently in **plan mode** (plan mode is active and `ExitPlanMode` has not
-yet been called in this session), **exit this skill immediately** — do not read any
-devcoach MCP resources, do not run onboarding, do not deliver or log any lesson.
-
----
-
 ## Onboarding flow
 
 The onboarding flow runs inline, immediately before delivering a lesson, whenever
@@ -94,15 +86,17 @@ Once the full topic list is agreed:
   These names emerge from the conversation — there is no fixed list.
 - Show the proposed grouping: *"Here's how I'd organise these — does this look
   right? Any changes?"*
-- When confirmed, call the MCP tool `complete_onboarding`:
+- When confirmed, call the MCP tool `complete_onboarding`, including the personalized
+  `notebook` markdown you compose in Step 4 (so the profile and notebook are saved
+  together):
   ```json
   {
     "topics": { "lang_a": 7, "tool_b": 8, "practice_c": 7 },
-    "groups": { "Languages": ["lang_a"], "DevOps": ["tool_b"], "Version Control": ["practice_c"] }
+    "groups": { "Languages": ["lang_a"], "DevOps": ["tool_b"], "Version Control": ["practice_c"] },
+    "notebook": "# devcoach — Coaching Notebook\n_Last updated: …_\n\n## Observations\n…"
   }
   ```
-- Continue to Step 4. Do not deliver a lesson in this turn — the rate-limit clock
-  starts after onboarding.
+- Do not deliver a lesson in this turn — the rate-limit clock starts after onboarding.
 
 **Rule:** Never ask about groups during topic collection. Propose them only in
 Step 3 after all topics are known.
@@ -121,30 +115,39 @@ Then tell the user **how to change any of it later**, across all three surfaces:
 - **UI** — `devcoach ui` (web dashboard at http://localhost:7860), or ask me to open
   it (the `open_ui` tool).
 
-### Step 4 — Initialise the coaching notebook
+### Step 4 — Compose the coaching notebook (pass it to `complete_onboarding`)
 
-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.
+Do **not** write `learning-state.md` yourself — compose its full markdown and pass it
+as the `notebook` field of the `complete_onboarding` call in Step 3. The tool saves it
+to `~/.devcoach/learning-state.md` atomically with the profile (so it is never empty
+and never created before the user finishes).
+
+Make it **personalized**: draw on everything you know about *this* user — not only this
+onboarding conversation, but how they work across **all their projects** (languages and
+tools they reach for, recurring habits, strengths, and gaps you have observed elsewhere).
+Generic boilerplate is a failure; write specific, real notes. Use this structure:
 
 ```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.]
+[Specific, real notes about this user: background, how they work across their
+projects, confidence style, gaps. Personalized — never generic.]
 
 ## Recurring patterns
-[Leave empty — nothing observed yet.]
+[Patterns you have noticed in how they build, debug, or structure work.]
 
 ## Recommended focus
 [Topics the user flagged as priorities or areas of uncertainty.]
 
 ## Open hypotheses
-[Leave empty — nothing to track yet.]
+[Things to watch for and confirm in future sessions.]
 ```
 
+If re-onboarding or returning, fold prior notes into the markdown you pass —
+`complete_onboarding` overwrites the file with exactly what you provide.
+
 ---
 
 ## Session context
@@ -342,21 +345,17 @@ it is central to the task and no applicable profile topic exists.
 
 ## 4. Lesson format
 
-Append the lesson **at the bottom of the response**, rendered as a card: a titled
-top band, the content **indented as a blockquote**, and a bottom band echoing the
-topic and level.
+Append the lesson **at the bottom of the response**, rendered as a card: a titled top
+band, the lesson as **plain markdown**, and a bottom band echoing the topic and level.
 
 ```
 ### ──────── 🎓 devcoach ────────
-> [Category] · Level: [Junior|Mid|Senior]
->
-> **[Lesson title]**
->
-> [Body: 3–6 paragraphs. Concise, practical, with a code example if useful.
-> Explain the WHY, not just the what. Connect it to the task just completed.]
->
-> 💡 *Senior tip:* [One sentence a senior would say to a junior on this topic]
+**[Lesson title]** · [Category] · [Junior|Mid|Senior]
 
+[Body: 3–6 paragraphs. Concise, practical, with a code example if useful.
+Explain the WHY, not just the what. Connect it to the task just completed.]
+
+💡 *Senior tip:* [One sentence a senior would say to a junior on this topic]
 ### ──────── [topic] · [level] ────────
 ```
 
@@ -365,16 +364,16 @@ Card rules:
   U+2500) around a centered title — the heading makes Claude Code colour the whole
   line. Do **not** use `---` (a real rule can't carry a title). Aim for a band
   width of ~34 characters and keep the top and bottom bands the same width.
-- Every content line is prefixed with `> ` (blank separators become a bare `>`).
-- Leave **one blank line before the bottom band** so the blockquote closes cleanly.
+- The body is **plain markdown** between the bands — do **not** prefix lines with `> `
+  (a per-line blockquote breaks on multi-paragraph bodies and fenced code blocks).
 
-If `AskUserQuestion` is **not** available (Claude Desktop / claude.ai web), append
-this block — plain list format so the interface renders it as clickable buttons:
+**Display vs storage:** the card above is for chat only. When you call `log_lesson`,
+the `body` is **clean markdown** — no bands, no `> ` blockquote, and no title/`Category ·
+Level` line (those go in their own fields). See Step 1 below.
 
-Did that land?
-- ✅ know — got it
-- ❌ don't know — need to revisit
-- ⏭️ skip
+**Feedback is handled by the MCP protocol** — `log_lesson` runs an elicitation
+(*"Did that land?"* → know / dont_know / skip) when the client supports it. Do **not**
+render a feedback question yourself; just deliver the card and call `log_lesson`.
 
 **Tone:** direct, like a senior colleague explaining during a code review.
 Not academic, not verbose. Gets straight to the point.
@@ -396,7 +395,7 @@ Call `log_lesson` right after delivering the lesson, without waiting for feedbac
   "title": "Lesson title",
   "level": "junior|mid|senior",
   "summary": "One line — what was taught",
-  "body": "The full lesson text exactly as delivered — all paragraphs, code blocks, and the senior tip. This is what the web UI displays on the lesson detail page.",
+  "body": "ONLY the lesson prose + the 💡 Senior tip, as CLEAN markdown — no card bands, no '>' blockquote, and do NOT repeat the title or the 'Category · Level' line (those are their own fields).",
   "task_context": "Brief description of the task that triggered it"
 }
 ```
@@ -435,6 +434,19 @@ Did that land?
 
 ---
 
+### Step 1c — Update the coaching notebook (only at every-10-lesson checkpoints)
+
+The notebook's observations are refreshed only at **checkpoints — every 10 delivered
+lessons**. The `lesson-ready` hook owns the count and tells you whether the current lesson
+is a checkpoint; do not count yourself. **At a checkpoint**, after feedback is known, call
+`update_notebook` with the full revised `learning-state.md` markdown — note what the user
+absorbed (`know`) or should revisit (`dont_know`), any new recurring pattern, and updated
+open hypotheses, keep the prior notes, and record `(updated after N lessons)`. **Between
+checkpoints, do not touch the notebook.** This keeps `devcoach://notebook` driving future
+lesson selection without churning it on every lesson.
+
+---
+
 ### Step 2 — Record feedback and conditionally adjust confidence (fallback only)
 
 When `log_lesson` returned `feedback: null` (elicitation declined or not supported),