Update Docs

Update Documentation

Update manually-written docs by launching parallel sub-agents for each section.

Documentation Sections

Section files live in docs/. The list below covers the hand-written sections; app pages (2.1–2.x) are generated and the changelog (9-changelog.md) is hand-curated — see Notes.

Run ls docs/*.md before starting so the section list reflects what currently exists.

Workflow

1. Launch Parallel Sub-Agents

For each section, launch a Task with:

1. Read current doc file(s)
2. Analyze relevant code for changes
3. Update outdated/missing info
4. Preserve existing structure
5. Report changes

2. Update the Changelog (manual curation)

docs/9-changelog.md is hand-curated — do NOT regenerate it. generate-changelog.ts skips when the file exists and --force (or generate:docs:full) would destroy the curated featured cards. Instead:

1. Find what's new since the last curation:

   git log -1 --format=%H -- docs/9-changelog.md   # last changelog commit
   git log <that-hash>..HEAD --no-merges --pretty='%ad %s' --date=short

2. Add new bullets to the current month's <details> block (never delete old content) and update the More from this month (N) count. Style: capitalized action verb, user-facing language; bold **Name**: only for significant items.
3. For headline features, add a featured card at the top of the month's changelog-feature-grid (newest first — the docs home "latest changelog" cards are built from the first two entries in document order):

   <article class="changelog-feature"><img src="/docs-assets/changelog/YYYY-MM-NN-slug-16x9.webp" alt="Feature in the <Month Year> ryOS snapshot" width="1280" height="720" loading="lazy"><div class="changelog-feature-copy"><h3>Feature</h3><p>One-line description.</p></div></article>

   Max 5 featured cards per month (test-enforced).

3. Capture Changelog Screenshots

Featured cards need an exactly 1280×720 WebP in public/docs-assets/changelog/, named YYYY-MM-NN-slug-16x9.webp. Quality bar: menubar labels (Maps, Stuff, Internet Explorer) must look as crisp as an existing July shot such as 2026-07-08-ie-reader-mode-16x9.webp. Do not ship a card that has horizontal scan-line / chroma-smear artifacts.

Capture (Playwright + Chrome)

1. Start bun run dev. Screenshot with Playwright (playwright-core in node_modules; Chrome at /usr/bin/google-chrome-stable). Viewport 1280×720, deviceScaleFactor: 1 only (never 2). Open http://localhost:5173/<app-id>?_ryo=1 (bare /<app-id> is OG share HTML and will redirect off-localhost). Wait ~20s for boot + entrance animations.
2. Stage the shot:
   • One window, sized to fit the frame. Several apps default larger than the usable area (Stuff is 920×580) and will overlap the dock — updateInstanceWindowState to ~720–800×440–480 before centering.
   • Center it between the menubar (~30px) and the top of the dock. Drag [data-window-instance-id] .title-bar with page.mouse (~10 steps). The window must not overlap the dock.
   • Clean desktop: close extra instances; disable the desktop assistant (useAssistantStore.getState().setEnabled(false)); hide toasts. Default desktop icons and the dock are fine.
   • Wallpaper: default shuffle is a random nature photo. Re-roll (new profile, or setWallpaper to another nature still such as /wallpapers/photos/nature/water.jpg) if the roll is speckled, grainy, snowy, or low-contrast. Aqua glass menubars are translucent — busy texture behind them looks like interlace even in the PNG. July Books/IE use a smooth water or sunset field; match that, do not pin a branded/custom wallpaper.
3. Freeze motion, then screenshot PNG only — never screenshot({ type: "webp" }) and never let Playwright write a lossy WebP:

   await page.addStyleTag({
     content: `*,*::before,*::after{animation:none!important;transition:none!important;}`,
   });
   const png = await page.screenshot({
     type: "png",
     animations: "disabled",
     caret: "hide",
     scale: "css",
   });

   Keep the raw PNG until the WebP passes the quality gate below. If the PNG menubar is already smeared, fix capture (animations, wallpaper, window size) — do not encode a dirty PNG.

Encode (sharp)

Default sharp(png).webp({ quality: 80 }) is wrong for these cards. It enables chroma smart-subsample and crushes flat UI / dark frames (a Sound pane became ~41KB) into horizontal scan lines. Convert the PNG with:

await sharp(png).webp({
  quality: 90,
  lossless: false,
  nearLossless: true,
  smartSubsample: false, // required — never omit
  effort: 6,
}).toFile(dest);

If a 2× nearest-neighbor crop of the menubar is still softer than July, use sharp(png).webp({ lossless: true, effort: 6 }). A few hundred KB per card is fine. Verify metadata is 1280×720.