@wilm-ai/wilma-cli 2.3.2 → 2.5.0

package/dist/agent-data.js

@@ -1,6 +1,6 @@
 import { NetworkError, WilmaClient, addExamTimes, } from "@wilm-ai/wilma-client";
-import { createHash } from "node:crypto";
 import { fileNameFromResponse, readResponseCapped } from "./downloads.js";
+import { fileLoginKeys } from "./session-keys.js";
 /**
  * An error with a stable code for agents and scripts (the CLI's JSON errors
  * and exit codes use it): e.g. "unknown_student", "invalid_argument".
@@ -104,13 +104,28 @@ function nextDateForWeekday(rawWeekday) {
     return addDays(today, (target - weekdayOf(today) + 7) % 7);
 }
 export const SCHEDULE_WHEN = ["today", "tomorrow", "week", "next-week"];
+/** The longest period one schedule request covers. */
+export const SCHEDULE_MAX_DAYS = 31;
 function resolveScheduleDateSelection(opts) {
     const when = opts.when || "week";
     if (!SCHEDULE_WHEN.includes(when)) {
         throw new WilmaAiError("invalid_argument", `Unknown period "${when}". Use ${SCHEDULE_WHEN.join(", ")}, a date or a weekday.`);
     }
-    if (opts.date && opts.weekday) {
-        throw new WilmaAiError("invalid_argument", "Use either a date or a weekday, not both.");
+    if ([opts.date, opts.weekday, opts.from].filter(Boolean).length > 1) {
+        throw new WilmaAiError("invalid_argument", "Use one of a date, a weekday, or from/to.");
+    }
+    if (opts.to && !opts.from)
+        throw new WilmaAiError("invalid_argument", "A period needs a start date (from) as well.");
+    if (opts.from) {
+        const from = parseIsoDate(opts.from);
+        // Without an end: to the Friday of that week (a school week from any day).
+        const to = opts.to ? parseIsoDate(opts.to) : addDays(from, Math.max(0, 5 - weekdayOf(from)));
+        if (to < from)
+            throw new WilmaAiError("invalid_argument", `The period ends (${to}) before it starts (${from}).`);
+        if (addDays(from, SCHEDULE_MAX_DAYS - 1) < to) {
+            throw new WilmaAiError("invalid_argument", `A period can be at most ${SCHEDULE_MAX_DAYS} days; ask for a longer one in parts.`);
+        }
+        return { when, startDate: from, endDate: to, outputWhen: "period" };
     }
     if (opts.date) {
         const parsed = parseIsoDate(opts.date);
@@ -131,6 +146,9 @@ function resolveScheduleDateSelection(opts) {
     const [startDate, endDate] = currentWeekBounds(when === "next-week" ? 1 : 0);
     return { when, startDate, endDate, outputWhen: when };
 }
+function listedInvitation(listing) {
+    return { ...listing.message, invitationStatus: listing.status, invitationInfo: listing.extra };
+}
 /**
  * One child's daily briefing: today's and the next school day's lessons,
  * upcoming exams (with start times), recent homework, lesson notes (teachers'
@@ -161,6 +179,7 @@ function buildSummaryData(input, opts = {}) {
         folder: m.folder,
         unread: Boolean(m.unread),
         replyCount: m.replyCount ?? 0,
+        ...(m.invitationStatus !== undefined ? { invitationStatus: m.invitationStatus, invitationInfo: m.invitationInfo ?? null } : {}),
     }));
     return {
         today,
@@ -205,7 +224,8 @@ async function fetchSummaryInputs(client, opts) {
         client.exams.calendarOrEmpty(),
         client.news.listIfShown(),
         client.messages.list("inbox"),
-        optional("appointments", client.messages.list("appointments"), []),
+        // The invitations folder, with whether the family has answered (one request, as for the folder itself).
+        optional("appointments", client.invitations.list(), []),
         optional("lessonNotes", client.attendance.list({ from: opts.notesFrom, to: todayString() }), []),
     ]);
     if (news === null)
@@ -213,7 +233,7 @@ async function fetchSummaryInputs(client, opts) {
     return {
         overview: { ...overview, upcomingExams: addExamTimes(overview.upcomingExams, calendar) },
         news: news ?? [],
-        messages: [...inbox, ...appointments],
+        messages: [...inbox, ...appointments.map(listedInvitation)],
         lessonNotes,
         unavailable,
     };
@@ -223,6 +243,43 @@ function daysBack(days) {
     const today = todayString();
     return addDays(today, -(days - 1));
 }
+/** What each teacher teaches, by teacher code as the timetable writes it ("KOJ" → ["Matematiikka"]). */
+function subjectsByTeacher(lessons) {
+    const map = new Map();
+    for (const lesson of lessons) {
+        // A lesson can have several teachers ("KOJ, MÄL"): each teaches it.
+        for (const code of (lesson.teacherCode ?? "").split(",")) {
+            const key = code.trim().toUpperCase();
+            if (!key || !lesson.subject)
+                continue;
+            const list = map.get(key) ?? [];
+            if (!list.includes(lesson.subject))
+                map.set(key, [...list, lesson.subject]);
+        }
+    }
+    return map;
+}
+/** The teacher's code at the end of a name as Wilma's recipient lists write it: "Korhonen Jussi (KOJ)" → "KOJ". */
+function codeInName(name) {
+    return /\(([^()\s]{1,12})\)\s*$/.exec(name)?.[1] ?? null;
+}
+/**
+ * The child's own teachers in Wilma's recipient list: the list behind its
+ * "all own teachers" group (whatever the Wilma's language calls it), once
+ * each. Without that group, none.
+ */
+function ownTeachers(recipients) {
+    const group = recipients.find((r) => r.kind === "group" && /[?&]r_ownteachers=/.test(r.composePath))?.group;
+    if (!group)
+        return [];
+    const seen = new Set();
+    return recipients.filter((r) => {
+        if (r.kind !== "teacher" || r.group !== group || seen.has(r.name))
+            return false;
+        seen.add(r.name);
+        return true;
+    });
+}
 /* ------------------------------------------------------------------ */
 /*  Session pool                                                       */
 /* ------------------------------------------------------------------ */
@@ -247,39 +304,59 @@ export function useSessionStore(store) {
  * in only when that one has ended too. Each login ends the others, so this
  * keeps WilmAI's programs from logging each other out.
  */
-function rememberSession(key, client, opts) {
+function rememberSession(keys, client, opts) {
     const store = sessionStore;
     if (!store)
         return;
     const save = (state) => {
-        const saving = store.save(key, state).catch(() => { });
+        const saving = saveUnder(store, keys, state).catch(() => { });
         pendingSaves.add(saving);
         void saving.finally(() => pendingSaves.delete(saving));
         return saving;
     };
-    client.useSharedSession({ load: () => store.load(key), save });
+    client.useSharedSession({ load: () => loadNewest(store, keys), save });
     // A resumed session is already saved (and another process may have saved a newer one since).
     if (opts.fresh)
         void save(client.exportSession());
 }
+/** A login's session under any of its labels, the newest (a store without that falls back to the first found). */
+async function loadNewest(store, keys) {
+    if (store.loadNewest)
+        return store.loadNewest(keys);
+    for (const key of keys) {
+        const state = await store.load(key);
+        if (state)
+            return state;
+    }
+    return null;
+}
+async function saveUnder(store, keys, state) {
+    if (store.saveAll)
+        return store.saveAll(keys, state);
+    for (const key of keys)
+        await store.save(key, state);
+}
+async function removeUnder(store, keys) {
+    if (store.removeAll)
+        return store.removeAll(keys);
+    for (const key of keys)
+        await store.remove(key);
+}
 const pendingSaves = new Set();
-/** Identifies one Wilma account and password (a changed password starts fresh). */
-function poolKey(profile) {
-    const { baseUrl, username, password } = profile;
-    // The password is part of the key, so a changed password starts a fresh session.
-    return createHash("sha256")
-        .update(`${baseUrl.replace(/\/$/, "")}\n${username.toLowerCase()}\n${password}`)
-        .digest("hex");
+/** The keys of a login known by its password (file and environment logins): both labels, v1 in the pool. */
+function defaultKeys(profile) {
+    return fileLoginKeys(profile.baseUrl, profile.username, profile.password);
 }
 /**
  * Keep a session that is already logged in — e.g. the one the login page just
  * verified — so the first tool call needs no second login (and, with two-step
- * verification, no second code).
+ * verification, no second code). `keys` are the saved login's (v2 for a
+ * keychain login); without them, today's keys from the profile.
  */
-export function adoptSession(profile, client) {
-    const key = poolKey(profile);
-    pool.set(key, { client: Promise.resolve(client), lastUsed: Date.now() });
-    rememberSession(key, client, { fresh: true });
+export function adoptSession(profileOrKeys, client) {
+    const keys = "sessionKeys" in profileOrKeys ? profileOrKeys : defaultKeys(profileOrKeys);
+    pool.set(keys.poolKey, { client: Promise.resolve(client), lastUsed: Date.now() });
+    rememberSession(keys.sessionKeys, client, { fresh: true });
 }
 /**
  * Finish saving sessions (call before a short-lived process exits). Only
@@ -291,38 +368,42 @@ export async function flushSessions() {
         await entry.client.catch(() => null);
     await Promise.all([...pendingSaves]);
 }
+/** Drop this process's client for a login (after its secrets moved, so the next use starts from its new keys). */
+export function dropPooledSession(keys) {
+    pool.delete(keys.poolKey);
+}
 /**
  * End WilmAI's Wilma session for one login (Wilma's own "Log out") and forget
  * it, in this process and in the session store, so nothing continues it. The
  * login itself stays saved; the next command or tool call logs in again.
- * Never logs in. Returns true when a live session was ended, false when there
- * was none. If Wilma can't be reached, throws and keeps the saved session, so
- * logging out can be tried again.
+ * Never logs in (so it needs no password). Returns true when a live session
+ * was ended, false when there was none. If Wilma can't be reached, throws and
+ * keeps the saved session, so logging out can be tried again.
  */
-export async function logoutSession(profile) {
-    const key = poolKey(profile);
-    const entry = pool.get(key);
+export async function logoutSession(profile, keys = defaultKeys(profile)) {
+    const entry = pool.get(keys.poolKey);
     // The session in use here (a login in progress finishes first) and the saved
     // one, which another process may have replaced since. At most one is live.
     const pooled = entry ? await entry.client.catch(() => null) : null;
     const pooledState = pooled?.exportSession();
-    const saved = sessionStore ? await sessionStore.load(key).catch(() => null) : null;
+    const saved = sessionStore ? await loadNewest(sessionStore, keys.sessionKeys).catch(() => null) : null;
     let ended = pooled ? await pooled.logout() : false;
-    if (pool.get(key) === entry)
-        pool.delete(key);
+    if (pool.get(keys.poolKey) === entry)
+        pool.delete(keys.poolKey);
     if (saved && saved !== pooledState) {
         const resumed = WilmaClient.resume({ ...profile, studentNumber: null }, saved);
         if (resumed && (await resumed.logout()))
             ended = true;
     }
-    await sessionStore?.remove(key);
+    if (sessionStore)
+        await removeUnder(sessionStore, keys.sessionKeys);
     return ended;
 }
 /** Forget one login's session without ending it in Wilma (when the login itself is removed). */
-export async function forgetSession(profile) {
-    const key = poolKey(profile);
-    pool.delete(key);
-    await sessionStore?.remove(key);
+export async function forgetSession(profile, keys = defaultKeys(profile)) {
+    pool.delete(keys.poolKey);
+    if (sessionStore)
+        await removeUnder(sessionStore, keys.sessionKeys);
 }
 function pooledSession(account) {
     const now = Date.now();
@@ -330,24 +411,26 @@ function pooledSession(account) {
         if (now - entry.lastUsed > POOL_IDLE_MS)
             pool.delete(key);
     }
-    const key = poolKey(account.profile);
-    let entry = pool.get(key);
+    const keys = account.keys ?? defaultKeys(account.profile);
+    let entry = pool.get(keys.poolKey);
     if (!entry) {
         const profile = { ...account.profile, studentNumber: null };
+        const lazy = account.password;
         const client = (async () => {
-            // A saved session first; it logs in again by itself if Wilma has ended it.
-            const saved = sessionStore ? await sessionStore.load(key).catch(() => null) : null;
-            const resumed = saved ? WilmaClient.resume(profile, saved, account.mfa) : null;
-            const client = resumed ?? (await WilmaClient.login(profile, account.mfa));
-            rememberSession(key, client, { fresh: !resumed });
+            // A saved session first; it logs in again by itself if Wilma has ended it
+            // (reading a keychain login's password only then).
+            const saved = sessionStore ? await loadNewest(sessionStore, keys.sessionKeys).catch(() => null) : null;
+            const resumed = saved ? WilmaClient.resume({ ...profile, password: lazy ?? profile.password }, saved, account.mfa) : null;
+            const client = resumed ?? (await WilmaClient.login({ ...profile, password: lazy ? await lazy() : profile.password }, account.mfa));
+            rememberSession(keys.sessionKeys, client, { fresh: !resumed });
             return client;
         })();
         const created = { client, lastUsed: now };
         entry = created;
-        pool.set(key, created);
+        pool.set(keys.poolKey, created);
         client.catch(() => {
-            if (pool.get(key) === created)
-                pool.delete(key);
+            if (pool.get(keys.poolKey) === created)
+                pool.delete(keys.poolKey);
         });
     }
     entry.lastUsed = now;
@@ -386,9 +469,19 @@ export function matchStudents(students, student) {
     }
     throw new WilmaAiError("ambiguous_student", `"${student}" matches several students (${matches.map((s) => s.name).join(", ")}). Use the full name or student number.`, { students: list });
 }
+/** Whose login it is: a student's own when Wilma lists only the student themself, a guardian's when it says so. */
+export function roleOf(students) {
+    if (students.length && students.every((s) => s.role === "student"))
+        return "student";
+    return students.some((s) => s.role === "guardian") ? "guardian" : undefined;
+}
 export class WilmaAccess {
     accounts;
     studentsCache = null;
+    /** The children each login lists (by login index), including those read through another login. */
+    listed = new Map();
+    /** Why a login failed (by login index), while others worked. */
+    failures = new Map();
     /** One logged-in session per Wilma login, shared by every child on it. */
     sessions = new Map();
     /** Logins that failed while other logins worked. */
@@ -431,7 +524,7 @@ export class WilmaAccess {
             }
         }));
         const all = [];
-        const seen = new Set();
+        const seen = new Map();
         let firstError = null;
         let worked = 0;
         for (const result of fetched) {
@@ -440,6 +533,7 @@ export class WilmaAccess {
                 firstError ??= result.error;
                 const message = result.error instanceof Error ? result.error.message : String(result.error);
                 this.problems.push({ wilma: this.labelOf(result.index), message });
+                this.failures.set(result.index, message);
                 continue;
             }
             worked += 1;
@@ -452,13 +546,21 @@ export class WilmaAccess {
                         account.knownStudents.map((s) => ({ ...s, href: `/!${s.studentNumber}/` }))
                     : // Accounts that list no students still work against the default page.
                         [{ studentNumber: account.profile.studentNumber ?? "", name: "", href: "/" }];
+            this.listed.set(result.index, list);
             for (const student of list) {
-                // Two guardians' logins on the same Wilma list the same children once.
-                const key = `${account.profile.baseUrl}|${student.studentNumber}`;
-                if (seen.has(key))
+                if (account.hidden?.includes(student.studentNumber))
                     continue;
-                seen.add(key);
-                all.push({ ...student, account: result.index });
+                // Two logins on the same Wilma (two guardians, or a guardian and the child) list the same child once.
+                const key = `${account.profile.baseUrl.replace(/\/$/, "").toLowerCase()}|${student.studentNumber}`;
+                const at = seen.get(key);
+                if (at === undefined) {
+                    seen.set(key, all.length);
+                    all.push({ ...student, account: result.index });
+                }
+                else if (all[at].role === "student" && student.role === "guardian") {
+                    // A guardian's login over the child's own, whichever logged in last: the parent's view (messages to guardians, invitations).
+                    all[at] = { ...student, account: result.index };
+                }
             }
         }
         if (!worked)
@@ -466,9 +568,46 @@ export class WilmaAccess {
         this.studentsCache = all;
         return all;
     }
-    /** The children as tools and commands show them (with their Wilma when there are several). */
+    /**
+     * The children as tools and commands show them (with their Wilma when there
+     * are several), and whose login reads each: a guardian's, or the student's own.
+     */
     async studentList() {
-        return (await this.students()).map((s) => this.ref(s));
+        return (await this.students()).map((s) => ({ ...this.ref(s), ...(s.role ? { role: s.role } : {}) }));
+    }
+    /**
+     * Each login: its Wilma, username, whose it is (a guardian's, or a
+     * student's own; missing when Wilma doesn't say) and the children it lists.
+     * A child another login on the same Wilma also lists is read through one of
+     * them only; `readVia` names the other login's username. A child unticked
+     * on the login page has `hidden: true` and isn't read.
+     */
+    async logins() {
+        const students = await this.students();
+        return this.accounts.map((account, index) => {
+            const listed = (this.listed.get(index) ?? []).filter((s) => s.name);
+            const role = roleOf(listed);
+            return {
+                wilma: this.labelOf(index),
+                username: account.profile.username,
+                ...(role ? { role } : {}),
+                children: listed.map((s) => {
+                    if (account.hidden?.includes(s.studentNumber))
+                        return { name: s.name, studentNumber: s.studentNumber, hidden: true };
+                    const read = students.find((x) => x.studentNumber === s.studentNumber && this.sameWilma(x.account, index));
+                    return {
+                        name: s.name,
+                        studentNumber: s.studentNumber,
+                        ...(read && read.account !== index ? { readVia: this.accounts[read.account].profile.username } : {}),
+                    };
+                }),
+                ...(this.failures.has(index) ? { problem: this.failures.get(index) } : {}),
+            };
+        });
+    }
+    sameWilma(a, b) {
+        const url = (i) => this.accounts[i].profile.baseUrl.replace(/\/$/, "").toLowerCase();
+        return url(a) === url(b);
     }
     async selectStudents(student) {
         const students = await this.students();
@@ -514,9 +653,11 @@ export class WilmaAccess {
     }
     async schedule(opts = {}) {
         const selection = resolveScheduleDateSelection(opts);
-        const range = selection.startDate === selection.endDate
-            ? { date: selection.startDate }
-            : { weekStart: selection.startDate, weekEnd: selection.endDate };
+        const range = selection.outputWhen === "period"
+            ? { from: selection.startDate, to: selection.endDate }
+            : selection.startDate === selection.endDate
+                ? { date: selection.startDate }
+                : { weekStart: selection.startDate, weekEnd: selection.endDate };
         const result = await this.perStudent(opts.student, async (client) => ({
             lessons: await client.schedule.list({ from: selection.startDate, to: selection.endDate }),
         }));
@@ -533,7 +674,29 @@ export class WilmaAccess {
             return { exams: (await client.exams.upcoming()).slice(0, opts.limit ?? 20) };
         });
     }
+    /**
+     * Exam grades: the newest the front page lists, or with `from` (to `to`,
+     * default today) Wilma's list of past exams for that period (Kokeet >
+     * Menneet), including exams still waiting for a grade (grade: null).
+     */
     async grades(opts = {}) {
+        if (opts.to && !opts.from)
+            throw new WilmaAiError("invalid_argument", "A period needs a start date (from) as well.");
+        if (opts.from) {
+            const from = parseIsoDate(opts.from);
+            const to = opts.to ? parseIsoDate(opts.to) : todayString();
+            if (to < from)
+                throw new WilmaAiError("invalid_argument", `The period ends (${to}) before it starts (${from}).`);
+            return {
+                from,
+                to,
+                ...(await this.perStudent(opts.student, async (client) => {
+                    const exams = await client.exams.past({ from, to });
+                    // Every exam of the period unless a limit is given.
+                    return { grades: opts.limit ? exams.slice(0, opts.limit) : exams };
+                })),
+            };
+        }
         return this.perStudent(opts.student, async (client) => {
             const overview = await client.overview.get();
             return { grades: overview.grades.slice(0, opts.limit ?? 20) };
@@ -567,6 +730,47 @@ export class WilmaAccess {
     async gradebook(opts = {}) {
         return this.perStudent(opts.student, async (client) => ({ gradebook: await client.gradebook.get() }));
     }
+    /**
+     * The child's class, class teacher and other supervisors (front page), and
+     * their own teachers (Wilma's recipient list) with what each teaches them,
+     * from this and next week's timetable. Parts Wilma can't give are listed in
+     * `unavailable`.
+     */
+    async contacts(opts = {}) {
+        const [from] = currentWeekBounds(0);
+        const [, to] = currentWeekBounds(1);
+        return this.perStudent(opts.student, async (client) => {
+            const unavailable = [];
+            const optional = (name, promise, fallback) => promise.catch((err) => {
+                if (err instanceof NetworkError)
+                    throw err;
+                unavailable.push(name);
+                return fallback;
+            });
+            const [details, recipients, lessons] = await Promise.all([
+                client.student.get(),
+                optional("teachers", client.messages.recipients(), []),
+                // Only for what each teacher teaches.
+                client.schedule.list({ from, to }).catch((err) => {
+                    if (err instanceof NetworkError)
+                        throw err;
+                    return [];
+                }),
+            ]);
+            const subjects = subjectsByTeacher(lessons);
+            return {
+                contacts: {
+                    className: details.className,
+                    supervisors: details.supervisors.map((s) => ({ name: s.name, role: s.role })),
+                    teachers: ownTeachers(recipients).map((r) => {
+                        const code = codeInName(r.name);
+                        return { name: r.name, subjects: (code && subjects.get(code.toUpperCase())) || [] };
+                    }),
+                    ...(unavailable.length ? { unavailable } : {}),
+                },
+            };
+        });
+    }
     async printouts(opts = {}) {
         return this.perStudent(opts.student, async (client) => ({ printouts: await client.printouts.list() }));
     }
@@ -585,7 +789,8 @@ export class WilmaAccess {
     }
     async messages(opts = {}) {
         return this.perStudent(opts.student, async (client) => {
-            const messages = await client.messages.list(opts.folder ?? "inbox");
+            // Invitations come with the family's answer as Wilma lists it (the same request).
+            const messages = opts.folder === "appointments" ? (await client.invitations.list()).map(listedInvitation) : await client.messages.list(opts.folder ?? "inbox");
             return { messages: messages.slice(0, opts.limit ?? 20) };
         });
     }

package/dist/cli-args.js

@@ -7,6 +7,7 @@ const DATA_COMMANDS = [
     "exams",
     "grades",
     "gradebook",
+    "contacts",
     "notes",
     "messages",
     "news",
@@ -229,9 +230,17 @@ export function parseCliArgs(argv) {
         case "logout":
             return parsed(null, args);
         case "config":
-            if (args[0] !== "clear" || args.length > 1)
-                throw usage('Expected "wilma config clear".');
-            return parsed("clear");
+            if (args[0] === "clear" && args.length === 1)
+                return parsed("clear");
+            if (args[0] === "secrets") {
+                const [, setting, ...extra] = args;
+                noMore(extra);
+                if (setting !== undefined && !["file", "auto", "keychain"].includes(setting)) {
+                    throw usage('Expected "wilma config secrets [file|auto|keychain]".');
+                }
+                return parsed("secrets", setting === undefined ? [] : [setting]);
+            }
+            throw usage('Expected "wilma config clear" or "wilma config secrets [file|auto|keychain]".');
         case "find-school":
             if (!args.length)
                 throw usage('Expected "wilma find-school <city or school>".');

package/dist/cli-help.js

@@ -8,10 +8,13 @@ const COMMAND_HELP = {
         output: "{ generatedAt, students: [{ student, summary: { today, tomorrow, todaySchedule, tomorrowSchedule, upcomingExams, homework, lessonNotes, news, messages, unreadMessages } }] }. --since <date> keeps only what is from that day on (for daily runs); messages carry unread and replyCount.",
     },
     schedule: {
-        usage: [`wilma schedule [today|tomorrow|week|next-week|<YYYY-MM-DD>|<weekday>] [${STUDENT}]`],
-        about: "Lessons with times, teachers and rooms. Default: this week. 'tomorrow' is the next school day; a weekday (mon…sun, or ma…su) is its next occurrence.",
-        examples: ["wilma schedule tomorrow", "wilma schedule next-week", "wilma schedule 2026-10-07", "wilma schedule thu --student Kiia"],
-        output: "{ when, date | weekStart+weekEnd, students: [{ student, lessons: [{ date, start, end, subject, teacher, room }] }] }",
+        usage: [
+            `wilma schedule [today|tomorrow|week|next-week|<YYYY-MM-DD>|<weekday>] [${STUDENT}]`,
+            `wilma schedule --from <date> [--to <date>] [${STUDENT}]`,
+        ],
+        about: "Lessons with times, teachers and rooms. Default: this week. 'tomorrow' is the next school day; a weekday (mon…sun, or ma…su) is its next occurrence. --from reads any other week or period (to the Friday of that week unless --to is given; at most 31 days).",
+        examples: ["wilma schedule tomorrow", "wilma schedule next-week", "wilma schedule 2026-10-07", "wilma schedule thu --student Kiia", "wilma schedule --from 2026-11-16"],
+        output: "{ when, date | weekStart+weekEnd | from+to, students: [{ student, lessons: [{ date, start, end, subject, teacher, room }] }] }",
     },
     homework: {
         usage: [`wilma homework [--limit 10] [${STUDENT}]`],
@@ -25,9 +28,16 @@ const COMMAND_HELP = {
         output: "{ students: [{ student, exams: [{ date, time, subject, name, topic, teacher }] }] }",
     },
     grades: {
-        usage: [`wilma grades [--limit 20] [${STUDENT}]`],
-        about: "Recent exam grades. For course and report-card grades, see `wilma gradebook`.",
-        examples: ["wilma grades"],
+        usage: [`wilma grades [--limit 20] [${STUDENT}]`, `wilma grades --from <date> [--to <date>] [--limit N] [${STUDENT}]`],
+        about: "Recent exam grades from Wilma's front page. --from reads Wilma's list of past exams for a period instead (as far back as the school keeps them), including exams still waiting for a grade (grade: null). For course and report-card grades, see `wilma gradebook`.",
+        examples: ["wilma grades", "wilma grades --from 2026-08-01 --student Kiia"],
+        output: "{ [from, to,] students: [{ student, grades: [{ date, subject, name, grade, verbalGrade, info, teacher, seen }] }] }",
+    },
+    contacts: {
+        usage: [`wilma contacts [${STUDENT}]`],
+        about: "The child's class, class teacher and other supervisors (with their role as Wilma names it), and their own teachers with the subjects each teaches them in this and next week's timetable.",
+        examples: ["wilma contacts", "wilma contacts --student Kiia"],
+        output: "{ students: [{ student, contacts: { className, supervisors: [{ name, role }], teachers: [{ name, subjects }], unavailable? } }] }",
     },
     gradebook: {
         usage: [`wilma gradebook [${STUDENT}]`],
@@ -58,17 +68,17 @@ const COMMAND_HELP = {
     },
     students: {
         usage: ["wilma students"],
-        about: "The children on the saved logins (number, name, and their Wilma when there are several).",
+        about: "The children on the saved logins (number, name, their Wilma when there are several, and role: whether a guardian's login or the student's own reads them).",
         examples: ["wilma students"],
     },
     login: {
         usage: ["wilma login [--no-browser]", "wilma login --tenant <url|city> --username <name> [--password-stdin] [--totp-secret <key>]"],
-        about: "Log in to Wilma, with a parent's account or a student's own. Opens a one-time login page in the browser where the user picks their school's Wilma; logins are saved on this computer. Families with children on different Wilmas add each one there. Without a browser, pass --tenant and --username with the password on stdin or in WILMA_PASSWORD.",
+        about: "Log in to Wilma, with a parent's account or a student's own. Opens a one-time login page in the browser where the user picks their school's Wilma; logins are saved on this computer. The page shows every saved Wilma with its children: families with children on different Wilmas add each one there, untick a child Wilma lists twice, log in again or remove a Wilma. Without a browser, pass --tenant and --username with the password on stdin or in WILMA_PASSWORD.",
         examples: ["wilma login"],
     },
     accounts: {
         usage: ["wilma accounts", "wilma accounts remove <number|Wilma name|username>"],
-        about: "Saved Wilma logins, numbered (one per Wilma the children use). `remove` deletes one and ends its Wilma session; the other logins keep theirs.",
+        about: "Saved Wilma logins, numbered (one per Wilma the children use), with role \"student\" for a student's own login, and under hidden the children unticked on the login page (not read). `remove` deletes one and ends its Wilma session; the other logins keep theirs. When a parent's and a child's own login on the same Wilma are both saved, commands read that child through the parent's.",
         examples: ["wilma accounts", "wilma accounts remove 2"],
     },
     logout: {
@@ -94,18 +104,24 @@ const COMMAND_HELP = {
         examples: ["npx -y @wilm-ai/wilma-cli@2 mcp"],
     },
     update: { usage: ["wilma update"], about: "Update the CLI with npm.", examples: ["wilma update"] },
-    config: { usage: ["wilma config clear"], about: "Delete every saved login and session on this computer.", examples: ["wilma config clear"] },
+    config: {
+        usage: ["wilma config clear", "wilma config secrets [file|auto|keychain]"],
+        about: "`clear` deletes every saved login and session on this computer (and their keychain entries). `secrets` shows where saved passwords are kept, or changes it: `file` (the default, WilmAI's own file readable only by you), `keychain` (the macOS Keychain, Windows Credential Manager or a Linux desktop's Secret Service; refuses to save anywhere else) or `auto` (the keychain where there is one, the file where there isn't). Changing it moves the saved logins without logging in again. WILMAI_SECRET_STORE sets where new logins go for one process.",
+        examples: ["wilma config secrets", "wilma config secrets auto", "wilma config secrets file", "wilma config clear"],
+        output: "secrets: { setting, envOverride, keychain: { kind, usable, problem }, logins: [{ wilma, username, store: \"file\" | \"keychain\", hasTotp }], moved? }",
+    },
 };
 const OVERVIEW = [
     ["summary", "daily briefing for every child (start here)"],
-    ["schedule [when]", "lessons: today, tomorrow, week, next-week, a date or a weekday"],
+    ["schedule [when]", "lessons: today, tomorrow, week, next-week, a date, a weekday, or --from <date>"],
     ["exams", "upcoming exams with topics and start times"],
     ["homework", "recent homework"],
     ["notes [summary]", "lesson notes: absences and teachers' feedback; summary counts them"],
     ["messages [id]", "messages, or one with its replies"],
     ["news [id [download r]]", "bulletins, one bulletin, or a linked file"],
-    ["grades", "recent exam grades"],
+    ["grades", "exam grades: recent, or --from <date> for a period"],
     ["gradebook", "course and report-card grades"],
+    ["contacts", "class, class teacher and teachers"],
     ["printouts [id]", "PDFs such as report cards"],
     ["students", "the children"],
     ["login", "log in (opens a page in the browser)"],

package/dist/cli-output.d.ts

@@ -1,6 +1,9 @@
 import type { Message, NewsItem } from "@wilm-ai/wilma-client";
 export declare function compactText(value: string | null | undefined): string;
 export declare function newsLine(item: Pick<NewsItem, "wilmaId" | "title" | "published" | "pinned" | "archived">): string;
-export declare function messageLine(msg: Pick<Message, "wilmaId" | "subject" | "sentAt" | "senderName" | "unread" | "replyCount">): string;
+export declare function messageLine(msg: Pick<Message, "wilmaId" | "subject" | "sentAt" | "senderName" | "unread" | "replyCount"> & {
+    invitationStatus?: string | null;
+    invitationInfo?: string | null;
+}): string;
 /** Text for a command's result. */
 export declare function formatText(command: string, action: string | null, result: any): string;