STCourses/docs/contract-requests/import.md

Contract requests from WP-B (Importer)

1. loadConfig should add <dataDir>/courses to courseDirs. The importer writes courses there. Worked around in apps/server/src/main.ts (the main guard pushes it) and in packages/feature-import/dev/serve.ts. /api/import/info reports coursesDirServed and the UI warns when it is false.
2. startServer accepts feature factories (Feature | ((ctx) => Feature)). A Feature needs ServerContext, but ServerContext.jobs is built from the features' job handlers. importFeature(ctx) only reads ctx while a job or request runs, so main.ts now builds ctx first, resolves the factories, then assigns ctx.jobs. The edit is about ten lines in apps/server/src/main.ts; Phase 2 should keep or replace it.
3. Web entry for features. apps/web must not pull a package's server code into the browser bundle. @stc/feature-import exposes a browser-safe entry as ./web (package.json exports), but the root tsconfig paths (@stc/* to packages/*/src) cannot resolve @stc/feature-import/web, so apps/web/src/features.ts imports it by relative path. Suggest a tsconfig paths entry per feature, or a src/web.ts convention.
4. Derived cache layout (no contract defines one). Written by the importer, to be read by the learner and AI packages:
   • <dataDir>/cache/decks/<courseId>/<deckId>/p-001.jpg ... (1280px wide JPEGs) and text.json ([{ page, text }]);
   • <dataDir>/cache/covers/<courseId>/frame-N.jpg and deck-<deckId>.jpg (cover candidates);
   • <dataDir>/cache/transcripts/<courseId>/<lessonId>.json ({ lessonId, text, segments: [{ start, end, text }] }). Suggest a cacheDir/deckPageUrl helper in core, and a media route for cache/decks so the deck viewer can load pages.
5. Video lessons have no description field. Packt clips come with a one-line description. It is dropped, because transcript is the only Markdown a video lesson can carry and the transcription job writes it.
6. STC_IMPORT_ROOTS (":"-separated, default <dataDir>/import-inbox, created when importFeature is built) is read inside the import package. Core config could own it later.