skill

Adom Wiki

Public Made by Adom

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

wikiclipackagesregistrypublishingguide
Overview Files Skills Discover Packages Releases Dependencies Issues8 Breadcrumbs Pull Requests Activity
Closed general

Serve page-repo files at their natural path, not only under render/

Ray · 2mo ago ·closed by Colby Knox

Request

Serve page-repo files directly at /<owner>/<slug>/<path>, so a file that is already public can be fetched at its natural URL:

https://wiki.adom.inc/adom/adom-kicad-library/pcm/repository.json

instead of the current:

https://wiki.adom.inc/adom/adom-kicad-library/render/pcm/repository.json

Keep render/ working as an alias. This is additive, nothing needs to break.

Why it matters

We are using the wiki as the public distribution host for a KiCad PCM library (adom/adom-kicad-library). KiCad's Plugin and Content Manager takes a repository URL, and the user pastes it into a settings dialog where it is stored permanently and polled for updates.

That makes this URL a long-lived public contract, not a link someone clicks once. Two problems with routing it through render/:

  1. It reads as an implementation detail. render describes what the wiki does internally (serve a page file without chrome). To someone pasting it into KiCad it is noise, and the first question we got was "why does the URL have render in it?"

  2. It is a stability risk we cannot manage. Every subscriber bakes the string into their KiCad config. If render/ is ever renamed or restructured, every install breaks at once, and PCM's failure mode is an opaque "Unable to parse packages metadata" dialog with no hint that the URL moved. A purpose-named path signals "this is a supported public surface" in a way that render/ does not.

The same argument applies to anyone else using the wiki to host a feed, a manifest, a .well-known file, or anything else a machine polls on a schedule.

The routing problem, and a suggested resolution

/<owner>/<slug>/<path> collides with the reserved page tabs. Confirmed live on adom/adom-kicad-library, these all return 200 HTML today:

/files  /issues  /releases  /packages  /skills

while unknown paths 404:

/pcm  /screenshots  /settings

So there is room to serve files at unreserved paths. The collision is real though, and skills/ is not hypothetical: it is a standard directory in page repos under the three-tier skill layout, so /<owner>/<slug>/skills/foo.md would be ambiguous the day someone tries it.

Suggested precedence:

  1. Reserved tab names win. /files, /issues, /releases, /packages, /skills keep rendering their tabs.
  2. Anything else resolves against the page repo and serves the file, same bytes, same MIME type, same visibility rules as render/ uses now.
  3. render/<path> stays as the unambiguous escape hatch, and remains the documented way to reach a file whose path collides with a reserved name.

If reserving the whole namespace is unappealing, a shorter purpose-named prefix would also solve our problem, for example /<owner>/<slug>/raw/<path>. Our preference is the bare path, but a stable, clearly-public prefix is the part that actually matters.

Current behaviour, for reference

Both of these work today and return identical bytes:

/adom/adom-kicad-library/render/pcm/repository.json               200 application/json
/api/pages/adom/adom-kicad-library/files/pcm/repository.json      200 application/json

/adom/adom-kicad-library/files/pcm/repository.json returns the HTML file browser rather than the file, and raw/ and blob/ do not exist.

Happy to test whatever lands against a real KiCad client, since we have the end-to-end path set up already.

1 Reply

Colby Knox · 2mo ago

Shipped, live on prod. Your preferred shape, the bare path:

https://wiki.adom.inc/adom/adom-kicad-library/pcm/repository.json

serves the file now, byte- and header-identical to the render/ URL, which stays as a permanent alias.

How the collision is resolved, which matches your suggested precedence with one deliberate strengthening:

  1. Reserved names win, including their whole subtrees. /files, /issues, /releases, /packages, /skills, /prs, /commits and the other tab routes keep rendering their tabs, and paths under them (/skills/foo.md) stay 404 as file paths even when the repo contains that file. You called out exactly this ambiguity for skills/; holding the subtree means a tab can grow sub-routes later without ever shadowing a published file URL, which matters precisely because these URLs get baked into client configs. The reserved set also pre-claims a few likely future names (settings, edit, raw, pulls) for the same reason.
  2. Everything else resolves against the page repo: same bytes, same MIME, same visibility gating, same security headers (HTML sandboxed, SVG no-script, nosniff) as render/. It is literally the same handler.
  3. render/<path> remains the documented escape hatch that reaches any file, including ones under a reserved name.

Regression-tested for byte/MIME parity with render/, reserved-subtree 404s, private-page gating, and the HTML/SVG security headers, and verified live against your exact URL. Since your KiCad e2e is already set up, please paste the bare URL into a real PCM client when you get a chance; if anything is off, reopen this and it goes to the top of the pile.

One note for the docs you hand users: prefer the bare path in anything new, and treat render/ as the compatibility spelling. Both are permanent.

Log in to reply.