Adom Wiki Skill Pack

@@ -0,0 +1,134 @@+---+name: wiki-sub-readme+description: >-+  Make a SUB-README on an Adom Wiki page: a second Markdown doc in the page's repo that fully+  explains ONE feature-set, linked from a short section in the main README. Use when a page has+  several distinct features and one README would bloat, so the main README becomes an index and each+  sub-readme is the deep dive. Covers the hard-won mechanics that are NOT obvious and cost real time:+  publish sub-readmes with `adom-wiki repo push --files` (NOT the files blob API, which does not+  update the git page repo the Files tab reads); reference other docs with RELATIVE links+  (docs/x.md, the renderer rewrites them, absolute URLs are wrong); reference images by their+  repo-root-relative path docs/img/x.png (the files-viewer prepends files/ to the ref as written);+  and VERIFY by looking at the rendered page, never by curling a URL you constructed. Trigger words:+  sub-readme, sub readme, subreadme, make a sub-readme, second readme, feature guide, feature guides,+  multi-page wiki docs, split my readme, link a doc from the readme, docs folder wiki page, add a+  page to my wiki page, deep-dive doc, wiki sub page, my readme is too long.+---++# Sub-READMEs on the Adom Wiki++A **sub-readme** is a second Markdown doc in a wiki page's own git repo that fully documents ONE+feature-set, with a short section in the **main README** that links to it. The main README stays the+**index**; each sub-readme is the **deep dive**. Use this when a page has several distinct features+and cramming them all into one README makes it a wall.++## The layout++```+<page repo>/+  README.md              # the Overview. Holds a "Feature guides" index table linking each sub-readme+  docs/+    aps-cloud-search.md  # one sub-readme per feature-set+    schematics.md+    3d-viewer.md+    img/+      thing-1.png        # screenshots the sub-readmes reference+```++In the main README, one index section:++```markdown+## Feature guides++| guide | what it covers |+|---|---|+| [APS cloud search](docs/aps-cloud-search.md) | Find any file in ~2s. Setup, auth, limits. |+| [Schematics](docs/schematics.md) | Open the project, drive the editor, import EAGLE. |+```++That is it structurally. The rest of this skill is the mechanics that are NOT obvious and WILL waste+your time if you guess.++## ⛔ Publish with `repo push`, NOT the files blob API++A wiki page has **two storage layers**, and they are not the same store:++- the **files blob store** (`POST /api/v1/pages/<slug>/files`), and+- the **git page repo** (what the **Files tab renders**, and what `adom-wiki repo` reads/writes).++`curl POST .../files` returns 200 but may **not update the git page repo**, so your sub-readme keeps+serving the OLD version even though the upload "succeeded". Always publish sub-readmes and their+images through the git repo:++```bash+adom-wiki repo push adom/<slug> \+  --files README.md docs/aps-cloud-search.md docs/schematics.md docs/img/thing-1.png \+  -m "add feature sub-readmes"+```++Verify it landed:++```bash+adom-wiki repo show adom/<slug> docs/aps-cloud-search.md | wc -l   # is the new content there?+```++## Links between docs: RELATIVE, and do not trust a curl++In the main README (and between sub-readmes), link with the **relative repo path**:++```markdown+[APS cloud search](docs/aps-cloud-search.md)      # from the README+[2D board layout](board-layout-2d.md)             # doc-to-doc, same docs/ folder+```++The wiki's Markdown renderer **rewrites** these to the working files-viewer URL+(`/adom/<slug>/files/docs/aps-cloud-search.md`). So:++- **Do NOT use absolute `https://wiki.adom.inc/...` links.** Relative is correct and cleaner.+- **Do NOT "verify" a link by curling the path you think it resolves to.** A naive+  `<page>/docs/x.md` 404s, but the RENDERED page emits the correct rewritten href. Curling your+  guessed URL will tell you it is broken when it is fine. Check the rendered `<a href>` (or just+  click it), not a constructed URL.++## Images: reference them by their repo-root path++The files-viewer rewrites a relative image ref by prepending **`files/`** to the ref **exactly as+written** (it does NOT resolve relative to the doc's own folder). So from `docs/foo.md`:++| you write | viewer loads | works if the image is at |+|---|---|---|+| `![](docs/img/x.png)` | `files/docs/img/x.png` | `docs/img/x.png` in the repo  ✅ |+| `![](img/x.png)` | `files/img/x.png` | `img/x.png` (usually wrong) |+| `![](x.png)` | `files/x.png` | repo root (clutters root) |++**Reference images by their repo-root-relative path, `docs/img/x.png`, and commit the image at that+path.** Then push both the doc and the image with `repo push`.++## VERIFY BY LOOKING, not by curling++The meta-lesson behind every gotcha above: the wiki renders through a client SPA that rewrites links+and images and serves from a specific store. A `curl` of a URL you constructed tests a URL the+renderer never emits. To confirm a sub-readme is right:++- open the page and **look** at it (screenshot / pup), or+- read the actual rendered `<a href>` / `<img src>` and whether the image `naturalWidth > 0`.++Never conclude "broken" from a raw curl of a hand-built path. That single habit prevents the most+common sub-readme rabbit hole.++## House style++- **No em-dashes**, anywhere. Run `prose-lint <file>.md` before publishing; fix every HARD issue.+- Put **real screenshots** in the sub-readmes (see wiki-readme for image rules). A text-only+  sub-readme is thin.+- Keep the main README's index short: one row per guide, a one-line "what it covers".+- Do NOT embed the page hero in any README or sub-readme (see wiki-hero, wiki-readme).++## Checklist++1. Write `docs/<topic>.md` per feature-set; link images as `docs/img/x.png`.+2. Add a `## Feature guides` index table to the main README with relative `docs/<topic>.md` links.+3. `prose-lint` every doc (no em-dashes / AI-tells).+4. `adom-wiki repo push adom/<slug> --files README.md docs/*.md docs/img/*.png -m "..."`.+5. `adom-wiki repo show` to confirm the new content is in the repo.+6. **Look** at the rendered page: links click through, images load. Do not curl-and-assume.