dsh-nerd-mode 0.2.1 → 0.4.3

package/cordis.patch.yml

@@ -1,19 +1,24 @@
-# Nerd Mode is a profile-level plugin, not a preset. See docs/adr/0008.
-- insert:
-    - id: dsh-nerd-mode
-      name: dsh-nerd-mode
-      config:
-        section: |
-          Nerd Mode is on for this conversation. These rules take precedence over any earlier persona, style, or answer-shape text in this prompt, including text that asks for brevity, for a direct answer, or for no follow-up question.
-
-          A learning-shaped request gets the guided shape. Learning-shaped means: explain a concept, tutor homework, walk through code, or prepare for an exam. Load the `study` skill once and follow it: numbered steps, one stop at the fork that changes the result, and the model produces the artifact. Write no file. Read no `study/` file. Do not grade, score, or log.
-
-          Every other request keeps the base mode's behavior: produce the artifact, run the command, make the edit. Answer in plain prose, without a teaching detour and without a closing question the learner did not ask for.
-
-          A request for a dated, recorded session is `/study-plus`. Say so once, and wait.
-    - id: study-plus-skills
-      name: '@deepseek-ai/dsh-skill-filesystem'
-      config:
-        providerName: study-plus
-        includeDefaultRoots: false
-        bundledSkillDir: !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dsh-nerd-mode/package.json')), 'skills')
+# Nerd Mode is a profile-level plugin, not a preset. See docs/adr/0008.
+- insert:
+    - id: dsh-nerd-mode
+      name: dsh-nerd-mode
+      config:
+        recallSessionEnabled: false
+        unseenQuestionCount: 3
+        unseenQuestionType: short-answer
+    - id: study-plus-skills
+      name: '@deepseek-ai/dsh-skill-filesystem'
+      config:
+        providerName: study-plus
+        includeDefaultRoots: false
+        bundledSkillDir: !!js process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('dsh-nerd-mode/package.json')), 'skills')
+
+# Goal mode stays off. The built-in create_goal description tells the model to
+# arm a goal for any long-running request, which turns one study answer into an
+# auto-continuing run. Without the three packages below, no goal can be created.
+- id: tool-goal
+  disabled: true
+- id: command-goal
+  disabled: true
+- id: goal-round-driver
+  disabled: true

package/lib/index.js

@@ -1,93 +1,223 @@
-/**
- * Nerd Mode: a per-session switch. While it is on, one prompt section joins
- * every request and the `study` skill becomes the default answer shape. State
- * folds from the session log, so it survives compaction, resume, and fork. The
- * tool set never changes.
- *
- * The section registers at the profile level, not inside a preset, so it
- * reaches every agent in every preset. See docs/adr/0008.
- */
-
-import { COMMAND, KEY, fold, init } from './fold.js'
-
-export const name = 'dsh-nerd-mode'
-export const PACKAGE_NAME = 'dsh-nerd-mode'
-export const inject = ['systemPrompt', 'sessionProjections']
-
-const SECTION = 'study:policy'
-// Between PLAN_POLICY (500) and TEAM_POLICY (600).
-const SECTION_ORDER = 550
-
-// shortcut: parse-only schemas, no zod. The projection registry calls `parse`
-// and nothing else. Upgrade to zod if the host starts introspecting schemas.
-const stateSchema = {
-  parse: (value) => ({
-    active: value?.active === true,
-    running:
-      value?.running && typeof value.running.commandId === 'string'
-        ? { commandId: value.running.commandId, wanted: value.running.wanted === true }
-        : null,
-  }),
-}
-
-const viewSchema = { parse: (value) => ({ active: value?.active === true }) }
-
-const projection = {
-  key: KEY,
-  stateVersion: 1,
-  stateSchema,
-  init,
-  apply: fold,
-  wire: {
-    viewSchema,
-    view: (state) => ({ active: state.active }),
-  },
-}
-
-/**
- * @param config - `section` is the overlay text, required and non-empty.
- */
-export function apply(ctx, config) {
-  const section = config?.section
-  if (typeof section !== 'string' || section.trim() === '') {
-    throw new Error('dsh-nerd-mode needs a non-empty string `section`')
-  }
-
-  ctx.sessionProjections.register(projection)
-
-  ctx.effect(
-    () =>
-      ctx.systemPrompt.section({
-        name: SECTION,
-        order: SECTION_ORDER,
-        text: (context) => {
-          if (context.agent === undefined) return ''
-          return ctx.sessionProjections.stateOf(context.agent.session, KEY).active ? section : ''
-        },
-      }),
-    'dsh-nerd-mode: section',
-  )
-
-  ctx.inject(['commands'], (commandCtx) => {
-    commandCtx.commands.register({
-      name: COMMAND,
-      description: 'Turn Nerd Mode on or off for this conversation',
-      input: { hint: '[on|off]' },
-      handler: ({ agent, rawInput }) => {
-        const arg = rawInput.trim().toLowerCase()
-        const active = ctx.sessionProjections.stateOf(agent.session, KEY).active
-
-        if (arg === 'off') {
-          return { kind: 'success', text: active ? 'Nerd Mode off.' : 'Nerd Mode is already off.' }
-        }
-        if (arg !== '' && arg !== 'on') {
-          return { kind: 'error', text: `Unknown argument "${arg}". Use /nerd-mode on or /nerd-mode off.` }
-        }
-        return {
-          kind: 'success',
-          text: active ? 'Nerd Mode is already on.' : 'Nerd Mode on. /study guides a concept or a task.',
-        }
-      },
-    })
-  })
-}
+/**
+ * Nerd Mode: a per-session switch. While it is on, one prompt section joins
+ * every request and the `study` skill becomes the default answer shape. State
+ * folds from the session log, so it survives compaction, resume, and fork. The
+ * tool set never changes.
+ *
+ * The section registers at the profile level, not inside a preset, so it
+ * reaches every agent in every preset. See docs/adr/0008.
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { COMMAND, KEY, fold, init } from './fold.js'
+import z from '@deepseek-ai/schemastery'
+
+export const name = 'dsh-nerd-mode'
+export const PACKAGE_NAME = 'dsh-nerd-mode'
+export const inject = ['systemPrompt', 'sessionProjections']
+
+// The prompt text ships with the package. Keeping it out of the config stops
+// every profile patch from carrying a stale copy of it.
+const BUNDLED_SECTION = readFileSync(
+  fileURLToPath(new URL('../assets/section.md', import.meta.url)),
+  'utf8',
+).trim()
+
+export const Config = z.object({
+  section: z.string().pattern(/\S/).default(BUNDLED_SECTION),
+  recallSessionEnabled: z.boolean().default(false).volatile(),
+  unseenQuestionCount: z.number().step(1).min(0).max(10).default(3).volatile(),
+  unseenQuestionType: z.union([
+    z.const('short-answer'),
+    z.const('multiple-choice'),
+    z.const('mixed'),
+  ]).default('short-answer').volatile(),
+})
+
+const SECTION = 'study:policy'
+// Between PLAN_POLICY (500) and TEAM_POLICY (600).
+const SECTION_ORDER = 550
+const studyPlusDefaultsBySession = new WeakMap()
+const directStudyPlusBySession = new WeakMap()
+// A PTC skill load leaves no message in the history, so keep its id for later
+// turns the way an injected skill message would.
+const ptcStudyPlusBySession = new WeakMap()
+const SKILL_COMMAND = /(^|\s)\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/g
+
+// shortcut: parse-only schemas, no zod. The projection registry calls `parse`
+// and nothing else. Upgrade to zod if the host starts introspecting schemas.
+const stateSchema = {
+  parse: (value) => ({
+    active: value?.active === true,
+    running:
+      value?.running && typeof value.running.commandId === 'string'
+        ? { commandId: value.running.commandId, wanted: value.running.wanted === true }
+        : null,
+  }),
+}
+
+const viewSchema = { parse: (value) => ({ active: value?.active === true }) }
+
+function studyPlusSettings(config, session, invocationId) {
+  let defaults = studyPlusDefaultsBySession.get(session)
+  if (defaults?.invocationId !== invocationId) {
+    defaults = {
+      invocationId,
+      recallSessionEnabled: config.recallSessionEnabled?.get?.() ?? false,
+      unseenQuestionCount: config.unseenQuestionCount?.get?.() ?? 3,
+      unseenQuestionType: config.unseenQuestionType?.get?.() ?? 'short-answer',
+    }
+    studyPlusDefaultsBySession.set(session, defaults)
+  }
+
+  return [
+    '',
+    '',
+    'Study-plus profile defaults for this tracked session:',
+    `- Recall Session: ${defaults.recallSessionEnabled ? 'enabled' : 'disabled'}.`,
+    `- Post-lecture questions: ${defaults.unseenQuestionCount}; type: ${defaults.unseenQuestionType}.`,
+    'Apply these defaults only during tracked study-plus sessions. Ignore them for ordinary study and all other requests.',
+    'An explicit preference in the current /study-plus request overrides its profile default for this session and does not update the profile.',
+  ].join('\n')
+}
+
+/** Return the message id when the message is a direct /study-plus command, else undefined. */
+function directStudyPlusId(message) {
+  if (message?.source?.kind !== 'user') return undefined
+  const text = (message.content ?? [])
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+  return [...text.matchAll(SKILL_COMMAND)].at(-1)?.[2] === 'study-plus' ? message.id : undefined
+}
+
+function studyPlusInvocation(session) {
+  const directInvocation = directStudyPlusBySession.get(session)
+  if (directInvocation !== undefined) return directInvocation
+  const ptcInvocation = ptcStudyPlusBySession.get(session)
+  if (ptcInvocation !== undefined) return ptcInvocation
+
+  // The host returns the full surface history here, not just this turn. See docs/agents/dsh-session-api.md.
+  const invocation = session.deriveMessages().findLast((message) => message.source?.kind === 'skill-invocation')
+  if (invocation?.source.name === 'study-plus') return invocation.id
+
+  const completedCalls = new Set()
+  let loadedId
+  let directId
+  let skillCall
+  let ptcSkillCall
+  for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+    const event = session.eventAt(seq)
+    if (event?.type === 'turn/start') break
+    // A resumed, forked, or seeded log may carry a partial event payload, so
+    // every nested read here is guarded. One bad record must not fail a turn.
+    if (event?.type === 'tool/result') {
+      const result = event.data?.message
+      if (result !== undefined && result.isError !== true && result.source?.callId !== undefined) {
+        completedCalls.add(result.source.callId)
+      }
+    } else if (event?.type === 'tool/call' && event.data?.name === 'skill') {
+      try {
+        if (JSON.parse(event.data.arguments).name === 'study-plus') skillCall = event.data.callId
+      } catch {}
+    } else if (event?.type === 'tool/ptc-dispatch' && event.data?.name === 'skill') {
+      // PTC records a skill call made inside run_code as a dispatch, not as a
+      // `tool/call`, and the dispatch event itself carries the outcome.
+      if (event.data.isError !== true && event.data.arguments?.name === 'study-plus') {
+        ptcSkillCall = event.data.subCallId
+      }
+    } else if (event?.type === 'user/message') {
+      // `user/message` stores the message fields directly in `data`; only
+      // `tool/result` and `system/message` wrap them under `data.message`.
+      const message = event.data
+      if (message?.source?.kind === 'skill-invocation') {
+        if (message.source.name === 'study-plus') loadedId = message.id
+      } else {
+        directId = directStudyPlusId(message) ?? directId
+      }
+    }
+  }
+
+  // A skill load counts only when its tool call completed. A typed command counts at once.
+  if (skillCall !== undefined) {
+    return completedCalls.has(skillCall) ? loadedId ?? directId ?? skillCall : undefined
+  }
+  if (ptcSkillCall !== undefined) {
+    ptcStudyPlusBySession.set(session, ptcSkillCall)
+    return loadedId ?? directId ?? ptcSkillCall
+  }
+  return loadedId ?? directId
+}
+
+const projection = {
+  key: KEY,
+  stateVersion: 1,
+  stateSchema,
+  init,
+  apply: fold,
+  wire: {
+    viewSchema,
+    view: (state) => ({ active: state.active }),
+  },
+}
+
+/**
+ * @param config - `section` is an optional overlay text; a missing value uses
+ * the bundled `assets/section.md`.
+ */
+export function apply(ctx, config) {
+  const section = config?.section
+  if (typeof section !== 'string' || section.trim() === '') {
+    throw new Error('dsh-nerd-mode needs a non-empty string `section`')
+  }
+
+  ctx.sessionProjections.register(projection)
+
+  ctx.effect(
+    () => ctx.on('agent/inbox/claimed', ({ agent, message }) => {
+      directStudyPlusBySession.set(agent.session, directStudyPlusId(message))
+    }),
+    'dsh-nerd-mode: study-plus claim',
+  )
+
+  ctx.effect(
+    () =>
+      ctx.systemPrompt.section({
+        name: SECTION,
+        order: SECTION_ORDER,
+        text: (context) => {
+          if (context.agent === undefined) return ''
+          if (!ctx.sessionProjections.stateOf(context.agent.session, KEY).active) return ''
+          const session = context.agent.session
+          const invocationId = studyPlusInvocation(session)
+          if (invocationId === undefined) return section
+          return section + studyPlusSettings(config ?? {}, session, invocationId)
+        },
+      }),
+    'dsh-nerd-mode: section',
+  )
+
+  ctx.inject(['commands'], (commandCtx) => {
+    commandCtx.commands.register({
+      name: COMMAND,
+      description: 'Turn Nerd Mode on or off for this conversation',
+      input: { hint: '[on|off]' },
+      handler: ({ agent, rawInput }) => {
+        const arg = rawInput.trim().toLowerCase()
+        const active = ctx.sessionProjections.stateOf(agent.session, KEY).active
+
+        if (arg === 'off') {
+          return { kind: 'success', text: active ? 'Nerd Mode off.' : 'Nerd Mode is already off.' }
+        }
+        if (arg !== '' && arg !== 'on') {
+          return { kind: 'error', text: `Unknown argument "${arg}". Use /nerd-mode on or /nerd-mode off.` }
+        }
+        return {
+          kind: 'success',
+          text: active ? 'Nerd Mode is already on.' : 'Nerd Mode on. /study guides a concept or a task.',
+        }
+      },
+    })
+  })
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-nerd-mode",
-  "version": "0.2.1",
+  "version": "0.4.3",
   "description": "A study switch and study skills for DeepSeek Harness.",
   "license": "MIT",
   "type": "module",
@@ -36,11 +36,18 @@
     "client": {
       "platform": "web",
       "immediately": true,
-      "inject": ["@deepseek-ai/dsh-client-ui-conversation"]
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
     }
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "lint": "eslint .",
+    "check": "npm run lint && npm test"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5"
   },
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -54,5 +61,10 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "eslint": "^10.13.0",
+    "globals": "^17.13.0"
   }
 }

package/skills/study/SKILL.md

@@ -1,86 +1,78 @@
----
-name: study
-description: Guide one concept or one task in steps, stop once at a fork, and write no file. Use when the learner wants to understand something rather than only receive it.
-argument-hint: "<concept or task>"
----
-
-# Study
-
-You guide one thing at a time. You write no file and you read none. A learner record, when one exists, belongs to `/study-plus` and you must not open it.
-
-## 1. Pick the scale
-
-Two scales, one shape.
-
-- **Concept**: the learner names an idea and wants to understand it. You teach it.
-- **Task**: the learner names work to finish, usually homework or code. You produce it while you teach it.
-
-When the request mixes both, take the task. The concept rides along inside the work.
-
-When you cannot tell which, ask one question with the two options. Do not guess.
-
-## 2. Plan before you speak
-
-Decide three things, in this order.
-
-1. The one sentence the learner should keep. Everything else supports it.
-2. The steps that reach it. Three to seven is usual. More means the idea is really two ideas.
-3. The fork: the first point where more than one route changes the result.
-
-If there is no fork, do not stop. A forced question is worse than none.
-
-## 3. Build in this order
-
-1. **Title.** Name the idea, not the session and not the date.
-2. **The central idea.** Two or three sentences. Put the sentence worth remembering in a blockquote.
-3. **Steps.** Number them when there are more than three, and name each by its content.
-4. **Symbols.** Three or more symbols get a short table before the first formula: symbol, noun, job.
-5. **Formulas.** State each once in display math, then read it back in plain English, term by term.
-6. **One example.** Concrete numbers. Say where an analogy stops matching.
-7. **The common mistake.** Name it, and state what the result does and does not assume.
-
-## 4. Stop at the fork
-
-At the fork, do three things and nothing more.
-
-1. Name the choice in one sentence.
-2. State what each route costs.
-3. Ask one question. Then stop and wait.
-
-A wrong answer never blocks. Name the wrong step, work the correct route, and continue. Do not ask the same fork twice.
-
-## 5. For a task, act
-
-Produce the artifact. Write the reason beside each step as you go, in one line, so the learner follows the work instead of reverse-engineering it.
-
-Stop at the fork only. Do not ask permission for each step, and do not hand back a half-finished file.
-
-The artifact must run or hand in as it stands. When you cannot finish, say exactly what is missing and why.
-
-## 6. Never grade
-
-No rubric. No pass. No miss. No score. No log.
-
-A wrong answer gets the wrong step named and the correct route shown. Nothing is counted.
-
-Self-report is not evidence and is not a reason to skip the steps. When the learner says they know it, teach the part they have not stated.
-
-## 7. End
-
-Close with one sentence on what was built or understood.
-
-Then offer similar practice in one line. Offer, do not impose. Practice that is recorded and dated belongs to `/study-plus`.
-
-## 8. Voice
-
-Plain, direct prose. One idea per paragraph. A paragraph that runs past six sentences becomes a list. Bold a key term only on first use. Use tables for comparisons.
-
-Write math as `$...$` inline and `$$...$$` on its own line. One expression per pair, and no prose inside.
-
-## 9. Do not
-
-- Do not read or write `study/`. Not `graph.md`, not `state.md`, not a new file.
-- Do not call the learner's understanding mastered, verified, or fluent.
-- Do not open with flattery or close with "does that make sense".
-- Do not stack questions. One at a time.
-- Do not turn a code task into a project. Produce the asked artifact and stop.
+---
+name: study
+description: Teach one concept or help complete one task, using the supplied material as scope and defaulting to chat output.
+argument-hint: "<concept or task>"
+---
+# Study
+
+Teach one concept or help complete one task. This skill owns the standards for teaching and lecture writing, including lecture drafts. `study-plus` owns tracked sessions, tracker updates, the choice of lecture paths, and book assembly. Never load or call `study-plus` from this skill.
+
+The upper layer selects the path for multiple independent concepts. Follow that path and do not ask again.
+
+## Teach accurately
+
+- Use supplied material to set the scope, title, chapter boundaries, and order. Treat it as a reference, not as truth. Check important or uncertain claims when needed, prefer accuracy, and flag differences.
+- Use an approved graph or supplied material by default. Do not research the web for every lecture.
+- Cover the major ideas, relationships, and qualifications. Explain intuition first, then terminology, then formal detail. Choose a structure that fits the content. Do not force a fixed section template.
+- Use examples and analogies when they help. State where an analogy stops matching. Include exam topics only when they matter to the request.
+- Use tables or figures when they clarify the material. Define every mathematical symbol and its role. In derivations, justify each meaningful step, explain the result, and check algebra, arithmetic, assumptions, and units.
+- Write math in LaTeX. Put one expression in each math span. Keep prose outside math spans.
+- Give every symbol a noun and a role. Define each symbol once, where the reader first meets it: inside the sentence for an inline mention, or in one line directly above the first display formula that uses it. Keep the line in the formula's reading order, and switch to one symbol per line when a definition needs an explanatory clause. Do not restate a symbol that an earlier sentence or definition line already made clear.
+- When four or more symbols each appear in two or more formulas, put a short table of just those symbols before the first formula. The table is a lookup aid, not a definition, so it does not remove any symbol from the line above a formula.
+- Compare three or more numbers in a short table before the first formula.
+- State bounds as verbal comparisons. Explain each formula once in plain words without symbols.
+- Use “you” for the reader’s actions and “we” for shared work. Avoid generic “one” and passive wording when the reader acts. Correct misleading terminology at first use.
+- Justify each meaningful derivation step before showing it. Put one meaningful move on each display line, and split long equality chains where the object changes. Mark approximations and assumptions.
+- Prefer verbs to abstract nouns. Open each paragraph with its claim, then support it. State each fact once. Avoid rhetorical questions that ask the reader to infer a conclusion. Keep lecture questions sparse and purposeful.
+- Name headings for their content. Number them only when useful.
+- For a task, produce the requested usable artifact and explain the important steps. Do not expand it into a project or return an avoidable partial result.
+
+## Teach at the given level
+
+The upper layer may give a teaching brief of up to three lines: `Goal`, `Background`, and `Teaching level`. Treat it as context for writing, and never read `graph.md` or any other tracker file to obtain it.
+
+`standard` uses every rule in this file unchanged. A missing `Teaching level` line means `standard`.
+
+For `beginner`:
+
+- Split the lecture into 3 to 7 numbered steps when the concept takes more than one move.
+- Explain each term at first use, including terms that `standard` assumes, such as a prerequisite idea or a notation convention.
+- Add one worked example per step when an example helps.
+- Never add a prerequisite recap block. No level adds one.
+
+For `advanced`:
+
+- Use one pass without numbered steps, unless the derivation needs them.
+- Skip the intuition for an idea only when the `Background` line names that idea as known. Start from the formal statement.
+- Use at most one example per idea. Keep the qualifications and edge cases that matter for the stated goal.
+
+Accuracy rules outrank the level. No level removes a symbol definition, a justification for a derivation step, a stated assumption or approximation, or a bound. No level adds filler, repeated explanation, or a section the concept does not need. The level affects the lecture only.
+
+For a one-off request with no graph, derive the level from the brief the upper layer supplies and from the request and the supplied material. A brief from an upper layer is final: never ask again for a goal or a background it leaves out. A bare topic, or "I want to learn X", states no goal. When no brief arrives and neither the request nor the supplied material states a goal or a background, ask one combined question before teaching: what the learner wants to reach and whether they have met the topic before. State the derived level in one line, then teach. Write no file.
+
+## Format the answer
+
+- For one concept, use an H1 named for the concept.
+- For a one-off multi-concept book, use ordinary Markdown, not a fenced block. Use an H1 for the book or topic, H2 headings for Chapters, and H3 headings for concept Sections. Name each Section after its concept. Follow the supplied book order when it exists.
+- For a task, title the requested artifact or task. Explain the reason for non-obvious steps.
+- Give the complete answer when it fits. If a platform limit forces continuation, state which chapters are covered and which remain, then wait.
+- Do not quiz, grade, score, or log. You may offer similar practice, but do not impose it.
+
+## Write lecture drafts
+
+The upper layer may hand you an approved concept graph, the relevant supplied material, the teaching brief, and one destination file per concept. Then write one complete draft per concept at the given level, under the same writing standard. A draft is prepared teaching material, not teaching.
+
+- Cover the concept completely at the given level: the teaching explanation, its relationships, and useful examples. Write no assessment questions, no answers, and no grading criteria. Actual questions stay unseen.
+- Write only the destinations you are given, and one Chapter per batch when the upper layer splits the work. Never invent a path, and never read or write `graph.md`, `state.md`, `log.md`, `plan.md`, or any other tracker file.
+- Frontmatter is exactly `status: draft` and the concept number. Add no date. The body opens with an H1 named for the concept.
+- Preparation is not teaching. Change no learner state and append nothing to the log.
+- Keep a valid existing draft or dated lecture at a destination. Report it instead of overwriting. Leave an occupied or unrecognized target alone and report it.
+- Report the paths you wrote and every destination you refused. Print no draft in chat.
+
+## Files and figures
+
+Default to chat output. If the learner asks to save a lecture or other artifact, save it to the requested path and show the same content in chat when practical.
+
+When an SVG would materially clarify a relationship, create it by default. When the upper layer scopes a Course, write `study/<course>/diagrams/<name>.svg`. When the guide runs alone, write `diagrams/<name>.svg` and create no folder under `study/`. Load `diagram` for its visual authoring rules, but use this study-specific path instead of its generic default. Sanitize `course` and `name` as single lowercase kebab-case path segments with no slashes or dot segments. If either is unclear, choose a safe fallback. Before writing, confirm the resolved parent stays inside the intended `diagrams/` root and the target is not `study/<course>/graph.md`, `state.md`, `log.md`, or `plan.md`. Compute plotted points rather than placing them by eye. Before replacing an SVG with the same name, copy the old file to `<name>.svg.bak`, replacing any older backup.
+
+Never read or write `study/<course>/graph.md`, `state.md`, `log.md`, or `plan.md`. Do not read or change tracker state. Study-plus owns the choice of lecture paths and the automatic lecture save during tracked sessions. Study may read or write ordinary artifacts, including lectures, drafts, and figures, at paths the user or the upper layer gives it.