Write the operator quickstart, including what an empty repository means

[iderex]

Depends on the release scope and on the address existing.

The quickstart is three steps and should stay three steps. Where the setting is,
what to paste, and what to expect.

The part worth more care is what comes after, because the failure modes of a
plugin repository are unusually quiet. A server that cannot reach the address
shows an empty list. A server that reaches it and cannot parse it shows an empty
list. A server whose version matches no entry in the catalogue shows an empty
list. Three different problems, one symptom, no error message, and an operator
with no way to tell them apart.

So the troubleshooting section is not an afterthought here, it is most of the
value. It should give the operator a way to distinguish those three from their
own machine, with the commands to do it, and it should say plainly what to check
first.

It also has to say what is normal. How long until a new plugin version appears
after it is released, so that somebody does not report a bug against a schedule
working as designed.

Done when

The quickstart is three steps, the troubleshooting section distinguishes
unreachable, unparseable and version-mismatch with a command for each, and the
expected delay between a plugin release and its appearance is stated.
Reading-decidable.

[iderex]

Three things stand in front of this, and each one is measurable rather than a
matter of wording.

The address the second step would print does not answer

curl -sS -o /dev/null -w "%{http_code}\n" https://flowfin.dev/
200
curl -sS -o /dev/null -w "%{http_code}\n" https://flowfin.dev/manifest.json
404

Run 2026-08-16 against origin/main at 65773d0. The host answers and the file
an operator would be told to paste the address of does not.

install-address-is-answered refuses a tracked file that prints an install
address before that address has been read as answering, the list that leg reads
is empty, and the leg runs on every push and pull request:

git grep -n 'var Answered' origin/main -- internal/address/address.go
origin/main:internal/address/address.go:54:var Answered = []string{}

grep -n 'install-address-is-answered' .github/workflows/gate.yml
203:      - run: go run . gate install-address-is-answered

So a quickstart carrying the address reds the gate, and a quickstart without it
is missing the step that says what to paste.

Nothing is placed at that address, because the run stops before placing anything

I ran the publish verb at 65773d0 on 2026-08-16:

go run . publish

2 of 12 declared plugin(s) resolved with something to publish.
  10 no releases

what each resolved plugin's releases came to:
  requests             1 version(s), 0 skipped, 0 stopping the run
  sso                  0 version(s), 3 skipped, 1 stopping the run
    stops   4.2.1-stable: no-descriptor: no asset is named sso-authentication_4.2.1.0.zip.meta.json, among sso-authentication_4.2.1.0.md5, sso-authentication_4.2.1.0.sha256, sso-authentication_4.2.1.0.zip

1 release(s) this run is trying to publish cannot be:
  sso 4.2.1-stable: no-descriptor: no asset is named sso-authentication_4.2.1.0.zip.meta.json, among sso-authentication_4.2.1.0.md5, sso-authentication_4.2.1.0.sha256, sso-authentication_4.2.1.0.zip
exit status 1

git status afterwards reported nothing under docs/, so no manifest was
placed. The newest finished release of that repository still ships no descriptor
beside the archive:

gh api 'repos/Flowfin/jellyfin-plugin-sso/releases?per_page=100' \
  --jq '.[] | select(.tag_name|test("^v?[0-9]+[.][0-9]+[.][0-9]+([.][0-9]+)?(-stable)?$")) | {tag: .tag_name, assets: [.assets[].name]}'
{"assets":["sso-authentication_4.2.1.0.md5","sso-authentication_4.2.1.0.sha256","sso-authentication_4.2.1.0.zip"],"tag":"4.2.1-stable"}
{"assets":["sso-authentication_4.2.0.0.md5","sso-authentication_4.2.0.0.sha256","sso-authentication_4.2.0.0.zip"],"tag":"4.2.0-stable"}
{"assets":["sso-authentication_4.1.1.0.md5","sso-authentication_4.1.1.0.sha256","sso-authentication_4.1.1.0.zip"],"tag":"4.1.1-stable"}
{"assets":["sso-authentication_4.1.0.0.md5","sso-authentication_4.1.0.0.sha256","sso-authentication_4.1.0.0.zip"],"tag":"v4.1.0.0"}

Run 2026-08-16. A published release is immutable, so what moves this is a new
finished release carrying a descriptor rather than a change here.

The last sentence of the done-condition has no value to state

It asks for the expected time between a plugin release and its appearance in the
catalogue. Nothing runs the verb that would place the file, so there is no
interval to write down:

grep -rn 'go run \. ' .github/workflows/ | grep -c publish
0

Run 2026-08-16 at 65773d0. #32 holds that route.

What this leaves

The troubleshooting section is where this issue puts most of the value, and each
of its three commands is a request against the address above. Against a 404 all
three answer alike, so they would not separate unreachable, unparseable and
version-mismatch, which is what they are for.

How many entries the first release carries is #65 and is open.