Repository navigation
docs: Polish README into a landing page and new-user guide - #135
Merged
Merged
Conversation
Owner
Author
|
let's hold off on that until critical parts of productization land |
cursor
Bot
force-pushed
the
cursor/polish-readme-landing-f8b9
branch
4 times, most recently
from
September 2, 2026 03:47
a0cc2b4 to
a75fcb5
Compare
This was referenced Sep 3, 2026
- 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
Bot
force-pushed
the
cursor/polish-readme-landing-f8b9
branch
from
September 5, 2026 18:16
a75fcb5 to
42ddffb
Compare
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>
- 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.
4 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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+):
ai-buddy)personality.txt→ Director picks Behaviors + dialogue, no chat window required. Spatial (perches, gestures) is the second beat.personality.txtDESIGN.md — State section added:
docs/DEVELOPMENT.md — Developer content comprehensive:
probe-model.sh)character_prompt, not in personality files)verify-overlay.sh, manual checklistAI_BUDDY_CHARACTERSenvGenerated 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 fpsdocs/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 fpsdocs/readme/bmo-sing.gif(10.4 KB) — 4-frame signature variant, 3 fpsdocs/readme/cat-walk.gif(27.2 KB) — 8-frame motion, 8 fpsdocs/readme/jotaro-kujo-react.gif(21.7 KB) — 8-frame Stand aura showcase, 7 fpsdocs/readme/nim-sleep.gif(6.3 KB) — 4-frame sleep (matches personality), 3 fpsdocs/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 fpsAll GIFs: transparent backgrounds, nearest-neighbor scaling, consistent 96px height, looping enabled.
How to verify
Automated:
[animations.*]frames).github/workflows/tests.ymlscripts/generate-readme-gifs.pyruns cleanly with PillowManual:
Visual verification (showcase GIFs in this PR):
Notes
Display name: "Desktop Buddy" is the user-facing product name; repository stays
ai-buddyfor URL/git stability.Personality-driven AI as differentiator: Each character's
personality.txtdrives 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_CHARACTERinsrc-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:
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.