~bigbes/sourcehut-root: 189ae48e

skills(custom-service): rewrite from the services we actually built

The page was written by reading upstream alone, before the nine Go services
on this instance existed. Three of its central claims had since gone false,
and each of them sent a reader the long way round:

- "core-go is purely API-side, there is no shared web chrome in Go — expect
  to reimplement the nav in ~30 lines." All eight web services import
  sr-ht-ecore, which ships the nav, login box, env banner, error page, CSRF
  guard and asset handler. The nav is a constructor call and one template
  line.
- "Add a config section with api-origin and SIGHUP api.sr.ht, and your types
  join the unified API." Upstream's gateway is dead measurably, not by
  misconfiguration: thistle was deleted, api.sr.ht is NXDOMAIN, no service
  answers _service, and every pair of upstream schemas fails to merge on
  User. sourcehut-federation is what runs.
- "The cookie gives identity; API writes need a meta OAuth token." There are
  five credential planes. The machine credential is a tokens.sr.ht working
  token; the cookie plus a same-origin check is browser-mutation auth; and
  no service here performs the meta OAuth client flow at all.

The config chapter carried its own errors — keys tabled that nothing in the
family reads, bind-address listed as an invented spelling when it is the
canonical one, [webhooks] private-key marked optional when InitCrypto exits
without it and it also derives the instance bearer HMAC key.

Split into a routing front page plus ten references: anatomy, ecore, auth,
chrome, federation, caching, config, deploy, pitfalls, and upstream — the
last keeping the upstream mechanisms that are still true, now stated as
background rather than as the recipe.

Citations gain a second root. `family::` reaches this instance's own repos,
`mirror::` the upstream documentation mirror; the justfile substitutes both
at install time, so a citation can no longer silently mean the tree that
does not get built.

Eugene Blikh <bigbes@gmail.com> — 2026-08-17 20:35:41 UTC

Commit 189ae48e8450259094940687aafb2c760774d492 — view raw patch

Parent(s): 3c5d8849

12 changed file(s)

File	Status	+	−
justfile	M	+10	-2
skills/sourcehut-custom-service/SKILL.md	M	+87	-225
skills/sourcehut-custom-service/references/anatomy.md	A	+513
skills/sourcehut-custom-service/references/auth.md	A	+567
skills/sourcehut-custom-service/references/caching.md	A	+560
skills/sourcehut-custom-service/references/chrome.md	A	+504
skills/sourcehut-custom-service/references/config.md	A	+479
skills/sourcehut-custom-service/references/deploy.md	A	+625
skills/sourcehut-custom-service/references/ecore.md	A	+724
skills/sourcehut-custom-service/references/federation.md	A	+569
skills/sourcehut-custom-service/references/pitfalls.md	A	+639
skills/sourcehut-custom-service/references/upstream.md	A	+149