neuro-canvas-lms 2.12.0 → 2.13.1

package/AGENTS.md

@@ -2,8 +2,8 @@
 
 This repo, **Neuro-CanvasLMS** (`neuro-canvas-lms`), is a read-only Canvas LMS connector (remote MCP
 server on Cloudflare Workers) that each user deploys to their **own** Cloudflare account. It works
-with any Canvas school; nothing school-specific is in the code (the school comes from Worker vars).
-It is a community project provided as is.
+with any Canvas school that lets students create access tokens; nothing school-specific is in the
+code (the school comes from Worker vars). It is a community project provided as is.
 
 - To install, update, reconnect, uninstall or troubleshoot: follow
   `.claude/skills/canvas-connector-setup/SKILL.md` (Claude Code loads it as a skill; other agents
@@ -30,9 +30,17 @@ Code map:
   `download-link.mjs` (one-time, minutes-long Canvas storage link so coding agents can curl an original
   file to disk).
 - `owner.mjs`: owner binding, allowed OAuth clients. `i18n.mjs` + `pages.mjs`: web pages.
+  `page-scene.mjs`: their one script (allowed by its hash in the CSP; pages stay off the network):
+  the black-hole scene and the step-by-step authorization. Everything works without it.
 - `update-check.mjs`: once a day reads the newest version number from npm; when it is newer the AI
   tells the user how to update. Also the `canvas_connector_version` tool.
-- `installer/`: the setup wizard. Re-running it asks once (y/n), then updates with the saved
+- `installer/`: the setup wizard. On a new Cloudflare account it registers a random workers.dev
+  subdomain through Cloudflare's API. Re-running it asks once (y/n), then updates with the saved
   settings (without a terminal it does not ask). `installer/verify.mjs`: the post-deploy online
   check, also run alone by `npx -y neuro-canvas-lms check`.
 - `version.mjs`: shown on the home page and /healthz, compared with npm by update-check.mjs.
+- `server.json`: the entry in the official MCP Registry (one remote whose host each user fills in).
+  Same version as `version.mjs` and package.json (`version.test.mjs`).
+- Releases: bump those three, push to main, then push a tag `vX.Y.Z`;
+  `.github/workflows/publish.yml` tests, publishes to npm and updates the MCP Registry, with
+  no stored secrets (OIDC trusted publishing).

package/README.md

@@ -2,9 +2,13 @@
 
 **English** · [简体中文](docs/README.zh-CN.md) · [Español](docs/README.es.md) · [日本語](docs/README.ja.md) · [हिन्दी](docs/README.hi.md)
 
-**Wire your Canvas LMS straight into Claude and ChatGPT.** Your courses, deadlines, grades and lecture files become part of what your AI knows, in any chat and on any device. Works with any school that uses Canvas.
+[![npm](https://img.shields.io/npm/v/neuro-canvas-lms?label=npm&color=c9a462)](https://www.npmjs.com/package/neuro-canvas-lms) [![tests](https://github.com/BloodyReginaa/Neuro-CanvasLMS/actions/workflows/test.yml/badge.svg)](https://github.com/BloodyReginaa/Neuro-CanvasLMS/actions/workflows/test.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/BloodyReginaa/Neuro-CanvasLMS/blob/main/LICENSE)
 
-> "What's due this week?" · "Summarize Lecture 5 in MATH 132." · "What feedback did I get on HW 3?" · "What's in the code ZIP for Lecture 12?"
+![Neuro-CanvasLMS answering "What's due this week?" in Claude](https://raw.githubusercontent.com/BloodyReginaa/Neuro-CanvasLMS/main/docs/images/banner.png)
+
+**Wire your Canvas LMS straight into Claude and ChatGPT.** Your courses, deadlines, grades and lecture files become part of what your AI knows, in any chat and on any device. It is a read-only remote MCP server that one command deploys to your own free Cloudflare account. Works at any Canvas school that lets students create access tokens ([30-second check](#can-you-use-it)).
+
+> "What's due this week?" · "Summarize Lecture 5 in MATH 132." · "What feedback did I get on HW 3?" · "What's in the code ZIP for Lecture 12?" · "Set up the PA2 starter code in this folder."
 
 ## Why Neuro-CanvasLMS
 
@@ -15,7 +19,7 @@
 | 💸 **Free** | It runs on Cloudflare's free plan, which is far more than one student needs. |
 | 🧠 **Your files live in the conversation** | Lecture notes and PDFs the AI reads stay with that chat on your AI provider's servers. Nothing to download. |
 
-Most Canvas integrations for AI are **local** tools: they only work while your own computer runs them, and only inside desktop or coding apps. Neuro-CanvasLMS is a **remote connector** that runs in your own Cloudflare account, so it also works on your phone and in ChatGPT.
+Local Canvas tools only work while your own computer runs them. Hosted services keep your Canvas token, or a copy of your courses, on their servers. Neuro-CanvasLMS runs in **your own** Cloudflare account: always on, usable from your phone and in ChatGPT, and your token goes only to your own Worker and your school's Canvas.
 
 ## What you get
 
@@ -23,20 +27,25 @@ Most Canvas integrations for AI are **local** tools: they only work while your o
 - **Real file reading:** text from PDF, Word, PowerPoint and Excel, about 90 kinds of code and text files, and Jupyter notebooks (cells and outputs); ZIP archives unpacked on the server (listing plus every code/text file); scanned or handwritten PDFs are recognised and their original pages handed to the AI to look at.
 - **Linked files too:** course files that a module links on Google Docs/Slides/Sheets, Google Drive, Dropbox (files and folders) and GitHub (files and repositories) are read as text, as long as they are shared publicly ("Anyone with the link").
 - **Finds files the course hides:** many courses hide their Files list from students. The connector searches the front page, syllabus, modules, assignments, announcements and the pages they link to, so the AI can still find "the Lecture 12 slides" by name.
+- **Starter code onto your computer:** in Claude Code, Codex and other coding agents, ask "set up PA2 from Canvas". The agent gets a one-time download link that expires in minutes, saves the assignment's starter files in your folder and unpacks them.
 - **Read-only by design:** only fixed `GET` requests. It never submits work, sends messages, starts quizzes or changes anything in Canvas.
 - **Yours only:** deployed in your own Cloudflare account and locked to your own Canvas account. Nobody else, including the authors, ever sees your Canvas token.
 
+## Can you use it?
+
+Check in 30 seconds: in Canvas, open **Account → Settings** and scroll to **Approved Integrations**. If you see a **+ New Access Token** button, you're set. If it is missing, or creating a token is refused, your school doesn't let students make personal tokens, and this connector can't work there yet.
+
 ## Install (about 5 minutes)
 
-You need [Node.js 22+](https://nodejs.org), a free [Cloudflare account](https://dash.cloudflare.com/sign-up) and your Canvas login. In a terminal, run:
+You need [Node.js 22+](https://nodejs.org), a free [Cloudflare account](https://dash.cloudflare.com/sign-up) (verify its email address) and your Canvas login. In a terminal, run:
 
 ```bash
 npx -y neuro-canvas-lms
 ```
 
-The installer signs you in to Cloudflare (a browser page opens; click **Authorize**), asks for your school's Canvas address, deploys the connector to your own account and checks that it works. Then:
+The installer signs you in to Cloudflare (a browser page opens; click **Authorize**), asks for your school's Canvas address, sets up your free workers.dev address if the account is new, deploys the connector to your own account and checks that it works. A new address can take a few minutes to come online; meanwhile the installer opens Canvas so you can create your token. Then:
 
-1. **Create a Canvas token:** Canvas → Account → Settings → **+ New Access Token**. Your school may cap its lifetime (30 days at UMass Amherst). Copy it right away; Canvas shows it only once.
+1. **Create a Canvas token** (if you haven't yet): Canvas → Account → Settings → **+ New Access Token**. Your school may cap its lifetime (30 days at UMass Amherst). Copy it right away; Canvas shows it only once.
 2. **Claude:** Settings → Connectors → **Add custom connector** → paste the URL the installer printed (it is already copied) → **Connect** → paste the Canvas token → Authorize. It then works everywhere you use Claude, including the mobile app and Claude Code.
 3. **ChatGPT:** add a custom connector (developer mode) with the same URL.
 4. Start a new chat and ask: "What assignments do I have this week?"

package/canvas-transport.mjs

@@ -135,9 +135,12 @@ export async function parseCanvasResponse(bytes) {
 }
 // A JSON answer is Canvas itself speaking; HTML (or a 406) means something in front of Canvas
 // rejected the request, which is when the socket path is worth trying.
+// A rate limit (429, or Canvas's own 403 carrying X-Rate-Limit-Remaining) is Canvas speaking too:
+// asking again at once over the socket would only add to the count.
 export function shouldFallBack(response) {
   if (response.status === 406) return true;
-  if (response.status < 400) return false;
+  if (response.status < 400 || response.status === 429) return false;
+  if (response.headers.has('x-rate-limit-remaining')) return false;
   return !(response.headers.get('content-type') ?? '').toLowerCase().includes('json');
 }
 

package/canvas.mjs

@@ -229,27 +229,87 @@ export async function callCanvas(name, args, token, fetcher = fetch, opts = {})
   return out;
 }
 
+// Canvas could not be reached at all: say so (and that the connection is fine), so the AI retries
+// instead of changing its arguments. Our own transport messages already start with "Canvas".
+export function unreachable(e) {
+  if (/^Canvas/.test(e?.message ?? '')) return e;
+  const timeout = e?.name === 'TimeoutError' || e?.name === 'AbortError';
+  return Object.assign(
+    new Error(
+      timeout
+        ? 'Canvas did not answer within 20 seconds; it may be slow or down right now. Try again in a minute. The token and the connection are fine: do not reconnect.'
+        : `Canvas could not be reached (network error: ${e?.name ?? 'Error'}). Try again in a minute. The token and the connection are fine: do not reconnect.`,
+    ),
+    { unreachable: true, cause: e },
+  );
+}
+
 // One GET to the Canvas API: fixed headers, no redirects, Canvas errors turned into safe messages
 // (never the upstream body). `e.status` is set when Canvas refused this item (not a token problem).
+// Canvas throttles API use per token: it answers "403 Forbidden (Rate Limit Exceeded)" (its own
+// answers carry X-Rate-Limit-Remaining), and a proxy in front may answer 429. That is not "this
+// course hides its files" (no find_files hint, no retry over the socket): the AI is told to wait.
+// The error has no `status`, so nothing treats it as a hidden resource.
+async function rateLimit(r) {
+  if (r.status !== 429 && r.status !== 403) return null;
+  let limited = r.status === 429;
+  if (!limited) {
+    const remaining = r.headers.get('x-rate-limit-remaining');
+    if (remaining !== null && Number(remaining) <= 0) limited = true;
+    else if (!(r.headers.get('content-type') ?? '').includes('json'))
+      try {
+        limited = /rate limit/i.test((await r.clone().text()).slice(0, 2000));
+      } catch {}
+  }
+  if (!limited) return null;
+  await r.body?.cancel().catch(() => {});
+  const seconds = Number(r.headers.get('retry-after'));
+  const wait =
+    Number.isFinite(seconds) && seconds > 0
+      ? `${Math.min(Math.ceil(seconds), 3600)} seconds`
+      : 'about a minute';
+  return Object.assign(
+    new Error(
+      `Canvas rate limit reached (HTTP ${r.status}): too many Canvas requests in a short time. Wait ${wait} before the next Canvas call and do not retry in a loop. The token and the connection are fine; this is not a permission problem.`,
+    ),
+    { rateLimited: true },
+  );
+}
+
 export async function canvasGet(u, token, fetcher = fetch) {
-  const r = await fetcher(u, {
-    method: 'GET',
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: 'application/json',
-      'User-Agent': 'Neuro-CanvasLMS/2.0 (read-only personal integration)',
-    },
-    redirect: 'manual',
-    signal: AbortSignal.timeout(20000),
-  });
+  let r;
+  try {
+    r = await fetcher(u, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json',
+        'User-Agent': 'Neuro-CanvasLMS/2.0 (read-only personal integration)',
+      },
+      redirect: 'manual',
+      signal: AbortSignal.timeout(20000),
+    });
+  } catch (e) {
+    throw unreachable(e);
+  }
+  const limited = await rateLimit(r);
+  if (limited) throw limited;
   if (
     r.status === 406 ||
     (r.status >= 500 && !(r.headers.get('content-type') ?? '').includes('json'))
   ) {
-    // Canvas answers its API with JSON. An HTML error page means a firewall in front of Canvas
-    // rejected the request, or Canvas failed on a malformed token (it returns an HTML 500 for that).
-    throw new Error(
-      `Canvas returned an HTML error page (HTTP ${r.status}) instead of JSON: a firewall in front of Canvas rejected the request, or the token is malformed. If it persists, reconnect with a freshly created token.`,
+    // Canvas answers its API with JSON. An HTML error page means Canvas is down or in maintenance
+    // (502/503/504 from the load balancer), a firewall in front of Canvas rejected the request, or
+    // Canvas failed on a malformed token (an HTML 500; only possible on the authorization page,
+    // since a connected token already passed). The phrase "HTML error page" stops canvas_find_files.
+    await r.body?.cancel().catch(() => {});
+    throw Object.assign(
+      new Error(
+        [502, 503, 504].includes(r.status)
+          ? `Canvas is temporarily unavailable (HTTP ${r.status}, an HTML error page instead of JSON). Try again in a few minutes. The token and the connection are fine: do not reconnect.`
+          : `Canvas returned an HTML error page (HTTP ${r.status}) instead of JSON: usually a temporary Canvas problem or a firewall in front of Canvas. Try again in a few minutes; reconnecting does not help.`,
+      ),
+      { htmlError: r.status },
     );
   }
   if (r.status === 401) {
@@ -276,7 +336,14 @@ export async function canvasGet(u, token, fetcher = fetch) {
       ),
       { status: r.status },
     );
-  const data = await r.json();
+  let data;
+  try {
+    data = await r.json();
+  } catch {
+    throw new Error(
+      `Canvas answered HTTP ${r.status} but not with JSON (a maintenance or login page in between?). Try again in a few minutes; the token and the connection are fine.`,
+    );
+  }
   const next = nextPage(r.headers.get('link'));
   // api_url is the API request itself (it shows JSON); links for the user are the html_url fields.
   return { data, has_more: next !== null, next_page: next, api_url: u.href };
@@ -299,12 +366,22 @@ const FEED = /https?:\/\/[^\s"'<>()]*\/feeds\/[^\s"'<>()]+/gi;
 const LINK = /(?:https?:\/\/|\/api\/v1\/(?:canvadoc|crocodoc)_session)[^\s"'<>()]*/gi;
 const SIGNED =
   /(?:canvadoc|crocodoc)_session|[?&](?:amp;)?(?:sf_verifier|hmac|x-amz-signature|signature)=|[?&](?:amp;)?token=[\w-]+\.[\w-]+\.[\w-]+/i;
-const SIGNED_KEYS = new Set(['canvadoc_session_url', 'crocodoc_session_url']);
+// A file's `uuid` is the verifier itself (Canvas accepts ?verifier=<uuid>) and its thumbnail_url
+// carries it in the path; a course's uuid is the key of its calendar feed. Raw results lose them.
+const SIGNED_KEYS = new Set([
+  'canvadoc_session_url',
+  'crocodoc_session_url',
+  'uuid',
+  'thumbnail_url',
+]);
+// The same pass URL-encoded inside another link (e.g. a login page's return_to=).
+const ENCODED_VERIFIER = /verifier%3D[^&#"'\s<>()%]*/gi;
 export function withoutVerifiers(value) {
   if (typeof value === 'string') {
     let v = value;
     if (v.includes('verifier='))
       v = v.replace(VERIFIER, (m, before, after) => (after ? before : ''));
+    if (/verifier%3D/i.test(v)) v = v.replace(ENCODED_VERIFIER, 'verifier%3D');
     if (v.includes('/feeds/')) v = v.replace(FEED, '[private feed link removed]');
     if (/[?]|_session/.test(v))
       v = v.replace(LINK, link => (SIGNED.test(link) ? '[signed link removed]' : link));

package/download-link.mjs

@@ -160,12 +160,20 @@ export function newDownloadId() {
     .replace(/=+$/, '');
 }
 
+// Cloudflare KV failed (briefly unavailable, or the free plan's 1000 writes a day are used up).
+export const STORAGE_DOWN =
+  "Connector storage (Cloudflare KV) is unavailable right now, so no download link could be made. It is often the free plan's daily KV limit, which resets at 00:00 UTC. Meanwhile use canvas_file_original or canvas_file_content; the Canvas connection itself is fine.";
+
 // Store the Canvas address for 5 minutes and return the Worker link that leads to it.
 export async function issueDownload(kv, origin, target, now = Date.now) {
   const id = newDownloadId();
-  await kv.put('dl:' + id, JSON.stringify({ target, exp: now() + DOWNLOAD_TTL * 1000 }), {
-    expirationTtl: DOWNLOAD_TTL,
-  });
+  try {
+    await kv.put('dl:' + id, JSON.stringify({ target, exp: now() + DOWNLOAD_TTL * 1000 }), {
+      expirationTtl: DOWNLOAD_TTL,
+    });
+  } catch {
+    throw new Error(STORAGE_DOWN);
+  }
   return `${origin}/dl/${id}`;
 }
 
@@ -188,11 +196,22 @@ export async function redeemDownload(request, kv, id, now = Date.now) {
       { status: 403, headers: plain },
     );
   const key = 'dl:' + id;
+  let stored;
+  try {
+    stored = await kv.get(key);
+  } catch {
+    // not "expired": the link may be fine, the storage is not
+    return new Response(
+      "The connector's storage (Cloudflare KV) is unavailable right now. Try again in a minute; if it keeps failing, the free plan's daily limit may be used up (it resets at 00:00 UTC).\n",
+      { status: 503, headers: plain },
+    );
+  }
   let entry = null;
   try {
-    entry = JSON.parse((await kv.get(key)) ?? 'null');
+    entry = JSON.parse(stored ?? 'null');
   } catch {}
-  if (entry) await kv.delete(key);
+  // Used up before it is used: a failed delete does not stop this download (it still expires).
+  if (entry) await kv.delete(key).catch(() => {});
   // KV expiry can lag a little: the stored deadline is checked too.
   if (!entry?.target || !(now() < entry.exp))
     return new Response(

package/file-content.mjs

@@ -226,6 +226,20 @@ export async function extractBytes(bytes, shown, mime = '', opts = {}) {
       'This format is not supported for text extraction. Call canvas_file_original with this file_id to get the original file.',
   };
 }
+// extractBytes, but a parser failing on the file itself (damaged, password-protected, or not really
+// a PDF/Office file) becomes a note with a way on instead of an error the AI reads as "check your
+// arguments". Our own messages (limits, a wrong `entry`) start with "Canvas" and go through.
+export async function extractOrExplain(bytes, name, mime, opts, wayOn) {
+  try {
+    return await extractBytes(bytes, name, mime, opts);
+  } catch (e) {
+    if (/^Canvas/.test(e?.message ?? '')) throw e;
+    return {
+      text: null,
+      extraction_note: `Could not read the text of this file (${e?.name ?? 'Error'}): it may be damaged, password-protected, or not really the type its name says. ${wayOn}`,
+    };
+  }
+}
 export async function readFileContent(meta, args, fetcher = fetch) {
   // `hidden` files are only hidden from the Files list ("only available with link"), which is how
   // many courses share files; students may open them. Only a lock stops a download.
@@ -237,7 +251,14 @@ export async function readFileContent(meta, args, fetcher = fetch) {
     html_url: `https://${CANVAS_HOST}/files/${meta.id}`,
     mime_type: meta['content-type'],
   };
-  if (!meta.url || !allowedDownload(meta.url))
+  if (!meta.url)
+    return {
+      ...base,
+      text: null,
+      extraction_note:
+        'Canvas gives no download address for this file (it may only be viewable inside Canvas); open html_url.',
+    };
+  if (!allowedDownload(meta.url))
     return {
       ...base,
       text: null,
@@ -262,14 +283,22 @@ export async function readFileContent(meta, args, fetcher = fetch) {
       throw new Error(
         'Canvas file redirect host is not allowed: ' + [...hops, where(url)].join(' → '),
       );
-    response = await fetcher(url, {
-      method: 'GET',
-      redirect: 'manual',
-      headers: { Accept: '*/*', 'User-Agent': DOWNLOAD_UA },
-      signal: AbortSignal.timeout(20000),
-    });
+    try {
+      response = await fetcher(url, {
+        method: 'GET',
+        redirect: 'manual',
+        headers: { Accept: '*/*', 'User-Agent': DOWNLOAD_UA },
+        signal: AbortSignal.timeout(20000),
+      });
+    } catch (e) {
+      if (/^Canvas/.test(e?.message ?? '')) throw e;
+      throw new Error(
+        `Canvas file download did not finish (${e?.name === 'TimeoutError' || e?.name === 'AbortError' ? 'no answer within 20 seconds' : 'network error: ' + (e?.name ?? 'Error')}; ${where(url)}). Try again in a minute; the connection is fine.`,
+      );
+    }
     hops.push(response.status + ' ' + where(url));
     if (response.status >= 300 && response.status < 400) {
+      await response.body?.cancel().catch(() => {});
       const location = response.headers.get('location');
       if (!location) throw new Error('Canvas download redirect is missing its destination.');
       url = new URL(location, url).href;
@@ -293,11 +322,12 @@ export async function readFileContent(meta, args, fetcher = fetch) {
         (response.headers.get('content-type') ?? 'unknown').split(';')[0] +
         ').',
     );
-  const extracted = await extractBytes(
+  const extracted = await extractOrExplain(
     await boundedBytes(response),
     base.name ?? '',
     base.mime_type ?? response.headers.get('content-type') ?? '',
     { entry: args.entry, storedName: meta.filename },
+    'Call canvas_file_original with this file_id to get the file itself, or open html_url.',
   );
   return paginated(base, extracted, args);
 }

package/find-files.mjs

@@ -180,14 +180,26 @@ export async function findFiles(args, token, fetcher) {
     return canvasGet(u, token, fetcher);
   };
   const searched = {};
-  // One source failing (hidden, not enabled) is normal; an expired token stops everything.
+  // A source being hidden or not enabled (401/403/404) is normal. A source that failed (timeout,
+  // network, rate limit, Canvas error) was not searched: the result is then incomplete, and if
+  // nothing could be searched at all the error is passed on instead of an empty "complete" list.
+  // An expired token, a rate limit or an HTML error page (Canvas down, a firewall) stops everything.
+  const failures = [];
+  const hidden = e => [401, 403, 404].includes(e.status);
+  const stops = e =>
+    e.rateLimited || /authorization expired|HTML error page/.test(e?.message ?? '');
   const attempt = async (source, run) => {
     try {
       const n = await run();
       searched[source] = n === undefined ? 'ok' : `ok (${n})`;
     } catch (e) {
-      if (/authorization expired|HTML error page/.test(e.message ?? '')) throw e;
-      searched[source] = e.status ? `not available (HTTP ${e.status})` : 'failed';
+      if (stops(e)) throw e;
+      if (hidden(e)) searched[source] = `not available (HTTP ${e.status})`;
+      else {
+        failures.push(e);
+        complete = false;
+        searched[source] = e.status ? `failed (HTTP ${e.status})` : 'failed';
+      }
     }
   };
   const pagesOf = async (path, query, maxPages, each) => {
@@ -337,7 +349,8 @@ export async function findFiles(args, token, fetcher) {
 
   // Pages linked from everything above, breadth first, never outside this course.
   let pagesRead = 0,
-    pagesUnavailable = 0;
+    pagesUnavailable = 0,
+    pagesFailed = 0;
   while (queue.length) {
     const batch = queue.splice(0, PAGE_BATCH).filter(slug => !read.has(slug));
     await Promise.all(
@@ -354,8 +367,13 @@ export async function findFiles(args, token, fetcher) {
             page_url: r.data?.url ?? slug,
           });
         } catch (e) {
-          if (/authorization expired|HTML error page/.test(e.message ?? '')) throw e;
-          pagesUnavailable++;
+          if (stops(e)) throw e;
+          if (hidden(e)) pagesUnavailable++;
+          else {
+            failures.push(e);
+            complete = false;
+            pagesFailed++;
+          }
         }
       }),
     );
@@ -365,7 +383,20 @@ export async function findFiles(args, token, fetcher) {
     }
   }
   searched.linked_pages =
-    `${pagesRead} read` + (pagesUnavailable ? `, ${pagesUnavailable} not available` : '');
+    `${pagesRead} read` +
+    (pagesUnavailable ? `, ${pagesUnavailable} not available` : '') +
+    (pagesFailed ? `, ${pagesFailed} failed` : '');
+  const sources = Object.entries(searched).filter(([k]) => k !== 'linked_pages');
+  // Nothing could be searched: say why instead of "no files, complete".
+  if (failures.length && !pagesRead && !sources.some(([, v]) => v.startsWith('ok'))) {
+    const e = failures.find(x => /^Canvas/.test(x.message ?? '')) ?? failures[0];
+    throw /^Canvas/.test(e.message ?? '')
+      ? e
+      : new Error(`Canvas could not be searched (${e.name}). Try again in a minute.`);
+  }
+  // Every source 404: most likely not a course this user is in.
+  const wrongCourse =
+    !files.size && sources.length && sources.every(([, v]) => v === 'not available (HTTP 404)');
 
   let list = [...files.values()];
   let matchedOn = null;
@@ -393,11 +424,21 @@ export async function findFiles(args, token, fetcher) {
     external_links: ext,
     searched,
     complete,
-    ...(complete
-      ? {}
-      : {
-          note: `Stopped after ${requests} Canvas requests; some linked pages or lists were not searched. Open more pages with canvas_context_page or canvas_module_items if the file is not listed.`,
-        }),
+    ...(failures.length
+      ? {
+          note: `Some places could not be searched (they failed, see searched: ${failures.length} failed request${failures.length > 1 ? 's' : ''}), so a file missing here may still exist. Try again in a minute before telling the user it is not there.`,
+        }
+      : complete
+        ? {}
+        : {
+            note: `Stopped after ${requests} Canvas requests; some linked pages or lists were not searched. Open more pages with canvas_context_page or canvas_module_items if the file is not listed.`,
+          }),
+    ...(wrongCourse
+      ? {
+          course_note:
+            'Every part of this course answered 404: check the course_id (canvas_courses lists the user’s courses).',
+        }
+      : {}),
     how_to_read:
       'Read a file_id with canvas_file_content (text from PDF/Office/code, ZIP listing and contents) or canvas_file_original (original bytes, e.g. scanned PDFs). An external link with read_with (a module item): call canvas_module_file_content with those IDs for its text (Google Docs/Slides/Sheets/Drive, Dropbox, GitHub), or canvas_module_file for the original file. Other external links cannot be read by this connector: give the user the link.',
   };