makelore/.project-docs/10-decisions/adr-005-learning-project-catalog.md

ADR-005: Learning Uses A Curated Project Catalog

Status

Superseded on 2026-09-04 by the explicit product decision to remove Learning from Makelore. Source 5a7cb9b was integrated as bd0873f by task 20260904-integrate-remove-learning-6e4a9c21.

This ADR remains only as historical context. Its catalog, route, API, download, packaging, and release obligations are no longer active.

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.

Superseded Consequences

• Makelore now exposes only Code, Canvas, and Robot as top-level modules.
• Learning Renderer, Main, shared DTO, asset, test, and server-contract sources are removed.
• Old Learning routes fall through to the module chooser and old Learning Host API paths return the normal not-found response; no compatibility implementation is retained.
• Historical downloaded course data remains untouched and is not read or migrated.
• The literal makelore-learning:v1 remains frozen only as a cross-module persisted account-partition compatibility salt; its name does not represent an active module.

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

Related

• .project-docs/20-architecture/system-overview.md
• .project-docs/20-architecture/data-flow.md
• .project-docs/40-domain/business-rules.md