@byline/admin 3.15.2 → 3.16.0

package/dist/fields/relation/relation-many-field.js

@@ -74,20 +74,26 @@ const RelationManyField = ({ field, defaultValue, id, path })=>{
         if (Array.isArray(v)) return v;
         return Array.isArray(defaultValue) ? defaultValue : [];
     };
-    const handleAdd = (selection)=>{
+    const handleAddMany = (selections)=>{
         setPickerOpen(false);
         const current = currentArray();
-        if (current.some((v)=>v.targetDocumentId === selection.targetDocumentId)) return;
-        if (selection.record) setPickedRecords((prev)=>({
-                ...prev,
-                [selection.targetDocumentId]: selection.record
-            }));
+        const existing = new Set(current.map((v)=>v.targetDocumentId));
+        const additions = selections.filter((s)=>!existing.has(s.targetDocumentId));
+        if (0 === additions.length) return;
+        const records = additions.filter((s)=>null != s.record);
+        if (records.length > 0) setPickedRecords((prev)=>{
+            const next = {
+                ...prev
+            };
+            for (const s of records)next[s.targetDocumentId] = s.record;
+            return next;
+        });
         setFieldValue(fieldPath, [
             ...current,
-            {
-                targetDocumentId: selection.targetDocumentId,
-                targetCollectionId: selection.targetCollectionId
-            }
+            ...additions.map((s)=>({
+                    targetDocumentId: s.targetDocumentId,
+                    targetCollectionId: s.targetCollectionId
+                }))
         ]);
     };
     const handleRemove = (targetDocumentId)=>{
@@ -178,11 +184,13 @@ const RelationManyField = ({ field, defaultValue, id, path })=>{
                         })
                     }),
                     /*#__PURE__*/ jsx(RelationPicker, {
+                        multiple: true,
                         targetCollectionPath: field.targetCollection,
                         targetDefinition: targetDef,
                         displayField: field.displayField,
                         isOpen: pickerOpen,
-                        onSelect: handleAdd,
+                        excludeIds: items.map((v)=>v.targetDocumentId),
+                        onSelectMany: handleAddMany,
                         onDismiss: ()=>setPickerOpen(false)
                     })
                 ]

package/dist/fields/relation/relation-picker.d.ts

@@ -18,7 +18,20 @@ import type { CollectionDefinition } from '@byline/core';
  *
  * Paths 2–4 render a single-line label (primary) + `path` (secondary).
  */
-interface RelationPickerProps {
+/**
+ * One confirmed pick. `record` is the raw document the picker row rendered —
+ * the caller can use it to show the selected value in its own tile without a
+ * refetch. The fields available on `record` are whatever `resolveSelectFields`
+ * asked the listing endpoint for (picker columns + `useAsTitle` +
+ * `displayField`), so any display surface downstream of the picker that also
+ * renders from those same columns will find the data it needs.
+ */
+export interface RelationPickerSelection {
+    targetDocumentId: string;
+    targetCollectionId: string;
+    record?: Record<string, any>;
+}
+interface RelationPickerBaseProps {
     /** The target collection path (e.g. `'media'`). */
     targetCollectionPath: string;
     /** The target collection definition (used for labels + displayField fallback). */
@@ -37,23 +50,33 @@ interface RelationPickerProps {
     extraSelectFields?: string[];
     /** Modal open/close state. */
     isOpen: boolean;
-    /**
-     * Called with the picked selection when the user confirms.
-     *
-     * `record` is the raw document the picker row rendered — the caller can
-     * use it to show the selected value in its own tile without a refetch.
-     * The fields available on `record` are whatever `resolveSelectFields`
-     * asked the listing endpoint for (picker columns + `useAsTitle` +
-     * `displayField`), so any display surface downstream of the picker that
-     * also renders from those same columns will find the data it needs.
-     */
-    onSelect: (selection: {
-        targetDocumentId: string;
-        targetCollectionId: string;
-        record?: Record<string, any>;
-    }) => void;
     /** Called when the user dismisses the modal. */
     onDismiss: () => void;
 }
-export declare const RelationPicker: ({ targetCollectionPath, targetDefinition, displayField, extraSelectFields, isOpen, onSelect, onDismiss, }: RelationPickerProps) => import("react").JSX.Element;
+interface RelationPickerSingleProps extends RelationPickerBaseProps {
+    /** Single-select (default): clicking a row selects it; confirm returns one pick. */
+    multiple?: false;
+    /** Called with the picked selection when the user confirms. */
+    onSelect: (selection: RelationPickerSelection) => void;
+    onSelectMany?: never;
+    excludeIds?: never;
+}
+interface RelationPickerMultiProps extends RelationPickerBaseProps {
+    /**
+     * Multi-select mode (`hasMany` widgets): rows toggle a check state and the
+     * confirm action returns every selection in pick order — several picks in
+     * one trip instead of reopening the modal per item.
+     */
+    multiple: true;
+    /** Called with the full selection set (pick order) when the user confirms. */
+    onSelectMany: (selections: RelationPickerSelection[]) => void;
+    onSelect?: never;
+    /**
+     * Target ids already present on the caller's value. Rendered as disabled
+     * "already added" rows so the same target can't be picked twice.
+     */
+    excludeIds?: string[];
+}
+type RelationPickerProps = RelationPickerSingleProps | RelationPickerMultiProps;
+export declare const RelationPicker: ({ targetCollectionPath, targetDefinition, displayField, extraSelectFields, isOpen, multiple, excludeIds, onSelect, onSelectMany, onDismiss, }: RelationPickerProps) => import("react").JSX.Element;
 export {};

package/dist/fields/relation/relation-picker.js

@@ -2,17 +2,18 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useState } from "react";
 import { getCollectionAdminConfig, resolveItemViewColumns } from "@byline/core";
 import { useTranslation } from "@byline/i18n/react";
-import { Button, LoaderRing, Modal, Search } from "@byline/ui/react";
+import { Button, CheckIcon, LoaderRing, Modal, Search } from "@byline/ui/react";
 import classnames from "classnames";
 import { useBylineFieldServices } from "../field-services-context.js";
 import { PickerCell, resolveFallbackDisplayField, resolveRowLabel, resolveSelectFields } from "./relation-display.js";
 import relation_picker_module from "./relation-picker.module.js";
 const PAGE_SIZE = 15;
-const RelationPicker = ({ targetCollectionPath, targetDefinition, displayField, extraSelectFields, isOpen, onSelect, onDismiss })=>{
+const RelationPicker = ({ targetCollectionPath, targetDefinition, displayField, extraSelectFields, isOpen, multiple = false, excludeIds, onSelect, onSelectMany, onDismiss })=>{
     const [query, setQuery] = useState('');
     const [page, setPage] = useState(1);
     const { t } = useTranslation('byline-admin');
     const [selectedDocumentId, setSelectedDocumentId] = useState(null);
+    const [selectedMap, setSelectedMap] = useState(()=>new Map());
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
     const [documents, setDocuments] = useState([]);
@@ -26,6 +27,7 @@ const RelationPicker = ({ targetCollectionPath, targetDefinition, displayField,
             setQuery('');
             setPage(1);
             setSelectedDocumentId(null);
+            setSelectedMap(new Map());
             setError(null);
         }
     }, [
@@ -73,7 +75,7 @@ const RelationPicker = ({ targetCollectionPath, targetDefinition, displayField,
     ]);
     const resolvedDisplayField = displayField ?? targetDefinition?.useAsTitle ?? resolveFallbackDisplayField(targetDefinition) ?? null;
     const handleSelect = useCallback(()=>{
-        if (!selectedDocumentId || !collectionId) return;
+        if (!selectedDocumentId || !collectionId || !onSelect) return;
         const record = documents.find((d)=>d?.id === selectedDocumentId);
         onSelect({
             targetDocumentId: selectedDocumentId,
@@ -86,6 +88,27 @@ const RelationPicker = ({ targetCollectionPath, targetDefinition, displayField,
         documents,
         onSelect
     ]);
+    const handleSelectMany = useCallback(()=>{
+        if (0 === selectedMap.size || !collectionId || !onSelectMany) return;
+        onSelectMany(Array.from(selectedMap, ([targetDocumentId, record])=>({
+                targetDocumentId,
+                targetCollectionId: collectionId,
+                record
+            })));
+    }, [
+        selectedMap,
+        collectionId,
+        onSelectMany
+    ]);
+    const toggleSelected = useCallback((doc)=>{
+        const id = doc.id;
+        setSelectedMap((prev)=>{
+            const next = new Map(prev);
+            if (next.has(id)) next.delete(id);
+            else next.set(id, doc);
+            return next;
+        });
+    }, []);
     const title = t('fields.relation.selectPickerTitle', {
         label: targetDefinition?.labels.singular ?? targetCollectionPath
     });
@@ -143,34 +166,65 @@ const RelationPicker = ({ targetCollectionPath, targetDefinition, displayField,
                                         className: classnames('byline-field-relation-picker-rows', relation_picker_module.rows),
                                         children: documents.map((doc)=>{
                                             const id = doc.id;
-                                            const selected = selectedDocumentId === id;
+                                            const selected = multiple ? selectedMap.has(id) : selectedDocumentId === id;
+                                            const excluded = multiple && (excludeIds?.includes(id) ?? false);
                                             return /*#__PURE__*/ jsx("li", {
-                                                children: /*#__PURE__*/ jsx("button", {
+                                                children: /*#__PURE__*/ jsxs("button", {
                                                     type: "button",
-                                                    className: classnames('byline-field-relation-picker-row-button', relation_picker_module["row-button"], selected && [
+                                                    disabled: excluded,
+                                                    "aria-pressed": multiple ? selected : void 0,
+                                                    title: excluded ? t('fields.relation.picker.alreadyAdded') : void 0,
+                                                    className: classnames('byline-field-relation-picker-row-button', relation_picker_module["row-button"], multiple && [
+                                                        'byline-field-relation-picker-row-multi',
+                                                        relation_picker_module["row-multi"]
+                                                    ], selected && [
                                                         'byline-field-relation-picker-row-selected',
                                                         relation_picker_module["row-selected"]
+                                                    ], excluded && [
+                                                        'byline-field-relation-picker-row-added',
+                                                        relation_picker_module["row-added"]
                                                     ]),
-                                                    onClick: ()=>setSelectedDocumentId(id),
-                                                    children: pickerColumns && pickerColumns.length > 0 ? /*#__PURE__*/ jsx("div", {
-                                                        className: classnames('byline-field-relation-picker-row-cells', relation_picker_module["row-cells"]),
-                                                        children: pickerColumns.map((col)=>/*#__PURE__*/ jsx(PickerCell, {
-                                                                column: col,
-                                                                record: doc
-                                                            }, String(col.fieldName)))
-                                                    }) : /*#__PURE__*/ jsxs("div", {
-                                                        className: classnames('byline-field-relation-picker-row-stack', relation_picker_module["row-stack"]),
-                                                        children: [
-                                                            /*#__PURE__*/ jsx("span", {
-                                                                className: classnames('byline-field-relation-picker-row-label', relation_picker_module["row-label"]),
-                                                                children: resolveRowLabel(doc, resolvedDisplayField) || id
-                                                            }),
-                                                            'string' == typeof doc.path && doc.path.length > 0 && /*#__PURE__*/ jsx("span", {
-                                                                className: classnames('byline-field-relation-picker-row-path', relation_picker_module["row-path"]),
-                                                                children: doc.path
+                                                    onClick: ()=>{
+                                                        if (excluded) return;
+                                                        if (multiple) toggleSelected(doc);
+                                                        else setSelectedDocumentId(id);
+                                                    },
+                                                    children: [
+                                                        multiple && /*#__PURE__*/ jsx("span", {
+                                                            "aria-hidden": "true",
+                                                            className: classnames('byline-field-relation-picker-check', relation_picker_module.check, (selected || excluded) && [
+                                                                'byline-field-relation-picker-check-checked',
+                                                                relation_picker_module["check-checked"]
+                                                            ]),
+                                                            children: (selected || excluded) && /*#__PURE__*/ jsx(CheckIcon, {
+                                                                width: "12px",
+                                                                height: "12px"
                                                             })
-                                                        ]
-                                                    })
+                                                        }),
+                                                        pickerColumns && pickerColumns.length > 0 ? /*#__PURE__*/ jsx("div", {
+                                                            className: classnames('byline-field-relation-picker-row-cells', relation_picker_module["row-cells"]),
+                                                            children: pickerColumns.map((col)=>/*#__PURE__*/ jsx(PickerCell, {
+                                                                    column: col,
+                                                                    record: doc
+                                                                }, String(col.fieldName)))
+                                                        }) : /*#__PURE__*/ jsxs("div", {
+                                                            className: classnames('byline-field-relation-picker-row-stack', relation_picker_module["row-stack"]),
+                                                            children: [
+                                                                /*#__PURE__*/ jsx("span", {
+                                                                    className: classnames('byline-field-relation-picker-row-label', relation_picker_module["row-label"]),
+                                                                    children: resolveRowLabel(doc, resolvedDisplayField) || id
+                                                                }),
+                                                                'string' == typeof doc.path && doc.path.length > 0 && /*#__PURE__*/ jsx("span", {
+                                                                    className: classnames('byline-field-relation-picker-row-path', relation_picker_module["row-path"]),
+                                                                    children: doc.path
+                                                                })
+                                                            ]
+                                                        }),
+                                                        excluded && /*#__PURE__*/ jsx("span", {
+                                                            className: classnames('byline-field-relation-picker-added-hint', relation_picker_module["added-hint"]),
+                                                            children: t('fields.relation.picker.alreadyAdded')
+                                                        })
+                                                    ]
                                                 })
                                             }, id);
                                         })
@@ -224,9 +278,11 @@ const RelationPicker = ({ targetCollectionPath, targetDefinition, displayField,
                             className: classnames('byline-field-relation-picker-action', relation_picker_module.action),
                             intent: "primary",
                             type: "button",
-                            disabled: !selectedDocumentId,
-                            onClick: handleSelect,
-                            children: t('common.actions.select')
+                            disabled: multiple ? 0 === selectedMap.size : !selectedDocumentId,
+                            onClick: multiple ? handleSelectMany : handleSelect,
+                            children: multiple ? t('fields.relation.picker.addSelected', {
+                                count: selectedMap.size
+                            }) : t('common.actions.select')
                         })
                     ]
                 })

package/dist/fields/relation/relation-picker.module.js

@@ -12,6 +12,15 @@ const relation_picker_module = {
     rowButton: "row-button-ZHfXmj",
     "row-selected": "row-selected-VlrgyO",
     rowSelected: "row-selected-VlrgyO",
+    "row-multi": "row-multi-o06YCW",
+    rowMulti: "row-multi-o06YCW",
+    check: "check-gYmVOq",
+    "check-checked": "check-checked-Nopylj",
+    checkChecked: "check-checked-Nopylj",
+    "row-added": "row-added-PmlIQL",
+    rowAdded: "row-added-PmlIQL",
+    "added-hint": "added-hint-QGoYN3",
+    addedHint: "added-hint-QGoYN3",
     "row-cells": "row-cells-aSIcf5",
     rowCells: "row-cells-aSIcf5",
     "row-stack": "row-stack-BOPzzj",

package/dist/fields/relation/relation-picker_module.css

@@ -73,6 +73,47 @@
   border-left: 2px solid var(--primary-200);
 }
 
+:is(.row-multi-o06YCW, .byline-field-relation-picker-row-multi) {
+  align-items: center;
+  gap: .625rem;
+  display: flex;
+}
+
+:is(.check-gYmVOq, .byline-field-relation-picker-check) {
+  border: 1px solid var(--gray-400);
+  color: #0000;
+  border-radius: 4px;
+  flex: none;
+  justify-content: center;
+  align-items: center;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+}
+
+:is(.check-checked-Nopylj, .byline-field-relation-picker-check-checked) {
+  background-color: var(--primary-200);
+  border-color: var(--primary-200);
+  color: #fff;
+}
+
+:is(.row-added-PmlIQL, .byline-field-relation-picker-row-added) {
+  opacity: .55;
+  cursor: default;
+}
+
+:is(.row-added-PmlIQL:hover, .byline-field-relation-picker-row-added:hover) {
+  background-color: #0000;
+}
+
+:is(.added-hint-QGoYN3, .byline-field-relation-picker-added-hint) {
+  color: var(--gray-500);
+  font-size: var(--font-size-xs);
+  white-space: nowrap;
+  flex: none;
+  margin-left: auto;
+}
+
 :is(.row-cells-aSIcf5, .byline-field-relation-picker-row-cells) {
   align-items: center;
   gap: .75rem;

package/dist/forms/form-context.d.ts

@@ -35,7 +35,7 @@ type FieldUploadingListener = (uploading: boolean) => void;
  * Save button. `content` mints a new version (normal workflow). `direct-write`
  * is an immediate, non-versioned write of the document-grain system fields
  * (path / advertised locales) that does NOT reset workflow status. `both` does
- * each through its own write path. See docs/I18N.md.
+ * each through its own write path. See docs/07-internationalization/index.md.
  */
 export type DirtyReason = 'none' | 'content' | 'direct-write' | 'both';
 export interface DirtyBreakdown {
@@ -68,7 +68,7 @@ interface FormContextType {
     /**
      * Partition the current dirty state into content vs. system-field (path /
      * advertised-locales) writes so the Save button can branch. See
-     * docs/I18N.md.
+     * docs/07-internationalization/index.md.
      */
     getDirtyBreakdown: () => DirtyBreakdown;
     subscribeField: (name: string, listener: FieldListener) => () => void;

package/dist/forms/form-modals.d.ts

@@ -10,7 +10,7 @@ export declare const UnsavedChangesModal: ({ onClose }: {
  * Confirms an immediate, non-versioned write of the document-grain system
  * fields (path / advertised locales) — which does NOT reset workflow status.
  * When content is also dirty, the copy reassures that content edits still
- * follow the normal revision + publish workflow. See docs/I18N.md.
+ * follow the normal revision + publish workflow. See docs/07-internationalization/index.md.
  */
 export declare const SystemFieldsConfirmModal: ({ contentDirty, pathDirty, availableLocalesDirty, onCancel, onConfirm, }: {
     contentDirty: boolean;

package/dist/forms/form-renderer.d.ts

@@ -23,7 +23,7 @@ export interface PublishedVersionInfo {
  * patches) alongside the document-grain system fields (path / advertised
  * locales) and per-bucket dirty flags so the host can route each piece to the
  * right write path — versioned for content, immediate/non-versioned for the
- * system fields. See docs/I18N.md.
+ * system fields. See docs/07-internationalization/index.md.
  */
 export interface SystemFieldsSubmitPayload {
     data: any;
@@ -104,7 +104,7 @@ export interface FormRendererProps {
      * Opts the document-tree placement widget into the sidebar (above the
      * available-locales widget). Sourced from `CollectionDefinition.tree` by the
      * caller. Renders only in edit mode (placement needs a persisted document)
-     * and only when the host wires the tree services. See docs/DOCUMENT-TREE.md.
+     * and only when the host wires the tree services. See docs/04-collections/03-document-trees.md.
      */
     tree?: boolean;
     headingLabel?: string;

package/dist/forms/tree-placement-widget.d.ts

@@ -8,7 +8,7 @@ export interface TreePlacementWidgetProps {
 }
 /**
  * Sidebar widget for placing the current document within its collection's
- * single-parent document tree (the `tree: true` primitive — docs/DOCUMENT-TREE.md).
+ * single-parent document tree (the `tree: true` primitive — docs/04-collections/03-document-trees.md).
  *
  * The tree is document-grain and **unversioned**, so changes here write
  * immediately (independent of the form's content save). The editor picks a

package/dist/lib/create-command.d.ts

@@ -12,7 +12,7 @@ import type { ZodType } from 'zod';
  * contract (validate → authorise → invoke → shape) into a single
  * declaration.
  *
- * Implements Phase 1 of `docs/CORE-COMPOSITION.md`. Today's scope is
+ * Implements Phase 1 of `docs/03-architecture/02-core-composition.md`. Today's scope is
  * `@byline/admin`-internal: it gates against admin actor identity using
  * the existing `assertAdminActor` / `requireAdminActor` helpers, which
  * inherit the super-admin bypass from `AdminAuth.assertAbility`.

package/dist/modules/admin-activity/abilities.d.ts

@@ -7,7 +7,7 @@
  */
 import type { AbilityRegistry } from '@byline/auth';
 /**
- * Ability keys for the admin-activity module (docs/AUDIT.md — Workstream 4).
+ * Ability keys for the admin-activity module (docs/06-auth-and-security/02-auditability.md — Workstream 4).
  *
  * `read` gates the system-wide activity area — the `/admin/activity` report
  * over the version-stream + audit-log union. It is deliberately a **separate**

package/dist/modules/admin-activity/index.d.ts

@@ -7,7 +7,7 @@
  */
 /**
  * `@byline/admin/admin-activity` — the system-wide activity area
- * (docs/AUDIT.md — Workstream 4).
+ * (docs/06-auth-and-security/02-auditability.md — Workstream 4).
  *
  * Unlike the other admin modules this one owns no table and no AdminStore
  * repository: the activity feed is a read over the document db adapter's

package/dist/modules/admin-permissions/abilities.d.ts

@@ -9,7 +9,7 @@ import type { AbilityRegistry } from '@byline/auth';
 /**
  * Ability keys for the admin-permissions module.
  *
- * `read` gates the inspector view (see docs/AUTHN-AUTHZ.md).
+ * `read` gates the inspector view (see docs/06-auth-and-security/01-authn-authz.md).
  * `update` will gate the per-role ability editor mounted on the
  * admin-roles role detail page — declared here so the role editor can
  * assert against it once that surface lands. The per-role editor shares

package/dist/modules/admin-users/repository.d.ts

@@ -113,7 +113,7 @@ export interface AdminUsersRepository {
     getById(id: string): Promise<AdminUserRow | null>;
     /**
      * Bulk lookup for audit actor-label resolution (the `actors`
-     * map on admin document reads — see docs/AUDIT.md, Workstream 1). Ids
+     * map on admin document reads — see docs/06-auth-and-security/02-auditability.md, Workstream 1). Ids
      * with no matching row are simply absent from the result; callers
      * render a tombstone label for them.
      */

package/dist/widgets/source-locale-badge/source-locale-badge.d.ts

@@ -20,7 +20,7 @@ export interface SourceLocaleBadgeProps {
  * NOTE: currently rendered for *every* document so the anchor is visible during
  * development. The intended end state is to show it only when `locale` differs
  * from the system's current default content locale (a normal single-default
- * install then shows nothing). See docs/I18N.md.
+ * install then shows nothing). See docs/07-internationalization/index.md.
  *
  * Stable override handle: `.byline-source-locale-badge`.
  */

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.15.2",
+  "version": "3.16.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -155,11 +155,10 @@
     "react-diff-viewer-continued": "^4.2.2",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "zod-form-data": "^3.0.1",
-    "@byline/auth": "3.15.2",
-    "@byline/i18n": "3.15.2",
-    "@byline/ui": "3.15.2",
-    "@byline/core": "3.15.2"
+    "@byline/auth": "3.16.0",
+    "@byline/ui": "3.16.0",
+    "@byline/core": "3.16.0",
+    "@byline/i18n": "3.16.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/fields/field-services-types.ts

@@ -62,7 +62,7 @@ export type UploadFieldFn = (
   createDocument?: boolean
 ) => Promise<UploadedFileResult>
 
-// --- Document tree (the `tree: true` primitive — docs/DOCUMENT-TREE.md) -----
+// --- Document tree (the `tree: true` primitive — docs/04-collections/03-document-trees.md) -----
 
 /** One hydrated ancestor in a document's breadcrumb trail (root-first). */
 export interface TreeAncestor {

package/src/fields/relation/relation-many-field.tsx

@@ -32,7 +32,7 @@ import cx from 'classnames'
 
 import { useFieldError, useFieldValue, useFormContext } from '../../forms/form-context'
 import styles from './relation-field.module.css'
-import { RelationPicker } from './relation-picker'
+import { RelationPicker, type RelationPickerSelection } from './relation-picker'
 import { RelationSummary } from './relation-summary'
 
 // A single stored item. On the edit path the loader's populate pass attaches
@@ -147,24 +147,29 @@ export const RelationManyField = ({ field, defaultValue, id, path }: RelationMan
     return Array.isArray(defaultValue) ? (defaultValue as IncomingRelationValue[]) : []
   }
 
-  const handleAdd = (selection: {
-    targetDocumentId: string
-    targetCollectionId: string
-    record?: Record<string, any>
-  }) => {
+  const handleAddMany = (selections: RelationPickerSelection[]) => {
     setPickerOpen(false)
     const current = currentArray()
-    // Dedup — a target may appear at most once.
-    if (current.some((v) => v.targetDocumentId === selection.targetDocumentId)) return
-    if (selection.record) {
-      setPickedRecords((prev) => ({ ...prev, [selection.targetDocumentId]: selection.record! }))
+    // Dedup the batch against the current array — a target may appear at most
+    // once. The picker already disables already-added rows, so this is a
+    // belt-and-braces guard for stale state (e.g. a concurrent remove).
+    const existing = new Set(current.map((v) => v.targetDocumentId))
+    const additions = selections.filter((s) => !existing.has(s.targetDocumentId))
+    if (additions.length === 0) return
+    const records = additions.filter((s) => s.record != null)
+    if (records.length > 0) {
+      setPickedRecords((prev) => {
+        const next = { ...prev }
+        for (const s of records) next[s.targetDocumentId] = s.record!
+        return next
+      })
     }
     setFieldValue(fieldPath, [
       ...current,
-      {
-        targetDocumentId: selection.targetDocumentId,
-        targetCollectionId: selection.targetCollectionId,
-      },
+      ...additions.map((s) => ({
+        targetDocumentId: s.targetDocumentId,
+        targetCollectionId: s.targetCollectionId,
+      })),
     ])
   }
 
@@ -260,11 +265,13 @@ export const RelationManyField = ({ field, defaultValue, id, path }: RelationMan
           </div>
 
           <RelationPicker
+            multiple
             targetCollectionPath={field.targetCollection}
             targetDefinition={targetDef}
             displayField={field.displayField}
             isOpen={pickerOpen}
-            onSelect={handleAdd}
+            excludeIds={items.map((v) => v.targetDocumentId)}
+            onSelectMany={handleAddMany}
             onDismiss={() => setPickerOpen(false)}
           />
         </>

package/src/fields/relation/relation-picker.module.css

@@ -108,6 +108,55 @@
   border-left: 2px solid var(--primary-200);
 }
 
+/* Multi-select mode: rows lay out check indicator + content + trailing hint. */
+.row-multi,
+:global(.byline-field-relation-picker-row-multi) {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+}
+
+.check,
+:global(.byline-field-relation-picker-check) {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border: 1px solid var(--gray-400);
+  border-radius: 4px;
+  color: transparent;
+}
+
+.check-checked,
+:global(.byline-field-relation-picker-check-checked) {
+  background-color: var(--primary-200);
+  border-color: var(--primary-200);
+  color: #fff;
+}
+
+/* Already-added rows: inert, dimmed, no hover affordance. */
+.row-added,
+:global(.byline-field-relation-picker-row-added) {
+  opacity: 0.55;
+  cursor: default;
+}
+
+.row-added:hover,
+:global(.byline-field-relation-picker-row-added):hover {
+  background-color: transparent;
+}
+
+.added-hint,
+:global(.byline-field-relation-picker-added-hint) {
+  margin-left: auto;
+  flex: none;
+  color: var(--gray-500);
+  font-size: var(--font-size-xs);
+  white-space: nowrap;
+}
+
 .row-cells,
 :global(.byline-field-relation-picker-row-cells) {
   display: flex;

package/src/fields/relation/relation-picker.tsx

@@ -11,7 +11,7 @@ import { useCallback, useEffect, useState } from 'react'
 import type { CollectionAdminConfig, CollectionDefinition } from '@byline/core'
 import { getCollectionAdminConfig, resolveItemViewColumns } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
-import { Button, LoaderRing, Modal, Search } from '@byline/ui/react'
+import { Button, CheckIcon, LoaderRing, Modal, Search } from '@byline/ui/react'
 import cx from 'classnames'
 
 import { useBylineFieldServices } from '../field-services-context'
@@ -39,7 +39,21 @@ import styles from './relation-picker.module.css'
  *
  * Paths 2–4 render a single-line label (primary) + `path` (secondary).
  */
-interface RelationPickerProps {
+/**
+ * One confirmed pick. `record` is the raw document the picker row rendered —
+ * the caller can use it to show the selected value in its own tile without a
+ * refetch. The fields available on `record` are whatever `resolveSelectFields`
+ * asked the listing endpoint for (picker columns + `useAsTitle` +
+ * `displayField`), so any display surface downstream of the picker that also
+ * renders from those same columns will find the data it needs.
+ */
+export interface RelationPickerSelection {
+  targetDocumentId: string
+  targetCollectionId: string
+  record?: Record<string, any>
+}
+
+interface RelationPickerBaseProps {
   /** The target collection path (e.g. `'media'`). */
   targetCollectionPath: string
   /** The target collection definition (used for labels + displayField fallback). */
@@ -58,25 +72,38 @@ interface RelationPickerProps {
   extraSelectFields?: string[]
   /** Modal open/close state. */
   isOpen: boolean
-  /**
-   * Called with the picked selection when the user confirms.
-   *
-   * `record` is the raw document the picker row rendered — the caller can
-   * use it to show the selected value in its own tile without a refetch.
-   * The fields available on `record` are whatever `resolveSelectFields`
-   * asked the listing endpoint for (picker columns + `useAsTitle` +
-   * `displayField`), so any display surface downstream of the picker that
-   * also renders from those same columns will find the data it needs.
-   */
-  onSelect: (selection: {
-    targetDocumentId: string
-    targetCollectionId: string
-    record?: Record<string, any>
-  }) => void
   /** Called when the user dismisses the modal. */
   onDismiss: () => void
 }
 
+interface RelationPickerSingleProps extends RelationPickerBaseProps {
+  /** Single-select (default): clicking a row selects it; confirm returns one pick. */
+  multiple?: false
+  /** Called with the picked selection when the user confirms. */
+  onSelect: (selection: RelationPickerSelection) => void
+  onSelectMany?: never
+  excludeIds?: never
+}
+
+interface RelationPickerMultiProps extends RelationPickerBaseProps {
+  /**
+   * Multi-select mode (`hasMany` widgets): rows toggle a check state and the
+   * confirm action returns every selection in pick order — several picks in
+   * one trip instead of reopening the modal per item.
+   */
+  multiple: true
+  /** Called with the full selection set (pick order) when the user confirms. */
+  onSelectMany: (selections: RelationPickerSelection[]) => void
+  onSelect?: never
+  /**
+   * Target ids already present on the caller's value. Rendered as disabled
+   * "already added" rows so the same target can't be picked twice.
+   */
+  excludeIds?: string[]
+}
+
+type RelationPickerProps = RelationPickerSingleProps | RelationPickerMultiProps
+
 const PAGE_SIZE = 15
 
 export const RelationPicker = ({
@@ -85,13 +112,22 @@ export const RelationPicker = ({
   displayField,
   extraSelectFields,
   isOpen,
+  multiple = false,
+  excludeIds,
   onSelect,
+  onSelectMany,
   onDismiss,
 }: RelationPickerProps) => {
   const [query, setQuery] = useState<string>('')
   const [page, setPage] = useState<number>(1)
   const { t } = useTranslation('byline-admin')
   const [selectedDocumentId, setSelectedDocumentId] = useState<string | null>(null)
+  // Multi-select state. A Map keyed by target id preserves pick order (the
+  // confirmed batch appends in that order) and carries each row's record so
+  // picks survive page/search changes that swap out `documents`.
+  const [selectedMap, setSelectedMap] = useState<Map<string, Record<string, any> | undefined>>(
+    () => new Map()
+  )
   const [loading, setLoading] = useState<boolean>(false)
   const [error, setError] = useState<string | null>(null)
   const [documents, setDocuments] = useState<any[]>([])
@@ -110,6 +146,7 @@ export const RelationPicker = ({
       setQuery('')
       setPage(1)
       setSelectedDocumentId(null)
+      setSelectedMap(new Map())
       setError(null)
     }
   }, [isOpen])
@@ -174,7 +211,7 @@ export const RelationPicker = ({
     null
 
   const handleSelect = useCallback(() => {
-    if (!selectedDocumentId || !collectionId) return
+    if (!selectedDocumentId || !collectionId || !onSelect) return
     const record = documents.find((d) => d?.id === selectedDocumentId)
     onSelect({
       targetDocumentId: selectedDocumentId,
@@ -183,6 +220,30 @@ export const RelationPicker = ({
     })
   }, [selectedDocumentId, collectionId, documents, onSelect])
 
+  const handleSelectMany = useCallback(() => {
+    if (selectedMap.size === 0 || !collectionId || !onSelectMany) return
+    onSelectMany(
+      Array.from(selectedMap, ([targetDocumentId, record]) => ({
+        targetDocumentId,
+        targetCollectionId: collectionId,
+        record,
+      }))
+    )
+  }, [selectedMap, collectionId, onSelectMany])
+
+  const toggleSelected = useCallback((doc: Record<string, any>) => {
+    const id = doc.id as string
+    setSelectedMap((prev) => {
+      const next = new Map(prev)
+      if (next.has(id)) {
+        next.delete(id)
+      } else {
+        next.set(id, doc)
+      }
+      return next
+    })
+  }, [])
+
   const title = t('fields.relation.selectPickerTitle', {
     label: targetDefinition?.labels.singular ?? targetCollectionPath,
   })
@@ -228,21 +289,55 @@ export const RelationPicker = ({
                 <ul className={cx('byline-field-relation-picker-rows', styles.rows)}>
                   {documents.map((doc) => {
                     const id = doc.id as string
-                    const selected = selectedDocumentId === id
+                    const selected = multiple ? selectedMap.has(id) : selectedDocumentId === id
+                    const excluded = multiple && (excludeIds?.includes(id) ?? false)
                     return (
                       <li key={id}>
                         <button
                           type="button"
+                          disabled={excluded}
+                          aria-pressed={multiple ? selected : undefined}
+                          title={excluded ? t('fields.relation.picker.alreadyAdded') : undefined}
                           className={cx(
                             'byline-field-relation-picker-row-button',
                             styles['row-button'],
+                            multiple && [
+                              'byline-field-relation-picker-row-multi',
+                              styles['row-multi'],
+                            ],
                             selected && [
                               'byline-field-relation-picker-row-selected',
                               styles['row-selected'],
+                            ],
+                            excluded && [
+                              'byline-field-relation-picker-row-added',
+                              styles['row-added'],
                             ]
                           )}
-                          onClick={() => setSelectedDocumentId(id)}
+                          onClick={() => {
+                            if (excluded) return
+                            if (multiple) {
+                              toggleSelected(doc)
+                            } else {
+                              setSelectedDocumentId(id)
+                            }
+                          }}
                         >
+                          {multiple && (
+                            <span
+                              aria-hidden="true"
+                              className={cx(
+                                'byline-field-relation-picker-check',
+                                styles.check,
+                                (selected || excluded) && [
+                                  'byline-field-relation-picker-check-checked',
+                                  styles['check-checked'],
+                                ]
+                              )}
+                            >
+                              {(selected || excluded) && <CheckIcon width="12px" height="12px" />}
+                            </span>
+                          )}
                           {pickerColumns && pickerColumns.length > 0 ? (
                             <div
                               className={cx(
@@ -281,6 +376,16 @@ export const RelationPicker = ({
                               )}
                             </div>
                           )}
+                          {excluded && (
+                            <span
+                              className={cx(
+                                'byline-field-relation-picker-added-hint',
+                                styles['added-hint']
+                              )}
+                            >
+                              {t('fields.relation.picker.alreadyAdded')}
+                            </span>
+                          )}
                         </button>
                       </li>
                     )
@@ -331,10 +436,12 @@ export const RelationPicker = ({
             className={cx('byline-field-relation-picker-action', styles.action)}
             intent="primary"
             type="button"
-            disabled={!selectedDocumentId}
-            onClick={handleSelect}
+            disabled={multiple ? selectedMap.size === 0 : !selectedDocumentId}
+            onClick={multiple ? handleSelectMany : handleSelect}
           >
-            {t('common.actions.select')}
+            {multiple
+              ? t('fields.relation.picker.addSelected', { count: selectedMap.size })
+              : t('common.actions.select')}
           </Button>
         </Modal.Actions>
       </Modal.Container>

package/src/forms/available-locales-reconcile.test.node.ts

@@ -14,7 +14,7 @@ import { reconcileLocaleState } from './available-locales-reconcile.js'
  * The widget's reconciliation is expressed purely as Checkbox intent +
  * disabled state — no per-row text. `reconcileLocaleState` is the pure heart
  * of that mapping; the four cells below are the full truth table from
- * docs/I18N.md.
+ * docs/07-internationalization/index.md.
  */
 describe('reconcileLocaleState', () => {
   it('ledger-complete + advertised → green, enabled (advertised & complete)', () => {

package/src/forms/form-context.tsx

@@ -64,7 +64,7 @@ const sameLocaleSet = (a: string[], b: string[]): boolean => {
  * Save button. `content` mints a new version (normal workflow). `direct-write`
  * is an immediate, non-versioned write of the document-grain system fields
  * (path / advertised locales) that does NOT reset workflow status. `both` does
- * each through its own write path. See docs/I18N.md.
+ * each through its own write path. See docs/07-internationalization/index.md.
  */
 export type DirtyReason = 'none' | 'content' | 'direct-write' | 'both'
 
@@ -103,7 +103,7 @@ interface FormContextType {
   /**
    * Partition the current dirty state into content vs. system-field (path /
    * advertised-locales) writes so the Save button can branch. See
-   * docs/I18N.md.
+   * docs/07-internationalization/index.md.
    */
   getDirtyBreakdown: () => DirtyBreakdown
   subscribeField: (name: string, listener: FieldListener) => () => void
@@ -349,7 +349,7 @@ export const FormProvider = ({
   // button can route each piece correctly: content → versioned write; the
   // document-grain system fields (path / advertised locales) → immediate,
   // non-versioned direct write that leaves workflow status untouched.
-  // See docs/I18N.md.
+  // See docs/07-internationalization/index.md.
   const getDirtyBreakdown = useCallback((): DirtyBreakdown => {
     const keys = dirtyFields.current
     const pathDirty = keys.has(SYSTEM_PATH_DIRTY_KEY)

package/src/forms/form-modals.tsx

@@ -54,7 +54,7 @@ export const UnsavedChangesModal = ({ onClose }: { onClose: () => void }) => {
  * Confirms an immediate, non-versioned write of the document-grain system
  * fields (path / advertised locales) — which does NOT reset workflow status.
  * When content is also dirty, the copy reassures that content edits still
- * follow the normal revision + publish workflow. See docs/I18N.md.
+ * follow the normal revision + publish workflow. See docs/07-internationalization/index.md.
  */
 export const SystemFieldsConfirmModal = ({
   contentDirty,

package/src/forms/form-renderer.tsx

@@ -56,7 +56,7 @@ export interface PublishedVersionInfo {
  * patches) alongside the document-grain system fields (path / advertised
  * locales) and per-bucket dirty flags so the host can route each piece to the
  * right write path — versioned for content, immediate/non-versioned for the
- * system fields. See docs/I18N.md.
+ * system fields. See docs/07-internationalization/index.md.
  */
 export interface SystemFieldsSubmitPayload {
   // biome-ignore lint/suspicious/noExplicitAny: data is collection-specific
@@ -134,7 +134,7 @@ export interface FormRendererProps {
    * Opts the document-tree placement widget into the sidebar (above the
    * available-locales widget). Sourced from `CollectionDefinition.tree` by the
    * caller. Renders only in edit mode (placement needs a persisted document)
-   * and only when the host wires the tree services. See docs/DOCUMENT-TREE.md.
+   * and only when the host wires the tree services. See docs/04-collections/03-document-trees.md.
    */
   tree?: boolean
   headingLabel?: string
@@ -235,7 +235,7 @@ const FormContent = ({
   const [showUnsavedModal, setShowUnsavedModal] = useState(false)
   // Holds the pending Save payload while the editor confirms an immediate,
   // non-versioned system-field write (path / advertised locales). Non-null
-  // means the confirmation modal is open. See docs/I18N.md.
+  // means the confirmation modal is open. See docs/07-internationalization/index.md.
   const [pendingSystemFieldsSubmit, setPendingSystemFieldsSubmit] =
     useState<SystemFieldsSubmitPayload | null>(null)
   const [contentLocale, setContentLocale] = useState(initialLocale ?? defaultLocale)
@@ -532,7 +532,7 @@ const FormContent = ({
         {/* Source-locale anchor indicator removed pending heading-layout work.
             To re-enable: render `<SourceLocaleBadge locale={sourceLocale} />`
             here from `initialData.sourceLocale` (mismatch-only is the intended
-            end state). See docs/I18N.md. */}
+            end state). See docs/07-internationalization/index.md. */}
         {headerSlot}
       </div>
       <div className={cx('byline-form-status-bar', styles['status-bar'])}>

package/src/forms/tree-placement-widget.tsx

@@ -30,7 +30,7 @@ export interface TreePlacementWidgetProps {
 
 /**
  * Sidebar widget for placing the current document within its collection's
- * single-parent document tree (the `tree: true` primitive — docs/DOCUMENT-TREE.md).
+ * single-parent document tree (the `tree: true` primitive — docs/04-collections/03-document-trees.md).
  *
  * The tree is document-grain and **unversioned**, so changes here write
  * immediately (independent of the form's content save). The editor picks a

package/src/lib/create-command.ts

@@ -16,7 +16,7 @@ import { assertAdminActor, requireAdminActor } from './assert-admin-actor.js'
  * contract (validate → authorise → invoke → shape) into a single
  * declaration.
  *
- * Implements Phase 1 of `docs/CORE-COMPOSITION.md`. Today's scope is
+ * Implements Phase 1 of `docs/03-architecture/02-core-composition.md`. Today's scope is
  * `@byline/admin`-internal: it gates against admin actor identity using
  * the existing `assertAdminActor` / `requireAdminActor` helpers, which
  * inherit the super-admin bypass from `AdminAuth.assertAbility`.

package/src/modules/admin-activity/abilities.ts

@@ -9,7 +9,7 @@
 import type { AbilityRegistry } from '@byline/auth'
 
 /**
- * Ability keys for the admin-activity module (docs/AUDIT.md — Workstream 4).
+ * Ability keys for the admin-activity module (docs/06-auth-and-security/02-auditability.md — Workstream 4).
  *
  * `read` gates the system-wide activity area — the `/admin/activity` report
  * over the version-stream + audit-log union. It is deliberately a **separate**

package/src/modules/admin-activity/index.ts

@@ -8,7 +8,7 @@
 
 /**
  * `@byline/admin/admin-activity` — the system-wide activity area
- * (docs/AUDIT.md — Workstream 4).
+ * (docs/06-auth-and-security/02-auditability.md — Workstream 4).
  *
  * Unlike the other admin modules this one owns no table and no AdminStore
  * repository: the activity feed is a read over the document db adapter's

package/src/modules/admin-permissions/abilities.ts

@@ -11,7 +11,7 @@ import type { AbilityRegistry } from '@byline/auth'
 /**
  * Ability keys for the admin-permissions module.
  *
- * `read` gates the inspector view (see docs/AUTHN-AUTHZ.md).
+ * `read` gates the inspector view (see docs/06-auth-and-security/01-authn-authz.md).
  * `update` will gate the per-role ability editor mounted on the
  * admin-roles role detail page — declared here so the role editor can
  * assert against it once that surface lands. The per-role editor shares

package/src/modules/admin-permissions/components/inspector.tsx

@@ -9,7 +9,7 @@
  */
 
 /**
- * Read-only abilities inspector — see docs/AUTHN-AUTHZ.md.
+ * Read-only abilities inspector — see docs/06-auth-and-security/01-authn-authz.md.
  *
  * Top level: a collapsible group per ability source (collections.docs,
  * admin.users, etc.), each containing the abilities that group

package/src/modules/admin-users/repository.ts

@@ -128,7 +128,7 @@ export interface AdminUsersRepository {
   getById(id: string): Promise<AdminUserRow | null>
   /**
    * Bulk lookup for audit actor-label resolution (the `actors`
-   * map on admin document reads — see docs/AUDIT.md, Workstream 1). Ids
+   * map on admin document reads — see docs/06-auth-and-security/02-auditability.md, Workstream 1). Ids
    * with no matching row are simply absent from the result; callers
    * render a tombstone label for them.
    */

package/src/widgets/source-locale-badge/source-locale-badge.tsx

@@ -27,7 +27,7 @@ export interface SourceLocaleBadgeProps {
  * NOTE: currently rendered for *every* document so the anchor is visible during
  * development. The intended end state is to show it only when `locale` differs
  * from the system's current default content locale (a normal single-default
- * install then shows nothing). See docs/I18N.md.
+ * install then shows nothing). See docs/07-internationalization/index.md.
  *
  * Stable override handle: `.byline-source-locale-badge`.
  */