@flamingo-stack/openframe-frontend-core 0.0.847 → 0.0.849

package/src/components/ui/markdown/engine.tsx

@@ -35,7 +35,11 @@ import type { PluggableList } from 'unified';
 import type { ResolveLinkResult } from '../../../types/doc-source';
 import { readAppOrigins, SERVER_APP_ORIGINS, subscribeAppOrigins } from '../../../utils/app-origins';
 import { cn } from '../../../utils/cn';
-import { TextLineSkeleton } from '../../loading/unified-skeleton';
+import {
+  TextLineSkeleton,
+  TextLinesByBreakpointSkeleton,
+  type TextLinesByBreakpoint,
+} from '../../loading/unified-skeleton';
 import { LoadingItems, useLoadingScope } from '../loading-scope';
 import { buildBaseComponents, MARKDOWN_H1_CLASS, MARKDOWN_H2_CLASS, MARKDOWN_PARAGRAPH_CLASS } from './base-components';
 import { MarkdownMediaOriginsContext } from './external-media-notice';
@@ -193,8 +197,8 @@ export interface MarkdownEngineProps {
    * sections, each a heading and its paragraphs. Unset, one paragraph of `skeletonLines` lines.
    */
   skeletonSections?: number;
-  /** Lines of the one paragraph a loading body draws when it names no sections. Default 3. */
-  skeletonLines?: number;
+  /** Lines of the one paragraph a loading body draws when it names no sections, per width. Default 3 at every width. */
+  skeletonLines?: TextLinesByBreakpoint;
   /** A loading body opens with its own `# ` title (a legal document's): its title row is drawn first. */
   skeletonTitle?: boolean;
   /** The content is still being read: the body draws its skeleton (the `skeleton*` shape). A loading scope does the
@@ -203,16 +207,19 @@ export interface MarkdownEngineProps {
 }
 
 /** Lines a loading body draws when its caller names no shape. */
-export const MARKDOWN_SKELETON_LINES = 3;
+export const MARKDOWN_SKELETON_LINES: TextLinesByBreakpoint = { phone: 3, md: 3, lg: 3 };
 /** Paragraphs under each heading of a loading body, and their lines. */
-const SKELETON_SECTION_PARAGRAPHS = [3, 2] as const;
+const SKELETON_SECTION_PARAGRAPHS: readonly TextLinesByBreakpoint[] = [
+  { phone: 3, md: 3, lg: 3 },
+  { phone: 2, md: 2, lg: 2 },
+];
 /**
- * Lines a typical body's opening line set takes, on a phone (below `content-md`) and from `content-md`: a document's
+ * Lines a typical body's opening line set takes, per width: a document's
  * `# ` title wraps on a phone, and the opening paragraph every post and legal document starts with runs a few lines.
  * Typical lengths, never one record's: a longer record growing past them is a settle below its own lines.
  */
-const SKELETON_TITLE_LINES = { phone: 2, wide: 1 } as const;
-const SKELETON_LEAD_LINES = { phone: 5, wide: 3 } as const;
+const SKELETON_TITLE_LINES: TextLinesByBreakpoint = { phone: 2, md: 1, lg: 1 };
+const SKELETON_LEAD_LINES: TextLinesByBreakpoint = { phone: 5, md: 3, lg: 3 };
 /** The renderer's own frame: read by the engine and by its skeleton. */
 /** The renderer's root class, on the rendered document and on every skeleton of one: it names a markdown body. */
 export const MARKDOWN_RENDERER_CLASS = 'simple-markdown-renderer';
@@ -467,31 +474,15 @@ export const MarkdownEngine = memo(function MarkdownEngineGate(props: MarkdownEn
   return <MarkdownEngineImpl {...props} />;
 });
 
-/** A paragraph of `lines` lines at the body's own paragraph type, as one bar of its line height. */
-function ParagraphBar({ lines, className }: { lines: number; className: string }) {
+/** A paragraph of its `lines` per width at the body's own paragraph type. */
+function ParagraphBar({ lines, className }: { lines: TextLinesByBreakpoint; className: string }) {
   return (
     <div className={className}>
-      <TextLineSkeleton type="inherit" lines={lines} className="w-full" />
+      <TextLinesByBreakpointSkeleton lines={lines} />
     </div>
   );
 }
 
-/** Lines of a text run per breakpoint: on a phone, and from `content-md`. */
-interface SkeletonLinesByBreakpoint {
-  phone: number;
-  wide: number;
-}
-
-/** A text run of the lines it takes on a phone and from `content-md` (the content area's own steps). */
-function LinesByBreakpoint({ lines, as = 'div' }: { lines: SkeletonLinesByBreakpoint; as?: 'div' | 'span' }) {
-  return (
-    <>
-      <TextLineSkeleton type="inherit" as={as} lines={lines.phone} className="w-full content-md:hidden" />
-      <TextLineSkeleton type="inherit" as={as} lines={lines.wide} className="hidden w-full content-md:flex" />
-    </>
-  );
-}
-
 /**
  * A markdown body while it is read: the renderer's own frame and type. With `sections`, the body's opening paragraph
  * (a typical length per breakpoint), then each section a REAL `<h2>` (the renderer's heading classes) holding a bar,
@@ -506,7 +497,7 @@ export function MarkdownEngineSkeleton({
   className = '',
 }: {
   sections?: number;
-  lines?: number;
+  lines?: TextLinesByBreakpoint;
   textSize?: TextSizeConfig;
   /** The body opens with its own `# ` title (a legal document's, demoted to an `h2`): its H1 row is drawn first. */
   title?: boolean;
@@ -522,12 +513,12 @@ export function MarkdownEngineSkeleton({
         <div className={ARTICLE_CLASS}>
           {title && (
             <h2 className={cn(MARKDOWN_H1_CLASS, textSizes.h1)}>
-              <LinesByBreakpoint lines={SKELETON_TITLE_LINES} as="span" />
+              <TextLinesByBreakpointSkeleton lines={SKELETON_TITLE_LINES} as="span" />
             </h2>
           )}
           {sections ? (
             <div className={paragraphClass}>
-              <LinesByBreakpoint lines={SKELETON_LEAD_LINES} />
+              <TextLinesByBreakpointSkeleton lines={SKELETON_LEAD_LINES} />
             </div>
           ) : null}
           {sections ? (

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/people-cell.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import { cn } from '../../utils/cn';
 import { personFirstName } from '../../utils/format';
 import { TextLineSkeleton } from '../loading/unified-skeleton';
 import { AvatarStack } from './avatar-stack';
@@ -48,6 +49,11 @@ export interface PersonCellProps {
   size?: 'sm' | 'lg';
   /** The person is still being read: the cell draws its skeleton at its size. A loading scope does the same. */
   loading?: boolean;
+  /**
+   * `2` (default): the name and its second line. `1`: the name alone, one line, with the second line in a tooltip:
+   * for a table whose rows are one line in every column but the first.
+   */
+  lines?: 1 | 2;
 }
 
 const PERSON_CELL_SIZE = {
@@ -67,29 +73,35 @@ export function PersonCell({
   actionTitle,
   size = 'sm',
   loading,
+  lines = 2,
 }: PersonCellProps) {
   // In a page's loading state (or while the host reads the person) the cell is its skeleton.
-  if (useLoadingScope() || loading) return <PersonCellSkeleton size={size} />;
+  if (useLoadingScope() || loading) return <PersonCellSkeleton size={size} lines={lines} />;
   const displayName = name || fallbackName;
   const scale = PERSON_CELL_SIZE[size];
+  const nameLine = (
+    <TruncateText
+      variant={scale.primary}
+      className={onClick ? 'text-ods-accent group-hover/person-cell:underline' : undefined}
+    >
+      {displayName}
+    </TruncateText>
+  );
   const row = (
     <div className={`group/person-cell ${PERSON_ROW_CLASS} ${scale.gap}`}>
       <SquareAvatar size={scale.avatar} src={avatarUrl ?? undefined} alt={displayName} fallback={displayName} />
       <div className="min-w-0 flex-1">
-        <TruncateText
-          variant={scale.primary}
-          className={onClick ? 'text-ods-accent group-hover/person-cell:underline' : undefined}
-        >
-          {displayName}
-        </TruncateText>
-        <TruncateText variant="h6" tone="secondary">
-          {secondary === undefined ? ' ' : secondary || '·'}
-        </TruncateText>
+        {nameLine}
+        {lines === 2 ? (
+          <TruncateText variant="h6" tone="secondary">
+            {secondary === undefined ? ' ' : secondary || '·'}
+          </TruncateText>
+        ) : null}
       </div>
     </div>
   );
-  if (!onClick) return row;
-  return (
+  // A clickable cell is a button in both layouts, so `onClick` and `actionTitle` are never dropped by `lines`.
+  const cell = onClick ? (
     <Button
       variant="transparent"
       onClick={onClick}
@@ -100,18 +112,34 @@ export function PersonCell({
     >
       {row}
     </Button>
+  ) : (
+    row
+  );
+  // One line: the second line is not drawn, so it is the cell's tooltip.
+  return lines === 1 && secondary ? (
+    <FloatingTooltip content={`${displayName} · ${secondary}`} triggerClassName="min-w-0 max-w-full">
+      {cell}
+    </FloatingTooltip>
+  ) : (
+    cell
   );
 }
 
 /** The cell while it loads: the SAME avatar box, gap and two lines (the name's type step, then the caption's). */
-function PersonCellSkeleton({ size = 'sm' }: { size?: PersonCellProps['size'] }) {
+function PersonCellSkeleton({
+  size = 'sm',
+  lines = 2,
+}: {
+  size?: PersonCellProps['size'];
+  lines?: PersonCellProps['lines'];
+}) {
   const scale = PERSON_CELL_SIZE[size];
   return (
     <div className={`${PERSON_ROW_CLASS} ${scale.gap}`} aria-hidden>
       <SquareAvatar loading size={scale.avatar} />
       <div className="flex min-w-0 flex-1 flex-col">
         <TextLineSkeleton type={scale.primary} className="w-3/4" />
-        <TextLineSkeleton type="h6" className="w-1/2" />
+        {lines === 2 ? <TextLineSkeleton type="h6" className="w-1/2" /> : null}
       </div>
     </div>
   );
@@ -130,14 +158,16 @@ export interface PeopleCellProps {
   people: PeopleCellPerson[];
   /** Shown when the list is empty — the same slot `PersonCell` fills. */
   fallbackName?: string;
+  /** `1`: one line for one person or several (see `PersonCellProps.lines`). */
+  lines?: 1 | 2;
 }
 
 /** Positions the multi-person stack reserves: two faces, or one face and "+N". */
 const PEOPLE_CELL_STACK_SLOTS = 2;
 
-export function PeopleCell({ people, fallbackName = 'Unassigned' }: PeopleCellProps) {
+export function PeopleCell({ people, fallbackName = 'Unassigned', lines = 2 }: PeopleCellProps) {
   // In a page's loading state the people are read: the cell is a person cell's skeleton.
-  if (useLoadingScope()) return <PersonCellSkeleton />;
+  if (useLoadingScope()) return <PersonCellSkeleton lines={lines} />;
   if (people.length <= 1) {
     const [person] = people;
     return (
@@ -146,6 +176,7 @@ export function PeopleCell({ people, fallbackName = 'Unassigned' }: PeopleCellPr
         avatarUrl={person?.avatarUrl}
         secondary={person ? person.secondary : undefined}
         fallbackName={fallbackName}
+        lines={lines}
       />
     );
   }
@@ -163,7 +194,12 @@ export function PeopleCell({ people, fallbackName = 'Unassigned' }: PeopleCellPr
             people={people.map(p => ({ key: p.key, name: p.name || 'Unknown', avatarUrl: p.avatarUrl }))}
           />
         </div>
-        <p className="line-clamp-2 min-w-0 flex-1 break-words text-ods-text-primary text-h6">
+        <p
+          className={cn(
+            'min-w-0 flex-1 break-words text-ods-text-primary text-h6',
+            lines === 1 ? 'line-clamp-1' : 'line-clamp-2',
+          )}
+        >
           <span aria-hidden>{people.map(p => personFirstName(p.name, 'Unknown')).join(' & ')}</span>
           <span className="sr-only">{fullNames}</span>
         </p>

package/src/components/ui/progress-bar.tsx

@@ -27,6 +27,12 @@ type ProgressBarProps = {
   height?: number; // desktop height (px)
   mobileHeight?: number; // mobile height (px)
   inverted?: boolean; // if true, high values are good (green), low values are bad (red)
+  /**
+   * `threshold` (default): the fill takes the success, warning or error colour by the thresholds. `neutral`: the fill
+   * is the secondary text colour at every value, for a count that is progress, not a health reading (a sign-off
+   * count), so a partial bar never reads as an error.
+   */
+  tone?: 'threshold' | 'neutral';
   /** The value is still being read: the bar draws its `ProgressBarSkeleton` at its own height. A loading scope does
    *  the same. */
   loading?: boolean;
@@ -42,6 +48,7 @@ export const ProgressBar: React.FC<ProgressBarProps> = ({
   height = PROGRESS_BAR_HEIGHT.desktop,
   mobileHeight = PROGRESS_BAR_HEIGHT.mobile,
   inverted = false,
+  tone = 'threshold',
   loading: loadingProp,
 }) => {
   // ONE switch: in a page's loading state (or while the host reads the value) the bar is its skeleton.
@@ -76,6 +83,7 @@ export const ProgressBar: React.FC<ProgressBarProps> = ({
 
   // Pick color based on thresholds using ODS design tokens
   const getColor = () => {
+    if (tone === 'neutral') return 'var(--color-text-secondary)';
     if (inverted) {
       // Inverted: high values = good (green), low values = bad (red)
       // For battery health: 100% = green, <30% = red

package/src/components/ui/tag.tsx

@@ -201,6 +201,20 @@ function isEmptyTagLabel(label: React.ReactNode): boolean {
   return label == null || label === false || (typeof label === 'string' && label.trim() === '');
 }
 
+/** The tones a badge colour keeps when it is drawn as a tag. */
+const BADGE_COLOR_TAG_TONES = ['success', 'warning', 'error'] as const;
+
+/**
+ * THE tag variant for a badge colour that is data (a `StatusBadge` colour scheme a vocabulary row stores): the three
+ * semantic tones carry over, every other colour reads grey. Every card that draws such a colour as a tag reads it
+ * here, so a status is the same tone in a badge and in a chat card.
+ */
+export function tagVariantForBadgeColor(
+  color: string | null | undefined,
+): (typeof BADGE_COLOR_TAG_TONES)[number] | 'grey' {
+  return BADGE_COLOR_TAG_TONES.find(tone => tone === color) ?? 'grey';
+}
+
 export { Tag, tagVariants };
 
 /**

package/src/types/design-doc.ts

@@ -3,9 +3,11 @@
 //
 // Participant sections are keyed by the employee DEPARTMENT (FK to the ONE
 // `departments` table — see department.ts); there is no function enum.
-// A doc has no status: it is READY when every section is signed off and no
-// blocking comment is open. That math lives in the hub's
+// A doc's READINESS is derived: it is ready when every section is signed off and
+// no blocking comment is open. That math lives in the hub's
 // `lib/utils/design-doc-gate.ts` (isomorphic, shared by server + client).
+// Beside it a PERSON may set a lifecycle status (`lifecycle_status`: postponed,
+// shipped, archived), which replaces readiness on every surface while it is set.
 
 // MIGRATION NOTE (2026-09-11). This file dropped `status`, `DesignDocStatus`,
 // `DesignDocStatusTransition`, `approved_at`, `dri_vacated_by`, `by_status` and
@@ -53,7 +55,15 @@ import type { EntityAuthor } from './entity-author';
 /** One value of `design_doc_vocabulary.kind` — the STRUCTURAL list (one per
  *  value column), the only design-doc vocabulary that is code. */
 export type DesignDocVocabularyKind =
-  'tier' | 'spec_mode' | 'participant_status' | 'comment_type' | 'comment_status' | 'link_type' | 'media_type';
+  | 'tier'
+  | 'spec_mode'
+  | 'participant_status'
+  | 'comment_type'
+  | 'comment_status'
+  | 'link_type'
+  | 'media_type'
+  | 'lifecycle_status'
+  | 'readiness';
 
 /** A `design_doc_vocabulary` row, as the DAL and the vocabulary API return it. */
 export interface DesignDocVocabularyOption {
@@ -107,6 +117,24 @@ export type DesignDocCommentStatus = string;
 export type DesignDocLinkType = string;
 /** A `design_doc_vocabulary.value` of kind `media_type`. */
 export type DesignDocMediaType = string;
+/**
+ * A `design_doc_vocabulary.value` of kind `lifecycle_status`: a status a PERSON sets (postponed, shipped, archived),
+ * beside the readiness the sign-offs decide. Null on a doc = active, and its readiness shows.
+ */
+export type DesignDocLifecycleStatus = string;
+/**
+ * A `design_doc_vocabulary.value` of kind `readiness`: the stage the sign-offs put a doc in (not ready, in active
+ * work, blocked, ready to build). The hub picks the row by its role; the words and the colour are the row's.
+ */
+export type DesignDocReadiness = string;
+
+/** A vocabulary value as a card shows it, resolved by the hub so a surface without the vocabulary can draw it. */
+export interface DesignDocVocabularyDisplay {
+  value: string;
+  label: string;
+  /** A `StatusBadge` colorScheme name. */
+  color_scheme: string;
+}
 
 // ---------------------------------------------------------------------------
 // Rows (as returned by the hub DAL — hydrated)
@@ -258,6 +286,15 @@ export interface DesignDoc {
   comments: DesignDocComment[];
   completion: DesignDocCompletion;
   my_open_work?: DesignDocMyOpenWork;
+  /** The status a person set (postponed, shipped, archived); null = active, its readiness shows. */
+  lifecycle_status: DesignDocLifecycleStatus | null;
+  /** That status as the vocabulary words it, resolved by the hub (null when none is set). */
+  lifecycle?: DesignDocVocabularyDisplay | null;
+  /** When the status was last set or cleared, and by whom. */
+  lifecycle_status_changed_at: string | null;
+  lifecycle_status_changed_by?: DesignDocPerson | null;
+  /** The stage its sign-offs put it in, as the vocabulary words it, resolved by the hub. */
+  readiness?: DesignDocVocabularyDisplay | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -328,6 +365,8 @@ export interface UpdateDesignDocData {
    */
   feature_lead_ids?: string[];
   links?: DesignDocLinkInput[];
+  /** A `lifecycle_status` value, or null to make the doc active again. Anyone who may edit the doc may set it. */
+  lifecycle_status?: DesignDocLifecycleStatus | null;
   /** OCC token — the `updated_at` the editor seeded from; mismatch → 409. */
   expected_updated_at?: string;
 }
@@ -358,10 +397,18 @@ export interface AddDesignDocCommentData {
   body: string;
 }
 
-/** The dashboard's readiness filter (`?ready=`). */
-export type DesignDocReadyFilter = 'ready' | 'not_ready';
+/** The dashboard's readiness filter (`?ready=`): one `readiness` value. */
+export type DesignDocReadyFilter = DesignDocReadiness;
+
+/**
+ * The dashboard's status filter (`?status=`): `active` (no lifecycle status set, the default) or one
+ * `lifecycle_status` value.
+ */
+export type DesignDocLifecycleFilter = 'active' | DesignDocLifecycleStatus;
 
 export interface DesignDocFilters {
+  /** Defaults to `active`: a doc a person postponed, shipped or archived is listed only under its own status. */
+  lifecycle?: DesignDocLifecycleFilter;
   ready?: DesignDocReadyFilter;
   /** One or more `spec_mode` values (CSV on the wire). */
   spec_mode?: string;
@@ -378,16 +425,18 @@ export interface DesignDocListResponse {
    *  filter itself — so a filtered row still shows what the other value holds. */
   facets: {
     spec_mode: Record<string, number>;
-    /** The same over readiness (`ready` / `not_ready`), MINUS the ready filter itself: the filter row's options. */
-    ready: Record<'ready' | 'not_ready', number>;
+    /** The same over readiness (each `readiness` value), MINUS the ready filter itself: the filter row's options. */
+    ready: Record<DesignDocReadiness, number>;
+    /** The same over the status filter (`active` and each `lifecycle_status` value), MINUS the status filter itself. */
+    lifecycle: Record<string, number>;
   };
 }
 
+/** Counted over ACTIVE docs (no lifecycle status), so postponed, shipped and archived docs never inflate open work. */
 export interface DesignDocStats {
   total: number;
-  /** Docs whose every section is signed off with no open blocking comment. */
-  ready: number;
-  not_ready: number;
+  /** How many active docs each `readiness` value holds, zeros included. */
+  readiness: Record<DesignDocReadiness, number>;
   waiting_on_me_docs: number;
   waiting_on_me_tasks: number;
 }

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/design-doc-readiness.ts

@@ -1,34 +1,33 @@
 /**
- * A design doc's readiness in words — THE wording every surface prints (the hub's design-docs screens, its doc
- * page, the lib's design-doc card): "Ready to build" once every department section is signed off and no blocking
- * comment is open, else "Not ready", and the sign-off caption beside it. Pure, zero-import beyond the type.
+ * A design doc's status as every surface draws it (the hub's design-docs screens, its doc page, the lib's design-doc
+ * cards), and its sign-off caption.
+ *
+ * Both halves of the status are vocabulary rows the hub resolves onto the doc, so no surface holds a word or a colour:
+ *   - its READINESS (`doc.readiness`): the stage the sign-offs put it in (not ready, in active work, blocked, ready to
+ *     build), picked by the hub from the `readiness` rows by role;
+ *   - a LIFECYCLE status a person set (`doc.lifecycle`: postponed, shipped, archived). While one is set it is what the
+ *     doc shows; cleared, the readiness shows again.
+ *
+ * The sign-off caption is counts only ("4/6 signed off · 1 blocking"): the status has its own badge.
+ * Pure, zero-import beyond the type.
  */
-import type { DesignDocCompletion } from '../types/design-doc';
+import type { DesignDoc, DesignDocCompletion, DesignDocVocabularyDisplay } from '../types/design-doc';
 
-export const DESIGN_DOC_READINESS = ['ready', 'not_ready'] as const;
-export type DesignDocReadiness = (typeof DESIGN_DOC_READINESS)[number];
-
-/** Each readiness's label and badge colour (a `StatusBadge` scheme). */
-export const DESIGN_DOC_READINESS_DISPLAY: Record<
-  DesignDocReadiness,
-  { label: string; scheme: 'success' | 'default' }
-> = {
-  ready: { label: 'Ready to build', scheme: 'success' },
-  not_ready: { label: 'Not ready', scheme: 'default' },
-};
-
-/** Ready to build ⇔ `completion.isComplete` (every section signed off, no open blocking comment). */
-export const designDocReadiness = (completion: Pick<DesignDocCompletion, 'isComplete'>): DesignDocReadiness =>
-  completion.isComplete ? 'ready' : 'not_ready';
+/** What the doc's status badge says: its lifecycle status when a person set one, else its readiness (null from a hub
+ *  that resolves neither). */
+export function designDocStatusDisplay(
+  doc: Pick<DesignDoc, 'lifecycle' | 'readiness'>,
+): DesignDocVocabularyDisplay | null {
+  return doc.lifecycle ?? doc.readiness ?? null;
+}
 
-/** "4/6 reviews signed off" */
+/** "4/6 signed off" */
 export function formatCompletionLabel(completion: Pick<DesignDocCompletion, 'total' | 'completed'>): string {
-  return `${completion.completed}/${completion.total} reviews signed off`;
+  return `${completion.completed}/${completion.total} signed off`;
 }
 
-/** The SAME label plus readiness and the blocking veto (the dashboard row, the doc page, the card). */
+/** The SAME count plus the blocking veto ("4/6 signed off · 1 blocking"): the dashboard row, the doc page, the card. */
 export function formatCompletionLabelWithBlockers(completion: DesignDocCompletion): string {
   const base = formatCompletionLabel(completion);
-  if (completion.isComplete) return `${DESIGN_DOC_READINESS_DISPLAY.ready.label} · ${base}`;
   return completion.openBlocking > 0 ? `${base} · ${completion.openBlocking} blocking` : base;
 }

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 });
+}

package/src/utils/list-url.ts

@@ -99,7 +99,8 @@ const BUILDERS: Record<string, (ids: string[], base: string) => string> = {
   slack_message: (ids, b) => `${b}/api/slack-community/messages?ids=${ids.join(',')}`,
   hubspot_ticket: (ids, b) => `${b}/api/tickets/internal?ids=${ids.join(',')}`,
   hubspot_ticket_anon: (ids, b) => `${b}/api/tickets/known-issues?ids=${ids.join(',')}`,
-  data_room_doc: (ids, b) => `${b}/api/data-room/documents?ids=${ids.join(',')}`,
+  data_room_doc: (ids, b) => `${b}/api/libraries/data-room/documents?ids=${ids.join(',')}`,
+  policy_doc: (ids, b) => `${b}/api/libraries/company-policies/documents?ids=${ids.join(',')}`,
   markdown: (ids, b) => `${b}/api/docs/pages?ids=${ids.join(',')}`,
   financial_kpi: (ids, b) => `${b}/api/financials/kpis?ids=${ids.join(',')}`,
   cap_table: (ids, b) => `${b}/api/financials/cap-table?ids=${ids.join(',')}`,

package/src/utils/source-grouping.ts

@@ -27,13 +27,13 @@ import { defaultDocumentTypeForTableId, getSourceLabel } from './source-icons';
 
 /**
  * Doc-table documentTypes: whole documents with their own viewer (markdown =
- * product docs, data_room_doc = data room). They carry an in-app `path` (handed
+ * product docs, data_room_doc = data room, policy_doc = company policies). They carry an in-app `path` (handed
  * to the host's composer as the slug), and a server never folds them
  * into one citation (`groupsByTable`); the strip still draws them as one chip
  * per table. The hub's per-source contract test pins this list to its
  * doc-table configs.
  */
-export const DOC_TABLE_TYPES = ['markdown', 'data_room_doc'] as const;
+export const DOC_TABLE_TYPES = ['markdown', 'data_room_doc', 'policy_doc'] as const;
 
 /**
  * Which tables a SERVER folds into one citation: rows of a knowledge table

package/src/utils/source-icons.ts

@@ -29,6 +29,7 @@ export const SOURCE_ICON_NAMES: Record<string, string> = {
   // Doc tables
   'openframe-docs': 'openframe',
   'data-room-docs': 'shield',
+  'company-policies': 'book-open',
 
   // CMS / programs
   'blog-posts': 'newspaper',
@@ -136,6 +137,7 @@ export const SOURCE_LABELS_BY_TABLE: Record<string, string> = {
   // Doc tables
   'openframe-docs': 'OpenFrame Docs',
   'data-room-docs': 'Data Room',
+  'company-policies': 'Company Policies',
 
   // CMS / programs
   'blog-posts': 'Blog Posts',
@@ -242,6 +244,7 @@ export const DEFAULT_DOCUMENT_TYPE_TO_TABLE_ID: Record<string, string> = {
   // Doc tables
   markdown: 'openframe-docs',
   data_room_doc: 'data-room-docs',
+  policy_doc: 'company-policies',
 
   // CMS / programs
   blog_post: 'blog-posts',

package/dist/components/docs/skeletons.d.ts

@@ -1,25 +0,0 @@
-export declare function MarkdownSkeleton({ region, }?: {
-    /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
-    region?: boolean;
-}): import("react").JSX.Element;
-/**
- * Embed-style skeleton — matches the iframe loading state for `pdf`,
- * `google_sheet`, `figma`, and `file` document types. Used by
- * `<DocsHubPage>` as the default for non-markdown documentTypes.
- *
- * The skeleton is documentType-aware so its layout matches the actual
- * viewer that will replace it:
- *   - `pdf`                  → header with title + TWO buttons (Preview, Download)
- *   - `google_sheet`/`figma` → header with title + ONE button/toggle
- *   - `file`                 → centered FileDownloadCard-style box
- *   - undefined / others     → generic (1-button header)
- */
-export interface EmbedSkeletonProps {
-    /** When provided, the header layout matches the eventual viewer's
-     *  button count + arrangement, so the layout doesn't shift on load. */
-    documentType?: 'pdf' | 'google_sheet' | 'figma' | 'file' | string;
-    /** The loading state announces itself (`LoadingRegion`). `false` inside another loading region. Default `true`. */
-    region?: boolean;
-}
-export declare function EmbedSkeleton({ documentType, region }?: EmbedSkeletonProps): import("react").JSX.Element;
-//# sourceMappingURL=skeletons.d.ts.map

package/dist/components/docs/skeletons.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"skeletons.d.ts","sourceRoot":"","sources":["../../../src/components/docs/skeletons.tsx"],"names":[],"mappings":"AA2BA,wBAAgB,gBAAgB,CAAC,EAC/B,MAAa,GACd,GAAE;IACD,mHAAmH;IACnH,MAAM,CAAC,EAAE,OAAO,CAAC;CACb,+BA2BL;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,kBAAkB;IACjC;2EACuE;IACvE,YAAY,CAAC,EAAE,KAAK,GAAG,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAClE,mHAAmH;IACnH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,aAAa,CAAC,EAAE,YAAY,EAAE,MAAa,EAAE,GAAE,kBAAuB,+BAiDrF"}