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.

Section	Files	Related Code
Overview	1-overview.md, 1.1-architecture.md, 1.2-api-architecture.md, 1.3-self-hosting-vps.md	src/, api/, package.json
Apps Index	2-apps.md	src/config/appRegistry.tsx, src/apps/*/metadata.ts
Framework	3-*.md (incl. 3.1–3.5, 3.3.1)	src/components/layout/, src/stores/, src/themes/, src/hooks/
AI System	4-ai-system.md	api/chat.ts, api/chat/tools/, src/apps/chats/tools/
File System	5-file-system.md	useFilesStore.ts, src/apps/finder/
Audio System	6-audio-system.md	audioContext.ts, useSound.ts, src/apps/synth/
UI Components	7-*.md (incl. 7.1 component library, 7.2 i18n)	src/components/ui/, src/lib/locales/
API Reference	8-*.md (incl. 8.1–8.10)	api/*.ts, docs/8.10-api-design-guide.md
Legal	10-privacy.md, 11-terms.md	n/a (manual)

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.

Quality gate (required before commit)

1. Crop the output WebP menubar (extract y=0..28, ~420×28) and upscale 2× with kernel: "nearest". Compare to the same crop from 2026-07-08-ie-reader-mode-16x9.webp and from the raw PNG.
2. Labels (Maps, Stuff, System Preferences, Internet Explorer) must be readable with no horizontal scan lines or chroma fringing.
3. If the WebP crop is worse than the PNG, the bug is encode — raise to lossless. If the PNG crop is already dirty, recapture.
4. The Vite watcher ignores public/** — restart the dev server before loading new assets in the browser, or they 200 with the SPA HTML fallback.

4. Generate HTML

bun run generate:docs   # generate-app-docs.ts + generate-docs.ts

This regenerates all of public/docs/. Commit changelog.html and overview.html (its latest-changelog cards come from the two newest featured entries). Other pages may also change if their markdown drifted — review each diff and include legitimate syncs. Caution: the secret scanner can block committing self-hosting-vps.html from cloud agents (its content matches the STORAGE_PROVIDER secret value); unstage and revert it if flagged.

5. Sync Tests

tests/unit/i18n/test-changelog-docs-sync.test.ts enforces md/HTML sync, 1280×720 screenshot dimensions, month count, the ≤5 featured limit, and the exact featured-screenshot lists for recent months — update its expectations (and add new anchor phrases) when the featured set changes, then run:

bun test tests/unit/i18n/test-changelog-docs-sync.test.ts tests/unit/i18n/test-generate-docs-path-links.test.ts

6. Review Changes

git diff docs/ public/docs/ tests/

Sub-Agent Prompts

Overview: Review package.json, src/ structure → update tech stack, features

Apps Index: Review src/apps/*/index.ts, appRegistry.tsx → update app list

Framework: Review WindowFrame.tsx, stores, themes → update window/state/theme docs

AI System: Review api/chat.ts, tools → update models, capabilities

File System: Review useFileSystemStore.ts, finder → update operations

Audio System: Review audioContext.ts, synth → update audio features

UI Components: Review src/components/ui/, locales → update component list, i18n

API Reference: Review api/*.ts → update endpoints, request/response formats

Section Shortcuts

Arg	Sections
overview	1-overview, 1.1-architecture
apps	2-apps
framework	3-* files
ai	4-ai-system
filesystem	5-file-system
audio	6-audio-system
ui	7-* files
api	8-* files

Notes

• Changelog: 9-changelog.md is hand-curated (featured cards + screenshots + monthly bullets). generate-changelog.ts only exists to bootstrap a missing file from git history; never run it with --force (and avoid generate:docs:full, which does) over curated content. Screenshot encode: near-lossless WebP, smartSubsample: false — see §3; do not ship scan-line artifacts

• App docs: Individual app pages (2.1, 2.2, … one per registered app) are auto-generated via generate-app-docs.ts — do NOT hand-edit them. The count tracks appRegistry, so the range grows as apps are added

• One-shot generation: bun run generate:docs runs generate-app-docs.ts → generate-docs.ts; the changelog md is left untouched

• Preserve structure: Keep headings, mermaid diagrams, formatting

• Be conservative: Only update clearly outdated info

• Run HTML generation: Always run generate-docs.ts (or generate:docs) after updates