@flamingo-stack/openframe-frontend-core 0.0.563 → 0.0.564-1861.5029.1

package/dist/types/user.d.ts

@@ -1,6 +1,7 @@
 /**
  * Types related to users
  */
+import type { DepartmentRef } from './department';
 /**
  * User profile
  */
@@ -13,7 +14,8 @@ export type UserProfile = {
     company: string | null;
     bio: string | null;
     employee_id: string | null;
-    department: string | null;
+    department_id: string | null;
+    department: DepartmentRef | null;
     role: 'user' | 'super_admin';
     msp_id: string | null;
     created_at: string;

package/dist/types/user.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/types/user.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,IAAI,EAAE,MAAM,GAAG,aAAa,CAAA;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,aAAa,EAAE,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC/H,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;CACtC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;IAClC,mBAAmB,EAAE,OAAO,CAAA;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA"}
+{"version":3,"file":"user.d.ts","sourceRoot":"","sources":["../../src/types/user.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,UAAU,EAAE,aAAa,GAAG,IAAI,CAAA;IAChC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAA;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,aAAa,EAAE,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC/H,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAA;CACtC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;IAClC,mBAAmB,EAAE,OAAO,CAAA;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.563",
+  "version": "0.0.564-1861.5029.1",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/chat/entity-cards/employee-entry-card.tsx

@@ -38,6 +38,12 @@ const STATUS_BADGE_CLASS: Record<string, string> = {
   published: 'bg-ods-success-secondary text-ods-success',
   draft: 'bg-ods-warning-secondary text-ods-warning',
   archived: 'bg-ods-border text-ods-text-secondary',
+  // Design-doc lifecycle (product-hub) — same ODS pairs, no new palette.
+  in_review: 'bg-ods-warning-secondary text-ods-warning',
+  approved: 'bg-ods-success-secondary text-ods-success',
+  building: 'bg-ods-success-secondary text-ods-success',
+  shipped: 'bg-ods-success-secondary text-ods-success',
+  abandoned: 'bg-ods-border text-ods-text-secondary',
 }
 
 /** Shared badge treatment so an entity's own badges (discipline, level) sit

package/src/components/comment-card.tsx

@@ -37,7 +37,16 @@ interface CommentCardProps {
   onDeleteComment?: (commentId: string) => void
   showVendorInfo?: boolean
   compact?: boolean
-  context: 'profile' | 'vendor'
+  /**
+   * `profile` / `vendor` = the OpenMSP comment sections (fixed-height list tiles).
+   * `design_doc` = the product-hub design-doc thread: full-height body, no vendor
+   * chrome, deletability decided by the caller via `comment.canDelete`.
+   */
+  context: 'profile' | 'vendor' | 'design_doc'
+  /** Rendered under the body — badges + per-surface actions (design-doc threads). */
+  footer?: React.ReactNode
+  /** Rendered after the card — nested replies + reply composer (design-doc threads). */
+  children?: React.ReactNode
 }
 
 export function CommentCard({ 
@@ -46,7 +55,9 @@ export function CommentCard({
   onDeleteComment, 
   showVendorInfo = true,
   compact = false,
-  context = 'profile'
+  context = 'profile',
+  footer,
+  children
 }: CommentCardProps) {
   const { user: currentUser } = useAuth()
   
@@ -69,13 +80,21 @@ export function CommentCard({
     if (context === 'vendor' && comment.user) {
       return currentUser.id === comment.user.id
     }
+
+    // Design-doc threads: ownership (own-or-DRI) is computed by the caller with the
+    // shared gate rule and handed in as `canDelete`.
+    if (context === 'design_doc') {
+      return comment.canDelete === true
+    }
     
     return false
   }
 
   const showDeleteButton = canUserDeleteComment()
+  const isThread = context === 'design_doc'
 
   return (
+    <>
     <div className="bg-ods-card border border-ods-border rounded-lg p-4 hover:border-ods-accent transition-all group overflow-hidden w-full max-w-full box-border" style={{ maxWidth: '100%', wordBreak: 'break-word' }}>
       {/* Comment Header */}
       <div className="flex flex-col gap-3 mb-3 min-[420px]:flex-row min-[420px]:items-center min-[420px]:justify-between min-[420px]:gap-2 w-full">
@@ -94,7 +113,7 @@ export function CommentCard({
                 {formatActivityTime(comment.createdAt)}
               </span>
             </>
-          ) : context === 'vendor' && comment.user ? (
+          ) : (context === 'vendor' || isThread) && comment.user ? (
             <UserSummary
               name={comment.user.name}
               email=""
@@ -152,6 +171,12 @@ export function CommentCard({
             </h4>
           </div>
         )}
+        {isThread ? (
+          // Thread bodies are read in full — no fixed height, no clamp.
+          <p className="text-h4 text-ods-text-primary whitespace-pre-wrap" style={{ wordBreak: 'break-word', overflowWrap: 'break-word', maxWidth: '100%' }}>
+            {comment.content}
+          </p>
+        ) : (
         <div className={compact ? "h-[60px] flex items-center" : "h-[72px] flex items-center"}>
           <p className="text-h4 text-ods-text-primary line-clamp-3" style={{ 
             wordBreak: 'break-word', 
@@ -166,7 +191,11 @@ export function CommentCard({
             {comment.content}
           </p>
         </div>
+        )}
+        {footer ? <div className="pt-2 flex flex-wrap items-center gap-2">{footer}</div> : null}
       </div>
     </div>
+    {children}
+    </>
   )
 }

package/src/components/features/clickup-tasks-manager.tsx

@@ -14,13 +14,19 @@ interface ClickUpTasksManagerProps {
   onChange: (tasks: ClickUpTaskLink[]) => void;
   title?: ReactNode; // Support string or ReactNode for badge integration
   className?: string;
+  /**
+   * Per-row label renderer (passthrough to ArrayEntryManager) — lets a host
+   * hydrate the bare task id with the mirror's title/status row.
+   */
+  renderLabel?: (item: ClickUpTaskLink, index: number) => ReactNode;
 }
 
 export function ClickUpTasksManager({
   tasks,
   onChange,
   title = 'ClickUp Roadmap Tasks', // Default title
-  className = ''
+  className = '',
+  renderLabel
 }: ClickUpTasksManagerProps) {
   return (
     <ArrayEntryManager
@@ -33,6 +39,7 @@ export function ClickUpTasksManager({
       addButtonText="Add Task"
       icon={<Lightbulb className="w-5 h-5 text-ods-text-secondary" />}
       className={className}
+      renderLabel={renderLabel}
     />
   );
 }

package/src/components/ui/markdown/rich/__tests__/shortcodes.test.ts

@@ -56,3 +56,50 @@ describe('processShortcodes script stripping', () => {
     expect(output).toContain('<script>');
   });
 });
+
+/**
+ * Design-doc embeds (R11): the spec's `{{figma:FILE_KEY[:NODE_ID]}}` grammar
+ * is rewritten onto the canonical `{{figma:URL}}` rule, and the two Claude
+ * shortcodes alias the OG link card because claude.ai serves
+ * `frame-ancestors 'self'` (it cannot be framed — verified 2026-08-23).
+ */
+describe('processShortcodes design-doc embeds', () => {
+  it('rewrites {{figma:KEY:NODE}} to the canonical design URL and renders the figma embed', () => {
+    const output = processShortcodes('{{figma:aB3xK9:12-405}}');
+    expect(output).toContain('class="figma-embed"');
+    expect(output).toContain('data-figma-url="https://www.figma.com/design/aB3xK9?node-id=12-405"');
+  });
+
+  it('accepts a colon-separated node id and a bare key', () => {
+    expect(processShortcodes('{{figma:aB3xK9:12:405}}')).toContain('node-id=12-405');
+    expect(processShortcodes('{{figma:aB3xK9}}')).toContain('data-figma-url="https://www.figma.com/design/aB3xK9"');
+  });
+
+  it('leaves the existing {{figma:URL}} grammar untouched', () => {
+    const output = processShortcodes('{{figma:https://www.figma.com/proto/aB3xK9/Flows?node-id=1-2}}');
+    expect(output).toContain('data-figma-url="https://www.figma.com/proto/aB3xK9/Flows?node-id=1-2"');
+  });
+
+  it('renders {{claude-artifact:URL}} and {{claude-design:URL}} as link-preview cards, never iframes', () => {
+    const artifact = processShortcodes('{{claude-artifact:https://claude.ai/public/artifacts/abc}}');
+    const design = processShortcodes('{{claude-design:https://claude.ai/design/xyz}}');
+    for (const out of [artifact, design]) {
+      expect(out).toContain('class="link-preview"');
+      expect(out).not.toContain('<iframe');
+    }
+    expect(artifact).toContain('data-url="https://claude.ai/public/artifacts/abc"');
+    expect(design).toContain('data-url="https://claude.ai/design/xyz"');
+  });
+
+  it('attribute-escapes the claude URL like every other shortcode', () => {
+    const output = processShortcodes('{{claude-artifact:https://claude.ai/a?x="1"}}');
+    expect(output).toContain('data-url="https://claude.ai/a?x=&quot;1&quot;"');
+    expect(output).not.toContain('x="1"');
+  });
+
+  it('is rewritten inside a code fence exactly like {{link:}} is (parity, not fence-safety)', () => {
+    const link = processShortcodes('```\n{{link:https://example.com}}\n```');
+    const claude = processShortcodes('```\n{{claude-artifact:https://claude.ai/x}}\n```');
+    expect(claude.includes('link-preview')).toBe(link.includes('link-preview'));
+  });
+});

package/src/components/ui/markdown/rich/shortcodes.ts

@@ -55,6 +55,12 @@ export const processShortcodes = (content: string): string => {
         : `https://twitter.com/twitter/status/${tweetInput}`;
       return `\n\n<div class="tweet-embed" data-tweet-url="${escapeAttr(tweetUrl)}"></div>\n\n`;
     })
+    // Figma by file key (spec grammar): {{figma:FILE_KEY[:NODE_ID]}} → rewritten to the
+    // canonical URL form so the {{figma:URL}} rule below owns the rendering.
+    .replace(/\{\{figma:(?!https?:)([A-Za-z0-9]+)(?::([0-9]+[-:][0-9]+))?\}\}/g, (match, key, node) => {
+      const nodeParam = node ? `?node-id=${String(node).replace(':', '-')}` : '';
+      return `{{figma:https://www.figma.com/design/${key}${nodeParam}}}`;
+    })
     // Figma embeds: {{figma:URL}}
     .replace(/\{\{figma:([^}]+)\}\}/g, (match, url) => {
       return `\n\n<div class="figma-embed" data-figma-url="${escapeAttr(url.trim())}"></div>\n\n`;
@@ -63,6 +69,11 @@ export const processShortcodes = (content: string): string => {
     .replace(/\{\{linkedin:([^}]+)\}\}/g, (match, url) => {
       return `\n\n<div class="linkedin-embed" data-post-url="${escapeAttr(url.trim())}"></div>\n\n`;
     })
+    // Claude artifact / Claude Design: claude.ai serves `frame-ancestors 'self'` (cannot be
+    // framed by anyone), so both render as the OG link card — never an iframe.
+    .replace(/\{\{claude-(?:artifact|design):([^}]+)\}\}/g, (match, url) => {
+      return `\n\n<div class="link-preview" data-url="${escapeAttr(url.trim())}"></div>\n\n`;
+    })
     // Link previews: {{link:URL}}
     .replace(/\{\{link:([^}]+)\}\}/g, (match, url) => {
       return `\n\n<div class="link-preview" data-url="${escapeAttr(url.trim())}"></div>\n\n`;

package/src/types/department.ts

@@ -0,0 +1,39 @@
+/**
+ * Departments — THE single source of truth for the org's department
+ * vocabulary.
+ *
+ * The `departments` table is populated from Google Workspace (the org chart)
+ * by the hub's Google sync, which auto-creates a row the first time it sees a
+ * new department name. `profiles.department_id` is an FK to it; there is no
+ * free-text department column and no enum anywhere in code — every consumer
+ * reads the row (or the embedded `DepartmentRef`) and every picker lists the
+ * ACTIVE rows ordered by `display_order`.
+ *
+ * Hub owner module: `lib/data/department-utils.ts`.
+ */
+
+export interface Department {
+  id: string
+  name: string
+  slug: string
+  description?: string | null
+  parent_department_id?: string | null
+  display_order: number
+  is_active: boolean
+}
+
+/** The embedded shape a reader gets through the `department:departments(…)` PostgREST embed. */
+export type DepartmentRef = Pick<Department, 'id' | 'name' | 'slug'> & {
+  display_order?: number
+}
+
+/** `GET /api/admin/departments?counts=…` row — a department plus how many profiles carry it. */
+export interface DepartmentSummary {
+  id: string
+  name: string
+  slug: string
+  count: number
+}
+
+/** Population a department count is taken over. */
+export type DepartmentCountPopulation = 'directory' | 'scored'

package/src/types/design-doc.ts

@@ -0,0 +1,284 @@
+// Design Doc Types (product-hub)
+// Mirrors product-release.ts — entity + child tables + create/update/filter shapes.
+//
+// Participant sections are keyed by the employee DEPARTMENT (FK to the ONE
+// `departments` table — see department.ts); there is no function enum.
+// Completion-gate math and status transitions live in the hub's
+// `lib/utils/design-doc-gate.ts` (isomorphic, shared by server + client).
+
+import type { EntityAuthor } from './entity-author'
+import type { DeliveryItem } from './delivery'
+import type { DepartmentRef } from './department'
+
+// ---------------------------------------------------------------------------
+// Value vocabularies (string unions + `as const` arrays; badge colors and
+// option labels are declared ONCE in the hub gate module, not here)
+// ---------------------------------------------------------------------------
+
+export const DESIGN_DOC_STATUSES = ['draft', 'in_review', 'approved', 'building', 'shipped', 'abandoned'] as const
+export type DesignDocStatus = (typeof DESIGN_DOC_STATUSES)[number]
+
+export const DESIGN_DOC_TIERS = ['S', 'M', 'L'] as const
+export type DesignDocTier = (typeof DESIGN_DOC_TIERS)[number]
+
+export const DESIGN_DOC_PARTICIPANT_STATUSES = ['pending', 'in_progress', 'completed', 'blocked'] as const
+export type DesignDocParticipantStatus = (typeof DESIGN_DOC_PARTICIPANT_STATUSES)[number]
+
+export const DESIGN_DOC_COMMENT_TYPES = ['blocking', 'suggestion', 'question', 'note'] as const
+export type DesignDocCommentType = (typeof DESIGN_DOC_COMMENT_TYPES)[number]
+
+export const DESIGN_DOC_COMMENT_STATUSES = ['open', 'resolved', 'declined'] as const
+export type DesignDocCommentStatus = (typeof DESIGN_DOC_COMMENT_STATUSES)[number]
+
+export const DESIGN_DOC_LINK_TYPES = ['roadmap_task', 'figma', 'claude_artifact', 'claude_design', 'prototype', 'brief', 'other'] as const
+export type DesignDocLinkType = (typeof DESIGN_DOC_LINK_TYPES)[number]
+
+export const DESIGN_DOC_MEDIA_TYPES = ['image', 'video', 'screenshot', 'demo'] as const
+export type DesignDocMediaType = (typeof DESIGN_DOC_MEDIA_TYPES)[number]
+
+// ---------------------------------------------------------------------------
+// Rows (as returned by the hub DAL — hydrated)
+// ---------------------------------------------------------------------------
+
+/** Minimal profile identity the DAL embeds on participants / comment authors. */
+export interface DesignDocPerson {
+  id: string
+  full_name: string | null
+  avatar_url: string | null
+  job_title?: string | null
+  /** Present on the DRI/detail payload only — never on list payloads. */
+  email?: string | null
+  department_id?: string | null
+  department?: DepartmentRef | null
+}
+
+export interface DesignDocClickUpTask {
+  id: number
+  doc_id: number
+  participant_id: number | null
+  clickup_task_id: string
+  display_order: number | null
+  created_at: string
+  /** Hydrated from the `clickup_tasks` mirror (never the live API). `undefined` = not in the mirror. */
+  task?: DeliveryItem
+}
+
+export interface DesignDocLink {
+  id: number
+  doc_id: number
+  link_type: DesignDocLinkType
+  url: string | null
+  clickup_task_id: string | null
+  title: string | null
+  display_order: number | null
+  created_at: string
+  /** `roadmap_task` links are hydrated from the mirror too. */
+  task?: DeliveryItem
+}
+
+export interface DesignDocMedia {
+  id: number
+  doc_id: number
+  participant_id: number | null
+  media_type: DesignDocMediaType
+  media_url: string
+  title: string | null
+  description: string | null
+  display_order: number | null
+  created_at: string
+  created_by: string | null
+}
+
+/**
+ * A comment. ROOT comments (`parent_comment_id === null`) carry `comment_type`
+ * + `status` and gate approval when `blocking` + `open`; REPLIES carry neither
+ * (single-level threads — a reply to a reply is re-parented to the root).
+ */
+export interface DesignDocComment {
+  id: number
+  doc_id: number
+  participant_id: number | null
+  parent_comment_id: number | null
+  author_id: string | null
+  comment_type: DesignDocCommentType | null
+  title: string | null
+  body: string
+  status: DesignDocCommentStatus | null
+  resolved_at: string | null
+  created_at: string
+  author?: DesignDocPerson | null
+  /** Threaded by the DAL; always `[]` on replies. */
+  replies: DesignDocComment[]
+}
+
+export interface DesignDocParticipant {
+  id: number
+  doc_id: number
+  department_id: string
+  department: DepartmentRef
+  assignee_id: string | null
+  assignee?: DesignDocPerson | null
+  status: DesignDocParticipantStatus
+  content: string | null
+  completed_at: string | null
+  display_order: number | null
+  created_at: string
+  updated_at: string
+  tasks: DesignDocClickUpTask[]
+  media: DesignDocMedia[]
+  /** Section-scoped root comments (threaded). */
+  comments: DesignDocComment[]
+}
+
+export interface DesignDocCompletion {
+  total: number
+  completed: number
+  blocked: number
+  openBlocking: number
+  isComplete: boolean
+  waitingOn: Array<{
+    participantId: number
+    department: DepartmentRef
+    assigneeName: string | null
+    status: DesignDocParticipantStatus
+  }>
+}
+
+/** R13 — what the signed-in viewer still owes on one doc. */
+export interface DesignDocMyOpenWork {
+  /** One person may own several department sections on the same doc. */
+  participants: Array<{ id: number; department: DepartmentRef; status: DesignDocParticipantStatus }>
+  openTasks: DeliveryItem[]
+}
+
+export interface DesignDoc {
+  id: number
+  title: string
+  slug: string
+  tier: DesignDocTier
+  summary: string | null
+  content: string | null
+  status: DesignDocStatus
+  author_id: string | null
+  approved_at: string | null
+  created_at: string
+  updated_at: string
+  /** DRI, hydrated via the shared author hydrator. */
+  author?: EntityAuthor
+  participants: DesignDocParticipant[]
+  links: DesignDocLink[]
+  /** Doc-level comments only (participant-scoped comments ride on their participant). */
+  comments: DesignDocComment[]
+  completion: DesignDocCompletion
+  my_open_work?: DesignDocMyOpenWork
+}
+
+// ---------------------------------------------------------------------------
+// Write shapes
+// ---------------------------------------------------------------------------
+
+export interface DesignDocLinkInput {
+  link_type: DesignDocLinkType
+  url?: string | null
+  clickup_task_id?: string | null
+  title?: string | null
+  display_order?: number
+}
+
+export interface DesignDocClickUpTaskInput {
+  clickup_task_id: string
+  display_order?: number
+}
+
+export interface DesignDocMediaInput {
+  media_type: DesignDocMediaType
+  media_url: string
+  title?: string | null
+  description?: string | null
+  display_order?: number
+}
+
+export interface CreateDesignDocParticipantInput {
+  /** Defaults to the assignee's profile department when omitted. */
+  department_id?: string
+  assignee_id: string
+}
+
+/** Wizard payload (POST /api/admin/design-docs). */
+export interface CreateDesignDocData {
+  title: string
+  slug: string
+  tier: DesignDocTier
+  summary?: string | null
+  /** DRI; defaults to the caller. */
+  author_id?: string | null
+  participants: CreateDesignDocParticipantInput[]
+  links: DesignDocLinkInput[]
+}
+
+/**
+ * Doc-level allowlist (PUT). `status` and `participants` are NOT here — status
+ * only moves through PATCH (the gate), participants only through their routes.
+ */
+export interface UpdateDesignDocData {
+  title?: string
+  slug?: string
+  tier?: DesignDocTier
+  summary?: string | null
+  content?: string | null
+  author_id?: string | null
+  links?: DesignDocLinkInput[]
+  /** OCC token — the `updated_at` the editor seeded from; mismatch → 409. */
+  expected_updated_at?: string
+}
+
+export interface UpdateDesignDocParticipantData {
+  content?: string | null
+  status?: DesignDocParticipantStatus
+  assignee_id?: string | null
+  department_id?: string
+  clickup_tasks?: DesignDocClickUpTaskInput[]
+  media?: DesignDocMediaInput[]
+  expected_updated_at?: string
+}
+
+export interface AddDesignDocParticipantData {
+  /** Defaults to the assignee's profile department when omitted. */
+  department_id?: string
+  assignee_id: string
+}
+
+export interface AddDesignDocCommentData {
+  participant_id?: number | null
+  /** Set for a reply; the DAL re-parents replies-of-replies to the root. */
+  parent_comment_id?: number | null
+  /** Required on root comments, ignored on replies. */
+  comment_type?: DesignDocCommentType
+  title?: string | null
+  body: string
+}
+
+export interface DesignDocFilters {
+  status?: string
+  search?: string
+  mine?: 'open'
+  limit?: number
+  offset?: number
+}
+
+export interface DesignDocListResponse {
+  data: DesignDoc[]
+  count: number
+  /** Server-computed status facet counts (how-i-work feed convention). */
+  facets: { status: Record<string, number> }
+}
+
+export interface DesignDocStats {
+  total: number
+  draft: number
+  in_review: number
+  approved: number
+  building: number
+  waiting_on_me_docs: number
+  waiting_on_me_tasks: number
+}

package/src/types/employee.ts

@@ -1,7 +1,11 @@
+import type { DepartmentRef } from './department';
+
 export interface Employee {
   id: string;
   full_name: string;
-  department: string;
+  /** FK to the ONE `departments` table; `department` is the embedded row. */
+  department_id: string | null;
+  department: DepartmentRef | null;
   avatar_url: string;
   role: string;
   job_title: string;
@@ -16,7 +20,8 @@ export interface EmployeeResponse {
 
 export interface EmployeeProfileData {
   full_name: string;
-  department: string;
+  department_id: string | null;
+  department: DepartmentRef | null;
   avatar_url: string;
   role: string;
   job_title: string;

package/src/types/index.ts

@@ -28,11 +28,13 @@ export * from './customer-interview-ai.types'
 export * from './luma'
 export * from './product-release'
 export * from './delivery'
+export * from './design-doc'
 export * from './vendor'
 export * from './vendor-links'
 export * from './video-processing'
 
 // User and profile types
+export * from './department'
 export * from './employee'
 export * from './profile'
 export * from './team'

package/src/types/marketing.ts

@@ -350,6 +350,7 @@ export type ContentSourceType =
   | 'what_i_shipped'      // What I Shipped employee check-ins (lives on people-hub)
   | 'how_i_work'          // How I Work employee AI-workflow sessions (lives on people-hub)
   | 'faq'                 // FAQ Q&A pair (single-page /faqs index; deep-link by category anchor)
+  | 'design_doc'          // Internal design docs (product-hub admin; preview route only, no public page)
   | 'from_scratch';
 
 export type URLInjectionPreference = 'none' | 'in_post' | 'as_comment';

package/src/types/profile.ts

@@ -1,5 +1,7 @@
 // Profile system TypeScript interfaces for OpenMSP
 
+import type { DepartmentRef } from './department'
+
 export interface ProfileResponse {
   id: string;
   name: string;
@@ -14,7 +16,7 @@ export interface ProfileResponse {
   jobTitle: string | null;
   isCommunityMember: boolean;
   lastSignIn: string | null;
-  department: string | null;
+  department: DepartmentRef | null;
   employeeId: string | null;
 }
 

package/src/types/team.ts

@@ -1,3 +1,5 @@
+import type { DepartmentRef } from './department';
+
 export interface TeamMember {
   id: string;
   employee_id: string;
@@ -9,7 +11,9 @@ export interface TeamMember {
   phone?: string;
   role?: string;
   title?: string;
+  /** Display name of the department (presentational shape); `department_id` is the FK. */
   department?: string;
+  department_id?: string | null;
   team?: string;
   manager_id?: string;
   profile_image_url?: string;
@@ -33,7 +37,11 @@ export interface TeamMember {
 
 export interface TeamSection {
   title: string;
+  /** Department display name. */
   department: string;
+  department_id: string | null;
+  /** `departments.display_order` — sections sort by it (no name sentinels). */
+  display_order: number;
   description: string;
   members: TeamMember[];
 }
@@ -45,5 +53,5 @@ export interface TeamData {
 
 export interface GetTeamOptions {
   includeInactive?: boolean;
-  department?: string;
+  departmentId?: string;
 }