Adom Wiki

@@ -480,6 +480,31 @@ references that must survive renames (dashboards, configs, cross-page tooling). Old slugs also keep 301ing via aliases, but aliases are compat, not identity: they can be retired once redirect traffic flatlines. +## Linking a document inside a page (why your .md renders as raw text)++Two routes serve a repo file, and only one of them renders Markdown:++| Route | What it does | Use it for |+|---|---|---|+| `https://wiki.adom.inc/<owner>/<slug>/files/<path>` | The Files tab viewer. Renders `.md` (headings, tables, images) inside the page chrome; `<folder>/README.md` renders as a sub-page of the folder | Any document a human will read: `docs/plan.md`, `runbooks/oncall/README.md` |+| `https://wiki.adom.inc/<owner>/<slug>/render/<path>` | Raw file, no chrome, served as-is (`text/markdown` for `.md`) | Assets that must be served verbatim: a self-contained `.html` app, images, JSON, fonts referenced from a `readme.html` |++Do not hand anyone a `/render/<x>.md` URL and do not put one in a README. It opens as a wall of raw Markdown, and the page looks broken.++The rule is simpler than the routes: **from the root README, link a doc by its relative repo path** and let the renderer rewrite it.++```markdown+[Bridge vs MHS deep dive](docs/bridge-vs-mhs.md)     # renderer rewrites to /<owner>/<slug>/files/docs/bridge-vs-mhs.md+[Oncall runbook](runbooks/oncall/README.md)           # a folder README renders as its own sub-page+[Interactive gantt](https://wiki.adom.inc/<owner>/<slug>/render/gantt/index.html)   # a self-contained HTML app is the one case for /render/+```++Inside a doc that lives in a folder, reference images and other assets by their repo-root-relative path (`docs/img/x.png`), or by the absolute blob URL when the doc is a folder `README.md` (the `wiki-subreadme` skill has the table of what resolves where).++Verify by looking, not by curling: open the page in a browser and click the link, or read the rendered `<a href>`. A curl of a URL you constructed tests a URL the renderer never emits. From a container with no desktop, `adom-wiki auth login --json --next /<owner>/<slug>` mints a single-use login URL that headless Chrome can open, then screenshot the page and read the screenshot before reporting the doc as published.++Full mechanics: the `wiki-sub-readme` skill (a second Markdown doc under `docs/`, linked from an index in the README) and `wiki-subreadme` (a `README.md` inside a folder that renders as a sub-page).+ ## Decision table  | You want to | Do this |@@ -487,6 +512,7 @@ they can be retired once redirect traffic flatlines. | Read the docs | open the README on the page | | Browse / share source | push files to the repo, link the Files tab; do NOT attach a tarball | | Get a local copy of source | `adom-wiki repo clone <owner>/<slug>` |+| Attach a document to a page (plan, runbook, deep dive) | write `docs/<topic>.md` or `<folder>/README.md`, link it RELATIVELY from the README, push with `repo push`, verify in a browser; never link `/render/<x>.md` | | Distribute an installable (CLI + skills) | `adom-wiki pkg publish`, consumers `adom-wiki pkg install` | | Make a skill for your app | put it in the app's repo as `skills/<name>/SKILL.md`; do NOT create a separate skill package (that's only for reusable, cross-app skills) | | Keep a build/debug/test or publish skill out of installs | put it in `dev-skills/` or `publish-skills/`; it stays in source, never in the tarball |@@ -497,6 +523,7 @@ they can be retired once redirect traffic flatlines. ## Anti-patterns (these are why agents get lost)  - Reaching for `adompkg` (deprecated). Use `adom-wiki`.+- Linking a Markdown doc through `/render/<path>.md` (raw text) instead of a relative `docs/<x>.md` link that the renderer rewrites to the Files-tab viewer. Then reporting it as published without looking at the rendered page. - Pointing at a `*.adom.cloud` slug host or "wiki v1/v2". The host is wiki.adom.inc. - Shipping source as a `source.tar.gz` / `.bundle`. Push files instead. - Assuming `pkg install` drags down every page asset. It fetches one per-platform