Repository navigation
Description
Goal
Make https://omesser.github.io/fidget/ the place a first-time visitor lands: what Fidget is, what it looks like moving, and one click to install it. It is for people arriving from a link, a post or a search, who have never opened the repository. Contributors keep the README and the design pages.
Current state
- The root is the design-page directory,
docs/design/index.html, published by.github/workflows/pages.yml. Its own header says "This is a directory, not a landing page. The README is the project's front door." - ADR-0011 considered "A real landing page" and rejected it as "two front doors that drift". It also allows only two page classes: Generated from repository data at deploy, or Dated and frozen. A hand-written landing page is the Described class it forbids. This work needs that decision revisited first.
- The workflow is an allowlist. It copies six named pages and runs two generators (
make-character-gallery.py,make-expression-page.py). A guard then fails the build if_siteholds anything but.html,.css,.js,.pngor.svg. That rules outdocs/readme/hero.gif(docs(readme): Lead with a hero GIF of a throw, a perch, and a reply #1188) andbranding/banner.jpgtoday. - The build job runs on every pull request, and deploy runs only on
main.tests/design-pages.test.jschecks the index entries and the Dated class lines, so a "docs only" page change can turnnode --test tests/red. - Live URLs, checked with
curlon 2026-10-01:/,/index.html,/characters.html,/cues.html,/bubble.html,/chat.html,/chat-mockups.html,/expression.htmland/window-titles-hint.htmlall return 200. - Inbound links: README links
/cues.html,/chat-mockups.htmland/characters.html, anddocs/DEVELOPMENT.mdlinks/characters.html. Update in-repo forge URLs after rename to omesser/fidget #1086 links the root. docs: Add the interactive cue proposal for #277 #282, feat(shell): Cue each click on the Character, in sight and in sound #284, ci: Publish the design pages to GitHub Pages #285, test(shell): Verify the click cues on Linux X11, in sight and in sound #292 and spike: Decide what the published site should hold #293 linkomesser.github.io/ai-buddy/, which has returned 404 since the rename. Pages does not redirect a renamed project site, andomesser/omesser.github.iodoes not exist. - Downloads: GitHub marks a
tmp: #588 Open chat croprelease as Latest, so/releases/latestpoints at a screenshot and not at the app. The installable build is thev0.0.1-devprerelease, and its assets are still namedai-buddy_0.0.1-dev_*. - In flight: docs(readme): Lead with a hero GIF of a throw, a perch, and a reply #1188 (README hero GIF), build: Publish the Homebrew cask with each Release #1204 (Homebrew cask, pins
v0.0.1-dev) and docs(readme): Lead "Get It" with Settings, not env vars #1206 (README Get It). Demo mockup docs(design): Propose the landing page as a Dated mockup #1211 merged;/landing.htmlis published. No open PR yet for the Generated root page.
Design
Demo: #1211 (merged). It is a Dated mockup at docs/design/landing.html, published at /landing.html, and it uses the gallery's own published frames. It is laid out as a hero with the README headline, three platform buttons and the cask line, then Buddy Bot perched on a mock window and talking. Below that sit the four "What it does" cards, the Harness list, the eight packaged Fidgets walking, and three cards on adding your own. It ends with a footer linking the gallery and the design pages.
The shipped page is Generated, not hand-written. scripts/make-landing-page.py reads the headline, the feature bullets and the Harness names from README.md, the cast from characters/*/character.manifest, and the release tag from the cask. The README and the landing page then share one source and cannot drift, which answers ADR-0011's objection. The generator reuses the frames the gallery already copies into _site/characters/.
URL plan:
| URL | After this issue |
|---|---|
/ and /index.html |
The landing page |
/design.html |
The design-page directory. Every existing design page stays published and reachable from it, linked from the landing footer only, off the visitor path |
/characters.html, /cues.html, /bubble.html, /chat.html, /chat-mockups.html, /expression.html, /window-titles-hint.html |
Unchanged |
/landing.html |
Gone once the generated page owns the root. Nothing links a specific landing file, only / (decision 5) |
omesser.github.io/ai-buddy/* |
Stays 404. Losing the old slug is accepted (decision 4) |
Decisions
Answered by @omesser on 2026-10-01.
- Amend ADR-0011: yes. Task 2 goes ahead.
- Hero media: yes. Originally a shared GIF (not docs(readme): Lead with a hero GIF of a throw, a perch, and a reply #1188's). docs(readme): Lead with a hero GIF of a throw, a perch, and a reply #1188 put an MP4 on the README; feat(site): Play the README's demo video in the landing hero of the website #1254 made the landing hero play that same attachment URL instead of a GIF. Task 7 is done under that design.
- Delete the
tmp: #588release: no. A new, more relevant release is coming. Task 6 originally pinned via the cask; feat(site): Link each download button to its asset in the Latest release #1257 instead links Latest-release assets by suffix (and falls back to/releases/latestwhen an asset is missing). - Redirects for
omesser.github.io/ai-buddy/*: no. The old slug can go. - About website field: yes, set to
https://omesser.github.io/fidget/. Done — repo homepage is that URL. The root serves the landing page, so nothing should linklanding.htmlor any other specific file.
Tasks
Each item is one PR against main, in order. Every PR runs node --test tests/, and its Pages build job uploads the site artifact, which is the preview.
- 1.
docs(design): Propose the landing page as a Dated mockup. Done in docs(design): Propose the landing page as a Dated mockup #1211 @1b47786. Touchesdocs/design/landing.html,docs/design/index.html(entry),.github/workflows/pages.yml(onecp) andtests/design-pages.test.js. Published at/landing.html. Depends on nothing. - 2.
docs(adr): Let a Generated landing page own the site root. This adds a new ADR that amends ADR-0011 and leaves it live, becausepages.ymland both generators cite it. It touchesdocs/adr/00NN-*.mdand one pointer line in ADR-0011. Verified bynode --test tests/(adr-citations.test.js). Depends on decision 1. - 3.
ci(pages): Also publish the design index at /design.html. This one is additive, and the root stays as it is. It touches.github/workflows/pages.yml, and switches the demo's "Design pages" links todesign.html. Verified when the PR's Pages artifact holds bothindex.htmlanddesign.htmlwith identical bytes, and after deploycurl -I /design.htmlreturns 200. Depends on 2. - 4.
feat(site): Generate the landing page from README.md and characters/. This addsscripts/make-landing-page.py(stdlib,--outand--self-check, like the gallery). It turnsdocs/design/landing.htmlinto the page shell with a data block and publishes it at/landing.html. It also addstests/landing-page.test.js, which runs the generator into a temp dir and asserts that the README headline and all eight character names appear, and that a README with no H1 fails the build. The cast and its count come fromcharacters/, so a ninth character needs no page edit. Review on docs(design): Propose the landing page as a Dated mockup #1211 also asks for the walk loops to pause while the tab is hidden, with reduced-motion stills kept, and for the hero bubble to be tied to the sprite for assistive tech. Verified by that test,--self-checkin the workflow, and a screenshot of the PR artifact. Depends on 3. - 5.
feat(site): Serve the landing page at the site root. The generator writes_site/index.html, the design index moves to/design.htmlonly, and/landing.htmlis no longer published. It also adds<meta name="description">, Open Graph tags with a PNG image and a canonical link. The brand link points at the root, and "Design pages" appears in the footer only. It touches.github/workflows/pages.yml, the generator andtests/landing-page.test.js. Verified by the artifact check (root is the landing page, and every URL in the table resolves) and, after deploy, bycurlon each URL in the table. Depends on 4. - 6.
feat(site): Link each download button to its asset in the pinned release. Done in feat(site): Link each download button to its asset in the Latest release #1257 @8d1aa10with a changed design:pages.ymlreads Latest viagh release view --json tagName,assetsand the generator matches each button by asset suffix (_aarch64.dmg,-setup.exe,.AppImage); no cask / build: Publish the Homebrew cask with each Release #1204 dependency. Missing asset falls back to/releases/latest. A successful Release run refreshes the page viaworkflow_run. Verified by landing-page tests and live/linking the threev0.1.0Fidget_*assets (302). Depends on 5 (decision 3 path evolved). - 7.
feat(site): Show the hero GIF on the landing page. Done in feat(site): Play the README's demo video in the landing hero of the website #1254 @76a62d9with a changed design: the hero plays the README'suser-attachmentsdemo video (hotlinked<video>), not a GIF; no.mp4in the repo and the_siteguard is unchanged. Desk vignette remains the fallback. Verified by landing-page tests + Chrome CDP checks in the PR. Depends on 5 and the README media (decision 2 / docs(readme): Lead with a hero GIF of a throw, a perch, and a reply #1188 path evolved). - 8.
docs(readme): Point the README at the landing page. This adds one link under the banner and leaves Get It as is. It touchesREADME.md. Verified bynode --test tests/(readme-gifsonly —rename-to-fidgetwas removed on main; see hygiene after chore: Delete the one-time rename-to-fidget lever and its test #1233). Depends on 5.
Decision 5 (About website) is set. All numbered tasks 1–8 are done.
— Claude Code agent, on @omesser's behalf.
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone

Activity
omesser commentedon Oct 1, 2026
Hygiene after #1233: task 8’s verify line still names
rename-to-fidget, but that test (and the lever) were deleted onmain. When that task runs, verify withreadme-gifs(and the rest ofnode --test tests/) only — drop therename-to-fidgetmention.— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Oct 1, 2026
Hygiene after #1211 merged onto
main@1b47786:Done — task 1. The Dated mockup is on main:
docs/design/landing.html, design-index entry, Pagescpto/landing.html, and thedesign-pagestests. Live preview path:/landing.html(root still the design directory until later tasks).Still open — tasks 2–8 (ADR amend,
/design.html, Generated landing, root cutover, pinned download links, hero GIF, README link). No close.— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Oct 1, 2026
Tasks 2, 3, 4, 5 and 8 are in #1244, one commit per task:
/design.html, in feat(site): Serve a Generated landing page at the site root #1244scripts/make-landing-page.pyandtests/landing-page.test.js, in feat(site): Serve a Generated landing page at the site root #1244meta description, Open Graph and canonical, in feat(site): Serve a Generated landing page at the site root #1244Still open:
v0.0.1-devassets. The Homebrew line is left off until the cask is onmain.— Claude Code agent, on @omesser's behalf.
omesser commentedon Oct 1, 2026
Hygiene after #1244 merged onto
main@ad368d5:Done — tasks 2, 3, 4, 5, and 8 (checkboxes updated in the issue body).
On
mainnow:/design.htmlis the design directory (docs/design/design.html); Pages no longer publishes/landing.htmlscripts/make-landing-page.py+tests/landing-page.test.jsgenerate the root page from README + manifests//index.htmlis the Generated landing page (meta description, Open Graph, canonical)Still open — leave this issue open:
v0.0.1-dev; Homebrew line waits on the cask onmain/ build: Publish the Homebrew cask with each Release #1204).gifin the Pages guard)https://omesser.github.io/fidget/once Pages has deployed this merge (repo setting, outside PRs)No close.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Oct 2, 2026
Hygiene after #1188 merged onto
main@1ad038c:README hero shipped — the README now embeds a throw/perch/reply take as a
user-attachmentsMP4 (not a repo GIF).docs/readme/hero.gifis gone;scripts/scenarios/hero-gif.shis on main.Does not clear task 7 — decision 2 still stands: landing-page hero waits on a separate GIF recording that the README and generator can share as a file. This merge also does not extend the Pages
_siteguard with.gif.Still open — leave this issue open: task 6 (pinned release assets), task 7 (hero GIF + guard), decision 5 (About website once Pages is current).
No close.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Oct 2, 2026
Task 7 is in #1254, with a changed design. The hero plays the MP4 the README already embeds, hotlinked from its
user-attachmentsURL. There is no GIF and no.mp4in the repo, and the_siteextension check is unchanged. Without the video the hero is the sprite desk scene.— Claude Code agent, on @omesser's behalf.
omesser commentedon Oct 2, 2026
Hygiene after #1254 merged onto
main@76a62d9:Done — task 7 (checkbox + decision 2 note updated in the issue body), with the PR’s changed design rather than a GIF:
user-attachmentsURL as a muted looping<video>(hotlinked; no.mp4in the repo)_siteextension guard unchanged (no.gif/.mp4publish)tests/landing-page.test.jscases plus the PR’s Chrome CDP checksStill open — leave this issue open:
https://omesser.github.io/fidget/(repo setting; task 5 already deployed)PR open question left as product follow-up, not tracked here: whether every visitor should get
controlsfor WCAG 2.2.2 (autoplay loop without a pause control).No close.
— Cursor agent (Coder), on @omesser's behalf.
omesser commentedon Oct 2, 2026
Task 6 is in #1257, with a changed design. The Pages build reads the Latest release with
gh release viewand matches each button to its asset by suffix. It no longer reads the cask tag, so it does not depend on #1204. A button with no matching asset links/releases/latest. The page refreshes when a Release run succeeds, so publishing a release needs no commit.— Claude Code agent, on @omesser's behalf.
omesser commentedon Oct 2, 2026
Hygiene after #1257 merged onto
main@8d1aa10:Done — task 6 (checkbox + decision 3 note updated in the issue body), with the PR’s changed design rather than a cask-pinned tag:
pages.ymlreads Latest withgh release view --json tagName,assetsand passes it tomake-landing-page.py --release/releases/latestworkflow_run(no commit needed)https://omesser.github.io/fidget/already links the threev0.1.0Fidget_*assets; each returns 302 to the download CDNAlso done — decision 5: repo About website is already
https://omesser.github.io/fidget/.All tasks 1–8 and decisions tracked here are complete → closing as completed. #1204 stays open on its own (Homebrew cask publish).
— Cursor agent (Coder), on @omesser's behalf.