# Nepal Dev Verse Docs (/docs)

Nepal Dev Verse holds the documentation for packages and projects by Nepalese developers all over the world, as part of
[nepal-dev.com](https://nepal-dev.com). It documents itself the same way, as the project `docs`.

## How every package and project is organised [#how-every-package-and-project-is-organised]

Each one lives at its own address, `/<slug>`, and has the same shape:

| Address | What it holds |
|---|---|
| `/<slug>` | The overview: what it is, its versions and where to go next |
| `/<slug>/use/…` | **Use**: docs for people using it, one set per release |
| `/<slug>/use/dev/…` | Work in progress on the default branch, not released yet |
| `/<slug>/use/latest/…` | Always the latest release |
| `/<slug>/maintain/…` | **Maintain**: docs for the people who look after it |

Every page states the version it documents. Add `.md` to any page's address for its Markdown,
or read [`/llms.txt`](/llms.txt) for an index of every page.

## This site [#this-site]

Nepal Dev Verse Docs has no Use track yet. Its **Maintain** track holds the decisions and design documents
behind it: start at the [maintainer documentation map](./maintain/index.mdx).


# ADR-NNNN — <short imperative title> (/docs/maintain/_templates/adr)

- **Status:** Proposed
- **Date:** YYYY-MM-DD
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** —
- **Approved on:** —
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `content/docs/maintain/app-flow/<slug>.mdx` (when the UI changes, ADR-0008), `content/docs/maintain/prd/<slug>.mdx`,
  `content/docs/maintain/architecture/system.mdx`, … (the living docs this decision creates or changes — see ADR-0002)

## Context [#context]

What problem are we solving? What forces, constraints and facts about the current codebase
make this decision necessary *now*? State only what is true and verifiable.

## Decision [#decision]

The decision, stated plainly and in the present tense ("We use X", "Y lives in Z").
Include the concrete shape of the change: directories, file names, contracts, commands.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — `<name>` | | | Chosen / Rejected |
| B — `<name>` | | | Chosen / Rejected |

## Consequences [#consequences]

**Positive**

- …

**Negative / accepted trade-offs**

- …

## Content invariants [#content-invariants]

Which invariants in `AGENTS.md` §6 this touches, and how it keeps them. If it departs from
one, say so explicitly. That departure is part of what the owner approves.

## Security considerations [#security-considerations]

Mandatory — never omit this section (ADR-0005). For a change with no security surface,
"None — this change touches no data, no endpoint and no secret" is a valid answer; an omitted
section is indistinguishable from not having thought about it.

Where there is a surface, state: what content or data it handles and its classification,
whether anything private can reach a public surface, what authorization applies and where it is
enforced, what leaves the system (search provider, host, analytics), and what residual risk is
accepted. Link `content/docs/maintain/security/<slug>.mdx` when the feature warrants its own analysis.

## Implementation notes [#implementation-notes]

What actually changes in the repo once this is approved. Keep this list checkable — it is
the scope of the implementation that follows the approval.

- [ ] …
- [ ] Tests — the happy path **and** the obvious failure paths (ADR-0007). If some part cannot
      be unit-tested, say which, and say what was verified instead.
- [ ] `bun run lint`, `bun run types:check` and `bunx next build` pass.

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

Living design documents are snapshots of the system as it stands — edit them in place, never
as a log of what changed (ADR-0002). Delete anything in them that is no longer true.

- [ ] `content/docs/maintain/app-flow/<slug>.mdx` — if the UI changed
- [ ] `content/docs/maintain/prd/<slug>.mdx` — requirements + user stories
- [ ] `content/docs/maintain/erd/system.mdx` — if persisted data changed
- [ ] `content/docs/maintain/architecture/system.mdx` · `content/docs/maintain/dfd/` · `content/docs/maintain/state/` · `content/docs/maintain/sequence/` ·
      `content/docs/maintain/api/` · `content/docs/maintain/rbac/` — whichever the change requires (ADR-0002)
- [ ] `content/docs/maintain/security/` — `secrets.mdx` if a secret is introduced; `threat-model.mdx` if the
      attack surface changed; `<slug>.mdx` if the feature warrants its own analysis
- [ ] `AGENTS.md` — \<what changes, if the way we work changed>
- [ ] `README.md` — \<what changes, if the project overview changed>
- [ ] `content/docs/maintain/adr/index.mdx` — index row + status


# API — <route or resource> (/docs/maintain/_templates/api)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Endpoints [#endpoints]

| Method | Path | Purpose | Auth |
|---|---|---|---|

---

### `METHOD /path` [#method-path]

**Purpose.** One line.

**Authorisation.** Who may call it, and which content it may return — cross-reference
`content/docs/maintain/rbac/<slug>.mdx`. If it is public, say what keeps private content out of it.

**Request**

```json
{}
```

| Field | Type | Required | Notes |
|---|---|---|---|

**Responses**

| Status | Meaning | Body |
|---|---|---|
| 200 | | |
| 400 | Validation failed | `{ "error": { "code": "...", "message": "..." } }` |
| 401 | Not authenticated | |
| 403 | Authenticated but not permitted | |
| 404 | Not found, or hidden by permission | |

**Notes.** Caching and revalidation, content type, pagination, rate limits, side effects.


# App flow — <feature> (/docs/maintain/_templates/app-flow)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a person sees and how they move through it. Sample values are invented (ADR-0008).
Phone width first; note where desktop differs.

## Entry points [#entry-points]

- Where a person reaches it from (home page, sidebar, search, a package badge or README link,
  a direct URL, the Markdown version), and what access it needs.
- Who does not see it, and what they get at its URL.

## Flow [#flow]

Draw this diagram with Archify too. In a copy, wrap the fence in
`<Diagram src="/diagrams/<project-slug>/<slug>.html" title="…">` … `</Diagram>`, with nothing else
inside: the page shows the Archify view and its Markdown the Mermaid. Outside the templates, a
bare Mermaid fence fails the build (ADR-0022).

```mermaid
flowchart LR
  A[Screen A] -->|action| B[Screen B]
  B -->|back| A
  B -->|search| S[Search dialog]
```

## Screens [#screens]

### 1. `<Screen name>` — `/route` [#1-screen-name--route]

The wireframe gets its own Archify view too, one per screen: an `architecture` diagram drawn
from this Mermaid, its boxes placed as the rows, inside a labelled phone-screen region. Wrap the
fence in its `<Diagram>` the same way.

```mermaid
block-beta
  columns 4
  menu["☰"] title["Site name"]:2 search["⌕"]
  crumb["Packages › npm › example-pkg"]:4
  h1["example-pkg"]:3 version["v1.2.0 ▾"]
  block:body:4
    columns 4
    install["npm install example-pkg"]:4
    para["Short description of what it does."]:4
  end
  nav["‹ Previous · Next ›"]:4
```

**States**

- Empty: …
- Loading: …
- Not found: …
- Refused (private, no access): …
- Error: …
- Degraded (an external service such as search is unavailable): …
- Success: …


# Architecture — <system or feature> (/docs/maintain/_templates/architecture)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Context [#context]

What this is, and the boundary between it and everything else.

## Components [#components]

| Component | Responsibility | Depends on |
|---|---|---|
| | | |

## Diagram [#diagram]

Draw this diagram with Archify too. In a copy, wrap the fence in
`<Diagram src="/diagrams/<project-slug>/<slug>.html" title="…">` … `</Diagram>`, with nothing else
inside: the page shows the Archify view and its Markdown the Mermaid. Outside the templates, a
bare Mermaid fence fails the build (ADR-0022).

```mermaid
flowchart TB
  subgraph Site["puncoz-packages-docs"]
    CONTENT["content/<br/>MDX"]
    APP["Next.js + Fumadocs"]
  end
  Reader["Reader"] --> APP
  CONTENT --> APP
```

## Key decisions in force [#key-decisions-in-force]

Links to the ADRs that govern this, one line each on what they mandate.

## Constraints [#constraints]

Performance, security, privacy and operational constraints this must respect.


# DFD — <system (Level 0) or feature (Level 1/2)> (/docs/maintain/_templates/dfd)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.
> Conventions: `content/docs/maintain/dfd/index.mdx`. Levels balance — a child's flows match its parent's.

## Scope [#scope]

Which process this decomposes, and its parent diagram.

## Diagram [#diagram]

Draw this diagram with Archify too. In a copy, wrap the fence in
`<Diagram src="/diagrams/<project-slug>/<slug>.html" title="…">` … `</Diagram>`, with nothing else
inside: the page shows the Archify view and its Markdown the Mermaid. Outside the templates, a
bare Mermaid fence fails the build (ADR-0022).

```mermaid
flowchart LR
  Ext["External Entity"]

  subgraph Trust["Trust boundary — puncoz-packages-docs"]
    P1(("1.0<br/>Process name"))
    D1[("D1 · Data store")]
  end

  Ext -->|"data that moves"| P1
  P1 -->|"record written"| D1
  D1 -->|"record read"| P1
  P1 -->|"result returned"| Ext
```

## External entities [#external-entities]

| Entity | Role |
|---|---|

## Processes [#processes]

| # | Process | Input → Output |
|---|---|---|

## Data stores [#data-stores]

| ID | Store | Contents | Classification |
|---|---|---|---|
| D1 | | | Public / Internal / Confidential / Restricted — see [`../security/data-classification.mdx`](../security/data-classification.mdx) |

## Trust boundary crossings [#trust-boundary-crossings]

Every flow that crosses a boundary, with how it is authorised and whether private content can
travel on it.

| Flow | Direction | Authorisation | Private content? |
|---|---|---|---|


# ERD — <system or feature subset> (/docs/maintain/_templates/erd)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Diagram [#diagram]

Draw this diagram with Archify too. In a copy, wrap the fence in
`<Diagram src="/diagrams/<project-slug>/<slug>.html" title="…">` … `</Diagram>`, with nothing else
inside: the page shows the Archify view and its Markdown the Mermaid. Outside the templates, a
bare Mermaid fence fails the build (ADR-0022).

```mermaid
erDiagram
  PROJECT ||--o{ VERSION : "has"
  PROJECT {
    text slug PK
    text visibility "public | private"
  }
  VERSION {
    text project_slug FK
    text version "semver"
  }
```

## Entities [#entities]

### `<ENTITY>` [#entity]

| Column | Type | Null | Notes |
|---|---|---|---|

**Indexes:** …
**Invariants:** rules the store or application guarantees (uniqueness, required references,
allowed values).

## Relationships [#relationships]

| From | To | Cardinality | On delete |
|---|---|---|---|

## Sensitive fields [#sensitive-fields]

Classification per [`../security/data-classification.mdx`](../security/data-classification.mdx).

| Field | Classification | Protection |
|---|---|---|


# Templates (/docs/maintain/_templates)

A starting point for each document type. Copy the file into its directory, fill it in, and
delete what does not apply. Each one is a Markdown page with a frontmatter `title`
([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)) and `description`, a required line
([ADR-0035](../adr/ADR-0035-every-page-is-ready-for-search-and-sharing.mdx)) whose placeholder the build
can't tell from your own, so replace it.

| Template | Copy to |
|---|---|
| [ADR](./adr.mdx) | `adr/ADR-NNNN-kebab-title.mdx` |
| [App flow](./app-flow.mdx) | `app-flow/<feature-slug>.mdx` |
| [PRD](./prd.mdx) | `prd/<feature-slug>.mdx` |
| [Architecture](./architecture.mdx) | `architecture/<area>.mdx` |
| [API](./api.mdx) | `api/<resource>.mdx` |
| [DFD](./dfd.mdx) | `dfd/<feature-slug>.mdx` |
| [Sequence](./sequence.mdx) | `sequence/<flow>.mdx` |
| [State machine](./state.mdx) | `state/<entity>.mdx` |
| [ERD](./erd.mdx) | `erd/system.mdx` |
| [RBAC](./rbac.mdx) | `rbac/<feature-slug>.mdx` |
| [Security](./security.mdx) | `security/<feature-slug>.mdx` |


# PRD — <feature name> (/docs/maintain/_templates/prd)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

Whose problem is this, and what does it cost them today? Observable facts, not aspirations.

## Goal [#goal]

What is true once this ships, stated so it can be checked.

## Non-goals [#non-goals]

What this deliberately does not do, and where that need is met instead.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **`<role>`**, I want **`<capability>`**, so that **`<outcome>`**. | - Given … when … then …<br />- … |
| US-2 | | |

## Rules and edge cases [#rules-and-edge-cases]

Behaviour that the stories imply but do not spell out: validation, empty states, versions,
private versus public content, what happens to existing pages and their URLs.

## Out of scope for now [#out-of-scope-for-now]

Deferred, with the reason.

## Open questions [#open-questions]

Decisions still needed, each with options (ADR-0004). Remove once answered.


# RBAC — <feature> (/docs/maintain/_templates/rbac)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Roles in scope [#roles-in-scope]

| Role | Definition |
|---|---|

## Scope [#scope]

How a role's reach is bounded: public content only · one private project · every project.

## Action matrix [#action-matrix]

Legend: ✅ allowed · 🔶 allowed within scope · ❌ denied

| Action | Role A | Role B | Role C |
|---|---|---|---|
| Read page | | | |
| Read Markdown / `llms.txt` | | | |
| Search | | | |
| Edit content | | | |
| Publish | | | |

## Surface-level visibility [#surface-level-visibility]

Surfaces where visibility differs from the page's own (search index, `llms-full.txt`, Open
Graph images, sitemap).

| Surface | Public content | Private content | Enforced where |
|---|---|---|---|

## Denial behaviour [#denial-behaviour]

Whether a denied page is hidden (404) or visible-but-locked (403), and why.


# Security — <feature> (/docs/maintain/_templates/security)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Attack surface introduced [#attack-surface-introduced]

What this feature adds that did not exist before: routes, inputs, published surfaces, stored
data, secrets, integrations, build steps.

## Data handled [#data-handled]

| Data | Classification | Stored where | Sent where |
|---|---|---|---|

Classification per [`data-classification.mdx`](../security/data-classification.mdx). If a level is unclear,
**ask** — never assign one by assumption (ADR-0004).

## Threats and controls [#threats-and-controls]

| # | Threat | How it would be exploited | Control |
|---|---|---|---|
| T1 | | | |

## Authorization [#authorization]

Who may do what, and **where the check happens server-side**. Cross-reference
`content/docs/maintain/rbac/<slug>.mdx` rather than restating it.

## What is logged [#what-is-logged]

Which actions produce a log or audit record, and confirmation that none carries a secret or
private content.

## Residual risk [#residual-risk]

What is knowingly not defended against, and why that is acceptable. Accepted by whom.


# Sequence — <flow name> (/docs/maintain/_templates/sequence)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Trigger [#trigger]

What starts this flow, and the preconditions that must hold.

## Diagram [#diagram]

Draw this diagram with Archify too. In a copy, wrap the fence in
`<Diagram src="/diagrams/<project-slug>/<slug>.html" title="…">` … `</Diagram>`, with nothing else
inside: the page shows the Archify view and its Markdown the Mermaid. Outside the templates, a
bare Mermaid fence fails the build (ADR-0022).

```mermaid
sequenceDiagram
  autonumber
  actor R as Reader
  participant B as Browser
  participant S as Site
  participant X as External service

  R->>B: action
  B->>S: request
  S->>X: call
  X-->>S: result
  S-->>B: response
  B-->>R: outcome
```

## Failure paths [#failure-paths]

| Step | Failure | Behaviour | Recovery |
|---|---|---|---|

## Post-conditions [#post-conditions]

What is true once the flow completes, including what was written or published.


# State machine — <entity> (/docs/maintain/_templates/state)

- **Status:** Draft
- **Last updated:** YYYY-MM-DD
- **Related ADRs:** ADR-NNNN

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Diagram [#diagram]

Draw this diagram with Archify too. In a copy, wrap the fence in
`<Diagram src="/diagrams/<project-slug>/<slug>.html" title="…">` … `</Diagram>`, with nothing else
inside: the page shows the Archify view and its Markdown the Mermaid. Outside the templates, a
bare Mermaid fence fails the build (ADR-0022).

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: publish
  Published --> Deprecated: deprecate
  Deprecated --> [*]
```

## States [#states]

| State | Meaning | Who can see it |
|---|---|---|

## Transitions [#transitions]

| From | To | Trigger | Guard | Side effects |
|---|---|---|---|---|

## Terminal states [#terminal-states]

Which states are final, and what remains possible from them (read, redirect, archive).


# ADR-0001 — Every change starts with an approved ADR (/docs/maintain/adr/ADR-0001-adr-driven-development-workflow)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §2–§3, `content/docs/maintain/adr/index.mdx`, `content/docs/maintain/_templates/adr.mdx`

## Context [#context]

puncoz-packages-docs is greenfield: a Fumadocs scaffold that will document every package,
library and project its owner builds — npm, Composer and other ecosystems, public and private
projects. The owner builds it change by change, largely with AI agents.

Two forces make an explicit gate necessary:

- **The expensive mistakes are structural and early.** How content is laid out per ecosystem
  and package, how versions are handled, and how private project documentation is kept off the
  public site are cheap to get right on paper and expensive to change once many pages and
  inbound links depend on them. A private page that was published cannot be unpublished.
- **Agents produce plausible work fast.** Without a gate, a decision is made implicitly in code
  and found late.

## Decision [#decision]

1. **Every feature and functional change starts with an ADR** in `content/docs/maintain/adr/`, written from
   `content/docs/maintain/_templates/adr.mdx`, with `Status: Proposed` and an index row in `content/docs/maintain/adr/index.mdx`.
2. **No application code is written until the owner explicitly approves it.** Approval sets
   `Status: Approved`, `Approved by`, `Approved on`.
3. **Once approved, the whole scope is implemented in one pass**, with tests and every affected
   document, without stopping for per-step review.
4. **Agents never commit, push, rebase or switch branches.** The owner reviews the working tree
   and commits.
5. **An approved ADR's Decision is never edited**; it is superseded by a new ADR.
6. **Content within approved conventions needs no ADR.** Writing or updating a package's or
   project's pages is the site's normal work; deciding the conventions themselves is not.

What needs an ADR is the table in `AGENTS.md` §2. Anything that decides how private project
documentation is stored, built, served or searched always does.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — ADR gate for every functional change | Decisions are explicit, reviewable and recorded; structural mistakes are caught before code | Ceremony on small features | Chosen |
| B — Code first, document after | Fast | Decisions are implicit; privacy and structure errors are found late | Rejected |
| C — ADRs only for "big" changes | Less ceremony | "Big" is judged by whoever wants to skip it | Rejected |

## Consequences [#consequences]

**Positive**

- Every decision has a record of why, which an agent in a later session can read.
- The owner controls scope change by change.

**Negative / accepted trade-offs**

- Small features carry an ADR's overhead. Accepted: the template keeps a small ADR small.

## Content invariants [#content-invariants]

Establishes the gate through which any departure from `AGENTS.md` §6 must pass.

## Security considerations [#security-considerations]

None directly — this is a process decision. It does make every later security decision pass
through the mandatory security section of an ADR (ADR-0005).

## Implementation notes [#implementation-notes]

- [x] `AGENTS.md` §2–§3 describe the gate and execution rules.
- [x] `content/docs/maintain/adr/index.mdx` holds the index and the next free number.
- [x] `content/docs/maintain/_templates/adr.mdx` exists.
- Tests: not applicable (process only).

> Written together with the documents it governs, at the owner's direct request, so the
> implementation notes above are already done. If the owner rejects or changes this ADR, the
> documents are changed to match.

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

- [x] `content/docs/maintain/adr/index.mdx` — status on approval.


# ADR-0002 — Design documents are living snapshots, published as this site's Maintain track (/docs/maintain/adr/ADR-0002-living-design-documentation)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** [ADR-0012](./ADR-0012-every-page-is-mdx.mdx) (decision 4: every page is
  MDX); [ADR-0011](./ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx) (decision 5,
  in part: Archify diagrams are embedded from sandboxed HTML, with the Mermaid version kept)
- **Design documents:** `content/docs/maintain/index.mdx`, `content/docs/maintain/meta.json`,
  every directory `index.mdx`, `content/docs/maintain/_templates/`

## Context [#context]

This repository is a documentation site, so "documentation" means two different things here:

- **Package and project documentation**: the pages readers come for. It is the product.
- **Documentation about the site**: why it is built the way it is, and how it works.

The second kind serves two further jobs:

- **Decisions** need a permanent, ordered record of why.
- **Design documents** (flows, data flows, access rules, the threat model) must match the code
  at all times. A document that describes an old version is worse than none, because it is
  believed.

The owner decided on 2026-10-31 that the site's own documentation is published on the site,
rather than kept in a separate `docs/` folder outside the content. ADR-0015 then made the site
a catalogued project like any other, slug `docs`, so this documentation is that project's
Maintain track.

## Decision [#decision]

1. **The site's own documentation is the Maintain track of the project `docs`**,
   `content/docs/maintain/`, published at `/docs/maintain` (ADR-0015).
2. **Three kinds of document:**
   - `content/<slug>/`, except `content/docs/maintain/` — **package and project documentation**,
     written and updated within the approved content conventions and the invariants in
     `AGENTS.md` §6.
   - `content/docs/maintain/adr/` — **immutable once approved**; superseded, never
     rewritten.
   - Everything else under `content/docs/maintain/` — **living snapshots** of the site as
     it stands, edited in place. No revision tables, no "previously X, now Y", no
     strikethrough. What is no longer true is deleted. Git and ADRs hold the history.
3. **Typed directories**: `app-flow/`, `prd/`, `architecture/`, `erd/`, `dfd/`, `state/`,
   `sequence/`, `api/`, `rbac/`, `security/`, each with an `index.mdx` of its conventions, and
   `_templates/` with a starting point for each. Which ones a change requires is the table in
   `AGENTS.md` §8.
4. **Pages are Markdown (`.md`)** with a frontmatter `title` and no `#` heading; links between
   them are relative file paths.
5. **Diagrams are Mermaid** in fenced blocks: flows, sequences, state machines, ERDs and screen
   wireframes. No binary or externally hosted images. Rendering them as diagrams on the site is
   a separate decision (a new dependency).
6. **An implementation is not complete while a design document contradicts it.**
7. **Skill-generated specs and plans** go into these directories (usually the ADR and its
   design documents), not into a skill's own folder layout.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Published with the site, now `content/docs/maintain/` | The site documents itself with its own tooling; one content tree; search, Markdown and `llms.txt` cover the design docs too | Design documents, including the threat model, are public | Chosen by the owner |
| B — A separate `docs/` folder outside the content | Internal notes stay off the site | Two folders called "docs"; the design docs get none of the site's features | Rejected by the owner |
| C — Changelog-style design docs | History visible inline | Readers must reconstruct the current state | Rejected |

## Consequences [#consequences]

**Positive**

- A reader finds the current system in the design docs, the reasons in ADRs, and the packages
  in the rest of the site — all in one place, searchable.

**Negative / accepted trade-offs**

- Everything here is public: the threat model, the audit checklist and the secrets inventory
  (variable names, never values). Accepted with this decision.
- Mermaid shows as code on the site until a renderer is adopted.

## Content invariants [#content-invariants]

§6.1 applies here as everywhere: nothing about a private project goes into these pages.

## Security considerations [#security-considerations]

These pages are published on every surface (`AGENTS.md` §6.1), so they must never hold a secret
value, a private project's details, or an unfixed vulnerability's exploit path. A finding that
is not yet fixed is reported to the owner, not written here, until it is fixed.
`content/docs/maintain/security/` follows the living-snapshot rule, so the threat model
and secrets inventory are kept accurate rather than historical.

## Implementation notes [#implementation-notes]

- [x] `content/docs/maintain/` with `meta.json`, `index.mdx` and each directory `index.mdx`;
      `content/docs/meta.json` catalogues the site as project `docs` (ADR-0015).
- [x] `content/docs/maintain/_templates/` holds the templates.
- [x] `AGENTS.md` §8 states the three kinds, the page format and the "write before building"
      table.
- Tests: none — verified by `bunx next build` compiling every page.

> Approved as written on 2026-11-01, by the owner's choice. Decision 4 was already superseded by
> ADR-0012 and decision 5 in part by ADR-0011; diagrams are made with Archify, with their
> Mermaid version kept, by the owner's standing choice in `AGENTS.md` §8.

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

- [x] `content/docs/maintain/adr/index.mdx` — status on approval.


# ADR-0003 — Comments explain why; every branch takes a block (/docs/maintain/adr/ADR-0003-code-comment-policy)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §7

## Context [#context]

AI-written code tends to over-comment: restating the code, adding banners and section headers.
Those comments rot as the code changes, and they hide the few comments that matter — the
non-obvious constraints (framework quirks, third-party API limits, build-environment
differences).

Separately, an unbraced `if` body reads as guarded when a second line is added under it, and
the diff looks right. In a filter that decides which pages are published, that is a silent
leak.

## Decision [#decision]

1. **Comments explain *why*; the code explains *what*.** Default to no comment. Write one only
   for reasoning, trade-offs, edge cases or external constraints that cannot be recovered from
   the code. Prefer a reference to an ADR over prose. One or two lines, directly above what they
   explain. No banners, no `=====` headers.
2. **Configuration files may describe what a key does** (`next.config.mjs`,
   `eslint.config.mjs`, `tsconfig.json`, `.env.example`, CI and deployment manifests), still
   briefly, still linking the governing ADR. `.env.example` documents every variable and never
   its value.
3. **Tooling-consumed documentation stays**: JSDoc/TSDoc on exported public APIs,
   `@ts-expect-error` reasons, pragmas, directives.
4. **Every control-flow branch takes a block**: `if`, `else`, `for`, `while`, `do` bodies are
   braced even for one statement, enforced by ESLint `curly: ["error", "all"]`.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Why-only comments + mandatory braces (lint-enforced) | Comments stay meaningful; brace rule is mechanical and cheap | Requires discipline from agents | Chosen |
| B — Comment liberally | Feels explanatory | Comments rot and drown the important ones | Rejected |
| C — Braces by convention only | No lint change | Unenforced conventions drift | Rejected |

## Consequences [#consequences]

**Positive**

- The comments that exist are worth reading.
- A class of control-flow bugs is ruled out by lint.

**Negative / accepted trade-offs**

- Slightly more verbose one-line conditionals.

## Content invariants [#content-invariants]

None directly.

## Security considerations [#security-considerations]

None — this change touches no data, no endpoint and no secret. (Comments must still never
contain secrets; see ADR-0005.)

## Implementation notes [#implementation-notes]

- [ ] Add `curly: ["error", "all"]` to `eslint.config.mjs`, with a one-line comment linking
      this ADR. **Deferred by the owner's choice (2026-11-01)** to the ADR that makes
      `bun run lint` run again: typescript-eslint does not support TypeScript 7, so the rule
      could not be checked. The policy is followed by hand until then.
- [ ] Run `bun run lint` and fix any violations, with that ADR.
- [ ] Tests: none meaningful for a lint rule; verified by `bun run lint` failing on an unbraced
      branch and passing after.

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

- [ ] `AGENTS.md` §7 — say the brace rule is enforced (drop "once it is approved").
- [x] `content/docs/maintain/adr/index.mdx` — status.


# ADR-0004 — Resolve ambiguity by asking, never by guessing (/docs/maintain/adr/ADR-0004-ask-never-guess)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §4

## Context [#context]

The cheapest failure for an agent is to pick something plausible and move on. The assumption
looks finished, gives no signal it was made, and is found late. On a documentation site the
damage is public: a plausible guess about an install command, a function signature, a default
option or a supported runtime is published as fact and copied into other people's code. A
guess about whether a project is private publishes it.

The owner prefers to be questioned with **selectable options**, not open-ended prompts.

## Decision [#decision]

1. **Classify the question first.**
   - *Verifiable* (framework API, library behaviour, existing code, config, what a documented
     package exports or requires): **check it** in `node_modules/next/dist/docs/`, the
     installed Fumadocs source and types, the config, or the documented package's own source
     and manifest. Don't assert from memory and don't ask the owner.
   - *Undetermined* (product behaviour, scope, priority, naming, content structure, public
     versus private, trade-offs): **ask**.
2. **Every question carries** the decision in one line and why it can't be settled from the
   code or documents; two to four concrete options with their consequences; a recommendation
   listed first and marked; and what each option builds, costs and forecloses. Use a selectable
   options tool where available.
3. **No silent assumptions.** Work that proceeds on an assumption states it in the response and
   in the ADR or design document it shapes.
4. **Ask at ADR time**, in *Options considered*. Mid-implementation: finish what doesn't depend
   on the answer, then ask.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Ask with options + recommendation; check what is checkable | Owner answers by picking; decisions recorded; no noise for verifiable facts | Some interruptions | Chosen |
| B — Agent decides and documents | Fewer interruptions | Wrong guesses look like right ones, and get published | Rejected |
| C — Ask everything open-ended | Maximum control | Slow; owner asked for options | Rejected |

## Consequences [#consequences]

**Positive**

- Content, structure and privacy decisions stay with the owner and are written down.
- Published facts about packages are read from their source, not recalled.

**Negative / accepted trade-offs**

- More questions at ADR time. Accepted: that is the cheapest moment for them.

## Content invariants [#content-invariants]

Protects all of `AGENTS.md` §6 by routing any ambiguity about them to the owner; directly
enforces §6.2 (documentation is checked against the code).

## Security considerations [#security-considerations]

Security, privacy and visibility questions are always *undetermined* and always asked
(ADR-0005).

## Implementation notes [#implementation-notes]

- [x] `AGENTS.md` §4 states the rule.
- Tests: not applicable (process only).

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

- [x] `content/docs/maintain/adr/index.mdx` — status.


# ADR-0005 — Security and privacy are a standing practice (/docs/maintain/adr/ADR-0005-security-as-a-standing-practice)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §9, `content/docs/maintain/security/index.mdx`, `threat-model.mdx`,
  `data-classification.mdx`, `secrets.mdx`, `checklist.mdx`, `content/docs/maintain/_templates/security.mdx`

## Context [#context]

The site documents public packages and will also document **private projects**. Today every
page in `content/` is published on several surfaces at once: the rendered page, its
Markdown version, `llms.txt` / `llms-full.txt`, the `static.json` record list, an Open Graph
image, and the Algolia index, which anyone holding the public search-only key can read in full.
A private page placed there is public the moment the site is built.

The build also holds a write key to the search index, and documentation examples are a natural
place for a real token or internal hostname to slip in.

Security added before launch, as a one-off review, misses the decisions made along the way.

## Decision [#decision]

1. **Security is a property of every change.** Every ADR has a mandatory *Security
   considerations* section. "None" is a valid answer; an omitted section is not.
2. **The owner decides security and privacy questions** — which projects are private, who may
   read them, what is sent to a third party, what an example may contain — and they are
   recorded (ADR-0004).
3. **A per-change checklist** (`AGENTS.md` §9) is run for the rows a change touches.
4. **Full audits** (`content/docs/maintain/security/checklist.mdx`) run before the first internet-reachable
   deployment and before each release.
5. **Living security documents** in `content/docs/maintain/security/`: threat model, data classification,
   secrets inventory, audit checklist, and per-feature analyses when warranted.
6. **Tool-specific rules arrive with the tool.** The ADR adopting a host, analytics, CI or an
   authentication provider adds its checks to `checklist.mdx`.
7. **Principles that hold regardless of stack**: no secret literals; anything in the browser or
   the search index is public; authorization server-side; published is permanent; no secrets or
   personal data in logs or responses; generic client errors; a publishing build refuses to run
   without its secrets.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Standing practice, per-change checks, gated audits | Decisions are made deliberately when they are cheapest | Overhead on each ADR | Chosen |
| B — Pre-launch security review only | Less overhead | Misses design-time decisions; a published private page cannot be recalled | Rejected |

## Consequences [#consequences]

**Positive**

- How private documentation is kept and served is designed in, not patched on.

**Negative / accepted trade-offs**

- Every ADR is longer. Accepted.

## Content invariants [#content-invariants]

Directly supports §6.1 (private stays private) and §6.4 (examples carry no real credentials or
data).

## Security considerations [#security-considerations]

This ADR is the security policy. The data classification levels in
`content/docs/maintain/security/data-classification.mdx` are **proposed** with it and become binding on approval.

## Implementation notes [#implementation-notes]

- [x] `content/docs/maintain/security/` files exist and describe the current surface.
- [x] `AGENTS.md` §9 holds the per-change checklist.
- [x] `content/docs/maintain/_templates/security.mdx` exists.
- [x] Add `.env.example` with the three Algolia variables, names only.
- Tests: not applicable (process only).

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

- [x] `content/docs/maintain/security/data-classification.mdx` — mark the levels approved.
- [x] `content/docs/maintain/adr/index.mdx` — status.


# ADR-0006 — Agent skills are advisory; this repository's documentation is binding (/docs/maintain/adr/ADR-0006-agent-skills-are-advisory)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §12

## Context [#context]

Contributors have a library of installed skills (brainstorming, debugging, planning, TDD,
technical writing, security review, UI design…). Used, they make work consistent. But they are
written for generic projects, and several carry process opinions that contradict this
repository: a brainstorming skill that writes specs to its own folder and commits them, a
planning skill that proceeds straight to implementation, skills that add dependencies or deploy
freely.

## Decision [#decision]

1. **Use skills**: invoke any skill that fits, and name it. Process skills come before
   implementation skills.
2. **Precedence**: `AGENTS.md` and `content/docs/maintain/` are binding; skills are advisory; default behaviour
   comes last.
3. **No skill grants a permission this repository withholds**: code before approval, commits,
   new dependencies or tooling, a different docs layout, *what*-comments, security or privacy
   decisions, `NEXT_PUBLIC_` variables or integrations, publishing (a production build, a
   deploy, a search-index write), and framework claims from recall.
4. **Skills stop at the gate**: a workflow that ends in "implement" ends here at
   `Status: Proposed`.
5. **Report what was dropped**: when a rule cuts a skill short, say which skill, which step,
   and which rule.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Skills advisory, repo docs binding | Method from skills, authority from the repo | Agents must reconcile the two | Chosen |
| B — Skills binding | Simple | Skills would bypass the ADR gate and commit rule | Rejected |
| C — No skills | No conflicts | Loses consistent method | Rejected |

## Consequences [#consequences]

**Positive**

- Consistent method without giving up the gate.

**Negative / accepted trade-offs**

- Some skill steps are routinely dropped (spec folders, commits) and must be reported.

## Content invariants [#content-invariants]

None directly.

## Security considerations [#security-considerations]

Prevents skills from making security or privacy decisions, adding integrations or publishing on
the owner's behalf.

## Implementation notes [#implementation-notes]

- [x] `AGENTS.md` §12 holds the precedence and the "no skill authorises" table.
- Tests: not applicable (process only).

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

- [x] `content/docs/maintain/adr/index.mdx` — status.


# ADR-0007 — Tests are part of every change (/docs/maintain/adr/ADR-0007-tests-are-part-of-every-change)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §3, §5, §11

## Context [#context]

Most of this site is content, but the code around it decides what is published and where: the
content loader, the Markdown and `llms.txt` routes, the search records and their sync, and —
once private documentation exists — whatever keeps private pages off public surfaces. Errors
there are silent: a page goes missing from search, or a private page appears in it.

No test runner is installed. Bun is the package manager and has a built-in test runner; the
choice of runner is left to its own ADR so it can be weighed against what the site's code needs.

## Decision [#decision]

1. **Every change ships tests** for its happy path and its obvious failure paths — empty or
   missing input, the boundary and the first value past it, the wrong shape or an unknown
   value, and **the rejection the code exists to perform** (a private page refused, a malformed
   frontmatter rejected). Part of being done, not a follow-up.
2. **A bug fix starts with a test that fails for the bug's reason.**
3. **A test must have been seen to fail** (written first, or checked by breaking the code)
   before it counts.
4. **The runner is chosen by its own ADR**, before the first code change that needs tests.
   Until then, a change is verified with `bun run lint`, `bun run types:check` and
   `bunx next build`, and the ADR's implementation notes say what was verified instead.
5. **Unit tests are pure**: no live search index, network or real private content. Fixtures are
   invented.
6. **Content is verified by the build.** `bunx next build` fails on invalid MDX or frontmatter;
   link and example checks, if wanted, are decided by their own ADR.
7. **Exempt from unit tests**: config modules, pure layout and styling. Anything that needs a
   browser says so in the ADR's implementation notes, with what was verified instead.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Tests with every change; runner chosen by its own ADR | The rule holds from now; the runner is a deliberate choice | No runner until that ADR lands | Chosen |
| B — Pick a runner in this ADR | Tests can start immediately | Decides tooling before there is code that needs it | Rejected |
| C — Tests optional for small changes | Faster small changes | Publishing bugs hide in small changes | Rejected |

## Consequences [#consequences]

**Positive**

- The code that decides what is published has a safety net from its first line.

**Negative / accepted trade-offs**

- Every change takes longer. Accepted.

## Content invariants [#content-invariants]

Guards §6.1 (private stays private) and §6.5 (every page readable as Markdown) through tests on
the code that serves them.

## Security considerations [#security-considerations]

Tests must never contain a real secret, a real search key, or private project content.
Visibility code is tested for refusals, not only for success.

## Implementation notes [#implementation-notes]

- [ ] A test-runner ADR before the first code change that needs tests: [ADR-0021](./ADR-0021-tests-run-with-bun-test.mdx),
      proposed 2026-11-01. ADR-0018 and ADR-0019 shipped with hand checks only; their checks become the
      first tests once ADR-0021 is approved.
- Tests: not applicable (process only).

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

- [ ] `AGENTS.md` §5 — the runner and its command, once its ADR is approved.
- [ ] `README.md` scripts — the test command.
- [x] `content/docs/maintain/adr/index.mdx` — status.


# ADR-0008 — A UI change ships an app flow, drawn in Mermaid (/docs/maintain/adr/ADR-0008-a-ui-change-ships-an-app-flow)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `content/docs/maintain/app-flow/index.mdx`, `content/docs/maintain/_templates/app-flow.mdx`, `AGENTS.md` §2

## Context [#context]

An ADR's text says what is decided. It rarely shows what a reader will see, and UI mistakes
(a missing state, a confusing navigation, a buried install command) are cheapest to catch
before code. A documentation site lives or dies on how fast a reader gets from a search or a
package name to the snippet they need.

The owner wants diagrams, flows and screens drawn in **Mermaid**: flowcharts for flows and
`block-beta` diagrams for wireframes.

## Decision [#decision]

1. **Any ADR that adds or changes something a person sees ships
   `content/docs/maintain/app-flow/<feature-slug>.mdx`**, reviewed together with the ADR.
2. It contains:
   - **entry points**, and who does not see the feature;
   - **the flow** as a Mermaid flowchart;
   - **one wireframe per screen** as a Mermaid `block-beta` diagram, phone width first, with
     invented sample values;
   - **each screen's states**: empty, loading, not found, refused, error, degraded, success.
3. **One file per feature, living** (ADR-0002): later ADRs that change the feature's UI edit it
   in place.
4. Not required for bug fixes, for content within the approved conventions, or for ADRs that
   change nothing visible. If unsure, write it.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Mermaid flow + `block-beta` wireframes | Matches the owner's instruction; renders on GitHub; diffs as text | `block-beta` is coarse for detailed layout | Chosen |
| B — Plain-text ASCII mockups | Precise layout; no renderer needed | Doesn't match the owner's instruction | Rejected |
| C — Design tool images | High fidelity | Binary, external, don't diff, drift | Rejected |

## Consequences [#consequences]

**Positive**

- The owner reviews what readers will see, not just what will be built.

**Negative / accepted trade-offs**

- Wireframes are approximate; visual design is decided in its own ADR(s).

## Content invariants [#content-invariants]

Supports §6.5 (every page readable as Markdown) by putting each page type's Markdown entry
points up for review with the screens.

## Security considerations [#security-considerations]

Wireframes use invented values only — never a private project's name or details.

## Implementation notes [#implementation-notes]

- [x] `content/docs/maintain/app-flow/index.mdx` and `content/docs/maintain/_templates/app-flow.mdx` exist.
- [x] `AGENTS.md` §2 describes the requirement.
- Tests: not applicable (process only).

> Approved as written on 2026-11-01, by the owner's choice. `AGENTS.md` §2 and §8 add, by the
> owner's standing choice, that the flow is made with Archify with its Mermaid version kept in
> the page; HTML prototypes are not made.

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

- [x] `content/docs/maintain/adr/index.mdx` — status.


# ADR-0009 — Trusted agent skills are vendored in .claude/agent-skills/, routed by an index (/docs/maintain/adr/ADR-0009-trusted-agent-skills-are-vendored)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `.claude/agent-skills/INDEX.md`, `.claude/agent-skills/SOURCES.md`,
  `AGENTS.md` §12, [`../index.mdx`](../index.mdx)

## Context [#context]

ADR-0006 makes skills advisory and this repository binding. Two problems remain:

- **Trust.** Skills are instructions an agent follows. Registries hold hundreds of thousands of
  them, most from unknown authors, some without a licence. A malicious or careless skill is a
  supply-chain risk: it can tell an agent to run commands, exfiltrate data, or quietly bypass
  this repository's rules.
- **Context cost.** Loading many skills at once wastes the model's context and blurs which
  guidance applies. The owner wants agents to load only what a task needs.

Only trusted skills may be used: ones trusted by many, ones from the owner of the package,
library or service they cover, or ones from another source of high trust. Untrusted ones must be
put to the owner with better alternatives. `AGENTS.md` always ranks above skills.

The skills are tooling for contributors, not documentation for readers, so they do not belong
in `content/`, where every file is published (ADR-0002).

## Decision [#decision]

1. **Trusted skills are vendored** — copied into
   `.claude/agent-skills/<owner>-<repository>/<upstream path>` at a pinned upstream commit, with
   the upstream licence and unmodified files. Upstream paths are kept so a skill's relative
   links resolve. JavaScript/TypeScript files are omitted so lint and the build ignore the
   folder; omissions are listed.
2. **A skill is trusted** when at least one holds: it comes from the owner of what it covers
   (the maintainer of a package, library or service this site uses); it is trusted by many
   (wide, visible adoption from a recognised maintainer); or its source has otherwise high
   trust (an established security or engineering reputation, the agent's own vendor). It must
   also be licensed for copying, scanned, and pinned.
3. **`.claude/agent-skills/SOURCES.md`** records the trust policy, every source (repository,
   commit, date, licence, trust basis), what was read in full and what was scanned, omissions,
   rejected candidates, and how to update.
4. **`.claude/agent-skills/INDEX.md` is the router.** Agents read it, then load only the one or
   two `SKILL.md` files their task needs. Its *Overrides* state how each conflicting skill
   instruction is handled here, generally and per skill.
5. **Not `.claude/skills/`.** Claude Code auto-loads skills from `.claude/skills/`; these are
   read through the index instead, so the overrides are applied every time and nothing loads
   unasked.
6. **In-house skills**, when the owner wants one, live in `.claude/agent-skills/local/` and are
   reviewed like any design document.
7. **Untrusted skills are not used.** Anything not in this folder, including skills installed
   as plugins, needs the owner's approval first. The request names the trusted alternatives.
   Where an installed plugin has a skill of the same name, the pinned copy wins.
8. **The set grows as work needs it, with the owner's yes first.** An agent that finds a task
   better served by a skill that is not vendored proposes trusted candidates, with a
   recommendation. Nothing is cloned, downloaded or added until the owner approves
   (`SOURCES.md` § Adding a skill).
9. **Owner-approved installed skills are the exception to vendoring.** The owner approved skill
   sets that they install themselves: impeccable, ui-ux-pro-max, the taste skills, hallmark and
   Archify. They are listed in `SOURCES.md` and routed, with overrides, in `INDEX.md`.
   They are not pinned, so they are re-reviewed after an update.
10. **Remote instructions are pinned.** A skill that fetches its rules at run time uses a pinned
   local snapshot instead.
11. **Precedence is unchanged:** `AGENTS.md` > ADRs and `content/docs/maintain/` > skills >
   default behaviour.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Vendor pinned copies in `.claude/agent-skills/` + index router | Reviewed content; immune to upstream changes; minimal context via routing; works for any agent; not published | Manual updates; repository size grows (~1 MB) | Chosen |
| B — Vendor into `.claude/skills/` for auto-loading | Skills appear in the agent's skill list | Every skill's description loads into every session; the overrides can be skipped | Rejected |
| C — Vendor into `content/docs/maintain/agent-skills/` | Visible on the site | Published to the site, search index and `llms.txt`; third-party text presented as this site's documentation | Rejected |
| D — Install from registries (`npx skills add`) per machine | Always current | Unpinned; content can change under us; differs by machine; harder to review | Rejected |
| E — Link to upstream only | No copying | Agents fetch live, unreviewed instructions | Rejected |

## Consequences [#consequences]

**Positive**

- Every instruction an agent follows from a skill has been read or scanned, pinned and
  attributed.
- Agents load a small, task-specific slice of guidance.

**Negative / accepted trade-offs**

- Vendored skills go stale; updates are a deliberate review (`SOURCES.md` § Updating).
- Some skills duplicate installed plugins; the index states the pinned copy wins.
- The approved installed UI/UX skills are not pinned: an update can change what an agent
  follows before anyone re-reviews it.
- An agent that does not read `AGENTS.md` will not find the skills; `AGENTS.md` §12 points to
  the index.

## Content invariants [#content-invariants]

None directly. The overrides protect the process rules (no commits, ADR gate, no unapproved
dependencies, secrets or publishing).

## Security considerations [#security-considerations]

This decision is a supply-chain control. Vendored content is scanned for command execution,
network calls, credential handling and instruction-override text before copying. Findings are
neutralised by the overrides in `INDEX.md`. Bundled scripts are never run without approval: the
supply-chain auditor's scripts call registry, advisory and GitHub APIs and read `gh auth token`.
Licences with attribution or share-alike terms (CC-BY-SA-4.0 for the Trail of Bits skill) apply
to the files they cover. `.claude/` is not under `content/`, so none of it is published.

## Implementation notes [#implementation-notes]

- [x] `.claude/agent-skills/INDEX.md` and `SOURCES.md` exist, with the trust policy and
      overrides.
- [x] The first sources are vendored, scanned, recorded in `SOURCES.md` and routed in
      `INDEX.md`: obra/superpowers, addyosmani/agent-skills, vercel-labs/agent-skills (with the
      writing and web-interface guideline snapshots), vercel/next.js, anthropics/skills,
      mattpocock/skills, trailofbits/skills, algolia/skills.
- [x] The owner reviewed the selection and accepted vercel-labs/agent-skills, which states MIT
      in its README but has no `LICENSE` file (2026-11-01).
- [x] ESLint ignores `.claude/**` (`eslint.config.mjs`), by the owner's decision: installed skills
      (hallmark, design-taste-frontend v2) ship `.mjs` scripts and `.tsx` fixtures there.
- Tests: not applicable (documentation). Verified that no `.js`, `.cjs`, `.mjs`, `.ts`, `.tsx`
  or `.jsx` file is vendored, and that `bunx next build` is unaffected.

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

- [x] `AGENTS.md` §10, §11, §12
- [x] `README.md` — project structure, skills, decisions table
- [x] [`../index.mdx`](../index.mdx) — directory map
- [x] [`./index.mdx`](./index.mdx) — title
- [x] [`./index.mdx`](./index.mdx) — status on approval


# ADR-0010 — Projects document themselves here through a git submodule, one folder each (/docs/maintain/adr/ADR-0010-projects-document-themselves-through-a-submodule)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** [ADR-0024](./ADR-0024-a-project-can-span-several-repositories.mdx) (in part:
  decision 2 for a project with several repositories: each edits its own folders, the primary
  the shared files)
- **Design documents:** `PROJECT_AGENTS.md`,
  [`../app-flow/package-navigation.mdx`](../app-flow/package-navigation.mdx),
  [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx), `AGENTS.md` §1, §8

## Context [#context]

The owner's project and package repositories will include this repository as a git submodule
and maintain their own documentation in it. Their agents then work inside this repository
without having read its working agreement, from a repository whose rules differ.

Three things are undecided without this ADR: where a project's pages go (the per-project
content layout is open, `AGENTS.md` §1), how changes made in a submodule come back, and what
a private project may put here. Every file under `content/` is published (ADR-0002, §6.1),
and a consuming repository may be private.

## Decision [#decision]

1. **One folder per project or package**: `content/<project-slug>/`, published at
   `/<project-slug>`, in the shape of ADR-0013 and ADR-0015. Readers reach it from the home page,
   search and the header. The slug is agreed with the owner when the folder is first created.
2. **Consuming repositories edit only their own folder.** Any other change, such as another
   project's pages, `src/`, configuration, dependencies or this site's documents, is a change
   to the site and goes through ADR-0001.
3. **Edit only; a human commits.** An agent in a consuming repository never commits, pushes,
   rebases or switches branches inside the submodule, and never moves the submodule pointer. It
   lists its changes and hands the human the commands.
4. **Public only until private documentation is decided.** A private project keeps its
   documentation in its own repository and adds nothing here, until an ADR decides how private
   documentation is stored, served and searched.
5. **`PROJECT_AGENTS.md`** at the repository root is the guide for consuming repositories,
   with a block each one pastes into its own `AGENTS.md` / `CLAUDE.md`. It changes in the same
   change as anything that alters how they work here, and so does `AGENTS.md`.
6. **Writing pages inside a project's folder needs no ADR**, within this guide and the content
   invariants.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Layout | A — `content/<slug>/` folder per project | Self-contained; a consumer touches one folder; this site is one too (`docs`) | Every slug shares the root with the site's routes, so some are reserved (ADR-0015) | Chosen |
| Layout | B — grouped: `projects/<slug>/`, `packages/<ecosystem>/<slug>/` | Browsable by kind and ecosystem | Deeper paths; the grouping itself needs deciding | Rejected |
| Layout | C — a separate content-layout ADR first | Decides everything at once | Consumers wait | Rejected |
| Git flow | A — edit only, a human commits | Same rule as this repository; a person reviews every change before it is published | Manual steps for every update | Chosen |
| Git flow | B — the agent commits on a branch and opens a pull request | Reviewable and traceable | Agents commit, against `AGENTS.md` §3 | Rejected |
| Git flow | C — the agent commits and pushes to `main` | Fastest | No review before publishing | Rejected |
| Private | A — not yet; private projects keep docs locally | Nothing private can leak | Private projects get no site yet | Chosen |
| Private | B — draft the private-documentation ADR now | Starts the design | Private consumers still wait for it | Deferred |
| Private | C — this site stays public only, permanently | Simplest | Contradicts the site's purpose (`AGENTS.md` §1) | Rejected |
| Guide | `PROJECT_AGENTS.md` + a paste-in block | Short and separate; consumers' agents find it from their own instructions | A second file to keep in step with `AGENTS.md` | Chosen |

## Consequences [#consequences]

**Positive**

- Each project's documentation lives next to its code and is published in one place.
- A person reviews every change before it reaches a public surface.

**Negative / accepted trade-offs**

- Every update needs a manual commit in the submodule and a pointer bump in the project.
- Private projects have no documentation here until a later ADR.
- Projects are found from the home page and search, not a sidebar switcher; a large number may
  need grouping later (a new ADR).

## Content invariants [#content-invariants]

All five apply to every consuming repository's pages; `PROJECT_AGENTS.md` §4 restates them.
Invariant 1 is the reason for decision 4.

## Security considerations [#security-considerations]

- **Trust boundary.** Content moves from consuming repositories, some of them private, into
  this public site. The controls are: private repositories add nothing (decision 4); public
  pages carry no secrets, internal hostnames, client names, personal data or copied private
  code (`PROJECT_AGENTS.md` §2); and a human reviews and commits every change (decision 3).
- **Scope.** Consuming agents may only edit their own folder (decision 2), so a consuming
  repository cannot change routes, the search sync or another project's pages.
- **Publishing.** Consumers verify with `bunx next build` and never run `bun run build`, which
  writes to the live search index.

## Implementation notes [#implementation-notes]

- [x] `PROJECT_AGENTS.md` written with the paste-in block.
- [x] App flow: [`../app-flow/package-navigation.mdx`](../app-flow/package-navigation.mdx) and
      [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx).
- [ ] On approval: the first consuming project's folder, with the slug agreed with the owner.
- [x] On approval: `../dfd/system.mdx` gains consuming repositories as a source, across the
      trust boundary.
- Tests: the catalogue build checks (ADR-0015 decision 5) fail on a folder without a `catalog`;
  automated tests belong with the test runner chosen under ADR-0007.

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

- [x] `AGENTS.md` §1, §8, §10
- [x] `README.md` — project structure, decisions table
- [x] [`./index.mdx`](./index.mdx) — index row, next free number
- [x] [`./index.mdx`](./index.mdx) — status on approval


# ADR-0011 — Archify diagrams are embedded in pages from sandboxed HTML files (/docs/maintain/adr/ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** [ADR-0002](./ADR-0002-living-design-documentation.mdx) decision 5 (in part:
  rendering diagrams on the site)
- **Superseded by:** [ADR-0022](./ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown.mdx) decisions 1 to 3
- **Design documents:** [`../app-flow/diagrams.mdx`](../app-flow/diagrams.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx),
  [`../api/content-routes.mdx`](../api/content-routes.mdx),
  [`../security/threat-model.mdx`](../security/threat-model.mdx), `AGENTS.md` §8,
  `PROJECT_AGENTS.md` §3, §4

## Context [#context]

Diagrams and flows for this site's pages are always made with Archify (`AGENTS.md` §8), which
writes one standalone HTML file per diagram. Every page keeps a Mermaid version of each diagram
and screen wireframe, so it stays readable as Markdown. Until this ADR is decided, the HTML
stays out of `content/` and `public/`.

HTML prototypes of an app flow's screens are not made: by the owner's decision (2026-11-01),
an app flow's screens are Mermaid `block-beta` wireframes only.

Facts this decision rests on, checked against the installed packages and tools:

- **Archify 3.2.0 output.** `deliver` writes `<stem>.html` and a receipt,
  `<stem>.delivery.json`, holding absolute local paths (`/Users/…/candidate.json`). The HTML
  holds none. It loads no external script, stylesheet or image, and calls no network API
  (`fetch`, `XMLHttpRequest`, `WebSocket`, `sendBeacon`). It keeps only the reader's theme and
  motion choice in `localStorage`, inside `try`/`catch`, written for sandboxed frames. The
  seven-node workflow made for this ADR is 819 KB. On narrow screens Archify gives
  "containment only" (`references/viewer-runtime.md`).
- **Pages are MDX** (ADR-0012), so a page can use a component registered in
  `src/components/mdx.tsx`. In the Markdown surfaces a component stays as its JSX tag with its
  props (checked in the built `llms.mdx` output for `<Cards>`).
- **Serving.** Files in `public/` are served from `/`. `headers()` in `next.config.mjs` applies
  to them ("Headers are checked before the filesystem which includes pages and `/public`
  files"). Pages live at the root, `/<slug>/…`, and `src/proxy.ts` acts only on paths whose
  first segment is a catalogued slug (ADR-0015).

## Decision [#decision]

1. **Where the files live.** The Archify candidate is the committed source,
   `diagrams/<project-slug>/<slug>.json` (not published); the published file is
   `public/diagrams/<project-slug>/<slug>.html`. This site's own files use its slug, `docs`.
   On approval, `diagrams` joins the reserved slugs of ADR-0015 decision 2, so no entry's pages
   share a first segment with these files and the Markdown rewrites in `src/proxy.ts` never
   apply.
2. **Archify is delivered and checked outside the published folders**, with `deliver` and
   `check --require-provenance` into `.archify/` (gitignored), as `AGENTS.md` §8 sets out. Only
   the HTML is copied, byte for byte. Receipts, pending journals and lock files never are: they
   carry local paths.
3. **Pages embed them with one MDX component**, `<HtmlEmbed>`, registered in
   `src/components/mdx.tsx`:

   ```mdx
   <HtmlEmbed src="/diagrams/example-cli/request-flow.html" title="Request flow" />
   ```

   - An `<iframe>` with `sandbox="allow-scripts allow-downloads"`, without
     `allow-same-origin`, `loading="lazy"` and the required `title`, at the content width and
     a fixed height.
   - Below the frame: an **Open full screen** link to the file, and the title as a caption.
   - `src` must start with `/diagrams/` and end in `.html`; anything else fails the build.
   - The Mermaid version stays in the page, directly above the embed.
4. **Direct visits are sandboxed too.** `next.config.mjs` serves `/diagrams/:path*` with
   `Content-Security-Policy: sandbox allow-scripts allow-downloads`, so opening a file through
   **Open full screen** or a shared URL gives the same isolation as the frame.
5. **Consuming repositories may write their own**: `diagrams/<project-slug>/` and
   `public/diagrams/<project-slug>/`, alongside `content/<project-slug>/`. This widens
   ADR-0010, decision 2.
6. **Not indexed.** The HTML files are not part of `static.json`, the search index or
   `llms.txt`. Search finds the page through its text and Mermaid version.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Embed | A — `<HtmlEmbed>` MDX component | Works on every page (ADR-0012); one place for sandboxing and fallbacks | A component to maintain | Chosen (owner) |
| Embed | B — a remark plugin turning a link into an iframe | Pages need no component | Custom build code | Rejected |
| Archify display | A — embedded in the page | The diagram is where it is discussed | 819 KB per diagram on the page (loaded lazily); cramped at phone width, where Archify gives containment only; zoom and scroll inside a frame | Chosen (owner) |
| Archify display | B — a link to the diagram as its own page | Full screen for exploring; nothing heavy on the page | Readers leave the page | Rejected; **Open full screen** gives the same view |
| Source | A — Archify candidate JSON in `diagrams/` | Text diffs; regenerated after an upgrade | A second folder per project | Chosen |
| Source | B — next to the page in `content/` | One folder | That folder is what Fumadocs loads and publishes | Rejected |
| Isolation | A — iframe `sandbox` and a CSP `sandbox` header | Generated script cannot touch the site's origin, now or after sign-in exists | Theme choice inside a diagram is not remembered; clipboard copy may be refused (checked on implementation) | Chosen |
| Isolation | B — none | Every viewer feature works | Third-party script with the site's origin | Rejected |
| Isolation | C — a separate origin | Strongest | Needs a hosting decision first | Deferred |

## Consequences [#consequences]

**Positive**

- Readers see the diagram in the page, and can open it full screen.
- Markdown readers and tools keep the Mermaid versions and the component tag with its URL.

**Negative / accepted trade-offs**

- Two versions of each diagram, Mermaid and HTML, can drift. Both change in the same change and
  are reviewed together.
- A page with an Archify diagram loads about 0.8 MB once the frame scrolls into view.
- At phone width an embedded diagram is small; the reader uses **Open full screen**.
- An Archify upgrade changes the generated HTML: diagrams are delivered again, and the checks
  below run again.
- The embed component is new site code with its own tests.

## Content invariants [#content-invariants]

- **1 (Private stays private).** A diagram of a private project is private content: none goes
  into `diagrams/` or `public/diagrams/`. `public/` is published.
- **4 (Examples run).** Labels and sample content are invented.
- **5 (Readable as Markdown).** Kept: the Mermaid version stays in the page, and the
  component's tag, with its `src`, appears in the Markdown output.

## Security considerations [#security-considerations]

- **What is published.** Every HTML file under `public/diagrams/` is public. It is written from
  public information only (invariant 1).
- **Local paths.** Only Archify's HTML is copied, never its receipts (decision 2). A check
  fails the build if any `*.delivery*.json` file is under `public/`.
- **Script in the page.** Diagrams run Archify's generated script in an opaque origin, by the
  iframe sandbox and the CSP header (decisions 3 and 4), so it cannot read the site's cookies or
  storage or act as the site.
- **`src` is fixed to one folder** (decision 3), so a page cannot embed another site or an
  arbitrary path.
- **Nothing leaves the system.** Checked for Archify 3.2.0: no external resources and no
  network calls. The same scan runs on every Archify upgrade.
- **Residual risk.** A future Archify release could add a network call; the sandbox does not
  block outgoing requests. Accepted, because each upgrade is scanned and reviewed.

## Implementation notes [#implementation-notes]

- [x] App flow: [`../app-flow/diagrams.mdx`](../app-flow/diagrams.mdx), its flow made
      with Archify.
- [x] `src/components/html-embed.tsx`, registered in `src/components/mdx.tsx` (decision 3). It
      also fails the build when the file is missing from `public/` or the title is empty.
- [x] `next.config.mjs`: the `headers()` entry for `/diagrams/:path*`, with a comment linking
      this ADR. Checked against `next start`: the file is served with
      `Content-Security-Policy: sandbox allow-scripts allow-downloads`.
- [x] `diagrams` added to the reserved slugs (`src/lib/catalog-plugin.ts`).
- [x] The build checks in `src/lib/diagrams.ts`, run by a loader plugin
      (`src/lib/diagrams-plugin.ts`): a published diagram needs its JSON source, only
      `<project-slug>/<slug>.html` belongs under `public/diagrams/`, and no `*.delivery*.json`
      may be under `public/`.
- [x] This site's seven diagrams published to `diagrams/docs/` and `public/diagrams/docs/`
      (html-embeds, site-pages, package-navigation, solar-system, docs-sidebars,
      adr-constellation, package-version-lifecycle), each embedded under its Mermaid version.
      Each passed `check --require-provenance` and a scan for local paths and network calls.
      The html-embeds flow was delivered again first: its source still named prototypes.
- [ ] When the owner first opens it in a browser: the frame loads under the sandbox, PNG and
      SVG downloads work, and whether clipboard copy works is recorded in the app flow.
- [x] Tests (ADR-0007, runner ADR-0021): `src/components/html-embed.test.tsx` (the sandboxed
      frame and full-screen link; a `src` outside `/diagrams/`, an unpublished file, an empty
      title) and `src/lib/diagrams.test.ts` (allowed and refused `src` values, a receipt
      anywhere under `public/`, a diagram without its source, a stray file, and the loader
      plugin passing and failing on a fixture folder).
- [ ] `bun run lint`, `bun run types:check` and `bunx next build` pass.

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

- [x] [`../app-flow/diagrams.mdx`](../app-flow/diagrams.mdx)
- [x] [`../architecture/system.mdx`](../architecture/system.mdx): diagram sources, the embed
      component
- [x] [`../api/content-routes.mdx`](../api/content-routes.mdx): `/diagrams/…`, public, static,
      sandboxed
- [x] [`../security/threat-model.mdx`](../security/threat-model.mdx): the attack-surface table;
      [`../security/checklist.mdx`](../security/checklist.mdx): Archify rows under
      tool-specific checks
- [x] `AGENTS.md` §8 (where the files go, the component, the copy step) and §10 (`diagrams/`,
      `public/`)
- [x] `PROJECT_AGENTS.md` §3 and §4: consumers' folders and the component
- [x] `.claude/agent-skills/INDEX.md`: the Archify override, which today keeps the HTML out of
      `public/` until this ADR
- [x] `README.md`: project structure
- [x] [`./index.mdx`](./index.mdx): status on approval


# ADR-0012 — Every page in content/docs is MDX (/docs/maintain/adr/ADR-0012-every-page-is-mdx)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz), by direct instruction ("change all content/docs to mdx
  supported pages, so that components can be used when required")
- **Approved on:** 2026-10-31
- **Supersedes:** [ADR-0002](./ADR-0002-living-design-documentation.mdx) decision 4 (pages are
  `.md`)
- **Superseded by:** —
- **Design documents:** `AGENTS.md` §8 (*Format of a page*), `PROJECT_AGENTS.md` §4

## Context [#context]

Pages in the Documentation project were `.md`. `fumadocs-mdx` compiles a file as plain
Markdown unless its name ends in `.mdx` (`const format = filePath.endsWith(".mdx") ? "mdx" : "md"`),
so a `.md` page cannot use a component. Embedding prototypes and diagrams in pages (ADR-0011)
needs components, and so may later package pages. The owner asked for every page to support
them.

## Decision [#decision]

1. **Every page under `content/docs/` is `.mdx`.** New pages and templates are `.mdx`; links
   between pages name the `.mdx` file (`./adr/index.mdx`).
2. **Pages stay Markdown first.** A component is used only where it does something Markdown
   cannot. The components available are those registered in `src/components/mdx.tsx`; adding
   one is a site change with its own ADR.
3. **MDX syntax rules in prose:** a `<slug>`-style placeholder goes in backticks or is escaped
   (`\<slug>`); void tags are closed (`<br />`); comments are `{/* … */}`. Code blocks and
   frontmatter are unaffected.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — every page `.mdx` | One format; any page can take a component without a rename later | `<` and `{` in prose must be escaped | Chosen (owner's instruction) |
| B — `.mdx` only for pages that use a component | Plain Markdown stays the default | Two formats; renaming a page changes every link to it | Rejected |
| C — keep `.md`, add a remark plugin for embeds | No renames | Custom build code; components still unavailable elsewhere | Rejected |

## Consequences [#consequences]

**Positive**

- Any page can use a registered component.
- One page format for this site and for consuming repositories.

**Negative / accepted trade-offs**

- Prose must follow MDX syntax; a stray `<word>` or `{` breaks the build. The build catches it.
- In the Markdown surfaces, an escaped placeholder appears as `\<what changes>`, which renders
  correctly as Markdown.

## Content invariants [#content-invariants]

- **5 (Readable as Markdown).** Kept: the per-page Markdown and `llms-full.txt` are generated
  from the processed MDX. A component's Markdown fallback is the job of the ADR that adds it.

## Security considerations [#security-considerations]

None — this change renames files and escapes text. It adds no endpoint, data or secret. MDX
can run code at build time, but only code in this repository's pages, which are reviewed.

## Implementation notes [#implementation-notes]

- [x] All 45 `.md` pages under `content/docs/` renamed to `.mdx`.
- [x] Two placeholders escaped in `_templates/adr.mdx`; `<br>` closed in `_templates/prd.mdx`.
- [x] Every relative link and every `content/docs/…` path in pages, `AGENTS.md`, `README.md`,
      `PROJECT_AGENTS.md` and `.claude/agent-skills/` updated to `.mdx`. URLs such as
      `/docs/<page>.md` are routes, not files, and are unchanged.
- [x] `bunx next build`: no unresolved `.md` or `.mdx` links in the rendered pages.
- Tests: a build check that no `.md` file exists under `content/docs/` belongs with the test
  runner chosen under ADR-0007. Until then, the build itself is the check.

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

- [x] `AGENTS.md` §8, *Format of a page*
- [x] `PROJECT_AGENTS.md` §4, format
- [x] [`./index.mdx`](./index.mdx): index row, next free number


# ADR-0013 — Packages and projects share one catalogue shape: two tracks, version lines and demos (/docs/maintain/adr/ADR-0013-packages-and-projects-share-one-catalogue-shape)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-10-31
- **Supersedes:** —
- **Superseded by:** [ADR-0024](./ADR-0024-a-project-can-span-several-repositories.mdx) (in part:
  decision 4's last sentence, a project has at most `dev` and one released line)
- **Design documents:** [`../app-flow/package-navigation.mdx`](../app-flow/package-navigation.mdx),
  [`../state/package-version-lifecycle.mdx`](../state/package-version-lifecycle.mdx),
  [`../prd/home-page.mdx`](../prd/home-page.mdx), `../architecture/system.mdx`,
  `../dfd/system.mdx`, `PROJECT_AGENTS.md`

## Context [#context]

ADR-0010 gives every package and project a root folder, `content/docs/<project-slug>/`, but
leaves open what goes inside it (`AGENTS.md` §1). The home page (ADR-0014) lists the whole
collection, so it needs that answer first. Four facts shape it:

- **Packages have versions.** A package can have several released versions in use and an
  unreleased one in progress. Invariant 3 requires every package page to say which version it
  documents.
- **Two kinds of reader.** People who use a package or project need install steps, guides and
  APIs. The people who maintain it need architecture, local setup, testing and the release
  process. The owner decided on 2026-10-31 that each project has both, as two tracks.
- **Demos.** Some packages, npm ones in particular, need a working demo next to their docs.
- **Private projects.** The site will hold private projects behind sign-in (WorkOS, in a later
  ADR). The owner decided on 2026-10-31 that a signed-out visitor sees nothing of them: no name,
  no count, no placeholder.

What Fumadocs does today, read from the installed source:

- `getSidebarTabs` (`fumadocs-ui/dist/components/sidebar/tabs`) turns every folder with
  `root: true`, nested ones included, into one entry in a single flat switcher. It cannot show
  package → version → track as levels.
- `DocsLayout` takes any `tree` and an explicit `tabs` list or `false`
  (`fumadocs-ui/dist/layouts/docs/index.d.ts`), so a package route can be given only its own
  subtree and its own switches.
- `meta.json` files are validated by `metaSchema` in `src/lib/source.ts`, which can be extended.

## Decision [#decision]

1. **Every root folder declares a catalogue entry** in its `meta.json`, validated by an
   extended `metaSchema`:

   ```json
   {
     "title": "lodestar",
     "description": "Keyboard-first command palette for React.",
     "root": true,
     "catalog": {
       "kind": "package",
       "ecosystem": "npm",
       "visibility": "public",
       "repository": "https://github.com/example/lodestar",
       "registry": "https://www.npmjs.com/package/lodestar",
       "featured": false
     }
   }
   ```

   `kind` is `package` or `project`. `ecosystem` is required for packages: `npm`, `composer`,
   `pypi`, `go`, `cargo` or `other`. `visibility` accepts only `public` until the
   private-documentation ADR adds `private`, so the build **fails** on a private entry instead
   of publishing it. `featured` puts a package with a demo forward on the home page. The
   Documentation project has no `catalog` and is not listed.

2. **Two tracks in every root folder:** `use/` and `maintain/`. Use is for people using the
   package or project: install, guides, API, demo. Maintain is for the people who look after
   it: architecture, local setup, tests, releasing, contributing, its own decisions. A track may
   be missing; the switch then hides it. For a public package or project both tracks are
   public. For a private project both will be private.

3. **A package's Use track has one folder per documented major version, called a line:**
   `use/v3/`, `use/v2/`, and `use/next/` for an unreleased major. Each line's `meta.json` sets
   `version` (the exact version it documents, read from the package's manifest, such as
   `3.2.0` or `4.0.0-beta.3`) and `channel`: `latest`, `next` or `legacy`. A released package
   has exactly one `latest` line and at most one `next`. A package with only `next` is
   unreleased. The lifecycle is in
   [`../state/package-version-lifecycle.mdx`](../state/package-version-lifecycle.mdx).

4. **The Maintain track is not versioned.** It describes the repository's default branch.
   Projects are unversioned by default: their `use/` holds pages directly. A project that ships
   releases may use lines like a package.

5. **URLs follow the folders:** `/docs/<slug>` is the overview (the root folder's
   `index.mdx`); `/docs/<slug>/use/<line>/…` and `/docs/<slug>/maintain/…` are the tracks.
   `/docs/<slug>/use/latest/…` is a stable alias that redirects to the line marked `latest`, so
   READMEs and registry pages can link without going stale. The redirect lives in
   `src/proxy.ts`, which already rewrites `/docs/…` paths.

6. **Navigation inside a package is scoped.** On package and project routes, `DocsLayout`
   receives only the current track and line as its tree. The top of the sidebar holds a track
   switch (Use | Maintain) and a version menu that keeps the reader on the same page when it
   exists in the chosen line. Pages in a `next` line open with an "Unreleased" banner and pages
   in a `legacy` line with an "Older version" banner. Each banner names the exact version and
   links to the same page in `latest`. The site-wide switcher of root folders is replaced by the
   home page catalogue and search; the Documentation project keeps its default layout.

7. **Demos are pages in a line,** `use/<line>/demo.mdx`, that embed a self-contained HTML file
   built by the package's own repository, through ADR-0011's sandboxed embed. The file lives at
   `public/demos/<slug>/<line>/index.html`, so each line demos the version it documents. This
   decision depends on ADR-0011. Until ADR-0011 is approved, no demo is published.

8. **Search and `llms.txt` carry the shape.** Each Algolia record gains `package`, `kind`,
   `ecosystem`, `track`, `line` and `channel`. Search ranks `latest` and Maintain pages first
   and labels `next` and `legacy` results. Each page's Markdown opens with the version it
   documents. `llms.txt` lists every line, labelled.

9. **The build checks the shape** and fails on: a missing or invalid `catalog`; a `private`
   entry; two `latest` or two `next` lines; released lines without a `latest`; a line without a
   `version`.

Decisions 2 and the signed-out rule in *Context* are the owner's (2026-10-31). Decisions 1, 3–9
are proposed here for the owner to confirm.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Audiences | A — two tracks per root folder | One place per project; a reader switches tracks without losing context | Each folder has two trees to keep current | Chosen (owner) |
| Audiences | B — tracks, Maintain always private | Internal notes never public | Outside contributors can't read how to contribute or release | Rejected (owner) |
| Audiences | C — a separate signed-in maintainer hub | Works across projects | A project's two kinds of docs live apart | Rejected (owner) |
| Versions | A — a folder per major line, plus `next` | Matches semver: pages change at majors; Fumadocs needs nothing new; a line can be deleted cleanly | Minor-version differences inside a line are noted in the text | Proposed |
| Versions | B — a folder per exact version | Every release exactly preserved | Dozens of near-identical copies; search full of duplicates | Rejected |
| Versions | C — latest only, older versions from git tags at build time | No copies in the tree | A build step that checks out tags; consumers can't edit old lines in place | Rejected |
| Versions | D — a separate content source per version | Strong isolation | One `defineDocs` per version; heavy for a few packages | Rejected |
| Maintain versioning | A — unversioned, the default branch | Maintainers work on the default branch; one copy | Releasing notes for an old line live in that line's Use pages or the changelog | Proposed |
| Maintain versioning | B — versioned like Use | Exact for old branches | Duplicates rarely changing pages | Rejected |
| Demos | A — HTML built by the package repo, sandboxed embed (ADR-0011) | Each line demos its own version; the site takes no dependency on the package; isolated from the site | Depends on ADR-0011; each package repo must build a demo file | Proposed |
| Demos | B — the package as a site dependency, demo as an MDX component | Shares the site's React | A dependency (and an ADR) per package and version; versions collide in one `node_modules` | Rejected |
| Demos | C — third-party sandboxes (StackBlitz, CodeSandbox) | No build work here | A third party on every demo page; slow; needs a DFD crossing and an ADR | Rejected |
| Stable links | A — `use/latest/…` alias redirect | README links never go stale | One more rule in `src/proxy.ts` | Proposed |
| Stable links | B — none | Nothing to build | Links to `v2` pages break when `v2` is removed | Rejected |
| Navigation | A — scoped `DocsLayout` per package with track switch and version menu | Matches the shape; uses `tree` and `tabs` Fumadocs already accepts | Custom sidebar header to build | Proposed |
| Navigation | B — default flat switcher with nested `root: true` folders | No code | Every track and line becomes a separate entry in one long list | Rejected |

## Consequences [#consequences]

**Positive**

- Every package and project reads the same way (product principle 2), and the home page can
  list them from data instead of hand-written links.
- Unreleased docs can be published early without misleading anyone: the banner and the label in
  search say so.
- A private entry cannot be published by mistake: the schema rejects it.

**Negative / accepted trade-offs**

- Consuming repositories must follow the folder shape; `PROJECT_AGENTS.md` changes with this ADR.
- Releasing a major means renaming `next` to `v<major>` and moving `latest` in one change.
- Sidebar header, version menu, banners, alias redirect and build checks are new code.
- Demos wait for ADR-0011.

## Content invariants [#content-invariants]

- **1 Private stays private:** kept, and enforced by the build (decision 1, decision 9). Nothing
  private enters `content/docs/` until its own ADR.
- **2 Checked against the code:** each line's `version` is read from the package's manifest
  by the consuming repository.
- **3 Every package page states its version:** the line's `version` is shown in the page
  header, in the banner and in the Markdown version.
- **4 Examples run:** each example belongs to a line and runs against that line's version.
- **5 Readable as Markdown:** unchanged; lines and tracks are ordinary pages.

## Security considerations [#security-considerations]

- **Private content.** The schema accepts `public` only. The future private-documentation
  ADR must keep private entries out of the build output, the search index, `llms.txt`,
  `static.json`, per-page Markdown and Open Graph images, and return the same 404 for an
  unknown and a private URL to a signed-out visitor, so a URL does not confirm a project exists.
- **Search records.** The new fields (`package`, `kind`, `ecosystem`, `track`, `line`,
  `channel`) are public metadata about public pages; nothing else is added. Readable by anyone
  with the search-only key, like every record.
- **Demos.** Third-party code built by a package repository runs only inside ADR-0011's
  sandboxed frame, with no access to the site's origin, cookies or storage.
- **Alias redirect.** It maps `use/latest` to a line folder name from the build's page tree,
  never to a value taken from the request, so it cannot be turned into an open redirect.

## Implementation notes [#implementation-notes]

- [x] Extend `metaSchema` with `catalog`, `version` and `channel`: `src/lib/catalog-schema.ts`,
      a Standard Schema around Fumadocs' `metaSchema`, used by `src/lib/source.ts`.
- [x] A catalogue helper in `src/lib/` that reads root folders into typed entries (kind,
      ecosystem, lines, tracks, demo) for the home page, search and navigation:
      `src/lib/catalog.ts`.
- [x] Scoped `DocsLayout` for package and project routes: track switch, version menu, banners.
      Typed root folders from `src/lib/catalog-plugin.ts`; `src/components/docs/`.
- [x] `src/proxy.ts`: the `use/latest` alias and the redirects for removed lines
      (`src/lib/catalog-routes.ts`).
- [x] Search records in `src/app/static.json/route.ts`: the new fields, and a scope `tag` per
      page. **Ranking is not applied**: it needs a change to the live index settings, which waits
      for the owner.
- [x] `llms.txt` and per-page Markdown: the version line.
- [x] Build checks (decision 9), in the loader plugin; the build fails with one line per
      problem, naming the file.
- [x] Tests — manual checks until ADR-0007 picks a runner:
      - `bunx next build` with sample content (three entries, kept out of `content/docs/`)
        passes. Each failure stops it with its message: two `latest` lines, a `private`
        entry, a root folder without `catalog`, a line without `version`, `legacy` without
        `latest`, and a package without `ecosystem`.
      - Two `next` lines, a line without `channel`, a non-https URL and line order were
        checked against the functions with a throwaway `bun test` script outside the
        repository: 6 tests, 32 assertions, all passing.
      - On `bunx next start`: `use/latest/…` and `.md` give 307 to the latest line, a removed
        line (`v9/…`) gives 307 to the same path in latest, real pages give 200, and an unknown
        package gives 404. Markdown starts with the "Documents" line; `llms.txt` labels lines;
        `static.json` carries the tags.
- [ ] `bun run lint`, `bun run types:check` and `bunx next build` pass. Type check and build
      pass. **Lint does not run**: `typescript-eslint` does not support TypeScript 7. This
      predates this ADR, and fixing it needs its own ADR.

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

- [x] [`../app-flow/package-navigation.mdx`](../app-flow/package-navigation.mdx) — to match the build
- [x] [`../state/package-version-lifecycle.mdx`](../state/package-version-lifecycle.mdx)
- [x] `../architecture/system.mdx` — the catalogue helper and scoped layout
- [x] `../dfd/system.mdx` — the new search record fields
- [x] `../api/` — `llms.txt`, per-page Markdown and `static.json` contracts
- [x] `PROJECT_AGENTS.md` and `AGENTS.md` §1, §6, §10 — the folder shape consumers follow
- [x] `README.md` — project structure
- [x] [`./index.mdx`](./index.mdx) — index row, next free number
- [x] [`./index.mdx`](./index.mdx) — status on approval


# ADR-0014 — The home page is a search-first map of every release (/docs/maintain/adr/ADR-0014-home-page-is-a-search-first-release-map)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-10-31
- **Supersedes:** —
- **Superseded by:** [ADR-0015](./ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx)
  in part (decisions 3, 6 and 9); [ADR-0016](./ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx) in part (decisions 3, 4, 8 and 10);
  [ADR-0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) in part (decision 4 and the footer)
- **Design documents:** [`../app-flow/home-page.mdx`](../app-flow/home-page.mdx),
  [`../prd/home-page.mdx`](../prd/home-page.mdx), `../architecture/system.mdx`,
  `../dfd/system.mdx`, `PRODUCT.md`

## Context [#context]

The home page at `/` is still the Fumadocs scaffold: "Hello World" and a link to `/docs`
(`src/app/(home)/page.tsx`). The site name is the placeholder `My App` and the GitHub link points
at the Fumadocs repository (`src/lib/shared.ts`).

The owner's brief, 2026-10-31: one home page for the whole collection, modern, readable,
seamless and unique. The owner settled these:

- **Job:** the catalogue and a showcase of the owner's work at once.
- **Private projects:** signed-out visitors see nothing of them: no name, count or placeholder.
- **Two tracks** per package and project, Use and Maintain (ADR-0013).
- **Craft bar:** Stripe, Linear and Resend.
- **Name:** "Puncoz Docs" for now. The final name will include neither the owner's name nor
  "docs".

A first direction (a narrow "quiet instrument" column, a hero of two doors for Packages and
Projects, a sand-and-moss palette) was built as a prototype and **rejected by the owner** the
same day. The owner asked for a cool, modern, technical look, a strong search input instead of a
choice between two options, a page that reads as a documentation landing page, and motion and
graphics. The owner **delegated the design decisions** to the agent without a further review
round ("brainstorm yourself and you decide"). This ADR records those decisions for approval
before any code is written.

The home page depends on the catalogue shape in ADR-0013 for its entries, versions, tracks and
demos.

## Decision [#decision]

1. **The builder is impeccable**, the primary UI skill in this repository (`INDEX.md` §
   Approved installed skills). design-taste-frontend built the rejected direction. Its house
   rules also forbid monospace outside code, and a technical look needs monospace for package
   names and versions. The page is a documentation landing page: it is structured for finding
   things, with one showcase moment, the hero.

2. **The signature is a map of every release.** The hero is a slowly turning orbital map drawn
   on a `<canvas>`:

   - each **ecosystem** (npm, Composer, PyPI, Go) is an elliptical orbit ring, and public
     **projects** are a dotted outer ring;
   - each **package or project** is a body on its ring, coloured by ecosystem (a project is an
     outlined body);
   - each **documented version line** is a moon circling its body: solid for a released line,
     an outlined moon on a dashed orbit for an unreleased `next` line;
   - hovering a body slows the map and shows a card with the name, description and version
     tags; clicking it puts the name in the search.

   The map is built from the same catalogue data as the list below it, so it shows the real
   shape of the collection: how many packages per ecosystem, how many lines each, what is
   unreleased. The canvas is decorative for assistive technology (`role="img"` with a label that
   explains the encoding). The catalogue below holds the same information as text.

3. **Search is the hero's one control, and it steers the page.** A large search field (64px
   high on desktop, 56px on phones) sits under the headline:

   - **Filter words become chips** inside the field. Typing `npm`, `composer`, `pypi`, `go`,
     `projects`, `maintain` or `next` followed by a space turns the word into a removable chip
     (`php`, `python` and `unreleased` are aliases). Backspace in an empty field removes the last
     chip.
   - **Three places answer at once.** The results list under the field shows matching pages,
     each tagged with its line and version (`v0 · 0.1.4`, `next 0.2.0-beta.3`) or `maintain`.
     Matching bodies in the orbital map light up and the rest dim. The catalogue below filters
     itself, with a live count ("3 of 11 match") and a clear action.
   - **Keyboard:** `⌘K` / `Ctrl K` and `/` focus the field from anywhere on the home page;
     arrow keys move through results, Enter opens one, Escape closes the list. On every other
     page the same keys open the existing Fumadocs search dialog.
   - **Where answers come from.** The catalogue and the map filter locally, from build-time
     catalogue data. Page results come from the existing Algolia index through the existing
     search-only client. Chips become filters on the record fields ADR-0013 adds (`ecosystem`,
     `kind`, `track`, `channel`). With no query, the list offers each package's install page.
   - **Suggestions:** a row of "Try" buttons under the field (`npm`, `next`, `maintain` and two
     example queries) adds a chip or fills the field.
   - **An idle demonstration:** until the reader focuses the field, its placeholder types real
     queries one after another and the map lights the matching bodies. It stops on focus and
     never runs under reduced motion.

4. **Page argument, top to bottom** (each section carries one claim):

   | Section | Claim | Proof on the page |
   |---|---|---|
   | Hero: release map and search | Everything is here, and you can find it from one field | The map of every public package, project and line; the search field |
   | Browse everything | Find any package or project in seconds | Every entry in a dense two-column list: name, description, Use / Maintain / Demo links, latest version, any `next`; filtered by the hero search |
   | Two tracks, one place | Users and maintainers each get their own docs | A Use / Maintain switch that swaps a live preview of a documentation page |
   | Every version, released or not | You always know which version a page describes | Version rails for featured packages, drawn on scroll: released lines solid, `latest` marked, `next` dashed |
   | Try it before you install it | The packages work, and you can try one here | One featured package's real demo, with its controls |
   | Read it anywhere | You can take the docs without the site | A terminal fetching `llms.txt`; cards for per-page `.md`, `llms.txt` / `llms-full.txt`, and private stays private |
   | Footer | — | One line and four links |

   A section with no data is left out, never shown empty: no featured demo means no demo
   section, and fewer than two packages with several lines means no version rails.

5. **Type** (loaded with `next/font/google`, as Inter is today, so the fonts are downloaded at
   build time and served from the site):

   | Role | Face | Used for |
   |---|---|---|
   | Display | Bricolage Grotesque 600–800 | Headline, section headings, wordmark |
   | Text | Onest 400–600 | Body, controls, descriptions |
   | Data | JetBrains Mono 400–500 | Package names, versions, URLs, commands, code, counts |

   impeccable's detector flagged Geist and Instrument Sans as overused; these three pass it.
   Home page only; documentation pages keep Inter until their own ADR.

6. **Colour: graphite and teal, dark first.** Tokens in `src/app/global.css`, scoped to the home
   page. The page follows the reader's theme through Fumadocs' theme setting; dark is the
   default.

   | Token | Dark | Light | Role |
   |---|---|---|---|
   | `--bg` | `#0a0c10` | `#f6f7f9` | Page |
   | `--panel` | `#141821` | `#ffffff` | Search field, windows, cards |
   | `--line` / `--line-2` | `#232937` / `#323a4c` | `#dde1e9` / `#c4cbd8` | Rules, borders, orbit rings |
   | `--ink` | `#e9ecf2` | `#0d1016` | Text |
   | `--muted` | `#9ba4b6` | `#4f586b` | Secondary text |
   | `--faint` | `#7f889e` | `#5f6880` | Hints, group labels |
   | `--accent` | `#3ddbb6` | `#077a63` | Focus, highlights, the one accent |
   | `--npm` · `--composer` · `--pypi` · `--go` | `#ff6f61` · `#a394ff` · `#ffd166` · `#56cdf2` | `#d4382b` · `#5b48e0` · `#9a6d00` · `#0a7fa6` | Ecosystem bodies, dots and chips |

   Measured: every text colour is 4.5:1 or more against `--bg` and `--panel` in both themes
   (`--faint` on `--panel`, the tightest pair, is 5.0:1 dark and 5.6:1 light). Ecosystem colours
   mark shapes, never carry text alone, and are 4.2:1 or more against `--bg`. Selection, caret,
   scrollbar and focus rings use the tokens.

7. **Motion, without a library.** Transform, opacity and canvas drawing only:

   - the orbit turns slowly (one revolution of the inner ring takes about 100s); it slows under
     the pointer, and pauses when the tab is hidden or the hero is off-screen;
   - search highlights fade bodies in and out over about 300ms; chips pop in;
   - each section's parts enter once, rising and un-blurring;
   - the version rails draw from left to right once; the track preview cross-fades with a
     blur; the terminal types its command once, when it comes into view;
   - under `prefers-reduced-motion` the orbit is drawn once and stays still, the placeholder
     doesn't type, the terminal shows its full output, and nothing enters or draws;
   - without scripts every section's content is visible, the map is absent, and the search field
     is replaced by a link to `/docs`; the catalogue below lists every entry.

8. **Data comes from the catalogue at build time** (ADR-0013): entries, versions, `next` lines,
   tracks, the featured demo and the rails. The page is static. Its only runtime request is the
   Algolia query the reader types.

9. **Header:** the wordmark on the left; Packages, Projects and `llms.txt` links; GitHub on the
   right. Sticky, with a blurred background and a border that appears after scrolling. No
   sign-in link until the private-documentation ADR. `appName` in `src/lib/shared.ts` becomes
   `Puncoz Docs` until the final name is chosen.

10. **Phones first.** The headline, search field and "Try" row fill the first screen; the map
    turns behind them at a smaller scale; the legend and key hints are hidden. The catalogue
    becomes one column, the track preview stacks its sidebar above the page, and the demo puts
    its controls under the stage.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Builder | impeccable | Primary UI skill here; its detector and craft floor ran on the prototype | — | Chosen (delegated) |
| Builder | design-taste-frontend | Strong showcase pages | Built the rejected direction; its rules forbid the monospace a technical look needs | Rejected (owner's feedback) |
| Hero | Orbital release map with search | Shows the real shape of the collection: ecosystems, packages, lines, what is unreleased; search lights it | Canvas code to write and test; information is visual, so the catalogue must carry it as text | Chosen (delegated) |
| Hero | Constellation graph of packages | Lively | Decoration with no meaning: says nothing about versions or ecosystems | Rejected |
| Hero | Two doors, Packages and Projects | Plain split of the collection | Rejected by the owner: a choice instead of a search, and a dull look | Rejected (owner) |
| Hero | Search field only, no graphic | Quickest to build | The owner asked for motion and graphics | Rejected |
| Search | Field steers the page: chips, results, map and catalogue | One control, three answers; filters are typed, not hunted in menus | More state to keep in sync | Chosen (delegated) |
| Search | Field opens the existing dialog | No new code | The page does nothing with the query; the hero becomes a button | Rejected |
| Page results | Existing Algolia index, chips as filters | No new integration; the same results as the dialog | Depends on ADR-0013's record fields; degraded when Algolia is down | Chosen (delegated) |
| Page results | A local index of every page shipped to the browser | Works offline | Duplicates Algolia; grows with every page | Rejected |
| Map rendering | Canvas 2D | No dependency; dozens of bodies at 60fps | Hit-testing by hand; needs a text equivalent | Chosen (delegated) |
| Map rendering | SVG | Each body is an element | Animating dozens of elements every frame costs layout | Rejected |
| Map rendering | WebGL / three.js | 3D depth | A dependency and its own ADR; heavy for a home page | Rejected |
| Palette | Graphite and teal, dark first, light variant | Technical and calm; ecosystem colours stand out on it | Light theme needs its own tuned values | Chosen (delegated) |
| Palette | Sand and moss | Warm | Rejected by the owner | Rejected (owner) |
| Fonts | Bricolage Grotesque, Onest, JetBrains Mono | Distinct display face; readable text face; a coding mono | Three faces to load | Chosen (delegated) |
| Fonts | Geist and Geist Mono | Two faces from one family | Flagged as overused by impeccable's detector | Rejected |
| Fonts | System stack | No fetch | No character | Rejected |
| Scope of tokens | Home page only, docs pages later | Small change; docs pages keep their treatment until their ADR | Home and docs look different until then | Proposed |
| Scope of tokens | Sitewide now | One look at once | Changes every docs page without an app flow | Rejected |

## Consequences [#consequences]

**Positive**

- The first screen says what the site is, shows the size and shape of the collection, and puts
  the reader's next action, a search, in the middle of it.
- Everything on the page is built from content, so the map, list and rails stay current as
  packages and lines are added.
- One field does the job of category menus, filters and a search dialog.

**Negative / accepted trade-offs**

- The map is custom canvas code: hit-testing, resizing, theming and reduced motion are
  hand-written and need their own checks.
- Page results need ADR-0013's search record fields first; until then chips filter only the
  map and the catalogue.
- Home and documentation pages look different until the docs-page ADR.
- The two-column list suits up to about 40 entries; past that, grouping needs its own ADR.
- The demo section waits for ADR-0011 and for a package with a demo.
- Three fonts are added to the build.

## Content invariants [#content-invariants]

- **1 Private stays private:** the map, list, rails, search suggestions and counts are built only
  from public catalogue entries; ADR-0013's build check rejects a private one. No placeholder,
  lock or count hints at private work.
- **2 Checked against the code:** versions and lines come from catalogue data, which consuming
  repositories read from manifests (ADR-0013).
- **3, 4:** versions on the page are the `latest` and `next` lines' exact versions; the demo
  runs the version its line documents.
- **5:** the home page is navigation; every entry it lists is a page with a Markdown version.

## Security considerations [#security-considerations]

- **Data.** Public catalogue metadata only, read at build time. No secret and no new environment
  variable.
- **Search.** The hero uses the existing Algolia search-only client (`src/components/search.tsx`);
  the key is already public by design and reads only public records. Query text goes to Algolia
  exactly as it does from the dialog today; the DFD gains no new crossing, only a second place
  that starts one. Results and highlights are rendered as text, never as HTML from the record.
- **Input.** Chips come from a fixed list of words; anything else stays free text. Free text is
  only sent as a query and shown escaped.
- **Fonts.** Fetched from Google at build time and served from the site; a reader's browser
  makes no request to Google.
- **Demo.** The featured demo runs in ADR-0011's sandboxed frame.
- **Private projects.** Nothing reveals them to a signed-out visitor. The future private ADR
  must keep it so when signed-in readers see them, including on the map.

## Implementation notes [#implementation-notes]

- [x] `src/app/(home)/page.tsx` and a component per section (`src/components/home/`), reading
      the ADR-0013 catalogue helper. No demo section until ADR-0011.
- [x] The orbital map as a client component: canvas drawing, hit-testing, resize, theme tokens,
      pause when hidden or off-screen, reduced-motion still frame.
- [x] The hero search: chip parsing, results list (listbox pattern with
      `aria-activedescendant`), Algolia filters from chips (on the `tag` facet), shared query
      state for the map and the catalogue, degraded state when Algolia fails.
- [x] Tokens and fonts (decisions 5 and 6), home page scope (`.home` in `global.css`,
      `src/app/(home)/home.css`).
- [x] Motion (decision 7) with reduced-motion and no-script fallbacks.
- [x] Header (decision 9); `appName` → `Puncoz Docs`; `gitConfig` → `puncoz-official/docs`.
- [x] impeccable's detector on the source and the built HTML. Contrast was computed from the
      tokens in both themes. No browser visual check: it needs the owner's yes.
- [ ] Tests — manual checks until ADR-0007 picks a runner:
      - Catalogue filtering by chip and text, and the Algolia filter built from chips, were
        checked against the functions with a throwaway `bun test` script outside the
        repository: all passing.
      - `next`, legacy and unreleased rows, the tracks preview and the version rails were
        checked in the built HTML with sample content. Empty sections were checked as left out
        in the built HTML with no entries.
      - **Not checked in a browser:** chip parsing as the reader types, keyboard navigation of
        the results, and the degraded state. They run only in the client.
- [ ] `bun run lint`, `bun run types:check` and `bunx next build` pass. Type check and build
      pass. **Lint does not run**: `typescript-eslint` does not support TypeScript 7.

## Open questions [#open-questions]

- **GitHub link:** resolved: the header links to `puncoz-official/docs` (owner, 2026-10-31).
- **Final name:** still open. Until it is chosen the site is "Puncoz Docs" (owner, 2026-10-31);
  the name lives in `appName` in `src/lib/shared.ts` only.

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

- [x] [`../app-flow/home-page.mdx`](../app-flow/home-page.mdx) — to match the build
- [x] [`../prd/home-page.mdx`](../prd/home-page.mdx)
- [x] `../architecture/system.mdx` — the home page, its data and the hero search
- [x] `../dfd/system.mdx` — the home page as a second origin of search queries
- [x] `DESIGN.md` — the home page's visual system
- [x] `AGENTS.md` §1 (current state), `README.md` — the home page
- [x] [`./index.mdx`](./index.mdx) — index row, next free number
- [x] [`./index.mdx`](./index.mdx) — status on approval


# ADR-0015 — Every package and project lives at the root, in one shape and one look (/docs/maintain/adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-10-31
- **Supersedes:** [ADR-0013](./ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx)
  decisions 1 (in part: the Documentation project's exemption), 3 (line names, the `next` line
  and channel), 5 (URLs), 6 (in part: the Documentation project's default layout) and 9 (in part:
  the line checks);
  [ADR-0014](./ADR-0014-home-page-is-a-search-first-release-map.mdx) decisions 3 (in part: the
  `next` chip becomes `dev`), 6 (in part: tokens scoped to the home page) and 9 (header)
- **Superseded by:** [ADR-0016](./ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx) in part (decisions 8 and 9);
  [ADR-0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) in part (decision 9);
  [ADR-0030](./ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx) in part (decision 7's "no entrance motion on docs pages", for the footer);
  [ADR-0034](./ADR-0034-the-proxy-answers-unknown-paths-with-a-true-404.mdx) in part (its implementation's "the proxy acts only on catalogued paths")
- **Design documents:** [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx),
  [`../prd/site-pages.mdx`](../prd/site-pages.mdx); on implementation
  `architecture/system.mdx`, `api/content-routes.mdx`, `state/package-version-lifecycle.mdx`,
  `app-flow/package-navigation.mdx`, `DESIGN.md`

## Context [#context]

ADR-0013 and ADR-0014 are built. Three things about the result are now wrong for the owner:

- **`/docs` means two things.** Packages and projects sit under `/docs/<slug>`, and so does this
  site's own documentation (`/docs/documentation`). Next to them sit two scaffold pages
  ("Hello World" at `/docs`, "Components" at `/docs/test`). The owner wants a package at
  `/<slug>`, and this site's documentation treated as what it is: maintainer documentation
  for the site itself.
- **Docs pages don't look like the site.** The home page has its own visual system (`DESIGN.md`:
  graphite and teal, Bricolage Grotesque, Onest, JetBrains Mono), scoped to `.home`. Docs pages
  still wear Fumadocs' neutral theme and Inter. There is no light/dark switch on the home page;
  docs pages have Fumadocs' own.
- **Versions need a permanent home for unreleased work, and names the package chooses.**
  ADR-0013 has a `next/` line created for an unreleased major and renamed on release, and fixes
  line names to `v<major>`. The owner wants one permanent `dev` line for work in progress, and
  released lines named by whatever string the package supplies (`v1.0`, `2024-lts`, …),
  configured in a file.

Facts this decision rests on, read from the installed code:

- Fumadocs' `loader()` takes a `baseUrl` (`src/lib/source.ts` passes `docsRoute = '/docs'`).
  `DocsLayout` (fumadocs-ui 16.17.9) accepts `slots` (header, sidebar, container), so the header
  can be replaced while the sidebar, contents panel, version menu and page footer stay.
  `fumadocs-ui/layouts/shared/slots/theme-switch` exports `ThemeSwitch` with `mode:
  'light-dark' | 'light-dark-system'`. The loader takes a slug function per page (`SlugFn`,
  and `slugsFromData` in fumadocs-core 16.17.9), so a line's URL segment can come from its
  `meta.json` rather than its folder name.
- Next.js route groups let `app/(home)/page.tsx` own `/` while a required catch-all
  `app/(site)/[...slug]/page.tsx` owns every other content path (`dynamic-routes.md`,
  `route-groups.md`). A required catch-all does not match `/`. The installed docs do not state
  that a static top-level route (`llms.txt`, `static.json`, `og/`, `llms.mdx/`) wins over a
  root catch-all; the implementation proves it with a build before relying on it, and the
  reserved-slug check below keeps a content folder from ever claiming those names.
- Nothing has been deployed (owner, 2026-10-31), so no `/docs/…` URL needs a redirect.
- No package or project is documented yet: moving folders and URLs now costs only this site's
  own pages and the references to them.

## Decision [#decision]

### Routes and folders [#routes-and-folders]

1. **Every package and project lives at the root:** `/<slug>`. There is no `/docs` prefix. The
   folder path is the URL path:

   | Folder | URL |
   |---|---|
   | `content/<slug>/index.mdx` | `/<slug>` — overview, with the package hero (decision 7) |
   | `content/<slug>/use/<folder>/<page>.mdx` | `/<slug>/use/<line>/<page>` — user docs, versioned; `<line>` comes from the line's `name` (decision 4) |
   | `content/<slug>/use/<page>.mdx` | `/<slug>/use/<page>` — user docs of an unversioned project |
   | `content/<slug>/maintain/<page>.mdx` | `/<slug>/maintain/<page>` — maintainer docs, not versioned |
   | — | `/<slug>/use` → the `latest` line's first page, or `dev`'s when nothing is released |
   | — | `/<slug>/use/latest/<page>` → 307 to the same page in the `latest` line |
   | — | `/<slug>/….md` — the page as Markdown |
   | — | `/og/<slug>/…/image.png`, `/llms.mdx/<slug>/…/content.md` — internal, as today |

   The folder path is the URL path everywhere except a line's segment, which is its configured
   name. The collection root moves from `content/docs/` to `content/`. `docsRoute` becomes `''`
   (root), and the docs page moves from `app/docs/[[...slug]]/` to `app/(site)/[...slug]/`,
   with its layout in `app/(site)/layout.tsx`.

2. **Slugs are checked.** A root folder's name matches `^[a-z0-9][a-z0-9-]*$` and is none of
   the reserved names: `api`, `auth`, `callback`, `sign-in`, `sign-out`, `og`, `search`,
   `static`, `assets`, `public`, `_next`. The build fails otherwise. Names with a dot (`llms.txt`,
   `static.json`, `llms.mdx`) can't match the pattern. A new top-level route adds its name to the
   list in the same change.

3. **The shape of every entry** (ADR-0013 decisions 2, 4 and 7 stand; lines change):

   ```
   content/<slug>/
   ├── meta.json            # title, description, catalog (ADR-0013 decision 1)
   ├── index.mdx            # overview → /<slug>
   ├── use/                 # user docs
   │   ├── meta.json
   │   ├── meta.json        # optional "pages": the order of older lines in the version menu
   │   ├── dev/             # work in progress on the default branch: always present
   │   │   ├── meta.json    # {"channel": "dev", "version": "2.0.0-dev.4"}
   │   │   └── …
   │   ├── v1.0/            # one folder per released line; any folder name
   │   │   ├── meta.json    # {"name": "v1.0", "version": "1.0.3", "channel": "latest"}
   │   │   └── …
   │   └── lts-2024/        # an older line
   │       ├── meta.json    # {"name": "2024 LTS", "version": "0.9.3", "channel": "legacy"}
   │       └── …
   └── maintain/            # maintainer docs: the default branch, never versioned
       ├── meta.json
       └── …                # architecture, local setup, tests, releasing, contributing, decisions
   ```

4. **Version lines: one `dev`, and released lines named by the package.**
   - **`dev`** documents the default branch: work in progress, not yet released. Every versioned
     package has it, in `use/dev/`, at `/<slug>/use/dev/…`. Its `channel` is `dev`, its banner
     says "In development", and its `version` is the manifest's version on the default branch.
     Its name is always `dev`.
   - **A released line's name is any string the package supplies**, set as `name` in the line's
     `meta.json`: `v1.0`, `1.x`, `2024 LTS`. The name is what readers see in the version menu,
     the banners, search results and `llms.txt`. The line's URL segment is the name made
     URL-safe: lowercased, spaces to hyphens, anything else outside letters, digits, `.`, `_`
     and `-` removed (`2024 LTS` → `2024-lts`, `v1.0` → `v1.0`). The folder name is free and
     never appears in a URL. Without `name`, the folder name is used.
   - **`version`** is the exact release the line documents, read from the package's manifest,
     and **`channel`** is `latest` or `legacy`. Exactly one released line is `latest`.
   - **Order in the version menu:** `latest`, then `dev`, then older lines in the order of
     `use/meta.json`'s `pages`, or by `version` (natural order, newest first) when it isn't set.
   - **Releasing** copies `use/dev/` into a new line folder with its `name`, `version` and
     `channel: "latest"`, and turns the previous `latest` to `legacy` (or updates the current
     line in place, when the package keeps one line per range). `dev` keeps going. A legacy line
     may be deleted when it is no longer supported; its URLs then redirect to `latest`
     (ADR-0013's rule stands).
   - **Unreleased package:** only `dev`. **Unversioned project:** no lines; its `use/` holds pages
     directly. A project that ships releases may use lines like a package.

5. **The build checks the shape** (ADR-0013 decision 9, extended): a missing or invalid
   `catalog`; a `private` entry; a bad or reserved slug; a line without `version` or
   `channel`; a `dev` channel anywhere but `use/dev/`, or `use/dev/` with another channel; a
   released line whose URL segment is empty, is `dev` or `latest`, ends in `.md`, or matches
   another line's; two `latest` lines; `legacy` lines without a `latest`.

### This site's own documentation [#this-sites-own-documentation]

6. **The site is the catalogued project `docs`.** Its folder is `content/docs/` (overview at
   `/docs`, "Puncoz Docs: what this site is and how it is organised"), with
   `catalog: { kind: "project", visibility: "public" }`. Today's Documentation tree becomes its
   **Maintain track**: `content/docs/maintain/{adr,architecture,app-flow,prd,api,dfd,sequence,
   state,erd,rbac,security,_templates}` at `/docs/maintain/…`. It has no Use track yet; one
   holding the consumer guide (`PROJECT_AGENTS.md` as pages) is left for a later change. It is
   listed in the catalogue and on the map like any project, and the `documentation` exemption in
   the catalogue plugin is removed. The scaffold pages `content/docs/index.mdx` (Hello World) and
   `content/docs/test.mdx` are deleted.

### One look across the site [#one-look-across-the-site]

7. **Docs pages use the home page's visual system, quietly** (`DESIGN.md`):
   - The tokens move from the `.home` scope to the whole site, and Fumadocs' `--color-fd-*`
     variables are mapped onto them, so the sidebar, contents panel, callouts and code blocks
     take the graphite and teal palette in both themes.
   - Headings in Bricolage Grotesque, body text in Onest, code, package names and versions in
     JetBrains Mono, loaded once in the root layout.
   - No orbit and no entrance motion on docs pages: reading pages stay still.
   - **Package hero** on each overview (`/<slug>`): a band above the page's own content, built
     from the catalogue. It holds the ecosystem dot and colour (outlined for a project), the name
     in monospace, the description, the `latest` version and `dev` on a dashed tag, a small
     version rail of the lines, and links: Use, Maintain, registry, repository. A project
     without lines shows Use and Maintain only.

8. **One header on every page**, replacing ADR-0014 decision 9's home-only header and
   Fumadocs' own: the wordmark, a search trigger (`⌘K`, opening the site search dialog),
   Packages, Projects (only when a project exists) and `llms.txt`, then GitHub and the
   **theme switch**. On docs pages it fills `DocsLayout`'s header slot; the sidebar, version
   menu and Use | Maintain switch stay below it.

9. **Light and dark on every page.** The header carries Fumadocs' `ThemeSwitch` in
   `light-dark` mode. Dark stays the default (`RootProvider theme={{ defaultTheme: 'dark' }}`);
   the reader's choice is kept by Fumadocs' theme provider in their own browser and applies to
   the home page and docs pages alike. The orbit map, rails and terminal read the tokens, so
   they follow the switch.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| URLs | A — `/<slug>` at the root | Short, memorable URLs; the owner's choice | Slugs share the root with site routes; needs the reserved list | Chosen (owner) |
| URLs | B — keep `/docs/<slug>` | No route change | `/docs` keeps meaning two things | Rejected |
| Folders | A — `content/<slug>/`, folder path = URL | One rule to explain; the site's folder is `content/docs/` | Moves the collection root; consumers' guide changes | Chosen (owner) |
| Folders | B — keep `content/docs/<slug>/` | No move | The site's folder becomes `content/docs/docs/`; paths no longer match URLs | Rejected |
| Site docs | A — Maintain track of the listed project `docs` | No special case; the site follows its own rules | Its pages move; ~170 references to update | Chosen (owner) |
| Site docs | B — Maintain track, unlisted | Not presented as a project | Needs an `unlisted` flag | Rejected |
| Site docs | C — not published, repository only | Smallest site | Supersedes ADR-0002; no rendered diagrams | Rejected |
| Unreleased work | A — permanent `dev` line | Always a place for work in progress; releasing is a copy | One more folder per package | Chosen (owner, named `dev`) |
| Unreleased work | B — `next/` renamed on release (ADR-0013) | Fewer folders between majors | Unreleased minor work has nowhere to go | Superseded |
| Released line names | A — `name` in the line's `meta.json`, any string; URL segment derived from it | The package chooses its own scheme (`v1.0`, `2024 LTS`); one place to set it; folder names don't matter | Order can't come from the names, so it comes from `pages` or `version`; renaming changes URLs | Chosen (owner) |
| Released line names | B — the folder name is the name | Nothing to configure | Folder names must be URL-safe and can't carry a display name like `2024 LTS` | Rejected |
| Released line names | C — a fixed scheme (`v<major>`, `v0.<minor>`) | Predictable, checkable | Doesn't fit packages with other schemes | Rejected (owner) |
| Maintainer docs | A — not versioned | Maintainers work on the default branch | Old lines' setup notes aren't kept | Chosen (owner) |
| Docs look | A — same system, quiet, plus a package hero | One site; overviews say what a package is at a glance | Fumadocs variables to map and check in both themes | Chosen (owner) |
| Docs look | B — tokens and fonts only | Smallest change | Header and docs pages don't match the home page | Rejected |
| Theme | A — `ThemeSwitch` in the shared header, dark default | Installed component; one place | Light theme of the docs pages needs its own contrast check | Chosen |
| Theme | B — light / dark / system | Follows the OS | A third state the owner didn't ask for | Rejected |

## Consequences [#consequences]

**Positive**

- One rule for every URL and folder: `/<slug>` is `content/<slug>/`, and the shape inside is the
  same for packages, projects and the site itself.
- Work in progress always has a line (`dev`), releasing never renames a folder, and each
  package names its lines its own way.
- Docs pages and the home page read as one site, in either theme.

**Negative / accepted trade-offs**

- Every reference to `content/docs/documentation/` and `/docs/documentation` (AGENTS.md,
  PROJECT_AGENTS.md, README, the skills index, templates, every ADR's links) changes in one pass.
- The root URL space is shared: every future top-level route must be added to the reserved list.
- Changing a line's `name` changes its URLs; old links then 404 unless the line is removed
  (which redirects to `latest`). The consumer guide says to treat names as permanent.

## Content invariants [#content-invariants]

- **§6.1 Private stays private:** unchanged; the schema still refuses a non-`public` entry.
- **§6.3 Every package page states its version:** kept; `dev` pages say "In development" with
  the default branch's version.
- **§6.5 Every page is readable as Markdown:** kept at the new paths (`/<slug>/….md`),
  `llms.txt` and `llms-full.txt`.

## Security considerations [#security-considerations]

- **No new data, endpoint or secret.** The pages, Markdown, OG images and search records are the
  same public content at new URLs.
- **Search index:** record URLs change. The index is rewritten on the owner's next
  `bun run build`; until then, live results would point at old URLs. Nothing is deployed, so
  no reader sees that gap.
- **Reserved slugs** keep a content folder from shadowing a future security-relevant route
  (`/api`, `/auth`, `/sign-in`, `/callback` for the WorkOS ADR).
- **Theme choice** is stored by the theme provider in the reader's browser (`localStorage`): a
  preference, not personal data, never sent anywhere.

## Implementation notes [#implementation-notes]

- [x] A test build proving a root required catch-all coexists with `/`, `/llms.txt`,
      `/llms-full.txt`, `/static.json`, `/og/…` and `/llms.mdx/…`.
- [x] Move `content/docs/documentation/` → `content/docs/maintain/`; write
      `content/docs/meta.json` (catalogue entry) and `content/docs/index.mdx` (overview); delete
      the two scaffold pages. Collection root `content/`.
- [x] `src/lib/shared.ts`: root routes; `src/lib/source.ts`, `catalog-routes.ts`, `src/proxy.ts`:
      new paths, line URL segments from `name` (a loader slug function), the `dev` line,
      `/<slug>/use` landing. The proxy acts only on catalogued paths (`isEntryPath`).
- [x] `catalog-plugin.ts` and `catalog-schema.ts`: `name` field, `dev` channel in place of
      `next`, slug and line checks, version-menu order, the `documentation` exemption removed.
      `llms.txt` labels a line by its name.
- [x] The home page: the `next` chip becomes `dev` (aliases `next`, `unreleased`); rows and rails
      show `dev`.
- [x] `app/(site)/[...slug]/` and `app/(site)/layout.tsx` (Fumadocs notebook layout, whose
      `nav.component` takes the site header: the docs layout's own header is mobile-only); OG,
      Markdown and `llms` routes on the new paths. `src/lib/layout.shared.tsx` removed, unused.
- [x] Site-wide tokens and fonts; Fumadocs variable mapping; a shared `SiteHeader` with the search
      trigger and `ThemeSwitch`, used by the home page and the docs layout's header slot.
- [x] The package hero on overviews.
- [x] Contrast check of docs pages in both themes, computed from the tokens: every text pair is
      4.5:1 or more except the active sidebar link on the page colour in light (4.29:1), so the
      phone drawer now sits on the panel colour (4.61:1), like the desktop sidebar. impeccable's
      detector on the source: its one finding, a 3px side stripe on the hero, was removed. On the
      built HTML it could not load the stylesheets, so its one finding there (flat type sizes) is
      not a real result. Checking in a browser, the theme switch included, waits for the owner's
      yes.
- [x] Rewrite every reference to the old paths.
- [x] Tests — manual checks until ADR-0007 picks a runner, recorded 2026-10-31 and 2026-11-01
      with sample entries copied into `content/` and removed afterwards:
      - a scratch `bun test` passed 9 tests (47 assertions): every build-check failure, including
        a reserved slug, a bad slug, a root page, a misplaced `dev`, a bad or duplicate segment
        and pages under a versioned `use/`; `lineSegment`, `lineInfo` and `pageVersion`; menu
        order with and without `pages`; the chip filter and catalogue filter with `dev`.
      - on `next start`, all as expected:
        - `/lodestar/use` and `/lodestar/use/latest/commands` gave 307 to `v0.1`, `.md` kept;
        - `/ledgerly/use/v3` gave 307 to `4.x`;
        - `/ledgerly/use/3.x-lts` (a line named `3.x LTS`) gave 200;
        - `/docs`, `/docs/maintain/adr` and their `.md` gave 200 (`text/markdown` for `.md`);
        - `/nothing` and `/docs/documentation` gave 404;
        - `/llms.txt`, `/static.json`, `/og/<slug>/image.png` and `/llms.mdx/<slug>/content.md`
          responded;
        - the rendered HTML had the hero tags, the version menu descriptions and both banners,
          and the theme toggle on home and docs pages.
- [x] `bun run types:check` and `bunx next build` pass (171 pages without samples).
      `bun run lint` still fails: "typescript-eslint does not support TS 7.0". Reported, not
      fixed here.

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

- [x] [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx) — to match the build
- [x] [`../prd/site-pages.mdx`](../prd/site-pages.mdx)
- [x] `../app-flow/package-navigation.mdx`, `../app-flow/home-page.mdx` — new URLs, header, theme
- [x] `../state/package-version-lifecycle.mdx` — the `dev` line, named lines, release by copy
- [x] `../architecture/system.mdx`, `../api/content-routes.mdx`, `../dfd/system.mdx` — routes
- [x] `DESIGN.md` — tokens site-wide, docs pages, package hero, header, theme switch
- [x] ADR-0002 and ADR-0010 (both Proposed) — revised in place for the new location and paths;
      `../app-flow/project-root-folders.mdx` removed, since no sidebar switcher of projects remains
- [x] `AGENTS.md`, `PROJECT_AGENTS.md`, `README.md`, `.claude/agent-skills/INDEX.md` — paths, shape
- [x] [`./index.mdx`](./index.mdx) — index row, next free number
- [x] [`./index.mdx`](./index.mdx) — status on approval

## Open questions [#open-questions]

None. Line names and the `dev` line are the owner's (2026-10-31).


# ADR-0016 — Home search is the Fumadocs dialog, and private projects render server-side (/docs/maintain/adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side)

- **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:** [ADR-0014](./ADR-0014-home-page-is-a-search-first-release-map.mdx) decisions 3
  (search steers the page), 4 (in part: Browse everything filtered by search; the Read it
  anywhere cards), 8 (in part: chips and filters from catalogue data) and 10 (in part: the "Try"
  row); [ADR-0015](./ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx)
  decisions 8 (in part: the search trigger in the home page's header) and 9 (in part: how the
  theme switch looks)
- **Superseded by:** [ADR-0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) in part
  (decisions 3, 5 in part and 8)
- **Design documents:** [`../app-flow/home-page.mdx`](../app-flow/home-page.mdx),
  [`../prd/home-page.mdx`](../prd/home-page.mdx),
  [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx)

## Context [#context]

The owner reviewed the built home page on 2026-11-01 and asked for six changes:

1. The header search on the home page is not needed; the hero already has one.
2. The hero search should be Fumadocs' search, with no custom search.
3. The hero text cannot be selected: the cursor shows the map's crosshair.
4. The theme switch is too small next to the header's 36px buttons; make it balanced, with
   some creativity.
5. Browse everything should gain a private projects section, visible only to signed-in
   readers. For now it shows an empty state; the sign-in session comes later.
6. The "Private stays private" card goes: the public needn't know anything about private work.

Item 3 was a bug (the hero's text had `pointer-events: none`, so the pointer reached the canvas).
It is fixed without an ADR, with the owner's link from the footer's "Puncoz Nepal" to
`https://puncoz.com`. The rest change approved decisions.

What the code and the installed packages settle:

- **Fumadocs' search UI is a dialog.** `fumadocs-ui/components/dialog/search` exports
  `SearchDialog` and its parts (`SearchDialogInput`, `SearchDialogList`, …), which work inside
  the dialog's context. The site already uses them with Algolia in `src/components/search.tsx`,
  opened by `⌘K` / `Ctrl K` (Fumadocs' hotkeys) and by `useSearchContext().setOpenSearch`.
  There is no inline results component, so "Fumadocs' search in the hero" means the hero opens
  this dialog.
- **Without the custom search, nothing filters.** The chips, the results list, the map lighting,
  the catalogue's live filter and count, and the "Try" row all hang on
  `src/components/home/search-state.tsx`. The owner chose **dialog only, no filters**.
- **Every docs page already has** Fumadocs' Copy Markdown button and "Open" menu
  (`MarkdownCopyButton`, `ViewOptionsPopover`), whose options are Open in GitHub, ChatGPT,
  Claude, Cursor and Scira (`fumadocs-ui/dist/layouts/shared/page-actions.js`).
- **Rendering.** Without Cache Components, reading a request-time API such as `cookies()`
  makes the whole route render per request
  (`node_modules/next/dist/docs/01-app/02-guides/caching-without-cache-components.md`). With
  `cacheComponents: true`, Next.js prerenders a static shell and streams only the parts behind a
  `<Suspense>` boundary that read request data; a session read belongs inside such a boundary
  (`…/02-guides/authentication-with-cache-components.md`). Under Cache Components the
  `revalidate` route segment config errors, and a `GET` route handler that reads no runtime data
  is prerendered without it (`…/02-guides/migrating-to-cache-components.md`). Five route handlers
  export `revalidate = false` today. The docs ask for `partialPrefetching` to be set explicitly
  with `cacheComponents` (`…/05-config/01-next-config-js/cacheComponents.md`). The owner asked
  for the private section to be "Next.js server side" and chose **Cache Components**.
- **No sign-in exists.** WorkOS is named in the home PRD for a later ADR. There is no session to
  verify. The owner decided the private group's empty state **shows to every reader for now**;
  hiding it from signed-out readers is the sign-in ADR's work.
- **`.env.example` does not exist**, although `AGENTS.md` §9 asks for one.

## Decision [#decision]

1. **The hero's search is a button that opens the Fumadocs dialog.** It keeps the field's look:
   64px high (56px on phones), Graphite Panel, 14px corners, the search icon, the placeholder
   "Search packages, projects and pages" and a `⌘K` key hint. It is a `<button>`: click, Enter
   or Space opens the site's existing search dialog (`src/components/search.tsx`). `⌘K` /
   `Ctrl K` open the same dialog, as on every other page; the home page no longer captures them,
   and `/` is no longer bound. **Removed:** the inline results list, the filter chips, the "Try"
   row, the idle typing demonstration, the map lighting while searching, the catalogue's live
   filter, count and "Clear search", and the code behind them (`hero-search.tsx`,
   `search-state.tsx`).
2. **The home header has no search button.** On docs pages the header keeps it. Its links
   become anchors: Packages → `/#packages` (shown when a package exists), Projects →
   `/#projects` (shown when a project exists), replacing the chip actions and
   `?filter=projects`.
3. **Browse everything is grouped.** Under its heading, a **Packages** group and a **Projects**
   group, each with its own id and count, in the same ruled two-column rows. A group with no
   entries is left out. The catalogue is a Server Component: it no longer has client state.
4. **The orbit map stays, quieter.** It turns, slows under the pointer and shows its card on
   hover as now. Clicking a body opens that entry's overview, instead of putting its name in the
   field. It no longer reacts to search. The hero's text stays selectable above it.
5. **Private projects: a server-rendered group, shown to everyone for now.**
   - A **Private projects** group (`#private`) follows Packages and Projects. It is a Server
     Component with no client code.
   - It shows its empty state to **every reader**, by the owner's decision: "No private projects
     yet. They'll appear here once private documentation is set up." It lists nothing: there is
     no private content until the private-documentation ADR (invariant 1).
   - **The sign-in ADR hides it from signed-out readers.** It adds the session read inside a
     `<Suspense>` boundary around this group, so the rest of `/` stays in the static shell. No
     viewer check, cookie read or preview variable is added before then.
6. **The site adopts Cache Components.**
   - `next.config.mjs` sets `cacheComponents: true` and `partialPrefetching: true`.
   - The `revalidate = false` exports go from the five route handlers (`llms.txt`,
     `llms-full.txt`, `llms.mdx/[...slug]`, `og/[...slug]`, `static.json`): they read no
     runtime data, so they are prerendered without it.
   - Every page stays prerendered, `/` included, until the sign-in ADR adds the first
     request-time part.
7. **Read it anywhere is redesigned around doing, not telling.** The three cards go, "Private
   stays private" among them.
   - **The terminal gets three tabs** in its title bar: `page.md`, `llms.txt` and `Accept`. Each
     shows a real command and the real first lines of its output, taken from the build:
     - `curl -s <origin><page>.md | head -6`;
     - `curl -s <origin>/llms.txt | head -6`;
     - `curl -s -H "Accept: text/markdown" <origin><page> | head -6`.

     The chosen tab types its command once (not under reduced motion). Under the terminal, one
     line: "Everything in one file: `/llms-full.txt`".
   - **Beside it, "Hand any page to your assistant":** the same two Fumadocs controls every docs
     page has, `MarkdownCopyButton` and `ViewOptionsPopover`, live, for the example page, with
     one line of text and a "See it on a page" link. They are the real components, not a picture
     of them.
8. **The theme switch is an orbit in phase.** The header keeps Fumadocs' `ThemeSwitch` (same
   button, next-themes behaviour, view transition and accessible name). CSS in `site.css`
   reshapes it:
   - a 36px square with a hairline border and 8px corners, like the header's other buttons, with
     the border strengthening on hover;
   - Fumadocs' sun and moon icons hidden; inside, a 14px planet on a tilted ring (the brand
     mark's ellipse), drawn with CSS;
   - a shadow disc that sweeps across the planet: a full disc in light, a crescent in dark. It
     eases over 0.4s and switches instantly under reduced motion;
   - keyed to the `.dark` class next-themes sets before first paint, so it is right on load.

   No new dependency.
9. **`.env.example` is added**, listing the variables the site reads today, names and comments
   only.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Hero search | A — opens the Fumadocs dialog, no filters | One search on every page; least code; what the owner asked for | No chips, no map lighting, no catalogue filter | Chosen by the owner |
| Hero search | B — opens the dialog; chips move to the catalogue | Keeps filtering | Custom filter UI stays | Rejected by the owner |
| Hero search | C — inline results on Fumadocs' search hook | Keeps every behaviour | Still a custom search UI | Rejected by the owner |
| Private rendering | A — route-level dynamic: `/` reads `cookies()` | Smallest change today | The whole home page renders per request once sign-in exists | Rejected by the owner |
| Private rendering | B — Cache Components: static shell, private group streamed | The rest of `/` stays static when sign-in arrives; the documented pattern for authenticated UI | Site-wide config change; the five `revalidate = false` exports go | Chosen by the owner |
| Private rendering | C — client-side fetch after load | `/` stays static | Needs an API route and a loading state | Rejected |
| Private now | A — empty state for everyone until sign-in | The owner can see and review it now; no preview switch | Tells the public a private projects group exists | Chosen by the owner |
| Private now | B — hidden until sign-in; development-only preview | Nothing about private work on a public surface | A preview variable; the empty state only in `bun run dev` | Rejected by the owner |
| Private now | C — hidden, no preview | Least code | The empty state cannot be seen until sign-in exists | Rejected |
| Read it anywhere | A — terminal with three tabs, and the live page actions | Shows instead of tells; every claim runs on the page; nothing about private | More interaction in the terminal | Chosen |
| Read it anywhere | B — keep two cards | Least change | The terminal and cards no longer balance | Rejected |
| Read it anywhere | C — a third card about `Accept: text/markdown` | True and on theme | Still three cards telling, not showing | Rejected |
| Theme switch | A — orbit phase, CSS over Fumadocs' `ThemeSwitch` | On theme; same behaviour; no dependency | Depends on the markup of Fumadocs' switch | Chosen by the owner |
| Theme switch | B — a sliding sun / moon pill | Very clear | Wider than the other header buttons | Rejected by the owner |
| Theme switch | C — a larger icon button | Lowest risk | Least distinctive | Rejected by the owner |

## Consequences [#consequences]

**Positive**

- One search, the same everywhere. The home page sheds its largest custom component and the
  filter code; the catalogue becomes server-rendered.
- Private projects have a place on the home page, and the sign-in ADR only has to add a
  boundary and a session read around it.
- "Read it anywhere" proves its claims with real commands and the real page controls.

**Negative / accepted trade-offs**

- No filtering on the home page. Readers browse grouped lists or use the dialog.
- Every reader sees that a Private projects group exists, with its empty state, until the
  sign-in ADR. No private name, count or content is shown.
- Cache Components is now on for the whole site. Later changes follow its model: `use cache`
  and `<Suspense>`, not route segment configs. Once a request-time part exists, `/` needs a
  Node.js server for it; hosting is not decided.
- The theme switch's look relies on Fumadocs' markup (`[data-theme-toggle]` and its two icons).
  An upgrade that changes it shows up in review.
- The Fumadocs dialog has no ecosystem, project or `dev` filters.

## Content invariants [#content-invariants]

- **Invariant 1** is why the private group lists nothing: no private content exists until the
  private-documentation ADR.
- **Invariant 5** is what the Read it anywhere tabs demonstrate. They only read existing
  routes.

## Security considerations [#security-considerations]

- **No access control yet.** The private group's empty state is public by the owner's decision;
  it carries no private data. Hiding it from signed-out readers is decided and enforced on the
  server by the sign-in ADR, inside the `<Suspense>` boundary this design leaves room for. A
  hidden element is never the control.
- **No new variable, no new input.** `.env.example` lists the existing Algolia variables, names
  only.
- **Third parties.** The "Open in ChatGPT / Claude / Cursor / Scira" links on the home page send
  a public page's URL to that service when the reader clicks one, exactly as on every docs page
  today.
- **RBAC:** none yet. Visibility does not depend on the reader until the sign-in ADR, which
  writes the first matrix.

## Implementation notes [#implementation-notes]

- [x] Hero: the search button opening the dialog; results, chips, "Try" row, demo, `/` and
      `⌘K` capture removed; map, legend and noscript link kept.
- [x] `search-state.tsx` and `hero-search.tsx` removed.
- [x] Header: no search on the home page (`SiteHeader`'s search is optional); anchors for
      Packages and Projects on home and docs headers.
- [x] Catalogue grouped into Packages and Projects, with ids `packages` and `projects`.
- [x] Orbit map: click opens the overview; no search lighting.
- [x] The Private projects group with its empty state, a Server Component.
- [x] Cache Components on; `revalidate` exports removed.
- [x] Read it anywhere: terminal tabs with build-time outputs; the live page actions for the
      example page; the `llms-full.txt` line.
- [x] Theme switch restyled in `site.css`.
- [x] `.env.example` with every variable, names only.
- [x] Tests — manual until ADR-0007 picks a runner (results in the report to the owner):
      - `next build` prerenders every page, `/` included;
      - the built `/` holds the Packages and Private projects groups, no "Private stays
        private", no chips and no results list;
      - each tab's output matches the route;
      - the switch's phase CSS keys to `.dark`.
- [x] `bun run types:check` and `bunx next build` pass; `bun run lint` blocked by TypeScript 7.

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

- [x] [`../app-flow/home-page.mdx`](../app-flow/home-page.mdx) and
      [`../prd/home-page.mdx`](../prd/home-page.mdx) — to match the build; the draft
      `home-search-and-private` app flow and PRD folded in and removed
- [x] [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx) — the header on the home page,
      the theme switch
- [x] [`../architecture/system.mdx`](../architecture/system.mdx) — Cache Components
- [x] [`../rbac/index.mdx`](../rbac/index.mdx) — still no matrix; the draft removed
- [x] [`../security/threat-model.mdx`](../security/threat-model.mdx),
      [`../security/secrets.mdx`](../security/secrets.mdx)
- [x] `DESIGN.md`, `AGENTS.md` §1 and §5, `README.md`
- [x] [`./index.mdx`](./index.mdx) — index row, status

## Open questions [#open-questions]

None open.


# ADR-0017 — The whole site is one solar system (/docs/maintain/adr/ADR-0017-the-whole-site-is-one-solar-system)

- **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:** [ADR-0014](./ADR-0014-home-page-is-a-search-first-release-map.mdx) decision 4
  (in part: the "Browse everything" heading and its ruled rows) and the footer;
  [ADR-0016](./ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx)
  decisions 3 (the catalogue as grouped rows), 5 (in part: what the private group shows) and 8
  (the orbit-phase theme switch CSS);
  [ADR-0015](./ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx) decision 9
  (in part: the package hero, the version notices and the docs chrome's look)
- **Superseded by:** [ADR-0018](./ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx); [ADR-0036](./ADR-0036-the-site-is-nepal-dev-verse.mdx) (in part: who the star is, and its label)
  (in part: decision 8 on docs pages, and decision 10's orbit lines and sidebar top);
  [ADR-0030](./ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx) (in part: decision 8, what the scene draws);
  [ADR-0032](./ADR-0032-the-heros-system-comes-alive.mdx) (in part: decision 2, what the hero's system draws);
  [ADR-0033](./ADR-0033-the-footer-says-you-have-reached-the-horizon.mdx) (in part: decision 8, the closing line's words and link)
- **Design documents:** [`../app-flow/solar-system.mdx`](../app-flow/solar-system.mdx),
  [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx),
  [`../prd/home-page.mdx`](../prd/home-page.mdx), `DESIGN.md`, `.impeccable/design.json`

## Context [#context]

The owner reviewed the home page built for ADR-0016 on 2026-11-01. In their words: the idea of
orbits and planets is good, but the site does not justify it. They asked for:

1. A footer that is more useful and different from a single credit line.
2. A different approach to Browse everything, and no "Browse everything" heading: there will be
   at most four or five packages and projects.
3. A redesigned private projects section, with sample projects and an empty state.
4. A clearer theme switch. The orbit-phase concept stays; the drawing is unclear.
5. The whole site reworked around the star, orbits and planets.

They then chose (2026-11-01):

- **Scope:** everything, docs pages included: home, header, theme switch, footer, package hero,
  version notices, 404, sidebar and table of contents.
- **Entries:** planet cards. Each package or project gets a card with its planet drawn in its
  ecosystem colour, its version lines as moons, a fact sheet and Use / Maintain links.
- **Private projects:** shown on the live site as real-looking projects, not marked as samples;
  their links may lead nowhere. The empty state is still designed.
- **Footer:** Horizon. A closing band where the star rises over a planet's curved horizon.

What the code and the installed packages settle:

- The metaphor already runs through the data: ecosystems are rings (`src/components/home/rings.ts`),
  entries are bodies, version lines are moons (ADR-0014). Only the home hero draws it; the cards,
  docs pages, footer and switch do not.
- **A custom theme switch needs no new dependency.** `fumadocs-ui/provider/base` exports
  `useTheme` (re-exported from next-themes; `package.json` `exports` lists `./provider/base`).
  Today's switch is Fumadocs' `ThemeSwitch` with its two icons hidden by CSS, so its drawing
  cannot show a sun and a terminator.
- **Fumadocs' notebook layout takes replacements for its slots.** The sidebar, TOC and page
  header are styled today through `src/app/site.css`; the version and track switches are this
  site's own components in `src/components/docs/`.
- **Cache Components stays as decided** (ADR-0016 decision 6). Nothing here reads runtime data.

## Decision [#decision]

1. **One metaphor, stated once and used everywhere.** The star is the maker, Puncoz Nepal, at the
   centre of the system. Each ecosystem is an orbit. A package is a solid planet in its
   ecosystem's colour; a project is a ringed planet. Each version line is a moon: the latest
   release full, older releases crescents, `dev` a new moon drawn dashed. Use is a planet's day
   side; Maintain its night side. The hero's legend teaches this once; every later surface uses
   the same marks without explaining them again.

2. **The hero is the system.** Text on the left and the system on the right on desktop; the
   system above the text on phones. The star is labelled "Puncoz Nepal". Every planet is always
   labelled (the catalogue stays small), its moons circle it, and its night side faces away from
   the star. Pointing at a planet slows the system and shows its card; clicking opens its
   overview. The hero search button and legend stay (ADR-0016 decision 1).

3. **Planet cards replace Browse everything.** No section heading on screen (a visually hidden
   h2, "Packages and projects", keeps the outline). One card per public entry, in catalogue
   order, in a grid that fits two or three across on desktop and one on phones. A card has:
   - a sky panel drawing the planet with one orbit per version line and its moons, each labelled
     with the line's name (`v0.1`, `dev`); unreleased orbits dashed; a project shows its ring
     and no moons;
   - the name, linked to the overview (the whole card is the link target);
   - kind and ecosystem, the description;
   - a fact sheet: Latest, In development, Older lines, from the catalogue fields;
   - Use →, Maintain and Demo links, each only when that track or page exists.
   `#packages` and `#projects` keep working as header anchors: the first package card carries
   `id="packages"`, the first project card `id="projects"`.

4. **Private projects sit beyond an asteroid belt.** A scattered belt divides the public
   planets from an h2 "Private projects" and one line of copy. Private projects are drawn as
   night-side planets on dashed orbits with a lock mark, in a lighter, dashed card: name,
   description and a short meta line (client or internal, which tracks). Their names link to
   their future URL, which returns the site's 404 today. The data lives in code, in
   `src/components/home/private-projects.ts`, never in `content/`. With no private projects,
   the group shows an empty dashed orbit and "No private projects in orbit yet. They'll appear
   here once private documentation is set up." Everyone sees the group until the sign-in ADR
   (ADR-0016 decision 5 stands for who sees it).

   The private projects shown are **harbor-ops** ("Operations dashboard for a shipping
   client."), **fieldnote** ("Offline survey app for field teams.") and **tessera** ("Internal
   billing and invoicing service."). They are invented names chosen by the owner's instruction;
   they are not marked as samples on the page.

5. **Two sides of every planet** replaces "Two tracks, one place": Use as the day side and
   Maintain as the night side, split by a terminator drawn through a planet. Each side lists
   real pages of one featured entry with their line, as today's preview does.

6. **Every moon, released or not** replaces the version rails: one row per entry with two or
   more lines, its moons in order (older crescents, the latest full, `dev` new and dashed), each
   with its name and version. A three-item legend names the phases.

7. **Read it anywhere stays** (ADR-0016 decision 7) with the new card and panel styling.

8. **The Horizon footer, on every page.** A closing line, "Everything here orbits one maker:
   Puncoz Nepal" (linked to `https://puncoz.com`); below it the star rising behind a planet's
   curved horizon with a thin atmosphere rim in the accent colour; then, on the planet's surface,
   one link per public planet (its mark and name), and a row with Search `⌘K`, `llms.txt`,
   `llms-full.txt`, GitHub and "Back to orbit ↑". On docs pages the footer drops the scene and
   keeps the surface rows, so reading pages stay calm. The links wrap on phones.

9. **The theme switch is a small orrery** (supersedes ADR-0016 decision 8). A client component,
   `src/components/theme-switch.tsx`, using `useTheme` from `fumadocs-ui/provider/base`, draws
   an inline SVG in the 36px header button: a tilted orbit, a sun on it and a planet with a
   terminator. In light the sun stands in front of the planet and its face is fully lit (day
   side); in dark the sun moves behind the planet, smaller, and the planet shows a thin crescent
   (night side). The change animates for about half a second, and instantly under reduced motion.
   Its accessible name says what it does: "Switch to night side (dark theme)" or "Switch to day
   side (light theme)", and a tooltip says the same. Before hydration it renders the dark
   drawing (the site's default) with no layout shift.

10. **Docs pages keep the planet in view.** In the Fumadocs notebook layout:
    - the sidebar opens with a **planet chip** (mark, name, kind), a **day/night switch** for Use
      and Maintain (sun and moon marks drawn as SVG), and on Use a **moon picker** whose items
      show each line's phase mark;
    - the sidebar's link list and the TOC hang on a thin **orbit line**; the current page is a
      filled planet dot on that line;
    - an entry's overview opens with a **planet header**: kind, name, description, fact sheet and
      links on the left, its planet and labelled moons drawn on the right (below on phones);
    - **version notices** carry the moon of their line: crescent for an older release, a dashed
      new moon for `dev`;
    - page headings and body text are unchanged; the reading column stays calm.

11. **The 404 is "drifted out of orbit".** A planet that has left its dashed orbit, the heading
    "This page drifted out of orbit.", one line of help, the search button and "Back to the
    system →". It replaces Fumadocs' default not-found page for every path.

12. **The search dialog stays Fumadocs' own**, coloured by the existing tokens.

13. **Tokens.** One token is added, `--star` (light `#e08a00`, dark `#ffe2a8`) with
    `--star-glow`, and `--night` for a planet's unlit face. Everything else uses the existing
    tokens and fonts (ADR-0015). Every planet, moon, sun, lock and phase mark is drawn SVG; no
    emoji or text glyphs as icons.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| Scope A — everything, docs pages too | One world from home to the last docs page; the owner's ask | Largest change; touches the notebook layout's chrome | **Chosen** by the owner |
| Scope B — home page, header, switch and footer only | Smaller | Docs pages keep the old look; the metaphor stops at the home page | Rejected |
| Entries A — planet cards with moons and fact sheet | Uses the metaphor to carry real data (versions); suits 4–5 entries | Taller than rows; needs care to stay readable at one column | **Chosen** by the owner |
| Entries B — the hero system as the only index, no cards | Most striking | Hides facts behind hover; poor for keyboard and screen readers | Rejected |
| Entries C — keep ruled rows, no heading | Least work | Does not answer "the site does not justify the concept" | Rejected |
| Private A — invented projects on the live site, unmarked | What the owner asked for; shows the section's intended shape | Visitors read invented projects as real; dead links (see trade-offs) | **Chosen** by the owner |
| Private B — invented projects only in prototypes; empty state live | Nothing invented reaches the public site | The live section stays an empty state until the sign-in ADR | Rejected by the owner |
| Footer A — Horizon | A real ending; carries useful links (planets, llms, search, top) | A large decorative band | **Chosen** by the owner |
| Footer B — a compact link grid | Familiar, small | Generic; no part of the world | Rejected |
| Switch A — custom SVG orrery with `useTheme` | Can draw a sun and a terminator; no new dependency | A component to own instead of Fumadocs' | **Chosen** (recommended) |
| Switch B — restyle Fumadocs' `ThemeSwitch` with CSS only | No new component | CSS pseudo-elements cannot draw the terminator clearly; that is today's problem | Rejected |

## Consequences [#consequences]

**Positive**

- One idea explains the whole site: a reader who learns the legend on the home page can read
  versions and tracks on every docs page from the marks alone.
- The cards carry the facts the rows carried, plus the version lines, without a heading or a
  filter.
- The footer is useful: it links every planet, the Markdown routes, search and the top.
- The switch states its result in words and in the drawing.

**Negative / accepted trade-offs**

- **Invented private projects on the live site.** harbor-ops, fieldnote and tessera are not real
  projects, but the page presents them as real. Visitors may ask about them, and their links
  return the 404. This departs from `PRODUCT.md`'s "no invented data" stance and from ADR-0016's
  "no private project, name or count exists on the site". The owner accepts it; replacing the
  list is a code change in one file.
- More SVG on every page. The drawings are small, inline and static except the hero canvas.
- A custom theme switch to maintain, and the notebook sidebar's chrome to keep working across
  Fumadocs upgrades.
- The 404 becomes this site's own page.

## Content invariants [#content-invariants]

- **1, Private stays private.** Kept in substance: no private documentation exists, and the
  invented private projects are names and one-line descriptions in a component file, never in
  `content/`, the search index, `static.json`, `llms.txt`, `llms-full.txt`, per-page Markdown or
  Open Graph images. They are not real projects, so nothing private is disclosed. Real private
  project names must never be put in that file: that waits for the private-documentation ADR.
- **3, version on every page.** Strengthened: the moon picker and notices show the line and its
  version.
- **5, readable as Markdown.** Unchanged: the redesign changes HTML chrome only.
- **2 and 4** are untouched.

## Security considerations [#security-considerations]

- **Data handled:** public catalogue fields (unchanged) and three invented private project
  entries, classified public. No secret, environment variable or endpoint is added.
- **Private to public:** the invented list is the one place a private project name could ever be
  typed into code. The risk is that someone later replaces an invented name with a real client
  name. Mitigation: the file states that only invented entries belong there until the
  private-documentation ADR, and `security/threat-model.mdx` records the risk.
- **Authorization:** none; everyone sees the same page (ADR-0016 decision 5).
- **What leaves the system:** nothing new. The invented entries are not sent to Algolia.
- **Input:** none new. The 404 renders no part of the requested path.
- **Residual risk accepted:** visitors may take the invented private projects as real.

## Implementation notes [#implementation-notes]

- [x] `src/app/global.css`: the star and night tokens in light and dark, named in the site's
      `--home-*` set: `--home-star`, `--home-star-glow`, `--home-night`.
- [x] `src/components/theme-switch.tsx`: the orrery switch; `site-header.tsx` uses it instead of
      `ThemeSwitch`; the orbit-phase CSS in `site.css` is removed.
- [x] `src/components/planet.tsx`: `PlanetSystem` (the planet-with-moons drawing: `ring`, `kind`,
      `lines`, size and scale), shared by the cards and the planet header; `PlanetMark` for the
      sidebar chip, kinds and footer; and `MoonPhase` for the phase marks, in the same file.
      Ring helpers and kind names moved to `src/lib/rings.ts`.
- [x] `src/components/home/orbit-map.tsx`: the star, its label, always-on planet labels, moons,
      night sides; layout split left/right on desktop.
- [x] `src/components/home/planet-cards.tsx` replaces `catalogue.tsx`; `page.tsx` drops the
      "Browse everything" heading; anchors move onto the first cards.
- [x] `src/components/home/private-projects.ts` (the invented list, with its warning comment)
      and the belt with both states in `src/components/home/beyond-the-belt.tsx` (named apart
      from the data file, so the two modules don't share a name).
- [x] Two sides (`two-sides.tsx`, replacing `tracks-preview.tsx`), Every moon (`moon-rows.tsx`,
      replacing `version-rails.tsx`) and Read it anywhere restyled in `home.css`.
- [x] `src/components/horizon-footer.tsx`, used by the home page, the 404 and, without the
      scene, by the docs layout.
- [x] Docs chrome: planet chip and day/night switch in `src/components/docs/track-switch.tsx`;
      moon icons on Fumadocs' version menu from the layout's `tabs.transform`; the current page's
      planet dot on the sidebar's and the contents' lines, planet header and notices in
      `site.css`.
- [x] `src/app/not-found.tsx`: the out-of-orbit page.
- [ ] Tests — the happy path **and** the obvious failure paths (ADR-0007). No test runner is
      installed yet (its own ADR). Verified instead: the build prerenders every page, and the
      built HTML of `/`, `/docs`, `/docs/maintain` and the 404 holds the new parts. Browser
      checks (layout at phone width, the canvas, the switch's animation, contrast of the star
      and night tokens) are not run.
- [ ] `bun run lint` is blocked (typescript-eslint does not support TypeScript 7);
      `bun run types:check` and `bunx next build` pass.

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

- [x] `content/docs/maintain/app-flow/solar-system.mdx` is current for the shared look (marks,
      theme switch, planet header, sidebar, notices, footer, 404); `home-page.mdx` keeps the home
      page's screens, matching its PRD's slug; `site-pages.mdx` keeps routes, header and docs
      pages and points to both
- [x] `content/docs/maintain/prd/home-page.mdx` — planet cards, private states, footer, switch
- [x] `content/docs/maintain/security/threat-model.mdx` — the invented private list
- [x] `DESIGN.md` and `.impeccable/design.json` — the metaphor, new tokens and components
- [x] `PRODUCT.md` — the invented-data exception for the private list
- [x] `AGENTS.md` §1 and §5 and the repository map; `PROJECT_AGENTS.md` does not describe the
      look, so it is unchanged
- [x] `README.md` — the home page summary
- [x] `content/docs/maintain/adr/index.mdx` — status
- [x] ADR-0014, ADR-0015 and ADR-0016 — "Superseded by" in their headers


# ADR-0018 — Docs pages get orbit stations, a trajectory and the full horizon (/docs/maintain/adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon)

- **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:** [ADR-0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) decision 8 (in
  part: docs pages dropping the horizon's scene) and decision 10 (in part: the sidebar's link
  list and the table of contents hanging on a thin orbit line, and the sidebar top's layout)
- **Superseded by:** [ADR-0019](./ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar.mdx)
  (in part: decision 2, how an ADR folder's pages show);
  [ADR-0023](./ADR-0023-sidebar-stations-open-one-at-a-time.mdx) (in part: decision 2's *Open and
  closed* point, stations now open one at a time),
  [ADR-0027](./ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx) for decision 2, in part
  (every folder a card; how top-level pages and separators look);
  [ADR-0030](./ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx) (in part: decision 4, the footer sitting below the sidebar, and its scene)
- **Design documents:** [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx),
  [`../prd/docs-sidebars.mdx`](../prd/docs-sidebars.mdx),
  [`../app-flow/solar-system.mdx`](../app-flow/solar-system.mdx),
  [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx), `DESIGN.md`

## Context [#context]

ADR-0017 made the whole site one solar system, but the two columns a reader uses most on a docs
page still look like Fumadocs' defaults with a dot added:

- **The left sidebar** is Fumadocs' list: folders as plain rows with a straight guide line, the
  current page marked by a dot. The metaphor stops at the planet chip.
- **The right-hand "On this page"** is Fumadocs' `normal` table of contents. Its rail curves only
  where heading depth changes (`components/toc/default.js` draws a cubic curve between items of
  different depth and a straight line otherwise), so on a page whose headings are all `##` it is
  one straight line. The owner remembers it as "tech-like" and curvy, and finds it plain now.
- **The horizon** below docs pages drops its scene and closing line (ADR-0017 decision 8). The
  owner wants the full horizon on every page.

The owner chose, from options with previews (2026-11-01): **orbit stations** for the left
sidebar, a **trajectory with a probe** for "On this page", and the **full horizon** on docs
pages.

Facts this decision rests on, read from the installed Fumadocs 16.17.9:

- The notebook layout's `sidebar.components` accepts `Item`, `Folder` and `Separator`
  components (`SidebarPageTreeComponents`, `components/sidebar/page-tree.d.ts`). The default
  renderer opens a folder when the current page is inside it (`active: path.includes(node)`),
  and otherwise follows `defaultOpenLevel`, 0 by default, so other folders start closed.
- `DocsPage` takes `slots.toc` with `provider`, `main` and `popover`
  (`layouts/notebook/page/index.d.ts`); `main` is the desktop column and `popover` the bar on
  narrow screens.
- `fumadocs-core/toc` exports `useItems`, `useActiveAnchors` and `AnchorProvider`; each item has
  `title`, `url` and `depth`.
- Each page's `structuredData` (fumadocs-mdx) holds its headings and text, so its word count is
  known at build time without reading the file again.

## Decision [#decision]

1. **The sidebar top becomes one planet row.** The planet chip (mark and name, linked to the
   overview) and the day/night switch share one row: the switch shrinks to two icon buttons, a
   drawn sun for Use and a drawn moon for Maintain, each with its full name as its accessible
   name and tooltip. The moon picker sits under it on Use, as today.

2. **Every section is an orbit station.** A sidebar folder renders as a station: a card
   (12px radius, 1px border, the panel colour) with a header and its pages.
   - **Header:** a small orbit drawing (a ring, with a filled planet on it when the current page
     is inside), the section's name, the number of pages in it, and a chevron. When the folder
     has an index page, the name links to it, as Fumadocs does today.
   - **Pages are moons.** Inside an open station each page is a row with a moon dot, and the
     dots sit on one arc of the station's orbit, drawn in the left gutter: the arc bows outward,
     so a long station is a gentle curve, never a ruled line. The current page is the planet: an
     accent dot with a halo, its row tinted with the entry's ecosystem colour, marked
     `aria-current="page"`. Hovering a row fills its dot.
   - **Open and closed.** The station holding the current page opens and its border takes the
     ecosystem colour; the others start closed and show only their header, so a long sidebar
     (this site's Maintain track has twelve sections) scans as a list of station names. The
     chevron opens and closes a station.
   - **Nested folders** are smaller stations inside their parent, without a card border: a
     smaller orbit drawing and a shorter arc. Deeper levels indent without a further drawing.
   - **Top-level pages** outside any folder (an overview) sit above the stations on their own
     short arc, with the same moon dots. A Fumadocs separator is a dotted line with its label.

3. **"On this page" is a trajectory with a probe.** Our own component replaces Fumadocs'
   `normal` table of contents in both `slots.toc.main` and `slots.toc.popover`, built on
   `useItems` and `useActiveAnchors`.
   - **The path.** One continuous curved path through a dot per heading, drawn in a 28px gutter.
     Depth sets each dot's offset (`##` 6px, `###` 18px, deeper 26px). Between two headings of
     the same depth the path bows outward in a shallow arc; across a depth change it swings in an
     S-curve. So the path curves on every page, including one with only `##` headings.
   - **Read and unread.** The stretch already read is drawn solid in the accent colour, and its
     dots filled. The stretch ahead is drawn dashed and muted, with hollow dots, the same dashed
     language as an unreleased moon.
   - **The probe.** A small planet (accent, with a halo and a shaded night side) rides the path
     at the reader's position, gliding between dots as they scroll through a section, not jumping
     from heading to heading. The active heading's text takes the foreground colour.
   - **Time left.** The header reads "On this page" and, at the right, "4 min left": the page's
     reading time, from its word count at build time at 220 words a minute, scaled by how much
     is still unread and rounded up. At the end of the page it reads "End of page". A page under
     one minute shows no time.
   - **Back to top.** Under the list, "Back to top ↑", shown once the reader has scrolled past
     the first heading.
   - **On phones**, Fumadocs' bar under the header becomes our bar: a small ring with the probe
     at the reading position, the current heading, and the time left. Tapping it opens the same
     trajectory as a sheet; choosing a heading scrolls there and closes it.
   - Choosing a heading scrolls to it smoothly, and instantly under reduced motion, where the
     probe also jumps from dot to dot instead of gliding.

4. **The full horizon closes every page** (supersedes ADR-0017 decision 8, in part). Docs pages
   get the same footer as the home page: the closing line, the star rising over the planet's
   edge, the planet row and the link row, across the full width below the sidebar and the page.
   Its last link reads "Back to top" on docs pages and "Back to orbit" on the home page and the
   404. The `compact` variant is removed.

5. **What stays.** The moon picker, version notices, planet header, page headings, body text
   and reading column are unchanged. Search, the header and the theme switch are unchanged.
   Every drawing is inline SVG in the existing tokens (ADR-0017 decision 13); no dependency is
   added.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Left sidebar | A — orbit stations | Each section reads as a place in the system; closed stations make long sidebars short | A custom `Folder` and `Item` to own; a card per section takes more height when open | Chosen (owner) |
| Left sidebar | B — planet console: the moons as the version picker, a sliding terminator for Use and Maintain, one continuous path through every page | The strongest use of the metaphor | The most custom code; replaces Fumadocs' version menu | Rejected |
| Left sidebar | C — refined classic: today's structure, polished | Lowest risk | Changes little; the metaphor still stops at the chip | Rejected |
| On this page | A — trajectory with a probe and time left | Curves on every page; shows progress and what is left | Our own component in place of Fumadocs' | Chosen (owner) |
| On this page | B — orbit dial: a reading-progress orbit above a curved list | Compact and playful | Progress and the list sit apart | Rejected |
| On this page | C — Fumadocs' `clerk` style, recoloured | No custom code | Least distinctive; still Fumadocs' look | Rejected |
| Horizon on docs pages | A — the full horizon | One footer everywhere | A long page ends with a tall footer | Chosen (owner) |
| Horizon on docs pages | B — the scene without the closing line | Shorter | Two footers to keep | Rejected |
| Reading time | A — word count at build time from `structuredData` | No work in the browser; the same number in every visit | Code blocks count as words | Chosen |
| Reading time | B — count the rendered text in the browser | Counts exactly what is shown | Work on every visit; differs before hydration | Rejected |

## Consequences [#consequences]

**Positive**

- Both columns carry the metaphor: sections are stations, pages are moons, reading is a
  trajectory.
- "On this page" curves on every page and tells the reader how far they are and how long is
  left.
- Long sidebars, such as this site's Maintain track, collapse to station names.
- One footer on every page.

**Negative / accepted trade-offs**

- Two Fumadocs parts are replaced by our own (the sidebar's folder and item, the table of
  contents and its phone bar). A Fumadocs upgrade that changes those slots needs a check.
- An open station takes more height than a plain folder.
- The full horizon adds height to the end of every docs page.
- Reading time is an estimate; long code blocks overstate it.

## Content invariants [#content-invariants]

- **3 (Version on every page)** and **5 (Readable as Markdown)**: unchanged. The trajectory and
  stations are page chrome; the per-page Markdown, `llms.txt` and `llms-full.txt` don't include
  them.
- No other invariant is touched; no content changes.

## Security considerations [#security-considerations]

None. This change touches no data, no endpoint and no secret. The reading time is computed at
build time from the page's own public text; nothing new leaves the system, and nothing is stored
in the browser.

## Implementation notes [#implementation-notes]

- [x] `src/lib/trajectory.ts`: the path builder (dot offsets by depth, arcs and S-curves between
      dots, the length at each dot), the probe's position, the time-left function, and the
      sidebar's station arcs (`arcRow`, `arcSlot`). Pure functions, no React.
- [x] `src/lib/reading-time.ts`: words in a page's `structuredData`, and its minutes at 220 a
      minute. Found on implementation: fumadocs-mdx structures headings, paragraphs, quotes,
      tables and JSX blocks, not code blocks, so code does not count towards the reading time.
- [x] `src/components/docs/trajectory-toc.tsx` (client): the desktop column and the phone bar,
      passed as `slots.toc.main` and `slots.toc.popover` from `src/app/(site)/[...slug]/page.tsx`,
      which also passes the page's minutes through `ReadingTimeProvider`. Fumadocs' `TOCProvider`
      stays the provider. The reading position is measured from the headings' places on the page
      (the probe needs how far between two headings the reader is), so it uses `useTOCItems`
      rather than `useActiveAnchors`.
- [x] `src/components/docs/orbit-station.tsx` (client): `OrbitStation`, `OrbitItem` and
      `OrbitSeparator`, passed as `sidebar.components` in `src/app/(site)/layout.tsx`, built on
      Fumadocs' sidebar primitives (`fumadocs-ui/components/sidebar/base`) so opening, closing
      and the drawer keep working.
- [x] `src/components/docs/track-switch.tsx`: the planet row (decision 1); the banner carries
      `data-ring`, from which the sidebar takes its ecosystem colour.
- [x] `src/app/(site)/layout.tsx`: the full `HorizonFooter` with `backLabel="Back to top"`;
      `compact` removed from `src/components/horizon-footer.tsx`.
- [x] `src/app/site.css`: station, trajectory, probe and phone bar styles, with reduced-motion
      and `hover: none` rules; the orbit-line and dot overrides on Fumadocs' list and table of
      contents removed.
- [x] Tests (ADR-0007, runner ADR-0021): `src/lib/trajectory.test.ts` and
      `src/lib/reading-time.test.ts` cover the offsets by depth, the arc between equal depths and
      the S-curve across a change, one heading and none, the probe before, within and past a
      section, the time left (counting down, the end, before hydration, under a minute, never
      zero), the station arc and its slots, and reading time. The client components that draw
      them need a browser and are not unit-tested (ADR-0021 decision 5).
- [x] Checked in the built HTML: twelve stations on this site's Maintain pages with the current
      one open and marked, the current page with `aria-current="page"`, the trajectory column and
      phone bar, and the full horizon with its closing line and scene. Not yet looked at in a
      browser.
- [ ] `bun run lint` is blocked by typescript-eslint and TypeScript 7 (reported);
      `bun run types:check` and `bunx next build` pass.

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

- [x] [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx): status Current
- [x] [`../prd/docs-sidebars.mdx`](../prd/docs-sidebars.mdx): status Current
- [x] [`../app-flow/solar-system.mdx`](../app-flow/solar-system.mdx): screen 3 (sidebar top) and
      screen 5 (the footer on docs pages)
- [x] [`../app-flow/site-pages.mdx`](../app-flow/site-pages.mdx): the docs page screen
- [x] [`../architecture/system.mdx`](../architecture/system.mdx): the new components and lib files
- [x] `DESIGN.md` and `.impeccable/design.json`: the station, trajectory and probe components
- [x] `AGENTS.md` §1, §5 and §10; `README.md` if its layout section names the changed files
- [x] [`./index.mdx`](./index.mdx): index row and status; ADR-0017's "Superseded by" header


# ADR-0019 — ADR folders show as a constellation in the sidebar (/docs/maintain/adr/ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar)

- **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:** [ADR-0018](./ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx)
  decision 2 (in part: how an ADR folder's pages show inside its station)
- **Superseded by:** —
- **Design documents:** [`../app-flow/adr-constellation.mdx`](../app-flow/adr-constellation.mdx),
  [`../prd/adr-constellation.mdx`](../prd/adr-constellation.mdx),
  [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx), `DESIGN.md`,
  `PROJECT_AGENTS.md`

## Context [#context]

ADR-0018 made every sidebar folder an orbit station whose pages are rows on an arc. On this
site's Maintain pages the Decisions station holds 18 ADRs, one 32px row each, so when it is open
it takes about 600px of sidebar. It grows with every decision, and every package and project
that keeps ADRs in its Maintain track will have the same problem.

The owner chose (2026-11-01), from options with previews: a **constellation**, a compact grid
of moons in place of the rows; applied to **ADR folders in every entry's docs**, not to long
folders in general and not to this site alone.

Facts this decision rests on:

- Each folder node in the page tree carries `$ref.folder`, its path under `content/`
  (`docs/maintain/adr` for this site's ADRs), read from the built page tree.
- ADR titles start with their number, `ADR-NNNN — …` (the ADR template).
- Every ADR states its status in its first lines, `- **Status:** Approved` (the ADR template).
  The text fumadocs-mdx structures for search keeps that line, `**Status:** Approved`, so the
  status is known at build time (read in the built `static.json`).

## Decision [#decision]

1. **Which folders.** A folder whose own name is `adr` (the last segment of `$ref.folder`), in
   any package's or project's docs, shows as a constellation. Every other folder stays an orbit
   station as ADR-0018 decided. Consuming repositories get it by keeping their ADRs in
   `maintain/adr/`; `PROJECT_AGENTS.md` says so.

2. **The station's header stays**: orbit glyph, name, page count and chevron. It opens on any of
   its pages and on its index page, and starts closed elsewhere.

3. **The constellation.** Inside the open station, the folder's pages (its index excluded) are
   a grid of moons in page order, oldest first, as many to a row as fit (about nine in the
   268px sidebar, more in the phone drawer). Each moon is a link with a 24px target.
   - **Its phase is its status**, the same language as version lines: **full** for Approved (in
     force), a **dashed new moon** for Proposed (not yet in force), a **crescent** for
     Superseded (an older decision), a hollow faint ring for Rejected or a page without a status
     line.
   - **The current page is the planet**: the teal planet with its glow, ringed in the ecosystem
     colour.
   - Each link's accessible name is its full title and status, "ADR-0016 — Home search is the
     Fumadocs dialog…, Approved".

4. **The readout.** Under the grid, one line shows the moon being pointed at or focused, its
   number and title ("16 · Home search is the Fumadocs dialog, and private projects render
   server-side", wrapping to two lines at most); with nothing pointed at, the current page's; on
   the folder's index page, a summary ("18 decisions · 1 proposed"). The number comes from the
   title's `ADR-NNNN`, or the page's place in the folder when the title has none.

5. **Previous and next.** Under the readout, "← 15" and "17 →" link to the neighbouring pages,
   with their titles as accessible names; each is left out at the ends and on the index page.

6. **The register link.** "All 18 decisions →" links to the folder's index page, where the
   full list is read. Left out when the folder has no index page.

7. **A legend**, one 11px line under the register link: full "approved", dashed "proposed",
   crescent "superseded", drawn with the same marks.

8. **The status reaches the sidebar from the server.** The docs layout reads each ADR's status
   from its structured text at build time and passes a map of page URL to status to the sidebar
   through a client context, with the rest of the page. No request at run time.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Display | A — constellation: a grid of moons, a readout, previous and next, the register | Constant height at 18 or 60 ADRs; the solar-system look; status at a glance | Other titles appear only on pointing or focus; reading every title happens on the register | Chosen (owner) |
| Display | B — neighbours window: the current page and two either side, the rest folded | Titles readable | Familiar; still about seven rows; less distinctive | Rejected |
| Display | C — register only: no pages listed in the sidebar | Shortest | Every jump goes through the index page | Rejected |
| Scope | A — ADR folders in every entry's docs | Every project's decisions get it; no flag to learn | Recognised by folder name | Chosen (owner) |
| Scope | B — any station over eight pages | Automatic for long references too | Titles hidden for folders that are read by title | Rejected |
| Scope | C — folders that opt in through `meta.json` | Explicit | A schema change; each project must know the flag | Rejected |
| Scope | D — this site's ADRs only | Smallest | Special-case code; no project benefits | Rejected |
| Moon phase | A — the ADR's status, in the version lines' language | Status at a glance; one meaning for each phase: in force, not yet, older | Phases now mean status here and release state on lines | Chosen (owner) |
| Moon phase | B — every moon the same | Simplest | The grid says nothing but position | Rejected |
| Status source | A — the status line, read from the structured text at build | No change to how ADRs are written | Depends on the template's `**Status:**` line; a page without it shows the faint ring | Chosen |
| Status source | B — a `status` field in each ADR's frontmatter | Explicit and validated | A schema change, and every existing ADR edited | Rejected |

## Consequences [#consequences]

**Positive**

- The Decisions station stays about seven rows tall however many ADRs there are.
- Each ADR's status shows in the sidebar.
- Consuming repositories get the same with no configuration.

**Negative / accepted trade-offs**

- A reader scanning for an ADR by title points at moons or opens the register.
- The status is read from a line of text; an ADR that drops the template's status line shows
  the faint ring until fixed.
- A folder named `adr` that is not decisions would be shown as a constellation.
- One more custom piece of sidebar to keep in step with Fumadocs.

## Content invariants [#content-invariants]

Unchanged. The constellation is page chrome; the per-page Markdown and `llms.txt` don't include
it, and every ADR is still listed on its folder's index page.

## Security considerations [#security-considerations]

None. This change touches no data, no endpoint and no secret. The status map is built from the
same public pages it describes and sent with them; nothing new leaves the system.

## Implementation notes [#implementation-notes]

- [x] `src/lib/adr-status.ts`: the status from a page's structured text, the number and short
      title from its title, and whether a folder is named `adr`. Pure functions.
- [x] `src/components/docs/adr-constellation.tsx` (client): the grid, readout, previous and
      next, register link and legend; `OrbitStation` renders it for a folder named `adr`. Found
      on implementation: a folder named `adr` that has sub-folders keeps the plain station, so
      none of its pages are hidden.
- [x] The status map: built in `src/app/(site)/layout.tsx` from every page in a folder named
      `adr` (its index excluded), passed through `AdrStatusProvider` around the layout.
- [x] The rejected or unknown ring is drawn in the constellation; `MoonPhase` is unchanged.
- [x] `src/app/site.css`: constellation styles, with focus and reduced-motion rules. The readout
      keeps two lines of height, so pointing at moons doesn't move the links under it. On touch
      screens only focus sets the readout, so a tap opens the ADR.
- [x] Tests (ADR-0007, runner ADR-0021): `src/lib/adr-status.test.ts`, each status, a
      backticked status, no status line, another word, a title with and without `ADR-NNNN`, the
      short title, folder detection. The constellation itself is a client component and is not
      unit-tested (ADR-0021 decision 5).
- [x] Checked in the built HTML: on ADR-0016 the Decisions station is a constellation of 19 moons
      (7 approved, 12 proposed), ADR-0016 lit as the planet, the readout "16 · Home search is…",
      previous and next, and "All 19 decisions"; on the register page the summary "19 decisions
      · 12 proposed" with no previous or next; elsewhere the station starts closed. Not yet looked
      at in a browser.
- [ ] `bun run types:check` and `bunx next build` pass; `bun run lint` stays blocked
      (typescript-eslint and TypeScript 7).

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

- [x] [`../app-flow/adr-constellation.mdx`](../app-flow/adr-constellation.mdx) and
      [`../prd/adr-constellation.mdx`](../prd/adr-constellation.mdx): status Current
- [x] [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx): screen 1 names the
      exception
- [x] [`../architecture/system.mdx`](../architecture/system.mdx): the new files
- [x] `DESIGN.md` and `.impeccable/design.json`: the constellation component
- [x] `AGENTS.md` §1, §5 and §10; `PROJECT_AGENTS.md`: keep ADRs in `maintain/adr/`, with the
      template's status line
- [x] [`./index.mdx`](./index.mdx): index row and status; ADR-0018's "Superseded by" header


# ADR-0020 — People in ADRs are GitHub usernames, shown as profile chips (/docs/maintain/adr/ADR-0020-people-in-adrs-are-github-usernames-shown-as-profile-chips)

- **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:** [ADR-0002](./ADR-0002-living-design-documentation.mdx) decision 5 (in part: "no
  externally hosted images", for the avatar in a profile chip)
- **Superseded by:** —
- **Design documents:** [`../app-flow/github-profile-chips.mdx`](../app-flow/github-profile-chips.mdx),
  [`../dfd/system.mdx`](../dfd/system.mdx), [`../security/threat-model.mdx`](../security/threat-model.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx), `AGENTS.md` §2 and §8,
  `PROJECT_AGENTS.md` §3

## Context [#context]

The owner asked (2026-11-01) that the people in an ADR, its deciders and approvers, be named by
their GitHub username; that an ADR page link to each person's GitHub profile and show their
profile picture if possible; and that agents in consuming repositories ask for a username they
don't already have.

The text side was done on the owner's direct instruction, as a content change: every ADR's
`Deciders` and `Approved by` line, and the template's, reads
`[@puncoz](https://github.com/puncoz)`; `AGENTS.md` §2 and `PROJECT_AGENTS.md` §3 and §7 say to
write people that way and to ask for an unknown username. What remains is a UI change, the
profile picture, and it departs from a rule, so it is this ADR.

The owner chose, from options:

- **Format:** a plain Markdown link, `[@user](https://github.com/user)`, not a component or a
  frontmatter field.
- **Avatar:** loaded live from GitHub, not a copy committed to the repository.

Facts this decision rests on, checked:

- MDX links on docs pages render through `a: createRelativeLink(source, page)` in
  `src/app/(site)/[...slug]/page.tsx`, over Fumadocs' `a: Link` (`fumadocs-ui/dist/mdx.js`).
  Fumadocs' `Link` opens an external link in a new tab (`fumadocs-core/dist/link.js`).
- `https://github.com/puncoz.png` answers `302` to
  `https://avatars.githubusercontent.com/u/7767424?v=4` (`cache-control: no-cache` on the
  redirect); the image is a JPEG with `cache-control: max-age=300`. `?size=40` is passed on as
  `s=40`. Checked with `curl -I` on 2026-11-01.
- The Markdown surfaces (`/<page>.md`, `llms-full.txt`, `static.json`) carry the link as text.
- `AGENTS.md` §8 and ADR-0002 decision 5 say "No binary or externally hosted images".

## Decision [#decision]

1. **People in an ADR are GitHub usernames.** Every person an ADR names as deciding or
   approving is written as a profile link, `[@user](https://github.com/user)`. The owner is
   `puncoz`. An agent that does not know a person's username asks for it, and never writes a
   display name in its place or guesses one (`AGENTS.md` §2, `PROJECT_AGENTS.md` §3).

2. **A profile link renders as a chip.** On any page, a link whose text is exactly `@user` and
   whose address is exactly `https://github.com/user`, for the same `user` (compared without
   case) and a valid GitHub username (1 to 39 letters, digits or single hyphens, not starting
   or ending with a hyphen), shows as a chip: a 20px round avatar beside `@user`, linking to
   the profile and opening in a new tab like the site's other external links. Every other link
   is unchanged. The site's `a` component checks the shape and hands everything else to
   `createRelativeLink` as today.

3. **The avatar is loaded live from GitHub**:
   `<img src="https://github.com/<user>.png?size=40" width="20" height="20" alt="" loading="lazy" decoding="async" referrerpolicy="no-referrer">`.
   The username's first letter sits behind the image, so while it loads, or if it is blocked or
   missing, the chip shows the letter. The image is decorative: the link's name is its visible
   `@user` text, with the title "@user on GitHub".

4. **Nothing changes in the Markdown surfaces.** The per-page Markdown, `llms.txt`,
   `llms-full.txt` and the search records keep the link as written; no image URL is added.

5. **The one exception to "no externally hosted images".** The avatar in a profile chip is the
   only externally hosted image on the site. `AGENTS.md` §8 says so, and this ADR supersedes
   ADR-0002 decision 5 for it alone.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Format | A — a Markdown link, `[@user](https://github.com/user)` | Reads and works anywhere: GitHub, the Markdown routes, an editor; no schema change | The site has to recognise a link's shape | Chosen (owner) |
| Format | B — an MDX component, `<GitHubUser name="puncoz" />` | Explicit | Markdown readers and GitHub see a bare tag | Rejected |
| Format | C — frontmatter, `deciders: [puncoz]` | Validated by the schema | A schema change; every ADR's header rewritten; the header lines lose the names | Rejected |
| Avatar | A — loaded live from `github.com/<user>.png` | Always current; no file to keep; works on any host | Each reader's browser contacts GitHub; an exception to the no-external-images rule | Chosen (owner) |
| Avatar | B — a copy committed to `public/` | No third-party request | Goes stale; a binary file in the repository; another person's picture copied | Rejected |
| Avatar | C — through the Next.js image optimiser (`images.remotePatterns`) | Readers never contact GitHub | Needs a host with image optimisation; no hosting ADR yet; config change | Rejected for now |
| Avatar | D — no avatar, the link only | Nothing new | Not what the owner asked for | Rejected |
| Where | A — any link of exactly that shape, on any page | One rule; a project's own pages get it too | A page that writes such a link outside an ADR also gets a chip | Chosen (owner) |
| Where | B — ADR pages only | Narrowest | A second rule about which pages count | Rejected |

## Consequences [#consequences]

**Positive**

- Each decider and approver is one click from their profile, with their face beside the name.
- ADRs read the same in an editor, on GitHub and on the site.

**Negative / accepted trade-offs**

- Every reader of a page with a chip makes requests to `github.com` and
  `avatars.githubusercontent.com`.
- A person's avatar is whatever they set on GitHub, shown on this site.
- A renamed GitHub account leaves its old links pointing at someone else, or at nothing.

## Content invariants [#content-invariants]

- **1 (Private stays private).** Unchanged: a username in a public page is public. A private
  project's ADRs are not in `content/` at all.
- **5 (Readable as Markdown).** Kept: the Markdown keeps the link as written (decision 4).
- **Departs from** ADR-0002 decision 5 and `AGENTS.md` §8, "no externally hosted images", for
  the avatar alone (decision 5). That departure is part of what the owner approves.

## Security considerations [#security-considerations]

- **What leaves the system.** Nothing from the site. Each reader's browser requests
  `github.com/<user>.png` and follows the redirect to `avatars.githubusercontent.com`, sending
  the reader's IP address and user agent. `referrerpolicy="no-referrer"` keeps the page's
  address out of the request. GitHub learns that someone viewed a picture of `user`. This is a
  new boundary crossing, Browser → GitHub, recorded in [`../dfd/system.mdx`](../dfd/system.mdx)
  on implementation.
- **Personal data.** A GitHub username is personal data, public on GitHub. Only the owner's is
  written today. Another person's goes in only with the owner's yes, as `PROJECT_AGENTS.md`
  says.
- **Input.** The username comes from a page's own Markdown, never from a reader. It is checked
  against GitHub's username rules (decision 2) before it is put into a URL, so a link cannot
  build an address on another host or path.
- **Image content.** The picture is controlled by the GitHub account. Shown at 20px, as a
  decorative image, not a link target of its own. Accepted.
- **Content Security Policy.** The site sets none for its pages today. One added later must
  allow `img-src` for `https://github.com` and `https://avatars.githubusercontent.com`; the
  ADR that adds it says so.
- **Residual risk.** GitHub can see which IP addresses load which avatars. Accepted by the
  owner's choice of live avatars over a committed copy or a proxy.

## Implementation notes [#implementation-notes]

- [x] `src/lib/github-profile.ts`: `profileUser(href, text)`, the username when the link is a
      profile link of exactly that shape, else undefined; `profileUrl`, `avatarUrl`. Pure.
- [x] `src/components/profile-link.tsx` (server): `ProfileChip`, and `withProfileChips`, the
      page's `a` component wrapping `createRelativeLink`, used in
      `src/app/(site)/[...slug]/page.tsx`.
- [x] `src/app/site.css`: the chip, with focus, hover, the letter behind the avatar, and the
      light and dark themes through the site's tokens.
- [x] Tests (ADR-0007, with the runner of ADR-0021): a matching link; text and address naming
      different users; a username of 40 characters, with a leading or doubled hyphen, or with
      a path, query or other host; `http://`; a trailing slash; text without `@`; the chip's
      markup (avatar URL, `referrerpolicy`, empty `alt`, the letter); other links unchanged.
      In `src/lib/github-profile.test.ts` and `src/components/profile-link.test.tsx`; each
      seen to fail with the code broken.
- [x] Checked in the built HTML: the chips on ADR pages (`@puncoz` with its avatar), and the
      Markdown route unchanged (`[@puncoz](https://github.com/puncoz)`). Not yet looked at in a
      browser: the avatar loading, and the letter when it is blocked.
- [x] `bun run test`, `bun run types:check` and `bunx next build` pass; `bun run lint` stays
      blocked (typescript-eslint and TypeScript 7).

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

- [x] [`../app-flow/github-profile-chips.mdx`](../app-flow/github-profile-chips.mdx): status
      Current
- [x] [`../dfd/system.mdx`](../dfd/system.mdx): the Browser → GitHub crossing
- [x] [`../security/threat-model.mdx`](../security/threat-model.mdx): third-party integrations
      and the accepted risk; [`../security/data-classification.mdx`](../security/data-classification.mdx):
      GitHub usernames
- [x] [`../architecture/system.mdx`](../architecture/system.mdx): the new files
- [x] `AGENTS.md` §8: the one exception to "no externally hosted images"; §5 and §10
- [x] `PROJECT_AGENTS.md` §4: the same exception
- [x] `DESIGN.md` and `.impeccable/design.json`: the profile chip component
- [x] [`./index.mdx`](./index.mdx): status on approval


# ADR-0021 — Tests run with Bun's built-in test runner (/docs/maintain/adr/ADR-0021-tests-run-with-bun-test)

- **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:** —
- **Superseded by:** —
- **Design documents:** [`../architecture/system.mdx`](../architecture/system.mdx), `AGENTS.md` §5
  and §11, `README.md`

## Context [#context]

[ADR-0007](./ADR-0007-tests-are-part-of-every-change.mdx), approved 2026-11-01, makes tests part
of every change and leaves the runner to its own ADR, "before the first code change that needs
tests". Since then ADR-0011, ADR-0018 and ADR-0019 shipped code that was checked by hand with
throwaway scripts: `src/lib/trajectory.ts` (20 cases), `src/lib/adr-status.ts` (12),
`src/lib/diagrams.ts` and `diagrams-plugin.ts` (13). The owner chose (2026-11-01) to approve
ADR-0007 now and propose the runner next, comparing Bun's built-in runner with Vitest, then turn
the hand checks into tests.

Facts this decision rests on, checked on 2026-11-01:

- **Bun 1.4.4** is the package manager (`bun.lock`) and ships `bun test`. A probe test run with
  `bun test` imported `src/components/html-embed.tsx`, resolved its `@/lib/diagrams` import
  through `tsconfig.json` `paths`, rendered it with `react-dom/server`, and passed (3 tests,
  sandbox attribute present, a missing file and an empty title rejected).
- **Types.** `tsconfig.json` includes `**/*.ts`, so `bun run types:check` checks test files.
  Without types for `bun:test`, `tsc` fails: "Cannot find module 'bun:test' or its
  corresponding type declarations" (checked with a probe file, then removed). No `@types/bun`
  is installed.
- **Environment files.** Bun loads `.env` files on its own; `.env.local` holds
  `ALGOLIA_WRITE_KEY`. `bun test --no-env-file` turns that off (`bun test --help`).
- **Client components** (`trajectory-toc.tsx`, `orbit-station.tsx`, `adr-constellation.tsx`) use
  hooks and the DOM. Rendering them needs a DOM implementation (happy-dom or jsdom), which is not
  installed. Their logic lives in the pure modules above.
- Vitest is not installed.

## Decision [#decision]

1. **The runner is `bun test`**, built into Bun. No test-runner dependency.
2. **`@types/bun` is added to `devDependencies`**, types only, so test files are type-checked
   by `bun run types:check` like the rest of the code. The install runs after the owner's yes
   on this ADR (`AGENTS.md` §3).
3. **Tests sit beside the code**: `src/lib/diagrams.test.ts` next to `src/lib/diagrams.ts`,
   `*.test.ts` and `*.test.tsx`. Fixtures are invented, inline in the test file.
4. **The command is `bun run test`**, a `package.json` script running
   `bun test --no-env-file`, so no secret from `.env.local` is in a test's environment.
5. **What is unit-tested.** Pure modules, and server components rendered to a string with
   `react-dom/server`. Client components are not rendered until an ADR adds a DOM; their logic
   is tested through the pure modules they call, and what needs a browser is said in each ADR's
   implementation notes (ADR-0007 decision 7).
6. **The first tests** replace the hand checks: `trajectory.ts`, `reading-time.ts`,
   `adr-status.ts`, `diagrams.ts` with `diagrams-plugin.ts`, `<HtmlEmbed>`, and the pure
   catalogue checks in `catalog-plugin.ts` (`checkCatalogue`, `lineSegment`, `lineInfo`,
   `compareLines`). Each is seen to fail once, by breaking the code, before it counts
   (ADR-0007 decision 3).
7. **Done means** `bun run test`, `bun run types:check` and `bunx next build` pass, with
   `bun run lint` while it is blocked reported as such. `AGENTS.md` §5 and §11 list the
   command.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — `bun test` | Already installed with Bun; fast; TypeScript, JSX and the `@/` alias work with no config (probed); Jest-style `expect` | Needs `@types/bun` for type checks; tests run on Bun while Next.js runs on Node, so a Node-only behaviour could pass here and fail there; DOM testing needs another package | Chosen (recommended) |
| B — Vitest | The common choice for Vite and React projects; runs on Node, like Next.js; jsdom and happy-dom integrations documented | A new dependency tree (Vite with it); a config file for the `@/` alias and JSX; slower start | Rejected for now; the natural choice if component tests in a DOM are wanted later |
| C — Node's built-in `node:test` | No dependency; runs on Node | No TypeScript paths or JSX without a loader; a thinner `assert` API | Rejected |

## Consequences [#consequences]

**Positive**

- Tests run with what is installed, plus one types package.
- The hand checks of ADR-0011, ADR-0018 and ADR-0019 become tests that run on every change.

**Negative / accepted trade-offs**

- Tests run on Bun, the site on Node. Accepted: the tested code is pure TypeScript and React
  rendering, which behave the same on both; `bunx next build` still runs everything on Node.
- Client components' rendering is not unit-tested. Accepted until a DOM is needed.
- One more devDependency, `@types/bun`.

## Content invariants [#content-invariants]

Unchanged. Tests use invented fixtures, never real private content (ADR-0007 decision 5).

## Security considerations [#security-considerations]

- **Secrets.** `--no-env-file` keeps `.env.local`, and so `ALGOLIA_WRITE_KEY`, out of the test
  environment (decision 4). No test reads a secret or calls a network service.
- **Supply chain.** `@types/bun` is type declarations only, from the DefinitelyTyped
  publisher, and is not bundled into the site. Its version is pinned by `bun.lock`.
- **Nothing leaves the system.** Tests run locally; no live index, no network.

## Implementation notes [#implementation-notes]

- [x] The owner's yes on the install, with this ADR's approval: `bun add -d @types/bun@1.4.4`
      (devDependencies; the version matches Bun 1.4.4).
- [x] `package.json`: `"test": "bun test --no-env-file"`.
- [x] Found on implementation: TypeScript 7 loads no `@types` package unless `types` names it,
      so `@types/bun` alone did not reach `tsc`. Tests get their own `tsconfig.test.json`
      (extends `tsconfig.json`, `types: ["bun"]`), `tsconfig.json` excludes `*.test.ts(x)`, and
      `bun run types:check` runs both. Bun's types stay out of the site's own check, since the
      site runs on Node; `next build` checks only the site.
- [x] Tests for the modules in decision 6, and for ADR-0020's chip: 94 tests in 9 files beside
      the code. Each module was broken once (20 changes, from the arc's bow to the catalogue's
      public-only rule) and its tests failed every time, then the code was restored.
- [x] ADR-0011, ADR-0018 and ADR-0019 implementation notes: the hand-checked items ticked, with
      the test files named.
- [x] `bun run test`, `bun run types:check` and `bunx next build` pass; `bun run lint` stays
      blocked (typescript-eslint and TypeScript 7).

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

- [x] `AGENTS.md` §5 (Testing row, commands table) and §11 (the checklist)
- [x] `README.md`: commands
- [x] `PROJECT_AGENTS.md` §6: `bun run test` among the commands a consuming repository may run
- [x] [`../architecture/system.mdx`](../architecture/system.mdx): where tests live
- [x] [`./index.mdx`](./index.mdx): status on approval


# ADR-0022 — Diagrams show their Archify view on the page and their Mermaid in Markdown (/docs/maintain/adr/ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown)

- **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:** [ADR-0011](./ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx)
  decisions 1 to 3 (where the files live, the byte-for-byte copy into `public/`, `<HtmlEmbed>`
  with the Mermaid shown above it)
- **Superseded by:** —
- **Design documents:** [`../app-flow/diagrams.mdx`](../app-flow/diagrams.mdx),
  [`../prd/diagrams.mdx`](../prd/diagrams.mdx), [`../architecture/system.mdx`](../architecture/system.mdx),
  [`../api/content-routes.mdx`](../api/content-routes.mdx),
  [`../security/threat-model.mdx`](../security/threat-model.mdx), `AGENTS.md` §8, `PROJECT_AGENTS.md` §4,
  `DESIGN.md`

## Context [#context]

ADR-0011 put each Archify diagram on its page in a sandboxed frame, under its Mermaid version.
The owner asked (2026-11-01):

- **Inside the frame, only the diagram, its labels and its controls.** Today the frame also
  shows Archify's title and subtitle, its notes and index rail and its theme and style buttons,
  and because all of that is taller than the frame, the frame scrolls.
- **On the page, only the Archify view; in Markdown, only the Mermaid.** The copy-Markdown
  action, the Markdown routes and `llms-full.txt` give Mermaid, never the Archify tag. Enforced
  for every package and project.
- **The diagram's background matches the site's theme**, while boxes and arrows stay vibrant
  and meaningful, with live animation.

The owner then chose, from options: **wireframes get Archify versions too**, drawn from their
Mermaid, **one per screen**; enforcement is **strict**, so every Mermaid diagram outside the
templates has an Archify view, and the four that lack one today get it in this change; and
the implementation is **checked in the owner's Chrome** through the Claude in Chrome extension,
on localhost only.

Facts this decision rests on, read from Archify 3.2.0's output and the installed packages:

- **What an Archify page holds.** A toolbar (theme, style, Live/Still, Present, Export); a
  header (the title and subtitle); the diagram, with its own controls (Route, Map, Lens, find,
  guide, zoom); and a notes rail (cards, a node index, "Notes & index").
- **`?embed=1`** hides the toolbar, header, cards and diagram controls, and turns motion and
  exploration off. Too bare for what the owner asked.
- **`?theme=light` or `?theme=dark`** sets the theme before first paint.
- **Colours are CSS variables.** The page's: `--bg`, `--grid`, `--canvas-dot`, `--panel`,
  `--panel-border`, `--text` and its muted, dim and faint variants. The nodes' come from their
  kind: `--frontend-stroke` cyan, `--backend-stroke` green, `--database-stroke` violet,
  `--cloud-stroke` amber, `--security-stroke` rose, `--messagebus-stroke` orange,
  `--external-stroke` slate, each with a light-theme value.
- **Motion** starts Still when no preference is saved. Inside the sandbox, storage throws, so
  every embed starts Still today.
- **Size.** The diagram's `svg` carries a `viewBox` and `data-reader-fit`: `width-first`
  (it fills the width) or `intrinsic-height` (a wide diagram, such as the 1277 × 236 version
  lifecycle). Archify has no wheel handler; the scrolling comes from its page being taller than
  the 420 or 560px frame.
- **Markdown.** fumadocs-mdx's `includeProcessedMarkdown` takes a `filterElement` that can keep
  an element's children and drop the element (`'children-only'`, `fumadocs-core` remark-llms).
  The copy-Markdown action, `/<page>.md`, Markdown negotiation and `llms-full.txt` all read
  that processed Markdown (`docsLlms` in `src/lib/source.ts`). Search records exclude code
  blocks, so a Mermaid fence never reaches them.
- **Wireframes.** Archify has no wireframe type. Its `architecture` type places components by
  `pos` and `size` and wraps them in labelled `region` boundaries, enough to draw a screen as
  boxes inside a phone frame.
- **Counts.** 37 wireframes in 8 app flows, 4 Mermaid diagrams without an Archify view
  (`maintain/index.mdx`, `architecture/system.mdx`, `dfd/system.mdx`,
  `sequence/build-and-search-sync.mdx`), and 9 diagrams with one. An Archify file is about
  820 KB, most of it the viewer built into every file.

## Decision [#decision]

1. **One shape for every diagram.** A diagram in `content/` is written as a `<Diagram>` holding
   exactly one Mermaid fence and nothing else:

   ````mdx
   <Diagram src="/diagrams/example-cli/request-flow.html" title="Request flow">

   ```mermaid
   flowchart LR
     Parser --> Router --> Handler
   ```

   </Diagram>
   ````

   `src` follows ADR-0011's rule (`/diagrams/<project-slug>/<slug>.html`); `title` is required.
   `<Diagram>` is registered in `src/components/mdx.tsx`; `<HtmlEmbed>` is no longer available to
   pages and lives on inside `<Diagram>`.

2. **The page shows only the Archify view.** `<Diagram>` renders the frame; the Mermaid is not
   rendered on the page. Under the frame stay the title as its caption and **Open full screen**.

3. **Markdown shows only the Mermaid.** The processed Markdown keeps `<Diagram>`'s children and
   drops the tag (`filterElement`, `'children-only'`), so every Markdown surface (the
   copy-Markdown action, `/<page>.md`, Markdown negotiation, `llms-full.txt`) carries the
   Mermaid fence and never an Archify URL.

4. **Every Mermaid diagram is a `<Diagram>`, wireframes included.** The build fails on a Mermaid
   fence outside a `<Diagram>`, anywhere in `content/` except `content/docs/maintain/_templates/`
   (templates show the shape; a copy must be wrapped before it builds). A wireframe's Archify
   version is an `architecture` diagram drawn from its Mermaid: one per screen, its boxes placed
   as the Mermaid rows, inside a labelled phone-screen region, at phone width. The four diagrams
   without one get theirs in this change.

5. **Where the files live.** Both files sit in `diagrams/<project-slug>/`: the candidate,
   `<slug>.json`, and Archify's HTML, `<slug>.html`, byte for byte as `deliver` wrote it, so
   `check --require-provenance` can run on the committed file. `public/diagrams/` goes. A
   route, `src/app/diagrams/[project]/[file]/route.ts`, prerenders each at
   `/diagrams/<project-slug>/<slug>.html`, with the site shell of decision 6, served with
   ADR-0011's CSP `sandbox` header. The build fails on: an HTML without its JSON; a `src` with
   no file; a diagram file no page uses; an Archify receipt (`*.delivery*.json`) in `diagrams/`
   or `public/`.

6. **The site shell**, `src/lib/diagram-shell.ts`, is added to every diagram as it is served,
   so a new package's diagrams need nothing of their own:
   - **In a frame** (`?frame=1`, set by `<Diagram>`): Archify's title and subtitle, notes rail
     and its reveal button, theme and style buttons and the guide's credit line are hidden. The
     diagram, its labels, Live/Still, Present, Export and the diagram controls stay. A direct
     visit, through **Open full screen**, keeps Archify's title and notes.
   - **Colours.** The page variables take the site's tokens for each theme (`--home-bg`,
     `--home-panel`, `--home-line`, `--home-ink`, `--home-muted`, `--home-faint`), so the
     diagram sits on the page's own ground. Nodes and arrows keep Archify's kind palette,
     vibrant and meaningful. Diagrams are delivered with Archify's classic style (no
     `visual_preset`), and the existing ones are delivered again that way.
   - **Theme.** `<Diagram>` passes `?theme=` from the site's theme, and changes it when the
     reader switches theme (the frame reloads from the browser cache).
   - **Motion** starts Live: the shell turns Archify's motion on once after load, unless the
     reader prefers reduced motion. The reader can switch to Still.
   - **No inner scrolling.** The frame's height is set on the server from the diagram's
     `viewBox`, plus room for the controls, as a CSS aspect ratio, so the page doesn't jump. The
     shell then reports the exact content height to the page with `postMessage`. The page takes
     it only from that frame (`event.source`), and only as a number within bounds. Page
     scrolling passes over the frame. A wide diagram (`intrinsic-height`) scrolls sideways
     inside the frame on phones, Archify's own containment.

7. **The same for every repository.** `AGENTS.md` §8, `PROJECT_AGENTS.md` §4 and the templates
   state the shape. The build checks run on every folder in `content/`.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Trimming Archify | A — a shell added as the file is served | One place for every diagram; the committed file stays Archify's own | Depends on Archify's class names; re-checked on each Archify upgrade | Chosen |
| Trimming Archify | B — Archify's `?embed=1` | No site code | No controls and no motion: not what the owner asked | Rejected |
| Trimming Archify | C — edit each delivered file in the repository | No route | Breaks `check --require-provenance` on the committed file; repeated per file | Rejected |
| Mermaid on the page | A — not shown | What the owner asked | The text version is one action away (Markdown), not on the page | Chosen (owner) |
| Mermaid on the page | B — a closed "Text version" disclosure | Text on the page for those who want it | Not what the owner asked | Rejected |
| Markdown | A — `filterElement`, `'children-only'` | Every Markdown surface at once, at build | Ties to fumadocs-mdx's option | Chosen |
| Markdown | B — rewrite the text in `renderPage` | No build option | A regular expression over MDX | Rejected |
| Frame height | A — from the `viewBox` on the server, refined by the shell's report | No jump; no inner scroll | A `postMessage` channel to validate | Chosen |
| Frame height | B — fixed, as today | Simple | Scrolls or leaves empty space | Rejected |
| Wireframes | A — one Archify file per screen | Each screen's picture where its Mermaid is | 37 files, about 30 MB; a page with 7 screens loads about 5.6 MB of frames as it scrolls | Chosen (owner) |
| Wireframes | B — one per app flow | 8 files, about 6.5 MB | Screens apart from their states | Rejected (owner) |
| Wireframes | C — stay as code | No new files | Code on the page | Rejected (owner) |
| Enforcement | A — strict: every Mermaid diagram outside the templates | No page can skip it | The 4 diagrams without a view are drawn now | Chosen (owner) |
| Enforcement | B — only the `<Diagram>` shape | Less work now | Bare Mermaid keeps showing as code | Rejected (owner) |
| Colours | A — site ground, Archify's kind palette, classic style | Matches the site; colour carries meaning | Every existing diagram is delivered again | Chosen |
| Colours | B — keep Archify's backgrounds | No shell colours | Doesn't match the site | Rejected |

## Consequences [#consequences]

**Positive**

- A reader sees the diagram and its controls, at its own height, in the site's colours, moving.
- Tools and LLMs get Mermaid text, never an iframe URL.
- A consuming repository writes one `<Diagram>`; the rest is the site's.

**Negative / accepted trade-offs**

- About 41 new Archify files, roughly 34 MB more in the repository and the deployed output.
- A page with many screens loads several frames as the reader scrolls.
- Each diagram exists twice, Mermaid and Archify; both change in the same change.
- The shell depends on Archify's markup. Its tests run against a committed Archify file, so an
  upgrade that renames what the shell hides fails the tests.
- The Mermaid text is not on the page. Archify's diagram is an accessible `svg` (`role="img"`,
  title and description), and the frame has a title.

## Content invariants [#content-invariants]

- **1 (Private stays private).** Unchanged: a diagram of a private project never goes into
  `diagrams/`.
- **5 (Readable as Markdown).** Strengthened: every diagram's Markdown is its Mermaid.

## Security considerations [#security-considerations]

- **Isolation unchanged.** The shell's script runs inside the same sandboxed, opaque-origin
  frame (no `allow-same-origin`), and direct visits keep the CSP `sandbox` header.
- **`postMessage`.** The page accepts a message only when `event.source` is that frame's
  window and the data is `{ type: 'archify-height', height }` with a finite height between
  120 and 4000; anything else is ignored. The frame sends nothing but its height, and a
  Present request (`{ type: 'archify-present' }`, no data) when it cannot go fullscreen; the
  page answers it by opening that diagram's own URL, which it builds itself (implementation
  notes).
- **The route** serves only files matching `<project-slug>/<slug>.html` from `diagrams/`,
  listed at build (`generateStaticParams`, no other paths). No request data is read.
- **Nothing new leaves the system.** The shell adds no network call; the checks of ADR-0011
  (no external resources, no network APIs, no local paths) run on each committed file.

## Implementation notes [#implementation-notes]

- [x] `src/components/diagram.tsx` (`<Diagram>`, server: checks the `src` and title, reads the
      size) with its client part `diagram-frame.tsx` for the theme and the height. `<HtmlEmbed>`
      was folded into the frame rather than kept as a separate component; it is removed from
      `src/components/mdx.tsx` and from the repository, and a page that still uses it fails the
      build with the way forward.
- [x] `src/lib/source.ts`: `includeProcessedMarkdown` with `filterElement` keeping
      `<Diagram>`'s children (`markdownFilter` in `src/lib/remark-diagrams.ts`).
- [x] The build check of decision 4 (`remarkDiagrams`, first among the remark plugins through
      `applyMdxPreset`) and the file checks of decision 5 (`checkDiagrams`, run by the loader
      plugin; a JSON without its HTML fails too).
- [x] `src/app/diagrams/[project]/[file]/route.ts` (with `src/lib/diagram-files.ts`) and
      `src/lib/diagram-shell.ts`. A diagram is wide, for the frame's minimum width, at Archify's
      own ratio (1.55); the frame's first height is the `viewBox` ratio plus 10rem for the
      controls, then the reported height.
- [x] Every diagram moved to `diagrams/docs/` and delivered again in the classic style; Archify
      views made for the 4 diagrams and the 37 wireframes; every page converted to
      `<Diagram>`; the templates updated. Wireframe text is shortened with "…" where Archify
      would draw it below about 11px (it draws a label on one line); the full text is in the
      Mermaid. 49 diagrams in all, about 40 MB of HTML. Every file passes
      `check --require-provenance`, holds no local path and calls no network API.
- [x] Tests: the shell (what it hides, against a committed Archify file; the colours against
      `global.css`; Live start and reduced motion; the height report, an open menu, a height
      that answers itself, the toolbar's stacking, Present to fullscreen and its fallback), the
      height bounds and the Present request, the
      `<Diagram>` shape check (no fence, two fences, other content, a bare fence outside one, a
      bare fence nested in another element, templates exempt, `<HtmlEmbed>`), the Markdown
      output (the fence kept, the tag gone), `<Diagram>`'s frame, and the route's paths.
- [x] Checked in Chrome on localhost (the built site, desktop and phone width, both themes).
      Three faults found there and fixed in the shell and the frame:
      - **Flicker.** Archify lifts its bottom dock and reserves room for it from the viewport
        height, which in a frame is the frame: the frame answered its own height, about 16
        times a second. In a frame the dock holds still and has fixed room, and past 8 changes
        in 2 seconds the shell reports only growth until the frame's width changes.
      - **Export menu under the diagram.** The frame's toolbar kept its stacking (`z-index`),
        spans the frame so the menu opens inside it on phones, and the menu takes its own
        height; the shell reports the open menu's bottom, so the frame grows to show it.
      - **Present.** Archify's Present stage is the viewport's height, the frame's own. The
        frame now has `allow="fullscreen"`, and the shell takes the stage to fullscreen;
        leaving fullscreen leaves the stage. Where fullscreen is refused, the frame asks the
        page (`archify-present`), which opens the diagram's own page with `?present=1`.
      - **Theme.** A lazy frame did not always follow its changed `src` after hydration, and
        stayed dark on a light page; the frame is now a new element per theme.
      Real fullscreen could not be seen: the automated Chrome refuses fullscreen to any page
      ("not granted", even at the top level). The fallback was seen working; the fullscreen
      path is covered by tests.
- [x] `bun run test`, `bun run types:check` and `bunx next build` pass.

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

- [x] [`../app-flow/diagrams.mdx`](../app-flow/diagrams.mdx): Current;
      `../app-flow/html-embeds.mdx` removed, its index row with it
- [x] [`../prd/diagrams.mdx`](../prd/diagrams.mdx): Current
- [x] [`../architecture/system.mdx`](../architecture/system.mdx),
      [`../api/content-routes.mdx`](../api/content-routes.mdx),
      [`../security/threat-model.mdx`](../security/threat-model.mdx),
      [`../security/checklist.mdx`](../security/checklist.mdx)
- [x] `AGENTS.md` §5, §8 and §10; `PROJECT_AGENTS.md` §3 and §4; `README.md`;
      `.claude/agent-skills/INDEX.md` (the Archify override)
- [x] `DESIGN.md` and `.impeccable/design.json`: the diagram frame
- [x] [`./index.mdx`](./index.mdx): status on approval; ADR-0011's "Superseded by"


# ADR-0023 — Sidebar stations open one at a time (/docs/maintain/adr/ADR-0023-sidebar-stations-open-one-at-a-time)

- **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:** [ADR-0018](./ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx)
  decision 2, its *Open and closed* point only (each station opening and closing on its own)
- **Superseded by:** —
- **Design documents:** [`../app-flow/one-open-station.mdx`](../app-flow/one-open-station.mdx),
  [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx)

## Context [#context]

ADR-0018 made every sidebar folder an orbit station. The station that holds the current page
opens, the others start closed, and each station's chevron opens and closes it on its own. A
reader who opens three stations has three open: this site's Maintain track has twelve
sections, so a few clicks turn the sidebar back into the long list that stations were meant to
shorten, and the open station you came for scrolls out of view.

What the code does today (`src/components/docs/orbit-station.tsx`):

- Each station is Fumadocs' `SidebarFolder`, which keeps its own `open` state
  (`fumadocs-ui/components/sidebar/base`). It opens itself when it holds the current page
  (`active`) and never closes itself.
- `useFolder()` gives a station's content its own `open` and `setOpen`; nothing links one
  station's state to another's.

The owner asked on 2026-11-01 for one open section at a time, opening one closing the other,
and chose that this applies at every level, nested stations included.

## Decision [#decision]

1. **At most one open station per level.** Stations that share a parent (the track's top
   level, or the inside of one station) form a group, and at most one station in a group is
   open. Opening a station, with its chevron or its name, closes the open station beside it.
   The same holds inside an open station for its nested stations, and below that.
2. **Closing leaves the group closed.** Closing the open station opens no other; a track can
   show every station closed.
3. **The current page sets the open path.** On every page change, each station on the current
   page's path opens and every other station closes, at every level. A reader who opened a
   station and then follows a link elsewhere sees the new page's stations open, not the one
   they had opened.
4. **Everything else in ADR-0018 decision 2 stands**: the card, header, moons on an arc, the
   current station's border in the ecosystem colour, nested stations, top-level pages and
   separators. The ADR constellation (ADR-0019) is a station like any other here.
5. **Built on Fumadocs' folder state.** A small client context per group records which station
   is open; each station reports its own opening through `useFolder()` and closes when another
   in its group opens. No fork of the sidebar and no new dependency.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Scope | A — every level | One rule everywhere; the shortest sidebar | A nested station closes when its sibling opens, even inside a long section | Chosen (owner) |
| Scope | B — top-level stations only | Nested stations stay free | Two behaviours in one sidebar | Rejected (owner) |
| On a page change | A — the current path opens, the rest close | The sidebar always shows where the reader is | A station the reader opened by hand closes when they navigate away from it | Chosen |
| On a page change | B — keep what the reader opened | Respects a manual choice | Two stations open again: the current one and the manual one, which breaks decision 1 | Rejected |
| Build | A — a group context over Fumadocs' `useFolder()` | Small; stays on Fumadocs' primitives (ADR-0018) | Depends on `SidebarFolder` keeping `useFolder()` and opening on `active` | Chosen |
| Build | B — a controlled folder of our own | Full control | Re-implements Fumadocs' collapsible, its animation and keyboard handling | Rejected |

## Consequences [#consequences]

**Positive**

- A long track stays a short list of station names with one open, wherever the reader clicks.
- The open station is always the one the reader chose last, or the current page's.

**Negative / accepted trade-offs**

- Comparing two sections side by side in the sidebar is no longer possible; the reader opens
  one after the other.
- A station opened by hand closes on the next page change unless it holds that page.
- The behaviour needs a client context; the server render still shows the current path open
  and the rest closed, as today.

## Content invariants [#content-invariants]

None touched: the sidebar's behaviour changes, not any page, and per-page Markdown and
`llms.txt` carry no sidebar.

## Security considerations [#security-considerations]

None — this change touches no data, no endpoint and no secret. It changes client-side
open and closed state in the sidebar only.

## Implementation notes [#implementation-notes]

- [x] `src/components/docs/orbit-station.tsx`: a group context per level (the root's, and one
      inside each station) holding the open station's id; a station that opens claims the
      group, and a station closes when another claims it. The current page's path claims each
      group on every page change.
- [x] Keyboard and screen readers unchanged (by construction, not tested with a screen reader): the chevron stays Fumadocs' collapsible trigger
      with `aria-expanded`; a station closed by another reports `aria-expanded="false"`.
- [x] Reduced motion: stations open and close without animation, as today (the animation is untouched).
- [x] Tests (ADR-0007, ADR-0021): the group's rule as a pure function (open one, open a
      sibling, close the open one, a page change to another station, a nested group, a page
      change into a nested station). The rendered station (client) is not unit-tested until a
      DOM is chosen (ADR-0021); it is checked in Chrome on localhost at phone and desktop
      width. Checked in Chrome at desktop width only: opening a station closes the open one,
      closing leaves all closed, a page change opens that page's station (also when the reader had
      opened another), and the ADR constellation follows the rule. The automated Chrome window did
      not resize, so phone width (the drawer) was not seen.
- [x] `bun run test`, `bun run types:check` and `bunx next build` pass; `bun run lint` is
      reported while it stays blocked (AGENTS.md §5).

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

- [x] [`../app-flow/one-open-station.mdx`](../app-flow/one-open-station.mdx): Current, folded
      into [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx) screen 1 and its
      states. Kept as its own page, which docs-sidebars links from screen 1, so its diagrams stay
      with it.
- [x] [`ADR-0018`](./ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx):
      *Superseded by:* this ADR for decision 2's *Open and closed* point.
- [x] `AGENTS.md` §1 (the sidebar bullet) and `PROJECT_AGENTS.md`, where the sidebar is
      described (it describes only the ADR constellation, so nothing changed there); `README.md`.
- [x] `DESIGN.md` and `.impeccable/design.json`, where they describe stations opening.
- [x] [`./index.mdx`](./index.mdx): status.


# ADR-0024 — A project can span several repositories (/docs/maintain/adr/ADR-0024-a-project-can-span-several-repositories)

- **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:** [ADR-0013](./ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx)
  decision 4, its last sentence only ("A project that ships releases may use lines like a
  package"); [ADR-0010](./ADR-0010-projects-document-themselves-through-a-submodule.mdx)
  decision 2, for projects with several repositories (who edits what inside the one folder)
- **Superseded by:** —
- **Design documents:** [`../app-flow/multi-repository-projects.mdx`](../app-flow/multi-repository-projects.mdx),
  [`../prd/multi-repository-projects.mdx`](../prd/multi-repository-projects.mdx),
  [`../state/package-version-lifecycle.mdx`](../state/package-version-lifecycle.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx), `PROJECT_AGENTS.md`

## Context [#context]

A project is often more than one repository: a frontend, a backend and an API, or any other
split. Today the site assumes one repository per entry:

- **One folder, one repository.** ADR-0010 gives each project one folder,
  `content/<project-slug>/`, written by the repository that includes this one as a submodule,
  and that repository edits only its own folder. Several repositories writing one folder would
  all edit the same `meta.json`, overview and track files.
- **One repository link.** `catalog.repository` is a single optional URL
  (`src/lib/catalog-schema.ts`); the planet header shows it as one *Repository* link
  (`src/components/docs/package-hero.tsx`).
- **Project versions.** ADR-0013 lets a project version its Use track like a package, with any
  number of lines, older (`legacy`) ones included. The build checks lines the same way for both
  kinds (`src/lib/catalog-plugin.ts`).

No project is documented yet, so nothing has to move. The owner decided on 2026-11-01:

- one entry per project, with a folder per repository inside each track;
- a project has at most a `dev` line and one released line, for the whole project, and this
  holds for every project; several versions are for packages only;
- one repository is primary and owns the shared files.

## Decision [#decision]

1. **The catalogue lists a project's repositories.** A project with more than one repository
   sets `catalog.repositories` instead of `catalog.repository`:

   ```json
   "catalog": {
     "kind": "project",
     "visibility": "public",
     "repositories": [
       { "id": "frontend", "name": "Frontend", "url": "https://github.com/example/acme-web", "primary": true },
       { "id": "backend", "name": "Backend", "url": "https://github.com/example/acme-server" },
       { "id": "api", "name": "API" }
     ]
   }
   ```

   - `id` is the repository's folder name: lowercase letters, digits and hyphens, unique in the
     list, and not `dev`, `latest`, `adr` or the URL segment of one of the project's lines.
   - `name` is what readers see; without it the `id` is shown. `url` is an optional `https`
     URL to the repository.
   - Exactly one repository has `primary: true`.
   - The list holds two or more repositories, only on `kind: "project"`, and never together
     with `repository`. A one-repository project keeps `repository`, as today. Packages are
     one repository each.

2. **Each repository has its own folder in each track.** Its pages go in a folder named its
   `id`: `use/<id>/` and `maintain/<id>/`. Either may be missing; a repository with nothing for
   readers has no `use/<id>/`. Pages about the project as a whole (an architecture that spans
   the repositories, how they talk to each other) sit in the track beside those folders, as
   pages or folders of their own. In the sidebar a repository folder is an orbit station like
   any other, titled with the repository's `name` unless its `meta.json` sets a title.

   ```
   content/acme/
   ├── meta.json          # catalog.repositories
   ├── index.mdx          # the project overview
   ├── use/
   │   ├── frontend/
   │   ├── backend/
   │   └── api/
   └── maintain/
       ├── architecture.mdx   # spans the repositories
       ├── frontend/
       ├── backend/
       └── api/
   ```

3. **Projects have at most two lines, for the whole project.** For every project, one
   repository or several:

   - Unversioned by default: `use/` holds pages (and, with several repositories, the
     repository folders) directly.
   - A project that ships releases has `use/dev/` (`channel: "dev"`) and at most one released
     line (`channel: "latest"`). The build fails on a `legacy` line in a project. Packages keep
     every rule of ADR-0013 and ADR-0015, older lines included.
   - With several repositories, each line holds the repository folders:
     `use/dev/<id>/` and `use/<line>/<id>/`. A release copies the whole of `use/dev/` to the
     new released line and removes the previous one; a link to the removed line redirects to
     the same path in the new one (ADR-0015).
   - Maintain is not versioned (ADR-0013).

4. **The primary repository owns the shared files.** In a project with several repositories:

   - The **primary** repository edits the root `meta.json`, `index.mdx`, `use/meta.json`,
     `maintain/meta.json`, every line's `meta.json`, every page outside a repository folder,
     and releases (decision 3).
   - **Every other repository** edits only its own folders: `use/<id>/` (in each line, when
     the project has lines) and `maintain/<id>/`, and its diagrams, named
     `diagrams/<project-slug>/<id>-<slug>.json` and `.html` (ADR-0022).
   - A repository that needs a change outside its folders asks the primary repository's
     maintainers or the owner. The slug, the list of repositories and which one is primary
     are agreed with the owner.
   - The build cannot know which repository wrote a file; `PROJECT_AGENTS.md` states the rule
     and each repository's agent instructions name its `id`.

5. **Readers see the repositories.**

   - **Planet header**: the single *Repository* link becomes one link per repository, primary
     first, each with the repository's name (*Frontend ↗*, *Backend ↗*); a repository without
     a `url` is named without a link. The fact sheet shows *Repositories: Frontend, Backend,
     API*.
   - **Home page**: the planet card's kind line adds the count, *Project · 3 repositories*.
   - **Sidebar**: repository folders are stations (decision 2), under ADR-0023's one open
     station at a time.
   - Search records, `llms.txt` and per-page Markdown are unchanged: a page in a repository
     folder is a page of the project, and its breadcrumb names the folder.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Layout | A — one entry, a folder per repository inside each track | One overview and one planet per project; repository folders are ordinary stations; smallest change to the one shape of ADR-0015 | Shared files need an owner (decision 4) | Chosen (owner) |
| Layout | B — one entry with a repository switch: each repository its own Use and Maintain | Each repository fully independent | A new navigation level beside the track switch and the moon picker; departs from ADR-0015's one shape | Rejected (owner) |
| Layout | C — separate entries linked by a group | No shared files at all | No project overview; one project shows as several planets | Rejected (owner) |
| Versions | A — dev and one released line, for the whole project, for every project | One rule for projects; one moon picker per project | Repositories that release separately can't say so; a project's older release is not kept | Chosen (owner) |
| Versions | B — lines per repository | Independent releases | A moon picker per station; much more to build and check | Rejected (owner) |
| Versions | C — as today: projects version like packages | No change | Older project lines, which the owner does not want | Rejected (owner) |
| Shared files | A — a primary repository owns them | Clear ownership; no two repositories edit one file | The others depend on it for the overview | Chosen (owner) |
| Shared files | B — any repository edits them | Flexible | Two repositories can change the overview in different directions | Rejected |
| Shared files | C — only the owner, in this repository | Strict | Every overview change waits for the owner | Rejected |
| Catalogue | A — `repositories` beside `repository`, never both | A one-repository project is unchanged | Two fields for one idea | Chosen |
| Catalogue | B — only `repositories`, for every entry | One field | Every existing entry, and packages, change for nothing | Rejected |

## Consequences [#consequences]

**Positive**

- A project of several repositories reads as one project: one overview, one planet, one
  search scope, with each repository's pages in its own station.
- Each repository's agent has a folder it alone edits, so their changes don't collide.
- One version rule for projects; the moon picker for a project shows at most `dev` and the
  released line.

**Negative / accepted trade-offs**

- The primary repository is a bottleneck for the overview, the tracks' order and releases.
- A project's previous release is not kept on the site once a new one is released.
- Ownership inside the folder is a convention the build cannot check.
- A repository `id` can't be named like a line (`dev`, `latest`) or `adr`.

## Content invariants [#content-invariants]

- **§6.1 Private stays private.** Unchanged: `visibility` must be `public` for the whole
  project, so every repository's pages are public. A project whose repositories are partly
  private documents only what is public, or nothing, until the private-documentation ADR.
- **§6.2 Checked against the code.** Each repository's pages are checked against that
  repository's source; the `url` in the catalogue is the repository's own.
- **§6.3 Every package page says which version it documents.** Unchanged for packages; a
  project's line states its version as today.
- **§6.4, §6.5.** Unchanged.

## Security considerations [#security-considerations]

- **New data:** repository names and `https` URLs in the catalogue, all public. The schema
  refuses a non-`https` URL, as it does `repository` today; links open with
  `rel="noreferrer noopener"`.
- **No private repository by accident.** A repository listed in a public project is named on
  the site; listing a private repository's URL publishes its name and location. `PROJECT_AGENTS.md`
  says to list a private repository without `url`, or not at all, and to ask the owner.
- **Several writers, one folder.** More repositories can now write into one project's folder.
  The rules of ADR-0010 still apply to each: edit only, a human commits, nothing private. The
  owner reviews every change before committing; ownership (decision 4) narrows what each
  repository should touch.
- Nothing new leaves the system: search records gain no field.

## Implementation notes [#implementation-notes]

- [x] `src/lib/catalog-schema.ts`: `repositories` (id, name, url, primary) with its checks:
      projects only, two or more, unique ids, reserved ids, `https`, exactly one primary, not
      with `repository`.
- [x] `src/lib/catalog-plugin.ts`: no `legacy` line in a project, at most one released line; a
      repository id that is a line's segment fails; a repository folder's title defaults to
      the repository's `name`.
- [x] `src/lib/catalog.ts`: entries carry `repositories` (primary first) for the planet header
      and the home card.
- [x] `src/components/docs/package-hero.tsx`: a link per repository and the *Repositories*
      fact; `src/components/home/planet-cards.tsx`: the repository count.
- [x] Tests (ADR-0007): the schema (a valid list; one repository; no primary, two primaries;
      a duplicate, reserved or upper-case id; an `http` URL; `repositories` on a package; with
      `repository`), the plugin (a project with `dev` and a released line passes; a `legacy`
      line in a project fails; a package keeps its older lines; a repository folder titled from
      its name; an id clashing with a line segment), the planet header (links, primary first, a
      repository without a URL) and the home card count.
- [x] Checked in Chrome on localhost with a test project in a scratch copy of `content/`, never
      committed: invented names only. Done with a temporary `content/acme/` (three repositories,
      `dev` and a latest line), deleted afterwards: the header links and the unlinked API, the
      Repositories fact, a station per repository titled from the catalogue, a `meta.json` title
      winning over the name, and shared Maintain pages above the stations.
- [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/multi-repository-projects.mdx`](../app-flow/multi-repository-projects.mdx)
      and [`../prd/multi-repository-projects.mdx`](../prd/multi-repository-projects.mdx): Current.
- [x] [`../state/package-version-lifecycle.mdx`](../state/package-version-lifecycle.mdx): a
      project's lines (no Legacy state).
- [x] [`../architecture/system.mdx`](../architecture/system.mdx): the catalogue's repositories.
- [x] [`ADR-0013`](./ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx) and
      [`ADR-0010`](./ADR-0010-projects-document-themselves-through-a-submodule.mdx):
      *Superseded by:* this ADR, for the parts named above.
- [x] `PROJECT_AGENTS.md`: §1's snippet names the repository's `id` and whether it is primary;
      §3 the folders, the catalogue's `repositories`, project lines and who edits what.
- [x] `AGENTS.md` §1 (one shape for every entry) and §10 (the repository map); `README.md`
      where it describes an entry's folder.
- [x] [`./index.mdx`](./index.mdx): status.


# ADR-0025 — The overview has the same sidebar as its tracks (/docs/maintain/adr/ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks)

- **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 what [`../app-flow/package-navigation.mdx`](../app-flow/package-navigation.mdx)
  screen 1 describes; [ADR-0013](./ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx)
  decision 6's scoped navigation now covers the overview too)
- **Superseded by:** [ADR-0026](./ADR-0026-the-moon-picker-on-an-overview-opens-a-lines-first-page.mdx)
  for decision 4 only (the moon picker on the overview)
- **Design documents:** [`../app-flow/overview-sidebar.mdx`](../app-flow/overview-sidebar.mdx),
  [`../app-flow/package-navigation.mdx`](../app-flow/package-navigation.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx)

## Context [#context]

The owner reported on 2026-11-01 that the sidebar changes shape between an entry's overview and
its pages. On the overview, Maintain opens as a folder in the sidebar; clicking one of its pages
shows a different sidebar, which is confusing.

What the code does today:

- Fumadocs shows the sidebar of the deepest root folder on the current page's path
  (`TreeContextProvider` in `fumadocs-ui/contexts/tree`). Its path search checks a folder's
  `index` before its children.
- The catalogue plugin marks the entry folder `root: true`, each track `root: 'track'` and each
  version line `root: 'line'` (`src/lib/catalog-plugin.ts`). The overview is the entry folder's
  `index`, so its path ends at the entry folder: the sidebar shows the whole entry, with Use and
  Maintain as stations that open in place.
- A track page's path reaches its track or line, so its sidebar shows only that track's
  stations, as top-level cards. The same sections are nested on the overview and top-level on a
  page.
- The planet row (`src/components/docs/track-switch.tsx`) marks the current side from the URL;
  on the overview it marks neither.

The owner chose that the overview shows exactly the sidebar of a track page.

## Decision [#decision]

1. **The overview shows its default track's sidebar.** The default track is Use when the entry
   has one (its latest line, or `dev` when nothing is released), otherwise Maintain. The sidebar
   on the overview is that track's: its stations as top-level cards, one open at a time
   (ADR-0023). When the entry has both tracks, the planet row marks the default track's side as
   current: the sun for Use, the moon for Maintain. The other side's button opens that track, as
   today.
2. **Every track's sidebar starts with the overview.** An *Overview* item, linking to
   `/<slug>`, is the first item of each Use line, of an unversioned Use and of Maintain, on the
   top-level arc above the stations. On the overview it is the current page. From any page the
   reader returns to the overview from the same place.
3. **Built in the page tree.** The catalogue plugin's `root` hook detaches the entry folder's
   `index` and puts an *Overview* item for the same page first in each line, unversioned Use and
   Maintain, with Use before Maintain among the entry's children, so Fumadocs resolves the
   overview into the default track. The catalogue's own reads (an entry's URL, the Use,
   Maintain and line links) skip the *Overview* item. No change to Fumadocs, no new dependency.
4. **The moon picker on the overview** lists the lines as on any Use page. Choosing another
   line keeps the reader on the overview with that line's sidebar, as Fumadocs does for a page
   that every line holds.
5. **Unchanged:** the overview page itself (the planet header and the entry's `index.mdx`), its
   URL, its Markdown, search records and `llms.txt`. This site's overview, `/docs`, has only
   Maintain, so it shows Maintain's stations under *Overview*.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Overview sidebar | A — the default track's sidebar | One sidebar everywhere; nothing changes shape when the reader clicks into a page | The overview looks like part of Use (or Maintain) | Chosen (owner) |
| Overview sidebar | B — the planet row and two links, Use → and Maintain → | Simple; nothing expands | A third sidebar shape, shown only on the overview | Rejected (owner) |
| Overview sidebar | C — the whole entry on every page | One shape everywhere | Long sidebars; undoes ADR-0013's scoped navigation | Rejected (owner) |
| Build | A — the page tree's `root` hook | One place; Fumadocs resolves it like any page | The overview item appears in several places of the tree, so tree readers skip it | Chosen |
| Build | B — a separate tree passed for the overview | No duplicate items | `DocsLayout` is in the shared layout and takes one tree; a second layout for overviews only | Rejected |
| Back to the overview | A — an *Overview* item first in every track | Same place on every page; the reader sees where they are | One more row in each sidebar | Chosen |
| Back to the overview | B — only the planet chip | No extra row | The chip is easy to miss as a link | Rejected |

## Consequences [#consequences]

**Positive**

- The sidebar keeps its shape from the overview into any page of the default track, and the
  sun and moon switch between the two tracks' sidebars everywhere.
- The overview is one click away from every page, in the same place.

**Negative / accepted trade-offs**

- On the overview, the sidebar shows Use's stations (or Maintain's), not both tracks; Maintain
  is the moon button away.
- Each track's sidebar gains one row.
- Fumadocs' previous and next links on the first page of a track now point back to the
  overview.

## Content invariants [#content-invariants]

None touched: pages, URLs, Markdown, search records and `llms.txt` stay as they are.

## Security considerations [#security-considerations]

None — this change touches no data, no endpoint and no secret. It rearranges the sidebar's
page tree, which holds only public pages.

## Implementation notes [#implementation-notes]

- [x] `src/lib/catalog-plugin.ts`: the `root` hook (decision 3), as `overviewInTracks()`, tested
      on its own. The overview is the entry folder's `index`, or a child page when the entry's
      `meta.json` lists `"index"` in `pages` (this site's does); both move the same way.
      `withoutOverviewItems()` gives `llms.txt` the tree as written (`src/lib/source.ts`).
- [x] `src/lib/catalog.ts`: an entry's URL is its overview page's; the Use, Maintain and line
      links, and the home page's track previews, skip the *Overview* item.
- [x] `src/components/docs/track-switch.tsx`: on the overview, the default track's side is
      current (decision 1), through `currentSide()` in `src/lib/overview-sidebar.ts`.
- [x] The moon picker: Fumadocs links each line to its folder's first page, which is now the
      *Overview* item, so the layout's tab transform (`src/app/(site)/layout.tsx`) links each line
      to its first page after it (`folderUrls()` and `lineLink()`).
- [x] **Decision 4 is not met as written.** From the overview, choosing another line cannot keep
      the reader on the overview with that line's sidebar: the overview is one URL, and Fumadocs
      resolves it to the first line on its path, the latest. Choosing another line from the
      overview opens that line's first page. From any other page the picker keeps the reader on
      the same page, as before. Superseded by
      [ADR-0026](./ADR-0026-the-moon-picker-on-an-overview-opens-a-lines-first-page.mdx), which
      keeps this behaviour.
- [x] Tests (ADR-0007): the tree (Overview first in each line, unversioned Use and Maintain; Use
      before Maintain; the entry folder without its index; an overview listed in `pages`; an
      entry without an overview; folders outside the catalogue; this site's Maintain-only entry;
      the tree restored for `llms.txt`), the current side and the line links as pure functions
      (`src/lib/overview-tree.test.ts`, `src/lib/overview-sidebar.test.ts`). The catalogue links
      are read from the built site, not unit-tested: `catalog.ts` reads the loaded source.
- [x] Checked in Chrome on localhost at desktop width, with a temporary invented package
      (`content/lodestar/`, a latest and a `dev` line, two Maintain pages; deleted afterwards)
      and `/docs`: the overview shows the v0.1 sidebar with *Overview* current and the sun
      current; a Use page and a Maintain page start with *Overview*; the moon picker links each
      line to its own first page; the hero and planet row link to the first Use and Maintain
      pages; `/docs` shows Maintain's stations under *Overview*; `use/latest` and a removed line
      still redirect; `llms.txt` lists each overview once, under its entry. Phone width (the
      drawer) was not seen.
- [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/overview-sidebar.mdx`](../app-flow/overview-sidebar.mdx): Current;
      [`../app-flow/package-navigation.mdx`](../app-flow/package-navigation.mdx) screen 1, its
      Mermaid and its Archify view.
- [x] [`../architecture/system.mdx`](../architecture/system.mdx): the plugin's `root` hook.
- [x] `AGENTS.md` §1 and `PROJECT_AGENTS.md`, where they describe the sidebar; `README.md`.
- [x] [`./index.mdx`](./index.mdx): status.


# ADR-0026 — The moon picker on an overview opens a line's first page (/docs/maintain/adr/ADR-0026-the-moon-picker-on-an-overview-opens-a-lines-first-page)

- **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:** [ADR-0025](./ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks.mdx)
  decision 4 only (the moon picker on the overview)
- **Superseded by:** —
- **Design documents:** [`../app-flow/overview-sidebar.mdx`](../app-flow/overview-sidebar.mdx)

## Context [#context]

ADR-0025 decision 4 says that on an entry's overview, choosing another line in the moon picker
keeps the reader on the overview with that line's sidebar. Implementing ADR-0025 showed that
this cannot work with one overview URL:

- Fumadocs shows the sidebar of the deepest root folder on the current page's path, and finds
  that path depth first (`TreeContextProvider` in `fumadocs-ui/contexts/tree`). The overview is
  one URL, `/<slug>`, held by every line's *Overview* item, so its path always ends in the first
  line: the latest, or `dev` before the first release.
- The picker keeps the reader on the same page by matching the page's file path inside the line
  (`findProjection` in `fumadocs-core`). The overview's file, `<slug>/index.mdx`, is in no line,
  so the picker uses each line's own link.
- As built, that link is the line's first page after the *Overview* item (`lineLink()` in
  `src/lib/overview-sidebar.ts`). From any other page the picker behaves as before.

The owner chose on 2026-11-01 to keep what is built.

## Decision [#decision]

1. **On an overview, the moon picker opens the chosen line's first page.** It lists every line,
   with the line the overview's sidebar shows (the latest, or `dev` before the first release)
   checked. Choosing another line opens that line's first page (its index when it has one), with
   that line's sidebar. This is what the picker already does on any page a line does not have.
2. **Everything else in ADR-0025 stands.** On every other page the picker keeps the reader on the
   same page when the chosen line has it, otherwise that line's first page, as before.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — open the line's first page | Built and checked; one rule for a page a line does not hold | Choosing a line leaves the overview | Chosen (owner) |
| B — no moon picker on overviews | Nothing on the overview leads away from it | The overview's sidebar no longer matches a Use page's; a code change | Rejected (owner) |
| C — an overview per line (`/<slug>/use/<line>` shows the overview) | The reader stays on an overview | New routes, redirects and tests; one page at several URLs | Rejected (owner) |

## Consequences [#consequences]

**Positive**

- No code changes: the site already behaves this way.
- One rule for the picker: the same page when the line holds it, otherwise its first page.

**Negative / accepted trade-offs**

- A reader on the overview who chooses another line leaves the overview; *Overview* is first in
  that line's sidebar to return.

## Content invariants [#content-invariants]

None touched.

## Security considerations [#security-considerations]

None — this change touches no data, no endpoint and no secret.

## Implementation notes [#implementation-notes]

- [x] No code changes: `lineLink()` and the layout's tab transform already do this (ADR-0025).
- [x] [`ADR-0025`](./ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks.mdx): *Superseded
      by:* this ADR for decision 4, and its open implementation note closed.

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

- [x] [`../app-flow/overview-sidebar.mdx`](../app-flow/overview-sidebar.mdx): already describes
      this; add this ADR to its related ADRs.
- [x] [`./index.mdx`](./index.mdx): status.


# ADR-0027 — The sidebar is a scale ladder with one lifted orbit (/docs/maintain/adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit)

- **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:** [ADR-0018](./ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx)
  decision 2, in part: every folder drawn as a card, and how top-level pages and separators
  look. The station's header parts, the pages' arc, nested folders and ADR-0023's one open
  station at a time stand.
- **Superseded by:** —
- **Design documents:** [`../app-flow/sidebar-scale-ladder.mdx`](../app-flow/sidebar-scale-ladder.mdx),
  [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx),
  [`../prd/docs-sidebars.mdx`](../prd/docs-sidebars.mdx)

## Context [#context]

The owner reported on 2026-11-01 that the docs sidebar does not feel good: "so many card like
view, while overview and maintainer documentation is small". The hierarchy should be rethought
now that the content is known.

What the sidebar shows today (ADR-0018 decision 2, ADR-0023, ADR-0025;
`src/components/docs/orbit-station.tsx`, `src/app/site.css`):

- **Every folder is a card**, open or closed: a bordered panel with a glyph, the name, a count
  pill and a chevron. This site's Maintain track has 12 folders holding 0 to 25 pages, so its
  sidebar is a column of 12 equal cards, and a folder with one page weighs as much as the ADRs.
- **Top-level pages are the smallest rows.** *Overview* and *Maintainer documentation*, the
  two entry points, are 13.5px muted rows on a short arc above the cards.
- **Nothing groups the folders.** Fumadocs separators (`---Label---` in a `meta.json`) render
  as a dotted rule, but no track uses them.
- The content is now known: a package's Use line holds a few pages and a few folders (getting
  started, guides, reference); a project of several repositories adds a folder per repository
  (ADR-0024); this site's Maintain holds 2 pages and 12 folders, the ADRs among them.

The owner chose on 2026-11-01:

- **One lifted card**: only the open folder is a card; closed folders are plain rows; top-level
  pages are full-size rows;
- **group labels** for long tracks, starting with this site's Maintain;
- the **scale ladder**: each sidebar level is a smaller body than the one above it, following
  the universe hierarchy the owner wants for the whole site;
- the rename to *Puncoz Verse* and the whole-site universe theme in a separate ADR (ADR-0028),
  after this one.

## Decision [#decision]

1. **Each level of the sidebar is a smaller body than the one above it.** From the top:

   | Level | Body | Mark and type |
   |---|---|---|
   | The entry | **Planet** | The planet row: chip and the sun and moon (ADR-0018 decision 1), unchanged |
   | A version line | **Moon** | The moon picker (ADR-0013), unchanged |
   | A top-level page | **Landmark satellite** | An 8px satellite dot, the name in 14.5px Text 500, Frost Ink |
   | A group | **Belt** | A small label (11px Text 600, uppercase, 0.08em tracking, Steel Faint) on a dotted hairline running to the edge |
   | A folder | **Orbit** | A 12px ring, the name in 14px Text 500, the page count in 11.5px Data, Steel Faint, at the right |
   | A page in a folder | **Satellite** | A 6px hollow dot on the orbit's arc, the name in 13.5px Text |
   | The current page | **Probe** | A 9px teal dot with its glow, the row tinted with 10% of the ecosystem colour, Frost Ink 500 |

   Moons stay version lines only (DESIGN.md, *The Mark Means Rule*); a page is a satellite.

2. **Only the open orbit is a card.** A closed folder is a plain row: no border and no fill,
   its ring, name and count, and a chevron in Steel Faint. The open folder lifts into the one
   card in the sidebar: Graphite Panel, a hairline border, 12px corners; its ring fills with a
   planet (as the station glyph does today), and its satellites follow on their arc. When it
   holds the current page its border takes 45% of the ecosystem colour, as today. Opening a
   folder lifts it and drops the open one back to a row (ADR-0023, unchanged).

3. **Nested folders stay inside the card.** A folder inside the open orbit is a smaller orbit
   row (a 10px ring, 13.5px name). Opening it shows its satellites indented inside the same
   card; there is never a card inside a card. ADR-0023 holds at each level.

4. **Top-level pages are landmarks.** Pages directly in a track or line (the *Overview* item of
   ADR-0025, a track's own index listed in its `pages`, any other top-level page) sit above the
   first belt or orbit as full-size rows. The current one is the probe.

5. **Belts group orbits.** A Fumadocs separator in a `meta.json` is drawn as a belt (decision 1),
   with 18px above it. A track without separators shows no belts. This site's Maintain track
   gets four, in `content/docs/maintain/meta.json`:

   | Belt | Folders |
   |---|---|
   | Decisions | ADRs |
   | Design | Architecture, App flows, Product requirements, API, Data flow diagrams, Sequence diagrams, State machines, ERD |
   | Security | Access control, Security |
   | Templates | Templates |

   `PROJECT_AGENTS.md` tells consuming repositories they may group their own tracks the same
   way.

6. **A folder holding only its index is a plain orbit link.** It shows its ring and name, no
   count and no chevron, and opens its index page (today it shows a count of 0).

7. **The ADR constellation** (ADR-0019) is unchanged, inside the ADRs' card when it is open.

8. **Unchanged:** the planet row, the moon picker, the trajectory, the version notices, the
   pages' arc, one open orbit at each level (ADR-0023), the overview's sidebar (ADR-0025),
   keyboard behaviour (Fumadocs' collapsible trigger and `aria-expanded`), and the phone drawer,
   which shows the same sidebar. With reduced motion an orbit lifts and drops without animation.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Shape | A — one lifted card | Smallest change; the card says "you are in this orbit" | Closed folders lose their glyph-in-a-box look | Chosen (owner) |
| Shape | B — orbit rail: no cards, one continuous orbit line with every page and folder on it | Echoes the trajectory on the right | The biggest change; a long rail is hard to scan | Rejected (owner) |
| Shape | C — drill-in levels: one level at a time, ← back | Calm at every size | Hides the sibling folders; replaces ADR-0023 | Rejected (owner) |
| Marks | A — scale ladder: a body per level, sized to its rank | Follows the universe hierarchy; rank shows in size | One more mark (the ring) per closed row | Chosen (owner) |
| Marks | B — bodies only up top, plain type below | Quietest | Loses the theme below the planet row | Rejected (owner) |
| Groups | A — belts from `meta.json` separators | Uses Fumadocs' own separators; a content choice per track | Each track's maintainers place them | Chosen (owner) |
| Groups | B — one list | Nothing to maintain | Twelve folders in one run | Rejected (owner) |

## Consequences [#consequences]

**Positive**

- One card in the sidebar at a time, so the reader sees where they are at a glance.
- The two entry points, *Overview* and the track's own index, read as the most important rows.
- Long tracks scan by group.

**Negative / accepted trade-offs**

- A closed folder is quieter than today; its count and ring carry its weight.
- Belts need a separator per group in each track's `meta.json`; a track without them shows one
  list.
- The sidebar's look changes on every docs page at once.

## Content invariants [#content-invariants]

None touched: the change is to how the sidebar looks, and to the order labels of this site's
own Maintain track. Pages, URLs, per-page Markdown and `llms.txt` stay as they are (a
separator adds a bold label line to `llms.txt`, which keeps it readable).

## Security considerations [#security-considerations]

None — this change touches no data, no endpoint and no secret. It changes the sidebar's
presentation and one `meta.json`.

## Implementation notes [#implementation-notes]

- [x] `src/components/docs/orbit-station.tsx`: a closed folder is a row and the open one the card
      (decisions 2, 3), through Fumadocs' `data-open` on the folder; landmarks (decision 4); belts
      (decision 5); a folder holding only its index as an orbit link (decision 6). The tree and
      ADR-0023's group logic are unchanged. The open orbit's planet sits at the ring's centre: on
      the ring it read as a broken ring at 12px.
- [x] `src/app/site.css`: the ladder's marks and type (decision 1), the card only on the open
      orbit, the belt; reduced motion.
- [x] `content/docs/maintain/meta.json`: the four belts (decision 5).
- [x] Tests (ADR-0007, ADR-0021): `countPages()`, `pageBody()` and `folderBody()` in
      `src/lib/sidebar-ladder.ts` as pure functions, and the belts in this site's Maintain
      `meta.json` (`src/lib/sidebar-ladder.test.ts`). The rendered client component is checked in
      Chrome until a DOM is chosen.
- [x] Checked in Chrome on localhost at desktop width, dark and light: `/docs/maintain/prd/diagrams`
      (landmarks, belts, rows, the one card), an ADR page (the constellation inside the ADRs card;
      ERD and Access control as orbit links), and a temporary invented package (`content/lodestar/`,
      deleted afterwards) with a nested folder inside the card; opening Reference lifted it and
      dropped Guides back to a row, its ring still in the ecosystem colour. The phone drawer was not
      seen: the automated window does not resize.
- [x] `impeccable detect` over the changed files: one advisory, `font-size: 11px` in the existing
      profile chip (ADR-0020), not in this change. `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/sidebar-scale-ladder.mdx`](../app-flow/sidebar-scale-ladder.mdx): Current;
      [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx) screen 1 and
      [`../app-flow/one-open-station.mdx`](../app-flow/one-open-station.mdx), their Mermaid and
      Archify views; [`../prd/docs-sidebars.mdx`](../prd/docs-sidebars.mdx).
- [x] [`ADR-0018`](./ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx):
      *Superseded by:* this ADR for decision 2, in part.
- [x] `DESIGN.md` and `.impeccable/design.json`: the ladder, the lifted card, belts.
- [x] `AGENTS.md` §1 (the sidebar), `PROJECT_AGENTS.md` (belts), `README.md`.
- [x] [`./index.mdx`](./index.mdx): status.


# ADR-0028 — The site is named Puncoz Verse (/docs/maintain/adr/ADR-0028-the-site-is-named-puncoz-verse)

- **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)
- **Design documents:** [`../app-flow/community-identity.mdx`](../app-flow/community-identity.mdx)

## Context [#context]

The site has used a working name, *Puncoz Docs*, 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 name **Puncoz Verse**, as in universe, and asked for it
throughout the project. They named this site's own documentation, the project with the slug
`docs`, **Puncoz Verse Docs**. 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 is Puncoz Verse.** `appName` becomes *Puncoz Verse*: the header's wordmark on every
   page, the home page's title (*Puncoz Verse — 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 are Puncoz Verse Docs.** The project with the slug `docs` takes the
   title *Puncoz Verse Docs* 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
   *Puncoz Verse*. The slug and every URL stay as they are: `/docs`, `/docs/maintain/…`.
3. **Unchanged identifiers.** The repository folder and `package.json` name
   (`puncoz-packages-docs`), the GitHub link (`puncoz-official/docs`, 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 | *Puncoz Verse* for the site, *Puncoz Verse 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: *Puncoz Verse* is the whole, *Puncoz Verse
  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`: *Puncoz Verse Docs*, and the prose
      (decision 2).
- [x] Tests (ADR-0007): the site's name and this project's title; the `llms.txt` heading; no
      *Puncoz Docs* 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` (*# Puncoz Verse*) and `/docs.md`. `llms-full.txt` keeps *Puncoz Docs* 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.


# ADR-0029 — The Verse is a still sky you zoom through (/docs/maintain/adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through)

- **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:** —
- **Superseded by:** [ADR-0036](./ADR-0036-the-site-is-nepal-dev-verse.mdx) (in part: the brand mark)
- **Design documents:** [`../app-flow/universe-theme.mdx`](../app-flow/universe-theme.mdx),
  [`../prd/universe-theme.mdx`](../prd/universe-theme.mdx)

## Context [#context]

The site is named *Puncoz Verse*, as in universe (ADR-0028). When the owner chose the name, they
asked for the whole site to carry that theme, and ADR-0028 left the theme to this ADR.

The solar system is already on every page (ADR-0017, ADR-0018, ADR-0027): the star is the maker,
entries are planets, version lines are moons, Use and Maintain are a planet's day and night sides,
and the sidebar is a scale ladder down to the page. What the site does not have:

- **A level above the system.** The home page shows one system and nothing around it, so the
  name *Verse* has no place on the map.
- **A mark of its own.** The header's brand mark is a ringed planet, and under DESIGN.md's
  *Mark Means* rule a ring means a project.
- **A sky on reading pages.** Docs pages are plain graphite; the space feeling lives on the home
  page, the 404 and the footer only.
- **A sense of scale between pages.** Moving from the home page to a planet, or from a page back
  up to its planet, is an ordinary page change. Fumadocs' breadcrumb names the folders but none of
  the levels above them.

Facts that shape the options:

- React 19.3 ships `<ViewTransition>` and `addTransitionType`, and Next.js 16.4 runs App Router
  navigations as transitions with no configuration; `<Link>` takes `transitionTypes`
  (`node_modules/next/dist/docs/01-app/02-guides/view-transitions.md`, `…/02-components/link.md`).
  Browsers without the View Transitions API navigate normally.
- Fumadocs' notebook page takes its breadcrumb as a slot (`slots.breadcrumb` on `DocsPage`).
- The site has no favicon or app icon (`src/app/` holds no `icon` file).
- DESIGN.md's *One Orbit* rule: the turning system is the only continuous motion of the site's
  own.

The owner chose on 2026-11-01:

- all three parts of the theme, **staged**: identity and sky, then zoom, then words, each
  built and reviewed as its own step;
- **one system, a wider sky** at the top level;
- the approach **still sky, morph zoom**.

## Decision [#decision]

1. **The Verse is the sky around the one system.** ADR-0017's metaphor stands: the star is the
   maker, and every public entry orbits it. Above the system there is only sky, the asteroid belt
   and, beyond it, the private projects, dim and far. The site has one scale ladder, from the top:
   **Verse** (the site) → **System** (the home page) → **Planet** (an entry's overview) → **Side
   and moon** (a track and its version line) → **Orbit** (a folder) → **Satellite** (a page) →
   **Probe** (where the reader is).

### Stage 1: identity and sky [#stage-1-identity-and-sky]

2. **The Verse mark.** A new brand mark replaces the ringed planet in the header and on Open
   Graph images, and becomes the site's icon (`src/app/icon.svg`, Next.js' file convention): the
   system seen from outside, a star-coloured centre inside two nested, tilted orbits in Frost Ink
   with a teal planet on the inner one. It has no ring, so it never reads as a project. The
   wordmark keeps its face and size; the name stays *Puncoz Verse*. The final drawing is reviewed
   with stage 1.
3. **A still sky on every page.** The home page, docs pages and the 404 stand on one star field:
   - drawn on the server as SVG from a fixed seed, so it is the same on every load and needs no
     script;
   - still: it never moves, twinkles or drifts (the *One Orbit* rule holds);
   - three sizes of star (about 0.6, 1 and 1.6px) in Steel Faint and Frost Ink at low opacity,
     thickest at the page's edges and behind the header, thinning toward the content;
   - **never behind text**: none under the reading column, the sidebar's rows or the table of
     contents, so every contrast measured in DESIGN.md stays as it is;
   - in the light theme, the same field as fine graphite specks at lower opacity, like a printed
     star chart.
   The home page's turning system draws over the sky, with its own stars removed so the two don't
   double.

### Stage 2: zoom [#stage-2-zoom]

4. **The scale strip.** On every docs page Fumadocs' breadcrumb is replaced by a strip naming
   each level with its mark: `Verse ▸ System ▸ ● lodestar ▸ ☀ Use · ◯ v0.1 ▸ ○ Guides ▸ Forms`.
   - *Verse* links to `/#verse`, *System* to `/`, the planet to its overview, the side and moon to
     the line's first page, the orbit to its index when it has one (otherwise it is plain text);
     the current page is plain text with `aria-current="page"`.
   - It is a `nav` labelled *Scale*. On phones it shows only the parent level, with a back arrow,
     and the current page's name.
   - An overview shows `Verse ▸ System ▸ ● planet`. Maintain shows a moon for the side and no
     version line.
5. **The Verse view.** The home page's system gets one control at its lower right, *Zoom out to
   the Verse*. Pressing it, or opening `/#verse`, eases the camera out over about 1.2 seconds with
   the site's ease: the system shrinks to the centre, still turning, the wider sky opens around it,
   the belt and the private planets show dim and far, labels fade except *Puncoz Nepal*, and a
   caption reads *The Verse · one system so far*. The control becomes *Back to the system*;
   pressing it, or the system itself, eases back in. It is a single response to input, so the
   *One Orbit* rule holds.
6. **The morph.** Opening a planet from its home page card morphs the card's planet into the
   overview's planet header (a shared `<ViewTransition>` named for the entry), and coming back
   morphs it back. Links in the scale strip and the sidebar's planet chip carry a transition type:
   going up a level the new page settles in from slightly larger (zoom out), going down from
   slightly smaller (zoom in), in about 0.35 seconds.
7. **Motion off means no motion.** With reduced motion the Verse view changes instantly and no
   page morphs or zooms; in a browser without view transitions, navigation is unchanged. Nothing
   is hidden before scripts run.

### Stage 3: words [#stage-3-words]

8. **Space words name places, never controls.** Controls and the labels readers scan for keep
   their plain names: Search, Overview, Use, Maintain, On this page, version names, Back to top.
   Space words go where the site describes itself: empty states, hints, the scale strip's top two
   levels, the Verse view, the 404 and the footer, always alongside a plain sentence. The copy
   that changes is listed in the app flow's *Words* table; DESIGN.md gains the vocabulary as a
   named rule.

### How it is built [#how-it-is-built]

9. **One stage at a time, reviewed between.** Stage 1 is built on approval. Stage 2 starts once
   the owner has reviewed stage 1 in the working tree, and stage 3 once they have reviewed stage
   2. This departs from `AGENTS.md` §3 ("don't stop for per-change review") by the owner's
   choice. Each stage ships its tests, DESIGN.md, the app flow's status and the docs below.
10. **Unchanged:** the marks and their meanings, the scale ladder in the sidebar (ADR-0027), the
    search button's text, every URL, and every Markdown surface: the sky, the strip, the zoom and
    the morph are only drawn on the page, so per-page Markdown, `llms.txt` and `llms-full.txt`
    stay the same.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Scope | A — identity and a quiet sky | Smallest change seen everywhere | The name still has no place on the map | Rejected (owner) |
| Scope | B — zoom between scales | The hierarchy becomes something you move through | A navigation element and transitions | Rejected alone (owner) |
| Scope | C — words only | Cheap | Clarity risk on a docs site; nothing visible | Rejected alone (owner) |
| Scope | D — all three, staged | The whole theme, reviewed in steps | Largest; three reviews | Chosen (owner) |
| Top level | A — one system, a wider sky | ADR-0017 stays true; nothing changes meaning | The top level is atmosphere more than navigation | Chosen (owner) |
| Top level | B — ecosystems as star systems, the maker as the galaxy's core | Real navigation at the top | Supersedes ADR-0017's metaphor; redraws the home page | Rejected (owner) |
| Top level | C — a public and a private system | Prepares sign-in | Decides how private work shows, which needs its own ADR | Rejected (owner) |
| Top level | D — no level above the system | Smallest | *Verse* is only a name | Rejected (owner) |
| Approach | A — still sky, morph zoom | Keeps the *One Orbit* rule; reading pages stay server-rendered; no new library | The sky never moves | Chosen (owner) |
| Approach | B — a living sky with a camera zoom | Most immersive | A second continuous motion; a client canvas on every reading page | Rejected (owner) |
| Approach | C — zoom as a place only | Safest for motion | The zoom is never seen happening | Rejected (owner) |
| Sky on reading pages | A — around the content, never behind text | Contrast unchanged | Fewer stars on narrow screens | Chosen |
| Sky on reading pages | B — everywhere, dimmed behind text | Fuller sky | Every text pair re-measured; busier reading | Rejected |
| Phone strip | A — parent level and current page | Fits 360px; one tap up | The full ladder is only on wider screens | Chosen |
| Phone strip | B — the full strip, scrolled sideways | Every level | Horizontal scrolling inside the page | Rejected |

## Consequences [#consequences]

**Positive**

- The name has a place: the Verse is the first level of the ladder and a view on the home page.
- Every page shares one sky and one mark, so the site reads as one place.
- Readers see where they are in the ladder on every page, and moving up or down it shows as a
  zoom.
- The brand mark no longer borrows the project mark.

**Negative / accepted trade-offs**

- Three stages and three reviews before the theme is complete.
- The star field adds an inline SVG to every page (a few kilobytes).
- The morph works only between a home page card and its overview; the canvas planets can't be
  part of a view transition.
- The Verse view is mostly atmosphere until there is more than one system to show.

## Content invariants [#content-invariants]

None touched. No page moves and no URL changes. The sky, the strip, the Verse view and the morph
are drawn on the page only, so every Markdown surface stays as it is (§6.5). The private planets
in the Verse view are the three invented names already on the home page (ADR-0017); no private
content is added.

## Security considerations [#security-considerations]

None. This change touches no data, no endpoint and no secret. `/#verse` is a fragment read in the
browser; it never reaches the server and carries nothing about the reader. No new third party is
involved and no dependency is added.

## Implementation notes [#implementation-notes]

**Stage 1: identity and sky**

- [x] `src/components/verse-mark.tsx`: the mark (decision 2), used by `site-header.tsx` and the
      Open Graph image; `src/app/icon.svg` from the same drawing.
- [x] `src/components/sky.tsx` and `src/lib/sky.ts`: the seeded field as a server component,
      with the regions kept clear of text (decision 3); placed once in `src/app/layout.tsx`;
      styles in `src/app/global.css` for both themes. The home page's canvas drew no background
      stars, so nothing there changed; the home wrapper's own ground fill, which hid the sky, is
      removed (the body paints the same colour). The header's band is `HeaderSky`, evenly spread
      and masked to the gap between the links and the buttons.
- [x] Tests (ADR-0007, ADR-0021): the field is the same for the same seed and different for
      another; no star falls in a cleared region; star counts and sizes stay in their ranges; the
      mark renders with no ring and with its title for assistive tech.
- [x] Checked in Chrome on localhost against `bunx next build`, dark and light: home and a docs page
      on a wide screen (the sky in the gutters, clear of the column and the contents), the header
      band at 1600px and at 570px (clear of the wordmark and the buttons), the 404, the Open Graph
      image and the icon link. Where the content fills the width there is no page sky, only the
      header's band. `impeccable detect` over the changed files: one advisory, the existing 11px
      profile chip (ADR-0020).

**Stage 2: zoom**

- [x] `src/components/docs/scale-strip.tsx` and `src/lib/scale-strip.ts`: the levels from the
      page tree and the catalogue (decision 4). Fumadocs' `slots.breadcrumb` receives only its
      own breadcrumb options and its `component` option is deprecated, so the page turns the
      breadcrumb off (`breadcrumb={{ enabled: false }}`) and renders the strip as its first
      child, in the same place. A side level links to the first page of its line or track; an
      orbit links to its folder's index when it has one.
- [x] `src/components/home/orbit-map.tsx` with `src/lib/verse-view.ts`: the Verse view, its
      control and caption, and `#verse` (decision 5). The far planets sit up-right, right and
      below the star, so they never reach the hero's text; a click on the canvas in the Verse
      view zooms back in.
- [x] `src/components/zoom-page.tsx`: `ZoomPage` around each page (the home page and every docs
      page) and `PlanetMorph` on the card's and the planet header's planet (decision 6).
      `src/lib/zoom.ts` holds the two transition types, apart from `scale-strip.ts` so client
      components do not pull in the catalogue's build checks. Zoom-out on the strip's links and
      the planet chip; zoom-in on the card's name and on the Use and Maintain links of the card
      and the planet header. The CSS for both directions and for reduced motion is in
      `src/app/global.css` (decision 7).
- [x] Tests: the strip's levels for an overview, a Use page in a line, a Maintain page, a page in
      a nested folder, a folder's index and a folder without one, a page outside the catalogue;
      the phone level; the Verse view's easing, scale and far planets; the wrappers add no
      markup.
- [x] Checked in Chrome on localhost against `bunx next build`: the strip at 1600px and 570px
      (links and their targets, the phone's parent level and back arrow), the Verse view in and
      out by the button and by a click, `/#verse` easing out on load, and the morph from the card
      to the planet header with the `zoom-in` type. Between two docs pages the page zooms out;
      between the home page and a docs page the route groups' layouts differ, so the page itself
      crossfades and only the planet morphs. Coming back, the home page opens at its top with the
      card below the fold, so the planet fades out rather than morphing into it (the app flow's
      off-screen case). Reduced motion was checked in the CSS and the
      easing's tests, not by emulating the setting in the browser. `impeccable detect` over the
      changed files: no findings beyond the existing 11px profile chip.

**Stage 3: words**

- [x] The *Words* table in the app flow, applied (decision 8): the home page's and the ADR
      constellation's empty states, and the search dialog's no results. Fumadocs'
      `SearchDialogList` takes an `Empty` component, so `src/components/search-empty.tsx` replaces
      the message there, with the same `role="status"`, rather than through Fumadocs'
      translations, which would mean configuring its i18n for one string. The other rows were
      built in stages 1 and 2 or were already in place.
- [x] Tests: the home page's empty state and the search message, both rendered on the server.
      The constellation is a client component, not unit-tested until a DOM is chosen (ADR-0021).

**Every stage**

- [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/universe-theme.mdx`](../app-flow/universe-theme.mdx): each stage's screens
      marked built; Current after stage 3.
- [x] [`../prd/universe-theme.mdx`](../prd/universe-theme.mdx): Current after stage 3.
- [x] `DESIGN.md` and `.impeccable/design.json`: the mark and the sky (stage 1), the strip, the
      Verse view and the morph (stage 2), the vocabulary rule (stage 3).
- [x] `PRODUCT.md` (the Verse as the top level), `AGENTS.md` §1 and §10, `PROJECT_AGENTS.md` if
      the strip changes what consuming repositories see, `README.md`,
      [`../architecture/system.mdx`](../architecture/system.mdx).
- [x] The app flows that draw the header's mark or the breadcrumb, their Mermaid and Archify views:
      site pages (the mark's description), multi-repository projects (the strip names the
      repository); the home page and package navigation name the wordmark only in text, which
      still holds. The home page and ADR constellation app flows and the home page PRD carry the
      new empty states.
- [x] [`./index.mdx`](./index.mdx): status (Approved; the app flow and PRD rows are Current).


# ADR-0030 — The horizon rises over the page, and its sky comes alive (/docs/maintain/adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive)

- **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:** [ADR-0018](./ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx)
  decision 4 (in part: the footer sitting "below the sidebar and the page", and its scene);
  [ADR-0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) decision 8 (in part: what the
  scene draws); [ADR-0015](./ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx)
  decision 7 (in part: "no entrance motion on docs pages", for the footer only)
- **Superseded by:** [ADR-0031](./ADR-0031-the-sidebar-sets-without-dimming.mdx) (in part: decision 1's "dim to 55%"); [ADR-0037](./ADR-0037-the-horizon-is-the-himalaya.mdx) (in part: decision 2's aurora and rim, and the places of the clouds, the star and the observatory; decision 4's light scene)
- **Design documents:** [`../app-flow/living-horizon.mdx`](../app-flow/living-horizon.mdx),
  [`../prd/docs-sidebars.mdx`](../prd/docs-sidebars.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx), `DESIGN.md`

## Context [#context]

- Every page ends with the full Horizon footer (ADR-0018 decision 4): the closing line, a scene
  of the star rising behind a planet's curved edge, then the planet row, the link row and the
  credit. `src/components/horizon-footer.tsx` draws the scene as one still SVG: 60 seeded stars,
  the star's glow and disc, the planet's ground and its teal atmosphere rim.
- **On docs pages the sidebar runs over it.** Fumadocs' notebook layout puts the sidebar in a
  sticky wrapper (`z-index: 20`) as tall as the window, and the trajectory ("On this page") in a
  sticky column. The footer is a full-width grid row with no stacking of its own, so at the end
  of a page the sidebar's cards and the trajectory sit on top of the closing line and the scene.
  Checked in Chrome at 1632px on `/docs/maintain/prd/diagrams`.
- The owner finds the scene not lively enough, and asked for clouds and other sky objects, with
  animation where it helps, without making it worse.
- What stands in the way:
  - DESIGN.md's *One Orbit* rule: the turning system is the site's only continuous motion. Its one
    exception is a diagram's Archify trace (ADR-0022).
  - ADR-0015 decision 7: no entrance motion on docs pages.
  - DESIGN.md's *Mark Means* rule: a moon means a version line and a ring means a project. So
    the scene gets no moon and no ringed planet.
  - ADR-0029 decision 3: the page's still sky never moves. That sky lies behind the page; the
    scene is the footer's own sky and is not part of it.
- The owner chose, with options: the horizon **rises over** the page; a **gentle loop** of
  motion; and four objects, **lit clouds, a shooting star, an aurora on the rim and an
  observatory on the ridge**.

## Decision [#decision]

1. **The horizon rises over the page.** On docs pages the footer stacks above the sidebar and
   the trajectory, under the site header (`z-index: 30`, the header is 40), on an opaque sky.
   - Its top edge is a **dusk edge**: 96px fading from transparent to the ground colour, so
     the sidebar and the trajectory sink into dusk where the horizon meets them, rather than
     being cut off by a line.
   - As the footer comes into view, the sidebar and the trajectory **set**: they drop up to 24px
     and dim to 55%, in step with the scroll. Scrolling back up raises them again.
   - What lies above the horizon stays where it was and works as before. What lies below it is
     hidden until the reader scrolls up.
   - On phones the sidebar is a drawer and the trajectory a bar under the header, so nothing
     overlaps. The home page and the 404 have neither.
2. **The scene is a dusk sky with five layers**, back to front, the same on every page:
   - **Stars:** the 60 seeded stars stay. Fourteen of them twinkle, between 25% and full
     opacity over 3 to 7 seconds each, with staggered starts.
   - **Aurora:** two soft teal ribbons rising off the atmosphere rim, drawn as blurred SVG
     paths. They breathe over about 9 seconds (opacity 0.25 to 0.55, a slight vertical
     stretch), and the rim brightens with them.
   - **Shooting stars:** a thin streak with a fading tail crosses the upper sky, down and to the
     left, visible for about a second. There are two, on 14- and 23-second cycles, so they never
     fall into a beat.
   - **The star** rises with the scroll: from 40px below the curve, as the footer starts to
     enter, to its place when the footer is half in view, its glow growing with it.
   - **Lit clouds:** three thin bands at different heights, each a seamless strip that loops
     sideways over 90, 140 and 200 seconds. Their undersides catch the star's colour and their
     tops fade into the ground; the lowest band passes in front of the star's glow, never its
     disc.
   - **The observatory:** a small silhouette on the ridge, left of the star: a domed building
     standing on the planet's curve, its slit open toward the star, a telescope line in it and
     one warm window. It does not move.
3. **The rules for its motion.** The scene is the *One Orbit* rule's second named exception,
   beside Archify:
   - Only transform and opacity animate, in CSS, with no library (ADR-0014 decision 7). The blur
     is drawn once and never animated.
   - Loops run only while the footer is on screen. A small client component,
     `HorizonAwake`, sets `data-awake` on the footer through an `IntersectionObserver`; without it,
     every loop is paused. Browsers already pause them in hidden tabs.
   - The rise and the setting are scroll-driven (`animation-timeline`, named
     `--horizon` on the footer and scoped to the page). Where a browser does not support that,
     the star stands risen, and the sidebar and the trajectory are simply covered by the dusk
     edge.
   - Under reduced motion nothing loops, rises or sets. The star stands risen, the clouds stay
     where they are drawn, and the sidebar is covered as in the fallback.
   - Nothing moves behind text: the closing line and the surface rows stand on the opaque
     ground, above the scene.
4. **Light theme.** The clouds turn pale with warm undersides, the aurora drops to half its
   opacity, the stars use Steel Faint at lower opacity, and the ground is the light ground.
5. **Unchanged:** the closing line, the planet row, the link row and its labels ("Back to top" on
   docs pages, "Back to orbit" elsewhere), the credit, the page's still sky (ADR-0029), every
   URL and every Markdown surface. The scene stays `aria-hidden` inline SVG in the existing
   tokens (ADR-0017 decision 13). No dependency is added.

## Options considered [#options-considered]

| Question | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Overlap | A — the horizon rises over the page | Keeps the full-width scene; the end of the page becomes a moment; reuses the planet's own edge | The bottom of the sidebar is hidden while the footer is in view | Chosen (owner) |
| Overlap | B — the sidebar lands on the horizon | Conventional; no new motion | The sidebar and trajectory scroll away abruptly; nothing of the theme | Rejected |
| Overlap | C — the horizon fits the reading column | No overlap at all | A narrow, cramped scene; two footer widths to keep | Rejected |
| Motion | A — a moment on arrival, then a slow drift | Calm; one small exception | Less lively than asked | Rejected |
| Motion | B — a moment on arrival only | Keeps the *One Orbit* rule | The scene goes still again at once | Rejected |
| Motion | C — a gentle loop | The liveliest; reads as a real sky | Motion at the end of every page; a second exception to *One Orbit* | Chosen (owner) |
| Objects | Lit clouds, a shooting star, an aurora on the rim, an observatory on the ridge | Depth, life and a story beat, with no mark that carries meaning | More drawing and CSS in the footer | Chosen (owner), all four |
| Objects | A moon, a ringed planet | Familiar sky objects | Break the *Mark Means* rule: moons are version lines, rings are projects | Rejected |

## Consequences [#consequences]

**Positive**

- The sidebar and the trajectory no longer sit on the closing line and the scene; they set
  below the horizon, which belongs to the site's own world.
- The end of every page has a living sky that rewards reaching it.
- The motion stays cheap and stops when nobody is looking: CSS transforms and opacity, paused off
  screen and in hidden tabs, and gone under reduced motion.

**Negative / accepted trade-offs**

- While the footer is in view, the bottom of the sidebar is hidden; scrolling up brings it back.
  On a page shorter than the window the footer is in view on arrival, and the sidebar stands
  partly below the horizon.
- The scene moves at the end of every page, including docs pages, which ADR-0015 kept still.
- Firefox, without scroll-driven animations by default, shows the risen star and no setting.
- The footer's SVG and CSS grow; they ship with every page.

## Content invariants [#content-invariants]

None is touched. The scene is decoration in the footer: per-page Markdown, `llms.txt` and
`llms-full.txt` are unchanged (§6.5), and no content is added.

## Security considerations [#security-considerations]

None. This change touches no data, no endpoint and no secret. The scene is inline SVG and
CSS with no external resource. The new client component reads only whether the footer is on
screen.

## Implementation notes [#implementation-notes]

- [x] `src/lib/horizon-sky.ts`:
  - the scene's stars, from `starField` in `src/lib/sky.ts` (seeded, as now), with the
    twinkling subset and each one's duration and delay;
  - the cloud bands' shapes;
  - `ridgeY(x)`, the height of the planet's curve at a point, so the observatory stands on it.
- [x] `src/components/horizon-footer.tsx`: the layers in decision 2, in order, inside the
  `aria-hidden` scene. Every looping layer is its own element, so its transform or opacity is
  composited and the blurs are drawn once. The cloud bands are sized in container units to the
  viewBox the other layers show, so sliding a band by half its width moves it exactly one period
  at any width.
- [x] `src/components/horizon-awake.tsx`: the client component in decision 3. It sets
  `data-awake` while the footer is on screen and removes it when it leaves.
- [x] `src/app/site.css`:
  - the footer's stacking, opaque ground and dusk edge on docs pages;
  - the layers, their keyframes and the light theme;
  - the scroll-driven rise and setting inside `@supports (animation-timeline: view())`;
  - `timeline-scope: --horizon` on the root;
  - paused loops without `data-awake`;
  - the reduced-motion rules.
- [x] Tests (ADR-0007, ADR-0021):
  - the stars are the same on every build and the twinkling count is fourteen;
  - `ridgeY` lies on the curve at the centre and at the observatory's place;
  - the scene renders every layer in order, stays `aria-hidden` and has nothing to focus;
  - the clouds loop seamlessly (each puff inside its period) and never cross the star's disc.
  `HorizonAwake` is a client component, not unit-tested until a DOM is chosen. The surface rows
  are unchanged and not rendered in a test, because their Search button reads Fumadocs' search
  context. Both were checked in Chrome instead.
- [x] Checked in Chrome on localhost against `bunx next build`:
  - a docs page at about 1600px: the horizon over the sidebar and the trajectory, the setting
    and the rise both ways with the scroll;
  - the loops running only while the footer is on screen;
  - the home page, the light theme, and phone width;
  - the 404 ends with the same Horizon, but it still renders inside the docs layout at unknown
    paths, and that layout's header covers it (an existing bug, unchanged here);
  - reduced motion in the CSS, not by emulating the setting.
- [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/living-horizon.mdx`](../app-flow/living-horizon.mdx): Current; the
  [docs sidebars](../app-flow/docs-sidebars.mdx) and [home page](../app-flow/home-page.mdx) app
  flows where they describe the footer.
- [x] [`../prd/docs-sidebars.mdx`](../prd/docs-sidebars.mdx): the horizon's requirements.
- [x] `DESIGN.md` and `.impeccable/design.json`:
  - the Horizon footer component;
  - Motion;
  - the *One Orbit* rule's second exception.
- [x] `AGENTS.md` §1, §5 and §10, `README.md` if its overview names the footer, and
  [`../architecture/system.mdx`](../architecture/system.mdx).
- [x] [`./index.mdx`](./index.mdx): index row and status.


# ADR-0031 — The sidebar sets without dimming (/docs/maintain/adr/ADR-0031-the-sidebar-sets-without-dimming)

- **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:** [ADR-0030](./ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx)
  decision 1 (in part: "dim to 55%")
- **Superseded by:** —
- **Design documents:** [`../app-flow/living-horizon.mdx`](../app-flow/living-horizon.mdx) (screen 2),
  [`../prd/docs-sidebars.mdx`](../prd/docs-sidebars.mdx), `DESIGN.md`

## Context [#context]

- Under ADR-0030 decision 1, when the Horizon footer rises over a docs page, the sidebar and the
  trajectory **set**: they drop up to 24px and dim to 55%, in step with the scroll
  (`@keyframes horizon-set` in `src/app/site.css`).
- What stays above the horizon still works: its links can be read, hovered and clicked.
- A light-theme contrast audit, run in Chrome against `bunx next build` on
  `/docs`, found that at 55% this text falls below WCAG AA's 4.5:1 on Graphite Ground
  (`#f6f7f9`). The ratios below are computed from the tokens in `src/app/global.css`:

  | Text | Full | 85% | 75% | 55% |
  |---|---|---|---|---|
  | Ink | 17.8:1 | 11.9:1 | 8.3:1 | 4.1:1 |
  | Muted | 6.7:1 | 4.7:1 | 3.7:1 | 2.5:1 |
  | Steel Faint (separators, counts, the trajectory) | 5.2:1 | 3.8:1 | 3.2:1 | 2.2:1 |
  | Teal (the open station, the current page) | 4.9:1 | 3.8:1 | 3.2:1 | 2.3:1 |

- No dim level keeps every text colour at 4.5:1; even 85% fails Steel Faint and Teal.
- The dusk edge already does the setting's visual work: what runs below the horizon fades into
  the ground over 96px and is hidden.
- The owner chose, with options: drop only, no dimming.

## Decision [#decision]

1. **The sidebar and the trajectory set by dropping, not by dimming.** As the Horizon enters, they
   drop up to 24px in step with the scroll, as now, and stay at full opacity. What runs below the
   horizon still sinks into the dusk edge and is hidden. In both themes.
2. **Unchanged from ADR-0030:**
   - the scroll range (entry 0% to 60%), the 768px minimum and the reduced-motion and
     no-support fallbacks;
   - the footer's stacking, its dusk edge and everything in the scene.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Drop only, no dimming | Every text colour keeps its contrast above the horizon; the dusk edge still does the setting | The sidebar no longer looks like it fades as it sets | Chosen (owner) |
| B — Dim only in dark | Keeps the fade where it reads as dusk | Dark keeps the same failure, measured against darker tokens; two behaviours to keep | Rejected |
| C — Dim less (75% or 85%) | A softer fade | Still under 4.5:1 for Steel Faint and Teal at any level that shows | Rejected |
| D — Keep 55% | No change | Readable, clickable text below AA at the end of every docs page | Rejected |

## Consequences [#consequences]

**Positive**

- The part of the sidebar and trajectory still above the horizon keeps the contrast every other
  text on the site has (DESIGN.md: every text colour 4.5:1 or more).
- One property fewer animates on the sidebar and the trajectory.

**Negative / accepted trade-offs**

- The setting is a drop and the dusk edge only; nothing fades as it sinks except where the dusk
  edge covers it.

## Content invariants [#content-invariants]

None is touched. No content, URL or Markdown surface changes.

## Security considerations [#security-considerations]

None. This change touches no data, no endpoint and no secret.

## Implementation notes [#implementation-notes]

- [x] `src/app/site.css`: `@keyframes horizon-set` keeps `translate: 0 24px` and drops its
  `opacity`.
- [x] Tests: the setting is CSS on Fumadocs' layout and is not rendered in a unit test
  (ADR-0021). `src/components/horizon-footer.test.tsx` reads the keyframes from `site.css`
  instead: they drop 24px and set no opacity (it failed before the change). The contrast of
  the sidebar's text at full opacity was measured in the light-theme audit that led to this ADR
  (the table above). Checked in Chrome after the change, in the light theme at the end of a
  docs page: the sidebar and the trajectory stand at opacity 1, dropped 24px; a full contrast
  scan was not re-run.
- [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/living-horizon.mdx`](../app-flow/living-horizon.mdx): screen 2's text and
  states (no dimming).
- [x] [`../prd/docs-sidebars.mdx`](../prd/docs-sidebars.mdx), where it describes the setting:
  it does not mention the dimming, so nothing changed.
- [x] `DESIGN.md`, the Horizon footer bullet: it names the setting without the dimming, so
  nothing changed.
- [x] ADR-0030's "Superseded by" line, and [`./index.mdx`](./index.mdx): index row and status.


# ADR-0032 — The hero's system comes alive (/docs/maintain/adr/ADR-0032-the-heros-system-comes-alive)

- **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:** [ADR-0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) decision 2 (in
  part: what the hero's system draws), and the *One Orbit* rule's two-exception list in
  `DESIGN.md` (ADR-0030 decision 3), which gains a third
- **Superseded by:** —
- **Design documents:** [`../app-flow/living-hero.mdx`](../app-flow/living-hero.mdx),
  [`../prd/home-page.mdx`](../prd/home-page.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx), `DESIGN.md`

## Context [#context]

- The home page's hero is the system (ADR-0017 decision 2): a canvas drawn by
  `src/components/home/orbit-map.tsx`. It has the star, an orbit for each ring that has entries
  (`presentRings` in `src/lib/rings.ts`), the planets with their moons, a tooltip on pointing,
  and the zoom to the Verse (ADR-0029).
- **Today it draws one star, one orbit and one ringed planet.** Only the site's own project is
  documented, so `presentRings` returns the Projects ring alone. The five default orbits appear
  only when the catalogue is empty. On a 1412px screen the system takes the right half of
  the hero and is mostly empty canvas. The owner finds it dull.
- What stands in the way:
  - **The Mark Means rule** (DESIGN.md): a ring means project, a full moon the latest release, a
    crescent an older one, a dashed new moon `dev`, a lock private. None is used for
    decoration, and the legend teaches "dashed = unreleased".
  - **The One Orbit rule** (DESIGN.md): the system is the site's only continuous motion. Its
    exceptions are a diagram's Archify trace (ADR-0022) and the Horizon's sky (ADR-0030).
  - **The still sky** (ADR-0029 decision 3): the page's sky never moves.
  - **The Places, Not Controls rule** (ADR-0029): a space word always stands beside a plain
    sentence.
  - **No invented planets.** The system shows only documented entries; the invented private
    names appear only in the Verse view and beyond the belt (ADR-0016, ADR-0017 decision 4).
- The owner chose, with options, all eight of: every ecosystem's orbit, a living star, planet
  trails, pointer depth, an arrival spin-up, a telemetry line, a comet now and then, and a
  nebula behind the system.

## Decision [#decision]

The hero's system gains eight things. Everything stays on the existing canvas, or in one still
layer behind it, and uses only the existing tokens. No dependency is added.

1. **Every ecosystem's orbit, waiting.**
   - The system always draws the npm, Composer, PyPI, Go and Projects orbits, the five the
     subline names. It also draws Cargo and Other when an entry is in them, in the existing ring
     order.
   - An orbit with planets is drawn as now.
   - An orbit with none is a thinner, fainter **solid** line: 0.75px, Line 2 mixed with 35% of
     its ecosystem colour, at 60% opacity. It is not dashed, because a dashed mark means
     unreleased.
   - Its name (npm, Composer, PyPI, Go, Projects) sits on the orbit's upper left in 11px Data,
     Steel Faint, and turns with nothing.
   - Pointing within 8px of an empty orbit shows the existing tooltip: its name, "No planets
     yet". It has nothing to open.
   - With planets in only some orbits, the documented planets take their own orbits' radii, so
     the system has the same shape whatever is documented.
2. **A living star.**
   - The disc grows from 9px to 14px, with "Puncoz Nepal" under it as now.
   - Its glow becomes a corona of three soft layers that breathe together over about 6 seconds
     (±15% opacity).
   - Eight thin rays in the star colour at 25% turn once every 120 seconds.
   - This is part of the system's own motion.
3. **Planet trails.** Each planet leaves a trail behind it along its orbit, a sixth of the way
   round: 2px wide, fading from 35% of its colour to nothing (Frost Ink for projects). Moons
   leave none. A trail is drawn from the planet's own position each frame and adds no motion of
   its own.
4. **Pointer depth.**
   - On a device with a fine pointer, the system leans toward the pointer as it moves over the
     hero: the orbits' tilt moves from 0.36 by up to ±0.05, and the centre by up to 8px.
   - The nebula shifts up to 12px the other way. Both ease over about 0.6s, and settle back
     when the pointer leaves.
   - The page's still sky does not move (ADR-0029 decision 3).
   - Off for touch and under reduced motion. A response to input, so the *One Orbit* rule holds.
5. **Arrival: the system spins up.**
   - On the first view of `/` in a session, the star ignites: its disc grows from 40% and its
     corona from nothing, over 0.6s.
   - Each planet starts a third of a turn behind its place and sweeps in along its orbit over
     1.2s with the site's ease; the orbits fade in over 0.4s. Then the system turns as usual.
   - Not again in the same session (remembered in `sessionStorage`; if storage is unavailable,
     it runs each time). Not when `/#verse` is opened, where the zoom out runs instead, and not
     under reduced motion.
   - A single response to arrival.
6. **A telemetry line.**
   - The caption beside *Zoom out to the Verse*, empty in the system view today, reads in 12.5px
     Data, Steel Faint, for example: `1 planet · 4 orbits waiting · 0 moons`.
   - Its counts come from the catalogue: the public entries; the drawn orbits with no planet;
     the version lines, `dev` included. Singular and plural follow the counts.
   - The plain sentence stands with it for screen readers, in place of the data line: "1
     project documented; npm, Composer, PyPI and Go have none yet; no versions released." On
     screen the legend under the search button names the marks.
   - In the Verse view the caption reads, as now, *The Verse · one system so far*.
7. **A comet now and then: the One Orbit rule's third exception.**
   - Every 20 to 30 seconds, on a seeded schedule, a comet crosses the upper part of the
     system: a 2px Frost Ink head with a 90px tail that fades. The tail always points away from
     the star, the way a comet's does.
   - It is in view for about 2.5 seconds.
   - It never crosses the text column. On desktop it stays right of 52% of the width; on phones
     it stays inside the system's 310px.
   - It runs only while the hero is on screen, like the system. It doesn't run in the Verse view
     or under reduced motion.
   - It is not a mark, and it carries no meaning.
8. **A nebula behind the system.**
   - A still layer behind the canvas: two soft radial washes centred on the star, Teal at 8% and
     the star colour at 6% in dark, half that in light. They reach 1.4 times the outer orbit.
   - It is masked away from the text column (left of 50% on desktop; outside the system's 310px
     on phones), so nothing glows behind text.
   - It moves only with pointer depth, and shrinks with the system in the Verse view.
9. **Restraint.**
   - Everything new is quieter than the planets. The only new labels are the empty orbits'
     names.
   - The new continuous motion is the star's breathing and rays, inside the system, and the
     rare comet.
   - Under reduced motion the system is drawn once, as now, with the corona, the trails, the
     empty orbits and the nebula still. Without scripts there is no canvas and nothing changes.
10. **Unchanged:** the headline, subline, search button, legend, tooltip on planets, clicking a
    planet, the Verse view and its words, the morph, the still sky, every URL and every Markdown
    surface.

## Options considered [#options-considered]

| Question | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Objects | Every ecosystem's orbit | Structure today; honest about scope; fills naturally | Five orbits with one planet still reads as early days | Chosen (owner) |
| Objects | A living star | The centre is the maker; costs a few draws | One more motion, inside the system | Chosen (owner) |
| Objects | Planet trails | The turning reads at a glance | Busier with many planets | Chosen (owner) |
| Objects | Pointer depth | Responsive and alive on desktop; no loop | Desktop only | Chosen (owner) |
| Around it | Arrival spin-up | A first-screen moment, once | 1.2s before the system settles | Chosen (owner) |
| Around it | A telemetry line | Honest numbers in the site's technical voice | One more line in the hero | Chosen (owner) |
| Around it | A comet now and then | The most alive | A third loop exception; it means nothing | Chosen (owner) |
| Around it | A nebula | Depth behind the system | Decorative; near the glow cliché | Chosen (owner), kept faint and masked from text |
| Empty orbits | Dashed, as first offered | Reads as "waiting" | The legend says dashed = unreleased: breaks *Mark Means* | Rejected for a fainter solid line |
| Telemetry | Plain words only ("1 project · 0 packages") | No space words | Less of the system's voice | Rejected; the plain sentence is the screen-reader text |
| Objects | A moon or ring as decoration | Familiar | Breaks *Mark Means* | Not offered |

## Consequences [#consequences]

**Positive**

- The first screen shows the whole shape of the site today, and grows into it as packages arrive.
- The system has a living centre, visible motion and depth, without a second always-on loop
  except the rare comet.

**Negative / accepted trade-offs**

- A third exception to the *One Orbit* rule: a comet with no meaning crosses the hero every 20
  to 30 seconds.
- The canvas code grows (`orbit-map.tsx` is already 443 lines); the new geometry moves to a
  library file so it can be tested.
- On first visit the system takes 1.2s to settle; the text and search button are usable at once.
- The nebula is decoration; it is kept faint and away from text.

## Content invariants [#content-invariants]

None is touched. No content is added; the telemetry counts come from the public catalogue.
Per-page Markdown, `llms.txt` and `llms-full.txt` are unchanged (§6.5).

## Security considerations [#security-considerations]

None. This change touches no data, no endpoint and no secret. It reads only the public
catalogue the page already has. `sessionStorage` holds one flag, "the hero has spun up", with
no personal data.

## Implementation notes [#implementation-notes]

- [x] `src/lib/hero-sky.ts`, plain functions so they can be tested:
  - `heroRings(entries)`: the five orbits always, plus Cargo and Other when present, in ring
    order;
  - `systemFacts(entries)`: the telemetry counts, the data line and the plain sentence;
    the sentence ends "no versions documented yet" rather than decision 6's "no versions
    released", because a `dev` line is a moon the count includes but is not a release;
  - `cometStarts(seed, n)`: when each comet starts, 20 to 30 seconds apart (named for what it
    returns, in place of `cometSchedule`);
  - `cometPath(...)`: its path inside the system region, never left of the text boundary nor
    above a `top` line, its tail pointing away from the star. The canvas passes `top: 72`, so a
    comet stays below the site header, which the hero's canvas runs under;
  - `trailArc(...)`: a planet's trail as an arc behind it;
  - `spinUp(t)`: the arrival's eased offset and the star's, corona's and orbits' light;
  - also `corona(t)`, `lean(nx, ny)`, `orbitDistance(...)` for the empty orbits' tooltip, and
    `mixHex(...)` for their colour.
- [x] `src/lib/rings.ts`: the hero uses `heroRings`. `presentRings` and `emptyRings` were used
  only by the hero, so they are removed; `ringOrder` is exported for `heroRings`.
- [x] `src/components/home/orbit-map.tsx`: empty orbits and their labels and tooltip, the star's
  corona and rays, trails, pointer depth, the arrival, the comet, all in the existing draw loop
  and its pause, reduced-motion and hidden-tab handling; the caption shows the telemetry line.
  With five orbits the system's size is capped on desktop so it stays clear of the text, and a
  planet's label flips to its left where it would leave the canvas.
- [x] `src/app/(home)/home.css`: the nebula layer, its mask and its pointer shift; the caption.
- [x] Tests (ADR-0007, ADR-0021) for `hero-sky.ts` (`src/lib/hero-sky.test.ts`):
  - the five orbits always, with extra rings only when present;
  - the counts, plurals and plain sentence, including an empty catalogue;
  - comets 20 to 30 seconds apart, always right of the text boundary and below the header,
    tails away from the star;
  - trails behind the planet and a sixth of a turn long;
  - the spin-up ending exactly at zero offset.
- [x] The canvas is a client component and is not unit-tested (ADR-0021). Checked in Chrome
  against `bunx next build` and the development server, at about 1412px and 390px, in both
  themes: the empty orbits and tooltip, the star, trails, pointer depth, the arrival once per
  session, the comet (sampled from the canvas: nothing drawn under the header), the nebula's
  mask, the caption, the Verse view; reduced motion in the code.
- [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/living-hero.mdx`](../app-flow/living-hero.mdx): Current; the
  [home page](../app-flow/home-page.mdx) and [universe theme](../app-flow/universe-theme.mdx)
  app flows where they describe the system and its empty state.
- [x] [`../prd/home-page.mdx`](../prd/home-page.mdx): the hero's requirements.
- [x] `DESIGN.md` and `.impeccable/design.json`: the system (hero canvas), Motion, the
  *One Orbit* rule's third exception.
- [x] `AGENTS.md` §1, §5 and §10, and [`../architecture/system.mdx`](../architecture/system.mdx).
- [x] ADR-0017's "Superseded by" line, and [`./index.mdx`](./index.mdx): index row and status.


# ADR-0033 — The footer says you've reached the horizon (/docs/maintain/adr/ADR-0033-the-footer-says-you-have-reached-the-horizon)

- **Status:** Approved
- **Date:** 2026-11-03
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-03
- **Supersedes:** [ADR-0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) decision 8 (in
  part: the words and the link of the closing line)
- **Superseded by:** [ADR-0036](./ADR-0036-the-site-is-nepal-dev-verse.mdx) (in part: decision 3, the credit's words)
- **Design documents:** [`../app-flow/horizon-closing-line.mdx`](../app-flow/horizon-closing-line.mdx),
  [`../app-flow/living-horizon.mdx`](../app-flow/living-horizon.mdx), `DESIGN.md`

## Context [#context]

- Every page ends with the Horizon footer. Its large closing line reads "Everything here orbits
  one maker: Puncoz Nepal", with the name linked to `https://puncoz.com` (ADR-0017 decision 8).
- The owner wants the line rewritten, better and more about the Verse. Since ADR-0028 and
  ADR-0029 the site is the Puncoz Verse, but the line speaks only of a maker and says nothing
  of the Verse, or of the horizon drawn right under it.
- The wording is quoted in an approved decision, so changing it takes this ADR, though it is copy.
- What was measured in Chrome with the new words, on the development server:
  - **The line breaks mid-sentence.** The closing line has `max-width: 22ch` and
    `text-wrap: balance`, which gives "You've reached the / horizon. The Verse goes on." Each
    sentence fits on its own line: at 48px the first is 565px wide in 638px of room, and at the
    smallest size, 27.2px, 330px in a 390px screen's 358px.
  - **A plain link to `/#verse` does nothing visible on the home page.** The hash changes and
    the Verse view opens, but the reader stays at the bottom of the page: 1772px down before the
    click and after it. The Verse view is in the hero, out of sight.

## Decision [#decision]

1. **The closing line reads, on two lines: "You've reached the horizon. The Verse goes on."**
   Each sentence is its own line. On a screen too narrow for one, it wraps within itself.
2. **"The Verse" is the link**, to `/#verse`, with the star-coloured underline the name has today.
3. **The maker's name leaves the closing line and stays in the credit** under the footer's links,
   unchanged: "Packages and projects by Puncoz Nepal", linked to `https://puncoz.com`. That
   credit is also the plain sentence beside the space words (*The Places, Not Controls Rule*).
4. **The link always shows the Verse view:**
   - from another page, it goes to the home page's Verse view with the zoom out, as the scale
     strip's *Verse* does;
   - on the home page, it returns to the top of the page and opens the Verse view there, with no
     history entry, as *Zoom out to the Verse* does; under reduced motion it jumps;
   - *Back to the system* then works as it always has.
5. **Unchanged:** the scene, the planet row, the footer's links, *Back to orbit* and *Back to
   top*, the type and the width of the closing line.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| "You've reached the horizon. The Verse goes on." | Says where the reader is, matches the drawn horizon, and leads somewhere | The name leaves the large line; the link needs care on the home page | Chosen (owner) |
| "One Verse, one star: Puncoz Nepal." | The shortest; keeps the name large | About who made it, not where the reader is | Rejected |
| "Every world in this Verse circles one star: Puncoz Nepal." | The closest to today's line | Three lines on most screens | Rejected |
| "The Verse is young. One star so far: Puncoz Nepal." | Honest; echoes the Verse view's caption | Hints that other makers may join, and "young" will date | Rejected |
| Home page link: a plain link | No script | The Verse view opens out of sight, as measured above | Rejected |
| Home page link: `id="verse"` on the hero, so the browser scrolls there | Almost no code | Lands 61px down the page, as measured, with the hero's top under the header, and would also move the page when `/#verse` is opened directly | Rejected |

## Consequences [#consequences]

**Positive**

- The line says something true on every page, and the footer gains a way into the Verse.

**Negative / accepted trade-offs**

- The maker's name is no longer large at the end of each page; it is in the small credit.
- A small client component is added to the footer for the link.
- Without scripts the home page has no Verse view, so there the link changes only the URL. From
  other pages it still reaches the home page.

## Content invariants [#content-invariants]

None is touched. The footer is not part of any Markdown surface, and the line names nothing
private.

## Security considerations [#security-considerations]

None. This change touches no data, no endpoint and no secret. The new link is a fixed internal
path, and the existing link to `https://puncoz.com` stays in the credit.

## Implementation notes [#implementation-notes]

- [x] `src/components/horizon-footer.tsx`: the closing line's words, one element per sentence, as
  `HorizonClosing`; the credit as `HorizonCredit`, so both can be rendered in a test.
- [x] `src/components/footer-actions.tsx`: a `VerseLink` client component (decision 4), using
  `verseFragment` and the `zoomOut` transition type. On the home page its `onNavigate` cancels the
  navigation, returns to the top and opens the view. Cmd and Ctrl clicks still open a new tab.
- [x] `src/components/home/orbit-map.tsx`: not changed. The link tells the system through its
  existing `hashchange` listener.
- [x] `src/app/site.css`: each sentence a block.
- [x] `src/app/(home)/page.tsx` and `home.css`, found while checking: an empty `id="verse"`
  target at the very top of the document. From a docs page or the 404 the link first landed
  1212px and 1967px down the home page, because Next.js keeps the scroll position for a hash with
  no target (`layout-router.js`). At y=0 the target does not move the page when `/#verse` is
  opened directly, unlike the `id` on the hero rejected above. It also takes the scale strip's
  *Verse* to the top, and without scripts this link now returns to the top of the home page, so
  it does more there than the Consequences above say.
- [x] Tests (ADR-0007, ADR-0021), in `src/components/horizon-footer.test.tsx`: the closing line's
  words, its one link to `/#verse`, the credit's link to the owner, each sentence a block, and the
  hash target at the top. `VerseLink`'s click is not unit-tested; checked in Chrome instead,
  against `bunx next build`:
  - the two lines at about 1412px, 390px and 320px (the last two in a same-origin frame, because
    the browser window would not shrink), where 320px wraps the first sentence within itself,
    with no sideways scroll; the light theme at all three and the dark at 1412px;
  - from a docs page, and from the 404, to the Verse view at the top;
  - from the bottom of the home page to the Verse view at the top, with no history entry;
  - `/#verse` opened directly, still at the top; *Back to the system* afterwards;
  - reduced motion in the code: the scroll jumps and the view changes at once.
- [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/horizon-closing-line.mdx`](../app-flow/horizon-closing-line.mdx): Current.
- [x] The line in the wireframes, with their Archify pairs:
  [`../app-flow/living-horizon.mdx`](../app-flow/living-horizon.mdx),
  [`../app-flow/solar-system.mdx`](../app-flow/solar-system.mdx),
  [`../app-flow/docs-sidebars.mdx`](../app-flow/docs-sidebars.mdx); and the table in
  [`../app-flow/universe-theme.mdx`](../app-flow/universe-theme.mdx), with the footer as a way
  into the Verse.
- [x] `DESIGN.md`: the Horizon footer and the zoom in Motion.
- [x] ADR-0017's "Superseded by" line, and [`./index.mdx`](./index.mdx): index row and status.


# ADR-0034 — The proxy answers unknown paths with a true 404 (/docs/maintain/adr/ADR-0034-the-proxy-answers-unknown-paths-with-a-true-404)

- **Status:** Approved
- **Date:** 2026-11-03
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-03
- **Supersedes:** [ADR-0015](./ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx)
  (in part: its implementation's "the proxy acts only on catalogued paths")
- **Superseded by:** —
- **Design documents:** [`../app-flow/unknown-paths.mdx`](../app-flow/unknown-paths.mdx),
  [`../api/content-routes.mdx`](../api/content-routes.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx)

## Context [#context]

- Every path that is not a site route reaches `src/app/(site)/(docs)/[...slug]/page.tsx`, which
  calls `notFound()` when it has no such page.
- That call comes too late for a path `generateStaticParams` did not list. Measured on
  `bunx next build`, for a path not requested before:

  | Request | Status | HTML |
  |---|---|---|
  | First `/no-such-page` | 200 | Blank: `<html id="__next_error__">`, no page content |
  | The same path again | 404 | Blank, the same shell |
  | First `/x/y/z`, `/docs/nothing-here` | 200 | Blank, the same shell |

  The route's prerendered fallback shell is empty, and the page learns the path is unknown only
  when it resumes. Scripts then build the 404 in the browser, with a `noindex` tag.
- So a reader without scripts sees a blank page, which contradicts the 404's documented state
  (*Back to the system* still works). Monitoring counts these as successes, some crawlers report
  soft 404s, and in Chrome the first hit's tab showed no title although the title is in the HTML.
- The installed Next.js documents this. A streamed page keeps its 200, and for a 404 "you can
  check the slug in Proxy, then rewrite it to a not-found route or return a 404 response"
  (`file-conventions/loading.md`, *Status codes*).
- `dynamicParams = false`, which would refuse unlisted paths, is not available with Cache
  Components (ADR-0016; `route-segment-config/dynamicParams.md`).
- The proxy has no `matcher`, so it runs on every request, including `_next` and files. It already
  answers line redirects and Markdown, but only for catalogued slugs, and it knows only `meta.json`
  files: `src/lib/catalog-routes.ts` keeps compiled pages out of its bundle.
- `fumadocs-mdx/macro` has an `async` mode (`docs: { async: true }`): frontmatter is imported at
  once and the compiled body only when asked for (`transform-*.js`, `only: "frontmatter"`).

## Decision [#decision]

1. **The proxy answers every unknown path with a true 404, before any page renders.** The status
   is 404 from the first request and the response is the whole out-of-orbit page, the existing
   `src/app/not-found.tsx`, in the HTML. The address does not change, and the page still shows no
   part of it.
2. **What it judges.** Only paths `[...slug]` would otherwise render. These pass through untouched:
   `/`, `/_next/…`, the site's own routes (`api`, `diagrams`, `llms-full.txt`, `llms.mdx`,
   `llms.txt`, `og`, `static.json`), `icon.svg` and any file in `public/`.
3. **What it knows.** Every page's URL, and each `/<slug>/use` and line root that redirects to a
   first page (ADR-0015 decision 1). Comparison is exact, so `/DOCS` is unknown.
4. **The existing order stays.** Line redirects and Markdown come first, so a retired line still
   redirects and `/<unknown>.md` still gets its own 404 from the Markdown route.
5. **The list comes from the content, and the build checks it.** `catalog-routes.ts` lists the
   pages' paths through an `async` collection, so no compiled page runs in the proxy, and works out
   each URL with the same line segments as `source.ts`. **The build fails if this list and
   `source.getPages()` differ**, because a page wrongly refused would be a real page gone.
6. **`notFound()` in the page stays**, as the safety net for anything that reaches it.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| Check every path in the proxy | True 404 with full HTML everywhere; what Next.js documents | The proxy must know the pages; a wrong list would hide a real page, so it needs a build check | Chosen (owner) |
| Check only the first segment | Uses data the proxy already has | `/docs/nothing-here` stays a blank 200 | Rejected (owner) |
| Leave it | No work; `noindex` already keeps these out of search | Blank without scripts, 200 in monitoring | Rejected (owner) |
| `dynamicParams = false` | One line, no list | Not available with Cache Components | Not possible |
| Generate the list in a script, or in `next.config.mjs` | No macro involved | A new build step, and it can go stale in development | Rejected |
| Read `content/` from the proxy at request time | Always current | Slow, and the content need not be on the server | Rejected |
| Fetch from a route in the proxy | Reuses `source` | A request per request; Next.js advises against it | Rejected |

## Consequences [#consequences]

**Positive**

- Unknown paths are true 404s for readers, tools and monitoring, and readable without scripts.
- The 404's documented degraded state becomes true.

**Negative / accepted trade-offs**

- The proxy gains a second view of the pages. The build check is what makes that safe.
- It runs one set lookup on each request it judges.
- The `async` collection adds lazily loaded chunks to the proxy's bundle. They are not run, but
  their size is unmeasured until this is built.
- A new top-level route must be added to the proxy's pass-through list, or it would answer 404. A
  test compares that list with `src/app/`.

## Content invariants [#content-invariants]

§6.5 is kept: Markdown routes are not changed. No content is added or exposed. The URL list holds
only pages that are already published.

## Security considerations [#security-considerations]

Low. The request's path is only compared with a fixed set, and it is never echoed, so the page
still shows no part of it. Nothing leaves the system and no secret is touched. The proxy's bundle
holds the same public URLs as `llms.txt`. An unknown path now gets a cached static page, which
costs less than a render. The threat model is checked on implementation.

## Implementation notes [#implementation-notes]

- [x] First, verified with a spike on `bunx next build`: a proxy rewrite to `/_not-found` with
  status 404 serves the whole page on the first request, for document and `_rsc` requests alike.
  The ADR's other route was not needed.
- [x] Measured the proxy's traced chunks: 512 KB before; 2.9 MB with a plain `async` collection,
  because it compiles a lazy chunk with the text of every page, which the proxy never loads. That
  was out of proportion, so the collection in `catalog-routes.ts` compiles each body empty, with a
  one-line remark plugin of its own. The result is 585 KB, with no page text in any proxy chunk,
  and the site's own collection keeps its bodies. The chunk loaded at start grows by about 20 KB,
  the frontmatter. A request took 1.5ms at the median through the proxy.
- [x] `src/lib/known-paths.ts`: the site routes, `knownPaths` and `knownPathProblems`, without the
  macro so they can be tested. `src/lib/catalog-routes.ts`: the collection, `isKnownPath` and
  `assertKnownPaths`. `src/proxy.ts`: the check, after the existing steps.
- [x] `lineSlugs` in `src/lib/catalog-plugin.ts`, used by `source.ts` and `known-paths.ts`, so both
  work out a line's URL the same way.
- [x] The build check of decision 5: `checkKnownPaths` in `src/lib/catalog.ts`, called from the
  page's `generateStaticParams`, comparing the list with `source.getPages()` and the catalogue's
  landings. Dropping one page from the list fails `bunx next build` and names that page.
- [x] Tests (ADR-0007), in `src/lib/known-paths.test.ts`: known pages, landings, line segments,
  unknown paths at each depth, the wrong case and trailing slashes; each pass-through; the
  pass-through list against `src/app/` and `public/`; the check failing on each kind of difference.
  Checked with `curl` against `bunx next build`:
  - the Context table's paths give 404 with the page in the HTML on the first request, and no part
    of the path in it;
  - the 93 pages in `llms.txt` and in `static.json` give 200;
  - the site's routes and files are unchanged, `/<entry>/<unknown>.md` still gets the Markdown
    route's 404, and `/docs/` still redirects to `/docs`.

  In Chrome: the tab's title on a first hit; the page with scripts off, in a frame sandboxed without
  `allow-scripts`, whole and with its links; a client-side push to an unknown path; seven real
  prefetches, all 200; *Back to the system* and an ordinary link staying client-side.

  In development, against `next dev`: a page added to `content/` answered 200 within four seconds,
  and 404 again within four seconds of being removed, so the proxy's list does not go stale there.
- [x] Found while checking:
  - A client-side link to an unknown path now loads the whole page rather than swapping it in,
    because Next.js does that for any RSC response that is not OK
    (`fetch-server-response.js`). The reader lands on the same page.
  - The 404 is served with `Cache-Control: s-maxage=31536000`, as a static page is. A shared cache
    that keeps it across a deploy would hide a page added later. No host is adopted yet; the ADR
    that adopts one must check this.
  - Decision 2 leaves everything below a site route alone, so a path such as `/api/nope` or
    `/diagrams/nope`, which only `[...slug]` matches, is still a blank 200. `/og/nope` is a 404 from
    its own route. ADR-0035 later removed `api` from the site routes, since no such route exists, so
    `/api/nope` is now a true 404; `/diagrams/nope` and `/llms.txt/x` are still blank 200s.
- [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/unknown-paths.mdx`](../app-flow/unknown-paths.mdx): Current.
- [x] [`../api/content-routes.mdx`](../api/content-routes.mdx): the 404 response.
- [x] [`../architecture/system.mdx`](../architecture/system.mdx): the routes table and what the
  proxy acts on, with the diagram's Archify pair; `content/docs/maintain/security/threat-model.mdx`.
- [x] `AGENTS.md` §1, §5 and §10. `PROJECT_AGENTS.md`: no change; a consuming repository's pages
  are listed from the content.
- [x] ADR-0015's "Superseded by" line, and [`./index.mdx`](./index.mdx): index row and status.


# ADR-0035 — Every page is ready for search and sharing (/docs/maintain/adr/ADR-0035-every-page-is-ready-for-search-and-sharing)

- **Status:** Approved
- **Date:** 2026-11-03
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-03
- **Supersedes:** —
- **Superseded by:** [ADR-0036](./ADR-0036-the-site-is-nepal-dev-verse.mdx) (decisions 1 and 10, in part: the address's value, and the owner's `Person`)
- **Design documents:** [`../app-flow/search-and-sharing.mdx`](../app-flow/search-and-sharing.mdx),
  [`../prd/search-and-sharing.mdx`](../prd/search-and-sharing.mdx),
  [`../api/crawler-routes.mdx`](../api/crawler-routes.mdx),
  [`../architecture/system.mdx`](../architecture/system.mdx)

## Context [#context]

- The owner wants proper search and sharing for every page: the home page, this site's pages and
  every package's and project's, with Open Graph and share images, and consuming projects told how
  it works.
- What the site has today, read from the code and from a page's HTML:

  | Concern | Today |
  |---|---|
  | The site's address | Unknown: no `metadataBase`, so `og:image` reads `http://localhost:3000/…` |
  | Canonical links | None |
  | `robots.txt`, `sitemap.xml`, web manifest | None |
  | Structured data | None |
  | Page title | The page's own title only, with no entry or site: `Architecture Decision Records` |
  | Description | 92 pages have none, out of the 93 before this ADR's documents; `description` is optional in `pageSchema` |
  | Share image | Fumadocs' default on every page: a pink rule on black, nothing of the site's look. The home page has none |
  | Markdown copies, `llms.txt`, `static.json`, diagram frames | Open to indexing, so they can compete with the pages they copy |
  | Version lines | Nothing stops an older line outranking the latest |

- No host or domain is adopted (`architecture/system.mdx`). The owner has chosen the address
  `https://docs.puncoz.com`, read from an environment variable at build.
- What the installed versions provide, read from their docs and source:
  - Next.js has `metadataBase`, `alternates`, `title.template`, `robots.ts`, `sitemap.ts`,
    `manifest.ts` and generated `apple-icon`; JSON-LD is a `<script>` in the page, with `<` escaped
    (`guides/json-ld.md`).
  - `next/og`'s `ImageResponse` draws an image from JSX with no new dependency: flexbox only, `ttf`,
    `otf` or `woff` fonts only, and a 500 KB bundle limit (`functions/image-response.md`).
  - `fumadocs-mdx` has `lastModified`, from `git log`. A shallow clone would give every page the
    date of the last commit.
- Everything here is a public surface. Search rules are not access control (§6.1).

## Decision [#decision]

### The address [#the-address]

1. **`SITE_URL` holds the site's address**, read at build: `https://docs.puncoz.com`, set in
   `.env.local` and on the host, and named without a value in `.env.example`. It is not secret and
   not `NEXT_PUBLIC_`, because only the server reads it. It must be an `https` origin with no path,
   or the build fails.
2. **With no `SITE_URL` there is no public address, so nothing is indexed.** Every page says
   `noindex`, `robots.txt` disallows everything and the sitemap is empty, so a preview or a local
   build can never be indexed by accident. **`bun run build` refuses to publish without it**, naming
   the variable, so production cannot lose its indexing silently.

### What search engines are told [#what-search-engines-are-told]

3. **Each page's rule comes from where it sits**, in one tested function. No page sets its own.

   | The page | Indexed | Canonical link | In the sitemap |
   |---|---|---|---|
   | The home page, an overview, a page with no lines | Yes | Itself | Yes |
   | A page in the `latest` line | Yes | Itself | Yes |
   | A page in Maintain | Yes | Itself | Yes |
   | A page in an older line, with the same path in `latest` | Yes | **That page in `latest`** | No |
   | A page in an older line, with no such page in `latest` | Yes | Itself | Yes |
   | A page in the `dev` line | No, `noindex, follow` | None | No |
   | A page in a folder named `_templates` | No, `noindex, follow` | None | No |
   | The 404 | No, as today | None | No |

   An unreleased package's Use pages are therefore out of search until its first release; its
   overview and Maintain are in.
4. **`robots.txt` allows everyone, AI crawlers included**, and names the sitemap. The site already
   offers itself to tools through `llms.txt`, and only public pages are here (§6.1).
5. **`sitemap.xml` lists the pages table 3 marks**, with `lastmod` from git. It has no `changefreq`
   or `priority`, because nothing in the content could set them honestly. Redirecting addresses are
   not in it.
6. **Machine-readable copies stay readable but out of results.** `/llms.mdx/…` (so also `/<page>.md`
   and Markdown negotiation), `/llms.txt`, `/llms-full.txt`, `/static.json`, `/diagrams/…` and
   `/api/search` answer with `X-Robots-Tag: noindex`, and `robots.txt` does not block them.

### What every page says [#what-every-page-says]

7. **Titles name the page, its entry and the site**, built in one tested function:

   | The page | Title |
   |---|---|
   | Home | `Puncoz Verse — every package and project, documented to the version` (as today, ADR-0028) |
   | Overview | `lodestar — Puncoz Verse` |
   | Latest line, no lines, Maintain | `Install — lodestar — Puncoz Verse` |
   | Older line | `Install — lodestar 2.x LTS — Puncoz Verse` |
   | `dev` line | `Install — lodestar dev — Puncoz Verse` |
   | 404 | `Page not found — Puncoz Verse` (as today) |

8. **`description` is required on every page.** The build fails and names any page without one, in
   every entry. Written for a person reading a search result: one or two plain sentences, about 160
   characters at most, saying what the page is for. This work writes the 92 missing ones; on an
   approved ADR it changes only the frontmatter, never a Decision section. The templates carry a
   placeholder.
9. **Every page's head carries**, from the content: its description; `alternates` for its canonical
   link and its Markdown (`text/markdown`); `robots` as table 3, with `max-image-preview:large` on
   indexed pages; Open Graph `title`, `description`, `url`, `site_name`, `locale`, `type` (`website`
   on the home page and overviews, `article` elsewhere, with `article:modified_time` and
   `article:author`) and its image with `width`, `height`, `type` and `alt`; a Twitter
   `summary_large_image` card; `authors`, `creator` and `publisher`, the owner; and `theme-color`
   for each theme. No `twitter:site`, because no handle is known, and no `keywords`.
10. **Structured data, as JSON-LD with `<` escaped:** on the home page `WebSite` and the owner's
    `Person` (`sameAs` their GitHub profile), with no `SearchAction`, because search is a dialog with
    no results address; on a docs page `TechArticle` and `BreadcrumbList`, in plain names (entry,
    Use or Maintain, folders, page), not space words; on an overview also `SoftwareSourceCode`, with
    the entry's repository and latest version. A page whose canonical link is another page, and a
    `noindex` page, carry none. The invented private projects are never in it.

### Share images and icons [#share-images-and-icons]

11. **Every page has its own designed share image, at 1200 by 630, and so does the home page**, drawn
    by the site with `next/og` in place of Fumadocs' default, and made at build:
    - in the dark theme's colours on the still star field, seeded from the page's address so each
      image's sky is its own and stays the same;
    - the Verse mark and *Puncoz Verse* (ADR-0028, ADR-0029);
    - a docs page: the entry's planet mark, its name, the track and the line with its moon; then the
      page's title and description; then the domain from `SITE_URL`;
    - the home page: the system, drawn still, with one planet per entry, and its line; at
      `/og/image.png`;
    - a long title is set smaller rather than cut, and a description is shortened at a word boundary.
12. **The images use the site's fonts**, Bricolage Grotesque and Onest, fetched as `ttf` from Google
    Fonts at build, the source `next/font` already uses. A failed fetch fails the build. No font file
    is committed.
13. **Icons:** `src/app/icon.svg` stays; `src/app/apple-icon.tsx` draws the Verse mark at build, so
    no binary is committed (§8); `src/app/manifest.ts` gives the name, short name, description,
    theme colours and those icons. No `favicon.ico`: it would be a committed binary, and `/favicon.ico`
    answers 404.

### Out of scope [#out-of-scope]

14. Analytics, RSS, `hreflang` and a search-console verification tag. Verifying the domain is by DNS,
    which is the owner's step after deployment. A frontmatter field to switch a page's indexing is
    also left out: it would look like a way to keep something private, and it is not.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| Address: `SITE_URL` at build, `docs.puncoz.com` | The domain can move with no code change; previews stay unindexed | One more variable to set | Chosen (owner) |
| Address: fixed in `shared.ts` | No variable | A preview would be crawlable; moving means a code change | Rejected (owner) |
| Versions: latest wins, nothing vanishes | Readers land on current docs, and a page only in an older line stays findable | A search for an old version usually reaches latest first | Chosen (owner) |
| Versions: only latest indexed | The simplest rule | A page only in an older line can't be found | Rejected (owner) |
| Versions: every line indexed | A search for an old version lands on it | An old version can outrank the current one | Rejected (owner) |
| Maintain: indexed, except templates | ADRs and architecture can be found | A maintainer page can appear above a user page | Chosen (owner) |
| Maintain: not indexed | Search shows only user docs | One indexable page today; maintainer docs can't be found | Rejected (owner) |
| Descriptions: required, the build fails | Every result and card has written words | One more line per page, and a project missing them can't build the site | Chosen (owner) |
| Descriptions: optional, from the first paragraph | No writing | Weak snippets; an ADR's first paragraph is its status lines | Rejected (owner) |
| Images: the site's own with `next/og` | On brand, no dependency | A component to keep; flexbox only | Proposed |
| Images: Fumadocs' `generateOGImage` with new colours | Least code | Its layout has no entry, version or sky | Rejected |
| Fonts: fetched at build | The site's own type, nothing committed | The build needs the network, as `next/font` already does | Proposed |
| Fonts: committed `ttf` files | Works offline | Committed binaries, up to the 500 KB limit | Rejected |
| Fonts: `next/og`'s default | No fetch | Not the site's type | Rejected |
| Robots: block AI crawlers | Keeps pages out of training sets | Contradicts `llms.txt`; only public pages are here | Rejected |
| `lastmod`: from git | True on a full clone, no field to maintain | A shallow clone dates everything to the last commit | Proposed; the hosting ADR must clone in full |
| `lastmod`: none | Nothing can be wrong | Crawlers get no signal of change | Rejected |

## Consequences [#consequences]

**Positive**

- Every page, in every entry, gets all of this from its folder and frontmatter, with nothing per page
  beyond a description.
- A shared link looks like this site, and a tab, a bookmark or a result names the page and its entry.
- A preview cannot be indexed unless it sets `SITE_URL`.

**Negative / accepted trade-offs**

- A consuming project's build fails until each of its pages has a description.
- A preview that does set `SITE_URL` is crawlable, with its canonical links pointing at production.
- An image per page and the fonts make the build slower, and the build needs the network.
- The 404 is served with a one-year `s-maxage` (ADR-0034), which is unchanged here.
- Search engines decide what they do. Canonical links and sitemaps are hints, and no ranking is
  promised.
- Nothing is reachable until a host serves `docs.puncoz.com`; this ADR adopts no host.

## Content invariants [#content-invariants]

§6.1 is kept and its list grows: `sitemap.xml`, `robots.txt`, JSON-LD and share images become public
surfaces, built only from pages already published. §6.5 is kept: `noindex` on a Markdown copy does not
stop anyone reading it. §6.3 is kept: an older line's page says its version in its title too.

## Security considerations [#security-considerations]

- **`SITE_URL`:** public and not a secret; recorded in `security/secrets.mdx` and `.env.example`.
- **JSON-LD:** titles and descriptions go into a `<script>`, so `<` is escaped, as the Next.js guide
  says. They come from the repository, not from a reader.
- **New third party at build:** Google Fonts, for font files. It is sent no content, and the page's
  words are not in the request. Recorded as a DFD boundary crossing.
- **`noindex` is not privacy:** a `noindex` page is still published and readable. The documents and
  `PROJECT_AGENTS.md` say so. §6.1 still keeps private content out of `content/`.
- **New routes:** `robots.txt`, `sitemap.xml`, the manifest, the Apple icon and the home image expose
  only public data, take no input and are prerendered. Documented in `api/crawler-routes.mdx`.

## Implementation notes [#implementation-notes]

- [x] `src/lib/seo.ts`, pure and tested: the address's validation, the rule of table 3, the title of
  decision 7, the description's shortening and the title's size, and the JSON-LD objects.
- [x] `src/app/layout.tsx`: `metadataBase`, the shared metadata, `theme-color`.
- [x] `src/app/(site)/(docs)/[...slug]/page.tsx`: `generateMetadata` from `seo.ts`, the JSON-LD
  script. `src/app/(home)/page.tsx`: the same for the home page.
- [x] `src/app/robots.ts`, `src/app/sitemap.ts`, `src/app/manifest.ts`, `src/app/apple-icon.tsx`;
  `lastModified: true` on the collection in `source.ts`.
- [x] `src/components/share-image.tsx` and `src/app/og/[...slug]/route.tsx`: the two images, including
  `/og/image.png`. Before relying on decision 12, verify a font can be fetched as `ttf` and stays
  within the bundle limit, and if not, **stop and ask**.
- [x] `X-Robots-Tag` on the routes of decision 6, checked on a prerendered response and through the
  proxy's rewrite.
- [x] `src/lib/source.ts`: a schema that requires `description`, with the page named in the failure.
  The 92 descriptions, each read from its page, and the templates' placeholders.
- [x] `src/lib/known-paths.ts` (ADR-0034): the new top-level routes in the pass-through list, with the
  test mapping `robots.ts` to `robots.txt` and so on.
- [x] `scripts/sync-content.ts`: refuse without `SITE_URL`. `.env.example`.
- [x] Tests (ADR-0007): every row of tables 3 and 7, including an older page with and without a
  counterpart and a project with no lines; `SITE_URL` unset, invalid and with a path; the sitemap's
  contents; the escaped JSON-LD; the description check; the shortening and sizes on long titles.
  With `curl` against `bunx next build`, with and without `SITE_URL` (given on the command line, never
  by reading `.env.local`): the head of each kind of page, `robots.txt`, `sitemap.xml`, the headers of
  decision 6. Looked at: the images for the home page, an overview, a long ADR title and a package
  with a line, the last from a temporary folder removed afterwards.
- [x] `bun run test`, `bun run types:check` and `bunx next build` pass; `bun run lint` is reported
  while it stays blocked.

What the implementation found, with the Decision above left as approved:

- **Fonts (decision 12):** Google Fonts answers with `ttf` to a legacy user agent. Each file is 82 to
  90 KB, well inside the 500 KB limit, so there was no need to stop and ask. `use cache` keeps the
  routes prerendered.
- **`/api/search` (decision 6) does not exist.** `src/app/api/search` and `src/app/api` were empty,
  untracked folders, left over and now removed, so no header was added. `api` also left the site routes,
  so `/api/search` and `/api/nope` are now true 404s. The old route-list test would have failed on a
  fresh clone, where those empty folders don't exist.
- **The description check** is `checkDescriptions` in `catalog-plugin.ts`, not the schema the note above
  names: the check names every undescribed page in one failure, where a schema stops at the first.
  Confirmed with a temporary page: `Description check failed (ADR-0035)` naming the file, exit 1.
- **Descriptions show on the page.** Fumadocs prints a page's description under its title, so the 92
  are visible there too. The app flow says so.
- **`apple-icon` joined the reserved slugs**, because a folder of that name would have been shadowed by
  the new route.
- **The home image's first draft** had its orbits across the headline. They now share one span, clear of
  the text at any number of rings, with a test.
- **With `SITE_URL` set and a temporary package with all three kinds of line:** every row of tables 3
  and 7 as decided, 90 URLs in the sitemap, 81 with `lastmod`. The other nine pages were uncommitted, and
  so have no date yet. **With no `SITE_URL`:** `noindex` on every page, `Disallow: /`, an empty sitemap,
  no domain on the images, and `og:image` on `http://localhost:3000`, Next.js's fallback, as the app flow's
  degraded state says.
- **Not fixed here:** `/diagrams/nope` and `/llms.txt/x` are still blank 200s, as ADR-0034 records. No
  real host has been tested, so nothing has been seen in a search engine or a real sharing app's card.

**For the owner after approval:** add `SITE_URL=https://docs.puncoz.com` to `.env.local`, which agents
do not read or change, and to the host when one is adopted.

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

- [x] `PROJECT_AGENTS.md`: the required description and how to write one (§7, §13); what search engines
  are told for each kind of page, and that it is automatic (§4, §5); `noindex` is not privacy (§2); the
  share image; the new build check (§9); the paste block.
- [x] `AGENTS.md`: §1, §5, §6.1's list of surfaces, §8's *Format of a page* (`description` required),
  §9's checks, §10's map. `README.md`.
- [x] [`../app-flow/search-and-sharing.mdx`](../app-flow/search-and-sharing.mdx),
  [`../prd/search-and-sharing.mdx`](../prd/search-and-sharing.mdx) and
  [`../api/crawler-routes.mdx`](../api/crawler-routes.mdx): Current.
- [x] [`../architecture/system.mdx`](../architecture/system.mdx), `../dfd/system.mdx`,
  `../security/secrets.mdx`, `../security/threat-model.mdx`, `../security/checklist.mdx` (the hosting
  ADR must clone in full and check the 404's cache), `../_templates/` (a `description` in each).
- [x] `DESIGN.md`: the share images. [`./index.mdx`](./index.mdx): index row and status.


# ADR-0036 — The site is Nepal Dev Verse, part of nepal-dev.com (/docs/maintain/adr/ADR-0036-the-site-is-nepal-dev-verse)

- **Status:** Approved
- **Date:** 2026-11-03
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-03
- **Supersedes:** [ADR-0028](./ADR-0028-the-site-is-named-puncoz-verse.mdx) decisions 1 and 2;
  [ADR-0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) decision 1 (in part: who the star is, and
  its label); [ADR-0029](./ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx) decision 2 (in part:
  the brand mark); [ADR-0033](./ADR-0033-the-footer-says-you-have-reached-the-horizon.mdx) decision 3 (the
  credit's words); [ADR-0035](./ADR-0035-every-page-is-ready-for-search-and-sharing.mdx) decisions 1 and 10
  (in part: the address's value, and the owner's `Person`)
- **Superseded by:** —
- **Design documents:** [`../app-flow/community-identity.mdx`](../app-flow/community-identity.mdx),
  `PRODUCT.md`, `DESIGN.md`

## Context [#context]

- The owner wants to publish this site as a documentation platform for the packages and projects of
  Nepalese developers all over the world, under the name **Nepal Dev Verse**, and has supplied the
  nepal-dev.com logo in `temp/logo.svg`. They asked for references to Puncoz Nepal to become
  nepal-dev.com, with a footer credit to nepal-dev.com and "made with ❤️ by Puncoz Nepal".
- The name appears through `appName` in `src/lib/shared.ts`. The maker appears through `owner` in the
  same file: the star's label, the footer's credit, the page metadata and the JSON-LD.
- What was measured of the logo:
  - It is 1.6 MB of SVG, 551 paths, 1395 by 1127: a mountain range with circuit traces, Nepal's flag on
    the summit and the wordmark *nepal-dev.com*.
  - On the site's dark ground (`#0a0c10`, the default theme) the navy *nepal* and *.com*, the cursor
    and the mountains' outline nearly vanish.
  - At 48px the wordmark cannot be read; at 16px the artwork is a smudge.
- Nepal's flag holds a moon above a sun. The site's sidebar already uses a sun for Use and a moon for
  Maintain, and its version lines are moons (ADR-0017), so the flag sits well in this site's own language.
  [ADR-0037](./ADR-0037-the-horizon-is-the-himalaya.mdx) builds on that.
- Today the content is this site's own documentation only, and only the owner reviews and commits what
  reaches `content/` (ADR-0010).

## Decision [#decision]

### The name [#the-name]

1. **The site is Nepal Dev Verse.** `appName` becomes *Nepal Dev Verse*, wherever it reaches today: the
   wordmark, titles, share images, the manifest, and the heading of `llms.txt` and `llms-full.txt`.
2. **This site's own docs are Nepal Dev Verse Docs.** The project with the slug `docs` takes that title in
   its `meta.json` and overview. The slug and every URL stay: `/docs`, `/docs/maintain/…`.

### What it says it is [#what-it-says-it-is]

3. **The home line reads: "Every package and project by Nepalese developers all over the world,
   documented to the version."** It is the hero's heading, with *documented to the version.* as its
   emphasis, the home share image's headline, set smaller to fit, and the manifest's description.
4. **The home page's title is `Nepal Dev Verse — packages and projects by Nepalese developers`.** The
   full line is too long for a search result.
5. **The star is nepal-dev.com.** ADR-0017's metaphor stands, with the community in the maker's place: the
   star on the home page is labelled *nepal-dev.com*, and the Verse view's plain sentence names it.

### The logo [#the-logo]

6. **The original is kept, unchanged, at `assets/nepal-dev-logo.svg`,** as the master. It is not served and
   not published. The owner removes `temp/`.
7. **A small summit-and-flag mark is redrawn from it** for everywhere the site shows a brand: about 2 KB
   of inline SVG in `src/components/brand-mark.tsx`, with a central peak, two shoulders, the snow, the
   logo's red face and one teal trace, all flying the flag.
   - **The flag keeps its own colours in both themes, and is never restyled.** Its shape, the moon above
     the sun, comes from the logo.
   - **The rock follows the theme:** the logo's navy on the light ground, a lifted blue from the logo's
     palette on the dark one, with at least 3:1 against the ground.
   - **It stands in** the site header, `src/app/icon.svg`, `src/app/apple-icon.tsx`, the share images and
     the footer's credit. At 16px the trace is left out and the flag simplified, so the favicon stays readable.
8. **The Verse mark stays as a place, not a brand:** only in the scale strip, for the Verse level.

### The credit and the references [#the-credit-and-the-references]

9. **The footer's credit reads: "Part of nepal-dev.com. Made with ❤️ by Puncoz Nepal."**, with the mark
   before it. *nepal-dev.com* links to `https://nepal-dev.com` and *Puncoz Nepal* to `https://puncoz.com`.
10. **Page metadata and JSON-LD name nepal-dev.com:** `authors`, `creator` and `publisher`, `article:author`,
    and an `Organization` with its URL in place of the owner's `Person`, with no `sameAs` because no
    profile is known. Per-entry authors wait for the contribution ADR (decision 13).
11. **The public address is `https://docs.nepal-dev.com`,** still from `SITE_URL`; ADR-0035's rules for it
    are unchanged. The owner adds the DNS record and sets the variable.

### What stays [#what-stays]

12. **Puncoz Nepal stays** in the footer's credit, as `@puncoz` in ADRs (ADR-0020), and as *the owner* in
    the working documents. Approved ADRs keep the names they were written with. The repository and package
    names, the GitHub link (`puncoz-official/docs`), the Algolia index and the environment variables are
    identifiers and do not change here.
13. **This is the identity, not the platform's workings.** How other developers contribute, who reviews
    them, and showing who built each entry all wait for their own ADR. Until then ADR-0010 stands and the
    owner remains the only reviewer. The private projects beyond the belt stay as they are, invented, by
    the owner's choice.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Logo | A simple mark from the logo; the Verse mark keeps its place | Readable at 16px, about 2 KB, in the site's themes | Two marks to keep apart | Chosen (owner) |
| Logo | The same, with the Verse mark retired | One mark | The top of the scale strip loses a symbol that fits the space theme | Rejected (owner) |
| Logo | The full logo, recoloured, as a file | The most faithful | Unreadable at header size, no favicon, about 1.6 MB per theme | Rejected (owner) |
| Logo | Keep the Verse mark as the brand, the logo in the credit only | The smallest change | The site barely looks like nepal-dev.com | Rejected (owner) |
| Address | `docs.nepal-dev.com` | Says what it is, on the community's domain | The owner adds DNS | Chosen (owner) |
| Address | `verse.nepal-dev.com` | Matches the name | Says less on its own | Rejected (owner) |
| Address | Keep `docs.puncoz.com` | No change | A community platform on a personal domain, with redirects to come later | Rejected (owner) |
| Scope | Identity now, and the belt stays | A small visual change; the contribution model gets its own review | Invented private projects under a community name | Chosen (owner) |
| Scope | Identity now, and the belt removed | No invented names on a community site | One more change here | Rejected (owner) |
| Scope | Identity and the contribution model together | One review | A far larger review, and the rename waits | Rejected (owner) |
| Home line | "…by Nepalese developers all over the world, documented to the version." | The owner's words; says whose work it is | Long: more lines on phones, and a smaller headline on the share image | Chosen (owner) |
| Home line | Unchanged | Short | Nothing says who it is for | Rejected (owner) |
| Theme with the rename | Separate ADRs, this one and ADR-0037 | Each is reviewed on its own, as ADR-0028 chose | Two to read | Chosen |

## Consequences [#consequences]

**Positive**

- The site says what it is for, and looks like part of nepal-dev.com, on every page and every shared link.
- The next step, inviting other developers, starts from a name and an identity that already fit.

**Negative / accepted trade-offs**

- **The words go ahead of the content:** the home page says "by Nepalese developers" while one project,
  this site, is documented. It also shows invented private projects under that name.
- The long home line takes more of the first screen, most of all on phones. It is measured at 320px and
  390px during implementation.
- The original logo adds 1.6 MB to the repository, and so to every consuming submodule's checkout.
- The repository and GitHub names keep *puncoz* until the owner renames them.
- The full logo appears nowhere on the site itself; only the mark drawn from it does.
- Nothing has been said here about whether `https://nepal-dev.com` is live. The owner confirms it before
  publishing, because the credit links there.

## Content invariants [#content-invariants]

None is departed from. §6.1 stands: nothing private goes into `content/`, and the belt's names stay
invented. No page moves, so §6.5's Markdown surfaces keep working; they take the new name. The search index
takes it on the next publish, which only the owner runs.

## Security considerations [#security-considerations]

- **No new endpoint, secret or third party.** `SITE_URL` changes value, not handling, and stays public.
- **Two external links** in the credit, both fixed, with `rel="noreferrer noopener"`.
- **The logo master** is not served, so it adds no surface. It was read before use: paths and masks only, with
  no script, external reference or embedded raster image. The mark is hand-drawn and inline.
- **A community name raises the stakes of §6.1.** The invented private projects could be read as real
  community projects; `private-projects.ts`'s rule stands, and the contribution ADR must revisit it.

## Implementation notes [#implementation-notes]

- [x] `src/lib/shared.ts`: `appName`; `owner` split into `community` and `maker`, with no other change in
  who reads what except as decisions 9 and 10 say.
- [x] `assets/nepal-dev-logo.svg`, byte for byte (decision 6). `temp/` is left for the owner.
- [x] `src/components/brand-mark.tsx`, with its tokens; `src/app/icon.svg`, `src/app/apple-icon.tsx`,
  `src/components/site-header.tsx`, `src/components/share-image.tsx`. `verse-mark.tsx` stays for
  `scale-strip.tsx`.
- [x] `src/app/(home)/page.tsx`, `src/components/share-image.tsx`, `src/app/manifest.ts`: the home line and
  title. `src/components/home/hero.tsx` and `orbit-map.tsx`: the star's label and sentence.
- [x] `src/components/horizon-footer.tsx`: the credit. `src/lib/seo.ts`, `src/app/layout.tsx`: decision 10.
- [x] `content/docs/meta.json`, `content/docs/index.mdx`: the title and prose. `.env.example`: unchanged.
- [x] Tests (ADR-0007): the name and the project's title; no *Puncoz Verse* left in `src/`, `content/` outside
  approved ADRs, or the living documents; the credit's words and two links; the mark's contrast in both themes
  and its small form; the `Organization`; the share image's headline staying clear of the system.
- [x] Looked at, in Chrome on localhost against `bunx next build`: the header at 320px, 390px and wide; the
  hero's line in both themes; the favicon at 16px; the share images; the footer's credit; `llms.txt`.
- [x] `bun run test`, `bun run types:check` and `bunx next build` pass; `bun run lint` is reported while it
  stays blocked.

What the build added or changed from the above, and what was measured:

- `src/components/brand-mark.tsx` redraws the flag by hand to the logo's proportions rather than using its paths: the logo
  is 1.6 MB and 551 paths, with no script, external resource or raster, and its flag alone is 83 auto-traced paths.
  `src/lib/flag.ts` and `src/components/nepal-flag.tsx` hold the flag, shared with ADR-0037's Horizon.
- The hero's line takes `max-width: 19ch` and a smaller minimum, `clamp(1.85rem, 1.5rem + 2.1vw, 3.4rem)`: six lines at
  320px, five at 390px, three at 860px, four on a wide screen, with no sideways scroll. The share image's headline is 54px.
- In Chrome the longer project name crossed the empty orbits' names on a phone, so `orbit-map.tsx` draws a planet's name
  with a halo in the ground colour. With many planets on a phone the names still crowd each other as they turn; that is
  ADR-0032's system at that width and was not changed here.
- `src/lib/site-name.test.ts` allows one exception to the old names, a row quoting ADR-0028's approved title.
- `README.md`'s list of decisions stopped at ADR-0028, so ADR-0029 to ADR-0037 were added to it.

**For the owner after approval:** set `SITE_URL=https://docs.nepal-dev.com` in `.env.local` and on the host, add
the DNS record, confirm `https://nepal-dev.com` is live, and remove `temp/`.

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

- [x] [`../app-flow/community-identity.mdx`](../app-flow/community-identity.mdx): Current, in place of
  `../app-flow/site-name.mdx`, which is deleted; every app flow whose wireframes show the name or
  `docs.puncoz.com`, with their Archify views.
- [x] `PRODUCT.md`, `DESIGN.md`, `.impeccable/design.json`, `AGENTS.md` §1 and §10, `README.md`,
  `PROJECT_AGENTS.md`, [`../architecture/system.mdx`](../architecture/system.mdx), and the PRDs and API pages
  that name the site.
- [x] "Superseded by" in ADR-0017, ADR-0028, ADR-0029, ADR-0033 and ADR-0035; [`./index.mdx`](./index.mdx).


# ADR-0037 — The Horizon is the Himalaya (/docs/maintain/adr/ADR-0037-the-horizon-is-the-himalaya)

- **Status:** Approved
- **Date:** 2026-11-03
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-03
- **Supersedes:** [ADR-0030](./ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx) decision 2
  (in part: the aurora and rim, the clouds' place, the star's place and the observatory's place) and decision 4
  (in part: the light theme's scene)
- **Superseded by:** —
- **Design documents:** [`../app-flow/himalayan-horizon.mdx`](../app-flow/himalayan-horizon.mdx), `DESIGN.md`

## Context [#context]

- The owner asked to see what the logo's mountains and flag could do in the Horizon, creatively. It depends
  on [ADR-0036](./ADR-0036-the-site-is-nepal-dev-verse.mdx), and can be approved or refused without touching it.
- Every page ends with the Horizon (ADR-0030): stars, an aurora on the rim of a bare curved planet, shooting
  stars, the star rising with the scroll, three cloud bands and an observatory. The closing line above it says
  *You've reached the horizon* (ADR-0033). Nothing in it is about Nepal.
- Three things in the logo and the flag already fit this site's language:
  - **The flag holds a moon above a sun.** The sidebar's Use is a sun and Maintain a moon, and each version line
    is a moon. The site's own marks are on the flag.
  - **The logo's red face reads as light.** Red on a peak's sunward side is what alpenglow looks like.
  - **The logo's circuit traces end in ringed nodes,** much like this site's planet marks.
- What the code does now, read from `horizon-sky.ts` and `site.css`: the scene is 170 to 260px tall, in layers on one
  1200 by 260 view with `xMidYMax slice`. At a very wide screen that crops the top of the view, and at 1920px it would
  cut off a flag at the summit. So the summit and flag can't simply be added to that layer.
- A still sketch was drawn outside the repository to check that it reads, in both themes and at phone width.

## Decision [#decision]

1. **The range stands on the planet's edge.** The curve stays, and three ranges rise from it, back to front: a far one
   in haze, a middle one and a near one with the summit at the centre and two shoulders, drawn from the logo's
   silhouette. It is still a planet seen from its edge, and its highest mountains are the ones the site is named for.
2. **The peaks rise out of a sea of cloud.** The three existing cloud bands keep their timing and move between the
   ranges, so the middle range wades through them and the near one stands in front. It is the view from above the
   clouds that anyone who has flown past these mountains knows.
3. **The light comes from the star.** It rises with the scroll as it does now, just right of the summit, so everything
   lit is lit from the right.
4. **Alpenglow: the logo's red is the star's light.** As the star rises, in step with the scroll, the red on the
   sunward faces of the summit and the second peak fades in from nothing to the logo's red. Scrolling back fades it
   out. Only its opacity changes.
5. **The flag is raised when you arrive.** When 40% of the footer is in view, the flag runs up its pole from the summit
   over about 1.2 seconds, once per page view, and then waves slowly.
   - **It is not tied to the scroll, because a flag left part-way up its pole means mourning.** It is either on its way
     up or at the top.
   - It is drawn from the logo's flag, in its own colours in both themes, and is never recoloured, cropped, or placed
     under text or cloud.
6. **The sky repeats the flag.** A thin, still crescent moon stands directly above the star, in the same order as the
   flag's emblems: moon over sun. Nothing points it out, and it is there for anyone who notices.
7. **Every entry is a light on the mountain.** The logo's traces climb the near rock, one per public entry, each ending
   in a ringed light in that entry's ecosystem colour, seeded from its slug so it stays in place. The mountain lights up
   as the community documents more. Today it has one light.
   - **The planet row is still the way in.** The scene stays `aria-hidden`. Hovering or focusing an entry's link in the
     row brightens its light, through CSS only.
   - The lights use a fixed set of spots on the rock. Past that number, the rest appear only in the planet row.
   - The invented private projects get no light.
8. **The aurora and the rim glow go.** Auroras are not a Himalayan sky, and with the alpenglow, the flag and the warm
   glow they would be one colour too many. The site's teal lives on in the traces. The stars, their twinkling and the
   shooting stars stay.
9. **The observatory moves** to the near range's left shoulder, its telescope turned toward the star.
10. **Light theme: the same scene at dawn.** The sky washes warm toward the ranges, the rock is the logo's navy, and the
    far ranges are pale blue. The red and the flag do not change.
11. **The summit and the flag are never cropped, at any width.** The near range has its own layer, anchored at the bottom
    centre and scaled to fit, while the far and middle ranges run wider and fall off the edges. The scene grows to fit
    them, and its height is settled by measuring at 320px, 390px, 860px, 1412px, 1920px and 2560px.
12. **The rules of motion hold** (ADR-0030 decision 3). Only transform and opacity animate, in CSS, with no library. The
    flag's wave is a new, slow loop in the Horizon's exception to *The One Orbit Rule*, and runs only while the footer is
    on screen. Under reduced motion, with no scripts, or with no scroll-driven animations: the star stands risen, the
    alpenglow is full, and the flag stands raised and still.
13. **The sun and moon in the sidebar become the flag's.** `track-switch.tsx`'s two icons take the flag's forms: a sun
    with twelve rays and a crescent moon. It is a small change, and it ties the two sides of every planet to the flag.
14. **Unchanged:** the closing line, *You've reached the horizon. The Verse goes on.*; the dusk edge; the planet row; the
    link row; every URL and Markdown surface. No dependency is added.

## Options considered [#options-considered]

| Concern | Option | Pros | Cons | Verdict |
|---|---|---|---|---|
| Scene | The range on the planet's edge, with cloud, alpenglow, flag and lights | Joins the logo to the space theme; grows with the community | The most work; more layers to keep light | Proposed |
| Scene | Only a ridge silhouette and a flag replacing the curve | Quick | Looks like a clip-art swap; nothing means anything | Rejected |
| Scene | The full logo artwork in the footer | Faithful | Reads as a sticker; its wordmark and outline fail on the dark ground (ADR-0036) | Rejected |
| Flag | Raised once on arrival | Marks reaching the end, and never rests part-way | A small script threshold beside `HorizonAwake` | Proposed |
| Flag | Raised in step with the scroll | No script, the same as the star | Can rest at half-mast, which means mourning | Rejected |
| Flag | Standing still, always | The simplest | Misses the one moment that makes the footer memorable | Rejected |
| Community | A light per entry on the rock | The picture grows as people join | A second mark for each entry to keep in step | Proposed |
| Community | A climber or trail that moves | Playful | A second moving focus, and it would tire on every page's end | Rejected |
| Aurora | Removed | Fewer colours and two fewer blurred layers | Drops something the owner approved in ADR-0030 | Proposed |
| Aurora | Kept, dimmed | Keeps ADR-0030 whole | Not a Himalayan sky; competes with the alpenglow | Rejected |
| Prayer flags along a ridge | Left out | Avoids using a sacred object as decoration | Loses a very Himalayan image; the owner may overrule it | Rejected |
| Closing line | Unchanged | Still true, and ADR-0033 was just settled | Says nothing of the summit | Proposed |
| Closing line | "You've reached the summit. The Verse goes on." | Fits the picture | Loses the word the footer is named for | Rejected |
| Share images | Unchanged here | ADR-0035's design stands, and this stays reviewable | Shared links don't show the range | Left for a later ADR |

## Consequences [#consequences]

**Positive**

- The end of every page becomes the site's signature, and only this site could have it: the flag's own emblems in the
  sky, its colour on the snow, the community's lights on the rock.
- The footer now shows the community grow, with no copy and no counter.

**Negative / accepted trade-offs**

- **The scene gets taller**, so every page's footer takes more room.
- With one entry, the light on the mountain looks modest until more arrive.
- More drawn geometry in every page's HTML, so it is checked with the Horizon's cost in mind: the blurred aurora and rim
  layers go, and the ranges are flat fills.
- A national flag carries meaning. It is drawn exactly and treated with care (decision 5), and the owner reviews the
  drawing before it ships.
- Peaks are drawn from the logo, not from any real view, so no peak is named or claimed.

## Content invariants [#content-invariants]

None is touched. The footer is not part of any Markdown surface. §6.1: the lights come only from public catalogue entries,
which are already on the page; the invented private projects are never drawn.

## Security considerations [#security-considerations]

None beyond this: this change touches no endpoint and no secret, and reads only public catalogue fields. The scene is
static inline SVG with no user input.

## Implementation notes [#implementation-notes]

- [x] `src/lib/horizon-sky.ts`, pure and tested: the three ranges, the snow and red faces, the flag's place, the moon, and
  the lights' fixed spots and seeded assignment.
- [x] `src/components/horizon-footer.tsx`: the layers, with `entries` passed to the scene. A `src/components/horizon-flag.tsx`
  drawn from the logo's flag paths. `src/components/horizon-awake.tsx`: the arrival threshold, setting `data-summit`.
- [x] `src/app/site.css`: the scene's height, the alpenglow on `--horizon`, the flag's raise and wave, the lights through
  `:has`, both themes, reduced motion. `src/components/docs/track-switch.tsx`: the two icons.
- [x] Tests (ADR-0007): every light stands on rock and no two collide; the same slug gets the same spot; more entries than
  spots draw no extra light; no private project is drawn; the summit and flag fit at every measured width; the scene
  renders with no entries; the flag stands raised without scripts. `HorizonAwake`'s threshold and the CSS are not
  unit-tested; checked in Chrome instead.
- [x] Looked at, in Chrome on localhost against `bunx next build`: both themes at the widths of decision 11; the flag raised
  once, and on a page short enough that the footer shows at load; reduced motion; a planet link lighting its node; the dusk
  edge over the docs sidebar; a temporary folder with several entries, removed afterwards.
- [x] Departures found while building, each smaller than the decision it serves:
  - the flag lives in `src/components/nepal-flag.tsx`, shared with the brand mark, not a `horizon-flag.tsx`, and is redrawn
    by hand because the logo's flag is 83 auto-traced paths;
  - arrival is measured on 40% of `.horizon-scene`, not of the footer, because the scene's top holds the flag;
  - a page whose summit already shows at load keeps the flag raised with no animation, measured on the 404 with 45% of
    the scene in view;
  - sixteen light spots; past them an entry has no light, though its link stays in the planet row;
  - the scene is `clamp(230px, 28vw, 360px)` tall;
  - the observatory stands on a flat top added to the left shoulder at x=395, in the rock's colour, because at x=372 it hung
    over the ridge and a 320px screen cut it in half;
  - the larger red face ends in a point rather than a flat foot.
- [x] Measured in Chrome against `bunx next build`: light and dark at about 1412px; light at 320px, 390px and 860px (in same-origin
  frames, because the window would not shrink), with no sideways scroll. The window also measured 2371px wide, where the scene
  is 360px tall. 1920px and 2560px were not looked at separately. The flag lowered, then raised, on reaching the footer. A
  focused planet link lit only its own node, with eight entries from temporary folders `content/zz-temp-a` to `g`, removed
  afterwards. The dusk edge took the docs sidebar. The reduced-motion rules were read from the built CSS rather than seen.

- [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/himalayan-horizon.mdx`](../app-flow/himalayan-horizon.mdx): Current;
  [`../app-flow/living-horizon.mdx`](../app-flow/living-horizon.mdx) with its Archify views.
- [x] `DESIGN.md`: the Horizon footer, *The One Orbit Rule*, the track switch. `.impeccable/design.json`.
- [x] `AGENTS.md` §1 and §5, [`../architecture/system.mdx`](../architecture/system.mdx).
- [x] "Superseded by" in ADR-0030; [`./index.mdx`](./index.mdx).


# Architecture Decision Records (/docs/maintain/adr)

Every feature and functional change starts here
([ADR-0001](./ADR-0001-adr-driven-development-workflow.mdx)). Template:
[`../_templates/adr.mdx`](../_templates/adr.mdx).

**Next free number: 0038**

## Conventions [#conventions]

- File name: `ADR-NNNN-kebab-title.mdx`, numbered from the *next free number* above. Add the
  index row and bump the number **in the same change** that creates the file, so ADRs in flight
  cannot collide.
- Title: a short imperative statement of the decision ("Keep private project docs out of the
  public build").
- Status: `Proposed` → `Approved` (by the owner, with name and date) → optionally
  `Superseded by ADR-NNNN`. A rejected proposal is marked `Rejected` and kept.
- An approved ADR's **Decision** is never edited. Supersede it with a new ADR and cross-link
  both.
- The **Security considerations** section is mandatory
  ([ADR-0005](./ADR-0005-security-as-a-standing-practice.mdx)).

## Index [#index]

| ADR | Title | Status | Date |
|---|---|---|---|
| [0001](./ADR-0001-adr-driven-development-workflow.mdx) | Every change starts with an approved ADR | Approved | 2026-10-31 |
| [0002](./ADR-0002-living-design-documentation.mdx) | Design documents are living snapshots, published as this site's Maintain track | Approved | 2026-10-31 |
| [0003](./ADR-0003-code-comment-policy.mdx) | Comments explain why; every branch takes a block | Approved | 2026-10-31 |
| [0004](./ADR-0004-ask-never-guess.mdx) | Resolve ambiguity by asking, never by guessing | Approved | 2026-10-31 |
| [0005](./ADR-0005-security-as-a-standing-practice.mdx) | Security and privacy are a standing practice | Approved | 2026-10-31 |
| [0006](./ADR-0006-agent-skills-are-advisory.mdx) | Agent skills are advisory; this repository's documentation is binding | Approved | 2026-10-31 |
| [0007](./ADR-0007-tests-are-part-of-every-change.mdx) | Tests are part of every change | Approved | 2026-10-31 |
| [0008](./ADR-0008-a-ui-change-ships-an-app-flow.mdx) | A UI change ships an app flow, drawn in Mermaid | Approved | 2026-10-31 |
| [0009](./ADR-0009-trusted-agent-skills-are-vendored.mdx) | Trusted agent skills are vendored in `.claude/agent-skills/`, routed by an index | Approved | 2026-10-31 |
| [0010](./ADR-0010-projects-document-themselves-through-a-submodule.mdx) | Projects document themselves here through a git submodule, one folder each | Approved | 2026-10-31 |
| [0011](./ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx) | Archify diagrams are embedded in pages from sandboxed HTML files | Approved | 2026-10-31 |
| [0012](./ADR-0012-every-page-is-mdx.mdx) | Every page in `content/docs` is MDX | Approved | 2026-10-31 |
| [0013](./ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx) | Packages and projects share one catalogue shape: two tracks, version lines and demos | Approved | 2026-10-31 |
| [0014](./ADR-0014-home-page-is-a-search-first-release-map.mdx) | The home page is a search-first map of every release | Approved | 2026-10-31 |
| [0015](./ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx) | Every package and project lives at the root, in one shape and one look | Approved | 2026-10-31 |
| [0016](./ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx) | Home search is the Fumadocs dialog, and private projects render server-side | Approved | 2026-11-01 |
| [0017](./ADR-0017-the-whole-site-is-one-solar-system.mdx) | The whole site is one solar system | Approved | 2026-11-01 |
| [0018](./ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx) | Docs pages get orbit stations, a trajectory and the full horizon | Approved | 2026-11-01 |
| [0019](./ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar.mdx) | ADR folders show as a constellation in the sidebar | Approved | 2026-11-01 |
| [0020](./ADR-0020-people-in-adrs-are-github-usernames-shown-as-profile-chips.mdx) | People in ADRs are GitHub usernames, shown as profile chips | Approved | 2026-11-01 |
| [0021](./ADR-0021-tests-run-with-bun-test.mdx) | Tests run with Bun's built-in test runner | Approved | 2026-11-01 |
| [0022](./ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown.mdx) | Diagrams show their Archify view on the page and their Mermaid in Markdown | Approved | 2026-11-01 |
| [0023](./ADR-0023-sidebar-stations-open-one-at-a-time.mdx) | Sidebar stations open one at a time | Approved | 2026-11-01 |
| [0024](./ADR-0024-a-project-can-span-several-repositories.mdx) | A project can span several repositories | Approved | 2026-11-01 |
| [0025](./ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks.mdx) | The overview has the same sidebar as its tracks | Approved | 2026-11-01 |
| [0026](./ADR-0026-the-moon-picker-on-an-overview-opens-a-lines-first-page.mdx) | The moon picker on an overview opens a line's first page | Approved | 2026-11-01 |
| [0027](./ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx) | The sidebar is a scale ladder with one lifted orbit | Approved | 2026-11-01 |
| [0028](./ADR-0028-the-site-is-named-puncoz-verse.mdx) | The site is named Puncoz Verse | Approved | 2026-11-01 |
| [0029](./ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx) | The Verse is a still sky you zoom through | Approved | 2026-11-01 |
| [0030](./ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx) | The horizon rises over the page, and its sky comes alive | Approved | 2026-11-01 |
| [0031](./ADR-0031-the-sidebar-sets-without-dimming.mdx) | The sidebar sets without dimming | Approved | 2026-11-01 |
| [0032](./ADR-0032-the-heros-system-comes-alive.mdx) | The hero's system comes alive | Approved | 2026-11-01 |
| [0033](./ADR-0033-the-footer-says-you-have-reached-the-horizon.mdx) | The footer says you've reached the horizon | Approved | 2026-11-03 |
| [0034](./ADR-0034-the-proxy-answers-unknown-paths-with-a-true-404.mdx) | The proxy answers unknown paths with a true 404 | Approved | 2026-11-03 |
| [0035](./ADR-0035-every-page-is-ready-for-search-and-sharing.mdx) | Every page is ready for search and sharing | Approved | 2026-11-03 |
| [0036](./ADR-0036-the-site-is-nepal-dev-verse.mdx) | The site is Nepal Dev Verse, part of nepal-dev.com | Approved | 2026-11-03 |
| [0037](./ADR-0037-the-horizon-is-the-himalaya.mdx) | The Horizon is the Himalaya | Approved | 2026-11-03 |


# API — Machine-readable content routes (/docs/maintain/api/content-routes)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx),
  [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx),
  [ADR-0011](../adr/ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

All of these are prerendered at build time (they read no request data, ADR-0016), need no
authentication, and
return **every page in `content/`**. None filters anything out. Pages live at the root,
`/<slug>/…` (ADR-0015). `src/proxy.ts` handles line redirects and Markdown on paths whose first
segment is a catalogued slug, and answers any path that is not a page with a 404 (ADR-0034).

## Endpoints [#endpoints]

| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | `/<package>/use/latest/<path>` | 307 to the same path in the line marked `latest`, or in `dev` when nothing is released (also with `.md`) | None |
| GET | `/<package>/use/<segment>/<path>` for a line that does not exist | 307 to the same path in `latest` (or `dev`); 404 there if the page doesn't exist | None |
| GET | Any other path that is not a page or a site route | 404 with the whole out-of-orbit page (rewritten by `src/proxy.ts` to `/_not-found`; the address does not change) | None |
| GET | `/<page>.md` | One page as Markdown (rewritten by `src/proxy.ts`) | None |
| GET | `/<page>` with `Accept` preferring Markdown | One page as Markdown (rewritten by `src/proxy.ts`) | None |
| GET | `/llms.mdx/<slug>/content.md` | One page as Markdown | None |
| GET | `/llms.txt` | Index of every page | None |
| GET | `/llms-full.txt` | Every page's Markdown, concatenated | None |
| GET | `/og/<slug>/image.png` | A page's share image, see [`./crawler-routes.mdx`](./crawler-routes.mdx) | None |
| GET | `/static.json` | Every page as an Algolia search record | None |
| GET | `/diagrams/<project-slug>/<slug>.html` | One Archify diagram, a static file from `public/`, served sandboxed | None |

---

### `GET /llms.mdx/<slug>/content.md` [#get-llmsmdxslugcontentmd]

**Purpose.** The processed Markdown of one page, headed `# <title> (<url>)`. A page in a
package's version line follows the heading with `> Documents <package> <version> (<line name>, <latest | in development | older version>).`,
such as `> Documents lodestar 0.1.4 (v0.1, latest).`

**Authorisation.** Public. Nothing keeps private content out — see `AGENTS.md` §6.1.

**Responses**

| Status | Meaning | Body |
|---|---|---|
| 200 | Page found | Markdown, `Content-Type: text/markdown` |
| 404 | No such page | Next.js not-found page |

**Notes.** `/<page>.md`, and `/<page>` when the request prefers Markdown, are
rewritten here by `src/proxy.ts`; the second adds `Vary: Accept`.

---

### `GET /llms.txt` and `GET /llms-full.txt` [#get-llmstxt-and-get-llms-fulltxt]

**Purpose.** `llms.txt` lists every page; `llms-full.txt` returns all of their Markdown in one
response. Both come from `docsLlms` in `src/lib/source.ts`. In `llms.txt`, each version line
is named with its line name, version and channel, such as `v4.0 — 4.0.1, latest` or
`dev — 5.0.0-dev, in development`.

**Authorisation.** Public.

**Responses**

| Status | Meaning | Body |
|---|---|---|
| 200 | Always | Plain text |

---

### `GET /og/<slug>/image.png` [#get-ogslugimagepng]

**Purpose.** A page's share image, showing its entry, track, line, title, description and the site's
name. [`./crawler-routes.mdx`](./crawler-routes.mdx) has the details and the home page's image.

**Authorisation.** Public.

**Responses**

| Status | Meaning | Body |
|---|---|---|
| 200 | Page found | PNG |
| 404 | No such page | Next.js not-found page |

---

### `GET /static.json` [#get-staticjson]

**Purpose.** Every page as an Algolia `DocumentRecord`, from `toDocuments(source)`. The
build reads this route's output and pushes it to the index (`scripts/sync-content.ts`).

**Fields added here (ADR-0013 decision 8).** `tag` is the page's scope, the index's one facet:
`<package>`, `<package>:maintain`, `<package>:use` or `<package>:use:<segment>` for catalogue
pages (`ledgerly:use:3.x-lts`, `docs:maintain`), and `site` for anything outside an entry. The home page's
search filters on it. Catalogue pages also carry `extra_data` with `package`, `kind`,
`ecosystem`, `track`, `line` (the line's name) and `channel`; these reach the index, but the current index
settings neither retrieve nor rank on them. Ranking `latest` and Maintain pages first needs an
index settings change, which is publishing and waits for the owner.

**Authorisation.** Public — it is served by the deployed site as well as read by the build.

**Responses**

| Status | Meaning | Body |
|---|---|---|
| 200 | Always | JSON array of records |

## `GET /diagrams/<project-slug>/<slug>.html` [#get-diagramsproject-slugslughtml]

One Archify diagram: the file at `diagrams/<project-slug>/<slug>.html`, exactly as Archify's
`deliver` wrote it, with the site shell added (`src/lib/diagram-shell.ts`, ADR-0022). Prerendered
by `src/app/diagrams/[project]/[file]/route.ts` for every file listed at build; no other path is
served and no request data is read. `<Diagram>` frames it with `?frame=1&theme=…`;
**Open full screen** links to it with `?theme=…` only. The frame carries `allow="fullscreen"`.

**Query.** Read by the shell's script in the browser, never by the server: `frame=1` hides
Archify's title, subtitle, notes rail, theme and style buttons and credit, and reports the
content height to the embedding page with `postMessage({ type: 'archify-height', height })`,
including an open toolbar menu. Present takes the frame to fullscreen; where fullscreen is
refused, the frame posts `{ type: 'archify-present' }` and the page opens
`<src>?theme=…&present=1` itself. `theme=light|dark` sets the theme before first paint and
`present=1` opens Archify's Present stage (both Archify's own parameters).

**Headers.** `Content-Security-Policy: sandbox allow-scripts allow-downloads`, set for
`/diagrams/:path*` in `next.config.mjs`, so a direct visit runs the diagram's script in an
opaque origin, as the embedding frame does (`sandbox="allow-scripts allow-downloads"`, no
`allow-same-origin`).

**Authorisation.** Public. Everything in `diagrams/` is published; no diagram of a private
project goes there.

**Not indexed.** The files are not in `static.json`, the search index or `llms.txt`. A page's
Markdown carries the diagram's Mermaid fence, never the `<Diagram>` tag or the file's URL.

**Build checks** (`src/lib/remark-diagrams.ts` as each page compiles; `src/lib/diagrams.ts`, run
by the loader plugin in `src/lib/diagrams-plugin.ts`; and `<Diagram>` itself): a Mermaid fence
outside a `<Diagram>` (templates excepted), a `<Diagram>` without a plain `src` and `title` or
without exactly one Mermaid fence, a `src` that is not `/diagrams/<project-slug>/<slug>.html` or
has no file, an HTML without its JSON (or the reverse), an HTML no page uses, any file in
`public/diagrams/`, and an Archify receipt (`*.delivery*.json`) in `diagrams/` or `public/` each
fail the build.

**Responses**

| Status | Meaning | Body |
|---|---|---|
| 200 | File found | HTML, `Content-Type: text/html` |
| 404 | Not a listed file, including the JSON sources | The site's not-found page |


# API — crawler routes (/docs/maintain/api/crawler-routes)

- **Status:** Current
- **Last updated:** 2026-11-03
- **Related ADRs:** [ADR-0035](../adr/ADR-0035-every-page-is-ready-for-search-and-sharing.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

All of these are prerendered at build, take no input and need no authentication. They are built only
from pages already published, so a private project stays out of them by staying out of `content/`
(`AGENTS.md` §6.1).

## Endpoints [#endpoints]

| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | `/robots.txt` | Who may crawl, and where the sitemap is | None |
| GET | `/sitemap.xml` | Every page that should be indexed | None |
| GET | `/manifest.webmanifest` | The site's name, colours and icons | None |
| GET | `/apple-icon` | The brand mark, drawn at build | None |
| GET | `/og/image.png` | The home page's share image | None |
| GET | `/og/<page>/image.png` | A page's share image | None |

---

### `GET /robots.txt` [#get-robotstxt]

**Purpose.** Tells every crawler it may read the site.

**Responses**

| `SITE_URL` | Body |
|---|---|
| Set | `User-Agent: *`, `Allow: /`, and `Sitemap: <SITE_URL>/sitemap.xml` |
| Not set | `User-Agent: *`, `Disallow: /` |

---

### `GET /sitemap.xml` [#get-sitemapxml]

**Purpose.** Lists the home page and each page ADR-0035's table marks, as absolute addresses, with
`lastmod` from git. No `changefreq` or `priority`.

**Responses**

| `SITE_URL` | Body |
|---|---|
| Set | One `<url>` per listed page |
| Not set | An empty `<urlset>` |

---

### `GET /og/image.png` and `GET /og/<page>/image.png` [#get-ogimagepng-and-get-ogpageimagepng]

**Purpose.** A PNG of 1200 by 630, the same on every request.

**Responses**

| Status | Meaning | Body |
|---|---|---|
| 200 | A page, or the home page | `image/png` |
| 404 | No such page | Next.js not-found page |

---

## The `noindex` header [#the-noindex-header]

`X-Robots-Tag: noindex` is on these, which stay readable and are not blocked in `robots.txt`:
`/llms.mdx/…` (with `/<page>.md` and Markdown negotiation), `/llms.txt`, `/llms-full.txt`,
`/static.json` and `/diagrams/…`.


# API (/docs/maintain/api)

Contracts for every route handler and endpoint that another client or system calls — the
Markdown routes, `llms.txt`, the search records, and any future integration.

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- File name: `<resource>.mdx`.
- Each endpoint: purpose, who may call it and what content it can return (cross-reference `content/docs/maintain/rbac/`), request, responses, caching, side effects.
- A public endpoint says what keeps private content out of it.

**Template:** [`../_templates/api.mdx`](../_templates/api.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|
| [Machine-readable content routes](./content-routes.mdx) | Current | — (Fumadocs scaffold) |
| [Crawler routes](./crawler-routes.mdx) | Current | [ADR-0035](../adr/ADR-0035-every-page-is-ready-for-search-and-sharing.mdx) |


# App flow — the ADR constellation (/docs/maintain/app-flow/adr-constellation)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0019](../adr/ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar.mdx),
  [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

How an ADR folder's station shows its pages (ADR-0019). Every other folder stays
an orbit station ([Docs sidebars](./docs-sidebars.mdx), screen 1). Sample values are invented
(ADR-0008): `lodestar` is not a real package; this site's own ADRs are real and public. Phone
width first; the characters in the wireframes stand for drawn SVG moons.

The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `adr-constellation.json` for the
flow, one `adr-constellation-screen-<n>.json` per screen.

## Entry points [#entry-points]

- Any page in a track that has a folder named `adr`: the station opens on any ADR and on the
  folder's index page, and starts closed elsewhere. A folder named `adr` with sub-folders keeps
  the plain station.
- On phones, the sidebar drawer; on desktop, the sidebar column.
- Everyone sees the same; the per-page Markdown and `llms.txt` carry none of it.

## Flow [#flow]

```mermaid
flowchart LR
  R[Reader] -->|opens an ADR| G["Constellation<br/>a moon per ADR, current lit"]
  G -->|points at or focuses a moon| O["Readout<br/>16 · Home search is…"]
  O -->|clicks the moon| A["That ADR<br/>its moon lit"]
  G -->|← 15 · 17 →| A
  G -->|All 18 decisions →| I["Register<br/>the folder's index page"]
  I -->|a row| A
```

## Screens [#screens]

### 1. `Constellation` — the open Decisions station, on `/docs/maintain/adr/ADR-0016-…` [#1-constellation--the-open-decisions-station-on-docsmaintainadradr-0016-]

```mermaid
block-beta
  columns 10
  head["◎ Architecture Decision Records · 19 ▾"]:10
  m1["◌"] m2["◌"] m3["◌"] m4["◌"] m5["◌"] m6["◌"] m7["◌"] m8["◌"] m9["◌"] m10["◌"]
  m11["◌"] m12["●"] m13["●"] m14["●"] m15["●"] m16["◉"] m17["●"] m18["●"] m19["◌"] sp[" "]
  read["16 · Home search is the Fumadocs dialog, and private projects render server-side"]:10
  steps["← 15"]:5 next["17 →"]:5
  all["All 19 decisions →"]:10
  legend["● approved · ◌ proposed · ◐ superseded"]:10
```

Moons run in page order, oldest first, as many to a row as fit. Each moon's phase is its ADR's
status: full approved, dashed new moon proposed, crescent superseded, a faint ring rejected or
without a status line. The current ADR is the teal planet ringed in the ecosystem colour.
Pointing at or focusing a moon shows its number and title in the readout; leaving it returns
the readout to the current page. The wireframe shows this site's ADRs as they stand: 0001 to
0011 and 0019 proposed, 0012 to 0018 approved. Desktop: about nine moons a row in the 268px sidebar. Phone:
more a row in the wider drawer.

**States**

- On the folder's index page: no moon lit, the readout reads "19 decisions · 12 proposed", no
  previous or next.
- First or last ADR: only "17 →" or only "← 17".
- One ADR: one moon, no previous or next.
- Empty: a folder named `adr` with only its index page shows the header and "No decisions in this constellation yet."
- No index page: no register link.
- Loading: none; prerendered with the page, statuses included.
- Not found, refused: not applicable; every ADR here is public.
- Error: not applicable at run time; a page without a status line shows the faint ring.
- Degraded: on touch screens nothing is pointed at; a tap opens the ADR, and the readout shows
  the current page. With reduced motion the readout changes without fading. Without scripts the
  moons, previous, next and the register link still work; the readout stays on the current page.
- Success: a moon, previous, next or the register opens that page.

### 2. `Closed station` — elsewhere in the track [#2-closed-station--elsewhere-in-the-track]

```mermaid
block-beta
  columns 10
  head["○ Architecture Decision Records · 19 ▸"]:10
```

The header alone, as every closed station. Its chevron opens the constellation.

**States**

- Success: opening shows screen 1 with no moon lit and the summary readout.
- Other states: as screen 1.


# App flow — the community identity (/docs/maintain/app-flow/community-identity)

- **Status:** Current
- **Last updated:** 2026-11-03
- **Related ADRs:** [ADR-0036](../adr/ADR-0036-the-site-is-nepal-dev-verse.mdx),
  [ADR-0028](../adr/ADR-0028-the-site-is-named-puncoz-verse.mdx),
  [ADR-0029](../adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

Where readers see the site's identity under ADR-0036. The site is *Nepal Dev Verse*, part of
nepal-dev.com; its own documentation, the project with the slug `docs`, is *Nepal Dev Verse Docs*.
No page moves and no URL changes. Sample values are invented (ADR-0008): `lodestar` is not a real
package. Phone width first.

The flow and every screen are drawn with Archify; the page shows them and its Markdown carries their
Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `community-identity.json` for the flow, one
`community-identity-screen-<n>.json` per screen.

## Entry points [#entry-points]

- **Every page:** the header's mark and wordmark, the browser tab, the favicon, the footer's credit.
- **The home page:** the home line and the star's label.
- **A shared link:** the mark and the name on the share image.
- **A device's home screen:** the Apple icon and the manifest's name.
- **`/docs`:** the project's planet card, planet header and sidebar chip.
- Everyone sees the same.

## Flow [#flow]

```mermaid
flowchart LR
  S["Shared link<br/>share image: mark and name"] --> H["Home page<br/>the home line, the star: nepal-dev.com"]
  H -->|a planet card| P["/lodestar<br/>header: mark and Nepal Dev Verse"]
  P -->|mark and wordmark| H
  P -->|the end of the page| F["Footer credit"]
  F -->|nepal-dev.com| N["nepal-dev.com"]
  F -->|Puncoz Nepal| M["puncoz.com"]
```

## Screens [#screens]

### 1. `Header` — every page [#1-header--every-page]

```mermaid
block-beta
  columns 4
  mark["▲ Summit-and-flag mark · Nepal Dev Verse"]:2 search["⌕"] menu["☰"]
  tab["browser tab · Install — lodestar — Nepal Dev Verse"]:4
  scale["Scale strip · the Verse mark stays only here, for the Verse level"]:4
```

The mark and wordmark link home. The flag keeps its own colours in both themes; only the rock changes
with the theme, so it stands clear of the ground. The Verse mark stays as the place mark of the Verse
level in the scale strip.

**States**

- Empty, loading, not found, refused, degraded: the header does not change with them; the 404 keeps it.
- Error: the mark is inline, so it cannot fail to load.
- Success: the same mark and name on every page, and the same mark as the favicon.

### 2. `Home page` — the top, at phone width [#2-home-page--the-top-at-phone-width]

```mermaid
block-beta
  columns 4
  hdr["▲ Nepal Dev Verse"]:2 search["⌕"] menu["☰"]
  system["The system · the star labelled nepal-dev.com, orbits and planets"]:4
  line["Every package and project by Nepalese developers all over the world, documented to the version."]:4
  sub["Guides, APIs and release notes, read from each package's own source."]:4
  find["⌕ Search packages, projects and pages"]:4
  zoom["Zoom out to the Verse"]:4
```

**States**

- Empty: with only this site documented, the empty orbits are faint and named, as they are now.
- Loading: none; the page is prerendered.
- Not found, refused, error: not applicable.
- Degraded: under reduced motion the system is drawn still, with the same label.
- Success: the line says whose work this is before anything is opened.

### 3. `Footer credit` — the end of every page [#3-footer-credit--the-end-of-every-page]

```mermaid
block-beta
  columns 4
  closing["You've reached the horizon. The Verse goes on."]:4
  scene["The Horizon's scene (ADR-0037)"]:4
  planets["Planet row · Nepal Dev Verse Docs"]:4
  links["Search · llms.txt · llms-full.txt · GitHub · Back to orbit"]:4
  credit["▲ Part of nepal-dev.com. Made with ❤️ by Puncoz Nepal."]:4
```

*nepal-dev.com* links to `https://nepal-dev.com` and *Puncoz Nepal* to `https://puncoz.com`. It is also
the plain sentence beside the space words (*The Places, Not Controls Rule*).

**States**

- Empty, loading, not found, refused, error, degraded: the credit is plain text and links, and does not
  change with them.
- Success: both links open in the same tab, with `rel="noreferrer noopener"`.

### 4. `Share image` — at its fixed 1200 by 630 [#4-share-image--at-its-fixed-1200-by-630]

```mermaid
block-beta
  columns 4
  brand["▲ Summit-and-flag mark · Nepal Dev Verse"]:4
  kicker["lodestar · Use · v3.2"]:2 sky["The star and its orbit, on the right"]:2
  title["Install"]:2 sky2["Clear of the text"]:2
  domain["docs.nepal-dev.com"]:4
```

**States**

- Empty: not applicable; every image has its page.
- Loading: none; the image is made at build.
- Not found: an unknown path's image address answers 404.
- Refused: not applicable.
- Error: a failed font fetch fails the build, as ADR-0035 decided.
- Degraded: with no `SITE_URL` the image leaves out the domain.
- Success: the card shows the mark and the name. The home page's image carries the long home line, set
  smaller so it stays clear of the system.


# App flow — diagrams (/docs/maintain/app-flow/diagrams)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0022](../adr/ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown.mdx),
  [ADR-0011](../adr/ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a person sees and how they move through it. Sample values are invented (ADR-0008).
Phone width first; note where desktop differs.

Every diagram, flows and screen wireframes alike, shows on its page as its Archify view only:
the diagram, its labels and its controls, at its own height, on the site's background, moving.
Every Markdown surface carries its Mermaid instead.

The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `diagrams.json` for the
flow, one `diagrams-screen-<n>.json` per screen.

## Entry points [#entry-points]

- Any docs page with a diagram: an app flow's flow and screens, an architecture, data-flow,
  state or sequence page, a package's own pages.
- **Open full screen** under a frame, or a shared link to the file.
- The page's Markdown: **Copy Markdown** and the view options above the page, `/<page>.md`,
  Markdown negotiation, `llms-full.txt`.
- Search leads to the page, never to the file: the diagram files are not indexed.
- Everyone sees the same diagrams; no private project has any.

## Flow [#flow]

```mermaid
flowchart LR
  R[Reader] -->|opens| P["Docs page<br/>the diagram, no Mermaid"]
  P -->|scrolls to| V["Archify view<br/>diagram, labels, controls"]
  V -->|Open full screen| F["Full screen<br/>with title and notes"]
  V -->|Present| P2["Present stage<br/>fullscreen, or own page"]
  P2 -.->|Esc| V
  F -->|browser back| P
  S["Theme switch"] -.->|same theme| V
  T["Tool, LLM or Copy Markdown"] -->|fetches| M["Page as Markdown<br/>the Mermaid fence"]
```

## Screens [#screens]

### 1. `Docs page with a diagram` — `/<project-slug>/…` [#1-docs-page-with-a-diagram--project-slug]

Phone width. The frame takes the content width and the diagram's own height: nothing scrolls
inside it vertically, and its height holds still while the diagram moves. The controls sit on
the frame's edges. **Export** opens its menu over the diagram, from the frame's right edge, and
the frame grows to show the whole menu while it is open.

```mermaid
block-beta
  columns 4
  menu["☰"] title["Site name"]:2 search["⌕"]
  h1["Internals"]:4
  para["How a request moves through the CLI."]:4
  block:frame:4
    columns 4
    live["● Live"] present["Present"] export["Export ▾"]:2
    canvas["Parser → Router → Handler (vibrant boxes, moving arrows)"]:4
    route["Route"] map["Map"] lens["Lens"] zoom["＋ －"]
  end
  caption["Request flow"]:2 full["Open full screen ↗"]:2
```

Desktop: the same, wider, with the sidebar and "On this page" either side.

**States**

- Empty: a page without a diagram has no frame.
- Loading: the frame keeps the diagram's height from the start, on the page's own background,
  with the caption and the link under it; the diagram appears when the frame scrolls near.
- Not found: never reaches a reader. A `<Diagram>` without its file, a Mermaid fence outside a
  `<Diagram>`, or a `<Diagram>` without exactly one Mermaid fence fails the build.
- Refused: not applicable.
- Error: scripts blocked in the frame show Archify's static diagram, without motion or controls.
- Degraded: the reader prefers reduced motion: the diagram starts Still. A wide diagram on a
  phone scrolls sideways inside the frame.
- Success: the diagram moving on the cycle, labels readable, Live/Still, Present, Export (PNG,
  SVG or WebM), and Route, Map, Lens, find, guide and zoom working; the theme matches the page
  and follows the theme switch.
- Present: the frame takes Archify's Present stage to fullscreen; Esc, or Present again, leaves
  both. Where the browser refuses fullscreen to the frame (a phone, a browser setting), the
  page opens the diagram's own page in its Present stage (screen 2, `?present=1`), and the
  browser's back returns.

### 2. `Full screen` — `/diagrams/<project-slug>/<slug>.html` [#2-full-screen--diagramsproject-slugslughtml]

Archify's own page in the site's colours: title, diagram and notes; reached from Present, it
opens in Archify's Present stage. The reader returns with the browser's back.

```mermaid
block-beta
  columns 4
  live["● Live"] present["Present"] export["Export ▾"]:2
  title["Request flow"]:4
  canvas["Parser → Router → Handler, full width"]:4
  notes["Notes & index"]:4
```

**States**

- Not found: an unknown file shows the site's 404.
- Success: as in the frame, with the title and notes.
- Empty, loading, refused, error, degraded: as in the frame.

### 3. `Page as Markdown` — **Copy Markdown**, `/<project-slug>/<page>.md` [#3-page-as-markdown--copy-markdown-project-slugpagemd]

```mermaid
block-beta
  columns 4
  h["# Internals (/example-cli/use/v1.0/internals)"]:4
  para["How a request moves through the CLI."]:4
  fence["mermaid fence: flowchart LR · Parser --> Router --> Handler"]:4
```

**States**

- Success: the Mermaid fence where the diagram is; no `<Diagram>` tag, no Archify URL.
- Empty, loading, not found, refused, error, degraded: as for the page's Markdown route today.


# App flow — docs sidebars: orbit stations, the trajectory and the horizon (/docs/maintain/app-flow/docs-sidebars)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0019](../adr/ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar.mdx),
  [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx),
  [ADR-0027](../adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx),
  [ADR-0030](../adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a reader sees around a docs page (ADR-0018): the left sidebar's planet row
and orbit stations, the right-hand "On this page" trajectory, its bar on phones, and the full
horizon below. Sample values are invented (ADR-0008): `lodestar` is not a real package. Phone
width first; desktop differences are noted under each screen. The marks (planet, moons, sun and
moon) are those of [The solar system](./solar-system.mdx); the characters in the wireframes stand
for drawn SVG.

The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `docs-sidebars.json` for the
flow, one `docs-sidebars-screen-<n>.json` per screen.

## Entry points [#entry-points]

- Every page inside a package or project, `/<slug>/…`, and this site's own pages under `/docs`.
- On phones the left sidebar is Fumadocs' drawer, opened from the header; the trajectory is the
  bar under the header.
- Everyone sees the same pages. Nothing here depends on who the reader is.
- The per-page Markdown (`/<page>.md`) and `llms.txt` carry none of this; they are the page's
  content only.

## Flow [#flow]

```mermaid
flowchart LR
  R[Reader] -->|opens a page| PR["Planet row<br/>chip · sun | moon · moon picker"]
  PR -->|current orbit lifts| ST["Open orbit, the one card<br/>pages as satellites"]
  ST -->|chevron| CL["Closed orbit, a row<br/>ring · name · page count"]
  CL -->|chevron| ST
  ST -->|a satellite| P["Docs page"]
  P -->|scroll| T["Trajectory<br/>probe · 4 min left"]
  T -->|a heading| P
  P -->|phone width| B["Phone bar<br/>ring · heading · min left"]
  B -->|tap| SH["Trajectory sheet"]
  SH -->|a heading| P
  T -->|end of page| H["Full horizon<br/>scene · planets · Back to top"]
  H -->|Back to top| P
```

## Screens [#screens]

### 1. `Planet row and orbit stations` — the left sidebar, `/lodestar/use/v0.1/install` [#1-planet-row-and-orbit-stations--the-left-sidebar-lodestarusev01install]

```mermaid
block-beta
  columns 4
  chip["● lodestar"]:3 sw["☀ | ☾"]:1
  moon["full moon · v0.1 · 0.1.4 · Latest ▾"]:4
  top["• Overview (landmark)"]:4
  block:card:4
    columns 4
    h1["◎ Get started · 2 ▾ (the one card)"]:4
    p1["  ◉ Install (probe, tinted)"]:4
    p2[" ∘ Commands"]:4
  end
  h2["○ Reference · 3 ▸ (a row)"]:4
  h3["○ Guides · 4 ▸ (a row)"]:4
```

The planet row: the chip links to `/lodestar`; the sun and moon buttons open the same page on
Use or Maintain ("Use, the day side" and "Maintain, the night side" as names and tooltips).
Below it the sidebar is a scale ladder ([The sidebar's scale ladder](./sidebar-scale-ladder.mdx),
ADR-0027): top-level pages are landmarks, separators are belts, folders are orbits. A closed
orbit is a row with its ring, name and page count; the open one is the sidebar's one card, its
border in the ecosystem colour when it holds the current page, its ring with a planet inside.
Its pages are satellites on one outward-bowing arc, and the current page is the teal probe. One
orbit is open at a time at each level: opening one closes the open one beside it, and a page
change opens that page's orbits and closes the rest ([One open station](./one-open-station.mdx)).

Desktop: the same, in the sidebar column; the sidebar's collapse button works as today. Phone:
the same inside Fumadocs' drawer.

```mermaid
block-beta
  columns 4
  block:nest:4
    columns 4
    h["◎ Guides · 6 ▾ (the one card)"]:4
    a1[" ∘ Theming"]:4
    sub["   ◦ Recipes · 3 ▾ (nested orbit, no inner card)"]:4
    a2["     ○ Async commands"]:4
    a3[" ◉ Keyboard shortcuts (current)"]:4
  end
```

A nested folder is a smaller orbit inside its parent's card, never a card of its own. A folder
holding only its index page is an orbit link, with no count. A folder named
`adr` is a constellation instead, one moon per ADR ([The ADR constellation](./adr-constellation.mdx)).

**States**

- Empty: a track with no folders shows only its landmarks; a track without separators shows no
  belts.
- Loading: none; the sidebar is prerendered with the page. Before scripts load, orbits show
  in their starting state (the current one lifted, others as rows) and the chevrons do nothing until
  hydration.
- Not found: an unknown page gets the out-of-orbit 404, which has no sidebar.
- Refused: not applicable; every page is public.
- Error: not applicable at runtime; a broken `meta.json` fails the build (ADR-0013).
- Degraded: with reduced motion, orbits lift and drop without animation. On touch screens no
  tooltips; the buttons' names are read out.
- One track: no sun and moon buttons. Maintain: no moon picker.
- Success: a moon opens its page; the sun or moon opens the same page on the other side when it
  exists, else that side's first page.

### 2. `Trajectory` — "On this page", desktop column [#2-trajectory--on-this-page-desktop-column]

```mermaid
block-beta
  columns 4
  head["On this page"]:3 left["4 min left"]:1
  i1["● Add the package (read)"]:4
  i2["● Render a palette (read)"]:4
  i3["  ◉ Props (probe)"]:4
  i4["  ○ Events (dashed ahead)"]:4
  i5["○ Options"]:4
  i6["○ Troubleshooting"]:4
  top["Back to top ↑"]:4
```

The path curves through every dot: shallow outward arcs between headings of the same depth, an
S-curve where depth changes. The read stretch is solid accent with filled dots; ahead is dashed
and muted with hollow dots. The probe planet glides along the path as the reader scrolls. The
column sits to the right of the page from Fumadocs' desktop breakpoint up.

**States**

- Empty: a page without headings shows "On this page", its reading time, and "This page has no
  sections."; no path.
- One heading: one dot and the probe on it; no path.
- Loading: none; prerendered. Before scripts load the whole path is drawn dashed with hollow
  dots, no probe, and the header shows the total, "4 min read".
- Long lists: the column scrolls, and keeps the probe's row in view.
- Not found, refused, error: not applicable.
- Degraded: with reduced motion the probe jumps from dot to dot and headings scroll into view
  instantly. Without scripts the headings are plain links that still jump.
- A page under one minute: no time shown. At the end of the page: "End of page".
- Success: choosing a heading scrolls to it; Back to top returns to the top of the page.

### 3. `Phone bar and sheet` — under the header, phone width [#3-phone-bar-and-sheet--under-the-header-phone-width]

```mermaid
block-beta
  columns 4
  ring["◔ ring + probe"]:1 cur["Props"]:2 min["4 min left ▾"]:1
```

```mermaid
block-beta
  columns 4
  sheet["On this page · 4 min left"]:4
  s1["● Add the package"]:4
  s2["● Render a palette"]:4
  s3["  ◉ Props"]:4
  s4["  ○ Events"]:4
  s5["○ Options"]:4
```

The bar replaces Fumadocs' table-of-contents bar: a small ring with the probe at the reading
position, the current heading (truncated), the time left and a chevron. Tapping opens the same
trajectory as a sheet; choosing a heading scrolls there and closes it.

**States**

- Empty: a page without headings has no bar.
- Before the first heading: the bar shows the first heading, muted, and the total time.
- Degraded: with reduced motion the sheet opens without sliding. Without scripts the bar does not
  open; the page reads normally.
- Success: the reader jumps to a section and the sheet closes.

### 4. `Full horizon` — below every docs page [#4-full-horizon--below-every-docs-page]

```mermaid
block-beta
  columns 4
  close["You've reached the horizon. The Verse goes on."]:4
  scene["The Himalaya · twinkling stars, shooting stars, the star rising, clouds, the flag on the summit, an observatory"]:4
  planets["● lodestar  ● ledgerly  ○ orbit-board  ○ Nepal Dev Verse Docs"]:4
  links["Search ⌘K · llms.txt · llms-full.txt · GitHub · Back to top"]:4
  credit["Part of nepal-dev.com. Made with ❤️ by Puncoz Nepal."]:4
```

The same footer as the home page ([The solar system](./solar-system.mdx), screen 5), across the
full width; its last link reads "Back to top". It rises over the sidebar and the trajectory, which
set below its dusk edge as it comes into view ([The living horizon](./living-horizon.mdx),
screen 2).

**States**

- Empty: with no public entries, the planet row is left out.
- Degraded: with reduced motion Back to top jumps instead of scrolling, the sky is still and the
  sidebar does not set. Without scripts Search and Back to top do nothing and the sky is still;
  the links work.
- Success: a planet link opens its overview; Search opens the dialog; Back to top returns to the
  top of the page.


# App flow — GitHub profile chips (/docs/maintain/app-flow/github-profile-chips)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0020](../adr/ADR-0020-people-in-adrs-are-github-usernames-shown-as-profile-chips.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a person sees and how they move through it. Sample values are invented (ADR-0008).
Phone width first; note where desktop differs.

A link written `[@user](https://github.com/user)` shows as a chip: the person's GitHub avatar,
20px and round, beside `@user`. In ADR headers, every decider and approver is written that way.

The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `github-profile-chips.json` for the
flow, one `github-profile-chips-screen-<n>.json` per screen.

## Entry points [#entry-points]

- Any ADR page: the `Deciders` and `Approved by` lines in its header. The sidebar's
  constellation and the search dialog lead there.
- Any other page that writes a link of exactly that shape.
- The page's Markdown version (`/<page>.md`, `llms-full.txt`): the plain link, no chip.
- Everyone sees the same chips. Nothing here depends on who is reading.

## Flow [#flow]

```mermaid
flowchart LR
  R[Reader] -->|opens an ADR| H["ADR header<br/>Deciders · Approved by"]
  H -->|a profile link| C["Chip<br/>avatar + @mira-k"]
  C -->|loads, no referrer| A["Avatar<br/>github.com/mira-k.png"]
  A -.->|fails or blocked| L["First letter<br/>in the chip"]
  C -->|clicks| P["GitHub profile<br/>new tab"]
  T[Markdown reader] -->|fetches| M["Page as Markdown<br/>the plain link"]
  M -->|the link| P
```

## Screens [#screens]

### 1. `ADR header` — `/<project-slug>/maintain/adr/ADR-0007-…` [#1-adr-header--project-slugmaintainadradr-0007-]

Phone width. The chip sits inline in the header line, so a line with two people wraps after
the first chip when it doesn't fit.

```mermaid
block-beta
  columns 4
  menu["☰"] title["Site name"]:2 search["⌕"]
  h1["ADR-0007 — Cache search results for an hour"]:4
  status["Status: Approved"]:4
  deciders["Deciders:"] chip1["(M) @mira-k"] chip2["(T) @tomas-r"]:2
  approved["Approved by:"] chip3["(M) @mira-k"]:3
  date["Approved on: 2026-03-14"]:4
  body["## Context …"]:4
```

`(M)` stands for the avatar. Desktop: the same, with the sidebar and the table of contents on
either side.

**States**

- Empty: a line that names no profile link stays as written, plain text.
- Loading: the avatar is lazy; until it loads, the chip shows the username's first letter on a
  quiet disc.
- Not found: a username GitHub doesn't know returns no image, so the letter stays; the link
  opens GitHub's own not-found page.
- Refused: not applicable; the chip shows the same to everyone.
- Error: a link whose text and address name different users, or an address that isn't exactly
  `https://github.com/<user>`, is not a chip; it renders as an ordinary link.
- Degraded: GitHub unreachable, or the image blocked by the browser or an extension: the letter
  shows; the link still points at the profile.
- Success: the avatar and `@mira-k`, one target that opens the profile in a new tab; hover
  underlines the name, focus rings the whole chip.

### 2. `Page as Markdown` — `/<project-slug>/maintain/adr/ADR-0007-….md` [#2-page-as-markdown--project-slugmaintainadradr-0007-md]

```mermaid
block-beta
  columns 4
  h["# ADR-0007 — Cache search results for an hour"]:4
  line1["- **Deciders:** [@mira-k](https://github.com/mira-k)"]:4
  line2["- **Approved by:** [@mira-k](https://github.com/mira-k)"]:4
```

**States**

- Success: the links as written; no image URL is added.
- Empty, loading, not found, refused, error, degraded: as for the page's Markdown route today.


# App flow — the Himalayan Horizon (/docs/maintain/app-flow/himalayan-horizon)

- **Status:** Current
- **Last updated:** 2026-11-03
- **Related ADRs:** [ADR-0037](../adr/ADR-0037-the-horizon-is-the-himalaya.mdx),
  [ADR-0030](../adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx),
  [ADR-0033](../adr/ADR-0033-the-footer-says-you-have-reached-the-horizon.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

How the end of every page works under ADR-0037. The bare curve of the planet becomes a range rising out
of a sea of cloud, and the summit carries the flag. Sample values are invented (ADR-0008). Phone width
first.

The flow and each screen are drawn with Archify; the page shows them and its Markdown carries their
Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `himalayan-horizon.json` for the flow, one
`himalayan-horizon-screen-<n>.json` per screen.

## Entry points [#entry-points]

- **The end of every page:** docs pages, the home page and the 404. Everyone sees it, and nothing in the
  scene is a control.
- **The planet row:** hovering or focusing an entry's link lights that entry's point on the mountain.
- **Not here:** Markdown surfaces, which carry no footer. Screen readers skip the scene, which is
  `aria-hidden`, and read the closing line, the planet row and the credit.

## Flow [#flow]

```mermaid
flowchart LR
  R["Reading a page"] -->|scrolls to the end| E["The footer enters<br/>the star rises, alpenglow grows"]
  E -->|40% in view| A["Arrival<br/>the flag runs up its pole once"]
  A --> S["The summit<br/>the flag waves while on screen"]
  S -->|hover or focus a planet link| L["That entry's light brightens"]
```

## Screens [#screens]

### 1. `The Horizon` — the end of any page, at phone width [#1-the-horizon--the-end-of-any-page-at-phone-width]

```mermaid
block-beta
  columns 4
  closing["You've reached the horizon. The Verse goes on."]:4
  moon["Stars and shooting stars · a still crescent moon above the star"]:4
  flag["The flag on the summit"]:2 star["The star, right of the summit"]:2
  peak["The summit · snow, its right face red with alpenglow"]:4
  sea["A sea of cloud between the ranges"]:4
  rock["The near rock · traces climb to one light per entry"]:4
  planets["Planet row · Nepal Dev Verse Docs"]:4
  links["Search · llms.txt · llms-full.txt · GitHub · Back to orbit"]:4
  credit["▲ Part of nepal-dev.com. Made with ❤️ by Puncoz Nepal."]:4
```

**States**

- Empty: with no entries there are no traces and no lights, and the mountain stands bare; the planet row
  is not shown, as now.
- Loading: none; the scene is inline in the static page. Before scripts run, the flag stands raised.
- Not found: the 404 has the same scene.
- Refused, error: not applicable.
- Degraded: under reduced motion, with no scripts or with no scroll-driven animations, the star stands
  risen, the alpenglow is full, the flag stands raised and still, and the clouds stay where they are drawn.
- Success: the flag is at the top of its pole by the time the closing line has been read, and is never
  left part-way.

### 2. `The Horizon` — the end of a docs page, on a wide screen [#2-the-horizon--the-end-of-a-docs-page-on-a-wide-screen]

```mermaid
block-beta
  columns 4
  closing["You've reached the horizon. The Verse goes on."]:4
  far["Far range, hazy"] flag["The flag on the summit"] star["Moon above the star"] far2["Far range, hazy"]
  mid["Middle range, out of the clouds"] peak["The summit, its right face lit"] shoulder["A second peak, lit on its right"] mid2["Middle range, out of the clouds"]
  obs["The observatory on the left shoulder"] rock["Traces and lights on the near rock"]:2 slope["The range runs off both edges"]
  surface["Planet row · link row · credit"]:4
```

The summit and the flag are never cropped, at any width: the far and middle ranges run wider and fall off
the edges, and the summit stays at the centre.

**States**

- As screen 1.
- Light theme: the same scene at dawn. The sky washes warm toward the ranges, the rock is the logo's navy,
  and the red and the flag do not change.
- Success: hovering *lodestar* in the planet row brightens its light, in its ecosystem's colour, and it
  settles again when the pointer leaves.


# App flow — home page (/docs/maintain/app-flow/home-page)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx),
  [ADR-0016](../adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx),
  [ADR-0014](../adr/ADR-0014-home-page-is-a-search-first-release-map.mdx),
  [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a person sees and how they move through it. Sample values are invented (ADR-0008):
`lodestar`, `ledgerly`, `pykettle` and `orbit-board` are not real packages or projects. The
private projects `harbor-ops`, `fieldnote` and `tessera` are invented too, and are the ones the
live site shows (ADR-0017 decision 4). Phone width first; desktop differences are noted under
each screen.

The home page at `/` is the solar system (ADR-0017): the star is the community, nepal-dev.com; each
ecosystem is an orbit; a solid planet is a package and a ringed planet a project; each version
line is a moon, full for the latest release, a crescent for an older one, a dashed new moon for
`dev`. The marks are described once in [The solar system](./solar-system.mdx). Every entry, line
and version comes from the catalogue fields in the content folders (ADR-0013) at build time, and
the page is prerendered.

Only this site, the project `docs`, is documented yet, so the page shows one project planet, the
three private projects, no Two sides and no Every moon section.

The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `solar-system.json` for the
flow, one `home-page-screen-<n>.json` per screen.

## Entry points [#entry-points]

- A direct visit to the site's root URL, the header wordmark on every page, `llms.txt`, and
  links from package READMEs or registry pages that point at the site rather than at one
  package.
- The header's Packages and Projects links, on every page, land on the first package card
  (`/#packages`) and the first project card (`/#projects`).
- Everyone sees the same page, the private projects included. The sign-in ADR will decide who
  sees the private group.
- The page has no Markdown twin of its own. `llms.txt` lists every package and project instead
  (invariant 5 covers documentation pages; the home page is navigation).

## Flow [#flow]

```mermaid
flowchart TB
  V[Visitor] -->|opens /| H["The system<br/>star · orbits · search button"]
  H -->|click, Enter or ⌘K| S["Search dialog<br/>Fumadocs"]
  S -->|choose a result| P["Docs page<br/>/lodestar/use/v0.1/install"]
  H -->|click a planet| O["Overview<br/>/lodestar · planet header"]
  H -->|scroll or header link| C["Planet cards"]
  C -->|card| O
  C -->|Use · Maintain · Demo| P
  C -->|scroll| B["Beyond the belt<br/>private projects"]
  B -->|private project name| L["Out of orbit<br/>404"]
  B -->|scroll| T["Two sides · Every moon · Read it anywhere"]
  T -->|Copy Markdown · Open in…| X["clipboard, or ChatGPT, Claude, Cursor, Scira, GitHub"]
  T --> F["Horizon footer"]
  F -->|planet link| O
  F -->|Search| S
  F -->|Back to orbit| H
```

## Screens [#screens]

### 1. `The system` — `/` [#1-the-system--]

```mermaid
block-beta
  columns 4
  word["▲ Nepal Dev Verse"]:2 gh["GitHub"] theme["orrery switch"]
  sys["star · nepal-dev.com, orbits npm · Composer · PyPI · Go · projects, planets lodestar · ledgerly · pykettle · orbit-board with moons"]:4
  h1["Every package and project by Nepalese developers all over the world, documented to the version."]:4
  sub["Guides, APIs and release notes for npm, Composer, PyPI and Go packages"]:4
  field["⌕  Search packages, projects and pages"]:4
```

The star sits in the system with "nepal-dev.com" under it. The npm, Composer, PyPI, Go and
Projects orbits are always there, the empty ones fainter and named; every planet is labelled,
carries its moons and a trail, and turns its night side away from the star. How the system
spins up, leans, breathes and sees a comet is in [the living hero](./living-hero.mdx).
The system turns slowly; pointing at a planet slows it and shows a card (name, description,
kind, latest version, "click to open"); clicking opens the overview. The headline and subline
are selectable text, and the canvas's crosshair cursor shows only over open sky.

The header is the site's one header ([site pages](./site-pages.mdx)) without its search button:
the hero's button is this page's search. Clicking it, Enter or Space on it, or `⌘K` / `Ctrl K`
anywhere opens the search dialog.

Desktop: the text and the 520px search button with its `⌘K` hint sit on the left; the system
fills the right, centred at 70% of the width. A legend under the button shows package, project,
moon = version and dashed = unreleased. The hero is up to 860px tall. Phone: the system sits in
the top 310px, the text and button below it.

**States**

- Empty: with no public entries, the five orbits around the star are all empty and named, no
  planets, and the telemetry line reads `0 planets · 5 orbits waiting · 0 moons`.
- Loading: none; prerendered. The system starts turning after first paint; the text and button
  are usable before it.
- Not found, Refused: not applicable at `/`; unknown paths get the out-of-orbit 404.
- Error: a broken catalogue field fails the build (ADR-0013). If the canvas cannot draw, the
  text and button show on the plain background.
- Degraded: with reduced motion, the system is drawn still and redrawn on hover. With scripts
  off, no canvas; the search button is replaced by a link to the cards. Keyboard and
  screen-reader users get the same content in the cards; the canvas has a label explaining it.
- Success: the dialog opens with the cursor in its field, or a planet opens its overview.

### 2. `Search dialog` — over the home page [#2-search-dialog--over-the-home-page]

```mermaid
block-beta
  columns 4
  input["⌕  lodestar instal▍                      esc"]:4
  r1["Install · lodestar"]:4
  r2["Commands · lodestar"]:4
  foot["Search powered by Algolia"]:4
```

Fumadocs' dialog, the one every page uses (`src/components/search.tsx`), in the site's colours:
results as you type, arrow keys and Enter, Escape closes it.

**States**

- Empty query: the dialog's own empty view.
- Loading: the dialog's own indicator while Algolia answers.
- Not found: the dialog's "no results". A result whose page was removed since the last index
  sync opens the 404.
- Refused: not applicable.
- Degraded: Algolia unreachable shows the dialog's error.
- Success: choosing a result opens that page.

### 3. `Planet cards` — `/#packages`, `/#projects` [#3-planet-cards--packages-projects]

```mermaid
block-beta
  columns 4
  block:c1:4
    columns 4
    sky1["sky: red planet, orbit v0.1 with full moon, dashed orbit dev with new moon"]:4
    n1["lodestar"]:4
    k1["● npm package · Command palette for React apps."]:4
    f1["Latest 0.1.4 · In development 0.2.0-dev.3"]:4
    l1["[Use →]  Maintain  Demo"]:4
  end
  block:c2:4
    columns 4
    sky2["sky: violet planet, orbits v4.0 · v3.2 · v2.9 · dev"]:4
    n2["ledgerly"]:4
    f2["Latest 4.0.1 · In development 4.1.0-dev.2 · Older v3.2, v2.9"]:4
  end
  c3["orbit-board — ringed planet, no moons · Project · [Use →] Maintain"]:4
```

No heading on screen (a visually hidden h2, "Packages and projects", keeps the outline). One card
per public entry, in catalogue order: the sky draws the planet, one orbit per version line with
its moon labelled by the line's name; then the name (the whole card links to the overview),
kind, description, the fact sheet (Latest, In development, Older) and the Use →, Maintain and
Demo links, each only when it exists. Desktop: two or three cards across; hovering a card turns
its moons a little and tints its border with the ecosystem colour.

**States**

- Empty: with nothing documented, "No planets in the Verse yet. Packages and projects appear here
  once they are documented."
- A package with no release: Latest reads "unreleased"; only its dashed `dev` moon is drawn.
- A project: a ringed planet; no fact sheet without lines; no Use link without a Use track (this
  site's own documentation, Nepal Dev Verse Docs).
- Loading, Not found, Refused, Error: not applicable; built from content that passed the build
  checks.
- Success: the card opens the overview; Use, Maintain and Demo open their pages.

### 4. `Beyond the belt` — `/#private` [#4-beyond-the-belt--private]

```mermaid
block-beta
  columns 4
  belt["· ·  ·   · asteroid belt ·  · ·   ·  ·"]:4
  h["Private projects"]:2 copy["Client and internal work. The pages stay private; only their names orbit here."]:2
  p1["night planet · harbor-ops · lock · Operations dashboard for a shipping client. · client · Use, Maintain"]:4
  p2["night planet · fieldnote · lock · Offline survey app for field teams. · client · Use"]:4
  p3["night planet · tessera · lock · Internal billing and invoicing service. · internal · Maintain"]:4
```

A seeded asteroid belt divides the public planets from the private ones. Each private project is
a night-side planet on a dashed orbit in a dashed card, with a drawn lock (read out as
"private"). The list is in `src/components/home/private-projects.ts`, never in `content/`.
Desktop: three cards across. Empty state:

```mermaid
block-beta
  columns 4
  orbit["dashed empty orbit"]:1 msg["No private projects in orbit yet. They'll appear here once private documentation is set up."]:3
```

**States**

- Empty: the dashed empty orbit and its message, when the list is empty.
- Filled: the three invented projects.
- Not found: a private project's name opens `/<slug>`, which returns the out-of-orbit 404.
- Refused: not applicable today; the sign-in ADR will decide who sees the group.
- Loading, Error: not applicable; rendered on the server with the page.
- Success: the reader sees which private projects exist.

### 5. `Two sides · Every moon · Read it anywhere` [#5-two-sides--every-moon--read-it-anywhere]

```mermaid
block-beta
  columns 4
  hs["Two sides of every planet"]:4
  day["☀ Use v0.1 · 0.1.4 — Install · Commands · API reference"]:2 night["☾ Maintain — Releasing · Architecture · Decisions"]:2
  hm["Every moon, released or not"]:4
  m1["ledgerly  ◔ v2.9 ── ◔ v3.2 ── ● v4.0 latest ┄ ○ dev"]:4
  ha["Read it anywhere"]:4
  term["[page.md] llms.txt Accept · $ curl -s …/install.md | head -6"]:4
  assist["Hand any page to your assistant · [Copy Markdown] [Open ▾]"]:4
```

The sun, moon and phase characters stand for drawn SVG marks.

- **Two sides of every planet.** Use is the day side and Maintain the night side of the first
  entry with both tracks, split by a planet drawn with its terminator. Each side lists that
  entry's real pages; Use names its line.
- **Every moon, released or not.** One row per entry with two or more lines: its moons oldest
  first, each with its phase mark, name and version, linking to that line. A legend names the
  three phases.
- **Read it anywhere.** A terminal with three tabs, each a real `curl` against this site with the
  real first lines of its output, taken at build time: `page.md`, `llms.txt` and `Accept`. A tab
  types its command the first time it is shown; arrow keys move between tabs. Under it,
  "Everything in one file: `/llms-full.txt`". Beside it, Fumadocs' own Copy Markdown button and
  Open menu, live, for the example page, and a "See it on a page" link. The example page is a
  package's first Use page, or this site's overview, `/docs`, while no package is documented.

Desktop: the two sides sit either side of the terminator; Read it anywhere is two columns.

**States**

- Empty: no entry with both tracks drops Two sides; no entry with two or more lines drops Every
  moon. With only `llms.txt` available, the terminal shows one tab and the assistant panel is
  left out.
- Loading: none; prerendered. The terminal and assistant panel enter once as they come into
  view; their content is visible without scripts.
- Not found, Refused, Error: not applicable at runtime. A failed copy leaves the button as it
  was.
- Degraded: with reduced motion, commands show without typing. With scripts off, the first tab
  shows and the tabs don't switch; Copy Markdown and the Open menu don't respond.
- Success: the reader follows a page or line, copies the page, or opens it in their assistant.

### 6. `Horizon footer` [#6-horizon-footer]

Drawn in [The solar system](./solar-system.mdx), screen 5: the closing line, the living sky over
a planet's horizon ([The living horizon](./living-horizon.mdx)), the planet links and the link row.


# App flow — the Horizon's closing line (/docs/maintain/app-flow/horizon-closing-line)

- **Status:** Current
- **Last updated:** 2026-11-03
- **Related ADRs:** [ADR-0033](../adr/ADR-0033-the-footer-says-you-have-reached-the-horizon.mdx),
  [ADR-0030](../adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx),
  [ADR-0029](../adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

How the closing line of the Horizon footer works under ADR-0033: it tells the reader they have
reached the horizon, and its link leads to the Verse view. Sample values are invented (ADR-0008).
Phone width first.

The flow and the screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `horizon-closing-line.json` for
the flow, `horizon-closing-line-screen-1.json` for the screen.

## Entry points [#entry-points]

- **The end of every page:** docs pages, the home page and the 404. Everyone sees it.

## Flow [#flow]

```mermaid
flowchart LR
  A["End of any page<br/>You've reached the horizon"] -->|The Verse, on another page| B["The home page<br/>the page zooms out"]
  A -->|The Verse, on the home page| C["Back to the top<br/>the camera eases out"]
  B --> V["The Verse view<br/>Back to the system returns"]
  C --> V
  A -->|Puncoz Nepal, in the credit| P["puncoz.com"]
```

## Screens [#screens]

### 1. `The closing line` — the end of any page, at phone width [#1-the-closing-line--the-end-of-any-page-at-phone-width]

```mermaid
block-beta
  columns 4
  closing["You've reached the horizon."]:4
  verse["The Verse goes on. · The Verse is the link, underlined"]:4
  scene["The Horizon's sky · the star rising · the observatory"]:4
  planets["lodestar · Nepal Dev Verse Docs"]:4
  links["Search ⌘K · llms.txt · llms-full.txt · GitHub · Back to top ↑"]:4
  credit["Part of nepal-dev.com. Made with ❤️ by Puncoz Nepal."]:4
```

Each sentence stands on its own line, centred on the opaque ground above the scene. On a wide
screen the layout is the same at a larger size. Only "The Verse" is a link; the maker's name is
in the credit.

**States**

- Empty: not applicable; the line has no data. With no public planets the planet row is left out,
  as today.
- Loading: none; prerendered, and the link works as soon as scripts run.
- Not found: the 404 ends with the same line, and its link goes to the home page's Verse view.
- Refused, error: not applicable.
- Degraded:
  - with reduced motion the page jumps to the top and the Verse view opens at once, with no zoom;
  - without scripts the link is a plain link to the top of the home page, which then has no
    canvas and no Verse view;
  - on a screen too narrow for a sentence on one line, that sentence wraps within itself.
- Success: the reader follows the link and sees the Verse view at the top of the home page, and
  *Back to the system* returns them to the system.


# App flows (/docs/maintain/app-flow)

What a person sees and how they move through it — one file per feature, written with every ADR
that changes the UI ([ADR-0008](../adr/ADR-0008-a-ui-change-ships-an-app-flow.mdx)).

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- File name: `<feature-slug>.mdx`, matching the feature's PRD slug.
- The flow as a Mermaid `flowchart` with its Archify view; one `block-beta` wireframe per
  screen, **phone width first**, with its Archify view drawn from it (an `architecture`
  diagram inside a phone-screen region). Each is a `<Diagram>` (ADR-0022).
- Every screen lists its states: empty, loading, not found, refused, error, degraded, success.
  *Degraded* is what the person sees when an external service (search, for one) is
  unavailable: a clear notice, never a hang or a raw error.
- Sample values are invented: an example package name, never a private project's.
- Each page type names its Markdown entry point (`/<slug>.md`), so readers and tools can
  take the content without the site.

**Template:** [`../_templates/app-flow.mdx`](../_templates/app-flow.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|
| [The ADR constellation](./adr-constellation.mdx) | Current | [ADR-0019](../adr/ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar.mdx) |
| [Diagrams](./diagrams.mdx) | Current | [ADR-0022](../adr/ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown.mdx), [ADR-0011](../adr/ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx) |
| [Docs sidebars: orbit stations, the trajectory and the horizon](./docs-sidebars.mdx) | Current | [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx) |
| [GitHub profile chips](./github-profile-chips.mdx) | Current | [ADR-0020](../adr/ADR-0020-people-in-adrs-are-github-usernames-shown-as-profile-chips.mdx) |
| [Multi-repository projects](./multi-repository-projects.mdx) | Current | [ADR-0024](../adr/ADR-0024-a-project-can-span-several-repositories.mdx) |
| [One open station](./one-open-station.mdx) | Current | [ADR-0023](../adr/ADR-0023-sidebar-stations-open-one-at-a-time.mdx) |
| [The overview's sidebar](./overview-sidebar.mdx) | Current | [ADR-0025](../adr/ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks.mdx) |
| [The sidebar's scale ladder](./sidebar-scale-ladder.mdx) | Current | [ADR-0027](../adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx) |
| [The universe theme](./universe-theme.mdx) | Current | [ADR-0029](../adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx) |
| [The living horizon](./living-horizon.mdx) | Current | [ADR-0030](../adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx) |
| [The living hero](./living-hero.mdx) | Current | [ADR-0032](../adr/ADR-0032-the-heros-system-comes-alive.mdx) |
| [The Horizon's closing line](./horizon-closing-line.mdx) | Current | [ADR-0033](../adr/ADR-0033-the-footer-says-you-have-reached-the-horizon.mdx) |
| [Unknown paths](./unknown-paths.mdx) | Current | [ADR-0034](../adr/ADR-0034-the-proxy-answers-unknown-paths-with-a-true-404.mdx) |
| [Search and sharing](./search-and-sharing.mdx) | Current | [ADR-0035](../adr/ADR-0035-every-page-is-ready-for-search-and-sharing.mdx) |
| [The community identity](./community-identity.mdx) | Current | [ADR-0036](../adr/ADR-0036-the-site-is-nepal-dev-verse.mdx) |
| [The Himalayan Horizon](./himalayan-horizon.mdx) | Current | [ADR-0037](../adr/ADR-0037-the-horizon-is-the-himalaya.mdx) |
| [Home page](./home-page.mdx) | Current | [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx), [ADR-0016](../adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx), [ADR-0014](../adr/ADR-0014-home-page-is-a-search-first-release-map.mdx) |
| [The solar system: marks, theme switch, planet header, footer, 404](./solar-system.mdx) | Current | [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx) |
| [Package and project navigation](./package-navigation.mdx) | Current | [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx) |
| [Site pages: root URLs, header and docs pages](./site-pages.mdx) | Current | [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx), [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx) |


# App flow — the living hero (/docs/maintain/app-flow/living-hero)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0032](../adr/ADR-0032-the-heros-system-comes-alive.mdx),
  [ADR-0029](../adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

How the home page's hero works under ADR-0032. The system draws every ecosystem's orbit, a
living star, planet trails and a still nebula; it spins up on arrival, leans toward the pointer,
names its facts in one data line and sees a comet now and then. Sample values are invented
(ADR-0008). Phone width first.

The flow and each screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `living-hero.json` for the
flow, one `living-hero-screen-<n>.json` per screen.

## Entry points [#entry-points]

- **`/`**, from the header's wordmark, *Back to orbit* in the footer, the 404's *Back to the
  system* and any link to the home page. Everyone sees it.
- **`/#verse`** opens the Verse view directly; the system skips the spin-up there.

## Flow [#flow]

```mermaid
flowchart LR
  A["Arrives at /<br/>first time this session"] --> S["Spin-up<br/>star ignites, planets sweep in"]
  B["Arrives again<br/>or with reduced motion"] --> T["The system turns<br/>trails, star breathing"]
  S -->|1.2s| T
  T -->|pointer moves| L["Leans to the pointer<br/>nebula shifts"]
  T -->|now and then| C["A comet crosses<br/>every 20 to 30s"]
  T -->|points at a planet| P["Planet tooltip<br/>name, kind, latest"]
  P -->|click| O["The planet's overview"]
  T -->|points at an empty orbit| E["No planets yet<br/>an empty orbit's tooltip"]
  T -->|Zoom out to the Verse| V["The Verse view<br/>Back to the system returns"]
```

## Screens [#screens]

### 1. `The living hero` — `/`, at phone width [#1-the-living-hero---at-phone-width]

```mermaid
block-beta
  columns 4
  mark["Brand mark · Nepal Dev Verse"]:3 menu["☰"]
  system["The system · star with corona, five orbits, lodestar with its trail, nebula behind"]:4
  caption["Telemetry · 1 planet · 4 orbits waiting · 0 moons"]:3 zoom["Zoom out ↘"]:1
  head["Every package and project by Nepalese developers all over the world, documented to the version"]:4
  sub["Guides, APIs and release notes for npm, Composer, PyPI and Go"]:4
  search["⌕ Search packages, projects and pages"]:4
  legend["Legend · package · project · moon = version · dashed = unreleased"]:4
```

The system fills the top 310px: the star with its corona and turning rays, the five orbits (the
empty ones fainter, with their names on the upper left), each planet with its trail, and the
nebula behind, kept inside the system's area. Under it, the telemetry line and *Zoom out to
the Verse*; then the headline, subline, search button and legend, all still.

**States**

- Empty: with no public entries the five orbits are all empty, there are no trails, and the line
  reads `0 planets · 5 orbits waiting · 0 moons`.
- Loading: prerendered text first; the canvas draws after scripts load, spinning up on the first
  view of the session.
- Not found, refused, error: not applicable at `/`. If the canvas cannot draw, the text, the
  search button and the caption show on the plain background.
- Degraded:
  - with reduced motion the system is drawn once: no spin-up, breathing, rays, comet or lean;
    the trails, empty orbits and nebula stay, still;
  - with a touch pointer there is no lean;
  - without scripts there is no canvas and no caption; the search button is replaced by a link
    to the cards, as today;
  - without `sessionStorage` the spin-up runs on every visit.
- Success: the reader sees the whole shape of the site, opens a planet or zooms out.

### 2. `The living hero` — `/`, on a wide screen [#2-the-living-hero---on-a-wide-screen]

```mermaid
block-beta
  columns 6
  header["Brand mark · Nepal Dev Verse · Projects · llms.txt · GitHub · theme"]:6
  head["Every package and project by Nepalese developers all over the world, documented to the version"]:3 system["The system · leans toward the pointer · a comet now and then"]:3
  sub["Guides, APIs and release notes"]:3 orbits["Five orbits · npm · Composer · PyPI · Go · Projects"]:3
  search["⌕ Search packages, projects and pages ⌘K"]:3 tip["Pointing at an orbit · Go · No planets yet"]:3
  legend["Legend · package · project · moon = version · dashed = unreleased"]:3 caption["Telemetry · 1 planet · 4 orbits waiting · 0 moons · Zoom out to the Verse"]:3
```

The text column stands on the left, untouched; the system fills the right, centred at 70% of the
width. Moving the pointer over the hero leans the system up to ±0.05 of tilt and 8px, and shifts
the nebula 12px the other way. A comet crosses the upper part of the system, right of 52% of
the width, its tail pointing away from the star. Pointing near an empty orbit shows its name and
"No planets yet". The telemetry line sits beside *Zoom out to the Verse* at the lower right; in
the Verse view it gives way to *The Verse · one system so far*.

**States**

- Empty: as screen 1.
- Loading: as screen 1.
- Not found, refused, error: not applicable.
- Degraded: as screen 1; in a hidden tab, or with the hero scrolled away, everything pauses.
- Success: the system responds to the pointer, and a planet opens its overview.


# App flow — the living horizon (/docs/maintain/app-flow/living-horizon)

- **Status:** Current
- **Last updated:** 2026-11-03
- **Related ADRs:** [ADR-0037](../adr/ADR-0037-the-horizon-is-the-himalaya.mdx),
  [ADR-0030](../adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx),
  [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

How the end of every page moves under ADR-0030. The Horizon footer rises over the docs page's
sidebar and trajectory as the reader reaches it, and its sky is alive: twinkling stars, shooting
stars, the star rising with the scroll and drifting lit clouds. What stands under that sky, the
range, the flag and the entries' lights, is in [the Himalayan Horizon](./himalayan-horizon.mdx)
(ADR-0037). Sample values are invented (ADR-0008). Phone width first.

The flow and each screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `living-horizon.json` for the
flow, one `living-horizon-screen-<n>.json` per screen.

## Entry points [#entry-points]

- **The end of every page:** docs pages, the home page and the 404. Everyone sees it; there is
  nothing to open or switch.
- **Docs pages on a wide screen**, where the sidebar and the trajectory stand beside the page:
  they set below the horizon as it rises (screen 2). On phones neither stands beside the page.

## Flow [#flow]

```mermaid
flowchart LR
  R["Reading<br/>sidebar and trajectory in place"] -->|scrolls to the end| E["Horizon enters<br/>star rises, sidebar sets"]
  E -->|keeps scrolling| H["Horizon in view<br/>the sky loops"]
  H -->|scrolls up| E
  E -->|scrolls up| R
  H -->|a planet or a footer link| P["Another page"]
```

The loops run only while the footer is on screen; once it leaves, they pause where they are.

## Screens [#screens]

### 1. `The Horizon` — the end of any page, at phone width [#1-the-horizon--the-end-of-any-page-at-phone-width]

```mermaid
block-beta
  columns 4
  closing["You've reached the horizon. The Verse goes on."]:4
  stars["Twinkling stars · ☄ a shooting star now and then"]:4
  clouds["Lit clouds · three bands drifting, warm undersides"]:4
  ridge["⌂ observatory on the shoulder · ☀ the star rising · ⚑ the flag · the range"]:4
  planets["lodestar · Nepal Dev Verse Docs"]:4
  links["Search ⌘K · llms.txt · llms-full.txt · GitHub · Back to top ↑"]:4
  credit["Part of nepal-dev.com. Made with ❤️ by Puncoz Nepal."]:4
```

The closing line stands on the opaque ground above the scene, and the surface rows below it;
nothing moves behind text. In the scene, back to front: stars (some twinkling), two shooting stars on 14- and
23-second cycles, the star rising with the scroll, the far range, three cloud bands looping sideways
over 90, 140 and 200 seconds, the mid range and the near range with the flag waving on its summit and
the observatory standing still on its left shoulder, its slit open toward the star.

**States**

- Empty: with no public planets the planet row is left out; the scene and the links stay.
- Loading: none; the scene is prerendered SVG. Until scripts run, the loops are paused, so the
  scene shows as a still picture with the star risen.
- Not found: the 404 ends with the same Horizon.
- Refused, error: not applicable.
- Degraded:
  - with reduced motion nothing loops or rises;
  - in a browser without scroll-driven animations the star stands risen;
  - in the light theme the clouds take a cool grey body with soft warm undersides;
  - without scripts the scene stays still.
- Success: the reader reaches the end, sees the sky come alive and finds the links below it.

### 2. `The horizon rises` — the end of a docs page, on a wide screen [#2-the-horizon-rises--the-end-of-a-docs-page-on-a-wide-screen]

```mermaid
block-beta
  columns 6
  header["Brand mark · Nepal Dev Verse · Search ⌘K · GitHub · theme"]:6
  side["Sidebar · setting"]:1 last["The page's last lines · previous and next"]:4 toc["On this page · setting"]:1
  dusk["Dusk edge · the sidebar and the trajectory sink into it"]:6
  scene["The Horizon · over the sidebar and the contents"]:6
  surface["Planets · links · credit"]:6
```

The footer stacks above the sidebar and the trajectory, under the header. As it comes into view,
both drop up to 24px in step with the scroll, at full opacity so their text keeps its contrast
(ADR-0031), and its dusk edge, 96px from clear
to the ground colour, takes them; what is below the horizon is hidden. Scrolling up raises them
again. The page column scrolls as usual.

**States**

- Empty: not applicable; every docs page has a sidebar.
- Loading: none; prerendered.
- Not found, refused, error: not applicable.
- Degraded:
  - with reduced motion, or without scroll-driven animations, the sidebar and the trajectory
    do not drop; the horizon simply covers them at its dusk edge;
  - on a page shorter than the window the footer is in view on arrival, and the sidebar stands
    partly below the horizon; its upper part and its own scrolling still work.
- Success: at the end of the page nothing sits on the closing line or the scene, and the
  sidebar comes back as the reader scrolls up.


# App flow — multi-repository projects (/docs/maintain/app-flow/multi-repository-projects)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0024](../adr/ADR-0024-a-project-can-span-several-repositories.mdx),
  [ADR-0023](../adr/ADR-0023-sidebar-stations-open-one-at-a-time.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a reader sees of a project made of several repositories (ADR-0024). Sample values are
invented (ADR-0008): `acme` and its repositories are not real. Phone width first.

The flow and every screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`:
`multi-repository-projects.json` for the flow, one `multi-repository-projects-screen-<n>.json`
per screen.

## Entry points [#entry-points]

- The home page's planet card, search, a direct URL, or a repository's README linking to
  `/acme` or `/acme/use/latest/…`.
- Everyone sees the same; every project here is public (AGENTS.md §6.1).
- The per-page Markdown and `llms.txt` carry each page as today; a page in a repository
  folder sits under that folder in `llms.txt`.

## Flow [#flow]

```mermaid
flowchart LR
  H["Home planet card<br/>Project · 3 repositories"] -->|opens| O["Project overview<br/>repositories linked"]
  O -->|Use| U["Use track<br/>a station per repository"]
  O -->|Maintain| M["Maintain track<br/>shared pages + repository stations"]
  O -->|Frontend ↗| G["Repository on GitHub"]
  U -->|a repository's page| P["Docs page<br/>scale strip names the repository"]
  M -->|a repository's page| P
  P -->|sun or moon| U
  P -->|sun or moon| M
```

## Screens [#screens]

### 1. `Home planet card` — `/` [#1-home-planet-card--]

```mermaid
block-beta
  columns 4
  draw["ringed planet with moons released and dev"]:4
  kind["◉ Project · 3 repositories"]:4
  name["acme"]:4
  desc["Bookings for small studios."]:4
  links["[Use →] Maintain"]:4
```

The kind line adds the number of repositories; a one-repository project shows the kind alone,
as today.

**States**

- Empty: no project, no card (the home page's own empty state).
- Loading: none; the card is prerendered.
- Not found, refused, error: not applicable; a broken catalogue fails the build.
- Degraded: with reduced motion the planet does not turn.
- Success: the card opens the overview.

### 2. `Project overview` — `/acme` [#2-project-overview--acme]

```mermaid
block-beta
  columns 4
  kind["◉ Project"]:4
  name["acme"]:4
  desc["Bookings for small studios."]:4
  facts["Latest 2.0.0 · v2 · In development 2.1.0-dev.1"]:4
  repos["Repositories: Frontend, Backend, API"]:4
  links["[Use →] Maintain"]:4
  repolinks["Frontend ↗ · Backend ↗ · API"]:4
  draw["ringed planet with moons v2 and dev"]:4
```

The planet header (`src/components/docs/package-hero.tsx`) links each repository by name,
primary first; *API* has no `url`, so it is named without a link. Desktop: the text on the left,
the planet on the right, as today.

**States**

- Empty: a project without a released line shows *In development* only.
- Loading, refused, error: as every overview.
- Not found: an unknown slug gets the out-of-orbit 404.
- Degraded: a repository without a `url` shows its name only.
- Success: each repository link opens the repository in the same tab.

### 3. `Use track` — the sidebar on `/acme/use/v2/frontend/getting-started` [#3-use-track--the-sidebar-on-acmeusev2frontendgetting-started]

```mermaid
block-beta
  columns 4
  chip["◉ acme · Project"]:3 sw["☀ | ☾"]:1
  moon["full moon · v2 · 2.0.0 · Latest ▾"]:4
  top["◌ Overview of the Use track"]:4
  block:s1:4
    columns 4
    h1["◎ Frontend · 4 ▾ (open, current)"]:4
    p1["  ◉ Getting started (current)"]:4
    p2[" ○ Booking widget"]:4
  end
  block:s2:4
    columns 4
    h2["○ Backend · 3 ▸"]:4
  end
  block:s3:4
    columns 4
    h3["○ API · 6 ▸"]:4
  end
```

Each repository folder is a station titled with its name; one station is open at a time
(ADR-0023). The moon picker lists at most two moons, the latest line and `dev`.

**States**

- Empty: a repository with no `use/<id>/` has no station here.
- Loading: none; prerendered.
- Not found: a page in a removed line redirects to the same path in the released line.
- Refused, error: not applicable.
- Degraded: an unversioned project has no moon picker.
- Success: a moon opens the repository's page; its scale strip reads *Use ▸ Frontend*, with the
  line's moon and name beside *Use* (ADR-0029).

### 4. `Maintain track` — the sidebar on `/acme/maintain/architecture` [#4-maintain-track--the-sidebar-on-acmemaintainarchitecture]

```mermaid
block-beta
  columns 4
  chip["◉ acme · Project"]:3 sw["☀ | ☾"]:1
  arc1["◉ Architecture (current, spans the repositories)"]:4
  arc2["○ Releasing"]:4
  block:s1:4
    columns 4
    h1["○ Frontend · 5 ▸"]:4
  end
  block:s2:4
    columns 4
    h2["○ Backend · 7 ▸"]:4
  end
  block:s3:4
    columns 4
    h3["○ API · 2 ▸"]:4
  end
```

Pages about the whole project sit on the top-level arc, above the repository stations. Maintain
has no moon picker (it is not versioned).

**States**

- Empty: a project with no `maintain/` has no moon button in the planet row.
- Loading, not found, refused, error: as screen 3.
- Degraded: as screen 3.
- Success: a repository's station opens and the others close; a moon opens its page.


# App flow — one open station (/docs/maintain/app-flow/one-open-station)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0023](../adr/ADR-0023-sidebar-stations-open-one-at-a-time.mdx),
  [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx),
  [ADR-0027](../adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

How the sidebar's orbit stations open and close under ADR-0023: at most one open station
beside another, at every level. Everything else about stations is in
[Docs sidebars](./docs-sidebars.mdx), screen 1. Sample values are invented (ADR-0008):
`lodestar` is not a real package. Phone width first.

The flow and every screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `one-open-station.json` for
the flow, one `one-open-station-screen-<n>.json` per screen.

## Entry points [#entry-points]

- Any docs page with stations in its sidebar: on desktop the sidebar column, on phones the
  sidebar drawer from the header.
- Everyone sees the same. The per-page Markdown and `llms.txt` carry no sidebar.

## Flow [#flow]

```mermaid
flowchart LR
  R[Reader] -->|opens a page| A["Current station open<br/>others closed"]
  A -->|opens another station| B["That station open<br/>the current one closed"]
  B -->|closes it| C["Every station closed"]
  C -->|opens a station| B
  B -->|a moon in it| P["New page<br/>its station open"]
  B -->|a link elsewhere| Q["Other page<br/>its station open, the rest closed"]
  P --> A
  Q --> A
```

## Screens [#screens]

### 1. `Current station open` — the sidebar on `/lodestar/use/v0.1/install` [#1-current-station-open--the-sidebar-on-lodestarusev01install]

```mermaid
block-beta
  columns 4
  chip["● lodestar"]:3 sw["☀ | ☾"]:1
  moon["full moon · v0.1 · 0.1.4 · Latest ▾"]:4
  block:card:4
    columns 4
    h1["◎ Get started · 2 ▾ (open, the one card)"]:4
    p1["  ◉ Install (probe, tinted)"]:4
    p2[" ∘ Commands"]:4
  end
  h2["○ Reference · 3 ▸ (closed, a row)"]:4
  h3["○ Guides · 4 ▸ (closed, a row)"]:4
```

The orbit holding the current page is open, as the sidebar's one card; the others are closed
rows (ADR-0027).

**States**

- Empty: a track with no folders has no stations.
- Loading: none; the sidebar is prerendered open on the current path. Before scripts load,
  the chevrons do nothing.
- Not found: the out-of-orbit 404 has no sidebar.
- Refused: not applicable; every page is public.
- Error: not applicable at runtime.
- Degraded: with reduced motion, stations open and close without animation.
- Success: one station open, the current page's.

### 2. `Another station opened` — the reader opens Guides on the same page [#2-another-station-opened--the-reader-opens-guides-on-the-same-page]

```mermaid
block-beta
  columns 4
  chip["● lodestar"]:3 sw["☀ | ☾"]:1
  moon["full moon · v0.1 · 0.1.4 · Latest ▾"]:4
  h1["◎ Get started · 2 ▸ (a row, holds the current page)"]:4
  h2["○ Reference · 3 ▸ (a row)"]:4
  block:card:4
    columns 4
    h3["◎ Guides · 4 ▾ (open, the one card)"]:4
    g1[" ∘ Theming"]:4
    g2[" ∘ Keyboard shortcuts"]:4
    g3[" ◦ Recipes · 3 ▸ (nested, closed)"]:4
  end
```

Get started drops back to a row as Guides lifts into the card; its ring keeps the ecosystem
colour, because it still holds the current page. Opening the nested Recipes station closes any other nested station
inside Guides, and leaves Guides open. Closing Guides leaves every station closed. Following a
moon or any link to another page opens that page's stations and closes the rest (screen 1 for
the new page).

**States**

- Empty, loading, not found, refused, error: as screen 1.
- Degraded: as screen 1.
- Success: one station open at each level, the one the reader opened last.


# App flow — the overview's sidebar (/docs/maintain/app-flow/overview-sidebar)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0025](../adr/ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks.mdx),
  [ADR-0026](../adr/ADR-0026-the-moon-picker-on-an-overview-opens-a-lines-first-page.mdx),
  [ADR-0023](../adr/ADR-0023-sidebar-stations-open-one-at-a-time.mdx),
  [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What the sidebar shows on an entry's overview, `/<slug>`, under ADR-0025: the same sidebar as
a page of its default track, with an *Overview* item first in every track. Everything else
about stations is in [Docs sidebars](./docs-sidebars.mdx) and
[One open station](./one-open-station.mdx). Sample values are invented (ADR-0008): `lodestar`
is not a real package. Phone width first.

The flow and every screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `overview-sidebar.json` for
the flow, one `overview-sidebar-screen-<n>.json` per screen.

## Entry points [#entry-points]

- An entry's overview, `/<slug>`: from a planet card on the home page, a search result, the
  planet chip in the sidebar, or the *Overview* item in any of its tracks.
- On desktop the sidebar column; on phones the sidebar drawer from the header.
- Everyone sees the same. The per-page Markdown and `llms.txt` carry no sidebar.

## Flow [#flow]

```mermaid
flowchart LR
  E[Planet card or search] --> O["Overview<br/>Use sidebar, Overview current"]
  O -->|a moon in a station| U["Use page<br/>the same sidebar"]
  U -->|Overview item| O
  O -->|moon button| M["Maintain page<br/>Overview first"]
  U -->|moon button| M
  M -->|Overview item| O
  M -->|sun button| U
  O -->|moon picker: another line| L["That line's first page<br/>its sidebar"]
```

## Screens [#screens]

### 1. `Overview` — the sidebar on `/lodestar` [#1-overview--the-sidebar-on-lodestar]

```mermaid
block-beta
  columns 4
  chip["● lodestar"]:3 sw["☀ current | ☾"]:1
  moon["full moon · v0.1 · 0.1.4 · Latest ▾"]:4
  ov["◉ Overview (current, tinted)"]:4
  block:s1:4
    columns 4
    h1["○ Get started · 2 ▸ (closed)"]:4
  end
  block:s2:4
    columns 4
    h2["○ Reference · 3 ▸ (closed)"]:4
  end
  block:s3:4
    columns 4
    h3["○ Guides · 4 ▸ (closed)"]:4
  end
```

The sidebar of the latest Use line: the planet row with the sun current, the moon picker,
*Overview* as the current page on the top-level arc, then the line's stations, all closed. The
page beside it is unchanged: the planet header, then the entry's own overview. Opening a
station closes any other (ADR-0023); a moon in it opens that page with the same sidebar. The
moon picker lists every line, the latest checked; another line opens that line's first page,
since the overview is the same page in every line.

**States**

- Empty: an entry whose Use has no folders shows *Overview* and its top-level pages only.
- Loading: none; prerendered.
- Not found: an unknown slug gets the out-of-orbit 404, with no sidebar.
- Refused: not applicable; every page is public.
- Error: a malformed catalogue fails the build, so it never reaches readers.
- Degraded: search unavailable shows the dialog's notice; the sidebar works.
- Success: the reader sees the Use sidebar they will keep on every Use page.

### 2. `Maintain page` — the sidebar on `/lodestar/maintain/releasing` [#2-maintain-page--the-sidebar-on-lodestarmaintainreleasing]

```mermaid
block-beta
  columns 4
  chip["● lodestar"]:3 sw["☀ | ☾ current"]:1
  ov["○ Overview"]:4
  p1["◉ Releasing (current, tinted)"]:4
  block:s1:4
    columns 4
    h1["○ Architecture · 2 ▸ (closed)"]:4
  end
  block:s2:4
    columns 4
    h2["○ Decisions · 5 ▸ (closed)"]:4
  end
```

Maintain's sidebar, as today, with *Overview* first on the arc. The moon is current; the sun
opens the Use line's first page. *Overview* returns to screen 1.

**States**

- Empty, loading, not found, refused, error, degraded: as screen 1.
- Success: Maintain's stations, with the overview one click away.

### 3. `Maintain-only overview` — the sidebar on `/docs` [#3-maintain-only-overview--the-sidebar-on-docs]

```mermaid
block-beta
  columns 4
  chip["● Nepal Dev Verse Docs · Project"]:4
  ov["◉ Overview (current, tinted)"]:4
  p1["○ Maintainer documentation"]:4
  block:s1:4
    columns 4
    h1["○ ADRs · 25 ▸ (closed)"]:4
  end
  block:s2:4
    columns 4
    h2["○ Architecture · 2 ▸ (closed)"]:4
  end
  block:s3:4
    columns 4
    h3["○ App flows · 11 ▸ (closed)"]:4
  end
```

An entry with Maintain only, like this site: the overview shows Maintain's sidebar, with
*Overview* current above Maintain's own first page. The planet row is the chip alone, with no
sun or moon, and there is no moon picker, as on its Maintain pages today.

**States**

- As screen 1.
- Success: the same sidebar as every Maintain page of the entry.


# App flow — package and project navigation (/docs/maintain/app-flow/package-navigation)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx),
  [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx),
  [ADR-0010](../adr/ADR-0010-projects-document-themselves-through-a-submodule.mdx),
  [ADR-0025](../adr/ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a person sees and how they move through it. Sample values are invented (ADR-0008).
Phone width first; desktop differences are noted under each screen.

Every package and project has the same shape (ADR-0013, ADR-0015). Its overview is at
`/<slug>`, under the package hero, and it has two tracks: **Use**, for people using it, and
**Maintain**, for people who look after it. A package's Use track has one line per documented
release, at the URL segment of the name its `meta.json` gives (`v0.1`, `2024-lts`), plus `dev`
for the work in progress. The sidebar shows the current track and line only. At its top sit
the version menu (on Use pages of a versioned package) and, under it, the package name with the
Use | Maintain switch. The site header, its search and the theme switch are described in
[site pages](./site-pages.mdx).

The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `package-navigation.json` for the
flow, one `package-navigation-screen-<n>.json` per screen.

## Entry points [#entry-points]

- A row in the home page catalogue, or a search result.
- A README or registry badge linking to `/<slug>` or to a stable alias such as
  `/lodestar/use/latest/install`, which redirects to the line marked `latest` (or `dev` before
  the first release). `/lodestar/use` opens the first page of that line.
- A direct URL to a line: `/lodestar/use/v0.1/install`, `/lodestar/use/dev/install`. A line
  that does not exist (removed, or never there) redirects to the same path in `latest`.
- The Markdown version of any page: `/lodestar/use/v0.1/install.md`.
- Everyone sees every public package and project. Private projects have no pages here until the
  private-documentation ADR is approved; when it is, a signed-out visitor at a private URL gets
  the same 404 as for a page that does not exist, so the URL does not confirm the project exists.

## Flow [#flow]

```mermaid
flowchart LR
  E[Catalogue row or search] --> O["Overview<br/>/lodestar"]
  A["Alias<br/>/lodestar/use/latest/…"] -->|redirect| U
  R["Removed line<br/>/lodestar/use/v0.0/…"] -->|redirect| U
  O -->|hero or track switch: Use| U["Use · latest line<br/>/lodestar/use/v0.1/install"]
  O -->|hero or track switch: Maintain| M["Maintain<br/>/lodestar/maintain/releasing"]
  U -->|version menu: dev| N["Use · dev line<br/>banner: In development"]
  U -->|version menu: older line| G["Use · older line<br/>banner: Older version"]
  N -->|banner link| U
  G -->|banner link| U
  U -->|track switch| M
  M -->|track switch| U
  U -.->|page not in the chosen line| F["That line's first page"]
```

## Screens [#screens]

### 1. `Overview` — `/<slug>` [#1-overview--slug]

The package hero, then the package's own `index.mdx`, as its repository writes it. The sidebar
is the latest Use line's, as on screen 2, with *Overview* first and current; an entry without
Use shows Maintain's (ADR-0025, drawn in [the overview's sidebar](./overview-sidebar.mdx)). The
hero is drawn in [site pages](./site-pages.mdx).

```mermaid
block-beta
  columns 4
  title["▲ Nepal Dev Verse"]:2 search["⌕"] menu["☰"]
  block:drawer:4
    columns 4
    ver["v0.1 · 0.1.4 · Latest ▾"]:4
    name["lodestar"]:4
    track["Use (current) | Maintain"]:4
    ov["Overview (current)"]:4
    l1["Install"]:4
  end
  hero["package hero: lodestar · v0.1 · 0.1.4 · latest · Use · Maintain"]:4
  h1["lodestar"]:4
  body["the package's overview page"]:4
```

Desktop: the same, with the sidebar always visible.

**States**

- Empty: a package with one track shows no switch, only its name.
- Loading: none; prerendered.
- Not found: an unknown slug shows the site's 404.
- Refused: not applicable until private documentation exists (see Entry points).
- Error: a malformed catalogue field fails the build, so it never reaches readers.
- Degraded: search unavailable shows the dialog's error notice; everything else works.
- Success: the overview, with the Use sidebar the reader keeps on every Use page and Maintain
  one click away.

### 2. `Use page` — `/<slug>/use/<line>/<page>` [#2-use-page--sluguselinepage]

Phone width: the sidebar is a drawer; the version menu and track switch sit at its top.

```mermaid
block-beta
  columns 4
  title["▲ Nepal Dev Verse"]:2 search["⌕"] menu["☰"]
  block:drawer:4
    columns 4
    ver["v0.1 · 0.1.4 · Latest ▾"]:4
    name["lodestar"]:4
    track["Use | Maintain"]:4
    l1["Install"]:4
    l2["Commands"]:4
  end
  h1["Install"]:4
  stated["Documents lodestar 0.1.4"]:4
  body["page content"]:4
```

Desktop: the sidebar is always visible with the menu and switch at its top. Under the page
description, a line states the version the page documents (invariant 3).

**States**

- Empty: a line with only its index page shows that page and a one-link sidebar.
- Loading: none; prerendered.
- Not found: a missing page gets the site's 404.
- Refused: not applicable today.
- Error: the site's error page; no raw error text.
- Degraded: search unavailable shows the dialog's notice.
- Success: the page, with the current line selected and Use highlighted.

### 3. `Version menu` — opened from the sidebar [#3-version-menu--opened-from-the-sidebar]

```mermaid
block-beta
  columns 4
  cur["v0.1 · 0.1.4 · Latest ▾"]:4
  block:opts:4
    columns 4
    o1["v0.1 · 0.1.4 · Latest ✓"]:4
    o2["dev · 0.2.0-dev.3 · In development"]:4
  end
```

Lines are listed latest first, then `dev`, then older lines in the order of `use/meta.json`
`pages`, or newest version first. Each option shows the line's name and names its channel in
words, not by colour alone.

**States**

- Empty: a package with one line shows a menu with that one line.
- Success: choosing a line opens the same page in that line when it exists, otherwise that
  line's first page.

### 4. `In development page` — `/<slug>/use/dev/<page>` [#4-in-development-page--slugusedevpage]

```mermaid
block-beta
  columns 4
  h1["Install"]:4
  banner["In development — This page documents lodestar 0.2.0-dev.3, work in progress on the default branch. Read this page for 0.1.4, the latest release."]:4
  body["page content"]:4
```

Older lines show the same shape: "Older version — This page documents ledgerly 3.6.2. Read this
page for 4.0.1, the latest release."

**States**

- Success: the banner sits under the title and links to the same page in the latest line, or
  that line's first page. An unreleased package with no latest line shows the banner without
  the link.
- Other states: as the Use page.

### 5. `Maintain page` — `/<slug>/maintain/<page>` [#5-maintain-page--slugmaintainpage]

```mermaid
block-beta
  columns 4
  title["▲ Nepal Dev Verse"]:2 search["⌕"] menu["☰"]
  name["lodestar"]:4
  track["Use | Maintain"]:4
  h1["Releasing"]:4
  body["How a release is cut, from the default branch"]:4
```

The Maintain track is not versioned: it describes the repository's default branch, so it has
no version menu and no version line.

**States**

- Empty: a package without a Maintain track has no switch; its Maintain URLs get the 404.
- Other states: as the Use page.

### 6. `Demo page` — `/<slug>/use/<line>/demo` [#6-demo-page--sluguselinedemo]

Not published: how a demo runs needs its own ADR, since ADR-0011's embed takes only diagrams.
When a line has a `demo.mdx` page, the home page catalogue links to it.


# App flow — search and sharing (/docs/maintain/app-flow/search-and-sharing)

- **Status:** Current
- **Last updated:** 2026-11-03
- **Related ADRs:** [ADR-0035](../adr/ADR-0035-every-page-is-ready-for-search-and-sharing.mdx),
  [ADR-0034](../adr/ADR-0034-the-proxy-answers-unknown-paths-with-a-true-404.mdx),
  [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a person sees of a page before opening it, or outside it: the browser tab, a search result and
the card when a link is shared. Inside a page, one thing shows: its description, under its title. Sample values are invented (ADR-0008),
including the package `lodestar`. Phone width first.

The flow and the screens are drawn with Archify; the page shows them and its Markdown carries their
Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `search-and-sharing.json` for the flow and
`search-and-sharing-screen-1.json` to `-screen-5.json` for the screens.

## Entry points [#entry-points]

- **A search engine:** a person searches, and sees the page's title and description.
- **A shared link:** pasted into a chat or a post, which shows the page's card.
- **Any open page:** its title in the browser tab, in history and in bookmarks.
- **Not here:** the 404, which stays out of search; Markdown copies, `llms.txt`, `static.json` and
  diagram frames, which stay readable by tools but out of search results.

## Flow [#flow]

```mermaid
flowchart TB
  C["A search engine<br/>robots.txt, then the sitemap"] --> P["A page<br/>judged by where it sits"]
  P -->|home, latest line, no lines, Maintain, or only in an older line| I["Indexed<br/>its own canonical link"]
  P -->|older line, and also in latest| A["Canonical link<br/>to the same page in latest"]
  P -->|dev line or a template| N["noindex<br/>still readable by link"]
  I --> R["Search result<br/>title and description"]
  A -->|shown as the page in latest| R
  L["A shared link"] --> K["Share card<br/>title, description and image"]
```

## Screens [#screens]

### 1. Search result, at phone width [#1-search-result-at-phone-width]

```mermaid
block-beta
  columns 4
  site["docs.nepal-dev.com › lodestar › use › install"]:4
  title["Install — lodestar — Nepal Dev Verse"]:4
  desc["Add lodestar to a React project and open the command palette with one hook."]:4
```

How the result is laid out is the search engine's choice; the site supplies the words.

**States**

- Empty: not applicable; the build refuses a page without a description.
- Loading: not applicable.
- Not found: a removed page answers 404 and drops out over time.
- Refused: a `dev` page or a template is `noindex`, so it has no result.
- Error: not applicable.
- Degraded: with no `SITE_URL`, as on a preview or a local build, every page is `noindex`.
- Success: the reader opens the page. A search for an older version's page usually leads to the same
  page in latest, where the version menu is one click away.

### 2. Share card, at phone width [#2-share-card-at-phone-width]

```mermaid
block-beta
  columns 4
  image["The page's share image, screen 4"]:4
  title["Install — lodestar — Nepal Dev Verse"]:4
  desc["Add lodestar to a React project and open the command palette with one hook."]:4
  domain["docs.nepal-dev.com"]:4
```

The home page's card has its own image, screen 5. The layout is the sharing app's choice.

**States**

- Empty: not applicable; every page has an image and a description.
- Loading: the sharing app fetches the card; the site does nothing.
- Not found: an unknown path has no card of its own, only the title *Page not found*.
- Refused, error: not applicable.
- Degraded: with no `SITE_URL` the image's address is a local one, so the app shows no image. This
  is only ever a preview or a local build.
- Success: the card shows, and opening it leads to the page.

### 3. Browser tab, at phone width [#3-browser-tab-at-phone-width]

```mermaid
block-beta
  columns 4
  latest["Tab, latest line: Install — lodestar — Nepal Dev Verse"]:4
  older["Tab, older line: Install — lodestar 2.x LTS — Nepal Dev Verse"]:4
  dev["Tab, dev line: Install — lodestar dev — Nepal Dev Verse"]:4
  overview["Tab, overview: lodestar — Nepal Dev Verse"]:4
  home["Tab, home page: Nepal Dev Verse — packages and projects by Nepalese developers"]:4
```

**States**

- Empty, loading, refused, error, degraded: not applicable; the title is in the page's HTML.
- Not found: *Page not found — Nepal Dev Verse*.
- Success: the tab, history and bookmarks name the page, its package and the site.

### 4. A page's share image, at its fixed 1200 by 630 [#4-a-pages-share-image-at-its-fixed-1200-by-630]

```mermaid
block-beta
  columns 4
  brand["The brand mark and Nepal Dev Verse, top left, on the still dark star field"]:4
  kicker["The entry's planet mark · lodestar · Use · v3.2 with its moon"]:4
  title["Install"]:4
  desc["Add lodestar to a React project and open the command palette with one hook."]:4
  domain["docs.nepal-dev.com"]:4
```

Always in the dark theme's colours, because an image cannot follow the reader's theme. A project has
a ringed planet and a package a solid one, as everywhere on the site. Maintain has no moon, and a
long title is set smaller rather than cut.

**States**

- Empty: a page outside a track, such as an overview, has no track or moon in its kicker.
- Loading: none; every image is made at build.
- Not found: an unknown path's image address answers 404.
- Refused, error: a font that cannot be fetched fails the build rather than publishing a wrong image.
- Degraded: with no `SITE_URL` the image leaves out the domain.
- Success: the image shows in the sharing app's card.

### 5. The home page's share image, at its fixed 1200 by 630 [#5-the-home-pages-share-image-at-its-fixed-1200-by-630]

```mermaid
block-beta
  columns 4
  brand["The brand mark and Nepal Dev Verse, top left, on the still dark star field"]:4
  line["Every package and project by Nepalese developers all over the world, documented to the version."]:2
  system["On the right: the star, its orbits and a planet on each, still, clear of the text"]:2
  domain["docs.nepal-dev.com"]:4
```

**States**

- Empty: with nothing documented, the orbits are drawn with no planets on them.
- Loading: none; the image is made at build.
- Not found, refused: not applicable.
- Error: as screen 4.
- Degraded: as screen 4.
- Success: the image shows in the sharing app's card.


# App flow — the sidebar's scale ladder (/docs/maintain/app-flow/sidebar-scale-ladder)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0027](../adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx),
  [ADR-0023](../adr/ADR-0023-sidebar-stations-open-one-at-a-time.mdx),
  [ADR-0025](../adr/ADR-0025-the-overview-has-the-same-sidebar-as-its-tracks.mdx),
  [ADR-0019](../adr/ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

How the docs sidebar is drawn under ADR-0027. Each level is a smaller body than the one above it:
the planet (the entry), its moon (the version line), landmark satellites (top-level pages),
belts (groups), orbits (folders) and satellites (pages), with the current page as the probe.
Only the open orbit is a card. Sample values are invented (ADR-0008): `lodestar` is not a real
package; this site's own Maintain track is shown with its real sections. Phone width first.

The flow and every screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `sidebar-scale-ladder.json`
for the flow, one `sidebar-scale-ladder-screen-<n>.json` per screen.

## Entry points [#entry-points]

- Every docs page: on desktop the sidebar column, on phones the sidebar drawer from the header.
- Everyone sees the same. The per-page Markdown and `llms.txt` carry no sidebar.

## Flow [#flow]

```mermaid
flowchart LR
  R[Reader opens a page] --> A["Its orbit lifted as the card<br/>other orbits as rows"]
  A -->|opens a closed orbit| B["That orbit lifted<br/>the card drops back to a row"]
  B -->|closes it| C["No card<br/>every orbit a row"]
  C -->|opens an orbit| B
  A -->|a satellite or a landmark| P["New page<br/>its orbit lifted"]
  B -->|a satellite in it| P
  A -->|an orbit link| I["That folder's index page"]
  P --> A
  I --> A
```

## Screens [#screens]

### 1. `Maintain page` — the sidebar on `/docs/maintain/prd/diagrams` [#1-maintain-page--the-sidebar-on-docsmaintainprddiagrams]

```mermaid
block-beta
  columns 4
  chip["◍ Nepal Dev Verse Docs · Project"]:4
  ov["• Overview (landmark)"]:4
  md["• Maintainer documentation (landmark)"]:4
  b1["DECISIONS ┈┈┈┈ belt"]:4
  o1["○ ADRs · 25"]:4
  b2["DESIGN ┈┈┈┈ belt"]:4
  o2["○ Architecture · 1"]:4
  o3["○ App flows · 11"]:4
  block:card:4
    columns 4
    h1["◎ Product requirements · 6 ▾ (the one card)"]:4
    s1["  ∘ The ADR constellation"]:4
    s2["  ◉ Diagrams (probe, tinted)"]:4
    s3["  ∘ Docs sidebars"]:4
  end
  o4["○ API · 1"]:4
  o5["○ Data flow diagrams · 1"]:4
  b3["SECURITY ┈┈┈┈ belt"]:4
  o6["○ Access control (orbit link)"]:4
  b4["TEMPLATES ┈┈┈┈ belt"]:4
  o7["○ Templates · 11"]:4
```

The planet row, then the two landmarks at full size, then the belts with their orbits. Only
*Product requirements* is a card, because it holds the current page; its border takes the
ecosystem colour. *Access control* holds only its index, so it is an orbit link with no count.
The rows between *Data flow diagrams* and *Access control* (Sequence diagrams, State machines,
ERD) are left out of the drawing.

**States**

- Empty: a track with no folders shows only its landmarks; a track without separators shows no
  belts.
- Loading: none; prerendered with the current orbit lifted. Before scripts load, the chevrons
  do nothing.
- Not found: the out-of-orbit 404 has no sidebar.
- Refused: not applicable; every page is public.
- Error: a malformed `meta.json` fails the build, so it never reaches readers.
- Degraded: with reduced motion an orbit lifts and drops without animation. A project has no
  ecosystem colour, so its tint is the signal teal.
- Success: one card, the current page's orbit, with the probe on it.

### 2. `Another orbit opened` — the reader opens ADRs on the same page [#2-another-orbit-opened--the-reader-opens-adrs-on-the-same-page]

```mermaid
block-beta
  columns 4
  chip["◍ Nepal Dev Verse Docs · Project"]:4
  ov["• Overview (landmark)"]:4
  md["• Maintainer documentation (landmark)"]:4
  b1["DECISIONS ┈┈┈┈ belt"]:4
  block:card:4
    columns 4
    h1["◎ ADRs · 25 ▾ (the one card)"]:4
    cst["constellation: 25 moons phased by status"]:4
    rd["ADR-0027 · The sidebar is a scale ladder"]:4
  end
  b2["DESIGN ┈┈┈┈ belt"]:4
  o2["○ Architecture · 1"]:4
  o3["○ App flows · 11"]:4
  o4["○ Product requirements · 6 (holds the page)"]:4
```

*ADRs* lifts into the card and shows its constellation (ADR-0019); *Product requirements* drops
back to a row, its ring still in the ecosystem colour because it holds the current page. Closing
*ADRs* leaves no card.

**States**

- As screen 1.
- Success: one card, the orbit the reader opened last.

### 3. `Use page with a nested orbit` — the sidebar on `/lodestar/use/v0.1/guides/recipes/forms` [#3-use-page-with-a-nested-orbit--the-sidebar-on-lodestarusev01guidesrecipesforms]

```mermaid
block-beta
  columns 4
  chip["● lodestar · npm package"]:3 sw["☀ | ☾"]:1
  moon["full moon · v0.1 · 0.1.4 · Latest ▾"]:4
  ov["• Overview (landmark)"]:4
  in["• Install (landmark)"]:4
  o1["○ Reference · 3"]:4
  block:card:4
    columns 4
    h1["◎ Guides · 4 ▾ (the one card)"]:4
    s1["  ∘ Theming"]:4
    n1["  ◦ Recipes · 2 ▾ (nested orbit, no inner card)"]:4
    s2["      ◉ Forms (probe, tinted)"]:4
    s3["      ∘ Tables"]:4
  end
  o2["○ Migrating · 2"]:4
```

A package line without separators: no belts. *Recipes* is a nested orbit inside the *Guides*
card, opened in place with its satellites indented; there is no card inside the card. Opening
another nested orbit in *Guides* closes *Recipes* (ADR-0023).

**States**

- As screen 1.
- Success: the current page's orbit and nested orbit open, the probe on *Forms*.


# App flow — site pages: root URLs, header and docs pages (/docs/maintain/app-flow/site-pages)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx),
  [ADR-0016](../adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx),
  [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx),
  [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx),
  [ADR-0014](../adr/ADR-0014-home-page-is-a-search-first-release-map.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a person sees and how they move through it: the root URLs, the header and the docs pages
(ADR-0015), drawn in the site's solar-system look (ADR-0017). The look's shared pieces, the
theme switch, the planet header, the sidebar's planet row and moon picker, the notices, the
footer and the 404, are drawn in [The solar system](./solar-system.mdx); the sidebar's stations
and "On this page" in [Docs sidebars](./docs-sidebars.mdx). Sample values are
invented (ADR-0008): `lodestar`, `ledgerly` and `orbit-board` are not real packages or projects.
Phone width first; desktop differences are noted under each screen.

Every package and project lives at `/<slug>`. Inside it, **Use** holds the user docs, one line
per release, each named by the package, plus `dev` for work in progress, and **Maintain**
holds the maintainer docs. This
site is the project `docs`: its overview is `/docs` and its ADRs and design documents are its
Maintain track, `/docs/maintain/…`. Every page, the home page included, shares one header with
the orrery theme switch; docs pages add a search button, and use the home page's colours and
type without its motion.

The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `site-pages.json` for the
flow, one `site-pages-screen-<n>.json` per screen.

## Entry points [#entry-points]

- The home page: a planet card, a planet on the system or a search result opens `/<slug>` or one of its
  pages.
- The header on every page: the wordmark (home), Packages and Projects (their groups on the home
  page, `/#packages` and `/#projects`), `llms.txt`, GitHub. On docs pages, the search button; on
  every page, `⌘K` opens the search dialog (on the home page, the hero's button opens it too).
- A README or registry badge: `/<slug>` or the stable `/<slug>/use/latest/<page>`.
- A direct URL: `/<slug>/use/v1.4/install`, `/<slug>/use/dev/install`, `/<slug>/maintain/releasing`,
  or the Markdown version with `.md`.
- Everyone sees every public package and project. Private projects have no pages until the
  private-documentation ADR; a private URL then gets the same 404 as a missing page.

## Flow [#flow]

```mermaid
flowchart TB
  V[Visitor] --> H["Home /"]
  V -->|badge or link| O
  H -->|card, planet or result| O["Package overview<br/>/lodestar · planet header"]
  H -->|hero button or ⌘K| S
  P -->|header: search or ⌘K| S["Search dialog"]
  S -->|result| P
  O -->|planet header: Use| U["Use page · latest line<br/>/lodestar/use/v1.4/install"]
  O -->|planet header: Maintain| M["Maintain page<br/>/lodestar/maintain/releasing"]
  A["/lodestar/use/latest/… or /lodestar/use"] -->|redirect| U
  U -->|moon picker: dev| N["Use page · dev<br/>notice: new moon"]
  U -->|moon picker: older line| G["Use page · legacy line<br/>notice: crescent"]
  N -->|notice link| U
  G -->|notice link| U
  U <-->|day/night switch| M
  P["Any page"] -->|header: theme switch| P
  H -->|card: Nepal Dev Verse Docs| D["Site overview /docs"]
  D -->|Maintain| DM["/docs/maintain/adr/…"]
```

## Screens [#screens]

### 0. `Header` — on every page [#0-header--on-every-page]

```mermaid
block-beta
  columns 6
  mark["▲ Nepal Dev Verse"]:2 search["⌕"] gh["GitHub"] theme["orrery"] menu["☰"]
```

Phone width: the wordmark (the brand mark: the mountain and the flag, ADR-0036),
then 36px icon buttons:
search (docs pages only), GitHub, the theme switch (40px wide) and, on docs pages, a menu button that opens the sidebar. The nav links are hidden; on
the home page its own sections carry them.

Desktop: wordmark · Packages · Projects · `llms.txt` · a search button showing `⌘K` (docs pages
only; the home page's hero holds its search) · GitHub · the theme switch. Sticky. On docs pages
it carries a hairline border; on the home page it gains one once the page scrolls.

**States**

- Empty: with no package, Packages is not shown; with no project, Projects is not shown.
- Loading: none; prerendered. The theme switch shows the current theme from first paint.
- Not found, Refused: not applicable.
- Error: none at runtime.
- Degraded: search unavailable shows the dialog's notice; without scripts the search trigger and
  the theme switch don't respond, and the page keeps the default dark theme.
- Success: the switch flips light and dark on the spot and the choice holds on the next page and
  the next visit.

### 1. `Package overview` — `/<slug>` [#1-package-overview--slug]

```mermaid
block-beta
  columns 4
  hdr["▲ Nepal Dev Verse   ⌕ orrery ☰"]:4
  block:hero:4
    columns 4
    kind["● npm package"]:4
    name["lodestar"]:4
    desc["Keyboard-first command palette for React."]:4
    facts["Latest 1.4.2 · v1.4 · In development 2.0.0-dev.4 · Older 2024 LTS"]:4
    use["Use →"] maint["Maintain"] reg["Registry ↗"] repo["Repository ↗"]
    draw["planet with labelled moons v1.4 · dev · 2024 LTS"]:4
  end
  body["the package's own overview page"]:4
```

The planet header ([The solar system](./solar-system.mdx), screen 2): the planet mark and a
faint wash take the ecosystem colour; a project is a ringed planet. Desktop: the text on the
left, the planet and its labelled moons on the right; the sidebar shows the planet row and its
stations, "On this page" the overview's headings on its trajectory.

**States**

- Empty: an unreleased package reads Latest "unreleased" and draws only its dashed `dev` moon;
  a project without lines has no fact sheet and no moons; a missing track, registry or
  repository has no link.
- Loading: none; prerendered.
- Not found: an unknown slug shows the site's 404.
- Refused: not applicable until private documentation exists.
- Error: a malformed catalogue field fails the build.
- Degraded: as the header.
- Success: the reader sees what the package is, its current and unreleased versions, and both
  tracks one click away.

### 2. `Use page` — `/<slug>/use/<line>/<page>` [#2-use-page--sluguselinepage]

```mermaid
block-beta
  columns 4
  hdr["▲ Nepal Dev Verse   ⌕ orrery ☰"]:4
  block:drawer:4
    columns 4
    chip["● lodestar · npm package"]:3 track["☀ | ☾"]:1
    ver["● v1.4 · 1.4.2 · Latest ▾"]:4
    st["◎ Get started · 2 ▾"]:4
    l1[" ◉ Install"]:4
    l2[" ○ Commands"]:4
  end
  bar["◔ Add the package · 4 min left ▾"]:4
  h1["Install"]:4
  stated["● Documents lodestar 1.4.2"]:4
  body["page content · code in JetBrains Mono"]:4
```

The drawer is the sidebar, opened from the header's menu button. Its top holds the planet row
(the chip linking to the overview, a sun for Use and a moon for Maintain) and the moon picker;
below, each folder is an orbit station whose pages are moons on an arc, the current page the
teal planet ([Docs sidebars](./docs-sidebars.mdx), screen 1). Under the header, the "On this
page" bar shows the reading position and time left (screen 3 there). The sun, moon and dot
characters in the wireframes stand for drawn SVG marks. Desktop: the sidebar on the left, the
page in the middle, the trajectory on the right. Headings in Bricolage Grotesque, text in Onest,
code on the panel colour.

**States**

- Empty: a line with only its index page shows that page and a one-link sidebar.
- Loading: none; prerendered.
- Not found: a missing page gets the site's 404; a removed line redirects to the same page in
  `latest`.
- Refused: not applicable today.
- Error: the site's error page; no raw error text.
- Degraded: as the header.
- Success: the page, with its line selected and Use highlighted.

### 3. `Moon picker` — opened from the sidebar [#3-moon-picker--opened-from-the-sidebar]

```mermaid
block-beta
  columns 4
  cur["full moon · v1.4 · 1.4.2 · Latest ▾"]:4
  block:opts:4
    columns 4
    o1["full moon · v1.4 · 1.4.2 · Latest ✓"]:4
    o2["dashed new moon · dev · 2.0.0-dev.4 · In development"]:4
    o3["crescent · 2024 LTS · 0.9.3 · Older version"]:4
  end
```

Latest first, then `dev`, then older lines in the order `use/meta.json` gives, or newest
version first. Each option shows its line's moon, the line's name as the package set it, its
version, and its channel in words.

**States**

- Empty: an unreleased package lists only `dev`.
- Success: choosing a line opens the same page in that line when it exists, otherwise that
  line's first page.

### 4. `In development or older page` — `/<slug>/use/dev/<page>`, `/<slug>/use/2024-lts/<page>` [#4-in-development-or-older-page--slugusedevpage-sluguse2024-ltspage]

```mermaid
block-beta
  columns 4
  h1["Install"]:4
  banner["dashed new moon · In development. This page documents lodestar 2.0.0-dev.4, work in progress on the default branch. Read this page for 1.4.2, the latest release."]:4
  body["page content"]:4
```

An older line shows a crescent and reads "Older version. This page documents lodestar 0.9.3.
Read this page for 1.4.2, the latest release."

**States**

- Success: the notice links to the same page in `latest`, or that line's first page. An
  unreleased package's `dev` notice has no link.
- Other states: as the Use page.

### 5. `Maintain page` — `/<slug>/maintain/<page>` [#5-maintain-page--slugmaintainpage]

```mermaid
block-beta
  columns 4
  hdr["▲ Nepal Dev Verse   ⌕ orrery ☰"]:4
  chip["● lodestar · npm package"]:4
  track["☀ Use | ☾ Maintain"]:4
  h1["Releasing"]:4
  body["How a release is cut from the default branch"]:4
```

Not versioned: no moon picker and no version line.

**States**

- Empty: a package without a Maintain track has no switch; its Maintain URLs get the 404.
- Other states: as the Use page.

### 6. `Site overview` — `/docs` [#6-site-overview--docs]

```mermaid
block-beta
  columns 4
  hdr["▲ Nepal Dev Verse   ⌕ orrery ☰"]:4
  block:hero:4
    columns 4
    kind["ringed planet · Project"]:4
    name["Nepal Dev Verse Docs"]:4
    desc["This documentation site: how it is organised, built and decided."]:4
    maint["Maintain"]:2 repo["Repository ↗"]:2
    draw["ringed planet, no moons"]:4
  end
  body["what the site is · where decisions and design documents live"]:4
```

The site's own entry has the project's planet header with a Maintain link and its repository. Its Maintain
track holds
the ADRs, architecture, app flows, PRDs, API, data flow, sequence, state, ERD, RBAC, security
and templates, in today's order.

**States**

- Empty: not applicable; the site always has its Maintain track.
- Other states: as the package overview.

### 7. `Theme switch` and `Footer` [#7-theme-switch-and-footer]

Drawn in [The solar system](./solar-system.mdx): the orrery theme switch (screen 1) and, below
every docs page, the full Horizon footer (screen 5).


# App flow — the solar system (/docs/maintain/app-flow/solar-system)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0030](../adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx),
  [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx),
  [ADR-0016](../adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx),
  [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx),
  [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

The look every page shares (ADR-0017). The home page's own screens are in
[Home page](./home-page.mdx); the routes, header and docs page layout are in
[Site pages](./site-pages.mdx); the sidebar's stations and "On this page" in
[Docs sidebars](./docs-sidebars.mdx). Sample values are invented (ADR-0008): `lodestar`, `ledgerly`
and `orbit-board` are not real packages or projects. Phone width first; desktop differences are
noted under each screen.

## The marks [#the-marks]

One metaphor, stated once and used everywhere:

| Mark | Means | Where |
|---|---|---|
| The star, labelled "nepal-dev.com" | the community | the home page's system, the footer's horizon, the 404 |
| An orbit | an ecosystem | the home page's system |
| A solid planet in an ecosystem colour, its night side shaded | a package | the system, cards, planet header, sidebar chip, footer |
| A ringed planet | a project | the same places |
| A full moon | the latest release | cards, planet header, moon picker, version line, Every moon |
| A small orbit with a planet on it | a section of pages, an orbit station | the docs sidebar |
| A moon dot on an arc | a page; the current page is the teal planet | the docs sidebar |
| A small planet riding a curved path | the reader's place on the page | "On this page" |
| A crescent | an older release | the same places |
| A dashed new moon | `dev`, in development | the same places |
| The day side, a drawn sun | Use | Two sides, the sidebar's switch |
| The night side, a drawn moon | Maintain | the same places |

The hero's legend teaches these once. Every mark is drawn SVG (`src/components/planet.tsx`):
`PlanetMark`, `MoonPhase` and `PlanetSystem`. The star uses `--home-star`, an unlit face
`--home-night`.

The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `solar-system.json` for the
flow, one `solar-system-screen-<n>.json` per screen.

## Entry points [#entry-points]

- The theme switch and the footer are on every page. The planet header opens every package and
  project overview; the sidebar's planet row and moon picker are on every page
  inside a package or project; the notices are on `dev` and older lines; the 404 is at every
  unknown path.
- Everyone sees the same pages.

## Flow [#flow]

```mermaid
flowchart TB
  Any["Any page"] -->|theme switch| Any
  Any -->|footer planet link| O["Planet header<br/>/lodestar"]
  O -->|Use →| P["Docs page<br/>/lodestar/use/v0.1/install"]
  P -->|day/night switch| M["Maintain page"]
  P -->|moon picker: dev| D["Docs page · dev<br/>new-moon notice"]
  D -->|notice link| P
  Any -->|unknown URL| L["Out of orbit<br/>404"]
  L -->|search| S["Search dialog"]
  L -->|Back to the system| H["Home /"]
  Any -->|footer: Back to orbit / Back to top| Any
```

## Screens [#screens]

### 1. `Theme switch` — the header, every page [#1-theme-switch--the-header-every-page]

```mermaid
block-beta
  columns 2
  dark["Dark, the night side: sun behind the planet, small; planet a thin crescent · name: Switch to day side (light theme)"]:1
  light["Light, the day side: sun in front; planet fully lit · name: Switch to night side (dark theme)"]:1
```

A 40 × 36px button (`src/components/theme-switch.tsx`): a tilted orbit, a sun on it, a planet
with a terminator. A click switches the theme; the sun moves along its orbit and the shadow
sweeps across the planet over half a second. A tooltip under the button repeats its accessible
name in short ("Night side · switch to day").

**States**

- Before hydration: the drawing follows the `dark` class next-themes sets before paint, so it
  never flashes; the accessible name starts as the dark one.
- Hover or focus: the tooltip shows (not on touch screens).
- Degraded: with reduced motion the drawing switches instantly. Without scripts the button does
  nothing and the site stays dark.
- Success: the theme and the drawing change together, and the choice holds across pages and
  visits in that browser.

### 2. `Planet header` — `/lodestar` [#2-planet-header--lodestar]

```mermaid
block-beta
  columns 4
  kind["● npm package"]:4
  name["lodestar"]:4
  desc["A command palette for React apps."]:4
  facts["Latest 0.1.4 · v0.1 · In development 0.2.0-dev.3"]:4
  links["[Use →] Maintain · Registry ↗ · Repository ↗"]:4
  draw["planet with labelled moons v0.1 and dev"]:4
```

Above every overview (`src/components/docs/package-hero.tsx`), on the panel colour with a wash of
the ecosystem colour from the right. Desktop: the text on the left, the planet and its moons on
the right.

**States**

- A project: a ringed planet; without lines, no fact sheet and no moons.
- No released line: Latest reads "unreleased"; only the dashed `dev` moon.
- Not found: an unknown slug gets the 404.
- Loading, Refused, Error: not applicable; prerendered.
- Success: Use → opens the current line's first page.

### 3. `Sidebar top` — inside a package or project [#3-sidebar-top--inside-a-package-or-project]

```mermaid
block-beta
  columns 4
  chip["● lodestar · npm package"]:3 sw["☀ | ☾"]:1
  moon["full moon · v0.1 · 0.1.4 · Latest ▾"]:4
  st["◎ Get started · 2 ▾ — the open station"]:4
```

The planet row: the planet chip links to the overview; beside it a sun for Use and a moon for
Maintain, shown when both tracks exist, each named "Use, the day side" or "Maintain, the night
side" with a tooltip; the current side is raised and, on the day side, its sun takes the star's
colour. The moon picker under it is Fumadocs' version menu with each line's moon as its icon.
The pages below are orbit stations ([Docs sidebars](./docs-sidebars.mdx), screen 1).

**States**

- One track: no sun and moon.
- Maintain: no moon picker (Maintain is not versioned).
- Success: the sun, the moon and the picker open the same page on the other side or line, when
  it exists.

### 4. `Version notice` — on `dev` and older lines [#4-version-notice--on-dev-and-older-lines]

```mermaid
block-beta
  columns 4
  notice["dashed new moon · In development. This page documents lodestar 0.2.0-dev.3, work in progress on the default branch. Read this page for 0.1.4, the latest release."]:4
```

An older line shows a crescent and "Older version." The latest line shows a single quiet line
instead: a full moon and "Documents lodestar 0.1.4".

**States**

- No released line: the `dev` notice has no link.
- Success: the link opens the same page in the latest line, or its first page.

### 5. `Horizon footer` — every page [#5-horizon-footer--every-page]

```mermaid
block-beta
  columns 4
  close["You've reached the horizon. The Verse goes on."]:4
  scene["The Himalaya · twinkling stars, shooting stars, the star rising, clouds, the flag on the summit, an observatory"]:4
  planets["● lodestar  ● ledgerly  ● pykettle  ○ orbit-board  ○ Nepal Dev Verse Docs"]:4
  links["Search ⌘K · llms.txt · llms-full.txt · GitHub · Back to orbit"]:4
  credit["Part of nepal-dev.com. Made with ❤️ by Puncoz Nepal."]:4
```

`src/components/horizon-footer.tsx`, the same on every page: the closing line (its *The Verse* links to
the Verse view, [the closing line](./horizon-closing-line.mdx)), the scene, then the surface rows. The scene is a living dusk sky
([The living horizon](./living-horizon.mdx), screen 1). On docs pages it runs across the full
width and rises over the sidebar and the trajectory, and its last link reads "Back to top"
instead of "Back to orbit". The links wrap on phones.

**States**

- Empty: with no public entries, the planet row is left out.
- Degraded: with reduced motion, Back to orbit jumps instead of scrolling and the sky is still.
  Without scripts, Search and Back to orbit do nothing and the sky is still; the links work.
- Success: a planet link opens its overview; Search opens the dialog; Back to orbit (Back to top
  on docs pages) returns to the top.

### 6. `Out of orbit` — any unknown path [#6-out-of-orbit--any-unknown-path]

```mermaid
block-beta
  columns 4
  draw["a planet that has left its dashed orbit around the star"]:4
  h1["This page drifted out of orbit."]:4
  help["It may have moved to another version or been renamed. Search for it, or start again from the system."]:4
  field["⌕  Search packages, projects and pages"]:4
  back["Back to the system →"]:4
```

`src/app/not-found.tsx`, with the home page's header (its anchors lead to `/#packages` and
`/#projects`) and the full footer.

**States**

- Degraded: without scripts the search button does nothing; "Back to the system" still works.
- Success: the reader searches or returns home. The page shows no part of the requested path.


# App flow — the universe theme (/docs/maintain/app-flow/universe-theme)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0029](../adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx),
  [ADR-0027](../adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

How the Verse reaches every page under ADR-0029, in three stages: **identity and sky** (screen 1),
**zoom** (screens 2 to 5) and **words** (the table at the end). The Verse is the sky around the
one system; readers move through one scale ladder: Verse, System, Planet, Side and moon, Orbit,
Satellite, Probe. Sample values are invented (ADR-0008): `lodestar` is not a real package, and the
private planets are the three invented names already on the home page. Phone width first.

The flow and every screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `universe-theme.json` for the
flow, one `universe-theme-screen-<n>.json` per screen.

## Entry points [#entry-points]

- **Every page** (stage 1): the brand mark in the header, the still sky behind the page, the
  site icon in the browser tab.
- **Every docs page** (stage 2): the scale strip above the title.
- **The home page** (stage 2): *Zoom out to the Verse* on the system; a planet card opens its
  overview with the morph.
- **`/#verse`** (stage 2): the home page opened in the Verse view, from the strip's *Verse*, the
  footer's closing line or a shared link.
- Everyone sees the same. The Markdown surfaces (`/<page>.md`, `llms.txt`, `llms-full.txt`) carry
  none of it.

## Flow [#flow]

```mermaid
flowchart LR
  X["Search, a link, a registry"] --> G["Page in an orbit<br/>scale strip"]
  V["Verse view<br/>/#verse"] -->|Back to the system| S["System<br/>home page"]
  S -->|Zoom out to the Verse| V
  S -->|planet card · morph| P["Planet<br/>overview"]
  P -->|strip: System · zoom out| S
  P -->|a page · zoom in| G
  G -->|strip: planet · zoom out| P
```

From any docs page, the strip's *Verse* also opens the Verse view directly (screen 2).

## Screens [#screens]

### 1. `Docs page` — the sky and the mark, on `/lodestar/use/v0.1/guides/forms` (stage 1) [#1-docs-page--the-sky-and-the-mark-on-lodestarusev01guidesforms-stage-1]

```mermaid
block-beta
  columns 4
  mark["Brand mark · Nepal Dev Verse"]:2 search["⌕"] menu["☰"]
  skyl["· sky ·"]:1 title["Forms"]:2 skyr["· sky ·"]:1
  skyl2["·"]:1 body["Reading column · plain ground, no stars behind text"]:2 skyr2["·"]:1
  skyl3["· ·"]:1 code["npm install lodestar"]:2 skyr3["· ·"]:1
  foot["Footer · Back to top"]:4
```

The header shows the brand mark, nepal-dev.com's mountain and flag (ADR-0036), beside *Nepal Dev
Verse*. The still sky fills the page's edges and the band behind the
header, and thins to nothing before the reading column, the sidebar's rows and "On this page".
The same mark is the browser tab's icon and sits on every share image. The Verse mark, a
star-coloured centre inside two tilted orbits with a teal planet, is the Verse's place mark in the
scale strip.

**States**

- Empty: not applicable; every page has the sky and the mark.
- Loading: none; the sky is server-rendered SVG, present in the first paint and without scripts.
- Not found: the 404 stands on the same sky.
- Refused: not applicable; every page is public.
- Error: not applicable; the field is built from a fixed seed at build time.
- Degraded: reduced motion changes nothing, because the sky never moves. In the light theme the
  field is fine graphite specks, like a printed star chart. Where the content fills the width (most
  laptops on docs pages, every phone) there are no edges to fill, so the sky shows only in the
  header, in the gap between the wordmark and the buttons; the narrowest phones have no gap and no
  stars. The page's edges fill once the screen is wider than the content column.
- Success: one sky and one mark on every page; no text crosses a star.

### 2. `Scale strip` — the top of `/lodestar/use/v0.1/guides/forms` (stage 2) [#2-scale-strip--the-top-of-lodestarusev01guidesforms-stage-2]

```mermaid
block-beta
  columns 4
  mark["Brand mark · Nepal Dev Verse"]:2 search["⌕"] menu["☰"]
  strip["‹ ○ Guides · Forms (phone strip)"]:4
  wide["Wider screens · Verse ▸ System ▸ ● lodestar ▸ ☀ Use · ◯ v0.1 ▸ ○ Guides ▸ Forms"]:4
  title["Forms"]:4
  body["Reading column"]:4
```

The strip replaces Fumadocs' breadcrumb. On a phone it shows the parent level with a back arrow
and the current page's name; from about 720px it shows every level with its mark. *Verse* opens
`/#verse`, *System* the home page, the planet its overview, *Use · v0.1* the line's first page,
*Guides* its index if it has one. The current page is plain text. Going up a level settles the new
page in from slightly larger; going down, from slightly smaller.

**States**

- Empty: an overview shows `Verse ▸ System ▸ ● lodestar` only; a Maintain page shows a moon for
  the side and no version line.
- Loading: none; the strip is part of the prerendered page.
- Not found: the 404 has no strip.
- Refused: not applicable.
- Error: a page outside any catalogued entry is impossible (the build checks the shape); if it
  happened, the strip would show `Verse ▸ System` and the page.
- Degraded: with reduced motion, or without view transitions, the links navigate without a zoom.
  Without scripts every link still works. A folder without an index is plain text.
- Success: the reader sees every level above them and moves up one with a tap.

### 3. `The system` — the home page's hero, with the zoom control (stage 2) [#3-the-system--the-home-pages-hero-with-the-zoom-control-stage-2]

```mermaid
block-beta
  columns 4
  mark["Brand mark · Nepal Dev Verse"]:3 menu["☰"]
  system["The turning system · star, orbits, planets, moons"]:4
  zoom["Zoom out to the Verse ↘"]:4
  head["Every package and project by Nepalese developers all over the world, documented to the version"]:4
  search["Search packages, projects and pages"]:4
```

The system has one ghost control at its lower right, *Zoom out to the Verse*, with the
telemetry line beside it, and the still sky behind it in place of the canvas's own stars. What
the system itself draws is in [the living hero](./living-hero.mdx).

**States**

- Empty: with no public entries the system shows the star and its five empty orbits, and the
  control still opens the Verse.
- Loading: the canvas draws after scripts load; before that, the sky and the text are in place.
- Not found, refused, error: not applicable.
- Degraded: without scripts there is no canvas and no control (as today). With reduced motion
  the system is drawn once.
- Success: the system turns; the control is reachable by keyboard and names what it does.

### 4. `The Verse view` — the home page zoomed out, or opened at `/#verse` (stage 2) [#4-the-verse-view--the-home-page-zoomed-out-or-opened-at-verse-stage-2]

```mermaid
block-beta
  columns 4
  mark["Brand mark · Nepal Dev Verse"]:3 menu["☰"]
  sky1["· wide sky ·"]:4
  sys["✦ nepal-dev.com · the system, small and turning"]:4
  belt["· · asteroid belt · ·"]:4
  far["◐ harbor-ops ◐ fieldnote ◐ tessera · dim and far"]:4
  back["Back to the system ↖"]:4
  cap["The Verse · one system so far"]:4
```

The camera eases out over about 1.2 seconds: the system shrinks to the centre and keeps turning,
the wider sky opens, the belt and the private planets show dim and far, labels fade except
*nepal-dev.com*. *Back to the system*, or a tap anywhere on the system's canvas, eases back in.
On a phone the caption sits under the button; on wider screens, to its left. The page below the
hero does not change.

**States**

- Empty: with no private planets there is no far region; the caption stays.
- Loading: `/#verse` opens in the Verse view once the canvas draws; before that the system's
  place shows the sky.
- Not found, refused, error: not applicable. An unknown fragment opens the system as usual.
- Degraded: with reduced motion the view changes instantly. Without scripts there is no canvas,
  so `/#verse` shows the home page as it is.
- Success: the reader sees the Verse around the one system and returns with one press.

### 5. `The morph` — a planet card opening its overview (stage 2) [#5-the-morph--a-planet-card-opening-its-overview-stage-2]

```mermaid
block-beta
  columns 4
  before["Home · lodestar card · its planet in the sky panel"]:4
  arrow["planet morphs, about 0.35 seconds"]:4
  mark["Brand mark · Nepal Dev Verse"]:3 menu["☰"]
  strip["Verse ▸ System ▸ ● lodestar"]:4
  hero["Planet header · lodestar · the same planet, larger"]:4
  title["lodestar"]:4
```

The card's planet grows into the planet header's drawing while the rest of the page changes
under it. Going back from the overview, it shrinks into the card.

**States**

- Empty, not found, refused, error: not applicable; a card exists only for an entry with an
  overview.
- Loading: the overview is prerendered; the morph waits for it, as any navigation does.
- Degraded: with reduced motion, without view transitions, or when the card is off screen, the
  overview opens without the morph. The canvas planets open the overview without a morph.
- Success: the reader sees the planet they chose become the page they opened.

## Words [#words]

Under ADR-0029 decision 8, space words name places, never controls. Controls and scanned labels
keep their names: Search, Overview, Use, Maintain, On this page, version names, Back to top, and
the search button's text.

| Where | Words |
|---|---|
| Home page, no entries | No planets in the Verse yet. Packages and projects appear here once they are documented. |
| ADR constellation, no ADRs | No decisions in this constellation yet. |
| Search dialog, no results | Nothing in orbit matches. Try another word. |
| Scale strip, top levels | Verse · System |
| Home page system control | Zoom out to the Verse · Back to the system |
| Verse view caption | The Verse · one system so far |
| The 404 | This page drifted out of orbit. |
| Private projects, none | No private projects in orbit yet. |
| Footer | You've reached the horizon. The Verse goes on. · Back to orbit ↑ |


# App flow — unknown paths (/docs/maintain/app-flow/unknown-paths)

- **Status:** Current
- **Last updated:** 2026-11-03
- **Related ADRs:** [ADR-0034](../adr/ADR-0034-the-proxy-answers-unknown-paths-with-a-true-404.mdx),
  [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

What a reader gets at a path that is not a page (ADR-0034). The page arrives whole, with a 404
status, on the first request. Sample values are invented (ADR-0008). Phone width first.

The flow and the screen are drawn with Archify; the page shows them and its Markdown carries
their Mermaid (ADR-0022). Their sources are in `diagrams/docs/`: `unknown-paths.json` for the
flow, `unknown-paths-screen-1.json` for the screen.

## Entry points [#entry-points]

- **Any path that is not a page:** a mistyped address, an old or shared link, a private project's
  name on the home page, or `/docs/nothing-here` inside an entry. Everyone gets the same page.
- **Not here:** `/`, the site's own routes and anything below them (`/llms.txt`, `/og/…`,
  `/diagrams/…`), files, and a retired version line, which still redirects to the same path in the
  latest line.

## Flow [#flow]

```mermaid
flowchart LR
  R["The proxy checks the path<br/>before any page renders"] -->|not a page path| S["Served as today<br/>home, site routes, files"]
  R -->|a known page| P["The page<br/>or its redirect"]
  R -->|anything else| N["Out of orbit<br/>a true 404, with full HTML"]
```

## Screens [#screens]

### 1. `Out of orbit` — any unknown path, at phone width [#1-out-of-orbit--any-unknown-path-at-phone-width]

```mermaid
block-beta
  columns 4
  draw["a planet that has left its dashed orbit around the star"]:4
  h1["This page drifted out of orbit."]:4
  help["It may have moved to another version or been renamed. Search for it, or start again from the system."]:4
  field["⌕  Search packages, projects and pages"]:4
  back["Back to the system →"]:4
  foot["The Horizon footer · You've reached the horizon. The Verse goes on."]:4
```

The address stays as the reader typed it, and the page shows no part of it. The browser tab reads
*Page not found — Nepal Dev Verse*.

**States**

- Empty: not applicable; the page has no data of its own. With no public planets the footer's
  planet row is left out.
- Loading: none; the whole page is in the first response.
- Not found: this is that state, with a 404 status from the first request.
- Refused, error: not applicable.
- Degraded: without scripts the page and its links are all there, and *Back to the system* works;
  the search button does nothing.
- Success: the reader searches, or goes back to the system. A link inside the site to an unknown
  path shows the same page, with a full page load.


# Architecture (/docs/maintain/architecture)

How the site is put together: content sources, build steps, routes, integrations.

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- `system.mdx` is the primary document: what exists today.
- Per-area documents (`content-model.mdx`, `search.mdx`, `private-docs.mdx`, …) when one area needs its own picture.
- Describe only what exists. Direction belongs in a Proposed ADR.

**Template:** [`../_templates/architecture.mdx`](../_templates/architecture.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|
| [System](./system.mdx) | Current | — (Fumadocs scaffold) |


# Architecture — puncoz-packages-docs (/docs/maintain/architecture/system)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx),
  [ADR-0014](../adr/ADR-0014-home-page-is-a-search-first-release-map.mdx),
  [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx),
  [ADR-0011](../adr/ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx),
  [ADR-0020](../adr/ADR-0020-people-in-adrs-are-github-usernames-shown-as-profile-chips.mdx),
  [ADR-0021](../adr/ADR-0021-tests-run-with-bun-test.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Context [#context]

A Next.js 16 App Router site built on Fumadocs. It renders the MDX pages in `content/`
as a documentation site, and serves every page again as Markdown, as an Open Graph image, and
as a search record. Search runs on Algolia. There is no database, no sign-in and no
server-side state. Cache Components is on (`cacheComponents` and `partialPrefetching` in
`next.config.mjs`, ADR-0016), and every page and route handler is prerendered at build time: none
reads request data yet. The sign-in ADR adds the first request-time part, the home page's
private group, inside a `<Suspense>` boundary, so the rest of `/` stays in the static shell.

Every top-level folder in `content/` is a **catalogue entry**, published at `/<slug>`: a
package or project whose root `meta.json` carries a `catalog` field (ADR-0013, ADR-0015). Inside
it, `use/` and `maintain/` are the two tracks. A versioned `use/` holds one folder per version
line, each with `version` and `channel` in its `meta.json`: `use/dev/` for unreleased work in
progress, and released lines whose URL segment comes from their `name` (`v1.0`, `2024 LTS` →
`2024-lts`). Maintain is not versioned. The only entry today is this site itself, project
`docs`, whose Maintain track (`content/docs/maintain/`) holds its decisions and design
documents; no package is documented yet, so the home page shows its empty states.

## Routes [#routes]

| URL | File | What it is |
|---|---|---|
| `/` | `src/app/(home)/page.tsx` | Home page: the system, the search button opening the search dialog, planet cards, private projects beyond the belt and the sections of ADR-0017 |
| `/<slug>/…` | `src/app/(site)/(docs)/[...slug]/page.tsx` | A documentation page in the notebook layout, each wrapped in `ZoomPage` and opening with the scale strip (Fumadocs' breadcrumb off); an overview opens with the planet header, a line page adds the version line or its moon notice; "On this page" is the trajectory, with the page's reading time worked out at build time |
| `/<slug>/use` and a line root without its own page | `src/app/(site)/(docs)/[...slug]/page.tsx` | 307 redirect to the first page (the latest line, else `dev`) |
| `/<slug>/use/latest/…` | `src/proxy.ts` | 307 redirect to the line marked `latest`, or `dev` when nothing is released |
| `/<slug>/use/<segment>/…` for a line that does not exist | `src/proxy.ts` | 307 redirect to the same path in `latest` (or `dev`) |
| `/<slug>….md` | `src/proxy.ts` → `/llms.mdx/<slug>…/content.md` | The page as Markdown |
| `/<slug>…` with `Accept` preferring Markdown | `src/proxy.ts` → `/llms.mdx/<slug>…/content.md` | The page as Markdown, `Vary: Accept` |
| Any other path that is not a page or a site route | `src/proxy.ts` → `src/app/not-found.tsx` | The out-of-orbit page, 404 from the first request, the address unchanged (ADR-0034) |
| `/llms.mdx/…/content.md` | `src/app/llms.mdx/[...slug]/route.ts` | Processed Markdown of one page, `text/markdown` |
| `/llms.txt` | `src/app/llms.txt/route.ts` | Index of every page, version lines labelled |
| `/llms-full.txt` | `src/app/llms-full.txt/route.ts` | Every page's full Markdown in one file |
| `/og/image.png`, `/og/…/image.png` | `src/app/og/[...slug]/route.tsx` | Share image, 1200 by 630: the home page's system, or a page's entry, track, line, title and description (ADR-0035) |
| `/robots.txt` | `src/app/robots.ts` | Allows everyone and names the sitemap; with no `SITE_URL`, disallows everything |
| `/sitemap.xml` | `src/app/sitemap.ts` | Every page the rule of ADR-0035 marks, with `lastmod` from git; with no `SITE_URL`, empty |
| `/manifest.webmanifest` | `src/app/manifest.ts` | Name, description, theme colours and icons |
| `/apple-icon` | `src/app/apple-icon.tsx` | The brand mark as a PNG, drawn at build |
| `/static.json` | `src/app/static.json/route.ts` | Every page as an Algolia search record |

Pages share the root with the site's own routes. The proxy leaves those routes and everything
below them alone (`isSiteRoute`), handles line redirects and Markdown on paths whose first segment
is a catalogued slug (`isEntryPath`), and answers any remaining path that is not a page with a 404
(`isKnownPath`). The build fails if its list of pages differs from the site's, and refuses a slug
that would collide with a route (`api`, `og`, `static`, …). Contracts for the machine-readable routes are in
[`../api/`](../api/index.mdx).

## Components [#components]

| Component | Responsibility | Depends on |
|---|---|---|
| `content/` | The published pages and `meta.json` files, one folder per catalogue entry | — |
| `src/lib/catalog-schema.ts` | `catalogMetaSchema`: Fumadocs' `metaSchema` plus `catalog`, `name`, `version` and `channel` (`latest`, `dev`, `legacy`), as a Standard Schema; rejects any `visibility` but `public`; a project's `repositories` (`id`, `name`, `url`, one `primary`), primary first — ADR-0024 | `fumadocs-core` |
| `src/lib/catalog-plugin.ts` | Loader plugin: the build checks of ADR-0015 decision 5, typed roots (`root: true` on an entry, `'track'` on `use/` and `maintain/`, `'line'` on a version line), line names and descriptions (`version · channel`) and line order (latest, `dev`, then older lines in `use/meta.json` `pages` order or newest first); a project's lines (`dev` and one released line) and repository folders named from the catalogue (ADR-0024); the `root` hook `overviewInTracks()`, which moves each overview into its tracks as an *Overview* item, and `withoutOverviewItems()` for `llms.txt` (ADR-0025); `lineInfo()`, `lineSegment()`, `pageVersion()`, `repositoryName()` | `fumadocs-core` |
| `src/lib/source.ts` | Loads `content/` with `defineDocs` at base URL `/`, swapping each line folder's URL segment for its name (`slugs`), with the diagram shape check first among the remark plugins and the Markdown filter for `<Diagram>` (ADR-0022); exposes `source`, `getMeta` and `docsLlms` (version line in each page's Markdown and in `llms.txt`) | `fumadocs-mdx`, the two above |
| `src/lib/catalog.ts` | Reads the page tree into typed catalogue entries (lines, tracks, demo, repositories), the page context for banners, and the home page's previews | `source.ts` |
| `src/lib/catalog-routes.ts` | Meta files and pages' paths, with every body compiled empty, for the proxy: the catalogued slugs, each package's line segments, `latest` and `dev`, the known paths; `isEntryPath()`, `resolveLineRedirect()`, `isKnownPath()`, `assertKnownPaths()` | `fumadocs-mdx`, `known-paths.ts` |
| `src/lib/known-paths.ts` | The site's top-level routes, every path with a page behind it, and where two such lists differ (ADR-0034) | `catalog-plugin.ts` |
| `diagrams/` | Archify diagrams, one pair per diagram: the candidate JSON (not published) and the HTML exactly as `deliver` wrote it (ADR-0022) | — |
| `src/app/diagrams/[project]/[file]/route.ts`, `src/lib/diagram-files.ts` | Prerenders every HTML in `diagrams/` at `/diagrams/<project-slug>/<slug>.html` with the site shell; the CSP `sandbox` header comes from `next.config.mjs` | `diagram-shell.ts` |
| `src/lib/diagram-shell.ts` | The site shell added as a diagram is served: in a frame (`?frame=1`) it hides Archify's title, notes rail, theme and style buttons and credit; it sets the page colours to the site's tokens, starts motion Live (unless reduced motion) and reports the content height to the page | — |
| `src/components/diagram.tsx`, `diagram-frame.tsx` | `<Diagram src title>`, registered in `src/components/mdx.tsx`: the sandboxed, lazy frame sized from the diagram's `viewBox`, with the site's theme in its URL and the reported height taken only from that frame; the caption and **Open full screen**. The Mermaid it holds is not rendered | `diagrams.ts`, `fumadocs-ui/provider/base` |
| `src/lib/remark-diagrams.ts` | The shape check (a Mermaid fence only inside a `<Diagram>` that holds exactly that fence; templates exempt) and `markdownFilter`, which keeps a `<Diagram>`'s fence in the processed Markdown and drops the tag (ADR-0022) | `diagrams.ts` |
| `src/lib/diagrams.ts`, `diagrams-plugin.ts` | Which `src` is allowed, a diagram's size, the bounds of a height report, and the file checks run as a loader plugin: every HTML with its JSON and used by a page, every `src` with its file, nothing in `public/diagrams/`, no Archify receipt | `node:fs` |
| `src/lib/github-profile.ts`, `src/components/profile-link.tsx` | Which links are GitHub profile links (`[@user](https://github.com/user)`), and `withProfileChips`, the page's `a` component, which shows them as a chip with the avatar loaded live from GitHub and hands every other link to `createRelativeLink` (ADR-0020) | `fumadocs-ui/mdx.server` |
| `*.test.ts`, `*.test.tsx` beside the code | Unit tests, run with `bun run test` (`bun test --no-env-file`); type-checked through `tsconfig.test.json`, which adds Bun's types and is kept out of the site's own check (ADR-0021) | `bun:test`, `react-dom/server` |
| `src/lib/search-scope.ts` | The scope tag of a page (`<slug>`, `<slug>:maintain`, `<slug>:use:<segment>`) | — |
| `src/lib/adr-status.ts` | An ADR's status from its status line, its number and short title, whether a folder is named `adr` (ADR-0019) | — |
| `src/lib/trajectory.ts`, `reading-time.ts` | Pure geometry for the trajectory and the station arcs, the probe's position and the time left; a page's reading time from its `structuredData` at 220 words a minute (ADR-0018) | — |
| `src/lib/algolia.ts` | The search-only Algolia client used by the search dialog | `algoliasearch/lite` |
| `src/lib/shared.ts` | Site name (`Nepal Dev Verse`), the community, the maker and the home line (ADR-0036), route prefixes (pages at the root, `/og`, `/llms.mdx`), GitHub repository (`puncoz-official/docs`), URL builders | — |
| `src/app/layout.tsx`, `global.css`, `site.css` | Root layout: the three fonts, the RootProvider (dark by default, light/dark through next-themes) and the search dialog; the tokens on `:root` / `.dark` mapped onto Fumadocs' colours; the site header, theme switch, docs typography, planet header, notices, planet row, stations, trajectory and footer | `fumadocs-ui` |
| `src/components/site-header.tsx`, `theme-switch.tsx` | The one header: the brand mark and wordmark, the header's band of sky, nav, optional search button (left out on the home page), GitHub, the orrery theme switch (`useTheme`), optional menu button | `fumadocs-ui/provider/base` |
| `src/components/planet.tsx` | The shared marks, plain SVG with no client state: `PlanetMark`, `MoonPhase`, `PlanetSystem` (ADR-0017) | `rings.ts` |
| `src/components/brand-mark.tsx`, `nepal-flag.tsx`, `src/lib/flag.ts`, `src/app/icon.svg` | The brand mark, nepal-dev.com's mountain and flag: the header's, the credit's, the share images' and the Apple icon's (in fixed colours), and the site icon; the flag's geometry and cloth, shared with the Horizon (ADR-0036) | — |
| `src/components/verse-mark.tsx` | The Verse mark: the place mark of the Verse in the scale strip (ADR-0029) | — |
| `src/components/docs/scale-strip.tsx`, `src/lib/scale-strip.ts` | The scale strip: every level from the Verse to the page, worked out on the server from the page tree and the catalogue, with the phone's parent level (ADR-0029) | `catalog-plugin.ts`, `planet.tsx`, `verse-mark.tsx` |
| `src/components/zoom-page.tsx`, `src/lib/zoom.ts` | React `<ViewTransition>` wrappers: `ZoomPage` in each page enters and exits on the `zoom-in` and `zoom-out` transition types that links carry; `PlanetMorph` shares a planet's drawing between its card and its planet header. `zoom.ts` holds the two types, apart from the catalogue code, for client components (ADR-0029) | `react` |
| `src/components/sky.tsx`, `src/lib/sky.ts` | The still sky: seeded star fields drawn on the server, one fixed behind every page (placed in the root layout) and one band in the header; CSS keeps them clear of text (ADR-0029) | — |
| `src/components/horizon-footer.tsx`, `horizon-awake.tsx`, `footer-actions.tsx`, `src/lib/horizon-sky.ts` | The Horizon footer on every page: the closing line, whose `VerseLink` opens the Verse view (ADR-0033), and a living scene of layered SVGs (stars, shooting stars, the moon and the star, three ranges and lit clouds, alpenglow, the flag, one light per entry, an observatory and the ground, ADR-0037) drawn on the server from `horizon-sky.ts`; `HorizonAwake` lets its CSS loops run only while it is on screen and raises the flag once on arrival; on docs pages it stacks above the sidebar and the trajectory, which set as it enters (ADR-0030). Its Search and Back to top buttons are client components | `catalog.ts`, `fumadocs-ui` |
| `src/app/not-found.tsx` | The out-of-orbit 404 for every unknown path and `notFound()` | `catalog.ts` |
| `src/app/(site)/(docs)/layout.tsx` | Fumadocs notebook `DocsLayout` with the site header as its `nav.component`, the version-line switcher only (each line with its moon icon), the planet row as sidebar banner, orbit stations as the sidebar's folder, page and separator components, the ADR statuses for the constellation (`AdrStatusProvider`), and the full Horizon footer | `catalog.ts`, `source.ts` |
| `src/components/docs/` | `DocsHeader` (site header opening the search dialog and the sidebar), `PackageHero` (the planet header), `TrackSwitch` (the planet row: chip, a sun for Use and a moon for Maintain), `OrbitStation` / `OrbitItem` / `OrbitSeparator` (the sidebar's stations, on Fumadocs' sidebar primitives) with `StationGroup` (one open station per level, the rule in `src/lib/station-group.ts`, ADR-0023), `AdrConstellation` and `AdrStatusProvider` (a folder named `adr` as a grid of moons phased by status, ADR-0019), `TrajectoryTOC` / `TrajectoryPopover` ("On this page" as a trajectory with a probe and time left, on desktop and as the phone bar) and `VersionNotice` (the version stated with its moon; In development and Older version notices) — ADR-0018 | `fumadocs-ui`, `trajectory.ts` |
| `src/app/(home)/` | Home layout (`.home` wrapper, `home.css`) and page | `catalog.ts`, `source.ts` |
| `src/components/home/` | Server: hero, home header, planet cards, beyond the belt (private projects from `private-projects.ts`), two sides, moon rows. Client: orbit map (canvas; a planet opens its overview; the Verse view at `#verse`, its easing and far planets from `src/lib/verse-view.ts`, ADR-0029; every ecosystem's orbit, the living star, trails, pointer depth, the arrival, the comet and the telemetry line from `src/lib/hero-sky.ts`, with the nebula behind it in `home.css`, ADR-0032), search button (opens the search dialog), terminal (tabs), assistant actions (Fumadocs' Copy Markdown and Open menu for the example page), reveal | `catalog.ts`, `rings.ts`, `fumadocs-ui`, `lucide-react` |
| `src/components/search.tsx`, `search-empty.tsx` | The site-wide search dialog, opened by `⌘K`, the docs header's search button and the home page's hero button; its no-results line is the site's own (ADR-0029) | `algolia.ts` |
| `src/proxy.ts` | Leaves site routes alone; on catalogued paths, line redirects and the Markdown rewrites; any other unknown path, the 404 | `catalog-routes.ts`, `known-paths.ts`, `fumadocs-core/negotiation` |
| `src/lib/seo.ts` | Pure and tested: validates `SITE_URL` (`https` origin, no path), each page's search rule, its title, its metadata, the robots rules, the sitemap entries, the JSON-LD and its escaping, and the share images' colours and sizing (ADR-0035) | `shared.ts` |
| `src/components/json-ld.tsx` | The JSON-LD `<script>` in the home page and in an indexed docs page | `seo.ts` |
| `src/components/share-image.tsx`, `src/lib/share-fonts.ts` | The two share images for `next/og`, with the stars and orbits kept clear of the text; Bricolage Grotesque and Onest fetched as `ttf` from Google Fonts in `use cache`, so a failed fetch fails the build and the routes stay prerendered | `seo.ts`, `sky.ts`, `verse-mark.tsx` |
| `scripts/sync-content.ts` | After `next build`, refuses to run without `SITE_URL`; reads the built `static.json` and replaces the Algolia index `document` with it | `algoliasearch`, `ALGOLIA_WRITE_KEY`, `SITE_URL` |

## How navigation is scoped [#how-navigation-is-scoped]

Fumadocs shows the sidebar of the deepest root folder on the current path, and groups root
folders of the same type into one switcher whose options keep the reader on the same page
(`fumadocs-ui/contexts/tree`). The catalogue plugin marks folders so that:

- on a package's Use page the sidebar holds only that line's pages, with a version menu
  (`v4.0` / `4.0.1 · Latest`, `dev` / `5.0.0-dev · In development`, older lines) that keeps the
  reader on the same page when it exists, matched by file path, not URL;
- on a Maintain page the sidebar holds only the Maintain pages;
- on an overview the sidebar is its default track's: the plugin's `root` hook takes the overview
  off the entry folder and puts an *Overview* item for it first in each Use line (or an
  unversioned Use) and in Maintain, with Use first, so the path search finds the overview in the
  latest Use line, or in Maintain when there is no Use (ADR-0025). The catalogue's links
  (`src/lib/catalog.ts`) and the version menu's (`lineLink()` in `src/lib/overview-sidebar.ts`)
  skip the item, and `llms.txt` reads the tree without it;
- `TrackSwitch` switches between the two tracks, and on an overview marks the default track as
  current;
- the site-wide switcher of root folders is not shown: the layout passes only `line` roots as
  tabs. Entries are reached from the home page and the header.

## Diagram [#diagram]

```mermaid
flowchart TB
  subgraph Repo["Repository"]
    CONTENT["content/<br/>MDX + meta.json catalogue"]
  end
  subgraph Build["bun run build"]
    NEXT["next build<br/>schema + catalogue checks → static pages and routes"]
    SYNC["scripts/sync-content.ts"]
  end
  subgraph Site["Deployed site"]
    PROXY["proxy: line redirects, Markdown rewrites, 404 for unknown paths"]
    HOME["/ home page"]
    PAGES["/slug pages"]
    MD["Markdown · llms.txt · llms-full.txt"]
    OG["Share images · Apple icon"]
    CRAWL["robots.txt · sitemap.xml · manifest"]
    DIAG["/diagrams/ Archify views, with the site shell"]
    REC["static.json"]
  end
  ALG[("Algolia index<br/>document")]
  Reader["Reader / browser"]
  Bot["LLM tools and crawlers"]

  CONTENT --> NEXT --> HOME & PAGES & MD & OG & REC & CRAWL
  NEXT --> SYNC -->|write key| ALG
  Reader --> PROXY --> HOME & PAGES
  Reader -->|search-only key, from the dialog and the hero| ALG
  Bot --> PROXY --> MD & CRAWL
  PAGES -.->|frames| DIAG
```

## Key decisions in force [#key-decisions-in-force]

- [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx): the catalogue
  shape, tracks, version lines, URLs, scoped navigation, search fields and build checks.
- [ADR-0014](../adr/ADR-0014-home-page-is-a-search-first-release-map.mdx): the home page.
- [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx): root
  addresses, `dev` and named lines, the site as project `docs`, one look and one header,
  light/dark.

## Constraints [#constraints]

- **Mermaid is not rendered.** Diagrams in these pages show as highlighted code.
- **Every page is public on every surface.** Nothing filters a page out of the site, the
  Markdown routes, `llms.txt` / `llms-full.txt`, `static.json`, the share images or the search
  index; `noindex` keeps a page out of search results only. The catalogue schema rejects a private entry, so the build fails instead of publishing
  one (`AGENTS.md` §6.1).
- **`lastmod` needs a full clone.** It comes from `git log`, so a shallow clone would date every page
  to the last commit, and an uncommitted page has none. The hosting ADR must clone in full.
- **The build needs the network**, for `next/font` and the share images' fonts.
- **Demos are not published.** A `use/<line>/demo.mdx` page would be linked from the catalogue,
  but ADR-0011's embed takes only `/diagrams/…` files, so how a demo runs needs its own ADR; the
  home page has no demo section.
- **`defineCollections({ type: 'meta' })` is broken in fumadocs-mdx 15.4.10** (its generated
  call passes `meta` where the runtime reads `entries`), so `catalog-routes.ts` uses a
  `defineDocs` whose page pattern matches nothing.
- **`bun run build` publishes.** Its second step overwrites the live search index.
- **Hosting is not decided.** `.gitignore` lists `.vercel`, from the scaffold; no host is
  configured in the repository.


# Data flow diagrams (/docs/maintain/dfd)

Where content and data go, and every trust boundary they cross.

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- `system.mdx` is Level 0 (context): the site, its readers and every external system. Feature files decompose it (Level 1/2); levels balance — a child's flows match its parent's.
- Every crossing to a third party (search provider, host, analytics, CI) is listed with exactly what is sent, how it is authorised, and whether private content can travel on it.
- Data stores carry their classification.

**Template:** [`../_templates/dfd.mdx`](../_templates/dfd.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|
| [System (Level 0)](./system.mdx) | Current | — (Fumadocs scaffold) |


# DFD — System (Level 0) (/docs/maintain/dfd/system)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** ADR-0005, ADR-0010, ADR-0020, ADR-0013, ADR-0014, ADR-0016

> Snapshot of the system as it stands today. Edit in place; never record what changed.
> Conventions: `content/docs/maintain/dfd/index.mdx`. Levels balance — a child's flows match its parent's.

## Scope [#scope]

The whole site: authoring, build, publishing and reading. No parent diagram.

## Diagram [#diagram]

```mermaid
flowchart LR
  Owner["Owner<br/>(author)"]
  Consumer["Consuming repositories<br/>(submodule)"]
  Reader["Reader"]
  Bot["LLM tools / crawlers"]
  ALG["Algolia"]
  GH["GitHub<br/>(avatars)"]
  GF["Google Fonts"]

  subgraph Trust["Trust boundary — repository and build"]
    D1[("D1 · content/ and diagrams/")]
    D2[("D2 · .env.local")]
    P1(("1.0<br/>Build"))
    P2(("2.0<br/>Sync search index"))
  end

  subgraph Public["Public — deployed site"]
    P3(("3.0<br/>Serve pages and<br/>machine-readable routes"))
  end

  Owner -->|"MDX pages"| D1
  Consumer -->|"MDX pages in content/&lt;slug&gt;/,<br/>reviewed and committed by the owner"| D1
  D1 -->|"pages"| P1
  P1 -->|"static pages, Markdown, llms.txt, share images,<br/>robots.txt, sitemap.xml, static.json"| P3
  P1 -->|"font request, no content"| GF
  P1 -->|"static.json records"| P2
  D2 -->|"ALGOLIA_WRITE_KEY"| P2
  P2 -->|"every record, replaces index"| ALG
  P3 -->|"pages"| Reader
  P3 -->|"Markdown, llms.txt, llms-full.txt,<br/>robots.txt, sitemap.xml"| Bot
  Reader -->|"search query + search-only key<br/>(the search dialog, on every page)"| ALG
  ALG -->|"matching records"| Reader
  Reader -->|"avatar request, no referrer<br/>(profile chips)"| GH
  GH -->|"avatar image"| Reader
```

## External entities [#external-entities]

| Entity | Role |
|---|---|
| Owner | Writes the content; reviews and commits every change; runs the build |
| Consuming repositories | The owner's project and package repositories, which include this one as a git submodule and write their own folder, `content/<slug>/` (ADR-0010) |
| Reader | Reads pages; searches from the browser, in the search dialog or the home page's hero field |
| LLM tools / crawlers | Read the pages, the Markdown routes, `llms.txt` / `llms-full.txt`, `robots.txt` and `sitemap.xml` |
| Google Fonts | Serves font files during the build, for `next/font` and the share images (ADR-0035) |
| Algolia | Hosts the search index `document` |
| GitHub | Serves the avatar in each profile chip, `github.com/<user>.png`, redirecting to `avatars.githubusercontent.com` (ADR-0020) |

## Processes [#processes]

| # | Process | Input → Output |
|---|---|---|
| 1.0 | Build (`next build`) | `content/` → static pages and routes |
| 2.0 | Sync search index (`scripts/sync-content.ts`) | Built `static.json` → Algolia index |
| 3.0 | Serve | Built output → readers and tools |

## Data stores [#data-stores]

| ID | Store | Contents | Classification |
|---|---|---|---|
| D1 | `content/` | Published documentation, one folder per package or project, including this site's own design documents (`docs/maintain/`) | Public — see [`../security/data-classification.mdx`](../security/data-classification.mdx) |
| D2 | `.env.local` (gitignored) | Algolia app ID, search-only key, write key | The write key is Restricted; the others are Public |

## Trust boundary crossings [#trust-boundary-crossings]

| Flow | Direction | Authorisation | Private content? |
|---|---|---|---|
| Pages from a consuming repository → `content/` | Submodule → repository | The owner's review and commit; agents there never commit (`PROJECT_AGENTS.md` §10) | Could carry a private project's text if written into its folder; the owner's review is the control, and `PROJECT_AGENTS.md` §2 forbids it |
| Records → Algolia | Build → Algolia | `ALGOLIA_WRITE_KEY` | Would carry any page in `content/`. Each record also carries its scope `tag` and, for catalogue pages, `package`, `kind`, `ecosystem`, `track`, `line`, `channel` (ADR-0013) — public metadata about public pages |
| Search query → Algolia | Browser → Algolia | Search-only key, public by design | Can read every record in the index. The query is the reader's text only; the dialog adds no filter |
| Pages and machine-readable routes → readers and tools | Site → public | None | Would carry any page in `content/` |
| Font request → Google Fonts | Build → Google Fonts | None | No. The request names a font family and weight, and no page's words |
| Avatar → reader | Browser → GitHub | None | No. The request carries the reader's IP address and user agent and, with `referrerpolicy="no-referrer"`, no page address. The username in it is already on the page (Public) |
| "View on GitHub" link | Site → GitHub | GitHub's own access rules | Points at the page's source in the repository named in `gitConfig` |

Every crossing carries everything in `content/`. That is why no private project content
may go there until its ADR is approved (`AGENTS.md` §6.1).


# ERD (/docs/maintain/erd)

Persisted data, as it stands. It is never allowed to drift from the code or migrations that
define it.

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- `system.mdx` is the whole schema, created by the first ADR that stores data (a database, a
  key-value store, a structured content index) and updated by **every** change to it after.
- Each entity lists columns, indexes, invariants, relationships with on-delete behaviour, and sensitive fields with their classification ([`../security/data-classification.mdx`](../security/data-classification.mdx)).
- MDX frontmatter is not persisted data; its schema lives with the content conventions.

**Template:** [`../_templates/erd.mdx`](../_templates/erd.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|

None: the site stores no data. Content is files in `content/`; the search index is a
build output, described in [`../architecture/system.mdx`](../architecture/system.mdx).


# Maintainer documentation (/docs/maintain)

How this site is built and decided: its decisions, design documents and security documents.
Each directory's `index.mdx` holds its own conventions. The rules behind this layout are
[ADR-0002](./adr/ADR-0002-living-design-documentation.mdx).

This is the Maintain track of the project `docs`, this site itself. Packages, libraries and other
projects each have their own folder, `content/<slug>/`, published at `/<slug>`.

## Three kinds of document [#three-kinds-of-document]

| Kind | Directory | Changes how |
|---|---|---|
| **Package and project documentation** | `content/<slug>/`, one folder per package or project | **The product.** Written and updated within the approved content conventions and the invariants in `AGENTS.md` §6. |
| **Decisions** | [`adr/`](./adr/index.mdx) | **Immutable once approved.** A change of mind is a new ADR that supersedes the old one. |
| **Design documents** | everything else here | **Living snapshots.** Describe the site as it stands right now, edited in place. What is no longer true is deleted, not annotated. |

How they relate:

```mermaid
flowchart LR
  N["Need<br/>a feature or a decision"] --> A["adr/<br/>Proposed ADR"]
  A -->|owner approves| I[Implementation]
  A -. written with .-> D["design documents<br/>app-flow · prd · dfd · …"]
  I -->|kept in sync| D
  I -->|content conventions| C["content/<br/>published pages"]
```

## Directories [#directories]

| Directory | Holds | Required when |
|---|---|---|
| [`adr/`](./adr/index.mdx) | Architecture Decision Records and their index | Every feature and functional change ([ADR-0001](./adr/ADR-0001-adr-driven-development-workflow.mdx)) |
| [`app-flow/`](./app-flow/index.mdx) | The flow and screen wireframes, Mermaid and Archify, one file per feature | Any ADR that changes something a person sees ([ADR-0008](./adr/ADR-0008-a-ui-change-ships-an-app-flow.mdx)) |
| [`prd/`](./prd/index.mdx) | Requirements and user stories | Any reader-facing feature |
| [`architecture/`](./architecture/index.mdx) | High-level design | A new module, content source, build step or external integration |
| [`erd/`](./erd/index.mdx) | Persisted data | The first ADR that stores data creates `erd/system.mdx` |
| [`dfd/`](./dfd/index.mdx) | Data flow diagrams with trust boundaries | Data crosses a trust boundary or reaches an external system |
| [`state/`](./state/index.mdx) | State machines | An entity with more than two states, or guarded / timed transitions |
| [`sequence/`](./sequence/index.mdx) | Sequence diagrams | Multi-actor, async, or retrying flows |
| [`api/`](./api/index.mdx) | Route handler and endpoint contracts | Anything another client or system calls |
| [`rbac/`](./rbac/index.mdx) | Access matrices | Visibility depends on who the reader is |
| [`security/`](./security/index.mdx) | Threat model, data classification, secrets, audit checklist | Always kept accurate; per-feature analyses when warranted |
| [`_templates/`](./_templates/index.mdx) | A starting point for each document type | — |

Agent skills are not part of this project. They are tooling for contributors, vendored in
`.claude/agent-skills/` outside `content/`, so they are never published: `INDEX.md` routes
tasks to skills and `SOURCES.md` records provenance
([ADR-0009](./adr/ADR-0009-trusted-agent-skills-are-vendored.mdx)).

## Conventions for every design document [#conventions-for-every-design-document]

- **Frontmatter `title`**, no `#` heading; then the header: `Status`, `Last updated`, `Related ADRs`.
- **Snapshot, not changelog**: no revision tables, no "previously", no strikethrough.
- **Every diagram is Mermaid and Archify together**: flowcharts, sequences, state machines,
  ERDs and screen wireframes (`block-beta`) are a Mermaid fence inside a `<Diagram>`, with the
  Archify files in `diagrams/<project-slug>/`. The page shows the Archify view; the page's
  Markdown carries the Mermaid ([ADR-0022](./adr/ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown.mdx),
  `AGENTS.md` §8). No binary or externally hosted images.
- **Sample values are invented**, never a real person's name, a client's name, a real token or
  a private project's details.
- **Links between documents are relative and start with `./` or `../`** (`./adr/index.mdx`), so the site resolves them to page URLs and they still work on GitHub.
- **Start from [`_templates/`](./_templates/index.mdx)**. If unsure whether a document is required, write it.


# PRD — the ADR constellation (/docs/maintain/prd/adr-constellation)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0019](../adr/ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

An open ADR station lists every decision as a 32px row. This site's 18 ADRs take about 600px of
sidebar, the list grows with every decision, and each package or project that keeps ADRs will
grow the same way.

## Goal [#goal]

- An ADR folder's station stays about seven rows tall at any number of ADRs.
- A reader sees each ADR's status, and where the current one sits among them, at a glance.
- Every title stays one point, one step or one click away.

## Non-goals [#non-goals]

- Changing other folders' stations (ADR-0018).
- Changing ADR pages or their index page.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **maintainer**, I want **the decisions to take little sidebar space**, so that **the other sections stay in view**. | - An ADR folder's open station shows a grid of moons, not rows.<br />- Its height does not grow with each ADR beyond one row per about nine. |
| US-2 | As a **reader**, I want **to see each decision's status**, so that **I know what is in force**. | - Full moon approved, dashed new moon proposed, crescent superseded, faint ring rejected or unknown.<br />- A one-line legend names them. |
| US-3 | As a **reader**, I want **to see an ADR's title before opening it**, so that **I open the right one**. | - Pointing at or focusing a moon shows its number and title in the readout.<br />- Each moon's accessible name is its full title and status. |
| US-4 | As a **reader working through decisions**, I want **to step to the next or previous one**, so that **I read them in order**. | - "← 15" and "17 →" link to the neighbours; each is left out at the ends. |
| US-5 | As a **reader**, I want **every title in one list**, so that **I can scan them all**. | - "All 18 decisions →" opens the folder's index page. |
| US-6 | As a **consuming repository**, I want **the same for my ADRs**, so that **I don't configure anything**. | - Any folder named `adr` in an entry shows as a constellation. |

## Rules and edge cases [#rules-and-edge-cases]

- The folder's index page is not a moon; it is the register.
- The number is the title's `ADR-NNNN`, or the page's place in the folder.
- The status comes from the template's `**Status:**` line; without it, the faint ring.
- On touch screens nothing is pointed at; a tap opens the ADR.

## Out of scope for now [#out-of-scope-for-now]

- Filtering or searching inside the constellation: the site's search and the register cover it.

## Open questions [#open-questions]

None.


# PRD — diagrams (/docs/maintain/prd/diagrams)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0022](../adr/ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

An embedded Archify diagram shows its own title, notes and theme buttons inside a frame that
scrolls, on a background that ignores the site's theme, under a Mermaid block repeating the
same diagram as code. Wireframes and four diagrams show only as Mermaid code.

## Goal [#goal]

- On the page, every diagram is its Archify view: the diagram, its labels and its controls, at
  its own height, in the site's colours, moving.
- In Markdown, every diagram is its Mermaid.
- No package or project can publish a diagram any other way.

## Non-goals [#non-goals]

- Changing Archify itself, or drawing diagrams without it.
- Rendering Mermaid on the page.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **reader**, I want **only the diagram in the frame**, so that **I read it at a glance**. | - No Archify title, subtitle, notes rail, theme or style button in the frame.<br />- Live/Still, Present, Export and the diagram controls stay. |
| US-2 | As a **reader**, I want **the frame to fit the diagram**, so that **I scroll the page, not the frame**. | - No vertical scrollbar inside the frame at phone or desktop width.<br />- The page doesn't jump when the diagram loads. |
| US-3 | As a **reader**, I want **the diagram in the site's theme**, so that **it belongs to the page**. | - The background is the page's in light and dark.<br />- Switching the site's theme switches the diagram's. |
| US-4 | As a **reader**, I want **the diagram to show its movement**, so that **I see the order of things**. | - It starts Live; with reduced motion it starts Still.<br />- Boxes keep their kind colours. |
| US-5 | As a **reader copying a page**, I want **the diagrams as Mermaid**, so that **a tool or an LLM can read them**. | - Copy Markdown, `/<page>.md` and `llms-full.txt` hold the Mermaid fence.<br />- They never hold `<Diagram>` or an Archify URL. |
| US-6 | As a **reader**, I want **screens drawn like the flows**, so that **I see each screen, not code**. | - Each wireframe shows as its Archify view. |
| US-7 | As a **consuming repository**, I want **the build to tell me** when a diagram is wrong, so that **I fix it before it publishes**. | - A Mermaid fence outside `<Diagram>`, a `<Diagram>` without exactly one fence, or a missing file fails the build, naming the page. |

## Rules and edge cases [#rules-and-edge-cases]

- Templates in `content/docs/maintain/_templates/` keep bare Mermaid; a copy must be wrapped.
- **Open full screen** shows Archify's own page, with its title and notes, in the site's colours.
- A wide diagram scrolls sideways inside the frame on a phone.

## Out of scope for now [#out-of-scope-for-now]

- A shared Archify viewer loaded once for all diagrams on a page.

## Open questions [#open-questions]

None.


# PRD — docs sidebars: orbit stations, the trajectory and the horizon (/docs/maintain/prd/docs-sidebars)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx),
  [ADR-0027](../adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx),
  [ADR-0030](../adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

Readers spend most of their time on docs pages, between the left sidebar and "On this page".
Both are Fumadocs' defaults with a dot added: long sidebars, such as this site's Maintain track
with twelve sections, are a long list of rows, and "On this page" is a straight line on any page
whose headings are one depth. Neither says how much of the page is left. Docs pages also end on a
shortened footer that differs from every other page's.

## Goal [#goal]

- Each sidebar level reads as a smaller body than the one above it: landmarks, belts, orbits,
  satellites; only the open orbit is a card (ADR-0027).
- "On this page" curves on every page, shows where the reader is, and how long is left.
- Every page, docs pages included, ends on the same full horizon, with a living sky, and nothing
  of the sidebar or the trajectory sits on it.

## Non-goals [#non-goals]

- Changing page headings, body text or the reading column.
- Changing the moon picker, version notices or planet header (ADR-0017).
- Search, the header and the theme switch.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **reader**, I want **to see the sections of a package at a glance**, so that **I can find the right page in a long sidebar**. | - Each folder is an orbit row with its ring, name and page count; the open one is the sidebar's one card (ADR-0027).<br />- The orbit holding the current page is open; the others are rows.<br />- Separators group orbits under belts; top-level pages are landmarks above them.<br />- The chevron opens and closes an orbit; opening one closes the open one beside it, at every level (ADR-0023). |
| US-2 | As a **reader**, I want **to see where I am in the sidebar**, so that **I keep my place**. | - The current page is the teal probe on its orbit's arc, its row tinted, with `aria-current="page"`.<br />- Its orbit's ring takes the ecosystem colour, with a planet inside while it is open. |
| US-3 | As a **reader**, I want **to switch between Use and Maintain from the sidebar's first row**, so that **it takes no extra space**. | - The chip and the sun and moon buttons share one row.<br />- Each button has its full name as its accessible name and tooltip. |
| US-4 | As a **reader**, I want **to see how far through a page I am**, so that **I know what is left**. | - The read stretch of the path is solid with filled dots; ahead is dashed with hollow dots.<br />- A probe rides the path at the reading position. |
| US-5 | As a **reader**, I want **to know how long the rest of the page takes**, so that **I can decide to read now or later**. | - The header shows the minutes left, from the build-time word count at 220 a minute, rounded up.<br />- "End of page" at the end; no time for a page under a minute. |
| US-6 | As a **reader on a phone**, I want **the same progress and section list**, so that **I can jump without scrolling back up**. | - The bar under the header shows the ring, the current heading and the time left.<br />- Tapping opens the trajectory; choosing a heading scrolls there and closes it. |
| US-7 | As a **reader at the end of a docs page**, I want **the same footer as every page**, so that **the site feels like one place**. | - The full horizon, with its closing line and scene, closes every docs page.<br />- Its last link reads "Back to top".<br />- The sidebar and the trajectory set below its dusk edge as it comes into view, and come back as the reader scrolls up. |
| US-8 | As a **reader who prefers less motion, or uses a keyboard or a screen reader**, I want **the same information**, so that **nothing depends on animation or pointing**. | - With reduced motion, stations and the sheet open without animation and the probe jumps.<br />- Stations, headings and buttons are reachable by keyboard and named for screen readers. |

## Rules and edge cases [#rules-and-edge-cases]

- A track with no folders shows its landmarks only. A nested folder is a smaller orbit inside
  its parent's card. A folder holding only its index page is an orbit link with no count.
- A page without headings shows its reading time and "This page has no sections." on desktop,
  and no bar on phones. One heading: one dot, no path.
- Before scripts load, stations show their starting state, the path is dashed throughout with
  the total reading time, and there is no probe.
- Reading time counts the page's headings, paragraphs, quotes, tables and components, not its
  code blocks.
- While the horizon is in view, the bottom of the sidebar is hidden under it; on a page shorter
  than the window the sidebar stands partly below the horizon on arrival, and its upper part and
  its own scrolling still work.
- The horizon's sky loops only while it is on screen; with reduced motion it is still and the
  sidebar does not set.

## Out of scope for now [#out-of-scope-for-now]

- Remembering which stations a reader opened, across pages or visits: it would need browser
  storage and a decision of its own.

## Open questions [#open-questions]

None.


# PRD — home page and catalogue (/docs/maintain/prd/home-page)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx),
  [ADR-0016](../adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx),
  [ADR-0014](../adr/ADR-0014-home-page-is-a-search-first-release-map.mdx),
  [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

A developer arriving from a registry or a README needs to see what is documented, which version
a page covers, and whether a package has a demo, without guessing URLs. A maintainer needs to
find a package's release and contribution notes. A visitor curious about the owner's work needs
to see all of it at a glance.

## Goal [#goal]

- From `/`, a reader reaches any public page in two interactions or fewer: search, then choose,
  with the same Fumadocs search dialog as every other page.
- The first screen shows the shape of the whole collection as one solar system: ecosystems,
  packages, projects, version lines, and what is unreleased.
- Every planet card shows the latest released version, any unreleased `dev` version and any
  older lines, as read from the content.
- The same marks (planets, moons, day and night sides) carry the same meaning on every page.
- Every package and project has a Use track, and can have a Maintain track, reachable from the
  home page and its overview.
- Private projects have a group on the home page, beyond an asteroid belt. Today it lists three
  invented projects by the owner's decision (ADR-0017 decision 4); no real private name or
  content is on any public surface.
- The footer is useful: every planet, the Markdown routes, search and the way back up.

## Non-goals [#non-goals]

- Sign-in, and listing private projects: later ADRs (WorkOS; private documentation).
- Filters on the home page or in the search dialog.
- Documentation page design: ADR-0015 and [site pages](./site-pages.mdx).
- Usage figures, download counts, testimonials: none are on hand, and none are invented
  (`PRODUCT.md`). The invented private projects are the one exception, by the owner's decision.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **package user**, I want **to search for a package or page from the first screen**, so that **I reach its docs without guessing a URL**. | - The hero's search button, Enter or Space on it, and `⌘K` / `Ctrl K` open the Fumadocs search dialog, the same one as on every page.<br />- The home header has no second search.<br />- Arrow keys and Enter open a result; Escape closes the dialog. |
| US-2 | As a **reader**, I want **to browse packages and projects**, so that **I see everything without searching**. | - One planet card per public entry, with no section heading on screen.<br />- The header's Packages and Projects links land on the first card of each kind, from any page.<br />- Clicking a planet in the system opens its overview; every planet is labelled. |
| US-3 | As a **package user**, I want **to see which version is documented**, so that **I know the docs match what I installed**. | - Each card's fact sheet shows the `latest` line's exact version, `In development` with the `dev` version, and older lines.<br />- An unreleased package shows "unreleased".<br />- The card and the system draw one moon per line, labelled with the line's name; unreleased moons dashed.<br />- Every moon, released or not, lists each entry's lines with their phase marks. |
| US-4 | As a **developer evaluating a package**, I want **to try a demo**, so that **I can judge it before installing**. | - Planet cards link to the latest line's `demo` page when it has one.<br />- A demo that runs on the page, and a demo section on the home page, wait for ADR-0011's sandboxed embed. |
| US-5 | As a **maintainer**, I want **to reach a package's Maintain track**, so that **I find the release and contribution notes**. | - Every planet card links to Maintain when the track exists.<br />- Two sides of every planet shows what each track holds, with real pages. |
| US-6 | As a **project stakeholder**, I want **to find a public project**, so that **I can read its documentation**. | - Projects are ringed planets: on their own orbit in the system, as cards, and in the footer. |
| US-7 | As a **signed-in reader**, I want **my private projects on the home page**, so that **I reach them from the same place**. | - Private projects, beyond an asteroid belt after the cards, rendered on the server.<br />- Each is a night-side planet with a lock, a description and who it is for.<br />- With none, an empty dashed orbit says so.<br />- Today every reader sees the three invented projects (owner's decision); the sign-in ADR decides who sees the group.<br />- No private project is in `content/`, search, `llms.txt` or `static.json`, and none is a planet in the system. |
| US-8 | As a **developer or AI tool**, I want **to see how to take a page out of the site**, so that **I can use it in my tools**. | - Terminal tabs for `.md`, `llms.txt` and `Accept: text/markdown`, each with its route's real output.<br />- The live Copy Markdown button and Open menu for one real page.<br />- A link to `/llms-full.txt`; `llms.txt` lists every package and project. |
| US-9 | As a **reader who prefers less motion or uses a keyboard or screen reader**, I want **the same information without the animation**, so that **the page works for me**. | - Under reduced motion the system is still, commands don't type and nothing enters or turns.<br />- The planet cards hold everything the system shows, as text.<br />- The hero's headline and subline select with the mouse.<br />- Every control is reachable and visible on focus. |
| US-10 | As a **reader**, I want **a theme switch I can understand**, so that **I know what it will do**. | - The same height as the header's other buttons; draws the sun in front of a lit planet in light and behind a crescent in dark.<br />- Its name and tooltip say what a click does ("Switch to day side (light theme)").<br />- Shows the current theme from first paint; instant under reduced motion. |
| US-11 | As a **reader at the end of a page**, I want **a footer that takes me somewhere**, so that **I don't scroll back up to move on**. | - Every planet, Search, `llms.txt`, `llms-full.txt`, GitHub and Back to orbit.<br />- Every page has the closing line and the horizon; the closing line's *The Verse* opens the Verse view. |
| US-12 | As a **reader who followed a dead link**, I want **a way back**, so that **I am not stuck**. | - Unknown paths show "This page drifted out of orbit." with search and "Back to the system". |

## Rules and edge cases [#rules-and-edge-cases]

- Entries come only from content folders with a valid `catalog` (ADR-0013); this
  site is listed as the project `docs`.
- Counts are computed from the same entries: public packages and public projects.
- The system always draws the npm, Composer, PyPI, Go and Projects orbits, and Cargo and Other
  when an entry is in them (ADR-0032). An orbit with no planet is a thinner, fainter solid line
  with its name, and pointing at it says "No planets yet". With no public entries at all, every
  orbit is empty, the telemetry line reads `0 planets · 5 orbits waiting · 0 moons`, and the
  cards are replaced by "No planets in the Verse yet. Packages and projects appear here once
  they are documented."
- A kind with no entries has no header link.
- The private projects are three invented names in `src/components/home/private-projects.ts`
  until the private-documentation ADR; their links return the 404.
- If Algolia is unreachable, the dialog shows its error; the cards still list everything.
- More than 40 entries: further grouping, decided in its own ADR.
- Every moon shows each entry with two or more lines. Two sides shows the first entry that has
  both tracks.

## Out of scope for now [#out-of-scope-for-now]

- Sign-in, and hiding the private group from signed-out readers: the sign-in ADR. Listing
  private projects: the private-documentation ADR.
- A changelog or "recent releases" feed: no release data source is decided.
- Open Graph image for the home page: the existing OG route covers documentation pages only.

## Open questions [#open-questions]

- None open in this document; see ADR-0013, ADR-0014, ADR-0016 and ADR-0017.


# Product requirements (/docs/maintain/prd)

What a reader-facing feature must do, for whom, and how we know it works.

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- File name: `<feature-slug>.mdx`.
- User stories with acceptance criteria in *Given / when / then* form.
- **Rules and edge cases** carry the content details: versions, ecosystems, public versus private, what happens to existing pages and their URLs.
- Open questions are asked (ADR-0004), not left in the file.

**Template:** [`../_templates/prd.mdx`](../_templates/prd.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|
| [The ADR constellation](./adr-constellation.mdx) | Current | [ADR-0019](../adr/ADR-0019-adr-folders-show-as-a-constellation-in-the-sidebar.mdx) |
| [Diagrams](./diagrams.mdx) | Current | [ADR-0022](../adr/ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown.mdx) |
| [Docs sidebars](./docs-sidebars.mdx) | Current | [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx) |
| [Home page and catalogue](./home-page.mdx) | Current | [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx), [ADR-0016](../adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx), [ADR-0014](../adr/ADR-0014-home-page-is-a-search-first-release-map.mdx), [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx) |
| [Multi-repository projects](./multi-repository-projects.mdx) | Current | [ADR-0024](../adr/ADR-0024-a-project-can-span-several-repositories.mdx) |
| [Site pages](./site-pages.mdx) | Current | [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx) |
| [The universe theme](./universe-theme.mdx) | Current | [ADR-0029](../adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx) |
| [Search and sharing](./search-and-sharing.mdx) | Current | [ADR-0035](../adr/ADR-0035-every-page-is-ready-for-search-and-sharing.mdx) |


# PRD — multi-repository projects (/docs/maintain/prd/multi-repository-projects)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0024](../adr/ADR-0024-a-project-can-span-several-repositories.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

A project made of several repositories, such as a frontend, a backend and an API, has nowhere
to put its documentation: an entry has one folder written by one repository, and one
repository link. Several repositories writing one folder would edit the same files.

## Goal [#goal]

- A project of any number of repositories is one entry: one overview, one planet, one search
  scope.
- Each repository documents itself in its own folders, without touching another's.
- Readers see which repositories make up the project, and reach each one.
- Projects keep at most a `dev` line and one released line.

## Non-goals [#non-goals]

- Versions per repository.
- Private repositories or private projects (they wait for their own ADR, AGENTS.md §6.1).
- Checking which repository wrote a file.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **reader**, I want **to see a project's repositories on its overview**, so that **I know what it is made of and where its code lives**. | - Given a project with `repositories`, when I open its overview, then the planet header links each repository by name, primary first.<br />- Given a repository without a `url`, then its name shows without a link.<br />- The fact sheet lists *Repositories*. |
| US-2 | As a **reader**, I want **each repository's pages together in the sidebar**, so that **I find the frontend's pages without reading the backend's**. | - Given `use/frontend/`, when I open the Use track, then *Frontend* is a station.<br />- Pages about the whole project sit beside the repository stations.<br />- One station is open at a time (ADR-0023). |
| US-3 | As a **reader on the home page**, I want **to see that a project has several repositories**, so that **I know its scale before opening it**. | - The planet card reads *Project · 3 repositories*. |
| US-4 | As a **repository's agent**, I want **a folder only my repository edits**, so that **my changes never collide with another repository's**. | - `PROJECT_AGENTS.md` names the folders a non-primary repository edits: `use/<id>/`, `maintain/<id>/` and `diagrams/<slug>/<id>-*`.<br />- The primary repository edits the shared files. |
| US-5 | As a **maintainer**, I want **the build to refuse a wrong catalogue**, so that **a mistake never publishes**. | - Given no primary, two primaries, a duplicate or reserved id, an `http` URL, one repository only, `repositories` on a package, or both `repository` and `repositories`, when the site builds, then it fails naming the file. |
| US-6 | As a **maintainer of a project**, I want **only dev and the released line**, so that **the project's docs describe what runs now**. | - Given a project with `use/dev/` and one `latest` line, the build passes.<br />- Given a `legacy` line in a project, it fails.<br />- Packages keep their older lines. |

## Rules and edge cases [#rules-and-edge-cases]

- `id` is the folder name: lowercase letters, digits and hyphens; not `dev`, `latest`, `adr`
  or a line's segment.
- A repository folder's station title is the repository's `name`, unless its `meta.json` sets
  one.
- A repository with nothing for readers has no `use/<id>/`; one with nothing for maintainers
  has no `maintain/<id>/`.
- With lines, each line holds the repository folders: `use/dev/frontend/`,
  `use/<line>/frontend/`. A release copies `use/dev/` whole and replaces the released line;
  old links redirect to the new line.
- A one-repository project keeps `repository`; nothing about it changes but the line rule.
- Diagrams of a non-primary repository are named `diagrams/<slug>/<id>-<slug>.html`.

## Out of scope for now [#out-of-scope-for-now]

- A repository filter in search.
- Showing which repository a page came from on the page itself, beyond its breadcrumb.

## Open questions [#open-questions]

None.


# PRD — search and sharing (/docs/maintain/prd/search-and-sharing)

- **Status:** Current
- **Last updated:** 2026-11-03
- **Related ADRs:** [ADR-0035](../adr/ADR-0035-every-page-is-ready-for-search-and-sharing.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

A page's life starts outside the site: in a search result, in a shared link or in a browser tab. Today
those show a bare title, usually no description, a generic image and a local address.

## Who it is for [#who-it-is-for]

- **A developer searching** for a package's API or a guide.
- **A maintainer sharing** a link to a page or a decision.
- **Any consuming project**, which gets all of this from its folder.

## User stories [#user-stories]

| ID | Story | Acceptance |
|---|---|---|
| US-1 | As a **developer searching**, I want **the current docs to come first**, so that **I don't follow outdated instructions**. | Given a page in an older line that also exists in latest, when a search engine reads it, then its canonical link is the page in latest. |
| US-2 | As a **developer searching**, I want **a result that says what the page is for**, so that **I can choose without opening it**. | Given any page, when the site is built, then it has a written description, or the build fails naming it. |
| US-3 | As a **developer on an old version**, I want **a page only that version has to stay findable**, so that **it doesn't vanish**. | Given a page in an older line with no counterpart in latest, then it is indexed, in the sitemap and its own canonical. |
| US-4 | As a **maintainer sharing a link**, I want **a card with the page's title, its package and version, and the site's look**, so that **people know what they're opening**. | Given any page's link, when a sharing app reads it, then it gets that page's own image, title and description, with an absolute address. |
| US-5 | As **someone with many tabs**, I want **the tab to name the page and its package**, so that **I can tell them apart**. | Given a docs page, then its title is page, entry and site, with the line when it isn't latest. |
| US-6 | As **the owner**, I want **a preview never to be indexed**, so that **no draft address reaches search**. | Given no `SITE_URL`, then every page is `noindex` and `robots.txt` disallows everything; and `bun run build` refuses to publish. |
| US-7 | As **a consuming project**, I want **all of this without configuration**, so that **I only write pages**. | Given a page with a title and a description in the right folder, then everything else follows from where it sits. |

## Rules and edge cases [#rules-and-edge-cases]

- **Unreleased work:** `dev` pages are out of search. An unreleased package is found through its
  overview and Maintain until its first release.
- **Templates** in `_templates/` are out of search and readable by link.
- **Not a privacy tool:** `noindex` keeps a page out of results, not out of reach. Nothing private goes
  in `content/` (`AGENTS.md` §6.1).
- **No promise of ranking:** search engines decide what they show. The site gives them accurate signals.

## Out of scope [#out-of-scope]

Analytics, RSS, translated versions and any per-page override of indexing.


# PRD — site pages: root URLs, versions, user and maintainer docs, one look (/docs/maintain/prd/site-pages)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx),
  [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

Readers type and share package addresses, so they should be short. This site's own decisions
belong with the site, not between package docs. A reader who moves from the home page into the
docs should stay in one site, with one header, one look and a light/dark choice that holds.
Packages need a lasting place for unreleased work and should name their released lines the way
they name their releases.

## Goal [#goal]

- Every package and project is at `/<slug>`, and its folder is `content/<slug>/`.
- Every entry has the same shape: an overview, user docs (Use) with one line per release plus
  `dev` for work in progress, and maintainer docs (Maintain), unversioned. Each package names its
  own released lines.
- This site documents itself the same way: the project `docs`, its decisions and design
  documents in its Maintain track.
- Every page shares one header, one palette and one type system, in light and dark.

## Non-goals [#non-goals]

- Private projects and sign-in (their own ADR, WorkOS).
- Demos (their own ADR; ADR-0011 covers diagrams only).
- A Use track for this site (the consumer guide as pages): a later change.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **package user**, I want **a short URL for a package**, so that **I can type or share it**. | - `/<slug>` opens the overview.<br />- `/<slug>/use` opens the latest line's first page, or `dev`'s when nothing is released.<br />- `/<slug>/use/latest/<page>` redirects to that page in the latest line. |
| US-2 | As a **package user**, I want **docs for the version I installed**, so that **examples match my code**. | - Released lines carry the name the package set in their `meta.json` (`v1.4`, `2024 LTS`); the version menu lists latest, `dev`, then older lines.<br />- Each page states the version it documents; `dev` and older lines carry a banner linking to latest. |
| US-3 | As a **package user**, I want **to see unreleased changes**, so that **I can prepare for the next release**. | - A package's `dev` line is at `/<slug>/use/dev`, labelled "In development" with the default branch's version, and stays after each release. |
| US-4 | As a **maintainer**, I want **the maintainer docs one click from the overview**, so that **I find setup and release notes**. | - The hero and the track switch link to Maintain when it exists.<br />- Maintain has no version menu. |
| US-5 | As a **reader**, I want **to know what a package is at a glance**, so that **I can decide whether to read on**. | - The overview opens with the hero: ecosystem, name, description, latest and `dev` versions, version rail, Use / Maintain / registry / repository links. |
| US-6 | As a **reader**, I want **light or dark on any page**, so that **the site suits my screen**. | - Every page's header has the switch; dark is the default; the choice holds across pages and visits; no flash on load. |
| US-7 | As a **maintainer of this site**, I want **its decisions in its own Maintain track**, so that **they follow the same rules as every project**. | - `/docs` is the site's overview; ADRs and design documents are under `/docs/maintain/…`.<br />- The site appears in the catalogue as a project. |
| US-8 | As a **consuming repository**, I want **one folder shape and a build that checks it**, so that **mistakes fail before they publish**. | - Bad or reserved slugs, clashing line names, a misplaced `dev` channel, two `latest` lines and `legacy` without `latest` all fail the build with the file named. |

## Rules and edge cases [#rules-and-edge-cases]

- Reserved slugs: `api`, `auth`, `callback`, `sign-in`, `sign-out`, `og`, `search`, `static`,
  `assets`, `public`, `_next`. Slugs are lowercase letters, digits and hyphens.
- Line names: `dev` for work in progress; a released line's `name` is any string, and its URL
  segment is that name made URL-safe (`2024 LTS` → `2024-lts`). Two lines can't share a segment,
  and none may be `dev` or `latest`.
- Releasing copies `dev` into the new line; a release a package keeps in an existing line updates
  it in place.
- A deleted legacy line's URLs redirect to the same page in `latest`.
- Docs pages have no motion beyond the theme change, opening a menu or a station, and the
  trajectory's probe following the reader's scroll (ADR-0018).


# PRD — the universe theme (/docs/maintain/prd/universe-theme)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0029](../adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

The site is named *Nepal Dev Verse*, but nothing on it is bigger than one solar system. The brand
mark borrows the project mark, reading pages have no sky, and moving between the home page, a
planet and its pages feels like any other page change. The levels above a folder are named
nowhere on a docs page.

## Goal [#goal]

- One mark and one still sky on every page (stage 1).
- One scale ladder readers can see and move through: a strip on every docs page, a Verse view on
  the home page, and a zoom when they move up or down it (stage 2).
- Words that describe the site in its own terms without renaming a single control (stage 3).

## Non-goals [#non-goals]

- Changing the solar-system metaphor, the marks' meanings or the sidebar (ADR-0017, ADR-0027).
- Any motion that keeps going besides the turning system.
- Showing private projects in a new way; the Verse view uses the invented names already shown.
- Changing URLs or any Markdown surface.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **reader**, I want **every page to look like the same place**, so that **I know I am still on Nepal Dev Verse**. | - The header shows the Verse mark on every page, and the browser tab shows it as the icon.<br />- Every page stands on the same still sky, in both themes.<br />- No star sits behind text; every text contrast in DESIGN.md is unchanged. |
| US-2 | As a **reader**, I want **to see where a page sits**, so that **I can go up a level in one tap**. | - Every docs page shows the scale strip from *Verse* down to the page, with each level's mark.<br />- On a phone it shows the parent level with a back arrow and the current page.<br />- The current page has `aria-current="page"`; the strip is a `nav` labelled *Scale*. |
| US-3 | As a **visitor on the home page**, I want **to zoom out past the system**, so that **I see what the Verse is**. | - *Zoom out to the Verse* eases out to the Verse view; *Back to the system* or the system eases back.<br />- `/#verse` opens the Verse view.<br />- With reduced motion it changes instantly. |
| US-4 | As a **reader**, I want **opening a planet to feel like moving closer**, so that **I keep track of what I chose**. | - The card's planet morphs into the overview's planet header, and back.<br />- Strip and planet chip links zoom in going down and out going up.<br />- Without view transitions or with reduced motion, navigation is unchanged. |
| US-5 | As a **reader in a hurry**, I want **controls to keep their plain names**, so that **the theme never slows me down**. | - Search, Overview, Use, Maintain, On this page and version names are unchanged.<br />- Every space word appears next to a plain sentence. |

## Success [#success]

- The owner, reviewing each stage in the working tree, accepts it before the next starts.
- `impeccable detect` reports nothing new in the changed files.
- No change to `/<page>.md`, `llms.txt` or `llms-full.txt` for any page.


# Access control (/docs/maintain/rbac)

Who may read and do what — public readers, people given access to a private project, and the
owner — on every surface a page appears on.

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- File name: `<feature-slug>.mdx`; `system.mdx` once more than one feature has access rules.
- Action matrix plus surface-level visibility: a page's access rule applies to its Markdown, `llms.txt` entry, OG image and search record too.
- State whether a denied page is hidden (404) or visible-but-locked (403), and why.
- Authorization is enforced server-side; the matrix says where.

**Template:** [`../_templates/rbac.mdx`](../_templates/rbac.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|

None: there is no access control. Every page is public to everyone, the home page's Private
projects group and its empty state included (ADR-0016). The sign-in ADR writes the first matrix,
and the ADR that decides how private project documentation is served extends it.


# Security audit checklist (/docs/maintain/security/checklist)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** ADR-0005, ADR-0011

> Snapshot of the system as it stands today. Edit in place; never record what changed.

The per-change check lives in `AGENTS.md` §9. The audits below run in full **before the first
internet-reachable deployment** and **before each release** of the site. Findings are
reported as: what it is · where it is · how it would be exploited · the fix. Fix data exposure
and unauthorized access first, abuse and logic flaws second.

## Audit 1 — Secret leak prevention [#audit-1--secret-leak-prevention]

- [ ] `grep` the tree and git history for keys, tokens, connection strings, private keys.
- [ ] Every variable the code reads is in [`secrets.mdx`](./secrets.mdx) and `.env.example`.
- [ ] No `NEXT_PUBLIC_*` carries a secret; inspect the client bundle for each one.
- [ ] Build output, error pages and `content/` examples contain no secret or real token.

## Audit 2 — Private content exposure [#audit-2--private-content-exposure]

- [ ] Every page in `content/` belongs to a public package or project, or is handled as
      its private-documentation ADR requires.
- [ ] For each private page: absent from (or protected on) the rendered site, the Markdown
      route, `llms.txt`, `llms-full.txt`, `static.json`, the share image route, `sitemap.xml`,
      each page's structured data and the search index. Check each surface on the deployed site, not only in code.
- [ ] Query the live Algolia index with the public search-only key; confirm it returns only
      Public records.
- [ ] "View on GitHub" links point only at a repository whose visibility matches the page.
- [ ] No client name, internal hostname or personal data in any page, example or screenshot.

## Audit 3 — Pre-deploy production [#audit-3--pre-deploy-production]

- [ ] The publishing build refuses to run without its secrets and without `SITE_URL`.
- [ ] `SITE_URL` is set on the production host and on no preview; `robots.txt` names the sitemap on
      production and disallows everything on a preview.
- [ ] The host clones the repository in full, so `lastmod` is true (ADR-0035).
- [ ] The 404's one-year `s-maxage` (ADR-0034) does not outlive a deploy in the host's cache.
- [ ] TLS everywhere.
- [ ] Security headers set (CSP, frame-ancestors, referrer policy) and verified.
- [ ] Placeholder settings replaced: `appName` and `gitConfig` in `src/lib/shared.ts`.

## Audit 4 — Content integrity [#audit-4--content-integrity]

- [ ] Install commands, package names and versions on each package page match the published
      package's manifest.
- [ ] Examples run against the version the page documents.
- [ ] Dependencies are pinned through `bun.lock`; no unreviewed dependency in the build.

## Audit 5 — Attacker's perspective [#audit-5--attackers-perspective]

- [ ] Request every page of a private project through each machine-readable route and the
      `Accept: text/markdown` negotiation.
- [ ] Try to write to the Algolia index with the search-only key; confirm it is refused.
- [ ] Search for terms that appear only in private content; confirm no results.

## Tool-specific checks [#tool-specific-checks]

### Algolia [#algolia]

- [ ] `NEXT_PUBLIC_ALGOLIA_SEARCH_KEY` is a search-only key, with no write or admin ACL.
- [ ] `ALGOLIA_WRITE_KEY` is scoped to the `document` index only, and held only in local
      `.env.local` and the host's secret store.
- [ ] The index contains exactly the Public pages of the last build, and nothing else.

### Archify diagrams (ADR-0011, ADR-0022) [#archify-diagrams-adr-0011-adr-0022]

- [ ] Every file in `diagrams/` is `<project-slug>/<slug>.html` or `.json`, in pairs, nothing is
      in `public/diagrams/`, and no `*.delivery*.json` is in `diagrams/` or `public/` (the build
      checks all three).
- [ ] No published diagram holds a local path (`/Users/`, `/home/`, `/private/`), a secret, an
      internal hostname, or anything about a private project.
- [ ] The HTML loads no external script, stylesheet, font or image and calls no network API
      (`fetch`, `XMLHttpRequest`, `WebSocket`, `sendBeacon`). Run again after every Archify
      upgrade.
- [ ] The deployed site serves `/diagrams/…` with
      `Content-Security-Policy: sandbox allow-scripts allow-downloads`, and every embed frame
      has `sandbox="allow-scripts allow-downloads"` without `allow-same-origin`.
- [ ] The site shell (`src/lib/diagram-shell.ts`) adds no network call and posts only
      `{ type: 'archify-height', height }` and `{ type: 'archify-present' }`; `<Diagram>`
      accepts them only from its own frame's window, a height only within 120 to 4000, and on
      a Present request opens only that diagram's own URL, built by the page.
- [ ] Embed frames delegate fullscreen (`allow="fullscreen"`) and nothing else.


# Data classification (/docs/maintain/security/data-classification)

- **Status:** Binding (ADR-0005, approved 2026-11-01)
- **Last updated:** 2026-10-31
- **Related ADRs:** ADR-0005

> Snapshot of the system as it stands today. Edit in place; never record what changed.

Every piece of content, every stored field and every piece of data that leaves the system has
one level. When a level is unclear, **ask** — never assign one by assumption
([ADR-0004](../adr/ADR-0004-ask-never-guess.mdx)).

## Levels [#levels]

| Level | Meaning | Examples | Handling |
|---|---|---|---|
| **Public** | Safe for anyone, anywhere | Documentation of public packages and public projects; the Algolia app ID and search-only key | May go on every published surface |
| **Internal** | Not secret, not meant for readers | Build configuration, unfixed security findings | Stays in the repository or with the owner; never in `content/` |
| **Confidential** | Belongs to a private project | Its documentation, architecture, internal APIs, roadmap, hostnames | Never on a public surface; served only as its ADR decides, to the readers it names |
| **Restricted** | Disclosure enables abuse or harms someone else | Secrets and API keys, client names and client data, personal data | Never in content, examples, screenshots, logs or the search index; secrets only in environment files and secret stores |

## Classified so far [#classified-so-far]

| Data | Level | Why |
|---|---|---|
| `content/<slug>/` (package and project pages; today only this site's own, `content/docs/`) | Public | Published on every surface today |
| `content/docs/maintain/` (this site's decisions, design and security documents) | Public | Published by the owner's decision (ADR-0002); holds variable names, never values |
| `NEXT_PUBLIC_ALGOLIA_APP_ID`, `NEXT_PUBLIC_ALGOLIA_SEARCH_KEY` | Public | Shipped to every browser by design |
| `ALGOLIA_WRITE_KEY` | Restricted | Write access to the live search index |
| GitHub usernames of deciders and approvers in ADRs | Public | Already public on GitHub; written only with the owner's yes for anyone but the owner, `puncoz` (ADR-0020). A person's other personal data stays Restricted |

## Rules that follow [#rules-that-follow]

- **A page's level is decided before it is written.** If a project's visibility is not
  recorded, ask.
- **Published surfaces carry Public content only**, until an ADR defines how Confidential
  content is served.
- **Third-party crossings** (`content/docs/maintain/dfd/`) state the level of everything sent.
- **Examples use invented values**, so they stay Public whatever they document.

## Open [#open]

For the owner to decide with the private-documentation ADR:

- Where Confidential content lives: a separate repository, a separate deployment, or this site
  behind authentication.
- Whether a private project's *existence* (its name in a list) is Public or Confidential.


# Security (/docs/maintain/security)

How puncoz-packages-docs protects what it holds. Security and privacy are a property of
**every change**, not a pre-deploy event — see
[ADR-0005](../adr/ADR-0005-security-as-a-standing-practice.mdx).

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Documents [#documents]

| File | Answers |
|---|---|
| [`threat-model.mdx`](./threat-model.mdx) | What is worth protecting, from whom, and what stops them |
| [`data-classification.mdx`](./data-classification.mdx) | How sensitive a piece of content or data is, and how it must be handled |
| [`secrets.mdx`](./secrets.mdx) | Every secret: what it is, where it lives, whether it reaches the browser |
| [`checklist.mdx`](./checklist.mdx) | The audits, and the gates at which they run |
| `<feature-slug>.mdx` | A feature's own threat surface, when it warrants one |

**Template:** [`../_templates/security.mdx`](../_templates/security.mdx)

## The rules that matter most [#the-rules-that-matter-most]

**1. Never guess at a security decision.** Whether a project is private, who may read it,
whether a route is public, what is sent to the search provider — the owner decides, and it is
recorded ([ADR-0004](../adr/ADR-0004-ask-never-guess.mdx)).

**2. Private stays private.** Today every page in `content/` is published on every
surface: the site, the Markdown routes, `llms.txt` / `llms-full.txt`, `static.json`, share images,
`sitemap.xml`, structured data and the search index. **No private project content goes there** until an ADR decides how it is
kept and served (`AGENTS.md` §6.1).

**3. Published is permanent.** A page that was served, indexed or crawled cannot be recalled.
Treat it as public from that moment, and rotate anything secret it contained.

**4. Tool-specific rules arrive with the tool.** Algolia is adopted, and its checks are in
[`checklist.mdx`](./checklist.mdx#tool-specific-checks). When a host, analytics, CI or an
authentication provider is adopted, **its ADR adds its own entries there**. This project makes
no claim about tools it has not adopted.


# Secrets inventory (/docs/maintain/security/secrets)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** ADR-0005, [ADR-0016](../adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Inventory [#inventory]

The variables are read directly where they are used. Locally they live in `.env.local`, which
`.gitignore` excludes (`.env*.local`). `.env.example` at the repository root lists every
variable below, with a comment and no value.

| Variable | What it is | Secret? | Reaches the browser? | Read by | Rotation |
|---|---|---|---|---|---|
| `SITE_URL` | The site's public address, an `https` origin with no path; without it every page is `noindex` (ADR-0035) | No — public, and printed on every share image | Only as the address in pages' links and images; never as a variable | `src/lib/seo.ts`, `src/app/og/[...slug]/route.tsx`, `scripts/sync-content.ts` | When the domain changes |
| `NEXT_PUBLIC_ALGOLIA_APP_ID` | Algolia application ID | No | **Yes**, inlined into the client bundle | `src/lib/algolia.ts`, `scripts/sync-content.ts` | With the Algolia application |
| `NEXT_PUBLIC_ALGOLIA_SEARCH_KEY` | Algolia search-only API key | No — public by design, but it can read **every record** in the index | **Yes**, inlined into the client bundle | `src/lib/algolia.ts` | On suspicion of abuse, in the Algolia dashboard |
| `ALGOLIA_WRITE_KEY` | Algolia key with write access to the index | **Yes** | No | `scripts/sync-content.ts` only | On suspicion, or yearly, in the Algolia dashboard |

## Rules [#rules]

- **No secret is ever a string literal** — not in source, config, comments, tests or docs.
- **`NEXT_PUBLIC_*` publishes a value to every browser.** Never a secret; each one is reviewed
  as a publication. `ALGOLIA_WRITE_KEY` must never gain the prefix.
- **`.env*.local` files stay out of git.** `.env.example` is committed and documents every
  variable with a comment, never a value.
- **A build that publishes refuses to run without the secrets it needs**, naming the variable
  and never printing its value. `scripts/sync-content.ts` refuses in the same way without `SITE_URL`,
  so production cannot silently go `noindex`.
- **If a secret is ever committed, rotate it immediately.** Removing it from the tree or from
  history is not enough.


# Threat model — puncoz-packages-docs (/docs/maintain/security/threat-model)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** ADR-0005, [ADR-0016](../adr/ADR-0016-home-search-is-the-fumadocs-dialog-and-private-projects-render-server-side.mdx),
  [ADR-0017](../adr/ADR-0017-the-whole-site-is-one-solar-system.mdx),
  [ADR-0011](../adr/ADR-0011-archify-diagrams-are-embedded-from-sandboxed-html.mdx),
  [ADR-0022](../adr/ADR-0022-diagrams-show-archify-on-the-page-and-mermaid-in-markdown.mdx),
  [ADR-0020](../adr/ADR-0020-people-in-adrs-are-github-usernames-shown-as-profile-chips.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Current attack surface [#current-attack-surface]

The site is static pages built from `content/`, one folder per package or project at
`/<slug>/…`, served with their Markdown, `llms.txt` / `llms-full.txt`, share images and `static.json`, plus Algolia
search ([`../architecture/system.mdx`](../architecture/system.mdx)). Every page is prerendered
(Cache Components, ADR-0016); none reads cookies or headers. There is no sign-in, no database
and no user input beyond the search box. The home page's Private projects group is public
static markup listing three invented projects from `src/components/home/private-projects.ts`
(ADR-0017 decision 4); it holds no private data.

| Surface | Present | Detail |
|---|---|---|
| Authentication / sessions | No | — |
| Route handlers | Yes | Markdown, `llms.txt`, `llms-full.txt`, share images, `static.json`, `robots.txt`, `sitemap.xml`, the manifest, the Apple icon, the Archify diagrams under `/diagrams/` — all public, all static ([`../api/content-routes.mdx`](../api/content-routes.mdx), [`../api/crawler-routes.mdx`](../api/crawler-routes.mdx)) |
| User input of any kind | Yes | The search query, sent from the browser straight to Algolia; the `Accept` header, read by `src/proxy.ts`; the request's path, compared by `src/proxy.ts` with a fixed list and never echoed |
| Database or persistence | No | Content is files; the search index is a build output |
| Files / uploads | No uploads | Archify diagrams in `diagrams/`: generated script, committed by the owner, served with the site shell's added script and style, run in a sandboxed frame and served with a CSP `sandbox` header. The frame sends the page one message, its height, which the page takes only from that frame's window and only as a number from 120 to 4000 (ADR-0011, ADR-0022, [`../api/content-routes.mdx`](../api/content-routes.mdx)) |
| Secrets / environment variables | Yes | Three Algolia variables, listed in [`secrets.mdx`](./secrets.mdx) |
| Third-party integrations | Yes | Algolia (search). GitHub serves the avatar in each profile chip to the reader's browser, without a referrer (ADR-0020). The page actions' Open in ChatGPT, Claude, Cursor and Scira links, on docs pages and the home page, send a public page's URL to that service when the reader clicks one. The fonts are fetched by `next/font` at build time and served from the site's own origin |
| Logging / audit trail | No | The sync script prints a record count |

Each ADR that adds a surface updates this table in the same change.

## Assets to protect [#assets-to-protect]

| # | Asset | Harm if exposed or corrupted |
|---|---|---|
| A1 | Private project documentation | Architecture, internal APIs, hostnames or client names published and crawled; cannot be recalled |
| A2 | `ALGOLIA_WRITE_KEY` | Anyone can replace or wipe the search index, or plant pages in it |
| A3 | Integrity of published package docs | A wrong install command or a tampered example is copied into other people's projects |
| A4 | Unfixed security findings | Published in these maintainer pages before the fix, they are an attack plan; they go to the owner, not into these pages (ADR-0002) |
| A5 | The owner's identity and reputation | Pages or search results that appear to be the owner's but are not |

## Adversaries to design for [#adversaries-to-design-for]

| Adversary | Goal | Typical path |
|---|---|---|
| Anyone on the internet | Read private documentation | The site, `llms-full.txt`, `static.json`, or the search index with the public search-only key |
| Crawlers and LLM scrapers | Collect everything published | `llms.txt` / `llms-full.txt`, the Markdown routes — intended for public content, indiscriminate for private |
| Someone holding a leaked write key | Deface or poison search | Direct writes to the Algolia index |
| A malicious contribution or dependency | Tamper with content or the build | A changed example, a compromised package in the build |

## Trust boundaries [#trust-boundaries]

Crossed today, each in [`../dfd/system.mdx`](../dfd/system.mdx):

| Boundary | Carries |
|---|---|
| Build ↔ Algolia | Every page's search record, with the write key |
| Browser ↔ Algolia | Search queries and results, with the search-only key |
| Browser ↔ GitHub | Avatar requests for profile chips: the reader's IP address and user agent, no page address |
| Site ↔ public | Every page on every surface |

Anticipated, each documented by the ADR that introduces it:

| Boundary | Will carry |
|---|---|
| Repository ↔ host | The build and its environment variables |
| Site ↔ authentication provider | Reader identity, if private docs are served from this site |
| Site ↔ analytics | Page views, if analytics is adopted |

## Accepted risks [#accepted-risks]

| Risk | Why accepted | Guard |
|---|---|---|
| GitHub sees which IP addresses load which avatars, so it can tell that someone read a page naming that user (A5 for readers' privacy). | The owner chose live avatars over a committed copy or an image proxy (ADR-0020). | `referrerpolicy="no-referrer"`; avatars load lazily, only when the chip is near the viewport. |
| The avatar is whatever the GitHub account sets, shown on the site. | It is that person's own profile picture, shown at 20px as decoration. | The chip's name and link come from the page, not from GitHub. |
| A future Archify release adds a network call or an external resource to the generated diagrams; the sandbox does not block outgoing requests. | Diagrams are made with Archify by the owner's standing choice; Archify 3.2.0 makes none. | Each upgrade needs the owner's yes, and its HTML is scanned before it is published (checklist, Archify). |
| The private projects list (`src/components/home/private-projects.ts`) is the one place in code where a private project's name is typed. Someone may later replace an invented name with a real client's, publishing it on the home page and to crawlers (A1). | The owner chose to show invented private projects on the live site (ADR-0017). | The file's comment says only invented names belong there until the private-documentation ADR; a real name there breaks invariant 1. The list is never sent to search, `llms.txt` or `static.json`. |
| Visitors take the invented private projects as real, and their links return the 404 (A5). | The owner's decision, ADR-0017. | Replacing the list is a one-file change. |

## Incidents [#incidents]

None.


# Sequence — Build and search sync (/docs/maintain/sequence/build-and-search-sync)

- **Status:** Current
- **Last updated:** 2026-10-31
- **Related ADRs:** none yet — scaffold behaviour

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Trigger [#trigger]

`bun run build`. It runs `next build`, then
`node --env-file-if-exists=.env.local scripts/sync-content.ts`.

## Diagram [#diagram]

```mermaid
sequenceDiagram
  autonumber
  actor O as Owner
  participant N as next build
  participant F as .next/ output
  participant S as sync-content.ts
  participant A as Algolia

  O->>N: bun run build
  N->>N: compile content/ (Fumadocs MDX)
  N->>F: static pages, Markdown routes, share images, static.json
  N-->>O: build done
  O->>S: (same command, second step)
  S->>F: glob .next/server/{app,route-cache/*/*/$}/static.json.body
  F-->>S: records
  S->>A: sync(index "document", records) with ALGOLIA_WRITE_KEY
  A-->>S: ok
  S-->>O: "search updated: N records"
```

## Failure paths [#failure-paths]

| Step | Failure | Behaviour | Recovery |
|---|---|---|---|
| 2 | Invalid MDX or frontmatter | `next build` fails; the sync never runs | Fix the page, rebuild |
| 5 | `SITE_URL` missing from the environment | The script throws, naming the variable, before reading anything; the index is unchanged (ADR-0035) | Set `SITE_URL`, then re-run the build |
| 6 | `static.json.body` not found (unknown build adapter layout) | The script throws reading an undefined path; the index is unchanged | Check the build output layout; adjust the glob |
| 8 | Algolia variables missing from the environment | The script does not check for them (non-null assertions), so `undefined` reaches the Algolia client; where it fails has not been verified | Set the variables (`content/docs/maintain/security/secrets.mdx`) |
| 8 | Algolia rejects or is unreachable | The script fails after a successful build | Re-run the build, or the sync step alone |

## Post-conditions [#post-conditions]

The Algolia index `document` holds exactly the pages in this build — every page in
`content/`. Anyone with the public search-only key can query all of them.


# Sequence diagrams (/docs/maintain/sequence)

Flows that span actors or systems, run asynchronously, or retry — the build and search sync,
docs generated from a package's source, deploys.

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- File name: `<flow>.mdx`.
- Mermaid `sequenceDiagram` with `autonumber`, then failure paths (step, failure, behaviour, recovery) and post-conditions.

**Template:** [`../_templates/sequence.mdx`](../_templates/sequence.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|
| [Build and search sync](./build-and-search-sync.mdx) | Current | — (Fumadocs scaffold) |


# State machines (/docs/maintain/state)

Lifecycles of entities with more than two states or guarded / timed transitions — a page's
draft → published → deprecated, a package version from pre-release to end of life, a private
project made public.

> **Living snapshots.** Edit in place so each file describes the system as it is right now. No
> revision tables, no "previously X, now Y" — delete what is no longer true
> ([ADR-0002](../adr/ADR-0002-living-design-documentation.mdx)).

## Conventions [#conventions]

- File name: `<entity>.mdx`.
- Mermaid `stateDiagram-v2`, then tables of states, transitions (trigger, guard, side effects — including what is published or removed) and terminal states.

**Template:** [`../_templates/state.mdx`](../_templates/state.mdx)

## Documents [#documents]

| Document | Status | ADR |
|---|---|---|
| [Package version line](./package-version-lifecycle.mdx) | Draft | [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx) |


# State machine — package version line (/docs/maintain/state/package-version-lifecycle)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0013](../adr/ADR-0013-packages-and-projects-share-one-catalogue-shape.mdx),
  [ADR-0015](../adr/ADR-0015-every-entry-lives-at-the-root-in-one-shape-and-one-look.mdx),
  [ADR-0024](../adr/ADR-0024-a-project-can-span-several-repositories.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

A **line** is one documented version of a package's Use track: a folder under `use/` whose
`meta.json` sets `channel` and the exact `version` it documents (ADR-0013, ADR-0015).

- **`use/dev/`** is the unreleased work in progress on the default branch: always that folder,
  always `channel: "dev"`, always at `/<slug>/use/dev`.
- **A released line** has any folder name and a `name` (`v1.0`, `4.x`, `2024 LTS`; the folder
  name when unset). Its URL segment is the name in lowercase, spaces as `-`, other characters
  outside `a-z 0-9 . _ -` dropped: `/<slug>/use/2024-lts`.

The consuming repository moves a line from one state to the next by editing those files, and a
human commits the change (ADR-0010).

**Projects have no Legacy state** (ADR-0024). A versioned project has Dev and at most one Latest
line, for the whole project: with several repositories each line holds their folders
(`use/dev/frontend/`). A release copies `dev/` to the new Latest line and removes the previous
one, which goes straight from Latest to Removed; links to it redirect to the new line. The build
fails on a `legacy` line in a project. The lifecycle below is a package's.

The diagram is drawn with Archify from its source, `diagrams/docs/package-version-lifecycle.json`; the page shows
it and its Markdown carries the Mermaid (ADR-0022).

## Diagram [#diagram]

```mermaid
stateDiagram-v2
  [*] --> Dev: open use/dev/
  Dev --> Latest: release, copy dev/ to a named line
  Latest --> Legacy: a newer line becomes latest
  Legacy --> Latest: the newer line is withdrawn
  Legacy --> Removed: stop documenting the line
  Dev --> Removed: development stops
  Removed --> [*]
```

A release does not move `dev` itself: the copy becomes the new Latest line and `use/dev/` keeps
documenting the next version.

## States [#states]

| State | Meaning | Who can see it |
|---|---|---|
| Dev | Documents the unreleased version (`4.0.0-dev.3`). Every page carries the "In development" banner. At most one per package. | Everyone, for a public package |
| Latest | Documents the newest released version. The `use/latest/…` alias redirects here. Exactly one per released package. | Everyone |
| Legacy | Documents an older version that is still in use. Every page carries the "Older version" banner. | Everyone |
| Removed | The folder is deleted; its pages no longer exist. | Nobody. URLs redirect (see below) |

## Transitions [#transitions]

| From | To | Trigger | Guard | Side effects |
|---|---|---|---|---|
| — | Dev | The consuming repository adds `use/dev/` with `channel: "dev"` | Only that folder may use `dev` | Pages published with the banner; the home page row shows `dev <version>`; search and `llms.txt` include them, labelled |
| Dev | Latest (a new line) | A release: `dev/` is copied to a new folder with a `name`, the released `version` and `channel: "latest"` | The previous `latest` moves to Legacy in the same change; the new name's segment is not taken | The alias moves; links to removed lines redirect to the same path in the new line; the home page row shows the new version |
| Latest | Legacy | Another line becomes latest | Same change as above | Banner added; the line stays in the version menu |
| Legacy | Latest | The newer release is withdrawn | Same change removes the newer line | The alias moves back |
| Legacy | Removed | The folder is deleted | — | Its URLs redirect to the same path in `latest` (404 there if that page doesn't exist); Algolia records removed on the next index sync |
| Dev | Removed | `use/dev/` is deleted | — | Its URLs redirect to the same path in `latest`; a package with no `latest` has nowhere to redirect, so they return 404 |

The version menu lists Latest first, then Dev, then Legacy lines in the order of `use/meta.json`
`pages`, or newest version first when `pages` does not name them.

The build fails (`src/lib/catalog-plugin.ts`) when a line misses `version` or `channel`, when
`channel: "dev"` is used outside `use/dev/` or `use/dev/` has another channel, when a name's
segment is empty, `dev`, `latest` or ends in `.md`, when two lines share a segment, when pages
sit directly in a versioned `use/`, when a package has two `latest` lines, or when it has
`legacy` lines but no `latest`. The redirects are in `src/proxy.ts`: `use/latest/…` and any
segment that is not a line go to `latest`, or to `dev` when nothing is released. A package
with only `dev` is unreleased, and the catalogue shows it as such.

## Terminal states [#terminal-states]

**Removed** is final. Its pages are gone from the site, `llms.txt` and the next index sync. Pages
already crawled or copied elsewhere cannot be withdrawn (ADR-0005). Restoring a line is adding
it again as a new folder.