eklavya 1.59.0 → 1.61.0

package/README.md

@@ -61,7 +61,7 @@ page in the dashboard, where the server grades the new pick, and `option_notes`
 (the note under each option, in order), which that page shows under each option. A `correct` that is not one of
 the options, or notes of the wrong length, is stored as nothing and reported
 back (`correct_mismatch`, `option_notes_mismatch`); the answer is still kept.
-An `outcome` of `declined` or `dont_know` with a grade of 3 or more is
+An `outcome` of `invalid` means the question itself was at fault (it assumed context the learner never saw, or two options both answered it): it is stored in `invalid_questions`, grades nothing, returns no `attempt_id`, and changes no mastery, level, review date or gate; only the repeat check reads it. An `outcome` of `declined` or `dont_know` with a grade of 3 or more is
 contradictory: it returns `error: "outcome_grade_conflict"` and records
 nothing, so that call can never update mastery, clear a gate or count toward a
 level.
@@ -72,7 +72,7 @@ level.
 right one, 2 for a near miss, 1 for a misconception), the right one in the
 plan's `answer_position` slot, and an explanation. It stores the question and
 returns at once; it writes no attempt. The panel records the answer through
-`panel_answer` with the same code `record_attempt` uses, exactly once. On a miss with `explain_on_wrong` on, its reply carries the same `explain` block `record_attempt` returns, and the panel starts the explainer agent from it. `present_question` returns `panel_disabled` while `quiz.panel` is off, and
+`panel_answer` with the same code `record_attempt` uses, exactly once. On a miss with `explain_on_wrong` on, its reply carries the same `explain` block `record_attempt` returns, and the panel starts the explainer agent from it. `present_question` sends a question back once with `conspicuous_options` (nothing stored) when one option's label plus description outruns the next by a few words or a description explains itself, and presents the same stem as written on the second call. It returns `panel_disabled` while `quiz.panel` is off, and
 `panel_sync` returns `{disabled: true}` and expires the session's open question without recording an attempt, so turning the panel back on cannot revive it; `panel_answer` answers only a question
 that already exists. A round the learner asked for (a topic, `max`) is remembered per session: `present_question` takes each question off it and sets the last one's `more` false, and `get_session_quiz_plan` with `resume_round: true` plans what is left. This is
 a Claude Code mod feature: a standalone MCP client has the tools but not the

package/dist/assets/dashboard.html

@@ -813,7 +813,6 @@
   .set__ctl input[type="number"], .set__ctl textarea { font:inherit; font-size:13.5px; background:var(--bg); color:var(--ink);
     border:1px solid var(--line-2); border-radius:0; padding:7px var(--space-3); width:100%; }
   .set__ctl textarea { font-family:var(--font-mono); font-size:12.5px; resize:vertical; min-height:64px; }
-  .set__ctl input[type="checkbox"] { width:18px; height:18px; accent-color:var(--spot); margin:4px 0; cursor:pointer; }
   .set__ctl :disabled { opacity:.55; cursor:not-allowed; }
   .set__rule { color:var(--faint); }
   .set__err { margin:var(--space-2) 0 0; color:var(--warning); font-size:12.5px; overflow-wrap:anywhere; }
@@ -821,6 +820,58 @@
   .set__btn { font-family:var(--font-mono); font-size:11px; letter-spacing:.06em; text-transform:uppercase;
               background:none; border:1px solid var(--line-2); color:var(--dim); padding:2px 8px; cursor:pointer; }
   .set__btn:hover { color:var(--ink); border-color:var(--spot); }
+  /* ---------- Settings switchboard: scopes on the right, one tab of settings at a time ---------- */
+  .sw { display:grid; grid-template-columns:minmax(0,1fr) 208px; gap:var(--space-5); align-items:stretch; min-height:calc(100vh - 168px); }
+  .sw__scopes { align-self:stretch; display:flex; flex-direction:column; gap:2px; align-content:flex-start;
+                background:var(--panel); border:1px solid var(--line-2); padding:var(--space-2); }
+  .sw__cap { margin:var(--space-3) var(--space-2) var(--space-1); font-family:var(--font-mono); font-size:10.5px;
+             letter-spacing:var(--tracking-caps); text-transform:uppercase; color:var(--faint); }
+  .sw__cap:first-child { margin-top:var(--space-1); }
+  .sw__projects { display:flex; flex-direction:column; gap:2px; overflow-y:auto; }
+  .sw__scope { display:flex; align-items:center; gap:10px; padding:8px 10px; color:var(--dim); text-decoration:none;
+               font-size:13.5px; min-width:0; transition:background var(--duration-fast) var(--ease), color var(--duration-fast) var(--ease); }
+  .sw__scope svg { width:16px; height:16px; flex:none; }
+  .sw__scope span { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .sw__scope:hover { background:var(--mass); color:var(--ink); }
+  .sw__scope[aria-current="page"] { background:var(--mass); color:var(--ink); box-shadow:inset 2px 0 0 var(--spot); }
+  .sw__scope[aria-current="page"] svg { color:var(--spot); }
+  .sw__none { margin:var(--space-1) var(--space-2) var(--space-2); color:var(--faint); font-size:12.5px; }
+  .sw__pane { min-width:0; display:flex; flex-direction:column; gap:var(--space-5); }
+  .sw__tabs { display:flex; gap:0; border-bottom:1px solid var(--line-2); overflow-x:auto; scrollbar-width:none; }
+  .sw__tabs::-webkit-scrollbar { display:none; }
+  .sw__tab { display:flex; align-items:center; gap:6px; padding:10px 9px; margin-bottom:-1px; white-space:nowrap;
+             font-family:var(--font-mono); font-size:10.5px; letter-spacing:.1em; text-transform:uppercase;
+             color:var(--faint); text-decoration:none; border-bottom:2px solid transparent;
+             transition:color var(--duration-fast) var(--ease); }
+  .sw__tab:hover { color:var(--ink); }
+  .sw__tab[aria-current="page"] { color:var(--ink); border-bottom-color:var(--spot); }
+  .sw__tab i { font-style:normal; color:var(--spot); }
+  .card.sw__list { padding:0; }
+  .sw__list .set, .sw__list .set:first-child, .sw__list .set:last-child { padding:var(--space-4) var(--space-5); border-bottom:1px solid var(--line); }
+  .sw__list .set:last-child { border-bottom:none; }
+  .set--bool { align-items:center; flex-wrap:nowrap; }
+  .set--bool .set__ctl { flex:0 0 auto; }
+  /* A switch: a square track and thumb, the accent when on. It is still a checkbox underneath. */
+  .set__ctl input[type="checkbox"] { appearance:none; -webkit-appearance:none; width:44px; height:24px; margin:0; position:relative;
+    background:var(--mass); border:1px solid var(--line-2); border-radius:0; cursor:pointer;
+    transition:background var(--duration-fast) var(--ease), border-color var(--duration-fast) var(--ease); }
+  .set__ctl input[type="checkbox"]::after { content:""; position:absolute; top:2px; left:2px; width:18px; height:18px;
+    background:var(--dim); transition:transform var(--duration-fast) var(--ease), background var(--duration-fast) var(--ease); }
+  .set__ctl input[type="checkbox"]:checked { background:var(--spot); border-color:var(--spot); }
+  .set__ctl input[type="checkbox"]:checked::after { transform:translateX(20px); background:var(--spot-ink); }
+  @media (max-width:900px) {
+    .sw { grid-template-columns:minmax(0,1fr); gap:var(--space-4); min-height:0; }
+    .sw__scopes { order:-1; align-self:auto; flex-direction:row; align-items:center; overflow-x:auto; scrollbar-width:none; }
+    .sw__scopes::-webkit-scrollbar { display:none; }
+    .sw__cap { display:none; }
+    .sw__projects { flex-direction:row; max-height:none; overflow:visible; }
+    .sw__scope { white-space:nowrap; }
+    .sw__none { margin:0; white-space:nowrap; }
+  }
+  @media (max-width:560px) {
+    .sw__list .set, .sw__list .set:first-child, .sw__list .set:last-child { padding:var(--space-4); }
+    .set--bool { flex-wrap:wrap; }
+  }
   /* A config path is one unbroken word; on a phone it has to break anywhere. */
   .counts .mono, .lines .mono { overflow-wrap:anywhere; }
   /* ---------- feature tips: Driver.js hints restyled, vendor CSS untouched ---------- */
@@ -3118,8 +3169,8 @@ const TIPS = [
     when: () => (S.artifacts ?? []).some((a) => a.correction === 'open') },
   { id: 'artifact-tabs', where: ['artifacts/view'], el: '#view [role="tablist"]', title: 'Open pages',
     text: 'Pages you open stay here as tabs, up to eight. All artifacts takes you back.' },
-  { id: 'settings-scope', where: ['settings/dashboard'], el: '#nav', side: 'right', title: 'User or project',
-    text: 'User settings apply everywhere. Project settings override them for one project.' },
+  { id: 'settings-scope', where: ['settings/dashboard'], el: '.sw__scopes', side: 'left', title: 'User or project',
+    text: 'User settings apply everywhere. Pick a project to override them for that project only.' },
   { id: 'ground', where: ['settings/dashboard'], el: '.ground[aria-label="Colour ground"]', side: 'right', title: 'Ink or paper',
     text: 'Switch the dashboard between a dark and a light ground.' },
 ];
@@ -3492,7 +3543,7 @@ function settingRow(f, d, scope) {
       ? (Object.hasOwn(d.user.set, f.key) ? 'inherited from user settings' : 'default')
       : 'default'}</span>`;
   }
-  return `<div class="set">
+  return `<div class="set${f.type === 'bool' ? ' set--bool' : ''}">
     <div class="set__main"><label for="${id}">${esc(f.label)}</label>
       <p id="${id}-h">${esc(f.help)}${ruleHint(f) ? ` <span class="set__rule">${esc(ruleHint(f))}</span>` : ''}</p>
       <p class="set__src"><code>${esc(f.key)}</code>${src}<span data-msg="${esc(f.key)}" role="status"></span></p></div>
@@ -3500,37 +3551,86 @@ function settingRow(f, d, scope) {
   </div>`;
 }
 
+/** A category's tab id: `This machine` is `this-machine`. */
+const swTab = (group) => group.toLowerCase().replace(/\W+/g, '-');
+const SW_ICON = {
+  user: '<circle cx="12" cy="8" r="4"/><path d="M4 21a8 8 0 0 1 16 0"/>',
+  project: '<path d="M3 7a2 2 0 0 1 2-2h4l2 2h8a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>',
+};
+
+/**
+ * The switchboard. On the left, the scope: you (user settings, the default) or
+ * one project. On the right, that scope's settings one category at a time, each
+ * category a tab in the URL (`#/settings/dashboard/memory`). Picking another scope
+ * keeps the tab. `Terminal` lists what stays a typed command; `Changed` lists
+ * what this scope's file actually sets.
+ */
 function drawSettings(d, scope) {
   SETS = d;
-  const W = scope === 'project' ? 'Project settings' : 'User settings';
+  const tabParam = (id) => (id === swTab(d.fields[0].group) ? null : id);
+  const page = scope === 'project' ? 'project' : 'dashboard';
+  const file = scope === 'project' ? d.project : d.user;
+  const groups = [...new Set(d.fields.map((f) => f.group))];
+  const tabs = groups.map((g) => {
+    const fields = d.fields.filter((f) => f.group === g);
+    return { id: swTab(g), label: g, fields, n: file ? fields.filter((f) => Object.hasOwn(file.set, f.key)).length : 0 };
+  });
+  tabs.push({ id: 'terminal', label: 'Terminal', n: 0 }, { id: 'changed', label: 'Changed', n: file ? Object.keys(file.set).length : 0 });
+  const here = tabs.find((t) => t.id === CUR.param) ?? tabs[0];
+
+  const scopeLink = (label, icon, to, current) =>
+    `<a class="sw__scope" href="${esc(to)}"${current ? ' aria-current="page"' : ''}>${svg(icon)}<span>${esc(label)}</span></a>`;
+  const rail = `<nav class="sw__scopes" aria-label="Settings scope">
+    <p class="sw__cap">Everywhere</p>
+    ${scopeLink('User', SW_ICON.user, SH('dashboard', tabParam(here.id)), scope === 'user')}
+    <p class="sw__cap">Projects</p>
+    <div class="sw__projects">${d.projects.length
+      ? d.projects.map((p) => scopeLink(p.name, SW_ICON.project, SH('project', tabParam(here.id), { project: p.inventory }),
+          scope === 'project' && d.project?.inventory === p.inventory)).join('')
+      : '<p class="sw__none">No project with a checkout on this machine yet.</p>'}</div>
+  </nav>`;
+
   const about = `User settings apply everywhere; a project setting wins in that project only, and <b>Inherit</b>
     removes it so the user setting applies again. Every change here is the same write as
     <code>eklavya config set &lt;key&gt; &lt;value&gt;</code> (with <code>--project</code> for a project), and
     <b>Inherit</b> / <b>Reset</b> is <code>eklavya config unset</code>. Nothing is written inside a repository.`;
-  if (scope === 'project' && !d.project) {
-    const known = d.projects.filter((p) => projectById(p.inventory));
-    return [
-      pageHead(W, [plural(known.length, 'project')], about),
+
+  if (!file) {
+    return `<div class="sw"><div class="sw__pane">${[
+      pageHead('Project settings', [], about),
       nextStep(PROJECT
-        ? `<strong>${esc(scopeName())}</strong> has no git checkout on this machine, so there is no project file to change. Pick one below.`
-        : 'Pick a project to change its settings, or use the project selector.'),
-      card(null, null, lines(known.map((p) => ({ t: esc(p.name), s: `<span class="mono">${esc(p.id)}</span>`,
-        go: SH('project', null, { project: p.inventory }) })), 'No project with a checkout on this machine yet.')),
-    ].join('');
+        ? `<strong>${esc(scopeName())}</strong> has no git checkout on this machine, so there is no project file to change. Pick another project on the right.`
+        : 'Pick a project on the right to change its settings.'),
+    ].join('')}</div>${rail}</div>`;
   }
-  const file = scope === 'project' ? d.project : d.user;
-  const groups = [...new Set(d.fields.map((f) => f.group))];
-  const setHere = Object.keys(file.set).length;
-  return [
-    pageHead(scope === 'project' ? `${esc(d.project.name)} settings` : W,
-      [`<span class="mono">${esc(file.path)}</span>`, `${setHere} set here`], about),
-    d.problem ? nextStep(`<strong>A config file is not being read.</strong> ${esc(d.problem)}`) : '',
-    ...groups.map((g) => card(g, null, d.fields.filter((f) => f.group === g).map((f) => settingRow(f, d, scope)).join(''))),
-    fold(`settings:${scope}:cli`, 'Changed from the terminal', plural(d.cli_only.length, 'setting'),
+
+  const tabBar = `<nav class="sw__tabs" aria-label="Setting categories">${tabs.map((t) =>
+    `<a class="sw__tab" href="${esc(SH(page, tabParam(t.id)))}"${t.id === here.id ? ' aria-current="page"' : ''}>${esc(t.label)}${t.n ? `<i title="${t.n} set in this scope">${t.n}</i>` : ''}</a>`).join('')}</nav>`;
+
+  let body;
+  if (here.id === 'terminal') {
+    body = card('Changed from the terminal', 'These send work off this machine or run a command, so they stay a typed command: eklavya config set <key> <value>.',
       lines(d.cli_only.map((c) => ({ t: `<code>${esc(c.key)}</code>`, s: esc(c.why),
-        v: `<span class="mono">${esc(showValue(file.effective[c.key]))}</span>` }))),
-      { hint: 'These send work off this machine or run a command, so they stay a typed command: eklavya config set <key> <value>.' }),
-  ].join('');
+        v: `<span class="mono">${esc(showValue(file.effective[c.key]))}</span>` }))));
+  } else if (here.id === 'changed') {
+    const tabOf = (k) => { const f = d.fields.find((x) => x.key === k); return f ? swTab(f.group) : 'terminal'; };
+    body = card(`Set ${scope === 'project' ? 'for this project' : 'by you'}`,
+      scope === 'project' ? 'Everything else inherits from user settings.' : 'Everything else is the default.',
+      lines(Object.keys(file.set).map((k) => ({ t: `<code>${esc(k)}</code>`,
+        s: scope === 'project' ? esc(`user: ${showValue(d.user.effective[k])}`) : '',
+        v: `<span class="mono">${esc(showValue(file.set[k]))}</span>`, go: SH(page, tabParam(tabOf(k))) })),
+        scope === 'project' ? 'This project overrides nothing; user settings apply.' : 'Nothing set: every setting is at its default.'));
+  } else {
+    body = `<section class="card sw__list" aria-label="${esc(here.label)} settings">${here.fields.map((f) => settingRow(f, d, scope)).join('')}</section>`;
+  }
+
+  return `<div class="sw"><div class="sw__pane">${[
+    pageHead(scope === 'project' ? `${esc(d.project.name)} settings` : 'User settings',
+      [`<span class="mono">${esc(file.path)}</span>`, `${Object.keys(file.set).length} set here`], about),
+    d.problem ? nextStep(`<strong>A config file is not being read.</strong> ${esc(d.problem)}`) : '',
+    tabBar,
+    body,
+  ].join('')}</div>${rail}</div>`;
 }
 
 /* ============================================================
@@ -3736,30 +3836,7 @@ function fbDelete(btn) {
 
 function viewSettings(scope) {
   fill('settings', settingsUrl(), (d) => drawSettings(d, scope));
-  return `<div class="stack" id="settings">${loader('Reading your settings…')}</div>`;
-}
-
-function viewSettingsHome() {
-  fill('settings', settingsUrl(), (d) => {
-    SETS = d;
-    const proj = d.project;
-    const overrides = proj ? Object.keys(proj.set).filter((k) => !d.global_only.includes(k)) : [];
-    return [
-      pageHead('Settings', [plural(Object.keys(d.user.set).length, 'user setting'),
-        proj ? `${plural(overrides.length, 'project setting')} in ${esc(proj.name)}` : 'no project selected'],
-        `Two files, one precedence: the project's file wins over yours, key by key, and anything neither sets is the
-         default. The terminal writes the same files — <code>eklavya config get</code> shows what is in force.`),
-      card(null, null, lines([
-        { t: 'User settings', s: `<span class="mono">${esc(d.user.path)}</span>`, v: esc(`${Object.keys(d.user.set).length} set`), go: SH('user') },
-        { t: 'Project settings', s: proj ? `<span class="mono">${esc(proj.path)}</span>` : 'choose a project',
-          v: proj ? esc(`${overrides.length} set`) : '', go: SH('project') },
-      ])),
-      proj && overrides.length ? card(`What ${proj.name} changes`, null, lines(overrides.map((k) => ({
-        t: `<code>${esc(k)}</code>`, s: esc(`user: ${showValue(d.user.effective[k])}`),
-        v: `<span class="mono">${esc(showValue(proj.set[k]))}</span>`, go: SH('project') })))) : '',
-    ].join('');
-  });
-  return `<div class="stack" id="settings">${loader('Reading your settings…')}</div>`;
+  return `<div id="settings">${loader('Reading your settings…')}</div>`;
 }
 
 /** Reads a control back into the value its field stores. */
@@ -3914,13 +3991,11 @@ const WORKFLOWS = {
   },
   settings: {
     name: 'Settings',
-    groups: [
-      { id: 'scopes', label: 'Scopes', items: ['user', 'project'] },
-    ],
+    groups: [],
     pages: {
-      dashboard: { label: 'Overview', view: () => viewSettingsHome() },
-      user:      { label: 'User', view: () => viewSettings('user') },
-      project:   { label: 'Project', view: () => viewSettings('project') },
+      dashboard: { label: 'Preferences', view: () => viewSettings('user') },
+      user:      { parent: 'dashboard', view: () => viewSettings('user') },
+      project:   { parent: 'dashboard', view: () => viewSettings('project') },
     },
   },
 };

package/dist/assets/tutor/SKILL.md

@@ -9,8 +9,16 @@ You are teaching a real person, not generating a lesson. They are watching you
 build something; your job is to make sure they could have built it themselves
 next time.
 
-Everything you learn about them persists in the Eklavya MCP server. Use it — the
-whole point is never asking the same question twice.
+Everything you learn about them persists in the Eklavya MCP server: use it to
+never ask the same question twice.
+
+## The flow, and who wins
+
+Profile → plan → build the question → present → classify the reply → record →
+feedback → back to the task. Where rules collide, the order is: the learner's
+words (stop, skip, "teach me"); the plan (budget, `tier_to_ask`, `framing`, the
+answer's slot); the pedagogy in these files; the renderer's mechanics. An
+exception sits beside the rule it overrides.
 
 ## Red flags
 
@@ -19,16 +27,17 @@ yourself thinking one, the right-hand column is what is actually happening.
 
 | The thought | What it is |
 |---|---|
-| "I'll log the concepts once the task is done." | A checkpoint can only fire while the work is happening. End-of-task logging restores the pile it replaced. |
-| "One more question while they're engaged." | The plan said one. Two is the batch, arriving early. |
+| "I'll log the concepts once the task is done." | A checkpoint can only fire mid-work. End-of-task logging restores the pile it replaced. |
+| "One more question while they're engaged." | The plan said one. Two is the batch, early. |
 | "The plan returned one item but there's more worth asking." | Calling the plan again refills a budget the server deliberately spent. |
 | "They got it, near enough." | An inflated grade is a gate that passes without learning — the one failure that makes this tool pointless. |
-| "Two blanks in a row; I should offer to stop." | You are pitching too high. Drop a tier and keep going. Wait to be told to stop. |
-| "I'll reword the question they got wrong." | A question in `asked_before` is spent, not recyclable. |
-| "A definition is the transferable version of this." | `concept` focus wants the general rule. "What is X" is tier-1 recall wearing a hat. |
-| "Too easy to be worth asking — I'll add a 'why'." | `easy` is tiers 1–2 and it was earned. A smuggled "why" is a question they cannot answer honestly. |
-| "They know what 'Task 6' means." | They saw none of it. Define the name or drop it. |
-| "I'll put the dials above the stem for context." | The dials are in the status bar. A line you assemble is one the server cannot keep consistent. |
+| "Two blanks in a row; I should offer to stop." | The planner already lowers the tier. Keep going at `tier_to_ask`; wait to be told to stop. |
+| "They said it lacks context; I'll record a blank." | That grades them 0 for your mistake. Record `invalid`. |
+| "I'll reword the question they got wrong." | A question in `asked_before` is spent. |
+| "A definition is the transferable version of this." | `concept` focus wants the general rule; "What is X" is tier-1 recall. |
+| "Too easy to be worth asking — I'll add a 'why'." | `easy` is tiers 1–2 and was earned. A smuggled "why" cannot be answered honestly. |
+| "They know what 'Task 6' means." | They saw none of it. Define it or drop it. |
+| "I'll put the dials above the stem for context." | They are in the status bar; a line you assemble cannot stay consistent. |
 | "Grade 5 — they picked the right option." | Multiple choice caps at 4. One in four is a coin. |
 
 ## While you work
@@ -49,9 +58,9 @@ Unknown slugs are fine — they are fuzzy-matched or created. Read the response:
 `domain`, an honest `tier` and at least one `prerequisite_of` edge. Without
 edges, `prereqs_unmet` is always empty and the fairness check silently passes.
 
-Logging is silent — never narrate it, never pause the work to announce it. It is
-also the trigger: on `as-you-go` cadence, the default, the log call may come
-straight back with a checkpoint.
+Logging is silent — never narrate it or pause the work to announce it. On
+`as-you-go` cadence, the default, the log call may come straight back with a
+checkpoint.
 
 ## Which one is asking
 
@@ -74,18 +83,18 @@ too. Call `get_session_quiz_plan`, run the quiz and follow its `on_skip` and
 once in a long session (paced by the clock), so treat each as its own single
 question, not a sign you missed the last one.
 
-**Your task answer goes last.** Write the answer when the task is done. If the
-Stop sweep then asks for questions, ask them one at a time with a verdict each,
-and end with "Back to your task:" and the answer again in 2-4 lines. Never end
-a turn on a question or a verdict.
+**Your task answer goes last.** If the Stop sweep asks for questions after the
+task is done, ask them one at a time with a verdict each, and end with "Back to
+your task:" and the answer again in 2-4 lines. Never end a turn on a question
+or a verdict.
 
 **While an agent builds.** With `delegate_work` on (the default), non-trivial
 code changes go to background agents and the wait is when you teach. A hook
 repeats this once, when you edit a second file yourself. Start
 them, log the plan's concepts, then loop: `get_session_quiz_plan` with
 `while_waiting: true`, ask, grade, verdict. Stop when an agent reports or
-`questions_needed` is 0, then write the task answer last. Agents cannot ask,
-and hooks do not quiz inside them. Keep small fixes and lookups inline.
+`questions_needed` is 0, then write the task answer last. Agents cannot ask, and hooks
+do not quiz inside them. Keep small fixes and lookups inline.
 
 **How many questions is not your call — it is the plan's.** Under `as-you-go`
 the plan returns one item, the sweep included. Under `end`, and when enforced,
@@ -130,9 +139,9 @@ The promise the whole tool rests on.
 
 - **A question in `asked_before` is spent** — not "reword it", spent. Ask a
   different thing about the same concept.
-- **Never ask about a slug in `known`** unless it is also in `due_for_review`.
-  Spaced repetition is the only reason a mastered concept returns, and it returns
-  harder.
+- **Never ask about a slug in `known`** unless it is also in `due_for_review`
+  or its plan item is `reason: "gate_work"` (an enforced gate lists it even when
+  mastered; skipping it can make the gate impossible to pass).
 - `record_attempt` returns `repeat_question: true` if you broke this. Treat it as
   a mistake you just made.
 
@@ -144,7 +153,7 @@ Never post a numbered list of five — that is a test, not teaching.
 **Ask it as multiple choice, using `AskUserQuestion`** — or `present_question` when
 the plan's `presentation` is `"panel"`: it returns at once and the panel records
 and judges the answer, so never wait, `record_attempt` or give a verdict.
-Nobody mid-task types a paragraph for a quiz they did not ask for. **Read
+**Read
 `references/writing-mcq.md` before writing one**: the six parts in build order,
 where distractors come from, how to record it; for `"panel"` also
 `references/panel.md`.
@@ -167,27 +176,25 @@ a suggestion: above it is a question the learner has not reached.
 
 Definitions are tier 1 **only**. "What is X" at tier 3 is a bad question.
 
-**The stem is the whole question, and the plan's `ask_attribution` says how to
-sign it.** The dials live in the developer's status bar — `[EKLAVYA
-concept · as-you-go · easy]` — so they never go in the stem. Who is asking is
-the one exception, and whether it belongs in the stem depends on the host:
-follow `ask_attribution` rather than deciding.
+**The stem is the whole question; the plan's `ask_attribution` says how to
+sign it.** The dials live in the status bar, so they never go in the stem.
+Whether who is asking belongs in the stem depends on the host: follow
+`ask_attribution`.
 
 ## Grading, and blanks
 
-`record_attempt` for **every** answer you collect, blanks and declines included, with
-`question` verbatim and `outcome` as `answered`, `dont_know` or `declined`.
-Grade honestly on 0–5; multiple choice caps at 4 and the server enforces it.
-
-"I don't know" is not a skip. It is the clearest request for teaching you will
-ever get, and answering it with a three-sentence correction is the failure this
-tool exists to prevent. **Read `references/grading.md` before you grade** — both
-scales, how long feedback may be, the sequence a blank earns, and what
-`already_taught` changes.
+`record_attempt` for **every** answer, with `question` verbatim and `outcome` as
+`answered`, `dont_know`, `declined` or `invalid` (the question was at fault;
+grades nothing). Multiple choice caps at 4. "I don't know" is not a skip: it is a
+request for teaching. **Read `references/grading.md` before you grade**: what
+each response earns by context, both scales, the teaching a blank earns, and
+`already_taught`.
 
 **A missed answer can come back with `explain`.** That is `explain_on_wrong` at
 work: follow its `instruction` exactly. Hand the explainer its `attempt_id` and
-`option_notes` too: the page shows the notes and can be corrected. The page is written in the background
+`option_notes` too: the page shows the notes and can be corrected. A parallel
+tutor's reply ends with a handoff block (`agents/tutor.md`): start the
+explainer from it, every field included. The page is written in the background
 and opens by itself, so give the verdict, say the page is on its way, and go
 back to the task — no longer explanation, no waiting. When the developer asks
 for something to be explained as a page ("explain this to me", "make me a page
@@ -200,12 +207,10 @@ ask, **difficulty** is how hard questions may get. They are independent and
 every combination is coherent.
 
 You choose none of them — the plan and the hooks do. **Read
-`references/focus-and-level.md` before you quiz**: the three focuses and what
-"grounded" means in each, the earned level bands, the cadence contract, and the
-enforced gate retry that is the only route out of a blocked commit.
+`references/focus-and-level.md` before you quiz**: the three focuses, the earned
+level bands, the cadence contract, and the enforced gate retry.
 
 ## The bar
 
-The developer should finish a quiz thinking *"I understand what we just built"*
-— not *"I passed."* If a question only proves they read the diff, it was the
-wrong question.
+The developer should finish a quiz thinking *"I understand what we just built"*,
+not *"I passed."* A question that only proves they read the diff was the wrong one.

package/dist/assets/tutor/references/focus-and-level.md

@@ -204,7 +204,8 @@ into the batch it replaced.
   is the only route out of the gate, so do not skip past it, and do not treat it
   as the tool repeating itself.
 
-  A concept they explicitly **declined** is not offered again. That is
+  A concept they explicitly **declined** is not offered again by this session's
+  retry (a later session's review may bring it back once it is due). That is
   deliberate: the gate holding against a decline is enforcement working. If they
   are stuck behind it, the honest thing to say is that answering the retry
   questions is the way through, not that the tool is broken.