Incognito-Wiki/docs/superpowers/specs/2026-08-03-internal-migration-comments-design.md

Internal Migration Comments Design

Goal

Remove editorial migration-state messages from the public Starlight site while preserving the information for repository maintainers as source comments.

Public notices that remain visible

• Historical-information cautions, including page-level outdated-content warnings and the 2022 study-abroad warning.
• Reader-actionable warnings, including the University network-use warnings.
• Historical course-list notes, because they explain the status and time context of content readers can see.

Notices moved into source comments

• Every Awaiting content callout on empty honours-programme pages and empty Handy Locations sections.
• Both Missing source asset callouts for the Year 1 and Year 2 schedule image.
• The statements on the Bachelor, Master AI, and Master DSDM overview pages that course summaries and old exams were absent from the export.

Use HTML comments in Markdown/MDX so maintainers retain the source-export context without rendering it in the generated site. Keep the affected pages, headings, and empty course/section structure intact.

Verification

Update the content tests before changing published content. The tests must verify that:

• all targeted information exists as HTML comments;
• none of the targeted text is present as visible Markdown or Starlight callouts;
• historical and reader-actionable notices remain present;
• empty pages and section headings remain in the content tree;
• the complete content audit, Astro build, rendered-output check, and internal-link check pass.

Finally, inspect representative affected pages in the running site to confirm the internal comments are absent from rendered output and the retained public warnings remain visible.