@medicine-wheel/app 0.17.2 → 0.17.4

package/README.md

@@ -95,7 +95,7 @@ Ceremony lifecycle protocol — manages ceremony state, four-phase transitions (
 - **Dependencies:** `@medicine-wheel/ontology-core`
 
 ### [@medicine-wheel/fire-keeper](src/fire-keeper)
-Fire Keeper coordination agent — tends the ceremony fire, ensures relational integrity through gating conditions, permission tier escalation, and maintains Wilson alignment as an active agent that evaluates, gates, routes, and escalates.
+Fire Keeper coordination agent — tends the ceremony fire through gating conditions (consent, ceremony phase, trajectory confidence), permission tier escalation, and human decision points; it evaluates, gates, routes, and escalates. It does not measure relational accountability; people judge that (#155).
 
 - **Dependencies:** `@medicine-wheel/ontology-core`, `@medicine-wheel/ceremony-protocol`
 
@@ -130,7 +130,7 @@ Four-source epistemic dimensional indexing — Land, Dream, Code, Vision travers
 - **Dependencies:** `@medicine-wheel/ontology-core`
 
 ### [@medicine-wheel/transformation-tracker](src/transformation-tracker)
-Research transformation tracking — Wilson validity criterion: "If research doesn't change you, you haven't done it right." Tracks researcher growth, community impact, relational shifts, reciprocity balance, and seven-generation sustainability.
+Research transformation tracking — built on the lesson Wilson quotes from his co-researchers, "If research doesn't change you as a person, then you haven't done it right" (2008, p. 135); the validity check is ours. Tracks researcher growth, community impact, relational shifts, reciprocity balance, and seven-generation sustainability.
 
 - **Dependencies:** `@medicine-wheel/ontology-core`, `@medicine-wheel/ceremony-protocol`, `zod`
 

package/app/episodes/[id]/page.tsx

@@ -12,14 +12,15 @@
  * that filtered by episode long before any page asked them
  * (`components/episode-holdings.tsx`). What is open, from
  * `?kind=attention&parent_id=<id>`. What it relates to, from
- * `/api/nodes/[id]/web`, which walks the traversal that shipped in
- * `relational-query` and went unimported. Ref jgwill/medicine-wheel#153.
+ * `/api/nodes/[id]/web`: its lineage first — each relation to another episode
+ * read from this episode's end ("continues from", "continued by") with the
+ * words that say why it holds — then everything else it touches
+ * (`lib/episode-lineage.ts`). Ref jgwill/medicine-wheel#153, #156.
  *
- * The relations panel is where the wheel's current honesty shows. 101 of 106
- * containment links live only in `metadata.parent_id` and were never written as
- * edges, so most episodes will show a parent here that has no relation behind
- * it. The panel names that rather than rendering an empty box, because an empty
- * box reads as "this episode touches nothing" when the truth is "the edge was
+ * Containment links that live only in `metadata.parent_id` were never written
+ * as edges, so an episode can show a parent with no relation behind it. The
+ * page names that rather than rendering an empty box, because an empty box
+ * reads as "this episode touches nothing" when the truth is "the edge was
  * never written".
  */
 
@@ -29,6 +30,13 @@ import Link from "next/link";
 import type { RelationalNode, RelationalEdge } from "@/lib/types";
 import { EpisodeFilesPanel } from "@/components/episode-files-panel";
 import { EpisodeHoldings } from "@/components/episode-holdings";
+import {
+  chronicleKey,
+  episodeFolderOfNode,
+  relationsOf,
+  type EpisodeRelation,
+  type LineageEdge,
+} from "@/lib/episode-lineage";
 
 // `description` lives on the store's node, not on ontology-core's — the same
 // widening `app/nodes/page.tsx` declares as `NodeRecord`. Named EpisodeNode
@@ -50,31 +58,39 @@ function metaString(node: EpisodeNode | null, key: string): string | null {
   return typeof value === "string" && value ? value : null;
 }
 
-/**
- * Where an episode sits in the chronicle: its folder's date, then its number —
- * the order the folders keep on disk. Not `created_at`, which records when the
- * wheel learned of an episode, and not the number alone, which the chronicle
- * does not hand out in date order (episode 1000 follows episode 550 by two days).
- */
-function chronicleKey(node: EpisodeNode): string {
-  const match = (episodeFolderOf(node) ?? "").match(/^(\d{4}-\d{2}-\d{2})-episode-(\d+)/i);
-  return match ? `${match[1]}-${match[2].padStart(6, "0")}` : (node.created_at ?? "");
-}
-
-/**
- * The episode's folder name — what the wheel's other records file it under.
- *
- * From the id when it is `chronicle:<folder>`. A few early episodes were
- * registered under other ids (`node:knowledge:…`, a bare uuid); their node
- * still carries the artefact reference, so the folder comes from
- * `metadata.relative_path` when `metadata.root` names the chronicle.
- */
-function episodeFolderOf(node: EpisodeNode): string | null {
-  if (node.id.startsWith("chronicle:")) return node.id.slice("chronicle:".length) || null;
-  const relative = metaString(node, "relative_path");
-  if (metaString(node, "root") !== "MIADI_CHRONICLE_ROOT" || !relative) return null;
-  const folder = relative.split("/")[0];
-  return folder && folder !== relative ? folder : null;
+/** One relation, as read from this episode, with the words that say why it holds. */
+function RelationRow({
+  relation,
+  node,
+  episode = false,
+}: {
+  relation: EpisodeRelation;
+  node?: EpisodeNode;
+  episode?: boolean;
+}) {
+  const name = node?.name ?? relation.other;
+  return (
+    <li className="p-3 border rounded-lg bg-card">
+      <p className="text-sm">
+        <span className="text-muted-foreground">{relation.label}</span>{" "}
+        {episode ? (
+          <Link href={`/episodes/${encodeURIComponent(relation.other)}`} className="font-medium hover:underline">
+            {name}
+          </Link>
+        ) : (
+          <span className="font-medium">{name}</span>
+        )}
+      </p>
+      {!episode && (
+        <span className="font-mono text-xs text-muted-foreground block break-all">{relation.other}</span>
+      )}
+      {relation.descriptions.map((said) => (
+        <p key={said} className="text-sm text-muted-foreground mt-1">
+          {said}
+        </p>
+      ))}
+    </li>
+  );
 }
 
 function EpisodeLink({ node, label }: { node: EpisodeNode | null; label: string }) {
@@ -140,10 +156,18 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
   }, [load]);
 
   const parentId = metaString(episode, "parent_id");
-  const folder = episode ? episodeFolderOf(episode) : null;
+  const folder = episode ? episodeFolderOfNode(episode) : null;
   const neighbours = (web?.nodes ?? []).filter((n) => n.id !== id);
   const parentHasEdge = Boolean(parentId && neighbours.some((n) => n.id === parentId));
 
+  // Each relation read from this episode's end, with the words that say why it
+  // holds; episodes first (the lineage), then everything else it touches.
+  const nodeById = new Map(neighbours.map((n) => [n.id, n]));
+  const relations = relationsOf(id, (web?.edges ?? []) as LineageEdge[]);
+  const isEpisodeId = (other: string) => nodeById.get(other)?.metadata?.kind === "chronicle_episode";
+  const lineage = relations.filter((r) => isEpisodeId(r.other));
+  const elsewhere = relations.filter((r) => !isEpisodeId(r.other));
+
   if (loading) {
     return <div className="p-6 max-w-4xl mx-auto text-sm text-muted-foreground">Loading…</div>;
   }
@@ -231,7 +255,24 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
 
       <section>
         <h2 className="text-sm font-semibold mb-2">
-          Relations {neighbours.length > 0 && `(${neighbours.length})`}
+          Lineage {lineage.length > 0 && `(${lineage.length})`}
+        </h2>
+        {lineage.length === 0 ? (
+          <p className="text-sm text-muted-foreground">
+            No relation to another episode has been woven yet.
+          </p>
+        ) : (
+          <ul className="space-y-2">
+            {lineage.map((r) => (
+              <RelationRow key={`${r.other}-${r.label}`} relation={r} node={nodeById.get(r.other)} episode />
+            ))}
+          </ul>
+        )}
+      </section>
+
+      <section>
+        <h2 className="text-sm font-semibold mb-2">
+          Also related {elsewhere.length > 0 && `(${elsewhere.length})`}
         </h2>
 
         {parentId && !parentHasEdge && (
@@ -242,37 +283,15 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
           </p>
         )}
 
-        {neighbours.length === 0 ? (
+        {elsewhere.length === 0 ? (
           <p className="text-sm text-muted-foreground">
-            No relation reaches this episode. {parentId ? "See the note above." : ""}
+            Nothing else is related to this episode. {parentId && !parentHasEdge ? "See the note above." : ""}
           </p>
         ) : (
           <ul className="space-y-2">
-            {neighbours.map((n) => {
-              const edge = (web?.edges ?? []).find(
-                (e) =>
-                  (e.from_id === id && e.to_id === n.id) ||
-                  (e.to_id === id && e.from_id === n.id),
-              );
-              return (
-                <li
-                  key={n.id}
-                  className="p-3 border rounded-lg bg-card flex items-baseline justify-between gap-3 flex-wrap"
-                >
-                  <span className="min-w-0">
-                    <span className="text-sm font-medium">{n.name}</span>
-                    <span className="font-mono text-xs text-muted-foreground block break-all">
-                      {n.id}
-                    </span>
-                  </span>
-                  {edge && (
-                    <span className="mw-badge shrink-0" title="relationship_type">
-                      {edge.from_id === id ? "→" : "←"} {edge.relationship_type}
-                    </span>
-                  )}
-                </li>
-              );
-            })}
+            {elsewhere.map((r) => (
+              <RelationRow key={`${r.other}-${r.label}`} relation={r} node={nodeById.get(r.other)} />
+            ))}
           </ul>
         )}
 

package/app/episodes/page.tsx

@@ -21,6 +21,10 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import Link from "next/link";
 import type { RelationalNode } from "@/lib/types";
+import { EpisodeLineageWeb } from "@/components/episode-lineage-web";
+import { chronicleKey, episodeDateOf, lineageEdges, type LineageEdge } from "@/lib/episode-lineage";
+
+type View = "list" | "lineage";
 
 // `description` lives on the store's node, not on ontology-core's — the same
 // widening `app/nodes/page.tsx` declares as `NodeRecord`.
@@ -63,6 +67,24 @@ export default function EpisodesPage() {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [query, setQuery] = useState("");
+  const [edges, setEdges] = useState<LineageEdge[]>([]);
+  const [edgesFailed, setEdgesFailed] = useState(false);
+  const [view, setView] = useState<View>("list");
+
+  // `?view=lineage` opens on the lineage, so it can be linked to. Read once on
+  // mount from the location rather than through useSearchParams, which would
+  // need a Suspense boundary around the whole page.
+  useEffect(() => {
+    if (new URLSearchParams(window.location.search).get("view") === "lineage") setView("lineage");
+  }, []);
+
+  const choose = useCallback((next: View) => {
+    setView(next);
+    const url = new URL(window.location.href);
+    if (next === "lineage") url.searchParams.set("view", "lineage");
+    else url.searchParams.delete("view");
+    window.history.replaceState(null, "", url);
+  }, []);
 
   const load = useCallback(async () => {
     setLoading(true);
@@ -70,9 +92,10 @@ export default function EpisodesPage() {
       // 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([
+      const [episodesRes, attentionRes, edgesRes] = await Promise.all([
         fetch("/api/nodes?kind=chronicle_episode&limit=all"),
         fetch("/api/nodes?kind=attention&limit=all"),
+        fetch("/api/edges?limit=all").catch(() => null),
       ]);
 
       if (!episodesRes.ok) throw new Error(`Episodes: ${episodesRes.status}`);
@@ -90,6 +113,18 @@ export default function EpisodesPage() {
 
       setEpisodes([...list].sort((a, b) => sortKey(b).localeCompare(sortKey(a))));
       setAttentionCounts(counts);
+
+      // The relations are a second answer: if they do not come, the list still does.
+      const ids = new Set(list.map((e) => e.id));
+      if (edgesRes?.ok) {
+        const body = await edgesRes.json();
+        const all: LineageEdge[] = Array.isArray(body) ? body : (body.edges ?? []);
+        setEdges(lineageEdges(all, (id) => ids.has(id)));
+        setEdgesFailed(false);
+      } else {
+        setEdges([]);
+        setEdgesFailed(true);
+      }
       setError(null);
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e));
@@ -113,6 +148,30 @@ export default function EpisodesPage() {
     );
   }, [episodes, query]);
 
+  /** Relations to other episodes, per episode. */
+  const relationCounts = useMemo(() => {
+    const counts: Record<string, number> = {};
+    for (const edge of edges) {
+      counts[edge.from_id] = (counts[edge.from_id] ?? 0) + 1;
+      counts[edge.to_id] = (counts[edge.to_id] ?? 0) + 1;
+    }
+    return counts;
+  }, [edges]);
+
+  /** The lineage reads oldest first, in the folders' own order. */
+  const chronological = useMemo(
+    () =>
+      [...episodes]
+        .sort((a, b) => chronicleKey(a).localeCompare(chronicleKey(b)))
+        .map((e) => ({ id: e.id, name: e.name, direction: e.direction, date: episodeDateOf(e) ?? occurredAt(e)?.slice(0, 10) })),
+    [episodes],
+  );
+
+  const matching = useMemo(
+    () => (query.trim() ? new Set(visible.map((e) => e.id)) : null),
+    [query, visible],
+  );
+
   /** How many rows are ordered by registration rather than by when they happened. */
   const undatedCount = useMemo(
     () => episodes.filter((e) => !occurredAt(e)).length,
@@ -128,16 +187,41 @@ export default function EpisodesPage() {
             {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 className="flex items-center gap-2 flex-wrap">
+          <div className="flex gap-1" role="group" aria-label="View">
+            {(["list", "lineage"] as const).map((v) => (
+              <button
+                key={v}
+                onClick={() => choose(v)}
+                aria-pressed={view === v}
+                className={`mw-btn ${view === v ? "" : "mw-btn--ghost"}`}
+              >
+                {v === "list" ? "List" : "Lineage"}
+              </button>
+            ))}
+          </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>
       </div>
 
-      {undatedCount > 0 && !loading && (
+      {view === "lineage" && !loading && episodes.length > 0 && (
+        <div className="mb-6">
+          {edgesFailed && (
+            <p className="mb-2 text-xs text-muted-foreground">
+              The wheel did not answer for its relations, so the lineage shows episodes without arcs.
+            </p>
+          )}
+          <EpisodeLineageWeb episodes={chronological} edges={edges} matches={matching} />
+        </div>
+      )}
+
+      {view === "list" && 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
@@ -163,10 +247,12 @@ export default function EpisodesPage() {
         </p>
       )}
 
+      {view === "list" && (
       <ul className="space-y-2">
         {visible.map((episode) => {
           const number = episodeNumber(episode.id);
           const open = attentionCounts[episode.id] ?? 0;
+          const related = relationCounts[episode.id] ?? 0;
           const dated = occurredAt(episode);
           return (
             <li key={episode.id}>
@@ -184,6 +270,11 @@ export default function EpisodesPage() {
                     <span className="font-medium truncate">{episode.name}</span>
                   </div>
                   <div className="flex items-center gap-2 shrink-0">
+                    {related > 0 && (
+                      <span className="mw-badge" title={`${related} relations to other episodes`}>
+                        {related} related
+                      </span>
+                    )}
                     {open > 0 && (
                       <span className="mw-badge" title={`${open} open attention items`}>
                         {open} attention
@@ -213,8 +304,9 @@ export default function EpisodesPage() {
           );
         })}
       </ul>
+      )}
 
-      {!loading && visible.length === 0 && episodes.length > 0 && (
+      {view === "list" && !loading && visible.length === 0 && episodes.length > 0 && (
         <p className="text-sm text-muted-foreground">Nothing matches “{query}”.</p>
       )}
     </div>

package/components/episode-lineage-web.tsx

@@ -0,0 +1,247 @@
+"use client";
+
+/**
+ * The chronicle as a lineage: every episode on a spine read left to right, in
+ * its direction's band, with the relations between episodes drawn as arcs.
+ *
+ * Miadi's chronicle opens on this picture (`LineageWeb`), and it answers what a
+ * list cannot: which episodes carry a thread forward, which stand alone, where
+ * the work keeps returning. The wheel already holds every relation it draws.
+ *
+ * Tap an episode to see its relations and the words that say why each holds;
+ * tap it again, or its name, to open it. Touch first — a phone has no hover.
+ * Ref jgwill/medicine-wheel#156.
+ */
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { isContinuation, relationsOf, type LineageEdge } from "@/lib/episode-lineage";
+
+export interface LineageEpisode {
+  id: string;
+  name: string;
+  direction?: string;
+  /** `YYYY-MM-DD`, when known: the axis is labelled by month. */
+  date?: string;
+}
+
+const BANDS = ["east", "south", "west", "north"] as const;
+const BAND_ICON: Record<string, string> = { east: "🌅", south: "🔥", west: "🌊", north: "❄️" };
+const BAND_H = 64;
+const TOP = 28;
+const AXIS = 26;
+const STEP = 15;
+const MARGIN_L = 72;
+const MARGIN_R = 24;
+const H = TOP + BAND_H * BANDS.length + AXIS;
+
+function bandOf(direction?: string): number {
+  const at = BANDS.indexOf((direction ?? "") as (typeof BANDS)[number]);
+  return at === -1 ? 1.5 : at;
+}
+
+export function EpisodeLineageWeb({
+  episodes,
+  edges,
+  matches,
+}: {
+  /** In chronicle order, oldest first. */
+  episodes: LineageEpisode[];
+  /** Episode↔episode relations only. */
+  edges: LineageEdge[];
+  /** When a filter is typed: the episodes it matches. The rest fade. */
+  matches?: Set<string> | null;
+}) {
+  const router = useRouter();
+  const scroller = useRef<HTMLDivElement>(null);
+  const [selected, setSelected] = useState<string | null>(null);
+  const [hovered, setHovered] = useState<string | null>(null);
+
+  const layout = useMemo(() => {
+    const position = new Map<string, { x: number; y: number }>();
+    episodes.forEach((episode, i) => {
+      const x = MARGIN_L + i * STEP;
+      // A small stagger so neighbours in one band do not sit on one line.
+      const y = TOP + (bandOf(episode.direction) + 0.5) * BAND_H + ((i % 3) - 1) * 13;
+      position.set(episode.id, { x, y });
+    });
+    const width = Math.max(MARGIN_L + (episodes.length - 1) * STEP + MARGIN_R, 360);
+
+    const months: Array<{ x: number; label: string }> = [];
+    let last = "";
+    episodes.forEach((episode, i) => {
+      const month = episode.date?.slice(0, 7) ?? "";
+      if (month && month !== last) {
+        months.push({ x: MARGIN_L + i * STEP, label: month });
+        last = month;
+      }
+    });
+
+    const degree = new Map<string, number>();
+    for (const edge of edges) {
+      degree.set(edge.from_id, (degree.get(edge.from_id) ?? 0) + 1);
+      degree.set(edge.to_id, (degree.get(edge.to_id) ?? 0) + 1);
+    }
+    return { position, width, months, degree };
+  }, [episodes, edges]);
+
+  // The newest episodes are where the work is: open scrolled to the right.
+  useEffect(() => {
+    const el = scroller.current;
+    if (el) el.scrollLeft = el.scrollWidth;
+  }, [layout.width]);
+
+  const focus = hovered ?? selected;
+  const near = useMemo(() => {
+    if (!focus) return null;
+    const set = new Set([focus]);
+    for (const edge of edges) {
+      if (edge.from_id === focus) set.add(edge.to_id);
+      if (edge.to_id === focus) set.add(edge.from_id);
+    }
+    return set;
+  }, [focus, edges]);
+
+  const byId = useMemo(() => new Map(episodes.map((e) => [e.id, e])), [episodes]);
+  const chosen = selected ? byId.get(selected) : undefined;
+  const chosenRelations = useMemo(
+    () => (selected ? relationsOf(selected, edges) : []),
+    [selected, edges],
+  );
+
+  function open(id: string) {
+    router.push(`/episodes/${encodeURIComponent(id)}`);
+  }
+
+  function tap(id: string) {
+    if (selected === id) open(id);
+    else setSelected(id);
+  }
+
+  const faded = (id: string) =>
+    (near !== null && !near.has(id)) || (matches != null && !matches.has(id));
+
+  return (
+    <div className="space-y-3">
+      <div ref={scroller} className="overflow-x-auto border rounded-lg bg-card">
+        <svg
+          width={layout.width}
+          height={H}
+          viewBox={`0 0 ${layout.width} ${H}`}
+          role="img"
+          aria-label={`${episodes.length} episodes in chronicle order, with ${edges.length} relations between them`}
+          onClick={(event) => {
+            if (event.target === event.currentTarget) setSelected(null);
+          }}
+        >
+          {BANDS.map((band, i) => (
+            <g key={band}>
+              <line
+                x1={0}
+                x2={layout.width}
+                y1={TOP + (i + 1) * BAND_H}
+                y2={TOP + (i + 1) * BAND_H}
+                stroke="var(--mw-border)"
+                strokeWidth={1}
+                opacity={0.5}
+              />
+              <text x={8} y={TOP + i * BAND_H + 16} fontSize={11} fill="var(--mw-muted)">
+                {BAND_ICON[band]} {band}
+              </text>
+            </g>
+          ))}
+
+          {layout.months.map((m) => (
+            <text key={m.label} x={m.x} y={H - 8} fontSize={10} fill="var(--mw-muted)">
+              {m.label}
+            </text>
+          ))}
+
+          {edges.map((edge) => {
+            const a = layout.position.get(edge.from_id);
+            const b = layout.position.get(edge.to_id);
+            if (!a || !b) return null;
+            const lit = focus !== null && (edge.from_id === focus || edge.to_id === focus);
+            const lift = Math.min(110, Math.abs(b.x - a.x) * 0.3) + 18;
+            const top = Math.max(6, Math.min(a.y, b.y) - lift);
+            const continuation = isContinuation(edge);
+            return (
+              <path
+                key={edge.id}
+                d={`M ${a.x} ${a.y} Q ${(a.x + b.x) / 2} ${top} ${b.x} ${b.y}`}
+                fill="none"
+                stroke={lit ? "var(--mw-primary)" : "var(--mw-muted)"}
+                strokeWidth={lit ? 2 : 1}
+                strokeDasharray={continuation ? undefined : "3 3"}
+                opacity={lit ? 1 : focus ? 0.12 : continuation ? 0.55 : 0.3}
+              />
+            );
+          })}
+
+          {episodes.map((episode) => {
+            const p = layout.position.get(episode.id)!;
+            const related = (layout.degree.get(episode.id) ?? 0) > 0;
+            const isSelected = episode.id === selected;
+            return (
+              <g
+                key={episode.id}
+                onClick={() => tap(episode.id)}
+                onMouseEnter={() => setHovered(episode.id)}
+                onMouseLeave={() => setHovered(null)}
+                style={{ cursor: "pointer" }}
+                opacity={faded(episode.id) ? 0.2 : 1}
+              >
+                <title>{episode.name}</title>
+                {/* A target a finger can hit, larger than the dot it holds. */}
+                <circle cx={p.x} cy={p.y} r={9} fill="transparent" />
+                <circle
+                  cx={p.x}
+                  cy={p.y}
+                  r={related ? 4.5 : 3}
+                  fill={`var(--mw-${episode.direction ?? "west"}-ink, var(--mw-muted))`}
+                  stroke={isSelected ? "var(--mw-primary)" : "none"}
+                  strokeWidth={isSelected ? 2.5 : 0}
+                />
+              </g>
+            );
+          })}
+        </svg>
+      </div>
+
+      {chosen ? (
+        <div className="p-3 border rounded-lg bg-card space-y-2">
+          <div className="flex items-baseline justify-between gap-3 flex-wrap">
+            <Link href={`/episodes/${encodeURIComponent(chosen.id)}`} className="text-sm font-medium hover:underline">
+              {chosen.name}
+            </Link>
+            <span className="text-xs text-muted-foreground">{chosen.date}</span>
+          </div>
+          {chosenRelations.length === 0 ? (
+            <p className="text-xs text-muted-foreground">No relation to another episode has been woven yet.</p>
+          ) : (
+            <ul className="space-y-1">
+              {chosenRelations.map((r) => (
+                <li key={`${r.other}-${r.label}`} className="text-sm">
+                  <span className="text-muted-foreground">{r.label}</span>{" "}
+                  <button className="hover:underline text-left" onClick={() => setSelected(r.other)}>
+                    {byId.get(r.other)?.name ?? r.other}
+                  </button>
+                  {r.descriptions[0] && (
+                    <p className="text-xs text-muted-foreground pl-3">{r.descriptions[0]}</p>
+                  )}
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      ) : (
+        <p className="text-xs text-muted-foreground">
+          Each dot is an episode, oldest on the left, in its direction&apos;s band. Solid arcs carry
+          a thread forward (continues from); dashed arcs relate two episodes. Tap a dot to see why
+          they are related; tap it again to open it.
+        </p>
+      )}
+    </div>
+  );
+}

package/lib/episode-lineage.ts

@@ -0,0 +1,165 @@
+/**
+ * An episode's lineage, read from the relations the wheel already holds.
+ *
+ * Miadi's chronicle writes every episode↔episode relation to the wheel as an
+ * edge, with the words that say why it holds in `description` (jgwill/Miadi#702,
+ * jgwill/medicine-wheel#150). The wheel kept them, and its Episodes tab listed a
+ * neighbour's name and a raw `relationship_type` — never the words, and never
+ * which way the relation runs. This module turns an edge into the sentence a
+ * reader expects from where they stand: on episode 549, `549 continues_from 045`
+ * reads "continues from 045"; on episode 045, the same edge reads "continued by
+ * 549".
+ *
+ * Pure functions, no fetching: the episode page and the lineage web read the
+ * same answer. Ref jgwill/medicine-wheel#156.
+ */
+
+export interface LineageEdge {
+  id: string;
+  from_id: string;
+  to_id: string;
+  relationship_type: string;
+  description?: string;
+}
+
+export interface EpisodeRelation {
+  /** The node on the other end. */
+  other: string;
+  /** The relation as read from this episode: "continues from", "continued by", "relates to"… */
+  label: string;
+  /** Lineage relations sort first, in this order; everything else after them. */
+  rank: number;
+  /** The words that say why it holds — one per edge that said something. */
+  descriptions: string[];
+  /** The edges this relation was read from (two when both directions were woven). */
+  edgeIds: string[];
+}
+
+/**
+ * Relations with a direction: [as read from `from_id`, as read from `to_id`].
+ * Both spellings appear on the chronicle wheel (`continues_from` from Miadi's
+ * lineage door, `continues-from` from an earlier writer), so both are named.
+ */
+const DIRECTED: Record<string, [string, string]> = {
+  continues_from: ["continues from", "continued by"],
+  "continues-from": ["continues from", "continued by"],
+  continued_by: ["continued by", "continues from"],
+  "continued-by": ["continued by", "continues from"],
+  descends_from: ["descends from", "gave rise to"],
+  "descends-from": ["descends from", "gave rise to"],
+  born_from: ["born from", "gave birth to"],
+};
+
+/** Relations that read the same from either end. */
+const SYMMETRIC = new Set(["relates_to", "relates-to", "speaks-with", "speaks_with"]);
+
+const RANK: Record<string, number> = {
+  "continues from": 0,
+  "descends from": 0,
+  "born from": 0,
+  "continued by": 1,
+  "gave rise to": 1,
+  "gave birth to": 1,
+  "relates to": 2,
+};
+
+function words(type: string): string {
+  return type.replace(/[_-]+/g, " ").trim().toLowerCase();
+}
+
+/** One edge, read from `episodeId`'s end. Null when the edge does not touch it, or loops on it. */
+export function readEdge(episodeId: string, edge: LineageEdge): { other: string; label: string } | null {
+  const outgoing = edge.from_id === episodeId;
+  const incoming = edge.to_id === episodeId;
+  if (outgoing === incoming) return null;
+  const other = outgoing ? edge.to_id : edge.from_id;
+  const type = edge.relationship_type ?? "";
+  const directed = DIRECTED[type.toLowerCase()];
+  if (directed) return { other, label: outgoing ? directed[0] : directed[1] };
+  if (SYMMETRIC.has(type.toLowerCase())) return { other, label: words(type) };
+  // A type the chronicle has not named a reverse for keeps its own words, and
+  // an arrow says which way it was written.
+  return { other, label: `${outgoing ? "→" : "←"} ${words(type) || "related"}` };
+}
+
+/**
+ * Every relation touching an episode, one per (other node, reading).
+ *
+ * Miadi's lineage door can weave a relation both ways — `A relates_to B` and
+ * `B relates_to A`, each with its own words. Read from A, those are the same
+ * relation said twice, so they merge and keep both sets of words. Two different
+ * readings of the same pair (A continues from B, and also relates to it) stay
+ * two relations.
+ */
+export function relationsOf(episodeId: string, edges: LineageEdge[]): EpisodeRelation[] {
+  const byKey = new Map<string, EpisodeRelation>();
+  for (const edge of edges) {
+    const read = readEdge(episodeId, edge);
+    if (!read) continue;
+    const key = `${read.other}\u0000${read.label}`;
+    const relation =
+      byKey.get(key) ??
+      { other: read.other, label: read.label, rank: RANK[read.label] ?? 3, descriptions: [], edgeIds: [] };
+    relation.edgeIds.push(edge.id);
+    const said = edge.description?.trim();
+    if (said && !relation.descriptions.includes(said)) relation.descriptions.push(said);
+    byKey.set(key, relation);
+  }
+  return [...byKey.values()].sort((a, b) => a.rank - b.rank || a.other.localeCompare(b.other));
+}
+
+/** Episode↔episode edges only — the lineage, without the chronicle root every episode belongs to. */
+export function lineageEdges(edges: LineageEdge[], isEpisode: (id: string) => boolean): LineageEdge[] {
+  return edges.filter(
+    (edge) => edge.from_id !== edge.to_id && isEpisode(edge.from_id) && isEpisode(edge.to_id),
+  );
+}
+
+/** Whether a reading runs along time (continues, descends) rather than across it (relates). */
+export function isContinuation(edge: LineageEdge): boolean {
+  return Boolean(DIRECTED[(edge.relationship_type ?? "").toLowerCase()]);
+}
+
+// ── Where an episode sits in the chronicle ──────────────────────────────────
+
+/** The fields of a wheel node these helpers read. */
+export interface ChronicleNode {
+  id: string;
+  created_at?: string;
+  metadata?: Record<string, unknown>;
+}
+
+const FOLDER = /^(\d{4}-\d{2}-\d{2})-episode-(\d+)/i;
+
+/**
+ * The episode's folder name — what the wheel's other records file it under.
+ *
+ * From the id when it is `chronicle:<folder>`. A few early episodes were
+ * registered under other ids (`node:knowledge:…`, a bare uuid); their node
+ * still carries the artefact reference, so the folder comes from
+ * `metadata.relative_path` when `metadata.root` names the chronicle.
+ */
+export function episodeFolderOfNode(node: ChronicleNode): string | null {
+  if (node.id.startsWith("chronicle:")) return node.id.slice("chronicle:".length) || null;
+  const root = node.metadata?.root;
+  const relative = node.metadata?.relative_path;
+  if (root !== "MIADI_CHRONICLE_ROOT" || typeof relative !== "string") return null;
+  const folder = relative.split("/")[0];
+  return folder && folder !== relative ? folder : null;
+}
+
+/**
+ * Where an episode sits in the chronicle: its folder's date, then its number —
+ * the order the folders keep on disk. Not `created_at`, which records when the
+ * wheel learned of an episode, and not the number alone, which the chronicle
+ * does not hand out in date order (episode 1000 follows episode 550 by two days).
+ */
+export function chronicleKey(node: ChronicleNode): string {
+  const match = (episodeFolderOfNode(node) ?? "").match(FOLDER);
+  return match ? `${match[1]}-${match[2].padStart(6, "0")}` : (node.created_at ?? "");
+}
+
+/** The day the episode's folder is dated, when it has one. */
+export function episodeDateOf(node: ChronicleNode): string | undefined {
+  return (episodeFolderOfNode(node) ?? "").match(FOLDER)?.[1];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/app",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "description": "Medicine Wheel — Interactive visual layer for Indigenous relational research with Four Directions, ceremonies, and narrative arcs",
   "bin": {
     "mw": "dist/cli/mw.js",
@@ -91,32 +91,32 @@
     "release:major": "npm run version:major && npm run publish:all && npm run release:commit"
   },
   "dependencies": {
-    "@medicine-wheel/ceremonial-diary": "^0.17.2",
-    "@medicine-wheel/ceremony-protocol": "^0.17.2",
-    "@medicine-wheel/community-identity": "^0.17.2",
-    "@medicine-wheel/community-review": "^0.17.2",
-    "@medicine-wheel/consent-lifecycle": "^0.17.2",
-    "@medicine-wheel/creative-orientation": "^0.17.2",
-    "@medicine-wheel/data-store": "^0.17.2",
-    "@medicine-wheel/data-store-postgres": "^0.17.2",
-    "@medicine-wheel/fire-keeper": "^0.17.2",
-    "@medicine-wheel/github-ceremony": "^0.17.2",
-    "@medicine-wheel/graph-viz": "^0.17.2",
-    "@medicine-wheel/honcho": "^0.17.2",
-    "@medicine-wheel/importance-unit": "^0.17.2",
-    "@medicine-wheel/mcp": "^4.17.2",
-    "@medicine-wheel/memory": "^0.17.2",
-    "@medicine-wheel/narrative-cluster": "^0.17.2",
-    "@medicine-wheel/narrative-engine": "^0.17.2",
-    "@medicine-wheel/ontology-core": "^0.17.2",
-    "@medicine-wheel/perception-layer": "^0.17.2",
-    "@medicine-wheel/prompt-decomposition": "^0.17.2",
-    "@medicine-wheel/relational-index": "^0.17.2",
-    "@medicine-wheel/relational-query": "^0.17.2",
-    "@medicine-wheel/session-reader": "^0.17.2",
-    "@medicine-wheel/storage-provider": "^0.17.2",
-    "@medicine-wheel/transformation-tracker": "^0.17.2",
-    "@medicine-wheel/ui-components": "^0.17.2",
+    "@medicine-wheel/ceremonial-diary": "^0.17.4",
+    "@medicine-wheel/ceremony-protocol": "^0.17.4",
+    "@medicine-wheel/community-identity": "^0.17.4",
+    "@medicine-wheel/community-review": "^0.17.4",
+    "@medicine-wheel/consent-lifecycle": "^0.17.4",
+    "@medicine-wheel/creative-orientation": "^0.17.4",
+    "@medicine-wheel/data-store": "^0.17.4",
+    "@medicine-wheel/data-store-postgres": "^0.17.4",
+    "@medicine-wheel/fire-keeper": "^0.17.4",
+    "@medicine-wheel/github-ceremony": "^0.17.4",
+    "@medicine-wheel/graph-viz": "^0.17.4",
+    "@medicine-wheel/honcho": "^0.17.4",
+    "@medicine-wheel/importance-unit": "^0.17.4",
+    "@medicine-wheel/mcp": "^4.17.4",
+    "@medicine-wheel/memory": "^0.17.4",
+    "@medicine-wheel/narrative-cluster": "^0.17.4",
+    "@medicine-wheel/narrative-engine": "^0.17.4",
+    "@medicine-wheel/ontology-core": "^0.17.4",
+    "@medicine-wheel/perception-layer": "^0.17.4",
+    "@medicine-wheel/prompt-decomposition": "^0.17.4",
+    "@medicine-wheel/relational-index": "^0.17.4",
+    "@medicine-wheel/relational-query": "^0.17.4",
+    "@medicine-wheel/session-reader": "^0.17.4",
+    "@medicine-wheel/storage-provider": "^0.17.4",
+    "@medicine-wheel/transformation-tracker": "^0.17.4",
+    "@medicine-wheel/ui-components": "^0.17.4",
     "@miadi/episode-vessel": "^0.2.1",
     "@neondatabase/serverless": "^0.10.0",
     "@xyflow/react": "^12.3.0",