@medicine-wheel/app 0.6.4 → 0.8.0

package/app/episodes/page.tsx

@@ -0,0 +1,222 @@
+"use client";
+
+/**
+ * The episodes surface — "what am I working on, and what came before it".
+ *
+ * `/api/nodes` has accepted `?kind=` and `?parent_id=` for some time, and no
+ * page ever passed either. So the only way to see an episode in this app was to
+ * find its dot on a wheel of 205, where 37% of the mass has no edge at all and
+ * the largest hubs are systemd units. The wheel could answer this question and
+ * was never asked it.
+ *
+ * Sorted by `metadata.occurred_at` when present, falling back to `created_at`.
+ * That fallback is not a nicety: `created_at` records when the wheel *learned*
+ * of an episode, not when the episode happened — 41 of 83 episodes disagree with
+ * their own date, and twelve May episodes all carry the same September timestamp
+ * from one import batch. Until `occurred_at` is backfilled this list is ordered
+ * by registration for those rows, and it says so rather than implying a history
+ * it does not have.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import Link from "next/link";
+import type { RelationalNode } from "@/lib/types";
+
+// `description` lives on the store's node, not on ontology-core's — the same
+// widening `app/nodes/page.tsx` declares as `NodeRecord`.
+type Episode = RelationalNode & {
+  description?: string;
+  metadata?: Record<string, unknown>;
+};
+
+const DIRECTION_ICONS: Record<string, string> = {
+  east: "🌅",
+  south: "🔥",
+  west: "🌊",
+  north: "❄️",
+};
+
+/** `chronicle:2026-06-19-episode-068-extending-…` → `068`, or null. */
+function episodeNumber(id: string): string | null {
+  const match = id.match(/episode-(\d+)/i);
+  return match ? match[1] : null;
+}
+
+/** The date the episode happened, if the wheel knows it apart from registration. */
+function occurredAt(node: Episode): string | null {
+  const value = node.metadata?.occurred_at;
+  return typeof value === "string" && value ? value : null;
+}
+
+function sortKey(node: Episode): string {
+  return occurredAt(node) ?? node.created_at ?? "";
+}
+
+function formatDate(iso: string): string {
+  if (!iso) return "—";
+  return iso.slice(0, 10);
+}
+
+export default function EpisodesPage() {
+  const [episodes, setEpisodes] = useState<Episode[]>([]);
+  const [attentionCounts, setAttentionCounts] = useState<Record<string, number>>({});
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [query, setQuery] = useState("");
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    try {
+      // limit=all, not the provider's 100-row default. The chronicle holds more
+      // episodes than a default page, and a list that silently ends is worse
+      // than one that refuses to load.
+      const [episodesRes, attentionRes] = await Promise.all([
+        fetch("/api/nodes?kind=chronicle_episode&limit=all"),
+        fetch("/api/nodes?kind=attention&limit=all"),
+      ]);
+
+      if (!episodesRes.ok) throw new Error(`Episodes: ${episodesRes.status}`);
+      const episodesBody = await episodesRes.json();
+      const list: Episode[] = episodesBody.nodes ?? [];
+
+      const counts: Record<string, number> = {};
+      if (attentionRes.ok) {
+        const attentionBody = await attentionRes.json();
+        for (const item of (attentionBody.nodes ?? []) as Episode[]) {
+          const parent = item.metadata?.parent_id;
+          if (typeof parent === "string") counts[parent] = (counts[parent] ?? 0) + 1;
+        }
+      }
+
+      setEpisodes([...list].sort((a, b) => sortKey(b).localeCompare(sortKey(a))));
+      setAttentionCounts(counts);
+      setError(null);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const visible = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    if (!needle) return episodes;
+    return episodes.filter(
+      (e) =>
+        e.name.toLowerCase().includes(needle) ||
+        e.id.toLowerCase().includes(needle) ||
+        (e.description ?? "").toLowerCase().includes(needle),
+    );
+  }, [episodes, query]);
+
+  /** How many rows are ordered by registration rather than by when they happened. */
+  const undatedCount = useMemo(
+    () => episodes.filter((e) => !occurredAt(e)).length,
+    [episodes],
+  );
+
+  return (
+    <div className="p-6 max-w-5xl mx-auto">
+      <div className="flex items-start justify-between mb-6 gap-4 flex-wrap">
+        <div>
+          <h1 className="text-2xl font-bold">Episodes</h1>
+          <p className="text-sm text-muted-foreground">
+            {loading ? "Reading the chronicle…" : `${episodes.length} episodes in the wheel`}
+          </p>
+        </div>
+        <input
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          placeholder="Filter by name or id"
+          className="mw-input max-w-xs"
+          aria-label="Filter episodes"
+        />
+      </div>
+
+      {undatedCount > 0 && !loading && (
+        <p className="mb-4 text-xs text-muted-foreground border rounded-lg p-3 bg-card">
+          {undatedCount} of {episodes.length} episodes have no <code>occurred_at</code>, so they
+          are ordered by when the wheel recorded them rather than by when they happened. That is
+          registration order, not history.
+        </p>
+      )}
+
+      {error && (
+        <div className="mb-4 p-4 border rounded-lg bg-card">
+          <p className="text-sm font-medium">The chronicle did not answer.</p>
+          <p className="text-sm text-muted-foreground">{error}</p>
+          <button onClick={load} className="mw-btn mw-btn--ghost mt-2">
+            Try again
+          </button>
+        </div>
+      )}
+
+      {!loading && episodes.length === 0 && !error && (
+        <p className="text-sm text-muted-foreground">
+          No node carries <code>metadata.kind: &quot;chronicle_episode&quot;</code>. The wheel is
+          reachable and holds no episodes — which is a different thing from the wheel being
+          unreachable.
+        </p>
+      )}
+
+      <ul className="space-y-2">
+        {visible.map((episode) => {
+          const number = episodeNumber(episode.id);
+          const open = attentionCounts[episode.id] ?? 0;
+          const dated = occurredAt(episode);
+          return (
+            <li key={episode.id}>
+              <Link
+                href={`/episodes/${encodeURIComponent(episode.id)}`}
+                className="block p-4 border rounded-lg bg-card hover:bg-secondary/50 transition-colors"
+              >
+                <div className="flex items-baseline justify-between gap-3 flex-wrap">
+                  <div className="flex items-baseline gap-2 min-w-0">
+                    {number && (
+                      <span className="font-mono text-xs text-muted-foreground shrink-0">
+                        {number}
+                      </span>
+                    )}
+                    <span className="font-medium truncate">{episode.name}</span>
+                  </div>
+                  <div className="flex items-center gap-2 shrink-0">
+                    {open > 0 && (
+                      <span className="mw-badge" title={`${open} open attention items`}>
+                        {open} attention
+                      </span>
+                    )}
+                    {episode.direction && (
+                      <span className={`mw-badge mw-badge--${episode.direction}`}>
+                        {DIRECTION_ICONS[episode.direction]} {episode.direction}
+                      </span>
+                    )}
+                    <span
+                      className="font-mono text-xs text-muted-foreground"
+                      title={dated ? "occurred_at" : "created_at — when the wheel learned this"}
+                    >
+                      {formatDate(dated ?? episode.created_at ?? "")}
+                      {!dated && "*"}
+                    </span>
+                  </div>
+                </div>
+                {episode.description && (
+                  <p className="text-sm text-muted-foreground mt-1 line-clamp-2">
+                    {episode.description}
+                  </p>
+                )}
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+
+      {!loading && visible.length === 0 && episodes.length > 0 && (
+        <p className="text-sm text-muted-foreground">Nothing matches “{query}”.</p>
+      )}
+    </div>
+  );
+}

package/app/graph/page.tsx

@@ -98,10 +98,34 @@ export default function GraphPage() {
   const [graph, setGraph] = useState<MWGraphData>({ nodes: [], links: [] });
   const [selectedNode, setSelectedNode] = useState<MWGraphNode | null>(null);
   const [focusedNodeId, setFocusedNodeId] = useState<string | undefined>(undefined);
+  /**
+   * Scope is not focus.
+   *
+   * `focusedNodeId` zooms the viewport at a node and leaves all 205 mounted —
+   * useful, and not an answer to "I cannot navigate", because the field is still
+   * there behind the zoom. `scopeId` replaces the graph with one node's
+   * neighbourhood, so the canvas holds only what was asked for. Two names
+   * because they are two questions; collapsing them would make the control
+   * silently mean different things depending on how the page was entered.
+   */
+  const [scopeId, setScopeId] = useState<string | null>(null);
+  // 1, not 2. With the chronicle root at degree 82, depth 2 from any episode
+  // used to return the whole corpus — see the route's DEFAULT_DEPTH.
+  const [scopeDepth, setScopeDepth] = useState(1);
+  const [scopeMeta, setScopeMeta] = useState<{
+    count: number;
+    truncated: boolean;
+    hubs: { id: string; name: string; degree: number; reason: string; unexpanded: number }[];
+    rootName: string | null;
+  } | null>(null);
+  const [storeTotal, setStoreTotal] = useState<number | null>(null);
   const [highlightDirection, setHighlightDirection] = useState<DirectionParam | undefined>(undefined);
   const [radialSnap, setRadialSnap] = useState<"off" | "ring" | "sector">("off");
   const [loading, setLoading] = useState(true);
-  const [showLabels, setShowLabels] = useState(true);
+  // `null` means "nobody has chosen" — the default then follows the crowding
+  // (see labelsAutoSuppressed). Once the user touches the toggle their choice
+  // sticks, including across a scope change.
+  const [showLabels, setShowLabels] = useState<boolean | null>(null);
   const [animationsEnabled, setAnimationsEnabled] = useState(
     DEFAULT_GRAPH_ANIMATION_ENABLED,
   );
@@ -166,22 +190,54 @@ export default function GraphPage() {
 
   const loadData = useCallback(async () => {
     try {
-      const [nodesRes, edgesRes] = await Promise.all([fetch("/api/nodes"), fetch("/api/edges")]);
+      // Scoped and whole-wheel are different questions, not the same question
+      // with a filter. `focusedNodeId` already existed and only zooms the
+      // viewport — every one of the 205 nodes stays mounted, so "focus" was
+      // never a way to look at less. Scope replaces the data.
+      if (scopeId) {
+        const res = await fetch(
+          `/api/nodes/${encodeURIComponent(scopeId)}/web?depth=${scopeDepth}`,
+        );
+        if (!res.ok) {
+          toast.error(
+            res.status === 404
+              ? "That node is not in the wheel."
+              : "Could not read that neighbourhood.",
+          );
+          setScopeId(null);
+          return;
+        }
+        const web = await res.json();
+        setGraph(buildGraphData(web.nodes ?? [], web.edges ?? []));
+        setScopeMeta({
+          count: web.count ?? 0,
+          truncated: Boolean(web.truncated),
+          hubs: web.hubs ?? [],
+          rootName: web.root?.name ?? null,
+        });
+        return;
+      }
+
+      const [nodesRes, edgesRes] = await Promise.all([fetch("/api/nodes?limit=all"), fetch("/api/edges?limit=all")]);
       const nodesResponse = await nodesRes.json();
       const edgesData: RelationalEdge[] = await edgesRes.json();
 
-      // API returns { nodes: [...], provider: '...', count: N }
+      // API returns { nodes: [...], provider: '...', count: N, total, truncated }
       const nodesData: RelationalNode[] = Array.isArray(nodesResponse)
         ? nodesResponse
         : nodesResponse.nodes || [];
 
       setGraph(buildGraphData(nodesData, edgesData));
+      setScopeMeta(null);
+      setStoreTotal(
+        Array.isArray(nodesResponse) ? nodesData.length : (nodesResponse.total ?? nodesData.length),
+      );
     } catch {
       toast.error("Failed to load graph data");
     } finally {
       setLoading(false);
     }
-  }, []);
+  }, [scopeId, scopeDepth]);
 
   useEffect(() => {
     loadData();
@@ -204,12 +260,31 @@ export default function GraphPage() {
     const params = new URLSearchParams(window.location.search);
     const node = params.get("node");
     if (node) setFocusedNodeId(node);
+    // ?scope=<id> arrives from an episode page's "Open in graph" and means
+    // "show me this and its neighbours", not "zoom at this".
+    const scope = params.get("scope");
+    if (scope) {
+      setScopeId(scope);
+      setFocusedNodeId(scope);
+    }
     const direction = params.get("direction");
     if (direction && (DIRECTION_NAMES as readonly string[]).includes(direction)) {
       setHighlightDirection(direction as DirectionParam);
     }
   }, []);
 
+  // Escape leaves the neighbourhood and returns the whole wheel. It is the only
+  // way out that needs no aiming, which matters when the reason you scoped was
+  // that you could not find anything.
+  useEffect(() => {
+    if (!scopeId) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setScopeId(null);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [scopeId]);
+
   // Surface the deep-linked node in the side panel once data arrives.
   useEffect(() => {
     if (!focusedNodeId || graph.nodes.length === 0) return;
@@ -217,10 +292,58 @@ export default function GraphPage() {
     if (node) setSelectedNode(node);
   }, [focusedNodeId, graph.nodes]);
 
-  const graphData = useMemo<MWGraphData>(
-    () => (focusedNodeId ? { ...graph, focusedNodeId } : graph),
-    [graph, focusedNodeId],
-  );
+  /**
+   * The node you asked about must be findable in the picture.
+   *
+   * Before this, arriving from an episode page put your episode somewhere in a
+   * field of identical dots — the graph knew which node you meant (it zoomed at
+   * it) and gave you no way to see which one it was once you panned. Marking is
+   * done here rather than in `graph-viz` because `MedicineWheelNode` already
+   * reads `size`, `color` and `opacity` off each node; the renderer needs no
+   * new concept, only better data.
+   *
+   * Hubs are dimmed rather than hidden. The chronicle root genuinely is in your
+   * neighbourhood — every episode belongs to it — but it is context, not the
+   * subject, and drawing it at full weight makes the one true container compete
+   * with the thing you were looking at.
+   */
+  const graphData = useMemo<MWGraphData>(() => {
+    const hubIds = new Set((scopeMeta?.hubs ?? []).map((h) => h.id));
+    const marked =
+      scopeId || hubIds.size > 0
+        ? {
+            ...graph,
+            nodes: graph.nodes.map((n) => {
+              if (n.id === scopeId) {
+                return {
+                  ...n,
+                  size: (n.size ?? 8) * 1.9,
+                  color: "#ffd75e",
+                  opacity: 1,
+                };
+              }
+              if (hubIds.has(n.id)) {
+                return { ...n, size: (n.size ?? 8) * 1.25, opacity: 0.45 };
+              }
+              return n;
+            }),
+          }
+        : graph;
+
+    return focusedNodeId ? { ...marked, focusedNodeId } : marked;
+  }, [graph, focusedNodeId, scopeId, scopeMeta]);
+
+  /**
+   * Labels are legible up to a point and then they are texture.
+   *
+   * At 83 nodes crushed into one quadrant the labels stacked into unreadable
+   * bands — worse than absent, because they cost the whole canvas its clarity
+   * while conveying nothing. Off past the threshold, and the existing toggle
+   * still wins: this sets the default, it does not take the control away.
+   */
+  const LABEL_LEGIBLE_UP_TO = 35;
+  const labelsAutoSuppressed = graph.nodes.length > LABEL_LEGIBLE_UP_TO;
+  const labelsVisible = showLabels ?? !labelsAutoSuppressed;
 
   useEffect(() => {
     layoutStoreRef.current = layoutStore;
@@ -430,10 +553,15 @@ export default function GraphPage() {
           </div>
           <div className="flex flex-wrap gap-2">
             <button
-              onClick={() => setShowLabels(!showLabels)}
-              className={`min-h-11 px-3 py-1.5 rounded text-sm ${showLabels ? "bg-white/10" : "bg-white/5"}`}
+              onClick={() => setShowLabels(!labelsVisible)}
+              className={`min-h-11 px-3 py-1.5 rounded text-sm ${labelsVisible ? "bg-white/10" : "bg-white/5"}`}
+              title={
+                showLabels === null && labelsAutoSuppressed
+                  ? `Off by default above ${LABEL_LEGIBLE_UP_TO} nodes — they overlap into bands`
+                  : undefined
+              }
             >
-              Labels {showLabels ? "ON" : "OFF"}
+              Labels {labelsVisible ? "ON" : "OFF"}
             </button>
             <button
               onClick={() =>
@@ -450,6 +578,64 @@ export default function GraphPage() {
           </div>
         </div>
 
+        {scopeId && (
+          <div className="mb-3 rounded-xl border border-yellow-400/30 bg-yellow-400/5 px-3 py-2 text-sm">
+            {/* min-w-0 on the growing child, so a long chronicle id truncates
+                instead of pushing the depth control and the exit off-screen —
+                the banner clipped its own warning at this width before. */}
+            <div className="flex flex-wrap items-center gap-x-3 gap-y-2">
+              <span className="min-w-0 flex-1 text-gray-300">
+                <strong className="text-yellow-300">
+                  {scopeMeta?.count ?? graph.nodes.length}
+                </strong>{" "}
+                nodes, {scopeDepth} {scopeDepth === 1 ? "hop" : "hops"} from{" "}
+                <span className="text-gray-100">{scopeMeta?.rootName ?? scopeId}</span>
+              </span>
+              <label className="inline-flex shrink-0 items-center gap-1.5 text-xs text-gray-400">
+                Depth
+                <select
+                  value={scopeDepth}
+                  onChange={(e) => setScopeDepth(Number(e.target.value))}
+                  className="rounded bg-white/5 px-1.5 py-0.5 text-gray-200"
+                  aria-label="Neighbourhood depth"
+                >
+                  {[1, 2, 3, 4, 5, 6].map((d) => (
+                    <option key={d} value={d}>
+                      {d}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <button
+                onClick={() => setScopeId(null)}
+                className="min-h-8 shrink-0 rounded bg-white/5 px-2 py-1 text-xs hover:bg-white/10 inline-flex items-center gap-1.5"
+              >
+                <X className="h-3.5 w-3.5" /> Whole wheel
+                <span className="text-gray-500">(Esc)</span>
+              </button>
+            </div>
+
+            {/* Say what was held back. A neighbourhood that quietly stopped at a
+                container is the same class of lie as a list that quietly
+                stopped at 100 rows. */}
+            {(scopeMeta?.hubs?.length ?? 0) > 0 && (
+              <p className="mt-1.5 text-xs text-gray-500">
+                {scopeMeta!.hubs.map((h) => (
+                  <span key={h.id} className="mr-3 inline-block">
+                    <span className="text-gray-400">{h.name}</span> holds {h.degree} relations —
+                    shown, not expanded{h.unexpanded > 0 ? ` (${h.unexpanded} beyond it)` : ""}
+                  </span>
+                ))}
+              </p>
+            )}
+            {scopeMeta?.truncated && (
+              <p className="mt-1 text-xs text-gray-500">
+                stopped at the depth limit — there is more further out
+              </p>
+            )}
+          </div>
+        )}
+
         <div className="flex flex-col lg:flex-row gap-4 lg:gap-6">
           <div className="relative flex-1 rounded-xl border border-white/10 overflow-hidden">
             {!loading && graph.nodes.length > 0 && (
@@ -477,7 +663,7 @@ export default function GraphPage() {
                 data={graphData}
                 height={graphHeight}
                 darkMode
-                showNodeLabels={showLabels}
+                showNodeLabels={labelsVisible}
                 showMiniMap={!isMobile}
                 animationsEnabled={animationsEnabled}
                 nodePositions={activeLayout.positions}
@@ -633,6 +819,14 @@ export default function GraphPage() {
                   <div><span className="text-xs text-gray-500">Type</span><p className="capitalize">{selectedNode.type}</p></div>
                   {selectedNode.direction && <div><span className="text-xs text-gray-500">Direction</span><p className="capitalize">{selectedNode.direction}</p></div>}
                   <div><span className="text-xs text-gray-500">ID</span><p className="text-xs text-gray-400 font-mono break-all">{selectedNode.id}</p></div>
+                  {scopeId !== selectedNode.id && (
+                    <button
+                      onClick={() => setScopeId(selectedNode.id)}
+                      className="inline-flex w-full items-center justify-center gap-2 rounded-md bg-yellow-400/15 px-3 py-2 text-sm text-yellow-200 hover:bg-yellow-400/25"
+                    >
+                      <Route className="h-4 w-4" /> Show only its neighbourhood
+                    </button>
+                  )}
                   <Link
                     href={`/nodes?node=${encodeURIComponent(selectedNode.id)}`}
                     className="inline-flex w-full items-center justify-center gap-2 rounded-md bg-white/10 px-3 py-2 text-sm text-white hover:bg-white/15"
@@ -644,9 +838,25 @@ export default function GraphPage() {
             )}
 
             <div className="rounded-xl border border-white/10 p-4">
-              <h3 className="text-sm font-semibold text-gray-400 mb-3">Graph Stats</h3>
+              <h3 className="text-sm font-semibold text-gray-400 mb-3">
+                Graph Stats
+                {/* This panel read "100 Nodes / 100 Relations" against a store of
+                    205 and 191 until 2026-09-03, because the page fetched without
+                    a limit and took the provider's default page in silence. A
+                    count with nothing to compare it to cannot be doubted, which
+                    is what made it a lie rather than a number. */}
+                {scopeId && <span className="ml-2 font-normal text-yellow-300/80">scoped</span>}
+              </h3>
               <div className="grid grid-cols-2 gap-3 text-center">
-                <div><p className="text-2xl font-bold">{graph.nodes.length}</p><p className="text-xs text-gray-500">Nodes</p></div>
+                <div>
+                  <p className="text-2xl font-bold">{graph.nodes.length}</p>
+                  <p className="text-xs text-gray-500">
+                    Nodes
+                    {storeTotal !== null && graph.nodes.length < storeTotal && (
+                      <span className="text-gray-600"> of {storeTotal}</span>
+                    )}
+                  </p>
+                </div>
                 <div><p className="text-2xl font-bold">{graph.links.length}</p><p className="text-xs text-gray-500">Relations</p></div>
                 <div><p className="text-2xl font-bold">{ceremoniedCount}</p><p className="text-xs text-gray-500">Ceremonied</p></div>
                 <div><p className="text-2xl font-bold">{directionCount}</p><p className="text-xs text-gray-500">Directions</p></div>

package/app/nodes/page.tsx

@@ -50,13 +50,16 @@ export default function NodesPage() {
   const loadNodes = useCallback(async () => {
     setLoading(true);
     try {
-      const params = new URLSearchParams();
+      // The list is client-side paginated below, so it needs the whole store.
+      // Without this the route applies its 100-row default and the table silently
+      // ends at 100 of 205 with no page control to reveal the rest.
+      const params = new URLSearchParams({ limit: "all" });
       if (filterType !== "all") params.set("type", filterType);
       if (filterDirection !== "all") params.set("direction", filterDirection);
 
       const [nodesRes, edgesRes] = await Promise.all([
         fetch(`/api/nodes?${params.toString()}`),
-        fetch("/api/edges"),
+        fetch("/api/edges?limit=all"),
       ]);
       const nodesResponse = await nodesRes.json();
       const edgesData: RelationalEdge[] = edgesRes.ok ? await edgesRes.json() : [];

package/app/relations/page.tsx

@@ -64,7 +64,7 @@ export default function RelationsPage() {
   const loadData = useCallback(async () => {
     setLoading(true);
     try {
-      const [nodesRes, edgesRes] = await Promise.all([fetch("/api/nodes"), fetch("/api/edges")]);
+      const [nodesRes, edgesRes] = await Promise.all([fetch("/api/nodes?limit=all"), fetch("/api/edges?limit=all")]);
       const nodesResponse = await nodesRes.json();
       const edgesData = await edgesRes.json();
       const nodesData: NodeRecord[] = Array.isArray(nodesResponse) ? nodesResponse : (nodesResponse.nodes || []);

package/components/navigation.tsx

@@ -13,6 +13,7 @@ import { WorkspacesPanel, WORKSPACES, type Workspace } from "@/components/worksp
 const NAV_ITEMS = [
   { href: "/", label: "Wheel", color: "var(--mw-east)" },
   { href: "/graph", label: "Graph", color: "var(--mw-primary)" },
+  { href: "/episodes", label: "Episodes", color: "var(--mw-node-ancestor)" },
   { href: "/nodes", label: "Nodes", color: "var(--mw-node-land)" },
   { href: "/relations", label: "Relations", color: "var(--mw-node-future)" },
   { href: "/ceremonies", label: "Ceremonies", color: "var(--mw-south)" },

package/lib/api-paging.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared paging contract for the wheel's read routes.
+ *
+ * The provider's `getAllNodes()` / `getAllEdges()` default to 100 rows. A bare
+ * `GET /api/nodes` therefore returned 100 of the store's 205 nodes, and the graph
+ * page — which sends no parameters — drew that window while its own panel read
+ * "100 Nodes / 100 Relations". Of the 100 it drew, 53 had no drawable edge,
+ * because 27 of the 100 delivered edges pointed at nodes that were never sent.
+ *
+ * Nothing was broken. Every layer did what it was told. The lie was that no layer
+ * ever said how much it had left out.
+ *
+ * So both routes accept the same `limit`, and both report enough for a caller to
+ * know it holds a page: `?limit=all` for the whole store, `?limit=<n>` for n.
+ * This lives in `lib/` rather than in either route because a second hand-written
+ * copy of a validation rule is how the two drift apart — the same defect this
+ * repo just removed from `PersonRole`.
+ */
+import { NextResponse } from "next/server";
+
+/** The provider's own default page size, restated so a route can report honestly. */
+export const DEFAULT_PAGE_SIZE = 100;
+
+/** Sentinel meaning "the whole store", distinct from "no limit given". */
+export const LIMIT_ALL = "all";
+
+/**
+ * Returns the requested page size, `null` for "everything", or a 400 response.
+ *
+ * An unparseable limit is refused rather than coerced. Falling back to the
+ * default on bad input would reintroduce the silent truncation this parameter
+ * exists to close, and would do it precisely when a caller had tried to ask.
+ */
+export function parseLimit(raw: string | null): number | null | NextResponse {
+  if (raw === null || raw === "") return DEFAULT_PAGE_SIZE;
+  if (raw === LIMIT_ALL) return null;
+
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return NextResponse.json(
+      {
+        error: `Invalid limit: ${raw} — nothing was returned.`,
+        hint: `limit must be a positive integer, or "${LIMIT_ALL}" for the whole store.`,
+      },
+      { status: 400 },
+    );
+  }
+  return parsed;
+}