Adom Wiki Skill Pack

@@ -1,176 +1,112 @@ --- name: wiki-sub-readme+user-invocable: true 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.+  Make a SUB-README on an Adom Wiki page: a README.md inside a subfolder of the page's repo that fully+  documents ONE topic (a feature-set, a lab, a runbook, an event plan, how a video was made), rendered as+  its own sub-page, and ALWAYS introduced from the main README by a section card: a section header, a+  thumbnail the AI makes from the sub-readme's most relevant visual, and a three-sentence write-up with+  links. Use whenever someone says "create me a sub-readme" or a page has grown topics that would bloat+  its README. Covers the card, the folder layout, publishing with `adom-wiki repo push` (not the files+  blob API), image and link paths, and verifying the RENDERED page. Trigger words: sub-readme, sub+  readme, subreadme, create me a sub-readme, make a sub-readme, folder README, README in a subfolder,+  second readme, feature guide, deep-dive doc, wiki sub page, add a page to my wiki page, nested doc on a+  wiki page, split my readme, my readme is too long, share this doc on our page but not on the overview. --- -# Sub-READMEs on the Adom Wiki+Parent skill: **adom-wiki-skillpack** -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.+# Sub-readmes on the Adom Wiki -## The layout+A **sub-readme** is a `README.md` inside a **subfolder** of a page's git repo (`tether-lab/README.md`,+`docs/video/README.md`). The wiki renders that folder's README as its own sub-page, the way GitHub renders a+folder's README. It lets a page carry a real, deep document without bloating the main README (the page's+overview) and without minting a separate wiki page (wiki-bloat). It has no slug, no hero and no search+card: it lives inside its parent page. -```-<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-```+**Every sub-readme gets a section card in the main README. Always, with no exceptions** (John, 2026-10-07).+Making the sub-readme and making its card are one job. -In the main README, one index section:+## 1. The section card in the main README (always) -```markdown-## Introducing ONE sub-readme in the main README: icon left, a few sentences right+When you create a sub-readme, add a section for it to the main README that looks like this. The live+example is the "Tether Lab" section on adom/adom-aiflow-probing: -When the main README introduces a single sub-readme (a sub-project, a lab, a tool), do NOT paste a big-screenshot of it. Give it a small card: a small icon on the left, a few sentences of preview and its-links on the right. That is the standard way to introduce a sub-readme (John, 2026-10-06; live on-adom/adom-aiflow-probing, "Tether Lab").--The sanitizer STRIPS `align` (verified 2026-10-06: `<img align="left">` renders with no float), so a-floated image does not work. Use a two-cell HTML table, which survives:+- **a section header** (`## <Topic>: <what it is>`), so the card shows in the page's table of contents;+- **on the left, a thumbnail** linked to the sub-readme, with the topic's short name as a caption under it;+- **on the right, exactly three sentences**: what the sub-readme covers, why a reader cares, and what they+  can do with it. Then the links (the sub-readme first, a live demo or video if there is one).  ```html+## Tether Lab: the ground wire's physics+ <table> <tr>-<td width="104"><a href="lab/README.md"><img src="lab/docs/lab-icon.png" width="112" alt="Lab"></a><br><sub>&nbsp;&nbsp;&nbsp;&nbsp;Lab&nbsp;name&nbsp;&nbsp;&nbsp;&nbsp;</sub></td>-<td>Two or three sentences: what it is and why a reader cares. <strong><a href="lab/README.md">Lab name</a></strong> ...<br><br><a href="https://wiki.adom.inc/<owner>/<slug>/render/lab/live.html">Play it live</a> · <a href="lab/README.md">How it works</a></td>+<td width="104"><a href="tether-lab/README.md"><img src="tether-lab/docs/tether-lab-icon.png" width="112" alt="Tether Lab"></a><br><sub>&nbsp;&nbsp;&nbsp;&nbsp;Tether&nbsp;Lab&nbsp;&nbsp;&nbsp;&nbsp;</sub></td>+<td>The probe's ground wire is short and stiff, so it decides where the probe can go. <strong><a href="tether-lab/README.md">Tether Lab</a></strong> simulates it on its own: move the probe, change the wire, or watch the pincers insert and extract the ground pin. The same Rust solver checks every move <code>compile</code> plans.<br><br><a href="https://wiki.adom.inc/<owner>/<slug>/render/tether-lab/lab.html">Play it live</a> · <a href="tether-lab/README.md">How it works, with the equations</a></td> </tr> </table> ``` -The traps, each found the hard way:-- **The cell's `width` is ignored** and the image's `max-width: 100%` lets the table squeeze the icon-  column to about 60 px. The non-breaking caption under the icon (`&nbsp;` padding around the name)-  gives the column a real minimum width. Keep it.-- **Give the image a `width` only, never a `height`**: with both, a squeezed cell distorts it.-- **The icon is real**: a square crop of the sub-project's own render or screenshot (about 256 px source,-  rounded corners), not a drawn glyph and not the full screenshot.-- In the MAIN README, relative `src` and `href` resolve (the Overview renderer rewrites them). Inside a-  sub-readme use absolute `/blob/` URLs for images (see wiki-subreadme).-- Verify on the rendered page (signed in when it is private): icon left, text starting to its right,-  icon square.--## 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+**Make the thumbnail yourself, and make it the most relevant picture of the sub-readme's subject:**+- Take it from the sub-readme's own visuals: its best screenshot, render, diagram or a video frame (the moment that says what the topic is). Never use a drawn glyph, a stock icon, a generic logo, or the page's hero.+- Crop it **square** around the subject, so it reads at about 112 px. Use a 256 px source with rounded corners, saved in the sub-readme's folder (`<folder>/docs/<folder>-icon.png`, or `<folder>/<folder>-icon.png`).+- Look at it at 112 px before you push. If the subject isn't obvious at that size, crop tighter. -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:+The traps, each found the hard way:+- **The sanitizer strips `align`**, so a floated image doesn't work. The two-cell table survives.+- **The cell's `width` is ignored.** The image's `max-width: 100%` lets the table squeeze the icon column to about 60 px. The non-breaking caption (`&nbsp;` padding around the name) gives the column a real minimum width. Keep it.+- **Give the image a `width` only, never a `height`.** With both, a squeezed cell distorts it.+- In the main README, relative `src` and `href` resolve (the Overview renderer rewrites them).++Several sub-readmes on one page each get their own card, in reading order. An index table (one row per+guide) is fine **in addition** to the cards on a page with many guides, never instead of them.++## 2. The folder and its README++1. Name the folder in kebab-case, as a path segment: `tether-lab/`, `docs/video/`, `runbooks/oncall/`,+   `september-dc-event/`.+2. Put the document at `<folder>/README.md`. Avoid a loose, oddly named `.md` at the repo root: the folder+   plus `README.md` is what renders as a browsable sub-page.+3. Put its images, PDFs and videos inside the same folder.+4. Write it for its reader:+   - real screenshots (a text-only sub-readme is thin);+   - short paragraphs and tables;+   - no em-dashes or en-dashes (run `prose-lint`);+   - never embed the page's hero.++### Image, video and link paths++- **Images and media inside a folder README:** since wiki 2026-09-14, a folder README resolves a relative path from its own folder first, then from the page root. So `![shot](img/x.png)` (next to the README) and `![shot](tether-lab/img/x.png)` (from the root) both work. `repo push` answers `README_ASSET_UNRESOLVED` when a referenced file exists in neither place.+- **If an image still shows broken on the rendered sub-page**, use the absolute blob URL, which always works: `https://wiki.adom.inc/blob/<type>/<slug>/<repo-path>`. `<type>` is the page's type (`app`, `skill`, `component`, ...), and there is no owner in a blob path.+- **Video** `src` and `poster` follow the same rules. Video, audio and iframes are capped at the column width. For a long or full-resolution video, link a YouTube upload (or use `::youtube{id="VIDEO_ID"}` on its own line) rather than committing a large file. See `demo-video-publishing` (adom/demo-authoring-skillpack).+- **Links between docs:** relative repo paths (`../other/README.md`, `tether-lab/README.md`). The renderer rewrites them. Links to other wiki PAGES stay normal URLs (`https://wiki.adom.inc/<owner>/<slug>`).+- **An HTML document** in a folder (`readme.html` / `index.html`) renders as the folder's sub-page in the sandboxed frame (see `wiki-readme-html`). On a PRIVATE page the listing shows a link instead of the frame. To link one from prose, use its raw-route URL `https://wiki.adom.inc/<owner>/<slug>/render/<folder>/<file>.html`.++## 3. Publish through the git layer, never the files blob API++A page has two stores: the files blob store (`POST /api/v1/pages/<slug>/files`) and the **git page repo**+(what the Files tab and the Overview render). An upload to the blob store can answer 200 and still leave+the page showing the old version. Always publish with `repo push`, the sub-readme, its assets and the+main README together:  ```bash-adom-wiki repo show adom/<slug> docs/aps-cloud-search.md | wc -l   # is the new content there?+adom-wiki repo push <owner>/<slug> --files README.md <folder>/README.md <folder>/docs/<folder>-icon.png <folder>/img/*.png -m "add the <folder> sub-readme and its card"+adom-wiki repo show <owner>/<slug> <folder>/README.md | head    # the new content is really 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`.--The same rule covers **video `src` and `poster`**. Since wiki 2026-09-14 a README inside a folder-resolves a relative path from its own folder first, then from the page root, so-`project-workspaces/README.md` may write `demo.mp4` for a file next to it or the full-`project-workspaces/demo.mp4`; the push answers `README_ASSET_UNRESOLVED` when a referenced file-exists in neither place. Video, audio and iframes are capped at the column width like images, so-a `width` attribute is optional. Full checklist: the `demo-video-publishing` skill-(adom/demo-authoring-skillpack).--A **YouTube** video is a tag on its own line, the same as in the main README:-`::youtube{id="VIDEO_ID"}` (details in **wiki-readme**, Embeds). Sub-readmes render it.--## 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+## 4. Verify by looking, never by curling a URL you built -- **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).+The wiki renders through a client app that rewrites links and images. A `curl` of a hand-built URL tests a+URL the renderer never emits: it can say "broken" when the page is fine, and "fine" when it's broken.+Instead:+- open the page (signed in if it's private) and **look**: the card shows a square thumbnail on the left with the text starting to its right, and the links click through;+- open the sub-page (`/<owner>/<slug>/files/<folder>`): every image loads (`naturalWidth > 0`) and the links work.  ## 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.+1. `<folder>/README.md` written, with real visuals; `prose-lint` is clean.+2. Thumbnail made from the sub-readme's most relevant visual: square, 256 px source, readable at 112 px.+3. Main README: a `## ` section header, the two-cell card (thumbnail plus caption linked to the sub-readme), three sentences, then the links.+4. `adom-wiki repo push` with the README, the sub-readme and every asset; `repo show` confirms it.+5. Looked at the rendered Overview card and the rendered sub-page.