Add the schulcloud CLI, and document the split

The CLI talks only to the Pi's /api surface and holds no Schulcloud
credential — only the same bearer token the Claude connector uses. That
is not layering for its own sake: a Schulcloud session dies after two
hours idle and a CLI process lives for seconds, so a CLI with its own
token would be dead most times you reached for it. Routing through the
Pi means one session, one keepalive, one monthly cookie paste.

sync is a one-way mirror, which follows from the data rather than from
scope-cutting: file records are immutable upstream, so there is no
versioning, no conflict resolution and no merge. State is keyed by file
record id with the path as derived output, so an upstream rename moves
the local file instead of duplicating it — verified against the live
server. Verification is size-only because the download endpoint exposes
no ETag and Schulcloud publishes no hash; size still catches the failure
that happens, a truncated download. Downloads land on a .part neighbour
and are renamed, so an interrupted run leaves no half-file that a later
run mistakes for complete. Deletions are reported but not propagated —
a teacher removing a worksheet is no reason to destroy the student's
copy — with --prune to opt in.

what_changed now clamps to the oldest stored generation instead of
refusing, and says it did: "what's new this week" is a reasonable
question to ask a two-day-old index.

Two build bugs caught by the checks rather than by luck: the smoke
harness constructed the app without services, so the index-backed tools
were never exercised; and the Docker build could not see
scripts/copy-assets.mjs, so the image would have shipped without
migrations and silently degraded to live-only.

67 unit tests (9 needing Postgres), smoke green both ways — 34 checks
with an index, 32 without, because graceful degradation is a supported
mode and not a fallback nobody runs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

scripts/smoke.mjs

@@ -10,13 +10,17 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { loadConfig } from '../dist/config.js';
 import { createHttpApp } from '../dist/http/server.js';
+import { closeServices, createServices } from '../dist/services.js';
 
 const TOKEN = 'smoke-test-token-' + Math.random().toString(36).slice(2);
 process.env.MCP_AUTH_TOKEN = TOKEN;
 // The app is bound by this script on an ephemeral port, so config.port is unused.
 
 const config = loadConfig();
-const app = createHttpApp(config);
+// Wire the real services so the index-backed tools are exercised when
+// DATABASE_URL is set, exactly as the deployed server does.
+const services = await createServices(config);
+const app = createHttpApp(config, services);
 const httpServer = await new Promise((resolve) => {
 	const s = app.listen(0, '127.0.0.1', () => resolve(s));
 });
@@ -150,9 +154,28 @@ if (fileId) {
 
 console.log('\n== search ==');
 const searchTerm = process.env.SMOKE_SEARCH ?? 'Datenschutz';
-const search = await call('search', { query: searchTerm });
-check(`search "${searchTerm}"`, !search.isError, search.text.split('\n')[0]);
-check('search scoped to one course', !(await call('search', { query: 'a b', courseId: courseIds[0] })).isError);
+const search = await call('search', { query: searchTerm, fresh: true });
+check(`search "${searchTerm}" (fresh, bypassing any index)`, !search.isError, search.text.split('\n')[0]);
+check('search scoped to one course', !(await call('search', { query: 'a b', courseId: courseIds[0], fresh: true })).isError);
+
+console.log('\n== index tools ==');
+// These degrade gracefully without DATABASE_URL, so assert on either outcome
+// rather than requiring a database for the smoke run to be meaningful.
+const hasIndex = Boolean(process.env.DATABASE_URL);
+const status = await call('index_status');
+check(
+	`index_status responds (${hasIndex ? 'with index' : 'no index configured'})`,
+	hasIndex ? !status.isError : status.isError && /not configured/.test(status.text),
+	status.text.split('\n')[0],
+);
+const changed = await call('what_changed', { since: '2026-01-01' });
+check('what_changed responds', hasIndex ? !changed.isError : changed.isError);
+if (hasIndex) {
+	const refreshed = await call('refresh_index', { courseId: courseIds[0], force: true });
+	check('refresh_index re-crawls one course', !refreshed.isError, refreshed.text.split('\n')[0]);
+	const indexed = await call('search', { query: searchTerm });
+	check('search uses the index and states freshness', !indexed.isError && /Index /.test(indexed.text));
+}
 
 console.log('\n== api_get guard rails ==');
 check('api_get allows /api/ paths', !(await call('api_get', { path: '/api/v3/me' })).isError);
@@ -165,6 +188,7 @@ check('unknown id returns a tool error, not a crash', bogus.isError, bogus.text.
 
 await client.close();
 httpServer.close();
+await closeServices(services);
 
 console.log(`\n${results.length - failures}/${results.length} checks passed`);
 process.exit(failures === 0 ? 0 : 1);