# ADR-0028 — The site gets its first Verse name (/docs/maintain/adr/ADR-0028-the-site-gets-its-first-verse-name)

- **Status:** Approved
- **Date:** 2026-11-01
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** — (changes the brand rule recorded in `PRODUCT.md`: "The final name will include
  neither the owner's name nor 'docs'")
- **Superseded by:** [ADR-0036](./ADR-0036-the-site-is-nepal-dev-verse.mdx) (decisions 1 and 2); [ADR-0038](./ADR-0038-earlier-names-leave-the-pages-and-the-github-link-follows-the-move.mdx) (decision 3, in part)
- **Reworded by:** [ADR-0038](./ADR-0038-earlier-names-leave-the-pages-and-the-github-link-follows-the-move.mdx) (earlier names only)
- **Design documents:** [`../app-flow/community-identity.mdx`](../app-flow/community-identity.mdx)

## Context [#context]

The site has used a working name since it began (`appName` in
`src/lib/shared.ts`). `PRODUCT.md` records that the final name was not chosen and would include
neither the owner's name nor "docs".

On 2026-11-01 the owner chose the site's first Verse name, as in universe, and asked for it
throughout the project. They named this site's own documentation, the project with the slug
`docs`, the same name with *Docs* added. Earlier the same day they decided that the rename gets its own ADR,
separate from the sidebar (ADR-0027), and mentioned a whole-site universe theme.

Today the one name stands for two things:

- **The site**: the header's wordmark, the home page's and the 404's titles, the Open Graph
  images' site line, through `appName`.
- **This site's own project entry**: the title in `content/docs/meta.json` and
  `content/docs/index.mdx`, shown on its planet card, planet header, sidebar chip and in search.

## Decision [#decision]

1. **The site takes the Verse name.** `appName` becomes that name: the header's wordmark on every
   page, the home page's title (*the name — every package and project, documented to the
   version*), the 404's title, the site line of every Open Graph image, and the heading of
   `llms.txt` and `llms-full.txt`'s index, which reads *Docs* today (Fumadocs' default root name).
2. **This site's own docs take the name with *Docs*.** The project with the slug `docs` takes the
   same title in its `meta.json` and overview, so its planet card, planet header,
   sidebar chip, search records and Markdown carry it. Its overview's prose names the site
   by the Verse name. The slug and every URL stay as they are: `/docs`, `/docs/maintain/…`.
3. **Unchanged identifiers.** The repository folder and `package.json` name,
   the GitHub link (still undecided in
   `PRODUCT.md`), the Algolia index name and environment variable names stay as they are: they
   are identifiers, not the name readers see, and renaming the repository is outside this
   repository. Approved ADRs keep the name they were written with; they are history.
4. **Every living document follows.** `PRODUCT.md` (the name is chosen; the old rule is removed),
   `DESIGN.md` and its sidecar, `AGENTS.md`, `README.md`, the architecture page, and every app
   flow whose wireframes show the name, with their Archify views.
5. **The universe theme is not part of this ADR.** It waits for its own ADR, ADR-0029, when the
   owner asks for it.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Name | The Verse name for the site, the same with *Docs* for its own project | The owner's choice; the site and its own docs are told apart | Two names to keep in step | Chosen (owner) |
| Identifiers | A — keep the repository, package and GitHub names | Nothing outside the site changes; no broken clones or links | The repository is still called `…-docs` | Chosen |
| Identifiers | B — rename them too | One name everywhere | The GitHub rename is outside this repository and the owner's to do; `package.json` alone changes nothing a reader sees | Rejected |
| Slug of this site's project | A — keep `docs` | Every URL, search record and link keeps working | The slug does not say "verse" | Chosen |
| Slug of this site's project | B — `verse-docs` | Matches the name | Every `/docs/…` URL moves and needs redirects | Rejected |
| Theme | A — rename only; the universe theme in its own ADR | A small, checkable change | Two steps | Chosen |
| Theme | B — rename and theme together | One review | A large change hidden behind a rename | Rejected |

## Consequences [#consequences]

**Positive**

- The site has its chosen name everywhere a reader sees one.
- The site and its own documentation are told apart: the site's name is the whole, the name with
  *Docs* is one planet in it.

**Negative / accepted trade-offs**

- The repository and GitHub names keep *docs* until the owner renames them.
- Pages already crawled or shared show the old name until they are fetched again.

## Content invariants [#content-invariants]

None touched: no page moves and no URL changes. The search index takes the new title on the next
publish (`bun run build`, run by the owner).

## Security considerations [#security-considerations]

None — this change touches no data, no endpoint and no secret. The name is public text.

## Implementation notes [#implementation-notes]

- [x] `src/lib/shared.ts`: `appName` (decision 1).
- [x] `src/lib/source.ts`: the `llms.txt` index heading reads the site's name (decision 1).
- [x] `content/docs/meta.json` and `content/docs/index.mdx`: the new title, and the prose
      (decision 2).
- [x] Tests (ADR-0007): the site's name and this project's title; the `llms.txt` heading; no
      working name left in `src/`, `content/` outside approved ADRs, or the living documents.
- [x] Checked in Chrome on localhost against `bunx next build`: the header, the home page and 404
      titles, `/docs` (planet card, planet header, sidebar chip, title), `/og/docs/image.png`,
      `llms.txt` (its heading, the site's name) and `/docs.md`. `llms-full.txt` keeps the working name only inside
      approved ADRs (decision 3).
- [x] `bun run test`, `bun run types:check` and `bunx next build` pass; `bun run lint` is
      reported while it stays blocked.

## Docs to update on implementation [#docs-to-update-on-implementation]

- [x] [`../app-flow/community-identity.mdx`](../app-flow/community-identity.mdx), which has replaced the flow written here: Current; the app flows whose
      wireframes show the name (site pages, home page, package navigation, the solar system, docs
      sidebars, the overview's sidebar, the scale ladder), their Mermaid and Archify views.
- [x] `PRODUCT.md`, `DESIGN.md`, `.impeccable/design.json`, `AGENTS.md` §1, `README.md`,
      [`../architecture/system.mdx`](../architecture/system.mdx).
- [x] [`./index.mdx`](./index.mdx): status.