# Baby Name Generator

> Describe the given name you are looking for and get a shortlist of candidates, each with its
> meaning, its origin, an English pronunciation respelling, the short forms it picks up, and a note
> on how the full name scans. Every meaning carries an attestation label saying whether the
> derivation is settled, disputed between specialists, a folk etymology, or a modern coinage with no
> ancient meaning at all.

Live at https://baby-name-generator.skillsafe.ai/ · API tutorial at /api.html

## Why this app is shaped the way it is

A name's meaning and origin are factual claims the reader cannot check, made once, about a decision
that is permanent. Someone reading a recipe can taste the result; someone reading an etymology
believes it and repeats it for forty years. A language model asked for meanings and origins will
produce confident, plausible, wrong ones, and nothing downstream catches the error.

Two mechanisms answer that, and between them they are most of what this app is:

1. **Every meaning is labelled for attestation.** The model must choose one of `well-attested`,
   `disputed`, `folk`, `modern-coinage` or `uncertain`, and must write a note saying what is
   contested whenever the label is not `well-attested`. The page renders that label at the same
   weight as the meaning itself, and a missing label is a hard finding rather than a blank field.
   "Origin uncertain; commonly given as X" is treated as a better answer than a clean fabrication.

2. **Everything derivable from spelling is derived in the browser, then used to check the answer.**
   Syllable counts, initials, the engraved monogram, surname rhymes and seams, and nickname
   formation are all computable without a model. They are computed before the run, passed in as
   measurements, and re-derived from the reply afterwards. Where the two disagree, the page shows
   the disagreement next to the name it belongs to. A syllable count that is wrong is displayed, not
   silently rendered.

**Popularity is never returned as a ranking.** Charts are re-cut every year, this app does not have
this year's, and a stale rank reads exactly as confident as a fresh one — the same failure as a
fabricated etymology. The model returns a `familiarity` band and may describe a direction; a rank,
a chart position or a "top N" appearing anywhere in the reply is detected and flagged automatically.

## What is computed in the browser, free, before you sign in

- **Syllables** — a documented English spelling heuristic over a grapheme-to-sound skeleton, with a
  short list of names whose count is settled but not derivable from the letters (Irish spellings
  that hide a consonant cluster, Greek final -oe, French silent endings). The count is always shown
  with its provenance, `heuristic` or `listed`.
- **Initials and the engraved monogram**, which are two different strings and are checked
  separately: initials run first-middle-last, a monogram runs first-*surname*-middle with the
  surname's letter enlarged. A name can be clean spoken and awkward on a towel.
- **Surname clashes** — full rhyme (measured from the penultimate vowel, with unstressed vowels
  reduced to a schwa, which is why *Aidan* and *Braden* are caught despite sharing no letters in
  that syllable), half rhyme, alliteration, a seam where one name ends on the sound the next begins
  with, a vowel elision that slurs the join, and names that read equally well in either direction.
- **Nickname derivation**, split into rule-based short forms and the irregular conventional English
  diminutives that no rule produces — *Margaret* to *Peggy*, *John* to *Jack*. Those are a
  documented feature of English naming practice rather than a claim about a name's origin, which is
  why they can be computed at all while meanings cannot.
- **Spelling risk** — patterns English readers will say more than one way.

## Input contract

`POST https://api.skillsafe.ai/v1/app-api/run` with the input object as the request body. There is
no `input` wrapper and no `X-App-Slug` header.

| Field | Meaning |
| --- | --- |
| `surname` | The surname the name must sit against. Drives the rhyme, seam and monogram checks. |
| `middle` | A middle name already decided. |
| `origins` | Origins, languages or heritages, free text. |
| `sound` | The texture wanted, in the mouth rather than on the page. |
| `themes` | Meanings or associations wanted. |
| `syllables` | `"any"` or `"1"`–`"4"`. When numeric, every candidate has exactly that many. |
| `usage` | `any` \| `unisex` \| `traditionally-feminine` \| `traditionally-masculine`. |
| `rarity` | `any` or one of the familiarity bands. |
| `siblings` | Comma-separated names already in the family. |
| `avoid_names` | Comma-separated names ruled out, spelling variants included. |
| `avoid_initials` | Comma-separated initial strings to avoid. |
| `notes` | Free text. |
| `count` | How many candidates. Default 8. |
| `computed_facts` | The browser's measurements: `{facts, surname, siblings, sibling_shape}`. |
| `refine` | Second pass: `{of, goal, previous}`. |

## Output contract

One JSON object. Keys: `brief_read`, `shape_note`, `candidates`, `sibling_note`,
`shortlist_advice`, `ruled_out`, `attestation_summary`, `assumptions`, `open_questions`,
`refine_note`, `summary`.

Each candidate: `id`, `name`, `also_spelled`, `pronunciation`, `pronunciation_note`, `syllables`,
`origin`, `origin_note`, `meaning`, `attestation`, `meaning_note`, `usage`, `usage_note`,
`familiarity`, `familiarity_note`, `era_note`, `nicknames`, `with_surname`, `initials`,
`scan_note`, `why`, `watch`.

- `attestation` ∈ {`well-attested`, `disputed`, `folk`, `modern-coinage`, `uncertain`}.
  `meaning_note` is required whenever it is not `well-attested`.
- `familiarity` ∈ {`very-familiar`, `familiar`, `uncommon`, `rare`, `very-rare`}.
- `usage` ∈ {`traditionally-feminine`, `traditionally-masculine`, `unisex`, `varies-by-country`}.
- `pronunciation` is an English respelling, hyphenated one chunk per syllable, stressed chunk in
  capitals. The number of chunks must equal `syllables`; the page counts both.

## What this app will not do

- It will not tell you a name is a good or bad choice for a person. It will tell you whether a name
  fits the brief you gave, which is a different question and the only one it is equipped for.
- It will not assume a gender, a country, a religion, a couple or a first child that the brief did
  not state.
- It will not quote a popularity ranking.
- It is not a reference work. For a name you are seriously considering, check a dictionary of given
  names or an onomastic reference before you repeat the story attached to it.

## Storage and cost

Shortlists are saved to a declared `shortlists` collection on your SkillSafe account, with semantic
search over the candidate names, the brief and the title, so a name you half-remember is findable.
`localStorage` is a mirror for instant paint, never the system of record. Runs are metered and
signed-in only; everything the browser measures is free and works before sign-in, and three bundled
briefs replay a saved shortlist at zero cost.