@aisystemresources/emdee 0.1.0

package/src/core/indexer.ts

@@ -0,0 +1,346 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { pickByLocality, filenameSlug } from "./resolveLink";
+import { missingSystemNodeFiles } from "../lib/system-nodes";
+
+export type RelationKind = "hierarchy" | "assoc";
+export type Role = "parent" | "child" | "assoc";
+
+/**
+ * One bullet under a relationship section. The first wiki-link on the bullet
+ * is the declared edge target. Any other wiki-links in the same bullet are
+ * captured as `inline` references (navigational hints, not edges).
+ */
+export interface Link {
+  /** Raw target title from the leading wiki-link. */
+  title: string;
+  /** Trailing prose on the bullet after the leading link, trimmed. May be empty. */
+  note: string;
+  /** Other wiki-links found in the bullet's prose (excluding the leading one). */
+  inline: string[];
+}
+
+export interface DocNode {
+  path: string;
+  title: string;
+  content: string;
+  /** First blockquote line directly under the H1 (`> ...`), trimmed. May be empty. */
+  summary: string;
+  /** Parents this doc declares (via `## Child of`). */
+  parents: Link[];
+  /** Children this doc declares (via `## Parent of`). */
+  children: Link[];
+  /** Associates this doc declares (via `## Associated with`). */
+  associates: Link[];
+  /** All wiki-link titles found anywhere in the doc (for derived backlinks). */
+  mentions: string[];
+}
+
+export interface Edge {
+  from: string;
+  to: string;
+  kind: RelationKind;
+}
+
+export interface DocIndex {
+  docs: DocNode[];
+  edges: Edge[];
+  entry: string | null;
+  needsNickname?: boolean;
+}
+
+const WIKI_LINK = /\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/g;
+const HEADING = /^(#{1,6})\s+(.+?)\s*$/;
+const BULLET = /^\s*[-*+]\s+(.*)$/;
+const BLOCKQUOTE = /^\s*>\s?(.*)$/;
+
+export function deriveTitle(rel: string, content: string): string {
+  const heading = content.match(/^#\s+(.+)$/m);
+  if (heading) return heading[1].trim();
+  return path.basename(rel, ".md");
+}
+
+const FENCE = /^\s*(?:```|~~~)/;
+
+/** Yields lines that are NOT inside fenced code blocks. */
+function* outsideFences(content: string): IterableIterator<string> {
+  let inFence = false;
+  for (const line of content.split(/\r?\n/)) {
+    if (FENCE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    yield line;
+  }
+}
+
+export function deriveSummary(content: string): string {
+  // First blockquote line that appears after the H1, before the next heading.
+  let seenH1 = false;
+  for (const line of outsideFences(content)) {
+    const h = line.match(HEADING);
+    if (h) {
+      if (!seenH1 && h[1] === "#") {
+        seenH1 = true;
+        continue;
+      }
+      if (seenH1) return ""; // hit another heading first — no summary
+    }
+    if (!seenH1) continue;
+    const bq = line.match(BLOCKQUOTE);
+    if (bq) return bq[1].trim();
+  }
+  return "";
+}
+
+function classifyHeading(raw: string): Role | null {
+  const t = raw.trim().toLowerCase();
+  if (t === "parent of") return "child"; // children of this doc
+  if (t === "child of") return "parent"; // parents of this doc
+  if (t === "associated with" || t === "associated") return "assoc";
+  return null;
+}
+
+interface BulletParse {
+  leading: string;
+  note: string;
+  inline: string[];
+}
+
+function parseBullet(text: string): BulletParse | null {
+  const links = [...text.matchAll(WIKI_LINK)];
+  if (links.length === 0) return null;
+  const first = links[0];
+  const leading = first[1].trim();
+  const after = text.slice(first.index! + first[0].length);
+  // Strip common leading separators between the link and the prose.
+  const note = after.replace(/^\s*[—–\-:|·,]\s*/, "").trim();
+  const inline = links.slice(1).map((m) => m[1].trim()).filter(Boolean);
+  return { leading, note, inline };
+}
+
+interface Sections {
+  parents: Link[];
+  children: Link[];
+  associates: Link[];
+}
+
+function extractSections(content: string): Sections {
+  const out: Sections = { parents: [], children: [], associates: [] };
+  let role: Role | null = null;
+  // Heading level at which `role` was set. Deeper sub-headings keep us
+  // inside the relation section; equal-or-shallower headings exit it.
+  // Mirrors parseEdges.ts to keep the indexer and the doc_edges sync
+  // path in agreement.
+  let roleLevel = 0;
+  for (const line of outsideFences(content)) {
+    const h = line.match(HEADING);
+    if (h) {
+      const level = h[1].length;
+      const classified = classifyHeading(h[2]);
+      if (classified) {
+        role = classified;
+        roleLevel = level;
+      } else if (level <= roleLevel) {
+        role = null;
+        roleLevel = 0;
+      }
+      continue;
+    }
+    if (!role) continue;
+    const b = line.match(BULLET);
+    if (!b) continue;
+    const parsed = parseBullet(b[1]);
+    if (!parsed) continue;
+    const link: Link = { title: parsed.leading, note: parsed.note, inline: parsed.inline };
+    if (role === "parent") out.parents.push(link);
+    else if (role === "child") out.children.push(link);
+    else out.associates.push(link);
+  }
+  return out;
+}
+
+function extractAllMentions(content: string): string[] {
+  const seen = new Set<string>();
+  for (const line of outsideFences(content)) {
+    for (const m of line.matchAll(WIKI_LINK)) {
+      const t = m[1].trim();
+      if (t) seen.add(t);
+    }
+  }
+  return [...seen];
+}
+
+async function walk(dir: string, base: string): Promise<string[]> {
+  const out: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.name.startsWith(".")) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(full, base)));
+    else if (e.isFile() && e.name.endsWith(".md")) out.push(path.relative(base, full));
+  }
+  return out;
+}
+
+/** Build an index from pre-loaded file contents — works without a filesystem. */
+export function buildIndexFromContents(files: { path: string; content: string }[]): DocIndex {
+  const docs: DocNode[] = [];
+  for (const { path: rel, content } of files) {
+    const sections = extractSections(content);
+    docs.push({
+      path: rel,
+      title: deriveTitle(rel, content),
+      content,
+      summary: deriveSummary(content),
+      parents: dedupeLinks(sections.parents),
+      children: dedupeLinks(sections.children),
+      associates: dedupeLinks(sections.associates),
+      mentions: extractAllMentions(content),
+    });
+  }
+
+  // Wiki-link resolution: prefer H1-title match, fall back to filename
+  // slug (last path segment without ".md"). Lets vaults that keep
+  // SCREAMING-KEBAB filenames but human-friendly H1s resolve their
+  // bullets to real docs without rewriting either side.
+  //
+  // Multi-maps because two docs can share a title or slug (e.g.
+  // SFPDI/DAY1 and GBI/DAY1). When that happens, the caller's path
+  // (`fromPath`) breaks the tie via path-locality scoring — see
+  // pickByLocality in resolveLink.ts.
+  const titleToPaths = new Map<string, string[]>();
+  const slugToPaths = new Map<string, string[]>();
+  for (const d of docs) {
+    const titleKey = d.title.toLowerCase();
+    const slugKey = filenameSlug(d.path).toLowerCase();
+    const titleArr = titleToPaths.get(titleKey) ?? [];
+    titleArr.push(d.path);
+    titleToPaths.set(titleKey, titleArr);
+    const slugArr = slugToPaths.get(slugKey) ?? [];
+    slugArr.push(d.path);
+    slugToPaths.set(slugKey, slugArr);
+  }
+  const resolve = (target: string, fromPath: string): string | undefined => {
+    const t = target.toLowerCase();
+    const titles = titleToPaths.get(t);
+    if (titles && titles.length > 0) {
+      if (titles.length === 1) return titles[0];
+      return pickByLocality(titles.map((path) => ({ path })), fromPath).path;
+    }
+    const slugs = slugToPaths.get(t);
+    if (slugs && slugs.length > 0) {
+      if (slugs.length === 1) return slugs[0];
+      return pickByLocality(slugs.map((path) => ({ path })), fromPath).path;
+    }
+    return undefined;
+  };
+
+  const seen = new Set<string>();
+  const edges: Edge[] = [];
+  const pushHier = (parentPath: string, childPath: string) => {
+    if (parentPath === childPath) return;
+    const key = `H:${parentPath}->${childPath}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    edges.push({ from: parentPath, to: childPath, kind: "hierarchy" });
+  };
+  const pushAssoc = (a: string, b: string) => {
+    if (a === b) return;
+    const [x, y] = a < b ? [a, b] : [b, a];
+    const key = `A:${x}::${y}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    edges.push({ from: x, to: y, kind: "assoc" });
+  };
+
+  // Pass 1: hierarchy. Pass 2: associates, dropping pairs that are
+  // already conveyed by the hierarchy (direct parent/child OR shared
+  // parent — i.e. siblings). The hierarchy edge or the implicit
+  // sibling-through-parent relationship is the canonical link;
+  // duplicating it as an assoc just double-draws in the graph.
+  // lint_doc surfaces the same conditions (`associate_duplicates_hierarchy`,
+  // `sibling_assoc_redundant`) so the markdown can be cleaned at source.
+  for (const d of docs) {
+    for (const link of d.children) {
+      const childPath = resolve(link.title, d.path);
+      if (childPath) pushHier(d.path, childPath);
+    }
+    for (const link of d.parents) {
+      const parentPath = resolve(link.title, d.path);
+      if (parentPath) pushHier(parentPath, d.path);
+    }
+  }
+
+  // Build a child→parents map from the hierarchy edges we just pushed,
+  // so the assoc pass can detect "these two docs share a parent" cheaply.
+  const parentsOf = new Map<string, Set<string>>();
+  for (const e of edges) {
+    if (e.kind !== "hierarchy") continue;
+    const set = parentsOf.get(e.to) ?? new Set<string>();
+    set.add(e.from);
+    parentsOf.set(e.to, set);
+  }
+  const shareParent = (a: string, b: string): boolean => {
+    const pa = parentsOf.get(a);
+    const pb = parentsOf.get(b);
+    if (!pa || !pb) return false;
+    for (const p of pa) if (pb.has(p)) return true;
+    return false;
+  };
+
+  for (const d of docs) {
+    for (const link of d.associates) {
+      const assocPath = resolve(link.title, d.path);
+      if (!assocPath) continue;
+      if (seen.has(`H:${d.path}->${assocPath}`) || seen.has(`H:${assocPath}->${d.path}`)) continue;
+      if (shareParent(d.path, assocPath)) continue;
+      pushAssoc(d.path, assocPath);
+    }
+  }
+
+  // Landing-doc resolution. INFO is the preferred starting point — it
+  // explains the conventions, so visitors get oriented before drilling.
+  // EMDEE is the secondary fallback for vaults that don't have INFO.
+  const overrideEntry = process.env.EMDEE_ENTRY?.toLowerCase();
+  const findByPath = (p: string) => docs.find((d) => d.path.toLowerCase() === p)?.path;
+  const entry =
+    (overrideEntry ? findByPath(overrideEntry) : undefined) ??
+    findByPath("info.md") ??
+    findByPath("emdee.md") ??
+    null;
+
+  return { docs, edges, entry };
+}
+
+export async function buildIndex(docsDir: string): Promise<DocIndex> {
+  let onDiskFiles: { path: string; content: string }[] = [];
+  try {
+    await stat(docsDir);
+    const filePaths = await walk(docsDir, docsDir);
+    onDiskFiles = await Promise.all(
+      filePaths.map(async (rel) => ({
+        path: rel,
+        content: await readFile(path.join(docsDir, rel), "utf8"),
+      }))
+    );
+  } catch {
+    // docsDir missing → treat as empty, still inject virtuals below so the
+    // 5 canonical OS-layer nodes surface even in a completely fresh vault.
+  }
+  const virtuals = missingSystemNodeFiles(onDiskFiles.map((f) => f.path));
+  return buildIndexFromContents([...onDiskFiles, ...virtuals]);
+}
+
+function dedupeLinks(links: Link[]): Link[] {
+  const out: Link[] = [];
+  const seen = new Set<string>();
+  for (const link of links) {
+    const key = link.title.toLowerCase();
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(link);
+  }
+  return out;
+}

package/src/core/parseEdges.ts

@@ -0,0 +1,106 @@
+// SPRINT-018 Phase 2: shared bullet parser for `## Parent of` /
+// `## Child of` / `## Associated with` sections. Returns a flat list of
+// ParsedEdge — the caller (syncDocEdges, backfill) resolves targets and
+// applies suppression.
+//
+// Kept dumb on purpose: no resolver, no de-dup, no cross-doc awareness.
+// Mirrors the indexer's parsing rules (outside fences only, leading
+// wiki-link wins, optional dash/colon between link and label prose).
+
+export type ParsedEdgeKind = "parent_of" | "child_of" | "associated";
+
+export interface ParsedEdge {
+  kind: ParsedEdgeKind;
+  /** Raw target title from the leading wiki-link (untrimmed of case). */
+  target: string;
+  /** Trailing prose on the bullet after the leading link, trimmed. May be null. */
+  label: string | null;
+  /** 0-based index within this section (resets per section). */
+  position: number;
+}
+
+const HEADING = /^(#{1,6})\s+(.*?)\s*$/;
+const BULLET = /^\s*[*+\-]\s+(.*?)\s*$/;
+const WIKI_LINK = /\[\[([^\]]+)\]\]/g;
+const FENCE = /^(```|~~~)/;
+
+function* outsideFences(content: string): IterableIterator<string> {
+  let inFence = false;
+  for (const line of content.split(/\r?\n/)) {
+    if (FENCE.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    yield line;
+  }
+}
+
+function classifyHeading(raw: string): ParsedEdgeKind | null {
+  const t = raw.trim().toLowerCase();
+  if (t === "parent of") return "parent_of";
+  if (t === "child of") return "child_of";
+  if (t === "associated with" || t === "associated") return "associated";
+  return null;
+}
+
+interface BulletParse {
+  leading: string;
+  label: string | null;
+}
+
+function parseBullet(text: string): BulletParse | null {
+  const links = [...text.matchAll(WIKI_LINK)];
+  if (links.length === 0) return null;
+  const first = links[0];
+  const leading = first[1].trim();
+  if (!leading) return null;
+  const after = text.slice((first.index ?? 0) + first[0].length);
+  // Strip common leading separators between the link and the prose.
+  const label = after.replace(/^\s*[—–\-:|·,]\s*/, "").trim();
+  return { leading, label: label || null };
+}
+
+/**
+ * Flat-parse a doc body into the edge declarations it makes. Position is
+ * reset per relationship section so the caller can preserve sibling
+ * ordering off `parent_of` bullets.
+ */
+export function parseEdges(content: string): ParsedEdge[] {
+  const out: ParsedEdge[] = [];
+  let kind: ParsedEdgeKind | null = null;
+  // Heading level at which `kind` was set. A deeper sub-heading (e.g.
+  // `### Vocabulary & units` inside `## Parent of`) does NOT exit the
+  // relation section — bullets under the sub-heading still count.
+  // Only an equal-or-shallower heading exits the section.
+  let kindLevel = 0;
+  let pos = 0;
+  for (const line of outsideFences(content)) {
+    const h = line.match(HEADING);
+    if (h) {
+      const level = h[1].length;
+      const classified = classifyHeading(h[2]);
+      if (classified) {
+        kind = classified;
+        kindLevel = level;
+        pos = 0;
+      } else if (level <= kindLevel) {
+        // Sibling-or-shallower heading exits the relation section.
+        kind = null;
+        kindLevel = 0;
+        pos = 0;
+      }
+      // Otherwise (deeper heading inside relation section): keep `kind`
+      // and `pos` so bullets under sub-headings continue to accrue.
+      continue;
+    }
+    if (!kind) continue;
+    const b = line.match(BULLET);
+    if (!b) continue;
+    const parsed = parseBullet(b[1]);
+    if (!parsed) continue;
+    out.push({ kind, target: parsed.leading, label: parsed.label, position: pos });
+    pos++;
+  }
+  return out;
+}

package/src/core/resolveLink.ts

@@ -0,0 +1,136 @@
+import type { DocIndex, DocNode } from "./indexer";
+
+/**
+ * Resolve a wiki-link target to a doc in the given index. Tries the H1
+ * title first (case-insensitive); falls back to the filename slug (last
+ * path segment without ".md"). The filename fallback handles vaults
+ * where wiki-links use the SCREAMING-KEBAB form while H1s carry a
+ * human-friendly title.
+ *
+ * When two docs share the same title or slug (e.g. an SFPDI/DAY1 and a
+ * GBI/DAY1), `fromPath` disambiguates by locality — a link from
+ * `events/seminars/SFPDI.md` to `[[DAY1]]` picks the candidate sitting
+ * under `events/seminars/SFPDI/`, not its GBI cousin. Without
+ * `fromPath` we fall back to first-match (legacy behaviour).
+ */
+export function resolveWikiLink(index: DocIndex, target: string, fromPath?: string): DocNode | null {
+  const t = target.trim().toLowerCase();
+  if (!t) return null;
+  const titleMatches = index.docs.filter((d) => d.title.toLowerCase() === t);
+  if (titleMatches.length === 1) return titleMatches[0];
+  if (titleMatches.length > 1) return pickByLocality(titleMatches, fromPath);
+  const slugMatches = index.docs.filter((d) => filenameSlug(d.path).toLowerCase() === t);
+  if (slugMatches.length === 1) return slugMatches[0];
+  if (slugMatches.length > 1) return pickByLocality(slugMatches, fromPath);
+  return null;
+}
+
+/** Last path segment with ".md" stripped. "events/foo/BAR.md" → "BAR". */
+export function filenameSlug(path: string): string {
+  const last = path.split("/").pop() ?? path;
+  return last.replace(/\.md$/i, "");
+}
+
+/**
+ * Build a set of lowercase keys (H1 titles + filename slugs) that
+ * resolve to in-set docs. Used by rewriteForPublic to decide whether a
+ * wiki-link should remain navigable or be flattened to plain text.
+ */
+export function resolvableKeysLower(docs: DocNode[]): Set<string> {
+  const out = new Set<string>();
+  for (const d of docs) {
+    out.add(d.title.toLowerCase());
+    out.add(filenameSlug(d.path).toLowerCase());
+  }
+  return out;
+}
+
+/**
+ * Tiered locality scoring for an ambiguous wiki-link. Higher tier wins;
+ * within a tier, shorter shared prefix loses (i.e. more shared segments
+ * is better). Falls back to first candidate if `fromPath` is missing.
+ *
+ * SPRINT-060 (SIG-007 part B): before locality scoring, candidates are
+ * filtered by **namespace family** to prevent shared content shadowing
+ * own content (and vice versa). The namespace family of a path:
+ *   - `__shared:<ownerId>:<rest>` → shared, scoped to that ownerId
+ *   - any other path                → own
+ * A wiki-link from an own doc only resolves to own candidates when an
+ * own candidate exists; from a shared doc by owner X only to candidates
+ * also shared by X. If no same-family candidate exists, fall through to
+ * the cross-family pool (preserves prior behaviour for single-match
+ * shared docs linked from own context).
+ *
+ * Tiers (from `fromPath`'s point of view):
+ *   5 — same directory as the linking doc (sibling)
+ *   4 — descendant of "fromPath as a folder" (matches the common pattern
+ *       where `SFPDI.md` indexes a sibling `SFPDI/` directory)
+ *   3 — ancestor directory of the linking doc (linking up the tree)
+ *   2 — shares any leading path segments
+ *   1 — no overlap; first match wins
+ */
+const SHARED_PATH_RE = /^__shared:([^:]+):/;
+
+function namespaceFamily(path: string): { kind: "shared"; ownerId: string } | { kind: "own" } {
+  const m = path.match(SHARED_PATH_RE);
+  if (m) return { kind: "shared", ownerId: m[1] };
+  return { kind: "own" };
+}
+
+function sameFamily(a: string, b: string): boolean {
+  const fa = namespaceFamily(a);
+  const fb = namespaceFamily(b);
+  if (fa.kind !== fb.kind) return false;
+  if (fa.kind === "shared" && fb.kind === "shared") return fa.ownerId === fb.ownerId;
+  return true;
+}
+
+export function pickByLocality<T extends { path: string }>(candidates: T[], fromPath?: string): T {
+  if (!fromPath || candidates.length === 0) return candidates[0];
+
+  // Namespace-family filter: if any candidate shares the linking doc's
+  // namespace family, restrict to those. Prevents own/shared shadowing
+  // when both have docs with the same title.
+  const sameFamilyCandidates = candidates.filter((c) => sameFamily(c.path, fromPath));
+  const effective = sameFamilyCandidates.length > 0 ? sameFamilyCandidates : candidates;
+
+  const fromSegs = fromPath.split("/");
+  const fromDir = fromSegs.slice(0, -1);
+  const fromBase = (fromSegs[fromSegs.length - 1] ?? "").replace(/\.md$/i, "");
+
+  let best = effective[0];
+  let bestScore = -1;
+  for (const c of effective) {
+    const cSegs = c.path.split("/");
+    const cDir = cSegs.slice(0, -1);
+    const shared = sharedPrefix(fromDir, cDir);
+
+    let tier = 1;
+    if (eqSegs(cDir, fromDir)) tier = 5;
+    else if (cDir.length > fromDir.length && eqSegs(cDir.slice(0, fromDir.length), fromDir) && cDir[fromDir.length] === fromBase) tier = 4;
+    else if (fromDir.length > cDir.length && eqSegs(fromDir.slice(0, cDir.length), cDir)) tier = 3;
+    else if (shared > 0) tier = 2;
+
+    // Score = tier * 1000 + shared-prefix-depth. Lets a tier-2 candidate
+    // with 4 shared segments beat a tier-2 with 2 shared segments.
+    const score = tier * 1000 + shared;
+    if (score > bestScore) {
+      bestScore = score;
+      best = c;
+    }
+  }
+  return best;
+}
+
+function eqSegs(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+function sharedPrefix(a: string[], b: string[]): number {
+  const n = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < n && a[i] === b[i]) i++;
+  return i;
+}

package/src/core/siblings.ts

@@ -0,0 +1,65 @@
+import type { DocIndex, DocNode } from "./indexer";
+import { resolveWikiLink } from "./resolveLink";
+
+/**
+ * Resolve the prev / next sibling of a focal doc by walking its first
+ * declared parent's children. The parent's `## Parent of` bullet order is
+ * the source of truth — that ordering drives prev/next sibling navigation
+ * across the doc toolbar, the graph view, and the get_neighbors MCP tool.
+ *
+ * Fallback for asymmetric edges: when the parent's Parent-of list doesn't
+ * include the focal (the child declared `Child of [[parent]]` but the
+ * parent didn't reciprocate), we still want navigation to work. We
+ * augment the declared list with any other doc whose first declared
+ * parent matches the focal's first declared parent, sorted by title.
+ * Declared siblings come first (in their bullet order) so the fix doesn't
+ * change ordering for vaults with clean reciprocal edges. The lint_doc
+ * tool surfaces the asymmetric edge as a separate signal so the user can
+ * heal the underlying data when they want.
+ *
+ * Associated-with relationships never participate — siblings are purely a
+ * taxonomic concept (same parent in the hierarchy).
+ *
+ * Wiki-link resolution defers to resolveWikiLink, so a bullet like
+ * `[[DAY1]]` is disambiguated by path locality when multiple docs share
+ * a title or slug.
+ */
+export function getPrevNextSiblings(
+  index: DocIndex,
+  focalPath: string
+): { prevPath: string | null; nextPath: string | null } {
+  const focalDoc = index.docs.find((d) => d.path === focalPath);
+  if (!focalDoc) return { prevPath: null, nextPath: null };
+  const primaryParent = focalDoc.parents[0];
+  if (!primaryParent) return { prevPath: null, nextPath: null };
+
+  const parentDoc = resolveWikiLink(index, primaryParent.title, focalPath);
+  if (!parentDoc) return { prevPath: null, nextPath: null };
+
+  const declared: string[] = [];
+  const declaredSet = new Set<string>();
+  for (const link of parentDoc.children) {
+    const child = resolveWikiLink(index, link.title, parentDoc.path);
+    if (!child || declaredSet.has(child.path)) continue;
+    declared.push(child.path);
+    declaredSet.add(child.path);
+  }
+
+  const inverse: DocNode[] = [];
+  for (const d of index.docs) {
+    if (declaredSet.has(d.path)) continue;
+    const childPrimary = d.parents[0];
+    if (!childPrimary) continue;
+    const cp = resolveWikiLink(index, childPrimary.title, d.path);
+    if (cp?.path === parentDoc.path) inverse.push(d);
+  }
+  inverse.sort((a, b) => a.title.toLowerCase().localeCompare(b.title.toLowerCase()));
+
+  const allSiblings = [...declared, ...inverse.map((d) => d.path)];
+  const idx = allSiblings.indexOf(focalPath);
+  if (idx === -1) return { prevPath: null, nextPath: null };
+  return {
+    prevPath: allSiblings[idx - 1] ?? null,
+    nextPath: allSiblings[idx + 1] ?? null,
+  };
+}