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
fix(cli): keep the index-only wiki honest, current and free (#976)
Raghav Chamadiyab55bc6c08880
diff --git a/docs/reference/TELEMETRY.md b/docs/reference/TELEMETRY.mdindex b525b1885..c0e8f7bbe 100644--- a/docs/reference/TELEMETRY.md+++ b/docs/reference/TELEMETRY.md@@ -56,7 +56,7 @@ generation is used. Never exact counts, never repo or file names:|---|---|---|| `properties.file_count_bucket` | `500-999` | Repo size distribution (a range, not a count) || `properties.top_language` | `python` | Which languages to prioritise |-| `properties.docs_mode` | `true` / `false` | AI docs vs index-only adoption |+| `properties.docs_mode` | `none` / `deterministic` / `llm` | How the wiki was produced: not at all, from templates, or by a model. Sent as `true` / `false` by versions before template wikis existed || `properties.provider` / `properties.model` | `anthropic` / `claude-opus` | Which models generate docs || `properties.embedder` | `openai` | Which embedders are in use || `properties.pages_bucket` | `100-499` | Docs volume (a range) |diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.pyindex df735ecae..47730c116 100644--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py@@ -66,7 +66,7 @@ from repowise.cli.ui import (quick_repo_scan,should_offer_fast_mode,)-from repowise.core.docs_mode import docs_mode_state_fields+from repowise.core.docs_mode import docs_mode_state_fields, resolve_docs_modefrom repowise.core.generation.languages import SUPPORTED_LANGUAGESfrom repowise.core.generation.styles import DEFAULT_STYLE, list_styles, resolve_stylefrom repowise.core.reasoning import REASONING_MODES@@ -115,16 +115,20 @@ def _record_init_outcome(if isinstance(lang_dist, dict) and lang_dist:outcome["top_language"] = max(lang_dist.items(), key=lambda kv: kv[1])[0]+ # docs_mode carries the same three values as the state field of that+ # name. It used to be a bool, which collapsed "template wiki" and "no+ # wiki" into one number, and template runs are the ones worth counting.+ pages = getattr(result, "generated_pages", None) or []+ det = sum(1 for p in pages if getattr(p, "provider_name", "") == "template")if not effective_index_only and provider is not None:- outcome["docs_mode"] = True+ outcome["docs_mode"] = "llm"outcome["provider"] = getattr(provider, "provider_name", None)outcome["model"] = getattr(provider, "model_name", None)- pages = getattr(result, "generated_pages", None) or []+ else:+ outcome["docs_mode"] = "deterministic" if pages else "none"+ if pages:outcome["pages_bucket"] = telemetry.bucket_count(len(pages))- det = sum(1 for p in pages if getattr(p, "provider_name", "") == "template")outcome["deterministic_pages_bucket"] = telemetry.bucket_count(det)- else:- outcome["docs_mode"] = Falseif embedder_name_resolved:outcome["embedder"] = embedder_name_resolved@@ -146,7 +150,7 @@ def _run_deterministic_generation_phase(embedder_name_resolved: str,embedder_was_requested: bool,resume: bool,-) -> None:+) -> str:"""Render the whole wiki from templates, for ``init --index-only``.Every page type has a deterministic renderer, so an index-only run is no@@ -154,6 +158,9 @@ def _run_deterministic_generation_phase(from structure rather than written by a model. There is nothing toestimate and nothing to gate, since no provider is involved and the runcosts nothing, so this skips the coverage chooser the LLM phase runs.++ Returns the embedder actually used, which the caller persists so a later+ ``repowise update`` embeds the same way rather than re-deciding."""from repowise.core.generation import GenerationConfigfrom repowise.core.providers.llm.template import TemplateProvider@@ -177,6 +184,21 @@ def _run_deterministic_generation_phase("Generation","Building wiki pages from the code's structure (no model, no cost)",)+ # Both knobs only reach a model. Templates carry their own English prose+ # and render without the style directive, so saying so beats letting the+ # user find out from the output (and beats recording a style the pages do+ # not have, which would leave `restyle` thinking there is nothing to do).+ if language != "en":+ console.print(+ f" [dim]Templates are written in English, so [bold]--language "+ f"{language}[/bold] has no effect here. Run [bold]repowise update "+ "--full[/bold] to write the wiki with a model in that language.[/dim]"+ )+ if wiki_style != DEFAULT_STYLE:+ console.print(+ f" [dim]Wiki styles shape how a model writes, so [bold]--wiki-style "+ f"{wiki_style}[/bold] has no effect here.[/dim]"+ )if embedder != embedder_name_resolved:console.print(f" [dim]Not embedding with [bold]{embedder_name_resolved}[/bold]: it was "@@ -198,10 +220,11 @@ def _run_deterministic_generation_phase(provider=TemplateProvider(),gen_config=gen_config,concurrency=concurrency,- embedder_name_resolved=embedder_name_resolved,+ embedder_name_resolved=embedder,resume=resume,verbose=True,)+ return embedderdef _run_generation_phase(@@ -843,11 +866,15 @@ def init_command(exclude = adv["exclude"]include_submodules = adv.get("include_submodules", include_submodules)run_mode = adv.get("run_mode", run_mode)+ # Asked in both branches: an index-only run renders a wiki too,+ # and those pages embed like any other, so the answer applies+ # either way. Read outside the docs-only block or the index-only+ # run would show the user their choice and then ignore it.+ embedder_name = adv.get("embedder") or embedder_name# Generation knobs (only gathered when docs are on).if generate_docs:concurrency = adv["concurrency"]reasoning = adv.get("reasoning") or reasoning- embedder_name = adv.get("embedder") or embedder_nametest_run = adv["test_run"]tier1_top_n = adv.get("tier1_top_n")tier2_tail_enabled = adv.get("tier2_tail_enabled", True)@@ -925,11 +952,39 @@ def init_command(# resolve_embedder inferring one from an LLM key it found lying around.# The deterministic generation phase needs the distinction: it advertises# itself as costing nothing, so it will not put a hosted embedder on the- # user's bill unless they named it.- embedder_was_requested = bool(embedder_name) or bool(- os.environ.get("REPOWISE_EMBEDDER", "").strip()+ # user's bill unless they named it. A repo whose config already names one+ # counts as asked: the choice was made on an earlier run, and silently+ # dropping to the mock here would re-embed the whole store at a different+ # vector width, which the LanceDB writer resolves by dropping the table.+ embedder_was_requested = (+ bool(embedder_name)+ or bool(os.environ.get("REPOWISE_EMBEDDER", "").strip())+ or bool(config.get("embedder")))+ # A template wiki overwrites a model-written one page for page: the upsert+ # replaces content and stamps provider_name="template", keeping the old+ # text only as a version snapshot. That is a fine outcome when it is what+ # the user meant and a bad surprise when they were reaching for a re-index,+ # so ask. Non-interactive runs refuse rather than guess.+ # ``--yes`` and ``--force`` both mean "do not ask me", which is the answer+ # here as much as at the cost gate.+ _prior_docs_mode = resolve_docs_mode(load_state(repo_path))+ if index_only and _prior_docs_mode == "llm" and not (force or yes):+ console.print(+ "\n[yellow]This repo already has a model-written wiki.[/yellow] "+ "Indexing without a model\nrewrites every page from templates; the "+ "written versions stay in page history."+ )+ if not sys.stdin.isatty():+ raise click.ClickException(+ "Refusing to replace a model-written wiki with template pages. "+ "Re-run with --yes to confirm, or drop --index-only."+ )+ if not click.confirm(" Replace the written wiki with template pages?", default=False):+ console.print("[dim]Nothing changed.[/dim]")+ return+# ---- Resolve provider ----provider = Nonedecision_provider = None@@ -1107,6 +1162,9 @@ def init_command(show_analysis_summary(result)# ---- Phase 3: Generation ----+ # The embedder the template wiki was actually built with, persisted below+ # so `repowise update` reuses it. None means no template wiki was rendered.+ _index_only_embedder: str | None = None# Both modes generate. Index-only renders from templates; full mode picks# a coverage level, estimates the spend and prompts a model.#@@ -1124,7 +1182,7 @@ def init_command("to write it with a model.[/dim]")elif index_only:- _run_deterministic_generation_phase(+ _index_only_embedder = _run_deterministic_generation_phase(repo_path=repo_path,result=result,total_phases=total_phases,@@ -1156,11 +1214,24 @@ def init_command(skip_tests=skip_tests,skip_infra=skip_infra,embedder_name_resolved=embedder_name_resolved,- resume=resume,+ # Resume seeds "already done" from the page ids in the vector+ # store, and a completed template wiki put one there for every+ # file. Resuming against it would skip the entire model run and+ # say nothing, so a template wiki is never a run to continue.+ resume=resume and _prior_docs_mode != "deterministic",)if gen_stop:return- if cost_declined:+ if cost_declined and _prior_docs_mode == "llm":+ # The repo already has written pages. Declining the price of new+ # ones is not a request to replace the old ones with templates,+ # which is what the fallback below would do.+ cost_declined = False+ console.print(+ " [dim]Keeping the wiki this repo already has. Nothing was "+ "generated and nothing was replaced.[/dim]"+ )+ elif cost_declined:# Declining the gate used to mean leaving with no wiki at all.# It only ever meant "not at that price", so fall back to the# free renderer rather than to nothing.@@ -1169,7 +1240,7 @@ def init_command("[bold]repowise update --full[/bold] to write it with a ""model later.[/dim]")- _run_deterministic_generation_phase(+ _index_only_embedder = _run_deterministic_generation_phase(repo_path=repo_path,result=result,total_phases=total_phases,@@ -1210,13 +1281,17 @@ def init_command(# re-passing the flag. Written before any config_fingerprint is computed# below so the first update doesn't false-positive on a config change. The# default is omitted to keep config files tidy — only an override is recorded.- if wiki_style != DEFAULT_STYLE:+ #+ # A template wiki records neither style nor language: it has neither, and+ # recording them would make `restyle` believe the pages are already in that+ # style and refuse the very run that would put them there.+ if wiki_style != DEFAULT_STYLE and not effective_index_only:save_config_partial(repo_path, wiki_style=wiki_style)# Persist the output language so `repowise update` regenerates changed# pages in the same language. Written only when the run's language differs# from what config.yaml already holds; the default stays unrecorded.- if language != config.get("language", "en"):+ if language != config.get("language", "en") and not effective_index_only:save_config_partial(repo_path, language=language)# ---- Post-run: config, state, MCP, editor project files ----@@ -1278,10 +1353,24 @@ def init_command(save_knowledge_graph_json(repo_path, kg)if effective_index_only or provider is None:# Index-only mode skips save_config(); persist exclude_patterns/commit_limit here.+ # The embedder rides along now that this mode produces pages: without+ # it `repowise update` would re-resolve from the environment and could+ # start embedding, at a different width, a store this run deliberately+ # built with the mock.+ # ``embedding_model`` rides with it, the way save_config() writes the+ # pair: `serve` pins the model from it, and the store-format upgrade+ # check reads it to notice an embedder change. Half the pair is not+ # enough for either.+ from repowise.cli.providers.embedders import resolve_embedding_model+save_config_partial(repo_path,exclude_patterns=exclude_patterns if exclude_patterns else None,commit_limit=resolved_commit_limit if commit_limit is not None else None,+ embedder=_index_only_embedder,+ embedding_model=(+ resolve_embedding_model(_index_only_embedder) if _index_only_embedder else None+ ),)# Fingerprint after config writes so the first update doesn't false-positive.base_state["config_fingerprint"] = config_fingerprint(repo_path)diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.pyindex 45f250f97..9597de320 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py@@ -84,6 +84,7 @@ def _record_update_outcome(changed_count: int,provider: Any = None,generated_pages: list | None = None,+ docs_mode: str | None = None,) -> None:"""Attach an anonymous update-shape outcome to the ``command_run`` event.@@ -93,16 +94,26 @@ def _record_update_outcome(try:from repowise.cli.platform import telemetry+ # docs_mode carries the same three values as the state field of that+ # name; it was a bool until an index-only update started re-rendering+ # template pages, which that shape could not express. It comes from the+ # repo's persisted mode, not from this run's page count: a commit that+ # touched no source file re-renders nothing, and that is not the same+ # as the repo having no wiki.+ pages = generated_pages or []+ if docs_mode is None:+ docs_mode = "llm" if (not index_only and provider is not None) else "none"outcome: dict[str, Any] = {"outcome": "success","index_only": bool(index_only),- "docs_mode": not index_only and provider is not None,+ "docs_mode": docs_mode,"changed_files_bucket": telemetry.bucket_count(changed_count),}if not index_only and provider is not None:outcome["provider"] = getattr(provider, "provider_name", None)outcome["model"] = getattr(provider, "model_name", None)- outcome["pages_bucket"] = telemetry.bucket_count(len(generated_pages or []))+ if pages:+ outcome["pages_bucket"] = telemetry.bucket_count(len(pages))telemetry.add_command_outcome(**{k: v for k, v in outcome.items() if v is not None})except Exception:return@@ -227,6 +238,14 @@ def _surface_release_news(*, written_by: str | None) -> None:"(set during `repowise init`)."),)+ "--yes",+ "-y",+ "yes",+ is_flag=True,+ default=False,+ help="Skip the cost confirmation on `--full`.",+)@click.option("--full","full",@@ -296,6 +315,7 @@ def update_command(index_only: bool = False,docs_flag: bool | None = None,full: bool = False,+ yes: bool = False,agents_md: bool | None = None,concurrency: int = 10,no_cost_tracking: bool = False,@@ -322,6 +342,7 @@ def update_command(index_only=index_only,docs_flag=docs_flag,full=full,+ yes=yes,agents_md=agents_md,concurrency=concurrency,no_cost_tracking=no_cost_tracking,@@ -344,6 +365,7 @@ def run_update(index_only: bool = False,docs_flag: bool | None = None,full: bool = False,+ yes: bool = False,agents_md: bool | None = None,concurrency: int = 10,no_cost_tracking: bool = False,@@ -478,6 +500,7 @@ def run_update(model=model,reasoning=reasoning,concurrency=concurrency,+ yes=yes,)except Exception as exc:if emitter is not None:@@ -790,6 +813,48 @@ def run_update()if index_only:+ # A repo whose wiki was rendered from templates keeps it current here.+ # Re-rendering is free, so the changed files' pages are refreshed on+ # every update rather than frozen at the commit `init` ran on. Repos+ # with no pages (fast mode, or an index from before templates existed)+ # skip this and stay a pure index.+ det_pages: list = []+ docs_mode = resolve_docs_mode(state)+ if docs_mode == "deterministic":+ from .deterministic import (+ load_prior_page_ids,+ persist_deterministic_pages,+ regenerate_deterministic_pages,+ )++ if emitter is not None:+ emitter.stage("generate")+ det_pages = regenerate_deterministic_pages(+ repo_path=repo_path,+ parsed_files=parsed_files,+ source_map=source_map,+ graph_builder=graph_builder,+ repo_structure=repo_structure,+ git_meta_map=git_meta_map,+ regenerate_paths=affected.regenerate,+ cfg=cfg,+ concurrency=concurrency,+ degraded=degraded,+ dead_code_report=dead_code_report,+ prior_page_ids=load_prior_page_ids(repo_path),+ )+ if det_pages:+ state["total_pages"] = persist_deterministic_pages(+ repo_path=repo_path,+ generated_pages=det_pages,+ decay_paths=affected.decay_only,+ degraded=degraded,+ )+ state["last_docs_commit"] = head+ console.print(+ f" [green]✓[/green] Re-rendered [bold]{len(det_pages)}[/bold] "+ "wiki pages from structure"+ )if emitter is not None:emitter.stage("persist")try:@@ -807,17 +872,27 @@ def run_update(knowledge_graph_result=knowledge_graph_result,parsed_files=parsed_files,degraded=degraded,+ # The repo's docs mode, not this run's page count: a commit+ # that touched no source file re-renders nothing, and that is+ # not the same as having no wiki.+ template_wiki=docs_mode == "deterministic",+ pages_rendered=len(det_pages),)except Exception as exc:if emitter is not None:emitter.error(str(exc))raise_refresh_editor_stamp(repo_path, agents_md, degraded)- _record_update_outcome(index_only=True, changed_count=len(file_diffs))+ _record_update_outcome(+ index_only=True,+ changed_count=len(file_diffs),+ generated_pages=det_pages,+ docs_mode=docs_mode,+ )if emitter is not None:emitter.done(ok=True,- pages_generated=0,+ pages_generated=len(det_pages),cost_usd=0.0,duration_s=time.monotonic() - start,degraded=degraded,diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.pynew file mode 100644index 000000000..d0e1f9cbf--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py@@ -0,0 +1,267 @@+"""Refresh a template wiki on an index-only update.++``repowise init --index-only`` renders a complete wiki from the repo's+structure. Without this module that wiki would be frozen at the commit it was+built from: an index-only update refreshes the graph, git history, health and+dead code, but never touched a page, because before templates existed there+were no pages on that path to touch.++Re-rendering costs nothing (no provider, no tokens), so the changed files'+pages are re-rendered on every update, the same set the LLM path would+regenerate. The work is deliberately narrow compared with+``_persist_full_update``: no decision extraction, no decision evolution, no KG+enrichment. All three are prompting, and this path has no model.+"""++from __future__ import annotations++import os+from pathlib import Path+from typing import Any++from repowise.cli.helpers import console, run_async+++def deterministic_embedder_name(cfg: dict) -> str:+ """Resolve the embedder for a no-spend run, honouring only an explicit one.++ Same rule as ``init --index-only``: a hosted embedder is a real bill, and+ ``resolve_embedder`` will infer one from any LLM key that happens to be in+ the environment. On a run sold as costing nothing, only a name the user+ actually chose counts, and index-only init persists that choice to+ ``.repowise/config.yaml``. Everything else falls back to the mock, which+ leaves full-text search working.+ """+ from repowise.cli.providers import resolve_embedder++ chosen = cfg.get("embedder") or os.environ.get("REPOWISE_EMBEDDER", "").strip()+ if chosen:+ return str(chosen)+ # Nothing was chosen, so whatever resolve_embedder returns was inferred+ # from a key. Only the ones that cannot bill survive that.+ resolved = resolve_embedder(None)+ return resolved if resolved in ("mock", "ollama") else "mock"+++def load_prior_page_ids(repo_path: Path) -> dict:+ """Every page id already in the wiki, mapped to a placeholder.++ Interlinking and related-pages resolve references against this, so a+ re-rendered page can still link to the pages this run did not touch.+ Only the ids are read: the full ``load_prior_pages`` pulls every page's+ content, and nothing here needs the bodies since template pages never go+ through the content-reuse gate.+ """+ return run_async(_load_prior_page_ids(repo_path))+++async def _load_prior_page_ids(repo_path: Path) -> dict:+ from repowise.cli.helpers import get_db_url_for_repo+ from repowise.core.persistence import create_engine, create_session_factory, get_session++ engine = create_engine(get_db_url_for_repo(repo_path))+ try:+ from sqlalchemy import select as sa_select++ from repowise.core.persistence.models import Page++ async with get_session(create_session_factory(engine)) as session:+ rows = await session.execute(sa_select(Page.id))+ return dict.fromkeys((r[0] for r in rows), None)+ except Exception:+ return {}+ finally:+ await engine.dispose()+++def regenerate_deterministic_pages(+ *,+ repo_path: Path,+ parsed_files: list,+ source_map: dict,+ graph_builder: Any,+ repo_structure: Any,+ git_meta_map: dict,+ regenerate_paths: list[str],+ cfg: dict,+ concurrency: int,+ degraded: list[str],+ dead_code_report: Any = None,+ prior_page_ids: dict | None = None,+) -> list:+ """Re-render the template pages for *regenerate_paths*. Never raises.++ Only the changed files' own pages. The repo-wide pages (cycles, modules,+ layers, overview, architecture diagram, onboarding) describe the whole+ repository and would be rendered here from a view containing only the+ changed files, so they are left as the last full run wrote them.++ A failure here degrades the run rather than failing it: the index half of+ an index-only update is the half the post-commit hook depends on, and it+ has already been computed by the time this runs.+ """+ from repowise.core.generation import ContextAssembler, GenerationConfig, PageGenerator+ from repowise.core.providers.llm.template import TemplateProvider++ regen_set = set(regenerate_paths)+ affected_parsed = [pf for pf in parsed_files if pf.file_info.path in regen_set]+ affected_source = {p: s for p, s in source_map.items() if p in regen_set}+ if not affected_parsed:+ return []++ try:+ config = GenerationConfig(+ deterministic=True,+ file_pages_only=True,+ max_concurrency=concurrency,+ language=cfg.get("language", "en"),+ enable_onboarding=bool(cfg.get("enable_onboarding", True)),+ wiki_style=cfg.get("wiki_style", "comprehensive"),+ )++ # Only build a store when there is a real embedder to build it with.+ # The mock is the index-only default, and writing its 8-wide vectors+ # into a store some earlier run filled at 1536 makes LanceDB drop the+ # table, taking every page and decision embedding with it. Skipping+ # leaves that store untouched; full-text search is unaffected either+ # way. It also keeps the lancedb import off the post-commit hook's+ # path, which is the one place in this command that avoids it.+ vector_store = None+ embedder_name = deterministic_embedder_name(cfg)+ if embedder_name != "mock":+ from repowise.cli.providers import build_embedder, build_vector_store++ try:+ vector_store = build_vector_store(repo_path, build_embedder(embedder_name))+ except Exception as exc: # embedding is optional; FTS still indexes+ degraded.append(f"Page embedding: {exc}")++ generator = PageGenerator(+ TemplateProvider(),+ ContextAssembler(config),+ config,+ vector_store=vector_store,+ language=config.language,+ # Every persisted page id, so interlinking and related-pages can+ # resolve references to pages outside this run's slice. Not a reuse+ # gate: template pages persist an empty content_hash precisely so a+ # later model run cannot inherit their content.+ prior_pages=prior_page_ids or {},+ repo_path=repo_path,+ )+ with console.status(" Re-rendering wiki pages from structure…"):+ return run_async(+ generator.generate_all(+ affected_parsed,+ affected_source,+ graph_builder,+ repo_structure,+ repo_path.name,+ git_meta_map=git_meta_map,+ repo_path=repo_path,+ dead_code_report=dead_code_report,+ )+ )+ except Exception as exc:+ degraded.append(f"Template page refresh: {exc}")+ return []+++def persist_deterministic_pages(+ *,+ repo_path: Path,+ generated_pages: list,+ decay_paths: list[str],+ degraded: list[str],+) -> int:+ """Write the re-rendered pages, decay the rest, and index them for search.++ Returns the repository's total page count, so the caller can stamp+ ``state["total_pages"]`` with the real DB number rather than accumulating.+ Runs before ``persist_incremental_index`` and in its own session: the pages+ must land before that call tombstones the ones whose files are gone, and+ page upserts are idempotent, so an interrupted run re-runs rather than+ tearing the index.+ """+ return run_async(+ _persist_async(+ repo_path=repo_path,+ generated_pages=generated_pages,+ decay_paths=decay_paths,+ degraded=degraded,+ )+ )+++async def _persist_async(+ *,+ repo_path: Path,+ generated_pages: list,+ decay_paths: list[str],+ degraded: list[str],+) -> int:+ from repowise.cli.helpers import get_db_url_for_repo+ from repowise.core.persistence import (+ FullTextSearch,+ create_engine,+ create_session_factory,+ get_session,+ init_db,+ upsert_pages_from_generated,+ upsert_repository,+ )++ url = get_db_url_for_repo(repo_path)+ engine = create_engine(url)+ total = 0+ try:+ await init_db(engine)+ sf = create_session_factory(engine)+ async with get_session(sf) as session:+ repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))+ repo_id = repo.id+ await upsert_pages_from_generated(session, generated_pages, repo_id)++ # No related-pages backfill here. ``persist_incremental_index``+ # runs one repo-wide immediately after this, unskipped, so it+ # already heals these pages; doing it first and exempting them+ # would skip the only pages that need it.++ # Pages the cascade reached but the budget did not: marked stale so+ # the coverage view is honest about which template pages predate+ # the current commit.+ try:+ from repowise.core.pipeline.persist import mark_stale_pages++ await mark_stale_pages(session, repo_id, decay_paths or [])+ except Exception as exc:+ degraded.append(f"Stale-page decay: {exc}")++ # Real DB total, not an accumulation: regeneration upserts, so+ # adding len(generated_pages) each run inflates the count forever.+ total = len(generated_pages)+ try:+ from sqlalchemy import func as sa_func+ from sqlalchemy import select as sa_select++ from repowise.core.persistence.models import Page++ count_result = await session.execute(+ sa_select(sa_func.count())+ .select_from(Page)+ .where(Page.repository_id == repo_id)+ )+ total = int(count_result.scalar_one())+ except Exception as exc:+ degraded.append(f"Page count: {exc}")++ try:+ fts = FullTextSearch(engine)+ await fts.ensure_index()+ for page in generated_pages:+ await fts.index(page.page_id, page.title, page.content)+ except Exception as exc:+ degraded.append(f"Full-text index: {exc}")+ finally:+ await engine.dispose()+ return totaldiff --git a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.pyindex 70451895a..f2a44c7ae 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/persistence.py@@ -141,6 +141,8 @@ def _persist_index_only_update(knowledge_graph_result: Any | None = None,parsed_files: list | None = None,degraded: list[str] | None = None,+ pages_rendered: int = 0,+ template_wiki: bool = False,) -> None:"""Persist the index-only update (graph + symbols + git + dead-code + health + KG),save state, and print the completion line. No LLM regeneration.@@ -196,6 +198,8 @@ def _persist_index_only_update(git_files=len(git_meta_map or {}),elapsed=elapsed,degraded=degraded,+ pages_rendered=pages_rendered,+ template_wiki=template_wiki,)diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/update_cmd/reporting.pyindex c2cab5f01..665fe43aa 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py@@ -225,8 +225,15 @@ def show_index_only_completion(git_files: int,elapsed: float,degraded: list[str] | None = None,+ pages_rendered: int = 0,+ template_wiki: bool = False,) -> None:- """Render the completion panel for an index-only update (no LLM regen)."""+ """Render the completion panel for an index-only update (no LLM regen).++ *pages_rendered* is non-zero on a repo whose wiki was rendered from+ templates: those pages are re-rendered here for free, so the panel says so+ rather than leaving the user to assume the wiki went stale.+ """render_degraded(degraded)graph = graph_builder.graph()unreachable, unused = _dead_code_counts(dead_code_report)@@ -236,6 +243,8 @@ def show_index_only_completion(("Graph", f"{graph.number_of_nodes():,} nodes · {graph.number_of_edges():,} edges"),("Dead code", f"{unreachable} unreachable · {unused} unused exports"),]+ if pages_rendered:+ metrics.append(("Wiki pages", f"{pages_rendered} re-rendered from structure"))if degraded:metrics.append(("Degraded", f"{len(degraded)} step(s)"))if git_files:@@ -244,8 +253,11 @@ def show_index_only_completion(next_steps = [("repowise serve", "browse the index at localhost:3000"),- ("repowise update --docs", "regenerate docs for the changed files"),]+ if template_wiki:+ next_steps.append(("repowise update --full", "rewrite the wiki with a model (needs a key)"))+ else:+ next_steps.append(("repowise update --docs", "regenerate docs for the changed files"))console.print()console.print(build_completion_panel("repowise index-only update complete", metrics, next_steps=next_steps)diff --git a/packages/cli/src/repowise/cli/commands/upgrade_flow.py b/packages/cli/src/repowise/cli/commands/upgrade_flow.pyindex 2f7cf651e..176a3a13c 100644--- a/packages/cli/src/repowise/cli/commands/upgrade_flow.py+++ b/packages/cli/src/repowise/cli/commands/upgrade_flow.py@@ -25,6 +25,7 @@ when ``--full`` is passed.from __future__ import annotationsimport dataclasses+import sysimport timefrom pathlib import Pathfrom typing import Any@@ -44,6 +45,50 @@ from repowise.cli.helpers import (from repowise.core.docs_mode import docs_mode_state_fields+def _gate_cost(+ parsed_files: list[Any],+ graph_builder: Any,+ config: Any,+ provider: Any,+ repo_path: Path,+ *,+ yes: bool,+) -> None:+ """Print the estimated spend and confirm past the gate. Raises on decline.++ Best-effort on the estimate itself: a failure there prints the reason and+ lets the run proceed rather than blocking an upgrade on a number that is+ advisory anyway.+ """+ try:+ from repowise.cli.commands.init_cmd.generation import (+ COST_GATE_USD,+ cost_gate_declined,+ format_cost,+ )+ from repowise.core.cost_estimator import build_generation_plan, estimate_cost++ plans = build_generation_plan(parsed_files, graph_builder, config)+ est = estimate_cost(plans, provider.provider_name, provider.model_name, repo_path=repo_path)+ except Exception as exc:+ console.print(f"[yellow]Cost estimate unavailable ({exc}); continuing.[/yellow]")+ return++ pages = sum(p.count for p in plans)+ console.print(f"Estimated: [bold]{pages}[/bold] pages, [bold]{format_cost(est)}[/bold].")++ # Nothing to ask on a run that cannot be asked. Without this the confirm+ # reads EOF, raises, and the caller reports a successful run that generated+ # nothing, which is the worst of the three possible answers.+ if est.estimated_cost_usd > COST_GATE_USD and not yes and not sys.stdin.isatty():+ raise click.ClickException(+ f"This would spend about {format_cost(est)} and there is no terminal to "+ "confirm on. Re-run with --yes to accept the cost."+ )+ if cost_gate_declined(est, yes=yes, message=" Generate the wiki at this cost?"):+ raise click.Abort()++def _reparse(repo_path: Path, exclude_patterns: list[str]) -> tuple[list[Any], dict[str, bytes], Any]:"""Parse files for ASTs + source bytes WITHOUT building/resolving the graph.@@ -147,6 +192,8 @@ async def _run_upgrade(exclude_patterns: list[str],commit_limit: int | None,follow_renames: bool,+ embedder_name: str | None,+ yes: bool,) -> list[Any]:"""Drive the full upgrade and return the generated pages."""from repowise.cli.helpers import get_db_url_for_repo@@ -195,6 +242,14 @@ async def _run_upgrade("(graph reused from index — not re-resolved).")+ # Show the bill before running it. `init` gates its generation phase and+ # this one did not, which mattered little while `--full` only ever followed+ # an explicit `--mode fast`, and matters now that it is the advertised way+ # to turn a template wiki into a written one: the user reaching for it has+ # never been shown a cost for this repo.+ _gate_cost(parsed_files, graph_builder, config, provider, repo_path, yes=yes)++# 5. Generate the docs the fast index skipped. Honor the cost-tracking# opt-out (issue #326) so REPOWISE_NO_COST_TRACKING is respected here too;# an in-memory tracker still powers the live cost readout.@@ -207,6 +262,21 @@ async def _run_upgrade(# they never contend with the generation writer (issue #326).cost_tracker = CostTracker(session_factory=sf, repo_id=repo_id, buffered=True)provider._cost_tracker = cost_tracker++ # Embed as we generate. Leaving this None meant the upgrade produced a+ # fully written wiki that semantic search could not see, and the user had+ # no reason to suspect it: nothing in the output mentions embedding. The+ # store is the same LanceDB directory `init` and `update` write to.+ from repowise.cli.providers import build_embedder, build_vector_store, resolve_embedder++ embedder = None+ vector_store = None+ try:+ embedder = build_embedder(resolve_embedder(embedder_name))+ vector_store = build_vector_store(repo_path, embedder)+ except Exception as exc:+ console.print(f"[yellow]Embedding skipped: {exc}[/yellow]")+generated_pages = await run_generation(repo_path=repo_path,parsed_files=parsed_files,@@ -215,8 +285,8 @@ async def _run_upgrade(repo_structure=repo_structure,git_meta_map=git_meta_map,llm_client=provider,- embedder=None,- vector_store=None,+ embedder=embedder,+ vector_store=vector_store,concurrency=config.max_concurrency,progress=None,cost_tracker=cost_tracker,@@ -306,8 +376,31 @@ async def _run_upgrade(except Exception as exc:console.print(f"[yellow]Health recompute skipped: {exc}[/yellow]")+ # The repo's real page count, not this run's. An upgrade regenerates rather+ # than appends, and it does not necessarily cover every page the repo+ # already had, so `len(generated_pages)` under-reports the wiki that+ # `repowise status` then displays.+ try:+ from sqlalchemy import func as sa_func+ from sqlalchemy import select as sa_select++ from repowise.core.persistence.models import Page++ async with get_session(sf) as session:+ total_pages = int(+ (+ await session.execute(+ sa_select(sa_func.count())+ .select_from(Page)+ .where(Page.repository_id == repo_id)+ )+ ).scalar_one()+ )+ except Exception:+ total_pages = len(generated_pages)+await engine.dispose()- return generated_pages+ return generated_pages, total_pagesdef upgrade_to_full(@@ -317,11 +410,14 @@ def upgrade_to_full(model: str | None,reasoning: str | None,concurrency: int,+ yes: bool = False,) -> None:- """Upgrade a fast (index-only / ESSENTIAL git) index to a full one.+ """Write the repo's wiki with a model, reusing the persisted graph.- Backfills the git tier and generates the LLM docs the fast index skipped,- reusing the persisted graph instead of rebuilding it.+ Two repos arrive here. A ``--mode fast`` index has no pages and an+ ESSENTIAL git tier, both of which this fills in. An ``--index-only`` repo+ has a full git tier and a wiki rendered from templates, and this replaces+ those pages with written ones."""from repowise.cli.ui import load_dotenvfrom repowise.core.generation import GenerationConfig@@ -361,24 +457,58 @@ def upgrade_to_full(f"[cyan]{provider.model_name}[/cyan]. This generates docs for the whole repo.")- generated_pages = run_async(- _run_upgrade(- repo_path,- provider,- config,- exclude_patterns=exclude_patterns,- commit_limit=commit_limit,- follow_renames=follow_renames,+ # An index-only repo records the mock embedder, because that mode promises+ # no spend and a hosted embedder is a real bill. That promise is void here:+ # the user is already paying a model. Keeping the mock would leave the+ # upgrade with a fully written wiki that semantic search cannot read, which+ # is the failure this whole path exists to end. So re-resolve, and record+ # the answer so later updates stay on it.+ embedder_name = cfg.get("embedder")+ if not embedder_name or embedder_name == "mock":+ from repowise.cli.providers import resolve_embedder++ resolved = resolve_embedder(None)+ if resolved != (embedder_name or "mock"):+ console.print(f"Embedder: [cyan]{resolved}[/cyan] (was mock, index-only's default).")+ embedder_name = resolved++ try:+ generated_pages, total_pages = run_async(+ _run_upgrade(+ repo_path,+ provider,+ config,+ exclude_patterns=exclude_patterns,+ commit_limit=commit_limit,+ follow_renames=follow_renames,+ embedder_name=embedder_name,+ yes=yes,+ ))- )+ except click.Abort:+ # Declined at the cost gate. The git backfill that ran before it is+ # kept (it costs nothing to keep and everything to redo), and the+ # persisted docs mode is left alone so the repo keeps whatever wiki it+ # already had.+ console.print("[yellow]Nothing generated.[/yellow] The index is unchanged.")+ return# Flip persisted state to full so subsequent `repowise update` runs the# normal incremental LLM path rather than offering upgrade.state["last_sync_commit"] = headstate.update(docs_mode_state_fields("llm"))state["git_tier"] = "full"- state["total_pages"] = len(generated_pages)+ state["total_pages"] = total_pages+ # Record who wrote the pages. Without this, `repowise status` on a repo+ # upgraded this way reports its provider and model as unknown, which reads+ # as "nothing wrote this wiki" right after a run that did.+ state["provider"] = provider.provider_name+ state["model"] = provider.model_namesave_state(repo_path, state)+ if embedder_name and embedder_name != cfg.get("embedder"):+ from repowise.cli.helpers import save_config_partial++ save_config_partial(repo_path, embedder=embedder_name)elapsed = time.monotonic() - startconsole.print(diff --git a/packages/cli/src/repowise/cli/ui/mode_selection.py b/packages/cli/src/repowise/cli/ui/mode_selection.pyindex ea1ae677d..b42c722a2 100644--- a/packages/cli/src/repowise/cli/ui/mode_selection.py+++ b/packages/cli/src/repowise/cli/ui/mode_selection.py@@ -446,6 +446,9 @@ def _build_summary_table(# Bullet-list when many patterns — comma-joined wraps unreadably.summary.add_row("Exclude", "\n".join(f"• {p}" for p in patterns))+ if not generate_docs and result.get("embedder"):+ summary.add_row("Embedder", result["embedder"])+# ── Generation (docs only) ─────────────────────────────────────────────if generate_docs:summary.add_row("Concurrency", str(result["concurrency"]))@@ -531,6 +534,9 @@ def interactive_advanced_config(wiki_style=wiki_style,language=language,)+ elif result.get("run_mode") != "fast":+ # Fast mode renders no wiki at all, so there would be nothing to embed.+ _prompt_index_only_search(console, result)result["generate_docs"] = generate_docs# ── Summary ───────────────────────────────────────────────────────────@@ -550,6 +556,29 @@ def interactive_advanced_config(return result+def _prompt_index_only_search(console: Console, result: dict[str, Any]) -> None:+ """Ask an index-only run which embedder its template wiki should use.++ Index-only renders a full wiki now, and those pages embed like any other,+ so the choice is real. It is not asked outside advanced mode because the+ honest default is the one that cannot bill anyone: a hosted embedder is+ picked up automatically from an API key in the environment, and this mode+ promises no spend. Choosing one here counts as asking for it.+ """+ console.print()+ console.print(f" [{BRAND}]Search[/]")+ console.print(+ " [dim]Full-text search always works. Semantic search needs an embedder;\n"+ " ollama is the keyless one, and the hosted ones charge per page.[/dim]"+ )+ console.print()+ result["embedder"] = click.prompt(+ " Embedder for semantic search (mock = full-text only)",+ default="mock",+ type=click.Choice(["mock", "ollama", "gemini", "openai", "openrouter"]),+ )++def _resolve_embedder_from_env() -> str:"""Auto-detect embedder from env vars (for advanced config default)."""if os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY"):diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.pyindex d3da3b625..a3389d926 100644--- a/packages/core/src/repowise/core/generation/models.py+++ b/packages/core/src/repowise/core/generation/models.py@@ -197,6 +197,18 @@ class GenerationConfig:# ``metadata["deterministic"]=True``, exactly like the tier-2 tail.deterministic: bool = False+ # ---- Incremental regeneration: file-level pages only ---------------+ # Levels 3 to 8 (cycles, modules, layers, repo overview, architecture+ # diagram, infra, onboarding) describe the repository, not a file. They+ # render from the graph and from ``parsed_files``, and an incremental run+ # holds only the files that changed, so letting them run would overwrite a+ # whole-repo page with a view of one commit: a codebase map with no+ # directories, a module page claiming one file. Their inputs are also+ # unchanged by most commits, so the work is wasted as well as wrong.+ # Set by the incremental deterministic path, which regenerates the changed+ # files' pages and leaves the repo-wide ones to a full run.+ file_pages_only: bool = False+def __post_init__(self) -> None:if self.embed_concurrency is None:object.__setattr__(self, "embed_concurrency", self.max_concurrency)diff --git a/packages/core/src/repowise/core/generation/page_generator/deterministic.py b/packages/core/src/repowise/core/generation/page_generator/deterministic.pyindex 302b72eb8..5822829a2 100644--- a/packages/core/src/repowise/core/generation/page_generator/deterministic.py+++ b/packages/core/src/repowise/core/generation/page_generator/deterministic.py@@ -86,7 +86,7 @@ class DeterministicRenderMixin:page_type=page_type,title=title,content=content,- summary=_extract_summary(content),+ summary=_extract_summary(content, skip_metadata=True),source_hash=compute_source_hash(content),model_name=self._provider.model_name,provider_name="template",diff --git a/packages/core/src/repowise/core/generation/page_generator/helpers.py b/packages/core/src/repowise/core/generation/page_generator/helpers.pyindex 155a8a275..83da30f63 100644--- a/packages/core/src/repowise/core/generation/page_generator/helpers.py+++ b/packages/core/src/repowise/core/generation/page_generator/helpers.py@@ -26,18 +26,31 @@ def _now_iso() -> str:return datetime.now(UTC).isoformat()-def _extract_summary(content: str, max_chars: int = 320) -> str:+def _extract_summary(content: str, max_chars: int = 320, skip_metadata: bool = False) -> str:"""Extract a 1-3 sentence purpose blurb from rendered wiki markdown.Strategy: walk lines top-to-bottom, skip blanks/headings/list-markers/HTMLcomments, and take the first prose paragraph. Truncate at sentence boundarynear max_chars. Fully deterministic — no extra LLM call.++ *skip_metadata* skips what several deterministic templates put between the+ H1 and the prose: a bold field line (``**Language:** Python | **Files:**+ 412``) and a fenced signature block. Both would otherwise become the+ summary, and the summary is what the wiki list, search results and+ ``get_context`` display. Off by default: a model that opens with+ ``**Purpose:** …`` means it as prose."""if not content:return ""para_lines: list[str] = []+ in_lead_fence = Falsefor raw in content.splitlines():line = raw.strip()+ if in_lead_fence:+ # Inside a fenced block that preceded any prose: the fence's+ # contents are code, and its closing marker ends the skip.+ in_lead_fence = not line.startswith("```")+ continueif not line:if para_lines:break@@ -45,6 +58,10 @@ def _extract_summary(content: str, max_chars: int = 320) -> str:if line.startswith(("#", ">", "```", "---", "<!--", "|", "- ", "* ", "1.")):if para_lines:break+ if skip_metadata and line.startswith("```"):+ in_lead_fence = True+ continue+ if skip_metadata and not para_lines and line.startswith("**") and ":**" in line:continuepara_lines.append(line)if not para_lines:diff --git a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py b/packages/core/src/repowise/core/generation/page_generator/orchestrate.pyindex c66bda1ed..c7b0b3407 100644--- a/packages/core/src/repowise/core/generation/page_generator/orchestrate.py+++ b/packages/core/src/repowise/core/generation/page_generator/orchestrate.py@@ -283,8 +283,14 @@ class _GenerationRun:history, mining error) yields an empty map and selection staysuniform. Runs only on real generation — the cost estimator builds itsown demand-free SelectionInputs, so estimates are untouched.++ Skipped on a deterministic run. Demand exists to tilt a budget toward+ the files agents ask about, and a template page costs nothing, so there+ is no budget to tilt. The sweep reads every session transcript for the+ repo, which grows with the user's chat history rather than the repo:+ seconds of work per run, on the path a post-commit hook takes."""- if not self.repo_path:+ if not self.repo_path or self.config.deterministic:return {}try:from repowise.core.repo_config import load_repo_config@@ -521,6 +527,13 @@ class _GenerationRun:level2 = await _levels.build_level2_coros(self)all_pages.extend(await self.run_level(level2, 2))+ # Levels 3 and up describe the repository rather than a file, and an+ # incremental run holds only the changed files, so running them here+ # would rewrite a whole-repo page from a one-commit view. They stay as+ # the last full run left them.+ if getattr(self.config, "file_pages_only", False):+ return self._finalize(all_pages)+# Level 3 (scc_page).all_pages.extend(await self.run_level(_levels.build_level3_coros(self), 3))@@ -553,6 +566,15 @@ class _GenerationRun:page.metadata["layer_order"] = self.layer_orderbreak+ return self._finalize(all_pages)++ def _finalize(self, all_pages: list[GeneratedPage]) -> list[GeneratedPage]:+ """Run the post-generation passes and close out the job.++ Shared with the ``file_pages_only`` early return, so an incremental+ deterministic run still gets mermaid repair, interlinking, related+ pages and tour links over the pages it did produce.+ """# Post-generation: repair mermaid diagrams so illegal node IDs / unquoted# labels in LLM output don't break the whole diagram in the renderer.try: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.j2index b6184eb30..36ed29e27 100644--- 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.j2@@ -10,7 +10,9 @@ Traced from the entry points outward: which files each run touches, in order. Wh## Shape-`{{ ctx.repo_name }}` looks like {{ "an" if ctx.archetype[0] in "aeiou" else "a" }} **{{ ctx.archetype }}**{% if ctx.archetype_evidence %}, based on:+{#- archetype can come through empty on a repo with no recognised sources;+ indexing it unguarded raises under StrictUndefined and loses the page. -#}+`{{ ctx.repo_name }}` looks like {{ "an" if ctx.archetype and ctx.archetype[0] in "aeiou" else "a" }} **{{ ctx.archetype or "codebase" }}**{% if ctx.archetype_evidence %}, based on:{% for e in ctx.archetype_evidence %}- {{ e }}{% endfor %}diff --git a/tests/integration/test_deterministic_generation.py b/tests/integration/test_deterministic_generation.pyindex 36bd200bf..5879a93d4 100644--- a/tests/integration/test_deterministic_generation.py+++ b/tests/integration/test_deterministic_generation.py@@ -146,3 +146,71 @@ class TestDeterministicGeneration:for p in deterministic_pages:assert "Generate a complete wiki page" not in p.content, p.page_idassert not p.content.lstrip().startswith("You are "), p.page_id+++class TestFilePagesOnly:+ """The incremental path: only the changed files' own pages.++ An update holds only the files that changed. Levels 3 and up describe the+ whole repository and read ``parsed_files``, so letting them run against+ that slice rewrites a whole-repo page from a one-commit view: a codebase+ map with no directories, a module page claiming one file. The flag stops+ them, leaving those pages as the last full run wrote them.+ """++ @pytest.fixture(scope="class")+ async def scoped_pages(self, tmp_path_factory):+ tmp = tmp_path_factory.mktemp("det_scoped")+ 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()+ repo_structure = RepoStructure(+ is_monorepo=False,+ packages=[],+ root_language_distribution={"python": 1.0},+ total_files=len(parsed_files),+ total_loc=0,+ entry_points=[],+ )+ # One code file, the way an incremental run arrives. It has to be one+ # the selector would pick: file pages are only built for code.+ one = [p for p in parsed_files if p.file_info.language == "python"][:1]+ one_src = {p.file_info.path: source_map[p.file_info.path] for p in one}+ config = GenerationConfig(+ deterministic=True,+ file_pages_only=True,+ max_concurrency=2,+ jobs_dir=str(tmp / "jobs"),+ )+ generator = PageGenerator(TemplateProvider(), ContextAssembler(config), config)+ return await generator.generate_all(+ one, one_src, builder, repo_structure, "sample_repo", job_system=None+ )++ def test_no_repo_wide_pages(self, scoped_pages):+ repo_wide = {+ "scc_page",+ "module_page",+ "layer_page",+ "repo_overview",+ "architecture_diagram",+ "onboarding",+ }+ produced = {p.page_type for p in scoped_pages}+ assert not (produced & repo_wide), f"repo-wide pages rebuilt from one file: {produced}"++ def test_still_produces_the_file_page(self, scoped_pages):+ assert scoped_pages, "the changed file's own page must still be rendered"+ assert all(p.provider_name == "template" for p in scoped_pages)diff --git a/tests/unit/cli/test_deterministic_update.py b/tests/unit/cli/test_deterministic_update.pynew file mode 100644index 000000000..f75b4f9d7--- /dev/null+++ b/tests/unit/cli/test_deterministic_update.py@@ -0,0 +1,54 @@+"""The no-spend rules around a template wiki.++Two promises are under test. A run that says it costs nothing does not put a+hosted embedder on the bill, and it does not silently change which embedder a+repo uses between one run and the next. Both are easy to break by accident,+because the embedder is resolved from whatever API key happens to be in the+environment.+"""++from __future__ import annotations++import pytest++from repowise.cli.commands.update_cmd.deterministic import deterministic_embedder_name++[email protected](autouse=True)+def _no_ambient_keys(monkeypatch: pytest.MonkeyPatch) -> None:+ """Start from an environment that infers nothing."""+ for var in (+ "REPOWISE_EMBEDDER",+ "GEMINI_API_KEY",+ "GOOGLE_API_KEY",+ "OPENAI_API_KEY",+ "OPENROUTER_API_KEY",+ "OLLAMA_EMBEDDING_MODEL",+ ):+ monkeypatch.delenv(var, raising=False)+++class TestDeterministicEmbedderName:+ def test_config_choice_wins(self, monkeypatch: pytest.MonkeyPatch) -> None:+ # The repo was indexed with this embedder, so its store holds vectors+ # of that width. Re-deciding here would rewrite the store.+ monkeypatch.setenv("GEMINI_API_KEY", "k")+ assert deterministic_embedder_name({"embedder": "openai"}) == "openai"++ def test_ambient_key_alone_does_not_bill(self, monkeypatch: pytest.MonkeyPatch) -> None:+ # The key is there to pay for a model somewhere else. Nobody asked for+ # 2000 pages of embeddings on a run advertised as free.+ monkeypatch.setenv("OPENAI_API_KEY", "k")+ assert deterministic_embedder_name({}) == "mock"++ def test_explicit_env_embedder_is_honoured(self, monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("REPOWISE_EMBEDDER", "openai")+ assert deterministic_embedder_name({}) == "openai"++ def test_ollama_needs_no_permission(self, monkeypatch: pytest.MonkeyPatch) -> None:+ # The keyless one: running it costs nothing, so inferring it is fine.+ monkeypatch.setenv("OLLAMA_EMBEDDING_MODEL", "nomic-embed-text")+ assert deterministic_embedder_name({}) == "ollama"++ def test_nothing_configured_is_mock(self) -> None:+ assert deterministic_embedder_name({}) == "mock"diff --git a/tests/unit/cli/test_ui_package.py b/tests/unit/cli/test_ui_package.pyindex af62b6a81..e10bc4f85 100644--- a/tests/unit/cli/test_ui_package.py+++ b/tests/unit/cli/test_ui_package.py@@ -126,7 +126,12 @@ def test_advanced_config_default_keys_no_fast(monkeypatch: pytest.MonkeyPatch) -def test_advanced_config_index_only_omits_generation_keys(monkeypatch: pytest.MonkeyPatch,) -> None:- """generate_docs=False gathers indexing knobs only — no LLM-only keys."""+ """generate_docs=False gathers indexing knobs only — no LLM-only keys.++ ``embedder`` is the exception and is asked for: an index-only run renders a+ template wiki, and those pages embed like any other, so the choice is real.+ It defaults to the mock because this mode promises no spend.+ """result = _drive_advanced_config(monkeypatch, scan=None, allow_fast=False, generate_docs=False)assert result == {"generate_docs": False,@@ -137,9 +142,10 @@ def test_advanced_config_index_only_omits_generation_keys("exclude": (),"commit_limit": 500,"follow_renames": False,+ "embedder": "mock",}- # The generation-only knobs must not appear.- for key in ("concurrency", "embedder", "onboarding", "harvest_decisions", "wiki_style"):+ # The knobs that only shape a model's writing must not appear.+ for key in ("concurrency", "reasoning", "onboarding", "harvest_decisions", "wiki_style"):assert key not in resultdiff --git a/tests/unit/generation/test_deterministic_templates.py b/tests/unit/generation/test_deterministic_templates.pyindex bc3ca9ba4..0603a8572 100644--- a/tests/unit/generation/test_deterministic_templates.py+++ b/tests/unit/generation/test_deterministic_templates.py@@ -241,3 +241,23 @@ def test_multiline_summaries_stay_inside_their_list_item(generator):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]+++def test_summary_skips_the_stats_line():+ """Several templates open with a bold field line under the H1.++ The persisted summary is what the wiki list, search results and+ get_context show, so a summary of "**Files:** 412 | **Lines:** 90210"+ displaces the sentence that would have told the reader what the page is.+ """+ from repowise.core.generation.page_generator.helpers import _extract_summary++ content = (+ "# Module: core/ingestion\n\n"+ "**Files:** 412 | **Lines:** 90210\n\n"+ "## Overview\n\n"+ "Walks the repository and parses every source file it recognises.\n"+ )+ assert _extract_summary(content, skip_metadata=True).startswith("Walks the repository")+ # Off by default: a model that opens with **Purpose:** means it as prose.+ assert _extract_summary(content).startswith("**Files:**")