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(generation): render every wiki page type without an LLM (#972)
Raghav Chamadiyab5a9293cf978
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.pyindex d5bc07c94..1c44d80ad 100644--- a/packages/core/src/repowise/core/generation/models.py+++ b/packages/core/src/repowise/core/generation/models.py@@ -185,6 +185,17 @@ class GenerationConfig:tier2_tail_cap: int | None = None# Optional directory allow-list (repo-relative prefixes). None = all dirs.tier2_tail_dirs: tuple[str, ...] | None = None+ # ---- Fully deterministic generation (index-only mode) -------------+ # When True, EVERY page type is rendered from a Jinja template instead+ # of being written by a model: no provider call, no tokens, no key. The+ # selection budget is bypassed (a template page is free, so there is+ # nothing to ration) and every candidate in every bucket gets a page.+ # This is what ``repowise init --index-only`` produces: a complete,+ # navigable, searchable wiki whose prose is structural rather than+ # synthesised, with each page individually upgradable to an LLM page+ # later. Pages are marked ``provider_name="template"`` and+ # ``metadata["deterministic"]=True``, exactly like the tier-2 tail.+ deterministic: bool = Falsedef __post_init__(self) -> None:if self.embed_concurrency is None:diff --git a/packages/core/src/repowise/core/generation/page_generator/core.py b/packages/core/src/repowise/core/generation/page_generator/core.pyindex 2e58d7ffc..37fa25f6a 100644--- a/packages/core/src/repowise/core/generation/page_generator/core.py+++ b/packages/core/src/repowise/core/generation/page_generator/core.py@@ -40,6 +40,7 @@ from .decision_harvest import (HARVESTABLE_PAGE_TYPES,harvest_decisions,)+from .deterministic import DeterministicRenderMixin, onelinefrom .helpers import _extract_summary, _now_isofrom .pertype import PerTypeGenerationMixinfrom .prompts import SUPPORTED_LANGUAGES, SYSTEM_PROMPTS@@ -120,7 +121,7 @@ class PriorPage:content_hash: str = ""-class PageGenerator(PerTypeGenerationMixin):+class PageGenerator(PerTypeGenerationMixin, DeterministicRenderMixin):"""Generate wiki pages by rendering prompts and calling an LLM provider.Args:@@ -188,6 +189,9 @@ class PageGenerator(PerTypeGenerationMixin):autoescape=False,)self._jinja_env = jinja_env+ # Registered on whatever env we ended up with (including one a caller+ # injected), since deterministic templates depend on it.+ self._jinja_env.filters.setdefault("oneline", oneline)# ------------------------------------------------------------------# generate_all — orchestration (delegates to orchestrate.py)diff --git a/packages/core/src/repowise/core/generation/page_generator/deterministic.py b/packages/core/src/repowise/core/generation/page_generator/deterministic.pynew file mode 100644index 000000000..302b72eb8--- /dev/null+++ b/packages/core/src/repowise/core/generation/page_generator/deterministic.py@@ -0,0 +1,239 @@+"""Template-rendered (no-LLM) variants of every page type.++The tier-2 file page proved the shape: take the context the LLM path already+assembles, render it through a Jinja template, and stamp the result as+template-generated. This module generalises that to the rest of the wiki so+``repowise init --index-only`` can produce a complete page set without a key.++Each deterministic template lives at ``templates/deterministic/<name>``,+mirroring the prompt template it replaces (``module_page.j2`` ->+``deterministic/module_page.j2``), so the pairing needs no registry.++What these pages are and are not: every sentence is derived from the parsed+AST, the import graph, git history or the knowledge graph, so they are factual+by construction and need no hallucination check. What they cannot do is+explain *why* the code is shaped the way it is. Page types whose whole value+is that synthesis (api_contract, infra_page) render an honest structural stub+rather than pretending. Every page carries ``metadata["deterministic"]`` so+the UI can offer to rewrite it with a model.+"""++from __future__ import annotations++from typing import Any++import structlog++from ..models import GENERATION_LEVELS, GeneratedPage, compute_page_id, compute_source_hash+from .helpers import _extract_summary, _now_iso++log = structlog.get_logger(__name__)++# Rendered under templates/deterministic/. Keeping the leaf name identical to+# the prompt template makes the pairing obvious when reading either side.+_DET_PREFIX = "deterministic"++# Cap for free text folded into a list item or table cell. Long enough for a+# real summary sentence, short enough that a bullet stays a bullet.+_ONELINE_LIMIT = 200+++def oneline(value: object, limit: int = _ONELINE_LIMIT) -> str:+ """Flatten free text so it can sit inside a markdown list item or cell.++ Deterministic templates interpolate text the pipeline produced elsewhere:+ docstrings, page summaries, decision rationales. That text is routinely+ multi-paragraph, and a raw newline inside a bullet ends the list, dumping+ the remainder as body text and restarting the numbering after it. The LLM+ templates never had this problem because their output was a prompt, not+ page content.+ """+ text = " ".join(str(value or "").split())+ if len(text) > limit:+ text = text[: limit - 1].rstrip() + "…"+ return text+++class DeterministicRenderMixin:+ """Template-only ``_deterministic_*`` renderers, mixed into PageGenerator.++ Requires the host to provide ``_render``, ``_provider`` and ``_config``.+ """++ def _deterministic_page(+ self,+ *,+ page_type: str,+ target_path: str,+ title: str,+ template: str,+ doc_tier: int = 2,+ **render_kwargs: Any,+ ) -> GeneratedPage:+ """Render one template page and wrap it as a GeneratedPage.++ The mirror of ``_build_generated_page`` for the no-LLM path: same+ fields, zero tokens, ``provider_name="template"``.+ """+ content = self._render(f"{_DET_PREFIX}/{template}", style_prefix=False, **render_kwargs)+ now = _now_iso()+ # content_hash deliberately stays empty. The cross-run reuse gate keys+ # on model_name rather than provider_name, so stamping one here would+ # let a later LLM run serve this template content as if a model had+ # written it. Template pages are free to rebuild anyway.+ page = GeneratedPage(+ page_id=compute_page_id(page_type, target_path),+ page_type=page_type,+ title=title,+ content=content,+ summary=_extract_summary(content),+ source_hash=compute_source_hash(content),+ model_name=self._provider.model_name,+ provider_name="template",+ input_tokens=0,+ output_tokens=0,+ cached_tokens=0,+ generation_level=GENERATION_LEVELS[page_type],+ target_path=target_path,+ created_at=now,+ updated_at=now,+ )+ page.metadata["doc_tier"] = doc_tier+ page.metadata["deterministic"] = True+ return page++ # ------------------------------------------------------------------+ # Per-type renderers. One per LLM generate_* method it stands in for.+ # ------------------------------------------------------------------++ def _deterministic_symbol_spotlight(+ self, ctx: Any, target_path: str, title: str+ ) -> GeneratedPage:+ return self._deterministic_page(+ page_type="symbol_spotlight",+ target_path=target_path,+ title=title,+ template="symbol_spotlight.j2",+ ctx=ctx,+ )++ def _deterministic_module_page(+ self,+ ctx: Any,+ target_path: str,+ title: str,+ module_git_summary: dict | None,+ ) -> GeneratedPage:+ return self._deterministic_page(+ page_type="module_page",+ target_path=target_path,+ title=title,+ template="module_page.j2",+ ctx=ctx,+ module_git_summary=module_git_summary,+ )++ def _deterministic_scc_page(self, ctx: Any, scc_id: str, title: str) -> GeneratedPage:+ return self._deterministic_page(+ page_type="scc_page",+ target_path=scc_id,+ title=title,+ template="scc_page.j2",+ ctx=ctx,+ # Ranked by how many cross-edges each file carries: the highest+ # is the cheapest place to break the cycle. Computed here rather+ # than in Jinja because the template language makes grouping+ # painful and this is the one genuinely useful thing the page can+ # say that the LLM page says in prose.+ decouple_ranking=_rank_cycle_participants(ctx),+ )++ def _deterministic_repo_overview(+ self, ctx: Any, repo_name: str, title: str, repo_git_summary: dict | None+ ) -> GeneratedPage:+ return self._deterministic_page(+ page_type="repo_overview",+ target_path=repo_name,+ title=title,+ template="repo_overview.j2",+ ctx=ctx,+ repo_git_summary=repo_git_summary,+ )++ def _deterministic_architecture_diagram(+ self, ctx: Any, repo_name: str, title: str, overview_mermaid: str | None+ ) -> GeneratedPage:+ return self._deterministic_page(+ page_type="architecture_diagram",+ target_path=repo_name,+ title=title,+ template="architecture_diagram.j2",+ ctx=ctx,+ # Already structural on the LLM path too, where it overwrites+ # whatever diagram the model drew. Here it is simply the diagram.+ overview_mermaid=overview_mermaid or "",+ )++ def _deterministic_layer_page(self, ctx: Any, title: str) -> GeneratedPage:+ return self._deterministic_page(+ page_type="layer_page",+ target_path=ctx.layer_id,+ title=title,+ template="layer_page.j2",+ ctx=ctx,+ )++ def _deterministic_api_contract(self, ctx: Any, file_path: str, title: str) -> GeneratedPage:+ return self._deterministic_page(+ page_type="api_contract",+ target_path=file_path,+ title=title,+ template="api_contract.j2",+ ctx=ctx,+ )++ def _deterministic_infra_page(self, ctx: Any, file_path: str, title: str) -> GeneratedPage:+ return self._deterministic_page(+ page_type="infra_page",+ target_path=file_path,+ title=title,+ template="infra_page.j2",+ ctx=ctx,+ )++ def _deterministic_onboarding_page(+ self, spec: Any, ctx: Any, target_path: str+ ) -> GeneratedPage:+ page = self._deterministic_page(+ page_type="onboarding",+ target_path=target_path,+ title=spec.title,+ template=f"onboarding/{spec.template}",+ ctx=ctx,+ slot=spec.slot,+ )+ page.metadata["subkind"] = spec.slot+ page.metadata["onboarding_slot"] = spec.slot+ return page+++def _rank_cycle_participants(ctx: Any) -> list[dict]:+ """Order a cycle's files by how many of its edges they carry.++ A file that both imports and is imported by the rest of the cycle is+ where the loop is tightest, so it is the first place to look when+ breaking it. Returns ``[{"path", "out", "in", "total"}]``, highest first.+ """+ counts: dict[str, dict[str, int]] = {f: {"out": 0, "in": 0} for f in ctx.files}+ for edge in ctx.cross_imports:+ src, dst = edge.get("from", ""), edge.get("to", "")+ if src in counts:+ counts[src]["out"] += 1+ if dst in counts:+ counts[dst]["in"] += 1+ ranked = [+ {"path": path, "out": c["out"], "in": c["in"], "total": c["out"] + c["in"]}+ for path, c in counts.items()+ ]+ ranked.sort(key=lambda r: (-r["total"], r["path"]))+ return rankeddiff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.pyindex e57ba2d5e..c66bda1ed 100644--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py@@ -249,10 +249,14 @@ class _GenerationRun:# Tiered doc generation: split the selected file pages into a full-LLM# tier-1 and a deterministic template-only tier-2. When tier1_top_n is# None this puts every selected page in tier-1 (no behaviour change).+ # A fully deterministic run has no tier-1 by definition: every file page+ # goes through the same template renderer, so force the cap to 0 rather+ # than making the tier split learn about the mode.+ tier1_cap = 0 if self.config.deterministic else getattr(self.config, "tier1_top_n", None)self.tier1_paths, self.tier2_paths = partition_file_tiers(self.sel_file_paths,self.pagerank,- getattr(self.config, "tier1_top_n", None),+ tier1_cap,kg_file_scores=kg_scores or None,)@@ -436,7 +440,7 @@ class _GenerationRun:if self.on_page_ready is not None:try:self.on_page_ready(result)- except Exception as exc: # noqa: BLE001+ except Exception as exc:log.debug("on_page_ready.failed", error=str(exc))# A page reused verbatim from the prior run already has an# identical vector in any store that survives across runs;diff --git a/packages/core/src/repowise/core/generation/page_generator/pertype.py b/packages/core/src/repowise/core/generation/page_generator/pertype.pyindex 8f0915b19..5a19172d5 100644--- a/packages/core/src/repowise/core/generation/page_generator/pertype.py+++ b/packages/core/src/repowise/core/generation/page_generator/pertype.py@@ -76,8 +76,12 @@ class PerTypeGenerationMixin:graph,source_bytes=(source_map or {}).get(parsed.file_info.path, b""),)- user_prompt = self._render("symbol_spotlight.j2", ctx=ctx)target = f"{parsed.file_info.path}::{symbol.name}"+ if self._config.deterministic:+ return self._deterministic_symbol_spotlight(+ ctx, target, f"Symbol: {symbol.qualified_name}"+ )+ user_prompt = self._render("symbol_spotlight.j2", ctx=ctx)response = await self._call_provider("symbol_spotlight", user_prompt, str(uuid.uuid4()), target_path=target)@@ -136,8 +140,12 @@ class PerTypeGenerationMixin:"most_active_file": most_active.get("file_path", ""),"most_active_commits_90d": most_active.get("commit_count_90d", 0),}- user_prompt = self._render("module_page.j2", ctx=ctx, module_git_summary=module_git_summary)page_target = target_path or module_path+ if self._config.deterministic:+ return self._deterministic_module_page(+ ctx, page_target, f"Module: {module_path}", module_git_summary+ )+ user_prompt = self._render("module_page.j2", ctx=ctx, module_git_summary=module_git_summary)response = await self._call_provider("module_page", user_prompt, str(uuid.uuid4()), target_path=page_target)@@ -157,6 +165,8 @@ class PerTypeGenerationMixin:file_contexts: list[FilePageContext],) -> GeneratedPage:ctx = self._assembler.assemble_scc_page(scc_id, scc_files, file_contexts)+ if self._config.deterministic:+ return self._deterministic_scc_page(ctx, scc_id, f"Circular Dependency: {scc_id}")user_prompt = self._render("scc_page.j2", ctx=ctx)response = await self._call_provider("scc_page", user_prompt, str(uuid.uuid4()), target_path=scc_id@@ -209,6 +219,10 @@ class PerTypeGenerationMixin:}if not repo_name:repo_name = getattr(repo_structure, "name", None) or "repo"+ if self._config.deterministic:+ return self._deterministic_repo_overview(+ ctx, repo_name, f"Repository Overview: {repo_name}", repo_git_summary+ )user_prompt = self._render("repo_overview.j2", ctx=ctx, repo_git_summary=repo_git_summary)response = await self._call_provider("repo_overview", user_prompt, str(uuid.uuid4()), target_path=repo_name@@ -234,6 +248,10 @@ class PerTypeGenerationMixin:ctx = self._assembler.assemble_architecture_diagram(graph, pagerank, community, sccs, repo_name)+ if self._config.deterministic:+ return self._deterministic_architecture_diagram(+ ctx, repo_name, f"Architecture Diagram: {repo_name}", overview_mermaid+ )user_prompt = self._render("architecture_diagram.j2", ctx=ctx)response = await self._call_provider("architecture_diagram", user_prompt, str(uuid.uuid4()), target_path=repo_name@@ -263,6 +281,10 @@ class PerTypeGenerationMixin:source_bytes: bytes,) -> GeneratedPage:ctx = self._assembler.assemble_api_contract(parsed, source_bytes)+ if self._config.deterministic:+ return self._deterministic_api_contract(+ ctx, parsed.file_info.path, f"API Contract: {parsed.file_info.path}"+ )user_prompt = self._render("api_contract.j2", ctx=ctx)response = await self._call_provider("api_contract", user_prompt, str(uuid.uuid4()), target_path=parsed.file_info.path@@ -291,9 +313,14 @@ class PerTypeGenerationMixin:log.debug("onboarding.gate_skipped", slot=spec.slot)return None+ target = _onboarding.target_path(spec.slot)+ if self._config.deterministic:+ # No grounding post-check: a template can only cite what the+ # context handed it, so there is nothing ungrounded to strip.+ return self._deterministic_onboarding_page(spec, ctx, target)+template_name = f"onboarding/{spec.template}"user_prompt = self._render(template_name, ctx=ctx, slot=spec.slot)- target = _onboarding.target_path(spec.slot)# Fold the onboarding generation version into the reuse hash so a# builder/template upgrade forces a one-time regen of cached pages.salt = _onboarding.ONBOARDING_GENERATION_VERSION@@ -344,11 +371,15 @@ class PerTypeGenerationMixin:self,ctx: LayerPageContext,) -> GeneratedPage:- user_prompt = self._render("layer_page.j2", ctx=ctx)# target_path = the layer's STABLE slug id, so the page key survives# the post-generation LLM rename of ``layer_name``. The title still# uses the (heuristic) display name.target = ctx.layer_id+ if self._config.deterministic:+ # The template embeds ctx.diagram_mermaid itself, so there is no+ # post-generation embed_mermaid step on this path.+ return self._deterministic_layer_page(ctx, f"Layer: {ctx.layer_name}")+ user_prompt = self._render("layer_page.j2", ctx=ctx)response = await self._call_provider("layer_page", user_prompt, str(uuid.uuid4()), target_path=target)@@ -376,6 +407,10 @@ class PerTypeGenerationMixin:source_bytes: bytes,) -> GeneratedPage:ctx = self._assembler.assemble_infra_page(parsed, source_bytes)+ if self._config.deterministic:+ return self._deterministic_infra_page(+ ctx, parsed.file_info.path, f"Infrastructure: {parsed.file_info.path}"+ )user_prompt = self._render("infra_page.j2", ctx=ctx)response = await self._call_provider("infra_page", user_prompt, str(uuid.uuid4()), target_path=parsed.file_info.pathdiff --git a/packages/core/src/repowise/core/generation/selection/selector.py b/packages/core/src/repowise/core/generation/selection/selector.pyindex 4c3262adc..cf299382e 100644--- a/packages/core/src/repowise/core/generation/selection/selector.py+++ b/packages/core/src/repowise/core/generation/selection/selector.py@@ -244,7 +244,20 @@ def _build_symbol_candidates(if s > 0.0:scored.append((s, (p.file_info.path, sym.name)))scored.sort(key=lambda x: x[0], reverse=True)- return scored+ # A spotlight page is keyed by ``(file_path, symbol_name)``, but one file+ # can declare that pair twice: two classes in the same Java file each+ # with a ``toString``, two Rust impl blocks each with a ``new``. Left in,+ # the duplicates generate the same page id twice (the second silently+ # overwriting the first, having spent a full LLM call to do it). Keep the+ # highest-scoring occurrence; the list is already sorted, so first wins.+ seen: set[tuple[str, str]] = set()+ deduped: list[tuple[float, tuple[str, str]]] = []+ for score, target in scored:+ if target in seen:+ continue+ seen.add(target)+ deduped.append((score, target))+ return dedupeddef _build_curated_module_groups(@@ -536,6 +549,51 @@ def _ensure_landmarks(selected: list[str], landmarks: list[str]) -> list[str]:return sel+def _select_everything(+ files: list,+ modules: list,+ apis: list,+ infras: list,+ sccs: list,+ available: dict[str, int],+) -> Selection:+ """Return a Selection holding every scored candidate, budget bypassed.++ Used by fully deterministic (no-LLM) generation, where every page is free+ to produce. Candidates are already score-ordered, so the resulting page+ order still puts the most central files first.+ """+ sel = Selection(+ file_page_paths=[p for _, p in files],+ deterministic_tail_paths=[],+ # Symbol spotlights are the one bucket deterministic mode drops. A+ # template spotlight carries the signature, docstring and importer+ # list, all of which the file page for its containing file already+ # renders, so taking every candidate would triple the index for no+ # new information and dilute retrieval, the same failure the tier-2+ # tail's importance floor exists to avoid. On the fixture repo that is+ # 171 near-duplicate pages against 33 file pages. Users who want a+ # spotlight on a specific symbol can generate one on demand.+ symbol_spotlights=[],+ module_groups=[m for _, m in modules],+ api_contract_paths=[p for _, p in apis],+ infra_paths=[p for _, p in infras],+ scc_groups=[g for _, g in sccs],+ emit_repo_overview=True,+ emit_arch_diagram=True,+ allocation=BucketAllocation(+ file_page=available["file_page"],+ symbol_spotlight=0,+ module_page=available["module_page"],+ api_contract=available["api_contract"],+ infra_page=available["infra_page"],+ scc_page=available["scc_page"],+ ),+ )+ log.info("page_selection.complete", mode="deterministic", counts=sel.counts())+ return sel++def select_pages(inputs: SelectionInputs) -> Selection:"""Return the allow-set of pages to generate for one run.@@ -563,6 +621,15 @@ def select_pages(inputs: SelectionInputs) -> Selection:"scc_page": len(sccs),}+ # getattr, not attribute access: select_pages accepts any config-like+ # object (the cost estimator passes its own), so a new field must not+ # become a hard requirement on callers.+ if getattr(cfg, "deterministic", False):+ # Nothing to ration: a template page costs no tokens, so the coverage+ # budget has no job to do. Take every candidate in every bucket. The+ # tail stays empty because the file bucket already holds every file.+ return _select_everything(files, modules, apis, infras, sccs, available)+allocation = allocate_budget(budget=budget,candidates_per_bucket=available,diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/_footer.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/_footer.j2new file mode 100644index 000000000..923d41c6c--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/_footer.j2@@ -0,0 +1,8 @@++---++*This page was built from the code itself: parsed symbols, the import graph, git+history and the knowledge graph. It states what the code **is**, not why it is+that way. Rewrite it with a model to get the reasoning.*++<!-- Generated deterministically (no LLM). -->diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/api_contract.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/api_contract.j2new file mode 100644index 000000000..91ff863e5--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/api_contract.j2@@ -0,0 +1,38 @@+{#- Deterministic (no-LLM) API contract page.++ An honest stub, and marked as one. The assembled context is only a+ symbol-kind partition (functions -> "endpoints", classes -> "schemas"),+ not real route extraction, so a template cannot say what any of these+ accept, return or do. Listing the shapes and the source is the most this+ page can truthfully offer until a model rewrites it.+-#}+# API Contract: {{ ctx.file_path }}++**Language:** {{ ctx.language }} | **Operations:** {{ ctx.endpoints | length }} | **Types:** {{ ctx.schemas | length }}++## Overview++`{{ ctx.file_path }}` was classified as an API surface. It declares {{ ctx.endpoints | length }} callable{{ "s" if ctx.endpoints | length != 1 else "" }} and {{ ctx.schemas | length }} type{{ "s" if ctx.schemas | length != 1 else "" }}. The list below is taken from the parsed symbols, so it reflects what the file *declares*; request and response semantics are not derivable from structure alone.++{% if ctx.endpoints %}+## Operations+{% for e in ctx.endpoints %}+- `{{ e | oneline(160) }}`+{% endfor %}+{% endif %}++{% if ctx.schemas %}+## Types+{% for s in ctx.schemas %}+- `{{ s }}`+{% endfor %}+{% endif %}++{% if ctx.raw_content %}+## Source++```{{ ctx.language }}+{{ ctx.raw_content }}+```+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/architecture_diagram.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/architecture_diagram.j2new file mode 100644index 000000000..0ce7be8b9--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/architecture_diagram.j2@@ -0,0 +1,57 @@+{#- Deterministic (no-LLM) architecture map.++ The strongest of the deterministic pages: the mermaid diagram is built+ from the knowledge graph on BOTH paths, and on the LLM path it replaces+ whatever the model drew. So the only thing lost here is the prose around+ an already-structural artifact.++ ``overview_mermaid`` is the KG-derived diagram. When the KG can't produce+ one, fall back to drawing the top-ranked nodes and edges the context+ already carries.+-#}+# Architecture Diagram: {{ ctx.repo_name }}++## Architecture map++{% if overview_mermaid %}+```mermaid+{{ overview_mermaid }}+```+{% elif ctx.edges %}+```mermaid+graph TD+{% for src, dst in ctx.edges[:60] %}+ {{ src | replace("/", "_") | replace(".", "_") | replace("-", "_") }}["{{ src }}"] --> {{ dst | replace("/", "_") | replace(".", "_") | replace("-", "_") }}["{{ dst }}"]+{% endfor %}+```+{% else %}+_Not enough resolved dependencies to draw a map._+{% endif %}++## How to read this++Nodes are the most central files and modules by PageRank; arrows point from importer to imported. Groups are the architectural clusters dependency analysis found. The map covers the top {{ ctx.nodes | length }} node{{ "s" if ctx.nodes | length != 1 else "" }}, not the whole repository.++{% if ctx.communities %}+## Clusters+{% for cid, members in ctx.communities.items() %}+- **Cluster {{ cid }}** ({{ members | length }} shown){% for m in members %}+ - `{{ m }}`{% endfor %}+{% endfor %}+{% endif %}++{% if ctx.scc_groups %}+## Import cycles+Groups whose members import each other in a loop. Each has its own page.+{% for group in ctx.scc_groups %}+- {{ group | length }} files: {% for f in group[:5] %}`{{ f }}`{% if not loop.last %}, {% endif %}{% endfor %}{% if group | length > 5 %} and {{ group | length - 5 }} more{% endif %}+{% endfor %}+{% endif %}++{% if ctx.nodes %}+## Nodes on the map+{% for n in ctx.nodes %}+- `{{ n }}`+{% endfor %}+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/infra_page.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/infra_page.j2new file mode 100644index 000000000..95cf28564--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/infra_page.j2@@ -0,0 +1,31 @@+{#- Deterministic (no-LLM) infrastructure page.++ The thinnest context in the set: path, language, declared targets and the+ raw source. What makes an infra page useful (what the Dockerfile builds,+ which ports it opens, what the CI job gates on) needs either real+ per-format extraction or a model, and this path has neither. So the page+ is explicitly a source view rather than an explanation.+-#}+# Infrastructure: {{ ctx.file_path }}++**Type:** {{ ctx.language }}{% if ctx.targets %} | **Declared targets:** {{ ctx.targets | length }}{% endif %}++## Overview++`{{ ctx.file_path }}` is an infrastructure file ({{ ctx.language }}).{% if ctx.targets %} It declares {{ ctx.targets | length }} named target{{ "s" if ctx.targets | length != 1 else "" }}, listed below.{% endif %} Its behaviour is not derivable from structure, so the source is reproduced in full.++{% if ctx.targets %}+## Declared targets+{% for t in ctx.targets %}+- `{{ t }}`+{% endfor %}+{% endif %}++{% if ctx.raw_content %}+## Source++```{{ ctx.language }}+{{ ctx.raw_content }}+```+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/layer_page.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/layer_page.j2new file mode 100644index 000000000..f05223eda--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/layer_page.j2@@ -0,0 +1,69 @@+{#- Deterministic (no-LLM) architectural layer page.++ The per-layer mermaid diagram is already built structurally by+ ArchitectureMermaidBuilder, so on this path it is simply embedded+ inline rather than spliced in after generation.+-#}+# Layer: {{ ctx.layer_name }}++{% if ctx.layer_description %}{{ ctx.layer_description }}++{% endif %}**Files:** {{ ctx.file_count }}{% if ctx.entry_points %} | **Entry points:** {{ ctx.entry_points | length }}{% endif %}{% if ctx.edge_connectors %} | **Edge connectors:** {{ ctx.edge_connectors | length }}{% endif %}++## Overview++{% set _in = ctx.deps_in | length %}{% set _out = ctx.deps_out | length -%}+This layer holds {{ ctx.file_count }} file{{ "s" if ctx.file_count != 1 else "" }}.+{%- if _in and _out %} It is called by {{ _in }} layer{{ "s" if _in != 1 else "" }} and calls into {{ _out }}, so it sits mid-stack: work flows in from above and out to the layers below.+{%- elif _out %} It calls into {{ _out }} layer{{ "s" if _out != 1 else "" }} and nothing in this repository imports it, which puts it at the top of the stack.+{%- elif _in %} {{ _in }} layer{{ "s" if _in != 1 else "" }} import{{ "s" if _in == 1 else "" }} it and it imports none itself, which makes it foundational.+{%- else %} It has no resolved inter-layer edges, so it stands on its own.+{%- endif %}++{% if ctx.diagram_mermaid %}+## Architecture++```mermaid+{{ ctx.diagram_mermaid }}+```+{% endif %}++{% if ctx.entry_points %}+## Entry points+{% for ep in ctx.entry_points %}+- `{{ ep }}`+{% endfor %}+{% endif %}++{% if ctx.key_files %}+## Key files+{% for kf in ctx.key_files %}+- `{{ kf.path }}` *({{ kf.role }})*{% if kf.summary %}: {{ kf.summary | oneline }}{% endif %}+{% endfor %}+{% endif %}++{% if ctx.edge_connectors %}+## Edge connectors+Files where this layer meets the outside world.+{% for ec in ctx.edge_connectors %}+- `{{ ec }}`+{% endfor %}+{% endif %}++{% if ctx.deps_in or ctx.deps_out %}+## Neighbouring layers+{% for d in ctx.deps_in %}+- **{{ d.source_layer }}** imports this layer ({{ d.edge_count }} edge{{ "s" if d.edge_count != 1 else "" }})+{% endfor %}+{% for d in ctx.deps_out %}+- This layer imports **{{ d.target_layer }}** ({{ d.edge_count }} edge{{ "s" if d.edge_count != 1 else "" }})+{% endfor %}+{% endif %}++{% if ctx.tour_steps %}+## On the guided tour+{% for s in ctx.tour_steps %}+- Step {{ s.order }}: {{ s.title }}{% if s.description %}. {{ s.description | oneline }}{% endif %}+{% endfor %}+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/module_page.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/module_page.j2new file mode 100644index 000000000..09ae38a7e--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/module_page.j2@@ -0,0 +1,93 @@+{#- Deterministic (no-LLM) module page.++ The LLM version of this template is already almost a finished page; the+ model's job there is the Overview / Architecture Notes prose. Here the+ Overview is synthesised from the module's own signals (centrality, entry+ points, cluster) and the structural sections carry the rest.+-#}+# Module: {{ ctx.module_path }}++**Language:** {{ ctx.language }} | **Files:** {{ ctx.files | length }} | **Public symbols:** {{ ctx.public_symbols }} / {{ ctx.total_symbols }}{% if ctx.community_label %} | **Cluster:** {{ ctx.community_label }}{% if ctx.community_cohesion > 0 %} (cohesion {{ "%.2f"|format(ctx.community_cohesion) }}){% endif %}{% endif %}++## Overview++{% set _role = [] -%}+{%- if ctx.entry_points %}{% set _ = _role.append("hosts " ~ ctx.entry_points | length ~ " entry point" ~ ("s" if ctx.entry_points | length != 1 else "") ~ " into this subsystem") %}{% endif -%}+{%- if ctx.pagerank_mean is defined and ctx.pagerank_mean >= 0.005 %}{% set _ = _role.append("sits centrally in the import graph (mean PageRank " ~ "%.4f"|format(ctx.pagerank_mean) ~ ")") %}{% endif -%}+{%- if ctx.dependents %}{% set _ = _role.append("is imported by " ~ ctx.dependents | length ~ " other module" ~ ("s" if ctx.dependents | length != 1 else "")) %}{% endif -%}+{%- if ctx.dependencies %}{% set _ = _role.append("draws on " ~ ctx.dependencies | length ~ " internal module" ~ ("s" if ctx.dependencies | length != 1 else "")) %}{% endif -%}+`{{ ctx.module_path }}` groups {{ ctx.files | length }} {{ ctx.language }} file{{ "s" if ctx.files | length != 1 else "" }} exposing {{ ctx.public_symbols }} public symbol{{ "s" if ctx.public_symbols != 1 else "" }}.{% if _role %} It {{ _role | join("; ") }}.{% endif %}++{% if ctx.entry_points %}+## Entry Points+{% for ep in ctx.entry_points %}+- `{{ ep }}`+{% endfor %}+{% endif %}++## Files+{% if ctx.key_files %}+Highest-PageRank first: the order to read them in.+{% for kf in ctx.key_files %}+- `{{ kf.path }}`{% if kf.is_entry_point %} *(entry point)*{% endif %}{% if kf.summary %}: {{ kf.summary | oneline }}{% endif %}+{% endfor %}+{% else %}+{% for f in ctx.files %}+- `{{ f }}`+{% endfor %}+{% endif %}++{% if ctx.key_classes %}+## Type Hierarchy+{% for h in ctx.key_classes %}+- `{{ h.child }}` {{ h.kind }} `{{ h.parent }}`{% if h.parent_file is defined and h.parent_file %} (in `{{ h.parent_file }}`){% endif %}+{% endfor %}+{% endif %}++{% if ctx.decision_records %}+## Recorded decisions+{% for dr in ctx.decision_records[:5] %}+- **{{ dr.title | oneline(80) }}**: {{ dr.decision | oneline }}{% if dr.rationale %} *(Why: {{ dr.rationale | oneline }})*{% endif %}+{% endfor %}+{% endif %}++{% if ctx.dependencies %}+## Dependencies (modules this imports)+{% for dep in ctx.dependencies[:25] %}+- `{{ dep }}`+{% endfor %}+{% endif %}++{% if ctx.dependents %}+## Dependents (modules that import this)+{% for dep in ctx.dependents[:25] %}+- `{{ dep }}`+{% endfor %}+{% endif %}++{% if ctx.external_systems %}+## External systems used+{% for sys in ctx.external_systems[:15] %}+- `{{ sys.name }}`{% if sys.category and sys.category != 'library' %} *({{ sys.category }})*{% endif %}{% if sys.ecosystem %} ({{ sys.ecosystem }}){% endif %}+{% endfor %}+{% endif %}++{% if ctx.top_owners %}+## Ownership+{% for o in ctx.top_owners %}+- **{{ o.name }}**: primary maintainer of {{ o.file_count }} file{{ "s" if o.file_count != 1 else "" }}+{% endfor %}+{% endif %}++{% if ctx.dead_code_findings %}+## Potentially unused code+{% for finding in ctx.dead_code_findings[:10] %}+- `{{ finding.symbol_name or '?' }}`: {{ finding.reason | oneline }} ({{ (finding.confidence * 100) | int }}%{% if finding.safe_to_delete %}, cleanup-ready{% endif %})+{% endfor %}+{% endif %}++{% if module_git_summary %}+## Recent activity+Most active file: `{{ module_git_summary.most_active_file }}` ({{ module_git_summary.most_active_commits_90d }} commits in the last 90 days).+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/active_landscape.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/active_landscape.j2new file mode 100644index 000000000..b986eff01--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/active_landscape.j2@@ -0,0 +1,38 @@+{#- Deterministic (no-LLM) active landscape. Pure git history, so this page+ loses essentially nothing without a model.+-#}+# Active Landscape++Where `{{ ctx.repo_name }}` has actually been changing. {{ ctx.total_commits_90d }} commits touched {{ ctx.files_touched_90d }} files in the last 90 days{% if ctx.stable_file_count %}; {{ ctx.stable_file_count }} files have not moved at all{% endif %}.++{% if ctx.hot_files %}+## Files under active change++| File | Commits (90d) | Owner | Hotspot | Age |+| --- | --- | --- | --- | --- |+{% for f in ctx.hot_files -%}+| `{{ f.path }}` | {{ f.commit_count_90d }} | {{ (f.primary_owner or "unknown") | oneline(40) }} | {{ "yes" if f.is_hotspot else "no" }} | {{ f.age_days }}d |+{% endfor %}++A hotspot is a file that is both high-churn and structurally complex. Those are the ones where changes are most likely to go wrong.+{% endif %}++{% if ctx.hot_dirs %}+## Areas under active change++| Directory | Commits (90d) | Files | Hotspots |+| --- | --- | --- | --- |+{% for d in ctx.hot_dirs -%}+| `{{ d.path }}` | {{ d.total_commits_90d }} | {{ d.file_count }} | {{ d.hotspot_count }} |+{% endfor %}+{% endif %}++{% if ctx.dead_code_in_hot_files %}+## Unused code in files that keep changing++Worth deleting first: it is being carried through every edit.+{% for f in ctx.dead_code_in_hot_files[:15] %}+- `{{ f.get("symbol_name") or f.get("file_path") }}`{% if f.get("file_path") and f.get("symbol_name") %} in `{{ f.get("file_path") }}`{% endif %}{% if f.get("reason") %} ({{ f.get("reason") | oneline }}){% endif %}+{% endfor %}+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/codebase_map.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/codebase_map.j2new file mode 100644index 000000000..c183ea5f0--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/codebase_map.j2@@ -0,0 +1,51 @@+{#- Deterministic (no-LLM) codebase map. Directory tables render well from+ structure alone, so this page is near-parity with its LLM counterpart.+-#}+# Codebase Map++`{{ ctx.repo_name }}` holds {{ ctx.total_files }} files and {{ ctx.total_loc }} lines across {{ ctx.directories | length }} significant director{{ "ies" if ctx.directories | length != 1 else "y" }}.++{% if ctx.layer_order %}+## Architectural layers++Top to bottom, the order work flows through.+{% for l in ctx.layer_order %}+{{ loop.index }}. {{ l }}+{% endfor %}+{% endif %}++{% if ctx.entry_points %}+## Entry points+{% for ep in ctx.entry_points %}+- `{{ ep }}`+{% endfor %}+{% endif %}++## Directories++| Directory | Files | Language | Clusters |+| --- | --- | --- | --- |+{% for d in ctx.directories -%}+| `{{ d.path }}` | {{ d.file_count }} | {{ d.dominant_language }} | {{ (d.community_labels | join(", ")) | oneline(60) if d.community_labels else "none" }} |+{% endfor %}++{% for d in ctx.directories %}+{% if d.top_files or d.entry_points %}+### `{{ d.path }}`++{{ d.file_count }} {{ d.dominant_language }} file{{ "s" if d.file_count != 1 else "" }}.+{% if d.entry_points %}+Entry points:+{% for ep in d.entry_points %}+- `{{ ep }}`+{% endfor %}+{% endif %}+{% if d.top_files %}+Most central files:+{% for f in d.top_files %}+- `{{ f }}`+{% endfor %}+{% endif %}+{% endif %}+{% endfor %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/development_guide.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/development_guide.j2new file mode 100644index 000000000..68c2a909a--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/development_guide.j2@@ -0,0 +1,42 @@+{#- Deterministic (no-LLM) development guide. The conventions here are mined+ from file naming and directory shape, so they are observations rather+ than rules. Worded that way on purpose.+-#}+# Development Guide++Conventions observed in `{{ ctx.repo_name }}` by looking at how files are named and arranged. These are patterns the codebase already follows, not rules anyone wrote down.++{% if ctx.suffix_patterns %}+## Naming patterns++| Suffix | Files | Examples |+| --- | --- | --- |+{% for p in ctx.suffix_patterns -%}+| `{{ p.suffix }}` | {{ p.file_count }} | {% for e in p.examples[:3] %}`{{ e }}`{% if not loop.last %}, {% endif %}{% endfor %} |+{% endfor %}++A new file that fits one of these categories should follow the matching suffix.+{% endif %}++{% if ctx.test_mirror %}+## Where tests live++Tests sit under `{{ ctx.test_mirror.test_root }}`, mirroring the source tree: {{ ctx.test_mirror.matched_files }} of {{ ctx.test_mirror.source_files }} source files have a matching test path. A new source file's test belongs at the mirrored path under `{{ ctx.test_mirror.test_root }}`.+{% endif %}++{% if ctx.parallel_dirs %}+## Directories that move together++These sit at the same level and tend to be structured alike, so a change in one usually has a counterpart in the others.+{% for d in ctx.parallel_dirs %}+- `{{ d }}`+{% endfor %}+{% endif %}++{% if ctx.entry_points %}+## Entry points to run+{% for ep in ctx.entry_points %}+- `{{ ep }}`+{% endfor %}+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/getting_started.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/getting_started.j2new file mode 100644index 000000000..cba35ffae--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/getting_started.j2@@ -0,0 +1,46 @@+{#- Deterministic (no-LLM) getting started.++ README sections are quoted rather than rewritten: the repo's own setup+ instructions are more reliable than anything derivable from structure,+ and quoting keeps the page honest about where the text came from.+-#}+# Getting Started++{% if ctx.package_managers %}+## Toolchain++`{{ ctx.repo_name }}` is managed with {% for pm in ctx.package_managers %}**{{ pm }}**{% if not loop.last %}, {% endif %}{% endfor %}. Install dependencies with your usual command for {{ ctx.package_managers[0] }} before anything else.+{% endif %}++{% if ctx.entry_points %}+## Entry points+{% for ep in ctx.entry_points %}+- `{{ ep }}`+{% endfor %}+{% endif %}++{% if ctx.readme_sections %}+## From the README++Quoted verbatim from the repository's own README.+{% for s in ctx.readme_sections %}+### {{ s.heading }}++{{ s.body | trim }}+{% endfor %}+{% endif %}++{% if ctx.runtime_dependencies %}+## Runtime dependencies+{% for d in ctx.runtime_dependencies[:30] %}+- `{{ d.name }}`{% if d.version %} {{ d.version }}{% endif %}+{% endfor %}+{% endif %}++{% if ctx.dev_dependencies %}+## Development dependencies+{% for d in ctx.dev_dependencies[:30] %}+- `{{ d.name }}`{% if d.version %} {{ d.version }}{% endif %}+{% endfor %}+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/guided_tour.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/guided_tour.j2new file mode 100644index 000000000..2f410b2e2--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/guided_tour.j2@@ -0,0 +1,30 @@+{#- Deterministic (no-LLM) guided tour.++ Stop order, kind and the per-stop `reason` strings are all produced by+ generation/tour.py, so this page is close to its LLM counterpart. What a+ model adds is the connective narration between stops ("the parser from+ step 2 hands its output to..."), which structure cannot supply.+-#}+# Guided Tour++A reading order through `{{ ctx.repo_name }}`, {{ ctx.stops | length }} stops long. Each stop is picked by how much of the codebase depends on it and how early it sits in the import graph, so following them in order means you rarely meet a name before it has been introduced.++{% if ctx.layer_order %}+**Layer order:** {% for l in ctx.layer_order %}{{ l }}{% if not loop.last %} → {% endif %}{% endfor %}+{% endif %}++{% for stop in ctx.stops %}+## {{ stop.order }}. {{ stop.title }}++`{{ stop.target_path }}` *({{ stop.kind }})*++{{ stop.reason | oneline(300) }}+{% if stop.summary %}+{{ stop.summary }}+{% endif %}+{% endfor %}++## Where to go next++Read the layer pages for the architectural spine, then the module pages for the areas you will work in.+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/how_it_works.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/how_it_works.j2new file mode 100644index 000000000..b6184eb30--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/how_it_works.j2@@ -0,0 +1,57 @@+{#- Deterministic (no-LLM) how it works.++ The other page where synthesis is the product. The traced flows below are+ real (call/import paths out of each entry point), but a template can only+ list the hops, not say what happens at each one. Framed accordingly.+-#}+# How It Works++Traced from the entry points outward: which files each run touches, in order. What happens at each hop is not derivable from the call graph, so this page shows the shape of execution rather than the behaviour.++## Shape++`{{ ctx.repo_name }}` looks like {{ "an" if ctx.archetype[0] in "aeiou" else "a" }} **{{ ctx.archetype }}**{% if ctx.archetype_evidence %}, based on:+{% for e in ctx.archetype_evidence %}+- {{ e }}+{% endfor %}+{% else %}.+{% endif %}++{% if ctx.entry_points %}+## Entry points+{% for ep in ctx.entry_points %}+- `{{ ep }}`+{% endfor %}+{% endif %}++{% if ctx.flows %}+## Traced flows+{% for f in ctx.flows %}+{# entry_point is empty for symbol-rooted flows. Fall back to the first hop+ rather than emitting an empty heading, and drop it from the step list+ below so the heading is not immediately repeated as step 1. #}+{% set root = f.entry_point or (f.hops[0] if f.hops else "") %}+{% set steps = f.hops if f.entry_point else f.hops[1:] %}+### From `{{ root or "an unnamed entry point" }}`++{% if steps %}+{% for h in steps %}+{{ loop.index }}. `{{ h }}`+{% endfor %}+{% else %}+_No downstream hops resolved._+{% endif %}+{% endfor %}+{% endif %}++{% if ctx.kg_tour_steps %}+## Reading order++The guided tour walks these in sequence.+{% for s in ctx.kg_tour_steps %}+{{ loop.index }}. {{ s.title }}{% if s.description %}. {{ s.description | oneline }}{% endif %}+{% for nid in s.nodeIds[:3] %} - `{{ nid | replace("file:", "") }}`+{% endfor %}+{% endfor %}+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/key_concepts.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/key_concepts.j2new file mode 100644index 000000000..36ed9e373--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/onboarding/key_concepts.j2@@ -0,0 +1,49 @@+{#- Deterministic (no-LLM) key concepts.++ One of the two onboarding pages where the synthesis IS the product: the+ LLM version explains what each concept means and how they relate. A+ template can only point at the symbols the graph says matter most. Framed+ as a starting list rather than an explanation, so the gap is visible.+-#}+# Key Concepts++The types and functions the rest of `{{ ctx.repo_name }}` leans on most, ranked by how many files across the codebase reach for them. This is a list of what to learn, not yet an explanation of it.++{% if ctx.layer_order %}+**Layers these sit in:** {% for l in ctx.layer_order %}{{ l }}{% if not loop.last %} → {% endif %}{% endfor %}+{% endif %}++{% if ctx.concept_symbols %}+## Core symbols+{% for s in ctx.concept_symbols %}+### `{{ s.name }}`++**{{ s.kind }}** in `{{ s.file_path }}`{% if s.cluster %} · {{ s.cluster }}{% endif %}{% if s.cross_file_callers %} · used from {{ s.cross_file_callers }} other file{{ "s" if s.cross_file_callers != 1 else "" }}{% endif %}++{% if s.docstring %}{{ s.docstring | oneline(400) }}{% else %}_No docstring._{% endif %}+{% endfor %}+{% endif %}++{% if ctx.relations %}+## How they connect+{% for r in ctx.relations %}+- `{{ r.source }}` {{ r.kind }} `{{ r.target }}`+{% endfor %}+{% endif %}++{% if ctx.community_labels %}+## Vocabulary from the clusters++Dependency analysis named these groups. Their names are usually the codebase's own words for its parts.+{% for c in ctx.community_labels %}+- {{ c }}+{% endfor %}+{% endif %}++{% if ctx.decision_titles %}+## Decisions worth knowing early+{% for d in ctx.decision_titles %}+- {{ d | oneline(80) }}+{% endfor %}+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/repo_overview.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/repo_overview.j2new file mode 100644index 000000000..f8eb9f2c0--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/repo_overview.j2@@ -0,0 +1,92 @@+{#- Deterministic (no-LLM) repository overview.++ This is the weakest of the deterministic pages, and deliberately so. The+ one thing the LLM version contributes that matters is the opening+ sentence answering "what does this repository do, end-to-end?", and no+ template can derive intent from structure. Rather than bluff, the summary+ below states what the repo is *made of* and points at the entry points to+ read. It is the page most worth upgrading first.+-#}+# Repository Overview: {{ ctx.repo_name }}++**Files:** {{ ctx.total_files }} | **Lines:** {{ ctx.total_loc }}{% if ctx.is_monorepo %} | **Monorepo:** {{ ctx.packages | length }} packages{% endif %}{% if ctx.circular_dependency_count > 0 %} | **Import cycles:** {{ ctx.circular_dependency_count }}{% endif %}++## Project Summary++{% set _langs = ctx.language_distribution.items() | list -%}+`{{ ctx.repo_name }}` is a {% if ctx.is_monorepo %}multi-package {% endif %}+{%- if _langs %}{{ _langs[0][0] }} {% endif %}codebase of {{ ctx.total_files }} files+{%- if ctx.is_monorepo %}, split across {{ ctx.packages | length }} packages{% endif %}.+{%- if ctx.entry_points %} Execution starts at {% for ep in ctx.entry_points[:3] %}`{{ ep }}`{% if not loop.last %}, {% endif %}{% endfor %}{% if ctx.entry_points | length > 3 %} and {{ ctx.entry_points | length - 3 }} other entry point{{ "s" if ctx.entry_points | length - 3 != 1 else "" }}{% endif %}.{% endif %}+{%- if ctx.communities %} Dependency analysis splits it into {{ ctx.communities | length }} clusters{% set _named = ctx.communities | selectattr("label") | list %}{% if _named %}, led by {% for c in _named[:3] %}**{{ c.label }}**{% if not loop.last %}, {% endif %}{% endfor %}{% endif %}.{% endif %}+{%- if ctx.external_systems %} It builds on {{ ctx.external_systems | length }} external {{ "dependency" if ctx.external_systems | length == 1 else "dependencies" }}, including {% for s in ctx.external_systems[:5] %}`{{ s.name }}`{% if not loop.last %}, {% endif %}{% endfor %}.{% endif %}++{% if ctx.packages %}+## Packages+{% for pkg in ctx.packages %}+- **{{ pkg.name }}** (`{{ pkg.path }}`, {{ pkg.language }})+{% endfor %}+{% endif %}++{% if ctx.entry_points %}+## Entry Points+Start here when reading the codebase.+{% for ep in ctx.entry_points %}+- `{{ ep }}`+{% endfor %}+{% endif %}++{% if ctx.execution_flows %}+## Primary Execution Flows+{% for f in ctx.execution_flows %}+- `{{ f.entry_point }}`{% if f.trace_length %} ({{ f.trace_length }} steps){% endif %}+{% endfor %}+{% endif %}++{% if ctx.communities %}+## Architectural Clusters+Groups of files that depend on each other far more than on the rest of the repo.+{% for c in ctx.communities %}+- **{{ (c.label or "Cluster " ~ c.id) | oneline(60) }}**: {{ c.size }} files (cohesion {{ c.cohesion }})+{% endfor %}+{% endif %}++{% if ctx.top_files_by_pagerank %}+## Most Central Files+Ranked by PageRank over the import graph: the files most of the codebase ultimately depends on.+{% for item in ctx.top_files_by_pagerank %}+- `{{ item.path }}` ({{ "%.4f"|format(item.score) }})+{% endfor %}+{% endif %}++{% if ctx.language_distribution %}+## Languages+{% for lang, pct in ctx.language_distribution.items() %}+- {{ lang }}: {{ "%.1f"|format(pct * 100) }}%+{% endfor %}+{% endif %}++{% if ctx.external_systems %}+## External Systems+{% for sys in ctx.external_systems[:25] %}+- `{{ sys.name }}`{% if sys.category and sys.category != 'library' %} *({{ sys.category }})*{% endif %}{% if sys.ecosystem %} ({{ sys.ecosystem }}){% endif %}+{% endfor %}+{% endif %}++{% if ctx.decision_records %}+## Recorded Decisions+{% for dr in ctx.decision_records[:8] %}+- **{{ dr.title | oneline(80) }}**: {{ dr.decision | oneline }}{% if dr.rationale %} *(Why: {{ dr.rationale | oneline }})*{% endif %}+{% endfor %}+{% endif %}++{% if repo_git_summary %}+## Codebase health signals+- **Hotspots:** {{ repo_git_summary.hotspot_count }} files are both high-churn and high-complexity+- **Stable core:** {{ repo_git_summary.stable_count }} files unchanged in 90+ days+{% if repo_git_summary.top_churn_files %}- **Most changed (90d):** {% for f in repo_git_summary.top_churn_files[:3] %}`{{ f }}`{% if not loop.last %}, {% endif %}{% endfor %}+{% endif %}+{%- if repo_git_summary.oldest_file %}- **Oldest file:** `{{ repo_git_summary.oldest_file }}` ({{ repo_git_summary.oldest_file_age_days }} days)+{% endif %}+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/scc_page.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/scc_page.j2new file mode 100644index 000000000..4e1288232--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/scc_page.j2@@ -0,0 +1,47 @@+{#- Deterministic (no-LLM) circular-dependency page.++ The context here is entirely structural, so this page loses almost+ nothing against its LLM counterpart. The one thing a model adds is+ advice on breaking the cycle; the decouple ranking below is the+ structural stand-in for it.+-#}+# Circular Dependency: {{ ctx.scc_id }}++{{ ctx.files | length }} files import each other in a loop, directly or transitively. Nothing in this group can be loaded, tested or extracted without the rest of it.++## Files in the cycle+{% for f in ctx.files %}+- `{{ f }}`+{% endfor %}++{% if ctx.cross_imports %}+## The loop+{% for edge in ctx.cross_imports %}+- `{{ edge.from }}` → `{{ edge.to }}`+{% endfor %}+{% endif %}++{% if decouple_ranking %}+## Where to break it++Ranked by how many of the cycle's edges each file carries. The file at the top is the most entangled, so it is usually where an extracted interface or a moved import buys the most.++| File | Imports in cycle | Imported by | Total |+| --- | --- | --- | --- |+{% for r in decouple_ranking -%}+| `{{ r.path }}` | {{ r.out }} | {{ r["in"] }} | {{ r.total }} |+{% endfor %}+{% endif %}++{% if ctx.member_symbols %}+## Symbols defined in the cycle+{% for m in ctx.member_symbols %}+### `{{ m.file_path }}`+{% for s in m.symbols[:15] %}+- `{{ s.name }}`{% if s.signature %}: `{{ s.signature | oneline(120) }}`{% endif %}+{% endfor %}+{% endfor %}+{% endif %}++**Total symbols in cycle:** {{ ctx.total_symbols }}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/generation/templates/deterministic/symbol_spotlight.j2 b/packages/core/src/repowise/core/generation/templates/deterministic/symbol_spotlight.j2new file mode 100644index 000000000..cb940b0d3--- /dev/null+++ b/packages/core/src/repowise/core/generation/templates/deterministic/symbol_spotlight.j2@@ -0,0 +1,50 @@+{#- Deterministic (no-LLM) symbol spotlight.++ Note the wording around callers: ``ctx.callers`` holds files that import+ the containing module, not verified call sites. The LLM template hedges+ the same way; a template that claimed otherwise would over-state what the+ graph actually knows.+-#}+# {{ ctx.qualified_name }}++**Kind:** {{ ctx.kind }}{% if ctx.is_async %} (async){% endif %} | **Defined in:** `{{ ctx.file_path }}`{% if ctx.complexity_estimate %} | **Estimated complexity:** {{ ctx.complexity_estimate }}{% endif %}++{% if ctx.signature %}+```+{{ ctx.signature }}+```+{% endif %}++## Overview++{% if ctx.docstring %}{{ ctx.docstring | trim }}+{% else %}`{{ ctx.symbol_name }}` is {{ "an" if ctx.kind and ctx.kind[0] in "aeiou" else "a" }} {{ ctx.kind or "symbol" }} defined in `{{ ctx.file_path }}`. It carries no docstring.{% endif %}++{% if ctx.decorators %}+## Decorators+{% for d in ctx.decorators %}+- `{{ d }}`+{% endfor %}+{% endif %}++{% if ctx.callers %}+## Where it is used++{{ ctx.callers | length }} file{{ "s" if ctx.callers | length != 1 else "" }} import the module that defines it. These are import-level references, not confirmed call sites.+{% for c in ctx.callers %}+- `{{ c }}`+{% endfor %}+{% else %}+## Where it is used++No importers of the defining module were resolved.+{% endif %}++{% if ctx.source_body %}+## Implementation++```+{{ ctx.source_body }}+```+{% endif %}+{% include "deterministic/_footer.j2" %}diff --git a/packages/core/src/repowise/core/providers/llm/template.py b/packages/core/src/repowise/core/providers/llm/template.pynew file mode 100644index 000000000..74585d00f--- /dev/null+++ b/packages/core/src/repowise/core/providers/llm/template.py@@ -0,0 +1,50 @@+"""Null provider for fully deterministic (no-LLM) generation.++``repowise init --index-only`` renders every wiki page from a Jinja template,+so there is no model to call and often no API key to call it with. The+generation engine still expects a :class:`BaseProvider` for its identity+fields (``provider_name`` / ``model_name`` end up as page provenance), so this+stands in for one.++:meth:`generate` raises rather than returning a stub: a provider call on the+deterministic path means a page type forgot to branch, and a silent empty page+would be far harder to notice than a traceback.+"""++from __future__ import annotations++from repowise.core.providers.llm.base import BaseProvider, GeneratedResponse+from repowise.core.reasoning import ReasoningMode++# Matches the ``provider_name`` the tier-2 file-page renderer has always+# stamped, so "was this page written by a model?" stays a single check+# (``provider_name == "template"``) across both paths.+TEMPLATE_PROVIDER_NAME = "template"+++class TemplateProvider(BaseProvider):+ """Stands in for an LLM when every page is rendered from a template."""++ @property+ def provider_name(self) -> str:+ return TEMPLATE_PROVIDER_NAME++ @property+ def model_name(self) -> str:+ return TEMPLATE_PROVIDER_NAME++ async def generate(+ self,+ system_prompt: str,+ user_prompt: str,+ max_tokens: int = 4096,+ temperature: float = 0.3,+ request_id: str | None = None,+ reasoning: ReasoningMode = "auto",+ cache_hints: tuple = (),+ ) -> GeneratedResponse:+ raise RuntimeError(+ "TemplateProvider.generate() was called: a page type reached the "+ "LLM path during deterministic generation. Every generate_* method "+ "must branch on GenerationConfig.deterministic."+ )diff --git a/tests/integration/test_deterministic_generation.py b/tests/integration/test_deterministic_generation.pynew file mode 100644index 000000000..36bd200bf--- /dev/null+++ b/tests/integration/test_deterministic_generation.py@@ -0,0 +1,148 @@+"""Integration tests for fully deterministic (no-LLM) generation.++``repowise init --index-only`` renders every page type from a Jinja template+instead of calling a model. These tests run the real generation pipeline over+the sample_repo fixture with ``GenerationConfig.deterministic=True`` and a+provider that raises on any call, so a page type that forgets to branch fails+loudly rather than silently costing tokens.+"""++from __future__ import annotations++from pathlib import Path++import pytest++from repowise.core.generation.context_assembler import ContextAssembler+from repowise.core.generation.models import GenerationConfig+from repowise.core.generation.page_generator import PageGenerator+from repowise.core.ingestion.graph import GraphBuilder+from repowise.core.ingestion.models import PackageInfo, ParsedFile, RepoStructure+from repowise.core.ingestion.parser import ASTParser+from repowise.core.ingestion.traverser import FileTraverser+from repowise.core.providers.llm.template import TemplateProvider++SAMPLE_REPO = Path(__file__).parents[1] / "fixtures" / "sample_repo"++[email protected](scope="module")+async def deterministic_pages(tmp_path_factory):+ """Run generate_all() in deterministic mode and return the page list."""+ tmp = tmp_path_factory.mktemp("det_gen")++ traverser = FileTraverser(SAMPLE_REPO)+ parser = ASTParser()+ builder = GraphBuilder()+ parsed_files: list[ParsedFile] = []+ source_map: dict[str, bytes] = {}++ for fi in traverser.traverse():+ try:+ src = Path(fi.abs_path).read_bytes()+ parsed = parser.parse_file(fi, src)+ builder.add_file(parsed)+ parsed_files.append(parsed)+ source_map[fi.path] = src+ except Exception:+ pass++ builder.build()++ packages = [+ PackageInfo(name=d.name, path=d.name, language="unknown", entry_points=[], manifest_file="")+ for d in SAMPLE_REPO.iterdir()+ if d.is_dir()+ ]+ repo_structure = RepoStructure(+ is_monorepo=len(packages) > 1,+ packages=packages,+ root_language_distribution={"python": 0.7, "typescript": 0.3},+ total_files=len(parsed_files),+ total_loc=sum(+ len(source_map.get(p.file_info.path, b"").splitlines()) for p in parsed_files+ ),+ entry_points=[],+ )++ config = GenerationConfig(+ deterministic=True,+ max_concurrency=3,+ jobs_dir=str(tmp / "jobs"),+ )+ generator = PageGenerator(TemplateProvider(), ContextAssembler(config), config)++ return await generator.generate_all(+ parsed_files,+ source_map,+ builder,+ repo_structure,+ "sample_repo",+ job_system=None,+ )+++class TestDeterministicGeneration:+ def test_pages_generated(self, deterministic_pages):+ assert deterministic_pages, "deterministic run produced no pages"++ def test_no_provider_calls(self, deterministic_pages):+ """TemplateProvider.generate() raises, so reaching here proves no page+ type fell through to the LLM path."""+ assert all(p.provider_name == "template" for p in deterministic_pages)++ def test_zero_token_cost(self, deterministic_pages):+ for p in deterministic_pages:+ assert p.input_tokens == 0+ assert p.output_tokens == 0+ assert p.cached_tokens == 0++ def test_every_page_marked_deterministic(self, deterministic_pages):+ for p in deterministic_pages:+ assert p.metadata.get("deterministic") is True, p.page_id++ def test_every_page_has_content(self, deterministic_pages):+ for p in deterministic_pages:+ assert p.content.strip(), f"empty content for {p.page_id}"+ assert p.summary, f"empty summary for {p.page_id}"++ def test_no_duplicate_page_ids(self, deterministic_pages):+ ids = [p.page_id for p in deterministic_pages]+ assert len(ids) == len(set(ids))++ def test_every_page_carries_the_provenance_footer(self, deterministic_pages):+ """The footer is what tells a reader (and the UI) the page is+ structural rather than written, so no page may skip it."""+ for p in deterministic_pages:+ assert "Generated deterministically" in p.content, p.page_id++ def test_covers_multiple_page_types(self, deterministic_pages):+ """Deterministic mode is only worth shipping if it produces a whole+ wiki, not just file pages."""+ types = {p.page_type for p in deterministic_pages}+ assert "file_page" in types+ assert "repo_overview" in types+ assert "architecture_diagram" in types+ assert len(types) >= 4, f"only got {types}"++ def test_full_file_coverage(self, deterministic_pages):+ """The budget is bypassed, so every parsed code file should have a+ page, which is the whole point of the mode."""+ file_pages = [p for p in deterministic_pages if p.page_type == "file_page"]+ assert len(file_pages) >= 5+ # No page may land in the budget-dropped coverage tail: nothing was+ # dropped, so nothing should be tagged as tail (doc_tier 3).+ assert all(p.metadata.get("doc_tier") != 3 for p in file_pages)++ def test_content_hash_left_empty(self, deterministic_pages):+ """The cross-run reuse gate keys on model_name, not provider_name. A+ stamped content_hash here would let a later LLM run serve template+ content as if a model had written it."""+ for p in deterministic_pages:+ assert not p.content_hash, p.page_id++ def test_pages_are_not_prompts(self, deterministic_pages):+ """A template rendered through the prompt path would carry+ instructions to the model. Catch that leaking into page content."""+ for p in deterministic_pages:+ assert "Generate a complete wiki page" not in p.content, p.page_id+ assert not p.content.lstrip().startswith("You are "), p.page_iddiff --git a/tests/unit/generation/test_deterministic_templates.py b/tests/unit/generation/test_deterministic_templates.pynew file mode 100644index 000000000..bc3ca9ba4--- /dev/null+++ b/tests/unit/generation/test_deterministic_templates.py@@ -0,0 +1,243 @@+"""Render tests for deterministic templates the sample repo cannot reach.++``tests/integration/test_deterministic_generation.py`` covers the page types+the fixture repo actually produces. Four templates are unreachable there: the+layer page needs a knowledge graph, and three onboarding slots gate themselves+off on a fixture with no git history and no dependency manifest. Rendering+them here keeps a Jinja typo from shipping unnoticed.+"""++from __future__ import annotations++import pytest++from repowise.core.generation.context_assembler import ContextAssembler, LayerPageContext+from repowise.core.generation.models import GenerationConfig+from repowise.core.generation.onboarding.subkinds.active_landscape import (+ ActiveLandscapeContext,+ HotDir,+ HotFile,+)+from repowise.core.generation.onboarding.subkinds.development_guide import (+ DevelopmentGuideContext,+ SuffixPattern,+)+from repowise.core.generation.onboarding.subkinds.development_guide import (+ # Aliased so pytest does not try to collect it as a test class.+ TestMirror as _TestMirror,+)+from repowise.core.generation.onboarding.subkinds.getting_started import (+ GettingStartedContext,+ ReadmeSection,+)+from repowise.core.generation.page_generator import PageGenerator+from repowise.core.providers.llm.template import TemplateProvider+++def generator() -> PageGenerator:+ config = GenerationConfig(deterministic=True)+ return PageGenerator(TemplateProvider(), ContextAssembler(config), config)+++def test_layer_page_renders(generator):+ ctx = LayerPageContext(+ layer_name="Ingestion",+ layer_id="layer:ingestion",+ layer_description="Parses source files into ASTs.",+ file_count=7,+ key_files=[{"path": "src/parse.py", "role": "entry_point", "summary": "Parses files."}],+ deps_out=[{"target_layer": "Storage", "edge_count": 4}],+ deps_in=[{"source_layer": "CLI", "edge_count": 2}],+ # Exactly the shape KnowledgeGraphContext.get_file_context builds+ # (order/title/description). Inventing a shape here is how the first+ # version of this template shipped with a field that never exists.+ tour_steps=[{"order": 1, "title": "Parsing", "description": "Where parsing starts."}],+ entry_points=["src/parse.py"],+ edge_connectors=["src/io.py"],+ diagram_mermaid="flowchart LR\n a --> b",+ )+ page = generator._deterministic_layer_page(ctx, "Layer: Ingestion")++ assert page.page_id == "layer_page:layer:ingestion"+ assert page.provider_name == "template"+ assert page.input_tokens == 0+ assert "```mermaid" in page.content+ assert "flowchart LR" in page.content+ assert "**Storage**" in page.content+ assert "**CLI**" in page.content+ # Sits between two layers, so the overview should say so rather than+ # calling it foundational or top-of-stack.+ assert "mid-stack" in page.content+ assert "Step 1: Parsing. Where parsing starts." in page.content+ assert "Generated deterministically" in page.content+++def test_layer_page_without_diagram_renders(generator):+ """A layer with no KG diagram must still produce a usable page."""+ ctx = LayerPageContext(+ layer_name="Utilities",+ layer_id="layer:utilities",+ layer_description="",+ file_count=3,+ )+ page = generator._deterministic_layer_page(ctx, "Layer: Utilities")++ assert "```mermaid" not in page.content+ assert "stands on its own" in page.content+++def _onboarding_spec(slot: str, template: str):+ from repowise.core.generation.onboarding.registry import SubkindSpec++ return SubkindSpec(+ slot=slot,+ title=slot.replace("_", " ").title(),+ template=template,+ build_context=lambda _s: None,+ )+++def test_getting_started_renders(generator):+ ctx = GettingStartedContext(+ repo_name="demo",+ package_managers=["uv"],+ runtime_dependencies=[{"name": "httpx", "version": "0.27"}],+ dev_dependencies=[{"name": "pytest", "version": "9.0"}],+ readme_sections=[ReadmeSection(heading="Install", body="Run `uv sync`.")],+ entry_points=["src/main.py"],+ )+ page = generator._deterministic_onboarding_page(+ _onboarding_spec("getting_started", "getting_started.j2"), ctx, "onboarding/getting_started"+ )++ assert page.metadata["onboarding_slot"] == "getting_started"+ assert "**uv**" in page.content+ assert "Run `uv sync`." in page.content+ assert "`httpx`" in page.content+++def test_development_guide_renders(generator):+ ctx = DevelopmentGuideContext(+ repo_name="demo",+ suffix_patterns=[SuffixPattern(suffix="_cmd.py", examples=["a_cmd.py"], file_count=4)],+ test_mirror=_TestMirror(test_root="tests", matched_files=12, source_files=20),+ parallel_dirs=["packages/core", "packages/cli"],+ entry_points=["src/main.py"],+ )+ page = generator._deterministic_onboarding_page(+ _onboarding_spec("development_guide", "development_guide.j2"),+ ctx,+ "onboarding/development_guide",+ )++ assert "`_cmd.py`" in page.content+ assert "tests" in page.content+ assert "12 of 20" in page.content+++def test_active_landscape_renders(generator):+ ctx = ActiveLandscapeContext(+ repo_name="demo",+ total_commits_90d=120,+ files_touched_90d=45,+ hot_files=[+ HotFile(+ path="src/core.py",+ commit_count_90d=30,+ primary_owner="Ada",+ is_hotspot=True,+ age_days=400,+ )+ ],+ hot_dirs=[HotDir(path="src", total_commits_90d=90, hotspot_count=2, file_count=20)],+ dead_code_in_hot_files=[{"symbol_name": "old_fn", "file_path": "src/core.py"}],+ stable_file_count=8,+ )+ page = generator._deterministic_onboarding_page(+ _onboarding_spec("active_landscape", "active_landscape.j2"),+ ctx,+ "onboarding/active_landscape",+ )++ assert "120 commits touched 45 files" in page.content+ assert "`src/core.py`" in page.content+ assert "Ada" in page.content+ assert "old_fn" in page.content+++def test_symbol_spotlight_renders(generator):+ """Not reachable through generate_all (deterministic mode drops the+ spotlight bucket), but the renderer stays for on-demand generation, so+ it needs coverage of its own."""+ from repowise.core.generation.context_assembler import SymbolSpotlightContext++ ctx = SymbolSpotlightContext(+ symbol_name="parse_file",+ qualified_name="parser.ASTParser.parse_file",+ kind="method",+ signature="def parse_file(self, fi, src) -> ParsedFile",+ docstring="Parse one file into an AST.",+ file_path="src/parser.py",+ decorators=["@lru_cache"],+ is_async=False,+ complexity_estimate=7,+ callers=["src/pipeline.py"],+ source_body="def parse_file(self, fi, src):\n return ...",+ )+ page = generator._deterministic_symbol_spotlight(+ ctx, "src/parser.py::parse_file", "Symbol: parser.ASTParser.parse_file"+ )++ assert page.page_type == "symbol_spotlight"+ assert page.provider_name == "template"+ assert "Parse one file into an AST." in page.content+ assert "@lru_cache" in page.content+ # Callers are module importers, not verified call sites. The page must+ # not claim more than the graph knows.+ assert "not confirmed call sites" in page.content+++def test_symbol_spotlight_tolerates_missing_kind(generator):+ from repowise.core.generation.context_assembler import SymbolSpotlightContext++ ctx = SymbolSpotlightContext(+ symbol_name="x",+ qualified_name="x",+ kind="",+ signature="",+ docstring=None,+ file_path="a.py",+ decorators=[],+ is_async=False,+ complexity_estimate=0,+ callers=[],+ )+ page = generator._deterministic_symbol_spotlight(ctx, "a.py::x", "Symbol: x")+ assert "is a symbol defined in" in page.content+++def test_multiline_summaries_stay_inside_their_list_item(generator):+ """A raw newline in a bullet ends the markdown list, dumping the rest as+ body text. Page summaries are routinely multi-paragraph, so every text+ field folded into a list item runs through the oneline filter."""+ ctx = LayerPageContext(+ layer_name="Core",+ layer_id="layer:core",+ layer_description="",+ file_count=3,+ key_files=[+ {+ "path": "a.py",+ "role": "internal",+ "summary": "First line.\n\nSecond paragraph that would break the list.",+ },+ {"path": "b.py", "role": "internal", "summary": "Short."},+ ],+ )+ page = generator._deterministic_layer_page(ctx, "Layer: Core")++ body = page.content.split("## Key files", 1)[1]+ bullets = [ln for ln in body.splitlines() if ln.startswith("- ")]+ assert len(bullets) == 2, f"list broke apart: {bullets}"+ assert "First line. Second paragraph" in bullets[0]