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: provider key settings and per-page AI docs generation from the reader (#988)
Raghav Chamadiya2e84d6b79a54
diff --git a/packages/api-client/src/hosted.ts b/packages/api-client/src/hosted.tsindex a95341e5a..c51ad663f 100644--- a/packages/api-client/src/hosted.ts+++ b/packages/api-client/src/hosted.ts@@ -270,6 +270,11 @@ export function mapHostedPage(raw: Record<string, unknown>, repoId: string): Paghuman_notes: null,created_at: str("created_at"),updated_at: str("updated_at") || str("created_at"),+ is_deterministic:+ typeof raw.is_deterministic === "boolean"+ ? (raw.is_deterministic as boolean)+ : str("provider_name") === "template",+ doc_tier: typeof raw.doc_tier === "number" ? (raw.doc_tier as number) : null,};}diff --git a/packages/api-client/src/pages.test.ts b/packages/api-client/src/pages.test.tsindex 084d3fcc6..6d410a013 100644--- a/packages/api-client/src/pages.test.ts+++ b/packages/api-client/src/pages.test.ts@@ -23,7 +23,7 @@ describe("regeneratePage", () => {});it("includes the style param for a per-page override", async () => {- await regeneratePage("file_page:src/main.py", "caveman");+ await regeneratePage("file_page:src/main.py", { style: "caveman" });expect(apiPost.mock.calls[0]![3]).toEqual({page_id: "file_page:src/main.py",style: "caveman",@@ -31,7 +31,15 @@ describe("regeneratePage", () => {});it("omits the style param for an empty override", async () => {- await regeneratePage("file_page:src/main.py", "");+ await regeneratePage("file_page:src/main.py", { style: "" });expect(apiPost.mock.calls[0]![3]).toEqual({ page_id: "file_page:src/main.py" });});++ it("includes the cascade param when given", async () => {+ await regeneratePage("file_page:src/main.py", { cascade: "dependents" });+ expect(apiPost.mock.calls[0]![3]).toEqual({+ page_id: "file_page:src/main.py",+ cascade: "dependents",+ });+ });});diff --git a/packages/api-client/src/pages.ts b/packages/api-client/src/pages.tsindex b9094fb3b..2bec236a2 100644--- a/packages/api-client/src/pages.ts+++ b/packages/api-client/src/pages.ts@@ -1,5 +1,10 @@import { apiGet, apiPatch, apiPost } from "./client";-import type { PageResponse, PageVersionResponse } from "./types";+import type {+ PageResponse,+ PageVersionResponse,+ JobLaunchResponse,+ GenerateCascade,+} from "./types";export async function listPages(repoId: string,@@ -55,15 +60,26 @@ export async function updatePageNotes(}/**- * Force-regenerate a page by ID. Pass `style` to regenerate this page in a- * specific wiki style (per-page override); omit it to use the repo's style.+ * Force-regenerate a single page by ID. Launches the job immediately and+ * returns its id + stream token (D1/D5).+ *+ * `cascade` controls the pages that summarize this one — `none` (default)+ * touches only this page, `dependents` also refreshes its module/layer/overview+ * containers, `full` refreshes repo-wide. Pass `style` for a per-page wiki-style+ * override; omit it to use the repo's style.*/export async function regeneratePage(pageId: string,- style?: string,-): Promise<{ job_id: string }> {- return apiPost<{ job_id: string }>("/api/pages/lookup/regenerate", undefined, undefined, {- page_id: pageId,- ...(style ? { style } : {}),- });+ opts?: { cascade?: GenerateCascade; style?: string },+): Promise<JobLaunchResponse> {+ return apiPost<JobLaunchResponse>(+ "/api/pages/lookup/regenerate",+ undefined,+ undefined,+ {+ page_id: pageId,+ ...(opts?.cascade ? { cascade: opts.cascade } : {}),+ ...(opts?.style ? { style: opts.style } : {}),+ },+ );}diff --git a/packages/api-client/src/providers.ts b/packages/api-client/src/providers.tsindex 2bd3a6dee..a2689f2a2 100644--- a/packages/api-client/src/providers.ts+++ b/packages/api-client/src/providers.ts@@ -3,7 +3,7 @@*/import { apiGet, apiPatch, apiPost, apiDelete } from "./client";-import type { ProvidersResponse } from "./types";+import type { ProvidersResponse, ProviderValidation } from "./types";export async function getProviders(repoId?: string,@@ -24,13 +24,38 @@ export async function setActiveProvider(});}+/** Store a key for a provider. Passing `repoId` also mirrors it into that+ * repo's `.repowise/.env` (D6), so a later CLI run in the repo picks it up —+ * without it the key stays server-global and the CLI never sees it. */export async function addProviderKey(providerId: string,apiKey: string,+ repoId?: string,+): Promise<void> {+ await apiPost(`/api/providers/${providerId}/key`, {+ api_key: apiKey,+ repo_id: repoId ?? null,+ });+}++/** Remove a provider's key. Passing `repoId` also clears it from that repo's+ * `.repowise/.env` mirror. */+export async function removeProviderKey(+ providerId: string,+ repoId?: string,): Promise<void> {- await apiPost(`/api/providers/${providerId}/key`, { api_key: apiKey });+ const qs = repoId ? `?repo_id=${encodeURIComponent(repoId)}` : "";+ await apiDelete(`/api/providers/${providerId}/key${qs}`);}-export async function removeProviderKey(providerId: string): Promise<void> {- await apiDelete(`/api/providers/${providerId}/key`);+/** Live smoke test for a single provider's configured key. Never throws for a+ * bad key — the failure is reported in `ok` / `error`. */+export async function validateProviderKey(+ providerId: string,+ repoId?: string,+): Promise<ProviderValidation> {+ const qs = repoId ? `?repo_id=${encodeURIComponent(repoId)}` : "";+ return apiPost<ProviderValidation>(+ `/api/providers/${providerId}/validate${qs}`,+ );}diff --git a/packages/api-client/src/repos.ts b/packages/api-client/src/repos.tsindex 9708e900b..71dff7a32 100644--- a/packages/api-client/src/repos.ts+++ b/packages/api-client/src/repos.ts@@ -6,6 +6,9 @@ import type {JobResponse,RepoStatsResponse,PreflightResponse,+ GenerateRequest,+ GenerateEstimate,+ JobLaunchResponse,} from "./types";export async function listRepos(): Promise<RepoResponse[]> {@@ -53,6 +56,25 @@ export async function preflightIndex();}+/** Cost + page counts for a generate selection, cascade fallout included.+ * Heavy (rehydrates the graph and re-parses), so fetch it lazily — never on+ * every render. */+export async function generateEstimate(+ repoId: string,+ body: GenerateRequest,+): Promise<GenerateEstimate> {+ return apiPost<GenerateEstimate>(`/api/repos/${repoId}/generate/estimate`, body);+}++/** Launch a scoped generate job (writes the selected pages with a model).+ * Returns the job id + a short-lived stream token to watch progress. */+export async function generatePages(+ repoId: string,+ body: GenerateRequest,+): Promise<JobLaunchResponse> {+ return apiPost<JobLaunchResponse>(`/api/repos/${repoId}/generate`, body);+}+export async function deleteRepo(repoId: string): Promise<{ ok: boolean; deleted_pages: number }> {return apiDelete<{ ok: boolean; deleted_pages: number }>(`/api/repos/${repoId}`);}diff --git a/packages/api-client/src/types/misc.ts b/packages/api-client/src/types/misc.tsindex 4ae4957a8..bee03a308 100644--- a/packages/api-client/src/types/misc.ts+++ b/packages/api-client/src/types/misc.ts@@ -37,6 +37,54 @@ export interface ProvidersResponse {providers: ProviderInfo[];}+/** Result of a live provider smoke test. `ok: false` carries the reason in+ * `error` — the endpoint never throws for a bad key. */+export interface ProviderValidation {+ ok: boolean;+ provider: string | null;+ model: string | null;+ error: string | null;+}++// ---------------------------------------------------------------------------+// Scoped generation (POST /repos/{id}/generate[/estimate])+// ---------------------------------------------------------------------------++export type GenerateCascade = "none" | "dependents" | "full";++/** Which pages a generate/estimate call targets. Mirrors the server's+ * `GenerateSelectionBody`. */+export interface GenerateSelection {+ kind: "all" | "unwritten" | "stale" | "page_ids" | "path_prefix";+ page_ids?: string[];+ path_prefix?: string;+}++export interface GenerateRequest {+ selection?: GenerateSelection;+ cascade?: GenerateCascade;+ style?: string;+}++/** Cost + page counts for a generate selection, cascade fallout included.+ * `estimate` is null when no provider resolves (nothing to price). */+export interface GenerateEstimate {+ total_pages: number;+ pages_by_type: Record<string, number>;+ pages_to_mark_stale: number;+ unknown_page_ids: string[];+ provider: { name: string | null; model: string | null; error: string | null };+ estimate: {+ estimated_cost_usd: number;+ cost_low_usd: number | null;+ cost_high_usd: number | null;+ estimated_input_tokens: number;+ estimated_output_tokens: number;+ is_calibrated: boolean;+ } | null;+ note?: string | null;+}+// ---------------------------------------------------------------------------// API error// ---------------------------------------------------------------------------diff --git a/packages/api-client/src/types/pages.ts b/packages/api-client/src/types/pages.tsindex 12e3b2fe0..ac40cf677 100644--- a/packages/api-client/src/types/pages.ts+++ b/packages/api-client/src/types/pages.ts@@ -23,6 +23,13 @@ export interface PageResponse {human_notes: string | null;created_at: string;updated_at: string;+ /** True when the page was rendered from structure (a template) rather than+ * written by a model — the flat marker the server projects from+ * `provider_name === "template"`. Drives the "Write with AI" vs+ * "Regenerate" affordance. */+ is_deterministic: boolean;+ /** 2 = in-budget template, 3 = coverage tail; null on model-written pages. */+ doc_tier: number | null;}export interface PageVersionResponse {@@ -72,6 +79,15 @@ export interface JobResponse {stream_token?: string | null;}+/** What a launch endpoint (`/generate`, `/pages/lookup/regenerate`, `/index`)+ * returns: the new job's id plus a short-lived token for its SSE stream. */+export interface JobLaunchResponse {+ job_id: string;+ status: string;+ /** Present while the job is live; pass as `?token=` on the stream URL. */+ stream_token?: string | null;+}+export interface JobProgressEvent {event: "progress" | "done" | "error";job_id: string;diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.pyindex b9a7ddcc3..a2fd2febc 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py@@ -828,16 +828,28 @@ def run_update(# with no pages (fast mode, or an index from before templates existed)# skip this and stay a pure index.det_pages: list = []+ index_only_cost = 0.0docs_mode = resolve_docs_mode(state)if docs_mode == "deterministic":from .deterministic import (load_prior_page_ids,+ partition_regenerate_by_provenance,persist_deterministic_pages,regenerate_deterministic_pages,+ regenerate_model_pages,)if emitter is not None:emitter.stage("generate")+ prior_ids = load_prior_page_ids(repo_path)++ # Per-page re-render mode: a page a user upgraded to model prose must+ # not silently revert to a template. Template pages re-render for+ # free; model-written pages stay model-written.+ template_paths, model_paths = partition_regenerate_by_provenance(+ repo_path, affected.regenerate+ )+det_pages = regenerate_deterministic_pages(repo_path=repo_path,parsed_files=parsed_files,@@ -845,25 +857,102 @@ def run_update(graph_builder=graph_builder,repo_structure=repo_structure,git_meta_map=git_meta_map,- regenerate_paths=affected.regenerate,+ regenerate_paths=template_paths,cfg=cfg,concurrency=concurrency,degraded=degraded,dead_code_report=dead_code_report,- prior_page_ids=load_prior_page_ids(repo_path),+ prior_page_ids=prior_ids,)- if det_pages:++ # Model-written pages: re-render with the model when one resolves+ # (D6 wrote the key into .repowise/.env, so an index-only repo whose+ # pages were upgraded now has a provider). With no provider, keep the+ # existing LLM content and mark it stale — never revert to a template.+ model_pages: list = []+ stale_model_paths: list[str] = []+ if model_paths:+ model_provider = None+ try:+ from repowise.cli.helpers import resolve_provider++ model_provider = resolve_provider(+ provider_name, model, repo_path=repo_path+ )+ except Exception:+ model_provider = None++ if model_provider is not None:+ from repowise.cli.providers import build_cost_tracker++ tracker = build_cost_tracker(+ repo_path, repo_path.name, no_cost_tracking=no_cost_tracking+ )+ model_provider._cost_tracker = tracker+ model_pages = regenerate_model_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=model_paths,+ cfg=cfg,+ concurrency=concurrency,+ degraded=degraded,+ provider=model_provider,+ dead_code_report=dead_code_report,+ prior_page_ids=prior_ids,+ )+ index_only_cost = float(getattr(tracker, "session_cost", 0.0) or 0.0)+ # Any requested model page the render did not actually+ # produce is kept and marked stale. generate_all catches a+ # per-page provider error and filters that page out of its+ # result, so a partial batch (page A rendered, page B errored)+ # must not leave B silently fresh-but-outdated — that is the+ # exact revert-in-disguise Task 3 prevents. Full failure+ # (empty result) falls out of the same computation.+ rendered_paths = {+ pg.page_id.split("file_page:", 1)[1]+ for pg in model_pages+ if getattr(pg, "page_id", "").startswith("file_page:")+ }+ stale_model_paths = [p for p in model_paths if p not in rendered_paths]+ else:+ stale_model_paths = list(model_paths)+ console.print(+ " [yellow]![/yellow] "+ f"{len(model_paths)} model-written page(s) changed but no "+ "provider is configured; keeping them and marking stale. "+ "Add a key, then run [bold]repowise generate[/bold]."+ )++ all_pages = det_pages + model_pages+ if all_pages or stale_model_paths:state["total_pages"] = persist_deterministic_pages(repo_path=repo_path,- generated_pages=det_pages,- decay_paths=affected.decay_only,+ generated_pages=all_pages,+ # decay_only are cascade-reached templates; the kept model+ # pages are stale until a provider re-writes them.+ decay_paths=[*affected.decay_only, *stale_model_paths],degraded=degraded,)- state["last_docs_commit"] = head- console.print(- f" [green]✓[/green] Re-rendered [bold]{len(det_pages)}[/bold] "- "wiki pages from structure"- )+ # Advance the docs commit only when something was actually+ # re-rendered to HEAD; a run that only kept-and-staled model pages+ # has not brought the wiki up to HEAD.+ if all_pages:+ state["last_docs_commit"] = head+ if det_pages:+ console.print(+ f" [green]✓[/green] Re-rendered [bold]{len(det_pages)}[/bold] "+ "wiki pages from structure"+ )+ if model_pages:+ console.print(+ f" [green]✓[/green] Re-wrote [bold]{len(model_pages)}[/bold] "+ "upgraded page(s) with the model"+ )+ det_pages = all_pagesif emitter is not None:emitter.stage("persist")try:@@ -902,7 +991,7 @@ def run_update(emitter.done(ok=True,pages_generated=len(det_pages),- cost_usd=0.0,+ cost_usd=index_only_cost,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.pyindex d0e1f9cbf..2f8b8c8de 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py@@ -74,6 +74,56 @@ async def _load_prior_page_ids(repo_path: Path) -> dict:await engine.dispose()+def partition_regenerate_by_provenance(+ repo_path: Path, regenerate_paths: list[str]+) -> tuple[list[str], list[str]]:+ """Split changed file paths into (template, model_written) by existing page.++ A page a user upgraded to model prose must not silently revert to a template+ on the next update. The re-render mode is therefore per-page, read from the+ existing ``file_page:<path>`` provenance: ``provider_name == "template"`` (or+ no page yet) stays a template; anything else was model-written and is kept so.+ Order within each bucket follows ``regenerate_paths``. Never raises — on a+ lookup failure every path is treated as model-written, so the free template+ render can never overwrite (revert) a page whose provenance we could not read.+ A provider then re-renders them; without one the caller keeps and marks them+ stale. Erring toward "keep" is the safe direction for the Task 3 guarantee.+ """+ if not regenerate_paths:+ return [], []+ try:+ model_paths = run_async(_load_model_written_paths(repo_path, regenerate_paths))+ except Exception:+ return [], list(regenerate_paths)+ template = [p for p in regenerate_paths if p not in model_paths]+ model = [p for p in regenerate_paths if p in model_paths]+ return template, model+++async def _load_model_written_paths(repo_path: Path, paths: list[str]) -> set[str]:+ 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++ wanted = {f"file_page:{p}": p for p in paths}+ async with get_session(create_session_factory(engine)) as session:+ rows = await session.execute(+ sa_select(Page.id, Page.provider_name).where(Page.id.in_(list(wanted)))+ )+ return {+ wanted[pid]+ for pid, provider_name in rows+ if provider_name and provider_name != "template"+ }+ finally:+ await engine.dispose()++def regenerate_deterministic_pages(*,repo_path: Path,@@ -100,6 +150,90 @@ def regenerate_deterministic_pages(an index-only update is the half the post-commit hook depends on, and ithas already been computed by the time this runs."""+ return _render_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=regenerate_paths,+ cfg=cfg,+ concurrency=concurrency,+ degraded=degraded,+ dead_code_report=dead_code_report,+ prior_page_ids=prior_page_ids,+ provider=None,+ degrade_label="Template page refresh",+ )+++def regenerate_model_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],+ provider: Any,+ dead_code_report: Any = None,+ prior_page_ids: dict | None = None,+) -> list:+ """Re-render *regenerate_paths* with a real model, keeping them model-written.++ The sibling of :func:`regenerate_deterministic_pages` for the pages a user+ upgraded away from templates on an otherwise index-only repo. Scoped by+ ``only_page_ids`` so the budget can't ration them down: exactly the requested+ file pages render, from the same complete view. Never raises — a model+ failure degrades the run, and the caller keeps the existing content and marks+ those pages stale rather than reverting them.+ """+ return _render_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=regenerate_paths,+ cfg=cfg,+ concurrency=concurrency,+ degraded=degraded,+ dead_code_report=dead_code_report,+ prior_page_ids=prior_page_ids,+ provider=provider,+ degrade_label="Model page refresh",+ )+++def _render_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,+ prior_page_ids: dict | None,+ provider: Any,+ degrade_label: str,+) -> list:+ """Shared render body for the template and model paths.++ ``provider=None`` renders from templates (free, no LLM); a provider renders+ the file pages with the model, scoped to exactly ``regenerate_paths`` via+ ``only_page_ids`` so the coverage budget cannot drop any of them.+ """from repowise.core.generation import ContextAssembler, GenerationConfig, PageGeneratorfrom repowise.core.providers.llm.template import TemplateProvider@@ -109,9 +243,10 @@ def regenerate_deterministic_pages(if not affected_parsed:return []+ is_template = provider is Nonetry:config = GenerationConfig(- deterministic=True,+ deterministic=is_template,file_pages_only=True,max_concurrency=concurrency,language=cfg.get("language", "en"),@@ -137,7 +272,7 @@ def regenerate_deterministic_pages(degraded.append(f"Page embedding: {exc}")generator = PageGenerator(- TemplateProvider(),+ provider if provider is not None else TemplateProvider(),ContextAssembler(config),config,vector_store=vector_store,@@ -149,7 +284,16 @@ def regenerate_deterministic_pages(prior_pages=prior_page_ids or {},repo_path=repo_path,)- with console.status(" Re-rendering wiki pages from structure…"):+ # A model render targets exactly the requested file pages so the coverage+ # budget can't ration them; a template render takes every page it is fed+ # (deterministic mode bypasses the budget already).+ only_page_ids = None if is_template else {f"file_page:{p}" for p in regenerate_paths}+ status_msg = (+ " Re-rendering wiki pages from structure…"+ if is_template+ else " Re-writing upgraded pages with the model…"+ )+ with console.status(status_msg):return run_async(generator.generate_all(affected_parsed,@@ -160,10 +304,11 @@ def regenerate_deterministic_pages(git_meta_map=git_meta_map,repo_path=repo_path,dead_code_report=dead_code_report,+ only_page_ids=only_page_ids,))except Exception as exc:- degraded.append(f"Template page refresh: {exc}")+ degraded.append(f"{degrade_label}: {exc}")return []diff --git a/packages/server/src/repowise/server/routers/providers.py b/packages/server/src/repowise/server/routers/providers.pyindex af97bf09a..f2eeef0b8 100644--- a/packages/server/src/repowise/server/routers/providers.py+++ b/packages/server/src/repowise/server/routers/providers.py@@ -98,3 +98,42 @@ async def remove_provider_key(set_api_key(provider_id, None, repo_path=repo_path)except ValueError as exc:raise HTTPException(400, str(exc)) from exc++[email protected]("/{provider_id}/validate")+async def validate_provider(+ provider_id: str,+ request: Request,+ repo_id: str | None = None,+):+ """Live smoke test for a single provider's configured key.++ Instantiates *this* provider (not the active one) with the key resolved for+ the repo and does a tiny ``generate`` round-trip — the same probe the CLI+ and pre-index preflight use, scoped to one provider so the settings UI can+ confirm a key it just added actually works. A keyless provider (Ollama,+ mock) still exercises reachability. Returns ``{ok, provider, model, error}``+ rather than raising, so the UI renders a clean error state.+ """+ repo_path = await _repo_path_for(request, repo_id)++ provider_name: str | None = None+ model_name: str | None = None+ llm_client = None+ try:+ from repowise.server.provider_config import get_chat_provider_instance++ llm_client = get_chat_provider_instance(+ repo_path=repo_path, repo_id=repo_id, provider_override=provider_id+ )+ provider_name = getattr(llm_client, "provider_name", None)+ model_name = getattr(llm_client, "model_name", None)+ except Exception as exc:+ return {"ok": False, "provider": provider_id, "model": None, "error": str(exc)}++ try:+ await llm_client.generate("You are a test.", "Reply with OK.", max_tokens=50)+ except Exception as exc:+ return {"ok": False, "provider": provider_name, "model": model_name, "error": str(exc)}++ return {"ok": True, "provider": provider_name, "model": model_name, "error": None}diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsxindex 95ce6b194..2d3ef374c 100644--- a/packages/ui/src/docs/docs-reader.tsx+++ b/packages/ui/src/docs/docs-reader.tsx@@ -10,6 +10,8 @@ import {Loader2,Layers,FileInput,+ Sparkles,+ Cog,} from "lucide-react";import type { DocPage } from "@repowise-dev/types/docs";import { cn } from "../lib/cn";@@ -19,6 +21,8 @@ import {isDeterministicPage,DETERMINISTIC_BADGE_LABEL,DETERMINISTIC_BADGE_TITLE,+ AI_WRITTEN_BADGE_LABEL,+ AI_WRITTEN_BADGE_TITLE,} from "../lib/page-types";import { computeDocNav } from "./doc-nav";import { filterMarkdownByPersona, type ReaderPersona } from "./reader-persona";@@ -321,13 +325,22 @@ function DocsReaderBody({<span className="rounded-full bg-[var(--color-bg-elevated)] px-2 py-0.5 uppercase tracking-wider">{getPageTypeLabel(page.page_type)}</span>- {isDeterministicPage(page) && (+ {isDeterministicPage(page) ? (<span- className="rounded-full border border-[var(--color-border-default)] px-2 py-0.5 uppercase tracking-wider text-[var(--color-text-tertiary)]"+ className="inline-flex items-center gap-1 rounded-full border border-[var(--color-info)]/35 bg-[var(--color-info)]/10 px-2 py-0.5 uppercase tracking-wider text-[var(--color-info)]"title={DETERMINISTIC_BADGE_TITLE}>+ <Cog className="h-2.5 w-2.5" />{DETERMINISTIC_BADGE_LABEL}</span>+ ) : (+ <span+ className="inline-flex items-center gap-1 rounded-full border border-[var(--color-accent-primary)]/40 bg-[var(--color-accent-muted)] px-2 py-0.5 uppercase tracking-wider text-[var(--color-accent-primary)]"+ title={AI_WRITTEN_BADGE_TITLE}+ >+ <Sparkles className="h-2.5 w-2.5" />+ {AI_WRITTEN_BADGE_LABEL}+ </span>)}{moduleSeg && (<buttondiff --git a/packages/ui/src/lib/page-types.ts b/packages/ui/src/lib/page-types.tsindex 0a9d22c3e..99397eae4 100644--- a/packages/ui/src/lib/page-types.ts+++ b/packages/ui/src/lib/page-types.ts@@ -74,6 +74,10 @@ export const DETERMINISTIC_BADGE_LABEL = "Auto";export const DETERMINISTIC_BADGE_TITLE ="Auto-documented from code structure (no AI). Factual but terse.";+export const AI_WRITTEN_BADGE_LABEL = "AI";+export const AI_WRITTEN_BADGE_TITLE =+ "Written by AI from the code and its context.";+// ---------------------------------------------------------------------------// Onboarding collection// ---------------------------------------------------------------------------diff --git a/packages/ui/src/settings/index.ts b/packages/ui/src/settings/index.tsindex b037ccb06..649cfa9f1 100644--- a/packages/ui/src/settings/index.ts+++ b/packages/ui/src/settings/index.ts@@ -1 +1,2 @@export * from "./general-form";+export * from "./provider-settings";diff --git a/packages/ui/src/settings/provider-settings.tsx b/packages/ui/src/settings/provider-settings.tsxnew file mode 100644index 000000000..9f7fb658a--- /dev/null+++ b/packages/ui/src/settings/provider-settings.tsx@@ -0,0 +1,346 @@+"use client";++import { useState } from "react";+import {+ Check,+ KeyRound,+ Loader2,+ Plug,+ Trash2,+ X,+} from "lucide-react";+import { Badge } from "../ui/badge";+import { Button } from "../ui/button";+import { Input } from "../ui/input";+import { Label } from "../ui/label";+import {+ Select,+ SelectContent,+ SelectItem,+ SelectTrigger,+ SelectValue,+} from "../ui/select";+import { cn } from "../lib/cn";++/** One provider row for the settings surface. Structurally a subset of the+ * api-client `ProviderInfo`, redeclared here so the shared component stays+ * free of any api-client dependency. */+export interface ProviderOption {+ id: string;+ name: string;+ models: string[];+ default_model: string;+ /** Whether a usable key is on file (server-computed; never the key itself). */+ configured: boolean;+}++export type ProviderValidationStatus = "idle" | "testing" | "ok" | "error";++export interface ProviderValidationState {+ status: ProviderValidationStatus;+ error?: string | null;+}++/** Providers that authenticate without an API key (local runtimes / CLIs).+ * For these the key affordance is hidden — only reachability is validated. */+const KEYLESS_PROVIDERS = new Set(["ollama", "opencode", "codex_cli", "mock"]);++export interface ProviderSettingsProps {+ providers: ProviderOption[];+ /** The active provider/model selection for this repo. */+ active: { provider: string | null; model: string | null };+ onAddKey: (providerId: string, apiKey: string) => Promise<void> | void;+ onRemoveKey: (providerId: string) => Promise<void> | void;+ onSetActive: (providerId: string, model?: string) => Promise<void> | void;+ onValidate: (providerId: string) => Promise<void> | void;+ /** Per-provider probe state, keyed by provider id. */+ validation?: Record<string, ProviderValidationState>;+ /** Rendered when there are no providers at all (e.g. a fetch miss). */+ emptyHint?: string;+}++export function ProviderSettings({+ providers,+ active,+ onAddKey,+ onRemoveKey,+ onSetActive,+ onValidate,+ validation = {},+ emptyHint = "No providers available.",+}: ProviderSettingsProps) {+ if (providers.length === 0) {+ return (+ <p className="text-sm text-[var(--color-text-tertiary)]">{emptyHint}</p>+ );+ }++ return (+ <div className="space-y-2.5">+ {providers.map((provider) => (+ <ProviderRow+ key={provider.id}+ provider={provider}+ isActive={active.provider === provider.id}+ activeModel={active.provider === provider.id ? active.model : null}+ onAddKey={onAddKey}+ onRemoveKey={onRemoveKey}+ onSetActive={onSetActive}+ onValidate={onValidate}+ validation={validation[provider.id]}+ />+ ))}+ </div>+ );+}++function ProviderRow({+ provider,+ isActive,+ activeModel,+ onAddKey,+ onRemoveKey,+ onSetActive,+ onValidate,+ validation,+}: {+ provider: ProviderOption;+ isActive: boolean;+ activeModel: string | null;+ onAddKey: ProviderSettingsProps["onAddKey"];+ onRemoveKey: ProviderSettingsProps["onRemoveKey"];+ onSetActive: ProviderSettingsProps["onSetActive"];+ onValidate: ProviderSettingsProps["onValidate"];+ validation: ProviderValidationState | undefined;+}) {+ const [editing, setEditing] = useState(false);+ const [keyDraft, setKeyDraft] = useState("");+ const [busy, setBusy] = useState<null | "save" | "remove" | "activate">(null);++ const keyless = KEYLESS_PROVIDERS.has(provider.id);+ const status = validation?.status ?? "idle";++ async function saveKey() {+ const key = keyDraft.trim();+ if (!key) return;+ setBusy("save");+ try {+ await onAddKey(provider.id, key);+ setKeyDraft("");+ setEditing(false);+ } finally {+ setBusy(null);+ }+ }++ async function removeKey() {+ setBusy("remove");+ try {+ await onRemoveKey(provider.id);+ } finally {+ setBusy(null);+ }+ }++ async function activate(model?: string) {+ setBusy("activate");+ try {+ await onSetActive(provider.id, model);+ } finally {+ setBusy(null);+ }+ }++ return (+ <div+ className={cn(+ "rounded-md border p-3 transition-colors",+ isActive+ ? "border-[var(--color-border-active)] bg-[var(--color-accent-muted)]"+ : "border-[var(--color-border-default)]",+ )}+ >+ <div className="flex items-center gap-3">+ <div className="min-w-0 flex-1">+ <div className="flex items-center gap-2">+ <span className="text-sm font-medium text-[var(--color-text-primary)]">+ {provider.name}+ </span>+ {isActive && (+ <Badge variant="accent" className="text-[10px]">+ Active+ </Badge>+ )}+ {keyless ? (+ <Badge variant="outline" className="text-[10px]">+ No key required+ </Badge>+ ) : provider.configured ? (+ <span className="inline-flex items-center gap-1 text-[11px] text-[var(--color-success)]">+ <Check className="h-3 w-3" />+ Key set+ </span>+ ) : (+ <span className="text-[11px] text-[var(--color-text-tertiary)]">+ No key+ </span>+ )}+ </div>+ </div>++ <div className="flex shrink-0 items-center gap-1.5">+ {!isActive && (+ <Button+ type="button"+ variant="outline"+ size="sm"+ className="h-7 text-xs"+ disabled={busy !== null || (!keyless && !provider.configured)}+ onClick={() => activate()}+ aria-label={`Use ${provider.name}`}+ >+ {busy === "activate" ? (+ <Loader2 className="h-3.5 w-3.5 animate-spin" />+ ) : (+ "Use"+ )}+ </Button>+ )}+ {(keyless || provider.configured) && (+ <Button+ type="button"+ variant="ghost"+ size="sm"+ className="h-7 gap-1.5 text-xs"+ disabled={status === "testing"}+ onClick={() => onValidate(provider.id)}+ aria-label={`Test ${provider.name} connection`}+ >+ {status === "testing" ? (+ <Loader2 className="h-3.5 w-3.5 animate-spin" />+ ) : (+ <Plug className="h-3.5 w-3.5" />+ )}+ Test+ </Button>+ )}+ {!keyless &&+ (editing ? null : (+ <Button+ type="button"+ variant="ghost"+ size="sm"+ className="h-7 gap-1.5 text-xs"+ onClick={() => setEditing(true)}+ >+ <KeyRound className="h-3.5 w-3.5" />+ {provider.configured ? "Update key" : "Add key"}+ </Button>+ ))}+ {!keyless && provider.configured && !editing && (+ <Button+ type="button"+ variant="ghost"+ size="sm"+ className="h-7 w-7 p-0 text-[var(--color-text-tertiary)] hover:text-[var(--color-error)]"+ disabled={busy !== null}+ onClick={removeKey}+ aria-label={`Remove ${provider.name} key`}+ >+ {busy === "remove" ? (+ <Loader2 className="h-3.5 w-3.5 animate-spin" />+ ) : (+ <Trash2 className="h-3.5 w-3.5" />+ )}+ </Button>+ )}+ </div>+ </div>++ {editing && !keyless && (+ <div className="mt-3 flex items-center gap-2">+ <Input+ type="password"+ autoComplete="off"+ autoFocus+ aria-label={`${provider.name} API key`}+ value={keyDraft}+ onChange={(e) => setKeyDraft(e.target.value)}+ onKeyDown={(e) => {+ if (e.key === "Enter") {+ e.preventDefault();+ void saveKey();+ }+ if (e.key === "Escape") {+ setEditing(false);+ setKeyDraft("");+ }+ }}+ placeholder={`Paste your ${provider.name} API key`}+ className="h-8 font-mono text-xs"+ />+ <Button+ type="button"+ size="sm"+ className="h-8 text-xs"+ disabled={!keyDraft.trim() || busy === "save"}+ onClick={saveKey}+ aria-label={`Save ${provider.name} API key`}+ >+ {busy === "save" ? (+ <Loader2 className="h-3.5 w-3.5 animate-spin" />+ ) : (+ "Save"+ )}+ </Button>+ <Button+ type="button"+ variant="ghost"+ size="sm"+ className="h-8 w-8 p-0"+ onClick={() => {+ setEditing(false);+ setKeyDraft("");+ }}+ aria-label="Cancel"+ >+ <X className="h-3.5 w-3.5" />+ </Button>+ </div>+ )}++ {isActive && provider.models.length > 0 && (+ <div className="mt-3 flex items-center gap-2">+ <Label className="text-xs text-[var(--color-text-secondary)]">Model</Label>+ <Select+ value={activeModel ?? provider.default_model}+ onValueChange={(m) => activate(m)}+ >+ <SelectTrigger className="h-8 w-64 text-xs">+ <SelectValue />+ </SelectTrigger>+ <SelectContent>+ {provider.models.map((m) => (+ <SelectItem key={m} value={m} className="text-xs">+ {m}+ </SelectItem>+ ))}+ </SelectContent>+ </Select>+ </div>+ )}++ {status === "ok" && (+ <p className="mt-2 inline-flex items-center gap-1 text-xs text-[var(--color-success)]">+ <Check className="h-3.5 w-3.5" />+ Connection verified+ </p>+ )}+ {status === "error" && (+ <p className="mt-2 text-xs text-[var(--color-error)]">+ {validation?.error || "Connection failed"}+ </p>+ )}+ </div>+ );+}diff --git a/packages/ui/src/wiki/regenerate-button.tsx b/packages/ui/src/wiki/regenerate-button.tsxindex 9e19c886a..f73818cf4 100644--- a/packages/ui/src/wiki/regenerate-button.tsx+++ b/packages/ui/src/wiki/regenerate-button.tsx@@ -1,7 +1,7 @@"use client";import type { ReactNode } from "react";-import { RefreshCw } from "lucide-react";+import { Loader2, RefreshCw, Sparkles } from "lucide-react";import { Button } from "../ui/button";import {Dialog,@@ -9,43 +9,68 @@ import {DialogHeader,DialogTitle,} from "../ui/dialog";+import { cn } from "../lib/cn";++export type RegenerateMode = "write" | "regenerate";++export type RegenerateCascade = "none" | "dependents" | "full";export interface RegenerateButtonProps {- /** Fired when the user clicks the regenerate button. Wrapper owns the- * mutation + toast + cache-invalidation lifecycle. */+ /** "write" for an unwritten (template) page — an inviting, accented+ * "Write with AI"; "regenerate" for a model-written page — a quiet+ * "Regenerate". Defaults to "regenerate". */+ mode?: RegenerateMode;+ /** Fired when the user clicks the button. Wrapper owns opening the confirm+ * dialog, the mutation, the toast, and cache-invalidation. */onRegenerate: () => void;- /** When true, the button shows a spinning icon and is disabled (request- * in-flight prior to a job id being assigned). */+ /** When true, the button shows a spinner and is disabled (request in-flight+ * prior to a job id being assigned). */isLoading?: boolean;- /** When true, the progress dialog is open. The wrapper sets this to- * `true` once it receives a job id back from the regenerate mutation. */+ /** When true, the progress dialog is open. The wrapper sets this to `true`+ * once it receives a job id back from the regenerate mutation. */isInProgress?: boolean;- /** Called when the dialog requests to close (user dismiss or job done). */+ /** Called when the progress dialog requests to close (dismiss or job done). */onDialogClose?: () => void;- /** Rendered inside the in-progress dialog — typically a job-progress- * widget owned by the wrapper. */+ /** Rendered inside the in-progress dialog — typically a job-progress widget+ * owned by the wrapper. */jobSlot?: ReactNode;}export function RegenerateButton({+ mode = "regenerate",onRegenerate,isLoading = false,isInProgress = false,onDialogClose,jobSlot,}: RegenerateButtonProps) {+ const isWrite = mode === "write";+ const Icon = isLoading ? Loader2 : isWrite ? Sparkles : RefreshCw;+return (<><Button- variant="ghost"+ variant={isWrite ? "outline" : "ghost"}size="sm"onClick={onRegenerate}disabled={isLoading || isInProgress}- className="h-7 gap-1.5 text-xs"- aria-label="Regenerate this page"+ className={cn(+ "h-7 gap-1.5 text-xs",+ isWrite &&+ "border-[var(--color-accent-primary)]/40 bg-[var(--color-accent-muted)] text-[var(--color-accent-primary)] hover:bg-[var(--color-accent-muted)] hover:text-[var(--color-accent-hover)]",+ )}+ aria-label={isWrite ? "Write this page with AI" : "Regenerate this page"}>- <RefreshCw className={`h-3.5 w-3.5 ${isLoading ? "animate-spin" : ""}`} />- <span className="hidden sm:inline">Regenerate</span>+ <Icon+ className={cn(+ "h-3.5 w-3.5",+ isLoading && "animate-spin",+ isWrite && !isLoading && "text-[var(--color-accent-primary)]",+ )}+ />+ <span className="hidden sm:inline">+ {isWrite ? "Write with AI" : "Regenerate"}+ </span></Button><Dialog@@ -56,7 +81,9 @@ export function RegenerateButton({><DialogContent className="sm:max-w-md"><DialogHeader>- <DialogTitle>Regenerating Page</DialogTitle>+ <DialogTitle>+ {isWrite ? "Writing page with AI" : "Regenerating page"}+ </DialogTitle></DialogHeader>{jobSlot}</DialogContent>@@ -64,3 +91,206 @@ export function RegenerateButton({</>);}++const CASCADE_OPTIONS: {+ value: RegenerateCascade;+ label: string;+ hint: string;+}[] = [+ { value: "none", label: "Just this page", hint: "Fastest, cheapest." },+ {+ value: "dependents",+ label: "This page and its summaries",+ hint: "Also refreshes the module, layer, and overview pages that cover it.",+ },+ {+ value: "full",+ label: "This page and all repo-wide pages",+ hint: "Refreshes every page that summarizes the codebase. Costs the most.",+ },+];++export interface GenerateConfirmDialogProps {+ open: boolean;+ onOpenChange: (open: boolean) => void;+ mode?: RegenerateMode;+ /** Page title, shown in the body for context. */+ pageTitle?: string;+ cascade: RegenerateCascade;+ onCascadeChange: (next: RegenerateCascade) => void;+ /** Lazily-fetched estimate for the current cascade. `null` while unknown. */+ estimate?: {+ totalPages: number;+ /** Preformatted cost string (e.g. "$0.01 – $0.02"); omit when no provider. */+ costText?: string | null;+ staleCount?: number;+ } | null;+ /** True while the estimate request is in flight. */+ estimateLoading?: boolean;+ /** A non-fatal estimate error (the launch is still allowed). */+ estimateError?: string | null;+ /** When no provider is configured, the dialog routes to settings instead of+ * offering to launch. */+ noProvider?: boolean;+ settingsHref?: string;+ onConfirm: () => void;+ /** True once the launch request is in flight. */+ launching?: boolean;+}++export function GenerateConfirmDialog({+ open,+ onOpenChange,+ mode = "write",+ pageTitle,+ cascade,+ onCascadeChange,+ estimate,+ estimateLoading = false,+ estimateError,+ noProvider = false,+ settingsHref,+ onConfirm,+ launching = false,+}: GenerateConfirmDialogProps) {+ const isWrite = mode === "write";++ return (+ <Dialog open={open} onOpenChange={onOpenChange}>+ <DialogContent className="sm:max-w-md">+ <DialogHeader>+ <DialogTitle className="flex items-center gap-2">+ {isWrite && (+ <Sparkles className="h-4 w-4 text-[var(--color-accent-primary)]" />+ )}+ {isWrite ? "Write this page with AI" : "Regenerate this page"}+ </DialogTitle>+ </DialogHeader>++ {noProvider ? (+ <div className="space-y-4">+ <p className="text-sm text-[var(--color-text-secondary)]">+ No AI provider is configured for this repository yet. Add a model key+ to write documentation with AI.+ </p>+ <div className="flex justify-end gap-2">+ <Button variant="ghost" size="sm" onClick={() => onOpenChange(false)}>+ Cancel+ </Button>+ {settingsHref && (+ <Button asChild size="sm">+ <a href={settingsHref}>Add a provider key</a>+ </Button>+ )}+ </div>+ </div>+ ) : (+ <div className="space-y-4">+ {pageTitle && (+ <p className="text-sm text-[var(--color-text-secondary)]">+ {isWrite ? "Write" : "Regenerate"}{" "}+ <span className="font-medium text-[var(--color-text-primary)]">+ {pageTitle}+ </span>{" "}+ with your configured model.+ </p>+ )}++ <fieldset className="space-y-1.5">+ <legend className="text-xs font-medium text-[var(--color-text-secondary)]">+ What else to update+ </legend>+ {CASCADE_OPTIONS.map((opt) => (+ <label+ key={opt.value}+ className={cn(+ "flex cursor-pointer items-start gap-2.5 rounded-md border p-2.5 transition-colors",+ cascade === opt.value+ ? "border-[var(--color-border-active)] bg-[var(--color-accent-muted)]"+ : "border-[var(--color-border-default)] hover:bg-[var(--color-bg-inset)]",+ )}+ >+ <input+ type="radio"+ name="cascade"+ value={opt.value}+ checked={cascade === opt.value}+ onChange={() => onCascadeChange(opt.value)}+ className="mt-0.5 accent-[var(--color-accent-fill)]"+ />+ <span className="min-w-0">+ <span className="block text-sm text-[var(--color-text-primary)]">+ {opt.label}+ </span>+ <span className="block text-xs text-[var(--color-text-tertiary)]">+ {opt.hint}+ </span>+ </span>+ </label>+ ))}+ </fieldset>++ <div+ aria-live="polite"+ className="rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-inset)] px-3 py-2 text-xs text-[var(--color-text-secondary)]"+ >+ {estimateLoading ? (+ <span className="inline-flex items-center gap-1.5">+ <Loader2 className="h-3.5 w-3.5 animate-spin" />+ Analyzing the repository to price this accurately…+ </span>+ ) : estimate ? (+ <span>+ <span className="font-medium text-[var(--color-text-primary)]">+ {estimate.totalPages}+ </span>{" "}+ {estimate.totalPages === 1 ? "page" : "pages"} to write+ {estimate.costText ? (+ <>+ {" · est. "}+ <span className="font-medium text-[var(--color-text-primary)]">+ {estimate.costText}+ </span>+ </>+ ) : null}+ {estimate.staleCount ? (+ <> · {estimate.staleCount} marked stale</>+ ) : null}+ </span>+ ) : estimateError ? (+ <span className="text-[var(--color-warning)]">+ Couldn't estimate cost. {estimateError}+ </span>+ ) : (+ <span>Cost estimate unavailable.</span>+ )}+ </div>++ <div className="flex justify-end gap-2">+ <Button+ variant="ghost"+ size="sm"+ onClick={() => onOpenChange(false)}+ disabled={launching}+ >+ Cancel+ </Button>+ <Button size="sm" onClick={onConfirm} disabled={launching}>+ {launching ? (+ <Loader2 className="h-3.5 w-3.5 animate-spin" />+ ) : isWrite ? (+ <>+ <Sparkles className="mr-1.5 h-3.5 w-3.5" />+ Write with AI+ </>+ ) : (+ "Regenerate"+ )}+ </Button>+ </div>+ </div>+ )}+ </DialogContent>+ </Dialog>+ );+}diff --git a/packages/web/src/app/repos/[id]/settings/page.tsx b/packages/web/src/app/repos/[id]/settings/page.tsxindex 69975b142..0351e5796 100644--- a/packages/web/src/app/repos/[id]/settings/page.tsx+++ b/packages/web/src/app/repos/[id]/settings/page.tsx@@ -3,6 +3,7 @@ import Link from "next/link";import { notFound } from "next/navigation";import { Settings } from "lucide-react";import { WebhookSection } from "@/components/settings/webhook-section";+import { ProviderSettingsPanel } from "@/components/settings/provider-settings-panel";import { RefactoringSettingsSection } from "@/components/repos/refactoring-settings-section";import { getRepo } from "@/lib/api/repos";import { getCoordinatorHealth } from "@/lib/api/health";@@ -67,6 +68,19 @@ export default async function RepoSettingsPage({ params }: Props) {</CardContent></Card>+ <Card id="provider">+ <CardHeader>+ <CardTitle className="text-sm font-medium">AI provider</CardTitle>+ <CardDescription>+ Add a model key to write documentation with AI. Keys are stored with this+ repository and used by generation from the UI or the CLI.+ </CardDescription>+ </CardHeader>+ <CardContent className="pt-0">+ <ProviderSettingsPanel repoId={id} />+ </CardContent>+ </Card>+<Card><CardHeader><CardTitle className="text-sm font-medium">Refactoring code generation</CardTitle>@@ -98,7 +112,7 @@ export default async function RepoSettingsPage({ params }: Props) {<WebhookSection /><p className="text-xs text-[var(--color-text-tertiary)]">- Connection, provider and MCP configuration live in{" "}+ Server connection and MCP configuration live in{" "}<Linkhref="/settings"className="text-[var(--color-accent-primary)] hover:underline"diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsxindex dfeafe122..fc5d851ea 100644--- a/packages/web/src/components/docs/docs-explorer.tsx+++ b/packages/web/src/components/docs/docs-explorer.tsx@@ -27,6 +27,7 @@ import {ExportMenu,SidebarToggle,} from "./docs-page-actions";+import { PageGenerateButton } from "./page-generate-button";import { search as searchPages } from "@/lib/api/search";import { downloadTextFile } from "@/lib/utils/download";import { Skeleton } from "@repowise-dev/ui/ui/skeleton";@@ -38,7 +39,7 @@ interface DocsExplorerProps {}export function DocsExplorer({ repoId }: DocsExplorerProps) {- const { pages, isLoading } = usePages(repoId);+ const { pages, isLoading, mutate } = usePages(repoId);const [selectedPage, setSelectedPage] = useState<PageResponse | null>(null);const [treePanelOpen, setTreePanelOpen] = useState(() => {if (typeof window === "undefined") return true;@@ -91,6 +92,16 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {setSelectedPage(overview ?? pages[0]);}, [pages, pageParam, selectedPage]);+ // After a page is (re)generated, pull the fresh page list and re-point the+ // viewer at the updated object so its content and provenance flip in place.+ const handleGenerated = useCallback(async () => {+ const fresh = await mutate();+ setSelectedPage((prev) => {+ if (!prev || !fresh) return prev;+ return fresh.find((p) => p.id === prev.id) ?? prev;+ });+ }, [mutate]);+const handleSelectPage = useCallback((page: PageResponse) => {setSelectedPage(page);// Update URL without full navigation@@ -210,7 +221,10 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {pages={pages}selectedPageId={selectedPage?.id ?? null}onSelectPage={(p) => {- handleSelectPage(p);+ // DocsTree yields its DocPage type; the elements are the real+ // PageResponse objects we passed in (they carry the extra+ // provenance fields), so this narrowing is safe.+ handleSelectPage(p as unknown as PageResponse);if (typeof window !== "undefined" && !window.matchMedia("(min-width: 768px)").matches) {setTreePanelOpen(false);}@@ -261,6 +275,13 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {personaHasEffect={personaHasEffect}/>)}+ {selectedPage && (+ <PageGenerateButton+ page={selectedPage}+ repoId={repoId}+ onGenerated={handleGenerated}+ />+ )}<buttononClick={() => setSearchOpen(true)}className="flex items-center gap-2 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2.5 py-1.5 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-text-secondary)]"diff --git a/packages/web/src/components/docs/page-generate-button.tsx b/packages/web/src/components/docs/page-generate-button.tsxnew file mode 100644index 000000000..d649965fc--- /dev/null+++ b/packages/web/src/components/docs/page-generate-button.tsx@@ -0,0 +1,160 @@+"use client";++import { useCallback, useRef, useState } from "react";+import { toast } from "sonner";+import {+ RegenerateButton,+ GenerateConfirmDialog,+ type RegenerateCascade,+} from "@repowise-dev/ui/wiki/regenerate-button";+import { toFriendlyMessage } from "@repowise-dev/ui/lib/errors";+import { GenerationProgressWrapper } from "@/components/jobs/generation-progress-wrapper";+import { regeneratePage } from "@/lib/api/pages";+import { generateEstimate } from "@/lib/api/repos";+import type { PageResponse, GenerateEstimate } from "@/lib/api/types";++/** Format the estimate's cost range into a compact string. */+function formatCost(est: GenerateEstimate["estimate"]): string | null {+ if (!est) return null;+ const fmt = (n: number) => `$${n < 0.01 ? n.toFixed(4) : n.toFixed(2)}`;+ if (est.cost_low_usd != null && est.cost_high_usd != null) {+ return `${fmt(est.cost_low_usd)} to ${fmt(est.cost_high_usd)}`;+ }+ return fmt(est.estimated_cost_usd);+}++/**+ * Reader-side "Write with AI" / "Regenerate" for a single page. Owns the+ * lazily-fetched cost estimate, the cascade choice, the launch, and the live+ * progress — the shared `ui` components stay presentational.+ */+export function PageGenerateButton({+ page,+ repoId,+ onGenerated,+}: {+ page: PageResponse;+ repoId: string;+ /** Called once a run completes so the host can refresh the page list. */+ onGenerated?: () => void;+}) {+ const mode = page.is_deterministic ? "write" : "regenerate";+ const settingsHref = `/repos/${repoId}/settings#provider`;++ const [confirmOpen, setConfirmOpen] = useState(false);+ const [cascade, setCascade] = useState<RegenerateCascade>("none");+ const [estimate, setEstimate] = useState<GenerateEstimate | null>(null);+ const [estimateLoading, setEstimateLoading] = useState(false);+ const [estimateError, setEstimateError] = useState<string | null>(null);+ const [launching, setLaunching] = useState(false);+ const [jobId, setJobId] = useState<string | null>(null);++ // Cache estimates per cascade so toggling the choice back doesn't refetch the+ // heavy /generate/estimate endpoint.+ const cacheRef = useRef<Map<RegenerateCascade, GenerateEstimate>>(new Map());+ // The cascade whose estimate we currently want shown. A slow response for a+ // since-abandoned cascade must not overwrite the displayed one (latest wins).+ const wantedCascadeRef = useRef<RegenerateCascade>("none");++ const fetchEstimate = useCallback(+ async (which: RegenerateCascade) => {+ wantedCascadeRef.current = which;+ const cached = cacheRef.current.get(which);+ if (cached) {+ setEstimate(cached);+ setEstimateError(null);+ return;+ }+ setEstimateLoading(true);+ setEstimateError(null);+ try {+ const res = await generateEstimate(repoId, {+ selection: { kind: "page_ids", page_ids: [page.id] },+ cascade: which,+ });+ cacheRef.current.set(which, res);+ if (wantedCascadeRef.current === which) setEstimate(res);+ } catch (e) {+ if (wantedCascadeRef.current === which) {+ setEstimateError(toFriendlyMessage(e));+ setEstimate(null);+ }+ } finally {+ if (wantedCascadeRef.current === which) setEstimateLoading(false);+ }+ },+ [repoId, page.id],+ );++ function openConfirm() {+ cacheRef.current.clear();+ setEstimate(null);+ setEstimateError(null);+ setConfirmOpen(true);+ void fetchEstimate(cascade);+ }++ function changeCascade(next: RegenerateCascade) {+ setCascade(next);+ void fetchEstimate(next);+ }++ async function confirm() {+ setLaunching(true);+ try {+ const res = await regeneratePage(page.id, { cascade });+ setJobId(res.job_id);+ setConfirmOpen(false);+ } catch (e) {+ toast.error("Couldn't start generation", { description: toFriendlyMessage(e) });+ } finally {+ setLaunching(false);+ }+ }++ const noProvider = !!estimate && estimate.provider.name == null;++ return (+ <>+ <RegenerateButton+ mode={mode}+ onRegenerate={openConfirm}+ isLoading={launching && !jobId}+ isInProgress={jobId != null}+ onDialogClose={() => setJobId(null)}+ jobSlot={+ jobId != null ? (+ <GenerationProgressWrapper+ jobId={jobId}+ onDone={() => onGenerated?.()}+ />+ ) : null+ }+ />++ <GenerateConfirmDialog+ open={confirmOpen}+ onOpenChange={setConfirmOpen}+ mode={mode}+ pageTitle={page.title}+ cascade={cascade}+ onCascadeChange={changeCascade}+ estimate={+ estimate && !noProvider+ ? {+ totalPages: estimate.total_pages,+ costText: formatCost(estimate.estimate),+ staleCount: estimate.pages_to_mark_stale,+ }+ : null+ }+ estimateLoading={estimateLoading}+ estimateError={estimateError}+ noProvider={noProvider}+ settingsHref={settingsHref}+ onConfirm={confirm}+ launching={launching}+ />+ </>+ );+}diff --git a/packages/web/src/components/settings/provider-settings-panel.tsx b/packages/web/src/components/settings/provider-settings-panel.tsxnew file mode 100644index 000000000..a5fb13495--- /dev/null+++ b/packages/web/src/components/settings/provider-settings-panel.tsx@@ -0,0 +1,77 @@+"use client";++import { toast } from "sonner";+import { ProviderSettings } from "@repowise-dev/ui/settings/provider-settings";+import { Skeleton } from "@repowise-dev/ui/ui/skeleton";+import { toFriendlyMessage } from "@repowise-dev/ui/lib/errors";+import { useProviders } from "@/lib/hooks/use-providers";++/**+ * Web data wrapper around the shared `ProviderSettings` shell. Owns the fetch,+ * the repo-scoped key mutations (so D6 mirrors the key into `.repowise/.env`),+ * validation, and the toasts. The shell stays presentational and hosted-portable.+ */+export function ProviderSettingsPanel({ repoId }: { repoId: string }) {+ const {+ providers,+ active,+ validation,+ isLoading,+ saveKey,+ removeKey,+ activate,+ validate,+ } = useProviders(repoId);++ if (isLoading) {+ return (+ <div className="space-y-2.5">+ <Skeleton className="h-16 w-full" />+ <Skeleton className="h-16 w-full" />+ <Skeleton className="h-16 w-full" />+ </div>+ );+ }++ async function handleAddKey(providerId: string, key: string) {+ try {+ await saveKey(providerId, key);+ toast.success("API key saved", {+ description: "Written to this repo. Test it to confirm it works.",+ });+ } catch (e) {+ toast.error("Couldn't save the key", { description: toFriendlyMessage(e) });+ }+ }++ async function handleRemoveKey(providerId: string) {+ try {+ await removeKey(providerId);+ toast.info("API key removed");+ } catch (e) {+ toast.error("Couldn't remove the key", { description: toFriendlyMessage(e) });+ }+ }++ async function handleSetActive(providerId: string, model?: string) {+ try {+ await activate(providerId, model);+ } catch (e) {+ toast.error("Couldn't set the active provider", {+ description: toFriendlyMessage(e),+ });+ }+ }++ return (+ <ProviderSettings+ providers={providers}+ active={active}+ onAddKey={handleAddKey}+ onRemoveKey={handleRemoveKey}+ onSetActive={handleSetActive}+ onValidate={validate}+ validation={validation}+ />+ );+}diff --git a/packages/web/src/lib/hooks/use-providers.ts b/packages/web/src/lib/hooks/use-providers.tsindex 133320060..23b3fe64d 100644--- a/packages/web/src/lib/hooks/use-providers.ts+++ b/packages/web/src/lib/hooks/use-providers.ts@@ -1,13 +1,16 @@"use client";+import { useState } from "react";import useSWR from "swr";import {getProviders,setActiveProvider,addProviderKey,removeProviderKey,+ validateProviderKey,} from "@/lib/api/providers";import type { ProvidersResponse } from "@/lib/api/types";+import type { ProviderValidationState } from "@repowise-dev/ui/settings/provider-settings";export function useProviders(repoId?: string) {const { data, mutate, isLoading } = useSWR<ProvidersResponse>(@@ -16,6 +19,10 @@ export function useProviders(repoId?: string) {{ revalidateOnFocus: false },);+ const [validation, setValidation] = useState<+ Record<string, ProviderValidationState>+ >({});+const activeProvider = data?.active.provider ?? null;const activeModel = data?.active.model ?? null;@@ -24,23 +31,52 @@ export function useProviders(repoId?: string) {await mutate();}+ // Repo-scoped so D6 mirrors the key into the repo's .repowise/.env, making a+ // later CLI run in that repo see it. Without repoId the key stays+ // server-global and the CLI never picks it up.async function saveKey(providerId: string, key: string) {- await addProviderKey(providerId, key);+ await addProviderKey(providerId, key, repoId);await mutate();}async function removeKey(providerId: string) {- await removeProviderKey(providerId);+ await removeProviderKey(providerId, repoId);+ setValidation((v) => {+ const next = { ...v };+ delete next[providerId];+ return next;+ });await mutate();}+ async function validate(providerId: string) {+ setValidation((v) => ({ ...v, [providerId]: { status: "testing" } }));+ try {+ const res = await validateProviderKey(providerId, repoId);+ setValidation((v) => ({+ ...v,+ [providerId]: res.ok+ ? { status: "ok" }+ : { status: "error", error: res.error },+ }));+ } catch (e) {+ setValidation((v) => ({+ ...v,+ [providerId]: { status: "error", error: (e as Error).message },+ }));+ }+ }+return {providers: data?.providers ?? [],activeProvider,activeModel,+ active: data?.active ?? { provider: null, model: null },isLoading,+ validation,activate,saveKey,removeKey,+ validate,};}diff --git a/tests/unit/cli/test_update_provenance_partition.py b/tests/unit/cli/test_update_provenance_partition.pynew file mode 100644index 000000000..344393352--- /dev/null+++ b/tests/unit/cli/test_update_provenance_partition.py@@ -0,0 +1,134 @@+"""Per-page re-render mode on an index-only update.++A page a user upgraded to model prose must not silently revert to a template on+the next `repowise update`. `partition_regenerate_by_provenance` is the split+that keeps that promise: it reads each changed file's existing page provenance+and routes template pages to the free template render and model-written pages to+the model render.+"""++from __future__ import annotations++from datetime import UTC, datetime++import pytest++from repowise.cli.commands.update_cmd.deterministic import (+ partition_regenerate_by_provenance,+)+from repowise.core.generation.models import GeneratedPage+from repowise.core.persistence import (+ create_engine,+ create_session_factory,+ get_session,+ init_db,+ upsert_pages_from_generated,+ upsert_repository,+)+++def _page(path: str, provider_name: str) -> GeneratedPage:+ now = datetime.now(UTC).isoformat()+ return GeneratedPage(+ page_id=f"file_page:{path}",+ page_type="file_page",+ title=path,+ content="body",+ source_hash=f"hash-{path}",+ model_name="template" if provider_name == "template" else "gpt-x",+ provider_name=provider_name,+ input_tokens=0,+ output_tokens=0,+ cached_tokens=0,+ generation_level=2,+ target_path=path,+ created_at=now,+ updated_at=now,+ )+++def repo_dir(tmp_path, monkeypatch):+ (tmp_path / ".repowise").mkdir(parents=True, exist_ok=True)+ db = tmp_path / ".repowise" / "wiki.db"+ monkeypatch.setenv("REPOWISE_DB_URL", f"sqlite+aiosqlite:///{db.as_posix()}")+ return tmp_path+++def _seed(repo_dir, pages: list[GeneratedPage]) -> None:+ # Seed synchronously (asyncio.run, no running loop): the function under test+ # is called from sync CLI code and drives its own loop via ``run_async``, so+ # the whole test must stay off the event loop or that call raises.+ import asyncio+ import os++ async def _do() -> None:+ engine = create_engine(os.environ["REPOWISE_DB_URL"])+ try:+ await init_db(engine)+ sf = create_session_factory(engine)+ async with get_session(sf) as session:+ repo = await upsert_repository(+ session, name=repo_dir.name, local_path=str(repo_dir)+ )+ await upsert_pages_from_generated(session, pages, repo.id)+ finally:+ await engine.dispose()++ asyncio.run(_do())+++def test_splits_template_from_model(repo_dir):+ _seed(+ repo_dir,+ [+ _page("a.py", "template"),+ _page("b.py", "openai"),+ _page("c.py", "template"),+ ],+ )+ template, model = partition_regenerate_by_provenance(+ repo_dir, ["a.py", "b.py", "c.py"]+ )+ assert template == ["a.py", "c.py"]+ assert model == ["b.py"]+++def test_unknown_path_is_a_template(repo_dir):+ # A newly added file has no page yet — it renders as a template (the free,+ # safe default), never as a model page we can't afford.+ _seed(repo_dir, [_page("a.py", "openai")])+ template, model = partition_regenerate_by_provenance(repo_dir, ["a.py", "new.py"])+ assert template == ["new.py"]+ assert model == ["a.py"]+++def test_preserves_input_order(repo_dir):+ _seed(repo_dir, [_page("x.py", "openai"), _page("y.py", "template")])+ template, model = partition_regenerate_by_provenance(repo_dir, ["y.py", "x.py"])+ assert template == ["y.py"]+ assert model == ["x.py"]+++def test_empty_input_is_two_empty_lists(repo_dir):+ assert partition_regenerate_by_provenance(repo_dir, []) == ([], [])+++def test_lookup_failure_keeps_pages_never_reverts(tmp_path, monkeypatch):+ # When provenance can't be read, every path is treated as model-written so+ # the free template render can never overwrite (revert) a page we couldn't+ # classify. The caller then re-renders with a provider or keeps + marks stale.+ monkeypatch.setenv(+ "REPOWISE_DB_URL", f"sqlite+aiosqlite:///{(tmp_path / 'missing.db').as_posix()}"+ )++ def _boom(*_a, **_k):+ raise RuntimeError("db unavailable")++ monkeypatch.setattr(+ "repowise.cli.commands.update_cmd.deterministic._load_model_written_paths",+ _boom,+ )+ template, model = partition_regenerate_by_provenance(tmp_path, ["a.py", "b.py"])+ assert template == []+ assert model == ["a.py", "b.py"]diff --git a/tests/unit/server/test_provider_key_endpoint.py b/tests/unit/server/test_provider_key_endpoint.pyindex c962a6376..d30bd2c37 100644--- a/tests/unit/server/test_provider_key_endpoint.py+++ b/tests/unit/server/test_provider_key_endpoint.py@@ -112,6 +112,65 @@ async def test_add_key_resolves_non_primary_workspace_repo(client: AsyncClient,await ws_engine.dispose()+class _FakeProvider:+ provider_name = "anthropic"+ model_name = "claude-x"++ def __init__(self, raises: bool = False):+ self._raises = raises++ async def generate(self, *_a, **_k):+ if self._raises:+ raise RuntimeError("401 Unauthorized")+ return "OK"+++async def test_validate_ok_when_probe_succeeds(client: AsyncClient, monkeypatch) -> None:+ repo = await create_test_repo(client)+ from repowise.server import provider_config as pc++ monkeypatch.setattr(pc, "get_chat_provider_instance", lambda **_k: _FakeProvider())++ resp = await client.post(f"/api/providers/anthropic/validate?repo_id={repo['id']}")+ assert resp.status_code == 200+ body = resp.json()+ assert body == {"ok": True, "provider": "anthropic", "model": "claude-x", "error": None}+++async def test_validate_reports_probe_failure(client: AsyncClient, monkeypatch) -> None:+ repo = await create_test_repo(client)+ from repowise.server import provider_config as pc++ monkeypatch.setattr(+ pc, "get_chat_provider_instance", lambda **_k: _FakeProvider(raises=True)+ )++ resp = await client.post(f"/api/providers/anthropic/validate?repo_id={repo['id']}")+ assert resp.status_code == 200+ body = resp.json()+ assert body["ok"] is False+ assert "401" in body["error"]+++async def test_validate_reports_missing_key(client: AsyncClient, monkeypatch) -> None:+ repo = await create_test_repo(client)+ from repowise.server import provider_config as pc++ def _boom(**_k):+ raise ValueError("No active provider configured. Set an API key first.")++ monkeypatch.setattr(pc, "get_chat_provider_instance", _boom)++ resp = await client.post(f"/api/providers/anthropic/validate?repo_id={repo['id']}")+ assert resp.status_code == 200+ body = resp.json()+ assert body["ok"] is False+ assert "API key" in body["error"]++@pytest.mark.asyncioasync def test_get_providers_returns_no_key_material(client: AsyncClient) -> None:repo = await create_test_repo(client)