Skip to content

Open-source status page, incident response and uptime monitoring

chore: improve repo agent experience (#2569)

Maximilian Kaske274784cb0ee7
diff --git a/.github/workflows/buf-push.yml b/.github/workflows/buf-push.yml
index 12ff5ab5f..33e039593 100644
--- a/.github/workflows/buf-push.yml
+++ b/.github/workflows/buf-push.yml
@@ -32,7 +32,7 @@ jobs:
- name: βŽ” Setup node
uses: actions/setup-node@v6
with:
- node-version: 24
+ node-version: 24.12.0
cache: "pnpm"
- name: πŸ“₯ Download deps
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 19510a393..a19ed3e0d 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -24,16 +24,23 @@ jobs:
- name: βŽ” Setup node
uses: actions/setup-node@v6
with:
- node-version: 24
+ node-version: 24.12.0
cache: "pnpm"
- name: πŸ¦• Setup Deno
uses: denoland/setup-deno@v2
with:
- deno-version: v2.x
+ deno-version: 2.9.4
- name: πŸ“₯ Download deps
run: pnpm install
+ # Blocking, unlike autofix.ci, which only commits formatting back.
+ - name: πŸ”¬ Lint
+ run: pnpm lint
+
+ - name: πŸ”— Doc references
+ run: pnpm check:docs
+
- name: πŸ” Check
run: pnpm check
diff --git a/.github/workflows/dx.yml b/.github/workflows/dx.yml
index 766bae466..6ddfb91d3 100644
--- a/.github/workflows/dx.yml
+++ b/.github/workflows/dx.yml
@@ -35,7 +35,7 @@ jobs:
- name: βŽ” Setup node
uses: actions/setup-node@v6
with:
- node-version: 24
+ node-version: 24.12.0
cache: "pnpm"
- name: πŸ“₯ Download deps
@@ -44,7 +44,7 @@ jobs:
- name: πŸ¦• Setup Deno
uses: denoland/setup-deno@v2
with:
- deno-version: v2.x
+ deno-version: 2.9.4
- name: πŸ”₯ DX task
run: pnpm dx
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 7169323ca..32aec6e4a 100644
--- a/.github/workflows/lint.yml
+++ b/.github/workflows/lint.yml
@@ -25,7 +25,7 @@ jobs:
- name: βŽ” Setup node
uses: actions/setup-node@v6
with:
- node-version: 24
+ node-version: 24.12.0
cache: "pnpm"
- name: πŸ“₯ Download deps
diff --git a/.github/workflows/migrate.yml b/.github/workflows/migrate.yml
index 1770625c2..5d80891bd 100644
--- a/.github/workflows/migrate.yml
+++ b/.github/workflows/migrate.yml
@@ -23,13 +23,13 @@ jobs:
- name: βŽ” Setup node
uses: actions/setup-node@v6
with:
- node-version: 24
+ node-version: 24.12.0
cache: "pnpm"
- name: πŸ¦• Install deno
uses: denoland/setup-deno@v2
with:
- deno-version: v2.x
+ deno-version: 2.9.4
- name: πŸ“₯ Download deps
run: pnpm install
diff --git a/.github/workflows/proto-check.yml b/.github/workflows/proto-check.yml
index 3568dcab6..2ee4684a8 100644
--- a/.github/workflows/proto-check.yml
+++ b/.github/workflows/proto-check.yml
@@ -32,7 +32,7 @@ jobs:
- name: βŽ” Setup node
uses: actions/setup-node@v6
with:
- node-version: 24
+ node-version: 24.12.0
cache: "pnpm"
- name: πŸ”₯ Install bun
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 9e5c5fac7..b46e29eb1 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -66,13 +66,13 @@ jobs:
- name: βŽ” Setup node
uses: actions/setup-node@v6
with:
- node-version: 24
+ node-version: 24.12.0
cache: "pnpm"
- name: πŸ¦• Setup Deno
uses: denoland/setup-deno@v2
with:
- deno-version: v2.x
+ deno-version: 2.9.4
- name: πŸ“₯ Download deps
run: pnpm install
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..da50576aa
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,91 @@
+# AGENTS.md
+
+Cross-cutting truth for openstatus. Package-scoped rules live in the nested
+`AGENTS.md` files listed at the bottom. Setup and how-to-run belong in READMEs β€”
+this file never restates them.
+
+## Verify your change
+
+```sh
+pnpm verify # oxfmt + oxlint + doc refs + deno check. No database, seconds.
+pnpm verify:test # tests for packages affected by your diff. Needs a database.
+```
+
+`pnpm verify` must be green before you hand work back β€” it is what CI's `Check`
+job runs. For `verify:test`, start the local libSQL and seed it first; the steps
+are in `apps/dashboard/README.md`.
+
+## Toolchain
+
+`devbox.json` pins exact node, deno, bun, turso-cli and sqld versions; the CI
+workflows pin the same node and deno. Never float one back to `@latest` or
+`v2.x` β€” `deno check` results differ by deno version, so a drifting pin makes
+`pnpm verify` disagree with CI for reasons unrelated to your change.
+
+## Architecture
+
+- **`packages/services`** owns every workspace-scoped mutation. tRPC routers,
+ Hono routes, MCP tools and jobs are thin adapters over it. Inline DB access in
+ a router is a defect β€” see `packages/services/AGENTS.md`.
+- **Turso (libSQL) holds application data**, through Drizzle in `packages/db`.
+ **Tinybird holds monitoring time-series**, through `packages/tinybird`. The two
+ are linked by id only: no cross-store transaction, no join across the boundary,
+ no referential integrity.
+- **Go is confined to the probing tier** (`apps/checker`, `apps/private-location`).
+ Product logic stays in TypeScript. Anything duplicated across that boundary β€”
+ assertion evaluation, region codes β€” must be changed on both sides in one PR.
+- **Shared UI comes from `@openstatus/ui`.** Do not fork a primitive into an app.
+
+## Tests
+
+- CI gives every DB-touching package its own database (the matrix in
+ `.github/workflows/test.yml`). Locally there is one shared libSQL, which is
+ why `verify:test` runs the affected packages one at a time. Cross-package
+ failures that vanish on a re-run of the single package are that sharing, not
+ your change β€” confirm with `turbo run test --filter=@openstatus/services`.
+- Suites mint their own workspace via `createTestWorkspace`
+ (`packages/db/src/test/factories.ts`). Never load a shared seeded workspace,
+ and never wipe a table globally β€” scope every cleanup to your own workspace id.
+- The `external_service` suites are not workspace-scoped; an aborted run leaves
+ rows that fail the *next* local run on a foreign key. Reseed to recover.
+- The `test` turbo task is deliberately uncached β€” results depend on database
+ state that is not in the input hash. Do not "fix" it.
+
+## Comment discipline
+
+Default to no comments. Code and identifiers already say *what*. Write a comment
+only when the *why* is not visible: a non-obvious invariant, a workaround for a
+specific bug, a constraint imposed from outside the file, a `// safe because …`
+above an unavoidable cast.
+
+- 1 short line where possible, 3 lines max. Never multi-paragraph JSDoc.
+- Strip: restatements of the code, the name of the caller, history ("added for
+ X"), PR or task context. That belongs in the commit message.
+- JSDoc on an exported symbol is fine when the signature alone is ambiguous β€”
+ one sentence, not a tutorial.
+
+## Type cast discipline
+
+`as unknown as X`, `as never` and `as any` are sometimes unavoidable at
+boundaries with external SDKs or at registry-style dispatch. When you need one:
+
+- **Centralize it in a named helper** whose name states the intent
+ (`asUIMessages`, `renderToolDraft`). Do not scatter the same cast.
+- **Comment the runtime guarantee** above the helper, so a future reader can
+ check whether it still holds.
+- A scattered `as never` is usually a missing helper.
+
+## Package context
+
+- `packages/services/AGENTS.md` β€” service verbs, audit log, scope enforcement
+- `packages/ui/AGENTS.md` β€” stock shadcn vs. the published blocks registry
+- `apps/dashboard/AGENTS.md` β€” Next.js runtimes, client boundary, UI verification
+- `apps/server/AGENTS.md` β€” Hono API, API-key scopes
+- `apps/status-page/AGENTS.md` β€” public surfaces and gated content
+- `apps/workflows/AGENTS.md` β€” Deno runtime constraints
+- `apps/checker/AGENTS.md` β€” Go probing tier
+- `apps/web/AGENTS.md` β€” marketing site, `.well-known`, search, content pages
+
+`docs/adr/` is frozen background on *why* some of these decisions were made. It
+is history, not current state; this file and its nested siblings are current
+state. Do not add new ADRs.
diff --git a/CLAUDE.md b/CLAUDE.md
index a621d75cf..af50da6d0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,161 +1,4 @@
-# Agent.md
+# CLAUDE.md
-This file provides a comprehensive overview of the OpenStatus project, its architecture, and development conventions to be used as instructional context for future interactions.
-
-## Project Overview
-
-OpenStatus is an open-source synthetic monitoring platform. It allows users to monitor their websites and APIs from multiple locations and receive notifications when they are down or slow.
-
-The project is a monorepo managed with pnpm workspaces and Turborepo. It consists of several applications and packages that work together to provide a complete monitoring solution.
-
-### Core Technologies
-
-- **Frontend:**
- - Next.js (with Turbopack)
- - React
- - Tailwind CSS
- - shadcn/ui
- - tRPC
-- **Backend:**
- - Hono (Node.js framework)
- - Go
-- **Database:**
- - Turso (libSQL)
- - Drizzle ORM
-- **Data Analytics:**
- - Tinybird
-- **Authentication:**
- - NextAuth.js
-- **Build System:**
- - Turborepo
-
-### Architecture
-
-The OpenStatus platform is composed of three main applications:
-
-- **`apps/dashboard`**: A Next.js application that provides the main user interface for managing monitors, viewing status pages, and configuring notifications.
-- **`apps/server`**: A Hono-based backend server that provides the API for the dashboard application.
-- **`apps/checker`**: A Go application responsible for performing the actual monitoring checks from different locations.
-
-These applications are supported by a collection of shared packages in the `packages/` directory, which provide common functionality such as database access, UI components, and utility functions.
-
-## Building and Running
-
-The project can be run using Docker (recommended) or a manual setup.
-
-### With Docker
-
-1. Copy the example environment file:
- ```sh
- cp .env.docker.example .env.docker
- ```
-2. Start all services:
- ```sh
- docker compose up -d
- ```
-3. Access the applications:
- - Dashboard: `http://localhost:3002`
- - Status Pages: `http://localhost:3003`
-
-### Manual Setup
-
-1. Install dependencies:
- ```sh
- pnpm install
- ```
-2. Initialize the development environment:
- ```sh
- pnpm dx
- ```
-3. Run a specific application:
- ```sh
- pnpm dev:dashboard
- pnpm dev:status-page
- pnpm dev:web
- ```
-
-### Running Tests
-
-To run the test suite, use the following command:
-
-Before running the test you should launch turso dev in a separate terminal:
-```sh
-turso dev
-```
-
-Then, seed the database with test data:
-
-```sh
-cd packages/db
-pnpm migrate
-pnpm seed
-```
-
-Then run the tests with:
-
-```sh
-pnpm test
-```
-
-## Development Conventions
-
-- **Monorepo:** The project is organized as a monorepo using pnpm workspaces. All applications and packages are located in the `apps/` and `packages/` directories, respectively.
-- **Build System:** Turborepo is used to manage the build process. The `turbo.json` file defines the build pipeline and dependencies between tasks.
-- **Linting and Formatting:** The project uses oxlint for linting and oxfmt for formatting. The configuration can be found in `oxlint.config.ts` and `oxfmt.config.ts`.
-- **Code Generation:** The project uses `drizzle-kit` for database schema migrations.
-- **API:** The backend API is built using Hono and tRPC. The API is documented using OpenAPI.
-
-## Comment Discipline
-
-Default to writing no comments. The code and identifiers should explain *what* β€” the reader can see that. Only write a comment when the *why* would not be obvious from reading the code: a non-obvious invariant, a workaround for a specific bug, a runtime guarantee that justifies a cast, a constraint imposed from outside this file.
-
-- **Keep them to 1 short line where possible**, 3 lines max. Never write multi-paragraph JSDoc blocks.
-- **Strip these every time:** restating what the code does, naming the caller / surface that uses the helper, history ("added for X", "used by the Y flow"), and PR/task context. That belongs in commit messages, not source.
-- **Keep these:** the WHY behind a non-obvious choice, an invariant that callers must uphold, a `// safe because …` line above an unavoidable cast, a `// workaround: <bug>` for a known issue.
-- **JSDoc:** allowed on exported symbols when the type signature alone is ambiguous β€” but one sentence, not a tutorial. Don't enumerate every branch of a function in prose.
-
-If you find yourself writing a comment that explains *what just changed* or *what you did*, delete it.
-
-## Type Cast Discipline
-
-`as unknown as X`, `as never`, and `as any` are sometimes unavoidable β€” usually at boundaries with external SDKs (AI SDK, third-party libs) or at registry-style dispatch where TypeScript can't link a runtime string to a literal-keyed map. When you need one:
-
-- **Centralize the cast in a named helper.** Don't scatter the same cast across call sites. Wrap it in a small function whose name describes the intent (`asUIMessages`, `findRenderer`, `renderToolDraft`).
-- **Comment the runtime guarantee.** Above the helper, write one or two lines explaining *why the cast is safe at runtime* (e.g. "the persisted shape is validated on write by `storedMessageSchema`, so reads return SDK-conforming rows"). Future readers can verify the invariant or notice when it breaks.
-- **Examples:** `apps/dashboard/src/components/chat/use-chat-session.ts` (`asUIMessages`); `apps/dashboard/src/components/chat/tool-renderers/index.tsx` (`renderToolDraft` / `renderToolResult` / `summarizeToolOutput`). Both eliminate scattered casts in the consuming components.
-
-A scattered `as never` is usually a missing helper.
-
-## Services & Audit Log Pattern
-
-All workspace-scoped business logic lives in `packages/services` β€” **not** in tRPC routers. Routers stay thin: validate input, call a service verb, map errors. This keeps logic reusable across tRPC, Hono, and background jobs.
-
-Note on runtimes: the dashboard's tRPC handler runs on the **Node.js** runtime (see the comment in `apps/dashboard/src/app/api/trpc/lambda/[trpc]/route.ts` β€” several routers pull Node-only deps), and no Edge route imports `@openstatus/services`. Node-only dependencies in services are therefore acceptable. What *is* enforced: `apps/workflows` runs on Deno and imports services, so `pnpm check` (`deno check --sloppy-imports`) must pass in both packages.
-
-Conventions for any new mutation:
-
-- **One file per verb** under `packages/services/src/<entity>/` (e.g. `create.ts`, `update.ts`, `remove.ts`), re-exported from the entity's `index.ts`. Routers import from `@openstatus/services/<entity>`.
-- **Standard signature:** `async function verbEntity(args: { ctx: ServiceContext; input: VerbInput }): Promise<...>`. `ctx` carries `workspace`, `actor`, and an optional `db`/transaction. Parse input with the schema at the top of the function.
-- **Wrap mutations in `withTransaction(ctx, async (tx) => { ... })`** β€” it reuses an outer tx if present, otherwise opens one. Always pass `tx` (not `defaultDb`) to writes inside the block.
-- **Workspace scoping is mandatory.** Every read/write filters by `ctx.workspace.id`. Use the `getXInWorkspace` helpers in `internal.ts` for fetch-or-throw.
-- **Throw `ServiceError` subclasses** (`NotFoundError`, `ForbiddenError`, etc. from `./errors`). Routers convert them via `toTRPCError`.
-- **Emit an audit row for every mutation** via `emitAudit(tx, ctx, entry)` inside the same transaction. Fail-closed: a failed audit insert rolls back the mutation. See `packages/services/src/audit/emit.ts`.
- - For updates, pass both `before` (pre-mutation snapshot) and `after` (post-`.returning()` row). `changed_fields` is auto-diffed; no-op updates are skipped.
- - For creates/deletes, pass only `after` or only `before`.
- - **Strip secrets** from snapshots before emitting (e.g. `credential`, bot tokens, raw API keys) β€” see `integration/remove.ts` for the pattern.
- - Action names follow `{entity}.{verb}` (`monitor.update`, `integration.delete`). Add new variants to the discriminated union in `@openstatus/db/src/schema/audit_logs/validation.ts`.
-- **Tests live in `packages/services/src/<entity>/__tests__/`** and use `expectAuditRow({ workspaceId, action, entityId, ... })` from `packages/services/test/helpers.ts` to assert the audit side-effect. Each suite scopes to its own workspace and clears `audit_log` between cases.
-
-When adding a router endpoint, the default answer is "write the service verb first, then call it from the router." Inline DB access in routers is a smell β€” it bypasses the audit log.
-
-## Scope Enforcement (API key RBAC)
-
-API keys carry **scopes** (`'read'` / `'write'`) that gate write access. See `packages/services/src/auth/`.
-
-- **Call `requireScope(ctx, "write")` as the first line** of every write verb β€” before `Input.parse(...)` and `withTransaction`. Import from `../auth`.
-- **"Write"** = any DB mutation **or** side-effecting external call (probes, webhooks, notifications). Everything else is read.
-- No-op for `user` / `system` / `slack` / `webhook` / `subscriber` actors; active for `apiKey` and `mcp`. Throws `ForbiddenError` on denial.
-- **Tests:** every entity's `__tests__/` includes a `'rejects read-only actor'` case via `makeApiKeyCtx(workspace, { keyId: "k", userId: 1, scopes: ["read"] })`. `requireScope` fires before DB lookup, so fake ids work for delete/update verbs.
-- **MCP tools** declare `scope: 'read' | 'write'` and register via `registerScopedTool` β€” read-only keys never see write tools.
-
-Treat a missing `requireScope` the same as a missing `emitAudit` β€” mandatory for every mutation.
+Read `AGENTS.md` in this directory β€” it holds the conventions for this repo, and
+the nested `AGENTS.md` files it links carry the package-specific ones.
diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.md
similarity index 83%
rename from CONTRIBUTING.MD
rename to CONTRIBUTING.md
index 1f0b9e606..0625cf948 100644
--- a/CONTRIBUTING.MD
+++ b/CONTRIBUTING.md
@@ -29,10 +29,13 @@ To contribute code changes, follow these steps:
1. Fork the repository and create a new branch for your changes.
2. Ensure that your code follows the project's coding conventions and style guide.
-3. Make commits with clear and descriptive messages. Each commit should have a single logical purpose.
-4. Push your branch to your forked repository.
-5. Open a pull request (PR) from your branch to the original repository's `main` branch.
-6. Provide a detailed description of your changes in the PR, including any related issues or feature requests.
+3. Run `pnpm verify` β€” formatting, lint, doc references and type checks. It needs
+ no database and takes seconds. `pnpm verify:test` runs the tests for the
+ packages your diff touches; those do need a local libSQL server.
+4. Make commits with clear and descriptive messages. Each commit should have a single logical purpose.
+5. Push your branch to your forked repository.
+6. Open a pull request (PR) from your branch to the original repository's `main` branch.
+7. Provide a detailed description of your changes in the PR, including any related issues or feature requests.
A project maintainer will review your PR, provide feedback if necessary, and merge it once it meets the project's standards.
diff --git a/apps/checker/AGENTS.md b/apps/checker/AGENTS.md
new file mode 100644
index 000000000..97a797cee
--- /dev/null
+++ b/apps/checker/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md β€” apps/checker
+
+Go 1.25, the only non-TypeScript tier in the repo along with
+`apps/private-location`. It probes customer endpoints from ~35 fly.io regions on
+512 MB VMs and writes results straight to Tinybird.
+
+Constraints:
+
+- **Keep Go scoped to probing.** Product and workspace logic belongs in
+ `packages/services`. The two sides talk through data contracts only β€” Tinybird
+ rows and protobuf (`packages/proto`) β€” never shared in-process code.
+- **Assertion evaluation exists twice**: `apps/checker/pkg/assertions` (Go) and
+ `packages/assertions` (TypeScript). So do region codes. Changing one without
+ the other silently diverges what the probe checks from what the dashboard
+ shows β€” move both in the same PR and say so in the description.
+- `pnpm verify` does not cover this app. Run `go test ./...` from
+ `apps/checker`; CI runs it in `.github/workflows/go-tests.yml`.
+- Per-phase timings (DNS, connect, TLS, TTFB, transfer) come from `httptrace`.
+ They are a product surface, not diagnostics β€” do not drop or rename fields.
diff --git a/apps/dashboard/AGENTS.md b/apps/dashboard/AGENTS.md
new file mode 100644
index 000000000..b5839e252
--- /dev/null
+++ b/apps/dashboard/AGENTS.md
@@ -0,0 +1,33 @@
+# AGENTS.md β€” apps/dashboard
+
+## Visual changes need a human
+
+An agent cannot verify rendering. If a change alters layout, styling or any
+visible behaviour, say so and ask for confirmation rather than reporting it as
+done. Prefer taking on work in `packages/services`, `packages/api` and the route
+handlers, where `pnpm verify` and the test suites are real evidence.
+
+## Runtimes
+
+The whole tRPC surface is served from
+`apps/dashboard/src/app/api/trpc/lambda/[trpc]/route.ts` on the **Node.js**
+runtime β€” several routers pull Node-only SDKs (`@slack/web-api`, email and
+notification clients). Node-only dependencies inside `@openstatus/services` are
+still forbidden, because `apps/workflows` runs the same code on Deno.
+
+## Client boundary
+
+A `"use client"` file must not **value**-import the schema barrel
+`@openstatus/db/src/schema` β€” it drags Drizzle and the whole schema graph into
+the browser bundle. Import the specific sub-path instead
+(`@openstatus/db/src/schema/page_components/constants`), or split the pure-zod
+part into a sibling file. `import type` from the barrel is fine; types erase.
+
+## Chat tool renderers
+
+Reuse the dashboard's own primitives β€” `TableCell*`, `ResultTable`,
+`ChangesTable`. Do not build bespoke chrome for a tool result.
+
+Persisted chat messages are validated on write, which is what makes the
+`asUIMessages` cast in `apps/dashboard/src/components/chat/use-chat-session.ts`
+safe. Keep casts of that kind in one named helper.
diff --git a/apps/dashboard/src/components/forms/monitor/form-general.tsx b/apps/dashboard/src/components/forms/monitor/form-general.tsx
index 0046efc2c..70179e263 100644
--- a/apps/dashboard/src/components/forms/monitor/form-general.tsx
+++ b/apps/dashboard/src/components/forms/monitor/form-general.tsx
@@ -12,7 +12,7 @@ import {
stringCompareDictionary,
textBodyAssertion,
} from "@openstatus/assertions";
-import { monitorMethods } from "@openstatus/db/src/schema";
+import { monitorMethods } from "@openstatus/db/src/schema/monitors/constants";
import { Globe, Network, Add, Server, Close } from "@openstatus/icons";
import {
AlertDialog,
diff --git a/apps/dashboard/src/components/forms/status-report-update/form-status-report.tsx b/apps/dashboard/src/components/forms/status-report-update/form-status-report.tsx
index 6f4471e5d..7b57e3af2 100644
--- a/apps/dashboard/src/components/forms/status-report-update/form-status-report.tsx
+++ b/apps/dashboard/src/components/forms/status-report-update/form-status-report.tsx
@@ -1,11 +1,9 @@
"use client";
import { zodResolver } from "@hookform/resolvers/zod";
-import {
- type StatusReportUpdate,
- statusReportStatus,
-} from "@openstatus/db/src/schema";
+import type { StatusReportUpdate } from "@openstatus/db/src/schema";
import { pageComponentImpact } from "@openstatus/db/src/schema/page_components/constants";
+import { statusReportStatus } from "@openstatus/db/src/schema/status_reports/constants";
import { Calendar as CalendarIcon, Clock } from "@openstatus/icons";
import { Button } from "@openstatus/ui/components/ui/button";
import { Calendar } from "@openstatus/ui/components/ui/calendar";
diff --git a/apps/dashboard/src/components/forms/status-report-update/form.tsx b/apps/dashboard/src/components/forms/status-report-update/form.tsx
index 3c35a0c8a..94e821c43 100644
--- a/apps/dashboard/src/components/forms/status-report-update/form.tsx
+++ b/apps/dashboard/src/components/forms/status-report-update/form.tsx
@@ -1,8 +1,8 @@
"use client";
import { zodResolver } from "@hookform/resolvers/zod";
-import { statusReportStatus } from "@openstatus/db/src/schema";
import { pageComponentImpact } from "@openstatus/db/src/schema/page_components/constants";
+import { statusReportStatus } from "@openstatus/db/src/schema/status_reports/constants";
import { Calendar as CalendarIcon, Clock } from "@openstatus/icons";
import { Button } from "@openstatus/ui/components/ui/button";
import { Calendar } from "@openstatus/ui/components/ui/calendar";
diff --git a/apps/dashboard/src/components/forms/status-report/form.tsx b/apps/dashboard/src/components/forms/status-report/form.tsx
index 76828518e..72e5b658b 100644
--- a/apps/dashboard/src/components/forms/status-report/form.tsx
+++ b/apps/dashboard/src/components/forms/status-report/form.tsx
@@ -1,8 +1,8 @@
"use client";
import { zodResolver } from "@hookform/resolvers/zod";
-import { statusReportStatus } from "@openstatus/db/src/schema";
import { pageComponentImpact } from "@openstatus/db/src/schema/page_components/constants";
+import { statusReportStatus } from "@openstatus/db/src/schema/status_reports/constants";
import { Calendar as CalendarIcon, Clock } from "@openstatus/icons";
import { Button } from "@openstatus/ui/components/ui/button";
import { Calendar } from "@openstatus/ui/components/ui/calendar";
diff --git a/apps/server/AGENTS.md b/apps/server/AGENTS.md
new file mode 100644
index 000000000..40c03a340
--- /dev/null
+++ b/apps/server/AGENTS.md
@@ -0,0 +1,36 @@
+# AGENTS.md β€” apps/server
+
+Hono, running on Deno. Four surfaces under `apps/server/src/routes/`: `v1`
+(public REST), `rpc` (ConnectRPC), `mcp`, and `slack`.
+
+## API-key scopes
+
+Two layers enforce `read` / `write`, and both must stay:
+
+- **Service level** β€” `requireScope(ctx, "write")` inside every service verb.
+ This is the real gate for anything routed through `@openstatus/services`.
+- **Transport level** β€” `requireWriteScope()` in
+ `apps/server/src/libs/middlewares/require-scope.ts`, mounted on the V1 router
+ after `authMiddleware`. V1 predates the services convention and still issues
+ inline Drizzle queries, so service-level checks would skip its write handlers
+ entirely. It maps method to scope: `GET`/`HEAD` are read, everything else is
+ write. Adding a V1 route that mutates through a `GET` silently bypasses it.
+
+New endpoints should call a service verb rather than query Drizzle directly;
+`oxlint.config.ts` already bans `@openstatus/db` and `drizzle-orm` imports in
+the handlers that have migrated, and that list grows one domain per PR.
+
+## Route config
+
+Resolve config once and pass it in;
+`createSlackRoute(config)` in `apps/server/src/routes/slack/index.ts` is the
+pattern β€” production calls `slackConfigFromEnv()` at module scope, tests build a
+route with explicit config. Reading `env` at request time is what made the slack
+route untestable under `deno test --parallel`, since the workers share one
+process environment.
+
+## MCP
+
+MCP tools declare `scope: 'read' | 'write'` and register via
+`registerScopedTool`, so a read-only key never sees a write tool in
+`tools/list`. A tool registered the plain way leaks regardless of the key.
diff --git a/apps/status-page/AGENTS.md b/apps/status-page/AGENTS.md
new file mode 100644
index 000000000..c9d0191bc
--- /dev/null
+++ b/apps/status-page/AGENTS.md
@@ -0,0 +1,39 @@
+# AGENTS.md β€” apps/status-page
+
+Public, unauthenticated, multi-tenant: the page is resolved from the request
+host or the `[domain]` segment. Assume every response you touch is served to
+anonymous visitors and cached.
+
+## Gated content
+
+Pages can be password-protected. Any new surface that renders page content β€”
+route, API handler, feed, embed β€” must apply the same gate the HTML route
+applies. The existing public representations to mirror are
+`apps/status-page/src/app/api/markdown/[[...path]]` and
+`apps/status-page/src/app/api/status/[[...path]]`.
+
+**Known open leak:** the public tRPC endpoint at `/api/trpc/lambda` serves
+gated page content. `guardTRPCSource` only filters on a spoofable
+`x-trpc-source` header and is explicitly not a security boundary. Do not treat
+it as one, and do not widen the surface until the procedures themselves check
+the gate.
+
+Never log or report tRPC `input` β€” it carries page passwords and subscriber
+tokens. `sentryLoggerLink` attaches the operation `path` only.
+
+## Caching
+
+Markdown and JSON representations negotiate on `Accept` at the same URL, so
+every response sets `Vary: Accept` plus a strong ETag. Cache-control depends on
+the page's access type β€” a gated page must not inherit a public TTL.
+
+## Theming
+
+Themes come from `@openstatus/theme-store` as OKLCH CSS variables. Add or edit
+a theme in that package; do not hard-code colours in a component.
+
+## Impact labels
+
+Status-page impact labels are coloured text only β€” no dots, no chevrons. The
+hover affordance is a dashed muted underline, never one tinted with the impact
+colour.
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
new file mode 100644
index 000000000..fa2c679f0
--- /dev/null
+++ b/apps/web/AGENTS.md
@@ -0,0 +1,24 @@
+# AGENTS.md β€” apps/web
+
+## `.well-known` routes
+
+`apps/web/src/app/.well-known/` is a dot-directory, and TypeScript's `include`
+wildcards skip those. Files under it are outside the tsconfig program, so path
+aliases (`@/…`) do not resolve and nothing there is type-checked as part of the
+app. Use relative imports (or node built-ins, as
+`.well-known/agent-skills/index.json/route.ts` does) and check the output by
+requesting the route.
+
+## Search
+
+The ⌘K search is homegrown: the ranker lives in `apps/web/src/app/api/search`
+and the index in `apps/web/src/content/utils/search-index.ts`. Do not reach for
+Pagefind, Orama or Algolia.
+
+## Content pages
+
+Content pages are MDX prose built from the existing components (`Grid`,
+`Details`, …). Reach for those before inventing a bespoke layout.
+
+Never link out to a competitor. Name them as plain text β€” an external link
+donates domain authority and leaks the conversion.
diff --git a/apps/workflows/AGENTS.md b/apps/workflows/AGENTS.md
new file mode 100644
index 000000000..b0d6b0910
--- /dev/null
+++ b/apps/workflows/AGENTS.md
@@ -0,0 +1,17 @@
+# AGENTS.md β€” apps/workflows
+
+Runs on **Deno**, not Node. `pnpm check` here is
+`deno check --sloppy-imports src/serve.ts`, and it must pass β€” it is the only
+type gate this app has (`pnpm test` runs with `--no-check`).
+
+Constraints that follow from the runtime:
+
+- No `node:*` built-ins, and no dependency that reaches for one. This app
+ imports `@openstatus/services`, so a `node:*` import added there breaks the
+ build here β€” run `pnpm check` in both packages after touching services.
+- Sentry comes from `@sentry/deno`, not `@sentry/node`.
+- Tests run `deno test --parallel`, so test files share one process
+ environment. Never drive a branch by assigning to `process.env` mid-test β€”
+ the assignment leaks into whatever else is running. Resolve config once at
+ module scope and pass it in, so "credential missing" is a value a test hands
+ you rather than a global it mutates.
diff --git a/devbox.json b/devbox.json
index 8a893e539..752b7cf0f 100644
--- a/devbox.json
+++ b/devbox.json
@@ -1,6 +1,12 @@
{
"$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.10.6/.schema/devbox.schema.json",
- "packages": ["turso-cli@latest", "nodejs@22", "bun@latest", "sqld@latest"],
+ "packages": [
+ ],
"env": {
"DEVBOX_COREPACK_ENABLED": "true",
"COREPACK_ENABLE_DOWNLOAD_PROMPT": "0"
diff --git a/devbox.lock b/devbox.lock
index 2275c40a9..3fdfc1155 100644
--- a/devbox.lock
+++ b/devbox.lock
@@ -1,51 +1,101 @@
{
"lockfile_version": "1",
"packages": {
- "bun@latest": {
- "last_modified": "2025-10-27T19:50:41Z",
- "resolved": "github:NixOS/nixpkgs/1666250dbe4141e4ca8aaf89b40a3a51c2e36144#bun",
+ "last_modified": "2026-08-01T16:34:20Z",
+ "resolved": "github:NixOS/nixpkgs/a5cbcfe954791221bfffe2307f7d1a1bf61a871e#bun",
"source": "devbox-search",
- "version": "1.3.1",
+ "version": "1.3.13",
"systems": {
"aarch64-darwin": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/q77q60pidwk04lgw5q930a32w9zp7r0p-bun-1.3.1",
+ "path": "/nix/store/f2lm68vnka4nz9wdz60vbmymnpv63f1x-bun-1.3.13",
"default": true
}
],
- "store_path": "/nix/store/q77q60pidwk04lgw5q930a32w9zp7r0p-bun-1.3.1"
+ "store_path": "/nix/store/f2lm68vnka4nz9wdz60vbmymnpv63f1x-bun-1.3.13"
},
"aarch64-linux": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/7ba6bigk4vpvxpmx0c3h6rg5zl9bs5np-bun-1.3.1",
+ "path": "/nix/store/pm8kj4ysqkf8b53yyi3576kwd23q0x23-bun-1.3.13",
"default": true
}
],
- "store_path": "/nix/store/7ba6bigk4vpvxpmx0c3h6rg5zl9bs5np-bun-1.3.1"
+ "store_path": "/nix/store/pm8kj4ysqkf8b53yyi3576kwd23q0x23-bun-1.3.13"
},
"x86_64-darwin": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/27338drvdd2cqz765wa4s51kz866v4ws-bun-1.3.1",
+ "path": "/nix/store/wn9cggwqflvqryxxb9xinl9iygndm8d9-bun-1.3.13",
"default": true
}
],
- "store_path": "/nix/store/27338drvdd2cqz765wa4s51kz866v4ws-bun-1.3.1"
+ "store_path": "/nix/store/wn9cggwqflvqryxxb9xinl9iygndm8d9-bun-1.3.13"
},
"x86_64-linux": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/jzjyn4d12klv4kp47c86z4dk1bksbg0q-bun-1.3.1",
+ "path": "/nix/store/sav1jc5c2axarnzif94rkm8byc6zw0kb-bun-1.3.13",
"default": true
}
],
- "store_path": "/nix/store/jzjyn4d12klv4kp47c86z4dk1bksbg0q-bun-1.3.1"
+ "store_path": "/nix/store/sav1jc5c2axarnzif94rkm8byc6zw0kb-bun-1.3.13"
+ }
+ }
+ },
+ "last_modified": "2026-08-01T16:34:20Z",
+ "resolved": "github:NixOS/nixpkgs/a5cbcfe954791221bfffe2307f7d1a1bf61a871e#deno",
+ "source": "devbox-search",
+ "version": "2.9.4",
+ "systems": {
+ "aarch64-darwin": {
+ "outputs": [
+ {
+ "name": "out",
+ "path": "/nix/store/lmqwp7gr0hapgh48vwfkvzd9as1qzsp2-deno-2.9.4",
+ "default": true
+ },
+ {
+ "name": "denort",
+ "path": "/nix/store/g0yd5grzazxkfgclcfbqxvqy1b8c6jy8-deno-2.9.4-denort"
+ }
+ ],
+ "store_path": "/nix/store/lmqwp7gr0hapgh48vwfkvzd9as1qzsp2-deno-2.9.4"
+ },
+ "aarch64-linux": {
+ "outputs": [
+ {
+ "name": "out",
+ "path": "/nix/store/gskl25gjd0aqrz432ahapzyq45mfim0l-deno-2.9.4",
+ "default": true
+ },
+ {
+ "name": "denort",
+ "path": "/nix/store/dm9j5iismy4bm9vch0z4g0ir6yg3k9bl-deno-2.9.4-denort"
+ }
+ ],
+ "store_path": "/nix/store/gskl25gjd0aqrz432ahapzyq45mfim0l-deno-2.9.4"
+ },
+ "x86_64-linux": {
+ "outputs": [
+ {
+ "name": "out",
+ "path": "/nix/store/1w42p7jj0dmw525pnnlsj9496fsb30fc-deno-2.9.4",
+ "default": true
+ },
+ {
+ "name": "denort",
+ "path": "/nix/store/0bgyyi7jcjlbjmf55if1xv7dk64qq2vr-deno-2.9.4-denort"
+ }
+ ],
+ "store_path": "/nix/store/1w42p7jj0dmw525pnnlsj9496fsb30fc-deno-2.9.4"
}
}
},
@@ -53,90 +103,90 @@
"last_modified": "2025-11-05T16:44:39Z",
"resolved": "github:NixOS/nixpkgs/ffcdcf99d65c61956d882df249a9be53e5902ea5?lastModified=1762361079&narHash=sha256-lz718rr1BDpZBYk7%2BG8cE6wee3PiBUpn8aomG%2FvLLiY%3D"
},
- "nodejs@22": {
- "last_modified": "2025-05-31T03:30:20Z",
+ "last_modified": "2025-12-27T12:56:01Z",
"plugin_version": "0.0.2",
- "resolved": "github:NixOS/nixpkgs/59138c7667b7970d205d6a05a8bfa2d78caa3643#nodejs_22",
+ "resolved": "github:NixOS/nixpkgs/3edc4a30ed3903fdf6f90c837f961fa6b49582d1#nodejs_24",
"source": "devbox-search",
- "version": "22.14.0",
+ "version": "24.12.0",
"systems": {
"aarch64-darwin": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/g5bv4gi6p7ryhs2hbaryxs6ivsxa6lqc-nodejs-22.14.0",
+ "path": "/nix/store/b1h0af3yb3z9jz048phclcqw6ihiww67-nodejs-24.12.0",
"default": true
},
{
"name": "dev",
- "path": "/nix/store/96vpirdcns8zxdwzwl7n804012lwrf1n-nodejs-22.14.0-dev"
+ "path": "/nix/store/ksn4nj0nbp0ikmh4scy9x4biqqdswwhy-nodejs-24.12.0-dev"
},
{
"name": "libv8",
- "path": "/nix/store/xph2837xqjnra80mqlk64xp7vb3kkqxs-nodejs-22.14.0-libv8"
+ "path": "/nix/store/3x72bm7l30ib7l7cximrp0sklcq8jqwy-nodejs-24.12.0-libv8"
}
],
- "store_path": "/nix/store/g5bv4gi6p7ryhs2hbaryxs6ivsxa6lqc-nodejs-22.14.0"
+ "store_path": "/nix/store/b1h0af3yb3z9jz048phclcqw6ihiww67-nodejs-24.12.0"
},
"aarch64-linux": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/cwb781xbp70f72njqh8vhvbsf1xq87i5-nodejs-22.14.0",
+ "path": "/nix/store/9jfsyhcr9c6rpm94lrkibv75jkggvwss-nodejs-24.12.0",
"default": true
},
{
"name": "dev",
- "path": "/nix/store/0w5mql46am2qai707a42q983l44l1h9z-nodejs-22.14.0-dev"
+ "path": "/nix/store/7izhv9x1yvsmyrhmmyps6bxjjclajm80-nodejs-24.12.0-dev"
},
{
"name": "libv8",
- "path": "/nix/store/vy56lahz381ayvw3hym3wj4r4ggv7gbk-nodejs-22.14.0-libv8"
+ "path": "/nix/store/8hl74pnc1qyz68rg10ixw7fz32hcxqkk-nodejs-24.12.0-libv8"
}
],
- "store_path": "/nix/store/cwb781xbp70f72njqh8vhvbsf1xq87i5-nodejs-22.14.0"
+ "store_path": "/nix/store/9jfsyhcr9c6rpm94lrkibv75jkggvwss-nodejs-24.12.0"
},
"x86_64-darwin": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/086zjv14ipka2vbpgwil3xyvi5ml4vh3-nodejs-22.14.0",
+ "path": "/nix/store/cj1243xswxvnwgifyiyg8axhn0r2vl48-nodejs-24.12.0",
"default": true
},
{
"name": "dev",
- "path": "/nix/store/24n01nfvy908pwzwpgsl0k4227187i7i-nodejs-22.14.0-dev"
+ "path": "/nix/store/kzia3rkaf9vwpn3py23q9v49jpjm6zx7-nodejs-24.12.0-dev"
},
{
"name": "libv8",
- "path": "/nix/store/jiwk0in1wk85crn9vp03gg937gbh1s0w-nodejs-22.14.0-libv8"
+ "path": "/nix/store/xszji81xj7ghjhz7jk0jkhb84nfwyd8f-nodejs-24.12.0-libv8"
}
],
- "store_path": "/nix/store/086zjv14ipka2vbpgwil3xyvi5ml4vh3-nodejs-22.14.0"
+ "store_path": "/nix/store/cj1243xswxvnwgifyiyg8axhn0r2vl48-nodejs-24.12.0"
},
"x86_64-linux": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/c8jxsih8yy2rnncdmx2hyraizf689nvp-nodejs-22.14.0",
+ "path": "/nix/store/9z1v3wyrxp6fpyzw21lcakd5w7aknzyc-nodejs-24.12.0",
"default": true
},
{
"name": "libv8",
- "path": "/nix/store/s8gnrgh9hgnbkrc1wrn21d6zvkbvm9vi-nodejs-22.14.0-libv8"
+ "path": "/nix/store/5yvx909wlis13qd2y1ahwl7ij21ma69a-nodejs-24.12.0-libv8"
},
{
"name": "dev",
- "path": "/nix/store/xw8c1c0inxq3xl1d7axz19vq8c05kjk5-nodejs-22.14.0-dev"
+ "path": "/nix/store/7ll99p08gmpg0n048669p80zjibl5akr-nodejs-24.12.0-dev"
}
],
- "store_path": "/nix/store/c8jxsih8yy2rnncdmx2hyraizf689nvp-nodejs-22.14.0"
+ "store_path": "/nix/store/9z1v3wyrxp6fpyzw21lcakd5w7aknzyc-nodejs-24.12.0"
}
}
},
- "sqld@latest": {
- "last_modified": "2025-10-22T20:59:19Z",
- "resolved": "github:NixOS/nixpkgs/01b6809f7f9d1183a2b3e081f0a1e6f8f415cb09#sqld",
+ "last_modified": "2026-05-21T08:15:18Z",
+ "resolved": "github:NixOS/nixpkgs/4a29d733e8a7d5b824c3d8c958a946a9867b3eb2#sqld",
"source": "devbox-search",
"version": "0.24.32",
"systems": {
@@ -144,47 +194,47 @@
"outputs": [
{
"name": "out",
- "path": "/nix/store/sgwjj0nld67nwx8w7b529bwvfyv9r9r0-sqld-0.24.32",
+ "path": "/nix/store/kxi3jrkyd0sg0wy9rz948vig1lxy395y-sqld-0.24.32",
"default": true
}
],
- "store_path": "/nix/store/sgwjj0nld67nwx8w7b529bwvfyv9r9r0-sqld-0.24.32"
+ "store_path": "/nix/store/kxi3jrkyd0sg0wy9rz948vig1lxy395y-sqld-0.24.32"
},
"aarch64-linux": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/gh46ibxxbfvz2qymp0vd2n4akad5wp7x-sqld-0.24.32",
+ "path": "/nix/store/4zlylzcrm9m8cvch4y88ynyi1d47kh7z-sqld-0.24.32",
"default": true
}
],
- "store_path": "/nix/store/gh46ibxxbfvz2qymp0vd2n4akad5wp7x-sqld-0.24.32"
+ "store_path": "/nix/store/4zlylzcrm9m8cvch4y88ynyi1d47kh7z-sqld-0.24.32"
},
"x86_64-darwin": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/gm5zbh90kw0qc9zmmmyrn3icjjycmdgz-sqld-0.24.32",
+ "path": "/nix/store/anmk86cv1hv6w89pak60cbadwm4fd1bs-sqld-0.24.32",
"default": true
}
],
- "store_path": "/nix/store/gm5zbh90kw0qc9zmmmyrn3icjjycmdgz-sqld-0.24.32"
+ "store_path": "/nix/store/anmk86cv1hv6w89pak60cbadwm4fd1bs-sqld-0.24.32"
},
"x86_64-linux": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/j29jdlfnnqpvm22n0w4sj4zf2lm3lv0w-sqld-0.24.32",
+ "path": "/nix/store/ib3jvxmgc731dxqyzx2i9sh1sj5n229b-sqld-0.24.32",
"default": true
}
],
- "store_path": "/nix/store/j29jdlfnnqpvm22n0w4sj4zf2lm3lv0w-sqld-0.24.32"
+ "store_path": "/nix/store/ib3jvxmgc731dxqyzx2i9sh1sj5n229b-sqld-0.24.32"
}
}
},
- "turso-cli@latest": {
- "last_modified": "2025-10-22T20:59:19Z",
- "resolved": "github:NixOS/nixpkgs/01b6809f7f9d1183a2b3e081f0a1e6f8f415cb09#turso-cli",
+ "last_modified": "2026-01-23T17:20:52Z",
+ "resolved": "github:NixOS/nixpkgs/a1bab9e494f5f4939442a57a58d0449a109593fe#turso-cli",
"source": "devbox-search",
"version": "1.0.15",
"systems": {
@@ -192,41 +242,41 @@
"outputs": [
{
"name": "out",
- "path": "/nix/store/n2a4r9cnif35d00qmn4zb96643n9xd05-turso-cli-1.0.15",
+ "path": "/nix/store/7mm8wc2f5p2h6hz6hrjkh1b7kzlg9cpg-turso-cli-1.0.15",
"default": true
}
],
- "store_path": "/nix/store/n2a4r9cnif35d00qmn4zb96643n9xd05-turso-cli-1.0.15"
+ "store_path": "/nix/store/7mm8wc2f5p2h6hz6hrjkh1b7kzlg9cpg-turso-cli-1.0.15"
},
"aarch64-linux": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/yy8nfs9z5f19xvjn07qxgi533ah59wdd-turso-cli-1.0.15",
+ "path": "/nix/store/619jqmd4q36k4li0ihq2hy3pvhlzkrgn-turso-cli-1.0.15",
"default": true
}
],
- "store_path": "/nix/store/yy8nfs9z5f19xvjn07qxgi533ah59wdd-turso-cli-1.0.15"
+ "store_path": "/nix/store/619jqmd4q36k4li0ihq2hy3pvhlzkrgn-turso-cli-1.0.15"
},
"x86_64-darwin": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/6lcri76g9pdjw628kw60zxa4ixhz41vq-turso-cli-1.0.15",
+ "path": "/nix/store/6kws97rwr8sbamhb7w9hmqi25w0p18c1-turso-cli-1.0.15",
"default": true
}
],
- "store_path": "/nix/store/6lcri76g9pdjw628kw60zxa4ixhz41vq-turso-cli-1.0.15"
+ "store_path": "/nix/store/6kws97rwr8sbamhb7w9hmqi25w0p18c1-turso-cli-1.0.15"
},
"x86_64-linux": {
"outputs": [
{
"name": "out",
- "path": "/nix/store/87zwzwq3h8hmznw1wqlqp9ksgy16s20n-turso-cli-1.0.15",
+ "path": "/nix/store/k3s154j4q09k7h4hwacb3crw50p76g34-turso-cli-1.0.15",
"default": true
}
],
- "store_path": "/nix/store/87zwzwq3h8hmznw1wqlqp9ksgy16s20n-turso-cli-1.0.15"
+ "store_path": "/nix/store/k3s154j4q09k7h4hwacb3crw50p76g34-turso-cli-1.0.15"
}
}
}
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 0dee58f9a..7ada3ca35 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -1,11 +1,16 @@
# Architecture Decision Records
-This directory holds the architecturally significant decisions made on
-openstatus, in [MADR](https://adr.github.io/madr/) format.
+**This set is frozen. Do not add new ADRs.**
-An ADR captures *why* a decision was made, what alternatives were weighed, and
-what trade-offs were accepted. `CLAUDE.md` documents the conventions in force
-today; ADRs explain how those conventions came to be.
+These nine records are background on *why* a handful of architectural decisions
+were made, in [MADR](https://adr.github.io/madr/) format. They are history, and
+several describe a change rather than a state β€” ADR-0008 says
+"`loadSeededWorkspace` is gone", which only makes sense against the world before
+it.
+
+Current-state truth lives in `AGENTS.md` at the repo root and in the nested
+`AGENTS.md` files it links. When a decision changes, update those; do not write
+a superseding ADR here.
## Index
@@ -19,28 +24,4 @@ today; ADRs explain how those conventions came to be.
| [0005](0005-turso-for-app-data-tinybird-for-time-series.md) | Turso for application data, Tinybird for time-series | accepted |
| [0006](0006-persist-external-incidents-in-turso.md) | Persist external-service incidents in Turso, not Tinybird | accepted |
| [0007](0007-store-external-service-components.md) | Store external-service components in Turso, their status history in Tinybird | accepted |
-
-## When to write an ADR
-
-Write one when a decision is hard to reverse, cross-cutting, or non-obvious β€”
-for example:
-
-- adopting or dropping a framework, library, or runtime;
-- a repo-wide pattern every contributor must follow;
-- a data-model or API-contract decision that is expensive to change;
-- choosing one approach over a reasonable alternative someone would ask about.
-
-Skip it for routine, local, or easily reversible changes.
-
-## How to add one
-
-1. Copy `template.md` to `NNNN-kebab-case-title.md`, where `NNNN` is the next
- zero-padded number.
-2. Fill it in. Keep it short β€” drivers, options, outcome, consequences.
-3. Add a row to the index above.
-4. Open it in the same PR as (or just before) the change it describes.
-
-## Changing a decision
-
-ADRs are immutable once accepted. To change a decision, write a new ADR and set
-the old one's `status` to `superseded by ADR-NNNN`.
+| [0008](0008-isolated-test-databases.md) | One test database per package, one workspace per suite, injected route config | accepted |
diff --git a/oxlint.config.ts b/oxlint.config.ts
index 0d2de31ec..2f56e4ef6 100644
--- a/oxlint.config.ts
+++ b/oxlint.config.ts
@@ -2,6 +2,7 @@ import { defineConfig } from "oxlint";
export default defineConfig({
plugins: ["eslint", "typescript", "react", "unicorn", "oxc"],
+ jsPlugins: ["./scripts/oxlint-plugin-openstatus.js"],
categories: {
correctness: "warn",
},
@@ -111,5 +112,33 @@ export default defineConfig({
"typescript/no-explicit-any": "off",
},
},
+ {
+ // Behaviour-triggered, not filename-triggered: anything opening a
+ // transaction in the services layer is a mutation.
+ files: ["packages/services/src/**/*.ts"],
+ excludeFiles: ["**/__tests__/**", "**/*.test.ts"],
+ rules: {
+ "openstatus/services-mutation-guards": "error",
+ // apps/workflows runs this on Deno, and it stays Edge-safe by design.
+ "no-restricted-imports": [
+ "error",
+ {
+ patterns: [
+ {
+ group: ["node:*"],
+ message:
+ "@openstatus/services must stay runtime-agnostic β€” no node built-ins. Hand-roll the helper (see deepEqual) or move the code to a Node-only package.",
+ },
+ ],
+ },
+ ],
+ },
+ },
+ {
+ files: ["apps/dashboard/src/**/*.tsx", "apps/dashboard/src/**/*.ts"],
+ rules: {
+ "openstatus/no-db-barrel-in-client": "error",
+ },
+ },
],
});
diff --git a/package.json b/package.json
index 995b4fb7f..fe4747769 100644
--- a/package.json
+++ b/package.json
@@ -17,6 +17,9 @@
"format:check": "oxfmt --check && oxlint",
"lint:turbo": "turbo run lint",
"check": "turbo run check",
+ "check:docs": "node scripts/check-doc-refs.mts",
+ "verify": "pnpm format:check && pnpm check:docs && pnpm check",
+ "verify:test": "turbo run test --affected --concurrency=1",
"dev:web": "turbo run dev --filter='./apps/web' --filter='./packages/db'",
"dev:status-page": "turbo run dev --filter='./apps/status-page' --filter='./packages/db'",
"dev:dashboard": "turbo run dev --filter='./apps/dashboard' --filter='./packages/db'",
diff --git a/packages/api/src/router/import.test.ts b/packages/api/src/router/import.test.ts
index 9cb9869ad..40d9ac0ce 100644
--- a/packages/api/src/router/import.test.ts
+++ b/packages/api/src/router/import.test.ts
@@ -195,7 +195,7 @@ async function cleanup() {
// entity. The entities are gone but the rows are not β€” and
// INTEGER PRIMARY KEY ids recycle, so a later test inserting into the
// same table can land on an id that already has an audit row,
- // inheriting its actor attribution. See docs/adr/test-audit-cleanup.md.
+ // inheriting its actor attribution. See packages/services/AGENTS.md.
await Promise.all([
clearAuditLogFor({ entityType: "page", entityIds: createdIds.pages }),
clearAuditLogFor({
diff --git a/packages/api/src/router/maintenance.test.ts b/packages/api/src/router/maintenance.test.ts
index c24e94259..4917f6fd1 100644
--- a/packages/api/src/router/maintenance.test.ts
+++ b/packages/api/src/router/maintenance.test.ts
@@ -21,7 +21,7 @@ let otherWorkspaceComponentId: number;
// the `maintenance.create` / `maintenance.update` audit rows outlive
// the row itself and β€” because INTEGER PRIMARY KEY recycles β€” a later
// test inserting into `maintenance` can land on the orphan's id and
-// inherit its actor attribution. See docs/adr/test-audit-cleanup.md.
+// inherit its actor attribution. See packages/services/AGENTS.md.
const createdMaintenanceIds: number[] = [];
const updatedMaintenanceIds: number[] = [];
diff --git a/packages/api/src/router/statusReport.test.ts b/packages/api/src/router/statusReport.test.ts
index 1c63e8ebd..a0cb8c7b1 100644
--- a/packages/api/src/router/statusReport.test.ts
+++ b/packages/api/src/router/statusReport.test.ts
@@ -24,7 +24,7 @@ let otherWorkspaceComponentId: number;
// reached the parent β€” leaving an orphan report and an orphan audit row.
// SQLite recycles INTEGER PRIMARY KEY ids on delete, so a later test
// inserting a status_report could land on the orphan's id and inherit
-// its `actor_type=user` attribution. See docs/adr/test-audit-cleanup.md.
+// its `actor_type=user` attribution. See packages/services/AGENTS.md.
const createdReportIds: number[] = [];
const updatedReportIds: number[] = [];
diff --git a/packages/db/src/schema/status_reports/constants.ts b/packages/db/src/schema/status_reports/constants.ts
new file mode 100644
index 000000000..fdaba4129
--- /dev/null
+++ b/packages/db/src/schema/status_reports/constants.ts
@@ -0,0 +1,8 @@
+// Kept free of drizzle imports so `"use client"` files can pull the enum
+// without dragging the schema graph into the browser bundle.
+export const statusReportStatus = [
+ "investigating",
+ "identified",
+ "monitoring",
+ "resolved",
+] as const;
diff --git a/packages/db/src/schema/status_reports/status_reports.ts b/packages/db/src/schema/status_reports/status_reports.ts
index 004a56cdf..4c245a745 100644
--- a/packages/db/src/schema/status_reports/status_reports.ts
+++ b/packages/db/src/schema/status_reports/status_reports.ts
@@ -7,13 +7,9 @@ import {
} from "../page_components";
import { page } from "../pages";
import { workspace } from "../workspaces";
+import { statusReportStatus } from "./constants";
-export const statusReportStatus = [
- "investigating",
- "identified",
- "monitoring",
- "resolved",
-] as const;
+export { statusReportStatus };
export const statusReport = sqliteTable(
"status_report",
diff --git a/packages/services/AGENTS.md b/packages/services/AGENTS.md
new file mode 100644
index 000000000..17da257ce
--- /dev/null
+++ b/packages/services/AGENTS.md
@@ -0,0 +1,82 @@
+# AGENTS.md β€” @openstatus/services
+
+Every workspace-scoped mutation lives here, not in a tRPC router or a Hono
+handler. Routers validate input, call a verb, map errors.
+
+## Shape of a verb
+
+- **One file per verb** under `packages/services/src/<entity>/` (`create.ts`,
+ `update.ts`, `remove.ts`), re-exported from that entity's `index.ts`. Callers
+ import from `@openstatus/services/<entity>`.
+- **Signature:** `async function verbEntity(args: { ctx: ServiceContext; input: VerbInput })`.
+ `ctx` carries `workspace`, `actor`, and an optional `db`/transaction.
+- **`requireScope(ctx, "write")` is the first line of every write verb** β€”
+ before `Input.parse(...)`, before `withTransaction`.
+- **`withTransaction(ctx, async (tx) => …)`** wraps every mutation; it reuses an
+ outer transaction if one was threaded through `ctx`, otherwise opens one.
+ Inside the block, write through `tx` β€” never `defaultDb`.
+- **Every read and write filters by `ctx.workspace.id`.** Use the
+ `getXInWorkspace` fetch-or-throw helpers in the entity's `internal.ts`.
+- **Throw `ServiceError` subclasses** from `./errors`. Routers convert them with
+ `toTRPCError`.
+
+## Audit log
+
+`emitAudit(tx, ctx, entry)` runs inside the same transaction as the mutation.
+Fail-closed: a failed audit insert rolls the mutation back.
+
+- Updates pass both `before` (pre-mutation snapshot) and `after` (the
+ `.returning()` row); `changed_fields` is diffed automatically and no-op updates
+ are skipped. Creates pass only `after`, deletes only `before`.
+- **Strip secrets from snapshots** β€” credentials, bot tokens, raw API keys.
+- Action names are `{entity}.{verb}`; new variants go in the discriminated union
+ at `packages/db/src/schema/audit_logs/validation.ts`.
+
+A missing `emitAudit` or `requireScope` is a defect, not a style nit. Both are
+lint-enforced; if a verb genuinely needs neither, the inline disable must carry
+a reason.
+
+## Scope enforcement
+
+API keys carry `read` / `write` scopes. "Write" means any DB mutation **or**
+side-effecting external call (probe, webhook, notification); everything else is
+read. `requireScope` is a no-op for `user` / `system` / `slack` / `webhook` /
+`subscriber` actors and active for `apiKey` and `mcp`. MCP tools declare
+`scope` and register through `registerScopedTool`, so read-only keys never see
+write tools.
+
+## Runtime constraints
+
+- **No `node:*` imports.** `apps/workflows` runs this code on Deno, and the
+ package is written to stay Edge-safe so a Next.js route can adopt it without a
+ rewrite β€” no Edge route imports it today. That is why `deepEqual` is
+ hand-rolled rather than pulled from `node:util`.
+- **No logtape here.** It breaks Edge builds; use `console.warn`.
+
+## Query plans
+
+Turso exposes neither `EXPLAIN` nor `ANALYZE`, and `sqlite_stat1` never exists
+there. Verify a plan locally against `openstatus-dev.db` instead; in production
+the only signal you get is `rows_read`.
+
+## Tests
+
+Suites live in `packages/services/src/<entity>/__tests__/`, mint their own
+workspace, and assert the audit side-effect with `expectAuditRow(...)` from
+`packages/services/test/helpers.ts`. Each entity also carries a
+`'rejects read-only actor'` case built with `makeApiKeyCtx(...)`; `requireScope`
+fires before any DB lookup, so fake ids are fine there.
+
+**Audit rows outlive the entities they describe.** A suite that creates entities
+through a service on the committed db and deletes them in cleanup must also call
+`clearAuditLogFor(...)` β€” SQLite recycles `INTEGER PRIMARY KEY` ids after
+deletes, so a later test's freshly-inserted entity can land on the orphan's id
+and inherit its actor attribution. The failure surfaces in an unrelated suite,
+which is what makes it expensive.
+
+## Uptime weights
+
+`impactUptimeWeight` in `packages/db/src/schema/page_components/constants.ts`
+is pinned by tests: `major_outage` = 1, `partial_outage` = 0.5,
+`degraded_performance` = 0. These numbers have been changed and reverted before β€”
+confirm with a maintainer before touching them.
diff --git a/packages/services/src/chat-session/create.ts b/packages/services/src/chat-session/create.ts
index e941065a0..3baea4188 100644
--- a/packages/services/src/chat-session/create.ts
+++ b/packages/services/src/chat-session/create.ts
@@ -14,6 +14,10 @@ import { UnauthorizedError } from "../errors";
import { enforceSessionCap } from "./internal";
import { CreateChatSessionInput } from "./schemas";
+// Per-user UI state, not workspace configuration: only user actors get past
+// `tryGetActorUserId`, so `requireScope` could never fire, and the audit action
+// union has no `chat_session` verb.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function createChatSession(args: {
ctx: ServiceContext;
input: CreateChatSessionInput;
diff --git a/packages/services/src/chat-session/remove.ts b/packages/services/src/chat-session/remove.ts
index d6e3ebe03..166017677 100644
--- a/packages/services/src/chat-session/remove.ts
+++ b/packages/services/src/chat-session/remove.ts
@@ -10,6 +10,10 @@ import { UnauthorizedError } from "../errors";
import { getChatSessionInWorkspace } from "./internal";
import { DeleteChatSessionInput } from "./schemas";
+// Per-user UI state, not workspace configuration: only user actors get past
+// `tryGetActorUserId`, so `requireScope` could never fire, and the audit action
+// union has no `chat_session` verb.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function deleteChatSession(args: {
ctx: ServiceContext;
input: DeleteChatSessionInput;
diff --git a/packages/services/src/chat-session/set.ts b/packages/services/src/chat-session/set.ts
index 4c6a5d85b..79fed1700 100644
--- a/packages/services/src/chat-session/set.ts
+++ b/packages/services/src/chat-session/set.ts
@@ -20,6 +20,10 @@ import { SetChatSessionMessagesInput } from "./schemas";
* full-replace lets each fire be the canonical snapshot. Existing-row
* `createdAt` wins on overlap so older messages don't drift forward.
*/
+// Per-user UI state, not workspace configuration: only user actors get past
+// `tryGetActorUserId`, so `requireScope` could never fire, and the audit action
+// union has no `chat_session` verb.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function setChatSessionMessages(args: {
ctx: ServiceContext;
input: SetChatSessionMessagesInput;
diff --git a/packages/services/src/import/run.ts b/packages/services/src/import/run.ts
index 35c8aabb6..9eab9de5c 100644
--- a/packages/services/src/import/run.ts
+++ b/packages/services/src/import/run.ts
@@ -2,6 +2,7 @@ import { and, count, db as defaultDb, eq } from "@openstatus/db";
import { page, pageComponent } from "@openstatus/db/src/schema";
import type { ImportSummary } from "@openstatus/importers";
+import { requireScope } from "../auth";
import type { ServiceContext } from "../context";
import { NotFoundError, ValidationError } from "../errors";
import { addLimitWarnings } from "./limits";
@@ -40,6 +41,7 @@ export async function runImport(args: {
input: RunImportInput;
}): Promise<ImportSummary> {
const { ctx } = args;
+ requireScope(ctx, "write");
const input = RunImportInput.parse(args.input);
const tx = ctx.db ?? defaultDb;
diff --git a/packages/services/src/member/delete.ts b/packages/services/src/member/delete.ts
index 5e467c65d..e656c6ba4 100644
--- a/packages/services/src/member/delete.ts
+++ b/packages/services/src/member/delete.ts
@@ -26,6 +26,9 @@ import { DeleteMemberInput } from "./schemas";
* Only fires when the actor is an openstatus user: removing another user is
* not something a system / apiKey / webhook actor should do today.
*/
+// The delete and its `member.delete` audit row live in
+// `removeMemberInWorkspace`; this verb only adds the owner / self-removal guards.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function deleteMember(args: {
ctx: ServiceContext;
input: DeleteMemberInput;
diff --git a/packages/services/src/monitor/relations.ts b/packages/services/src/monitor/relations.ts
index 1ecfc858f..0572e2470 100644
--- a/packages/services/src/monitor/relations.ts
+++ b/packages/services/src/monitor/relations.ts
@@ -7,6 +7,7 @@ import {
} from "@openstatus/db/src/schema";
import { emitAudit } from "../audit";
+import { requireScope } from "../auth";
import { type ServiceContext, withTransaction } from "../context";
import { LimitExceededError } from "../errors";
import {
@@ -31,6 +32,7 @@ export async function updateMonitorSchedulingRegions(args: {
input: UpdateMonitorSchedulingRegionsInput;
}): Promise<void> {
const { ctx } = args;
+ requireScope(ctx, "write");
const input = UpdateMonitorSchedulingRegionsInput.parse(args.input);
const limits = ctx.workspace.limits;
@@ -104,6 +106,7 @@ export async function updateMonitorTags(args: {
input: UpdateMonitorTagsInput;
}): Promise<void> {
const { ctx } = args;
+ requireScope(ctx, "write");
const input = UpdateMonitorTagsInput.parse(args.input);
await withTransaction(ctx, async (tx) => {
@@ -157,6 +160,7 @@ export async function updateMonitorNotifiers(args: {
input: UpdateMonitorNotifiersInput;
}): Promise<void> {
const { ctx } = args;
+ requireScope(ctx, "write");
const input = UpdateMonitorNotifiersInput.parse(args.input);
await withTransaction(ctx, async (tx) => {
diff --git a/packages/services/src/page-subscriber/send-test-webhook.ts b/packages/services/src/page-subscriber/send-test-webhook.ts
index 5990e708f..186367b17 100644
--- a/packages/services/src/page-subscriber/send-test-webhook.ts
+++ b/packages/services/src/page-subscriber/send-test-webhook.ts
@@ -17,6 +17,9 @@ import { SendPageSubscriberTestWebhookInput } from "./schemas";
* No audit emit β€” a test dispatch has no effect on the entity's durable
* state. If we add "last-tested-at" bookkeeping later, we'd revisit.
*/
+// The transaction only reads the subscriber row; the webhook send mutates
+// nothing, so there is no state change to audit.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function sendPageSubscriberTestWebhook(args: {
ctx: ServiceContext;
input: SendPageSubscriberTestWebhookInput;
diff --git a/packages/services/src/page-subscriber/slack.ts b/packages/services/src/page-subscriber/slack.ts
index dafb488bd..954f9ee0e 100644
--- a/packages/services/src/page-subscriber/slack.ts
+++ b/packages/services/src/page-subscriber/slack.ts
@@ -41,6 +41,9 @@ function channelLabel(channelId: string, channelName?: string): string {
* authenticated workspace at the call site β€” both workspace and audit actor
* are resolved from the page. Auto-accepted (the slash command is consent).
*/
+// Token-addressed self-service by an anonymous visitor: the audit actor is
+// `subscriber`, for which `requireScope` is a documented no-op.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function createSlackSubscriber(args: {
input: CreateSlackSubscriberInput;
db?: DB;
@@ -164,6 +167,9 @@ export async function createSlackSubscriber(args: {
});
}
+// Token-addressed self-service by an anonymous visitor: the audit actor is
+// `subscriber`, for which `requireScope` is a documented no-op.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function removeSlackSubscriber(args: {
input: RemoveSlackSubscriberInput;
db?: DB;
diff --git a/packages/services/src/page-subscriber/unsubscribe.ts b/packages/services/src/page-subscriber/unsubscribe.ts
index d5cc93ff3..6303dac61 100644
--- a/packages/services/src/page-subscriber/unsubscribe.ts
+++ b/packages/services/src/page-subscriber/unsubscribe.ts
@@ -16,6 +16,9 @@ import { UnsubscribeSubscriberInput } from "./schemas";
* second call on an already-unsubscribed row returns silently with no
* audit emit.
*/
+// Token-addressed self-service by an anonymous visitor: the audit actor is
+// `subscriber`, for which `requireScope` is a documented no-op.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function unsubscribeSubscriber(args: {
input: UnsubscribeSubscriberInput;
db?: DB;
diff --git a/packages/services/src/page-subscriber/update-scope.ts b/packages/services/src/page-subscriber/update-scope.ts
index 42f571f15..5ef3f981c 100644
--- a/packages/services/src/page-subscriber/update-scope.ts
+++ b/packages/services/src/page-subscriber/update-scope.ts
@@ -23,6 +23,9 @@ import { UpdateSubscriberScopeInput } from "./schemas";
* them via `metadata` to keep the audit row from being dropped by the
* empty-diff guard in `emitAudit`.
*/
+// Token-addressed self-service by an anonymous visitor: the audit actor is
+// `subscriber`, for which `requireScope` is a documented no-op.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function updateSubscriberScope(args: {
input: UpdateSubscriberScopeInput;
db?: DB;
diff --git a/packages/services/src/page-subscriber/upsert.ts b/packages/services/src/page-subscriber/upsert.ts
index fab85bf9a..b2710b087 100644
--- a/packages/services/src/page-subscriber/upsert.ts
+++ b/packages/services/src/page-subscriber/upsert.ts
@@ -49,6 +49,9 @@ export type UpsertSelfSignupResult = {
* components-only change)
* - already verified row β†’ no audit (no-op return)
*/
+// Token-addressed self-service by an anonymous visitor: the audit actor is
+// `subscriber`, for which `requireScope` is a documented no-op.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function upsertSelfSignupSubscriber(args: {
input: UpsertSelfSignupSubscriberInput;
db?: DB;
diff --git a/packages/services/src/page-subscriber/verify.ts b/packages/services/src/page-subscriber/verify.ts
index f4f96bb80..120d051f7 100644
--- a/packages/services/src/page-subscriber/verify.ts
+++ b/packages/services/src/page-subscriber/verify.ts
@@ -32,6 +32,9 @@ export type VerifyResult = {
* `acceptedAt` and writes one `page_subscriber.update` audit row with
* actor `subscriber:{id}`.
*/
+// Token-addressed self-service by an anonymous visitor: the audit actor is
+// `subscriber`, for which `requireScope` is a documented no-op.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function verifySelfSignupSubscriber(args: {
input: VerifySelfSignupSubscriberInput;
db?: DB;
diff --git a/packages/services/src/workspace/downgrade.ts b/packages/services/src/workspace/downgrade.ts
index 010df2021..035b5fafc 100644
--- a/packages/services/src/workspace/downgrade.ts
+++ b/packages/services/src/workspace/downgrade.ts
@@ -43,6 +43,9 @@ import { updateWorkspacePlan } from "./update";
* caller can release them on Vercel *after* the transaction commits β€”
* that cleanup is best-effort and must not roll the downgrade back.
*/
+// Every trim step routes through an audited entity verb, so the cascade is
+// fully attributable; the plan flip itself is audited by `updateWorkspacePlan`.
+// oxlint-disable-next-line openstatus/services-mutation-guards
export async function downgradeWorkspaceToFree(args: {
ctx: ServiceContext;
}): Promise<{ customDomains: string[]; ssoDisabled: boolean }> {
diff --git a/packages/services/test/helpers.ts b/packages/services/test/helpers.ts
index d20810588..171697bdc 100644
--- a/packages/services/test/helpers.ts
+++ b/packages/services/test/helpers.ts
@@ -66,7 +66,7 @@ export async function clearAuditLog(
* the audit row outlives the entity, and because SQLite recycles
* INTEGER PRIMARY KEY ids after deletes, a later test's freshly-inserted
* entity can land on the orphan's id and inherit its actor attribution.
- * See docs/adr/test-audit-cleanup.md.
+ * See packages/services/AGENTS.md.
*/
export async function clearAuditLogFor(args: {
entityType: string;
diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md
new file mode 100644
index 000000000..037f0251c
--- /dev/null
+++ b/packages/ui/AGENTS.md
@@ -0,0 +1,69 @@
+# AGENTS.md β€” @openstatus/ui
+
+Three directories under `src/components/`, three different contracts. Getting
+the wrong one is the most common mistake here.
+
+| Directory | What it is | Who else sees it |
+|---|---|---|
+| `ui/` | Stock shadcn/ui primitives | Nobody β€” never shipped |
+| `blocks/` | The openstatus shadcn registry (status page) | Every external consumer |
+| `custom/` | openstatus-only components | Our apps only |
+
+`blocks/README.md` documents the composition API and `REGISTRY.md` the publish
+flow. This file is only the rules those two assume you already know.
+
+## Do not customize `src/components/ui/`
+
+These 41 files are shadcn's, and the registry ships **zero** of them. Blocks
+instead declare `registryDependencies: ["button", "tooltip", …]`, which resolve
+to the **consumer's own** shadcn components at install time.
+
+So a block that depends on a local tweak to `button.tsx` renders correctly in
+this repo and incorrectly for everyone who installs it β€” with no error anywhere.
+Patching also means the next `shadcn add` either clobbers the change or silently
+skips the upgrade.
+
+When a primitive isn't enough, in order of preference: pass `className`, compose
+a wrapper in `blocks/` or `custom/`, or add a variant to the block that needs it.
+
+Editing a `ui/` file is a last resort, and only for a defect stock shadcn has
+too. `input-group.tsx` is the precedent β€” `FormControl`'s Slot injected a
+`data-slot` that clobbered the group's own, breaking the focus ring. It carries
+a comment saying why the prop order matters. Do the same, or don't touch them.
+
+## `blocks/` is a published registry, not internal code
+
+Anything you add here ends up on `openstatus.dev/r` and gets installed into
+codebases that are not this one.
+
+- **Register it.** A new file needs an entry in `registry.json` with its
+ `registryDependencies`. Forget that and it works in the monorepo and 404s for
+ consumers β€” nothing in CI catches it.
+- **No app imports.** No `next/link`, no `next-intl`, no `@openstatus/db`, no
+ tRPC. Every direct dependency becomes a mandatory install for consumers, and
+ most of them aren't even on Next.js. Routing, markdown and translation come in
+ through slot props (`renderEvent`, `renderMessage`, `asChild`) and the
+ `StatusBlocksI18nProvider` context.
+- **Imports must exist in a stock shadcn install.** `pnpm registry:build`
+ rewrites `@openstatus/ui/*` to `@/*`, so `@openstatus/ui/components/ui/button`
+ becomes `@/components/ui/button` on the consumer's machine. Importing a
+ primitive we have but they don't produces a build error there, not here.
+- **New color tokens go in `registry.json` `cssVars`.** That is how `--success`,
+ `--warning` and `--info` reach consumers; a token used only in `globals.css`
+ is undefined for them.
+- **Defaults must render unconfigured.** Slots are optional, i18n falls back to
+ English. The registry preview has no wiring.
+
+## Generated output
+
+`dist/` and `public/r/` are build artifacts of `pnpm registry:build` (which
+`apps/web`'s build runs). Both are gitignored. Never edit them, and never fix a
+registry bug by editing `dist/` β€” change `src/` and rebuild.
+
+## Imports
+
+Exports are path-based, with no barrel:
+`@openstatus/ui/components/ui/button`, `@openstatus/ui/components/blocks/status-bar`,
+`@openstatus/ui/hooks/use-media-query`. Import the exact file.
+
+Shared UI belongs here, not forked into an app β€” see `docs/adr/0003-shared-ui-comes-from-openstatus-ui.md`.
diff --git a/ralph/.gitignore b/ralph/.gitignore
deleted file mode 100644
index e93c46927..000000000
--- a/ralph/.gitignore
+++ /dev/null
@@ -1,4 +0,0 @@
-# Ignore PRD and progress files as they are specific to local development
-prd.json
-progress.txt
-
diff --git a/ralph/README.md b/ralph/README.md
deleted file mode 100644
index b54a819dd..000000000
--- a/ralph/README.md
+++ /dev/null
@@ -1,34 +0,0 @@
-Ralph is a technique for running AI coding agents in a loop. Our approach is taken from Matt Pocock's [Getting Started with Ralph](https://www.aihero.dev/getting-started-with-ralph) writeup. Make sure to have everything installed.
-
-The `prd.json` file is an array of object with the following format:
-
-```
-{
- "category": "functional",
- "description": "When a user is on wrong dashboard /status-pages/[id] redirect him to /status-pages",
- "steps": [
- "Redirect user no access for page id",
- "Avoid throwing an error",
- ],
- "passes": false
-}
-```
-
-- category: "functional" | "ui" or other categories
-- description: define what you are building
-- steps: break the task down into multiple smaller steps
-- passes: determines whether or not all defined steps and tests have succeed or not and makes it easier to track progress
-
-The `progress.txt` file simply keeps track of the changes and implementation decisions.
-
-You can run Ralph with a human-in-the-loop by running:
-
-```
-./ralph-once.sh
-```
-
-Or in AFK mode within the sandbox environment by specifying the iteration number with:
-
-```
-./afk-raph.sh 10
-```
\ No newline at end of file
diff --git a/ralph/afk-ralph.sh b/ralph/afk-ralph.sh
deleted file mode 100755
index e56b7116b..000000000
--- a/ralph/afk-ralph.sh
+++ /dev/null
@@ -1,25 +0,0 @@
-#!/bin/bash
-set -e
-
-if [ -z "$1" ]; then
- echo "Usage: $0 <iterations>"
- exit 1
-fi
-
-for ((i=1; i<=$1; i++)); do
- result=$(docker sandbox run claude --permission-mode acceptEdits -p "@prd.json @progress.txt \
- 1. Find the highest-priority task and implement it. \
- 2. Run your tests and type checks. \
- 3. Update the PRD with what was done. \
- 4. Append your progress to progress.txt. \
- 5. Commit your changes. \
- ONLY WORK ON A SINGLE TASK. \
- If the PRD is complete, output <promise>COMPLETE</promise>.")
-
- echo "$result"
-
- if [[ "$result" == *"<promise>COMPLETE</promise>"* ]]; then
- echo "PRD complete after $i iterations."
- exit 0
- fi
-done
\ No newline at end of file
diff --git a/ralph/ralph-once.sh b/ralph/ralph-once.sh
deleted file mode 100755
index e157ae0e2..000000000
--- a/ralph/ralph-once.sh
+++ /dev/null
@@ -1,8 +0,0 @@
-#!/bin/bash
-
-claude --permission-mode acceptEdits "@prd.json @progress.txt \
-1. Read the PRD and progress file. \
-2. Find the next incomplete task and implement it. \
-3. Commit your changes. \
-4. Update progress.txt with what you did. \
-ONLY DO ONE TASK AT A TIME."
\ No newline at end of file
diff --git a/scripts/check-doc-refs.mts b/scripts/check-doc-refs.mts
new file mode 100644
index 000000000..d0c4cc77a
--- /dev/null
+++ b/scripts/check-doc-refs.mts
@@ -0,0 +1,133 @@
+/**
+ * Fails when a cited path no longer exists: `docs/…` references anywhere in the
+ * repo, and backticked repo paths inside any `AGENTS.md`.
+ *
+ * Paths only β€” resolving symbols would need a parser and is out of proportion.
+ * Runs on node's native type stripping, so it needs no build step.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const SCANNED_EXTENSIONS = new Set([
+ "ts",
+ "tsx",
+ "js",
+ "jsx",
+ "mjs",
+ "cjs",
+ "md",
+ "mdx",
+ "go",
+ "yml",
+ "yaml",
+ "json",
+ "jsonc",
+ "sh",
+ "toml",
+ "sql",
+]);
+
+// A backticked token in AGENTS.md counts as a repo path only if it starts with
+// one of these. Keeps `@openstatus/db`, `node:fs` and `hono/jsx` out.
+const REPO_PATH_PREFIXES = [
+ "apps/",
+ "packages/",
+ "docs/",
+ "infra/",
+ "utils/",
+ "scripts/",
+ ".github/",
+ ".claude/",
+];
+
+// Brackets are in the class so Next.js route segments (`docs/[slug].md`) match.
+const DOCS_REFERENCE = /(?<![\w./@-])docs\/[\w./[\]-]+/g;
+const BACKTICKED = /`([^`\n]+)`/g;
+// Extension required, so docs-site slugs (`docs/concept/page-1`) are not read
+// as repo paths.
+const FILE_LIKE = /\.[a-z0-9]+$/i;
+
+type Violation = { file: string; line: number; path: string };
+
+function trackedFiles(): string[] {
+ return execFileSync("git", ["ls-files", "-z"], {
+ cwd: REPO_ROOT,
+ encoding: "utf8",
+ maxBuffer: 64 * 1024 * 1024,
+ })
+ .split("\0")
+ .filter((file) => file.length > 0);
+}
+
+/**
+ * Strips sentence punctuation and a `:42` line suffix a citation may carry.
+ * `]` is left alone β€” Next.js route segments legitimately end with it.
+ */
+function normalize(candidate: string): string {
+ return candidate.replace(/[.,;:)]+$/, "").replace(/:\d+$/, "");
+}
+
+function isRepoPath(candidate: string): boolean {
+ // `*`, `<…>` and `…` mark a pattern or placeholder, not a real path.
+ if (/[*<>…\s]/.test(candidate)) return false;
+ return REPO_PATH_PREFIXES.some((prefix) => candidate.startsWith(prefix));
+}
+
+function collect(file: string, contents: string): Violation[] {
+ const violations: Violation[] = [];
+ const isAgentsFile = file === "AGENTS.md" || file.endsWith("/AGENTS.md");
+
+ contents.split("\n").forEach((text, index) => {
+ const candidates = new Set<string>();
+
+ for (const match of text.matchAll(DOCS_REFERENCE)) {
+ const candidate = normalize(match[0]);
+ if (FILE_LIKE.test(candidate)) candidates.add(candidate);
+ }
+
+ if (isAgentsFile) {
+ for (const match of text.matchAll(BACKTICKED)) {
+ const candidate = normalize(match[1] ?? "");
+ if (isRepoPath(candidate)) candidates.add(candidate);
+ }
+ }
+
+ for (const candidate of candidates) {
+ if (!existsSync(join(REPO_ROOT, candidate))) {
+ violations.push({ file, line: index + 1, path: candidate });
+ }
+ }
+ });
+
+ return violations;
+}
+
+const files = trackedFiles();
+const violations: Violation[] = [];
+
+for (const file of files) {
+ const extension = file.split(".").pop()?.toLowerCase() ?? "";
+ if (!SCANNED_EXTENSIONS.has(extension)) continue;
+
+ violations.push(
+ ...collect(file, readFileSync(join(REPO_ROOT, file), "utf8")),
+ );
+}
+
+if (violations.length > 0) {
+ console.error(`Dangling path references (${violations.length}):\n`);
+ for (const { file, line, path } of violations) {
+ console.error(` ${file}:${line} β†’ ${path}`);
+ }
+ console.error(
+ "\nEvery `docs/…` citation and every backticked repo path in an AGENTS.md must resolve.",
+ );
+ process.exit(1);
+}
+
+console.log(`No dangling path references (${files.length} tracked files).`);
diff --git a/scripts/oxlint-plugin-openstatus.js b/scripts/oxlint-plugin-openstatus.js
new file mode 100644
index 000000000..6c302454a
--- /dev/null
+++ b/scripts/oxlint-plugin-openstatus.js
@@ -0,0 +1,175 @@
+/**
+ * Custom oxlint rules for openstatus.
+ *
+ * `services-mutation-guards` keys off behaviour, not filename: a top-level
+ * function that opens a transaction is a mutation, and every mutation must
+ * check the actor's scope and leave an audit row.
+ *
+ * It matches call names, not the call graph. `emitAudit` therefore counts from
+ * anywhere in the verb (it belongs inside the `withTransaction` callback), which
+ * a nested helper that never runs could satisfy. `requireScope` must appear in
+ * the verb body itself, which is where the convention puts it. A guard, not a
+ * proof β€” the audit tests are what actually pin the behaviour.
+ */
+
+const FUNCTION_TYPES = [
+ "FunctionDeclaration",
+ "FunctionExpression",
+ "ArrowFunctionExpression",
+];
+
+function calleeName(node) {
+ const callee = node.callee;
+ if (!callee) return null;
+ if (callee.type === "Identifier") return callee.name;
+ // `foo.bar()` β€” only the property matters here.
+ if (
+ callee.type === "MemberExpression" &&
+ callee.property?.type === "Identifier"
+ ) {
+ return callee.property.name;
+ }
+ return null;
+}
+
+/** Arrows and function expressions have no `id`; fall back to the const they're assigned to. */
+function functionName(node, assignedName) {
+ if (node.id?.type === "Identifier") return node.id.name;
+ return assignedName ?? "<anonymous>";
+}
+
+const servicesMutationGuards = {
+ meta: {
+ type: "problem",
+ docs: {
+ description:
+ "A services function that calls withTransaction must also call requireScope and emitAudit.",
+ },
+ messages: {
+ missing:
+ "`{{name}}` opens a transaction but never calls {{missing}}. Every mutation in @openstatus/services must check the actor's scope and emit an audit row β€” see packages/services/AGENTS.md. If this verb genuinely needs neither, disable this rule inline with the reason above it.",
+ },
+ },
+ create(context) {
+ let depth = 0;
+ let outermost = null;
+ let outermostName = null;
+ let pendingName = null;
+ // Anywhere in the verb, so a `withTransaction` callback's `emitAudit` counts.
+ const calls = new Set();
+ // The verb's own body, where `requireScope` belongs.
+ const bodyCalls = new Set();
+
+ function enter(node) {
+ if (depth === 0) {
+ outermost = node;
+ outermostName = functionName(node, pendingName);
+ calls.clear();
+ bodyCalls.clear();
+ }
+ depth += 1;
+ }
+
+ function exit() {
+ depth -= 1;
+ if (depth !== 0 || outermost === null) return;
+
+ if (calls.has("withTransaction")) {
+ const missing = [];
+ if (!bodyCalls.has("requireScope")) missing.push("requireScope");
+ if (!calls.has("emitAudit")) missing.push("emitAudit");
+
+ if (missing.length > 0) {
+ context.report({
+ node: outermost,
+ messageId: "missing",
+ data: {
+ name: outermostName,
+ missing: missing.map((name) => `\`${name}\``).join(" or "),
+ },
+ });
+ }
+ }
+ outermost = null;
+ outermostName = null;
+ pendingName = null;
+ }
+
+ const visitor = {
+ VariableDeclarator(node) {
+ if (depth === 0 && node.id?.type === "Identifier") {
+ pendingName = node.id.name;
+ }
+ },
+ CallExpression(node) {
+ const name = calleeName(node);
+ if (!name) return;
+ calls.add(name);
+ if (depth === 1) bodyCalls.add(name);
+ },
+ };
+ for (const type of FUNCTION_TYPES) {
+ visitor[type] = enter;
+ visitor[`${type}:exit`] = exit;
+ }
+ return visitor;
+ },
+};
+
+const DB_SCHEMA_BARREL = "@openstatus/db/src/schema";
+
+/**
+ * `"use client"` is a per-file directive, not a path convention, so this cannot
+ * be expressed as a `no-restricted-imports` override keyed on globs.
+ */
+const noDbBarrelInClient = {
+ meta: {
+ type: "problem",
+ docs: {
+ description:
+ 'A "use client" file must not value-import the db schema barrel.',
+ },
+ messages: {
+ barrel:
+ 'A "use client" file must not value-import `{{source}}` β€” it pulls drizzle and the whole schema graph into the browser bundle. Import the specific sub-path (e.g. `@openstatus/db/src/schema/monitors/constants`), or split the pure-zod part into a sibling file. `import type` is fine.',
+ },
+ },
+ create(context) {
+ let isClientFile = false;
+
+ return {
+ Program(node) {
+ isClientFile = node.body.some(
+ (statement) =>
+ statement.type === "ExpressionStatement" &&
+ statement.expression?.type === "Literal" &&
+ statement.expression.value === "use client",
+ );
+ },
+ ImportDeclaration(node) {
+ if (!isClientFile) return;
+ if (node.source?.value !== DB_SCHEMA_BARREL) return;
+ if (node.importKind === "type") return;
+ // `import { type Foo }` on every specifier erases too.
+ const hasValueSpecifier = node.specifiers.some(
+ (specifier) => specifier.importKind !== "type",
+ );
+ if (!hasValueSpecifier) return;
+
+ context.report({
+ node,
+ messageId: "barrel",
+ data: { source: DB_SCHEMA_BARREL },
+ });
+ },
+ };
+ },
+};
+
+export default {
+ meta: { name: "openstatus" },
+ rules: {
+ "services-mutation-guards": servicesMutationGuards,
+ "no-db-barrel-in-client": noDbBarrelInClient,
+ },
+};