Incognito-Wiki/docs/superpowers/plans/2026-08-11-publish-useful-guides.md

# Useful Guides Publication Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Publish Housing Guide, Linux Tricks, and Surviving DACS in the Starlight wiki and update Laptop Buying Advice with the newer hardware recommendations.

**Architecture:** Treat the three new pages as reviewed supplemental content sourced from the retained `wiki.msvincognito.nl` snapshot, while updating the manifest-backed laptop destination in place. Use native Markdown, explicit supplemental registry entries, the existing manual sidebar, and focused Node tests to enforce publication, discovery, content-safety, and laptop-specification requirements.

**Tech Stack:** Astro 7, Starlight 0.41, Markdown, JavaScript ES modules, Node.js test runner.

## Global Constraints

- Publish Laptop Buying Advice, Housing Guide, Linux Tricks, and Surviving DACS.
- Do not add historical-information or dated-warning callouts to these four guides.
- Preserve practical substance and contributor voice while correcting obvious spelling, grammar, and Markdown defects.
- Do not invent current facts or state that time-sensitive prices, services, housing practices, or university systems were reverified.
- Remove dead links, obsolete credential-handling instructions, and recommendations that create avoidable legal or safety risk.
- Use `useful-guide-recovery` for each new supplemental registry entry.
- Keep all routes under `/useful-information/`; do not introduce redirects or a new top-level navigation group.

## File map

- `src/content/docs/useful-information/laptop-buying-advice.md`: existing guide, updated with the newer buying baseline.
- `src/content/docs/useful-information/housing-guide.md`: new housing-search and scam-avoidance guide.
- `src/content/docs/useful-information/linux-tricks.md`: new Linux-oriented UM services guide with credential-safe examples.
- `src/content/docs/useful-information/surviving-dacs.md`: new academic and student-life guide.
- `src/content/docs/useful-information/index.md`: section introduction and discovery links.
- `src/config/sidebar.mjs`: manual navigation entries for all published guides.
- `docs/supplemental-content.json`: source provenance for the three new pages.
- `docs/migration-report.md`: publication-boundary record for the reviewed snapshot material.
- `to-be-studied/README.md`: research archive note acknowledging the reviewed derivatives.
- `tests/useful-guides.test.mjs`: focused guide content, provenance, navigation, and safety contract.
- `tests/content-audit.test.mjs`: updated total counts and removal of the old laptop-warning requirement.

---

### Task 1: Modernize Laptop Buying Advice

**Files:**
- Create: `tests/useful-guides.test.mjs`
- Modify: `tests/content-audit.test.mjs`
- Modify: `src/content/docs/useful-information/laptop-buying-advice.md`

**Interfaces:**
- Consumes: the existing manifest-backed laptop route at `useful-information/laptop-buying-advice.md`.
- Produces: a published laptop page whose frontmatter remains `title: Laptop Buying Advice` and whose body contains the new minimum specification and compatibility guidance without a historical caution directive.

- [ ] **Step 1: Write the failing laptop contract**

Create `tests/useful-guides.test.mjs`:

```js
import assert from 'node:assert/strict';
import { readFile } from 'node:fs/promises';
import test from 'node:test';

const docsRoot = 'src/content/docs/useful-information';

test('Laptop Buying Advice publishes the newer hardware baseline without a dated warning', async () => {
  const content = await readFile(`${docsRoot}/laptop-buying-advice.md`, 'utf8');

  assert.match(content, /16 GB/);
  assert.match(content, /512 GB/);
  assert.match(content, /Core i5-class or equivalent/i);
  assert.match(content, /M-series Mac/i);
  assert.match(content, /Nvidia[\s\S]*CUDA/i);
  assert.doesNotMatch(content, /:::caution\[Historical information\]/);
});
```

In `tests/content-audit.test.mjs`, keep the clean-Markdown loop's frontmatter and forbidden-token assertions. Replace its unconditional historical-notice assertion with this exception so all other migrated pages retain the existing invariant:

```js
if (file !== 'src/content/docs/useful-information/laptop-buying-advice.md') {
  assert.match(content, /This information originated in the previous wiki and may be outdated\./);
}
```

Change the `prominently identifies historical guidance` file list to contain only `src/content/docs/useful-information/it-services.md`.

- [ ] **Step 2: Run the focused tests and verify failure**

Run: `node --test tests/useful-guides.test.mjs tests/content-audit.test.mjs`

Expected: FAIL because the laptop page lacks the new baseline and still contains `:::caution[Historical information]`.

- [ ] **Step 3: Rewrite the laptop page around the current source update**

Retain this frontmatter:

```md
---
title: Laptop Buying Advice
description: Practical laptop-buying guidance for DACS students.
---
```

Use `## Recommended baseline for a new laptop` as the first body section and state all five required points explicitly:

```md
- **Memory:** At least 16 GB RAM.
- **Storage:** At least a 512 GB SSD.
- **Processor:** A mid-range Intel Core i5-class, AMD Ryzen 5-class, or equivalent processor.
- **Operating system:** Windows, Linux, and M-series Macs can all be suitable; confirm course-specific software compatibility before purchasing.
- **Data Science and AI workloads:** An Nvidia GPU is useful when coursework or personal projects use CUDA, but it is not required for every course.
```

Preserve and clean the source guidance about needing a laptop for labs and projects, screen size, keyboard layouts, battery/build quality, and dedicated graphics. Replace the obsolete €200/€400/€600/€800 configurations with budget-neutral advice headed `## Choosing within your budget`; do not present 2–8 GB RAM, 16–256 GB storage, Windows 10, or 2021 price bands as current recommendations.

- [ ] **Step 4: Run the focused tests and verify success**

Run: `node --test tests/useful-guides.test.mjs tests/content-audit.test.mjs`

Expected: PASS with the existing content totals unchanged at 83 pages and 55 supplemental entries.

- [ ] **Step 5: Commit the laptop update**

```bash
git add tests/useful-guides.test.mjs tests/content-audit.test.mjs src/content/docs/useful-information/laptop-buying-advice.md
git commit -m "content: update laptop buying guidance"
```

---

### Task 2: Publish the Three Additional Guides

**Files:**
- Create: `src/content/docs/useful-information/housing-guide.md`
- Create: `src/content/docs/useful-information/linux-tricks.md`
- Create: `src/content/docs/useful-information/surviving-dacs.md`
- Modify: `docs/supplemental-content.json`
- Modify: `tests/useful-guides.test.mjs`
- Modify: `tests/content-audit.test.mjs`

**Interfaces:**
- Consumes: the archived Markdown under `to-be-studied/live-wiki/2026-08-02/useful-guides/` and `auditContent({ docsRoot, manifest, supplemental })` from `scripts/audit-content.mjs`.
- Produces: three native Starlight Markdown pages plus three unique supplemental registry entries; the audit result becomes `pageCount: 86` and `supplementalCount: 58`.

- [ ] **Step 1: Extend the focused tests for publication and provenance**

Append to `tests/useful-guides.test.mjs`:

```js
const recoveredGuides = [
  {
    slug: 'housing-guide',
    title: 'Housing Guide',
    source: 'https://wiki.msvincognito.nl/useful-guides/housing-guide',
  },
  {
    slug: 'linux-tricks',
    title: 'Linux Tricks',
    source: 'https://wiki.msvincognito.nl/useful-guides/linux-tricks',
  },
  {
    slug: 'surviving-dacs',
    title: 'Surviving DACS',
    source: 'https://wiki.msvincognito.nl/useful-guides/survivingdacs',
  },
];

test('the three recovered guides are publishable native Markdown', async () => {
  for (const { slug, title } of recoveredGuides) {
    const content = await readFile(`${docsRoot}/${slug}.md`, 'utf8');
    assert.match(content, new RegExp(`^---\\n[\\s\\S]*title: ${title}`));
    assert.doesNotMatch(content, /^#\s+/m);
    assert.doesNotMatch(content, /:::caution\[Historical information\]/);
    assert.doesNotMatch(content, /\[\[|\{\{|NEWPAGE>|indexmenu>|~~NOCACHE~~/);
  }
});

test('the recovered guide registry records source provenance', async () => {
  const supplemental = JSON.parse(await readFile('docs/supplemental-content.json', 'utf8'));
  for (const { slug, source } of recoveredGuides) {
    assert.deepEqual(
      supplemental.find(({ destination }) => destination === `${docsRoot}/${slug}.md`),
      {
        destination: `${docsRoot}/${slug}.md`,
        source,
        category: 'useful-guide-recovery',
      },
    );
  }
});

test('published guides omit unsafe or legally questionable source recommendations', async () => {
  const linux = await readFile(`${docsRoot}/linux-tricks.md`, 'utf8');
  const survival = await readFile(`${docsRoot}/surviving-dacs.md`, 'utf8');
  assert.doesNotMatch(linux, /password=["']?<password>/i);
  assert.doesNotMatch(survival, /Sci-Hub|Library Genesis|Library\.nu/i);
});
```

Update both audit-count assertions in `tests/content-audit.test.mjs` from 83/55 to 86/58.

- [ ] **Step 2: Run the tests and verify failure**

Run: `node --test tests/useful-guides.test.mjs tests/content-audit.test.mjs`

Expected: FAIL with `ENOENT` for the three unpublished guide files and missing supplemental records.

- [ ] **Step 3: Create Housing Guide**

Create `src/content/docs/useful-information/housing-guide.md` with:

```md
---
title: Housing Guide
description: Practical guidance for finding student housing in Maastricht and recognizing scams.
---
```

Migrate the source into these native headings: `## Where to look`, `### Facebook groups and private listings`, `### Maastricht Housing`, `### Housing agencies and student residences`, `## Avoiding scams`, `### Checking private listings`, `### Checking agencies`, and `## Practical tips after moving`. Preserve the viewing, identity-document, address/landlord verification, reverse-image checking, included-cost, contract-before-payment, and Dutch Chamber of Commerce checks. Rephrase absolute claims based solely on nationality, country code, or phone number as signals to investigate rather than proof of fraud. Omit the unverified Kamernet accusation, exact platform fee, nationality-priority description, and claims about named residences that have not been reverified.

- [ ] **Step 4: Create Linux Tricks**

Create `src/content/docs/useful-information/linux-tricks.md` with:

```md
---
title: Linux Tricks
description: Linux-oriented tips for connecting to Maastricht University services.
---
```

Migrate the source into `## Eduroam`, `## VPN and library access`, `## University file services`, `## Remote desktop`, and `## Useful resources`. Preserve distro-neutral explanations and links to authoritative ArchWiki or vendor documentation. Code fences must use `sh` or an appropriate configuration language. Do not include a plaintext `password="<password>"` line, obsolete `unimaas.nl` identity examples, or a claim that an old UM VPN/file-service hostname is currently operational. Direct readers to current UM service instructions where the captured command depends on an institutional hostname.

- [ ] **Step 5: Create Surviving DACS**

Create `src/content/docs/useful-information/surviving-dacs.md` with:

```md
---
title: Surviving DACS
description: Student-contributed advice for studying and living as a DACS student.
---
```

Preserve the contributor disclaimer as ordinary introductory prose, not a warning directive. Migrate the source into the following section structure: `## University`, with Projects, Books and articles, Studying, Exams, Programming, and Mathematics; `## Thesis`; `## Grades`; `## Living`, with Sustainability, Housing, Food, Cooking, Essentials, and Transportation; `## Social life`; `## Gaining experience`, with Honours programmes, Internships, Mentorships, and Jobs; and `## Healthy and productive habits`, with Sleep, Ventilation, Ergonomics, Task management, and Audiobooks. Remove Sci-Hub, Library Genesis, and Library.nu references. Remove or generalize stale restaurant tables, exact rent/food/gym/wage prices, dead social-group links, and claims tied to a specific building or course schedule. Preserve actionable study habits, project/version-control advice, exam strategy, cooking and transport suggestions, career-development ideas, sleep, ventilation, and ergonomics.

- [ ] **Step 6: Register the new destinations**

Add these objects to `docs/supplemental-content.json`, maintaining destination sort order:

```json
{
  "destination": "src/content/docs/useful-information/housing-guide.md",
  "source": "https://wiki.msvincognito.nl/useful-guides/housing-guide",
  "category": "useful-guide-recovery"
},
{
  "destination": "src/content/docs/useful-information/linux-tricks.md",
  "source": "https://wiki.msvincognito.nl/useful-guides/linux-tricks",
  "category": "useful-guide-recovery"
},
{
  "destination": "src/content/docs/useful-information/surviving-dacs.md",
  "source": "https://wiki.msvincognito.nl/useful-guides/survivingdacs",
  "category": "useful-guide-recovery"
}
```

- [ ] **Step 7: Run the focused tests and content audit**

Run: `node --test tests/useful-guides.test.mjs tests/content-audit.test.mjs && npm run audit:content`

Expected: PASS; audit reports 29 sources, 28 unique manifest destinations, and 86 published pages.

- [ ] **Step 8: Commit the published guide content**

```bash
git add src/content/docs/useful-information/housing-guide.md src/content/docs/useful-information/linux-tricks.md src/content/docs/useful-information/surviving-dacs.md docs/supplemental-content.json tests/useful-guides.test.mjs tests/content-audit.test.mjs
git commit -m "content: publish practical student guides"
```

---

### Task 3: Add Guide Discovery and Navigation

**Files:**
- Modify: `tests/useful-guides.test.mjs`
- Modify: `src/content/docs/useful-information/index.md`
- Modify: `src/config/sidebar.mjs`

**Interfaces:**
- Consumes: the four guide slugs under `src/content/docs/useful-information/`.
- Produces: landing-page relative links and sidebar slug entries for every practical guide.

- [ ] **Step 1: Write the failing discovery test**

Append to `tests/useful-guides.test.mjs`:

```js
test('Useful Information navigation exposes every practical guide', async () => {
  const landing = await readFile(`${docsRoot}/index.md`, 'utf8');
  const sidebar = await readFile('src/config/sidebar.mjs', 'utf8');
  for (const slug of ['housing-guide', 'laptop-buying-advice', 'linux-tricks', 'surviving-dacs']) {
    assert.match(landing, new RegExp(`\\]\(\\./${slug}/\\)`));
    assert.match(sidebar, new RegExp(`slug: 'useful-information/${slug}'`));
  }
});
```

- [ ] **Step 2: Run the discovery test and verify failure**

Run: `node --test tests/useful-guides.test.mjs`

Expected: FAIL because the landing page and sidebar do not yet link the three new routes.

- [ ] **Step 3: Update the Useful Information landing page**

Retain the existing frontmatter and official Maastricht University education link. Add a `## Practical guides` section with these exact relative links:

```md
- [Housing Guide](./housing-guide/)
- [Laptop Buying Advice](./laptop-buying-advice/)
- [Linux Tricks](./linux-tricks/)
- [Surviving DACS](./surviving-dacs/)
```

Keep DKE Locations, Handy Locations, and IT Services under a separate `## Other useful information` heading. Remove the page-level historical caution because the landing page now introduces both current practical guides and legacy reference pages; individual legacy destinations retain their own treatment.

- [ ] **Step 4: Update the manual sidebar**

Within the `Useful Information` item list in `src/config/sidebar.mjs`, use this order:

```js
{ slug: 'useful-information' },
{ slug: 'useful-information/housing-guide' },
{ slug: 'useful-information/laptop-buying-advice' },
{ slug: 'useful-information/linux-tricks' },
{ slug: 'useful-information/surviving-dacs' },
{ slug: 'useful-information/dke-locations' },
{ slug: 'useful-information/handy-locations' },
{ slug: 'useful-information/it-services' },
```

- [ ] **Step 5: Run focused navigation and content tests**

Run: `node --test tests/useful-guides.test.mjs tests/content-audit.test.mjs`

Expected: PASS.

- [ ] **Step 6: Commit navigation changes**

```bash
git add src/content/docs/useful-information/index.md src/config/sidebar.mjs tests/useful-guides.test.mjs
git commit -m "content: expose useful guides in navigation"
```

---

### Task 4: Record Publication and Verify the Site

**Files:**
- Modify: `docs/migration-report.md`
- Modify: `to-be-studied/README.md`
- Test: complete repository workflow

**Interfaces:**
- Consumes: the completed guide pages, registry, and navigation.
- Produces: accurate maintainer documentation and a fully verified production build.

- [ ] **Step 1: Update the publication records**

In `docs/migration-report.md`, replace the blanket statement that all newer-wiki captures remain unpublished with an explicit record: three reviewed practical guides were published as supplemental content, and the existing laptop destination received the newer source recommendations. State that all remaining raw captures stay research-only. In the Laptop Buying Advice inventory row, change `Outdated` from `Yes, prominently historical` to `No`, and describe the incorporated 16 GB RAM, 512 GB SSD, processor, M-series Mac, and Nvidia/CUDA update. Replace the `Historical laptop advice` narrative with `Laptop buying advice`, explaining that obsolete price tiers were generalized instead of being presented as current recommendations.

In `to-be-studied/README.md`, retain the rule that raw capture files are never served directly. Add that Housing Guide, Linux Tricks, and Surviving DACS were editorially reviewed and published on 2026-08-11 through separately registered Markdown destinations, while Laptop Buying Advice was merged into its existing destination.

- [ ] **Step 2: Run formatting and targeted checks**

Run: `git diff --check && node --test tests/useful-guides.test.mjs tests/content-audit.test.mjs`

Expected: PASS with no whitespace errors.

- [ ] **Step 3: Run the complete verification workflow**

Run: `npm run verify`

Expected: Astro validation, all Node tests, content audit, production build, rendered-output check, and internal-link check all PASS.

- [ ] **Step 4: Review the built routes**

Confirm these files exist and contain rendered `<main>` content:

```text
dist/useful-information/housing-guide/index.html
dist/useful-information/laptop-buying-advice/index.html
dist/useful-information/linux-tricks/index.html
dist/useful-information/surviving-dacs/index.html
```

Run:

```bash
rg -l '<main' dist/useful-information/{housing-guide,laptop-buying-advice,linux-tricks,surviving-dacs}/index.html
```

Expected: all four files are listed.

- [ ] **Step 5: Commit documentation and any final verification fixes**

```bash
git add docs/migration-report.md to-be-studied/README.md
git commit -m "docs: record useful guides publication"
```

- [ ] **Step 6: Confirm the final worktree state**

Run: `git status --short && git log -4 --oneline`

Expected: no uncommitted changes; the four implementation commits appear above the design and plan history.