Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(wiki): IA upgrade — semantic spine, search, signals, guided tour, layers, personas (#238)

Raghav Chamadiya303be9e152bb
diff --git a/packages/core/src/repowise/core/generation/categories.py b/packages/core/src/repowise/core/generation/categories.py
new file mode 100644
index 000000000..58902639a
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/categories.py
@@ -0,0 +1,61 @@
+"""File-category classification for category-adaptive documentation.
+
+A ``file_page`` is mostly source code, but a migration, a CI workflow, a
+schema, or a config file deserve a different summary voice than a service
+class. :func:`file_category` assigns one of a small set of categories from a
+file's path and language; the ``file_page`` template branches its guidance on
+the result so a migration reads like data and a workflow reads like a pipeline.
+
+Pure and deterministic — path/language string checks only.
+"""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+
+# Categories the file_page prompt knows how to adapt to.
+CATEGORY_CODE = "code"
+CATEGORY_CONFIG = "config"
+CATEGORY_DOC = "doc"
+CATEGORY_DATA = "data"
+CATEGORY_PIPELINE = "pipeline"
+
+_DOC_SUFFIXES = frozenset({".md", ".mdx", ".rst", ".txt", ".adoc"})
+_CONFIG_LANGUAGES = frozenset({"yaml", "toml", "json", "ini", "properties", "hcl"})
+_DATA_DIR_TOKENS = frozenset({"migrations", "versions", "models", "schema", "schemas", "entities"})
+_DATA_SUFFIXES = frozenset({".sql", ".prisma", ".graphql", ".proto"})
+_PIPELINE_PATH_HINTS = (
+ ".github/workflows/",
+ ".gitlab-ci",
+ "jenkinsfile",
+ "azure-pipelines",
+ ".circleci/",
+ "/pipelines/",
+ "/etl/",
+)
+
+
+def file_category(path: str, language: str = "", *, is_config: bool = False) -> str:
+ """Return the documentation category for *path*.
+
+ Resolution order (most specific first): doc → pipeline → data → config →
+ code. The default is :data:`CATEGORY_CODE`.
+ """
+ p = PurePosixPath(path)
+ lower = path.lower()
+ suffix = p.suffix.lower()
+
+ if suffix in _DOC_SUFFIXES:
+ return CATEGORY_DOC
+
+ if any(hint in lower for hint in _PIPELINE_PATH_HINTS):
+ return CATEGORY_PIPELINE
+
+ segments = {seg.lower() for seg in p.parts[:-1]}
+ if suffix in _DATA_SUFFIXES or segments & _DATA_DIR_TOKENS:
+ return CATEGORY_DATA
+
+ if is_config or (language or "").lower() in _CONFIG_LANGUAGES:
+ return CATEGORY_CONFIG
+
+ return CATEGORY_CODE
diff --git a/packages/core/src/repowise/core/generation/context_assembler.py b/packages/core/src/repowise/core/generation/context_assembler.py
index a0d1109b2..6ba80deae 100644
--- a/packages/core/src/repowise/core/generation/context_assembler.py
+++ b/packages/core/src/repowise/core/generation/context_assembler.py
@@ -22,6 +22,7 @@ import structlog
from repowise.core.ingestion.models import ParsedFile, RepoStructure, Symbol
+from .categories import file_category
from .models import GenerationConfig
log = structlog.get_logger(__name__)
@@ -56,6 +57,9 @@ class FilePageContext:
is_test: bool
parse_errors: list[str]
estimated_tokens: int
+ # Documentation category (code/config/doc/data/pipeline) — the file_page
+ # template adapts its summary guidance to this.
+ file_category: str = "code"
rag_context: list[str] = field(default_factory=list)
git_metadata: dict | None = None
co_change_pages: list[dict] = field(default_factory=list)
@@ -373,6 +377,11 @@ class ContextAssembler:
is_api_contract=parsed.file_info.is_api_contract,
is_entry_point=parsed.file_info.is_entry_point,
is_test=parsed.file_info.is_test,
+ file_category=file_category(
+ path,
+ parsed.file_info.language,
+ is_config=getattr(parsed.file_info, "is_config", False),
+ ),
parse_errors=parsed.parse_errors,
estimated_tokens=used,
git_metadata=git_meta,
diff --git a/packages/core/src/repowise/core/generation/layers.py b/packages/core/src/repowise/core/generation/layers.py
new file mode 100644
index 000000000..3bc0f8c7e
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/layers.py
@@ -0,0 +1,126 @@
+"""Architectural layer inference — the grouping spine for the wiki.
+
+Two responsibilities, both pure and deterministic:
+
+1. :func:`infer_layer` — assign every file to exactly one architectural
+ layer from its path, using a directory→layer hint table. This is the
+ *fallback* used when the knowledge graph has no layer for a file, so the
+ wiki can guarantee that **every** ``file_page`` carries a
+ ``metadata.layer_name``.
+
+2. :func:`compute_layer_order` — order the layers top→bottom by inter-layer
+ **dependency direction** (a layer that imports others sits above the layers
+ it imports). This turns the Architecture section from a flat list into a
+ hierarchy that teaches how the system is stacked. We reuse the import graph
+ already built during ingestion rather than re-deriving fan-in/fan-out.
+
+Neither function does any I/O or depends on graph libraries — they take plain
+strings and edge tuples, which keeps them trivially unit-testable.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable, Mapping
+from pathlib import PurePosixPath
+
+# ---------------------------------------------------------------------------
+# Directory → layer hint table. Each canonical layer maps to the
+# directory-name tokens that imply it. A
+# file is assigned the layer of the first matching path segment, scanning
+# from the deepest segment outward (the closest directory wins).
+# ---------------------------------------------------------------------------
+
+_LAYER_HINTS: tuple[tuple[str, frozenset[str]], ...] = (
+ ("API", frozenset({"routes", "api", "controllers", "endpoints", "handlers", "routers"})),
+ ("Service", frozenset({"services", "core", "lib", "domain", "logic", "usecases"})),
+ ("Data", frozenset({"models", "db", "data", "persistence", "repository", "repositories", "store", "stores", "entities"})),
+ ("UI", frozenset({"components", "views", "pages", "ui", "layouts", "widgets", "screens"})),
+ ("Middleware", frozenset({"middleware", "plugins", "interceptors", "guards"})),
+ ("Utility", frozenset({"utils", "helpers", "common", "shared", "tools", "util"})),
+ ("Config", frozenset({"config", "constants", "env", "settings", "conf"})),
+ ("Test", frozenset({"__tests__", "test", "tests", "spec", "specs", "e2e"})),
+ ("Types", frozenset({"types", "interfaces", "schemas", "contracts", "dtos", "typings"})),
+)
+
+# Fallback layer for files whose path matches no hint (root scripts, etc.).
+DEFAULT_LAYER = "Application"
+
+# Canonical top→bottom dependency rank. Used to seed the ordering and to
+# break ties when the import graph is too sparse to imply a direction. Lower
+# index = closer to the top (consumers); higher = closer to the bottom
+# (foundational): top imports middle imports bottom.
+_CANONICAL_RANK: dict[str, int] = {
+ "UI": 0,
+ "API": 1,
+ "Middleware": 2,
+ "Service": 3,
+ DEFAULT_LAYER: 4,
+ "Data": 5,
+ "Types": 6,
+ "Config": 7,
+ "Utility": 8,
+ "Test": 9,
+}
+
+
+def infer_layer(path: str) -> str:
+ """Return the architectural layer name for *path*.
+
+ Scans path segments from the deepest directory outward and returns the
+ first layer whose hint set contains a segment. Falls back to
+ :data:`DEFAULT_LAYER` when nothing matches.
+ """
+ segments = [s.lower() for s in PurePosixPath(path).parts[:-1]] # drop filename
+ # Deepest directory first — the closest folder describes the file best.
+ for seg in reversed(segments):
+ for layer_name, tokens in _LAYER_HINTS:
+ if seg in tokens:
+ return layer_name
+ return DEFAULT_LAYER
+
+
+def compute_layer_order(
+ file_layers: Mapping[str, str],
+ import_edges: Iterable[tuple[str, str]],
+) -> list[str]:
+ """Order the layers present in *file_layers* top→bottom by dependency direction.
+
+ Parameters
+ ----------
+ file_layers:
+ ``{file_path: layer_name}`` for every documented file.
+ import_edges:
+ ``(src, dst)`` pairs meaning *src imports dst* (file paths). External
+ nodes (``external:*``) and intra-layer edges are ignored.
+
+ A layer that does more importing than being-imported sits higher (it
+ consumes the layers below it). We rank by ``in - out`` ascending: a layer
+ imported by many but importing few is foundational (bottom); a layer that
+ imports many but is imported by few is a consumer (top). Ties fall back to
+ the canonical rank so the result is stable on graphs with no clear
+ direction.
+ """
+ layers = sorted(set(file_layers.values()))
+ if len(layers) <= 1:
+ return layers
+
+ out_deg: dict[str, int] = defaultdict(int) # edges leaving the layer
+ in_deg: dict[str, int] = defaultdict(int) # edges entering the layer
+ for src, dst in import_edges:
+ if src.startswith("external:") or dst.startswith("external:"):
+ continue
+ ls = file_layers.get(src)
+ ld = file_layers.get(dst)
+ if not ls or not ld or ls == ld:
+ continue
+ out_deg[ls] += 1
+ in_deg[ld] += 1
+
+ def sort_key(layer: str) -> tuple[int, int]:
+ # Net "imported-ness": more incoming than outgoing → foundational →
+ # sorts later (bottom). Negate out so consumers float to the top.
+ net = in_deg[layer] - out_deg[layer]
+ return (net, _CANONICAL_RANK.get(layer, len(_CANONICAL_RANK)))
+
+ return sorted(layers, key=sort_key)
diff --git a/packages/core/src/repowise/core/generation/mermaid_safety.py b/packages/core/src/repowise/core/generation/mermaid_safety.py
new file mode 100644
index 000000000..392190a0a
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/mermaid_safety.py
@@ -0,0 +1,207 @@
+"""Mermaid diagram safety pass.
+
+LLM-generated mermaid frequently breaks the renderer in two ways:
+
+* **Illegal node IDs** — the model uses a file path (``pkg/foo.py``) or a
+ dotted name (``app.main``) directly as a node ID. Mermaid only accepts
+ ``[A-Za-z0-9_]`` in bare IDs, so a single path ID fails the *entire*
+ diagram.
+* **Unquoted labels** — a shape label containing parentheses, slashes,
+ quotes or angle brackets (``A[run() -> None]``) is a parse error unless
+ the label is wrapped in quotes.
+
+This module rewrites only the ``mermaid`` fenced blocks of generated
+markdown to fix both. It is deliberately conservative: every block is
+processed under ``try/except`` and the original text is kept on any doubt,
+so the pass can never make a diagram that already rendered worse.
+
+Pure string work, no LLM call — cheap enough to run on every page.
+"""
+
+from __future__ import annotations
+
+import re
+
+import structlog
+
+log = structlog.get_logger(__name__)
+
+# Capture a fenced mermaid block: opening fence (with optional info string),
+# body, closing fence. Non-greedy body so adjacent blocks don't merge.
+_MERMAID_FENCE_RE = re.compile(
+ r"(?P<open>```+[ \t]*mermaid[^\n]*\n)(?P<body>.*?)(?P<close>\n[ \t]*```+)",
+ re.DOTALL | re.IGNORECASE,
+)
+
+# Diagram kinds that use ``id[label]`` node syntax we know how to repair.
+_GRAPH_DIRECTIVE_RE = re.compile(r"^\s*(graph|flowchart)\b", re.IGNORECASE)
+
+# Shape bracket pairs, longest opener first so ``([`` wins over ``(``.
+_SHAPE_PAIRS: tuple[tuple[str, str], ...] = (
+ ("([", "])"),
+ ("[[", "]]"),
+ ("[(", ")]"),
+ ("((", "))"),
+ ("{{", "}}"),
+ ("[/", "/]"),
+ ("[\\", "\\]"),
+ ("[", "]"),
+ ("(", ")"),
+ ("{", "}"),
+)
+
+# A node ID directly preceding a shape bracket. Permits path/dotted chars so
+# we can detect (and then slug) the illegal ones.
+_RAW_ID_CHARS = r"A-Za-z0-9_./\\-"
+
+# A path/dotted token anywhere (used to also catch bare edge endpoints that
+# never got a shape definition, e.g. ``A --> pkg/foo.py``). Requires at least
+# one ``.``/``/``/``\`` so plain identifiers and ``-`` IDs are left alone.
+_PATHY_TOKEN_RE = re.compile(
+ r"(?<![\w./\\])([A-Za-z0-9_][\w]*(?:[./\\][\w]+)+)"
+)
+
+# Label characters that force quoting.
+_LABEL_NEEDS_QUOTE_RE = re.compile(r"[()\[\]{}\"<>|/]")
+
+
+def _slug(raw: str) -> str:
+ """Turn an illegal node ID into a clean ``[A-Za-z0-9_]`` slug."""
+ s = re.sub(r"[^A-Za-z0-9_]", "_", raw)
+ s = re.sub(r"_+", "_", s).strip("_")
+ if not s:
+ s = "n"
+ if not s[0].isalpha() and s[0] != "_":
+ s = "n_" + s
+ return s
+
+
+def _build_id_map(body: str) -> dict[str, str]:
+ """Map every illegal (path/dotted) node ID in *body* to a unique slug."""
+ raw_ids: list[str] = []
+ seen: set[str] = set()
+ for m in _PATHY_TOKEN_RE.finditer(body):
+ raw = m.group(1)
+ if raw not in seen:
+ seen.add(raw)
+ raw_ids.append(raw)
+
+ id_map: dict[str, str] = {}
+ used: set[str] = set()
+ for raw in raw_ids:
+ slug = _slug(raw)
+ base = slug
+ i = 2
+ while slug in used:
+ slug = f"{base}_{i}"
+ i += 1
+ used.add(slug)
+ id_map[raw] = slug
+ return id_map
+
+
+def _quote_labels(body: str) -> str:
+ """Wrap shape labels containing special characters in double quotes."""
+
+ def _process(text: str) -> str:
+ out: list[str] = []
+ i = 0
+ n = len(text)
+ while i < n:
+ matched = False
+ for opener, closer in _SHAPE_PAIRS:
+ if text.startswith(opener, i):
+ end = text.find(closer, i + len(opener))
+ if end == -1:
+ continue
+ label = text[i + len(opener) : end]
+ stripped = label.strip()
+ already_quoted = (
+ len(stripped) >= 2
+ and stripped[0] == '"'
+ and stripped[-1] == '"'
+ )
+ if (
+ stripped
+ and not already_quoted
+ and _LABEL_NEEDS_QUOTE_RE.search(label)
+ ):
+ safe = label.replace('"', "&quot;")
+ out.append(opener + '"' + safe + '"' + closer)
+ else:
+ out.append(opener + label + closer)
+ i = end + len(closer)
+ matched = True
+ break
+ if not matched:
+ out.append(text[i])
+ i += 1
+ return "".join(out)
+
+ return "\n".join(_process(line) for line in body.split("\n"))
+
+
+def _rewrite_graph_block(body: str) -> str:
+ """Slug illegal node IDs and quote risky labels in a graph/flowchart body."""
+ id_map = _build_id_map(body)
+ rewritten = body
+ for raw, slug in id_map.items():
+ # Replace the raw token only when it is a standalone node ID, i.e. not
+ # part of a longer path/word. Guards keep ``foo`` inside ``foobar/x``
+ # from matching.
+ pattern = re.compile(
+ r"(?<![" + _RAW_ID_CHARS + r"])" + re.escape(raw) + r"(?![" + _RAW_ID_CHARS + r"])"
+ )
+ rewritten = pattern.sub(slug, rewritten)
+ return _quote_labels(rewritten)
+
+
+def sanitize_mermaid(markdown: str) -> str:
+ """Return *markdown* with every mermaid block made render-safe.
+
+ No-op for content with no mermaid blocks. Each block is repaired
+ independently and falls back to its original text on any error.
+ """
+ if not markdown or "mermaid" not in markdown.lower():
+ return markdown
+
+ def _replace(match: re.Match[str]) -> str:
+ open_fence = match.group("open")
+ body = match.group("body")
+ close_fence = match.group("close")
+ try:
+ first_line = body.lstrip().split("\n", 1)[0]
+ if _GRAPH_DIRECTIVE_RE.match(first_line):
+ body = _rewrite_graph_block(body)
+ else:
+ # Other diagram kinds (sequenceDiagram, erDiagram, classDiagram)
+ # have different grammars — only quote obviously risky labels is
+ # unsafe there, so leave them untouched.
+ pass
+ except Exception as exc: # never corrupt a working diagram
+ log.debug("mermaid_safety.block_failed", error=str(exc))
+ body = match.group("body")
+ return open_fence + body + close_fence
+
+ return _MERMAID_FENCE_RE.sub(_replace, markdown)
+
+
+def sanitize_pages(pages: list) -> int:
+ """Run :func:`sanitize_mermaid` over a list of ``GeneratedPage``.
+
+ Mutates ``page.content`` in place. Returns the number of pages whose
+ content actually changed (for logging).
+ """
+ changed = 0
+ for page in pages:
+ content = getattr(page, "content", None)
+ if not content:
+ continue
+ fixed = sanitize_mermaid(content)
+ if fixed != content:
+ page.content = fixed
+ changed += 1
+ return changed
+
+
+__all__ = ["sanitize_mermaid", "sanitize_pages"]
diff --git a/packages/core/src/repowise/core/generation/onboarding/__init__.py b/packages/core/src/repowise/core/generation/onboarding/__init__.py
index 6d3f569e6..0c42172cc 100644
--- a/packages/core/src/repowise/core/generation/onboarding/__init__.py
+++ b/packages/core/src/repowise/core/generation/onboarding/__init__.py
@@ -28,6 +28,7 @@ from .slots import (
SLOT_CODEBASE_MAP,
SLOT_DEVELOPMENT_GUIDE,
SLOT_GETTING_STARTED,
+ SLOT_GUIDED_TOUR,
SLOT_HOW_IT_WORKS,
SLOT_KEY_CONCEPTS,
SLOT_PROJECT_OVERVIEW,
@@ -47,6 +48,7 @@ __all__ = [
"SLOT_CODEBASE_MAP",
"SLOT_DEVELOPMENT_GUIDE",
"SLOT_GETTING_STARTED",
+ "SLOT_GUIDED_TOUR",
"SLOT_HOW_IT_WORKS",
"SLOT_KEY_CONCEPTS",
"SLOT_PROJECT_OVERVIEW",
diff --git a/packages/core/src/repowise/core/generation/onboarding/signals.py b/packages/core/src/repowise/core/generation/onboarding/signals.py
index 1937bb318..c7b85faed 100644
--- a/packages/core/src/repowise/core/generation/onboarding/signals.py
+++ b/packages/core/src/repowise/core/generation/onboarding/signals.py
@@ -42,3 +42,8 @@ class OnboardingSignals:
# KG-derived signals for onboarding pages.
kg_layers: tuple[dict, ...] = ()
kg_tour_steps: tuple[dict, ...] = ()
+ # Topology-driven guided-tour stops (ordered), each referencing an
+ # already-generated page. Empty when no tour could be built.
+ tour_stops: tuple[dict, ...] = ()
+ # Layers ordered top→bottom by dependency direction (the grouping spine).
+ layer_order: tuple[str, ...] = ()
diff --git a/packages/core/src/repowise/core/generation/onboarding/slots.py b/packages/core/src/repowise/core/generation/onboarding/slots.py
index c99c05c1b..973c2adab 100644
--- a/packages/core/src/repowise/core/generation/onboarding/slots.py
+++ b/packages/core/src/repowise/core/generation/onboarding/slots.py
@@ -20,6 +20,7 @@ from __future__ import annotations
SLOT_PROJECT_OVERVIEW = "project_overview"
SLOT_ARCHITECTURE_GUIDE = "architecture_guide"
+SLOT_GUIDED_TOUR = "guided_tour"
SLOT_GETTING_STARTED = "getting_started"
SLOT_CODEBASE_MAP = "codebase_map"
SLOT_KEY_CONCEPTS = "key_concepts"
@@ -32,6 +33,7 @@ SLOT_ACTIVE_LANDSCAPE = "active_landscape"
ONBOARDING_ORDER: tuple[str, ...] = (
SLOT_PROJECT_OVERVIEW,
SLOT_ARCHITECTURE_GUIDE,
+ SLOT_GUIDED_TOUR,
SLOT_GETTING_STARTED,
SLOT_CODEBASE_MAP,
SLOT_KEY_CONCEPTS,
@@ -53,6 +55,7 @@ PROMOTED_SLOTS: dict[str, str] = {
SLOT_TITLES: dict[str, str] = {
SLOT_PROJECT_OVERVIEW: "Project Overview",
SLOT_ARCHITECTURE_GUIDE: "Architecture Guide",
+ SLOT_GUIDED_TOUR: "Guided Tour",
SLOT_GETTING_STARTED: "Getting Started",
SLOT_CODEBASE_MAP: "Codebase Map",
SLOT_KEY_CONCEPTS: "Key Concepts",
@@ -65,6 +68,7 @@ SLOT_TITLES: dict[str, str] = {
SLOT_PREREQUISITES: dict[str, tuple[str, ...]] = {
SLOT_PROJECT_OVERVIEW: (),
SLOT_ARCHITECTURE_GUIDE: (),
+ SLOT_GUIDED_TOUR: (SLOT_PROJECT_OVERVIEW,),
SLOT_GETTING_STARTED: (),
SLOT_CODEBASE_MAP: (SLOT_PROJECT_OVERVIEW,),
SLOT_KEY_CONCEPTS: (SLOT_PROJECT_OVERVIEW, SLOT_ARCHITECTURE_GUIDE),
diff --git a/packages/core/src/repowise/core/generation/onboarding/subkinds/__init__.py b/packages/core/src/repowise/core/generation/onboarding/subkinds/__init__.py
index a611a755e..75238f97a 100644
--- a/packages/core/src/repowise/core/generation/onboarding/subkinds/__init__.py
+++ b/packages/core/src/repowise/core/generation/onboarding/subkinds/__init__.py
@@ -9,6 +9,7 @@ re-orders to ``ONBOARDING_ORDER`` for iteration.
"""
# Side-effect imports — each module calls register() at import time.
+from . import guided_tour # noqa: F401
from . import codebase_map # noqa: F401
from . import getting_started # noqa: F401
from . import key_concepts # noqa: F401
diff --git a/packages/core/src/repowise/core/generation/onboarding/subkinds/codebase_map.py b/packages/core/src/repowise/core/generation/onboarding/subkinds/codebase_map.py
index e1c3f3072..13511204a 100644
--- a/packages/core/src/repowise/core/generation/onboarding/subkinds/codebase_map.py
+++ b/packages/core/src/repowise/core/generation/onboarding/subkinds/codebase_map.py
@@ -46,6 +46,8 @@ class CodebaseMapContext:
# Repo-wide entry points hoisted to a dedicated section.
entry_points: list[str] = field(default_factory=list)
kg_layers: list[dict] = field(default_factory=list)
+ # Layers ordered top→bottom by dependency direction (the grouping spine).
+ layer_order: list[str] = field(default_factory=list)
def _top_level_dir(path: str) -> str:
@@ -129,6 +131,7 @@ def _build(signals: OnboardingSignals) -> CodebaseMapContext | None:
directories=directories,
entry_points=list(getattr(signals.repo_structure, "entry_points", []))[:10],
kg_layers=list(signals.kg_layers) if signals.kg_layers else [],
+ layer_order=list(signals.layer_order),
)
diff --git a/packages/core/src/repowise/core/generation/onboarding/subkinds/guided_tour.py b/packages/core/src/repowise/core/generation/onboarding/subkinds/guided_tour.py
new file mode 100644
index 000000000..9ffe827f6
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/onboarding/subkinds/guided_tour.py
@@ -0,0 +1,82 @@
+"""Onboarding subkind: Guided Tour.
+
+A single pedagogical page that narrates the topology-driven tour — an ordered
+walk that starts at the entry points and follows the import graph inward,
+closing on how the system is built and deployed. The *ordering* is computed
+deterministically upstream (``generation.tour``) and arrives here as
+``signals.tour_stops``; this subkind hands those ordered stops (each already
+pointing at a real wiki page, with its one-line summary) to the LLM, which
+writes the connective narration that ties one step to the next.
+
+Gate: skips when no tour could be built (e.g. a repo with no documented
+files), so the slot simply doesn't appear.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..registry import SubkindSpec, register
+from ..signals import OnboardingSignals
+from ..slots import SLOT_GUIDED_TOUR, SLOT_TITLES
+
+# A tour with only the overview stop isn't worth a page on its own.
+_MIN_STOPS = 2
+
+
+@dataclass
+class TourStopContext:
+ """One stop as the template sees it — ordered page reference + summary."""
+
+ order: int
+ target_path: str
+ page_type: str
+ title: str
+ kind: str
+ reason: str
+ summary: str
+
+
+@dataclass
+class GuidedTourContext:
+ repo_name: str
+ stops: list[TourStopContext] = field(default_factory=list)
+ layer_order: list[str] = field(default_factory=list)
+
+
+def _build(signals: OnboardingSignals) -> GuidedTourContext | None:
+ if len(signals.tour_stops) < _MIN_STOPS:
+ return None
+
+ stops: list[TourStopContext] = []
+ for s in signals.tour_stops:
+ target = s.get("target_path", "")
+ # The overview's summary is keyed by repo_name; file/infra pages by path.
+ summary = (signals.completed_page_summaries.get(target) or "").strip()[:240]
+ stops.append(
+ TourStopContext(
+ order=int(s.get("order", len(stops) + 1)),
+ target_path=target,
+ page_type=s.get("page_type", "file_page"),
+ title=s.get("title", target),
+ kind=s.get("kind", "code"),
+ reason=s.get("reason", ""),
+ summary=summary,
+ )
+ )
+
+ return GuidedTourContext(
+ repo_name=signals.repo_name,
+ stops=stops,
+ layer_order=list(signals.layer_order),
+ )
+
+
+register(
+ SubkindSpec(
+ slot=SLOT_GUIDED_TOUR,
+ title=SLOT_TITLES[SLOT_GUIDED_TOUR],
+ template="guided_tour.j2",
+ build_context=_build,
+ )
+)
diff --git a/packages/core/src/repowise/core/generation/onboarding/subkinds/key_concepts.py b/packages/core/src/repowise/core/generation/onboarding/subkinds/key_concepts.py
index 2a5b1f6f6..f3f85257c 100644
--- a/packages/core/src/repowise/core/generation/onboarding/subkinds/key_concepts.py
+++ b/packages/core/src/repowise/core/generation/onboarding/subkinds/key_concepts.py
@@ -45,6 +45,7 @@ class KeyConceptsContext:
concept_symbols: list[ConceptSymbol] = field(default_factory=list)
community_labels: list[str] = field(default_factory=list)
decision_titles: list[str] = field(default_factory=list)
+ layer_order: list[str] = field(default_factory=list)
def _pagerank_threshold(pagerank: dict[str, float]) -> float:
@@ -164,6 +165,7 @@ def _build(signals: OnboardingSignals) -> KeyConceptsContext | None:
concept_symbols=concept_symbols,
community_labels=community_labels,
decision_titles=decision_titles,
+ layer_order=list(signals.layer_order),
)
diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.py
index 2d57e8db3..860bb6d6c 100644
--- a/packages/core/src/repowise/core/generation/page_generator/core.py
+++ b/packages/core/src/repowise/core/generation/page_generator/core.py
@@ -45,6 +45,43 @@ if TYPE_CHECKING:
log = structlog.get_logger(__name__)
+def _attach_file_provenance(page: GeneratedPage, ctx: FilePageContext) -> None:
+ """Surface KG layer + the inputs a file page was synthesised from.
+
+ Reads only already-assembled context (no new work), so it is cheap and
+ safe for both the LLM and the deterministic tier-2 path. The frontend
+ renders ``layer_name`` as a zoom-out chip and ``sources`` as a "built
+ from" provenance list.
+ """
+ if ctx.kg_layer_name:
+ page.metadata["layer_name"] = ctx.kg_layer_name
+ if ctx.kg_layer_role:
+ page.metadata["layer_role"] = ctx.kg_layer_role
+ else:
+ # Guarantee every file page carries a layer so the Architecture tree
+ # can group it. When the knowledge graph has no layer, fall back to
+ # path-based inference.
+ from ..layers import infer_layer
+
+ page.metadata["layer_name"] = infer_layer(ctx.file_path)
+
+ sources: list[dict[str, str]] = []
+ seen: set[str] = set()
+ # Direct dependencies are the upstream files this doc draws on.
+ for dep in ctx.dependencies[:10]:
+ if dep and dep not in seen:
+ seen.add(dep)
+ sources.append({"path": dep, "kind": "dependency"})
+ # Architectural decisions cite their own evidence file.
+ for rec in ctx.decision_records[:5]:
+ ev = rec.get("evidence_file") or rec.get("source")
+ if ev and ev not in seen:
+ seen.add(ev)
+ sources.append({"path": ev, "kind": "decision"})
+ if sources:
+ page.metadata["sources"] = sources
+
+
@dataclass(frozen=True)
class PriorPage:
"""Snapshot of a previously-generated page used for cross-run reuse.
@@ -227,6 +264,7 @@ class PageGenerator(PerTypeGenerationMixin):
refs=hal_warnings[:5],
)
page.metadata["hallucination_warnings"] = hal_warnings
+ _attach_file_provenance(page, ctx)
return page
async def _generate_file_page_tier2(
@@ -262,6 +300,7 @@ class PageGenerator(PerTypeGenerationMixin):
updated_at=now,
)
page.metadata["doc_tier"] = 2
+ _attach_file_provenance(page, ctx)
return page
# ------------------------------------------------------------------
diff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.py
index 7e9af2648..ff0880693 100644
--- a/packages/core/src/repowise/core/generation/page_generator/levels.py
+++ b/packages/core/src/repowise/core/generation/page_generator/levels.py
@@ -376,6 +376,8 @@ def build_level8_coros(run: _GenerationRun) -> list[tuple[str, Any]]:
completed_page_summaries=dict(run.completed_page_summaries),
kg_layers=kg_layers,
kg_tour_steps=kg_tour_steps,
+ tour_stops=tuple(run.tour_stops),
+ layer_order=tuple(run.layer_order),
)
for spec in specs:
page_id = compute_page_id("onboarding", _onboarding.target_path(spec.slot))
diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
index 1b5c8a48f..8127f64c2 100644
--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py
@@ -110,6 +110,12 @@ class _GenerationRun:
self.job_id: str | None = None
self.file_page_contexts: dict[str, FilePageContext] = {}
+ # Guided-tour ordering + the layer spine, both derived after selection
+ # and reused by level-8 onboarding, the repo overview, and the agent
+ # surface. Empty until _compute_ia() runs.
+ self.tour_stops: list[dict] = []
+ self.layer_order: list[str] = []
+
# Selection allow-sets (populated by _compute_selection).
self.selection: Any = None
self.code_files: list[Any] = []
@@ -257,6 +263,49 @@ class _GenerationRun:
if self.job_system is not None and self.job_id is not None:
self.job_system.start_job(self.job_id, estimated_total)
+ def _file_import_edges(self) -> list[tuple[str, str]]:
+ """``(src, dst)`` import edges between file nodes (src imports dst)."""
+ edges: list[tuple[str, str]] = []
+ try:
+ for src, dst in self.graph.edges():
+ if isinstance(src, str) and isinstance(dst, str):
+ edges.append((src, dst))
+ except Exception:
+ pass
+ return edges
+
+ def _compute_ia(self) -> None:
+ """Derive the guided-tour ordering and the layer spine after selection.
+
+ Both reuse already-computed signals (selection allow-sets, PageRank,
+ the import graph) and reference only pages that will exist, so neither
+ spawns new LLM work.
+ """
+ from ..layers import compute_layer_order, infer_layer
+ from ..tour import build_tour
+
+ import_edges = self._file_import_edges()
+
+ # Tour: ordered stops over the selected file/infra pages + overview.
+ stops = build_tour(
+ self.parsed_files,
+ self.pagerank,
+ import_edges,
+ file_page_paths=self.sel_file_paths,
+ infra_paths=self.sel_infra_paths,
+ repo_name=self.repo_name,
+ )
+ self.tour_stops = [s.as_dict() for s in stops]
+
+ # Layer spine: every documented file gets a layer (KG when present,
+ # path-based inference otherwise), then layers are ordered top→bottom
+ # by inter-layer dependency direction.
+ file_layers: dict[str, str] = {}
+ for path in self.sel_file_paths:
+ kg_fc = self.kg_ctx.get_file_context(path) if self.kg_ctx.available else None
+ file_layers[path] = (kg_fc.layer_name if kg_fc and kg_fc.layer_name else "") or infer_layer(path)
+ self.layer_order = compute_layer_order(file_layers, import_edges)
+
# ------------------------------------------------------------------
# Level runner
# ------------------------------------------------------------------
@@ -328,6 +377,7 @@ class _GenerationRun:
await self._seed_resume()
self._compute_selection()
self._announce_total()
+ self._compute_ia()
all_pages: list[GeneratedPage] = []
@@ -361,6 +411,28 @@ class _GenerationRun:
self.gen._tag_promoted_pages(final_pages)
all_pages.extend(final_pages)
+ # Attach the IA spine to the repo overview so the web reader and the
+ # MCP get_overview both expose the topology tour order + ordered layers.
+ if self.tour_stops or self.layer_order:
+ for page in final_pages:
+ if page.page_type == "repo_overview":
+ if self.tour_stops:
+ page.metadata["guided_tour"] = self.tour_stops
+ if self.layer_order:
+ page.metadata["layer_order"] = self.layer_order
+ break
+
+ # Post-generation: repair mermaid diagrams so illegal node IDs / unquoted
+ # labels in LLM output don't break the whole diagram in the renderer.
+ try:
+ from ..mermaid_safety import sanitize_pages
+
+ fixed = sanitize_pages(all_pages)
+ if fixed:
+ log.info("mermaid_safety.applied", pages_changed=fixed)
+ except Exception as exc:
+ log.debug("mermaid_safety.failed", error=str(exc))
+
# Post-generation: resolve backtick refs into wiki links + backlinks.
try:
from ..interlinking import attach_wiki_links_and_backlinks
diff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.py
index 09755ab9a..42425e38e 100644
--- a/packages/core/src/repowise/core/generation/selection/selector.py
+++ b/packages/core/src/repowise/core/generation/selection/selector.py
@@ -17,6 +17,7 @@ import structlog
from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY
+from ..tour import DEFAULT_MAX_LANDMARKS, tour_landmark_paths
from .budget import BucketAllocation, allocate_budget, compute_budget
from .scoring import (
score_api_contract,
@@ -305,6 +306,29 @@ def _coverage_pct(cfg: Any) -> float:
return float(getattr(cfg, "coverage_pct", None) or getattr(cfg, "max_pages_pct", 0.20))
+def _ensure_landmarks(selected: list[str], landmarks: list[str]) -> list[str]:
+ """Guarantee every *landmark* is in *selected*, keeping the count honest.
+
+ For each landmark not already chosen, drop the lowest-scored *non-landmark*
+ file from the tail (``selected`` is score-ordered descending) and append the
+ landmark — so the total file_page count is unchanged. The only case the
+ count can grow is when there is nothing left to displace (e.g. a near-zero
+ budget where every selected file is itself a landmark); that overage is
+ bounded by ``len(landmarks)`` (at most ``DEFAULT_MAX_LANDMARKS``).
+ """
+ sel = list(selected)
+ landmark_set = set(landmarks)
+ for m in landmarks:
+ if m in sel:
+ continue
+ for i in range(len(sel) - 1, -1, -1):
+ if sel[i] not in landmark_set:
+ sel.pop(i)
+ break
+ sel.append(m)
+ return sel
+
+
def select_pages(inputs: SelectionInputs) -> Selection:
"""Return the allow-set of pages to generate for one run.
@@ -339,8 +363,25 @@ def select_pages(inputs: SelectionInputs) -> Selection:
n_files=len(inputs.parsed_files),
)
+ # The guided tour wants its highest-value entry points to land on real
+ # pages. Force those landmarks into the file_page allow-set, displacing the
+ # lowest-scored picks so the budget total stays honest (see _ensure_landmarks).
+ selected_files = [p for _, p in files[: allocation.file_page]]
+ if selected_files or allocation.file_page > 0:
+ file_candidate_set = {p for _, p in files}
+ landmarks = [
+ p
+ for p in tour_landmark_paths(
+ inputs.parsed_files,
+ inputs.pagerank,
+ max_landmarks=DEFAULT_MAX_LANDMARKS,
+ )
+ if p in file_candidate_set
+ ]
+ selected_files = _ensure_landmarks(selected_files, landmarks)
+
sel = Selection(
- file_page_paths=[p for _, p in files[: allocation.file_page]],
+ file_page_paths=selected_files,
symbol_spotlights=[t for _, t in symbols[: allocation.symbol_spotlight]],
module_groups=[m for _, m in modules[: allocation.module_page]],
api_contract_paths=[p for _, p in apis[: allocation.api_contract]],
diff --git a/packages/core/src/repowise/core/generation/templates/file_page.j2 b/packages/core/src/repowise/core/generation/templates/file_page.j2
index 670a0151f..bcfab54ce 100644
--- a/packages/core/src/repowise/core/generation/templates/file_page.j2
+++ b/packages/core/src/repowise/core/generation/templates/file_page.j2
@@ -1,5 +1,28 @@
You are documenting the file `{{ ctx.file_path }}` (language: {{ ctx.language }}).
+{% if ctx.file_category == "config" %}
+This is a **configuration** file. Document what it configures and which
+components read it, what each meaningful key/section controls, and the
+operational effect of changing values — not its syntax. Lead with the system
+it configures.
+{% elif ctx.file_category == "data" %}
+This is a **data / schema** file (model, migration, or schema definition).
+Document the entities, tables, columns, and relationships it defines, what the
+data means, and — for a migration — what it changes and why. Lead with the
+data model, and name the foreign keys / relationships that connect it to the
+rest of the system.
+{% elif ctx.file_category == "pipeline" %}
+This is a **pipeline / CI-CD** file. Document the stages it runs, their order,
+the triggers and conditions, and the artifacts or deployments it produces.
+Lead with what the pipeline accomplishes end-to-end.
+{% elif ctx.file_category == "doc" %}
+This is a **documentation** file. Summarise what it explains and who should
+read it; do not restate it verbatim.
+{% else %}
+This is a **code** file. Lead with its architectural role and what it produces
+or consumes (see the lead-with-role rule).
+{% endif %}
+
## File Overview
**Path:** `{{ ctx.file_path }}` | **Language:** {{ ctx.language }}{% if ctx.is_test %} | test file{% endif %}{% if ctx.is_api_contract %} | API contract{% endif %}
diff --git a/packages/core/src/repowise/core/generation/templates/onboarding/codebase_map.j2 b/packages/core/src/repowise/core/generation/templates/onboarding/codebase_map.j2
index c5b13da57..a5f8c1c67 100644
--- a/packages/core/src/repowise/core/generation/templates/onboarding/codebase_map.j2
+++ b/packages/core/src/repowise/core/generation/templates/onboarding/codebase_map.j2
@@ -16,6 +16,15 @@ spatial. The right tone is: "if you're looking for X, go to Y."
{% endfor %}
{% endif %}
+{% if ctx.layer_order %}
+## Architectural layers (top → bottom by dependency direction)
+The codebase stacks into these layers; higher layers depend on lower ones.
+Use this ordering to frame the tour through the directories below.
+{% for layer in ctx.layer_order %}
+{{ loop.index }}. {{ layer }}
+{% endfor %}
+{% endif %}
+
{% if ctx.kg_layers %}
## Architectural Layers (from Knowledge Graph)
{% for layer in ctx.kg_layers %}
diff --git a/packages/core/src/repowise/core/generation/templates/onboarding/guided_tour.j2 b/packages/core/src/repowise/core/generation/templates/onboarding/guided_tour.j2
new file mode 100644
index 000000000..7f1a0146e
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/templates/onboarding/guided_tour.j2
@@ -0,0 +1,60 @@
+You are writing the "Guided Tour" page for `{{ ctx.repo_name }}` — a single,
+ordered walk that takes a new contributor from the entry points inward, one
+stop at a time, and closes on how the system is built and deployed.
+
+The stops below are ALREADY ORDERED by graph topology (entry points first,
+then the files they import, depth by depth, with infrastructure last). Each
+stop names a real wiki page and its one-line summary. Your job is the
+*connective tissue*: for each stop write 2–4 sentences that say what the
+reader is looking at, why it matters at this point in the walk, and — crucially
+— how it relates to the stops BEFORE it. The tour must read like a tour, not a
+glossary: explicitly back-reference earlier steps ("the parser introduced in
+Step 2 hands its output to…").
+
+{% if ctx.layer_order %}
+## Layer spine (top → bottom by dependency direction)
+The system stacks as: {{ ctx.layer_order | join(" → ") }}. Use this to orient
+the reader as the walk descends from entry points toward foundations.
+{% endif %}
+
+## The ordered stops (narrate these IN THIS ORDER — do not reorder)
+{% for s in ctx.stops %}
+### Step {{ s.order }}: {{ s.title }} ({{ s.kind }})
+- Page: `{{ s.target_path }}` ({{ s.page_type }})
+- Why this stop: {{ s.reason }}
+{% if s.summary %}- What it does: {{ s.summary }}{% endif %}
+
+{% endfor %}
+
+## What to write
+Produce a markdown page with this structure:
+
+1. **## How to take this tour** — one short paragraph: this is an ordered walk
+ from the entry points inward; each step builds on the last.
+2. **## The tour** — one `### Step N: <title>` subsection per stop above, in
+ order. For each step:
+ - Open with one sentence stating the file/page's role (lead with the role:
+ "orchestrator", "entry point", "parser", "adapter", "deploy manifest", …).
+ - Then 1–3 sentences of connective narration that reference at least one
+ earlier step by number where it makes sense.
+ - End the sentence that names the page with the path in backticks (e.g.
+ `{{ ctx.stops[0].target_path }}`) so the reader can click through.
+3. **## Where to go next** — 2–3 bullets pointing past the tour (the layer
+ pages, the module pages, or the search), each with a half-sentence reason.
+
+Style — make every step concrete, like these:
+- Bad: "This is the Dockerfile."
+ Good: "The Dockerfile defines how the application is packaged into a container
+ image — a multi-stage build that compiles the sources from Step 3 and
+ copies only the output into a slim runtime image."
+- Bad: "These are the database models."
+ Good: "The data models define the core entities; the `User` model here is the
+ one the request handler in Step 2 loads on every authenticated call."
+
+Hard rules:
+- Narrate the stops in the given order; never invent stops, paths, or files
+ that are not listed above.
+- If a stop's summary is missing, describe its role from its title and kind
+ rather than inventing internals.
+- Output markdown only. No preamble, no apologies, no closing summary section
+ beyond "Where to go next".
diff --git a/packages/core/src/repowise/core/generation/templates/onboarding/key_concepts.j2 b/packages/core/src/repowise/core/generation/templates/onboarding/key_concepts.j2
index 2002c5642..84321366f 100644
--- a/packages/core/src/repowise/core/generation/templates/onboarding/key_concepts.j2
+++ b/packages/core/src/repowise/core/generation/templates/onboarding/key_concepts.j2
@@ -12,6 +12,15 @@ explain how they fit together.
{% endif %}
{% endfor %}
+{% if ctx.layer_order %}
+## Architectural layers (top → bottom by dependency direction)
+Group the concepts by which layer they belong to when it clarifies the mental
+model; higher layers depend on lower ones.
+{% for layer in ctx.layer_order %}
+{{ loop.index }}. {{ layer }}
+{% endfor %}
+{% endif %}
+
{% if ctx.community_labels %}
## Architectural clusters present
The codebase organises into these clusters (detected via dependency
diff --git a/packages/core/src/repowise/core/generation/tour.py b/packages/core/src/repowise/core/generation/tour.py
new file mode 100644
index 000000000..618e57648
--- /dev/null
+++ b/packages/core/src/repowise/core/generation/tour.py
@@ -0,0 +1,289 @@
+"""Topology-driven guided tour.
+
+The guided tour is an **ordering + curation** layer over wiki pages that
+already exist within the user's coverage budget. It is *not* a generator of
+new expensive pages: every stop points at a page the selection layer already
+chose (a ``file_page`` / ``module_page`` / ``infra_page`` / ``repo_overview``)
+plus a short, deterministic "why you're here" reason. A single onboarding
+page later narrates the whole ordered sequence in one LLM call, so the tour
+adds at most one page regardless of repo size.
+
+How the order is derived (all deterministic — reuses signals the generation
+run already computes):
+
+1. **Entry-point scoring** (:func:`score_entry_points`) — filename heuristics
+ (``main``/``app``/``server``/…), our ``is_entry_point`` ingestion flag,
+ shallow path depth, and PageRank. The top scorers seed the walk.
+2. **Breadth-first walk** over the import graph from those seeds, assigning
+ each reachable file a *depth* (how many imports away from an entry point).
+3. **Depth-bucketed step order** — the reader moves from entry points inward,
+ so step N's narration can back-reference what step N-1 introduced.
+4. **Non-code woven in** — infrastructure pages land at the end ("how it's
+ built and deployed"); the repo overview always opens the tour.
+
+Because the tour only references already-selected pages, it honours the
+coverage budget by construction. :func:`tour_landmark_paths` lets the selector
+*guarantee* the handful of highest-value entry points get a page (see
+``selection.selector`` for how that is kept count-honest).
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Any
+
+# Filenames that conventionally mark an executable / wiring entry point.
+_ENTRY_FILENAME_STEMS: frozenset[str] = frozenset(
+ {
+ "index",
+ "main",
+ "app",
+ "server",
+ "mod",
+ "manage",
+ "wsgi",
+ "asgi",
+ "cli",
+ "__main__",
+ "bootstrap",
+ "entry",
+ }
+)
+
+# Upper bound on tour stops — long enough to teach the spine, short enough to
+# stay a tour and not a table of contents.
+DEFAULT_MAX_STOPS = 12
+
+# How many top-scored entry points the selector is asked to guarantee a page
+# for, so the tour can always open on real landmark documentation.
+DEFAULT_MAX_LANDMARKS = 5
+
+
+@dataclass(frozen=True)
+class TourStop:
+ """One ordered stop. Always points at a page that already exists."""
+
+ order: int
+ target_path: str
+ page_type: str
+ title: str
+ depth: int
+ kind: str # "overview" | "code" | "infra"
+ reason: str
+
+ def as_dict(self) -> dict[str, Any]:
+ return {
+ "order": self.order,
+ "target_path": self.target_path,
+ "page_type": self.page_type,
+ "title": self.title,
+ "depth": self.depth,
+ "kind": self.kind,
+ "reason": self.reason,
+ }
+
+
+def _path_depth(path: str) -> int:
+ """Directory depth — 0 for a root file, 1 for one level deep, etc."""
+ return max(0, len(PurePosixPath(path).parts) - 1)
+
+
+def score_entry_points(
+ parsed_files: Sequence[Any],
+ pagerank: Mapping[str, float],
+) -> list[tuple[float, str]]:
+ """Score code files as candidate tour entry points, descending.
+
+ Scoring (additive):
+ * ``is_entry_point`` ingestion flag .............. +3
+ * filename stem in the entry-name set ............ +3
+ * file at repo root or one level deep ............ +1
+ * PageRank in the top 10% of all files ........... +1
+
+ Returns ``[(score, path), ...]`` sorted by score then path for stability.
+ Only files with a positive score are returned.
+ """
+ if not parsed_files:
+ return []
+ pr_values = sorted((pagerank.get(p.file_info.path, 0.0) for p in parsed_files), reverse=True)
+ top_decile_idx = max(0, int(len(pr_values) * 0.10) - 1)
+ pr_threshold = pr_values[top_decile_idx] if pr_values else 0.0
+
+ scored: list[tuple[float, str]] = []
+ for p in parsed_files:
+ fi = p.file_info
+ path = fi.path
+ score = 0.0
+ if getattr(fi, "is_entry_point", False):
+ score += 3.0
+ if PurePosixPath(path).stem.lower() in _ENTRY_FILENAME_STEMS:
+ score += 3.0
+ if _path_depth(path) <= 1:
+ score += 1.0
+ if pagerank.get(path, 0.0) >= pr_threshold > 0.0:
+ score += 1.0
+ if score > 0.0:
+ scored.append((score, path))
+ scored.sort(key=lambda t: (-t[0], t[1]))
+ return scored
+
+
+def tour_landmark_paths(
+ parsed_files: Sequence[Any],
+ pagerank: Mapping[str, float],
+ *,
+ max_landmarks: int = DEFAULT_MAX_LANDMARKS,
+) -> list[str]:
+ """Return the top entry-point file paths the tour wants guaranteed a page.
+
+ The selector force-includes these into the ``file_page`` allow-set
+ (displacing its lowest-scored picks so the page count stays honest), so
+ the tour can always open on real landmark documentation even at low
+ coverage.
+ """
+ scored = score_entry_points(parsed_files, pagerank)
+ return [path for _, path in scored[: max(0, max_landmarks)]]
+
+
+def _bfs_depths(
+ seeds: list[str],
+ adjacency: Mapping[str, list[str]],
+ universe: set[str],
+) -> dict[str, int]:
+ """Assign a BFS depth to each file reachable from *seeds* within *universe*."""
+ depth: dict[str, int] = {}
+ queue: deque[tuple[str, int]] = deque()
+ for s in seeds:
+ if s in universe and s not in depth:
+ depth[s] = 0
+ queue.append((s, 0))
+ while queue:
+ node, d = queue.popleft()
+ for dep in adjacency.get(node, []):
+ if dep in universe and dep not in depth:
+ depth[dep] = d + 1
+ queue.append((dep, d + 1))
+ return depth
+
+
+def build_tour(
+ parsed_files: Sequence[Any],
+ pagerank: Mapping[str, float],
+ import_edges: Iterable[tuple[str, str]],
+ *,
+ file_page_paths: Iterable[str],
+ infra_paths: Iterable[str] = (),
+ repo_name: str = "",
+ max_stops: int = DEFAULT_MAX_STOPS,
+) -> list[TourStop]:
+ """Build the ordered tour over pages that already exist.
+
+ Only files in *file_page_paths* (and *infra_paths*) become stops — the
+ tour never references undocumented files, so it is budget-safe by
+ construction. ``repo_overview`` (when *repo_name* is given) always opens
+ the tour; infrastructure pages close it.
+ """
+ documented = set(file_page_paths)
+ infra = set(infra_paths)
+ adjacency: dict[str, list[str]] = defaultdict(list)
+ for src, dst in import_edges:
+ if src.startswith("external:") or dst.startswith("external:"):
+ continue
+ adjacency[src].append(dst)
+
+ # Seeds = the genuine entry points (the ``is_entry_point`` flag or an
+ # entry-style filename, both worth +3), restricted to documented files. A
+ # mere +1 for being shallow or high-PageRank does NOT make a file a seed —
+ # otherwise every root file would seed the walk and flatten all depths.
+ scored = score_entry_points(parsed_files, pagerank)
+ seeds = [path for s, path in scored if s >= 3.0 and path in documented]
+ if not seeds:
+ # Fall back to the single highest-scored documented file so the walk
+ # still has an anchor on repos with no obvious entry point.
+ seeds = [path for _, path in scored if path in documented][:1]
+ depths = _bfs_depths(seeds, adjacency, documented)
+
+ # Documented files never reached from a seed still belong in the tour;
+ # park them after the deepest reached file, ranked by PageRank.
+ max_reached = max(depths.values(), default=-1)
+ for path in documented:
+ if path not in depths:
+ depths[path] = max_reached + 1
+
+ pr_score = score_entry_points(parsed_files, pagerank)
+ ep_score = {path: s for s, path in pr_score}
+
+ def code_sort_key(path: str) -> tuple[int, float, str]:
+ # Shallower (closer to an entry point) first; within a depth, higher
+ # entry-point score then PageRank; path for determinism.
+ return (
+ depths[path],
+ -(ep_score.get(path, 0.0) * 100 + pagerank.get(path, 0.0)),
+ path,
+ )
+
+ code_order = sorted(documented, key=code_sort_key)
+
+ stops: list[TourStop] = []
+ order = 0
+
+ if repo_name:
+ order += 1
+ stops.append(
+ TourStop(
+ order=order,
+ target_path=repo_name,
+ page_type="repo_overview",
+ title="Repository Overview",
+ depth=0,
+ kind="overview",
+ reason="Start here for the end-to-end picture before diving into the code.",
+ )
+ )
+
+ # Reserve a couple of stops for infrastructure at the end when present.
+ infra_budget = min(2, len(infra), max(0, max_stops - len(stops) - 1))
+ code_budget = max(0, max_stops - len(stops) - infra_budget)
+
+ for path in code_order[:code_budget]:
+ order += 1
+ d = depths[path]
+ if d <= 0:
+ reason = "An entry point — execution and imports fan out from here."
+ elif d == 1:
+ reason = "Directly used by the entry points above; a core collaborator."
+ else:
+ reason = f"Reached {d} imports deep — a supporting building block."
+ stops.append(
+ TourStop(
+ order=order,
+ target_path=path,
+ page_type="file_page",
+ title=PurePosixPath(path).name,
+ depth=d,
+ kind="code",
+ reason=reason,
+ )
+ )
+
+ # Weave infrastructure in last: how the system is packaged and deployed.
+ infra_ranked = sorted(infra, key=lambda p: (-pagerank.get(p, 0.0), p))
+ deepest = max((s.depth for s in stops), default=0) + 1
+ for path in infra_ranked[:infra_budget]:
+ order += 1
+ stops.append(
+ TourStop(
+ order=order,
+ target_path=path,
+ page_type="infra_page",
+ title=PurePosixPath(path).name,
+ depth=deepest,
+ kind="infra",
+ reason="How the system above is configured, built, or deployed.",
+ )
+ )
+
+ return stops
diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.py
index 3a9a04472..9fa22d21b 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py
@@ -14,6 +14,10 @@ from repowise.core.persistence.crud import (
get_kg_layers as _get_kg_layers,
get_kg_tour_steps as _get_kg_tour_steps,
)
+from repowise.core.generation.onboarding.slots import (
+ ONBOARDING_ORDER,
+ PROMOTED_SLOTS,
+)
from repowise.core.persistence.database import get_session
from repowise.core.persistence.models import (
GitMetadata,
@@ -414,6 +418,40 @@ async def get_overview(repo: str | None = None) -> dict:
architecture["tour_available"] = bool(kg_tour)
architecture["tour_step_count"] = len(kg_tour)
+ # E. Reading order — the canonical onboarding spine, mirrored for agents
+ # so they can walk the wiki in the same order a human would (§ dual
+ # audience). Only slots that actually produced a page are listed.
+ ro_result = await session.execute(
+ select(Page).where(
+ Page.repository_id == repository.id,
+ Page.page_type.in_(
+ ["onboarding", *PROMOTED_SLOTS.keys()]
+ ),
+ )
+ )
+ slot_to_page: dict[str, Page] = {}
+ for p in ro_result.scalars().all():
+ if p.page_type == "onboarding":
+ slot = (p.target_path or "").rsplit("/", 1)[-1]
+ else:
+ slot = PROMOTED_SLOTS.get(p.page_type, "")
+ if slot and slot not in slot_to_page:
+ slot_to_page[slot] = p
+ reading_order: list[dict[str, Any]] = []
+ for slot in ONBOARDING_ORDER:
+ p = slot_to_page.get(slot)
+ if p is None:
+ continue
+ reading_order.append(
+ {
+ "order": len(reading_order) + 1,
+ "slot": slot,
+ "title": p.title,
+ "page_id": p.id,
+ "target_path": p.target_path,
+ }
+ )
+
# Older indexes persisted titles like "Repository Overview: repo" because
# repo_name was not passed through to generate_repo_overview. Substitute
# the actual repo name back in so the response is useful without reindex.
@@ -474,6 +512,48 @@ async def get_overview(repo: str | None = None) -> dict:
if architecture:
result["architecture"] = architecture
+ if reading_order:
+ result["reading_order"] = reading_order
+ result["reading_order_hint"] = (
+ "Canonical onboarding sequence — read these page_ids in order "
+ "via get_context/get_symbol to understand the repo the way a "
+ "new contributor would."
+ )
+
+ # Topology-driven guided tour — the ordered, page-by-page walk derived
+ # from the import graph (entry points first, then inward, infra last).
+ # Persisted on the repo_overview page metadata at generation time.
+ if overview_page:
+ from repowise.core.generation.models import compute_page_id
+
+ try:
+ ov_meta = json.loads(overview_page.metadata_json or "{}")
+ except (json.JSONDecodeError, TypeError):
+ ov_meta = {}
+ tour = ov_meta.get("guided_tour") or []
+ if tour:
+ result["guided_tour"] = [
+ {
+ "order": s.get("order"),
+ "title": s.get("title"),
+ "kind": s.get("kind"),
+ "reason": s.get("reason"),
+ "target_path": s.get("target_path"),
+ "page_id": compute_page_id(
+ s.get("page_type", "file_page"), s.get("target_path", "")
+ ),
+ }
+ for s in tour
+ ]
+ result["guided_tour_hint"] = (
+ "Topology-ordered walk of the codebase: read these page_ids "
+ "in order — entry points first, then the files they import, "
+ "with infrastructure last. Each step builds on the previous."
+ )
+ layer_order = ov_meta.get("layer_order") or []
+ if layer_order:
+ result.setdefault("architecture", {})["layer_order"] = layer_order
+
# Append workspace context footer when in workspace mode
ws_footer = _build_workspace_footer()
if ws_footer:
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 1e3180eb3..ec29db4d8 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -29,6 +29,8 @@
"./decisions": "./src/decisions/index.ts",
"./decisions/*": "./src/decisions/*.tsx",
"./docs": "./src/docs/index.ts",
+ "./docs/doc-nav": "./src/docs/doc-nav.ts",
+ "./docs/reader-persona": "./src/docs/reader-persona.ts",
"./docs/*": "./src/docs/*.tsx",
"./symbols": "./src/symbols/index.ts",
"./symbols/*": "./src/symbols/*.tsx",
diff --git a/packages/ui/src/docs/command-palette.tsx b/packages/ui/src/docs/command-palette.tsx
new file mode 100644
index 000000000..9ed32ca2c
--- /dev/null
+++ b/packages/ui/src/docs/command-palette.tsx
@@ -0,0 +1,270 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Search, CornerDownLeft } from "lucide-react";
+import { cn } from "../lib/cn";
+import { getPageTypeIcon, getPageTypeLabel } from "../lib/page-types";
+import { useDebounce } from "../hooks/use-debounce";
+import type { DocPage } from "@repowise-dev/types/docs";
+
+interface CommandPaletteProps {
+ pages: DocPage[];
+ onSelect: (page: DocPage) => void;
+ /** Controlled open state. Omit for self-managed (⌘K only). */
+ open?: boolean;
+ onOpenChange?: (open: boolean) => void;
+ /**
+ * Optional server-backed search (semantic / full-text). When provided, its
+ * results are merged in *after* strong local title/path matches, so the
+ * palette stays instant while also surfacing meaning-based hits that the
+ * client-side substring filter can't find. Should resolve to `DocPage`s
+ * (the caller maps the search endpoint's hits back to loaded pages).
+ */
+ searchFn?: (query: string) => Promise<DocPage[]>;
+}
+
+interface Hit {
+ page: DocPage;
+ /** Lower is better. */
+ rank: number;
+ /** Short context snippet when the match was in the body. */
+ snippet?: string;
+}
+
+// Title hit ranks above path hit ranks above body hit. A leading match
+// (startsWith) beats a contained match within the same tier.
+function score(page: DocPage, q: string): Hit | null {
+ const title = page.title.toLowerCase();
+ const path = (page.target_path || "").toLowerCase();
+ if (title.startsWith(q)) return { page, rank: 0 };
+ if (title.includes(q)) return { page, rank: 1 };
+ if (path.includes(q)) return { page, rank: 2 };
+ const body = page.content.toLowerCase();
+ const at = body.includes(q) ? body.indexOf(q) : -1;
+ if (at !== -1) {
+ const start = Math.max(0, at - 40);
+ const raw = page.content.slice(start, at + q.length + 40).replace(/\s+/g, " ").trim();
+ return { page, rank: 3, snippet: (start > 0 ? "…" : "") + raw + "…" };
+ }
+ return null;
+}
+
+/**
+ * ⌘K / Ctrl-K full-text command palette over the already-loaded page list.
+ * Searches title, path, and body — no extra request, since the page content
+ * is in the list response. (Semantic search is a separate backend feature.)
+ */
+export function DocsCommandPalette({
+ pages,
+ onSelect,
+ open: controlledOpen,
+ onOpenChange,
+ searchFn,
+}: CommandPaletteProps) {
+ const [internalOpen, setInternalOpen] = useState(false);
+ const isControlled = controlledOpen !== undefined;
+ const open = isControlled ? controlledOpen : internalOpen;
+ const setOpen = (next: boolean | ((o: boolean) => boolean)) => {
+ const value = typeof next === "function" ? next(open) : next;
+ if (isControlled) onOpenChange?.(value);
+ else setInternalOpen(value);
+ };
+ const [query, setQuery] = useState("");
+ const [active, setActive] = useState(0);
+ const inputRef = useRef<HTMLInputElement>(null);
+ const debounced = useDebounce(query, 120);
+
+ // Global ⌘K / Ctrl-K toggle.
+ useEffect(() => {
+ function onKey(e: KeyboardEvent) {
+ if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
+ e.preventDefault();
+ setOpen((o) => !o);
+ } else if (e.key === "Escape") {
+ setOpen(false);
+ }
+ }
+ window.addEventListener("keydown", onKey);
+ return () => window.removeEventListener("keydown", onKey);
+ }, []);
+
+ useEffect(() => {
+ if (open) {
+ setActive(0);
+ // Focus after the panel mounts.
+ requestAnimationFrame(() => inputRef.current?.focus());
+ } else {
+ setQuery("");
+ }
+ }, [open]);
+
+ const clientHits = useMemo<Hit[]>(() => {
+ const q = debounced.trim().toLowerCase();
+ if (q.length < 2) return [];
+ const out: Hit[] = [];
+ for (const page of pages) {
+ const hit = score(page, q);
+ if (hit) out.push(hit);
+ }
+ out.sort((a, b) => a.rank - b.rank || a.page.title.localeCompare(b.page.title));
+ return out;
+ }, [debounced, pages]);
+
+ // Server-backed (semantic / full-text) results, fetched only when a
+ // searchFn is supplied. Failures fall back silently to the client layer.
+ const [serverPages, setServerPages] = useState<DocPage[]>([]);
+ useEffect(() => {
+ const q = debounced.trim();
+ if (!searchFn || q.length < 2) {
+ setServerPages([]);
+ return;
+ }
+ let cancelled = false;
+ searchFn(q)
+ .then((r) => {
+ if (!cancelled) setServerPages(r);
+ })
+ .catch(() => {
+ if (!cancelled) setServerPages([]);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [debounced, searchFn]);
+
+ // Strong local matches (title/path) lead for instant feel; server hits
+ // (which can match by meaning or body across all pages) fill in after,
+ // then the remaining weaker local body matches. Deduped by page id.
+ const hits = useMemo<Hit[]>(() => {
+ if (!searchFn) return clientHits.slice(0, 40);
+ const seen = new Set<string>();
+ const merged: Hit[] = [];
+ for (const h of clientHits) {
+ if (h.rank <= 2) {
+ merged.push(h);
+ seen.add(h.page.id);
+ }
+ }
+ for (const p of serverPages) {
+ if (!seen.has(p.id)) {
+ merged.push({ page: p, rank: 3 });
+ seen.add(p.id);
+ }
+ }
+ for (const h of clientHits) {
+ if (!seen.has(h.page.id)) {
+ merged.push(h);
+ seen.add(h.page.id);
+ }
+ }
+ return merged.slice(0, 40);
+ }, [clientHits, serverPages, searchFn]);
+
+ useEffect(() => {
+ if (active >= hits.length) setActive(0);
+ }, [hits, active]);
+
+ if (!open) return null;
+
+ function choose(page: DocPage) {
+ onSelect(page);
+ setOpen(false);
+ }
+
+ function onInputKey(e: React.KeyboardEvent) {
+ if (e.key === "ArrowDown") {
+ e.preventDefault();
+ setActive((a) => Math.min(a + 1, hits.length - 1));
+ } else if (e.key === "ArrowUp") {
+ e.preventDefault();
+ setActive((a) => Math.max(a - 1, 0));
+ } else if (e.key === "Enter") {
+ e.preventDefault();
+ const hit = hits[active];
+ if (hit) choose(hit.page);
+ }
+ }
+
+ return (
+ <div
+ className="fixed inset-0 z-50 flex items-start justify-center bg-black/50 px-4 pt-[12vh] backdrop-blur-sm"
+ onClick={() => setOpen(false)}
+ >
+ <div
+ className="w-full max-w-xl overflow-hidden rounded-xl border border-[var(--color-border-default)] bg-[var(--color-bg-surface)] shadow-2xl"
+ onClick={(e) => e.stopPropagation()}
+ >
+ {/* Input */}
+ <div className="flex items-center gap-2 border-b border-[var(--color-border-default)] px-3 py-2.5">
+ <Search className="h-4 w-4 shrink-0 text-[var(--color-text-tertiary)]" />
+ <input
+ ref={inputRef}
+ value={query}
+ onChange={(e) => setQuery(e.target.value)}
+ onKeyDown={onInputKey}
+ placeholder="Search pages by title, path, or content…"
+ className="flex-1 bg-transparent text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-tertiary)] outline-none"
+ />
+ <kbd className="rounded border border-[var(--color-border-default)] px-1.5 py-0.5 text-[10px] text-[var(--color-text-tertiary)]">
+ esc
+ </kbd>
+ </div>
+
+ {/* Results */}
+ <div className="max-h-[50vh] overflow-y-auto p-1.5">
+ {debounced.trim().length < 2 ? (
+ <p className="px-3 py-6 text-center text-xs text-[var(--color-text-tertiary)]">
+ Type to search {pages.length} pages
+ </p>
+ ) : hits.length === 0 ? (
+ <p className="px-3 py-6 text-center text-xs text-[var(--color-text-tertiary)]">
+ No pages match “{debounced.trim()}”
+ </p>
+ ) : (
+ hits.map((hit, i) => {
+ const Icon = getPageTypeIcon(hit.page.page_type);
+ return (
+ <button
+ key={hit.page.id}
+ onMouseEnter={() => setActive(i)}
+ onClick={() => choose(hit.page)}
+ className={cn(
+ "flex w-full items-start gap-2.5 rounded-md px-3 py-2 text-left transition-colors",
+ i === active
+ ? "bg-[var(--color-accent-muted)]"
+ : "hover:bg-[var(--color-bg-elevated)]",
+ )}
+ >
+ <Icon className="mt-0.5 h-3.5 w-3.5 shrink-0 text-[var(--color-text-tertiary)]" />
+ <span className="min-w-0 flex-1">
+ <span className="flex items-center gap-2">
+ <span className="truncate text-sm text-[var(--color-text-primary)]">
+ {hit.page.title}
+ </span>
+ <span className="shrink-0 text-[10px] uppercase tracking-wider text-[var(--color-text-tertiary)]">
+ {getPageTypeLabel(hit.page.page_type)}
+ </span>
+ </span>
+ {hit.page.target_path && (
+ <span className="block truncate font-mono text-[11px] text-[var(--color-text-tertiary)]">
+ {hit.page.target_path}
+ </span>
+ )}
+ {hit.snippet && (
+ <span className="mt-0.5 block truncate text-[11px] text-[var(--color-text-secondary)]">
+ {hit.snippet}
+ </span>
+ )}
+ </span>
+ {i === active && (
+ <CornerDownLeft className="mt-0.5 h-3 w-3 shrink-0 text-[var(--color-text-tertiary)]" />
+ )}
+ </button>
+ );
+ })
+ )}
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/packages/ui/src/docs/doc-nav.ts b/packages/ui/src/docs/doc-nav.ts
new file mode 100644
index 000000000..0a71160ad
--- /dev/null
+++ b/packages/ui/src/docs/doc-nav.ts
@@ -0,0 +1,94 @@
+// Framework-neutral navigation helpers for the wiki reader.
+//
+// These derive a hierarchical breadcrumb trail (repo / module / file) and
+// sibling prev/next links from the flat page list the API already returns —
+// no extra endpoint needed. The host app turns the returned ``pageId`` values
+// into hrefs (route shape differs between the CLI web app and hosted frontend).
+
+import type { DocPage } from "@repowise-dev/types/docs";
+
+export interface DocNavSegment {
+ label: string;
+ /** Present when this segment maps to a real page that can be linked. */
+ pageId?: string;
+}
+
+export interface DocSiblingLink {
+ pageId: string;
+ title: string;
+}
+
+export interface DocNavInfo {
+ /** repo root is added by the caller; these are page-relative segments. */
+ breadcrumbs: DocNavSegment[];
+ prev?: DocSiblingLink;
+ next?: DocSiblingLink;
+}
+
+function parentDir(path: string): string {
+ const i = path.lastIndexOf("/");
+ return i === -1 ? "" : path.slice(0, i);
+}
+
+/**
+ * Derive breadcrumbs + sibling prev/next for ``page`` given the full page
+ * list. Breadcrumb ancestors link to their ``module_page`` when one exists,
+ * so readers can zoom out a level at a time.
+ */
+export function computeDocNav(page: DocPage, pages: DocPage[]): DocNavInfo {
+ // Special / synthetic pages (overview, onboarding, architecture) have no
+ // meaningful filesystem path — show a single label, no siblings.
+ if (!page.target_path) {
+ return { breadcrumbs: [{ label: page.title }] };
+ }
+
+ // Index module pages by the directory they represent so an ancestor
+ // directory segment can deep-link to its module overview.
+ const moduleByPath = new Map<string, DocPage>();
+ for (const p of pages) {
+ if (p.page_type === "module_page" && p.target_path) {
+ moduleByPath.set(p.target_path, p);
+ }
+ }
+
+ const parts = page.target_path.split("/").filter(Boolean);
+ const breadcrumbs: DocNavSegment[] = [];
+ for (let i = 0; i < parts.length; i++) {
+ const segPath = parts.slice(0, i + 1).join("/");
+ const isLeaf = i === parts.length - 1;
+ const mod = moduleByPath.get(segPath);
+ breadcrumbs.push({
+ label: parts[i] ?? segPath,
+ // The leaf is the current page; ancestors link to their module page
+ // when we have one.
+ ...(isLeaf
+ ? { pageId: page.id }
+ : mod
+ ? { pageId: mod.id }
+ : {}),
+ });
+ }
+
+ // Sibling prev/next: pages of the same type sharing the immediate parent
+ // directory, ordered by path. Keeps "next" within a coherent group rather
+ // than jumping across unrelated page types.
+ const dir = parentDir(page.target_path);
+ const siblings = pages
+ .filter(
+ (p) =>
+ p.page_type === page.page_type &&
+ p.target_path &&
+ parentDir(p.target_path) === dir,
+ )
+ .sort((a, b) => a.target_path.localeCompare(b.target_path));
+
+ const idx = siblings.findIndex((p) => p.id === page.id);
+ const result: DocNavInfo = { breadcrumbs };
+ if (idx !== -1) {
+ const prev = siblings[idx - 1];
+ const next = siblings[idx + 1];
+ if (prev) result.prev = { pageId: prev.id, title: prev.title };
+ if (next) result.next = { pageId: next.id, title: next.title };
+ }
+ return result;
+}
diff --git a/packages/ui/src/docs/docs-tree.tsx b/packages/ui/src/docs/docs-tree.tsx
index 081a60976..608490206 100644
--- a/packages/ui/src/docs/docs-tree.tsx
+++ b/packages/ui/src/docs/docs-tree.tsx
@@ -9,6 +9,11 @@ import {
Folder,
Search,
Filter,
+ FolderTree,
+ Network,
+ Layers,
+ BookOpen,
+ FileText,
} from "lucide-react";
import {
ALL_PAGE_TYPES,
@@ -236,6 +241,226 @@ function buildTree(pages: DocPage[]): TreeNode[] {
return root;
}
+// ---------------------------------------------------------------------------
+// Domain (semantic) tree
+// ---------------------------------------------------------------------------
+//
+// A narrative spine grouped by *meaning* rather than folder structure:
+//
+// Guided Tour → onboarding slots in canonical reading order
+// Architecture → layer / knowledge-graph / SCC pages (the zoom-out)
+// Modules → each module_page with its files nested underneath
+// Reference → loose files, symbols, API contracts, infra
+//
+// Section keys are namespaced with "@section:" so they never collide with a
+// real target_path and get their own icon in TreeItem.
+
+const SECTION_KEYS = {
+ tour: "@section:tour",
+ architecture: "@section:architecture",
+ modules: "@section:modules",
+ reference: "@section:reference",
+} as const;
+
+export const DOMAIN_SECTION_KEYS = Object.values(SECTION_KEYS);
+
+function parentDirOf(path: string): string {
+ const i = path.lastIndexOf("/");
+ return i === -1 ? "" : path.slice(0, i);
+}
+
+// Layers ordered top→bottom by dependency direction, persisted on the repo
+// overview page at generation time. Used to order the Architecture section and
+// the Modules section so the tree reads as a dependency hierarchy rather than
+// alphabetically. Returns a rank lookup (lower = closer to the top).
+function layerRankLookup(pages: DocPage[]): (layer: string) => number {
+ const overview = pages.find((p) => p.page_type === "repo_overview");
+ const raw = overview?.metadata?.["layer_order"];
+ const order = Array.isArray(raw) ? (raw.filter((x) => typeof x === "string") as string[]) : [];
+ const index = new Map(order.map((name, i) => [name, i]));
+ return (layer: string) => index.get(layer) ?? Number.MAX_SAFE_INTEGER;
+}
+
+// The layer a module belongs to = the most common layer_name across its files.
+function dominantLayer(files: DocPage[]): string {
+ const counts = new Map<string, number>();
+ for (const f of files) {
+ const layer = f.metadata?.["layer_name"];
+ if (typeof layer === "string" && layer) {
+ counts.set(layer, (counts.get(layer) ?? 0) + 1);
+ }
+ }
+ let best = "";
+ let bestN = 0;
+ for (const [layer, n] of counts) {
+ if (n > bestN) {
+ best = layer;
+ bestN = n;
+ }
+ }
+ return best;
+}
+
+function buildDomainTree(pages: DocPage[]): TreeNode[] {
+ const sections: TreeNode[] = [];
+ const rankOf = layerRankLookup(pages);
+
+ // ---- Guided Tour (reuse the canonical onboarding ordering) ----
+ const onboarding = buildOnboardingFolder(pages);
+ const tourIds = new Set<string>();
+ const tourChildren: TreeNode[] = onboarding ? [...onboarding.children] : [];
+ for (const c of tourChildren) if (c.page) tourIds.add(c.page.id);
+
+ // Guarantee the repo overview heads the tour even when it wasn't promoted
+ // into an onboarding slot — it's the canonical front door.
+ const overview = pages.find((p) => p.page_type === "repo_overview");
+ if (overview && !tourIds.has(overview.id)) {
+ tourChildren.unshift({
+ name: overview.title || "Overview",
+ path: overview.id,
+ isDir: false,
+ page: overview,
+ children: [],
+ });
+ tourIds.add(overview.id);
+ }
+
+ if (tourChildren.length > 0) {
+ sections.push({
+ name: "Guided Tour",
+ path: SECTION_KEYS.tour,
+ isDir: true,
+ children: tourChildren,
+ });
+ }
+
+ // ---- Architecture (layers / knowledge graph / strongly-connected) ----
+ const archTypes = new Set(["layer_page", "architecture_diagram", "scc_page"]);
+ const archChildren: TreeNode[] = pages
+ .filter((p) => archTypes.has(p.page_type) && !tourIds.has(p.id))
+ // Order layer pages top→bottom by dependency direction; other arch pages
+ // (knowledge graph, SCCs) fall after, alphabetically.
+ .sort((a, b) => {
+ const ra = a.page_type === "layer_page" ? rankOf(a.title.replace(/^Layer:\s*/, "")) : Number.MAX_SAFE_INTEGER;
+ const rb = b.page_type === "layer_page" ? rankOf(b.title.replace(/^Layer:\s*/, "")) : Number.MAX_SAFE_INTEGER;
+ return ra - rb || a.title.localeCompare(b.title);
+ })
+ .map((p) => ({ name: p.title, path: p.id, isDir: false, page: p, children: [] }));
+ if (archChildren.length > 0) {
+ sections.push({
+ name: "Architecture",
+ path: SECTION_KEYS.architecture,
+ isDir: true,
+ children: archChildren,
+ });
+ }
+
+ // ---- Modules (each module_page with the files it contains) ----
+ const modulePages = pages
+ .filter((p) => p.page_type === "module_page" && p.target_path)
+ .sort((a, b) => a.target_path.localeCompare(b.target_path));
+ const modulePaths = new Set(modulePages.map((p) => p.target_path));
+ const claimedFileIds = new Set<string>();
+
+ const moduleChildren: TreeNode[] = modulePages.map((mod) => {
+ const files = pages
+ .filter(
+ (p) =>
+ p.page_type === "file_page" &&
+ p.target_path &&
+ parentDirOf(p.target_path) === mod.target_path,
+ )
+ .sort((a, b) => a.target_path.localeCompare(b.target_path));
+ for (const f of files) claimedFileIds.add(f.id);
+ return {
+ name: mod.title || mod.target_path.split("/").pop() || mod.target_path,
+ path: mod.id,
+ isDir: true,
+ page: mod,
+ children: files.map((f) => ({
+ name: f.target_path.split("/").pop() || f.target_path,
+ path: f.id,
+ isDir: false,
+ page: f,
+ children: [],
+ })),
+ };
+ });
+ // Order modules top→bottom by the dependency layer of their files, so the
+ // module list mirrors the architecture spine instead of sorting by path.
+ moduleChildren.sort((a, b) => {
+ const la = dominantLayer(a.children.map((c) => c.page).filter(Boolean) as DocPage[]);
+ const lb = dominantLayer(b.children.map((c) => c.page).filter(Boolean) as DocPage[]);
+ return rankOf(la) - rankOf(lb) || a.name.localeCompare(b.name);
+ });
+ if (moduleChildren.length > 0) {
+ sections.push({
+ name: "Modules",
+ path: SECTION_KEYS.modules,
+ isDir: true,
+ children: moduleChildren,
+ });
+ }
+
+ // ---- Reference (everything not already surfaced above) ----
+ const surfacedTypes = new Set([
+ "module_page",
+ "repo_overview",
+ ...archTypes,
+ ]);
+ const refChildren: TreeNode[] = pages
+ .filter(
+ (p) =>
+ !tourIds.has(p.id) &&
+ !claimedFileIds.has(p.id) &&
+ !surfacedTypes.has(p.page_type) &&
+ // module-claimed dirs are not pages themselves; skip module dirs
+ !modulePaths.has(p.target_path),
+ )
+ .sort((a, b) => (a.target_path || a.title).localeCompare(b.target_path || b.title))
+ .map((p) => ({
+ name: p.target_path ? p.target_path.split("/").pop() || p.target_path : p.title,
+ path: p.id,
+ isDir: false,
+ page: p,
+ children: [],
+ }));
+ if (refChildren.length > 0) {
+ sections.push({
+ name: "Reference",
+ path: SECTION_KEYS.reference,
+ isDir: true,
+ children: refChildren,
+ });
+ }
+
+ return sections;
+}
+
+// Ordinal shown next to each domain section so the spine reads as a numbered
+// 1 → 4 reading order (Guided Tour → Architecture → Modules → Reference).
+const SECTION_NUMBER: Record<string, number> = {
+ [SECTION_KEYS.tour]: 1,
+ [SECTION_KEYS.architecture]: 2,
+ [SECTION_KEYS.modules]: 3,
+ [SECTION_KEYS.reference]: 4,
+};
+
+function sectionIcon(path: string) {
+ switch (path) {
+ case SECTION_KEYS.tour:
+ return Compass;
+ case SECTION_KEYS.architecture:
+ return Layers;
+ case SECTION_KEYS.modules:
+ return Network;
+ case SECTION_KEYS.reference:
+ return FileText;
+ default:
+ return BookOpen;
+ }
+}
+
// ---------------------------------------------------------------------------
// Filter helpers
// ---------------------------------------------------------------------------
@@ -335,7 +560,22 @@ function TreeItem({
) : (
<span className="w-3 shrink-0" />
)}
- {node.path === ONBOARDING_DIR_KEY ? (
+ {node.path.startsWith("@section:") ? (
+ (() => {
+ const SectionIcon = sectionIcon(node.path);
+ const num = SECTION_NUMBER[node.path];
+ return (
+ <>
+ {num != null && (
+ <span className="shrink-0 font-mono text-[10px] text-[var(--color-text-tertiary)] tabular-nums">
+ {num}
+ </span>
+ )}
+ <SectionIcon className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)]" />
+ </>
+ );
+ })()
+ ) : node.path === ONBOARDING_DIR_KEY ? (
<Compass className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)]" />
) : isExpanded ? (
<FolderOpen className="h-3.5 w-3.5 shrink-0 text-[var(--color-accent-primary)] opacity-70" />
@@ -345,7 +585,10 @@ function TreeItem({
<span
className={cn(
"truncate font-medium",
- node.path === ONBOARDING_DIR_KEY && "text-[var(--color-text-primary)]",
+ (node.path === ONBOARDING_DIR_KEY || node.path.startsWith("@section:")) &&
+ "text-[var(--color-text-primary)]",
+ node.path.startsWith("@section:") &&
+ "text-[11px] uppercase tracking-wider",
)}
>
{node.name}
@@ -415,13 +658,19 @@ function FreshnessDot({ status }: { status: FreshnessStatus }) {
// Main DocsTree component
// ---------------------------------------------------------------------------
+type ViewMode = "domain" | "folder";
+
export function DocsTree({ pages, selectedPageId, onSelectPage, className }: DocsTreeProps) {
const [search, setSearch] = useState("");
const [typeFilter, setTypeFilter] = useState<TypeFilter>("all");
const [freshnessFilter, setFreshnessFilter] = useState<FreshnessFilter>("all");
+ // Default to the semantic "By domain" spine — overview/architecture/modules
+ // first, filesystem second. The folder view is a toggle for power users.
+ const [viewMode, setViewMode] = useState<ViewMode>("domain");
const [expandedDirs, setExpandedDirs] = useState<Set<string>>(() => {
- // Auto-expand first two levels, plus the Onboarding folder if present.
- const dirs = new Set<string>();
+ // Auto-expand first two levels, the Onboarding folder, and every domain
+ // section so both views open in a useful state.
+ const dirs = new Set<string>(DOMAIN_SECTION_KEYS);
dirs.add(ONBOARDING_DIR_KEY);
for (const page of pages) {
const parts = page.target_path.split("/");
@@ -431,7 +680,10 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: Doc
});
const [showFilters, setShowFilters] = useState(true);
- const tree = useMemo(() => buildTree(pages), [pages]);
+ const tree = useMemo(
+ () => (viewMode === "domain" ? buildDomainTree(pages) : buildTree(pages)),
+ [pages, viewMode],
+ );
const filteredTree = useMemo(
() => filterTree(tree, search, typeFilter, freshnessFilter),
[tree, search, typeFilter, freshnessFilter],
@@ -454,6 +706,27 @@ export function DocsTree({ pages, selectedPageId, onSelectPage, className }: Doc
<div className={cn("flex flex-col h-full", className)}>
{/* Search + filter bar */}
<div className="p-3 space-y-2 border-b border-[var(--color-border-default)]">
+ {/* View mode: semantic spine vs. raw filesystem */}
+ <div className="flex items-center gap-1 rounded-md bg-[var(--color-bg-elevated)] p-0.5">
+ {([
+ { mode: "domain" as const, label: "By domain", Icon: Network },
+ { mode: "folder" as const, label: "By folder", Icon: FolderTree },
+ ]).map(({ mode, label, Icon }) => (
+ <button
+ key={mode}
+ onClick={() => setViewMode(mode)}
+ className={cn(
+ "flex flex-1 items-center justify-center gap-1.5 rounded px-2 py-1 text-[11px] font-medium transition-colors",
+ viewMode === mode
+ ? "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 w-3" />
+ {label}
+ </button>
+ ))}
+ </div>
<div className="flex items-center gap-2">
<div className="flex-1 flex items-center gap-1.5 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2 py-1.5">
<Search className="h-3.5 w-3.5 text-[var(--color-text-tertiary)] shrink-0" />
diff --git a/packages/ui/src/docs/index.ts b/packages/ui/src/docs/index.ts
index 2629c199c..5423c7b35 100644
--- a/packages/ui/src/docs/index.ts
+++ b/packages/ui/src/docs/index.ts
@@ -1 +1,4 @@
export * from "./docs-tree.js";
+export * from "./doc-nav.js";
+export * from "./command-palette.js";
+export * from "./reader-persona.js";
diff --git a/packages/ui/src/docs/reader-persona.ts b/packages/ui/src/docs/reader-persona.ts
new file mode 100644
index 000000000..34e34e8e0
--- /dev/null
+++ b/packages/ui/src/docs/reader-persona.ts
@@ -0,0 +1,99 @@
+// Reader personas — a client-side lens that filters which sections of a
+// generated page render, so the same rich page serves three audiences without
+// regenerating anything:
+//
+// overview — non-technical / first look: prose + diagrams only. Hides
+// symbol dumps, call graphs, dependency lists, raw metrics.
+// contributor — the default: everything except the rawest reference dumps.
+// deep — everything, including call graphs, metrics, dead code.
+//
+// Filtering is done by splitting the markdown on `## ` (H2) section headings
+// and dropping sections whose heading matches the persona's hide-list. Content
+// before the first H2 (the title + lead paragraph) is always kept.
+
+export type ReaderPersona = "overview" | "contributor" | "deep";
+
+export const READER_PERSONAS: { value: ReaderPersona; label: string; hint: string }[] = [
+ { value: "overview", label: "Overview", hint: "Prose & diagrams only" },
+ { value: "contributor", label: "Contributor", hint: "Balanced (default)" },
+ { value: "deep", label: "Deep", hint: "Everything" },
+];
+
+export const DEFAULT_PERSONA: ReaderPersona = "contributor";
+
+export function isReaderPersona(value: string | null | undefined): value is ReaderPersona {
+ return value === "overview" || value === "contributor" || value === "deep";
+}
+
+// Heading keywords (lowercased, matched as a prefix of the heading text) that
+// each persona hides. Matching is intentionally generous so it works across
+// the file/module/layer page templates without an exhaustive list.
+const OVERVIEW_HIDE = [
+ "symbols",
+ "symbol",
+ "public api",
+ "imports",
+ "exports",
+ "dependencies",
+ "dependents",
+ "call graph",
+ "class hierarchy",
+ "community",
+ "neighbors",
+ "raw metrics",
+ "dead code",
+ "parse errors",
+ "source",
+ "source snippet",
+ "metrics",
+];
+
+// Contributor keeps almost everything; only the rawest machine-oriented dumps
+// are hidden so the page stays readable.
+const CONTRIBUTOR_HIDE = ["raw metrics", "parse errors", "source snippet"];
+
+const HIDE_BY_PERSONA: Record<ReaderPersona, string[]> = {
+ overview: OVERVIEW_HIDE,
+ contributor: CONTRIBUTOR_HIDE,
+ deep: [],
+};
+
+function headingHidden(headingText: string, hideList: string[]): boolean {
+ const h = headingText.trim().toLowerCase();
+ return hideList.some((kw) => h === kw || h.startsWith(kw));
+}
+
+/**
+ * Filter a markdown document to the sections visible for *persona*.
+ *
+ * Splits on top-level (`## `) headings. The preamble before the first H2 is
+ * always retained. Returns the original content unchanged for the `deep`
+ * persona (or when there is nothing to hide).
+ */
+export function filterMarkdownByPersona(content: string, persona: ReaderPersona): string {
+ const hideList = HIDE_BY_PERSONA[persona];
+ if (!hideList || hideList.length === 0) return content;
+
+ const lines = content.split("\n");
+ const out: string[] = [];
+ let hiding = false;
+ let inFence = false;
+
+ for (const line of lines) {
+ // Track fenced code blocks so a `##` inside code isn't treated as a heading.
+ if (/^\s*```/.test(line)) {
+ inFence = !inFence;
+ if (!hiding) out.push(line);
+ continue;
+ }
+ const h2 = !inFence ? /^##\s+(.+?)\s*$/.exec(line) : null;
+ if (h2) {
+ hiding = headingHidden(h2[1] ?? "", hideList);
+ if (!hiding) out.push(line);
+ continue;
+ }
+ if (!hiding) out.push(line);
+ }
+
+ return out.join("\n").trim();
+}
diff --git a/packages/ui/src/lib/page-types.ts b/packages/ui/src/lib/page-types.ts
index a6b461649..59b3cb421 100644
--- a/packages/ui/src/lib/page-types.ts
+++ b/packages/ui/src/lib/page-types.ts
@@ -9,6 +9,7 @@ import {
RefreshCw,
Server,
Compass,
+ Layers,
} from "lucide-react";
import type { DocPage } from "@repowise-dev/types/docs";
@@ -20,6 +21,7 @@ export interface PageTypeConfig {
export const PAGE_TYPE_CONFIG: Record<string, PageTypeConfig> = {
repo_overview: { label: "Overview", icon: Globe },
architecture_diagram: { label: "Knowledge Graph", icon: LayoutGrid },
+ layer_page: { label: "Layer", icon: Layers },
module_page: { label: "Module", icon: FolderOpen },
symbol_spotlight: { label: "Symbol", icon: Sparkles },
file_page: { label: "File", icon: FileText },
@@ -54,6 +56,7 @@ export function getPageTypeLabel(pageType: string): string {
export const ONBOARDING_ORDER = [
"project_overview",
"architecture_guide",
+ "guided_tour",
"getting_started",
"codebase_map",
"key_concepts",
@@ -67,6 +70,7 @@ export type OnboardingSlot = (typeof ONBOARDING_ORDER)[number];
export const ONBOARDING_SLOT_TITLES: Record<OnboardingSlot, string> = {
project_overview: "Project Overview",
architecture_guide: "Architecture Guide",
+ guided_tour: "Guided Tour",
getting_started: "Getting Started",
codebase_map: "Codebase Map",
key_concepts: "Key Concepts",
diff --git a/packages/ui/src/wiki/wiki-markdown.tsx b/packages/ui/src/wiki/wiki-markdown.tsx
index 8132f283c..317c91845 100644
--- a/packages/ui/src/wiki/wiki-markdown.tsx
+++ b/packages/ui/src/wiki/wiki-markdown.tsx
@@ -4,9 +4,27 @@ import ReactMarkdown from "react-markdown";
import remarkGfm from "remark-gfm";
import type { Components } from "react-markdown";
import { MermaidDiagram } from "./mermaid-diagram";
-import { useState, useEffect } from "react";
+import { useState, useEffect, useMemo } from "react";
import { Copy, Check } from "lucide-react";
import { cn } from "../lib/cn";
+import {
+ buildAnchorIndex,
+ type WikiLinkKind,
+ type WikiLinkRef,
+} from "./wiki-links-types";
+
+/**
+ * Resolves an inline backtick ref to an internal wiki page href, or null
+ * when the ref doesn't map to a known page (renders as a plain code span).
+ */
+type WikiLinkLookup = (anchor: string) => { href: string; kind: WikiLinkKind } | null;
+
+type WikiLinkComponent = React.ElementType<{
+ href: string;
+ className?: string;
+ title?: string;
+ children: React.ReactNode;
+}>;
function slugify(text: string): string {
return text
@@ -85,7 +103,12 @@ function ClientCodeBlock({ code, language }: { code: string; language: string })
);
}
-const components: Components = {
+function buildComponents(
+ resolveLink: WikiLinkLookup | null,
+ LinkComponent: WikiLinkComponent,
+): Components {
+ const Link = LinkComponent;
+ return {
h1: ({ children }) => {
const text = typeof children === "string" ? children : extractText(children);
const id = slugify(text);
@@ -145,6 +168,23 @@ const components: Components = {
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.
+ const text = typeof children === "string" ? children : extractText(children);
+ const resolved = resolveLink ? resolveLink(text.trim()) : null;
+ if (resolved) {
+ return (
+ <Link
+ href={resolved.href}
+ title={`Go to ${text.trim()}`}
+ className="rounded bg-[var(--color-accent-muted)] px-1.5 py-0.5 text-xs font-mono text-[var(--color-accent-primary)] underline decoration-dotted underline-offset-2 hover:bg-[var(--color-accent-primary)] hover:text-white transition-colors"
+ >
+ {children}
+ </Link>
+ );
+ }
+
return (
<code
className="rounded bg-[var(--color-bg-elevated)] px-1.5 py-0.5 text-xs font-mono text-[var(--color-accent-primary)]"
@@ -196,7 +236,8 @@ const components: Components = {
{children}
</strong>
),
-};
+ };
+}
function extractText(node: unknown): string {
if (typeof node === "string") return node;
@@ -210,9 +251,37 @@ function extractText(node: unknown): string {
interface WikiMarkdownProps {
content: string;
+ /**
+ * Resolved forward links for this page (``page.metadata.wiki_links``).
+ * When provided alongside ``buildHref``, inline backtick refs that match
+ * a link anchor render as clickable internal links.
+ */
+ wikiLinks?: WikiLinkRef[];
+ /** Maps a resolved ``{ pageId, kind }`` to an in-app href. */
+ buildHref?: (pageId: string, kind: WikiLinkKind) => string;
+ /** Router-aware link (e.g. Next.js ``Link``). Defaults to a plain ``<a>``. */
+ LinkComponent?: WikiLinkComponent;
}
-export function WikiMarkdown({ content }: WikiMarkdownProps) {
+export function WikiMarkdown({
+ content,
+ wikiLinks,
+ buildHref,
+ LinkComponent = "a",
+}: WikiMarkdownProps) {
+ const components = useMemo(() => {
+ let resolveLink: WikiLinkLookup | null = null;
+ if (wikiLinks && wikiLinks.length > 0 && buildHref) {
+ const index = buildAnchorIndex(wikiLinks);
+ resolveLink = (anchor) => {
+ const hit = index.get(anchor);
+ if (!hit) return null;
+ return { href: buildHref(hit.pageId, hit.kind), kind: hit.kind };
+ };
+ }
+ return buildComponents(resolveLink, LinkComponent);
+ }, [wikiLinks, buildHref, LinkComponent]);
+
return (
<ReactMarkdown remarkPlugins={[remarkGfm]} components={components}>
{content}
diff --git a/packages/web/src/app/repos/[id]/docs/page.tsx b/packages/web/src/app/repos/[id]/docs/page.tsx
index 247adb0d6..3c42d88b7 100644
--- a/packages/web/src/app/repos/[id]/docs/page.tsx
+++ b/packages/web/src/app/repos/[id]/docs/page.tsx
@@ -1,12 +1,15 @@
"use client";
-import { use, useMemo, useState } from "react";
+import { use, useCallback, useMemo, useState } from "react";
+import { useRouter, useSearchParams } from "next/navigation";
import useSWR from "swr";
-import { Download, FolderArchive, Loader2 } from "lucide-react";
+import { Download, FolderArchive, Loader2, Search } from "lucide-react";
import { Button } from "@repowise-dev/ui/ui/button";
import { FirstFiveFiles, type FirstFiveFile } from "@repowise-dev/ui/onboarding/first-five-files";
+import { DocsCommandPalette } from "@repowise-dev/ui/docs/command-palette";
import { DocsExplorer } from "@/components/docs/docs-explorer";
import { listAllPages, listPages } from "@/lib/api/pages";
+import { search as searchPages } from "@/lib/api/search";
import { getGraph } from "@/lib/api/graph";
import type { DocPage } from "@repowise-dev/types/docs";
import { downloadTextFile } from "@/lib/utils/download";
@@ -19,6 +22,18 @@ export default function DocsPage({
}) {
const { id: repoId } = use(params);
const [isExporting, setIsExporting] = useState(false);
+ const [searchOpen, setSearchOpen] = useState(false);
+ const router = useRouter();
+ const searchParams = useSearchParams();
+
+ const openPage = useCallback(
+ (pageId: string) => {
+ const next = new URLSearchParams(searchParams.toString());
+ next.set("page", pageId);
+ router.replace(`?${next.toString()}`, { scroll: false });
+ },
+ [router, searchParams],
+ );
const { data: graphData } = useSWR<GraphExportResponse>(
`graph:${repoId}`,
@@ -32,6 +47,20 @@ export default function DocsPage({
{ revalidateOnFocus: false },
);
+ // Server-backed search for the ⌘K palette: hit the semantic/full-text
+ // endpoint, then map results back to the loaded page objects so selection
+ // behaves identically to a client-side hit. Unknown ids (rare) are dropped.
+ const searchFn = useCallback(
+ async (q: string) => {
+ const results = await searchPages(q, { repo_id: repoId, limit: 30 });
+ const byId = new Map((docPages ?? []).map((p) => [p.id, p]));
+ return results
+ .map((r) => byId.get(r.page_id))
+ .filter((p): p is DocPage => p !== undefined);
+ },
+ [repoId, docPages],
+ );
+
const pageByPath = useMemo(() => {
const m = new Map<string, DocPage>();
for (const p of docPages ?? []) {
@@ -87,6 +116,16 @@ export default function DocsPage({
</p>
</div>
<div className="flex gap-2 shrink-0">
+ <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>
<Button
variant="outline"
size="sm"
@@ -111,14 +150,16 @@ export default function DocsPage({
{startHere.length > 0 && (
<div className="px-4 sm:px-6 pt-3">
- <details className="rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-surface)]">
- <summary className="cursor-pointer list-none px-4 py-2.5 text-sm font-medium text-[var(--color-text-primary)] flex items-center gap-2 hover:bg-[var(--color-bg-elevated)] transition-colors">
+ <div className="rounded-lg border border-[var(--color-border-accent)] bg-[var(--color-accent-muted)]/30">
+ <div className="flex items-center gap-2 px-4 pt-3 pb-1">
<span className="text-[var(--color-accent-primary)]">✨</span>
- Start here
+ <span className="text-sm font-medium text-[var(--color-text-primary)]">
+ Start here
+ </span>
<span className="text-[10px] font-normal text-[var(--color-text-tertiary)] uppercase tracking-wider">
- first {startHere.length} files to read
+ the first {startHere.length} files to read
</span>
- </summary>
+ </div>
<div className="px-3 pb-3 pt-1">
<FirstFiveFiles
files={startHere}
@@ -131,7 +172,7 @@ export default function DocsPage({
}}
/>
</div>
- </details>
+ </div>
</div>
)}
@@ -139,6 +180,15 @@ export default function DocsPage({
<div className="flex-1 min-h-0">
<DocsExplorer repoId={repoId} />
</div>
+
+ {/* ⌘K full-text command palette over loaded pages */}
+ <DocsCommandPalette
+ pages={docPages ?? []}
+ open={searchOpen}
+ onOpenChange={setSearchOpen}
+ onSelect={(p) => openPage(p.id)}
+ searchFn={searchFn}
+ />
</div>
);
}
diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsx
index bc7f998d6..322da8cf1 100644
--- a/packages/web/src/components/docs/docs-explorer.tsx
+++ b/packages/web/src/components/docs/docs-explorer.tsx
@@ -24,15 +24,16 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
const searchParams = useSearchParams();
const router = useRouter();
- // Restore selection from URL on mount / when pages load
+ // Keep the selected page in sync with the ?page= URL param. This fires on
+ // mount and whenever the param changes — including when an in-content wiki
+ // link or breadcrumb navigates via <Link href="?page=...">.
+ const pageParam = searchParams.get("page");
useEffect(() => {
- if (pages.length === 0) return;
- const pageId = searchParams.get("page");
- if (pageId && !selectedPage) {
- const match = pages.find((p) => p.id === pageId);
- if (match) setSelectedPage(match);
- }
- }, [pages, searchParams, selectedPage]);
+ if (pages.length === 0 || !pageParam) return;
+ if (selectedPage?.id === pageParam) return;
+ const match = pages.find((p) => p.id === pageParam);
+ if (match) setSelectedPage(match);
+ }, [pages, pageParam, selectedPage]);
const handleSelectPage = useCallback((page: PageResponse) => {
setSelectedPage(page);
@@ -119,7 +120,12 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
{/* Viewer */}
<div className={cn("flex-1 min-w-0", treePanelOpen ? "hidden md:block" : "block")}>
- <DocsViewer page={selectedPage} repoId={repoId} />
+ <DocsViewer
+ page={selectedPage}
+ pages={pages}
+ repoId={repoId}
+ onSelectPage={handleSelectPage}
+ />
</div>
</div>
);
diff --git a/packages/web/src/components/docs/docs-viewer.tsx b/packages/web/src/components/docs/docs-viewer.tsx
index b91c16d07..d355edb79 100644
--- a/packages/web/src/components/docs/docs-viewer.tsx
+++ b/packages/web/src/components/docs/docs-viewer.tsx
@@ -1,31 +1,47 @@
"use client";
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import Link from "next/link";
+import { useRouter, useSearchParams } from "next/navigation";
+import useSWR from "swr";
import {
FileText,
Clock,
Cpu,
- Hash,
ExternalLink,
Download,
StickyNote,
ArrowRight,
- RefreshCw,
+ ArrowLeft,
Loader2,
PanelRight,
PanelRightClose,
Network,
Activity,
GitBranch,
+ Layers,
+ Flame,
+ FileInput,
} from "lucide-react";
import { cn } from "@/lib/utils/cn";
+import { getGitMetadata } from "@/lib/api/git";
import { WikiMarkdown } from "@repowise-dev/ui/wiki/wiki-markdown";
+import { getBacklinks, getWikiLinks } from "@repowise-dev/ui/wiki/wiki-links-types";
+import { TableOfContents } from "@repowise-dev/ui/wiki/table-of-contents";
+import { computeDocNav } from "@repowise-dev/ui/docs/doc-nav";
+import { Breadcrumb } from "@repowise-dev/ui/shared/breadcrumb";
+import { BacklinksPanel } from "@repowise-dev/ui/wiki/backlinks-panel";
+import { getPageTypeLabel } from "@repowise-dev/ui/lib/page-types";
+import {
+ DEFAULT_PERSONA,
+ READER_PERSONAS,
+ type ReaderPersona,
+ filterMarkdownByPersona,
+ isReaderPersona,
+} from "@repowise-dev/ui/docs/reader-persona";
import { VersionHistoryWrapper } from "@/components/wiki/version-history";
import { ConfidenceBadge } from "@repowise-dev/ui/wiki/confidence-badge";
-import { Button } from "@repowise-dev/ui/ui/button";
import { Badge } from "@repowise-dev/ui/ui/badge";
-import { ScrollArea } from "@repowise-dev/ui/ui/scroll-area";
import { Skeleton } from "@repowise-dev/ui/ui/skeleton";
import { formatRelativeTime, formatTokens } from "@repowise-dev/ui/lib/format";
import { downloadTextFile } from "@/lib/utils/download";
@@ -162,16 +178,124 @@ function DocsSidebar({ repoId, targetPath }: { repoId: string; targetPath: strin
);
}
+/**
+ * Consolidated "At a glance" signals for a file page — hotspot, ownership,
+ * churn, bus factor — pulled from the existing git-metadata endpoint so the
+ * reader doesn't have to leave the wiki to learn how risky/owned a file is.
+ * Renders nothing for non-file pages or files without git history.
+ */
+function AtAGlance({ repoId, targetPath }: { repoId: string; targetPath: string }) {
+ const isFile =
+ !!targetPath &&
+ !targetPath.includes("::") &&
+ !targetPath.startsWith("onboarding/") &&
+ !targetPath.startsWith("layer:");
+ const { data } = useSWR(
+ isFile ? `git-meta:${repoId}:${targetPath}` : null,
+ () => getGitMetadata(repoId, targetPath),
+ { revalidateOnFocus: false, shouldRetryOnError: false },
+ );
+ if (!data || data.commit_count_total === 0) return null;
+
+ const churnTop = Math.max(1, 100 - Math.round(data.churn_percentile));
+ 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-[11px] font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">
+ At a glance
+ </span>
+ </div>
+ <div className="flex flex-wrap gap-1.5">
+ {data.is_hotspot && (
+ <Badge variant="outline" className="text-[10px] border-amber-400/40 text-amber-300/90">
+ <Flame className="h-2.5 w-2.5 mr-1" />
+ Hotspot · top {churnTop}%
+ </Badge>
+ )}
+ {data.is_stable && !data.is_hotspot && (
+ <Badge variant="outline" className="text-[10px]">Stable</Badge>
+ )}
+ {data.bus_factor === 1 && (
+ <Badge variant="outline" className="text-[10px] border-amber-400/40 text-amber-300/90">
+ Bus factor 1
+ </Badge>
+ )}
+ </div>
+ <div className="mt-2 space-y-1 text-[11px] text-[var(--color-text-secondary)]">
+ {data.primary_owner_name && (
+ <div className="flex items-center justify-between gap-2">
+ <span className="text-[var(--color-text-tertiary)]">Owner</span>
+ <span className="truncate" title={data.primary_owner_name}>
+ {data.primary_owner_name}
+ {data.primary_owner_commit_pct != null &&
+ ` · ${Math.round(data.primary_owner_commit_pct * 100)}%`}
+ </span>
+ </div>
+ )}
+ <div className="flex items-center justify-between gap-2">
+ <span className="text-[var(--color-text-tertiary)]">Commits (90d)</span>
+ <span className="font-mono">{data.commit_count_90d}</span>
+ </div>
+ <div className="flex items-center justify-between gap-2">
+ <span className="text-[var(--color-text-tertiary)]">Contributors</span>
+ <span className="font-mono">{data.contributor_count}</span>
+ </div>
+ </div>
+ </div>
+ );
+}
+
interface DocsViewerProps {
page: PageResponse | null;
+ /** Full page list — powers hierarchical breadcrumbs and prev/next. */
+ pages?: PageResponse[];
repoId: string;
isLoading?: boolean;
+ /** Select another page in-place (breadcrumb / prev-next / wiki links). */
+ onSelectPage?: (page: PageResponse) => void;
}
-export function DocsViewer({ page, repoId, isLoading }: DocsViewerProps) {
+export function DocsViewer({
+ page,
+ pages = [],
+ repoId,
+ isLoading,
+ onSelectPage,
+}: DocsViewerProps) {
const scrollRef = useRef<HTMLDivElement>(null);
const [sidebarOpen, setSidebarOpen] = useState(true);
+ // Reader persona — a client-side section filter, persisted in the URL
+ // (?reader=) so a chosen depth is shareable and survives navigation.
+ const router = useRouter();
+ const searchParams = useSearchParams();
+ const readerParam = searchParams.get("reader");
+ const persona: ReaderPersona = isReaderPersona(readerParam) ? readerParam : DEFAULT_PERSONA;
+ const setPersona = useCallback(
+ (next: ReaderPersona) => {
+ const params = new URLSearchParams(searchParams.toString());
+ if (next === DEFAULT_PERSONA) params.delete("reader");
+ else params.set("reader", next);
+ const qs = params.toString();
+ router.replace(qs ? `?${qs}` : "?", { scroll: false });
+ },
+ [router, searchParams],
+ );
+
+ // In-app navigation to another page by id (used by breadcrumbs, prev/next,
+ // and resolved wiki links). Falls back to the full wiki route when the
+ // target isn't in the loaded list or no handler was supplied.
+ const goToPageId = useCallback(
+ (pageId: string) => {
+ const target = pages.find((p) => p.id === pageId);
+ if (target && onSelectPage) onSelectPage(target);
+ else
+ window.location.href = `/repos/${repoId}/wiki/${encodeURIComponent(pageId)}`;
+ },
+ [pages, onSelectPage, repoId],
+ );
+
// Scroll to top when page changes
useEffect(() => {
scrollRef.current?.scrollTo(0, 0);
@@ -205,17 +329,178 @@ export function DocsViewer({ page, repoId, isLoading }: DocsViewerProps) {
const hasTargetPath = !!page.target_path;
+ return (
+ <DocsViewerBody
+ page={page}
+ pages={pages}
+ repoId={repoId}
+ hasTargetPath={hasTargetPath}
+ sidebarOpen={sidebarOpen}
+ setSidebarOpen={setSidebarOpen}
+ scrollRef={scrollRef}
+ goToPageId={goToPageId}
+ persona={persona}
+ setPersona={setPersona}
+ />
+ );
+}
+
+function DocsViewerBody({
+ page,
+ pages,
+ repoId,
+ hasTargetPath,
+ sidebarOpen,
+ setSidebarOpen,
+ scrollRef,
+ goToPageId,
+ persona,
+ setPersona,
+}: {
+ page: PageResponse;
+ pages: PageResponse[];
+ repoId: string;
+ hasTargetPath: boolean;
+ sidebarOpen: boolean;
+ setSidebarOpen: (fn: (o: boolean) => boolean) => void;
+ scrollRef: React.RefObject<HTMLDivElement | null>;
+ goToPageId: (pageId: string) => void;
+ persona: ReaderPersona;
+ setPersona: (next: ReaderPersona) => void;
+}) {
+ // Hierarchical breadcrumb + sibling prev/next, derived from the page list.
+ const nav = useMemo(() => computeDocNav(page, pages), [page, pages]);
+ const wikiLinks = useMemo(() => getWikiLinks(page.metadata), [page.metadata]);
+
+ // Persona-filtered markdown — hides reference-heavy sections for the lighter
+ // reading levels. The TOC + download still operate on the full content.
+ const visibleContent = useMemo(
+ () => filterMarkdownByPersona(page.content, persona),
+ [page.content, persona],
+ );
+
+ // Nearest ancestor that maps to a module page — the "zoom out" chip target.
+ const moduleSeg = useMemo(
+ () =>
+ [...nav.breadcrumbs]
+ .slice(0, -1)
+ .reverse()
+ .find((s) => s.pageId && s.pageId !== page.id),
+ [nav.breadcrumbs, page.id],
+ );
+
+ const buildWikiHref = useCallback(
+ (pageId: string) =>
+ `/repos/${repoId}/docs?page=${encodeURIComponent(pageId)}`,
+ [repoId],
+ );
+
+ // Forward "Related" links: distinct wiki-link targets resolved to titles
+ // from the loaded page list. Pure metadata — no extra request.
+ const relatedLinks = useMemo(() => {
+ const byId = new Map(pages.map((p) => [p.id, p]));
+ const seen = new Set<string>();
+ const out: { id: string; title: string }[] = [];
+ for (const link of wikiLinks) {
+ const target = link.target_page_id;
+ if (target === page.id || seen.has(target)) continue;
+ const hit = byId.get(target);
+ if (!hit) continue;
+ seen.add(target);
+ out.push({ id: hit.id, title: hit.title });
+ if (out.length >= 8) break;
+ }
+ return out;
+ }, [wikiLinks, pages, page.id]);
+
+ // KG layer this file belongs to (P1.4 "layer Y" chip). Links to the layer
+ // page when one was generated, otherwise renders as a static chip.
+ const layerName =
+ typeof page.metadata?.layer_name === "string" ? page.metadata.layer_name : "";
+ const layerPage = useMemo(
+ () =>
+ layerName
+ ? pages.find(
+ (p) =>
+ p.page_type === "layer_page" &&
+ p.target_path === `layer:${layerName}`,
+ )
+ : undefined,
+ [pages, layerName],
+ );
+
+ // Provenance: the inputs this page was synthesised from (metadata.sources).
+ // Each is linked to its own page when one exists.
+ const sources = useMemo(() => {
+ const raw = page.metadata?.sources;
+ if (!Array.isArray(raw)) return [];
+ const byPath = new Map(pages.map((p) => [p.target_path, p]));
+ return (raw as Array<{ path?: string; kind?: string }>)
+ .map((s) => {
+ const path = typeof s?.path === "string" ? s.path : "";
+ return { path, kind: s?.kind ?? "", pageId: byPath.get(path)?.id };
+ })
+ .filter((s) => s.path)
+ .slice(0, 8);
+ }, [page.metadata, pages]);
+
+ // Renders a resolved wiki link as an <a> with a real href (middle-click /
+ // open-in-new-tab still work) but intercepts plain clicks for in-app nav.
+ const WikiInlineLink = useMemo(() => {
+ function Comp({
+ href,
+ className,
+ title,
+ children,
+ }: {
+ href: string;
+ className?: string;
+ title?: string;
+ children: React.ReactNode;
+ }) {
+ return (
+ <a
+ href={href}
+ className={className}
+ title={title}
+ onClick={(e) => {
+ if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;
+ try {
+ const u = new URL(href, window.location.origin);
+ const pid = u.searchParams.get("page");
+ if (pid) {
+ e.preventDefault();
+ goToPageId(pid);
+ }
+ } catch {
+ /* fall through to default navigation */
+ }
+ }}
+ >
+ {children}
+ </a>
+ );
+ }
+ return Comp;
+ }, [goToPageId]);
+
return (
<div className="flex h-full">
{/* Main content */}
<div className="flex flex-col flex-1 min-w-0">
{/* Sticky header */}
<div className="sticky top-0 z-10 flex items-center gap-2 border-b border-[var(--color-border-default)] bg-[var(--color-bg-surface)]/95 backdrop-blur px-4 sm:px-6 py-2.5 flex-wrap sm:flex-nowrap shrink-0">
- {/* Path breadcrumb */}
- <div className="flex items-center gap-1.5 text-xs text-[var(--color-text-tertiary)] min-w-0 flex-1">
- <span className="font-mono truncate text-[var(--color-text-secondary)]">
- {page.target_path || page.page_type}
- </span>
+ {/* Hierarchical breadcrumb: module / file, ancestors clickable */}
+ <div className="min-w-0 flex-1 overflow-hidden">
+ <Breadcrumb
+ segments={nav.breadcrumbs.map((seg) => ({
+ label: seg.label,
+ ...(seg.pageId && seg.pageId !== page.id
+ ? { href: buildWikiHref(seg.pageId) }
+ : {}),
+ }))}
+ LinkComponent={WikiInlineLink}
+ />
</div>
{/* Confidence */}
@@ -253,8 +538,31 @@ export function DocsViewer({ page, repoId, isLoading }: DocsViewerProps) {
<ExternalLink className="h-3.5 w-3.5" />
</Link>
+ {/* Reader persona — Overview / Contributor / Deep section filter */}
+ <div
+ className="hidden md:inline-flex items-center rounded-md border border-[var(--color-border-default)] p-0.5 shrink-0"
+ role="group"
+ aria-label="Reader level"
+ >
+ {READER_PERSONAS.map((p) => (
+ <button
+ key={p.value}
+ onClick={() => setPersona(p.value)}
+ title={p.hint}
+ className={cn(
+ "rounded px-1.5 py-0.5 text-[10px] font-medium transition-colors",
+ persona === p.value
+ ? "bg-[var(--color-accent-primary)] text-white"
+ : "text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)]",
+ )}
+ >
+ {p.label}
+ </button>
+ ))}
+ </div>
+
{/* Sidebar toggle */}
- {hasTargetPath && (
+ {(
<button
onClick={() => setSidebarOpen((o) => !o)}
className={cn(
@@ -282,6 +590,45 @@ export function DocsViewer({ page, repoId, isLoading }: DocsViewerProps) {
{page.title}
</h1>
+ {/* Context chips: page type + "in module" (zoom-out) */}
+ <div className="flex flex-wrap items-center gap-1.5 mb-2">
+ <span className="rounded-full bg-[var(--color-bg-elevated)] px-2 py-0.5 text-[10px] uppercase tracking-wider text-[var(--color-text-tertiary)]">
+ {getPageTypeLabel(page.page_type)}
+ </span>
+ {moduleSeg && (
+ <button
+ onClick={() => goToPageId(moduleSeg.pageId!)}
+ className="rounded-full border border-[var(--color-border-default)] px-2 py-0.5 text-[10px] text-[var(--color-text-secondary)] transition-colors hover:border-[var(--color-border-accent)] hover:text-[var(--color-accent-primary)]"
+ >
+ in {moduleSeg.label}
+ </button>
+ )}
+ {layerName &&
+ (layerPage ? (
+ <button
+ onClick={() => goToPageId(layerPage.id)}
+ className="inline-flex items-center gap-1 rounded-full border border-[var(--color-border-default)] px-2 py-0.5 text-[10px] text-[var(--color-text-secondary)] transition-colors hover:border-[var(--color-border-accent)] hover:text-[var(--color-accent-primary)]"
+ >
+ <Layers className="h-2.5 w-2.5" />
+ {layerName}
+ </button>
+ ) : (
+ <span className="inline-flex items-center gap-1 rounded-full bg-[var(--color-bg-elevated)] px-2 py-0.5 text-[10px] text-[var(--color-text-tertiary)]">
+ <Layers className="h-2.5 w-2.5" />
+ {layerName}
+ </span>
+ ))}
+ </div>
+
+ {/* Low-confidence flag */}
+ {page.confidence > 0 && page.confidence < 0.5 && (
+ <div className="mb-4 flex items-start gap-1.5 rounded-md border border-amber-400/30 bg-amber-50/5 px-3 py-2">
+ <span className="text-xs text-amber-300/90">
+ This page was generated with low confidence — verify against the source before relying on it.
+ </span>
+ </div>
+ )}
+
{/* Meta row */}
<div className="flex items-center gap-3 text-[10px] text-[var(--color-text-tertiary)] mb-6">
<span className="flex items-center gap-1">
@@ -311,9 +658,54 @@ export function DocsViewer({ page, repoId, isLoading }: DocsViewerProps) {
{/* Markdown content */}
<article className="prose prose-invert max-w-none leading-relaxed overflow-hidden">
- <WikiMarkdown content={page.content} />
+ <WikiMarkdown
+ content={visibleContent}
+ wikiLinks={wikiLinks}
+ buildHref={(pid) => buildWikiHref(pid)}
+ LinkComponent={WikiInlineLink}
+ />
</article>
+ {/* 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">
+ {nav.prev ? (
+ <button
+ onClick={() => goToPageId(nav.prev!.pageId)}
+ className="group flex flex-1 items-center gap-2 rounded-lg border border-[var(--color-border-default)] px-3 py-2 text-left transition-colors hover:border-[var(--color-border-accent)] hover:bg-[var(--color-bg-elevated)]"
+ >
+ <ArrowLeft className="h-3.5 w-3.5 shrink-0 text-[var(--color-text-tertiary)] group-hover:text-[var(--color-accent-primary)]" />
+ <span className="min-w-0">
+ <span className="block text-[10px] uppercase tracking-wider text-[var(--color-text-tertiary)]">
+ Previous
+ </span>
+ <span className="block truncate text-xs text-[var(--color-text-secondary)]">
+ {nav.prev.title}
+ </span>
+ </span>
+ </button>
+ ) : (
+ <span className="flex-1" />
+ )}
+ {nav.next && (
+ <button
+ onClick={() => goToPageId(nav.next!.pageId)}
+ className="group flex flex-1 items-center justify-end gap-2 rounded-lg border border-[var(--color-border-default)] px-3 py-2 text-right transition-colors hover:border-[var(--color-border-accent)] hover:bg-[var(--color-bg-elevated)]"
+ >
+ <span className="min-w-0">
+ <span className="block text-[10px] uppercase tracking-wider text-[var(--color-text-tertiary)]">
+ Next
+ </span>
+ <span className="block truncate text-xs text-[var(--color-text-secondary)]">
+ {nav.next.title}
+ </span>
+ </span>
+ <ArrowRight className="h-3.5 w-3.5 shrink-0 text-[var(--color-text-tertiary)] group-hover:text-[var(--color-accent-primary)]" />
+ </button>
+ )}
+ </nav>
+ )}
+
{/* Version history */}
<div className="mt-8">
<VersionHistoryWrapper
@@ -342,10 +734,81 @@ export function DocsViewer({ page, repoId, isLoading }: DocsViewerProps) {
</div>
</div>
- {/* Right sidebar — Graph Intelligence */}
- {hasTargetPath && sidebarOpen && (
+ {/* Right sidebar — on-page contents + graph intelligence */}
+ {sidebarOpen && (
<div className="hidden lg:flex flex-col border-l border-[var(--color-border-default)] bg-[var(--color-bg-surface)] shrink-0 w-[240px] overflow-auto">
- <DocsSidebar repoId={repoId} targetPath={page.target_path} />
+ {hasTargetPath && (
+ <div className="p-3 pb-0">
+ <AtAGlance repoId={repoId} targetPath={page.target_path} />
+ </div>
+ )}
+ <div className="p-3">
+ <TableOfContents content={page.content} />
+ </div>
+ {(relatedLinks.length > 0 || sources.length > 0 || hasTargetPath) && (
+ <div className="space-y-4 p-3 pt-0">
+ {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-[11px] font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider">
+ Built from
+ </span>
+ </div>
+ <ul className="space-y-1">
+ {sources.map((s) => (
+ <li key={s.path} className="text-[11px]">
+ {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}
+ </button>
+ ) : (
+ <span
+ className="block truncate font-mono text-[var(--color-text-tertiary)]"
+ title={`${s.path} (${s.kind})`}
+ >
+ {s.path}
+ </span>
+ )}
+ </li>
+ ))}
+ </ul>
+ </div>
+ )}
+ {relatedLinks.length > 0 && (
+ <div>
+ <p className="text-xs font-medium text-[var(--color-text-tertiary)] uppercase tracking-wider mb-2">
+ Related ({relatedLinks.length})
+ </p>
+ <ul className="space-y-1.5">
+ {relatedLinks.map((r) => (
+ <li key={r.id} className="text-xs">
+ <button
+ onClick={() => 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}
+ >
+ {r.title}
+ </button>
+ </li>
+ ))}
+ </ul>
+ </div>
+ )}
+ <BacklinksPanel
+ backlinks={getBacklinks(page.metadata)}
+ repoId={repoId}
+ buildHref={(rid, pid) =>
+ `/repos/${rid}/docs?page=${encodeURIComponent(pid)}`
+ }
+ />
+ </div>
+ )}
+ {hasTargetPath && <DocsSidebar repoId={repoId} targetPath={page.target_path} />}
</div>
)}
</div>
diff --git a/tests/unit/generation/test_categories.py b/tests/unit/generation/test_categories.py
new file mode 100644
index 000000000..bf1137f6a
--- /dev/null
+++ b/tests/unit/generation/test_categories.py
@@ -0,0 +1,42 @@
+"""Tests for file-category classification (generation.categories)."""
+
+from __future__ import annotations
+
+from repowise.core.generation.categories import (
+ CATEGORY_CODE,
+ CATEGORY_CONFIG,
+ CATEGORY_DATA,
+ CATEGORY_DOC,
+ CATEGORY_PIPELINE,
+ file_category,
+)
+
+
+def test_doc_files():
+ assert file_category("README.md", "markdown") == CATEGORY_DOC
+ assert file_category("docs/guide.rst") == CATEGORY_DOC
+
+
+def test_pipeline_files():
+ assert file_category(".github/workflows/ci.yml", "yaml") == CATEGORY_PIPELINE
+ assert file_category("Jenkinsfile") == CATEGORY_PIPELINE
+
+
+def test_data_files():
+ assert file_category("alembic/versions/0001_init.py", "python") == CATEGORY_DATA
+ assert file_category("app/models/user.py", "python") == CATEGORY_DATA
+ assert file_category("schema.sql", "sql") == CATEGORY_DATA
+
+
+def test_config_files():
+ assert file_category("pyproject.toml", "toml") == CATEGORY_CONFIG
+ assert file_category("settings.py", "python", is_config=True) == CATEGORY_CONFIG
+
+
+def test_code_default():
+ assert file_category("src/services/billing.py", "python") == CATEGORY_CODE
+
+
+def test_resolution_order_doc_beats_pipeline():
+ # A markdown file inside a workflows dir is still documentation.
+ assert file_category(".github/workflows/README.md", "markdown") == CATEGORY_DOC
diff --git a/tests/unit/generation/test_layers.py b/tests/unit/generation/test_layers.py
new file mode 100644
index 000000000..669b238d7
--- /dev/null
+++ b/tests/unit/generation/test_layers.py
@@ -0,0 +1,79 @@
+"""Tests for the architectural layer spine (generation.layers)."""
+
+from __future__ import annotations
+
+from repowise.core.generation.layers import (
+ DEFAULT_LAYER,
+ compute_layer_order,
+ infer_layer,
+)
+
+
+# ---------------------------------------------------------------------------
+# infer_layer — every file maps to exactly one layer
+# ---------------------------------------------------------------------------
+
+
+def test_infer_layer_matches_directory_hints():
+ assert infer_layer("src/api/users.py") == "API"
+ assert infer_layer("app/services/billing.py") == "Service"
+ assert infer_layer("pkg/models/user.py") == "Data"
+ assert infer_layer("web/components/Button.tsx") == "UI"
+ assert infer_layer("src/middleware/auth.ts") == "Middleware"
+ assert infer_layer("lib/utils/strings.py") == "Utility"
+ assert infer_layer("config/settings.py") == "Config"
+ assert infer_layer("tests/test_user.py") == "Test"
+ assert infer_layer("src/types/dtos.ts") == "Types"
+
+
+def test_infer_layer_uses_deepest_matching_directory():
+ # The closest directory wins over a shallower one.
+ assert infer_layer("services/api/handler.py") == "API"
+
+
+def test_infer_layer_falls_back_for_unmatched_paths():
+ assert infer_layer("main.py") == DEFAULT_LAYER
+ assert infer_layer("random/folder/thing.py") == DEFAULT_LAYER
+
+
+# ---------------------------------------------------------------------------
+# compute_layer_order — top→bottom by dependency direction
+# ---------------------------------------------------------------------------
+
+
+def test_compute_layer_order_follows_dependency_direction():
+ file_layers = {
+ "api/h.py": "API",
+ "services/s.py": "Service",
+ "models/m.py": "Data",
+ }
+ # API imports Service imports Data — a clean stack.
+ edges = [
+ ("api/h.py", "services/s.py"),
+ ("services/s.py", "models/m.py"),
+ ]
+ order = compute_layer_order(file_layers, edges)
+ assert order.index("API") < order.index("Service") < order.index("Data")
+
+
+def test_compute_layer_order_ignores_external_and_intra_layer_edges():
+ file_layers = {"api/a.py": "API", "api/b.py": "API", "data/d.py": "Data"}
+ edges = [
+ ("api/a.py", "api/b.py"), # intra-layer — ignored
+ ("api/a.py", "external:requests"), # external — ignored
+ ("api/a.py", "data/d.py"), # API → Data
+ ]
+ order = compute_layer_order(file_layers, edges)
+ assert order.index("API") < order.index("Data")
+
+
+def test_compute_layer_order_stable_without_edges():
+ file_layers = {"a.py": "API", "b.py": "Utility", "c.py": "Data"}
+ order = compute_layer_order(file_layers, [])
+ # Falls back to canonical rank: API above Data above Utility.
+ assert order == ["API", "Data", "Utility"]
+
+
+def test_compute_layer_order_single_layer():
+ assert compute_layer_order({"a.py": "API"}, []) == ["API"]
+ assert compute_layer_order({}, []) == []
diff --git a/tests/unit/generation/test_mermaid_safety.py b/tests/unit/generation/test_mermaid_safety.py
new file mode 100644
index 000000000..605e8672d
--- /dev/null
+++ b/tests/unit/generation/test_mermaid_safety.py
@@ -0,0 +1,83 @@
+"""Unit tests for the mermaid safety / auto-fix pass."""
+
+from __future__ import annotations
+
+from repowise.core.generation.mermaid_safety import sanitize_mermaid, sanitize_pages
+
+
+def _block(body: str) -> str:
+ return f"intro\n\n```mermaid\n{body}\n```\n\noutro"
+
+
+def test_no_mermaid_is_noop():
+ md = "# Title\n\nSome `code` and prose, no diagrams.\n"
+ assert sanitize_mermaid(md) == md
+
+
+def test_path_node_ids_are_slugged_consistently():
+ md = _block("graph TD\n pkg/foo.py[Foo] --> pkg/bar.py[Bar]")
+ out = sanitize_mermaid(md)
+ # Illegal path IDs gone; replaced by the same slug on both sides of the edge.
+ assert "pkg/foo.py" not in out
+ assert "pkg/bar.py" not in out
+ assert "pkg_foo_py" in out
+ assert "pkg_bar_py" in out
+ # The edge is preserved.
+ assert "-->" in out
+
+
+def test_dotted_ids_slugged():
+ md = _block("flowchart LR\n app.main --> app.db")
+ out = sanitize_mermaid(md)
+ assert "app.main" not in out
+ assert "app_main" in out
+ assert "app_db" in out
+
+
+def test_unquoted_label_with_parens_is_quoted():
+ md = _block("graph TD\n A[run() -> None] --> B[ok]")
+ out = sanitize_mermaid(md)
+ assert '"run() -> None"' in out
+ # A simple label with no special chars is left alone.
+ assert "B[ok]" in out
+
+
+def test_already_quoted_label_untouched():
+ md = _block('graph TD\n A["already (quoted)"] --> B')
+ out = sanitize_mermaid(md)
+ assert out.count('"already (quoted)"') == 1
+
+
+def test_inner_quotes_escaped():
+ md = _block('graph TD\n A[say "hi" (x)]')
+ out = sanitize_mermaid(md)
+ assert "&quot;hi&quot;" in out
+
+
+def test_non_graph_diagram_left_alone():
+ body = "sequenceDiagram\n Alice->>John: Hello John, how are you?"
+ md = _block(body)
+ out = sanitize_mermaid(md)
+ # Sequence diagrams use a different grammar — we must not touch them.
+ assert body in out
+
+
+def test_collision_produces_unique_slugs():
+ # Two distinct paths that slugify to the same base must stay distinct.
+ md = _block("graph TD\n a/b[X] --> a.b[Y]")
+ out = sanitize_mermaid(md)
+ assert "a_b" in out
+ assert "a_b_2" in out
+
+
+def test_sanitize_pages_mutates_and_counts():
+ class _P:
+ def __init__(self, content):
+ self.content = content
+
+ changed = _P(_block("graph TD\n pkg/x.py[X]"))
+ unchanged = _P("# clean\n\nno diagram here")
+ n = sanitize_pages([changed, unchanged])
+ assert n == 1
+ assert "pkg/x.py" not in changed.content
+ assert unchanged.content == "# clean\n\nno diagram here"
diff --git a/tests/unit/generation/test_onboarding.py b/tests/unit/generation/test_onboarding.py
index fb8b862f7..f3b8700b1 100644
--- a/tests/unit/generation/test_onboarding.py
+++ b/tests/unit/generation/test_onboarding.py
@@ -104,6 +104,9 @@ def _signals(
decisions: tuple[dict, ...] = (),
community: dict[str, int] | None = None,
entry_points: list[str] | None = None,
+ tour_stops: tuple[dict, ...] = (),
+ layer_order: tuple[str, ...] = (),
+ completed_page_summaries: dict[str, str] | None = None,
) -> OnboardingSignals:
paths = [f.file_info.path for f in files]
pr = pagerank or {p: 0.1 for p in paths}
@@ -135,7 +138,9 @@ def _signals(
dead_code_by_file={},
decisions_all=decisions,
external_systems=external_systems,
- completed_page_summaries={},
+ completed_page_summaries=completed_page_summaries or {},
+ tour_stops=tour_stops,
+ layer_order=layer_order,
)
@@ -144,14 +149,16 @@ def _signals(
# ---------------------------------------------------------------------------
-def test_six_subkinds_registered_in_canonical_order() -> None:
+def test_subkinds_registered_in_canonical_order() -> None:
specs = onboarding.iter_specs()
slots = [s.slot for s in specs]
# Promoted slots are excluded from iter_specs even though they're in
# ONBOARDING_ORDER.
expected = [s for s in ONBOARDING_ORDER if s not in PROMOTED_SLOTS.values()]
assert slots == expected
- assert len(slots) == 6
+ # Six templated subkinds + the topology-driven guided tour.
+ assert len(slots) == 7
+ assert "guided_tour" in slots
def test_onboarding_level_is_eight() -> None:
@@ -432,6 +439,50 @@ def test_tag_promoted_pages_sets_onboarding_slot() -> None:
assert "onboarding_slot" not in pages[2].metadata
+# ---------------------------------------------------------------------------
+# Guided tour — gated on having a real (multi-stop) tour
+# ---------------------------------------------------------------------------
+
+
+def _tour_stops(n: int) -> tuple[dict, ...]:
+ return tuple(
+ {
+ "order": i + 1,
+ "target_path": f"src/file_{i}.py",
+ "page_type": "file_page",
+ "title": f"file_{i}.py",
+ "depth": i,
+ "kind": "code",
+ "reason": "reason",
+ }
+ for i in range(n)
+ )
+
+
+def test_guided_tour_skipped_without_enough_stops() -> None:
+ spec = onboarding.get_spec("guided_tour")
+ assert spec is not None
+ sig = _signals(files=[_file("src/main.py", is_entry_point=True)], tour_stops=_tour_stops(1))
+ assert spec.build_context(sig) is None
+
+
+def test_guided_tour_builds_with_stops_and_summaries() -> None:
+ spec = onboarding.get_spec("guided_tour")
+ assert spec is not None
+ sig = _signals(
+ files=[_file("src/main.py", is_entry_point=True)],
+ tour_stops=_tour_stops(3),
+ layer_order=("API", "Service", "Data"),
+ completed_page_summaries={"src/file_0.py": "Entry orchestrator."},
+ )
+ ctx = spec.build_context(sig)
+ assert ctx is not None
+ assert len(ctx.stops) == 3
+ assert ctx.layer_order == ["API", "Service", "Data"]
+ # Summary is attached to the matching stop.
+ assert ctx.stops[0].summary == "Entry orchestrator."
+
+
# ---------------------------------------------------------------------------
# Templates render
# ---------------------------------------------------------------------------
@@ -520,6 +571,17 @@ def _jinja_env() -> jinja2.Environment:
)
),
),
+ (
+ "guided_tour",
+ lambda: onboarding.get_spec("guided_tour").build_context(
+ _signals(
+ files=[_file("src/main.py", is_entry_point=True)],
+ tour_stops=_tour_stops(3),
+ layer_order=("API", "Service"),
+ completed_page_summaries={"src/file_0.py": "Entry orchestrator."},
+ )
+ ),
+ ),
(
SLOT_DEVELOPMENT_GUIDE,
lambda: onboarding.get_spec(SLOT_DEVELOPMENT_GUIDE).build_context(
diff --git a/tests/unit/generation/test_provenance.py b/tests/unit/generation/test_provenance.py
new file mode 100644
index 000000000..3ee8edcf1
--- /dev/null
+++ b/tests/unit/generation/test_provenance.py
@@ -0,0 +1,85 @@
+"""Unit tests for file-page provenance + layer metadata attachment."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from repowise.core.generation.models import GeneratedPage
+from repowise.core.generation.page_generator.core import _attach_file_provenance
+
+
+def _page() -> GeneratedPage:
+ return GeneratedPage(
+ page_id="file_page:pkg/foo.py",
+ page_type="file_page",
+ title="File: pkg/foo.py",
+ content="",
+ source_hash="x",
+ model_name="mock",
+ provider_name="mock",
+ input_tokens=0,
+ output_tokens=0,
+ cached_tokens=0,
+ generation_level=2,
+ target_path="pkg/foo.py",
+ created_at="2026-01-01T00:00:00+00:00",
+ updated_at="2026-01-01T00:00:00+00:00",
+ )
+
+
+def _ctx(**over):
+ base = dict(
+ file_path="pkg/foo.py",
+ kg_layer_name="",
+ kg_layer_role="",
+ dependencies=[],
+ decision_records=[],
+ )
+ base.update(over)
+ return SimpleNamespace(**base)
+
+
+def test_layer_metadata_attached():
+ page = _page()
+ _attach_file_provenance(page, _ctx(kg_layer_name="Domain", kg_layer_role="entry_point"))
+ assert page.metadata["layer_name"] == "Domain"
+ assert page.metadata["layer_role"] == "entry_point"
+
+
+def test_no_kg_layer_falls_back_to_inferred_layer():
+ # Every file page must carry a layer_name so the Architecture tree can
+ # group it; with no KG layer it is inferred from the path.
+ page = _page()
+ _attach_file_provenance(page, _ctx(file_path="src/api/users.py"))
+ assert page.metadata["layer_name"] == "API"
+ # No KG role is invented for the fallback path.
+ assert "layer_role" not in page.metadata
+
+
+def test_sources_from_dependencies_and_decisions():
+ page = _page()
+ ctx = _ctx(
+ dependencies=["pkg/bar.py", "pkg/baz.py"],
+ decision_records=[{"evidence_file": "docs/adr-1.md"}, {"source": "pkg/bar.py"}],
+ )
+ _attach_file_provenance(page, ctx)
+ sources = page.metadata["sources"]
+ paths = [s["path"] for s in sources]
+ assert "pkg/bar.py" in paths
+ assert "pkg/baz.py" in paths
+ assert "docs/adr-1.md" in paths
+ # bar.py already recorded as a dependency — not duplicated by the decision.
+ assert paths.count("pkg/bar.py") == 1
+ assert {s["kind"] for s in sources} == {"dependency", "decision"}
+
+
+def test_no_sources_means_no_key():
+ page = _page()
+ _attach_file_provenance(page, _ctx())
+ assert "sources" not in page.metadata
+
+
+def test_dependencies_capped_at_ten():
+ page = _page()
+ _attach_file_provenance(page, _ctx(dependencies=[f"d{i}.py" for i in range(20)]))
+ assert len(page.metadata["sources"]) == 10
diff --git a/tests/unit/generation/test_selection_budget.py b/tests/unit/generation/test_selection_budget.py
index 752c50f4d..544c0c5d4 100644
--- a/tests/unit/generation/test_selection_budget.py
+++ b/tests/unit/generation/test_selection_budget.py
@@ -80,12 +80,16 @@ class FakeParsedFile:
# ---------------------------------------------------------------------------
-def _build_synthetic_repo(n_files: int) -> tuple[list[FakeParsedFile], dict, dict, dict]:
+def _build_synthetic_repo(
+ n_files: int, *, entry_points: int = 0
+) -> tuple[list[FakeParsedFile], dict, dict, dict]:
"""Return ``(parsed_files, pagerank, betweenness, community)``.
PageRank tapers linearly so the top file has 1.0 and the bottom
file has ~0.01. Community assignment buckets every 25 files into
- one community.
+ one community. The first ``entry_points`` files are flagged as
+ entry points but given LOW PageRank so they would normally fall
+ outside the budget — useful for landmark pull-in tests.
"""
parsed: list[FakeParsedFile] = []
pagerank: dict[str, float] = {}
@@ -94,7 +98,9 @@ def _build_synthetic_repo(n_files: int) -> tuple[list[FakeParsedFile], dict, dic
for i in range(n_files):
path = f"pkg{i // 25}/module_{i}.py"
- fi = FakeFileInfo(path=path)
+ # Flag the LAST `entry_points` files (lowest PageRank) as entry points.
+ is_ep = i >= n_files - entry_points if entry_points else False
+ fi = FakeFileInfo(path=path, is_entry_point=is_ep)
syms = [
FakeSymbol(name=f"func_{i}_{k}", qualified_name=f"module_{i}.func_{i}_{k}")
for k in range(3)
@@ -233,3 +239,59 @@ def test_higher_coverage_strictly_emits_more_pages():
)
totals.append(sum(sel.counts().values()))
assert totals == sorted(totals), f"Non-monotonic budget: {totals}"
+
+
+# ---------------------------------------------------------------------------
+# Tour landmark pull-in — must respect the budget (displace, don't inflate)
+# ---------------------------------------------------------------------------
+
+
+def _select(parsed, pagerank, betweenness, community, coverage_pct):
+ cfg = GenerationConfig(coverage_pct=coverage_pct)
+ return select_pages(
+ SelectionInputs(
+ parsed_files=parsed,
+ pagerank=pagerank,
+ betweenness=betweenness,
+ community=community,
+ community_info=None,
+ sccs=[],
+ git_meta_map=None,
+ config=cfg,
+ )
+ )
+
+
+def test_landmarks_are_pulled_into_budget_without_inflating_count():
+ """Low-PageRank entry points get a page, but the file_page count is unchanged."""
+ parsed, pr, bet, comm = _build_synthetic_repo(500, entry_points=5)
+ entry_paths = {p.file_info.path for p in parsed if p.file_info.is_entry_point}
+
+ baseline = _select(parsed, pr, bet, comm, 0.20)
+ baseline_count = len(baseline.file_page_paths)
+
+ # The flagged entry points have the lowest PageRank, so without the
+ # landmark rule they would not be selected. Confirm they now are…
+ selected = set(baseline.file_page_paths)
+ assert entry_paths.issubset(selected), "entry-point landmarks were not pulled in"
+
+ # …and that pulling them in displaced lower-ranked files rather than
+ # growing the budget: count is unchanged vs a repo with no entry points.
+ no_ep, pr2, bet2, comm2 = _build_synthetic_repo(500, entry_points=0)
+ no_ep_count = len(_select(no_ep, pr2, bet2, comm2, 0.20).file_page_paths)
+ assert baseline_count == no_ep_count
+
+
+def test_landmarks_respect_coverage_across_sizes():
+ """The total page count still tracks coverage_pct with landmarks active."""
+ for n, pct in [(40, 0.10), (500, 0.20), (1200, 0.10)]:
+ parsed, pr, bet, comm = _build_synthetic_repo(n, entry_points=5)
+ sel = _select(parsed, pr, bet, comm, pct)
+ total = sum(sel.counts().values())
+ # Landmark pull-in displaces rather than adds, so the total stays in
+ # the same ±20% band the budget contract guarantees.
+ expected = compute_budget(n, pct)
+ tolerance = max(20, int(expected * 0.30))
+ assert abs(total - expected) <= tolerance, (
+ f"n={n} pct={pct}: expected ~{expected}, got {total}"
+ )
diff --git a/tests/unit/generation/test_tour.py b/tests/unit/generation/test_tour.py
new file mode 100644
index 000000000..44f6ec60b
--- /dev/null
+++ b/tests/unit/generation/test_tour.py
@@ -0,0 +1,112 @@
+"""Tests for the topology-driven guided tour (generation.tour)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from repowise.core.generation.tour import (
+ DEFAULT_MAX_STOPS,
+ build_tour,
+ score_entry_points,
+ tour_landmark_paths,
+)
+
+
+@dataclass
+class _FI:
+ path: str
+ is_entry_point: bool = False
+
+
+@dataclass
+class _PF:
+ file_info: _FI
+
+
+def _repo(paths_entry: dict[str, bool]) -> list[_PF]:
+ return [_PF(_FI(path=p, is_entry_point=e)) for p, e in paths_entry.items()]
+
+
+# ---------------------------------------------------------------------------
+# Entry-point scoring
+# ---------------------------------------------------------------------------
+
+
+def test_score_entry_points_rewards_entry_flag_and_filename():
+ files = _repo({"src/main.py": True, "src/helpers/util.py": False})
+ pr = {"src/main.py": 0.9, "src/helpers/util.py": 0.1}
+ scored = score_entry_points(files, pr)
+ ranked = [p for _, p in scored]
+ assert ranked[0] == "src/main.py" # entry flag + main filename + shallow
+
+
+def test_score_entry_points_excludes_zero_score():
+ files = _repo({"deep/nested/pkg/thing.py": False})
+ pr = {"deep/nested/pkg/thing.py": 0.0}
+ assert score_entry_points(files, pr) == []
+
+
+# ---------------------------------------------------------------------------
+# Landmarks
+# ---------------------------------------------------------------------------
+
+
+def test_tour_landmark_paths_is_bounded():
+ files = _repo({f"src/app_{i}.py": True for i in range(20)})
+ pr = {f"src/app_{i}.py": 1.0 - i * 0.01 for i in range(20)}
+ landmarks = tour_landmark_paths(files, pr, max_landmarks=3)
+ assert len(landmarks) == 3
+
+
+# ---------------------------------------------------------------------------
+# build_tour
+# ---------------------------------------------------------------------------
+
+
+def test_build_tour_only_references_documented_pages():
+ files = _repo({"main.py": True, "a.py": False, "b.py": False, "undocumented.py": False})
+ pr = {"main.py": 0.9, "a.py": 0.5, "b.py": 0.3, "undocumented.py": 0.2}
+ edges = [("main.py", "a.py"), ("a.py", "b.py"), ("main.py", "undocumented.py")]
+ documented = {"main.py", "a.py", "b.py"} # undocumented.py NOT selected
+ stops = build_tour(
+ files, pr, edges, file_page_paths=documented, repo_name="myrepo"
+ )
+ targets = {s.target_path for s in stops}
+ assert "undocumented.py" not in targets
+ assert "myrepo" in targets # overview opens the tour
+
+
+def test_build_tour_orders_by_bfs_depth():
+ files = _repo({"main.py": True, "a.py": False, "b.py": False})
+ pr = {"main.py": 0.9, "a.py": 0.5, "b.py": 0.3}
+ edges = [("main.py", "a.py"), ("a.py", "b.py")]
+ stops = build_tour(files, pr, edges, file_page_paths={"main.py", "a.py", "b.py"})
+ code_stops = [s for s in stops if s.kind == "code"]
+ order = [s.target_path for s in code_stops]
+ assert order == ["main.py", "a.py", "b.py"]
+ assert [s.depth for s in code_stops] == [0, 1, 2]
+
+
+def test_build_tour_weaves_infra_last():
+ files = _repo({"main.py": True, "a.py": False})
+ pr = {"main.py": 0.9, "a.py": 0.5, "Dockerfile": 0.1}
+ edges = [("main.py", "a.py")]
+ stops = build_tour(
+ files,
+ pr,
+ edges,
+ file_page_paths={"main.py", "a.py"},
+ infra_paths={"Dockerfile"},
+ repo_name="r",
+ )
+ assert stops[-1].kind == "infra"
+ assert stops[-1].target_path == "Dockerfile"
+
+
+def test_build_tour_respects_max_stops():
+ files = _repo({f"f{i}.py": (i == 0) for i in range(50)})
+ pr = {f"f{i}.py": 1.0 - i * 0.01 for i in range(50)}
+ edges = [(f"f{i}.py", f"f{i+1}.py") for i in range(49)]
+ documented = {f"f{i}.py" for i in range(50)}
+ stops = build_tour(files, pr, edges, file_page_paths=documented, repo_name="r")
+ assert len(stops) <= DEFAULT_MAX_STOPS