@medicine-wheel/app 0.16.1 → 0.17.1

package/app/api/episodes/[id]/files/route.ts

@@ -0,0 +1,78 @@
+import { NextResponse } from "next/server";
+import { EpisodePathError } from "@miadi/episode-vessel";
+import { episodeFolderOf, openEpisodeRoom, readEpisodeRoomText } from "@/lib/episode-files";
+
+/**
+ * An episode's folder, read-only.
+ *
+ *   GET /api/episodes/<chronicle:folder>/files              the room's listing
+ *   GET /api/episodes/<chronicle:folder>/files?path=<file>  one text file, whole
+ *
+ * The rules — containment, the room, the audience — are `lib/episode-files.ts`
+ * and, beneath it, `@miadi/episode-vessel`. This file only says them in HTTP.
+ * Every answer carries a `state`, so a page can tell "this host has no
+ * chronicle" from "this episode is not on this host" from "this episode is for
+ * the community" — three empty lists that mean three different things.
+ *
+ * There is no PUT. The wheel reads an episode; Miadi writes it.
+ * Ref jgwill/medicine-wheel#153.
+ */
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+const STATUS_OF_STATE: Record<string, number> = {
+  open: 200,
+  "no-root": 503,
+  absent: 404,
+  community: 403,
+  "outside-the-room": 403,
+};
+
+const STATUS_OF_CODE: Record<string, number> = {
+  ENOENT: 404,
+  TOO_LARGE: 413,
+  NO_ROOT: 503,
+};
+
+function answer(body: Record<string, unknown>, status: number) {
+  return NextResponse.json(body, { status, headers: { "cache-control": "no-store" } });
+}
+
+function decoded(value: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export async function GET(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const { id: rawId } = await params;
+  const id = decoded(rawId);
+  const folder = episodeFolderOf(id);
+  if (!folder) {
+    return answer(
+      { state: "not-an-episode", error: `Not an episode id: ${id}. Expected chronicle:<episode folder>.` },
+      400,
+    );
+  }
+
+  const file = new URL(request.url).searchParams.get("path");
+  try {
+    const body = file === null ? openEpisodeRoom(folder) : readEpisodeRoomText(folder, file);
+    return answer(body, STATUS_OF_STATE[body.state] ?? 200);
+  } catch (error) {
+    if (error instanceof EpisodePathError) {
+      return answer(
+        { state: "refused", code: error.code, error: error.message },
+        STATUS_OF_CODE[error.code] ?? 400,
+      );
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return answer({ state: "error", error: message }, 500);
+  }
+}

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

@@ -1,13 +1,19 @@
 "use client";
 
 /**
- * One episode: what it is, what it still holds open, and what it touches.
+ * One episode: what it is, what it holds, what it still holds open, and what
+ * it touches.
  *
- * The three panels answer the three things the graph could not. What this is,
- * from the node itself. What is open, from `?kind=attention&parent_id=<id>` —
- * a query the API has always accepted and no page ever sent. What it relates to,
- * from `/api/nodes/[id]/web`, which walks the traversal that shipped in
- * `relational-query` and went unimported.
+ * What this is, from the node itself, with the episodes before and after it in
+ * the chronicle. What it holds, from its folder — read-only, through the rules
+ * `@miadi/episode-vessel` states for every surface that opens one (see
+ * `components/episode-files-panel.tsx`). What was said and gathered for it —
+ * ceremonies, diary, inquiry weaves, plan perspectives, captures — from routes
+ * 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.
  *
  * 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
@@ -21,6 +27,8 @@ import { useCallback, useEffect, useState } from "react";
 import { use } from "react";
 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";
 
 // `description` lives on the store's node, not on ontology-core's — the same
 // widening `app/nodes/page.tsx` declares as `NodeRecord`. Named EpisodeNode
@@ -42,6 +50,46 @@ 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;
+}
+
+function EpisodeLink({ node, label }: { node: EpisodeNode | null; label: string }) {
+  if (!node) return <span />;
+  return (
+    <Link
+      href={`/episodes/${encodeURIComponent(node.id)}`}
+      className="text-xs text-muted-foreground hover:underline min-w-0 truncate"
+      title={node.name}
+    >
+      {label} {node.name}
+    </Link>
+  );
+}
+
 export default function EpisodePage({ params }: { params: Promise<{ id: string }> }) {
   const { id: rawId } = use(params);
   const id = decodeURIComponent(rawId);
@@ -49,6 +97,8 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
   const [episode, setEpisode] = useState<EpisodeNode | null>(null);
   const [attention, setAttention] = useState<EpisodeNode[]>([]);
   const [web, setWeb] = useState<{ nodes: EpisodeNode[]; edges: RelationalEdge[] } | null>(null);
+  const [before, setBefore] = useState<EpisodeNode | null>(null);
+  const [after, setAfter] = useState<EpisodeNode | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
 
@@ -67,6 +117,11 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
       const found = all.find((n) => n.id === id) ?? null;
       setEpisode(found);
 
+      const ordered = [...all].sort((a, b) => chronicleKey(a).localeCompare(chronicleKey(b)));
+      const at = ordered.findIndex((n) => n.id === id);
+      setBefore(at > 0 ? ordered[at - 1] : null);
+      setAfter(at >= 0 && at < ordered.length - 1 ? ordered[at + 1] : null);
+
       setAttention(attentionRes.ok ? ((await attentionRes.json()).nodes ?? []) : []);
 
       // A 404 here means the node is not in the wheel at all — distinct from a
@@ -85,6 +140,7 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
   }, [load]);
 
   const parentId = metaString(episode, "parent_id");
+  const folder = episode ? episodeFolderOf(episode) : null;
   const neighbours = (web?.nodes ?? []).filter((n) => n.id !== id);
   const parentHasEdge = Boolean(parentId && neighbours.some((n) => n.id === parentId));
 
@@ -117,7 +173,7 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
         </Link>
         <p className="mt-4 text-sm text-muted-foreground">
           No episode node with id <code className="font-mono">{id}</code>. The wheel answered and
-          does not hold it — 102 of 185 episode folders on disk have no node yet.
+          does not hold it: an episode folder can exist before it is registered on the wheel.
         </p>
       </div>
     );
@@ -139,8 +195,16 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
         </div>
         <p className="font-mono text-xs text-muted-foreground mt-1 break-all">{episode.id}</p>
         {episode.description && <p className="text-sm mt-3">{episode.description}</p>}
+        {(before || after) && (
+          <nav className="flex justify-between gap-4 mt-3" aria-label="Neighbouring episodes">
+            <EpisodeLink node={before} label="←" />
+            <EpisodeLink node={after} label="→" />
+          </nav>
+        )}
       </div>
 
+      {folder && <EpisodeFilesPanel episodeId={`chronicle:${folder}`} />}
+
       <section>
         <h2 className="text-sm font-semibold mb-2">
           Open attention {attention.length > 0 && `(${attention.length})`}
@@ -163,6 +227,8 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
         )}
       </section>
 
+      {folder && <EpisodeHoldings episodeId={`chronicle:${folder}`} episodePath={folder} />}
+
       <section>
         <h2 className="text-sm font-semibold mb-2">
           Relations {neighbours.length > 0 && `(${neighbours.length})`}
@@ -172,8 +238,7 @@ export default function EpisodePage({ params }: { params: Promise<{ id: string }
           <p className="mb-2 text-xs text-muted-foreground border rounded-lg p-3 bg-card">
             This episode records a parent in <code>metadata.parent_id</code> (
             <code className="break-all">{parentId}</code>) that was never written as a relation, so
-            it does not appear below and the graph cannot draw it. 101 of 106 containment links in
-            this wheel are in that state.
+            it does not appear below and the graph cannot draw it.
           </p>
         )}
 

package/app/nodes/page.tsx

@@ -15,9 +15,9 @@ import { toast } from "sonner";
 // Storage returns description at the top level; legacy nodes carried it in metadata.
 type NodeRecord = RelationalNode & { description?: string };
 
-const NODE_TYPES: NodeType[] = ["human", "land", "spirit", "ancestor", "future", "knowledge", "circle"];
+const NODE_TYPES: NodeType[] = ["human", "land", "spirit", "ancestor", "future", "knowledge", "circle", "agent"];
 const DIRECTIONS: DirectionName[] = ["east", "south", "west", "north"];
-const NODE_TYPE_ICONS: Record<NodeType, string> = { human: "👤", land: "🌍", spirit: "✨", ancestor: "🪶", future: "🌱", knowledge: "📚", circle: "⭕" };
+const NODE_TYPE_ICONS: Record<NodeType, string> = { human: "👤", land: "🌍", spirit: "✨", ancestor: "🪶", future: "🌱", knowledge: "📚", circle: "⭕", agent: "🤖" };
 const DIRECTION_ICONS: Record<DirectionName, string> = { east: "🌅", south: "🌞", west: "🌄", north: "❄️" };
 
 function describeNode(node: NodeRecord): string {

package/components/episode-files-panel.tsx

@@ -0,0 +1,167 @@
+"use client";
+
+/**
+ * An episode's folder on the episode page — listed, and any text file read in
+ * place. Read-only: the wheel reads an episode, Miadi writes it.
+ *
+ * Text is shown as text. Markdown is not rendered here: rendering it means a
+ * renderer and a sanitizer between an episode's files and this page, and plain
+ * text is already readable. Media and documents are listed, not played.
+ *
+ * @see app/api/episodes/[id]/files/route.ts — and the rules it states
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+type EpisodeFile = {
+  relativePath: string;
+  name: string;
+  kind: "text" | "document" | "media";
+  size: number;
+  modifiedAt: string;
+  previewable: boolean;
+  guidance: boolean;
+};
+
+type Room =
+  | { state: "open"; episode_path: string; files: EpisodeFile[] }
+  | { state: "no-root" }
+  | { state: "absent"; episode_path: string }
+  | { state: "community"; episode_path: string }
+  | { state: "not-an-episode" | "refused" | "error"; error?: string };
+
+type Opened = { path: string; content?: string; error?: string };
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+}
+
+/** Why a folder is not shown, in words a reader can act on. */
+function closedReason(room: Room): string | null {
+  switch (room.state) {
+    case "no-root":
+      return "This wheel's host has no chronicle folder (MIADI_CHRONICLE_ROOT), so it knows the episode exists but cannot open it.";
+    case "absent":
+      return "The episode's folder is not on this host. The wheel holds its record; the folder lives in a chronicle checkout that has not reached this machine.";
+    case "community":
+      return "This episode is for the community signed in. The wheel has no sign-in, so its folder stays closed here.";
+    case "open":
+      return null;
+    default:
+      return room.error ?? "The folder could not be opened.";
+  }
+}
+
+export function EpisodeFilesPanel({ episodeId }: { episodeId: string }) {
+  const base = `/api/episodes/${encodeURIComponent(episodeId)}/files`;
+  const [room, setRoom] = useState<Room | null>(null);
+  const [opened, setOpened] = useState<Opened | null>(null);
+  // The path last asked for, so a slow answer for an earlier click cannot
+  // replace the file the reader opened after it.
+  const wanted = useRef<string | null>(null);
+
+  useEffect(() => {
+    let live = true;
+    setRoom(null);
+    setOpened(null);
+    fetch(base)
+      .then((res) => res.json())
+      .then((body: Room) => live && setRoom(body))
+      .catch((e) => live && setRoom({ state: "error", error: e instanceof Error ? e.message : String(e) }));
+    return () => {
+      live = false;
+    };
+  }, [base]);
+
+  const toggle = useCallback(
+    async (file: EpisodeFile) => {
+      if (wanted.current === file.relativePath) {
+        wanted.current = null;
+        setOpened(null);
+        return;
+      }
+      wanted.current = file.relativePath;
+      setOpened({ path: file.relativePath });
+      let next: Opened;
+      try {
+        const res = await fetch(`${base}?path=${encodeURIComponent(file.relativePath)}`);
+        const body = await res.json();
+        next = res.ok
+          ? { path: file.relativePath, content: body.content }
+          : { path: file.relativePath, error: body.error ?? body.state ?? `HTTP ${res.status}` };
+      } catch (e) {
+        next = { path: file.relativePath, error: e instanceof Error ? e.message : String(e) };
+      }
+      if (wanted.current === file.relativePath) setOpened(next);
+    },
+    [base],
+  );
+
+  const files =
+    room?.state === "open"
+      ? // The episode's own work first; host and agent guidance after it.
+        [...room.files].sort((a, b) => Number(a.guidance) - Number(b.guidance))
+      : [];
+
+  return (
+    <section>
+      <h2 className="text-sm font-semibold mb-2">
+        Files {files.length > 0 && `(${files.length})`}
+      </h2>
+
+      {room === null ? (
+        <p className="text-sm text-muted-foreground">Opening the folder…</p>
+      ) : room.state !== "open" ? (
+        <p className="text-sm text-muted-foreground">{closedReason(room)}</p>
+      ) : files.length === 0 ? (
+        <p className="text-sm text-muted-foreground">The folder holds nothing the room shows.</p>
+      ) : (
+        <ul className="space-y-1">
+          {files.map((file) => {
+            const isOpen = opened?.path === file.relativePath;
+            return (
+              <li key={file.relativePath}>
+                <div className="p-2 border rounded-lg bg-card flex items-baseline justify-between gap-3 flex-wrap">
+                  {file.previewable ? (
+                    <button
+                      onClick={() => toggle(file)}
+                      className="text-sm font-mono text-left break-all hover:underline"
+                      aria-expanded={isOpen}
+                    >
+                      {isOpen ? "▾" : "▸"} {file.relativePath}
+                    </button>
+                  ) : (
+                    <span className="text-sm font-mono break-all text-muted-foreground">
+                      {file.relativePath}
+                    </span>
+                  )}
+                  <span className="text-xs text-muted-foreground shrink-0 flex gap-2 items-baseline">
+                    {file.guidance && <span className="mw-badge">guidance</span>}
+                    {!file.previewable && <span className="mw-badge">{file.kind}</span>}
+                    <span>{formatSize(file.size)}</span>
+                    <span>{file.modifiedAt.slice(0, 10)}</span>
+                  </span>
+                </div>
+                {isOpen && (
+                  <div className="mt-1 p-3 border rounded-lg bg-card">
+                    {opened?.error ? (
+                      <p className="text-sm text-muted-foreground">{opened.error}</p>
+                    ) : opened?.content === undefined ? (
+                      <p className="text-sm text-muted-foreground">Reading…</p>
+                    ) : (
+                      <pre className="text-xs font-mono whitespace-pre-wrap break-words max-h-[70vh] overflow-auto">
+                        {opened.content}
+                      </pre>
+                    )}
+                  </div>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </section>
+  );
+}

package/components/episode-holdings.tsx

@@ -0,0 +1,252 @@
+"use client";
+
+/**
+ * What the wheel holds for one episode, beyond its node.
+ *
+ * Every route read here has filtered by episode for some time — ceremonies,
+ * inquiry weaves, plan perspectives and captures by `episode_path`, diary
+ * entries by the episode's node id — and the episode page never asked any of
+ * them. Nothing here is new data; it is the wheel's own records, gathered where
+ * a person looking at the episode can see them. Ref jgwill/medicine-wheel#153.
+ */
+
+import { useEffect, useState } from "react";
+
+type Ceremony = {
+  id: string;
+  type: string;
+  direction?: string;
+  intentions?: string[];
+  timestamp: string;
+};
+
+type DiaryEntry = {
+  id: string;
+  timestamp: string;
+  phase?: string;
+  entryType?: string;
+  content: string;
+  metadata?: { participant_name?: string };
+};
+
+type InquiryWeave = {
+  id: string;
+  artefact?: { id?: string };
+  last_sync?: { state?: string };
+  issue?: string;
+  issue_url?: string;
+};
+
+type PlanPerspective = {
+  id: string;
+  plan?: { plan_filename?: string; captured_at?: string };
+  narrative?: { title?: string };
+};
+
+type Capture = {
+  id: string;
+  filename: string;
+  kind?: string;
+  artifact_role?: string;
+  device?: string;
+  registered_at?: string;
+};
+
+type Holdings = {
+  ceremonies: Ceremony[];
+  diary: DiaryEntry[];
+  weaves: InquiryWeave[];
+  perspectives: PlanPerspective[];
+  captures: Capture[];
+};
+
+const DIRECTION_ICONS: Record<string, string> = {
+  east: "🌅",
+  south: "🔥",
+  west: "🌊",
+  north: "❄️",
+};
+
+/** A list from one route, or [] when that route did not answer — one silent route must not blank the rest. */
+async function listFrom<T>(url: string, key: string): Promise<{ items: T[]; failed: boolean }> {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return { items: [], failed: true };
+    const body = await res.json();
+    return { items: Array.isArray(body?.[key]) ? body[key] : [], failed: false };
+  } catch {
+    return { items: [], failed: true };
+  }
+}
+
+function byTime<T extends { timestamp: string }>(a: T, b: T): number {
+  return a.timestamp.localeCompare(b.timestamp);
+}
+
+export function EpisodeHoldings({ episodeId, episodePath }: { episodeId: string; episodePath: string }) {
+  const [holdings, setHoldings] = useState<Holdings | null>(null);
+  const [silent, setSilent] = useState<string[]>([]);
+
+  useEffect(() => {
+    let live = true;
+    const p = encodeURIComponent(episodePath);
+    Promise.all([
+      listFrom<Ceremony>(`/api/ceremonies?episode_path=${p}&limit=all`, "ceremonies"),
+      listFrom<DiaryEntry>(`/api/diary?chronicle=${encodeURIComponent(episodeId)}&limit=all`, "entries"),
+      listFrom<InquiryWeave>(`/api/inquiry-weaves?episode_path=${p}`, "inquiry_weaves"),
+      listFrom<PlanPerspective>(`/api/plan-perspectives?episode_path=${p}`, "plan_perspectives"),
+      listFrom<Capture>(`/api/captures?episode_path=${p}`, "captures"),
+    ]).then(([ceremonies, diary, weaves, perspectives, captures]) => {
+      if (!live) return;
+      setHoldings({
+        ceremonies: [...ceremonies.items].sort(byTime),
+        diary: [...diary.items].sort(byTime),
+        weaves: weaves.items,
+        perspectives: perspectives.items,
+        captures: captures.items,
+      });
+      setSilent(
+        (
+          [
+            ["ceremonies", ceremonies],
+            ["diary entries", diary],
+            ["inquiry weaves", weaves],
+            ["plan perspectives", perspectives],
+            ["captures", captures],
+          ] as const
+        )
+          .filter(([, r]) => r.failed)
+          .map(([name]) => name),
+      );
+    });
+    return () => {
+      live = false;
+    };
+  }, [episodeId, episodePath]);
+
+  if (!holdings) {
+    return (
+      <section>
+        <h2 className="text-sm font-semibold mb-2">Held on the wheel</h2>
+        <p className="text-sm text-muted-foreground">Asking the wheel…</p>
+      </section>
+    );
+  }
+
+  const { ceremonies, diary, weaves, perspectives, captures } = holdings;
+  // A route that did not answer is named as silent, not as empty.
+  const empty = (
+    [
+      ["ceremonies", ceremonies],
+      ["diary entries", diary],
+      ["inquiry weaves", weaves],
+      ["plan perspectives", perspectives],
+      ["captures", captures],
+    ] as const
+  )
+    .filter(([name, items]) => items.length === 0 && !silent.includes(name))
+    .map(([name]) => name);
+
+  return (
+    <section className="space-y-4">
+      <h2 className="text-sm font-semibold">Held on the wheel</h2>
+
+      {ceremonies.length > 0 && (
+        <div>
+          <h3 className="text-xs font-semibold text-muted-foreground mb-1">Ceremonies ({ceremonies.length})</h3>
+          <ul className="space-y-1">
+            {ceremonies.map((c) => (
+              <li key={c.id} className="p-2 border rounded-lg bg-card">
+                <div className="flex items-baseline justify-between gap-2 flex-wrap">
+                  <span className="text-sm font-medium">
+                    {c.direction && DIRECTION_ICONS[c.direction]} {c.type.replace(/_/g, " ")}
+                  </span>
+                  <span className="text-xs text-muted-foreground">{c.timestamp.slice(0, 16).replace("T", " ")}</span>
+                </div>
+                {c.intentions?.[0] && <p className="text-sm text-muted-foreground mt-1">{c.intentions[0]}</p>}
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {diary.length > 0 && (
+        <div>
+          <h3 className="text-xs font-semibold text-muted-foreground mb-1">Diary ({diary.length})</h3>
+          <ul className="space-y-1">
+            {diary.map((d) => (
+              <li key={d.id} className="p-2 border rounded-lg bg-card">
+                <p className="text-xs text-muted-foreground">
+                  {[d.metadata?.participant_name, d.entryType, d.phase].filter(Boolean).join(" · ")}
+                </p>
+                <p className="text-sm mt-1 whitespace-pre-wrap">{d.content}</p>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {weaves.length > 0 && (
+        <div>
+          <h3 className="text-xs font-semibold text-muted-foreground mb-1">Inquiry weaves ({weaves.length})</h3>
+          <ul className="space-y-1">
+            {weaves.map((w) => (
+              <li key={w.id} className="p-2 border rounded-lg bg-card flex items-baseline justify-between gap-2 flex-wrap">
+                <span className="text-sm font-mono break-all">{w.artefact?.id ?? w.id}</span>
+                <span className="text-xs text-muted-foreground flex gap-2">
+                  {w.last_sync?.state && <span className="mw-badge">{w.last_sync.state}</span>}
+                  {w.issue_url?.startsWith("https://") ? (
+                    <a href={w.issue_url} className="hover:underline" target="_blank" rel="noreferrer">
+                      {w.issue ?? "issue"}
+                    </a>
+                  ) : (
+                    w.issue
+                  )}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {perspectives.length > 0 && (
+        <div>
+          <h3 className="text-xs font-semibold text-muted-foreground mb-1">Plan perspectives ({perspectives.length})</h3>
+          <ul className="space-y-1">
+            {perspectives.map((pp) => (
+              <li key={pp.id} className="p-2 border rounded-lg bg-card flex items-baseline justify-between gap-2 flex-wrap">
+                <span className="text-sm">{pp.narrative?.title ?? pp.plan?.plan_filename ?? pp.id}</span>
+                <span className="text-xs text-muted-foreground">{pp.plan?.captured_at?.slice(0, 10)}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {captures.length > 0 && (
+        <div>
+          <h3 className="text-xs font-semibold text-muted-foreground mb-1">Captures ({captures.length})</h3>
+          <ul className="space-y-1">
+            {captures.map((c) => (
+              <li key={c.id} className="p-2 border rounded-lg bg-card flex items-baseline justify-between gap-2 flex-wrap">
+                <span className="text-sm font-mono break-all">{c.filename}</span>
+                <span className="text-xs text-muted-foreground flex gap-2">
+                  <span className="mw-badge">{c.artifact_role ?? c.kind ?? "capture"}</span>
+                  {c.device && <span>{c.device}</span>}
+                  <span>{c.registered_at?.slice(0, 10)}</span>
+                </span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {empty.length > 0 && (
+        <p className="text-xs text-muted-foreground">No {empty.join(", ")} bound to this episode.</p>
+      )}
+      {silent.length > 0 && (
+        <p className="text-xs text-muted-foreground">The wheel did not answer for: {silent.join(", ")}.</p>
+      )}
+    </section>
+  );
+}

package/lib/episode-files.ts

@@ -0,0 +1,170 @@
+/**
+ * An episode's folder, opened from the wheel — read-only.
+ *
+ * Every `chronicle_episode` node is registered under `chronicle:<folder>` and
+ * carries an artefact reference: `metadata.root` names `MIADI_CHRONICLE_ROOT`
+ * and `metadata.relative_path` the episode's `episode.yaml` beneath it. The
+ * wheel has always recorded where the work is and never opened it, so the
+ * Episodes tab could show an episode's name and nothing it contains.
+ *
+ * The rules for what an episode folder holds and what may be read from it are
+ * not written here. They live in `@miadi/episode-vessel`, published from
+ * jgwill/Miadi and used by every other surface that opens a vessel — the Miadi
+ * room and its file routes, the terminal browser, the phone. A second copy of
+ * them here is how two surfaces come to disagree about what is private.
+ *
+ * Two of those rules decide what the wheel shows. Both are applied as for a
+ * visitor, because the wheel has no signed-in reader:
+ *
+ *  - **the room rule**: `ceremonies/` (a circle's notes and participants) and
+ *    `captures/` (recordings) are not part of the room. The listing leaves them
+ *    out and a read refuses them.
+ *  - **the audience rule**: an episode whose `episode.yaml` says
+ *    `audience: community` is closed to a visitor — no listing, no read.
+ *
+ * So the wheel shows no more of a folder than Miadi's public room already does.
+ * Nothing here writes. Ref jgwill/medicine-wheel#153.
+ */
+
+import path from "node:path";
+import {
+  EpisodePathError,
+  isOutsideTheRoom,
+  listEpisodeFiles,
+  parseEpisodeFolder,
+  readEpisodeAudience,
+  readEpisodeText,
+  resolveEpisodeDir,
+  resolveEpisodeFile,
+  type EpisodeFile,
+  type FileRevision,
+} from "@miadi/episode-vessel";
+
+export type { EpisodeFile };
+
+export interface EpisodeRootOptions {
+  /** The chronicle root. Defaults to `MIADI_CHRONICLE_ROOT`. */
+  root?: string;
+}
+
+/** Why a folder could not be opened. Each one is a different thing to tell a reader. */
+export type EpisodeRoomClosed =
+  /** This host was given no chronicle root, or the one it names does not exist. */
+  | { state: "no-root" }
+  /** The chronicle on this host has no folder by that name. */
+  | { state: "absent"; episode_path: string }
+  /** The episode is for the community signed in, and the wheel has no signed-in reader. */
+  | { state: "community"; episode_path: string };
+
+export type EpisodeRoom =
+  | { state: "open"; episode_path: string; files: EpisodeFile[] }
+  | EpisodeRoomClosed;
+
+export type EpisodeRoomText =
+  | {
+      state: "open";
+      episode_path: string;
+      path: string;
+      content: string;
+      contentType: string;
+      size: number;
+      revision: FileRevision;
+    }
+  /** Under `ceremonies/` or `captures/`: not part of the room. */
+  | { state: "outside-the-room"; episode_path: string; path: string }
+  | EpisodeRoomClosed;
+
+const ID_PREFIX = "chronicle:";
+
+/**
+ * `chronicle:<folder>` → `<folder>`, or null when the id does not name exactly
+ * one episode folder.
+ *
+ * `parseEpisodeFolder` accepts any slug, `/.` included, and `<folder>/.`
+ * resolves to the same directory on disk while reading as a different name to
+ * the manifest reader — the hole that opened a community room in Miadi
+ * (jgwill/Miadi#712). A bare name is this module's own test.
+ */
+export function episodeFolderOf(id: string): string | null {
+  const value = id.trim();
+  if (!value.startsWith(ID_PREFIX)) return null;
+  const folder = value.slice(ID_PREFIX.length);
+  if (!folder || /[\\/]/.test(folder) || folder.startsWith(".")) return null;
+  return parseEpisodeFolder(folder) ? folder : null;
+}
+
+function rootOf(options: EpisodeRootOptions): string | null {
+  const root = options.root ?? process.env.MIADI_CHRONICLE_ROOT;
+  return root?.trim() ? root.trim() : null;
+}
+
+/** The gate both a listing and a read pass through, in the same order. */
+function gate(folder: string, root: string | null): EpisodeRoomClosed | null {
+  if (!root) return { state: "no-root" };
+  try {
+    resolveEpisodeDir(folder, { root });
+  } catch (error) {
+    if (error instanceof EpisodePathError && error.code === "NO_ROOT") return { state: "no-root" };
+    if (error instanceof EpisodePathError && error.code === "ENOENT") {
+      return { state: "absent", episode_path: folder };
+    }
+    throw error;
+  }
+  if (readEpisodeAudience(folder, { root }) === "community") {
+    return { state: "community", episode_path: folder };
+  }
+  return null;
+}
+
+/** The files of one episode's room: everything the vessel lists except what is outside the room. */
+export function openEpisodeRoom(folder: string, options: EpisodeRootOptions = {}): EpisodeRoom {
+  const root = rootOf(options);
+  const closed = gate(folder, root);
+  if (closed) return closed;
+  const files = listEpisodeFiles(folder, {
+    root: root!,
+    // Applied before a file consumes the listing cap, so a hundred capture
+    // files cannot push an ordinary artefact off the end.
+    include: (relativePath) => !isOutsideTheRoom(relativePath),
+  });
+  return { state: "open", episode_path: folder, files };
+}
+
+/**
+ * One text file of the room, whole.
+ *
+ * Throws `EpisodePathError` for what the vessel refuses — an unsafe path
+ * (`INVALID_PATH`), a missing file (`ENOENT`), text too large to read whole
+ * (`TOO_LARGE`), or a file that is not text. The HTTP edge maps those once.
+ */
+export function readEpisodeRoomText(
+  folder: string,
+  relativePath: string,
+  options: EpisodeRootOptions = {},
+): EpisodeRoomText {
+  const root = rootOf(options);
+  const closed = gate(folder, root);
+  if (closed) return closed;
+
+  // Validates the path (no `.`, `..`, empty or dot-prefixed segment) and
+  // refuses a symlinked file, but a linked *directory* partway down still
+  // resolves. The room rule is asked of both the name the caller gave and the
+  // file it really is, so `notes/<id>/notes.md` through a link to
+  // `ceremonies/` cannot read a ceremony's notes under another name.
+  const resolved = resolveEpisodeFile(folder, relativePath, { root: root! });
+  const real = path.relative(resolved.dir, resolved.path).split(path.sep).join("/");
+  if (isOutsideTheRoom(relativePath) || isOutsideTheRoom(real)) {
+    return { state: "outside-the-room", episode_path: folder, path: relativePath };
+  }
+
+  const text = readEpisodeText(folder, relativePath, { root: root! });
+  return {
+    state: "open",
+    episode_path: folder,
+    path: relativePath,
+    content: text.content,
+    contentType: text.contentType,
+    size: text.size,
+    revision: text.revision,
+  };
+}

package/lib/memory.ts

@@ -20,6 +20,7 @@ import {
 } from '@medicine-wheel/memory';
 import { WHEEL_PEER, createHonchoClient, honchoFromEnv, honchoMemoryProvider } from '@medicine-wheel/honcho';
 import { createProvider } from '@medicine-wheel/storage-provider';
+import { speakerKindOf } from '@medicine-wheel/community-identity';
 import { getAllBeats } from '@/lib/store';
 import { ceremonyEpisodePath } from '@/lib/ceremony-response';
 
@@ -116,6 +117,22 @@ export function wheelForMemory(): MemoryWheel {
       );
       return out;
     },
+
+    async kinds(ids) {
+      const store = await createProvider();
+      const out: Record<string, 'person' | 'agent' | 'wheel'> = {};
+      await Promise.all(
+        ids.map(async (id) => {
+          if (id === WHEEL_PEER) {
+            out[id] = 'wheel';
+            return;
+          }
+          const kind = speakerKindOf(await store.getNode(id).catch(() => null));
+          if (kind) out[id] = kind;
+        }),
+      );
+      return out;
+    },
   };
 }
 

package/package.json

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