@anthusai/papyrus 1.10.0 → 1.12.0

package/components/ui/sheet.tsx

@@ -45,6 +45,7 @@ function SheetContent({
       <DialogPrimitive.Backdrop
         className={cn(
           "fixed inset-0 z-50 bg-black/40 data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+          typeof className === "string" && className.includes("md:hidden") && "md:hidden",
           backdropClassName,
         )}
       />

package/components/wiki-concepts-view.tsx

@@ -0,0 +1,153 @@
+"use client";
+
+import Link from "next/link";
+import { useEffect, useMemo, useState, type ReactNode } from "react";
+import type { SemanticNodeRecord } from "../lib/category-repository";
+import { isLocalPreviewEnabled } from "../lib/local-preview";
+import { getNewsroomNavHref } from "../lib/newsroom-nav";
+import type { createSemanticGraphSnapshot } from "../lib/semantic-graph";
+import {
+  conceptEditedAt, conceptId, conceptTitle, conceptWikiPath, conceptsByTitle, recentlyEditedConcepts, resolveConceptLink,
+} from "../lib/wiki";
+import { MarkusIrPreview } from "./markus-ir-preview";
+import { createWikiIndexPage, loadWikiIndexPage, type WikiIndexPage } from "./wiki-index-client";
+
+type SemanticGraph = ReturnType<typeof createSemanticGraphSnapshot>;
+
+const editedFormat = new Intl.DateTimeFormat(undefined, { dateStyle: "medium" });
+
+function formatEdited(value: string): string {
+  const parsed = new Date(value);
+  return value && !Number.isNaN(parsed.getTime()) ? editedFormat.format(parsed) : "";
+}
+
+function kindLabel(kind: string): string {
+  return kind.replace(/_/g, " ");
+}
+
+function ConceptLink({ children, demo, node, onOpen }: { children?: ReactNode; demo: boolean; node: SemanticNodeRecord; onOpen: (lineageId: string) => void }) {
+  return <a className="wiki-link" data-wiki-concept-link={conceptId(node)} href={getNewsroomNavHref(conceptWikiPath(node), demo)} onClick={event => { if (event.metaKey || event.ctrlKey || event.shiftKey) return; event.preventDefault(); onOpen(conceptId(node)); }}>{children ?? conceptTitle(node)}</a>;
+}
+
+function ConceptRows({ demo, nodes, onOpen, showEdited }: { demo: boolean; nodes: SemanticNodeRecord[]; onOpen: (lineageId: string) => void; showEdited?: boolean }) {
+  if (!nodes.length) return <p className="wiki-empty">No concepts to show.</p>;
+  return <ul className="wiki-concept-list">
+    {nodes.map(node => <li key={conceptId(node)}>
+      <ConceptLink demo={demo} node={node} onOpen={onOpen} />
+      <span className="wiki-chip">{kindLabel(node.nodeKind)}</span>
+      {showEdited && conceptEditedAt(node) && <span className="wiki-meta">edited {formatEdited(conceptEditedAt(node))}</span>}
+    </li>)}
+  </ul>;
+}
+
+function WikiIndexPageView({ demo, nodes, onOpen }: { demo: boolean; nodes: SemanticNodeRecord[]; onOpen: (lineageId: string) => void }) {
+  const [page, setPage] = useState<WikiIndexPage | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    loadWikiIndexPage(demo || isLocalPreviewEnabled()).then(loaded => { if (!cancelled) setPage(loaded); }).catch((reason: unknown) => { if (!cancelled) setError(reason instanceof Error ? reason.message : "Could not load the wiki index."); });
+    return () => { cancelled = true; };
+  }, [demo]);
+  const dynamicDirectives = useMemo(() => ({
+    "recent-concepts": (attributes: Record<string, unknown>) => <ConceptRows demo={demo} nodes={recentlyEditedConcepts(nodes, { kind: typeof attributes.kind === "string" ? attributes.kind : null, limit: Number(attributes.limit) || 10 })} onOpen={onOpen} showEdited />,
+    "concept-list": (attributes: Record<string, unknown>) => <ConceptRows demo={demo} nodes={conceptsByTitle(nodes, { kind: typeof attributes.kind === "string" ? attributes.kind : null, limit: Number(attributes.limit) || null })} onOpen={onOpen} />,
+    "concept-count": (attributes: Record<string, unknown>) => <strong>{nodes.filter(node => !attributes.kind || node.nodeKind === attributes.kind).length}</strong>,
+  }), [demo, nodes, onOpen]);
+  const renderLink = (href: string, children: ReactNode) => {
+    const node = resolveConceptLink(href, nodes);
+    return node ? <ConceptLink demo={demo} node={node} onOpen={onOpen}>{children}</ConceptLink> : null;
+  };
+  if (error) return <p className="wiki-empty" role="alert">{error}</p>;
+  if (!page) return <p className="wiki-empty">Loading the wiki…</p>;
+  return <article className="wiki-page" data-wiki-index>
+    <div className="wiki-page-tools">
+      {page.itemId
+        ? <Link className="wiki-tool-link" href={getNewsroomNavHref(`/newsroom/articles/${encodeURIComponent(page.itemId)}`, demo)}>Edit this page</Link>
+        : <button className="wiki-tool-link" disabled={saving} onClick={() => { setSaving(true); createWikiIndexPage(demo || isLocalPreviewEnabled()).then(setPage).catch((reason: unknown) => setError(reason instanceof Error ? reason.message : "Could not save the index.")).finally(() => setSaving(false)); }} type="button">{saving ? "Saving…" : "Save this page so it can be edited"}</button>}
+    </div>
+    <MarkusIrPreview bodyIr={page.bodyIr} dynamicDirectives={dynamicDirectives} renderLink={renderLink} />
+  </article>;
+}
+
+function ConceptPageView({ demo, graph, node, nodes, onOpen }: { demo: boolean; graph: SemanticGraph; node: SemanticNodeRecord; nodes: SemanticNodeRecord[]; onOpen: (lineageId: string) => void }) {
+  const lineage = conceptId(node);
+  const groups = graph.neighbors("semanticNode", lineage);
+  const references = graph.referencesForSemanticNode(lineage);
+  const byLineage = new Map(nodes.map(candidate => [conceptId(candidate), candidate]));
+  const aliases = (node.aliases ?? []).filter(Boolean) as string[];
+  return <article className="wiki-page" data-wiki-concept={lineage}>
+    <h1>{conceptTitle(node)}</h1>
+    <p className="wiki-meta"><span className="wiki-chip">{kindLabel(node.nodeKind)}</span> {node.status !== "current" && <span className="wiki-chip">{node.status}</span>} {conceptEditedAt(node) && <>Last edited {formatEdited(conceptEditedAt(node))}</>}{node.versionCreatedBy ? ` by ${node.versionCreatedBy}` : ""}</p>
+    {aliases.length > 0 && <p className="wiki-meta">Also known as {aliases.join(", ")}</p>}
+    {node.description ? node.description.split(/\n{2,}/).map((paragraph, index) => <p key={index}>{paragraph}</p>) : <p className="wiki-empty">This concept has no description yet.</p>}
+    <section data-wiki-section="connections">
+      <h2>Connections</h2>
+      {groups.length ? groups.map(group => <div className="wiki-connection-group" key={`${group.direction}-${group.predicate}`}>
+        <h3>{group.label}</h3>
+        <ul className="wiki-concept-list">
+          {group.objects.map(object => {
+            const target = object.kind === "semanticNode" ? byLineage.get(object.lineageId) : undefined;
+            return <li key={`${object.kind}-${object.lineageId}`}>{target ? <ConceptLink demo={demo} node={target} onOpen={onOpen} /> : <span>{object.label}</span>}<span className="wiki-chip">{target ? kindLabel(target.nodeKind) : object.kind}</span></li>;
+          })}
+        </ul>
+      </div>) : <p className="wiki-empty">No connections recorded.</p>}
+    </section>
+    <section data-wiki-section="references">
+      <h2>References</h2>
+      {references.length ? <ul className="wiki-concept-list">
+        {references.map(reference => <li key={reference.lineageId}><Link href={getNewsroomNavHref(`/newsroom/references/${encodeURIComponent(reference.lineageId)}`, demo)}>{reference.label}</Link></li>)}
+      </ul> : <p className="wiki-empty">No references recorded.</p>}
+    </section>
+  </article>;
+}
+
+/**
+ * The concept wiki: the front page is a content item whose Markus body can hold live components
+ * (recently edited concepts, concept lists), and every concept in the knowledge graph is a page
+ * linked to the concepts and references it connects to.
+ */
+export function WikiConceptsView({ demo = false, graph, initialNodeLineageId, nodes }: { demo?: boolean; graph: SemanticGraph; initialNodeLineageId?: string | null; nodes: SemanticNodeRecord[] }) {
+  const [selected, setSelected] = useState<string | null>(initialNodeLineageId ?? null);
+  const [search, setSearch] = useState("");
+  const [kind, setKind] = useState("");
+  useEffect(() => { setSelected(initialNodeLineageId ?? null); }, [initialNodeLineageId]);
+  useEffect(() => {
+    const onPop = () => {
+      const match = window.location.pathname.match(/\/concepts\/([^/?#]+)/);
+      setSelected(match ? decodeURIComponent(match[1]) : null);
+    };
+    window.addEventListener("popstate", onPop);
+    return () => window.removeEventListener("popstate", onPop);
+  }, []);
+  const open = (lineageId: string | null) => {
+    setSelected(lineageId);
+    const target = getNewsroomNavHref(lineageId ? `/newsroom/concepts/${encodeURIComponent(lineageId)}` : "/newsroom/concepts", demo);
+    if (`${window.location.pathname}${window.location.search}` !== target) window.history.pushState(null, "", target);
+  };
+  const node = selected ? nodes.find(candidate => conceptId(candidate) === selected || candidate.id === selected) ?? null : null;
+  const kinds = useMemo(() => Array.from(new Set(nodes.map(candidate => candidate.nodeKind))).sort(), [nodes]);
+  const matches = useMemo(() => {
+    const needle = search.trim().toLowerCase();
+    return conceptsByTitle(nodes, { kind: kind || null }).filter(candidate => !needle || conceptTitle(candidate).toLowerCase().includes(needle) || (candidate.aliases ?? []).some(alias => alias?.toLowerCase().includes(needle)));
+  }, [kind, nodes, search]);
+  return <div className="wiki" data-wiki>
+    <nav aria-label="Wiki" className="wiki-sidebar">
+      <button className="wiki-home" data-wiki-home aria-current={node ? undefined : "page"} onClick={() => open(null)} type="button">Wiki home</button>
+      <input aria-label="Search concepts" className="wiki-search" onChange={event => setSearch(event.target.value)} placeholder="Search concepts" value={search} />
+      {kinds.length > 1 && <select aria-label="Concept kind" className="wiki-kind" onChange={event => setKind(event.target.value)} value={kind}>
+        <option value="">All kinds</option>
+        {kinds.map(option => <option key={option} value={option}>{kindLabel(option)}</option>)}
+      </select>}
+      <ul className="wiki-sidebar-list">
+        {matches.map(candidate => <li key={conceptId(candidate)}><a aria-current={node && conceptId(node) === conceptId(candidate) ? "page" : undefined} href={getNewsroomNavHref(conceptWikiPath(candidate), demo)} onClick={event => { if (event.metaKey || event.ctrlKey || event.shiftKey) return; event.preventDefault(); open(conceptId(candidate)); }}>{conceptTitle(candidate)}</a></li>)}
+      </ul>
+    </nav>
+    <div className="wiki-main">
+      {node
+        ? <ConceptPageView demo={demo} graph={graph} node={node} nodes={nodes} onOpen={open} />
+        : selected ? <p className="wiki-empty" role="alert">That concept page was not found.</p>
+        : <WikiIndexPageView demo={demo} nodes={nodes} onOpen={open} />}
+    </div>
+  </div>;
+}

package/components/wiki-index-client.ts

@@ -0,0 +1,51 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import type { Schema } from "../amplify/data/resource";
+import { resolveArticlesBackend } from "../lib/newsroom-articles";
+import { isLocalPreviewEnabled } from "../lib/local-preview";
+import { DEFAULT_WIKI_INDEX_MARKUS, WIKI_INDEX_SLUG, WIKI_PAGE_ITEM_TYPE } from "../lib/wiki";
+import { configureAmplifyClient } from "./amplify-client-provider";
+
+export type WikiIndexPage = {
+  /** The id of the stored content item, or null while the wiki still shows the built-in starter content. */
+  itemId: string | null;
+  bodyMarkus: string;
+  bodyIr: unknown;
+};
+
+type GraphqlResponse = { data?: { itemBySlug?: { items?: Record<string, unknown>[] | null } | null } | null; errors?: { message?: string }[] | null };
+
+async function storedIndexRow(preview: boolean): Promise<Record<string, unknown> | null> {
+  if (preview || isLocalPreviewEnabled()) return null;
+  configureAmplifyClient();
+  const client = generateClient<Schema>() as unknown as { graphql: (options: Record<string, unknown>) => Promise<GraphqlResponse> };
+  const response = await client.graphql({
+    query: "query ($slug: String!) { itemBySlug(slug: $slug) { items { id versionNumber versionState bodyMarkus bodyIr } } }",
+    variables: { slug: WIKI_INDEX_SLUG },
+    authMode: "userPool",
+  });
+  if (response.errors?.length) throw new Error(response.errors.map(error => error.message ?? "GraphQL error").join("; "));
+  const rows = (response.data?.itemBySlug?.items ?? []).filter(Boolean) as Record<string, unknown>[];
+  const ranked = rows.sort((left, right) => Number(right.versionNumber ?? 0) - Number(left.versionNumber ?? 0));
+  return ranked.find(row => row.versionState === "current") ?? ranked[0] ?? null;
+}
+
+async function derive(bodyMarkus: string, preview: boolean): Promise<unknown> {
+  const result = await resolveArticlesBackend(preview).actions.deriveMarkus({ frontMatterYaml: null, bodyMarkus, includeIr: true });
+  return result.bodyIr ?? null;
+}
+
+/** Loads the wiki's front page content item, falling back to the starter content until one is saved. */
+export async function loadWikiIndexPage(preview: boolean): Promise<WikiIndexPage> {
+  const row = await storedIndexRow(preview);
+  const bodyMarkus = typeof row?.bodyMarkus === "string" && row.bodyMarkus.trim() ? row.bodyMarkus : DEFAULT_WIKI_INDEX_MARKUS;
+  const storedIr = row?.bodyIr;
+  return { itemId: row ? String(row.id) : null, bodyMarkus, bodyIr: storedIr ?? await derive(bodyMarkus, preview) };
+}
+
+/** Saves the starter index as the wiki-index content item so editors can change it like any other page. */
+export async function createWikiIndexPage(preview: boolean): Promise<WikiIndexPage> {
+  const saved = await resolveArticlesBackend(preview).actions.saveItemDraft({ id: null, type: WIKI_PAGE_ITEM_TYPE, slug: WIKI_INDEX_SLUG, section: null, frontMatterYaml: `title: Concept wiki\n`, bodyMarkus: DEFAULT_WIKI_INDEX_MARKUS, aliases: [], expectedContentHash: null });
+  return { itemId: saved.item.id, bodyMarkus: DEFAULT_WIKI_INDEX_MARKUS, bodyIr: await derive(DEFAULT_WIKI_INDEX_MARKUS, preview) };
+}

package/lib/content-actions-client.ts

@@ -13,6 +13,9 @@ export type SaveItemDraftInput = {
   bodyMarkus: string;
   aliases: string[];
   expectedContentHash: string | null;
+  /** Records a new draft version of the story instead of correcting the current one in place. */
+  newVersion?: boolean;
+  changeReason?: string | null;
 };
 
 export type DeriveMarkusResult = { ok: true; bodyIrBytes: number; bodyIr?: unknown; errors: [] };

package/lib/content-actions-demo.ts

@@ -1,4 +1,5 @@
 import { ContentActionFailure } from "./content-actions-client";
+import { isLocalPreviewEnabled } from "./local-preview";
 import type {
   DeriveMarkusInput,
   DeriveMarkusResult,
@@ -12,7 +13,7 @@ import {
   demoContentHash,
   type DemoArticleRecord,
 } from "./newsroom-demo-articles";
-import { createLocalPreviewEditableArticle } from "./local-preview-seed";
+import { createLocalPreviewEditableArticle, lineageForPreviewVersion, recordLocalPreviewDesk, recordLocalPreviewVersion } from "./local-preview-seed";
 import { sourceLineOffset, type ArticlesBackend, type EditableArticle, type NewsroomArticleRow } from "./newsroom-articles";
 
 function titleFromYaml(frontMatterYaml: string | null, fallback: string): string {
@@ -30,6 +31,18 @@ function demoAttribute(attributes: string, name: string): string {
   return match ? match[1] : "";
 }
 
+async function deriveThroughPreviewMarkusEngine(input: DeriveMarkusInput): Promise<DeriveMarkusResult | null> {
+  try {
+    const response = await fetch("/api/local-preview/derive", { method: "POST", body: JSON.stringify({ frontMatterYaml: input.frontMatterYaml, bodyMarkus: input.bodyMarkus }) });
+    if (!response.ok) return null;
+    const result = await response.json() as DeriveMarkusResult & { error?: string };
+    if (result.error) return null;
+    return input.includeIr ? result : { ...result, bodyIr: undefined };
+  } catch {
+    return null;
+  }
+}
+
 function demoEnvelope(bodyMarkus: string) {
   const images: Record<string, Record<string, unknown>> = {};
   const children = bodyMarkus
@@ -74,6 +87,10 @@ export function createDemoArticlesBackend(): ArticlesBackend {
   return {
     actions: {
       async deriveMarkus(input: DeriveMarkusInput): Promise<DeriveMarkusResult> {
+        if (isLocalPreviewEnabled()) {
+          const derived = await deriveThroughPreviewMarkusEngine(input);
+          if (derived) return derived;
+        }
         const lines = input.bodyMarkus.split("\n");
         const invalidIndex = lines.findIndex((line) => line.includes(":::nope"));
         if (invalidIndex >= 0) {
@@ -91,6 +108,28 @@ export function createDemoArticlesBackend(): ArticlesBackend {
       },
       async saveItemDraft(input: SaveItemDraftInput): Promise<SaveItemDraftResult> {
         const existing = input.id ? requireRecord(input.id) : null;
+        if (input.newVersion && existing) {
+          const lineageId = createLocalPreviewEditableArticle(existing.id)?.lineageId ?? existing.id;
+          const versionNumber = (existing.versionNumber ?? 1) + 1;
+          const id = `${lineageId}-v${versionNumber}`;
+          const frontMatterYaml = input.frontMatterYaml ?? "";
+          const record: DemoArticleRecord = {
+            ...existing,
+            id,
+            slug: existing.slug,
+            section: input.section,
+            title: titleFromYaml(input.frontMatterYaml, existing.slug),
+            status: "draft",
+            frontMatterYaml,
+            bodyMarkus: input.bodyMarkus,
+            contentHash: demoContentHash(frontMatterYaml, input.bodyMarkus),
+            versionNumber,
+            updatedAt: new Date().toISOString(),
+          };
+          records.set(id, record);
+          recordLocalPreviewVersion(lineageId, { id, versionNumber, versionState: "current", status: "draft", stage: null, headline: record.title, changeReason: input.changeReason ?? null, versionCreatedBy: "You", versionCreatedAt: record.updatedAt, updatedAt: record.updatedAt });
+          return { ok: true, item: { id, contentHash: record.contentHash, status: "draft", slug: record.slug, versionNumber } };
+        }
         if (existing && input.expectedContentHash !== null && input.expectedContentHash !== existing.contentHash) {
           throw new ContentActionFailure([
             { code: "conflict", message: "The item changed since it was loaded.", line: null },
@@ -120,6 +159,7 @@ export function createDemoArticlesBackend(): ArticlesBackend {
           updatedAt: new Date().toISOString(),
         };
         records.set(id, record);
+        recordLocalPreviewDesk(id, record.section);
         return {
           ok: true,
           item: {
@@ -172,11 +212,23 @@ export function createDemoArticlesBackend(): ArticlesBackend {
         .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
     },
     async loadArticle(id: string): Promise<EditableArticle> {
-      const previewRecord = records.get(id) ? null : createLocalPreviewEditableArticle(id);
-      if (previewRecord) return previewRecord;
+      if (!records.has(id)) {
+        const previewRecord = createLocalPreviewEditableArticle(id);
+        if (previewRecord) {
+          records.set(id, {
+            ...previewRecord,
+            title: titleFromYaml(previewRecord.frontMatterYaml, previewRecord.slug),
+            status: previewRecord.status === "published" ? "published" : "draft",
+            contentHash: demoContentHash(previewRecord.frontMatterYaml, previewRecord.bodyMarkus),
+            publishedContentHash: previewRecord.status === "published" ? demoContentHash(previewRecord.frontMatterYaml, previewRecord.bodyMarkus) : null,
+            updatedAt: new Date().toISOString(),
+          });
+        }
+      }
       const record = requireRecord(id);
       return {
         id: record.id,
+        lineageId: createLocalPreviewEditableArticle(record.id)?.lineageId ?? lineageForPreviewVersion(record.id),
         type: record.type,
         section: record.section,
         slug: record.slug,

package/lib/content-item-lifecycle.ts

@@ -28,9 +28,9 @@ export const DEFAULT_CONTENT_ITEM_STAGE_DEFINITIONS: readonly ContentItemStageDe
   { key: "copywriting", label: "Copywriting" },
   { key: "illustration", label: "Illustration" },
   { key: "typesetting", label: "Typesetting" },
-  { key: "published", label: "Published" },
-  { key: "held", label: "Held" },
   { key: "spiked", label: "Spiked", collapsedUntilOpened: true },
+  { key: "held", label: "Held" },
+  { key: "published", label: "Published" },
 ];
 
 export function contentItemStageKeys(stageDefinitions: readonly ContentItemStageDefinition[]): string[] {
@@ -68,6 +68,8 @@ export type ContentItemVersionRecord = {
   status: string;
   title?: string | null;
   headline?: string | null;
+  deck?: string | null;
+  metadata?: unknown;
   slug: string;
   section?: string | null;
   updatedAt?: string | null;

package/lib/content-source-context.ts

@@ -1,10 +1,13 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { getContentSource, type ContentSource } from "./site-env";
+import { tenantIdFromEnvironment } from "./tenant-keys";
 
 export type ContentSourceContext = {
   source: ContentSource;
   /** Request-scoped data client (drafts mode: carries the visitor's session cookies). */
   client?: unknown;
+  /** Tenant of the selected Prospectus account; falls back to PAPYRUS_TENANT_ID. */
+  tenantId?: string;
 };
 
 const contentSourceStorage = new AsyncLocalStorage<ContentSourceContext>();
@@ -13,8 +16,13 @@ export function runWithContentSource<T>(
   source: ContentSource,
   operation: () => Promise<T>,
   client?: unknown,
+  tenantId?: string,
 ): Promise<T> {
-  return contentSourceStorage.run({ source, client }, operation);
+  return contentSourceStorage.run({ source, client, tenantId }, operation);
+}
+
+export function currentTenantId(): string | undefined {
+  return contentSourceStorage.getStore()?.tenantId ?? tenantIdFromEnvironment();
 }
 
 export function currentRequestClient<T>(): T | undefined {

package/lib/curation-delegation-helpers.ts

@@ -0,0 +1,59 @@
+export const DEFAULT_DELEGATION_HOURS = 8;
+export const MINIMUM_DELEGATION_HOURS = 1;
+export const MAXIMUM_DELEGATION_HOURS = 72;
+
+export type CurationDelegationRecord = {
+  delegationId: string;
+  agentLabel: string;
+  grantorLabel: string | null;
+  expiresAt: string;
+  revokedAt: string | null;
+};
+
+export type DelegationInputValidation =
+  | { ok: true; agentLabel: string; hours: number }
+  | { ok: false; message: string };
+
+export function validateDelegationInput(agentLabelText: string, hoursText: string): DelegationInputValidation {
+  const agentLabel = agentLabelText.trim();
+  if (!agentLabel) return { ok: false, message: "Enter the name of the agent you are trusting." };
+  if (/\s/.test(agentLabel)) return { ok: false, message: "The agent name cannot contain spaces. Use the name the agent passes as --agent." };
+  const trimmedHours = hoursText.trim();
+  if (!/^\d+$/.test(trimmedHours)) return { ok: false, message: `Enter a whole number of hours from ${MINIMUM_DELEGATION_HOURS} to ${MAXIMUM_DELEGATION_HOURS}.` };
+  const hours = Number(trimmedHours);
+  if (hours < MINIMUM_DELEGATION_HOURS || hours > MAXIMUM_DELEGATION_HOURS) {
+    return { ok: false, message: `A delegation lasts from ${MINIMUM_DELEGATION_HOURS} to ${MAXIMUM_DELEGATION_HOURS} hours.` };
+  }
+  return { ok: true, agentLabel, hours };
+}
+
+export function delegationExpiryText(expiresAt: string, revokedAt: string | null, nowMilliseconds: number): string {
+  if (revokedAt) return "Revoked";
+  const remaining = Date.parse(expiresAt) - nowMilliseconds;
+  if (!Number.isFinite(remaining) || remaining <= 0) return "Expired";
+  const minutes = Math.ceil(remaining / 60_000);
+  if (minutes < 60) return `Expires in ${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+  const hours = Math.round(remaining / 3_600_000);
+  return `Expires in ${hours} ${hours === 1 ? "hour" : "hours"}`;
+}
+
+export function isDelegationActive(record: CurationDelegationRecord, nowMilliseconds: number): boolean {
+  return !record.revokedAt && Date.parse(record.expiresAt) > nowMilliseconds;
+}
+
+export function buildDelegatedCommandLine(input: { email: string; agentLabel: string; token: string; action?: "approve" | "reject" }): string {
+  const email = input.email.trim() || "<your-email>";
+  return `papyrus references ${input.action ?? "approve"} <reference-id> --on-behalf-of ${email} --agent ${input.agentLabel} --instruction "<the person's own words>" --delegation-token ${input.token}`;
+}
+
+export function describeDelegationError(error: unknown): string {
+  const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  const graphql = (error as { errors?: Array<{ message?: string }> } | null)?.errors?.[0]?.message ?? "";
+  const text = `${raw} ${graphql}`.toLowerCase();
+  if (text.includes("not authorized") || text.includes("unauthorized")) return "Your account is not allowed to manage delegations. Only editors and administrators can.";
+  if (text.includes("not found")) return "That delegation no longer exists.";
+  if (text.includes("only the person who granted")) return "Only the person who granted a delegation, or an administrator, can revoke it.";
+  if (text.includes("network") || text.includes("failed to fetch")) return "Could not reach the server. Check your connection and try again.";
+  const detail = (graphql || raw).trim();
+  return detail ? `The server refused the request: ${detail}` : "Something went wrong. Nothing was changed.";
+}