Skip to content

docs: Polish README into a landing page and new-user guide - #135

Merged
omesser merged 14 commits into
mainfrom
cursor/polish-readme-landing-f8b9
Sep 5, 2026
Merged

omesser merged 14 commits into
mainfrom
cursor/polish-readme-landing-f8b9

Conversation

@omesser

@omesser omesser commented Aug 31, 2026 •

Copy link
Copy Markdown
Owner

Why

The current README is a developer bible: 1100+ lines covering every toolchain detail, 23-step verification, TRACE variables, and probe-model instructions dominating the top-level document. Serious OSS projects (Zed, Ghostty, Starship, Tauri) split landing vs. developing. The GitHub README is the first surface for new users and potential contributors.

No visual representation of Buddy Bot, the logo mascot and default hero character. The published design site demos (https://omesser.github.io/ai-buddy) weren't linked from the README.

What changed

Landing page README (~188 lines, down from 1100+):

  • Product name: Display name is now "Desktop Buddy" (repo stays ai-buddy)
  • Personality-driven AI as hero: Opening leads with authored personality.txt → Director picks Behaviors + dialogue, no chat window required. Spatial (perches, gestures) is the second beat.
  • Removed Harness/coding agent framing: "Do real work on your machine" claim removed (Harness unshipped). No coding-agent positioning.
  • Reordered "What It Does": Personality-driven behavior first, then Spatial, then idle life
  • Buddy Bot as hero: Logo image, walk GIF prominently featured
  • Concise structure: What/See/Interact/Characters/Install/Running/Platform/Developing
  • See It section: Buddy Cues featured as primary demo; Chat Mockups demoted (moved to DESIGN.md with "speculative design" label — chat UI unshipped, Chat surface #17)
  • Character gallery: All 8 shipped characters with showcase animations (walk/react/sing/scan/talk), shortened Personality column to 1 sentence each + link to full personality.txt
  • Thin ops surface: Moved deep Completer/provider/keyring/signing/probe-model detail to DEVELOPMENT.md. README keeps short path to first success (download → open → optional Director in Settings)
  • Complete Install section: macOS/Linux/Windows with Release artifacts, AppImage/deb notes (fuse, tray, GStreamer), NSIS/SmartScreen warnings
  • Simplified Running it section: Works offline (Static weights), connect Completer optional. One OpenAI example, one Ollama example. Details in DEVELOPMENT.md.
  • Welcoming contributor path: "Want to help?" blurb links to open issues, DEVELOPMENT.md, alternatives.md
  • Accurate platform coverage: macOS first, Linux with degraded Spatial Layer under Wayland, Windows ships NSIS installer (Spatial Layer thin but packaging real)
  • Honest about characters: 8 ship in-repo (Buddy Bot default + BMO, Nim, Black Mage, Cat, Jotaro Kujo, Timber Wolf, Trump)
  • Five-bullet "What It Does" section: shipped behavior only, personality-driven first
  • Platform table: yes/degraded/stub cells preserved
  • No claims of unshipped features (Harness, chat UI, Windows Spatial depth clearly marked)
  • Link to GitHub Releases for DMG / AppImage+deb / NSIS downloads
  • Linked alternatives.md for desktop pet comparison

DESIGN.md — State section added:

  • Early status acknowledgment
  • Issues link for work tracking
  • alternatives.md pointer for feature comparison
  • Overlay/Engine/Director story (what's implemented, what's next)
  • Chat surface status (Chat surface #17 — Summon works, chat UI unshipped)
  • Placed before "Shape of the product" section
  • Chat Mockups demo now referenced here as "speculative design"

docs/DEVELOPMENT.md — Developer content comprehensive:

  • New "Running with a Completer" section with all moved details:
    • Provider examples (OpenAI, Anthropic, xAI, Ollama)
    • Full Director env table (7 variables)
    • Settings and Keyring (Linux Secret Service, macOS Keychain ACL essay)
    • Local model server table (Ollama/oMLX/llama.cpp/LM Studio/vLLM/MLX)
    • Testing connectivity (probe-model.sh)
    • Provider details (Cursor API, xAI keys, streaming philosophy)
    • Ambient wake behavior
    • Reply contract measurements (reference to main README archived version)
  • Fixed broken "lines 668–826" reference: Restored full 23-step manual verification checklist (click-through, perches, fullscreen, multi-display, multiple instances)
  • Character writing instructions added:
    • Writing a personality (three-part structure: who they are, fixations, sample lines)
    • Universal rules (injected by character_prompt, not in personality files)
    • Package format notes (undocumented until v2)
  • Toolchains (Rust, Python, Node) with rationale
  • Pre-commit hooks
  • Verifying the overlay: unit tests, verify-overlay.sh, manual checklist
  • Trace variables table (HITTEST, FRAMES, DIRECTOR, ENGINE, CAPTURABLE)
  • Character Packages: search paths, AI_BUDDY_CHARACTERS env
  • Importing pets from petscodex/Shimeji-ee
  • macOS developer signing
  • Linux dependencies and platform details

Generated assets (showcase animations, not boring idles):

  • scripts/generate-readme-gifs.py — generates showcase GIFs from character frames (Pillow)
  • docs/readme/buddy-bot-walk.gif (21.6 KB) — 8-frame motion stride, 8 fps
  • docs/readme/buddy-bot-react.gif (12.2 KB) — 5-frame delighted startle, 12 fps (Interact section)
  • docs/readme/black-mage-talk.gif (4.0 KB) — 2-frame incantation/cast, 3 fps
  • docs/readme/bmo-sing.gif (10.4 KB) — 4-frame signature variant, 3 fps
  • docs/readme/cat-walk.gif (27.2 KB) — 8-frame motion, 8 fps
  • docs/readme/jotaro-kujo-react.gif (21.7 KB) — 8-frame Stand aura showcase, 7 fps
  • docs/readme/nim-sleep.gif (6.3 KB) — 4-frame sleep (matches personality), 3 fps
  • docs/readme/timber-wolf-scan.gif (11.0 KB) — 4-frame TAC laser sweep, 4 fps (unique differentiator)
  • docs/readme/trump-talk.gif (13.5 KB) — 3-frame rally wave, 4 fps

All GIFs: transparent backgrounds, nearest-neighbor scaling, consistent 96px height, looping enabled.

How to verify

Automated:

  • Relative links from README to DEVELOPMENT.md, CONTEXT.md, DESIGN.md, SPEC.md, ADRs resolve
  • GIFs generated from character manifests ([animations.*] frames)
  • GIFs are small (4–28 KB), looping, transparent, equal display size
  • CI badge points to .github/workflows/tests.yml
  • scripts/generate-readme-gifs.py runs cleanly with Pillow
  • GitHub Releases link correct
  • README now 188 lines (down from 328, was 1100+ on main)
  • Display name "Desktop Buddy" in H1
  • Personality-driven AI leads opening and "What It Does"
  • Install section complete (macOS/Linux/Windows with all operational detail)
  • Running it section simplified (short path to first success)
  • Deep Completer details moved to DEVELOPMENT.md
  • DESIGN.md has State section before "Shape of the product"
  • DEVELOPMENT.md has manual checklist (no broken line number reference)
  • DEVELOPMENT.md has character writing instructions
  • DEVELOPMENT.md has comprehensive "Running with a Completer" section

Manual:

  • No claim of unshipped features: Harness, chat UI, Windows Spatial depth clearly marked
  • Eight characters acknowledged: Buddy Bot (default) + 7 more named
  • All 8 featured in gallery with showcase animations (not boring idles)
  • Personality column shortened to ~1 sentence each
  • Chat Mockups demoted (speculative design, not featured demo)
  • Welcoming "Want to help?" blurb under Developing
  • alternatives.md linked
  • Platforms accurate: macOS first, Linux with Wayland caveat, Windows ships NSIS (Spatial Layer thin but real)
  • Releases linked for DMG / AppImage+deb / NSIS downloads
  • Buddy Cues featured as primary interactive demo
  • Buddy Bot logo image displays
  • buddy-bot-react.gif shown in Interact section
  • Character GIFs display in table at consistent visual size
  • Developer content preserved in DEVELOPMENT.md (not deleted)
  • Install operational detail complete (not thin)
  • Running it simplified (practical, not essays)

Visual verification (showcase GIFs in this PR):

Buddy Bot walk
Black Mage talk
BMO sing
Timber Wolf scan

Notes

Display name: "Desktop Buddy" is the user-facing product name; repository stays ai-buddy for URL/git stability.

Personality-driven AI as differentiator: Each character's personality.txt drives idle behavior and dialogue — this is the unique value proposition. No chat window, no user prompting required. Static weights work offline; Completer adds model-driven variety.

Why Buddy Bot, not BMO: Buddy Bot is the logo mascot and the default character (DEFAULT_CHARACTER in src-tauri/src/package.rs). It represents the project identity. BMO is one of several shipped characters.

Why showcase animations vs idles: Idle loops are too boring for the Characters table. Each character now shows its most distinctive motion: walk, react, sing, scan, talk. Script reads frame lists from character.manifest [animations.*] entries for accuracy.

Why GIFs are in-repo: Product assets that version with the characters. Generated from shipped frames under characters/, so they stay accurate as characters change. Not one-off PR stills or external hosting.

Content restored and thinned: After aggressive README cut, operational detail was restored from main then reorganized:

  • README (188 lines): Short path to first success — download, open, optional Director in Settings. Install complete; Running it simplified.
  • DESIGN.md: State section (early status, overlay/Engine story, Chat surface #17 chat, alternatives link). Chat Mockups referenced as speculative design.
  • DEVELOPMENT.md: Manual checklist (fixed broken line ref) + character writing instructions + comprehensive "Running with a Completer" section (all provider details, keyring, local servers, probe-model, streaming, ambient wakes).

OSS landing page bar: Matches Ghostty/Zed/Starship conciseness. Personality-driven AI + Spatial features clearly differentiated. Welcoming to newcomers (5-second product understanding). Honest about what's shipped vs. unshipped.

Why DEVELOPMENT.md: Landing README is for new users and potential contributors; developer workflows (23-step verification, trace variables, pet importer, signing scripts, character writing, Completer setup) belong in a separate document. OSS convention (Zed, Tauri, Starship all split this way).

Windows status: Windows ships a real NSIS installer. The Spatial Layer is still thin (stub/degraded cells in platform table) — overlay and sensing depth lag macOS/Linux — but the packaging and shell binary are real, not out of scope.

Character count: All 8 shipped characters are now featured in the gallery (Buddy Bot, Black Mage, BMO, Cat, Jotaro Kujo, Nim, Timber Wolf, Trump) with consistent 96px display height and concise personality descriptions.

GIF sizes kept small: Smallest at 4.0 KB (Black Mage talk), largest at 27.2 KB (Cat walk, 8 frames). Transparent backgrounds and nearest-neighbor scaling preserved throughout.

— Cursor agent, on @omesser's behalf.

Open in Web Open in Cursor 

@omesser

omesser commented Aug 31, 2026

Copy link
Copy Markdown
Owner Author

let's hold off on that until critical parts of productization land

@cursor
cursor Bot force-pushed the cursor/polish-readme-landing-f8b9 branch 4 times, most recently from a0cc2b4 to a75fcb5 Compare September 2, 2026 03:47
- Feature Buddy Bot as the hero character throughout
- Add Buddy Bot logo, idle, and react GIFs
- Link to gh-pages demos (Buddy Cues, Chat Mockups)
- Restructure as concise OSS landing page: What/See/Interact/Characters/Run/Director/Platform/Developing
- Move developer content to docs/DEVELOPMENT.md: toolchains, hooks, verification, trace vars, Director env, local servers, Character Packages, pet importer, platform details
- Create scripts/generate-readme-gifs.py to generate GIFs from character frames
- Keep platform table honest (yes/degraded/stub)
- No claims of unshipped features (chat #17 linked as mockup only)
- Character gallery shows Buddy Bot (default), Nim, Black Mage with side-by-side GIFs
- README ~150 lines vs ~1100; developer detail preserved in DEVELOPMENT.md

Co-authored-by: Oded Messer <odedmesser@gmail.com>
@cursor
cursor Bot force-pushed the cursor/polish-readme-landing-f8b9 branch from a75fcb5 to 42ddffb Compare September 5, 2026 18:16
Move toolchains, hooks, verification, trace variables, Director env, local model servers, Character Packages, pet importer, and platform details from README to keep landing page concise.

Co-authored-by: Oded Messer <odedmesser@gmail.com>
@cursor
cursor Bot marked this pull request as ready for review September 5, 2026 18:21
cursoragent and others added 12 commits September 5, 2026 18:23
- Windows: Not out of v1 — ships NSIS installer, Spatial Layer is thin (stub/degraded) but packaging is real
- Link GitHub Releases for DMG / AppImage+deb / NSIS downloads
- Characters: 8 ship (Buddy Bot default + 7 more), not three
- Show buddy-bot-react.gif in Interact section
- Remove incorrect 'No packaged installers yet' claim

Co-authored-by: Oded Messer <odedmesser@gmail.com>
Click-through is infrastructure. The differentiator is Behaviors and
dialogue that follow the Character — Static or a Director Completer.
- Add all 8 characters: Buddy Bot, Black Mage, BMO, Cat, Jotaro Kujo, Nim, Timber Wolf, Trump
- Generate idle GIFs for all 8 at consistent 96px height
- New table structure: Character | Description | Personality
  - Character: equal-size GIF (HTML img height=96) + display name
  - Description: 1-2 sentences from manifest header (art origin, how it reads)
  - Personality: first paragraph from personality.txt + link to full file
- Drop Style column (not useful)
- Update scripts/generate-readme-gifs.py to generate all 8 character idles
- Update 'Switch characters' section to list all 8 options
- Order: Buddy Bot first (default), then alphabetical by display name

Co-authored-by: Oded Messer <odedmesser@gmail.com>
Replace idle loops in Characters table with more interesting animations:
- Buddy Bot: walk (motion stride)
- Black Mage: talk (incantation/cast)
- BMO: sing (signature variant)
- Cat: walk (motion)
- Jotaro Kujo: react (Stand aura showcase)
- Nim: sleep (matches personality)
- Timber Wolf: scan (TAC laser sweep, unique differentiator)
- Trump: talk (rally wave)

Updated generate-readme-gifs.py to read animation frames from character
manifests and generate showcase loops at consistent 96px height.

Deleted obsolete idle GIFs. buddy-bot-react.gif kept for Interact section.

Co-authored-by: Oded Messer <odedmesser@gmail.com>
…aracter writing to DEVELOPMENT

README.md:
- Restored ## Install (macOS/Linux/Windows: Release artifacts, AppImage/deb
  notes, NSIS/SmartScreen, fuse/tray/GStreamer details)
- Restored ## Running it (Linux deps/keyring, Static vs Completer, full
  provider examples OpenAI/Anthropic/xAI/Ollama, Settings precedence,
  ambient/DND, local model server table, probe-model)
- Merged previous thin Director (Optional) into comprehensive Running it
- Kept concise landing tone (Buddy Bot hero, Characters table, showcase GIFs)

DESIGN.md:
- Added ## State from main README (early status, issues link, alternatives.md,
  overlay/Engine/Director story, #17 chat surface status)
- Placed before "Shape of the product"

docs/DEVELOPMENT.md:
- Fixed broken "original README lines 668-826" reference
- Added ### Manual Verification Checklist (23-step human checklist for
  overlay, perches, click-through, fullscreen, multi-display)
- Added ### Writing a Character with personality instructions (three-part
  structure: who they are, fixations, sample lines)
- Added #### Universal rules (injected by character_prompt, not in files)
- Kept verify content (unit tests + verify-overlay.sh)

All operational detail restored from main, placed in proper homes.

Co-authored-by: Oded Messer <odedmesser@gmail.com>
pre-commit trailing-whitespace was failing CI on macOS/Ubuntu.
H1 and opening (priority 1-2):
- Display name: Desktop Buddy (repo stays ai-buddy)
- Lead with personality-driven AI behavior (personality.txt → Director picks
  Behaviors + dialogue, no chat window)
- Spatial (perches, gestures) is second beat
- Removed Harness/"real work" claim (unshipped)
- Opening now crisp: product sentence → walk GIF in 5 seconds

What It Does reorder (priority 3):
- First: Personality-driven behavior (character.txt, Director, Static/Completer)
- Then: Spatial (perches, reacts, stays out of way)
- Then: Idle life
- Dropped coding-agent framing

See It (priority 4):
- Keep Buddy Cues as featured demo
- Demoted Chat Mockups (moved to DESIGN.md with "speculative design" label)

Characters table (priority 5):
- Shortened Personality column to 1 short sentence each
- Kept link to full personality.txt

Thin ops surface (priority 6):
- README now 188 lines (down from 328, was 1100+ on main)
- Moved deep Completer details to DEVELOPMENT.md:
  * Provider details (Anthropic/xAI/Ollama/oMLX/llama.cpp/LM Studio)
  * Full Director env table
  * Keyring/secret store (Linux Secret Service, macOS Keychain ACL)
  * macOS signing identity essay
  * Accessibility/Screen Recording grants
  * Do Not Disturb details
  * xAI 403/mTLS details
  * Streaming philosophy
  * probe-model.sh details
  * Local server table with setup examples
  * Ambient wake behavior/exponential backoff
- Kept on README: short path to first success (download → open → optional
  Director in Settings, 1-2 provider examples)

Welcoming contributor path (priority 7):
- Added "Want to help?" blurb under Developing
- Links to open issues, DEVELOPMENT.md, alternatives.md
- No good first issues exist currently (checked via gh CLI)

Optional polish (priority 8):
- Linked docs/research/alternatives.md for comparison to other desktop pets
- Chat Mockups now labeled as "speculative design" under DESIGN.md link

Honest about unshipped: Harness, chat UI, Windows Spatial depth clearly marked.

Co-authored-by: Oded Messer <odedmesser@gmail.com>
Keep AppImage/deb, Wayland caveat, and install commands on the landing
page. Tray hosts, GStreamer cue audio, and AppImage fuse notes live under
Linux Dependencies in DEVELOPMENT.md.
Display-name rename belongs in #133; keep this README-only PR on ai-buddy.
Apply Ideator/Oded copy-edit: warmer open, tighter What It Does and
Interact, one-line See It, shorter Descriptions, unified repo-root
cargo run, collapsed Developing, polished Prior Art. Name stays ai-buddy.
@omesser
omesser merged commit 9e439b3 into main Sep 5, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants