dsh-nerd-mode 0.4.0 → 0.4.3

package/skills/study-plus/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: study-plus
 description: Run one tracked session against a dated learning record. Load for an explicit command or after the user chooses tracked study in the upper router.
-argument-hint: "<topic>, or empty to continue the last topic"
+argument-hint: "<course-slug>, or empty to continue the current Course"
 ---
 # Study Plus
 
@@ -14,23 +14,29 @@ Two rules override everything below.
 
 ## 1. Find the workspace and material
 
-The topic directory is `study/<slug>/` in the workspace root, where the slug is the topic in lowercase with hyphens.
+The Course directory is `study/<course>/` in the workspace root, where `<course>` is the Course name in lowercase with hyphens.
 
 Find it with a recursive search. Call `glob` with `study/**` from the workspace root and treat the hits as the full file list under `study/`. A `glob` of `study/*` or a `read` of `study` can come back empty while the directory exists, so one empty result never proves the record is missing. When either returns nothing, call `glob` with `**/study/**/graph.md` before you decide. Name the path you searched whenever you say no record exists.
 
-- With an argument: resolve the slug. If the directory exists, continue it. If it does not exist, build the graph (section 2). If it exists without a `graph.md`, the folder belongs to something else, so ask before writing.
-- Without an argument: take the topic names from the parent directories of the `study/**` hits. One topic, continue it. Several, ask which. None, ask for a topic.
+- With an argument: resolve the slug. If the directory exists, continue it. If it does not exist, ask once whether to create it, then build the graph (section 2). If it exists without a `graph.md`, the folder belongs to something else, so ask before writing.
+- Without an argument: the first tracked study settles the Course. Exactly one Course is used and named in one line. A new Course from the path item asks for its name once; every other Course is named without a question. Several Courses get one question that lists them and offers a new Course.
 - No `study/` anywhere in the workspace: create it on first use.
 
-Each topic holds `graph.md`, `state.md`, and `log.md`, plus `lectures/`, `diagrams/`, and `lectures/archive/` as needed. Read `graph.md`, `state.md`, and the last two blocks of `log.md` before you speak. A legacy `plan.md` is inert user data: never read it, never write it, never delete it. Do not read or write an unrelated file under `study/` just because the directory search finds it.
+When the opening question runs, it carries the Course in its path item: one complete answer in this conversation with no Course record, one continue choice for each existing Course, then start a new Course. Show a continue choice only for a Course that exists under `study/`. Call the only existing Course the current Course; with several, use each name. One round for the opening question, with no separate path question. An explicit `/study-plus` skips the opening question, so the Course question stands alone there. Settle the Course once per conversation and never ask again.
+
+A new Course from the path item asks for its name once before the graph. Offer the request's subject as the suggested name. When the name matches an existing Course, ask whether to continue that Course or use another name. An explicit `/study-plus <course>` settles the Course with no question. Otherwise, the name comes from the learner's words. Slug it the way the record path is slugged today, show the slug in the confirmation line, and create the folder on first write.
+
+When the conversation has a Course and the request is about a different subject, ask one question with two options: add these concepts to the current Course, or start a new Course. The first option runs the existing graph change. Never ask two questions in one turn.
+
+Each Course holds `graph.md`, `state.md`, and `log.md`, plus `lectures/`, `diagrams/`, and `lectures/archive/` as needed. Read `graph.md`, `state.md`, and the last two blocks of `log.md` before you speak. A legacy `plan.md` is inert user data: never read it, never write it, never delete it. Do not read or write an unrelated file under `study/` just because the directory search finds it.
 
 Use material supplied with the current request as scope and reference. Read it, then check important or uncertain claims when needed. Accuracy wins over the source, and relevant differences must be flagged. Use the approved graph and material by default. Do not research the web for every lecture.
 
-The record belongs to this workspace. The same topic studied in another folder starts a separate record. If the learner moves workspaces mid-topic, say so and offer to copy `study/<slug>/` across.
+The record belongs to this workspace. The same Course studied in another folder starts a separate record. If the learner moves workspaces mid-Course, say so and offer to copy `study/<course>/` across.
 
 ## 2. Build, migrate, or change the graph
 
-For a new topic, or when the learner asks for a change, build or rebuild the graph. For a legacy graph that uses `Structure` or `Block`, show a migration preview before continuing. If an existing graph lacks both Chapter/Section metadata and Structure/Block grouping, propose Chapter/Section groupings from its concepts and prerequisites, show the preview, and ask whether to retain or adjust it before writing. Convert legacy groupings to `Chapters`, `Chapter`, and `Section`. If the graph gives no chapter grouping, propose logical groupings. Ask only whether to retain or adjust the preview. After confirmation, write the normalized graph once. Do not change tracker states or lecture bodies.
+For a new Course, or when the learner asks for a change, build or rebuild the graph. For a legacy graph that uses `Structure` or `Block`, show a migration preview before continuing. If an existing graph lacks both Chapter/Section metadata and Structure/Block grouping, propose Chapter/Section groupings from its concepts and prerequisites, show the preview, and ask whether to retain or adjust it before writing. Convert legacy groupings to `Chapters`, `Chapter`, and `Section`. If the graph gives no chapter grouping, propose logical groupings. Ask only whether to retain or adjust the preview. After confirmation, write the normalized graph once. Do not change tracker states or lecture bodies.
 
 A graph change keeps work the learner already has.
 
@@ -45,8 +51,8 @@ For a new graph:
 1. Use supplied material first, then reliable sources when needed, then your own knowledge. Do not research the web for every lecture.
 2. Make a concept table in prerequisite order. Each row has a one-line definition and prerequisite numbers. Keep prerequisite order separate from textbook reading order.
 3. Use the source's book and chapter hierarchy when present. Otherwise, propose logical chapter groupings.
-4. Present the full graph and chapter layout together in the existing approve, edit, or rebuild question. Do not add another approval step. State in that question that approval starts draft generation for every concept, including any concept the learner then skips, and that drafts are not teaching.
-5. After approval, run calibration as one `question` call with three items: what the learner wants to be able to do after this topic, what they have already read, studied, or used in this area in their own words, and which concepts in the approved graph they know well enough to skip, as a multi-select list. Items 1 and 2 are free text. Ask the goal and background items only when the current request and the supplied material do not already state them. Derive the level. Then write `graph.md`, create `state.md` with every concept `new` and undated except the concepts selected to skip, which are `skipped`, create an empty `log.md`, and generate one draft per concept (section 3). Do not create `plan.md`.
+4. Show the full graph and chapter layout in the reply before the approval question, as a Markdown table. Keep the question text short, because it renders as one paragraph: ask whether to approve, edit, or rebuild the graph shown above, and state that approval starts draft generation for every concept, including any concept the learner then skips, and that drafts are not teaching. Do not put the table in the question text. Do not add another approval step.
+5. After approval, run calibration as one `question` call with up to three items: what the learner wants to be able to do after this Course, what they have already read, studied, or used in this area in their own words, and which concepts in the approved graph they know well enough to skip, as a multi-select list. Items 1 and 2 are free text. Ask the goal and background items only when nothing already answers them: not the current request, not the opening question, not the supplied material. Reuse an opening-question answer verbatim. Derive the level. Then write `graph.md`, create `state.md` with every concept `new` and undated except the concepts selected to skip, which are `skipped`, create an empty `log.md`, and generate one draft per concept (section 3). Do not create `plan.md`.
 
 Calibration writes `Goal`, `Background`, and `Teaching level` to `graph.md`. Derive the level from the two answers:
 
@@ -58,15 +64,15 @@ Calibration writes `Goal`, `Background`, and `Teaching level` to `graph.md`. Der
 
 When the two answers clearly conflict, you may choose an adjacent level and state the reason in one line. When the learner declines or gives no usable answer, write `Teaching level: standard` and omit the `Goal` and `Background` lines. Each selected concept becomes `skipped`, with no date and no passes.
 
-Do not ask for calibration on a topic that already has a `graph.md`. A missing `Teaching level` line means `standard`. A graph rebuild keeps the existing `Goal`, `Background`, and `Teaching level` values and asks for nothing the previous graph already recorded.
+Do not ask for calibration on a Course that already has a `graph.md`. A missing `Teaching level` line means `standard`. A graph rebuild keeps the existing `Goal`, `Background`, and `Teaching level` values and asks for nothing the previous graph already recorded.
 
-A mid-topic request such as "too detailed" or "give me the conclusion" changes the level for this session only. Write nothing to `graph.md` and add no log entry. A learner preference is not evidence. When the learner says to keep the change, rewrite the `Teaching level` line and keep the other two lines. This is the only path that changes an existing topic, and the only upgrade path for a topic with no `Teaching level` line.
+A mid-Course request such as "too detailed" or "give me the conclusion" changes the level for this session only. Write nothing to `graph.md` and add no log entry. A learner preference is not evidence. When the learner says to keep the change, rewrite the `Teaching level` line and keep the other two lines. This is the only path that changes an existing Course, and the only upgrade path for a Course with no `Teaching level` line.
 
 The level never changes the Recall Session, the skipped-prerequisite recap, the unseen questions, the Teach-back, the pass threshold, or any learner state. It affects the lecture only.
 
 The hierarchy is Book, Chapter, Section. A graph concept is one Section named after the concept. A lecture is the teaching explanation for one concept in one Concept cycle. It is not a book, chapter, or separate graph concept.
 
-`graph.md` keeps `# Topic`, `Goal`, `Background`, and `Teaching level`, and may add `Book: <title>`. The three brief lines are optional. If `Book` is absent, use the topic as the book title. A multi-chapter graph has `## Chapters` followed by numbered rows in book order: `1. <chapter title>: <scope>`. The concept table keeps prerequisite order and adds integer `Chapter` and `Section` columns. Each concept belongs to one chapter and one section. Number sections from 1 within each chapter in textbook order. A single-chapter graph still uses `Chapter = 1` and section numbers, but omits `## Chapters`; use the Book title, or topic fallback, as the displayed chapter title.
+`graph.md` keeps `# Course: <name>`, `Goal`, `Background`, and `Teaching level`, and may add `Book: <title>`. A new file opens with `# Course: <name>`. A reader accepts `# Topic:` as well, so an older graph keeps its title, and the skill never rewrites an existing `# Topic:` heading. The three brief lines are optional. If `Book` is absent, use the Course as the book title. A multi-chapter graph has `## Chapters` followed by numbered rows in book order: `1. <chapter title>: <scope>`. The concept table keeps prerequisite order and adds integer `Chapter` and `Section` columns. Each concept belongs to one chapter and one section. Number sections from 1 within each chapter in textbook order. A single-chapter graph still uses `Chapter = 1` and section numbers, but omits `## Chapters`; use the Book title, or Course fallback, as the displayed chapter title.
 
 A wrong order mis-teaches for weeks. Do not skip the approval.
 
@@ -74,7 +80,7 @@ A wrong order mis-teaches for weeks. Do not skip the approval.
 
 A Lecture draft is complete teaching material written before any Concept cycle. It is not teaching, it carries no teaching date, and it changes no learner state.
 
-1. Compute one destination per concept: `study/<slug>/lectures/<NN>-<concept-slug>.md`, where `NN` is the graph's concept number padded to at least two digits. The list covers every concept, including skipped concepts.
+1. Compute one destination per concept: `study/<course>/lectures/<NN>-<concept-slug>.md`, where `NN` is the graph's concept number padded to at least two digits. The list covers every concept, including skipped concepts.
 2. Hand the approved graph, the relevant supplied material, the three brief lines, and that explicit destination list to `study`. Copy `Goal`, `Background`, and `Teaching level` from `graph.md` verbatim: do not compress, summarize, or rewrite them. Pass one Chapter per request. `study` owns the draft content and its frontmatter, and it never reads tracker files or chooses paths.
 3. Split the Chapters across subagents when they are available. Give each one the `study` draft rules and keep each agent's destination list disjoint. Without subagents, write the Chapters yourself, one at a time.
 4. Check every returned file: path, `status: draft`, the `concept` number, one H1, coverage of every concept in the Chapter, prerequisite consistency, use of the supplied material, and any contradiction across Chapters. Report a contradiction in one line.
@@ -122,15 +128,15 @@ A tracked lecture belongs in `lectures/<NN>-<slug>.md`, with `date` and `concept
 
 Teach one concept according to `study`'s lecture rules. Write or update the Markdown file yourself, then show the same lecture content in the conversation. For long source material, give a roadmap and progress. Save the complete lecture file before displaying it in chunks if a platform limit requires chunking. Do not start assessment until the full lecture is displayed.
 
-The lecture has no length cap. Teach until the concept is complete at the given level. For visual authoring rules, load `diagram`, but save figures only under the scoped topic's `study/<slug>/diagrams/<name>.svg`, not its generic default. Sanitize the figure name to one lowercase kebab-case segment with no slashes or dot segments. If it is unclear, choose a safe fallback. Before writing, confirm the resolved parent stays within the scoped topic's `diagrams/` root and the target is not `graph.md`, `state.md`, or `log.md`. Compute every plotted point with the host shell. Use `pwsh` on Windows and `bash` on macOS or Linux. Never place a point by eye. Before replacing a same-name SVG, copy the old file to `<name>.svg.bak`, replacing any older backup.
+The lecture has no length cap. Teach until the concept is complete at the given level. For visual authoring rules, load `diagram`, but save figures only under the scoped Course's `study/<course>/diagrams/<name>.svg`, not its generic default. Sanitize the figure name to one lowercase kebab-case segment with no slashes or dot segments. If it is unclear, choose a safe fallback. Before writing, confirm the resolved parent stays within the scoped Course's `diagrams/` root and the target is not `graph.md`, `state.md`, or `log.md`. Compute every plotted point with the host shell. Use `pwsh` on Windows and `bash` on macOS or Linux. Never place a point by eye. Before replacing a same-name SVG, copy the old file to `<name>.svg.bak`, replacing any older backup.
 
 If saving the lecture fails, continue the assessment and record produced evidence. Tell the learner which save path failed.
 
 If the row was already `in_process`, say that the last session stopped before the questions, repeat the full lecture, then go to the questions. The configured question slots were never asked, so they are still unseen. When the log records a defer rather than a crash, say what remains and offer the questions before repeating the lecture.
 
-**Ask unseen questions.** Use the explicit count or type preference in the current `/study-plus` request when present. Otherwise, use the profile defaults in the top-level Nerd Mode instructions. Plan the configured number of unseen question slots, from 0 to 10. A hint, re-ask, or similar question stays in its current slot and does not add a slot. For each slot, write down the expected answer and criteria for a good answer. Keep both private. A draft never contains them. The criteria test the conclusion and whether each step taken is valid, not the route you had in mind. Ask one question at a time, then wait. Outside `study-plus`, ignore these preferences.
+**Ask unseen questions.** Use the explicit count or type preference in the current `/study-plus` request when present. Otherwise, use the profile defaults in the top-level Nerd Mode instructions. Plan the configured number of unseen question slots, from 0 to 10. A hint, re-ask, or similar question stays in its current slot and does not add a slot. For each slot, write down the expected answer and criteria for a good answer. Keep both private. A draft never contains them. The criteria test the conclusion and whether each step taken is valid, not the route you had in mind. Ask one question at a time, then wait. One call asks one question. Outside `study-plus`, ignore these preferences.
 
-For `short-answer`, ask a short-answer question. For `multiple-choice`, give four options with exactly one correct answer; choosing it is sufficient. For `mixed`, choose short-answer or multiple-choice independently at random for each planned slot. Do not add question-type details to the session log. When the configured count is zero, skip unseen questions. A passed Teach-back alone is sufficient to pass. With one or more slots, require a passed Teach-back and `ceil(2 × slot count / 3)` correct slots.
+For `short-answer`, ask the question in the conversation. For `multiple-choice`, ask it as one `question` call with four options and exactly one correct answer; choosing it is sufficient. Give the labels alone, with no description, and shuffle the four positions for each slot. A host without a `question` tool gets the same four options as a numbered text list. A typed answer that names or repeats one option counts as choosing it. Any other typed answer is graded like a short answer. For `mixed`, choose short-answer or multiple-choice independently at random for each planned slot. Do not add question-type details to the session log. When the configured count is zero, skip unseen questions. A passed Teach-back alone is sufficient to pass. With one or more slots, require a passed Teach-back and `ceil(2 × slot count / 3)` correct slots.
 
 A question exists to find the gap, not to stop the session. Nothing in this step blocks the learner.
 
@@ -140,6 +146,7 @@ A question exists to find the gap, not to stop the session. Nothing in this step
 - When an answer is wrong, do three things in one message: name the wrong step, work the correct answer with its process, then ask a similar question in the same slot. Mark one miss. Keep the original miss recorded even if the learner answers the similar question correctly.
 - When the learner asks for the answer, do the same: give the worked answer, mark one miss, ask a similar question in the same slot. Keep the original miss recorded even if the learner answers the similar question correctly.
 - When the learner defers a question or asks to move on, accept it at once. Record the defer and the learner's reason in the log. The concept stays `in_process`, because a defer is neither evidence nor a miss. Never argue about time.
+- When the learner closes the question card or the card times out, treat it as no answer. Ask the same question once more. If it happens again, record a defer with no reason. The concept stays `in_process`.
 
 **Teach-back.** Ask the learner to explain the idea to someone who has not seen it. Grade two things: the idea is correct, and the explanation would let that person use it. Note whether the language stays plain. Do not ask where the idea stops applying. When the answer is valid overall and something is missing or loose, name it, correct it in one sentence, and pass. A miss is for a wrong idea, not for a gap you can close in the moment.
 
@@ -173,7 +180,7 @@ After a completed cycle, rebuild the Book (section 8) and offer three choices in
 `graph.md`:
 
 ```md
-# Topic: <topic>
+# Course: <course>
 Goal: <one line, optional>
 Background: <one line, optional>
 Teaching level: beginner | standard | advanced
@@ -188,7 +195,7 @@ Book: <title, optional>
 | 2 | <name> | <one line> | 1 | 1 | 2 |
 ```
 
-Omit `Book` when the topic is the title. Omit `## Chapters` for one chapter. Use that chapter's table value `Chapter = 1` and section numbers within it. `Goal`, `Background`, and `Teaching level` are optional, and the values are lowercase. A missing `Teaching level` means `standard`. The Book shows no `Background` or `Teaching level` line.
+Omit `Book` when the Course is the title. Omit `## Chapters` for one chapter. Use that chapter's table value `Chapter = 1` and section numbers within it. `Goal`, `Background`, and `Teaching level` are optional, and the values are lowercase. A missing `Teaching level` means `standard`. The Book shows no `Background` or `Teaching level` line.
 
 A dated Lecture and a Lecture draft share one file per concept and differ in frontmatter:
 
@@ -214,7 +221,7 @@ A legacy `plan.md` stays on disk untouched. Nothing reads or writes it.
 
 Assemble a book by grouping lecture files according to Chapter and Section metadata, in textbook order, including drafts and dated Lectures. Each lecture file remains one concept. The page labels a draft as a draft and never shows learner states.
 
-Run `node skills/study-plus/scripts/build-book.mjs study/<slug>` from the workspace root after a complete or partial draft batch, after saving a Lecture, and after a graph rebuild. The learner does not need to ask. The builder copies the current `book.html` to `book.html.bak` before each replacement, and it replaces the older backup. If the builder fails, the current Book stays intact: say which path failed in one line and continue the Concept cycle. If it reports a malformed graph, explain the issue and propose a graph fix for confirmation before changing it.
+Run `node skills/study-plus/scripts/build-book.mjs study/<course>` from the workspace root after a complete or partial draft batch, after saving a Lecture, and after a graph rebuild. The learner does not need to ask. The builder copies the current `book.html` to `book.html.bak` before each replacement, and it replaces the older backup. If the builder fails, the current Book stays intact: say which path failed in one line and continue the Concept cycle. If it reports a malformed graph, explain the issue and propose a graph fix for confirmation before changing it.
 
 `state.md`:
 

package/skills/study-plus/scripts/book-data.mjs

@@ -96,8 +96,8 @@ function readChapterList(text, heading, errors) {
 
 function graphMetadata(text, topicFallback) {
   const firstHeading = text.match(/^#\s+(.+?)\s*$/m)?.[1]?.trim() || '';
-  const headingTopic = firstHeading.replace(/^Topic:\s*/i, '');
-  const topic = (headingTopic.toLowerCase() === 'topic' ? '' : headingTopic || topicFallback || 'Topic').trim();
+  const headingTopic = firstHeading.replace(/^(?:Topic|Course):\s*/i, '');
+  const topic = (headingTopic.toLowerCase() === 'topic' || headingTopic.toLowerCase() === 'course' ? '' : headingTopic || topicFallback || 'Course').trim();
   const book = (text.match(/^Book:\s*(.+?)\s*$/mi)?.[1] || '').trim();
   const goal = (text.match(/^Goal:\s*(.*?)\s*$/mi)?.[1] || '').trim();
   return { topic, title: book || topic, goal };
@@ -237,7 +237,7 @@ function demote(body) {
 /** Parse a graph and its lecture files into ordered book chapters and sections. */
 export function parseBookData(graphText, lectureFiles, { topicFallback = '' } = {}) {
   const graph = parseGraph(graphText, topicFallback);
-  if (!lectureFiles.length) throw new Error('No lecture files found. Add Markdown lectures under the topic lectures/ folder.');
+  if (!lectureFiles.length) throw new Error('No lecture files found. Add Markdown lectures under the Course lectures/ folder.');
 
   const lectures = lectureFiles.map(parseLecture);
   const byConcept = new Map();

package/skills/study-plus/scripts/build-book.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Build study/<topic>/book.html from the graph and its existing lecture files.
+// Build study/<course>/book.html from the graph and its existing lecture files.
 
 import { readFileSync, readdirSync, writeFileSync, existsSync, unlinkSync, realpathSync, statSync, lstatSync, copyFileSync, renameSync } from 'node:fs';
 import { join, resolve, dirname, relative, isAbsolute, sep } from 'node:path';
@@ -23,7 +23,7 @@ function findTopic(arg) {
   try {
     studyStat = lstatSync(studyPath);
   } catch (error) {
-    if (error.code === 'ENOENT') die('No study/ folder here. Pass a topic folder under workspace study/.');
+    if (error.code === 'ENOENT') die('No study/ folder here. Pass a Course folder under workspace study/.');
     die(`Cannot inspect workspace study/ folder: ${error.message}`);
   }
   if (studyStat.isSymbolicLink()) die(`Refusing to use symlink as workspace study/ folder: ${studyPath}`);
@@ -38,7 +38,7 @@ function findTopic(arg) {
   let topicPath = arg ? resolve(arg) : '';
   if (!arg) {
     const hits = readdirSync(studyRoot).filter((name) => existsSync(join(studyRoot, name, 'graph.md')));
-    if (hits.length !== 1) die(`Pass a topic folder under workspace study/. Found ${hits.length} topics under study/: ${hits.join(', ') || 'none'}.`);
+    if (hits.length !== 1) die(`Pass a Course folder under workspace study/. Found ${hits.length} Courses under study/: ${hits.join(', ') || 'none'}.`);
     topicPath = join(studyRoot, hits[0]);
   }
 
@@ -46,11 +46,11 @@ function findTopic(arg) {
   try {
     topicDir = realpathSync(topicPath);
   } catch (error) {
-    die(`Cannot resolve topic folder ${topicPath}: ${error.message}`);
+    die(`Cannot resolve Course folder ${topicPath}: ${error.message}`);
   }
   const topicRelative = relative(studyRoot, topicDir);
   if (!statSync(topicDir).isDirectory() || !topicRelative || topicRelative === '..' || topicRelative.startsWith(`..${sep}`) || isAbsolute(topicRelative)) {
-    die(`Topic folder must be a real directory at least one level below workspace study/: ${topicPath}`);
+    die(`Course folder must be a real directory at least one level below workspace study/: ${topicPath}`);
   }
   return topicDir;
 }