<Parent Title> - <Child descriptor>

# canonical org children publish into the org namespace, not personal:
adompkg publish --org adom -y
# if the child ships a binary, attach it as a release asset:
adompkg release upload adom/<child-slug>@<ver> ./bin/<bin> --platform linux
# then push source + a COMPLETE page.json (title leads with the parent, hero set,
# family tag in metadata) to the git layer LAST (the hero-clobber rule applies).

---
name: wiki-family
description: >-
  How to build a Family-style wiki repo on the Adom Wiki — an anchor page plus
  children published as their own pages, joined by a naming convention, a family
  tag, and breadcrumbs (e.g. adom-usb + adom-usb-sniffer-cdc, adom-desktop +
  bridges). Use this when a hub has parts that need their own owners or release
  cadence, or when adding a child/plugin to an existing family. Trigger words:
  wiki family repo, parent child wiki page, add a plugin to the family, anchor
  page, family tag, name a child page, adom-usb plugin, adom-desktop bridge,
  publish a child page, family naming convention, register a child.
---

Parent skill: **adom-wiki-skillpack**

# Building a Family repo

A **Family** is an anchor page plus children published as **separate** wiki pages
(not files in one repo), joined by convention so the relationship survives even
when a child is seen out of context. Use it when children need independent owners
or update cadences — see **wiki-repo-styles** for Family-vs-Skillpack. Examples:
`adom-usb` (+ sniffer/firmware plugins), `adom-desktop` (+ bridges).

## 1. Naming — every member announces its family

Users meet children out of context (a card, a search hit, a screensaver
billboard), so the family must be obvious without reading the slug. There are TWO
names, with DIFFERENT separators — don't mix them up:

### The title — the canonical format (this is the one people see)

The page **title** is what shows on cards, search, the homepage slideshow, and the
screensaver. **Nobody reads slugs — the title is what carries the family.** Use
exactly this format, every time, identically across siblings:

```
<Parent Title> - <Child descriptor>
```

- Separator is a **space, a plain ASCII hyphen `-`, and a space** (`" - "`).
- The parent is its **proper Title Case** product name (`Adom USB`, `Adom Desktop`),
  NOT the slug.
- **NEVER** a colon (`:`), an em-dash (`—`) or en-dash (`–`), a slug-style hyphen
  with no spaces, or the bare descriptor on its own.

| ✅ Correct | ❌ Wrong | Why it's wrong |
|---|---|---|
| `Adom USB - CDC serial sniffer` | `CDC serial sniffer` | bare descriptor — hides the family |
| `Adom USB - RP2040 persona pack` | `adom-usb-stub-rp2040` | slug used as the title |
| `Adom Desktop - KiCad Bridge` | `Adom Desktop: KiCad Bridge` | colon, not `" - "` |
| `Adom Desktop - Bridge SDK` | `Adom Desktop — Bridge SDK` | em-dash, not ASCII hyphen |
| `Adom Desktop - Altium Bridge` | `adom-desktop-altium-bridge` | slug as title (a real offender) |
| `Adom Desktop - Demo` | `Demo` | orphan — doesn't announce the family at all |
| `Adom Desktop - Bridges Registry` | `Adom Desktop Bridges Registry` | no `" - "` separator |

(The ❌ column is drawn from real inconsistencies already on the wiki — colons,
em-dashes, slug-as-title, and orphan titles all exist today. Match the ✅ column.)

### The slug — dashes, no spaces

- **Slug**: `<parent>-<descriptor>` — `adom-usb-sniffer-cdc`,
  `adom-desktop-kicad-bridge`. Dash separators, lowercase, **never a colon**
  (illegal in slugs) and never spaces. The slug is NOT the title — convert it to
  the spaced, Title-Cased form above for the `title` field.

### The other family markers

- **Family tag/keyword**: include `<parent>-plugin` (e.g. `adom-usb-plugin`) so
  the anchor's discovery and `<parent> plugins search` find the child.
- **Hero billboard**: carry a small family chip (e.g. `ADOM-USB · SNIFFER`) so the
  relationship survives even when only the image shows. Build it per **wiki-hero**.

After publishing a child, `GET /api/v1/pages/<child-slug>` and eyeball the
`title` — it must read `<Parent> - <descriptor>` with the spaced ASCII hyphen,
identical in style to its siblings.

## 2. The anchor page is a registry

The anchor (e.g. `adom-usb`) documents the family and keeps a **table of known
children** in its README ("install any of these"), plus the conventions so every
child adopts them. The anchor's skill explains how to author and publish a child.
Children point back to the anchor via **breadcrumbs** (see **wiki-breadcrumbs**),
which is how third-party children announce themselves to the anchor.

## 3. Ship reference children as templates

Include copyable child templates in the anchor repo under `examples/` (as
`adom-usb` does with `examples/adom-usb-sniffer-cdc/` and `.../adom-usb-stub-rp2040/`),
each with its own `plugin.json` + `package.json` + `install.sh`/`uninstall.sh` +
`README.md`. Third parties copy a template, rename per the convention, and publish.

## 4. Publishing a child

Each child is a normal Page publish (see **wiki-api** / **wiki-publish-safely**),
with the family conventions applied:

```bash
# canonical org children publish into the org namespace, not personal:
adompkg publish --org adom -y
# if the child ships a binary, attach it as a release asset:
adompkg release upload adom/<child-slug>@<ver> ./bin/<bin> --platform linux
# then push source + a COMPLETE page.json (title leads with the parent, hero set,
# family tag in metadata) to the git layer LAST (the hero-clobber rule applies).
```

After any title/hero change, confirm `GET /api/v1/pages/<child-slug>` shows the
`title` leading with the parent and `hero_path` set — cards, search, and the
screensaver read those fields.

## 5. Discovery

Children are found three ways, so set all three: the **family tag**
(`<parent>-plugin`), the anchor's **registry table** in its README, and
**breadcrumbs** from the child back to the anchor. The anchor can also query the
registry for everything tagged `<parent>-plugin` to list the family live.