koala73 / koala73/worldmonitor

docs(desktop): README/docs/registry claims drift from observed desktop behavior

Open
#5,910 1 comment 0 reactions 0 assignees View on GitHub
bug P2
Dominant language
TypeScript
Stars
86.6k
Forks
13.1k
Avg merge
8h 4m
Merged PRs (30d)
825

Description

## Summary

Observed at `7fc700303`, README/docs/registries promise things the desktop code does not do:

- `README.md:74` labels desktop binaries **Stable** against a 5-month-stale release; omits the Linux ARM64 AppImage that CI builds and `/api/download` serves; "one binary switches variants in-app" is true for content but false for branding/identifier/updater variant (build-time-fixed, `src/app/desktop-updater.ts:17-21`).
- README badges (`README.md:35-38`) use `windows-exe` while the in-app banner (`src/components/DownloadBanner.ts:35`) and updater (`src/app/desktop-updater.ts:132`) use `windows-msi` — a different installer depending on where the user clicked.
- `docs/desktop-app.mdx:218` says the app polls `worldmonitor.app/api/version`; the code polls `api.worldmonitor.app` (`src/app/desktop-updater.ts:73`). `:222` says results are cached 1 hour; actual `s-maxage=300` (`api/version.js:21`). `:11` omits Linux from keychain support — silently matching the open #802/#1905 gap rather than documenting it.
- `docs/usage-rate-limits.mdx:136` documents a ~50 MB cap on `api/download` that does not exist (the endpoint is a 302 redirect with no size handling).
- `api/api-route-exceptions.json:557-560` misdescribes `api/fwdstart.js` as "Tauri desktop updater bootstrap"; it is a newsletter RSS scraper. Audits trusting that registry for desktop surface area get a false positive.
- `docs/release-packaging.mdx` documents macOS/Windows only — no Linux packaging path despite Linux x64 + ARM64 artifacts being advertised, built, and served.
- Both local-backend audit docs are stale: `docs/Docs_To_Review/local-backend-audit.md` cites 10+ deleted files; `docs/local-backend-audit.md:11,13` describes a removed catch-all gateway (`api/[[...path]].js`, removed in #785) and miscounts JSON-serving `.js` routes. Superseded by `docs/desktop-parity-matrix.md` for route coverage — mark or archive them.
- `src/services/desktop-readiness.ts:64-65` still cites deleted `/api/risk-scores` routes; the string surfaces in the Service Status UI (feeds #1942).

## Ask

Align each claim with observed behavior (or change the behavior where the claim is the intent). #5902 acceptance requires README/download/docs status to reflect observed support rather than aspiration.

Found during the #5902 parity baseline audit (see `docs/desktop-parity-matrix.md`). Part of #5902.

Contributor guide

Open the contributing guide

Research direction

Start with docs/desktop-parity-matrix.md and verify the cited behavior in README.md, docs/desktop-app.mdx, docs/usage-rate-limits.mdx, docs/release-packaging.mdx, the audit docs, and the referenced TypeScript/API files. Reconcile each documented claim with the observed implementation, including the registry and readiness references. Done means the affected documentation and metadata consistently describe current desktop, download, updater, and route behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, desktop, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
58/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.