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, immutable size, and SHA-256 metadata.
Publish-time processing mirrors acceptable remote HTTPS raster images and rewrites README image references to fixed project-media paths. Renderer disables raw Markdown HTML; Main fetches controlled media with authentication, MIME validation, and a 10 MiB limit.
Electron Main owns Works credentials, the native save dialog, archive request, redirect/origin policy, temporary file, 512 MiB limit, declared size, SHA-256, ZIP signature, and atomic final rename. 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 successful publish-time mirroring; unsupported or failed images remain local display failures rather than arbitrary privileged network requests.
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

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

2.9 KiB Raw Blame History