Update manually-written docs by launching parallel sub-agents for each section.
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.
For each section, launch a Task with:
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:
git log -1 --format=%H -- docs/9-changelog.md # last changelog commit
git log <that-hash>..HEAD --no-merges --pretty='%ad %s' --date=short
<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.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>
Featured cards need an exactly 1280×720 WebP in public/docs-assets/changelog/, named YYYY-MM-NN-slug-16x9.webp. Capture from the running app:
bun run dev, then screenshot with Playwright (playwright-core is in node_modules; Chrome at /usr/bin/google-chrome-stable) using a 1280x720 viewport, deviceScaleFactor: 1. Open the relevant app/pane (http://localhost:5173/<app-id> launches an app directly) and wait ~20s for boot + entrance animations.page.mouse — the window root is [data-window-instance-id] and the drag handle is its .title-bar child; compute the delta from the window's to horizontally and vertically, and move in ~10 steps so the drag registers.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.
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
git diff docs/ public/docs/ tests/
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
| 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 |
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 content2.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 addedbun run generate:docs runs generate-app-docs.ts → ; the changelog md is left untouchedgetBoundingClientRect()(1280 - width) / 2menubar + (dockTop - menubar - height) / 2sharp(png).webp({ quality: 80 }).toFile(...) and verify metadata is 1280×720.public/** — restart the dev server before visually verifying new assets, or they 200 with the SPA HTML fallback.| 7-* files |
api | 8-* files |
generate-docs.tsgenerate-docs.ts (or generate:docs) after updates
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).