docs: overhaul README + add social preview - #53
Conversation
- Fix broken download links (were pointing to non-existent genspark-ai/hermesoffice; fork ships via release train + auto-update) - Remove leftover Genspark references (provider, ai-search, trademark) - Add badges, why-it-exists section, agent-native positioning - Link public roadmap (Phase 2 · Value Loops) and good-first-issue label - Add 1280x640 social preview banner (brand gradient, logo mark)
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ede4ee4c25
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| chmod +x HermesOffice-0.5.149.AppImage | ||
| ./HermesOffice-0.5.149.AppImage | ||
| ``` | ||
| - **Local-first by default.** Board material, CISO-grade conversations and NDAs never leave your machine. The Hermes Agent gateway runs on your computer — no API key, no cloud account. |
There was a problem hiding this comment.
For a fresh installation following these instructions, the AI functionality is unusable as described: docs/hermes-integration.md says Hermes must be installed separately, its API server must be enabled and running, and the user must configure and enter an API_SERVER_KEY; packages/ai-provider/src/stream.ts sends that key as the bearer token. Remove the “no API key” claim and link the required setup steps from the install section so users do not end up with a permanently failing AI panel.
Useful? React with 👍 / 👎.
| ``` | ||
| - **Local-first by default.** Board material, CISO-grade conversations and NDAs never leave your machine. The Hermes Agent gateway runs on your computer — no API key, no cloud account. | ||
| - **Open standards, byte-preserving.** Opening and saving never breaks layout in Word, Excel or PowerPoint. Only the blocks you (or the agent) touched are regenerated; everything else survives the round trip byte-for-byte. | ||
| - **Agent-native, auditable.** Every AI mutation is visible and reversible — a unified _Proposed Change_ pipeline (diff preview → atomic apply) that the agent itself goes through, in every app. |
There was a problem hiding this comment.
Users relying on this trust guarantee can have documents mutated before approval: the checked ROADMAP.md explicitly says only Sheets has the proposal flow, while Docs and Slides use after-the-fact snapshots and PDF's trust UX is pending; it also marks the unified Proposed Change contract as design work. This line should describe the current per-app behavior rather than claiming that every mutation already passes through a diff-preview/atomic-apply gate.
Useful? React with 👍 / 👎.
| **macOS (Apple Silicon / Intel):** | ||
|
|
||
| ```bash | ||
| git clone https://github.com/criptogus/HermesOffice.git | ||
| cd HermesOffice | ||
| npm install | ||
| npm run dist:mac # → apps/shell/release/HermesOffice-*.dmg |
There was a problem hiding this comment.
On an Intel Mac, the shown npm run dist:mac command still packages only arm64: apps/shell/electron-builder.cjs includes x64 only when GENOFFICE_MAC_X64=1, which these instructions never set. Anyone following the advertised Intel path therefore receives an incompatible DMG; either include the opt-in environment variable or label this command Apple-Silicon-only.
Useful? React with 👍 / 👎.
| ```bash | ||
| git clone https://github.com/criptogus/HermesOffice.git | ||
| cd HermesOffice | ||
| npm install | ||
| npm run fixtures # generate test .docx fixtures | ||
| npm test # engine + app unit tests (docs/sheets/slides need no display) | ||
| npm run typecheck # tsc --noEmit across every workspace | ||
| npm run dev # all four editors + shell against Vite dev servers | ||
| npm run dev:docs # a single app (same pattern works per workspace) | ||
| npm run dist:mac # package macOS dmg (regenerates third-party notices) | ||
| npm run dist:win # package Windows nsis installer | ||
| npm run dist:win # → apps/shell/release/HermesOfficeSetup-*.exe |
There was a problem hiding this comment.
On a fresh Windows checkout, this command does not produce a complete installer: build:all compiles the sidecar into Cargo's normal MSVC output, but apps/shell/electron-builder.cjs packages only target/x86_64-pc-windows-gnu/release/xlsx-sidecar.exe. The prerequisite already documented in CONTRIBUTING.md—building the GNU target or copying the binary into that path—must be included here; otherwise electron-builder can omit the resource and every workbook open in the resulting installer fails.
Useful? React with 👍 / 👎.
The markdown app shipped in the 2026-08-07 snapshot and the docs never followed it. README's intro and CONTRIBUTING's layout section still count five apps, README still says the shell hosts four editors and that npm run dev starts four, SECURITY.md's renderer-lockdown list names every window class except markdown (whose windows do set the same three flags), and neither issue template offers Markdown even though both dropdowns are required and the installer registers .md and .markdown associations. Separately, .nvmrc pinned 20 and CONTRIBUTING said Node 20+, while package.json engines requires >=22.12.0 and all three workflows run node-version: 22, so following the checked-in version gives an install npm rejects and a toolchain that does not match CI. README's Apps table also has no row for markdown. That one needs product wording rather than a count, so it is left for a maintainer.
1 participant
What changes
Overhaul of the repo's public face — README was broken and stale:
Fixes (critical)
genspark-ai/hermesoffice(repo does not exist; upstream isgenspark-ai/genoffice). The fork ships via release-train (ho-v*tags) + source-based auto-update, so the section now reflects reality: build from source instructions.ai-search, and the license section claimed "Genspark... trademarks of Mainfunc, Inc." All removed; the Hermes-native positioning now leads.Improvements
good-first-issuelabel.github/social-preview.png) with brand gradient + logo mark, shown on GitHub/links sharesBefore/after