@flamingo-stack/openframe-frontend-core 0.0.848 → 0.0.850

package/src/components/embeds/figma-embed.tsx

@@ -19,7 +19,9 @@ export interface FigmaEmbedProps {
    */
   height?: string;
   /** iframe loading strategy. Defaults to `"lazy"`; the data-room viewer passes `"eager"`. */
-  loading?: 'eager' | 'lazy';
+  iframeLoading?: 'eager' | 'lazy';
+  /** The document is being read: the embed draws its loading form. A loading scope does the same. */
+  loading?: boolean;
 }
 
 type SlidesView = 'present' | 'browse';
@@ -42,7 +44,9 @@ function SlidesViewToggle({ view, onChange }: { view: SlidesView; onChange: (v:
         if (v && v !== view) onChange(v as SlidesView);
       }}
       aria-label="Figma slides view mode"
-      className="flex shrink-0 items-center gap-0.5 rounded-lg border border-ods-border bg-ods-card p-0.5"
+      // The whole control is one button tall (40px, border and padding included), so the header row is the same height
+      // with or without it, loading and loaded alike.
+      className="flex h-10 shrink-0 items-center gap-0.5 rounded-lg border border-ods-border bg-ods-card p-0.5"
     >
       {options.map(({ key, label, Icon }) => {
         const active = view === key;
@@ -51,7 +55,7 @@ function SlidesViewToggle({ view, onChange }: { view: SlidesView; onChange: (v:
             key={key}
             value={key}
             aria-label={label}
-            className={`flex items-center gap-1.5 rounded-md px-2.5 py-1 transition-colors text-h6 ${
+            className={`flex h-full items-center gap-1.5 rounded-md px-2.5 py-1 transition-colors text-h6 ${
               active
                 ? 'bg-ods-accent text-ods-text-on-accent'
                 : 'text-ods-text-secondary hover:bg-ods-bg-hover hover:text-ods-text-primary'
@@ -80,7 +84,7 @@ function SlidesViewToggle({ view, onChange }: { view: SlidesView; onChange: (v:
  * plain ReactNode) — flipping it recomputes `embedSrc`, and the frame's
  * `EmbedIframe` remounts on the new src exactly as before the extraction.
  */
-export function FigmaEmbed({ url, title, height, loading = 'lazy' }: FigmaEmbedProps) {
+export function FigmaEmbed({ url, title, height, iframeLoading = 'lazy', loading = false }: FigmaEmbedProps) {
   const [view, setView] = useState<SlidesView>('present');
   const isSlides = url ? isFigmaSlidesUrl(url) : false;
   const embedSrc = url ? toFigmaEmbedUrl(url, { slidesView: view }) : null;
@@ -124,6 +128,7 @@ export function FigmaEmbed({ url, title, height, loading = 'lazy' }: FigmaEmbedP
       }
       src={embedSrc}
       allow="clipboard-write; clipboard-read; fullscreen"
+      iframeLoading={iframeLoading}
       loading={loading}
       height={height}
       allowFullScreen

package/src/components/embeds/file-download-card.tsx

@@ -1,14 +1,23 @@
 import { FileText, Download } from 'lucide-react';
 import { formatFileSize } from '../../utils';
+import { InteractiveSkeleton, TextLineSkeleton } from '../loading/unified-skeleton';
 import { Button } from '../ui';
+import { useLoadingScope } from '../ui/loading-scope';
 
 export interface FileDownloadCardProps {
   fileName?: string;
   mimeType?: string;
   fileSize?: number;
   fileUrl?: string;
+  /** The file is being read: the card draws its loading form. A loading scope does the same. */
+  loading?: boolean;
 }
 
+/** The card's boxes, shared by the card and its loading form. */
+const FILE_CARD_OUTER_CLASS = 'flex flex-col items-center justify-center py-16';
+const FILE_CARD_CLASS = 'w-full max-w-md space-y-4 rounded-xl border border-ods-border bg-ods-card p-8 text-center';
+const FILE_ICON_CLASS = 'mx-auto h-16 w-16 text-ods-text-secondary';
+
 /**
  * Generic downloadable-file card for the `file` document type. Used by
  * `<DocsHubPage>`'s default `documentTypeRenderers.file`. Embedders can
@@ -18,11 +27,26 @@ export interface FileDownloadCardProps {
  * renders the filename + type + size so the user knows what they were
  * about to download).
  */
-export function FileDownloadCard({ fileName, mimeType, fileSize, fileUrl }: FileDownloadCardProps) {
+export function FileDownloadCard({ fileName, mimeType, fileSize, fileUrl, loading = false }: FileDownloadCardProps) {
+  // In a loading scope the file is being read: the card draws its own loading form, in its own boxes.
+  if (useLoadingScope() || loading) {
+    return (
+      <div className={FILE_CARD_OUTER_CLASS}>
+        <div className={FILE_CARD_CLASS}>
+          <FileText className={FILE_ICON_CLASS} />
+          <div>
+            <TextLineSkeleton type="h3" className="mx-auto w-2/3" />
+            <TextLineSkeleton type="h6" className="mx-auto mt-2 w-1/2" />
+          </div>
+          <InteractiveSkeleton.Button className="mx-auto" />
+        </div>
+      </div>
+    );
+  }
   return (
-    <div className="flex flex-col items-center justify-center py-16">
-      <div className="w-full max-w-md space-y-4 rounded-xl border border-ods-border bg-ods-card p-8 text-center">
-        <FileText className="mx-auto h-16 w-16 text-ods-text-secondary" />
+    <div className={FILE_CARD_OUTER_CLASS}>
+      <div className={FILE_CARD_CLASS}>
+        <FileText className={FILE_ICON_CLASS} />
         <div>
           <h3 className="text-ods-text-primary text-h3">{fileName || 'File'}</h3>
           <div className="mt-2 flex items-center justify-center gap-3 text-ods-text-secondary text-h6">

package/src/components/embeds/google-sheets-viewer.tsx

@@ -4,20 +4,25 @@ import { ExternalLink } from 'lucide-react';
 import { toGoogleSheetsEmbedUrl, toGoogleSheetsOriginalUrl } from '../../utils/embed-url-converters';
 import { GoogleSheetsIcon } from '../icons-v2-generated';
 import { Button } from '../ui';
+import { useLoadingScope } from '../ui/loading-scope';
 import { EmbedViewerFrame } from './embed-viewer-frame';
 
 export interface GoogleSheetsViewerProps {
   externalUrl: string;
   fileName?: string;
   height?: string;
+  /** The document is being read: the viewer draws its loading form. A loading scope does the same. */
+  loading?: boolean;
 }
 
-export function GoogleSheetsViewer({ externalUrl, fileName, height }: GoogleSheetsViewerProps) {
+export function GoogleSheetsViewer({ externalUrl, fileName, height, loading = false }: GoogleSheetsViewerProps) {
   const displayName = fileName || 'Google Sheet';
+  // In a loading scope the document is being read: the frame draws its loading form, never "not configured".
+  const isLoading = useLoadingScope() || loading;
 
   // Historical shape: no URL at all → standalone empty state with NO header
   // (the frame's empty body keeps the header — that's the figma behavior).
-  if (!externalUrl) {
+  if (!externalUrl && !isLoading) {
     return (
       <div className="flex flex-col items-center justify-center py-16 text-center">
         <GoogleSheetsIcon className="mb-4 h-16 w-16 text-ods-text-secondary" />
@@ -43,8 +48,9 @@ export function GoogleSheetsViewer({ externalUrl, fileName, height }: GoogleShee
           Open in Google Sheets
         </Button>
       }
-      src={toGoogleSheetsEmbedUrl(externalUrl)}
+      src={externalUrl ? toGoogleSheetsEmbedUrl(externalUrl) : null}
       height={height}
+      loading={loading}
     />
   );
 }

package/src/components/embeds/pdf-viewer.tsx

@@ -3,6 +3,7 @@
 import { Download, Eye } from 'lucide-react';
 import { AdobePdfIcon } from '../icons-v2-generated';
 import { Button } from '../ui';
+import { useLoadingScope } from '../ui/loading-scope';
 import { EmbedViewerFrame } from './embed-viewer-frame';
 
 export interface PdfViewerProps {
@@ -11,13 +12,20 @@ export interface PdfViewerProps {
   onPreview?: () => void;
   onDownload?: () => void;
   height?: string;
+  /** The document is being read: the viewer draws its loading form. A loading scope does the same. */
+  loading?: boolean;
 }
 
-export function PdfViewer({ src, fileName, onPreview, onDownload, height }: PdfViewerProps) {
+/** The header's loading form: Preview and Download, the viewer's two actions. */
+const PDF_VIEWER_SKELETON_ACTIONS = 2;
+
+export function PdfViewer({ src, fileName, onPreview, onDownload, height, loading = false }: PdfViewerProps) {
   const displayName = fileName || 'PDF Document';
+  // In a loading scope the document is being read: the frame draws its loading form, never "not available".
+  const isLoading = useLoadingScope() || loading;
 
   // Historical shape: no src at all → standalone empty state with NO header.
-  if (!src) {
+  if (!src && !isLoading) {
     return (
       <div className="flex flex-col items-center justify-center py-16 text-center">
         <AdobePdfIcon className="mb-4 h-16 w-16 text-ods-text-secondary" />
@@ -57,6 +65,8 @@ export function PdfViewer({ src, fileName, onPreview, onDownload, height }: PdfV
         </div>
       }
       src={src}
+      loadingActionCount={PDF_VIEWER_SKELETON_ACTIONS}
+      loading={loading}
       height={height}
     />
   );

package/src/components/features/software/index.ts

@@ -40,6 +40,7 @@ export { type PackageSearchSlotProps, SoftwareRowFields, type SoftwareRowFieldsP
 export {
   DEFAULT_SOFTWARE_UPDATE_POLICY,
   DEFAULT_SOFTWARE_UPDATE_SETTINGS,
+  defaultSoftwareUpdateSettings,
   SOFTWARE_UPDATE_COUNTDOWN_OPTIONS,
   SOFTWARE_UPDATE_DEADLINE_OPTIONS,
   type SoftwareUpdateMode,

package/src/components/features/software/software-action-copy.ts

@@ -19,6 +19,21 @@ export interface SoftwareActionCopy {
   logsHeading: string;
 }
 
+/**
+ * The run modes say when a device actually gets the run, not only when it is sent. Both forms submit a software bundle
+ * (`submitSoftwareBundle`), and the backend delivers it per device:
+ * - Now: each device gets an online-dispatch sentinel (`SoftwareBundleService.armOnlineDispatch`), so an online device
+ *   starts at once and an offline one when it comes online.
+ * - Scheduled: the schedule is created with `offlineBehavior` RETRY_ON_RECONNECT and the reconnect window
+ *   `openframe.rmm.software.bundle.schedule.reconnect-window-seconds` (604800 s, 7 days, in saas-tenant
+ *   `configs/base/openframe-saas-api.yml`): a device offline at the start time gets the run when it reconnects within
+ *   that window. Keep "within 7 days" in step with that key.
+ */
+const nowDescription = (noun: string) =>
+  `The ${noun} starts now on online devices, and on the others when they come online.`;
+const scheduleDescription = (noun: string) =>
+  `The ${noun} runs at the scheduled time. Devices offline then get it when they come back online, within 7 days.`;
+
 /** Everything the install and update flows word differently, on every page that shows one. */
 export const SOFTWARE_ACTION_COPY: Record<SoftwareActionKind, SoftwareActionCopy> = {
   INSTALL: {
@@ -27,12 +42,8 @@ export const SOFTWARE_ACTION_COPY: Record<SoftwareActionKind, SoftwareActionCopy
     runLabel: 'Run Installation',
     scheduleLabel: 'Schedule Install',
     modes: [
-      { value: 'now', label: 'Install Now', description: 'The install starts immediately.' },
-      {
-        value: 'schedule',
-        label: 'Schedule Install',
-        description: 'The install runs automatically at the scheduled time.',
-      },
+      { value: 'now', label: 'Install Now', description: nowDescription('install') },
+      { value: 'schedule', label: 'Schedule Install', description: scheduleDescription('install') },
     ],
     started: 'Installation started',
     scheduled: 'Installation scheduled',
@@ -46,12 +57,8 @@ export const SOFTWARE_ACTION_COPY: Record<SoftwareActionKind, SoftwareActionCopy
     runLabel: 'Run Update',
     scheduleLabel: 'Schedule Update',
     modes: [
-      { value: 'now', label: 'Update Now', description: 'The update starts immediately.' },
-      {
-        value: 'schedule',
-        label: 'Schedule Update',
-        description: 'The update runs automatically at the scheduled time.',
-      },
+      { value: 'now', label: 'Update Now', description: nowDescription('update') },
+      { value: 'schedule', label: 'Schedule Update', description: scheduleDescription('update') },
     ],
     started: 'Update started',
     scheduled: 'Update scheduled',

package/src/components/features/software/software-action-form.tsx

@@ -10,7 +10,7 @@ import { SOFTWARE_ACTION_COPY, type SoftwareActionKind } from './software-action
 import { newSoftwareRow, type SoftwareRow } from './software-row';
 import { type PackageSearchSlotProps, SoftwareRowFields } from './software-row-fields';
 import {
-  DEFAULT_SOFTWARE_UPDATE_SETTINGS,
+  defaultSoftwareUpdateSettings,
   SoftwareUpdateSettingsFields,
   type SoftwareUpdateSettingsValues,
 } from './update-settings-fields';
@@ -74,6 +74,12 @@ export interface SoftwareActionFormProps<TRef extends string = string> {
    * settings yet never shows choices that go nowhere; the host that submits `updateSettings` passes true.
    */
   showUpdateSettings?: boolean;
+  /**
+   * "Update Settings" offer Wait & notify and the countdowns, which need the devices to notify the user. Default false:
+   * Wait (with an optional deadline that closes the app without warning) or Force Update, opening on Force Update, and
+   * no countdown.
+   */
+  updateUserNotifications?: boolean;
   /** The "Device Selection" heading over the picker. Default true; a host that titles the picker itself passes false. */
   showDeviceHeading?: boolean;
   className?: string;
@@ -104,6 +110,7 @@ export function SoftwareActionForm<TRef extends string = string>({
   addRows = true,
   runModeLayout = 'stacked',
   showUpdateSettings = false,
+  updateUserNotifications = false,
   showDeviceHeading = true,
   className = 'px-[var(--spacing-system-l)] pb-[var(--spacing-system-l)]',
 }: SoftwareActionFormProps<TRef>) {
@@ -115,7 +122,7 @@ export function SoftwareActionForm<TRef extends string = string>({
   const [time, setTime] = useState(initialValues.time ?? '');
   const [timeReference, setTimeReference] = useState<TRef>(initialValues.timeReference);
   const [updateSettings, setUpdateSettings] = useState<SoftwareUpdateSettingsValues>(
-    () => initialValues.updateSettings ?? DEFAULT_SOFTWARE_UPDATE_SETTINGS,
+    () => initialValues.updateSettings ?? defaultSoftwareUpdateSettings(updateUserNotifications),
   );
   const withUpdateSettings = action === 'UPDATE' && showUpdateSettings;
 
@@ -215,7 +222,13 @@ export function SoftwareActionForm<TRef extends string = string>({
         </>
       )}
 
-      {withUpdateSettings && <SoftwareUpdateSettingsFields value={updateSettings} onChange={setUpdateSettings} />}
+      {withUpdateSettings && (
+        <SoftwareUpdateSettingsFields
+          value={updateSettings}
+          onChange={setUpdateSettings}
+          userNotifications={updateUserNotifications}
+        />
+      )}
 
       {showDeviceHeading && (
         <h2 className="pt-[var(--spacing-system-l)] text-ods-text-primary text-h2">Device Selection</h2>

package/src/components/features/software/update-settings-fields.tsx

@@ -1,8 +1,6 @@
 'use client';
 
-import { InfoCircleIcon } from '../../icons-v2-generated';
 import {
-  Alert,
   CheckboxBlock,
   Label,
   RadioGroupBlock,
@@ -71,24 +69,95 @@ export const DEFAULT_SOFTWARE_UPDATE_SETTINGS: SoftwareUpdateSettingsValues = {
   autoUpdatePolicy: DEFAULT_SOFTWARE_UPDATE_POLICY,
 };
 
-const MODE_OPTIONS: RadioGroupBlockOption[] = [
-  {
+/** Force Update, with a 7-day deadline ready for when Wait is picked: what the form opens with without notifications. */
+const FORCE_UPDATE_POLICY: SoftwareUpdatePolicy = {
+  ...DEFAULT_SOFTWARE_UPDATE_POLICY,
+  mode: 'FORCE',
+  deadlineEnabled: false,
+};
+
+/**
+ * What the form opens with. With user notifications, the server's own defaults. Without them, Force Update: an app is
+ * never closed unannounced a week later, and nobody is promised a prompt that cannot be shown.
+ */
+export function defaultSoftwareUpdateSettings(userNotifications: boolean): SoftwareUpdateSettingsValues {
+  if (userNotifications) return DEFAULT_SOFTWARE_UPDATE_SETTINGS;
+  return { ...DEFAULT_SOFTWARE_UPDATE_SETTINGS, policy: FORCE_UPDATE_POLICY, autoUpdatePolicy: FORCE_UPDATE_POLICY };
+}
+
+/**
+ * The two modes and their deadline, worded by what the device does. With user notifications the user is asked and
+ * warned. Without them the agent shows nothing on the device (no prompt, no countdown on screen; there is no end-user
+ * UI anywhere yet), so the copy says only what happens:
+ * - Wait (WAIT, no deadline): the agent reports Waiting and installs once the app is closed.
+ * - A deadline (WAIT + `deadlineSeconds`): counted from the first time the agent finds the app running; at the deadline
+ *   the backend sends the update again as FORCE (`armDeadline` / `driveDeadlineForce` in openframe-client-core), and
+ *   withdraws that if the update finished first.
+ * - Force (FORCE): the agent waits `countdownSeconds` (clamped to 60–1800 s), asks the app to close, stops it after a
+ *   10 s grace and installs (`run.rs` / `close.rs` in openframe-client). The wait is silent, so it is not offered as a
+ *   control; the copy states it, since the app is not closed at once.
+ */
+interface ModeCopy {
+  wait: RadioGroupBlockOption;
+  force: RadioGroupBlockOption;
+  deadline: { label: string; description: string };
+}
+
+/** "5 minutes": the silent wait before a forced close, worded as the countdown options word it. */
+function closeDelay(countdownSeconds: number): string {
+  const option = SOFTWARE_UPDATE_COUNTDOWN_OPTIONS.find(candidate => candidate.seconds === countdownSeconds);
+  if (option) return option.label;
+  const minutes = Math.max(1, Math.round(countdownSeconds / 60));
+  return minutes === 1 ? '1 minute' : `${minutes} minutes`;
+}
+
+const NOTIFIED_COPY: ModeCopy = {
+  wait: {
     value: 'WAIT',
     label: 'Wait & notify',
     description: 'The user gets Update now or Ask Later. If they close the app, it updates then.',
   },
-  {
+  force: {
     value: 'FORCE',
     label: 'Force Update',
     description: 'The user gets a short countdown, then the app closes and updates.',
   },
-];
+  deadline: {
+    label: 'Countdown after the deadline',
+    description: 'If the update still isn’t installed by the deadline, the user gets a countdown and then it installs.',
+  },
+};
+
+function silentCopy(countdownSeconds: number): ModeCopy {
+  const delay = closeDelay(countdownSeconds);
+  return {
+    wait: { value: 'WAIT', label: 'Wait', description: 'The update waits until the user closes the app.' },
+    force: {
+      value: 'FORCE',
+      label: 'Force Update',
+      description: `The app is closed without warning ${delay} later, then updated.`,
+    },
+    deadline: {
+      label: 'Close the app after a deadline',
+      description: `If the app is still open by the deadline, it is closed without warning ${delay} later, then updated.`,
+    },
+  };
+}
 
 const SAME_SETTINGS_DESCRIPTION: Record<SoftwareUpdateMode, string> = {
   WAIT: 'Auto-updates follow "If the app is running" above. Uncheck to set them separately.',
   FORCE: 'Later releases will also be force-updated.',
 };
 
+/**
+ * "Keep it auto-updated", as the backend runs it (`PackageAutoUpdatePolicyService.turnOn`, `PackageAutoUpdateTrigger`):
+ * a run with it on enables a policy per device for the package, and the trigger orders each new catalog version (Brew
+ * and winget catalogs) on those devices. A run with it off leaves an earlier policy as it is: only Turn Off Auto-Update
+ * (`turnOffSoftwareAutoUpdate`) or the package leaving the device turns one off, so "off" does not mean "stop".
+ */
+const AUTO_UPDATE_DESCRIPTION =
+  'After this update, OpenFrame installs each new version from Winget or Brew on the selected devices. Leaving it off does not turn off auto-update that is already on there.';
+
 const groupLabelClass = 'text-h5 text-ods-text-secondary';
 
 function SecondsSelect({
@@ -126,17 +195,21 @@ function UpdatePolicyFields({
   name,
   label,
   policy,
+  userNotifications,
   onChange,
 }: {
   /** The radio group's name: two policies on one page must not share it. */
   name: string;
   label: string;
   policy: SoftwareUpdatePolicy;
+  /** Off, the choices say what the device does with nobody told, and there is no countdown to set. */
+  userNotifications: boolean;
   onChange: (policy: SoftwareUpdatePolicy) => void;
 }) {
+  const copy = userNotifications ? NOTIFIED_COPY : silentCopy(policy.countdownSeconds);
   const waits = policy.mode === 'WAIT';
   const deadline = waits && policy.deadlineEnabled;
-  const countdown = (
+  const countdown = userNotifications && (
     <SecondsSelect
       label="Countdown"
       value={policy.countdownSeconds}
@@ -154,7 +227,7 @@ function UpdatePolicyFields({
           variant="grouped"
           value={policy.mode}
           onValueChange={mode => onChange({ ...policy, mode: mode as SoftwareUpdateMode })}
-          options={MODE_OPTIONS}
+          options={[copy.wait, copy.force]}
           itemClassName="py-[var(--spacing-system-sf)]"
         />
       </div>
@@ -164,8 +237,8 @@ function UpdatePolicyFields({
             id={`${name}-deadline`}
             checked={policy.deadlineEnabled}
             onCheckedChange={deadlineEnabled => onChange({ ...policy, deadlineEnabled })}
-            label="Countdown after the deadline"
-            description="If the update still isn’t installed by the deadline, the user gets a countdown and then it installs."
+            label={copy.deadline.label}
+            description={copy.deadline.description}
           />
           {deadline && (
             <div className="grid grid-cols-1 gap-[var(--spacing-system-lf)] content-md:grid-cols-3 content-md:items-start">
@@ -180,7 +253,9 @@ function UpdatePolicyFields({
           )}
         </div>
       ) : (
-        <div className="grid grid-cols-1 gap-[var(--spacing-system-lf)] content-md:grid-cols-3">{countdown}</div>
+        userNotifications && (
+          <div className="grid grid-cols-1 gap-[var(--spacing-system-lf)] content-md:grid-cols-3">{countdown}</div>
+        )
       )}
     </div>
   );
@@ -189,6 +264,12 @@ function UpdatePolicyFields({
 export interface SoftwareUpdateSettingsFieldsProps {
   value: SoftwareUpdateSettingsValues;
   onChange: (value: SoftwareUpdateSettingsValues) => void;
+  /**
+   * The devices can notify the user: Wait & notify, its countdown after the deadline and the countdowns. Default false,
+   * as today, when the client has no notifications: Wait (until the user closes the app, or a deadline closes it without
+   * warning) or Force Update, and no countdown.
+   */
+  userNotifications?: boolean;
 }
 
 /**
@@ -196,7 +277,11 @@ export interface SoftwareUpdateSettingsFieldsProps {
  * rules 1034:8173): what happens on a device where the app is running, and
  * whether later releases are installed the same way.
  */
-export function SoftwareUpdateSettingsFields({ value, onChange }: SoftwareUpdateSettingsFieldsProps) {
+export function SoftwareUpdateSettingsFields({
+  value,
+  onChange,
+  userNotifications = false,
+}: SoftwareUpdateSettingsFieldsProps) {
   return (
     <section aria-labelledby="software-update-settings" className="flex flex-col gap-[var(--spacing-system-l)]">
       <h2 id="software-update-settings" className="pt-[var(--spacing-system-l)] text-ods-text-primary text-h2">
@@ -207,6 +292,7 @@ export function SoftwareUpdateSettingsFields({ value, onChange }: SoftwareUpdate
         name="updatePolicy"
         label="If the app is running"
         policy={value.policy}
+        userNotifications={userNotifications}
         onChange={policy => onChange({ ...value, policy })}
       />
 
@@ -218,7 +304,7 @@ export function SoftwareUpdateSettingsFields({ value, onChange }: SoftwareUpdate
             checked={value.autoUpdate}
             onCheckedChange={autoUpdate => onChange({ ...value, autoUpdate })}
             label="Keep it auto-updated"
-            description="After this update, OpenFrame installs each new version from Winget or Brew on the selected devices. When off, only this update runs."
+            description={AUTO_UPDATE_DESCRIPTION}
           />
           {value.autoUpdate && (
             <>
@@ -235,6 +321,7 @@ export function SoftwareUpdateSettingsFields({ value, onChange }: SoftwareUpdate
                     name="autoUpdatePolicy"
                     label="For auto-updates"
                     policy={value.autoUpdatePolicy}
+                    userNotifications={userNotifications}
                     onChange={autoUpdatePolicy => onChange({ ...value, autoUpdatePolicy })}
                   />
                 </div>
@@ -244,25 +331,10 @@ export function SoftwareUpdateSettingsFields({ value, onChange }: SoftwareUpdate
         </div>
       </div>
 
-      {/* Core Alert on the card surface, as a note: it comes with "Keep it auto-updated" and goes with it, since the
-          reinstall is what lets OpenFrame keep a hand-installed app updated, and a one-off update promises no more. The
-          icon sits in a span so Alert's `[&>svg]` positioning does not apply. */}
-      {value.autoUpdate && (
-        <Alert
-          role="note"
-          className="flex items-center gap-[var(--spacing-system-m)] rounded-[6px] border-ods-border bg-ods-card p-[var(--spacing-system-m)]"
-        >
-          <span className="shrink-0 text-ods-text-secondary">
-            <InfoCircleIcon size={24} color="currentColor" />
-          </span>
-          <div className="flex min-w-0 flex-1 flex-col gap-[var(--spacing-system-xxs)]">
-            <p className="text-ods-text-primary text-h3">Apps installed by hand get reinstalled</p>
-            <p className="text-ods-text-secondary text-h6">
-              On the first update, OpenFrame reinstalls them with Winget or Brew so it can keep them updated.
-            </p>
-          </div>
-        </Alert>
-      )}
+      {/* No note that apps installed by hand get reinstalled on the first update: the agent does not do that. A copy no
+          package manager installed is left alone (brew probes it as not installed, winget as "not installed from a
+          winget source"), so it is neither updated nor reinstalled. Reinstalling it with a package manager is Adopt
+          (`adoptSoftware`), which the backend does not implement yet. */}
     </section>
   );
 }

package/src/components/ui/markdown/rich/rich-markdown-renderer.tsx

@@ -101,6 +101,7 @@ const RichMarkdownInner: React.FC<InnerProps> = ({
   demoteMarkdownH1ToH2,
   skeletonSections,
   skeletonLines,
+  skeletonTitle,
 }) => {
   const { ogScraperUrl } = useRichMarkdownRuntime();
 
@@ -158,6 +159,7 @@ const RichMarkdownInner: React.FC<InnerProps> = ({
       allowRemoteMedia
       skeletonSections={skeletonSections}
       skeletonLines={skeletonLines}
+      skeletonTitle={skeletonTitle}
     />
   );
 };
@@ -174,6 +176,7 @@ const RichMarkdownRendererImpl: React.FC<RichMarkdownRendererProps> = ({
   demoteMarkdownH1ToH2 = false,
   skeletonSections,
   skeletonLines,
+  skeletonTitle,
   // Runtime overrides; provider fills the defaults
   redditProxyUrl,
   twitterProxyUrl,
@@ -199,6 +202,7 @@ const RichMarkdownRendererImpl: React.FC<RichMarkdownRendererProps> = ({
         demoteMarkdownH1ToH2={demoteMarkdownH1ToH2}
         skeletonSections={skeletonSections}
         skeletonLines={skeletonLines}
+        skeletonTitle={skeletonTitle}
       />
     </RichMarkdownRuntimeProvider>
   );

package/src/components/ui/page-actions.tsx

@@ -527,9 +527,26 @@ function CompactPrimaryActions({ actions, loading: loadingProp }: { actions: Pag
   );
 }
 
+const subscribeNothing = () => () => {};
+
+/**
+ * False on the server and through hydration, true after: what lets a render use a value only the client measures and
+ * still hydrate into the server's markup.
+ */
+function useHydrated(): boolean {
+  return React.useSyncExternalStore(
+    subscribeNothing,
+    () => true,
+    () => false,
+  );
+}
+
 function MobileBottomActions({ actions, loading: loadingProp }: { actions: PageActionButton[]; loading?: boolean }) {
   const loading = useLoadingScope() || loadingProp;
-  // Over the composer dock where the layout has one.
+  // Over the composer dock where the layout has one. `AppLayout` measures the dock after it mounts, and a page hydrates
+  // after the layout, so the height is often known by the bar's first client render: drawn then, it would not match the
+  // server's markup (no offset). The bar takes it from the render after hydration instead.
+  const hydrated = useHydrated();
   const dockHeight = useComposerDockHeight();
   // Its height, for the chrome that stays clear of it (`useMobileActionBarHeight`).
   const barRef = React.useRef<HTMLDivElement>(null);
@@ -543,7 +560,7 @@ function MobileBottomActions({ actions, loading: loadingProp }: { actions: PageA
     <div
       ref={barRef}
       data-testid="mobile-action-bar"
-      style={dockHeight > 0 ? { bottom: dockHeight } : undefined}
+      style={hydrated && dockHeight > 0 ? { bottom: dockHeight } : undefined}
       className={cn(
         'fixed bottom-0 left-0 right-0 z-50 md:hidden',
         'border-t border-ods-border bg-ods-card',

package/src/types/doc-source.ts

@@ -75,12 +75,12 @@ export interface DocSourceDal<Client = unknown> {
  * Doc-source registry id. The lib's `<DocViewer>` is generic over this union
  * — the hub's `DOC_SOURCES` registry defines the actual ids. Listed here as a
  * type-only union so the lib can flow the id into `DocRenderHandlers.sourceId`
- * without callers having to cast `string` → `'openframe-docs' | 'data-room-docs'`.
+ * without callers having to cast `string` to the union.
  *
  * Adding a new source = add the id here AND register it in the hub. The lib
  * never reaches into the registry — this is purely a type-narrowing handle.
  */
-export type DocSourceId = 'openframe-docs' | 'data-room-docs';
+export type DocSourceId = 'openframe-docs' | 'data-room-docs' | 'company-policies';
 
 /**
  * Result returned by the resolve-link endpoint. Discriminator-style: `success`

package/src/utils/doc-tree-nav.ts

@@ -102,3 +102,30 @@ export function getDocSourceDefaultPath(
   const firstFolderWithReadme = structure.find(node => node.type === 'folder' && node.hasReadme && !!node.path);
   return firstFolderWithReadme?.path ?? null;
 }
+
+/** The first document under a folder (its own files first, then each subfolder's, in order), never a diagram source. */
+export function findFirstDocPath(folder: DocNode): string | null {
+  const children = folder.children ?? [];
+  for (const child of children) {
+    if (child.type === 'file' && !child.path.toLowerCase().endsWith('.mmd')) return child.path;
+  }
+  for (const child of children) {
+    if (child.type === 'folder') {
+      const nested = findFirstDocPath(child);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+/**
+ * The document a source's root shows: its folder index when the tree has one, else its first document (the rule a
+ * folder with no README follows), else null (a tree with no document at all).
+ */
+export function rootDocumentPath(
+  structure: DocNode[],
+  folderIndexFile: string = DEFAULT_FOLDER_INDEX_FILE,
+): string | null {
+  if (structure.some(node => node.type === 'file' && node.path === folderIndexFile)) return folderIndexFile;
+  return findFirstDocPath({ id: '', name: '', slug: '', path: '', type: 'folder', children: structure });
+}