@validation-os/dashboard 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,143 @@
 import * as react from 'react';
-import { Collection, AnyRecord } from '@validation-os/core';
+import { ReactNode } from 'react';
+import { Collection, AnyRecord, Relation } from '@validation-os/core';
+import { Progress, MoverKind, TrajectoryPoint } from '@validation-os/core/derivation';
+
+/**
+ * Everything the instance passes — config only, never secrets. The API base
+ * path points at where the Clerk-gated `@validation-os/api` routes are mounted;
+ * the backend label (from the connector config) shows in the topbar; branding
+ * and the signed-in user are optional cosmetics. Auth is the instance's Clerk
+ * provider that this renders within — no credential reaches the package.
+ */
+interface DashboardConfig {
+    /** Where the API is mounted (default `/api`). */
+    basePath?: string;
+    /** Topbar backend indicator, e.g. "Firestore · doshi-crm". */
+    backendLabel?: string;
+    /** Optional product branding for the sidebar. */
+    branding?: {
+        /** Product name shown next to the mark (default "Validation-OS"). */
+        name?: string;
+        /** One or two letters for the square mark (default "V"). */
+        initials?: string;
+        /** A logo image for the square mark; overrides `initials` when set. */
+        logoUrl?: string;
+    };
+    /** Optional agent label shown in the topbar, e.g. "Claude Code". */
+    agentLabel?: string;
+    /** The signed-in user, for the topbar avatar + name. */
+    user?: {
+        name?: string;
+        caption?: string;
+    };
+    /** Restrict/reorder the registers shown; defaults to all, in order. */
+    registers?: Collection[];
+}
+interface ValidationOSDashboardProps {
+    config?: DashboardConfig;
+}
+/**
+ * The entire styled dashboard as one mountable app (spec OPS-1280): the frame —
+ * sidebar composing register nav + live counts, topbar with the backend
+ * indicator and user — and the register views (browse → drawer → understanding)
+ * it composes from the package's own bricks. Navigation is owned here, not the
+ * host router: the active register lives in client state (synced to the URL
+ * hash), so the instance mounts this at one route and wires no routing. Styled
+ * by the package's own token sheet — the instance imports `styles.css` once and
+ * builds no UI.
+ */
+declare function ValidationOSDashboard({ config }: ValidationOSDashboardProps): react.JSX.Element;
+
+/**
+ * Pure presentation logic for the dashboard's visual primitives — status→tone,
+ * risk→fraction/level, the sparkline path, and count/number formatting. Kept
+ * free of React and the DOM so the mapping that drives every pill, bar and
+ * sparkline is unit-tested at this seam (spec story 13), and the components stay
+ * thin wrappers over it.
+ */
+/** A pill/fill tone — maps onto the `--vos-good/warn/crit/accent` tokens. */
+type Tone = "good" | "warn" | "crit" | "accent" | "neutral";
+/**
+ * A record's Status → a pill tone. Live/concluded read good, testing/running
+ * read warn, invalidated/rejected read crit; everything else (Proposed, and any
+ * status we don't recognise) stays neutral rather than guessing a colour. Case-
+ * and whitespace-insensitive.
+ */
+declare function statusTone(status: string | null | undefined): Tone;
+/** Risk thresholds — a belief is critical at ≥60, watch at ≥30 (prototype). */
+declare const RISK_CRIT = 60;
+declare const RISK_WARN = 30;
+/** Risk (0–100) → a tone for the bar fill and the number. */
+declare function riskLevel(risk: number): Tone;
+/** Risk (0–100) → the bar's fill fraction (0–1), clamped. */
+declare function riskFraction(risk: number): number;
+/** Confidence (signed) → the tone for its number: negative reads crit. */
+declare function confidenceTone(confidence: number): Tone;
+/** A signed number rendered with an explicit sign: `+6`, `-3`, `0`. */
+declare function formatSigned(n: number): string;
+/** A count for the nav/tiles, thousands-separated. */
+declare function formatCount(n: number): string;
+/**
+ * An SVG polyline `d` for a sparkline over `values`, fit to a `width`×`height`
+ * box with a 2px inset. The vertical domain defaults to the data's own range
+ * (with 0 always included, so a signed series keeps its baseline meaningful);
+ * pass `min`/`max` to pin it — e.g. −100…100 for Confidence. Returns "" for
+ * fewer than two points (nothing to draw).
+ */
+declare function sparklinePath(values: number[], width: number, height: number, min?: number, max?: number): string;
+
+/** A colored status pill — tone from the status, the label shown verbatim. */
+declare function StatusPill({ status }: {
+    status: string | null | undefined;
+}): react.JSX.Element;
+/**
+ * A risk bar (0–100) plus its number, both toned by threshold: a longer, redder
+ * bar means a riskier belief the eye should land on first (spec story 5).
+ */
+declare function RiskBar({ risk }: {
+    risk: number;
+}): react.JSX.Element;
+/**
+ * A signed confidence reading: a tiny sparkline of its trajectory when a
+ * history is available, always the +/- number (negative reads crit) — so a row
+ * shows both where a belief stands and, when known, which way it is trending
+ * (spec story 6). With no history the number stands alone; the list endpoint
+ * carries no per-row series, so the in-row sparkline appears wherever a caller
+ * does have one (e.g. the drawer trajectory uses `Sparkline` directly).
+ */
+declare function ConfidenceCell({ confidence, history, }: {
+    confidence: number;
+    history?: number[];
+}): react.JSX.Element;
+/**
+ * A signed sparkline over `values`. A zero baseline is drawn whenever the domain
+ * spans it, so a line dipping below zero reads as a belief losing ground. The
+ * last point gets a dot. `fill` shades the area under the line. Pure geometry
+ * comes from `sparklinePath`/`sparklineY`.
+ */
+declare function Sparkline({ values, width, height, min, max, tone, fill, ariaLabel, }: {
+    values: number[];
+    width?: number;
+    height?: number;
+    min?: number;
+    max?: number;
+    tone?: Tone;
+    fill?: boolean;
+    ariaLabel?: string;
+}): react.JSX.Element | null;
+/**
+ * A glanceable stat tile — a label, a big number, and an optional sub-caption.
+ * Becomes a button when `onClick` is given (counts that double as nav). Pure
+ * presentation; the caller supplies the value.
+ */
+declare function StatTile({ label, value, sub, onClick, active, }: {
+    label: string;
+    value: number;
+    sub?: ReactNode;
+    onClick?: () => void;
+    active?: boolean;
+}): react.JSX.Element;
 
 type Counts = Partial<Record<Collection, number>>;
 interface UseCountsResult {
@@ -15,24 +153,43 @@ interface UseCountsResult {
  */
 declare function useCounts(basePath?: string): UseCountsResult;
 
+interface RegisterNavProps {
+    /** The active register, highlighted with a clear active state (spec story 7). */
+    active: Collection;
+    /** Called when a register is chosen. */
+    onSelect: (register: Collection) => void;
+    /** Live per-register counts; a middle dot shows until they load. */
+    counts?: Counts | null;
+    /** Restrict/reorder the registers shown; defaults to all, grouped. */
+    registers?: Collection[];
+}
+/**
+ * The sidebar register nav — every register with its live count and an active
+ * state, grouped into the register set and reference data (spec story 7). A
+ * presentational brick: the caller owns which register is active and supplies
+ * the counts. The assembled `<ValidationOSDashboard />` composes this; it's also
+ * exported so anyone building their own surface can reuse it (the second level
+ * of entry). Styled with the package's own token sheet — no host Tailwind.
+ */
+declare function RegisterNav({ active, onSelect, counts, registers, }: RegisterNavProps): react.JSX.Element;
+
 interface RegisterCountsProps {
     counts: Counts;
     /** Optional caption under the tiles (e.g. the backend the numbers came from). */
     caption?: string;
-    /**
-     * Optional link target per register. When supplied, each tile becomes a link
-     * (a plain anchor — works with any router), so counts double as navigation
-     * into the browse tables.
-     */
-    hrefFor?: (register: Collection) => string;
+    /** Optional click handler per register — makes each tile a nav button. */
+    onSelect?: (register: Collection) => void;
+    /** The active register, highlighted when tiles are nav. */
+    active?: Collection | null;
 }
 /**
  * A glanceable grid of stat tiles — one per register, the register's row count
- * as the hero number. Presentational: the caller reads the counts (server-side,
- * through the adapter) and hands them in. Styled with Tailwind utility classes;
- * the host app provides Tailwind.
+ * as the hero number. A brick kept for a counts landing; the assembled app
+ * surfaces the same counts in the sidebar nav. Presentational: the caller reads
+ * the counts (server-side, through the adapter) and hands them in. Rendered in
+ * the package's own token sheet — no host Tailwind.
  */
-declare function RegisterCounts({ counts, caption, hrefFor }: RegisterCountsProps): react.JSX.Element;
+declare function RegisterCounts({ counts, caption, onSelect, active, }: RegisterCountsProps): react.JSX.Element;
 
 interface RegisterTableProps {
     register: Collection;
@@ -44,9 +201,11 @@ interface RegisterTableProps {
 }
 /**
  * A list table for one register — a row per record, the register's key fields
- * as columns (assumptions show Impact, Confidence and Risk). Presentational:
- * the caller supplies the rows. Clicking a row opens the read-only drawer.
- * Styled with Tailwind utilities the host app provides.
+ * as columns. Assumptions read their state at a glance: a colored Status pill, a
+ * signed Confidence, and a threshold-toned Risk bar (spec stories 4–6). Which
+ * cells render as pills/bars/sparklines is declared on the column (`kind`), so
+ * the treatment stays testable at the columns seam and this component stays a
+ * dumb renderer. Presentational: the caller supplies the rows.
  */
 declare function RegisterTable({ register, records, onRowClick, selectedId, }: RegisterTableProps): react.JSX.Element;
 
@@ -60,27 +219,144 @@ interface RecordDrawerProps {
     /** Whether the drawer is open (a row is selected). */
     open: boolean;
     onClose: () => void;
+    /** API base path (default `/api`). */
+    basePath?: string;
+    /** Re-fetch the record + its list — called after a save, and the re-fetch
+     * path offered when a concurrent edit is detected. */
+    onChanged?: () => void;
+    /** Extra content below the fields in read mode — e.g. the relation editor. */
+    children?: ReactNode;
+}
+/**
+ * A record drawer that reads and edits, and wires relations. The derived
+ * numbers lead as a visually distinct "computed — not editable" hero (spec
+ * stories 4/10): a bordered box, each number big and mono, Confidence toned by
+ * sign and Risk by threshold, with a "Why?" reveal opening the understanding
+ * layer in the same accent/pill language (story 11). Editing recomputes those
+ * numbers server-side on save; a concurrent edit surfaces as a gentle, jargon-
+ * free prompt with a re-fetch path (story 12). In read mode the drawer hosts
+ * the relation editor (`children`). Chrome is shared via `DrawerShell`; styled
+ * with the package's own token sheet, no host Tailwind.
+ */
+declare function RecordDrawer({ register, record, loading, error, open, onClose, basePath, onChanged, children, }: RecordDrawerProps): react.JSX.Element;
+
+interface RecordFormProps {
+    register: Collection;
+    basePath?: string;
+    /** Called with the new record's id after a successful create. */
+    onCreated: (id: string) => void;
+    onCancel: () => void;
 }
 /**
- * A read-only drawer for one record. Any derived numbers lead as the hero,
- * explicitly marked computed — not editable (spec user story 4), so a reader
- * trusts they follow the formulas; the record's own fields follow. This slice
- * is read-only; editing lands in a later slice.
+ * The "new record" form for one register (spec user story 13). Editable own-
+ * fields only — derived numbers are computed server-side and marked
+ * computed-not-editable elsewhere; relations are wired by linking after the
+ * record exists. Presence-gap fields (5 Whys, etc.) appear as first-class
+ * textareas. On submit it POSTs through the API, which recomputes on write.
+ */
+declare function RecordForm({ register, basePath, onCreated, onCancel, }: RecordFormProps): react.JSX.Element;
+
+interface RelationEditorProps {
+    /** The register of the open record initiating the link. */
+    register: Collection;
+    /** The open record's id (the `from` end). */
+    recordId: string;
+    basePath?: string;
+    /** Called after a relation is wired, so the drawer can re-fetch. */
+    onLinked: () => void;
+}
+/**
+ * Wire a relation from the open record (spec user story 14). Pick an edge, then
+ * a target record from the register that edge points at; linking sets both ends
+ * server-side and recomputes derived fields. Registers with no outbound edges
+ * (glossary, people) render nothing.
+ */
+declare function RelationEditor({ register, recordId, basePath, onLinked, }: RelationEditorProps): react.JSX.Element | null;
+
+/**
+ * The understanding layer behind the Confidence "Why?" (OPS-1276): which
+ * experiments move the number (ranked by push) and how close each running
+ * experiment is to concluding, the goal/direct evidence that also moves it, and
+ * Confidence over time. It lazy-loads the readings + experiments registers (it
+ * only mounts when the Reveal is open), then derives everything through the
+ * shared derivation module. Restyled into the drawer's accent/pill language
+ * (spec story 11): signed push tracks and a signed trajectory sparkline, in the
+ * package's own token sheet — no host Tailwind.
  */
-declare function RecordDrawer({ register, record, loading, error, open, onClose, }: RecordDrawerProps): react.JSX.Element | null;
+declare function UnderstandingPanel({ assumption, basePath, }: {
+    assumption: AnyRecord;
+    basePath?: string;
+}): react.JSX.Element;
+
+/**
+ * The understanding layer's data join (OPS-1276). Pure: given an assumption
+ * and the readings + experiments registers, it produces everything the Reveal
+ * shows — the experiments testing the belief (each with how hard it moves
+ * Confidence and how close it is to concluding), the goal/direct evidence that
+ * also moves the number, and the Confidence-over-time trajectory.
+ *
+ * The record → derivation-input mapping is `@validation-os/core`'s shared
+ * `toReadingInput`, so a reading is read here exactly as it is server-side.
+ */
+
+/** An experiment testing this assumption: how hard it moves Confidence, and
+ * how close it is to concluding. `contribution` is 0 for a running experiment
+ * that has not produced a concluded reading yet — it still shows, so its
+ * progress-to-conclusion is visible. */
+interface ExperimentView {
+    experimentId: string;
+    title: string | null;
+    status: string | null;
+    /** Signed push on Confidence; 0 until a concluded reading lands. */
+    contribution: number;
+    magnitude: number;
+    /** Concluded readings this experiment has produced for the belief. */
+    readingCount: number;
+    progress: Progress | null;
+    /** Concluded/closed — reads as done rather than in-flight. */
+    done: boolean;
+}
+/** Goal-rung or direct evidence that moves Confidence but is not an experiment. */
+interface OtherMover {
+    key: string;
+    kind: Exclude<MoverKind, "experiment">;
+    goalId: string | null;
+    contribution: number;
+    magnitude: number;
+    readingCount: number;
+}
+interface Understanding {
+    /** The same Confidence the derived box shows. */
+    confidence: number;
+    /** Experiments testing this belief, ranked by how hard they push. */
+    experiments: ExperimentView[];
+    /** Goal/direct evidence that also moves the number. */
+    otherMovers: OtherMover[];
+    /** Confidence over time; empty when no concluded reading is dated. */
+    trajectory: TrajectoryPoint[];
+    /** Concluded readings feeding the number, across all sources. */
+    readingCount: number;
+}
+declare function buildUnderstanding(assumption: AnyRecord, readings: AnyRecord[], experiments: AnyRecord[]): Understanding;
 
 interface RegisterBrowserProps {
     register: Collection;
     /** API base path (default `/api`). */
     basePath?: string;
+    /** A one-line description under the register title (spec story 7/9). */
+    subtitle?: string;
 }
 /**
- * The browse-and-open surface for one register: a list table that opens a
- * read-only drawer on row click. Reads over HTTP through the Clerk-gated API
- * read routes (list + get), so the browser never touches Firestore directly.
- * The thin host app renders this with a `register` — that's the whole page.
+ * The browse-create-edit surface for one register: a list table that opens a
+ * record drawer on row click, a "New" button that opens the create form, and a
+ * relation editor in the drawer for wiring links. All reads and writes go over
+ * HTTP through the Clerk-gated API (which recomputes derived fields on write),
+ * so the browser never touches Firestore directly. After an edit saves, both
+ * the drawer's record and the list re-fetch so recomputed derived numbers show
+ * everywhere. The thin host app renders this with a `register` — that's the
+ * whole page.
  */
-declare function RegisterBrowser({ register, basePath }: RegisterBrowserProps): react.JSX.Element;
+declare function RegisterBrowser({ register, basePath, subtitle, }: RegisterBrowserProps): react.JSX.Element;
 
 interface UseListResult {
     records: AnyRecord[] | null;
@@ -94,12 +370,122 @@ interface UseRecordResult {
     record: AnyRecord | null;
     loading: boolean;
     error: string | null;
+    /** Re-fetch the record — the re-fetch path after a save or edit conflict. */
+    refresh: () => void;
 }
 /**
  * Fetch one record by id. `id` may be null (nothing open) — the hook stays
  * idle until an id is supplied, so it drives a drawer that opens on row click.
+ * `refresh` re-fetches: the edit flow calls it after a save, and it's the
+ * re-fetch path offered when a write hits a concurrent-edit conflict.
  */
 declare function useRecord(register: Collection, id: string | null, basePath?: string): UseRecordResult;
+/** The outcome of a save: the recomputed record, or a rejection with a
+ * plain-language message (a concurrent-edit conflict, or another failure). */
+type SaveResult = {
+    ok: true;
+    record: AnyRecord;
+} | {
+    ok: false;
+    conflict: boolean;
+    message: string;
+};
+/**
+ * Map an update response (status + parsed body) to a `SaveResult`. Pure, so
+ * the 409/error/ok branching is unit-testable without a DOM. A 409 is a
+ * concurrent-edit conflict, surfaced in the API's plain-language copy (or the
+ * `CONFLICT_MESSAGE` fallback) — never version jargon (spec user story 12).
+ */
+declare function interpretSave(status: number, body: unknown): SaveResult;
+interface UseUpdateResult {
+    /** PATCH `{ version, ...patch }`; resolves to the recomputed record or a
+     * rejection. Never throws — callers branch on `result.ok`. */
+    save: (id: string, patch: Record<string, unknown>) => Promise<SaveResult>;
+    saving: boolean;
+    /** Plain-language conflict prompt when a concurrent edit was detected. */
+    conflict: string | null;
+    /** Plain-language message for any other save failure. */
+    error: string | null;
+    /** Clear conflict/error state (e.g. when re-entering edit mode). */
+    reset: () => void;
+}
+/**
+ * Version-guarded update over the API write route. A stale version comes back
+ * as a 409, which we surface as a gentle, jargon-free `conflict` message (spec
+ * user story 12) — the API sends the copy, and `CONFLICT_MESSAGE` is the
+ * fallback. Derived values are recomputed server-side, so the returned record
+ * carries the authoritative numbers, never anything the client computed.
+ */
+declare function useUpdate(register: Collection, basePath?: string): UseUpdateResult;
+
+interface UseCreateResult {
+    create: (data: Record<string, unknown>) => Promise<AnyRecord>;
+    saving: boolean;
+    error: string | null;
+}
+/** Create a record in `register`; the server stamps derived fields on write. */
+declare function useCreate(register: Collection, basePath?: string): UseCreateResult;
+interface LinkArgs {
+    relation: Relation;
+    from: {
+        register: Collection;
+        id: string;
+    };
+    to: {
+        register: Collection;
+        id: string;
+    };
+}
+interface UseLinkResult {
+    link: (args: LinkArgs) => Promise<void>;
+    linking: boolean;
+    error: string | null;
+}
+/** Wire a relation; the API sets both ends and recomputes derived fields. */
+declare function useLink(basePath?: string): UseLinkResult;
+
+/**
+ * The pure edit-logic seam — which fields a register lets you edit, how a
+ * form draft maps back to a version-guarded patch, and the plain-language
+ * conflict copy. Kept as pure data/functions (no DOM) so the edit behaviour
+ * is unit-testable exactly like `columns.ts`; the drawer component consumes it.
+ *
+ * Derived numbers (Confidence, Risk, Derived Impact, Strength) are never
+ * editable — they are computed server-side on write (spec user story 4/11),
+ * so they never appear here. Relation links are set through `link`, a separate
+ * story, so relation-id fields aren't editable inputs either.
+ */
+
+/** The plain-language conflict prompt — never version jargon (user story 12).
+ * The API returns its own copy on a 409; this is the client-side fallback. */
+declare const CONFLICT_MESSAGE: string;
+type FieldKind = "text" | "textarea" | "number" | "select";
+interface FieldEditor {
+    /** The record key this editor writes. */
+    key: string;
+    /** Plain-language label shown beside the input. */
+    label: string;
+    kind: FieldKind;
+    /** For `select`: the allowed options (a leading blank = "unset"). */
+    options?: readonly string[];
+    /** An empty input clears the field to `null` rather than "". */
+    nullable?: boolean;
+}
+/** The fields a register lets you edit, in render order. */
+declare function editableFields(register: Collection): FieldEditor[];
+/** A form draft is a plain string map keyed by field — what the inputs hold. */
+type Draft = Record<string, string>;
+/** Build the initial form draft from a record: every editable field becomes a
+ * string input value, and missing values become empty inputs. */
+declare function draftFrom(register: Collection, record: AnyRecord): Draft;
+/**
+ * A version-guarded patch from a draft: the loaded `version` plus only the
+ * fields whose value actually changed (so an untouched save doesn't churn
+ * unrelated fields). The API rejects a stale version with a 409.
+ */
+declare function buildPatch(register: Collection, original: AnyRecord, draft: Draft): Record<string, unknown>;
+/** Whether a draft differs from the record it was loaded from. */
+declare function hasEdits(register: Collection, original: AnyRecord, draft: Draft): boolean;
 
 /**
  * Per-register table columns and value formatting — the presentational shape
@@ -108,6 +494,14 @@ declare function useRecord(register: Collection, id: string | null, basePath?: s
  * headers are plain language and derived numbers are shown, never hidden.
  */
 
+/**
+ * How a cell renders. `text` is plain formatted text; `status` is a colored
+ * pill; `risk` is a threshold-toned bar + number; `confidence` is a signed
+ * number (with a sparkline when a trajectory is available). Keeping this on the
+ * column — not branching by key in the table — is what makes the visual
+ * treatment declarative and testable at this seam (spec story 13).
+ */
+type CellKind = "text" | "status" | "risk" | "confidence";
 interface ColumnDef {
     /** Stable key; also the default field read from the record. */
     key: string;
@@ -119,6 +513,8 @@ interface ColumnDef {
     align?: "left" | "right";
     /** Marks a column whose value is computed, never hand-typed (spec story 4). */
     derived?: boolean;
+    /** How the cell renders; defaults to `text`. */
+    kind?: CellKind;
 }
 /** The columns to render for a register. */
 declare function columnsFor(register: Collection): ColumnDef[];
@@ -129,10 +525,76 @@ declare function formatValue(value: unknown): string;
 /** The record's headline for a row/drawer: Title, else Name, else its id. */
 declare function primaryLabel(record: AnyRecord): string;
 
+/**
+ * The editable-field spec for the "new record" form, per register — kept as
+ * pure data + functions (like `columns.ts`) so the create form is unit-testable
+ * without a DOM. Only a record's own scalar fields appear here: derived numbers
+ * are computed server-side (never typed), and relations are wired separately by
+ * linking (see `relations.ts` / the relation editor), so id/relation fields are
+ * deliberately absent. Vocabularies mirror `core`'s type unions.
+ */
+
+interface FormField {
+    /** Record field key (what the create payload uses). */
+    key: string;
+    /** Plain-language label a non-technical teammate reads. */
+    label: string;
+    kind: FieldKind;
+    /** Options for a `select`. */
+    options?: readonly string[];
+    /** A `select`/`text` value that should be stored as a number. */
+    coerce?: "number";
+    required?: boolean;
+    placeholder?: string;
+}
+/** The editable fields for a register's create form, in display order. */
+declare function formFieldsFor(register: Collection): FormField[];
+/** A blank draft: every field keyed to an empty string (form-friendly). */
+declare function emptyDraft(register: Collection): Record<string, string>;
+/** Labels of required fields the draft has left blank (submit-gating). */
+declare function missingRequired(register: Collection, draft: Record<string, string>): string[];
+/**
+ * Turn a string-keyed form draft into a create payload: numbers coerced, blank
+ * optional values dropped so the record stores only what was filled. Derived
+ * and relation fields are never here — the server computes the former and
+ * linking wires the latter.
+ */
+declare function toCreatePayload(register: Collection, draft: Record<string, string>): Record<string, unknown>;
+
+/**
+ * Which relations a record of a given register can initiate — the menu the
+ * relation editor offers. Derived from `core`'s single `RELATIONS` table (so
+ * the two never drift) and turned into plain-language choices, each naming the
+ * register whose records are valid link targets.
+ */
+
+interface LinkChoice {
+    relation: Relation;
+    /** Plain-language name of the edge, from the initiating record's side. */
+    label: string;
+    /** The register to pick a target record from. */
+    targetRegister: Collection;
+}
+/** The relations a record of `register` can initiate, in table order. */
+declare function linkChoicesFrom(register: Collection): LinkChoice[];
+
 /** Plain-language labels — the register is a surface a non-technical
  * teammate meets, so no jargon and no code-y plurals. */
 declare const REGISTER_LABEL: Record<Collection, string>;
+/** Singular labels — for "New {thing}" affordances (never a naive de-pluralise
+ * that would read "New Peopl" / "New Glossary"). */
+declare const REGISTER_SINGULAR: Record<Collection, string>;
 /** The order tiles read left-to-right, top-to-bottom. */
 declare const REGISTER_ORDER: Collection[];
+/** A one-line description shown under each register's title (spec story 9). */
+declare const REGISTER_SUBTITLE: Record<Collection, string>;
+/** A single-glyph icon per register for the sidebar nav (matches the prototype
+ * feel; a glyph, not an icon font, so nothing external is pulled in). */
+declare const REGISTER_ICON: Record<Collection, string>;
+/** The sidebar groups the registers into the register set and reference data. */
+declare const REGISTER_GROUPS: {
+    label: string;
+    registers: Collection[];
+}[];
 
-export { type ColumnDef, type Counts, REGISTER_LABEL, REGISTER_ORDER, RecordDrawer, type RecordDrawerProps, RegisterBrowser, type RegisterBrowserProps, RegisterCounts, type RegisterCountsProps, RegisterTable, type RegisterTableProps, type UseCountsResult, type UseListResult, type UseRecordResult, cellValue, columnsFor, formatValue, primaryLabel, useCounts, useList, useRecord };
+export { CONFLICT_MESSAGE, type CellKind, type ColumnDef, ConfidenceCell, type Counts, type DashboardConfig, type Draft, type ExperimentView, type FieldEditor, type FieldKind, type FormField, type LinkArgs, type LinkChoice, type OtherMover, REGISTER_GROUPS, REGISTER_ICON, REGISTER_LABEL, REGISTER_ORDER, REGISTER_SINGULAR, REGISTER_SUBTITLE, RISK_CRIT, RISK_WARN, RecordDrawer, type RecordDrawerProps, RecordForm, type RecordFormProps, RegisterBrowser, type RegisterBrowserProps, RegisterCounts, type RegisterCountsProps, RegisterNav, type RegisterNavProps, RegisterTable, type RegisterTableProps, RelationEditor, type RelationEditorProps, RiskBar, type SaveResult, Sparkline, StatTile, StatusPill, type Tone, type Understanding, UnderstandingPanel, type UseCountsResult, type UseCreateResult, type UseLinkResult, type UseListResult, type UseRecordResult, type UseUpdateResult, ValidationOSDashboard, type ValidationOSDashboardProps, buildPatch, buildUnderstanding, cellValue, columnsFor, confidenceTone, draftFrom, editableFields, emptyDraft, formFieldsFor, formatCount, formatSigned, formatValue, hasEdits, interpretSave, linkChoicesFrom, missingRequired, primaryLabel, riskFraction, riskLevel, sparklinePath, statusTone, toCreatePayload, useCounts, useCreate, useLink, useList, useRecord, useUpdate };