App flow — site pages: root URLs, header and docs pages

• Status: Current
• Last updated: 2026-11-01
• Related ADRs: ADR-0018, ADR-0017, ADR-0016, ADR-0015, ADR-0013, ADR-0014

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; the sidebar's stations and "On this page" in Docs sidebars. 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 pointsCopy Anchor Link

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

FlowCopy Anchor Link

ScreensCopy Anchor Link

0. Header — on every pageCopy Anchor Link

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>Copy Anchor Link

The planet header (The solar system, 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>Copy Anchor Link

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, 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 sidebarCopy Anchor Link

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>Copy Anchor Link

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>Copy Anchor Link

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 — /docsCopy Anchor Link

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 FooterCopy Anchor Link

Drawn in The solar system: the orrery theme switch (screen 1) and, below every docs page, the full Horizon footer (screen 5).