wicker-study-mcp 2.10.0 → 2.12.0

package/README.md

@@ -17,7 +17,7 @@ the MCP server.
 For a manually supplied key, the same secure bootstrap is available as:
 
 ```sh
-WICKER_STUDY_URL='https://study.wicker.life' WICKER_STUDY_API_KEY='wsk_…' npx -y wicker-study-mcp@2.10.0 configure
+WICKER_STUDY_URL='https://study.wicker.life' WICKER_STUDY_API_KEY='wsk_…' npx -y wicker-study-mcp@2.12.0 configure
 ```
 
 ```jsonc
@@ -77,7 +77,7 @@ they are how a key is obtained. Everything else needs one.
   `update_planning_objective`, `set_course_visibility`, `join_programme`
 - **Documents and calendars** — `analyze_documents`, `apply_changes`, `preview_calendar`,
   `save_calendar_link`, `sync_calendar_link`, `remove_calendar_link`
-- **Canvas** — `canvas_connect`, `canvas_updates` (announcements, assignments with
+- **Canvas** — `canvas_groups` (your course teams and global memberships; pass a group ID to read teammates), `canvas_connect`, `canvas_updates` (announcements, assignments with
   submission state, events, grades), `canvas_course_requirements` (syllabus and the
   module item carrying the assessment rules), `canvas_list_remote_courses`,
   `canvas_list_remote_course_modules`, `canvas_import_remote_course`,
@@ -100,7 +100,13 @@ authoritative list of endpoints and scopes.
 
 Direct context reads do not call the model. `tutor_ask` uses the student's AI allowance and can prepare attendance changes, assignment/catch-up trackers, group milestones, focused practice, diagnostics and rubric-based draft reviews. Reuse conversation IDs. Approve only the exact proposal the student reviewed; receipts prevent double application. No tool sends email or submits assignments to Canvas. Personal completion is separate from Canvas submission status.
 
-Update an installed client to `wicker-study-mcp@2.10.0` and restart its MCP connection to discover the new tools. The companion skill is served at [SKILL.md](https://study.wicker.life/skills/wicker-study/SKILL.md); re-download it to update an existing copy.
+Update an installed client to `wicker-study-mcp@2.12.0` and restart its MCP connection to discover the new tools. The companion skill is served at [SKILL.md](https://study.wicker.life/skills/wicker-study/SKILL.md); re-download it to update an existing copy.
+
+### Complete original downloads and remembered context
+
+Use `canvas_course_materials` to choose an exact asset/course/year, then call `download_course_original({assetId, courseCode, academicYear, outputFolder})`. The MCP streams the full stored original to a new private local subfolder and returns its path, size and SHA-256 only after verifying the complete file. PDFs, slide decks, images, spreadsheets and archives retain their original bytes. Existing files are never overwritten. Failed or incomplete downloads are removed. The maximum is 1 GB per file; larger files remain available through the authenticated web download. A remote MCP's filesystem may not be accessible to its client. This tool uses read scope and never scrapes Canvas or sends file bytes into the chat.
+
+The companion skill now proactively notices lasting preferences, project decisions, constraints and availability during normal discussions. It reads `tutor_sources` to avoid duplicates, prepares the exact new context, and asks for confirmation before saving with `tutor_confirm_update`. The agent reports a successful receipt instead of treating a draft or an ordinary chat reply as saved memory. Transient remarks and speculation are not stored, and tasks/attendance continue using their dedicated workflows.
 
 ## Licence
 
@@ -145,3 +151,44 @@ Use `feedback_prepare` to create an exact report preview, then show it and obtai
 Students can follow reports and withdraw evidence at `/app/feedback`; authorized staff review them at `/app/admin/feedback`. See [the operations guide](../docs/FEEDBACK.md) for data boundaries and retention.
 
 Contact sharing is optional per report: use `shareContactEmail:true` only when the student chooses it and show the returned address in the preview. `feedback_withdraw_contact` stops sharing it after fresh confirmation. Reports show receipt, investigation and completion updates with public comments; AI-assisted replies are labeled and reviewed by the team.
+
+## Updating an existing installation
+
+The in-app guide at [Docs → Update your MCP](https://study.wicker.life/app/docs#update) has copyable commands for both clients. For the standard installation, reuse your saved credentials; do not generate a new API key or run `configure` again.
+
+### Codex
+
+```sh
+codex mcp remove wicker-study
+codex mcp add wicker-study -- npx -y wicker-study-mcp@2.12.0
+```
+
+Quit and reopen the Codex app, restart the CLI session, or reload the IDE extension window so the local MCP process restarts.
+
+### Claude Code
+
+```sh
+claude mcp remove --scope user wicker-study
+claude mcp add --scope user wicker-study -- npx -y wicker-study-mcp@2.12.0
+```
+
+Exit and restart Claude Code, then check `/mcp`. `claude mcp add` does not overwrite an existing registration. If you originally installed with `project` or `local` scope, use that same scope in both commands.
+
+### Claude Desktop and custom configurations
+
+In Claude Desktop, use Settings → Developer → Edit Config. Change only the package argument in the existing `wicker-study` entry to `wicker-study-mcp@2.12.0`, preserve its other settings, then fully quit and reopen Claude Desktop. For custom Codex/Claude Code configurations with environment variables or a server URL, update the package argument in place instead of replacing the registration. Check project overrides if an older version still loads.
+
+The standard helper credentials stay in `~/.config/wicker-study/config.json`. These registration commands do not delete that file. After restarting, ask the agent to call `wicker_status` and `study_generation_contract` to verify connectivity and availability of the new tools. Replace any installed [companion skill](https://study.wicker.life/skills/wicker-study/SKILL.md) in its existing location too.
+
+Official client references: [Codex MCP configuration](https://developers.openai.com/codex/mcp), [Claude Code MCP configuration](https://code.claude.com/docs/en/mcp).
+
+## Local study generation
+
+The 2.12.0 source adds `study_generation_contract`, `study_generation_sources`, `study_generation_start`, `study_generation_next`, `study_generation_submit`, `study_generation_refresh`, `study_generation_stop`, and `study_generation_add_notes`. Install `wicker-study-mcp@2.12.0` using the update instructions above.
+
+1. Read the current contract and list the course edition’s sources. If needed, download originals with `canvas_import_remote_course`; inspect graphics and preserve page numbers. Add supplementary extraction as explicitly labelled local notes.
+2. Start the student-requested private run with its exact source selection, or continue a version prepared in the web UI.
+3. Fetch `study_generation_next`. Use its exact evidence, prompt and response schema to compute one complete response locally. Use a fresh critique context for review steps and report real findings.
+4. Submit with its `requestId` and `contractId`. Retry network failures with the identical payload. Fetch next again until complete. Failed content can be corrected with `retry:true`; ready chapters remain saved.
+
+Prompts and schemas are fetched from the deployed platform every step. An implementation fingerprint rejects submissions after pipeline changes; fetch next again. No platform generation worker, model call or AI allowance is used. Your local provider/subscription costs still apply. Local semantic reviews are agent-supplied; platform schema, citations and deterministic quality checks are enforced. This is not independent editorial verification, and nothing is shared automatically.

package/original-download.mjs

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto'
+import { mkdir, mkdtemp, open, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+// Stream to a private, unique directory. Never replace an existing user file or
+// expose a partial download as a successful original.
+export async function downloadCourseOriginal({ assetId, courseCode, academicYear, outputFolder }, { api, apiResponse }) {
+  const inventory = await api('/api/corpus/materials', { query: { courseCode, academicYear } })
+  const material = inventory.materials?.find(item => item.assetId === assetId)
+  if (!material) throw new Error('This original is not available in the selected course edition. Read canvas_course_materials again.')
+  const size = Number(material.byteSize)
+  if (!Number.isSafeInteger(size) || size < 0 || !/^[a-f0-9]{64}$/i.test(material.sha256 || '')) throw new Error('The original has no verifiable size or checksum. Refresh its material record before downloading.')
+  if (size > 1024 ** 3) throw new Error('This original exceeds the 1 GB local download limit. Use its authenticated web download instead.')
+  const response = await apiResponse(`/api/corpus/assets/${encodeURIComponent(assetId)}`, { query: { download: '1' }, timeoutMs: 300000, redirect: 'error' })
+  if (response.status !== 200 || !response.body) {
+    await response.body?.cancel()
+    throw new Error('The server did not return a complete original file. Retry the download.')
+  }
+  const root = resolve(outputFolder)
+  await mkdir(root, { recursive: true, mode: 0o700 })
+  const folder = await mkdtemp(join(root, 'wicker-original-'))
+  const filename = String(material.filename || assetId).split(/[\\/]/).pop().replace(/[\x00-\x1f\x7f]/g, '_').slice(0, 200)
+  const path = join(folder, !filename || /^\.+$/.test(filename) ? 'original' : filename)
+  let file
+  try {
+    file = await open(path, 'wx', 0o600)
+    const hash = createHash('sha256')
+    let byteSize = 0
+    for await (const chunk of response.body) {
+      byteSize += chunk.byteLength
+      if (byteSize > size) throw new Error('The downloaded original does not match its recorded size.')
+      hash.update(chunk)
+      // FileHandle.write may make a partial write; retain every byte.
+      let offset = 0
+      while (offset < chunk.byteLength) {
+        const { bytesWritten } = await file.write(chunk, offset, chunk.byteLength - offset)
+        if (!bytesWritten) throw new Error('The original could not be written completely.')
+        offset += bytesWritten
+      }
+    }
+    const sha256 = hash.digest('hex')
+    if (byteSize !== size || sha256 !== material.sha256.toLowerCase()) throw new Error('The downloaded original failed its size or checksum check. Retry; no partial file was retained.')
+    await file.close(); file = null
+    return { path, filename: material.filename, assetId, courseCode: material.courseCode, academicYear: material.academicYear, mediaType: material.mediaType, byteSize, sha256, complete: true, location: 'Local filesystem of this MCP server. The complete original bytes are saved; this is not extracted text.' }
+  } catch (error) {
+    await file?.close().catch(() => {})
+    await rm(folder, { recursive: true, force: true })
+    throw error
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicker-study-mcp",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "MCP server for Wicker Study: read course material and a student's academic record, study on their behalf, collect a private Canvas course snapshot, and \u2014 with an admin key \u2014 run the editorial workflow.",
   "keywords": [
     "mcp",
@@ -30,6 +30,7 @@
   "files": [
     "server.mjs",
     "study-tools.mjs",
+    "original-download.mjs",
     "feedback-tools.mjs",
     "write-confirmation.mjs",
     "config.mjs",

package/server.mjs

@@ -2,6 +2,7 @@
 import { registerFeedbackTools } from './feedback-tools.mjs'
 import { installWriteConfirmation, toolRequestContext } from './write-confirmation.mjs'
 import { registerStudyTools } from './study-tools.mjs'
+import { downloadCourseOriginal } from './original-download.mjs'
 // Wicker Study MCP server — a thin stdio wrapper over the HTTP API so agents
 // (Claude Desktop, Claude Code, Codex, Cursor, …) can read course material and
 // a student's record, record study activity, collect a private Canvas course
@@ -60,13 +61,14 @@ function requireKey() {
   return credential.apiKey
 }
 
-async function apiResponse(path, { method = 'GET', body, query, timeoutMs } = {}) {
+async function apiResponse(path, { method = 'GET', body, query, timeoutMs, redirect } = {}) {
   const url = new URL(baseUrl + path)
   for (const [key, value] of Object.entries(query || {})) if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, String(value))
   const response = await fetch(url, {
     ...(timeoutMs ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
     method,
-    headers: { authorization: `Bearer ${requireKey()}`, accept: 'application/json', 'x-wicker-client': 'wicker-study-mcp 2.10.0', ...(toolRequestContext.getStore() ? { 'x-wicker-tool': toolRequestContext.getStore().tool, 'x-wicker-confirmed': String(toolRequestContext.getStore().confirmed) } : {}), ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+    ...(redirect ? { redirect } : {}),
+    headers: { authorization: `Bearer ${requireKey()}`, accept: 'application/json', 'x-wicker-client': 'wicker-study-mcp 2.12.0', ...(toolRequestContext.getStore() ? { 'x-wicker-tool': toolRequestContext.getStore().tool, 'x-wicker-confirmed': String(toolRequestContext.getStore().confirmed) } : {}), ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
     body: body !== undefined ? JSON.stringify(body) : undefined
   })
   if (!response.ok) {
@@ -93,12 +95,15 @@ const json = (value) => ({ content: [{ type: 'text', text: typeof value === 'str
 const failed = (error) => ({ isError: true, content: [{ type: 'text', text: error.message }] })
 const run = (fn) => async (args) => { try { return json(await fn(args)) } catch (error) { return failed(error) } }
 
-const server = new McpServer({ name: 'wicker-study', version: '2.10.0' })
+const server = new McpServer({ name: 'wicker-study', version: '2.12.0' })
 installWriteConfirmation(server, z)
 const courseId = z.string().describe('Course id (e.g. "sec"). Use list_courses to discover ids.')
 const chapterId = z.string().describe('Chapter id (e.g. "02").')
 registerFeedbackTools(server, { z, run, api })
 registerStudyTools(server, { z, run, api, defaultCanvasUrl: DEFAULT_CANVAS_URL })
+server.tool('download_course_original', 'Download one complete original material file to the local filesystem of this MCP server, with size and SHA-256 verification. First use canvas_course_materials to choose its exact assetId and course/year. Use for PDFs, slide graphics, tables, datasets or any full-file analysis beyond indexed passages. Saves unchanged bytes in a new private subfolder of outputFolder; never overwrites files, executes content, or exposes credentials. This is a read of the platform, not a scrape or context update.', {
+  assetId: z.string().min(1).max(160), courseCode: z.string().min(1).max(40), academicYear: z.string().max(20).optional(), outputFolder: z.string().min(1).max(2000)
+}, run(args => downloadCourseOriginal(args, { api, apiResponse })))
 
 const COURSE_SOURCE_EXTENSIONS = new Set(['.pdf', '.ppt', '.pptx', '.doc', '.docx', '.txt', '.md', '.csv', '.tex', '.m', '.py', '.r', '.html', '.htm', '.png', '.jpg', '.jpeg', '.webp'])
 const SOURCE_MIME = { '.pdf': 'application/pdf', '.ppt': 'application/vnd.ms-powerpoint', '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation', '.doc': 'application/msword', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv', '.tex': 'text/x-tex', '.m': 'text/x-matlab', '.py': 'text/x-python', '.r': 'text/x-r', '.html': 'text/html', '.htm': 'text/html', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' }

package/study-tools.mjs

@@ -6,14 +6,27 @@ export function registerStudyTools(server, { z, run, api, defaultCanvasUrl }) {
   const canvasUrl = z.string().url().optional()
   const context = z.object({ courseId: code, courseCode: code, chapterId: code, sourcePath: z.string().max(500).optional(), attachmentIds: z.array(id).max(10).optional() }).optional()
   const tool = (name, description, schema, handler) => server.tool(name, description, schema, run(handler))
+  // The installed MCP is a transport. Prompts, schemas and validation always
+  // come from the deployed pipeline, never a bundled copy that can drift.
+  const courseIdentity = { courseCode: z.string().min(2).max(80), courseName: z.string().max(180).optional(), academicYear: z.string().regex(/^(20\d{2}-20\d{2}|undated)$/), period: z.string().max(80).optional() }
+  const selection = { sourceKeys: z.array(id).min(1).max(500), includeHistorical: z.boolean().optional() }
+  tool('study_generation_contract', 'Read the current deployed generation protocol and quality contract before local generation. The platform provides the exact prompt and JSON schema for every step; do not use a cached prompt pack. No platform model call.', {}, () => api('/api/study-versions/local/contract'))
+  tool('study_generation_sources', 'List authorised source keys for a course edition before starting local generation. To process original files locally, use canvas_import_remote_course; retain slide graphics, tables, notes and page numbers. Add your OCR/visual interpretations as explicit local notes, never mislabel them as original source text.', courseIdentity, args => api('/api/study-versions/sources', { query: args }))
+  tool('study_generation_start', 'Start a private local-generation run using the student’s chosen course and source keys. Use when the student requests local generation. Then repeatedly fetch next, compute its complete JSON response locally, and submit. No platform AI billing or hosted worker is started. The authorised run includes its generation and review steps; it does not publish or share the guide.', { ...courseIdentity, ...selection, title: z.string().max(180).optional(), confirmed: z.literal(true) }, body => api('/api/study-versions/local', { method: 'POST', body }))
+  tool('study_generation_next', 'Continue an already authorised local run. Fetch the latest exact prompt, source evidence, response schema and contractId. Compute the response with your local model and submit using the returned requestId. For quality review use a fresh critique context; report unsupported claims honestly. If request is null inspect status: complete/failed/stopped need no polling, active may need another next call. retry:true resumes failed/stopped work. Never regenerate a finished step or ask for approval on each continuation.', { versionId: id, retry: z.boolean().optional() }, ({versionId,...body}) => api(`/api/study-versions/${encodeURIComponent(versionId)}/local/next`, { method: 'POST', body, timeoutMs: 120000 }))
+  tool('study_generation_submit', 'Submit the complete JSON result for exactly one pending local request. Reuse requestId and identical response on network retry; changed contract or stale inputs require fetching next again. Server applies the same schema, citation, teaching-quality, repair and activation checks as hosted generation. This continues the existing authorised run and never publishes the guide.', { versionId: id, requestId: id, contractId: id, response: z.union([z.string().max(600000), z.record(z.unknown())]) }, ({versionId,...body}) => api(`/api/study-versions/${encodeURIComponent(versionId)}/local/submit`, { method: 'POST', body, timeoutMs: 120000 }))
+  tool('study_generation_refresh', 'Start a new local revision with a changed source selection after the student requests an update. Stop an active run first. Finished revisions remain readable. Then continue with study_generation_next.', { versionId: id, ...selection, confirmed: z.literal(true) }, ({versionId,...body}) => api(`/api/study-versions/${encodeURIComponent(versionId)}/local/refresh`, { method: 'POST', body }))
+  tool('study_generation_stop', 'Pause the student’s local run. Completed steps and published-to-self revisions are preserved; an outstanding local result can no longer be submitted.', { versionId: id }, ({versionId}) => api(`/api/study-versions/${encodeURIComponent(versionId)}/local/stop`, { method: 'POST', body: {} }))
+  tool('study_generation_add_notes', 'Save student-authorised local extraction or notes as a clearly labelled private source. Preserve original page numbers and identify source filenames in text. Describe relevant graphs, tables, diagrams and relationships accurately; distinguish inference from source facts. Does not alter the original Canvas document. Use its returned id in sourceKeys.', { ...courseIdentity, title: z.string().max(150), pages: z.array(z.object({page: z.number().int().positive().nullable(), text: z.string().max(300000)})).min(1).max(500), confirmed: z.literal(true) }, body => api('/api/study-versions/local/notes', { method: 'POST', body }))
   tool('read_course_source', 'Read 12 indexed passages from an authorised Canvas document returned by search_course. Follow nextOffset to read beyond the snippet, including later paper-list pages. Retains edition, path and page citations; never widens source access.', { assetId: id, courseCode: z.string().min(1).max(40), offset: z.number().int().min(0).max(100000).optional() }, args => api('/api/retrieve/source', { query: args }))
-  tool('canvas_course_materials', 'List indexed originals and source editions for one course. Select an exact academic year for a retake; use read_course_source for extracted text.', { courseCode: z.string().min(1).max(40), academicYear: z.string().max(20).optional() }, args => api('/api/corpus/materials', { query: args }))
+  tool('canvas_course_materials', 'List indexed originals and source editions for one course. Select an exact academic year for a retake; use read_course_source for extracted text or download_course_original for the complete unchanged file.', { courseCode: z.string().min(1).max(40), academicYear: z.string().max(20).optional() }, args => api('/api/corpus/materials', { query: args }))
+  tool('canvas_groups', 'Read your Canvas group memberships across courses and global groups. Filter by courseCode and academicYear to keep retake teams separate. Pass a groupId from these memberships to read teammates; include its canvasUrl if several Canvas hosts are connected. A failed roster is unknown, not an empty team. Read-only: never joins or changes groups.', {canvasUrl,courseCode:code,academicYear:z.string().max(20).optional(),scope:z.enum(['all','course','global']).optional(),groupId:z.string().regex(/^\d{1,20}$/).optional(),refresh:z.boolean().optional()}, ({refresh,...args}) => api('/api/integrations/canvas/groups',{query:{...args,refresh:refresh?'1':undefined}}))
   tool('canvas_assignment_detail', 'Read the full assignment brief, due/unlock/lock dates, own submission status, grade, rubric and submission comments. Use Canvas numeric course and assignment IDs from canvas_updates. Direct the student to /app/updates?tab=assignments&assignment=COURSE_ID%3AASSIGNMENT_ID; Canvas remains a secondary link.', { canvasUrl, courseId: z.string().regex(/^\d+$/), assignmentId: z.string().regex(/^\d+$/), refresh: z.boolean().optional() }, ({ refresh, ...args }) => api('/api/integrations/canvas/assignment', { query: { ...args, canvasUrl: args.canvasUrl || defaultCanvasUrl, refresh: refresh ? '1' : undefined } }))
   tool('canvas_sync_logs', 'Inspect durable progress for one sync job, optionally filtered by stage or severity. before is the next cursor returned by an earlier page. Last progress and worker checkpoints are distinct; do not claim a task is advancing from its heartbeat alone.', { job: id, before: z.string().max(160).optional(), stage: z.string().max(40).optional(), level: z.enum(['info','warning','error']).optional() }, args => api('/api/account/integrations/canvas/corpus/logs', { query: args }))
   tool('canvas_sync_control', 'Stop or retry one owned course-edition sync, after the student requests that action. Retry resumes saved originals and unfinished stages; stop fences the running worker and pauses future material refreshes for that edition.', { jobId: id, action: z.enum(['stop','retry']) }, ({ jobId, action }) => api(`/api/integrations/canvas/corpus/jobs/${encodeURIComponent(jobId)}`, { method: 'POST', body: { action } }))
   tool('canvas_sync_course', 'Queue a specific accessible Canvas course edition. Current-period latest editions refresh automatically; use this for a missing or historical edition or an explicit refresh. Existing material consent is required; this cannot grant consent. force:false reuses verified unchanged resources.', { canvasUrl, canvasCourseId: z.string().regex(/^\d+$/), force: z.boolean().default(false) }, args => api('/api/integrations/canvas/corpus/course', { method: 'POST', body: { ...args, canvasUrl: args.canvasUrl || defaultCanvasUrl } }))
   tool('tutor_prepare_attendance_update', 'Prepare an exact attendance change without applying it or calling a model. First read get_attendance, then use its exact session IDs and the student’s explicit report. Show the returned proposal detail and ask for confirmation before tutor_confirm_update.', { courseCode: code, from: date, to: date, eventIds: z.array(id).min(1).max(20), status: z.enum(['attended','missed','unknown']), note: z.string().max(500).optional() }, body => api('/api/tutor/updates/prepare', { method: 'POST', body: { ...body, kind: 'attendance' } }))
-  tool('tutor_prepare_context', 'Prepare personal context for future Tutor answers without adding it to memory yet or calling a model. Examples: preferred explanation style, project role, or work every Tuesday/Friday. Store exact student-provided wording; optional dates bound temporary context. Availability is advice context, not proof of absence. Show the returned wording, dates and weekdays before requesting confirmation.', { kind: z.enum(['preference','availability','context']), text: z.string().min(1).max(400), weekdays: z.array(z.enum(['monday','tuesday','wednesday','thursday','friday','saturday','sunday'])).max(7).optional(), startDate: date, endDate: date }, body => api('/api/tutor/updates/prepare', { method: 'POST', body }))
+  tool('tutor_prepare_context', 'Proactively prepare lasting student preferences, project decisions/roles, constraints or availability learned during a conversation; do not wait for a reminder to save context. Read tutor_sources first to avoid duplicates or detect corrections. This prepares a draft, not saved memory, and calls no model. Preserve student-provided facts; dates bound temporary context. Availability is not proof of absence. Show exact wording/dates/weekdays and obtain confirmation before tutor_confirm_update.', { kind: z.enum(['preference','availability','context']), text: z.string().min(1).max(400), weekdays: z.array(z.enum(['monday','tuesday','wednesday','thursday','friday','saturday','sunday'])).max(7).optional(), startDate: date, endDate: date }, body => api('/api/tutor/updates/prepare', { method: 'POST', body }))
   tool('tutor_confirm_update', 'Apply the exact prepared attendance/context update only after the student explicitly confirms this individual write. Cannot edit the prepared payload. Review expires after 30 minutes; retries return the same receipt. Context becomes visible to future Tutor conversations in this account/programme.', { updateId: id, confirmed: z.literal(true) }, body => api('/api/tutor/updates/confirm', { method: 'POST', body }))
   tool('tutor_forget_context', 'Remove one remembered fact/preference/availability item after explicit confirmation. Read tutor_sources first to identify its exact memory ID.', { memoryId: id, confirmed: z.literal(true) }, ({ memoryId }) => api(`/api/tutor/memory/${encodeURIComponent(memoryId)}`, { method: 'DELETE' }))
   tool('tutor_history', 'List saved Tutor conversations without loading every transcript. Reuse the relevant conversation for follow-ups.', {}, () => api('/api/tutor', { query: { view: 'history' } }))

package/vendor/canvas-course-import.mjs

@@ -93,7 +93,7 @@ export function sanitizeCanvasHtml(value) {
     .replace(/\s+(href|src)\s*=\s*(?:"\s*javascript:[^"]*"|'\s*javascript:[^']*'|javascript:[^\s>]+)/gi, '')
 }
 
-function htmlRecord({ title, url, body, details = [] }) {
+export function htmlRecord({ title, url, body, details = [] }) {
   const rows = details.filter(([label, value]) => text(value)).map(([label, value]) => `<dt>${escapeHtml(label)}</dt><dd>${escapeHtml(value)}</dd>`).join('')
   return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)}</title></head><body>
@@ -589,9 +589,19 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
     try {
       const assignment = initial && Object.hasOwn(initial, 'description') ? initial : await api.getJson(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/assignments/${encodeURIComponent(id)}`)
       const title = assignment.name || source.title || 'Canvas assignment'
+      source = { ...source, assignmentId: id, assignmentTitle: title }
       const outputPath = pagePath(join(base, 'assignments'), position, title, `assignment-${id}`)
       await write(outputPath, htmlRecord({ title, url: assignment.html_url, body: assignment.description, details: [['Due', assignment.due_at], ['Unlocks', assignment.unlock_at], ['Available until', assignment.lock_at], ['Points possible', assignment.points_possible], ['Submission types', (assignment.submission_types || []).join(', ')], ['Grading type', assignment.grading_type]] }))
       const links = uniqueLinks(assignment.description, assignment.html_url || `${canvas.origin}/courses/${canvas.courseId}/assignments/${id}`, canvas.origin, canvas.courseId)
+      // Some courses expose attachments as structured file objects, in addition
+      // to links in the assignment HTML. Resolve through the course file API.
+      for (const attachment of Array.isArray(assignment.attachments) ? assignment.attachments : []) {
+        const fileId = String(attachment.id || '')
+        if (/^\d+$/.test(fileId)) {
+          linkedFilePosition++
+          await importFile(fileId, join(root, 'linked-files'), linkedFilePosition, { ...source, itemType: 'Assignment attachment', title: attachment.display_name || attachment.filename || title })
+        }
+      }
       records.push({ kind: 'assignment', id, source, path: outputPath.slice(root.length + 1), canvasUrl: assignment.html_url || null, links })
       await indexAndFollowLinks({ title, pageUrl: assignment.html_url || `${canvas.origin}/courses/${canvas.courseId}/assignments/${id}`, body: assignment.description, outputPath, source, id: `assignment-${id}`, links })
       return outputPath
@@ -612,7 +622,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
       const discussion = initial && Object.hasOwn(initial, 'message') ? initial : await api.getJson(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/discussion_topics/${encodeURIComponent(id)}`)
       const title = discussion.title || source.title || 'Canvas discussion'
       const outputPath = pagePath(join(base, 'discussions'), position, title, `discussion-${id}`)
-      await write(outputPath, htmlRecord({ title, url: discussion.html_url, body: discussion.message, details: [['Posted', discussion.posted_at], ['Discussion type', discussion.discussion_type], ['Due', discussion.delayed_post_at]] }))
+      await write(outputPath, htmlRecord({ title, url: discussion.html_url, body: discussion.message, details: [['Posted', discussion.posted_at], ['Discussion type', discussion.discussion_type], ['Scheduled publication', discussion.delayed_post_at]] }))
       const links = uniqueLinks(discussion.message, discussion.html_url || `${canvas.origin}/courses/${canvas.courseId}/discussion_topics/${id}`, canvas.origin, canvas.courseId)
       records.push({ kind: 'discussion', id, source, path: outputPath.slice(root.length + 1), canvasUrl: discussion.html_url || null, links })
       await indexAndFollowLinks({ title, pageUrl: discussion.html_url || `${canvas.origin}/courses/${canvas.courseId}/discussion_topics/${id}`, body: discussion.message, outputPath, source, id: `discussion-${id}`, links })
@@ -665,7 +675,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
   async function importTextItem(item, moduleBase, module) {
     const kind = String(item.type || '').toLowerCase()
     const itemId = String(item.id || item.content_id || `${module?.id || 'course'}-${item.position || 0}`)
-    const source = { moduleId: module?.id || null, moduleName: module?.name || null, itemId, itemType: item.type || 'Unknown', title: text(item.title, 300) }
+    const source = { moduleId: module?.id || null, moduleName: module?.name || null, modulePosition: module?.position ?? null, itemPosition: item.position ?? null, itemId, itemType: item.type || 'Unknown', title: text(item.title, 300) }
     if (kind === 'file') return importFile(item.content_id || item.content_details?.content_id, moduleBase, item.position, source)
     if (kind === 'subheader') return null
     try {
@@ -704,7 +714,7 @@ export async function importCanvasCourse({ courseUrl, accessToken, outputFolder,
 
   for (const module of selectedModules.sort((left, right) => number(left.position) - number(right.position))) {
     const moduleBase = join(root, 'modules', `${prefix(module.position)} ${safeSegment(module.name)}--module-${safeSegment(module.id)}`)
-    if (durable) module.items = await api.getPaged(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/modules/${encodeURIComponent(module.id)}/items?per_page=100`)
+    if (durable || !Array.isArray(module.items) || Number(module.items_count) > module.items.length) module.items = await api.getPaged(`/api/v1/courses/${encodeURIComponent(canvas.courseId)}/modules/${encodeURIComponent(module.id)}/items?per_page=100`)
     const hierarchy = []
     for (const item of (Array.isArray(module.items) ? module.items : []).sort((left, right) => number(left.position) - number(right.position))) {
       const indent = Math.min(12, Math.max(0, number(item.indent)))