Say what a Bot is doing, and in plain words what it asks to do

.claude/skills/openbot-screen-layout/SKILL.md

@@ -188,11 +188,11 @@ itself when the dialog changes something.
 
 ## Units
 
-The root is the browser's 16px, so Tailwind's spacing, sizes and widths are their documented values
-(`p-4` is 16px, `max-w-3xl` is 768px) and land on its 4px grid. Text is the exception: `styles.css`
-sets every `--text-*` to Tailwind's default times 15/16, so `text-sm` is 13.125px and body text is
-15px. That is the scale this app has always read at; do not size text in px or rem by hand to match
-the docs.
+The root is the browser's 16px, so Tailwind's spacing, sizes, widths and text sizes are their
+documented values (`p-4` is 16px, `max-w-3xl` is 768px, `text-sm` is 14px) and land on its 4px grid.
+Text used to be the exception, on a 15px scale of its own; it is not any more. Where a screen needs one
+of the named sizes, use the five `type-*` utilities in `theme.css`; do not size text in px or rem by
+hand.
 
 Even so, never hardcode a pixel constant derived from a Tailwind token, and never compute a ratio
 from one. Measure the element — `offsetWidth`, `clientWidth`, a `ResizeObserver` — and scale from what

CHANGELOG.md

@@ -155,6 +155,72 @@ again when they come back to the end or press the arrow. A rail beside a convers
 per turn: hovering one previews what was asked and answered, and choosing it goes there. Nothing
 changes for a deployment.
 
+### First run shows what OpenBot does, one step at a time
+
+- The looping intro is replaced by steps that show what OpenBot does (a browser and files of its
+  own, a team of Bots, and asking before it acts, with Ask before making changes offered right
+  there), then Check your setup, Connect your apps, Get notified, and the name step, whose Get
+  started opens the app. On a desktop each step's words sit beside a picture of it, under one line
+  saying where the person is ("Step 5 of 9") that opens the list of steps; on a phone they come one
+  at a time. A reload, browser Back and a connection's return all keep the person's place, which is
+  now saved as they go. A link on a step to another page moves on to the next step and opens that
+  page once onboarding is done.
+- Check your setup asks the new `GET /api/setup` whether Intelligence, the model key, the Bot computer,
+  more apps and Slack and Teams work, row by row. An admin, or somebody running OpenBot alone, is
+  shown the page or the variables that close a gap; everybody else only that their admin sets it up,
+  with no warning colours. An admin can reopen the same checklist afterwards in Settings → Setup, to
+  check again after setting a variable and restarting OpenBot.
+  Check again asks Intelligence and the model provider again, at most every 10 seconds. Reading the
+  checklist does the same once an answer has failed or is five minutes old, without waiting for it,
+  so the next read has the new answer. To check the Bot computer, the server sends each running
+  computer its network policy whenever it asks, and sees that it answers; it wakes none.
+- An app connected from Connect your apps comes back to that step from the app's own sign-in page,
+  whether it connected, failed or was cancelled there. A connection started from Connections or an
+  app's admin page comes back where it did before.
+
+### OpenBot has a new look
+
+- Every screen has new colours: cool neutral greys, a near-black primary button that turns light
+  in dark mode, a purple focus ring, slightly rounder corners and quicker easing. Text now follows
+  the browser's own size, so it is a little larger than before.
+- Dark mode follows the system by default. Settings → General → Appearance offers System, Light and
+  Dark, kept in this browser. Someone who had turned the old dark switch on stays dark.
+- Every Bot, and OpenBot's own mark, is an orb with eyes that blinks and follows the pointer. It
+  holds still with reduced motion.
+- Each Bot's orb takes its colour and pattern from the Bot, so two Bots in one colour still look
+  different. Violet is kept for OpenBot's own mark.
+- The sidebar takes the same look, with OpenBot's orb beside its name. A row lifts to a card under
+  the pointer and while it is open, and you can always see where the keyboard is. While a Bot is
+  working, its orb in the list shows it, and so does a still blue dot. Each conversation has a "…"
+  button with Pin and Delete, which used to be on right-click alone. ⌘K, or Ctrl+K, opens the
+  sidebar and puts you in its search box.
+- A conversation reads like a chat. A Bot's reply arrives one bubble per thought, and a bubble holding
+  a code block or a table takes the full width on a wide screen; your messages sit in a tinted bubble,
+  and three dots show a Bot thinking. A step is marked done only when it worked: one that was refused,
+  failed or declined by you is named for what it would have done ("Send your email"), and one held on
+  its approval card says it is waiting for you. Mail and calendar steps, through any app, are named
+  for what happened to yours ("Searched your email").
+- A conversation with one Bot shows that Bot's orb in its header. The orb works while the Bot does,
+  watches while you type, and smiles when an answer lands. Under the conversation's name, "Working ·
+  Searching the web" says which step the Bot is on, and "Needs you" says an approval is waiting there.
+  A run that goes on after you allow something shows as working too. The message box is a rounded
+  pill with larger buttons, and it says "Message" and the Bot's name until you type.
+- A Bot's computer opens in a wider pane beside the conversation. Its header shows the Bot's orb,
+  whose computer it is and Take control, with a dot while the conversation needs you. Under the
+  screen, every step the Bot took in its browser, approved clicks included, sits among the commands
+  it ran, newest last, marked done, waiting for you or didn't work. The pane opens by itself only
+  when it fits beside the conversation; on a narrow screen the computer button lights up instead.
+  The box for a password or a code says the value goes straight to the page and the Bot never sees
+  it.
+- When a Bot asks before acting, its card says in plain words what it will do, in which app or
+  where, to whom, and what it will send, with everything else under Details. Decline and Allow once
+  answer it, and a quieter Always allow here saves a rule for that Bot, action and place; a step
+  handed to you asks "I did it myself" or "Don't do it". The same card is in the conversation, on
+  the Bot's page and in the list of what needs you. Once you answer, it folds to how it went
+  (Allowed, Sent, Done, Declined, Didn't work) and says who decided. A request for a step that is
+  alone in its turn now shows in the conversation too, where before it waited only on the Bot's
+  page. Under the message box, every conversation says that OpenBot is AI and can make mistakes.
+
 ### Generated interfaces use A2UI 1.0
 
 With generative UI on, a Bot builds an interface from CopilotKit's standard catalog on A2UI 1.0

app/index.html

@@ -5,15 +5,27 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>OpenBot</title>
     <!-- Sets the theme before the first paint. Must stay inline and classic: `defer` or `type="module"` runs too late. -->
+    <!-- The rule in src/lib/theme.ts (parseThemePreference, then resolveTheme): the person's choice, else the system's setting. -->
     <script>
-      // localStorage throws in some privacy modes; a theme is not worth taking the app down for.
-      try {
-        const dark = window.localStorage.getItem("openbot-theme") === "dark";
+      (() => {
+        let choice = null;
+        // localStorage throws in some privacy modes; the system's setting still applies.
+        try {
+          choice = window.localStorage.getItem("openbot-appearance");
+          if (choice !== "system" && choice !== "light" && choice !== "dark")
+            choice = window.localStorage.getItem("openbot-theme") === "dark" ? "dark" : "system";
+        } catch {}
+        const dark =
+          choice === "dark" ||
+          (choice !== "light" && !!window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches);
         document.documentElement.classList.toggle("dark", dark);
         document.documentElement.style.colorScheme = dark ? "dark" : "light";
-        const skin = window.localStorage.getItem("openbot-skin");
-        if (skin && skin !== "openbot") document.documentElement.dataset.skin = skin;
-      } catch {}
+        // The person's skin, painted before the bundle loads, the same way.
+        try {
+          const skin = window.localStorage.getItem("openbot-skin");
+          if (skin && skin !== "openbot") document.documentElement.dataset.skin = skin;
+        } catch {}
+      })();
     </script>
   </head>
   <body>

app/package.json

@@ -28,7 +28,6 @@
     "@tanstack/react-router": "^1.170.27",
     "@tanstack/react-table": "^9.3.1",
     "better-auth": "^1.6.27",
-    "boring-avatars": "^2.0.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "embla-carousel-react": "^8.6.0",

app/src/components/agents/abstract-avatar.tsx

@@ -1,25 +1,35 @@
-import Avatar from "boring-avatars";
+import { BotOrb } from "@/components/agents/orb/bot-orb";
 
+/**
+ * A Bot's face: its orb, with the look its seed picks. The seed is the Bot's id unless a tenant
+ * package set one or the Bot was copied from another, so `ChannelAvatar`, which goes by id, matches it
+ * for every other Bot.
+ * The orb hides itself from assistive tech, so the Bot is announced once, by name. Beside a heading
+ * that already names the Bot, pass `decorative` and the face is hidden too, so it isn't said twice.
+ *
+ * Clipped to its circle, so its glow never spills into the row beside it or makes a list scroll.
+ * At rest the glow is too faint that far out to be missed.
+ */
 export function AbstractAvatar({
+  decorative = false,
   name,
   seed,
   size = 40,
 }: {
+  decorative?: boolean;
   name: string;
   seed: string;
   size?: number;
 }) {
   return (
     <span
-      role="img"
-      aria-label={name}
+      {...(decorative
+        ? { "aria-hidden": true }
+        : { role: "img", "aria-label": name })}
       className="inline-flex shrink-0 overflow-hidden rounded-full"
       style={{ height: size, width: size }}
     >
-      {/* The drawing carries its own role; hidden so the coworker is announced once, by name. */}
-      <span aria-hidden="true" className="contents">
-        <Avatar name={seed} size={size} />
-      </span>
+      <BotOrb seed={seed} size={size} />
     </span>
   );
 }