Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.pynew file mode 100644index 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_CODEdiff --git a/packages/core/src/repowise/core/generation/context_assembler.py b/packages/core/src/repowise/core/generation/context_assembler.pyindex 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 structlogfrom repowise.core.ingestion.models import ParsedFile, RepoStructure, Symbol+from .categories import file_categoryfrom .models import GenerationConfiglog = structlog.get_logger(__name__)@@ -56,6 +57,9 @@ class FilePageContext:is_test: boolparse_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 = Noneco_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.pynew file mode 100644index 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.pynew file mode 100644index 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('"', """)+ 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__.pyindex 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.pyindex 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.pyindex 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 annotationsSLOT_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__.pyindex 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: F401from . import codebase_map # noqa: F401from . import getting_started # noqa: F401from . import key_concepts # noqa: F401diff --git a/packages/core/src/repowise/core/generation/onboarding/subkinds/codebase_map.py b/packages/core/src/repowise/core/generation/onboarding/subkinds/codebase_map.pyindex 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.pynew file mode 100644index 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.pyindex 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.pyindex 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 pageasync 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.pyindex 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.pyindex 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 = Noneself.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 = Noneself.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_backlinksdiff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.pyindex 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 structlogfrom repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY+from ..tour import DEFAULT_MAX_LANDMARKS, tour_landmark_pathsfrom .budget import BucketAllocation, allocate_budget, compute_budgetfrom .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.j2index 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.j2index 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.j2new file mode 100644index 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.j2index 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 presentThe codebase organises into these clusters (detected via dependencydiff --git a/packages/core/src/repowise/core/generation/tour.py b/packages/core/src/repowise/core/generation/tour.pynew file mode 100644index 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 stopsdiff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.pyindex 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_sessionfrom 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 modews_footer = _build_workspace_footer()if ws_footer:diff --git a/packages/ui/package.json b/packages/ui/package.jsonindex 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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({<spanclassName={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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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 (<codeclassName="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.tsxindex 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><Buttonvariant="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"><FirstFiveFilesfiles={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.tsxindex 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.tsxindex 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 changesuseEffect(() => {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 && (+ {(<buttononClick={() => 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.pynew file mode 100644index 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_DOCdiff --git a/tests/unit/generation/test_layers.py b/tests/unit/generation/test_layers.pynew file mode 100644index 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.pynew file mode 100644index 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 ""hi"" 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.pyindex 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 slotsdef 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.pynew file mode 100644index 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"]) == 10diff --git a/tests/unit/generation/test_selection_budget.py b/tests/unit/generation/test_selection_budget.pyindex 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 bottomfile 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, dicfor 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.pynew file mode 100644index 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