Wire operator Integrations page + capability-gating framework

Completes the arcadia-admin operator surface for the integration registry and
the capability/route-guard framework it depends on.

- Integration registry: route + Data-group nav entry + `platform.integrations`
  capability; the in-app client now delegates to the shared
  `@crema/integration-registry-client` lib (vite alias + tsconfig); the
  operator Integrations page (committed earlier) is now reachable.
- Capability gating: capabilities map + route-guard + jwt helpers + the
  apps/plan/entitlements routes and supporting tenants/session changes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/routes/announcements.tsx

@@ -69,6 +69,39 @@ export const meta = () => pageTitle("Announcements")
 
 const TYPES: AnnouncementType[] = ["info", "warning", "maintenance", "incident", "feature"]
 
+const KIND_OPTIONS: { value: AnnouncementType; hint: string }[] = [
+  { value: "info", hint: "Neutral update" },
+  { value: "warning", hint: "Degraded service or heads-up" },
+  { value: "maintenance", hint: "Scheduled work" },
+  { value: "incident", hint: "Active outage" },
+  { value: "feature", hint: "Something new shipped" },
+]
+
+function typeToAlertVariant(
+  t: AnnouncementType,
+): "info" | "success" | "warning" | "error" | "neutral" {
+  if (t === "incident") return "error"
+  if (t === "warning" || t === "maintenance") return "warning"
+  if (t === "feature") return "success"
+  return "info"
+}
+
+function publishButtonLabel(opts: {
+  isEdit: boolean
+  active: boolean
+  audience: "platform" | "tenant"
+  tenantId: string
+  tenants: Tenant[]
+}): string {
+  if (opts.isEdit) return "Save changes"
+  if (!opts.active) return "Save draft"
+  if (opts.audience === "tenant") {
+    const name = opts.tenants.find((t) => t.id === opts.tenantId)?.name
+    return name ? `Publish to ${name}` : "Publish to tenant"
+  }
+  return "Publish to all users"
+}
+
 type Editor =
   | { kind: "create" }
   | { kind: "edit"; announcement: Announcement }
@@ -86,6 +119,8 @@ export default function AnnouncementsRoute() {
   const [search, setSearch] = useState("")
   const [editor, setEditor] = useState<Editor>(null)
   const [pendingDelete, setPendingDelete] = useState<Announcement | null>(null)
+  const [refreshedAt, setRefreshedAt] = useState<number | null>(null)
+  const [now, setNow] = useState(() => Date.now())
 
   const refresh = useCallback(async () => {
     setError(null)
@@ -97,6 +132,7 @@ export default function AnnouncementsRoute() {
       ])
       setItems(a)
       setTenants(t)
+      setRefreshedAt(Date.now())
     } catch (err) {
       setError(err instanceof ArcadiaError ? err.message : "Failed to load announcements.")
     } finally {
@@ -104,6 +140,21 @@ export default function AnnouncementsRoute() {
     }
   }, [arcadia])
 
+  useEffect(() => {
+    if (refreshedAt == null) return
+    const id = window.setInterval(() => setNow(Date.now()), 30_000)
+    return () => window.clearInterval(id)
+  }, [refreshedAt])
+
+  const lastRefreshedLabel = useMemo(() => {
+    if (refreshedAt == null) return null
+    const seconds = Math.max(1, Math.round((now - refreshedAt) / 1000))
+    if (seconds < 60) return `${seconds}s ago`
+    const minutes = Math.round(seconds / 60)
+    if (minutes < 60) return `${minutes}m ago`
+    return `${Math.round(minutes / 60)}h ago`
+  }, [refreshedAt, now])
+
   useEffect(() => {
     if (session) refresh()
   }, [session, refresh])
@@ -133,13 +184,12 @@ export default function AnnouncementsRoute() {
       },
       {
         id: "scope",
-        header: "Scope",
-        cell: (a) =>
-          a.tenant_id ? (
-            <Badge variant="secondary">tenant</Badge>
-          ) : (
-            <Badge>platform</Badge>
-          ),
+        header: "Audience",
+        cell: (a) => {
+          if (!a.tenant_id) return <Badge>All apps</Badge>
+          const t = tenants.find((x) => x.id === a.tenant_id)
+          return <Badge variant="secondary">{t?.slug ?? "Single tenant"}</Badge>
+        },
       },
       {
         id: "active",
@@ -207,7 +257,7 @@ export default function AnnouncementsRoute() {
         },
       },
     ],
-    [arcadia, refresh],
+    [arcadia, refresh, tenants],
   )
 
   const summary = useMemo(
@@ -234,32 +284,48 @@ export default function AnnouncementsRoute() {
   return (
     <AppShell>
       <div className="flex flex-col gap-4">
-        <header className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
-          <div>
-            <h1 className="text-2xl font-semibold tracking-tight">Announcements</h1>
-            <p className="text-sm text-muted-foreground">
-              Platform-wide and per-tenant banners. Apps consuming arcadia surface these to users.
+        <header className="flex flex-col gap-3 sm:flex-row sm:items-end sm:justify-between">
+          <div className="min-w-0">
+            <h1 className="text-[26px] font-[620] leading-[1.1] tracking-[-0.02em]">
+              Announcements
+            </h1>
+            <p className="mt-1.5 max-w-[56ch] text-[13.5px] leading-[1.5] text-muted-foreground">
+              Banners that appear at the top of every Sky AI app. Use them for maintenance
+              windows, incidents, or new features.
             </p>
           </div>
-          <div className="flex items-center gap-2">
+          <div className="flex shrink-0 items-center gap-3">
+            {lastRefreshedLabel ? (
+              <span
+                className="text-xs tabular-nums text-muted-foreground"
+                aria-live="polite"
+                title={`Last refreshed ${lastRefreshedLabel}`}
+              >
+                <span className="hidden sm:inline">Updated </span>
+                {lastRefreshedLabel}
+              </span>
+            ) : null}
             <Button
-              variant="outline"
-              size="sm"
+              variant="ghost"
+              size="icon-sm"
               onClick={refresh}
               disabled={loading}
+              aria-label="Refresh announcements"
               data-action="announcements-refresh"
+              className="text-muted-foreground hover:text-foreground"
             >
               <RefreshCw className={`size-4 ${loading ? "animate-spin" : ""}`} />
-              Refresh
-            </Button>
-            <Button
-              size="sm"
-              onClick={() => setEditor({ kind: "create" })}
-              data-action="announcements-create"
-            >
-              <Plus className="size-4" />
-              New announcement
             </Button>
+            {items.length > 0 ? (
+              <Button
+                size="sm"
+                onClick={() => setEditor({ kind: "create" })}
+                data-action="announcements-create"
+              >
+                <Plus className="size-4" />
+                New announcement
+              </Button>
+            ) : null}
           </div>
         </header>
 
@@ -283,9 +349,13 @@ export default function AnnouncementsRoute() {
               data-action="announcements-search"
               className="max-w-sm flex-1"
             />
-            <div className="ml-auto text-xs text-muted-foreground">
-              {table.total} of {items.length}
-            </div>
+            {items.length > 0 ? (
+              <div className="ml-auto text-xs tabular-nums text-muted-foreground">
+                {search && table.total !== items.length
+                  ? `${table.total} of ${items.length}`
+                  : `${items.length} ${items.length === 1 ? "announcement" : "announcements"}`}
+              </div>
+            ) : null}
           </CardHeader>
 
           <CardContent className="relative p-0">
@@ -295,12 +365,47 @@ export default function AnnouncementsRoute() {
             />
             {table.total === 0 && !loading ? (
               <EmptyState
-                icon={<Megaphone className="size-6" />}
+                icon={
+                  <div
+                    className="grid size-14 place-items-center rounded-full"
+                    style={{
+                      background:
+                        "radial-gradient(circle at center, color-mix(in oklch, var(--primary) 22%, transparent), transparent 70%)",
+                    }}
+                  >
+                    <Megaphone
+                      className="size-6"
+                      style={{ color: "var(--primary)" }}
+                    />
+                  </div>
+                }
                 title={search ? "No announcements match." : "No announcements yet."}
                 description={
-                  search ? "Try a different search." : "Post the first one — platform-wide or scoped to a tenant."
+                  search
+                    ? "Try a different search."
+                    : "Post your first banner. Show it to everyone, or scope it to a single tenant."
+                }
+                action={
+                  search ? (
+                    <Button
+                      size="sm"
+                      variant="outline"
+                      onClick={() => setSearch("")}
+                      data-action="announcements-clear-search"
+                    >
+                      Clear search
+                    </Button>
+                  ) : (
+                    <Button
+                      size="sm"
+                      onClick={() => setEditor({ kind: "create" })}
+                      data-action="announcements-create-empty"
+                    >
+                      <Plus className="size-4" />
+                      New announcement
+                    </Button>
+                  )
                 }
-                className="py-12"
               />
             ) : (
               <>
@@ -407,6 +512,11 @@ function AnnouncementEditorDialog({
   const [dismissible, setDismissible] = useState(true)
   const [active, setActive] = useState(true)
   const [saving, setSaving] = useState(false)
+  const [localError, setLocalError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!open) setLocalError(null)
+  }, [open])
 
   useEffect(() => {
     if (!open) return
@@ -439,6 +549,7 @@ function AnnouncementEditorDialog({
 
   const submit = async () => {
     onError(null)
+    setLocalError(null)
     setSaving(true)
     try {
       const input: AnnouncementInput = {
@@ -462,13 +573,13 @@ function AnnouncementEditorDialog({
         await onSaved("Announcement posted.")
       }
     } catch (err) {
-      onError(
+      const msg =
         err instanceof ArcadiaError
           ? err.message
           : err instanceof Error
             ? err.message
-            : "Save failed.",
-      )
+            : "Save failed."
+      setLocalError(msg)
     } finally {
       setSaving(false)
     }
@@ -476,15 +587,59 @@ function AnnouncementEditorDialog({
 
   return (
     <Dialog open={open} onOpenChange={(o) => !o && onClose()}>
-      <DialogContent className="sm:max-w-xl max-h-[90vh] overflow-y-auto">
+      <DialogContent className="sm:max-w-2xl max-h-[90vh] overflow-y-auto">
         <DialogHeader>
           <DialogTitle>{isEdit ? "Edit announcement" : "New announcement"}</DialogTitle>
           <DialogDescription>
-            Banners surface in apps that consume arcadia. Active + currently within the start/end
-            window = visible.
+            A banner shows at the top of every Sky AI app. It's visible when it's switched on
+            and today falls inside its date range.
           </DialogDescription>
         </DialogHeader>
 
+        {/* Live preview — what users will see. Updates as the form is edited so
+            the operator never has to imagine the output or publish blind. */}
+        <div className="flex flex-col gap-1.5">
+          <Label className="text-xs uppercase tracking-wider text-muted-foreground">
+            Preview
+          </Label>
+          <div className="rounded-md border bg-muted/30 p-3">
+            <AlertBanner
+              variant={typeToAlertVariant(type)}
+              title={title || "Your banner title appears here"}
+              dismissible={dismissible}
+              onDismiss={() => {}}
+              action={
+                actionLabel && actionUrl ? (
+                  <Button size="xs" variant="outline" type="button" tabIndex={-1}>
+                    {actionLabel}
+                  </Button>
+                ) : undefined
+              }
+            >
+              {body || (
+                <span className="italic opacity-60">Body text appears here.</span>
+              )}
+            </AlertBanner>
+            <p className="mt-2 text-[11px] text-muted-foreground">
+              {audience === "tenant"
+                ? `Visible to users of ${
+                    tenants.find((t) => t.id === tenantId)?.name ?? "the selected tenant"
+                  } only.`
+                : "Visible to everyone across every Sky AI app."}
+            </p>
+          </div>
+        </div>
+
+        {localError ? (
+          <AlertBanner
+            variant="error"
+            dismissible
+            onDismiss={() => setLocalError(null)}
+          >
+            {localError}
+          </AlertBanner>
+        ) : null}
+
         <div className="grid grid-cols-2 gap-3">
           <div className="col-span-2 flex flex-col gap-1.5">
             <Label htmlFor="ann-title">Title</Label>
@@ -493,6 +648,7 @@ function AnnouncementEditorDialog({
               value={title}
               onChange={(e) => setTitle(e.target.value)}
               data-action="announcement-form-title"
+              placeholder="Scheduled maintenance Sunday 2am AEST"
             />
           </div>
           <div className="col-span-2 flex flex-col gap-1.5">
@@ -501,21 +657,25 @@ function AnnouncementEditorDialog({
               id="ann-body"
               value={body}
               onChange={(e) => setBody(e.target.value)}
-              rows={4}
+              rows={3}
               data-action="announcement-form-body"
+              placeholder="Expect ~10 minutes of downtime while we ship the new tenant switcher."
             />
           </div>
 
           <div className="flex flex-col gap-1.5">
-            <Label>Type</Label>
+            <Label>Kind</Label>
             <Select value={type} onValueChange={setType}>
               <SelectTrigger data-action="announcement-form-type">
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>
-                {TYPES.map((t) => (
-                  <SelectItem key={t} value={t}>
-                    {t}
+                {KIND_OPTIONS.map((opt) => (
+                  <SelectItem key={opt.value} value={opt.value}>
+                    <div className="flex flex-col">
+                      <span className="font-medium capitalize">{opt.value}</span>
+                      <span className="text-xs text-muted-foreground">{opt.hint}</span>
+                    </div>
                   </SelectItem>
                 ))}
               </SelectContent>
@@ -523,21 +683,21 @@ function AnnouncementEditorDialog({
           </div>
 
           <div className="flex flex-col gap-1.5">
-            <Label>Audience</Label>
+            <Label>Who sees this</Label>
             <Select value={audience} onValueChange={(v) => setAudience(v as "platform" | "tenant")}>
               <SelectTrigger data-action="announcement-form-audience">
                 <SelectValue />
               </SelectTrigger>
               <SelectContent>
-                <SelectItem value="platform">Platform-wide</SelectItem>
-                <SelectItem value="tenant">Single tenant</SelectItem>
+                <SelectItem value="platform">Everyone</SelectItem>
+                <SelectItem value="tenant">Just one tenant</SelectItem>
               </SelectContent>
             </Select>
           </div>
 
           {audience === "tenant" ? (
             <div className="col-span-2 flex flex-col gap-1.5">
-              <Label>Tenant</Label>
+              <Label>Which tenant</Label>
               <Select value={tenantId} onValueChange={setTenantId}>
                 <SelectTrigger data-action="announcement-form-tenant">
                   <SelectValue placeholder="Pick a tenant" />
@@ -554,7 +714,7 @@ function AnnouncementEditorDialog({
           ) : null}
 
           <div className="flex flex-col gap-1.5">
-            <Label htmlFor="ann-starts">Starts at</Label>
+            <Label htmlFor="ann-starts">Starts</Label>
             <Input
               id="ann-starts"
               type="datetime-local"
@@ -564,7 +724,7 @@ function AnnouncementEditorDialog({
             />
           </div>
           <div className="flex flex-col gap-1.5">
-            <Label htmlFor="ann-ends">Ends at</Label>
+            <Label htmlFor="ann-ends">Ends</Label>
             <Input
               id="ann-ends"
               type="datetime-local"
@@ -574,57 +734,88 @@ function AnnouncementEditorDialog({
             />
           </div>
 
-          <div className="flex flex-col gap-1.5">
-            <Label htmlFor="ann-action-label">Action label (optional)</Label>
-            <Input
-              id="ann-action-label"
-              value={actionLabel}
-              onChange={(e) => setActionLabel(e.target.value)}
-              placeholder="Read more"
-              data-action="announcement-form-action-label"
-            />
-          </div>
-          <div className="flex flex-col gap-1.5">
-            <Label htmlFor="ann-action-url">Action URL (optional)</Label>
-            <Input
-              id="ann-action-url"
-              value={actionUrl}
-              onChange={(e) => setActionUrl(e.target.value)}
-              placeholder="/changelog/v2"
-              data-action="announcement-form-action-url"
-            />
+          {/* Optional link group — heading clarifies these two are paired. */}
+          <div className="col-span-2 flex flex-col gap-2 rounded-md border border-dashed p-3">
+            <div className="flex items-baseline justify-between gap-2">
+              <Label className="text-sm">Add a link</Label>
+              <span className="text-xs text-muted-foreground">Optional</span>
+            </div>
+            <div className="grid grid-cols-2 gap-3">
+              <div className="flex flex-col gap-1.5">
+                <Label htmlFor="ann-action-label" className="text-xs text-muted-foreground">
+                  Button text
+                </Label>
+                <Input
+                  id="ann-action-label"
+                  value={actionLabel}
+                  onChange={(e) => setActionLabel(e.target.value)}
+                  placeholder="Read more"
+                  data-action="announcement-form-action-label"
+                />
+              </div>
+              <div className="flex flex-col gap-1.5">
+                <Label htmlFor="ann-action-url" className="text-xs text-muted-foreground">
+                  Where it goes
+                </Label>
+                <Input
+                  id="ann-action-url"
+                  value={actionUrl}
+                  onChange={(e) => setActionUrl(e.target.value)}
+                  placeholder="/changelog/v2"
+                  data-action="announcement-form-action-url"
+                />
+              </div>
+            </div>
           </div>
 
-          <div className="flex items-center justify-between rounded-md border px-3 py-2">
-            <Label className="text-sm">Dismissible</Label>
+          {/* End-user behavior toggle, not publish state — kept with content fields. */}
+          <div className="col-span-2 flex items-center justify-between rounded-md border px-3 py-2">
+            <div className="flex flex-col">
+              <Label className="text-sm">Let users dismiss</Label>
+              <span className="text-xs text-muted-foreground">
+                Adds an × users can click to hide the banner.
+              </span>
+            </div>
             <Switch
               checked={dismissible}
               onCheckedChange={setDismissible}
               data-action="announcement-form-dismissible"
             />
           </div>
-          <div className="flex items-center justify-between rounded-md border px-3 py-2">
-            <Label className="text-sm">Active</Label>
+        </div>
+
+        <DialogFooter className="flex-col items-stretch gap-3 sm:flex-row sm:items-center sm:justify-between">
+          {/* Active = publish state, paired with the publish button. */}
+          <label
+            htmlFor="ann-active"
+            className="flex items-center gap-2 text-xs text-muted-foreground sm:mr-auto"
+          >
             <Switch
+              id="ann-active"
               checked={active}
               onCheckedChange={setActive}
               data-action="announcement-form-active"
             />
-          </div>
-        </div>
+            <span>{active ? "Switched on" : "Switched off (draft)"}</span>
+          </label>
 
-        <DialogFooter>
-          <Button variant="outline" onClick={onClose} disabled={saving}>
-            Cancel
-          </Button>
-          <Button
-            onClick={submit}
-            disabled={saving || !title.trim() || (audience === "tenant" && !tenantId)}
-            data-action="announcement-form-save"
-          >
-            {saving ? <RefreshCw className="size-4 animate-spin" /> : <CheckCircle2 className="size-4" />}
-            {isEdit ? "Save" : "Post"}
-          </Button>
+          <div className="flex items-center justify-end gap-2">
+            <Button variant="outline" onClick={onClose} disabled={saving}>
+              Cancel
+            </Button>
+            <Button
+              onClick={submit}
+              disabled={saving || !title.trim() || (audience === "tenant" && !tenantId)}
+              data-action="announcement-form-save"
+            >
+              {saving ? (
+                <RefreshCw className="size-4 animate-spin" />
+              ) : (
+                <CheckCircle2 className="size-4" />
+              )}
+              {publishButtonLabel({ isEdit, active, audience, tenantId, tenants })}
+            </Button>
+          </div>
         </DialogFooter>
       </DialogContent>
     </Dialog>