feat(standalone): wire up the dev environment setup module

[miaulalala]

Why

content/php/beginner/1.md defers to a standalone "Setting Up Your Development Environment" module twice — once in the Docker path (line 36) and once in the Codespaces path (line 74) — telling readers to "find it in the Standalone section on the course home screen, or in the 'Before you start' section".

Neither existed in course-v2. So a beginner who had not set up Docker was sent to a module that rendered nowhere. This fixes a live broken instruction, not a missing extra.

The content was already written, at content/shared/setup.md. Only the wiring was missing.

What

• Manifest: standalone-env-setup gains a file field. Track modules resolve markdown by convention (content/<track>/<level>/<index>.md); standalone modules have no index to derive a path from, so it has to be declared.
• Types: CourseManifest now models standalone, which was already in the JSON but invisible to the app.
• Route: app/standalone/[module]/page.tsx, with generateStaticParams() as the static export requires. It reuses ModulePlayerClient, so progress, section navigation and the feedback link behave exactly as in a track module. Progress keys as standalone/<level>/<id>, which slots into the existing moduleKey() scheme with no special-casing.
• Player: backHref / backLabel are new optional props defaulting to current behaviour. Standalone modules have no level listing to return to, so they send readers back to the catalogue. The M1. prefix is suppressed for index 0, since track modules are 1-indexed.
• Homepage: a "Before you start" section above the tracks, worded to match what the track content already promises.

Route generation and the homepage listing are both gated on the markdown existing rather than on the manifest, following the precedent in getAllModuleParams(): the standalone section declares sixteen modules and one is written, so listing from the manifest would advertise fifteen dead links.

Also settles the hosts-file contradiction

The three setup docs had drifted. shared/setup.md told macOS and Linux readers to add the /etc/hosts entry by hand after running bootstrap.sh, while both track modules said bootstrap does it.

Bootstrap is right. It calls scripts/update-hosts, which greps before appending. The manual line does not, so following the doc appended a duplicate /etc/hosts entry and asked for sudo for nothing.

Removed for macOS and Linux. Kept for Windows, where it is genuinely required and now says why: bootstrap runs inside WSL 2 and only updates Linux's hosts file, which the Windows browser never reads.

Verification

Production build, 27 static pages including /standalone/standalone-env-setup:

└ ● /standalone/[module]
  └ /standalone/standalone-env-setup

tsc --noEmit clean.

Deliberately not in this PR

The two references in php/beginner/1.md are left as prose rather than turned into links. ReactMarkdown has no custom a renderer, so a markdown link renders as a plain <a href> with no basePath prefix and would 404 on the deployed site under /academy. No content currently relies on absolute internal links. Worth its own issue.

AI-Assisted-By: Claude Opus 5 (1M context)

[Copilot]

🟢 Approval recommended

The standalone module wiring is consistent with existing routing/player patterns and includes filesystem gating to prevent dead links, with only minor follow-up nits noted.

Pull request overview

This PR wires up rendering and discovery of standalone (trackless) modules so the “Setting Up Your Development Environment” content can actually be reached from the course UI, and it aligns the setup documentation with bootstrap’s real hosts-file behavior.

Changes:

• Model and resolve standalone modules via manifest + filesystem gating (avoid generating dead routes/links).
• Add a standalone module route that reuses the existing module player and progress storage scheme.
• Add a “Before you start” standalone section on the homepage and update setup docs to remove duplicate /etc/hosts instructions (except Windows).

File summaries

File	Description
lib/types.ts	Adds typed support for standalone modules/categories in the manifest.
lib/manifest.ts	Adds standalone lookups and static param generation gated by existing markdown.
lib/content.ts	Adds standalone markdown loading and a “written standalone modules” list for homepage gating.
content/shared/setup.md	Removes redundant manual hosts edits on macOS/Linux; clarifies Windows requirements.
content/course-manifest.json	Wires standalone-env-setup to shared/setup.md via a file field.
components/ModulePlayerClient.tsx	Adds optional back-link props and suppresses module prefix for standalone index 0.
components/CatalogClient.tsx	Adds a “Before you start” standalone section based on server-provided availability.
app/standalone/[module]/page.tsx	New standalone module page reusing ModulePlayerClient + static params.
app/page.tsx	Passes written-standalone IDs to the catalog for gating.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[miaulalala]

One deliberate deferral, noted so it isn't mistaken for an oversight: the "Before you start" section ignores the track and level filter chips, so filtering to PHP still shows it.

That seemed right for a module that belongs to no track and is a prerequisite for both, but it does mean the section sits outside the filter model and isn't counted in the "66 modules" total. Worth revisiting when there is more than one standalone module written — with one, filtering it is not a real interaction.

Same reasoning for not adding a "Standalone" filter chip yet.

[Copilot]

🟡 Changes recommended

Standalone route/listing gating should verify paths are regular files (and containment guarantees should match implementation) to avoid generating routes/cards for unreadable paths and to prevent runtime/build crashes.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (1)

lib/content.ts:76

• getWrittenStandaloneModules() treats any existing path as renderable, but fs.existsSync() also returns true for directories; that would incorrectly surface a standalone module as "written" (and generate links) even though the module can't be read. Prefer statSync(...).isFile() here.

  for (const category of Object.values(manifest.standalone?.categories ?? {})) {
    for (const mod of category.modules) {
      if (!mod.file) continue
      const filePath = standaloneContentPath(mod.file)
      if (filePath && fs.existsSync(filePath)) ids.push(mod.id)

• Files reviewed: 9/9 changed files
• Comments generated: 3
• Review effort level: Lite