Adom Wiki

--- a/SKILL.md+++ b/SKILL.md@@ -1,506 +1,534 @@⋯ 479 unchanged lines ⋯ 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 |⋯ 1 unchanged line ⋯ | 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 |⋯ 4 unchanged lines ⋯ ## 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⋯ 1 unchanged line ⋯ - Re-supplying title/hero/body to bump a version. Metadata lives in package.json. - Dumping build/debug/publish skills into `skills/` so they ship to every install.   Put them in `dev-skills/` or `publish-skills/`, publish auto-keeps them out.+