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. | 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: ```bash 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): ```html <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: ```ts 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: ```ts 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 ```bash 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: ```bash bun test tests/unit/i18n/test-changelog-docs-sync.test.ts tests/unit/i18n/test-generate-docs-path-links.test.ts ``` ### 6. Review Changes ```bash 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