<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

## 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. |

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"

adom-wiki repo show adom/<slug> docs/aps-cloud-search.md | wc -l   # is the new content there?

[APS cloud search](docs/aps-cloud-search.md)      # from the README
[2D board layout](board-layout-2d.md)             # doc-to-doc, same docs/ folder

---
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.