Canvas Setup

canvas-setup (first-run configurator)

This skill replaces the old "Helping the student configure" prose section in CLAUDE.md. The prose was a set of negative rules ("never say pip install") that CC had to apply on top of free-form judgment. This skill is the positive version: a fixed N-step script. Every step specifies (a) what CC does silently, (b) what CC says to the student, (c) what CC waits for. CC walks the script; CC does not improvise.

Why this skill exists (read this before editing)

The friend test (2026-05-02) found 12 setup-related UX bugs, all rooted in the same behavior: CC was reading framework docs (SETUP.md, .env.example comments, error tables) and parroting them at the student as a tutorial. Friend was told to pip install herself, edit .env herself, navigate Canvas back-office herself — even though CC has Bash/Edit/Write tools to do all of it. See .claude/plans/public-setup-ux-bugs.md for the full incident list.

The fix is not more prose rules in CLAUDE.md. The fix is making first-run a fixed sequence the SKILL.md mechanism enforces: CC dispatches this skill, walks the steps, returns. The student's only legitimate actions are answering domain questions (Canvas URL, which courses) and logging into Canvas once in a popup browser. Every other "step" the friend ever did manually (cp .env.example .env, pip install, edit env vars, run setup.py) is now CC's silent work.

Hard rules CC follows the entire way through this skill

The student's only legitimate actions during this skill:

1. Answering questions CC asks about their own situation (Canvas URL, which courses).
2. Logging into Canvas once in a browser window CC pops up.

Anything else is CC's job. If CC catches itself about to write a sentence telling the student to "open .env", "run pip install", "go to Canvas → Account → Settings → Approved Integrations", "copy this command into your terminal", "edit courses.yaml" — that is the bug this skill exists to prevent. Stop, do it with Bash/Edit/Write, and tell the student "我刚做了 X" / "I just did X" instead.

Internal vocabulary the student never sees: pip, playwright, chromium, cookie, token, probe, SSO, Duo, .env, courses.yaml, SECRETS.md, __PROJECT_ROOT__, ${CLAUDE_PROJECT_DIR}, runs/..., .cookies/..., any Canvas API field name, any course/user/file _id. These are fine in CC's internal reasoning; they are forbidden in user-facing output.

One question per turn: each user-facing message ends with at most one question. Multi-question turns are a bug.

Slow operations get one ETA + parsed progress: any Bash command that may take >30s runs with run_in_background=true, gets one upfront time estimate covering the whole bundle (e.g. "等我装下浏览器组件，3-10 分钟看你网速"), and gets monitored with progress reported as numbers ("下载到 30 MB / 165 MB, ~1 Mbps, 还要 5 分钟"). Never repeat-emit "继续等" with no new information.

Multi-command operations bundle into one Bash call: pip install playwright && python -m playwright install chromium runs as ONE command, not two separate "等一下" turns. Use && so failures stop the chain.

What you do

Step 1 — Open with value, ask consent

CC's silent action: none yet.

CC says (literal pin, pick the language matching the student's first message):

这是 Canvas 作业自动化工具。我会扫你这学期的 Canvas，列出待交作业，每周帮你处理重复性的（阅读注释、刷题、quiz 之类），交付前给你审批。要开始吗？

This is Canvas Pilot. I scan your Canvas, list what's pending, and each week help you draft the recurring stuff (reading annotations, quizzes, problem sets) — you review before anything gets submitted. Want to start?

CC waits for: any affirmative (yes/好/行/ok/嗯/start/开始). If the student says no or asks something else, answer their question and wait — do not advance to step 2.

Step 2 — Get the Canvas URL

CC asks for the school, not the URL — CC will find the URL itself.

CC says:

你哪个学校？学校名或域名都行（比如学校的简称或 <your-school>.edu）。

Which school do you go to? Name or domain works (e.g. your school's short name or <your-school>.edu).

CC waits for: a school identifier (name / domain / anything searchable). If the student volunteered school context in an earlier message (email domain like name@<school>.edu, or SSO URL like shib.service.<school>.edu/idp/...), CC may skip the question — extract the school silently from the prior message (base domain <school>.edu from email or SSO host).

CC's silent action: discover + verify the Canvas URL.

1. WebSearch <school> canvas login. From the result list, pick the first URL whose host matches Canvas-shaped patterns:

   • canvas.<anything>.edu
   • <anything>.instructure.com
   • gocanvas.<anything> (Stanford-style)
   • <anything>.canvas.<anything>

   If none of the WebSearch results match these patterns → skip to step 4 (fallback).

2. WebFetch <candidate> (the host root — Canvas root returns the login page or a /login redirect for unauthenticated users, and either way emits Canvas signature strings). The Canvas signature is any of:

   • HTML contains Canvas by Instructure
   • HTML contains canvas-login or /login/canvas form action
   • HTML contains instructure (case-insensitive)

3. If WebFetch succeeded AND signature matched → silently normalize and use:

   import re
   host_only = re.match(r"(https?://[^/]+)", candidate).group(1).rstrip("/")
   CANVAS_WEB_BASE = host_only
   CANVAS_BASE = host_only + "/api/v1"

   Advance to Step 3. Do NOT confirm with the student — they'll see the domain in Step 6 when the browser pops up.

4. Fallback — triggered when WebSearch returned no Canvas-shaped candidate, OR WebFetch failed (timeout / non-200 / permission deny), OR signature didn't match.

   CC says:

   查不到你们学校的 Canvas 地址 — 直接给我 Canvas 登录页的网址就行（比如 canvas.<your-school>.edu）。

   Couldn't find your school's Canvas — give me the Canvas login page URL directly (e.g. canvas.<your-school>.edu).

   When the student replies:

   4a. If the manual input looks like an SSO URL (host starts with shib. / idp. / sso. / login. subdomain prefix): extract the base domain (e.g. shib.service.<school>.edu → <school>.edu), re-run step 1 + step 2 once with the extracted school. If that round succeeds, use it silently and advance to Step 3. If it still fails, fall through to step 4b.

   4b. Otherwise normalize the manual URL as before:

   raw = student_input.strip()
   if not raw.startswith("http"):
       raw = "https://" + raw
   host_only = re.match(r"(https?://[^/]+)", raw).group(1).rstrip("/")
   CANVAS_WEB_BASE = host_only
   CANVAS_BASE = host_only + "/api/v1"

   If the manual input doesn't match https?://[a-z0-9.-]+ after normalization, ask once more without explaining regex: "我没认出来这是个 Canvas 网址 — 直接给我学校 Canvas 登录页那个地址就行。"

Step 3 — Tell the student a browser will pop up

CC's silent action: none yet.

CC says (literal pin):

配 Canvas 连接需要一次浏览器登录——我等会儿弹一个浏览器，你像平时一样登 Canvas 就行。session 偶尔过期了浏览器会再弹一下让你重登几秒，你不需要手动找或粘任何东西。

Setting up the Canvas connection needs a one-time browser login — I'll pop a browser, you log in like normal. If the session ever expires the browser pops up again for ~10 seconds. You don't need to find or copy anything manually.

CC waits for: any affirmative or silence (default: continue). If the student asks why / wants alternatives / is worried, answer their question briefly and continue once they're ready. Do not surface alternative auth paths — there is only one supported path.

Step 4 — Install browser components

First check whether playwright + chromium are already installed (single Python check, not a user-visible question):

import subprocess, sys
result = subprocess.run(
    [sys.executable, "-c", "import playwright; from playwright.sync_api import sync_playwright; p=sync_playwright().start(); p.chromium.launch(headless=True).close(); p.stop()"],
    capture_output=True, text=True, timeout=30
)
already_installed = result.returncode == 0

If already_installed → skip to Step 5 silently, say nothing.

If not installed → CC says (literal pin):

等我装下浏览器组件——3-10 分钟看你网速，第一次比较慢。我会同步进度。

Installing the browser components — 3-10 minutes depending on your connection. I'll keep you posted.

CC then runs ONE bundled Bash command in background:

pip install playwright && python -m playwright install chromium 2>&1 | tee /tmp/canvas_setup_install.log

(Use run_in_background=true. On Windows replace /tmp with a project-relative tmp dir.)

CC monitors the log file every 30-60 seconds. Each time CC reports, it must extract numbers from the log:

• playwright install chromium prints Downloading Chrome ... [progress bar] X% of YMb — parse to "下载到 X MB / Y MB"
• divide bytes-downloaded by elapsed time → throughput in Mbps
• (Y - X) / throughput → ETA in minutes

CC says (literal pin format):

下载到 30 MB / 165 MB，~1 Mbps，还要 5 分钟。网慢的话再等等就行。

30 MB / 165 MB downloaded, ~1 Mbps, ~5 min left. Hang tight if your connection is slow.

Suppression rule: if CC's last status update was <2 minutes ago AND the new numbers haven't moved meaningfully (same X MB), CC stays silent. Repeat-emitting "继续等" / "still downloading" with no new info is a bug.

If install fails (non-zero exit, network error, disk full): CC reads the tail of the log, surfaces the actual error in plain language ("下载断了，看起来是网络问题——要不要再试一次？"), and waits for the student's call.

Step 5 — Write .env silently

CC's silent action: write .env file. Never ask the student to do this.

env_content = (
    "CANVAS_AUTH=cookie\n"
    f"CANVAS_BASE={CANVAS_BASE}\n"
    f"CANVAS_WEB_BASE={CANVAS_WEB_BASE}\n"
)

Use Write tool. Do not announce ".env written" or any filename to the student.

If a .env already exists (e.g. student is re-running setup): read it first; preserve any non-Canvas keys the student may have added; only overwrite CANVAS_AUTH=cookie + CANVAS_BASE + CANVAS_WEB_BASE.

Escape hatch preservation: if the existing .env has CANVAS_AUTH=token (the student manually configured the undocumented token escape hatch — knows what they're doing), preserve it as-is. Do not change CANVAS_AUTH, do not touch CANVAS_TOKEN, do not ask the student about it, do not surface that token mode exists. Only update CANVAS_BASE / CANVAS_WEB_BASE if they're missing or empty. This is intentional: the escape hatch is for users who already configured it deliberately; canvas-setup's job is to configure cookie mode without disturbing existing manual config.