Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
Rebuild the docs page on the Overview's design language (#1118)
Raghav Chamadiya2282d0688db0
diff --git a/packages/ui/__tests__/wiki/path-index.test.ts b/packages/ui/__tests__/wiki/path-index.test.tsnew file mode 100644index 000000000..e2e71874a--- /dev/null+++ b/packages/ui/__tests__/wiki/path-index.test.ts@@ -0,0 +1,130 @@+import { describe, it, expect } from "vitest";+import {+ buildPathIndex,+ elidePath,+ looksLikePath,+ normalizePath,+ resolvePath,+} from "../../src/wiki/path-index";++const page = (id: string, target_path: string) => ({ id, target_path });++describe("looksLikePath", () => {+ it("accepts paths and filenames with extensions", () => {+ expect(looksLikePath("packages/core/fs_walk.py")).toBe(true);+ expect(looksLikePath("languages/spec.py")).toBe(true);+ expect(looksLikePath("spec.py")).toBe(true);+ expect(looksLikePath("index.ts")).toBe(true);+ });++ it("rejects prose shorthand that inline code is also used for", () => {+ // Bare words are identifiers, not paths.+ expect(looksLikePath("chat")).toBe(false);+ expect(looksLikePath("ParsedFile")).toBe(false);+ // A leading dot with no basename in front of it is a technology name.+ expect(looksLikePath(".NET")).toBe(false);+ // Anything with whitespace is a phrase.+ expect(looksLikePath("npm run build")).toBe(false);+ expect(looksLikePath("")).toBe(false);+ });+});++describe("normalizePath", () => {+ it("strips the decorations prose adds to a path", () => {+ expect(normalizePath("./packages/ui")).toBe("packages/ui");+ expect(normalizePath("packages/ui/")).toBe("packages/ui");+ expect(normalizePath("packages/ui/src/*")).toBe("packages/ui/src");+ expect(normalizePath(" packages/ui ")).toBe("packages/ui");+ expect(normalizePath("packages//ui")).toBe("packages/ui");+ });+});++describe("buildPathIndex / resolvePath", () => {+ const pages = [+ page("p1", "packages/core/src/repowise/core/fs_walk.py"),+ page("p2", "packages/core/src/repowise/core/ingestion/models.py"),+ page("p3", "packages/core/src/repowise/core/persistence/models.py"),+ page("p4", "packages/ui"),+ ];+ const index = buildPathIndex(pages);++ it("resolves a full path", () => {+ expect(resolvePath(index, "packages/core/src/repowise/core/fs_walk.py")).toEqual({+ pageId: "p1",+ path: "packages/core/src/repowise/core/fs_walk.py",+ });+ });++ it("resolves an unambiguous trailing fragment", () => {+ expect(resolvePath(index, "core/fs_walk.py")?.pageId).toBe("p1");+ expect(resolvePath(index, "fs_walk.py")?.pageId).toBe("p1");+ expect(resolvePath(index, "ingestion/models.py")?.pageId).toBe("p2");+ });++ it("refuses to guess when a fragment is ambiguous", () => {+ // Two pages end in models.py. A wrong link is indistinguishable from a+ // right one until you follow it, so neither wins.+ expect(resolvePath(index, "models.py")).toBeNull();+ });++ it("keeps an exact path even when it is also an ambiguous suffix", () => {+ const withCollision = buildPathIndex([+ page("a", "models.py"),+ page("b", "deep/nested/models.py"),+ ]);+ expect(resolvePath(withCollision, "models.py")?.pageId).toBe("a");+ });++ it("normalizes the anchor before lookup", () => {+ expect(resolvePath(index, "./packages/ui/")?.pageId).toBe("p4");+ expect(resolvePath(index, "packages/ui/*")?.pageId).toBe("p4");+ });++ it("returns null for unknown paths and for non-paths", () => {+ expect(resolvePath(index, "packages/nope/missing.py")).toBeNull();+ expect(resolvePath(index, "chat")).toBeNull();+ });++ it("ignores symbol targets, which the interlinker owns", () => {+ const symbols = buildPathIndex([page("s", "packages/core/engine.py::Engine")]);+ expect(resolvePath(symbols, "packages/core/engine.py")).toBeNull();+ });++ it("tolerates pages with no target path", () => {+ const messy = buildPathIndex([+ { id: "x" },+ { id: "y", target_path: null },+ { id: "z", target_path: "" },+ page("ok", "a/b.py"),+ ]);+ expect(resolvePath(messy, "a/b.py")?.pageId).toBe("ok");+ });++ it("indexes only the last few segments, so a deep prefix does not resolve", () => {+ const deep = buildPathIndex([page("d", "a/b/c/d/e/f.py")]);+ expect(resolvePath(deep, "d/e/f.py")?.pageId).toBe("d");+ // Six segments from the end is beyond what prose writes and beyond what+ // we index; the full path still works.+ expect(resolvePath(deep, "b/c/d/e/f.py")).toBeNull();+ expect(resolvePath(deep, "a/b/c/d/e/f.py")?.pageId).toBe("d");+ });+});++describe("elidePath", () => {+ it("leaves a short path alone", () => {+ expect(elidePath("packages/ui")).toEqual({ head: "", tail: "packages/ui" });+ });++ it("keeps the tail of a long path and marks the head for dimming", () => {+ const { head, tail } = elidePath(+ "packages/core/src/repowise/core/ingestion/models.py",+ );+ expect(tail).toBe("ingestion/models.py");+ expect(head).toBe("packages/…/");+ });++ it("does not elide a long path that has nothing to drop", () => {+ const single = "a-very-long-single-segment-filename-indeed.py";+ expect(elidePath(single)).toEqual({ head: "", tail: single });+ });+});diff --git a/packages/ui/src/brand.ts b/packages/ui/src/brand.tsindex 5f2cb4754..7b8ee8d6d 100644--- a/packages/ui/src/brand.ts+++ b/packages/ui/src/brand.ts@@ -43,13 +43,13 @@ export const LIGHT = {/** Dark-mode surface/text values. */export const DARK = {- bgRoot: "#1a1a1b",- bgSurface: "#232325",- bgElevated: "#2b2c2e",- bgInset: "#141415",- textPrimary: "#ececed",- textSecondary: "#a2a2a6",- textTertiary: "#717176",+ bgRoot: "#0e0e0f",+ bgSurface: "#141416",+ bgElevated: "#1c1c1f",+ bgInset: "#0a0a0b",+ textPrimary: "#f2f2f3",+ textSecondary: "#b4b4b9",+ textTertiary: "#7c7c82",accentPrimary: "#f59520",accentFill: "#f59520",accentSecondary: "#a98fc4",diff --git a/packages/ui/src/docs/docs-header.tsx b/packages/ui/src/docs/docs-header.tsxindex d5d079ede..1f22022c5 100644--- a/packages/ui/src/docs/docs-header.tsx+++ b/packages/ui/src/docs/docs-header.tsx@@ -17,10 +17,16 @@ const ICONS = {} as const;/**- * Single compact chrome row for the documentation surface: title, the- * Explorer / Doc-freshness view switch as a segmented control, and a- * right-aligned slot for page-specific actions. Pure presentation — the host- * resolves tab hrefs/active state and injects a router-aware ``LinkComponent``.+ * Single compact chrome row for the documentation surface: the Explorer /+ * Doc-freshness view switch as a segmented control, and a right-aligned slot+ * for page-specific actions. Pure presentation — the host resolves tab+ * hrefs/active state and injects a router-aware ``LinkComponent``.+ *+ * The row sits beside the pages tree rather than above it, so the tree keeps+ * the full height of the window and this bar spans only the surface it acts+ * on. The "Documentation" heading it used to show is kept for document+ * structure but no longer rendered: the route is /docs, the tab strip says+ * Explorer, and on the reader the page's own title is the h1 directly beneath.*/export function DocsHeader({tabs,@@ -33,13 +39,11 @@ export function DocsHeader({}) {const Link = LinkComponent;return (- <div className="shrink-0 flex h-12 items-center gap-3 border-b border-[var(--color-border-default)] px-4 sm:px-6">- <h1 className="text-sm font-semibold text-[var(--color-text-primary)]">- Documentation- </h1>+ <div className="shrink-0 flex h-12 items-center gap-2 border-b border-[var(--color-border-default)] px-3 sm:gap-3 sm:px-6">+ <h1 className="sr-only">Documentation</h1><nav- className="flex items-center rounded-lg bg-[var(--color-bg-elevated)] p-0.5"+ className="flex shrink-0 items-center rounded-lg bg-[var(--color-bg-elevated)] p-0.5"aria-label="Docs views">{tabs.map((tab) => {@@ -49,21 +53,29 @@ export function DocsHeader({key={tab.href}href={tab.href}aria-current={tab.isActive ? "page" : undefined}+ title={tab.label}className={cn(- "flex items-center gap-1.5 rounded-md px-2.5 py-1 text-xs font-medium transition-colors",+ "flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium whitespace-nowrap transition-colors sm:px-2.5",tab.isActive? "bg-[var(--color-bg-surface)] text-[var(--color-text-primary)] shadow-sm": "text-[var(--color-text-tertiary)] hover:text-[var(--color-text-secondary)]",)}>- <Icon className="h-3.5 w-3.5" />- {tab.label}+ <Icon className="h-3.5 w-3.5 shrink-0" />+ {/* On a phone the two icons carry the switch on their own. The+ labels are the first thing to go: they are the widest element+ in the row and the least load-bearing, since the active tab is+ already marked by its filled ground. */}+ <span className="hidden sm:inline">{tab.label}</span></Link>);})}</nav>- <div className="ml-auto flex items-center gap-2">{children}</div>+ {/* Actions scroll rather than wrap or squeeze the switch. */}+ <div className="ml-auto flex min-w-0 items-center gap-2 overflow-x-auto">+ {children}+ </div></div>);}diff --git a/packages/ui/src/docs/docs-page-actions.tsx b/packages/ui/src/docs/docs-page-actions.tsxindex ef6d4958b..b8df30c79 100644--- a/packages/ui/src/docs/docs-page-actions.tsx+++ b/packages/ui/src/docs/docs-page-actions.tsx@@ -35,7 +35,7 @@ export function DocsPageActions({}) {return (<>- <ConfidenceBadge score={confidence} status={freshnessStatus} />+ <ConfidenceBadge score={confidence} status={freshnessStatus} compact />{personaHasEffect && (<divclassName="inline-flex items-center rounded-md border border-[var(--color-border-default)] p-0.5 shrink-0"diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsxindex 8442073ec..fdafdfb09 100644--- a/packages/ui/src/docs/docs-reader.tsx+++ b/packages/ui/src/docs/docs-reader.tsx@@ -3,13 +3,11 @@import { useCallback, useEffect, useMemo, useRef } from "react";import {FileText,- Clock,- Cpu,ArrowRight,ArrowLeft,+ ChevronRight,Loader2,Layers,- FileInput,} from "lucide-react";import type { DocPage } from "@repowise-dev/types/docs";import { cn } from "../lib/cn";@@ -28,6 +26,11 @@ import {} from "../wiki/wiki-links-types";import { Breadcrumb } from "../shared/breadcrumb";+/** Related entries shown before the "+ N more" line. Five, not eight: the list+ * is a suggestion of where to go next, and past about five it reads as a dump+ * of everything the graph knows. */+const RELATED_LIMIT = 5;+const RELATED_REASON_LABELS: Record<RelatedReason, string> = {imports: "imports","imported-by": "imported by",@@ -195,6 +198,11 @@ function DocsReaderBody({const nav = useMemo(() => computeDocNav(page, pages), [page, pages]);const wikiLinks = useMemo(() => getWikiLinks(page.metadata), [page.metadata]);+ // A page with no model behind it. Structural pages are templates by design+ // and always will be; a model-written page that is still a template has+ // prose outstanding, which is what the upgrade affordance is for.+ const isTemplatePage = page.provider_name === "template";+// The reader renders the page title as the H1 above the body, but generated// content often opens with its own "# <title>" line (the deterministic// templates do), so the same heading shows twice. Drop a leading H1 that@@ -327,7 +335,14 @@ function DocsReaderBody({<div className="flex h-full"><div className="flex flex-col flex-1 min-w-0"><div ref={scrollRef} className="flex-1 overflow-y-auto">- <div className="px-4 sm:px-6 py-8 max-w-[768px] mx-auto">+ {/* Centred in the space the rail leaves, with the rail itself flush+ to the edge. The two alternatives both fail on a wide window:+ anchoring the column left opens a ~620px hole between it and the+ rail, and centring the column-plus-rail group as a unit unpins the+ rail from the edge and strands whitespace to its right. Centring+ here makes the gap to the rail equal the gap to the tree, so both+ read as margins rather than as a gap. */}+ <div className="mx-auto w-full max-w-[720px] px-4 py-8 sm:px-6">{/* Hierarchical breadcrumb */}<div className="mb-3 overflow-hidden"><Breadcrumb@@ -346,14 +361,33 @@ function DocsReaderBody({{page.title}</h1>- {/* One calm metadata line: type + module + layer + freshness. The- generation provenance (version, tokens, model) lives in the- right rail so the page opens on its content, not its receipt. */}- <div className="flex flex-wrap items-center gap-x-3 gap-y-1.5 text-[10px] text-[var(--color-text-tertiary)] mb-6">- <span className="rounded-full bg-[var(--color-bg-elevated)] px-2 py-0.5 uppercase tracking-wider">+ {/* One quiet provenance line: what kind of page this is, who wrote+ it, and when. Previously this row carried an accent-filled+ "Regenerate" pill immediately beside the h1, which read as a+ statement about the page rather than an action on it and+ out-shouted the title. The upgrade affordance now sits at the+ end of the content, where a reader has seen the page is thin.++ "Written by <model>" / "Built from the index" is the Overview+ page's vocabulary, deliberately: a page can lack prose because+ its provider call failed, so calling that "deterministic" would+ be untrue. */}+ <div className="flex flex-wrap items-center gap-x-2 gap-y-1.5 text-[11px] text-[var(--color-text-tertiary)] mb-5">+ <span className="font-mono text-[10px] uppercase tracking-[0.12em]">{getPageTypeLabel(page.page_type)}</span>- {upgradeSlot}+ <span aria-hidden className="opacity-40">·</span>+ <span className="text-[var(--color-text-secondary)]">+ {isTemplatePage+ ? "Built from the index"+ : page.model_name+ ? `Written by ${page.model_name}`+ : "Written by a model"}+ </span>+ <span aria-hidden className="opacity-40">·</span>+ <span title={page.updated_at}>+ updated {formatRelativeTime(page.updated_at)}+ </span>{moduleSeg && (<buttononClick={() => goToPageId(moduleSeg.pageId!)}@@ -377,12 +411,54 @@ function DocsReaderBody({{layerName}</span>))}- <span className="flex items-center gap-1">- <Clock className="h-3 w-3" />- {formatRelativeTime(page.updated_at)}- </span></div>+ {/* What this page was written from. The rail carried this as+ basenames only, below the fold of a narrow column; at the top of+ the page it frames everything under it, and it is the one piece+ of provenance a reader wants *before* reading rather than+ after. Collapsed by default — it answers a question, it does not+ raise one. */}+ {sources.length > 0 && (+ <details className="group mb-6 rounded-lg border border-[var(--color-border-default)]">+ <summary className="flex cursor-pointer list-none items-center gap-2 px-3.5 py-2 text-xs text-[var(--color-text-secondary)]">+ <ChevronRight className="h-3 w-3 shrink-0 text-[var(--color-text-tertiary)] transition-transform group-open:rotate-90" />+ <span>+ Built from {sources.length} source{sources.length === 1 ? "" : " files"}+ </span>+ <span className="ml-auto truncate font-mono text-[10px] text-[var(--color-text-tertiary)]">+ {sources+ .slice(0, 3)+ .map((s) => s.path.split("/").pop())+ .join(", ")}+ {sources.length > 3 && " …"}+ </span>+ </summary>+ <ul className="flex flex-col gap-1 border-t border-[var(--color-border-default)] px-3.5 py-2.5">+ {sources.map((s) => (+ <li key={s.path} className="text-xs">+ {s.pageId ? (+ <button+ onClick={() => goToPageId(s.pageId!)}+ className="block w-full truncate text-left font-mono text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-accent-primary)]"+ title={`${s.path} (${s.kind})`}+ >+ {s.path}+ </button>+ ) : (+ <span+ className="block truncate font-mono text-[var(--color-text-tertiary)]"+ title={`${s.path} (${s.kind})`}+ >+ {s.path}+ </span>+ )}+ </li>+ ))}+ </ul>+ </details>+ )}+{/* Low-confidence flag */}{page.confidence > 0 && page.confidence < 0.5 && (<div className="mb-4 flex items-start gap-1.5 rounded-md border border-[var(--color-warning)]/40 bg-[var(--color-warning)]/10 px-3 py-2">@@ -401,16 +477,36 @@ function DocsReaderBody({</div>)}- {/* Markdown content */}- <article className="prose prose-invert max-w-none leading-relaxed overflow-hidden">+ {/* Markdown content.+ No `prose` wrapper: every element the renderer emits is already+ styled through our own tokens, so the plugin contributed exactly+ two things — a hardcoded `prose-invert` that fed dark variables+ to light mode, and `code::before/::after { content: "`" }`, which+ printed literal backticks around every unresolved inline ref. */}+ <article className="max-w-none leading-relaxed overflow-hidden"><WikiMarkdowncontent={visibleContent}wikiLinks={wikiLinks}buildHref={(pid) => buildPageHref(pid)}LinkComponent={WikiInlineLink}+ pages={pages}/></article>+ {/* The upgrade affordance, at the end of the content rather than+ beside the title. Someone who has read to here knows the page is+ thin; someone at the title does not yet, and an accent pill up+ there competed with the h1 for a decision they could not make. */}+ {isTemplatePage && upgradeSlot && (+ <div className="mt-8 flex flex-wrap items-center gap-x-3 gap-y-2 border-t border-[var(--color-border-default)] pt-4">+ <p className="text-xs text-[var(--color-text-tertiary)]">+ This page is built from the index. A model can write the how and+ why on top of it.+ </p>+ {upgradeSlot}+ </div>+ )}+{/* Sibling prev / next */}{(nav.prev || nav.next) && (<nav className="mt-8 flex items-stretch gap-3 border-t border-[var(--color-border-default)] pt-4">@@ -471,127 +567,100 @@ function DocsReaderBody({</div>)}- {/* Related pages, bottom strip. The right rail is hidden below- lg (vscode webview panels rarely reach lg either), so narrow- viewports get the related links here instead. */}- {relatedLinks.length > 0 && (- <div className="mt-8 lg:hidden">- <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">- Related- </p>- <div className="flex flex-wrap gap-1.5">- {relatedLinks.slice(0, 8).map((r) => (- <button- key={r.id}- onClick={() => goToPageId(r.id)}- className="rounded-full border border-[var(--color-border-default)] bg-[var(--color-bg-surface)] px-2.5 py-1 text-xs text-[var(--color-text-secondary)] hover:text-[var(--color-accent-primary)] hover:border-[var(--color-accent-primary)] transition-colors"- title={r.reason ? RELATED_REASON_LABELS[r.reason] : r.title}- >- {r.title}- </button>- ))}+ {/* Where the rail goes when there is no room for a rail.+ Nothing is dropped at narrow widths, it relocates: the reader+ already did this for Related, and the same treatment now covers+ the intelligence sections and the contents. The breakpoint is+ 2xl, not lg — see the rail below for why. */}+ <div className="mt-10 grid gap-8 border-t border-[var(--color-border-default)] pt-6 sm:grid-cols-2 2xl:hidden">+ {intelligenceSlot && (+ <div className="flex flex-col gap-4">{intelligenceSlot}</div>+ )}+ {relatedLinks.length > 0 && (+ <div>+ <p className="mb-2 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">+ Related+ </p>+ <ul className="flex flex-col gap-2">+ {relatedLinks.slice(0, RELATED_LIMIT).map((r) => (+ <li key={r.id}>+ <button+ onClick={() => goToPageId(r.id)}+ className="block w-full text-left text-xs leading-snug text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-accent-primary)]"+ >+ {r.title}+ </button>+ {r.reason && (+ <span className="block font-mono text-[10px] text-[var(--color-text-tertiary)]">+ {RELATED_REASON_LABELS[r.reason]}+ </span>+ )}+ </li>+ ))}+ </ul></div>- </div>- )}+ )}+ </div></div></div></div>- {/* Right intelligence rail — on-page contents, provenance, related,- backlinks, then host-supplied data-bound intelligence sections. */}+ {/* Right rail — three zones, in the order a reader wants them: where am+ I in this page, what do I need to know about this code, where do I go+ next. The receipt sits under a hairline at the bottom.++ It used to carry eight blocks behind five uppercase labels, which is+ mostly label for about a dozen rows, and the intelligence sections+ each announced themselves separately even when they were three rows+ long. At a glance, Importance, Community, Call graph and Security are+ now one Signals list assembled by the host.++ `2xl` (1536px), not `lg` (1024px): the chrome either side of the+ reading column is 56 + 288 + 300 = 644px, and body copy at 16px wants+ about 640px to reach 65 characters. At lg the column landed at ~420px,+ so the rail was switching on some 400px before the layout could pay+ for it. Below 2xl every section here renders under the article+ instead. */}{sidebarOpen && (- <div className="hidden lg:block border-l border-[var(--color-border-default)] bg-[var(--color-bg-surface)] shrink-0 w-[260px] overflow-auto">- <div className="space-y-6 p-4">+ <div className="hidden 2xl:block shrink-0 w-[300px] overflow-auto">+ <div className="flex flex-col gap-7 py-8 pl-6 pr-7"><TableOfContents content={bodyContent} />- {sources.length > 0 && (- <div>- <div className="flex items-center gap-1.5 mb-2">- <FileInput className="h-3 w-3 text-[var(--color-text-tertiary)]" />- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">- Built from- </span>- </div>- <ul className="space-y-1">- {sources.slice(0, 5).map((s) => (- <li key={s.path} className="text-xs">- {s.pageId ? (- <button- onClick={() => goToPageId(s.pageId!)}- className="truncate text-left font-mono text-[var(--color-text-secondary)] hover:text-[var(--color-accent-primary)] transition-colors w-full"- title={`${s.path} (${s.kind})`}- >- {s.path.split("/").pop()}- </button>- ) : (- <span- className="block truncate font-mono text-[var(--color-text-tertiary)]"- title={`${s.path} (${s.kind})`}- >- {s.path.split("/").pop()}- </span>- )}- </li>- ))}- </ul>- {sources.length > 5 && (- <p className="mt-1 text-[10px] text-[var(--color-text-tertiary)]">- + {sources.length - 5} more- </p>- )}- </div>- )}- {/* Generation provenance — moved off the title row so the page- opens on its content. Model, cost and version answer "how was- this made", which is a rail question, not a headline. */}- <div>- <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">- Generated- </p>- <div className="space-y-1 text-[10px] text-[var(--color-text-tertiary)]">- {page.model_name && (- <div className="flex items-center gap-1.5 font-mono">- <Cpu className="h-3 w-3 shrink-0" />- <span className="truncate" title={page.model_name}>- {page.model_name}- </span>- </div>- )}- <div className="font-mono">- {formatTokens(page.input_tokens)} in · {formatTokens(page.output_tokens)} out- </div>- <div>v{page.version}</div>- </div>- </div>++ {intelligenceSlot}+{relatedLinks.length > 0 && (<div>- <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">+ <p className="mb-2.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">Related</p>- <ul className="space-y-1.5">- {relatedLinks.slice(0, 8).map((r) => (- <li key={r.id} className="text-xs">+ <ul className="flex flex-col gap-2.5">+ {relatedLinks.slice(0, RELATED_LIMIT).map((r) => (+ <li key={r.id}>+ {/* Wraps rather than truncates. At 260px the old rail+ rendered "File: packages/server/src/repowise/s…",+ which names nothing. */}<buttononClick={() => goToPageId(r.id)}- className="truncate text-left text-[var(--color-text-secondary)] hover:text-[var(--color-accent-primary)] transition-colors w-full"- title={r.title}+ className="block w-full text-left text-xs leading-snug text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-accent-primary)]">{r.title}</button>{r.reason && (- <span className="block text-[10px] text-[var(--color-text-tertiary)]">+ <span className="block font-mono text-[10px] text-[var(--color-text-tertiary)]">{RELATED_REASON_LABELS[r.reason]}</span>)}</li>))}</ul>- {relatedLinks.length > 8 && (- <p className="mt-1 text-[10px] text-[var(--color-text-tertiary)]">- + {relatedLinks.length - 8} more+ {relatedLinks.length > RELATED_LIMIT && (+ <p className="mt-2 text-[10px] text-[var(--color-text-tertiary)]">+ + {relatedLinks.length - RELATED_LIMIT} more</p>)}</div>)}+<BacklinksPanelbacklinks={getBacklinks(page.metadata)}repoId={repoId}@@ -602,7 +671,20 @@ function DocsReaderBody({</LinkComponent>)}/>- {intelligenceSlot}++ {/* How this page was made. A receipt, so it sits at the bottom+ under a rule rather than above the things you came for. */}+ <div className="mt-auto flex flex-wrap gap-x-3 gap-y-1 border-t border-[var(--color-border-default)] pt-3.5 font-mono text-[10px] tabular-nums text-[var(--color-text-tertiary)]">+ {page.model_name && (+ <span className="truncate" title={page.model_name}>+ {page.model_name}+ </span>+ )}+ <span>+ {formatTokens(page.input_tokens)} in · {formatTokens(page.output_tokens)} out+ </span>+ <span>v{page.version}</span>+ </div></div></div>)}diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsxindex 88c6c7b17..f465fa2e2 100644--- a/packages/ui/src/docs/docs-tree.tsx+++ b/packages/ui/src/docs/docs-tree.tsx@@ -18,6 +18,7 @@ import {getOnboardingSlot,getPageTypeIcon,getPageTypeLabel,+ isStubPage,type OnboardingSlot,} from "../lib/page-types";import { RAW_GRAPH_ID, displayLabel, treeLabel } from "./page-labels";@@ -311,13 +312,27 @@ const SPINE_TYPES = new Set([const isSpinePage = (page: DocPage) => SPINE_TYPES.has(page.page_type);-// Concept content rows (the modules and cycles nested under a layer) all carry-// the same folder glyph, so a run of them reads as a column of identical icons-// that says nothing the indentation does not already say. Dropping the icon on-// just these rows lets the outline read by its shape. Layers keep their icon as-// the section anchor, onboarding chapters keep theirs, and the deterministic-// file tree keeps its file/folder glyphs — only this middle rung goes quiet.-const CONCEPT_CONTENT_TYPES = new Set(["module_page", "scc_page"]);+// The whole concept spine goes without icons.+//+// This started as a rule for the middle rung only: modules and cycles nested+// under a layer all carry the same folder glyph, so a run of them reads as a+// column of identical icons that says nothing the indentation does not already+// say. The same argument holds one rung up. Every onboarding chapter draws the+// same compass and every layer the same stack, so the top of the tree was nine+// rows of near-identical glyphs down the left edge, which is a texture rather+// than information.+//+// Without them the outline reads by its shape — indentation for depth, weight+// for rank — which is how a table of contents has always worked. The+// deterministic file tree keeps its file/folder glyphs, where the icon does+// distinguish one row from the next.+const CONCEPT_CONTENT_TYPES = new Set([+ "module_page",+ "scc_page",+ "onboarding",+ "layer_page",+ "repo_overview",+]);const hidesTreeIcon = (page?: DocPage): boolean =>page ? CONCEPT_CONTENT_TYPES.has(page.page_type) : false;@@ -580,7 +595,11 @@ function TreeItem({)}<spanclassName={cn(- "truncate font-medium",+ // Wraps rather than truncates. A section title cut to+ // "Documentation Generation Engi…" names nothing, and the tree+ // has the vertical room — it is a list of a few dozen concept+ // rows, not a viewport-bound table.+ "min-w-0 text-left font-medium [overflow-wrap:anywhere]",// A top-level section is the parent of everything indented under// it, so it carries the strongest weight in the tree.(node.path === ONBOARDING_DIR_KEY || depth === 0) &&@@ -589,9 +608,7 @@ function TreeItem({>{node.name}</span>- {showFreshness && node.page && (- <FreshnessDot status={node.page.freshness_status as FreshnessStatus} />- )}+ <RowMarkers page={node.page} showFreshness={showFreshness} /></button>{isExpanded && hasChildren && (@@ -640,10 +657,8 @@ function TreeItem({)}/>)}- <span className="truncate">{node.name}</span>- {showFreshness && node.page && (- <FreshnessDot status={node.page.freshness_status as FreshnessStatus} />- )}+ <span className="min-w-0 text-left [overflow-wrap:anywhere]">{node.name}</span>+ <RowMarkers page={node.page} showFreshness={showFreshness} /></button>);}@@ -665,7 +680,49 @@ function FreshnessDot({ status }: { status: FreshnessStatus }) {if (status === "fresh") return null;const color =status === "stale" ? "bg-[var(--color-warning)]" : "bg-[var(--color-error)]";- return <span className={cn("ml-auto h-1.5 w-1.5 rounded-full shrink-0", color)} />;+ return <span className={cn("h-1.5 w-1.5 rounded-full shrink-0", color)} />;+}++/**+ * A page a model is expected to write that has not been written yet.+ *+ * Whether a page carries prose was previously only discoverable by opening it+ * and reading the rail, so "how far does the prose go" took one click per page.+ * Marking it in the tree answers that while browsing.+ *+ * Hollow, and only on stubs — same reasoning as FreshnessDot above. A marker+ * on every row says nothing; this one means there is something left to do.+ * Structural pages (files, symbols, contracts) are templates by design and are+ * never marked.+ */+function StubDot({ page }: { page: DocPage }) {+ if (!isStubPage(page)) return null;+ return (+ <span+ title="Built from the index. A model has not written this page yet."+ className="h-1.5 w-1.5 shrink-0 rounded-full ring-1 ring-[var(--color-text-tertiary)]"+ />+ );+}++/** Trailing status markers, right-aligned as one group so the two dots do not+ * fight over `ml-auto`. */+function RowMarkers({+ page,+ showFreshness,+}: {+ page: DocPage | undefined;+ showFreshness: boolean;+}) {+ if (!page) return null;+ return (+ <span className="ml-auto flex shrink-0 items-center gap-1 pl-1">+ <StubDot page={page} />+ {showFreshness && (+ <FreshnessDot status={page.freshness_status as FreshnessStatus} />+ )}+ </span>+ );}// ---------------------------------------------------------------------------diff --git a/packages/ui/src/wiki/confidence-badge.tsx b/packages/ui/src/wiki/confidence-badge.tsxindex 1db52c981..bc3cf5683 100644--- a/packages/ui/src/wiki/confidence-badge.tsx+++ b/packages/ui/src/wiki/confidence-badge.tsx@@ -17,6 +17,15 @@ interface ConfidenceBadgeProps {showScore?: boolean;staleSince?: string | null;className?: string;+ /**+ * Drop to the status dot alone below `sm`.+ *+ * For crowded chrome rows on a phone. The dot already carries the state —+ * colour is the whole signal, and the word beside it is the widest thing in+ * the row. Opt-in, because in a table or a card the label is the readable+ * part and losing it would be a downgrade.+ */+ compact?: boolean;}export function ConfidenceBadge({@@ -25,6 +34,7 @@ export function ConfidenceBadge({showScore = false,staleSince,className,+ compact = false,}: ConfidenceBadgeProps) {const status = (statusProp as FreshnessStatus | undefined) ?? scoreToStatus(score);const badgeClasses = statusBadgeClasses(status);@@ -32,22 +42,30 @@ export function ConfidenceBadge({const badge = (<span+ {...(compact ? { title: label } : {})}className={cn(- "inline-flex items-center gap-1.5 rounded border px-2 py-0.5 text-xs font-medium transition-colors",+ "inline-flex shrink-0 items-center gap-1.5 rounded border py-0.5 text-xs font-medium transition-colors",+ compact ? "px-1.5 sm:px-2" : "px-2",badgeClasses,className,)}><spanclassName={cn(- "h-1.5 w-1.5 rounded-full",+ "h-1.5 w-1.5 shrink-0 rounded-full",status === "fresh" && "bg-[var(--color-success)]",status === "stale" && "animate-pulse bg-[var(--color-warning)]",status === "outdated" && "bg-[var(--color-error)]",)}/>- {label}- {showScore && <span className="opacity-70">· {formatConfidence(score)}</span>}+ {/* Hidden visually, never from a screen reader: the colour is the signal+ on a phone, but "Fresh" is still the name of the state. */}+ <span className={cn(compact && "sr-only sm:not-sr-only")}>{label}</span>+ {showScore && (+ <span className={cn("opacity-70", compact && "hidden sm:inline")}>+ · {formatConfidence(score)}+ </span>+ )}</span>);diff --git a/packages/ui/src/wiki/path-index.ts b/packages/ui/src/wiki/path-index.tsnew file mode 100644index 000000000..c81cac500--- /dev/null+++ b/packages/ui/src/wiki/path-index.ts@@ -0,0 +1,174 @@+/**+ * Resolving a code path mentioned in prose to the wiki page that documents it.+ *+ * The backend already resolves *some* inline refs during interlinking and+ * persists them as ``metadata.wiki_links``. That pass only fires for anchors it+ * recognised at generation time, so on a real page most path mentions come back+ * unresolved: the repo overview for this codebase carries 57 distinct inline+ * code spans and 34 wiki_links, of which a handful actually match. Everything+ * else renders as dead text even though a ``file_page`` for that exact path is+ * sitting in the same loaded page list.+ *+ * So resolve the rest here, on the client, from the pages the reader already+ * has. No backend change, no regeneration, and it stays correct as the index+ * grows because it is derived from the live list rather than baked into prose.+ *+ * Two rules keep it honest:+ *+ * - An exact ``target_path`` always wins over a suffix match.+ * - An ambiguous suffix resolves to nothing. Prose says ``models.py`` and this+ * monorepo has eleven of them; linking to whichever one happened to be+ * indexed first is worse than not linking at all, because a wrong link is+ * indistinguishable from a right one until you follow it.+ */++/** The subset of a page this module needs. Structural typing keeps it usable+ * from both the web app's `PageResponse` and the shared `DocPage`. */+export interface PathIndexablePage {+ id: string;+ target_path?: string | null;+}++export interface PathTarget {+ pageId: string;+ /** The full indexed path, for the link's tooltip. */+ path: string;+}++export interface PathIndex {+ /** Full ``target_path`` → page. */+ exact: Map<string, PathTarget>;+ /** Trailing path fragment → page, or null where the fragment is ambiguous. */+ suffix: Map<string, PathTarget | null>;+}++/**+ * How many trailing segments of a path get their own suffix entry.+ *+ * Four covers what prose actually writes (`spec.py`, `languages/spec.py`,+ * `ingestion/languages/spec.py`) without indexing every prefix of every path+ * in a 5,000-page repo.+ */+const MAX_SUFFIX_SEGMENTS = 4;++/** A symbol page's target is ``path::Name``; those are the interlinker's job. */+function isPathLike(targetPath: string): boolean {+ return targetPath.length > 0 && !targetPath.includes("::");+}++/**+ * Normalise a path for lookup and indexing: no leading ``./``, no repeated or+ * trailing slashes, no trailing glob. Prose writes `packages/ui/src/*` and+ * `ingestion/resolvers/` for the same thing a target_path spells without either.+ */+export function normalizePath(raw: string): string {+ return raw+ .trim()+ .replace(/^\.\//, "")+ .replace(/\/+/g, "/")+ .replace(/\/\*+$/, "")+ .replace(/\/+$/, "");+}++/**+ * True when an inline code span is plausibly a path at all.+ *+ * Inline code is also used for identifiers, flags and prose shorthand, and a+ * bare word must never match a page. Requires either a slash with something+ * after it, or a single filename carrying an extension — which is why `.NET`+ * (no basename before the dot) and `chat` are rejected while `spec.py` is not.+ */+export function looksLikePath(anchor: string): boolean {+ if (!anchor || anchor.length > 200) return false;+ if (/\s/.test(anchor)) return false;+ if (/\/[^/]/.test(anchor)) return true;+ return /^[\w.-]*[\w-]\.[a-zA-Z0-9]{1,6}$/.test(anchor);+}++/** Register a suffix, tombstoning it as ambiguous if a different page claims+ * it. Once ambiguous it stays ambiguous — a third claimant changes nothing. */+function addSuffix(+ suffix: Map<string, PathTarget | null>,+ key: string,+ target: PathTarget,+): void {+ if (!suffix.has(key)) {+ suffix.set(key, target);+ return;+ }+ const existing = suffix.get(key);+ if (existing && existing.pageId !== target.pageId) suffix.set(key, null);+}++/**+ * Build the lookup from the loaded page list.+ *+ * Linear in total path segments and memoized by the caller on the page list,+ * so it runs once per repo rather than once per render.+ */+export function buildPathIndex(pages: readonly PathIndexablePage[]): PathIndex {+ const exact = new Map<string, PathTarget>();+ const suffix = new Map<string, PathTarget | null>();++ for (const page of pages) {+ const raw = page.target_path;+ if (typeof raw !== "string" || !isPathLike(raw)) continue;+ const path = normalizePath(raw);+ if (!path) continue;++ const target: PathTarget = { pageId: page.id, path };+ // First page to claim a path keeps it. Duplicates are a generator bug,+ // not something to surface in the reader.+ if (!exact.has(path)) exact.set(path, target);++ const segments = path.split("/");+ const start = Math.max(1, segments.length - MAX_SUFFIX_SEGMENTS);+ for (let i = start; i < segments.length; i++) {+ addSuffix(suffix, segments.slice(i).join("/"), target);+ }+ }++ return { exact, suffix };+}++/**+ * Resolve one inline ref. Returns null for anything that is not a path, is+ * unknown, or is ambiguous.+ */+export function resolvePath(+ index: PathIndex,+ anchor: string,+): PathTarget | null {+ if (!looksLikePath(anchor)) return null;+ const path = normalizePath(anchor);+ if (!path) return null;+ const hit = index.exact.get(path);+ if (hit) return hit;+ return index.suffix.get(path) ?? null;+}++/**+ * Shorten a long path for display, keeping the end.+ *+ * The informative part of `packages/core/src/repowise/core/ingestion/models.py`+ * is the tail; the head is the same on every path in the repo and, rendered at+ * full length inline, it breaks the line rhythm of the paragraph around it.+ * The full path stays available as the link's title.+ *+ * Returns the head to be dimmed and the tail to be shown at full strength, so+ * the caller can style them differently without re-parsing.+ */+export function elidePath(+ path: string,+ maxLength = 34,+ keepSegments = 2,+): { head: string; tail: string } {+ if (path.length <= maxLength) return { head: "", tail: path };+ const segments = path.split("/");+ if (segments.length <= keepSegments) return { head: "", tail: path };++ const tail = segments.slice(-keepSegments).join("/");+ // A tail that is already over budget means the basename itself is long;+ // eliding further would cost the only part worth reading.+ return { head: `${segments[0]}/…/`, tail };+}diff --git a/packages/ui/src/wiki/wiki-markdown.tsx b/packages/ui/src/wiki/wiki-markdown.tsxindex 73177f15e..ffbd2c5bd 100644--- a/packages/ui/src/wiki/wiki-markdown.tsx+++ b/packages/ui/src/wiki/wiki-markdown.tsx@@ -12,6 +12,13 @@ import {type WikiLinkKind,type WikiLinkRef,} from "./wiki-links-types";+import {+ buildPathIndex,+ elidePath,+ resolvePath,+ type PathIndex,+ type PathIndexablePage,+} from "./path-index";/*** Resolves an inline backtick ref to an internal wiki page href, or null@@ -112,6 +119,8 @@ function ClientCodeBlock({ code, language }: { code: string; language: string })function buildComponents(resolveLink: WikiLinkLookup | null,LinkComponent: WikiLinkComponent,+ pathIndex: PathIndex,+ buildPathHref: ((pageId: string) => string) | undefined,): Components {const Link = LinkComponent;return {@@ -174,26 +183,49 @@ function buildComponents(return <ClientCodeBlock code={trimmed} language={lang} />;}- // Inline code: if the ref resolves to a known wiki page, render it as- // a clickable internal link instead of a dead code span. We already- // computed these targets in interlinking.py — just surface them.+ // Inline code. Two states, and they have to look different:+ //+ // live — resolves to a page in this wiki. A faint ground, primary ink,+ // accent only on hover.+ // dead — nothing behind it. Plain mono in tertiary ink, no ground.+ //+ // Previously both rendered in full-saturation accent, which turned a list+ // of file paths into a wall of orange and made the clickable ones no more+ // clickable-looking than the rest. Decorating only what you can follow+ // inverts that: the loud thing on the page is the thing that does+ // something.const text = typeof children === "string" ? children : extractText(children);- const resolved = resolveLink ? resolveLink(text.trim()) : null;- if (resolved) {+ const anchor = text.trim();+ // The interlinker's own resolutions win — it can resolve symbols and page+ // titles, which the path index deliberately does not attempt.+ const linked = resolveLink ? resolveLink(anchor) : null;+ const viaPath = linked ? null : resolvePath(pathIndex, anchor);+ const href = linked?.href ?? (viaPath ? buildPathHref?.(viaPath.pageId) : undefined);++ if (href) {+ const full = viaPath?.path ?? anchor;+ const { head, tail } = elidePath(full);return (<Link- href={resolved.href}- title={`Go to ${text.trim()}`}- className="rounded bg-[var(--color-accent-muted)] px-1.5 py-0.5 text-[0.85em] font-mono text-[var(--color-accent-primary)] underline decoration-dotted underline-offset-2 hover:bg-[var(--color-accent-primary)] hover:text-white transition-colors"+ href={href}+ title={full}+ className="rounded bg-[color-mix(in_srgb,var(--color-text-primary)_6%,transparent)] px-1.5 py-0.5 text-[0.85em] font-mono whitespace-nowrap text-[var(--color-text-primary)] transition-colors hover:bg-[var(--color-accent-muted)] hover:text-[var(--color-accent-primary)] hover:underline hover:underline-offset-2">- {children}+ {head ? (+ <>+ <span className="opacity-55">{head}</span>+ {tail}+ </>+ ) : (+ children+ )}</Link>);}return (<code- className="rounded bg-[var(--color-bg-elevated)] px-1.5 py-0.5 text-[0.85em] font-mono text-[var(--color-accent-primary)]"+ className="text-[0.85em] font-mono text-[var(--color-text-tertiary)]"{...props}>{children}@@ -272,6 +304,12 @@ interface WikiMarkdownProps {buildHref?: (pageId: string, kind: WikiLinkKind) => string;/** Router-aware link (e.g. Next.js ``Link``). Defaults to a plain ``<a>``. */LinkComponent?: WikiLinkComponent;+ /**+ * The loaded page list, used to resolve inline path refs the backend's+ * interlinking pass left unresolved. Omit it and those refs simply render+ * as plain code spans, exactly as before.+ */+ pages?: readonly PathIndexablePage[];}export function WikiMarkdown({@@ -279,7 +317,12 @@ export function WikiMarkdown({wikiLinks,buildHref,LinkComponent = "a",+ pages,}: WikiMarkdownProps) {+ // Keyed on the page list identity: the reader loads it once per repo, so+ // this runs once rather than on every content change.+ const pathIndex = useMemo(() => buildPathIndex(pages ?? []), [pages]);+const components = useMemo(() => {let resolveLink: WikiLinkLookup | null = null;if (wikiLinks && wikiLinks.length > 0 && buildHref) {@@ -290,8 +333,12 @@ export function WikiMarkdown({return { href: buildHref(hit.pageId, hit.kind), kind: hit.kind };};}- return buildComponents(resolveLink, LinkComponent);- }, [wikiLinks, buildHref, LinkComponent]);+ // Path hits are always file-kind by construction.+ const buildPathHref = buildHref+ ? (pageId: string) => buildHref(pageId, "file")+ : undefined;+ return buildComponents(resolveLink, LinkComponent, pathIndex, buildPathHref);+ }, [wikiLinks, buildHref, LinkComponent, pathIndex]);// Parsing + reconciling a large markdown document is the dominant cost when a// page opens. Memoize the rendered tree on (content, components) so unrelateddiff --git a/packages/ui/styles/globals.css b/packages/ui/styles/globals.cssindex df79e7ff4..e543d4a98 100644--- a/packages/ui/styles/globals.css+++ b/packages/ui/styles/globals.css@@ -338,26 +338,37 @@.dark {/* Neutral graphite base — a true dark gray (near-zero hue) so nothing readsblue, green, or plum. The surface ramp climbs root -> surface -> elevated- -> overlay with wide steps so the sidebar, breadcrumb bar, cards, tables,- and modals all read as distinct layers off the same tokens. Light mode is- unchanged. */- --color-bg-root: #1a1a1b;- --color-bg-surface: #232325;- --color-bg-elevated: #2b2c2e;- --color-bg-overlay: #343539;- --color-bg-inset: #141415;-- /* Neutral hairlines so card / sidebar / table edges read on the gray base. */- --color-border-default: rgba(255, 255, 255, 0.1);- --color-border-hover: rgba(255, 255, 255, 0.18);+ -> overlay so the sidebar, breadcrumb bar, cards, tables and modals all+ read as distinct layers off the same tokens. Light mode is unchanged.++ The whole ramp sits lower than it used to (root was #1a1a1b, surface+ #232325). Two reasons. Reading surfaces are the base plane, and on the+ docs page the old values made the reading column the *darkest* of the+ three panels, recessed between two lighter ones — a trench, which is the+ opposite of how a reading UI should stack. And near-black gives the accent+ and the semantic colours somewhere to go: the same #f59520 that looked+ muddy on graphite carries on this ground. */+ --color-bg-root: #0e0e0f;+ --color-bg-surface: #141416;+ --color-bg-elevated: #1c1c1f;+ --color-bg-overlay: #26262a;+ --color-bg-inset: #0a0a0b;++ /* Neutral hairlines so card / sidebar / table edges read on the gray base.+ Lighter than before: the same alpha reads considerably louder against+ near-black, and at 0.10 every border on the page started shouting. */+ --color-border-default: rgba(255, 255, 255, 0.07);+ --color-border-hover: rgba(255, 255, 255, 0.15);--color-border-active: rgba(245, 149, 32, 0.55);- /* Neutral gray text (no plum / blue cast) to match the graphite chrome. */- --color-text-primary: #ececed;- --color-text-secondary: #a2a2a6;- --color-text-tertiary: #717176;- --color-text-inverse: #1a1a1b;- --color-text-on-accent: #1a1a1b;+ /* Neutral gray text (no plum / blue cast) to match the graphite chrome.+ Secondary carries body copy and is lifted the most — on the old ground it+ was grey-on-grey and read flat at any length. */+ --color-text-primary: #f2f2f3;+ --color-text-secondary: #b4b4b9;+ --color-text-tertiary: #7c7c82;+ --color-text-inverse: #0e0e0f;+ --color-text-on-accent: #0e0e0f;--color-accent-primary: #f59520;--color-accent-fill: #f59520;@@ -405,10 +416,13 @@--color-diagram-cluster-border: #a98fc4;--color-diagram-grid: rgba(222, 210, 235, 0.05);- /* Zoom canvas — dark: elevated graphite cards on the near-black canvas. */- --color-zoom-card-fill: #2b2c2e; /* leaf card (bg-elevated) */- --color-zoom-card-fill-2: #232325; /* container card (bg-surface) */- --color-zoom-card-text: #ececed;+ /* Zoom canvas — dark: elevated graphite cards on the near-black canvas.+ These are literals rather than var() references because the canvas+ renderer reads them into WebGL, but they have to move with the surface+ ramp or the cards float above a ground that has dropped beneath them. */+ --color-zoom-card-fill: #1c1c1f; /* leaf card (bg-elevated) */+ --color-zoom-card-fill-2: #141416; /* container card (bg-surface) */+ --color-zoom-card-text: #f2f2f3;--color-zoom-card-border: rgba(255, 255, 255, 0.10);--color-zoom-card-border-hover: rgba(255, 255, 255, 0.20);--color-zoom-card-shadow: rgba(0, 0, 0, 0.45);@@ -453,8 +467,9 @@--shadow-xl: 0 16px 48px rgba(0, 0, 0, 0.6), inset 0 0 0 1px rgba(255, 255, 255, 0.07);--shadow-button: 0 1px 2px rgba(0, 0, 0, 0.4);- /* Dark soft wash — neutral graphite with a faint lift at the end */- --gradient-warm-wash: linear-gradient(160deg, #1c1c1e 0%, #232325 55%, #2c2c2f 100%);+ /* Dark soft wash — neutral graphite with a faint lift at the end. Tracks the+ surface ramp: the wash reads as a lit panel only if it starts at the base. */+ --gradient-warm-wash: linear-gradient(160deg, #101012 0%, #16161a 55%, #1f1f23 100%);}/* -------------------------------------------------------------------- */diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsxindex ad2f0943e..b30236cd4 100644--- a/packages/web/src/components/docs/docs-explorer.tsx+++ b/packages/web/src/components/docs/docs-explorer.tsx@@ -47,7 +47,14 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {if (typeof window === "undefined") return true;return window.matchMedia("(min-width: 768px)").matches;});- const [sidebarOpen, setSidebarOpen] = useState(true);+ // The rail defaults to whether the layout can afford it, not to `true`.+ // Mirrors the 2xl breakpoint the reader uses to place its sections; a manual+ // toggle wins from then on, same contract as the app sidebar's route-based+ // collapse.+ const [sidebarOpen, setSidebarOpen] = useState(() => {+ if (typeof window === "undefined") return true;+ return window.matchMedia("(min-width: 1536px)").matches;+ });const [searchOpen, setSearchOpen] = useState(false);const [isExporting, setIsExporting] = useState(false);const searchParams = useSearchParams();@@ -182,11 +189,26 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {}}, [pages]);- let body: React.ReactNode;- if (isLoading) {- body = (- <div className="flex h-full">- <div className="w-full md:w-[300px] border-r border-[var(--color-border-default)] p-3 space-y-2">+ // The tree panel, rendered at every state so it keeps the full height of the+ // window rather than starting below a chrome bar. Its skeleton lives here+ // too, so the layout does not reflow once the pages land.+ const treePanel = (+ // No right border. Tree, reading column and rail sit on one plane and are+ // separated by space; a rule on each side of the reading column made it+ // read as a trench between two panels.+ // Below md the tree is a drawer over the reader, not a column beside it.+ // As a column it would claim the full width and starve the header column+ // it now sits next to, squashing the view switch into a few pixels.+ <div+ className={cn(+ "bg-[var(--color-bg-surface)] transition-all duration-200 shrink-0 overflow-y-auto",+ treePanelOpen+ ? "absolute inset-y-0 left-0 z-30 w-full md:static md:w-[288px]"+ : "w-0 overflow-hidden",+ )}+ >+ {isLoading ? (+ <div className="space-y-2 p-3"><Skeleton className="h-8 w-full rounded-md" /><Skeleton className="h-4 w-3/4 rounded" /><Skeleton className="h-4 w-1/2 rounded" />@@ -195,9 +217,29 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {<Skeleton className="h-4 w-3/4 rounded" /><Skeleton className="h-4 w-1/2 rounded" /></div>- <div className="flex-1 flex items-center justify-center">- <Skeleton className="h-8 w-48 rounded" />- </div>+ ) : (+ <DocsTree+ pages={pages}+ selectedPageId={selectedPage?.id ?? null}+ onSelectPage={(p) => {+ // DocsTree yields its DocPage type; the elements are the real+ // PageResponse objects we passed in (they carry the extra+ // provenance fields), so this narrowing is safe.+ handleSelectPage(p as unknown as PageResponse);+ if (typeof window !== "undefined" && !window.matchMedia("(min-width: 768px)").matches) {+ setTreePanelOpen(false);+ }+ }}+ />+ )}+ </div>+ );++ let body: React.ReactNode;+ if (isLoading) {+ body = (+ <div className="flex-1 flex items-center justify-center">+ <Skeleton className="h-8 w-48 rounded" /></div>);} else if (pages.length === 0) {@@ -218,108 +260,91 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {);} else {body = (- <div className="relative flex h-full">- {/* Tree sidebar */}- <div- className={cn(- "border-r border-[var(--color-border-default)] bg-[var(--color-bg-surface)] transition-all duration-200 shrink-0 relative",- treePanelOpen ? "w-full md:w-[300px]" : "w-0 overflow-hidden border-r-0",- )}- >- <DocsTree- pages={pages}- selectedPageId={selectedPage?.id ?? null}- onSelectPage={(p) => {- // DocsTree yields its DocPage type; the elements are the real- // PageResponse objects we passed in (they carry the extra- // provenance fields), so this narrowing is safe.- handleSelectPage(p as unknown as PageResponse);- if (typeof window !== "undefined" && !window.matchMedia("(min-width: 768px)").matches) {- setTreePanelOpen(false);- }- }}- />- </div>-- {/* Toggle button */}- <button- onClick={() => setTreePanelOpen((o) => !o)}- aria-label={treePanelOpen ? "Hide pages tree" : "Show pages tree"}- aria-expanded={treePanelOpen}- className={cn(- "absolute top-3 z-20 rounded-r-md border border-l-0 border-[var(--color-border-default)] bg-[var(--color-bg-surface)] p-1 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-elevated)] transition-colors",- treePanelOpen ? "hidden md:block left-[300px]" : "left-0",- )}- >- {treePanelOpen ? (- <PanelLeftClose className="h-3.5 w-3.5" />- ) : (- <PanelLeft className="h-3.5 w-3.5" />- )}- </button>-- {/* Viewer */}- <div className={cn("flex-1 min-w-0", treePanelOpen ? "hidden md:block" : "block")}>- <DocsViewer- page={selectedPage}- pages={pages}- repoId={repoId}- onSelectPage={handleSelectPage}- persona={persona}- sidebarOpen={sidebarOpen}- onGenerated={handleGenerated}- />- </div>+ <div className="h-full min-w-0">+ <DocsViewer+ page={selectedPage}+ pages={pages}+ repoId={repoId}+ onSelectPage={handleSelectPage}+ persona={persona}+ sidebarOpen={sidebarOpen}+ onGenerated={handleGenerated}+ /></div>);}+ // Tree beside the chrome, not under it. The header used to span the full+ // width, which pushed the tree down by its height on every screen and cost+ // that much of the list for a bar that says "Documentation" on a page whose+ // route is already /docs. The tree now starts at the top and the bar sits to+ // the right of it, over the reading column it actually acts on.return (- <div className="flex flex-col h-full">- <DocsHeader>- {selectedPage && (- <DocsPageActions- page={selectedPage}- persona={persona}- setPersona={setPersona}- personaHasEffect={personaHasEffect}- />+ <div className="relative flex h-full">+ {treePanel}++ <button+ onClick={() => setTreePanelOpen((o) => !o)}+ aria-label={treePanelOpen ? "Hide pages tree" : "Show pages tree"}+ aria-expanded={treePanelOpen}+ className={cn(+ "absolute top-3.5 z-20 rounded-md p-1 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] hover:bg-[var(--color-bg-elevated)] transition-colors",+ treePanelOpen ? "hidden md:block left-[292px]" : "left-1",+ )}+ >+ {treePanelOpen ? (+ <PanelLeftClose className="h-3.5 w-3.5" />+ ) : (+ <PanelLeft className="h-3.5 w-3.5" />)}- {selectedPage && isModelWrittenType(selectedPage.page_type) && (- <PageGenerateButton+ </button>++ <div className="flex flex-1 min-w-0 flex-col">+ <DocsHeader>+ {selectedPage && (+ <DocsPageActions+ page={selectedPage}+ persona={persona}+ setPersona={setPersona}+ personaHasEffect={personaHasEffect}+ />+ )}+ {selectedPage && isModelWrittenType(selectedPage.page_type) && (+ <PageGenerateButton+ page={selectedPage}+ repoId={repoId}+ onGenerated={handleGenerated}+ />+ )}+ {hasStubs && <BulkGenerateButton repoId={repoId} onGenerated={handleGenerated} />}+ <button+ onClick={() => setSearchOpen(true)}+ className="flex items-center gap-2 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2.5 py-1.5 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-text-secondary)]"+ >+ <Search className="h-3.5 w-3.5" />+ <span className="hidden sm:inline">Search</span>+ <kbd className="hidden rounded border border-[var(--color-border-default)] px-1 py-0.5 text-[10px] sm:inline">+ ⌘K+ </kbd>+ </button>+ <ExportMenu+ isExporting={isExporting}+ onExportAll={handleExportAll}+ zipHref={`/api/repos/${repoId}/export`}page={selectedPage}repoId={repoId}- onGenerated={handleGenerated}/>- )}- {hasStubs && <BulkGenerateButton repoId={repoId} onGenerated={handleGenerated} />}- <button- onClick={() => setSearchOpen(true)}- className="flex items-center gap-2 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2.5 py-1.5 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-text-secondary)]"- >- <Search className="h-3.5 w-3.5" />- <span className="hidden sm:inline">Search</span>- <kbd className="hidden rounded border border-[var(--color-border-default)] px-1 py-0.5 text-[10px] sm:inline">- ⌘K- </kbd>- </button>- <ExportMenu- isExporting={isExporting}- onExportAll={handleExportAll}- zipHref={`/api/repos/${repoId}/export`}- page={selectedPage}- repoId={repoId}- />- {presentable && <PresentButton onClick={() => setPresent("deck")} />}- {selectedPage && (- <SidebarToggle- open={sidebarOpen}- onToggle={() => setSidebarOpen((o) => !o)}- />- )}- </DocsHeader>+ {presentable && <PresentButton onClick={() => setPresent("deck")} />}+ {selectedPage && (+ <SidebarToggle+ open={sidebarOpen}+ onToggle={() => setSidebarOpen((o) => !o)}+ />+ )}+ </DocsHeader>- <div className="flex-1 min-h-0">{body}</div>+ <div className="flex-1 min-h-0">{body}</div>+ </div>{/* Present mode overlay — full-screen, escapes the dashboard chrome */}{presentMode && presentModel && (diff --git a/packages/web/src/components/docs/docs-viewer.tsx b/packages/web/src/components/docs/docs-viewer.tsxindex 55aed1507..a665d9684 100644--- a/packages/web/src/components/docs/docs-viewer.tsx+++ b/packages/web/src/components/docs/docs-viewer.tsx@@ -3,14 +3,7 @@import { useCallback } from "react";import Link from "next/link";import useSWR from "swr";-import {- Activity,- Network,- GitBranch,- ArrowRight,- Flame,- Bug,-} from "lucide-react";+import { ArrowRight, Flame, Bug } from "lucide-react";import { cn } from "@/lib/utils/cn";import { getGitMetadata } from "@/lib/api/git";import { summarizeFixHistory } from "@repowise-dev/ui/lib/fix-history";@@ -74,14 +67,9 @@ function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: strinreturn (<div className="space-y-4">- {/* Graph Metrics */}+ {/* Graph importance. No section header of its own — the rail groups these+ under one "Signals" label, so the rows speak for themselves. */}<div>- <div className="flex items-center gap-1.5 mb-2">- <Activity className="h-3 w-3 text-[var(--color-text-tertiary)]" />- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">- Importance- </span>- </div><div className="space-y-2"><PercentileBar value={metrics.pagerank_percentile} label="PageRank" /><PercentileBar value={metrics.betweenness_percentile} label="Centrality" />@@ -97,21 +85,17 @@ function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: strin</div></div>- {/* Community */}+ {/* Community — a single value, so it renders as a labelled row like the+ rest rather than as its own titled section. */}{metrics.community_label && (- <div>- <div className="flex items-center gap-1.5 mb-2">- <Network className="h-3 w-3 text-[var(--color-text-tertiary)]" />- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">- Community- </span>- </div>+ <div className="flex items-center justify-between gap-2">+ <span className="text-xs text-[var(--color-text-tertiary)]">Community</span><Linkhref={`/repos/${repoId}/architecture?view=graph&colorMode=community`}- className="inline-flex items-center gap-1 text-xs text-[var(--color-accent)] hover:underline"+ className="inline-flex items-center gap-1 truncate text-xs text-[var(--color-accent)] hover:underline">{metrics.community_label}- <ArrowRight className="h-2.5 w-2.5" />+ <ArrowRight className="h-2.5 w-2.5 shrink-0" /></Link></div>)}@@ -119,12 +103,6 @@ function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: strin{/* Callers/Callees (for symbol pages) */}{callData && (callData.caller_count > 0 || callData.callee_count > 0) && (<div>- <div className="flex items-center gap-1.5 mb-2">- <GitBranch className="h-3 w-3 text-[var(--color-text-tertiary)]" />- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">- Call Graph- </span>- </div>{callData.caller_count > 0 && (<div className="mb-2"><p className="text-[10px] text-[var(--color-text-tertiary)] mb-1">Called by ({callData.caller_count})</p>@@ -179,12 +157,8 @@ function AtAGlance({ repoId, targetPath }: { repoId: string; targetPath: string);return (<div>- <div className="flex items-center gap-1.5 mb-2">- <Flame className="h-3 w-3 text-[var(--color-text-tertiary)]" />- <span className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">- At a glance- </span>- </div>+ {/* Leads the Signals list: the chips are the fastest read on the page,+ and they carry their own meaning without a header over them. */}<div className="flex flex-wrap gap-1.5">{data.is_hotspot && (<Badge variant="outline" className="text-[10px] border-[var(--color-warning)]/40 text-[var(--color-warning)]">@@ -352,18 +326,23 @@ export function DocsViewer({}intelligenceSlot={hasTargetPath ? (- <>- <AtAGlance repoId={repoId} targetPath={targetPath} />- <DocsSidebar repoId={repoId} targetPath={targetPath} />- {isFilePath && (- <div>- <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">- Security signals- </p>+ // One "Signals" block, not five. At a glance, Importance, Community,+ // Call graph and Security each announced themselves with their own+ // uppercase label over a handful of rows, so the rail was mostly+ // label. They answer one question between them — what should I know+ // about this code before I touch it — so they read as one list.+ <div>+ <p className="mb-2.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]">+ Signals+ </p>+ <div className="flex flex-col gap-4">+ <AtAGlance repoId={repoId} targetPath={targetPath} />+ <DocsSidebar repoId={repoId} targetPath={targetPath} />+ {isFilePath && (<SecurityPanelWrapper repoId={repoId} filePath={targetPath} />- </div>- )}- </>+ )}+ </div>+ </div>) : undefined}/>