#50: the README needed to be a landing page for users, with
screenshots, and the technical documentation needed to live somewhere
else.
It was two documents in one. It opened on a feature list, then spent its
second half on Go versions, WebKitGTK packages and make targets — and
neither reader was served by the other's half.
It was also wrong. The install table named a yellowjacket-darwin-universal.app.zip and a yellowjacket-windows-amd64.exe that nothing has ever produced, and the
header claimed Linux, macOS and Windows while never mentioning
Android, which is the one platform with a published, credential-free,
self-updating channel. So this is a correctness pass as much as a
friendliness one.
What changed
Commit
Issue
docs: split the README into a landing page and CONTRIBUTING
README.md answers a user's questions only: what the app is, three
screenshots, the four formats, one install section per channel naming
what is actually published (Linux tarball / the Arch registry, the
Android APK and its Obtainium-pollable URL, the Homebrew tap that builds
on the user's own Mac, and Windows explicitly not published and why),
first run, where the data lives, and pointers out. The 0.0.1-after-1.x
note is linked to packaging/homebrew/README.md and docs/android-release.md rather than repeated, per the issue's
direction — a copy is a second thing to keep true.
CONTRIBUTING.md is new and takes the technical half: prerequisites,
the system libraries, the build and codegen commands, which verification
tier a change demands, the harness, the tracker workflow, the commit
grammar and the style rules.
CLAUDE.md gains one paragraph naming the split and is otherwise
untouched. It was already the deep reference both of the others point
at, and stays the only one of the three that explains why a shape is
what it is.
docs/images/{library,album,home}.png — 1440x900, captured from the
seeded fixture library (make sandbox-seed NAME=default → make dev-headless SEED=default), so anyone can retake them and they contain
nobody's real library.
Verification
This branch was claimed and largely written by an earlier scheduled run
that was killed before it committed anything. This run rebased it onto
current main (20 commits had landed) and read it as a reviewer rather
than as its author. Two things in it were wrong against the code:
The smart-playlist sentence offered "when you added it" as a rule
field. fieldMap in backend/smartplaylist/smartplaylist.go has no
such field and never has — it is days_since_played, so the README
now says "how long since you played it".
CONTRIBUTING.md described make css-check as one pass. The target
runs two (check-css-literals.mjs and check-css-nesting.mjs);
the first is what catches a backtick inside a css literal.
Tiers run:
The screenshot tier, which is the one this change actually rests
on. Re-seeded and re-captured all three views against current main
at the same 1440x900 .playwright/cli.config.json gives. Home and the
album page come back pixel-equivalent to the committed images, and cmd/gentestdata/spec.go has not moved since they were taken, so they
remain reproducible. Each of the three was also read against the
sentence next to it: the track list one does show a playing row, the
album one does show two discs and a running transport, the home one does show the shelves.
make skill-check — 47 documented targets, all present.
Links and anchors, by hand. Every relative link in both files
resolves against the tree; both deep anchors
(packaging/homebrew/README.md#upgrading-from-1x-needs-a-reinstall-once, docs/android-release.md#the-1x-installs-cannot-be-upgraded-to-00x)
match the headings they name; all 21 make targets CONTRIBUTING.md
mentions exist; the release asset name is the one desktop-assets.yml builds; the APK URL is the one android-apk.yml publishes to.
make commit-check (commit-msg hook) — well-formed.
Not run, and why: no Go, no .sql, no .templ, no bound signature, no
CSS and no frontend source, so make lint, make test, make generate, make bindings, make ui-test and make css-check have
nothing to say about this diff. No user-visible flow changed, so make e2e was not run.
Deliberately not done
The logo is #22 and stays there.#50 records a hard dependency on it
and says it is "blocked-ish on the logo issue for the header image" —
but screenshots of the running app do not need a mark, and the rest of
the issue is the whole of the diff. The consequence for whoever merges: Gitea will decline to auto-close #50 from the Closes footer while #22 is open, so it will need closing by hand if you are happy that the
header image is the only thing outstanding.
README.md keeps a Windows column in its data-locations table even
though Windows is unpublished, because you can still build it yourself
and the path is then the true one.
Filed, not fixed here
#220 — scripts/skill-check.sh scans .pi/ and CLAUDE.md but not README.md or CONTRIBUTING.md, which is now where a contributor
reads a make target from. All 21 are correct today and nothing would
say so if one were renamed. Changing what a CI gate scans is a
separate change from moving prose between two files.
## What the issue was
#50: the README needed to be a landing page for *users*, with
screenshots, and the technical documentation needed to live somewhere
else.
It was two documents in one. It opened on a feature list, then spent its
second half on Go versions, WebKitGTK packages and `make` targets — and
neither reader was served by the other's half.
It was also wrong. The install table named a
`yellowjacket-darwin-universal.app.zip` and a
`yellowjacket-windows-amd64.exe` that nothing has ever produced, and the
header claimed **Linux, macOS and Windows** while never mentioning
Android, which is the one platform with a published, credential-free,
self-updating channel. So this is a correctness pass as much as a
friendliness one.
## What changed
| Commit | Issue |
|---|---|
| `docs: split the README into a landing page and CONTRIBUTING` | #50 |
**`README.md`** answers a user's questions only: what the app is, three
screenshots, the four formats, one install section per channel naming
what is *actually* published (Linux tarball / the Arch registry, the
Android APK and its Obtainium-pollable URL, the Homebrew tap that builds
on the user's own Mac, and Windows explicitly not published and why),
first run, where the data lives, and pointers out. The `0.0.1`-after-`1.x`
note is **linked** to `packaging/homebrew/README.md` and
`docs/android-release.md` rather than repeated, per the issue's
direction — a copy is a second thing to keep true.
**`CONTRIBUTING.md`** is new and takes the technical half: prerequisites,
the system libraries, the build and codegen commands, which verification
tier a change demands, the harness, the tracker workflow, the commit
grammar and the style rules.
**`CLAUDE.md`** gains one paragraph naming the split and is otherwise
untouched. It was already the deep reference both of the others point
at, and stays the only one of the three that explains *why* a shape is
what it is.
**`docs/images/{library,album,home}.png`** — 1440x900, captured from the
seeded fixture library (`make sandbox-seed NAME=default` → `make
dev-headless SEED=default`), so anyone can retake them and they contain
nobody's real library.
## Verification
This branch was claimed and largely written by an earlier scheduled run
that was killed before it committed anything. This run rebased it onto
current `main` (20 commits had landed) and read it as a reviewer rather
than as its author. **Two things in it were wrong against the code:**
- The smart-playlist sentence offered *"when you added it"* as a rule
field. `fieldMap` in `backend/smartplaylist/smartplaylist.go` has no
such field and never has — it is `days_since_played`, so the README
now says "how long since you played it".
- `CONTRIBUTING.md` described `make css-check` as one pass. The target
runs **two** (`check-css-literals.mjs` and `check-css-nesting.mjs`);
the first is what catches a backtick inside a `css` literal.
Tiers run:
- **The screenshot tier**, which is the one this change actually rests
on. Re-seeded and re-captured all three views against current `main`
at the same 1440x900 `.playwright/cli.config.json` gives. Home and the
album page come back **pixel-equivalent** to the committed images, and
`cmd/gentestdata/spec.go` has not moved since they were taken, so they
remain reproducible. Each of the three was also read against the
sentence next to it: the track list one *does* show a playing row, the
album one *does* show two discs and a running transport, the home one
*does* show the shelves.
- **`make skill-check`** — 47 documented targets, all present.
- **Links and anchors, by hand.** Every relative link in both files
resolves against the tree; both deep anchors
(`packaging/homebrew/README.md#upgrading-from-1x-needs-a-reinstall-once`,
`docs/android-release.md#the-1x-installs-cannot-be-upgraded-to-00x`)
match the headings they name; all 21 `make` targets `CONTRIBUTING.md`
mentions exist; the release asset name is the one
`desktop-assets.yml` builds; the APK URL is the one
`android-apk.yml` publishes to.
- **`make commit-check`** (commit-msg hook) — well-formed.
Not run, and why: no Go, no `.sql`, no `.templ`, no bound signature, no
CSS and no frontend source, so `make lint`, `make test`, `make
generate`, `make bindings`, `make ui-test` and `make css-check` have
nothing to say about this diff. No user-visible flow changed, so `make
e2e` was not run.
## Deliberately not done
**The logo is #22 and stays there.** #50 records a hard dependency on it
and says it is "blocked-ish on the logo issue for the header image" —
but screenshots of the running app do not need a mark, and the rest of
the issue is the whole of the diff. The consequence for whoever merges:
**Gitea will decline to auto-close #50 from the `Closes` footer while
#22 is open**, so it will need closing by hand if you are happy that the
header image is the only thing outstanding.
`README.md` keeps a Windows column in its data-locations table even
though Windows is unpublished, because you can still build it yourself
and the path is then the true one.
## Filed, not fixed here
- #220 — `scripts/skill-check.sh` scans `.pi/` and `CLAUDE.md` but not
`README.md` or `CONTRIBUTING.md`, which is now where a contributor
reads a `make` target from. All 21 are correct today and nothing would
say so if one were renamed. Changing what a CI gate scans is a
separate change from moving prose between two files.
Closes #50
The README was two documents in one, and neither reader was served by
the other's half. It opened on a feature list, then spent its second
half on Go versions, WebKitGTK packages and `make` targets — while its
install table named a `darwin-universal.app.zip` and a
`windows-amd64.exe` that nothing has ever produced, and its header
claimed Windows and never mentioned Android, which is the one platform
with a published, self-updating channel.
So this is a correctness pass as much as a friendliness one. The README
now answers a user's questions only: what the app is, three screenshots
from the seeded fixture library so anyone can retake them, the four
formats, one install section per channel that names what is actually
published, first run, where the data lives, and pointers out. The
version-restart note is linked to the two documents that own it rather
than copied, because a copy is a second thing to keep true.
CONTRIBUTING.md takes the technical half: prerequisites, the system
libraries, the build and codegen commands, which verification tier a
change demands, the tracker workflow, the commit grammar and the style
rules. CLAUDE.md is unchanged apart from one paragraph naming the split
— it was already the deep reference both of the others point at, and
stays the only one of the three that explains why a shape is what it is.
Closes#50
e2e (job 29325) — success, all steps, including E2E — webkit. Checked per-step rather than trusting the job conclusion, because that is the step CLAUDE.md records as having silently skipped for two sessions behind a chromium failure. Only App log on failure and Upload traces and screenshots skipped, which is what they are conditioned to do on a pass.
Nothing in this diff can move either job — it is four Markdown files and three PNGs — so this is a check that the branch is mergeable rather than evidence about the change. The evidence for the change itself is in the Verification section above: the screenshots re-captured against this main, the links and anchors resolved by hand, and make skill-check.
Not merging, per the run's instructions.
**CI green**, run [17994](https://git.ljones.me/yonlu/yellowjacket/actions/runs/17994), both required jobs:
- **`check`** (job 29324) — success, all 14 steps: commit messages, lint, test, frontend typecheck, CSS literals, component/store suite, bindings, documented `make` targets.
- **`e2e`** (job 29325) — success, all steps, **including `E2E — webkit`**. Checked per-step rather than trusting the job conclusion, because that is the step `CLAUDE.md` records as having silently skipped for two sessions behind a chromium failure. Only `App log on failure` and `Upload traces and screenshots` skipped, which is what they are conditioned to do on a pass.
Nothing in this diff can move either job — it is four Markdown files and three PNGs — so this is a check that the branch is mergeable rather than evidence about the change. The evidence for the change itself is in the Verification section above: the screenshots re-captured against this `main`, the links and anchors resolved by hand, and `make skill-check`.
Not merging, per the run's instructions.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
What the issue was
#50: the README needed to be a landing page for users, with
screenshots, and the technical documentation needed to live somewhere
else.
It was two documents in one. It opened on a feature list, then spent its
second half on Go versions, WebKitGTK packages and
maketargets — andneither reader was served by the other's half.
It was also wrong. The install table named a
yellowjacket-darwin-universal.app.zipand ayellowjacket-windows-amd64.exethat nothing has ever produced, and theheader claimed Linux, macOS and Windows while never mentioning
Android, which is the one platform with a published, credential-free,
self-updating channel. So this is a correctness pass as much as a
friendliness one.
What changed
docs: split the README into a landing page and CONTRIBUTINGREADME.mdanswers a user's questions only: what the app is, threescreenshots, the four formats, one install section per channel naming
what is actually published (Linux tarball / the Arch registry, the
Android APK and its Obtainium-pollable URL, the Homebrew tap that builds
on the user's own Mac, and Windows explicitly not published and why),
first run, where the data lives, and pointers out. The
0.0.1-after-1.xnote is linked to
packaging/homebrew/README.mdanddocs/android-release.mdrather than repeated, per the issue'sdirection — a copy is a second thing to keep true.
CONTRIBUTING.mdis new and takes the technical half: prerequisites,the system libraries, the build and codegen commands, which verification
tier a change demands, the harness, the tracker workflow, the commit
grammar and the style rules.
CLAUDE.mdgains one paragraph naming the split and is otherwiseuntouched. It was already the deep reference both of the others point
at, and stays the only one of the three that explains why a shape is
what it is.
docs/images/{library,album,home}.png— 1440x900, captured from theseeded fixture library (
make sandbox-seed NAME=default→make dev-headless SEED=default), so anyone can retake them and they containnobody's real library.
Verification
This branch was claimed and largely written by an earlier scheduled run
that was killed before it committed anything. This run rebased it onto
current
main(20 commits had landed) and read it as a reviewer ratherthan as its author. Two things in it were wrong against the code:
field.
fieldMapinbackend/smartplaylist/smartplaylist.gohas nosuch field and never has — it is
days_since_played, so the READMEnow says "how long since you played it".
CONTRIBUTING.mddescribedmake css-checkas one pass. The targetruns two (
check-css-literals.mjsandcheck-css-nesting.mjs);the first is what catches a backtick inside a
cssliteral.Tiers run:
on. Re-seeded and re-captured all three views against current
mainat the same 1440x900
.playwright/cli.config.jsongives. Home and thealbum page come back pixel-equivalent to the committed images, and
cmd/gentestdata/spec.gohas not moved since they were taken, so theyremain reproducible. Each of the three was also read against the
sentence next to it: the track list one does show a playing row, the
album one does show two discs and a running transport, the home one
does show the shelves.
make skill-check— 47 documented targets, all present.resolves against the tree; both deep anchors
(
packaging/homebrew/README.md#upgrading-from-1x-needs-a-reinstall-once,docs/android-release.md#the-1x-installs-cannot-be-upgraded-to-00x)match the headings they name; all 21
maketargetsCONTRIBUTING.mdmentions exist; the release asset name is the one
desktop-assets.ymlbuilds; the APK URL is the oneandroid-apk.ymlpublishes to.make commit-check(commit-msg hook) — well-formed.Not run, and why: no Go, no
.sql, no.templ, no bound signature, noCSS and no frontend source, so
make lint,make test,make generate,make bindings,make ui-testandmake css-checkhavenothing to say about this diff. No user-visible flow changed, so
make e2ewas not run.Deliberately not done
The logo is #22 and stays there. #50 records a hard dependency on it
and says it is "blocked-ish on the logo issue for the header image" —
but screenshots of the running app do not need a mark, and the rest of
the issue is the whole of the diff. The consequence for whoever merges:
Gitea will decline to auto-close #50 from the
Closesfooter while#22 is open, so it will need closing by hand if you are happy that the
header image is the only thing outstanding.
README.mdkeeps a Windows column in its data-locations table eventhough Windows is unpublished, because you can still build it yourself
and the path is then the true one.
Filed, not fixed here
scripts/skill-check.shscans.pi/andCLAUDE.mdbut notREADME.mdorCONTRIBUTING.md, which is now where a contributorreads a
maketarget from. All 21 are correct today and nothing wouldsay so if one were renamed. Changing what a CI gate scans is a
separate change from moving prose between two files.
Closes #50
CI green, run 17994, both required jobs:
check(job 29324) — success, all 14 steps: commit messages, lint, test, frontend typecheck, CSS literals, component/store suite, bindings, documentedmaketargets.e2e(job 29325) — success, all steps, includingE2E — webkit. Checked per-step rather than trusting the job conclusion, because that is the stepCLAUDE.mdrecords as having silently skipped for two sessions behind a chromium failure. OnlyApp log on failureandUpload traces and screenshotsskipped, which is what they are conditioned to do on a pass.Nothing in this diff can move either job — it is four Markdown files and three PNGs — so this is a check that the branch is mergeable rather than evidence about the change. The evidence for the change itself is in the Verification section above: the screenshots re-captured against this
main, the links and anchors resolved by hand, andmake skill-check.Not merging, per the run's instructions.