devcoach 0.8.3 → 0.9.1

package/README.md

@@ -16,7 +16,7 @@
 
 **Stay sharp while your AI does the work.**
 
-devcoach connects to Claude Code, Claude Desktop, Cursor, Windsurf, and other MCP-compatible tools. After every task you complete, it delivers a short targeted lesson calibrated to what you already know — no generic tutorials, no repeated topics, nothing to open.
+devcoach connects to Claude Code, Claude Desktop, Gemini CLI *(beta)*, Codex CLI *(beta)*, Cursor, Windsurf, and other MCP-compatible tools. After every task you complete, it delivers a short targeted lesson calibrated to what you already know — no generic tutorials, no repeated topics, nothing to open.
 
 Everything runs **locally**. No data leaves your machine. One SQLite file at `~/.devcoach/coaching.db`.
 
@@ -67,7 +67,7 @@ Everything stays on your machine. No telemetry, no accounts, no calls home. Just
 
 ## Installation
 
-devcoach runs **locally** — a stdio MCP server that stores everything in `~/.devcoach/coaching.db` on the machine where your agent runs. It works in **Claude Code** and **Claude Desktop**, but **not** on claude.ai web (which only supports hosted/remote connectors).
+devcoach runs **locally** — a stdio MCP server that stores everything in `~/.devcoach/coaching.db` on the machine where your agent runs. It works in **Claude Code**, **Claude Desktop**, **Gemini CLI** *(beta)*, and **Codex CLI** *(beta)*, but **not** on claude.ai web (which only supports hosted/remote connectors).
 
 **Requires Node.js ≥ 24** (devcoach uses the embedded `node:sqlite` module, available only from Node 24 onward).
 
@@ -191,6 +191,32 @@ after each turn whether a lesson is due, `prompt-hook` primes the model up front
 
 </details>
 
+<details>
+<summary><strong>Gemini CLI</strong> — full coaching loop (hooks + skill) — <strong>Beta</strong></summary>
+
+One command registers the MCP server, the `AfterAgent`/`BeforeAgent` lesson hooks, and the coaching skill:
+
+```bash
+npx -y devcoach install --gemini
+```
+
+Or install the bundled **Gemini extension** instead: download `devcoach-gemini-extension-<version>.zip` from the [latest release](https://github.com/UltimaPhoenix/dev-coach/releases/latest), unzip, then `gemini extensions install <folder>`. Pick **one** of the two (both provide the same hooks; devcoach detects the extension and skips duplicates). Details: [docs/install/gemini-cli.md](docs/install/gemini-cli.md).
+
+</details>
+
+<details>
+<summary><strong>Codex CLI</strong> — full coaching loop (hooks + skill) — <strong>Beta</strong></summary>
+
+One command registers the MCP server (`codex mcp add`), the `Stop`/`UserPromptSubmit` lesson hooks (`~/.codex/hooks.json`), and the coaching skill (`~/.agents/skills/`):
+
+```bash
+npx -y devcoach install --codex
+```
+
+Codex asks you to **trust** the new hooks once on the next run — approve them or coaching stays inert. Details: [docs/install/codex.md](docs/install/codex.md).
+
+</details>
+
 <details>
 <summary><strong>Other MCP agents</strong> (Cursor, Windsurf, Cline, Continue, Zed…)</summary>
 
@@ -215,7 +241,7 @@ Add this to your agent's MCP config file:
 | **Continue.dev** | `~/.continue/config.json` → `mcpServers` |
 | **Zed** | `.zed/settings.json` → `context_servers` |
 
-> Stop hooks (automatic lesson delivery after each task) are Claude Code-specific. Other agents have full access to all MCP tools and resources — coaching can be triggered manually or by prompting your agent.
+> Stop hooks (automatic lesson delivery after each task) exist for Claude Code, Gemini CLI, and Codex CLI. The agents in this table have full access to all MCP tools and resources — coaching can be triggered manually or by prompting your agent.
 
 </details>
 
@@ -432,7 +458,7 @@ Run `devcoach install` to re-register the server with Claude Code or Claude Desk
 
 **"Coaching isn't firing / no lessons appear"**
 
-Run **`devcoach doctor`** — it checks the whole wiring (Node version, hook entries in `~/.claude/settings.json`, skill, MCP registration, database, pacing counters, rate limit) and ends with a verdict explaining exactly why the next stop would or wouldn't cue a lesson. Remember that pacing is intentionally quiet: with the defaults a lesson is cued only after `nudge_every` interactions in a session and within the rate limits — that's by design, not a bug. For a live trace, set `DEVCOACH_HOOK_DEBUG=1` and watch `~/.devcoach/hook.log`: every hook run appends one line with its decision (`paced (3/10)`, `rate limited: …`, `cue`). Hooks are Claude Code-specific; other agents (Cursor, Windsurf, Cline) don't support them — coaching is available on demand via MCP tools or manual prompting.
+Run **`devcoach doctor`** — it checks the whole wiring (Node version, hook entries in `~/.claude/settings.json` — plus `~/.gemini/settings.json` and `~/.codex/hooks.json` when present — skill, MCP registration, database, pacing counters, rate limit) and ends with a verdict explaining exactly why the next stop would or wouldn't cue a lesson. Remember that pacing is intentionally quiet: with the defaults a lesson is cued only after `nudge_every` interactions in a session and within the rate limits — that's by design, not a bug. For a live trace, set `DEVCOACH_HOOK_DEBUG=1` and watch `~/.devcoach/hook.log`: every hook run appends one line with its decision (`paced (3/10)`, `rate limited: …`, `cue`). Hooks exist for Claude Code, Gemini CLI *(beta)*, and Codex CLI *(beta)*; other agents (Cursor, Windsurf, Cline) don't support them — coaching is available on demand via MCP tools or manual prompting.
 
 **"Stop hook error occurred" next to a lesson**
 

package/assets/SKILL.md

@@ -1,13 +1,19 @@
 ---
 name: devcoach
 description: >
-  Personal coaching engine: deliver, log, and manage progressive technical lessons.
-  Use when a devcoach hook cue asks for a lesson; when the user asks about their
-  learning — "what did I learn today/this week", "show my profile", "how good am I
-  at X", "coaching log", "lessons to revisit" — or asks to set up or reconfigure
-  devcoach ("setup devcoach", "redo onboarding", "reset my topics"); and after
-  completing a substantial technical task (code, review, commit, debugging, config,
-  queries, infra) to evaluate whether ONE lesson is due.
+  Use for the user's personal learning record and coaching data managed by
+  devcoach. Trigger when: (1) the user mentions devcoach in any form — setting it
+  up, redoing onboarding, resetting topics, or reviewing/rebuilding their profile
+  or notebook; (2) the user asks about their own learning or skill level — what
+  they learned recently, their coaching log or lesson history (by period, starred,
+  or marked don't-know), how good they are at a technology, lessons to revisit,
+  or whether new tech from their recent work should be tracked; (3) a devcoach
+  hook cue requests a lesson; (4) you just completed substantial technical work
+  (code, review, commit, debugging, config, queries, infra) — then evaluate
+  silently whether ONE lesson is due, even when coaching is never mentioned.
+  Do NOT use for ordinary development tasks on code, apps, or documents that
+  merely contain words like profile, lessons, or notebook — only when the subject
+  is the user's own coaching data.
 ---
 
 # devcoach — Progressive Coaching
@@ -17,10 +23,11 @@ by teaching one thing at a time, at the right moment, based on what they actuall
 
 The three hard rules, before anything else:
 
-1. **The lesson card is printed as visible reply text BEFORE calling `log_lesson` —
-   and only once, ever.** If you suspect the card was never printed, do NOT self-correct
-   by re-printing: a devcoach hook verifies visibility after the turn and recovers a
-   missing card itself. A card printed twice is an error.
+1. **The lesson card is printed as plain reply text BEFORE calling `log_lesson` —
+   and only once, ever.** The user sees only text you write directly in the reply:
+   the body passed to `log_lesson` is INVISIBLE to them, and composing it does not
+   count as showing the card. If, after `log_lesson` returns, your reply does not
+   contain the card as written text, write it then — once. Never write it twice.
 2. **The card ends the reply.** After `log_lesson` returns, output nothing else — no
    "lesson logged", no summary. The card is the last visible text of the turn.
 3. **A cue you decline is a `skip_lesson` call.** If a devcoach hook asked for a lesson
@@ -37,6 +44,14 @@ user explicitly asks to (re-)initialise their profile — read `references/onboa
 in this skill's directory and follow it. Do not deliver a lesson in the same turn as
 `complete_onboarding`; end the response after confirming setup.
 
+## Review & rebuild
+
+When the user asks to review or rebuild their profile or notebook — "review my
+profile/notebook", "rebuild/refresh my notebook", "refresh my profile from my
+projects", "any new tech I should track?" — read `references/review.md` in this
+skill's directory and follow it. Those flows are incremental and non-destructive;
+only an explicit "redo onboarding" goes through `references/onboarding.md`.
+
 ## Before delivering a lesson
 
 Read the **`devcoach://briefing`** MCP resource — ONE silent read returns everything
@@ -83,6 +98,11 @@ Priority order:
 Tiebreaker: always prefer the profile topic. Never teach off-context lessons, and
 never pitch **below** the user's confidence band on that topic.
 
+When the task's real stack is **not tracked** in the profile, prefer offering to
+track it (Profile expansion below) over teaching it by analogy to a tracked
+topic — analogy filing records the lesson under the wrong stack and can hide an
+entire technology from the coaching record for months.
+
 **Depth per confidence** (per-topic, never an average): `0–3` junior — explain from
 scratch, analogies, no jargon · `4–6` mid — the why, alternatives, trade-offs ·
 `7–9` senior — edge cases, production trade-offs, historical context · `10` —
@@ -129,10 +149,13 @@ know / dont_know / skip) — never render a feedback question yourself. Read the
 
 - `"know"` / `"dont_know"` → confidence already adjusted server-side. Done.
 - `null` → elicitation unsupported/declined. Append the text prompt "Did that land?
-  ✅ know · ❌ don't know · ⏭ skip", collect the reply next turn, then call
-  `submit_feedback(id, value)` — but only when confidence is below the lesson's band
-  for "know" (within/above band → already calibrated, skip the call). Never call
-  `update_knowledge` on top of feedback.
+  ✅ know · ❌ don't know · ⏭ skip" — and this line may only ever appear DIRECTLY
+  BENEATH the card's closing band in your reply text. If the card is not right
+  above it (the body you passed to log_lesson is invisible to the user — composing
+  it is not printing it), write the full card first, then this line. Collect the
+  reply next turn, then call `submit_feedback(id, value)` — but only when
+  confidence is below the lesson's band for "know" (within/above band → already
+  calibrated, skip the call). Never call `update_knowledge` on top of feedback.
 
 **Starring:** after feedback, if it was `dont_know` on a mid/senior lesson, or
 `get_lessons({search: topic_id})` shows 2+ lessons on the topic, offer *"Want to save

package/assets/references/onboarding.md

@@ -21,20 +21,30 @@ 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 — Ask how to set up (always ask; never pick for the user)
+## Step 1 — Ask how to set up (strongly recommend Automatic; never pick for the user)
 
-Present a single choice using the client's question UI (e.g. AskUserQuestion in
-Claude Code). Offer exactly three options and mark **Automatic** as recommended:
+Read `devcoach://onboarding` FIRST — its `detected_stack`, `detected_projects`, and
+`scanned_projects` come from a scan of the user's **full Claude Code history** (every
+project Claude has worked in, ranked by recent activity), not just the current folder.
 
-- **Automatic (Recommended)** — detect the tech stack from this project and build a
-  profile from it.
+Then present a single choice using the client's question UI (e.g. AskUserQuestion in
+Claude Code). Offer exactly three options, and make **Automatic** the first option,
+**strongly recommended**, with its description citing the real evidence — name the
+project count and 2–3 detected topics with where they were seen, e.g. *"I scanned 9
+of your Claude Code projects and found TypeScript (dev-coach), Java (discordbot,
+over-night-runner), Swift (blueprince) — I can build your profile from that."*:
+
+- **Automatic (Strongly recommended)** — build the profile from the detected
+  history-wide stack; the user only confirms and adjusts confidences.
 - **Guided** — a step-by-step conversation to map knowledge, confidence levels, and
   topic groups (thorough, interactive).
 - **Import backup** — restore knowledge, lessons, and settings from an existing
   backup file.
 
-Do **not** default to Automatic silently — surface the choice and wait for the user's
-answer before proceeding.
+When the scan found nothing (`scanned_projects` 0 or an empty `detected_stack`),
+present Automatic without the evidence sentence — it falls back to the current
+project's files. Do **not** default to Automatic silently — surface the choice and
+wait for the user's answer before proceeding.
 
 **If Import backup:** ask for the file path and call `restore` (CLI) with it. Restore
 brings back knowledge entries automatically — no further DB steps needed. Re-read
@@ -44,11 +54,14 @@ Step 4. If `notebook_ready` is also true, proceed normally.
 ## Step 2 — Collect topics for the chosen mode
 
 **Automatic mode:**
-- 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."*
+- Present a merged topic list: `detected_stack` (history-wide, already merged with
+  the current project) enriched with relevant entries from `default_topics` (the
+  project's default knowledge map).
+- Show each topic with its suggested confidence **and its provenance** from
+  `detected_projects` — e.g. *"java 6 — seen in discordbot, over-night-runner"*.
+  Weight what you emphasise by `prompt_count` and `last_activity`: a stack the user
+  works in daily deserves more topics than a one-off experiment. 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.
 
@@ -105,9 +118,11 @@ as the `notebook` field of the `complete_onboarding` call in Step 3. The tool sa
 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).
+Make it **personalized**: draw on everything you know about *this* user — this
+onboarding conversation, plus the real cross-project data in `detected_projects`
+(per-project stacks, activity volume and recency, and each project's auto-`memory`
+excerpt — distilled facts about how the user actually works). Cite project names and
+observed habits; never quote prompt text (it is not in the data, by design).
 Generic boilerplate is a failure; write specific, real notes. Use this structure:
 
 ```markdown

package/assets/references/review.md

@@ -0,0 +1,67 @@
+# devcoach — Review & rebuild flows
+
+Read this file when the user asks to review or rebuild their coaching setup:
+"review my notebook", "review my profile", "rebuild my notebook", "refresh my
+profile from my projects", "any new tech I should track?". These flows are
+**incremental and non-destructive** — the only destructive path is a full redo,
+which lives in `references/onboarding.md`.
+
+Route by intent:
+
+```
+review my profile / notebook      →  Review (below)
+rebuild / refresh my notebook     →  Rebuild notebook (below)
+new tech to track?                →  New tech check (below)
+redo onboarding / reset topics    →  references/onboarding.md, Steps 1–3 (confirm first — it wipes)
+```
+
+## Review
+
+1. Read `devcoach://briefing` — one silent read returns the profile, the taught
+   topics, and the notebook.
+2. Walk the user through the profile **grouped, not topic-by-topic**: show each
+   group with its topics and confidences, and ask what looks wrong. Apply
+   changes as they come: `update_knowledge` (confidence), `add_topic` /
+   `remove_topic` (membership).
+3. Then show the notebook section by section (Observations, Recurring patterns,
+   Recommended focus, Open hypotheses). Ask what is stale or wrong. Fold the
+   edits into a revised full markdown and save it with ONE `update_notebook`
+   call at the end — never one call per edit.
+4. Close with the New tech check below.
+
+## Rebuild notebook
+
+Re-derive the notebook from real data; the knowledge map is untouched.
+
+1. Read `devcoach://onboarding` — `detected_projects` carries the history-wide
+   evidence: per-project stacks, activity volume and recency, and auto-memory
+   excerpts. Read `devcoach://briefing` for the current notebook and profile,
+   and `get_lessons({period: "all"})` for feedback history (`dont_know` lessons
+   are open gaps).
+2. Compose a fresh notebook (structure in `references/onboarding.md`, Step 4):
+   cite real cross-project observations — project names, stacks, what recurs,
+   what the memories reveal about how the user works. Preserve prior notes that
+   are still true; drop the stale ones. Never quote prompt text — it is not in
+   the data, by design.
+3. Show the draft, adjust to taste, save with `update_notebook`.
+
+## New tech check (keep the profile curated)
+
+Compare `detected_stack` + `detected_projects` (from `devcoach://onboarding`)
+against the current profile:
+
+- Candidate = a detected topic **absent from the profile** that appears in **2+
+  scanned projects** or in the current project.
+- Propose **at most 5** candidates, each with its evidence ("seen in discordbot
+  and over-night-runner") and a suggested starting confidence (the detected
+  value). Use the client's question UI; `add_topic` ONLY for the ones the user
+  confirms — never add silently.
+- Also surface retirement candidates: profile topics at confidence ≤ 3 that
+  appear in **no** scanned project. Offer `remove_topic`; keeping them is fine.
+- Nothing qualifies → say so in one line and stop. An overcrowded topic list
+  dilutes lesson choice — fewer, real topics beat completeness.
+- `devcoach://onboarding` unreachable, or `detected_projects` empty → derive
+  candidates from lesson history instead (`get_lessons`: recurring stacks in
+  `task_context` that lack a matching topic), tell the user the evidence is
+  history-only, and defer the retirement pass — never guess retirements
+  without profile access.

package/assets/static/relative-time.js

@@ -18,7 +18,15 @@
     return rtf.format(-Math.floor(diffDays / 365), 'year');
   }
 
-  document.querySelectorAll('[data-ts]').forEach(function (el) {
-    el.textContent = relativeTime(el.dataset.ts);
+  function applyRelativeTimes(root) {
+    root.querySelectorAll('[data-ts]').forEach(function (el) {
+      el.textContent = relativeTime(el.dataset.ts);
+    });
+  }
+
+  applyRelativeTimes(document);
+  /* HTMX-swapped fragments (lesson rows, lesson meta) arrive with raw dates. */
+  document.body.addEventListener('htmx:afterSettle', function () {
+    applyRelativeTimes(document);
   });
 })();