create-ginko 0.4.0 → 0.6.0

package/templates/docs/README.md

@@ -0,0 +1,255 @@
+# Docs
+
+A documentation site to start from: a start page, guides and a reference in three sections, a changelog, search,
+and the same pages in English and German, with light and dark mode. The sample documents "Orbit SDK", a made-up
+TypeScript client for a made-up monitoring API. Built with [Nuxt](https://nuxt.com),
+[Ginko](https://github.com/lupinum-dev/ginko) and its docs layer
+[`@lupinum/ginko-docs`](https://www.npmjs.com/package/@lupinum/ginko-docs). All content is Markdown in `content/`;
+the site needs no account and no database.
+
+| Light | Dark |
+|---|---|
+| ![The start page in light mode](.github/screenshots/home-light.png) | ![A reference page in dark mode](.github/screenshots/page-dark.png) |
+
+## Quick start
+
+```bash
+npm create ginko@latest my-docs -- --template docs
+```
+
+This copies the template into `my-docs`, keeps the languages you choose (`--locales en` for English only,
+`--locales de,en` for German first), sets the site id and writes a `.env` with a new `NUXT_APP_SECRET`. Then:
+
+```bash
+cd my-docs
+npm install
+npm run dev
+```
+
+Or copy the folder as it is, with both languages, through Nuxt's own command:
+
+```bash
+npm create nuxt@latest my-docs -- -t github:lupinum-dev/ginko/templates/docs#release
+```
+
+Copy `.env.example` to `.env` and fill in `NUXT_APP_SECRET` (see below). The `#release` branch follows the latest
+Ginko release, so both commands give you the same files.
+
+## Deploy
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Flupinum-dev%2Fginko%2Ftree%2Frelease%2Ftemplates%2Fdocs&env=NUXT_APP_SECRET&envDescription=Signs%20the%20share%20card%20URLs.%20Any%2032%20or%20more%20random%20characters.)
+
+Any host that runs Node works: `npm run build` writes a server to `.output/`, started with
+`node .output/server/index.mjs`. Set these variables where the site runs:
+
+| Variable | What |
+|---|---|
+| `NUXT_APP_SECRET` | Signs the URLs of the share cards. 32 or more random characters (`openssl rand -hex 32`). |
+| `NUXT_PUBLIC_SITE_URL` | The address of the live site, for example `https://docs.my-library.dev`. On Vercel the production address is used when this is not set. |
+
+A build on Vercel stops with a message while the address is still `example.com`, so search engines never see wrong
+links. Other builds (CI, your computer) only print a warning.
+
+### Static files
+
+Docs change only when you change a file, so they can also be plain files on any static host (GitHub Pages,
+Netlify, an S3 bucket):
+
+```bash
+NUXT_PUBLIC_SITE_URL=https://docs.my-library.dev npm run generate
+```
+
+The pages, their Markdown versions (`/docs/<page>.md`), the search index, the sitemap, `llms.txt` and the share
+cards are written to `.output/public/`; upload that folder. A static site needs no `NUXT_APP_SECRET`. What changes:
+
+- Every change goes live with the next build, so let your host build on every push (Vercel, Netlify and Cloudflare
+  Pages do this by default).
+- A release dated after the build day appears with the first build on or after that date, so a site with scheduled
+  releases needs a daily rebuild (for example a Vercel cron job or a scheduled GitHub Action that triggers the build).
+  `draft: true` in a release file holds that release back until you remove it. Nothing else goes stale between
+  builds. If you add a banner (`docs.banner` in `app/app.config.ts`), it changes with the next build as well.
+- The MCP endpoint for AI agents (`POST /__ginko/docs-mcp`) needs the server; a static site has none. Agents can
+  still read `llms.txt` and the `.md` version of every page.
+
+## Develop, build, preview
+
+| Command | What |
+|---|---|
+| `npm run dev` | the site with live reload on http://localhost:3000 |
+| `npm run check` | Checks the content files in a few seconds: missing or wrong fields, dates, links between pages and files in `public/`. Each problem names the file and the field. |
+| `npm run build` | the production build in `.output/` |
+| `npm run preview` | runs that build locally |
+| `npm run generate` | static files instead of a server (see above) |
+| `npm run lint` | ESLint |
+| `npm run typecheck` | TypeScript and Vue types |
+
+`.github/workflows/ci.yml` runs lint, typecheck and build on every push. It needs no settings. The build also checks
+every link inside the pages: a link to a page or a heading that does not exist stops it, with the file and the link.
+
+## Edit content
+
+Every text is a Markdown file. After each change, run `npm run check`. The main language has no suffix
+(`webhooks.md`); a translation adds the language code (`webhooks.de.md`). The number at the start of a file name sets
+the order in the navigation. Write dates as `2026-11-20`.
+
+| On the site | File |
+|---|---|
+| Start page: title, text, install command, the two buttons, the cards, the text below | `content/home.md`, `content/home.de.md` |
+| Docs pages | `content/docs/<n>.<name>.md`; the German file sets its own address with `slug:` |
+| Changelog | `content/changelog/v<x>-<y>-<z>.md` with `version` and `date`; the translation holds only the text |
+| Site name, description for search engines | `ginko.config.ts` (`name`, `seo.description`) |
+| Logo, footer links, "Edit this page" | `app/app.config.ts` |
+| Texts of your own links | `i18n/en.json`, `i18n/de.json` |
+
+**A docs page** has `title` and `description` (the lead under the title, and the text search engines show) in its
+frontmatter. `section: Guides` starts a group in the navigation; the pages after it belong to it until the next
+`section`. `badge: New` puts a label next to the title. The address is the file name without the number
+(`3.authentication.md` → `/docs/authentication`) or the `slug`.
+
+**Links between pages** are written as `[Webhooks]($docs.webhooks)`: the name of the file, not its address. The link
+then goes to the page in the reader's language and keeps working when a translation has another address. Add
+`#heading` for a section. `[Changelog]($page.changelog)` links to the changelog. The start page's buttons and cards
+take the same form (`href: $docs.getting-started`). Renaming a file breaks the links to it (`npm run check` names each
+one); changing the `slug` does not.
+
+**A new release** is one new file in `content/changelog/`, for example `v2-2-0.md`:
+
+```md
+---
+version: 2.2.0
+date: 2026-11-20
+---
+
+### Added
+
+- `incidents.list()` takes `since`.
+```
+
+Add `v2-2-0.de.md` with the German text (no frontmatter needed). The changelog orders releases by `date`, newest
+first. Use dashes in the file name: a dot would read as a language code.
+
+**An outdated translation.** When you change an English page, change its `.de.md` file in the same commit, or note
+it in the pull request. In the files there is no marker for "outdated"; in Ginko Studio (below), an English change
+marks the German page as outdated under **Inhalte > Übersetzungen**. To find German pages that may be behind,
+compare the last change of both files: `git log -1 --format=%cs -- content/docs/6.webhooks.md content/docs/6.webhooks.de.md`
+(a newer date on the English file means the German page may be outdated).
+
+**A page without a translation** stays out of the German navigation and search. Links to it from German pages go to
+the English page, and on that page the language menu says "Not translated: opens the start page" next to Deutsch, so
+no reader lands on a missing page. `content/docs/7.upgrading-to-v2.md` is such a page.
+
+## Make it yours
+
+- **Name and logo.** `name` in `ginko.config.ts` is the name in the header and in page titles. The sample name
+  "Orbit SDK" also appears as text in `seo.description` (same file), in the start page (`content/home.md`,
+  `content/home.de.md`), in the descriptions and text of the docs pages, and in `docs.footer.api` in `i18n/en.json` and
+  `i18n/de.json`. Search `content/` and `i18n/` for "Orbit" and replace what is left. The logo is
+  `public/logo.svg` (and `public/logo-dark.svg` for dark mode), set in `app/app.config.ts` (`docs.logo`); remove
+  `logo` to show only the name. Replace `public/favicon.svg` too.
+- **Colour.** The five tokens in `app/assets/css/main.css` (`--primary`, `--primary-foreground`, `--ring`,
+  `--accent`, `--accent-foreground`, each with a light and a dark value), and the light `--primary` as `seo.color` in
+  `ginko.config.ts` (the background of the share cards). Text on the colour needs a contrast of at least 4.5:1 in both
+  modes; check each pair with a contrast checker (for example webaim.org/resources/contrastchecker). `DESIGN.md` has
+  the rules and the contrast of each pair.
+- **Fonts.** `--font-sans` and `--font-mono` in `main.css`. The layer serves Inter and JetBrains Mono itself; another
+  face needs its files and an `@font-face` rule. The layer always preloads Inter, so a site with another face still
+  loads it.
+- **Repository.** Set the `repository` constant at the top of `app/app.config.ts` to your own Git host (for GitHub,
+  `'https://github.com/<you>/<repo>'`). `docs.repository` uses it for "Edit this page" and "Report an issue" under
+  every page, and the footer `source` link uses it too. If your docs live in a subfolder of a larger repository, set
+  `editUrl: '{url}/edit/{branch}/docs/{source}'`.
+- **Header and footer links.** `docs.nav` (after Docs and Changelog) and `docs.footer.links` in `app/app.config.ts`;
+  the text of each is `docs.nav.<id>` or `docs.footer.<id>` in `i18n/<language>.json`. `docs.social` adds icon links
+  such as GitHub. `docs.banner` shows a notice above the header that readers can close.
+
+Every option of the layer is in the [`@lupinum/ginko-docs` README](https://www.npmjs.com/package/@lupinum/ginko-docs).
+
+## Add a page
+
+Add a Markdown file to `content/docs/`, for example `content/docs/12.testing.md`:
+
+```md
+---
+title: Testing
+description: Run your tests against a mock of the Orbit API.
+---
+
+## Use a test key
+…
+```
+
+It answers at `/docs/testing`, comes last in the navigation (the number sets the place) and is in the search. Add
+`content/docs/12.testing.de.md` with a German `title`, `description`, `slug` and text for `/de/docs/<slug>`.
+
+Pages sort by number, then by file name; numbers need not be consecutive. To put a page into Guides, give it the
+number of a neighbour (`7.testing.md` sorts before `7.upgrading-to-v2.md`) and it joins that section. Do not use
+decimals: `7.5.testing.md` reads "testing" as a language code.
+
+The Markdown components work in every page: `::callout`, `::steps`, `::code-group`, `::tabs`, `::card` and more
+(see the [components](https://github.com/lupinum-dev/ginko/tree/main/packages/ginko-components)). The build checks
+every component and its props.
+
+A page with its own Vue code goes into `app/pages/` (for example `app/pages/playground.vue`); a page you define there
+wins over the layer's page at the same address.
+
+## Add or remove a language
+
+The languages are the `locales` list in `ginko.config.ts`; the first is the main language, whose addresses have no
+prefix.
+
+- **Remove one:** delete it from `locales`, then delete its files (`*.de.md`, `i18n/de.json`).
+  Or start fresh with `npm create ginko@latest my-docs -- --template docs --locales en`.
+- **Change the main language** (for example to German): put `'de'` first in `locales`, then rename every pair:
+  `x.de.md` becomes `x.md` (it keeps its German `slug`) and the old `x.md` becomes `x.en.md` with
+  `slug: <its old name>` (for example `slug: introduction`). A page with only an English file, such as
+  `7.upgrading-to-v2.md`, needs a German `x.md` first; then rename the English one to `x.en.md`. Each page now has new
+  addresses, so list the old ones under `redirectFrom` in the German file. A new site: `npm create ginko@latest
+  my-docs -- --template docs --locales de,en`.
+- **Add one** (for example French): add `'fr'` to `locales` (`pages.home` follows the list), add
+  `content/**/*.fr.md` translations (pages without one stay in English, see "A page without a translation") and
+  `i18n/fr.json` with the texts of `i18n/en.json` translated. The layer's own texts (search, navigation, "On this
+  page") exist in English and German; for another language, add them under `docs` in `i18n/fr.json` (the keys are in
+  the layer's `i18n/en.json`).
+
+## Remove a feature
+
+| Feature | Delete |
+|---|---|
+| Start page | `content/home*.md`, `home: homePages(…)` and `home: docsHome()` in `ginko.config.ts` with their imports; `/` then opens the first docs page |
+| Changelog | `content/changelog/`, `changelog: changelogCollection()` and `changelog: changelogPages(…)` in `ginko.config.ts` with their imports, the `$page.changelog` links in `content/docs/1.introduction*.md` and the changelog card in `content/home*.md` |
+| German | see "Add or remove a language" |
+| "Edit this page" | `docs.repository` in `app/app.config.ts` (keep the `repository` constant: the footer `source` link uses it) |
+| "Copy page" and its menu | set `markdownActions: { copy: false, openIn: [] }` in `app/app.config.ts` |
+| Share cards | `nuxt-og-image` and `@takumi-rs/core` in `nuxt.config.ts` and `package.json`; then `NUXT_APP_SECRET` is not needed |
+
+## Before you deploy
+
+- [ ] `NUXT_PUBLIC_SITE_URL` (or `url` in `ginko.config.ts`) is your real address.
+- [ ] `NUXT_APP_SECRET` is set where the site runs (not needed for a static build).
+- [ ] `docs.repository` and the footer links in `app/app.config.ts` point at your project, not at `example.com`.
+- [ ] The Orbit sample pages are replaced by your own, and `public/logo.svg`, `logo-dark.svg` and `favicon.svg` by
+  your logo.
+- [ ] `npm run build` passes: it stops on a broken link inside a page.
+
+## Move to the Studio
+
+Ginko Studio is Lupinum's hosted editor: people who do not use Git change pages and changelog entries in the
+browser, and see which translations are behind under **Inhalte > Übersetzungen**. It is open by invitation, and
+Lupinum moves your content with you and switches the bricks of `ginko.config.ts` from files to the Studio
+(`source: 'platform'` in `docsHome`, `docsCollection` and `changelogCollection`); the pages and their code stay the
+same. One thing does not move yet: the search box is built from files, so it finds no page that lives in the Studio.
+Until then, everything here works without it. Ask at [lupinum.com](https://lupinum.com).
+
+## Updating
+
+Move all Ginko packages to the same version in one step:
+
+```bash
+npm install @lupinum/ginko@latest @lupinum/ginko-content@latest @lupinum/ginko-i18n@latest @lupinum/ginko-docs@latest
+```
+
+The release notes list "Template files changed": compare those files with yours if you want the changes.
+
+## License
+
+Code: MIT (see `LICENSE`). Media: see `MEDIA.md`.

package/templates/docs/app/app.config.ts

@@ -0,0 +1,26 @@
+// The docs layer's options (README of @lupinum/ginko-docs, "Configure"). Texts are not set here: the link texts are
+// `docs.footer.<id>` in i18n/en.json and i18n/de.json, so each language has its own.
+// The Git host of your project: used for "Edit this page" and the footer link.
+const repository = 'https://git.example.com/orbit/sdk'
+
+export default defineAppConfig({
+  docs: {
+    // Next to the name in the header; `logo-dark.svg` in dark mode.
+    logo: { light: '/logo.svg', dark: '/logo-dark.svg' },
+    // "Edit this page" under every page opens its file on the Git host. Set your own repository.
+    repository: {
+      url: repository,
+      branch: 'main',
+      issueUrl: '{url}/issues/new?title={title}&body={page}',
+    },
+    footer: {
+      links: [
+        { id: 'source', href: repository },
+        { id: 'api', href: 'https://orbit.example.com' },
+        // Link the imprint and privacy page of your main site; most sites in the EU need both on every page.
+        { id: 'imprint', href: 'https://orbit.example.com/imprint' },
+        { id: 'privacy', href: 'https://orbit.example.com/privacy' },
+      ],
+    },
+  },
+})

package/templates/docs/app/assets/css/main.css

@@ -0,0 +1,14 @@
+/* The colours of this docs site. The layer @lupinum/ginko-docs reads shadcn-style tokens; every value set here wins
+   over its defaults. Each value is light-dark(light, dark) and follows the light/dark switch. The rules and the other
+   tokens are in DESIGN.md. Keep `seo.color` in ginko.config.ts equal to the light --primary (share cards). */
+:root {
+  /* The accent: links, the main button, the active page. #047857 on white 5.5:1; #34d399 on #09090b 10.3:1. */
+  --primary: light-dark(#047857, #34d399);
+  /* Text on the accent: white on #047857 5.5:1; #09090b on #34d399 10.3:1. */
+  --primary-foreground: light-dark(#ffffff, #09090b);
+  /* The focus ring, at least 3:1 against the page. */
+  --ring: light-dark(#047857, #34d399);
+  /* The tinted background of the active page in the navigation, and its text (7.3:1 / 9.7:1). */
+  --accent: light-dark(#ecfdf5, #052e22);
+  --accent-foreground: light-dark(#065f46, #6ee7b7);
+}

package/templates/docs/content/changelog/v1-6-0.de.md

@@ -0,0 +1,13 @@
+Die letzte Nebenversion von 1.x. Sie bekommt Sicherheitskorrekturen bis zum 28. Februar 2027.
+
+### Neu
+
+- `closeIncident(id, { note })` speichert eine Notiz zum behobenen Vorfall.
+
+### Behoben
+
+- Eine `503`-Antwort ohne `Retry-After`-Header wirft keinen `TypeError` mehr, sondern wie beschrieben einen `OrbitHttpError`.
+
+### Veraltet
+
+- `page` und `perPage` in Listenmethoden. 2.0 ersetzt sie durch Cursor.

package/templates/docs/content/changelog/v1-6-0.md

@@ -0,0 +1,18 @@
+---
+version: 1.6.0
+date: 2026-06-16
+---
+
+The last minor version of 1.x. It gets security fixes until 28 February 2027.
+
+### Added
+
+- `closeIncident(id, { note })` stores a note with the resolved incident.
+
+### Fixed
+
+- A `503` answer without a `Retry-After` header no longer throws a `TypeError`; it throws `OrbitHttpError` as documented.
+
+### Deprecated
+
+- `page` and `perPage` in list methods. 2.0 replaces them with cursors.

package/templates/docs/content/changelog/v2-0-0.de.md

@@ -0,0 +1,14 @@
+Eine neue Hauptversion mit Änderungen, die bestehenden Code brechen. Die Anleitung [Upgrading to 2.0]($docs.upgrading-to-v2) (auf Englisch) zeigt jede Änderung mit dem Code vorher und nachher.
+
+### Geändert
+
+- Das Paket heißt jetzt `@orbit-example/sdk` (vorher `orbit-sdk`).
+- Ein Client-Objekt: `new Orbit({ apiKey })` mit `orbit.monitors`, `orbit.incidents`, `orbit.checks` und `orbit.webhooks`.
+- Listen nutzen Cursor (`limit`, `cursor`) statt Seitennummern, und `for await` liest alle Seiten. Siehe [Paginierung]($docs.pagination).
+- Jeder Fehler ist ein `OrbitError` mit einem `code`. Siehe [Fehlercodes]($docs.error-codes).
+- Nur noch Node.js 22 oder neuer und ES-Module.
+
+### Neu
+
+- Wiederholungen bei vorübergehenden Fehlern, standardmäßig zwei (`maxRetries`). Siehe [Fehler und Wiederholungen]($docs.errors-and-retries).
+- Ein `Idempotency-Key` bei jedem `create()`, damit eine Wiederholung nie einen zweiten Monitor anlegt.

package/templates/docs/content/changelog/v2-0-0.md

@@ -0,0 +1,19 @@
+---
+version: 2.0.0
+date: 2026-08-25
+---
+
+A new major version with breaking changes. [Upgrading to 2.0]($docs.upgrading-to-v2) shows each change with the code before and after.
+
+### Changed
+
+- The package is now `@orbit-example/sdk` (was `orbit-sdk`).
+- One client object: `new Orbit({ apiKey })` with `orbit.monitors`, `orbit.incidents`, `orbit.checks` and `orbit.webhooks`.
+- Lists use cursors (`limit`, `cursor`) instead of page numbers, and `for await` reads every page. See [Pagination]($docs.pagination).
+- Every error is an `OrbitError` with a `code`. See [Error codes]($docs.error-codes).
+- Node.js 22 or newer and ES modules only.
+
+### Added
+
+- Retries for temporary errors, two by default (`maxRetries`). See [Errors and retries]($docs.errors-and-retries).
+- An `Idempotency-Key` on every `create()`, so a retry never creates a second monitor.

package/templates/docs/content/changelog/v2-1-0.de.md

@@ -0,0 +1,9 @@
+### Neu
+
+- `monitors.pause()` und `monitors.resume()` halten die Prüfungen eines Monitors an und starten sie wieder, zum Beispiel während einer Wartung. Siehe [Monitore]($docs.monitors).
+- `checks.list()` nimmt `ok: false` und liefert dann nur fehlgeschlagene Prüfungen.
+
+### Behoben
+
+- `checks.list()` las ein `Date` in `since` auf Servern außerhalb von UTC als Ortszeit. Jetzt gilt UTC, wie beschrieben.
+- `webhooks.verify()` nimmt den Body auch als `Buffer`, nicht nur als String.

package/templates/docs/content/changelog/v2-1-0.md

@@ -0,0 +1,14 @@
+---
+version: 2.1.0
+date: 2026-10-06
+---
+
+### Added
+
+- `monitors.pause()` and `monitors.resume()` stop and restart the checks of a monitor, for example during maintenance. See [Monitors]($docs.monitors).
+- `checks.list()` takes `ok: false` to return failed checks only.
+
+### Fixed
+
+- `checks.list()` read a `Date` in `since` as local time on servers outside UTC. It is now read as UTC, as documented.
+- `webhooks.verify()` accepts a `Buffer` body as well as a string.

package/templates/docs/content/docs/1.introduction.de.md

@@ -0,0 +1,32 @@
+---
+title: Einführung
+slug: einfuehrung
+description: Was Orbit SDK macht, was du brauchst und wo du was findest.
+section: Erste Schritte
+---
+
+Orbit SDK ist der offizielle TypeScript-Client für die [Orbit API](https://orbit.example.com). Orbit prüft deine Websites und APIs aus mehreren Regionen, alle 30 Sekunden bis 15 Minuten, und eröffnet einen Vorfall, wenn eine nicht mehr antwortet. Mit dem SDK erledigt dein eigener Code, was sonst das Orbit-Dashboard tut: Monitore anlegen und pausieren, Vorfälle und Prüfergebnisse lesen und Webhooks empfangen.
+
+## Was der Client für dich erledigt
+
+- **Typen für jede Anfrage und Antwort.** Dein Editor weiß, dass `monitor.status` `'up'`, `'down'`, `'paused'` oder `'pending'` ist.
+- **Wiederholungen.** Eine Anfrage, die am Netz, an einer Zeitüberschreitung, am Ratenlimit oder an einem Serverfehler scheitert, sendet der Client bis zu zweimal erneut. Siehe [Fehler und Wiederholungen]($docs.errors-and-retries).
+- **Paginierung.** Listen kommen in Seiten mit bis zu 100 Einträgen; `for await` liest alle. Siehe [Paginierung]($docs.pagination).
+- **Webhook-Prüfung.** `orbit.webhooks.verify()` belegt, dass ein Webhook von Orbit kommt. Siehe [Webhooks]($docs.webhooks).
+
+## Was du brauchst
+
+- Node.js 22 oder neuer, oder eine andere Laufzeit mit `fetch` (Deno, Bun, Cloudflare Workers).
+- Ein Orbit-Konto und einen API-Schlüssel. Siehe [Authentifizierung]($docs.authentication).
+- ES-Module. Das Paket hat keinen CommonJS-Build.
+
+::callout{type="warning" title="Der Schlüssel bleibt auf dem Server"}
+Mit einem API-Schlüssel lässt sich jeder Monitor deines Kontos löschen. Nutze das SDK nur in Servercode, nie in Code, der im Browser läuft.
+::
+
+## Wo du was findest
+
+- Neu bei Orbit SDK: Der [Schnellstart]($docs.getting-started) installiert es und sendet eine erste Anfrage.
+- Eine Aufgabe, etwa alle Vorfälle lesen oder Webhooks verarbeiten: die Anleitungen.
+- Der genaue Name einer Option oder Methode: die Referenz, beginnend bei den [Client-Optionen]($docs.client).
+- Was sich in einer Version geändert hat: die [Änderungen]($page.changelog).

package/templates/docs/content/docs/1.introduction.md

@@ -0,0 +1,31 @@
+---
+title: Introduction
+description: What Orbit SDK does, what you need, and where to find what.
+section: Get started
+---
+
+Orbit SDK is the official TypeScript client for the [Orbit API](https://orbit.example.com). Orbit checks your websites and APIs from several regions, every 30 seconds to 15 minutes, and opens an incident when one stops answering. The SDK lets your own code do what the Orbit dashboard does: create and pause monitors, read incidents and check results, and receive webhooks.
+
+## What the client does for you
+
+- **Types for every request and answer.** Your editor knows that `monitor.status` is `'up'`, `'down'`, `'paused'` or `'pending'`.
+- **Retries.** A request that fails because of the network, a timeout, rate limiting or a server error is sent again, up to two more times. See [Errors and retries]($docs.errors-and-retries).
+- **Pagination.** Lists come in pages of up to 100 entries; `for await` reads all of them. See [Pagination]($docs.pagination).
+- **Webhook checks.** `orbit.webhooks.verify()` proves that a webhook came from Orbit. See [Webhooks]($docs.webhooks).
+
+## What you need
+
+- Node.js 22 or newer, or another runtime with `fetch` (Deno, Bun, Cloudflare Workers).
+- An Orbit account and an API key. See [Authentication]($docs.authentication).
+- ES modules. The package has no CommonJS build.
+
+::callout{type="warning" title="Keep the key on the server"}
+An API key can delete every monitor of your account. Use the SDK in server code only, never in code that runs in the browser.
+::
+
+## Where to find what
+
+- New to Orbit SDK: [Getting started]($docs.getting-started) installs it and sends a first request.
+- A task such as reading every incident or handling webhooks: the guides.
+- The exact name of an option or a method: the reference, starting at [Client options]($docs.client).
+- What changed in a version: the [changelog]($page.changelog).

package/templates/docs/content/docs/10.incidents-and-checks.de.md

@@ -0,0 +1,82 @@
+---
+title: Vorfälle und Prüfungen
+slug: vorfaelle-und-pruefungen
+description: Die Methoden von orbit.incidents und orbit.checks mit ihren Parametern, und die Typen Incident und Check.
+---
+
+Eine **Prüfung** (check) ist eine Anfrage, die Orbit an eine überwachte Adresse sendet. Ein **Vorfall** (incident) beginnt, wenn ein Monitor zwei Prüfungen hintereinander nicht besteht, und endet, wenn er wieder antwortet.
+
+## Der Typ Incident
+
+```ts
+interface Incident {
+  id: string                 // 'inc_3hq9we'
+  monitorId: string
+  status: 'open' | 'resolved'
+  cause: string              // 'HTTP 503' oder 'Timeout after 30 s'
+  openedAt: string           // ISO 8601, UTC
+  resolvedAt: string | null
+  note: string | null        // gesetzt von incidents.resolve()
+}
+```
+
+## incidents.list()
+
+```ts
+list(params?: ListIncidents, options?: RequestOptions): PageRequest<Incident>
+```
+
+Gibt Vorfälle zurück, die neuesten zuerst.
+
+| Parameter | Typ | Standard | |
+|---|---|---|---|
+| `monitorId` | `string` | alle Monitore | Nur Vorfälle dieses Monitors. |
+| `status` | `'open' \| 'resolved'` | beide | Nur offene oder nur behobene Vorfälle. |
+| `limit` | `number` | `20` | Einträge pro Seite, 1 bis 100. |
+| `cursor` | `string` | – | `nextCursor` der vorigen Seite. |
+
+## incidents.get()
+
+```ts
+get(id: string, options?: RequestOptions): Promise<Incident>
+```
+
+Gibt einen Vorfall zurück. Wirft `not_found`, wenn es keinen mit dieser id gibt.
+
+## incidents.resolve()
+
+```ts
+resolve(id: string, params?: { note?: string }, options?: RequestOptions): Promise<Incident>
+```
+
+Markiert einen offenen Vorfall als behoben, etwa wenn du die Ursache kennst und die nächste Prüfung noch Minuten entfernt ist. `note` (höchstens 500 Zeichen) erscheint im Dashboard und im Webhook `incident.resolved`. Einen behobenen Vorfall erneut zu beheben wirft `conflict`.
+
+## Der Typ Check
+
+```ts
+interface Check {
+  id: string                 // 'chk_91mdzr'
+  monitorId: string
+  region: Region
+  ok: boolean
+  statusCode: number | null  // null, wenn keine Antwort kam
+  durationMs: number
+  checkedAt: string          // ISO 8601, UTC
+}
+```
+
+## checks.list()
+
+```ts
+list(params: ListChecks, options?: RequestOptions): PageRequest<Check>
+```
+
+Gibt die Prüfungen eines Monitors zurück, die neuesten zuerst. Orbit bewahrt Prüfungen 30 Tage auf.
+
+| Parameter | Typ | Standard | |
+|---|---|---|---|
+| `monitorId` | `string` | Pflicht | Der Monitor. |
+| `since` | `Date \| string` | vor 24 Stunden | Nur Prüfungen ab diesem Zeitpunkt. Ein String ist eine Zeit nach ISO 8601; ein `Date` gilt als UTC. |
+| `ok` | `boolean` | beide | `false` für nur fehlgeschlagene Prüfungen. |
+| `limit` | `number` | `20` | Einträge pro Seite, 1 bis 100. |
+| `cursor` | `string` | – | `nextCursor` der vorigen Seite. |

package/templates/docs/content/docs/10.incidents-and-checks.md

@@ -0,0 +1,81 @@
+---
+title: Incidents and checks
+description: The methods of orbit.incidents and orbit.checks with their parameters, and the Incident and Check types.
+---
+
+A **check** is one request Orbit sends to a monitored address. An **incident** starts when a monitor fails two checks in a row and ends when it answers again.
+
+## The Incident type
+
+```ts
+interface Incident {
+  id: string                 // 'inc_3hq9we'
+  monitorId: string
+  status: 'open' | 'resolved'
+  cause: string              // 'HTTP 503' or 'Timeout after 30 s'
+  openedAt: string           // ISO 8601, UTC
+  resolvedAt: string | null
+  note: string | null        // set by incidents.resolve()
+}
+```
+
+## incidents.list()
+
+```ts
+list(params?: ListIncidents, options?: RequestOptions): PageRequest<Incident>
+```
+
+Returns incidents, newest first.
+
+| Parameter | Type | Default | |
+|---|---|---|---|
+| `monitorId` | `string` | all monitors | Only incidents of this monitor. |
+| `status` | `'open' \| 'resolved'` | both | Only open or only resolved incidents. |
+| `limit` | `number` | `20` | Entries per page, 1 to 100. |
+| `cursor` | `string` | – | `nextCursor` of the page before. |
+
+## incidents.get()
+
+```ts
+get(id: string, options?: RequestOptions): Promise<Incident>
+```
+
+Returns one incident. Throws `not_found` when there is none with this id.
+
+## incidents.resolve()
+
+```ts
+resolve(id: string, params?: { note?: string }, options?: RequestOptions): Promise<Incident>
+```
+
+Marks an open incident as resolved, for example when you know the cause and the next check is minutes away. `note` (at most 500 characters) is shown in the dashboard and sent with the `incident.resolved` webhook. Resolving a resolved incident throws `conflict`.
+
+## The Check type
+
+```ts
+interface Check {
+  id: string                 // 'chk_91mdzr'
+  monitorId: string
+  region: Region
+  ok: boolean
+  statusCode: number | null  // null when there was no answer
+  durationMs: number
+  checkedAt: string          // ISO 8601, UTC
+}
+```
+
+## checks.list()
+
+```ts
+list(params: ListChecks, options?: RequestOptions): PageRequest<Check>
+```
+
+Returns the checks of one monitor, newest first. Orbit keeps checks for 30 days.
+
+| Parameter | Type | Default | |
+|---|---|---|---|
+| `monitorId` | `string` | required | The monitor. |
+| `since` | `Date \| string` | 24 hours ago | Only checks from this time on. A string is an ISO 8601 time; a `Date` is read as UTC. |
+| `ok` | `boolean` | both | `false` for failed checks only. |
+| `limit` | `number` | `20` | Entries per page, 1 to 100. |
+| `cursor` | `string` | – | `nextCursor` of the page before. |

package/templates/docs/content/docs/11.error-codes.de.md

@@ -0,0 +1,36 @@
+---
+title: Fehlercodes
+slug: fehlercodes
+description: Jeder Code von OrbitError, sein HTTP-Status, ob der Client ihn wiederholt und was zu tun ist.
+---
+
+Jeder Fehler, den der Client wirft, ist ein `OrbitError` mit diesen Eigenschaften:
+
+| Eigenschaft | Typ | Was sie ist |
+|---|---|---|
+| `code` | `string` | Einer der Codes unten. |
+| `status` | `number \| null` | Der HTTP-Status, oder `null`, wenn keine Antwort kam. |
+| `message` | `string` | Ein Satz auf Englisch, der sagt, was schiefging. |
+| `requestId` | `string \| null` | Die id der Anfrage in den Protokollen von Orbit, für den Support. |
+| `details` | `{ field: string; message: string }[]` | Die ungültigen Felder, nur bei `validation_failed`; sonst leer. |
+| `retryAfter` | `number \| null` | Sekunden bis zum nächsten Versuch, nur bei `rate_limited`. |
+
+## Codes
+
+| Code | HTTP | Wiederholt | Bedeutung und was zu tun ist |
+|---|---|---|---|
+| `missing_api_key` | – | nein | Kein Schlüssel übergeben und `ORBIT_API_KEY` nicht gesetzt. Setze ihn. |
+| `invalid_request` | 400 | nein | Die Anfrage ist fehlerhaft. Prüfe die Parameter der Methode. |
+| `invalid_cursor` | 400 | nein | Der Cursor ist älter als 24 Stunden oder gehört zu anderen Filtern. Beginne die Liste neu. |
+| `unauthorized` | 401 | nein | Der Schlüssel ist falsch oder wurde gelöscht. |
+| `forbidden` | 403 | nein | Der Schlüssel darf das nicht, zum Beispiel ein Testschlüssel auf echten Daten. |
+| `not_found` | 404 | nein | Kein Monitor, Vorfall oder keine Prüfung mit dieser id. |
+| `conflict` | 409 | nein | Die Anfrage passt nicht zum aktuellen Stand, zum Beispiel ein zweiter Monitor für dieselbe Adresse. |
+| `validation_failed` | 422 | nein | Ein Wert ist nicht erlaubt. `details` nennt jedes Feld. |
+| `rate_limited` | 429 | ja | Mehr als 600 Anfragen in einer Minute. Der Client wartet `retryAfter` Sekunden. |
+| `server_error` | 500–504 | ja | Ein Problem bei Orbit. Hält es an, sieh auf der Statusseite nach. |
+| `timeout` | – | ja | Keine Antwort innerhalb von `timeout`. |
+| `connection_failed` | – | ja | Keine Verbindung zur API, zum Beispiel ein DNS- oder Netzwerkfehler. |
+| `invalid_signature` | – | nein | `webhooks.verify()`: Die Signatur passt nicht, oder der Webhook ist älter als fünf Minuten. |
+
+„Wiederholt“ heißt: Der Client sendet die Anfrage selbst erneut, bis zu `maxRetries`-mal, bevor er wirft. Siehe [Fehler und Wiederholungen]($docs.errors-and-retries).