dsh-diagnostic-tutor 0.1.0 → 0.2.0

package/README.md

@@ -11,19 +11,35 @@ learn interactively, and move to the next best step.
 
 ## Status
 
-`v0.1.0` — the first stable release, and the first one meant to be **installed
-rather than built**: `dsh plugin --profile web add dsh-diagnostic-tutor`, with
-prebuilt output and no clone, no `pnpm install`, no build step.
+`v0.2.0` is the published release. It includes the learning-path flow — saved
+goal and time budget, evidence-referenced initial assessment, versioned course
+routes with per-lesson Overviews, session-scoped attempts, and the
+English/Simplified-Chinese interface — plus the content/input/review loop:
+
+- typeset math, formula/code/quiz/flashcard/resource/comparison blocks;
+- learner sources with `sourceRefs` citations;
+- Today plan with ICS export and learner-controlled completion;
+- spaced review with automatic flashcard cards, four ratings and undo;
+- read-only Insights.
+
+Install it with
+`dsh plugin --profile web add dsh-diagnostic-tutor@0.2.0` — no clone, no
+`pnpm install`, no build step. A checkout can be installed instead (see
+[Installing a checkout](#installing-a-checkout-instead-of-the-package)).
 
 The learning loop works end to end: a real goal in your own words, a diagnosis
 map grown one node at a time, a tutor-written lesson, a check answered in the
 chat, recorded evidence, and a next step the tutor chose — which the learner
-presses Continue to take.
+presses Continue to take. The route flow adds a full plan the learner reviews
+and accepts, lesson by lesson; the content loop adds math, sources, Today and
+review on top of it.
 
 It is also early. The [limitations](#known-limitations) are listed rather than
 left to be discovered, and nothing below claims a capability that is not there:
-no PDF or document ingestion, no RAG, no flashcards, no resource libraries, no
-analytics, no course generation.
+no PDF extraction, no RAG, no automatic external resource fetching, no analytics.
+Review scheduling is a local interval heuristic, not FSRS. Course routes are
+proposed by the teaching model, never generated by the runtime, and a route never
+marks knowledge as mastered.
 
 ## Two halves, one system
 
@@ -119,20 +135,19 @@ see is a *diagnosis map*, not a syllabus.
 
 Stated plainly, because each one is a real edge a user can reach.
 
-**Math is styled, not typeset.** The tutor writes LaTeX by convention — `\(...\)`
-inline, `\[...\]` display — and the runtime sets it apart in a monospace face
-with its own background. It does **not** render it. Real typesetting needs a
-library plus fonts and CSS, and the client bundle is a single JavaScript file
-with nowhere to serve those from. This is the most visible rough edge in any
-STEM lesson.
-
-**Skill presence cannot always be detected.** The runtime reports whether the
-Universal Diagnostic Tutor skill is available, but the skill registry reads the
-*global* layer unless it is given a viewing scope, and the standard web profile
-mounts skills per agent. From a plugin at the profile root the catalog is
-therefore empty whether the skill is installed or not. The runtime says
-`cannot tell` rather than guessing, and the panel stays quiet. If lessons never
-appear, check the skill first.
+**Math is rendered as MathML on the host.** The tutor writes LaTeX by convention
+— `\(...\)` inline, `\[...\]` display — and the host pre-renders it with
+KaTeX's MathML output before storing the block. The browser renders native
+MathML through a tag/attribute whitelist; no font or CSS is fetched. Invalid
+TeX inside a text block falls back to the old styled source; an invalid
+`formula` block is refused at write time. Browser MathML quality varies, and
+this build ships no KaTeX CSS/fonts.
+
+**Skill presence requires a live Agent.** The runtime checks the open
+conversation's Agent scope on each overview, including its workspace. Before an
+Agent exists, or while discovery is empty or incomplete, it reports `cannot tell`
+and the panel stays quiet. Polling picks up later registration and Agent changes.
+If lessons never appear, check the skill first.
 
 **Storage is one document.** Every record lives in
 `<dsh-home>/storages/udt.json`. It is readable, copyable and easy to export, and
@@ -154,8 +169,12 @@ matrix as load-bearing, not decoration.
 
 | This plugin | Verified against DSH | Node |
 | --- | --- | --- |
+| `0.2.0` | `0.2.1-rc.3`, `0.2.1-rc.2`, `0.2.0-rc.2` (test suite also on `0.1.7-alpha.2`) | `^22.19.0 \|\| >=24.0.0` |
+| `0.1.1` | `0.2.1-rc.3`, `0.2.1-rc.2`, `0.2.0-rc.2` (test suite also on `0.1.7-alpha.2`) | `^22.19.0 \|\| >=24.0.0` |
 | `0.1.0` | `0.1.7-alpha.2` (also composed under `0.1.5-rc.1`) | `^22.19.0 \|\| >=24.0.0` |
 
+Phase 1–6 的本机 boot 矩阵（2026-10-29）覆盖 `0.2.1-rc.3`、`0.2.1-rc.2`、`0.2.0-rc.2`、`0.1.7-alpha.2` 的插件加载、本地路由、domain v1 与客户端启动；其中 rc3/alpha.2 还通过了 tarball 安装，并用真实模型完成 lesson → Review 评分/撤销 → Insights；rc2/rc20 的完整真实会话仍是补充项。详见 [`docs/planning/COMPATIBILITY.md`](docs/planning/COMPATIBILITY.md)。
+
 Rules this repository enforces mechanically:
 
 - **Named exports only.** A `export default` plugin makes Cordis' loader prefer
@@ -165,7 +184,42 @@ Rules this repository enforces mechanically:
   second runtime copy can be resolved. Enforced by `verbatimModuleSyntax`, and
   verified on the built artifact (it contains zero imports).
 - **No `instanceof` across package boundaries.** Take runtime objects from `ctx`.
-- Peer ranges are wide (`<0.2.0`); dev dependencies pin one exact cohort.
+- Peer ranges name the release lines this plugin was verified on. DSH ships
+  prereleases, and npm's semver only admits a prerelease when its line is named
+  in the range — so the compatibility matrix above, not the range floor, is the
+  contract. Dev dependencies pin one exact cohort for the type baseline.
+
+## UI baseline for redesign
+
+The current surfaces, state model and screenshots (generated from fixtures) live in
+[`docs/design/ui-baseline/index.html`](docs/design/ui-baseline/index.html) with a
+detailed handoff in
+[`docs/design/ui-baseline/README.md`](docs/design/ui-baseline/README.md). It covers
+the system structure, Learning map / Current lesson surfaces, every route-page state
+and the design constraints a new UI must keep.
+
+## Diagnostics
+
+Monitoring is local and content-free: no chat, goal, lesson or evidence text is
+recorded, and nothing is sent anywhere.
+
+```sh
+pnpm doctor                 # human-readable health report
+node scripts/doctor.mjs --json   # machine-readable
+node scripts/doctor.mjs --strict # exit 1 if an error-severity issue exists
+```
+
+It reads `<dsh-home>/storages/udt.json` plus the event journal and reports each
+project's stage, pending/failed tutor requests (with age), stalled attempts and
+route-length conflicts. The same report is available at
+`GET /diagnostic-tutor/api/diagnostics` (loopback-only, like every plugin
+route).
+
+The host journal lives at `<dsh-home>/logs/diagnostic-tutor-events.jsonl`
+(`DSH_DIAGNOSTIC_TUTOR_EVENTS` overrides the path, `off` disables it). It logs
+lifecycle events only: tool names and operations, durations, request outcomes,
+provider error messages (truncated). A single file is capped at 1 MB and
+rotated once.
 
 ---
 
@@ -175,7 +229,7 @@ Rules this repository enforces mechanically:
 
 | | |
 | --- | --- |
-| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | verified against `0.1.7-alpha.2` |
+| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | verified against `0.2.1-rc.3` |
 | the [Universal Diagnostic Tutor](https://github.com/SenmuuuuW/universal-diagnostic-tutor-skill) skill | the teaching brain. Without it the runtime loads, records and displays state, but **no lesson is ever written** |
 | Node | `^22.19.0 \|\| >=24.0.0` |
 
@@ -227,7 +281,7 @@ learn?*.
 
 ```sh
 npm pack
-dsh plugin --profile web add "$PWD/dsh-diagnostic-tutor-0.1.0-rc.1.tgz"
+dsh plugin --profile web add "$PWD/dsh-diagnostic-tutor-0.2.0.tgz"
 ```
 
 **What gets installed is prebuilt.** The package ships `lib/` — the host half
@@ -258,10 +312,30 @@ With the json backend you get exactly one document, `<storage root>/udt.json`
 
 | Slot | Holds |
 | --- | --- |
-| `global` | the learner singleton — preferences, active goal, `initializedAt` |
+| `global` | the learner singleton — preferences, `initializedAt`, and the legacy shared `activeCourseId` marker |
 | `tables.courses` | one record per learning goal, in the learner's own words |
 | `tables.nodes` | the diagnosis map: `id`, `courseId`, `title`, `parentId?`, `relation`, `state`, `evidence[]` |
 
+Courses, maps, lessons and evidence are shared by the learner's conversations.
+Project selection, focus, next step and handoff belong to one conversation,
+identified by its session ID. The legacy `activeCourseId` remains in storage for
+compatibility; it does not select a project for a conversation. A fresh
+conversation starts with the library, even when historical projects exist.
+
+| Conversation selection | Project binding |
+| --- | --- |
+| `none` | A new goal, or a validated write explicitly naming a course or node in this conversation, may select its project. Reading shared data does not select it. |
+| `new` | The learner pressed **Start something new**. Only a new goal created here may bind; historical map or lesson writes leave this choice intact. |
+| `project` | The selected course is the default for tools. Creating another goal does not replace it; writes to another course require selecting that course first. |
+
+`udt_status` reports this conversation's `selection` and, only for `project`,
+its `courseId`. Goal, map and lesson writes return `projectAdopted` and
+`projectBinding`: `adopted`, `already-selected`, `not-selected`, or
+`missing-session-id`. A choice made while a write is pending takes precedence
+over that write's adoption. Without a reliable session ID, status reports
+`sessionAvailable: false`; explicit shared writes can still be stored, but their
+result is `missing-session-id` and they claim no conversation binding.
+
 Two deliberate rules:
 
 - **zod is the contract.** Every record is validated at the durable boundary, so
@@ -294,16 +368,28 @@ route around them:
 
 ### Tools
 
-Five, and none of them decides anything about teaching.
+Eighteen. None of them decides anything about teaching; they record or report.
 
 | Tool | Does |
 | --- | --- |
-| `udt_status` | reports the runtime: domain, version, goals, map, **and the current focus** |
-| `udt_goal_create` | records a goal and plants the map root — and nothing else |
-| `udt_map_get` | reads the map with each node's relation, state and evidence |
+| `udt_status` | reports shared goals and counts, plus this conversation's selection, focus and pending next step |
+| `udt_goal_create` | records a goal and plants only the map root; may also select it for this conversation |
+| `udt_map_get` | reads the selected project's map, or an explicitly named shared course, with each node's relation, state and evidence |
 | `udt_map_update` | `add-nodes` · `set-state` · `add-evidence` |
-| `udt_lesson_update` | writes teaching into the learning surface as blocks |
+| `udt_lesson_update` | writes teaching into the learning surface as blocks; pre-renders math; attaches source citations |
+| `udt_quiz_update` | records a quiz/flashcard submission; never grades and never changes node state |
 | `udt_decide_next` | records where the learner should go next, and why |
+| `udt_path_get` | reads the goal brief, assessment, routes and this conversation's active attempt |
+| `udt_path_update` | saves a brief, assessment or route proposal |
+| `udt_course_run_update` | binds a diagnosed node to an attempt, or completes with evidence |
+| `udt_source_add` | stores pasted text or one explicitly named local `.md`/`.txt` file; deduplicates by SHA-256 |
+| `udt_source_list` | lists source metadata without content |
+| `udt_source_get` | returns one stored source for citation |
+| `udt_plan_get` | reads the learner-owned Today plan |
+| `udt_plan_update` | adds, completes or removes plan items; planning is policy, not teaching |
+| `udt_review_add` | queues review cards; scheduling is policy, not mastery |
+| `udt_review_next` | reads cards due now |
+| `udt_review_grade` | records a review rating and reschedules; never confirms a node |
 
 The division is the architecture: the tutor decides **what** to teach, when to
 check, and what an answer showed; the runtime decides **what may be stored** and
@@ -377,36 +463,36 @@ the button means.
 
 | Surface | Where | For |
 | --- | --- | --- |
-| **Learning tab** | right sidebar, beside the chat | everyday work — map, node and lesson while you talk |
-| **Learning panel** | the main column (`main`) | focus mode — the whole runtime at once |
-
-The tab is the reason the loop is usable: the full panel fills the main column,
-which is also where the conversation lives, so with only that panel answering a
-check meant leaving the lesson. The right sidebar is a separate column.
+| **Learning map** | the main column (`main`, key `diagnostic-tutor-map`) | browsing — course route, every lesson Overview, knowledge & evidence |
+| **Current lesson** | the right sidebar tab, beside the chat | the lesson itself — teaching units, and checks answered in the chat |
 
-Both run on one shared `useLearning` state, so they cannot disagree about what
-is focused or what the tutor wrote. The panel's **Answer in the chat** button
-returns to the conversation and docks the tab in the same step.
+One page for browsing, one surface for learning. The page never starts a lesson;
+the tab never decides what to teach. Both read the same `useLearning` state and
+the same path client, so they cannot disagree about what is focused, accepted or
+written. **Open current lesson** on the map returns to the conversation with the
+lesson tab open in the same step.
 
-The right sidebar hosts session-scoped tabs, so it can only accept one while a
-session surface is mounted — which is why docking happens on the way back to the
-conversation rather than at load.
+The container for the main column is the map page. A full-page lesson panel used
+to exist as a second main destination; it was removed so the same lesson is not
+offered in two places. The standalone full-page component is still used by the
+preview and the tests, but the plugin does not register it.
 
 ### Teaching-brain detection
 
-At load the plugin asks the platform's own skill registry whether the
-Universal Diagnostic Tutor skill is installed — no path is hardcoded, no skill
-root is assumed, and nothing is copied. A missing catalog, a missing skill and
-an unreadable body each degrade to a reported status rather than an error.
+Each overview asks the platform's own Agent and Skill registries whether the
+Universal Diagnostic Tutor skill is available in the requesting session's live
+Agent scope and cwd. No path is hardcoded, no skill root is assumed, and nothing
+is copied. Missing services and incomplete discovery return an inconclusive
+status; complete scoped discovery can establish presence or absence.
 
 Compatibility is probed by **capability**, not by a version string: the skill's
 maintenance contract permits only `name` and `description` in frontmatter, so
 it cannot declare a version. The result carries a short content digest as a
 version hint.
 
-Detection results stay **internal** — logged at `debug`, absent from every tool
-output. The skill forbids naming its files, versions or repository in
-learner-facing text, and this runtime will not be what leaks them.
+Paths, fingerprints and compatibility details stay **internal**, absent from
+every tool output and overview. The overview exposes only availability. The skill
+forbids naming its files, versions or repository in learner-facing text.
 
 ### How the two halves agree
 
@@ -422,20 +508,76 @@ which judged an answer is *not finished* until the next step is recorded — so
 the bridge was **deleted rather than kept as a second voice**. The plugin got
 better at it, which is the evidence it belonged upstream.
 
-## The panel
-
-The browser half registers two things and nothing else: a sidebar icon
-(`sidebar.panellist`, a `list`) and the page it opens (`main`, a `keyed` slot).
-The sidebar `id` and the panel `key` come from one constant — a drift between
-them would leave the icon opening nothing.
-
-It reads as one sentence, left to right:
+## The page and the lesson surface
+
+The browser half registers three things: the **Learning map** icon in the
+sidebar (`sidebar.panellist`, a `list`), the page it opens (`main`, a `keyed`
+slot, key `diagnostic-tutor-map`), and the **Current lesson** tab in the right
+sidebar (a tab type plus its body and title). The map's sidebar `id` and its
+`main` key come from one constant — a drift between them would leave the icon
+opening nothing.
+
+The page has two tabs: **Course route** (the versioned plan, route canvas,
+ordered lesson list and every Overview) and **Knowledge & evidence** (the
+diagnosis map and its recorded observations). Neither one teaches: they show
+stored state.
+
+The route tab shows one stage at a time and one next step. A progress bar names
+the four stages — goal & time, initial diagnosis, route, learning — and a
+**Next step** card always answers "what now?" with a single primary action
+(set the goal, request or answer the diagnosis, request the route, accept the
+version, start the first lesson, continue the current one) plus at most one
+real alternative. Competing action rows live in the folded history, not beside
+it. Before a goal is saved the wizard owns the page; while the tutor is asking
+diagnostic questions the card points back to the conversation, shows how long it
+has waited, says whether the tutor is still thinking, and on a failed turn
+retries with the current model and opens the chat (the failure is recorded on
+the path request, so it survives a restart; provider errors are translated into
+billing / auth / rate-limit / network / context advice); route versions
+appear only after the diagnosis is complete or skipped; once accepted, the page
+leads with the route canvas. A proposed or accepted route shows its total study
+time, the weeks it takes at the saved weekly budget, and any lessons longer than
+the preferred session. Next step moves to the first unfinished lesson after a
+completion, and says when the whole route is done. Completed diagnosis details
+and route settings stay reachable in folded sections.
+
+The plugin's own accent is **DeepSeek's brand blue** — `#4d6bfe` on the light
+canvas, `#6a84ff` on the dark one — used sparingly for progress, the active tab,
+the current/selected item, focus rings and action links. Primary buttons keep the
+host's near-black/white fill: the blue marks, it does not act. All other colours
+continue to come from the host theme.
+
+The initial diagnosis is asked through DSH's **interactive question card**
+(`ask_user_question`) when the profile provides it: options are tapped rather
+than typed, multi-select works, and a free-text question covers explanations.
+The tutor still owns the questions, evidence and assessment; profiles without
+that tool fall back to chat text.
+
+The lesson lives in the docked tab, where the conversation is still on screen.
+That is what makes the check loop work without leaving the lesson. The sidebar
+action **Learn** opens that tab and never takes over the main column; the map's
+**Open current lesson** button returns to the conversation and opens the same
+tab.
 
 ```
-[ Course + Diagnosis Map ]  →  [ Selected node ]  →  [ Learning surface ]
+sidebar Learn ─────────────▶ Current lesson (right sidebar)
+sidebar Learning map ──────▶ Learning map (main column: route | knowledge)
+
+Open current lesson ◀────── returns to chat + lesson tab
 ```
 
-There is no dashboard: three panes, and the map is the navigation.
+Entering learning follows the conversation, not the window. A project is
+shared, but its focus and planned runs belong to a conversation, so the project
+library and **Open current lesson** ask the host which conversation was last
+learning the project (`GET /project/session`, read-only) and switch there with
+the shell's session navigation when it differs. The order is: newest active
+focus, then newest course run with an attempt, then newest project selection;
+only a project no conversation has ever touched falls back to the conversation
+on screen.
+
+A full-page lesson panel used to exist as a second main destination. It was
+removed: one page for browsing, one surface for learning, and the conversation
+keeps the main column.
 
 ### Learning Blocks
 
@@ -445,25 +587,42 @@ keyed by `type`:
 
 | Type | Content |
 | --- | --- |
-| `text` | `md` — markdown, with the skill's `\(...\)` math convention |
+| `text` | `md` — markdown, plus host `math[]` fragments for typeset formulas |
 | `example` | `title`, `steps[]`, `takeaway?` |
 | `diagram` | `format` (`ascii` \| `mermaid`), `spec`, `caption?` |
 | `check` | `prompt`, `expect?`, `hint?` — the stop-and-wait surface |
-
-Adding Formula, Code, Comparison, Practice or Resource later means adding one
-registry entry, never rewriting the lesson renderer. An **unknown type renders a
-readable placeholder** rather than throwing, so a lesson authored by a newer
-host still renders here.
+| `formula` | `tex`, `display?`, host-rendered `mathml`, `caption?` |
+| `code` | `language?`, `source`, `caption?` — displayed, never executed |
+| `quiz` | `title?`, `questions[]` (`mcq`/`short`); answers are recorded, never graded by the runtime |
+| `flashcard` | `front`, `back`, `tags?`; self-report is recorded, not scheduled as mastery |
+| `resource` | `title`, optional `sourceId`/`locator`/`url`/`note` |
+| `comparison` | `columns[]`, `rows[][]`, `caption?` |
+
+Blocks may also carry `sourceRefs: [{sourceId, locator}]`; every reference is
+checked against the `sources` table at write time. The stored schema accepts an
+**unknown type** from a newer host and the client renders a readable placeholder;
+the current model tool still writes only known types.
+The Learning map also shows a compact **Today** card when `udt_plan_update` has created open plan items, with a done action and an **Export calendar** action for dated items. DSH's own `schedule` is session-local, so this is an explicit calendar export rather than a push notification. Review cards and their local interval scheduler are stored but have no separate review surface yet.
 
 ### Browser API
 
-Three calls, at `/diagnostic-tutor/api`:
+The browser's core calls, at `/diagnostic-tutor/api` (the full route list is in
+[the architecture notes](docs/planning/CURRENT-ARCHITECTURE.md)):
 
 | Route | Returns |
 | --- | --- |
 | `GET /overview` | the current course and its whole map (`course: null` on a first run) |
 | `GET /node?id=` | one node with its evidence, parent and children |
+| `GET /project/session?courseId=` | the conversation that should resume a project (read-only) |
 | `POST /lesson {nodeId}` | the prototype lesson, built once and reused after that |
+| `GET /source?id=` | one stored source and its text, for a citation preview |
+| `POST /path/answer` | record a quiz/flashcard submission on the active attempt |
+| `GET /plan/ics` | download open, dated Today plan items as an ICS calendar |
+| `GET /review` | due review cards (read-only) |
+| `POST /review/grade` | record a review rating and reschedule |
+| `POST /review/undo` | restore the previous schedule after the latest grade |
+| `GET /insights?courseId=` | read-only course insight counts |
+| `POST /plan/task` | mark a Today plan item done (learner action; plan only) |
 
 Every request passes a **trust fence**: a bare `ctx.webServer.register()` route
 inherits no authentication, so the route checks that the request arrived at a
@@ -471,6 +630,27 @@ loopback `Host`, from a loopback `Origin`, and is not marked cross-site. Anythin
 else gets `403` and no body. The browser receives **views only** — no storage
 path, no domain handle, no raw record.
 
+### Interface language
+
+Every plugin surface ships copy in **English and Simplified Chinese**: the
+Learning map page, the course route, the docked Current-lesson tab, the
+standalone full-page panel used by the preview and tests, and the shared
+next-step card, handoff line and welcome row. The sidebar Learn action and its
+missing-conversation explanation switch too. A toggle in the map header (and in
+the lesson surfaces) changes the copy in place; the language is saved on the
+learner profile (`preferredLanguage`, via `GET /preferences` and
+`POST /preferences/language`), so it survives a restart and applies to every
+conversation. The choice applies immediately and is saved in the background: a
+failed request keeps the local choice rather than flipping the UI back.
+
+It is copy, not content: the tutor's teaching, the learner's goal text, lesson
+overviews, node titles and recorded evidence are never machine-translated, and
+the model is not instructed to change language by the toggle. Three things stay
+outside the switch: the **Learning map** sidebar label (registered once when the
+plugin loads, so it cannot follow an in-place change), server/model error text
+and dynamic handoff details as generated, and the development preview's own
+toolbar.
+
 ## Preview
 
 The panel takes its API as a prop, so the UI runs with no DSH and no agent:
@@ -492,18 +672,67 @@ Machine Learning            [goal, unconfirmed]
 └─ Python                   [prerequisite, unconfirmed]
 ```
 
+Two query parameters reach the states that are otherwise awkward to produce on
+demand — `?scenario=` (`first-use`, `map`, `handoff`, `next`, `stay`, `noskill`,
+`long`, `scroll`, `library`, `new`, `showcase`, `curriculum`, `path-draft`,
+`path-setup`, `path-assessment`) and `?surface=tab` / `?surface=map` for the
+docked right-sidebar tab and the standalone map page. The scenario switch is in
+the page's toolbar, and the theme toggle sets the same
+`body[data-ds-dark-theme]` attribute DSH does. The page carries the real DSH
+design tokens for the same reason: with hardcoded fallbacks in their place, a
+token that resolves to near-white in dark mode looks perfectly fine locally.
+
 To capture the panel from a *live* profile instead:
 
 ```sh
 pnpm screenshot "<dsh-url-with-token>" preview/dsh-ui.png
 ```
 
+### Auditing the presentation
+
+```sh
+pnpm preview                                                     # in one shell
+pnpm audit:ui http://127.0.0.1:8391/?scenario=next                # in another
+pnpm audit:ui "<dsh-url-with-token>" /tmp/audit --surface=tab
+pnpm check:scroll http://127.0.0.1:8391/ /tmp/udt-scroll-check
+```
+
+The scroll regression requires local Chrome and runs against the built bundle.
+The preview uses a clipped, fixed-height slot like DSH, so the whole document
+cannot scroll to mask an unscrollable plugin. The check sends real wheel events
+and verifies bottom content remains visible in the tab, expanded tab, stacked
+panel, all three wide-panel panes, and long library/welcome views, in both themes.
+Only fixture data is used; no live learner state is changed. The ordinary visual
+audit alone does **not** verify scrolling.
+
+The visual audit measures, at each width this project targets and in both themes: the contrast
+of every control's own text against its own fill, class names in the DOM that no
+rule matches, how many controls carry primary weight in one view, tap targets
+under 28px, type under 10.5px, and anything spilling or clipped. It prints a
+table, writes `findings.json`, and saves screenshots — it does not fail the run,
+so a human can disagree with it.
+
+That is not a substitute for looking. It is what makes looking affordable: the
+docked tab's invisible primary button and the dark-mode 1.05:1 controls were
+both found by it, in a live profile, in seconds.
+
+What the surfaces look like now, captured from a live profile:
+
+| | light | dark |
+| --- | --- | --- |
+| standalone panel (preview/tests only) | ![panel, light](preview/ui-polish/panel-light-1440.png) | ![panel, dark](preview/ui-polish/panel-dark-1440.png) |
+| docked tab | ![tab, light](preview/ui-polish/tab-light-400.png) | ![tab, dark](preview/ui-polish/tab-dark-400.png) |
+
+These captures predate the current layout: the standalone full-page panel is no
+longer a product surface. Today the Learning map page owns the main column and
+the Current lesson tab holds the teaching.
+
 ## Development
 
 ```sh
 pnpm install
 pnpm typecheck   # tsc --noEmit  (host and client)
-pnpm test        # 253 tests: unit, guard, DOM, render, real composition
+pnpm test        # unit, guard, DOM, render, real composition
 pnpm build       # tsc -> lib/ (host) + tsdown -> lib/client.js
 ```
 
@@ -546,8 +775,10 @@ shows a loader row exists.
 | `v0.0.10` | export and delete your data |
 | `v0.0.11` | storage layout tested; `single` kept, with the reason |
 | `v0.1.0-rc.1` | packaged install, no clone or build required |
-| `v0.1.0` | **current** — first stable release, installable from npm |
-| `v0.2.0` | settings, i18n, math typesetting |
+| `v0.1.0` | first stable release, installable from npm |
+| `v0.1.1` | packaged release with the docked learning surface |
+| `v0.2.0` | **published** — Phase 1–6 content/input/review loop, learning-path flow, Today/Review/Insights |
+| next | settings, automatic replan suggestions (the tutor already proposes revisions on request; no runtime auto-replan) |
 
 ## Trust
 
@@ -555,7 +786,10 @@ DSH does not sandbox plugin code: an installed plugin runs in-process with your
 privileges, and a bare `ctx.webServer.register()` route inherits no
 authentication. This plugin's commitments:
 
-- reads and writes only its own storage domain;
+- reads and writes only its own storage domain, with one explicit exception:
+  `udt_source_add(path)` reads exactly one regular `.md`/`.markdown`/`.txt` file
+  the caller names, once, then stores its text in that domain. It never scans a
+  directory, follows a symlink, accepts a URL, or fetches anything;
 - serves its browser half only from loopback-fenced routes it checks itself;
 - makes no outbound network requests;
 - writes no files outside the harness's own storage;
@@ -571,18 +805,19 @@ panel opens, the map and the lesson surface render, and `GET /export` and
 `POST /reset` work. What does not happen is teaching — nothing writes a lesson,
 because nothing is making teaching decisions.
 
-**The plugin cannot always tell you that.** The skill registry reads the
-*global* layer unless it is given a viewing scope, and the standard web profile
-mounts the filesystem skill provider **inside a per-agent layer**. So a plugin
-at the profile root sees an empty skill catalog whether the skill is missing or
-merely mounted where it cannot look. The runtime therefore reports three states,
-not two:
+**Availability is checked for the conversation you have open.** On every
+`GET /overview?sessionId=…`, the plugin resolves that session's live Agent from
+DSH's Agent registry and asks the Skill registry for a complete snapshot using
+`{ scope: agent, cwd: agent.session.header.cwd }`. A root catalog containing
+Office skills cannot establish whether that Agent has a tutor. Services are
+resolved for each request, so delayed registration, removal and preset changes
+are picked up by the panel's existing polling. The runtime reports three states:
 
 | `teachingBrain` | meaning | what the panel does |
 | --- | --- | --- |
-| `true` | found | nothing |
-| `false` | not found, **in a catalog that has entries** | says a tutor is needed |
-| `null` | cannot tell from this scope | says nothing |
+| `true` | found and model-invocable in the live Agent scope | nothing |
+| `false` | unavailable after complete scoped discovery with entries | says a tutor is needed |
+| `null` | no live Agent, empty/incomplete discovery, or unsupported/unavailable service | says nothing |
 
 An earlier revision treated "not in my catalog" as "not installed" and showed a
 notice on that basis. In a web profile that was a confident, wrong answer — the
@@ -655,4 +890,6 @@ MIT. The Universal Diagnostic Tutor skill is a separate MIT project by the same
 author and is not vendored here.
 
 Planning and architecture research for this project live in
-[`docs/planning/`](docs/planning/).
+[`docs/planning/`](docs/planning/). Phase 1–6 merge order, acceptance checks and the DSH compatibility checklist are in
+[`docs/planning/PHASE-1-6-MERGE.md`](docs/planning/PHASE-1-6-MERGE.md). 0.2.0 发布清单与验证记录见
+[`docs/planning/RELEASE-0.2.0.md`](docs/planning/RELEASE-0.2.0.md).