ADR-005: Learning Uses A Curated Project Catalog

Status

Accepted and implemented on 2026-08-20.

Context

The integrated Learning module previously implemented course generation, an account-partitioned local course library, OpenMAIC playback, and Agent/ASR/classroom runtime bridges. The product direction changed to a simpler operations-curated catalog where users inspect a project's README and save its ZIP to their computer. Keeping the old runtime hidden would preserve substantial packaging, security, and maintenance cost without serving the new workflow.

Decision

Keep the existing authenticated Learning entry and module_access.learning policy.
Replace the old course model completely with a server-driven project list and README detail page; do not retain a compatibility API or local-course read path.
Works Square operations owns project name, cover, summary, tags, version, ordering, publication state, Markdown, ZIP, recorded byte count, and SHA-256 metadata.
Publish-time processing removes raw Markdown HTML and validates image references as credential-free, default-port HTTPS URLs whose current DNS answers are public. It preserves those URLs instead of downloading, decoding, transcoding, or mirroring image bytes. The Learning detail Renderer opts only Markdown image nodes into the guarded direct-HTTPS image path; covers and historical release media keep their existing controlled-media handling.
Electron Main owns Works credentials, the native save dialog, archive request, redirect/origin policy, temporary file, SHA-256, ZIP signature, and atomic final rename. It does not reject a download because of Content-Length, recorded archiveBytes, actual streamed byte count, or a client archive-size ceiling. Renderer receives only bounded project DTOs, media data, and saved or cancelled.
Remove course generation, progress, local library, OpenMAIC player, Agent, ASR, classroom runtime, Learning IPC channels, player packaging resources, and their tests.
Do not automatically delete historical downloaded course data. The new client never reads or migrates it.

Consequences

The desktop client and package are substantially smaller and no longer depend on a production Stage player artifact.
The external Works Square operations/admin/API contract must be implemented and deployed before the new client can provide real catalog data.
Remote README images depend on the third-party origin and Electron's supported image formats. Each image failure remains local to that image, while availability and requester network information are visible to the image origin.
Removing client download-size checks avoids rejecting otherwise valid streams with missing or inaccurate size metadata, but also removes client-side protection against an archive consuming excessive disk space. Works Square may retain an independent operations upload/storage limit.
A future historical-data cleanup must be an explicit, user-controlled maintenance feature.

Supersedes

The Learning course-generation, local-course, OpenMAIC playback, and classroom-runtime behavior introduced by integrated source 01bee31.

Evidence

Product confirmation task: 20260819-ai-learning-project-catalog-8f3c2a91
Source task: 20260819-learning-project-catalog-impl-4e9c71a2
Source commit: 38db158
Integration merge: d967b0f
Direct-image server source: 65ea070
Direct-image client source: 9956739
No-size-validation client source: 8509084
No-size-validation integration merge: 0c1a360

docs/learning-project-catalog-server-contract.md
.project-docs/20-architecture/system-overview.md
.project-docs/20-architecture/data-flow.md
.project-docs/40-domain/business-rules.md

3.7 KiB Raw Blame History