@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/docs/dev/plugins/starters.md

@@ -0,0 +1,70 @@
+---
+title: Starters
+description: Wizards a plugin brings as templates – how to register one, where it shows, and what a wizard made from it gets.
+version: 0.5.0
+---
+
+A starter is a wizard a plugin brings as a template. For the tenants that have the plugin, it
+stands beside the marketplace’s templates wherever a wizard is made.
+
+```ts
+import { readFileSync } from "node:fs";
+
+const read = (path: string) => readFileSync(wizards.resolvePath(path), "utf8");
+
+server.registerStarter({
+  id: "follow-up",
+  title: "Follow up a contact",
+  description: "Looks the person up and drafts a follow-up email.",
+  language: "en",
+  definition: JSON.parse(read("starters/follow-up.json")),
+  files: { "widget/card.html": read("starters/card.html") },
+});
+```
+
+| Field | |
+|---|---|
+| `id` | Lower case, digits and `-`, starting with a letter, at most 40 characters. Unique in the plugin |
+| `title` | What the list of templates calls it |
+| `description` | What it makes, in one or two sentences. Shown under the title |
+| `language` | `"de"` or `"en"`, the language its texts are in. Default: `"en"` |
+| `definition` | A complete wizard definition: the JSON the studio keeps and `get_authoring_guide` describes |
+| `files` | Files of the wizard’s workspace by path: widgets, sample data. A string is written as UTF-8, a `Uint8Array` as it is |
+
+## Checked when it is registered
+
+The definition is read as a wizard when `registerStarter` is called. A starter that is not a
+valid wizard, an id that is not allowed and an id registered twice all throw, and the plugin does
+not load. The error names the starter:
+
+```
+Starter "follow-up": steps.2.fields: …
+```
+
+## Where it shows
+
+The starter is known as `<plugin id>.<starter id>`: `contacts.follow-up`. A marketplace entry’s id
+has no dot, so the two never clash.
+
+| Where | |
+|---|---|
+| New wizard in the studio | First among the gallery’s templates, and under “Similar wizards” when the wish someone types comes close to it. Its card shows the plugin’s name. It cannot be starred: it is always there, also without a connection |
+| `GET /api/studio/marketplace` | First on the first page, with `plugin: { id, name }` |
+| MCP `list_starters`, `get_starter`, `create_wizard` | Listed first with `plugin`; `starterId` takes its id |
+| `GET /api/v1/templates`, for programs with a key | First, with `plugin`; `POST /api/v1/wizards` takes its id as `starterId` |
+
+Only the tenants that have the plugin see it, by the same rule as its tools
+([Which tenant has a plugin](./shipping.md#which-tenant-has-a-plugin)). A search finds it by its
+title, its description and the plugin’s name.
+
+A marketplace entry can stand for a plugin’s starter. Where the tenant has that plugin, the
+entry is left out and the plugin’s own starter is listed. Where it doesn’t, the entry is marked
+Pro with the plugins it needs, and a wizard cannot be made from it.
+
+## A wizard made from it
+
+- gets a copy of the definition and the files. Later changes to the starter do not reach it.
+- keeps the starter’s id in `starter`. `starterRevision` stays empty: the starter changes with
+  the plugin’s version, not with a revision of its own.
+- is written in the starter’s `language`, whatever language the person asked for.
+- is not counted at the marketplace.

package/apps/runtime/dist/docs/dev/plugins/studio.md

@@ -0,0 +1,363 @@
+---
+title: The studio half
+description: Pages, icons in the app bar, sections of the settings and of the space page – written in React, built once, drawn inside the studio.
+version: 0.5.0
+---
+
+The studio half is `ui/plugin.tsx`. Its default export is a function; the studio calls it after
+sign-in and hands it `studio`. What the plugin draws is part of the studio: the same React, the
+same router, the same components.
+
+```tsx
+import { defineStudioPlugin } from "@engenty/wizards/plugin/studio";
+import { Button, Card, Empty, Spinner } from "@engenty-wizards/web/ui";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Users } from "lucide-react";
+
+interface Person {
+  id: number;
+  email: string;
+  name: string | null;
+  wizard: string;
+}
+
+const messages = {
+  de: {
+    title: "Kontakte",
+    hint: "Wer einen Wizard bis zum Ende durchlaufen hat.",
+    empty: "Noch keine Kontakte.",
+    remove: "Entfernen",
+  },
+  en: {
+    title: "Contacts",
+    hint: "Everyone who ran a wizard to its end.",
+    empty: "No contacts yet.",
+    remove: "Remove",
+  },
+};
+
+export default defineStudioPlugin((studio) => {
+  const t = studio.i18n.register(messages);
+
+  function ContactsPage() {
+    const list = useQuery({
+      queryKey: ["contacts"],
+      queryFn: () => studio.api.get<{ contacts: Person[] }>("/"),
+    });
+    const cache = useQueryClient();
+    const remove = useMutation({
+      mutationFn: (id: number) => studio.api.del(`/${id}`),
+      onSuccess: () => cache.invalidateQueries({ queryKey: ["contacts"] }),
+    });
+    const admin = studio.me().tenant.role !== "member";
+    return (
+      <div>
+        <h1 className="font-display font-semibold text-[1.75rem] tracking-tight">{t("title")}</h1>
+        <p className="mt-1 text-[0.9375rem] text-ink-3">{t("hint")}</p>
+        <div className="mt-8 flex flex-col gap-2">
+          {list.isLoading ? <Spinner className="mx-auto" /> : null}
+          {list.data && !list.data.contacts.length ? <Empty>{t("empty")}</Empty> : null}
+          {list.data?.contacts.map((person) => (
+            <Card key={person.id} className="flex items-center gap-3 px-5 py-3.5">
+              <span className="min-w-0 flex-1 truncate font-medium text-[0.9375rem]">
+                {person.name ?? person.email}
+              </span>
+              <span className="text-[0.8125rem] text-ink-3 max-sm:hidden">{person.wizard}</span>
+              {admin ? (
+                <Button variant="ghost" size="sm" onClick={() => remove.mutate(person.id)}>
+                  {t("remove")}
+                </Button>
+              ) : null}
+            </Card>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  studio.registerPage({ path: "/contacts", component: ContactsPage });
+  studio.registerNav({ to: "/contacts", label: () => t("title"), icon: Users });
+});
+```
+
+## What it registers
+
+| Call | Adds |
+|---|---|
+| `studio.registerPage({ path, component, wide? })` | A page of the studio at `/studio<path>`, inside the studio’s frame. `path` takes `:name` parts. `wide`: the page lays out its own columns and takes the screen’s width |
+| `studio.registerNav({ to, label, icon })` | An icon in the app bar that opens a page |
+| `studio.registerSettingsSection({ id, label, icon, component, menu? })` | A section of the settings at `/studio/settings/<id>`. `menu`: the user menu links to it directly |
+| `studio.registerSpaceSection({ id, group?, label, hint?, component })` | A section of a part of the space page at `/studio/space/<group>#<id>`, below the part’s own. See [The space](#the-space) |
+| `studio.registerSpacePart({ id, label, icon, after?, component })` | A part of the space page of the plugin’s own, at `/studio/space/<id>`. See [A part of the plugin’s own](#a-part-of-the-plugins-own) |
+| `studio.registerShareSection({ runner, component })` | A runner’s own settings for a wizard (a keyword), under the share dialog’s gear once the runner is on and set up. See [Runners](./runners.md#the-runners-part-of-the-share-dialog) |
+| `studio.registerShareSetup({ runner, title, component, notice? })` | What “Set up” in the runner’s row opens: a view inside the share dialog, with its buttons at the dialog’s foot, and a banner of the runner’s news. See [Runners](./runners.md#setting-up-inside-the-dialog) |
+| `studio.registerAssistantCard({ tool, component })` | A card in the assistant’s chat for what a tool of the server half returned. See [The space](./space.md#a-card-in-the-chat) |
+
+- The studio’s own addresses are taken: `/new`, `/edit`, `/settings`, `/space`, `/setup`,
+  `/sign-in`.
+- The settings’ own sections are taken as ids: `account`, `team`, `connectors`, `models`,
+  `integrate` and `plugins`.
+- `label` is a function, since the language can change while the studio is open.
+- `icon` is a component that takes `className`: any icon of `lucide-react`.
+
+A settings section draws its own heading and cards:
+
+```tsx
+function ContactsSettings() {
+  return (
+    <section className="flex flex-col gap-2.5">
+      <h2 className="px-1 font-display font-semibold text-lg leading-tight">{t("title")}</h2>
+      <Card className="p-5 text-[0.875rem] text-ink-2">…</Card>
+    </section>
+  );
+}
+
+studio.registerSettingsSection({
+  id: "contacts",
+  label: () => t("title"),
+  icon: Users,
+  component: ContactsSettings,
+});
+```
+
+## The space
+
+A space holds what all its wizards share: a title, logos, colours, facts and Knowledge. The
+space page, behind the house icon (Space) in the app bar, shows them in four parts:
+
+| Part | `group` | Holds |
+|---|---|---|
+| Info & brand | `info` | Basics, Facts, Logos, Colours, Brand assets |
+| Knowledge | `knowledge` | Documents, pages, tables and files with their categories: what every AI step looks things up in |
+| Data | `data` | What the wizards keep |
+| Results | `results` | The runs that reached their result |
+
+A plugin adds a section to one of them, below the part’s own:
+
+```tsx
+function ContactsOfSpace() {
+  const space = studio.useSpace();
+  const list = useQuery({
+    queryKey: ["contacts", space?.id],
+    queryFn: () => studio.api.get<{ contacts: Person[] }>(`/?space=${space?.id}`),
+    enabled: Boolean(space),
+  });
+  return <Card className="p-5 text-[0.875rem] text-ink-2">…</Card>;
+}
+
+studio.registerSpaceSection({
+  id: "contacts",
+  group: "data",
+  label: () => t("title"),
+  hint: () => t("hint"),
+  component: ContactsOfSpace,
+});
+```
+
+- `group` is the part; without one the section stands under Knowledge.
+- The studio draws the heading and the hint above the section, as it does for the space’s own,
+  and lists the section in the part’s menu under the plugin’s name. The component draws the
+  rest, usually a `Card`.
+- `id` is the section’s anchor: `/studio/space/data#contacts` opens the page there, and so does
+  `/studio/space#contacts`. In Knowledge a section is a page of its own:
+  `/studio/space/knowledge?show=s:<id>`, where `#<id>` leads too. Ids are unique on the whole
+  page; the space’s own are taken: `base`, `facts`, `logos`, `colors`, `typography`, `assets`,
+  `documents`.
+- `studio.useSpace()` is a hook: `{ id, name, readOnly, brand }`, or `null` while there is none.
+  A component that calls it draws again when the person picks another space, or changes its
+  brand. `readOnly`: the space is edited in engenty wizards on a computer and only shown here,
+  or nothing is built on this runtime. Show it, but change nothing. `brand` is what Info & brand
+  holds of the look: `name`, `colors` (`{ name, value }`, the first is the accent) and `fonts`
+  (`{ family, role, weights }`).
+- Every wizard belongs to a space: a [run event](./events.md) names it as
+  `wizard.projectId`. Keep it with what the plugin stores to show a space’s part of it.
+
+### A part of the plugin’s own
+
+A plugin whose subject is as big as one of the parts adds a part of its own: an entry in the
+parts’ menu, with a page at `/studio/space/<id>` that the plugin draws whole. The part’s menu
+lists what the page holds; `studio.useSpaceMenu` fills it while the page is drawn.
+
+```tsx
+function Library() {
+  const space = studio.useSpace();
+  const sections = useSections(space?.id);
+  studio.useSpaceMenu(sections.map((s) => ({ id: s.id, label: s.title, icon: Component })));
+  return sections.map((s) => (
+    <Anchor key={s.id} id={s.id}>
+      <Section title={s.title}>…</Section>
+    </Anchor>
+  ));
+}
+
+studio.registerSpacePart({
+  id: "library",
+  label: () => t("title"),
+  icon: Blocks,
+  after: "info",
+  component: Library,
+});
+```
+
+- `id` is the address: `/studio/space/library`. The parts’ own (`info`, `knowledge`, `data`,
+  `results`) are taken.
+- `after` is the part it follows in the menu: `info`, `knowledge` or `data` (default).
+- Each entry of `useSpaceMenu` jumps to the element with its `id` in what the part draws, and
+  the menu marks the one in view. `Anchor` and `Section` draw them as the space’s own parts do.
+- The component is drawn again for another space: keep the space’s data under its id.
+
+## Words in two languages
+
+The studio speaks German and English. `studio.i18n.register` takes the plugin’s words and gives
+the function that reads them in the language in effect:
+
+```ts
+const t = studio.i18n.register({
+  de: { count: "{n} Kontakte sind gespeichert." },
+  en: { count: "{n} contacts are kept." },
+});
+
+t("count", { n: 12 });
+```
+
+- `de` is the source: a key missing in `en` shows the German, so give every key in both.
+- `{name}` in a text is filled from the second argument.
+- `studio.i18n.lang()` is `"de"` or `"en"`, for dates and numbers:
+  `new Date(at).toLocaleString(studio.i18n.lang())`.
+
+## The plugin’s own routes
+
+`studio.api` calls the routes the server half registered, signed in as the person:
+
+| Call | Asks |
+|---|---|
+| `studio.api.get<T>(path)` | `GET /api/studio/plugins/<id><path>` |
+| `studio.api.post<T>(path, body?)` | `POST`, the body as JSON |
+| `studio.api.put<T>(path, body?)`, `studio.api.patch<T>(path, body?)` | `PUT`, `PATCH` |
+| `studio.api.del<T>(path)` | `DELETE` |
+
+Each gives the parsed JSON. Use them with `useQuery` and `useMutation`, as the page above does.
+
+## The person
+
+`studio.me()` is the signed-in person:
+
+| | |
+|---|---|
+| `user` | `{ id, name, email }` |
+| `tenant` | `{ id, role }`, the role `owner`, `admin` or `member` |
+| `mode` | `"local"`: the runtime runs alone. `"managed"`: on engenty.ai |
+
+Hide what a member may not do, and guard it on the server too with `role: "admin"` on the
+route.
+
+`studio.plugin` is the plugin itself: `{ id, name, version }`.
+
+## Where the page stands
+
+The top bar shows a trail after the space’s name. `studio.useCrumbs` is a hook that sets it
+while the page is shown, in place of a heading of the page’s own:
+
+```tsx
+studio.useCrumbs([{ label: t("title"), to: "/contacts" }, { label: person.name ?? person.email }]);
+```
+
+- Each step is `{ label, to? }`; the last one is the page itself. A phone does not show the trail.
+- The assistant names the page by its trail.
+
+## A page with a menu
+
+A page with parts of its own puts its menu where the studio’s own pages put theirs. `MenuPage`
+from `@engenty-wizards/web/ui` draws the menu in the studio’s sidebar while that is open, and at
+the page’s left otherwise, so there is only ever one menu at the left. `PageMenu` draws the menu
+as the settings do: a list with one level below it, and tabs on a phone.
+
+```tsx
+import { MenuPage, PageMenu } from "@engenty-wizards/web/ui";
+import { useParams } from "react-router";
+
+function ContactsPage() {
+  const { tab = "all" } = useParams();
+  return (
+    <MenuPage
+      menu={
+        <PageMenu
+          title={t("title")}
+          current={tab}
+          entries={[
+            { id: "all", label: t("all"), to: "/contacts/all" },
+            { id: "new", label: t("new"), to: "/contacts/new" },
+          ]}
+        />
+      }
+    >
+      <ContactList tab={tab} />
+    </MenuPage>
+  );
+}
+```
+
+- An entry is `{ id, label, icon?, to, entries? }`; `entries` is the level below.
+- `current` is the id of the entry shown, at either level.
+
+## The assistant
+
+The studio’s assistant stands on a plugin’s pages too. `studio.Assistant`,
+`studio.useAssistantPage` and `studio.useAssistantTool` tell it what to say there, what the page
+shows and what it may do in it. See [The space](./space.md#the-assistant-on-the-plugins-own-page).
+
+For now the studio shows its assistant only where it is switched on, and it is off by default.
+While it is off, these calls do no harm and nobody sees what they say.
+
+## Build it
+
+The studio half is built to two files, `dist/client.js` and `dist/client.css`. The build needs
+a checkout of the repository, since it uses the studio’s own tools:
+
+```bash
+node scripts/build-plugin.mjs <plugin folder>
+```
+
+```bash
+node scripts/build-plugin.mjs <plugin folder> --watch
+```
+
+The plugin’s folder may be anywhere, also outside the checkout. With `--watch` the files are
+built again on every save, and an open studio takes them in place.
+
+Ship `dist/` with the plugin: an install without a checkout cannot build it.
+
+## What the studio shares
+
+These imports are not in `client.js`. The script takes them from the studio that loads it, so
+there is one React and one router on the page:
+
+| Import | What a plugin gets of it |
+|---|---|
+| `react`, `react/jsx-runtime` | All of it |
+| `react-dom` | `createPortal`, `flushSync` |
+| `react-router` | `Link`, `NavLink`, `Navigate`, `useNavigate`, `useParams`, `useLocation`, `useSearchParams` |
+| `@tanstack/react-query` | `useQuery`, `useMutation`, `useQueryClient` |
+| `@engenty-wizards/web/ui` | The studio’s components, see [Styles and components](./styling.md) |
+| `@engenty/wizards/plugin/studio` | `defineStudioPlugin` and the types |
+
+Everything else a plugin imports is bundled into `client.js`. A package the plugin’s folder
+does not have, such as `lucide-react`, comes from the studio’s.
+
+## Undo on reload
+
+The studio half loads again when its built files change. Pages, icons and sections, also those
+of the space page, are taken back for it. Anything else it started, it undoes itself:
+
+```ts
+const timer = setInterval(refresh, 30_000);
+studio.onUnload(() => clearInterval(timer));
+```
+
+## When it fails
+
+- A studio half that throws while it loads registers nothing. Settings → Plugins says “The
+  studio part didn’t load. Check the plugin and reload” with the reason. The server half keeps
+  working.
+- A page or section that throws while it draws shows “This part of a plugin crashed.” in its
+  place. The rest of the studio stays up.

package/apps/runtime/dist/docs/dev/plugins/styling.md

@@ -0,0 +1,129 @@
+---
+title: Styles and components
+description: The studio's components, Tailwind against the studio's theme, and why a plugin's styles never leak.
+version: 0.5.0
+---
+
+A plugin’s page should look like the studio. Two things make that easy: the studio’s components
+and its theme.
+
+## Components
+
+`@engenty-wizards/web/ui` is what the studio itself is drawn with:
+
+| Component | For | Props beside the element’s own |
+|---|---|---|
+| `Button` | An action | `variant`: `primary` (default), `secondary`, `ghost`, `quiet`, `danger` · `size`: `sm`, `md`, `lg` · `busy` |
+| `IconButton` | An action that is only an icon | `label`: its name for screen readers and the tooltip |
+| `Input`, `Textarea` | Text. The textarea grows with its content | `minRows`, `maxRows` on the textarea |
+| `Select` | One of a list | `value`, `onChange(value)`, `options: { value, label, disabled? }[]`, `placeholder` |
+| `Segmented` | One or several of a few | `value`, `onChange`, `options: string[]`, `multi`, `disabled` (options shown but not to be picked) |
+| `Tabs` | A row of tabs; the panels are yours | `value`, `onChange`, `options: { id, label }[]`, `label` (for screen readers) |
+| `Switch` | On or off | `checked`, `onChange(checked)`, `label`, `disabled` |
+| `Swatch` | A colour | The native colour input’s |
+| `Label` | A field’s label | `hint`, `required` |
+| `Card` | A surface | |
+| `Chip` | A state in a word | `tone`: `neutral` (default), `live`, `warn`, `ember` · `icon` (in place of the live dot) · `title` (on hover) |
+| `DatePicker` | A date from a month | `value` (“YYYY-MM-DD” or “”), `onChange`, `min`, `max`, `clearable` |
+| `DateRangePicker` | A day or a period in one month: the first click is the start, the second the end | `from`, `to`, `onChange({ from, to })`, `min`, `max` |
+| `TimePicker` | A time of day from an hour and a minute column; arrow keys on the field move it by `step` | `value` (“HH:MM” or “”), `onChange`, `step` (minutes, default 5), `compact` (narrow, no clock) |
+| `PageMenu` | A page’s own menu: a list at the side with one level below that slides in, tabs on a phone | `title`, `entries` ({ id, label, icon?, to, entries? }), `current`, `footer` |
+| `MenuPage` | A page with a menu of its own: the menu stands at the page’s left, or in the studio’s sidebar while that is open, so there is only ever one menu at the left | `menu` (a `PageMenu`, or any), `children` (the page) |
+| `Composer` | The field a message is written in: text, dictation, files, send | `onSend(text, files)` (false keeps the draft), `placeholder`, `disabled`, `attach`, `floating` |
+| `Dialog` | A modal; on a phone it fills the screen | `open`, `onClose`, `title`, `wide` (`true`, or `"page"` for a document), `height="tall"` (for tabs, folds or lists: its height does not jump), `bare` (the children are the panel) |
+| `Spinner`, `Empty` | Loading, and nothing there yet | |
+| `LinkedText` | A sentence with its web addresses as links, named by their host | `text` |
+| `QrCode` | A QR code of a text, such as a link or a `tel:` number, as the share dialog draws it | `text`, `label` (for screen readers) |
+| `cn(...)` | Joins class names, skipping what is false | |
+| `dateText(date, withWeekday?)` | A “YYYY-MM-DD” date in the studio’s language: “Wed 14 Oct 2026” | |
+| `Anchor`, `Section` | A section of the space page and the spot the menu jumps to: the heading and its hint above the card | `id` on the anchor · `title`, `hint`, `save` (how the last save went), `action` (beside the heading), `plain` (the content draws its own cards) |
+| `InlineText` | Text edited where it stands, without a field’s frame | `value`, `onChange`, `placeholder`, `label`, `maxLength`, `fit` (as wide as its text) |
+| `AddMenu` | The “Add” menu of a section’s heading | `entries: { label, icon, onPick }[]` |
+| `AddRow` | A quiet “+ …” row at the end of a list | `label`, `onClick` |
+| `RuleRows`, `useRuleRows(saved)` | Rules as rows, each with its sign (bullet, do, don’t, to check, important, numbered) | `rules` (what the hook gives), `placeholder`, `readOnly` |
+| `useAutosave(value, save)` | Saves a value a moment after it last changed; gives the state for a section’s `save` | |
+| `newId()` | A short id for something new | |
+
+```tsx
+import { Button, Card, Chip, Label, Input } from "@engenty-wizards/web/ui";
+
+<Card className="flex flex-col gap-4 p-5">
+  <Label hint="Where the message goes.">Address</Label>
+  <Input value={url} onChange={(e) => setUrl(e.target.value)} />
+  <div className="flex items-center gap-3">
+    <Button busy={save.isPending} onClick={() => save.mutate()}>Save</Button>
+    <Chip tone="live">connected</Chip>
+  </div>
+</Card>
+```
+
+Icons are from `lucide-react`.
+
+Most of these components live in the runner package (`@engenty-wizards/runner`), so a wizard’s
+run page looks like the studio. Import them from `@engenty-wizards/web/ui` all the same: that is
+the import the studio shares. `@engenty-wizards/runner` is not shared, so the build would bundle
+it into `client.js`.
+
+## Tailwind
+
+A plugin writes Tailwind classes, as the studio does. The build collects the classes the
+plugin’s files use into `dist/client.css`.
+
+The theme’s names are the studio’s:
+
+| | Names |
+|---|---|
+| Surfaces | `bg-paper`, `bg-paper-2`, `bg-paper-3`, `bg-card`, `bg-popover`, `bg-accent` |
+| Text | `text-ink`, `text-ink-2`, `text-ink-3`, `text-ink-4` |
+| Lines | `border-border`, `border-border-soft`, `ring-border-soft` |
+| The accent | `ember`, `ember-strong`, `ember-tint`; `primary`, `primary-foreground` |
+| States | `moss` and `moss-tint` (good), `amber` and `amber-tint` (attention), `rose` and `rose-tint` (danger), `cobalt` and `cobalt-tint` (information) |
+| Type | `font-sans`, `font-display` (headings), `font-mono` |
+| Corners | `rounded-sm` to `rounded-3xl`, from the theme’s radius |
+| Shadows | `shadow-soft`, `shadow-elevated`, `shadow-overlay` |
+| Variants | `dark:` and `coarse:` (a finger, not a mouse) beside Tailwind’s own |
+
+The full list is
+[packages/runner/src/theme.css](https://github.com/engenty/wizards/blob/main/packages/runner/src/theme.css):
+the studio and a wizard’s run page share it.
+
+## Rules
+
+- **Colours come from the names.** The dark theme is derived from the theme’s values, not from a
+  fixed palette. A literal colour (`#1a1a1a`, `text-gray-700`) breaks in the other theme.
+- **Check both themes.** Dark is the studio’s default. The user menu and the app bar’s own menu
+  switch between light, dark and the system’s.
+- **Touch targets.** `coarse:min-h-11` gives a control the 44 px a finger needs. The studio’s
+  components do that themselves.
+- **Don’t style outside your own part.** It would not work anyway: see below.
+
+## Why a plugin’s styles never leak
+
+`client.css` is built so that it cannot change how the studio looks:
+
+- Every rule applies only inside what the plugin draws. The studio wraps each page, section,
+  part of the space page, app bar icon, part of the share dialog and assistant card of a plugin
+  in an element with `data-plugin="<id>"`, and every rule of `client.css` is nested below that.
+- The rules sit in a layer above the studio’s utilities, so inside the plugin’s part the
+  plugin’s stylesheet decides.
+- The theme is used by reference: `client.css` carries the names’ uses, none of the variables
+  and no resets.
+
+## Your own CSS
+
+A stylesheet imported in `ui/plugin.tsx` lands in `client.css` as it is:
+
+```tsx
+import "./contacts.css";
+```
+
+The build doesn’t nest it for you. Begin its class names with the plugin’s id
+(`.contacts-chart`) and use the theme’s variables for colours: `var(--ink-2)`, `var(--paper-2)`,
+`var(--ember)`.
+
+## The theme is a contract
+
+A plugin is built against the names the theme has at the time of its build. If a later release
+renames or removes a name, plugins built before break without an error: the class is simply not
+there. That is why whoever changes `theme.css` treats its names as a contract. If you build
+against a name a release added, say in your plugin’s description which release it needs.

package/apps/runtime/dist/docs/dev/plugins/tables.md

@@ -0,0 +1,104 @@
+---
+title: Tables
+description: A plugin's own tables in every tenant's database – SQL files that run once, and Drizzle to read and write.
+version: 0.5.0
+---
+
+Every tenant has a database of its own (libSQL, the SQLite dialect). The runtime makes a plugin’s
+tables in each of them, from `.sql` files the plugin brings.
+
+## 1. The table, as SQL
+
+`migrations/0001_init.sql`:
+
+```sql
+CREATE TABLE contacts_person (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT NOT NULL UNIQUE,
+  name TEXT,
+  wizard TEXT NOT NULL,
+  seen_at INTEGER NOT NULL
+);
+```
+
+Register the folder when the plugin loads:
+
+```ts
+server.registerMigrations("migrations");
+```
+
+## 2. The table, for Drizzle
+
+`src/schema.ts` describes the same table, so queries are typed:
+
+```ts
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+export const person = sqliteTable("contacts_person", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  email: text("email").notNull().unique(),
+  name: text("name"),
+  wizard: text("wizard").notNull(),
+  seenAt: integer("seen_at", { mode: "timestamp_ms" }).notNull(),
+});
+```
+
+The runtime does not read this file. It is yours: keep it in step with the SQL by hand.
+
+## 3. Read and write
+
+`server.getTenantDb()` is the database of the tenant the current request, step or event belongs
+to, as a Drizzle database:
+
+```ts
+import { desc, eq } from "drizzle-orm";
+import { person } from "./schema";
+
+const db = () => server.getTenantDb();
+
+const newest = await db().select().from(person).orderBy(desc(person.seenAt)).limit(200);
+
+await db()
+  .insert(person)
+  .values({ email, name, wizard, seenAt: new Date() })
+  .onConflictDoUpdate({ target: person.email, set: { name, wizard, seenAt: new Date() } });
+
+await db().delete(person).where(eq(person.id, id));
+```
+
+Call `getTenantDb()` inside the handler, the tool, the listener or the job. Outside of them
+there is no tenant.
+
+## How the files run
+
+| | |
+|---|---|
+| Once | Each `.sql` file runs once per tenant database. The table `plugin_migration` records which ran |
+| In order | By file name: `0001_init.sql`, `0002_note.sql` |
+| Whole or not | A file and its record go in together or not at all. A file may hold several statements |
+| When | A database gets the files when it opens. The open ones get them when the plugin loads, also when it loads again with a new file |
+| Never back | Nothing is taken back. Unloading or removing a plugin leaves its tables and rows |
+
+A file that fails is logged with the plugin’s id and the file’s name. The files after it, other
+plugins’ included, wait for that database until the file is fixed. The tenant’s database still
+opens.
+
+## Rules
+
+- **Begin table names with the plugin’s id**: `contacts_person`. All plugins and the runtime
+  share the database. A `-` in the id becomes `_`.
+- **Never change a file that ran.** It will not run again. Add a new file:
+
+  ```sql
+  ALTER TABLE contacts_person ADD COLUMN phone TEXT;
+  ```
+
+- **Do not touch the runtime’s own tables** in a migration. Their shape changes with releases.
+- **Dates** are integers in milliseconds (`mode: "timestamp_ms"`); they leave a route as ISO
+  strings.
+
+## The runtime’s own data
+
+`getTenantDb()` reaches the whole tenant database, the runtime’s tables included. They are not
+a public interface: a release can rename a column. A plugin that must know about runs listens
+to [run events](./events.md) and keeps what it needs in its own table.