graphwiki 0.2.0__tar.gz → 0.3.0__tar.gz

{graphwiki-0.2.0 → graphwiki-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: graphwiki
-Version: 0.2.0
+Version: 0.3.0
 Summary: Graph-grounded code wiki generator: deterministic traversal, LLM writes prose only.
 Keywords: documentation,wiki,code-graph,llm,developer-tools
 Author: Mayur Pise
@@ -134,6 +134,7 @@ works.
 | `ollama` (default) | `http://localhost:11434/v1` | `gemma3` | No |
 | `nim` | `http://localhost:8000/v1` | `gemma` | No |
 | `offline` | none | none | No (no LLM at all) |
+| `agent` | none — a coding assistant writes the prose | No (no LLM/egress); see [Coding-assisted mode](#coding-assisted-mode-no-llm-api) |
 | `grok` | `https://api.x.ai/v1` | `grok-4` | **Yes** — external SaaS |
 | `claude` | `https://api.anthropic.com/v1` | `claude-opus-4-8` | **Yes** — external SaaS |
 | `openai` | `https://api.openai.com/v1` | `gpt-4o` | **Yes** — external SaaS |
@@ -155,19 +156,22 @@ page is sent unless you pass `--allow-cloud-egress` or set
 egress is never silent). A raw non-local `--base-url` (an internal NIM/Triton
 box) is only logged, never blocked. Full policy: [DATA_GOVERNANCE.md](docs/DATA_GOVERNANCE.md).
 
-> **Note:** these are model **APIs**. Coding-agent CLIs (Codex CLI, Claude Code)
-> are deliberately not supported as backends: they are interactive, tool-wielding
-> agents, whereas the writer needs a stateless completion that is fed ONLY the
-> pre-assembled graph context and forbidden from traversing — the invariant that
-> keeps citations verifiable. To use Claude, point `--base-url` at the Anthropic
-> API, not the CLI.
+> **Note:** the cloud/local rows above are model **APIs** reached over HTTP —
+> don't point `--base-url` at an interactive coding-agent CLI. When you want a
+> coding assistant to write the prose, use `--backend agent` (below): it feeds
+> the assistant the SAME stateless, pre-assembled context the API writer gets —
+> via prompt files, with no traversal tools — so citations stay verifiable.
 
 ### Coding-assisted mode (no LLM API)
 
-When no model endpoint is available, use the **graphwiki skill** with a coding
-assistant as the prose writer. Python still plans coverage and assembles context
-(`--backend offline`); the agent only rewrites narrative under the four `##`
-sections, then `graphwiki validate` gates the result.
+When no model endpoint is available, use `--backend agent` (or the **graphwiki
+skill**) to make a coding assistant the prose writer. Python still plans
+coverage and assembles context; the tool writes the exact `(system prompt,
+context)` pair the API writer sends into `wiki/.agent/prompts/<id>.md`, the
+assistant writes the four `§SECTION:` blocks back into
+`wiki/.agent/responses/<id>.md`, and a re-run feeds them through the same
+`merge → gate → emit` path — the assistant never edits a page. `graphwiki
+validate` gates the result.
 
 **Installers place the skill automatically** into every detected coding-assistant
 skill root (Claude Code, Cursor, GitHub Copilot, Grok, OpenAI Codex,
@@ -182,8 +186,10 @@ skill root (Claude Code, Cursor, GitHub Copilot, Grok, OpenAI Codex,
 graphwiki skill install          # detected assistants
 graphwiki skill install --all    # every known root
 graphwiki skill status
-graphwiki build . --backend offline --no-web
+graphwiki build . --backend agent --no-web
 # In the assistant: /graphwiki  or  "coding-assisted graphwiki"
+#   → narrate wiki/.agent/prompts/* into wiki/.agent/responses/*, then:
+graphwiki build . --backend agent --no-web   # ingests the responses
 graphwiki validate .
 ```
 

{graphwiki-0.2.0 → graphwiki-0.3.0}/README.md

@@ -106,6 +106,7 @@ works.
 | `ollama` (default) | `http://localhost:11434/v1` | `gemma3` | No |
 | `nim` | `http://localhost:8000/v1` | `gemma` | No |
 | `offline` | none | none | No (no LLM at all) |
+| `agent` | none — a coding assistant writes the prose | No (no LLM/egress); see [Coding-assisted mode](#coding-assisted-mode-no-llm-api) |
 | `grok` | `https://api.x.ai/v1` | `grok-4` | **Yes** — external SaaS |
 | `claude` | `https://api.anthropic.com/v1` | `claude-opus-4-8` | **Yes** — external SaaS |
 | `openai` | `https://api.openai.com/v1` | `gpt-4o` | **Yes** — external SaaS |
@@ -127,19 +128,22 @@ page is sent unless you pass `--allow-cloud-egress` or set
 egress is never silent). A raw non-local `--base-url` (an internal NIM/Triton
 box) is only logged, never blocked. Full policy: [DATA_GOVERNANCE.md](docs/DATA_GOVERNANCE.md).
 
-> **Note:** these are model **APIs**. Coding-agent CLIs (Codex CLI, Claude Code)
-> are deliberately not supported as backends: they are interactive, tool-wielding
-> agents, whereas the writer needs a stateless completion that is fed ONLY the
-> pre-assembled graph context and forbidden from traversing — the invariant that
-> keeps citations verifiable. To use Claude, point `--base-url` at the Anthropic
-> API, not the CLI.
+> **Note:** the cloud/local rows above are model **APIs** reached over HTTP —
+> don't point `--base-url` at an interactive coding-agent CLI. When you want a
+> coding assistant to write the prose, use `--backend agent` (below): it feeds
+> the assistant the SAME stateless, pre-assembled context the API writer gets —
+> via prompt files, with no traversal tools — so citations stay verifiable.
 
 ### Coding-assisted mode (no LLM API)
 
-When no model endpoint is available, use the **graphwiki skill** with a coding
-assistant as the prose writer. Python still plans coverage and assembles context
-(`--backend offline`); the agent only rewrites narrative under the four `##`
-sections, then `graphwiki validate` gates the result.
+When no model endpoint is available, use `--backend agent` (or the **graphwiki
+skill**) to make a coding assistant the prose writer. Python still plans
+coverage and assembles context; the tool writes the exact `(system prompt,
+context)` pair the API writer sends into `wiki/.agent/prompts/<id>.md`, the
+assistant writes the four `§SECTION:` blocks back into
+`wiki/.agent/responses/<id>.md`, and a re-run feeds them through the same
+`merge → gate → emit` path — the assistant never edits a page. `graphwiki
+validate` gates the result.
 
 **Installers place the skill automatically** into every detected coding-assistant
 skill root (Claude Code, Cursor, GitHub Copilot, Grok, OpenAI Codex,
@@ -154,8 +158,10 @@ skill root (Claude Code, Cursor, GitHub Copilot, Grok, OpenAI Codex,
 graphwiki skill install          # detected assistants
 graphwiki skill install --all    # every known root
 graphwiki skill status
-graphwiki build . --backend offline --no-web
+graphwiki build . --backend agent --no-web
 # In the assistant: /graphwiki  or  "coding-assisted graphwiki"
+#   → narrate wiki/.agent/prompts/* into wiki/.agent/responses/*, then:
+graphwiki build . --backend agent --no-web   # ingests the responses
 graphwiki validate .
 ```
 

{graphwiki-0.2.0 → graphwiki-0.3.0}/pyproject.toml

@@ -2,7 +2,7 @@
 # Name verified available on PyPI (2026-07-01). npm has an unrelated `graphwiki`
 # but this is a Python-only tool, so there is no conflict.
 name = "graphwiki"
-version = "0.2.0"
+version = "0.3.0"
 description = "Graph-grounded code wiki generator: deterministic traversal, LLM writes prose only."
 readme = "README.md"
 requires-python = ">=3.11"

{graphwiki-0.2.0 → graphwiki-0.3.0}/src/graphwiki/cli.py

@@ -27,7 +27,14 @@ from .graph_client import EngineError, GraphClient
 from .logging_util import echo as _echo
 from .state import State
 from .types import HOME_DIR, ConceptContext, ConceptType, Page
-from .writer import BACKENDS, CLOUD_BACKENDS, Writer, WriterConfig
+from .writer import (
+    BACKENDS,
+    CLOUD_BACKENDS,
+    AgentBridge,
+    Writer,
+    WriterConfig,
+    _serialize_context,
+)
 
 app = typer.Typer(add_completion=False, help="Graph-grounded code wiki generator.")
 skill_app = typer.Typer(
@@ -143,7 +150,9 @@ def _resolve_backend(
             )
             raise typer.Exit(code=2)
         preset_url, preset_model = BACKENDS[backend]
-        if backend == "offline":
+        if backend in ("offline", "agent"):
+            # agent has no endpoint either; an un-narrated page falls back to the
+            # offline template, so allow_offline must be set (else fail-loud).
             offline = True
         # Explicit (non-None) flags override the preset; else preset; else Ollama.
         resolved_url = base_url if base_url is not None else (preset_url or ollama_url)
@@ -196,7 +205,11 @@ def _resolve_backend(
         raise typer.Exit(code=2)
 
     return WriterConfig(
-        base_url=resolved_url, model=resolved_model, allow_offline=offline, api_key=key
+        base_url=resolved_url,
+        model=resolved_model,
+        allow_offline=offline,
+        api_key=key,
+        agent=backend == "agent",
     )
 
 
@@ -346,7 +359,27 @@ def _writer_fingerprint(cfg: WriterConfig) -> str:
     """Writer identity for staleness. A change here (backend/model/offline) must
     invalidate all pages even when the graph context is unchanged — otherwise
     ``update`` after switching backends is a silent no-op."""
-    return f"{cfg.model}|{cfg.base_url}|offline={cfg.allow_offline}"
+    return f"{cfg.model}|{cfg.base_url}|offline={cfg.allow_offline}|agent={cfg.agent}"
+
+
+def _report_agent_handoff(bridge: AgentBridge) -> None:
+    """Tell the coding assistant what prose is still owed after an agent-mode run.
+
+    Pass 1 (no responses yet) reports every page as pending and emits offline
+    fallback bodies (gate-valid). The assistant narrates the prompts, then a
+    re-run ingests the responses. Idempotent: re-runs re-report the true state.
+    """
+    narrated, pending = len(bridge.narrated), len(bridge.pending)
+    total = narrated + pending
+    _echo(f"[agent] {narrated}/{total} page(s) narrated, {pending} awaiting prose")
+    if pending:
+        _echo(
+            f"[agent] next: for each prompt in {bridge.prompts}/ write §SECTION: "
+            f"prose to {bridge.responses}/<same-name>, then re-run "
+            "`graphwiki build --backend agent`."
+        )
+    else:
+        _echo("[agent] all pages narrated — run `graphwiki validate` to gate.")
 
 
 def _fmt_eta(secs: float) -> str:
@@ -443,7 +476,16 @@ def _run(
 
         state = State(out)
         writer_fp = _writer_fingerprint(cfg)
-        targets = state.stale(contexts, writer_fp) if incremental else contexts
+        # Agent mode always regenerates every page: the two-phase (emit prompts →
+        # assistant writes responses → re-run to ingest) flow needs the second
+        # pass to re-render each page, which staleness would skip on an unchanged
+        # graph. Regeneration is offline-cheap, so this costs nothing but LLM-free
+        # passes over the plan.
+        targets = (
+            state.stale(contexts, writer_fp)
+            if (incremental and not cfg.agent)
+            else contexts
+        )
         _echo(
             f"[generate] {len(targets)}/{len(contexts)} pages "
             f"({'incremental' if incremental else 'full'})"
@@ -457,7 +499,15 @@ def _run(
         )
 
         _t = time.monotonic()
-        writer = Writer(cfg)
+        bridge: AgentBridge | None = None
+        if cfg.agent:
+            key_by_context = {
+                _serialize_context(c): c.concept.concept_id for c in targets
+            }
+            bridge = AgentBridge(out / ".agent", key_by_context)
+            writer = Writer(cfg, complete=bridge)
+        else:
+            writer = Writer(cfg)
         target_pages = _generate_pages(writer, targets)
         _log.debug(
             "generated %d page(s) in %.2fs", len(target_pages), time.monotonic() - _t
@@ -531,6 +581,8 @@ def _run(
             f"{len(target_pages)} page(s) emitted, gates {report.layers}",
         )
         _echo(f"[emit] {out} ({len(target_pages)} page(s) written)")
+        if bridge is not None:
+            _report_agent_handoff(bridge)
     finally:
         graph.close()
         if writer is not None:
@@ -609,7 +661,7 @@ def build(
     backend: str = typer.Option(
         None,
         "--backend",
-        help="Preset: ollama | nim | offline | grok | claude | openai. Sets base-url+model.",
+        help="Preset: ollama | nim | offline | agent | grok | claude | openai. Sets base-url+model.",
     ),
     base_url: str = typer.Option(
         None, "--base-url", help="OpenAI-compatible base URL (default: local Ollama)."
@@ -690,7 +742,7 @@ def update(
     backend: str = typer.Option(
         None,
         "--backend",
-        help="Preset: ollama | nim | offline | grok | claude | openai. Sets base-url+model.",
+        help="Preset: ollama | nim | offline | agent | grok | claude | openai. Sets base-url+model.",
     ),
     base_url: str = typer.Option(
         None, "--base-url", help="OpenAI-compatible base URL (default: local Ollama)."
@@ -858,6 +910,11 @@ def _doctor_backend(
     if backend == "offline":
         typer.echo("[doctor] backend: offline (deterministic bodies, no LLM/egress)")
         return
+    if backend == "agent":
+        typer.echo(
+            "[doctor] backend: agent (coding assistant writes prose; no LLM/egress)"
+        )
+        return
     if backend in CLOUD_BACKENDS:
         kind = (
             "CLOUD (needs --allow-cloud-egress + API key; sends code-derived context)"
@@ -998,7 +1055,9 @@ def _print_skill_results(results: list[skill_install.InstallResult]) -> None:
             "error": "x",
         }.get(r.status, "?")
         dest = str(r.dest) if r.dest else ""
-        detail = f" ({r.detail})" if r.detail and r.status in ("error", "skipped") else ""
+        detail = (
+            f" ({r.detail})" if r.detail and r.status in ("error", "skipped") else ""
+        )
         loc = f" → {dest}" if dest and r.status not in ("skipped",) else ""
         typer.echo(f"  [{mark}] {r.label}: {r.status}{loc}{detail}")
 
@@ -1081,7 +1140,7 @@ def watch(
     backend: str = typer.Option(
         None,
         "--backend",
-        help="Preset: ollama | nim | offline | grok | claude | openai. Sets base-url+model.",
+        help="Preset: ollama | nim | offline | agent | grok | claude | openai. Sets base-url+model.",
     ),
     base_url: str = typer.Option(
         None, "--base-url", help="OpenAI-compatible base URL (default: local Ollama)."

{graphwiki-0.2.0 → graphwiki-0.3.0}/src/graphwiki/logging_util.py

@@ -81,11 +81,7 @@ def configure(*, verbosity: int = 0, quiet: bool = False, json: bool = False) ->
     if json:
         handler.setFormatter(_JsonFormatter())
     else:
-        fmt = (
-            "%(levelname)s %(name)s: %(message)s"
-            if verbosity >= 2
-            else "%(message)s"
-        )
+        fmt = "%(levelname)s %(name)s: %(message)s" if verbosity >= 2 else "%(message)s"
         handler.setFormatter(logging.Formatter(fmt))
 
     _state.update(verbosity=verbosity, quiet=quiet, json=json)

{graphwiki-0.2.0 → graphwiki-0.3.0}/src/graphwiki/render.py

@@ -109,8 +109,16 @@ def _safe_label(text: str) -> str:
     inject markup into the viewer. Map the dangerous chars to readable-but-inert
     equivalents rather than trusting the names to be clean."""
     for bad, good in (
-        ("&", "+"), ("<", "("), (">", ")"), ('"', "'"),
-        ("[", "("), ("]", ")"), ("{", "("), ("}", ")"), ("|", "/"), ("`", "'"),
+        ("&", "+"),
+        ("<", "("),
+        (">", ")"),
+        ('"', "'"),
+        ("[", "("),
+        ("]", ")"),
+        ("{", "("),
+        ("}", ")"),
+        ("|", "/"),
+        ("`", "'"),
     ):
         text = text.replace(bad, good)
     return text

{graphwiki-0.2.0 → graphwiki-0.3.0}/src/graphwiki/skill_install.py

@@ -218,9 +218,7 @@ def status_skills(*, home: Path | None = None) -> list[InstallResult]:
                 InstallResult(tool, label, dest, "skipped", "skill not installed")
             )
         elif _trees_equal(src, dest):
-            results.append(
-                InstallResult(tool, label, dest, "unchanged", "up to date")
-            )
+            results.append(InstallResult(tool, label, dest, "unchanged", "up to date"))
         else:
             results.append(
                 InstallResult(tool, label, dest, "updated", "installed but stale")

graphwiki-0.3.0/src/graphwiki/skills/graphwiki/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: graphwiki
+description: >
+  Coding-assisted graphwiki — generate or refresh a graph-grounded code wiki
+  when no LLM API/backend is available. The coding assistant acts as the
+  prose writer only; Python still decides coverage and context. Use when the
+  user asks to "build graphwiki offline", "coding-assisted graphwiki",
+  "graphwiki without ollama/nim/api", "narrate the wiki", "rewrite offline
+  stubs", "agent-assisted wiki", or runs /graphwiki. Also use when graphwiki
+  build fails for lack of a model endpoint and the user wants quality prose
+  instead of deterministic offline templates.
+---
+
+# Coding-Assisted GraphWiki
+
+Run **graphwiki** with a coding assistant (Claude Code, Grok, Cursor, Codex, …)
+as the writer when no model API is reachable. This is **not** free-form repo
+documentation (OpenWiki/deepagents style). Coverage, context, citations, and
+gates stay owned by the Python tool.
+
+**How it works — `--backend agent` makes you a drop-in for the LLM.** The tool
+builds the graph, plans coverage, and assembles each page's context, then writes
+the SAME `(system prompt, context)` pair the online writer sends to an API into
+`wiki/.agent/prompts/<id>.md`. You write the four `§SECTION:` blocks back to
+`wiki/.agent/responses/<id>.md`. A re-run feeds your prose through the exact same
+`merge → assemble → gate → emit` path the API-key writer uses. You never open or
+edit a page under `wiki/` — Python assembles the frontmatter, fact lists, and
+Mermaid **around** your prose, so you cannot corrupt the deterministic parts.
+
+## Frozen invariants (do not break)
+
+| Layer | Owner | Agent may… |
+|---|---|---|
+| What to document (coverage law) | `graphwiki plan` | Never decide, never drop a required page |
+| What facts each page gets | `graphwiki` context assembly | Never invent members/callers/paths |
+| Narrative prose | **this skill / the agent (as the writer)** | Write the four `§SECTION:` blocks into the response file only |
+| Frontmatter, Mermaid, fact lists, page files | Python | **Never write or edit** — assembled around your prose |
+| Validation | `graphwiki validate` | Must pass before claiming done |
+
+**Anti-pattern:** grepping the repo and writing new path citations. That
+reintroduces hallucination and fails the citation gate. Ground every claim in
+the context the prompt file hands you (its `# Context` block) — nothing else.
+
+Full invariant detail: `references/invariants.md`.
+
+## Prerequisites
+
+```bash
+# Prefer uv on host
+uv tool install graphwiki          # or: uvx graphwiki …
+# Engine auto-fetches on first build (or pin --engine-bin)
+graphwiki doctor . --backend agent # engine + index healthy; no LLM needed
+```
+
+If `doctor` fails on the engine, fix that first — the agent cannot replace the
+graph engine.
+
+## Modes
+
+### A. Assisted build (no LLM API) — default
+
+Use when Ollama/NIM/cloud are unavailable or the user wants agent-written prose.
+
+```
+1. Build graph + emit per-page prompts (deterministic, no network):
+   graphwiki build . --backend agent --no-web
+   # Indexes the repo, plans coverage, assembles context, writes one prompt to
+   # wiki/.agent/prompts/<id>.md per page, and emits offline-fallback pages so
+   # the wiki is gate-valid immediately. The final [agent] line reports how many
+   # pages still await prose.  (optional: --out PATH, --allow-defer GLOB, --engine-bin PATH)
+
+2. Narrate each prompt (see "Narration recipe"): for every file in
+   wiki/.agent/prompts/, write §SECTION prose to wiki/.agent/responses/<same-name>.
+   Prioritize high x-hotspot-score pages first if the tree is large.
+
+3. Ingest + gate (re-run is idempotent):
+   graphwiki build . --backend agent --no-web
+   graphwiki validate .
+   # The re-run feeds your responses through the same writer path an LLM uses.
+   # Repeat step 2 → step 3 until [agent] reports "0 awaiting prose".
+
+4. Optional viewer:
+   graphwiki web --no-open   # or open the URL
+```
+
+Your responses persist in `wiki/.agent/responses/` — that directory is the
+durable narration store. Every `build --backend agent` re-derives the pages from
+`(graph + responses)`, so the flow is fully reproducible.
+
+### B. Assisted refresh (after code changes)
+
+```
+1. graphwiki build . --backend agent --no-web
+   # Re-indexes; each page's prompt now reflects current context; existing
+   # responses are re-applied. Pages whose context moved get an updated prompt.
+2. Re-narrate the prompts whose # Context changed (or that the user named);
+   leave the rest — their prior response still applies.
+3. graphwiki build . --backend agent --no-web  &&  graphwiki validate .
+```
+
+### C. Editorial polish (prose only)
+
+Existing wiki already gate-valid; user wants better narrative.
+
+```
+1. Edit the §SECTION prose in wiki/.agent/responses/<id>.md (NOT the page under
+   wiki/ — that is derived and will be overwritten on the next run).
+2. graphwiki build . --backend agent --no-web   # re-derives the page
+3. graphwiki validate .
+```
+
+### D. Consume wiki while coding (read path)
+
+Not generation. Point the agent at `wiki/.ai-context.md` and relevant pages,
+or run `graphwiki serve` (MCP: `read_wiki_structure` / `read_wiki_contents` /
+`ask_question`). Do not invent pages in this mode.
+
+## Pending pages (what still needs prose)
+
+Two signals, in order of authority:
+
+```bash
+# Authoritative: the run's own report
+#   [agent] 3/17 page(s) narrated, 14 awaiting prose
+# A prompt with no matching response file is pending:
+comm -23 <(cd wiki/.agent/prompts && ls) <(cd wiki/.agent/responses && ls 2>/dev/null)
+
+# Secondary: a derived page still carrying the offline template signature
+rg -n "documented from the code knowledge graph" wiki -g '*.md'
+```
+
+After you narrate and re-run, the pending count drops and the offline signature
+disappears from that page.
+
+## Narration recipe (one page)
+
+Load `references/page-format.md` once; apply for every page.
+
+1. **Read** the prompt file `wiki/.agent/prompts/<id>.md`. It contains:
+   - `# System instructions` — the writer contract (identical to the LLM's
+     system prompt). It defines the four sections and the `§SECTION:` markers.
+   - `# Context — the ONLY source of truth` — concept type, title, resource,
+     public surface, members, child modules, callers, blast radius, tests.
+2. **Do not** open source files or the page under `wiki/` to "learn more" for new
+   citations. The `# Context` block is the complete, only source of truth.
+   Optional peek at `resource` only to phrase responsibility accurately; still
+   cite only names/paths already in the context.
+3. **Write only** the four `§SECTION:` blocks to
+   `wiki/.agent/responses/<id>.md`, each introduced by a line that is EXACTLY:
+   ```
+   §SECTION: purpose
+   §SECTION: architecture
+   §SECTION: key_types
+   §SECTION: fit
+   ```
+   Nothing else — no frontmatter, no `##` headings, no code fences, no fact
+   lists. Python assembles all of that around your prose.
+4. **Prose rules** (they are also stated in the prompt's system block — follow it):
+   - Concrete, not boilerplate; explain the graph facts, do not restate raw lists
+   - Reference ONLY symbols/paths present in the `# Context` block
+   - A short bulleted list is allowed ONLY in `key_types`
+   - If a list (callers/tests/public surface) is empty, say so plainly (leaf / no
+     public surface / untested) — do not invent
+   - Clear depth floors (the tool's anti-stub gate; offline fallback already
+     clears them, so match or exceed): Subsystem ≥200, Module/Feature/Entrypoint
+     ≥120, API/DataModel ≥80 chars of prose
+
+## Batch strategy
+
+For large wikis:
+
+1. Run `build --backend agent` once to emit all prompts.
+2. Sort prompts by their page's `x-hotspot-score` (highest first — hotspot lives
+   in the emitted page frontmatter, or narrate the prompts flagged pending).
+3. Narrate responses in batches of 5–15, then run
+   `graphwiki build --backend agent && graphwiki validate .` so failures stay local.
+4. Skip deferred / non-required concepts (no prompt is emitted for them).
+
+Do not hand-create prompt or page files — re-run `graphwiki build --backend
+agent` to (re)materialize the plan.
+
+## Failure handling
+
+| Symptom | Action |
+|---|---|
+| `doctor` engine missing | Fix engine (`--engine-bin` or auto-fetch); do not free-write a wiki |
+| `validate` structure/quality fail | Narrate the named page's response deeper (below the anti-stub floor) |
+| `validate` citations fail | Remove the invented path token from that response; re-run + re-validate |
+| `validate` coverage fail | Re-run `build --backend agent` — do not invent missing pages |
+| A response is ignored on re-run | Confirm the filename matches its prompt exactly (`<id>.md`) and has `§SECTION:` markers |
+| User wants cloud/local API instead | Prefer `graphwiki build . --backend ollama\|nim\|…` over this skill |
+
+## Done criteria
+
+- [ ] `graphwiki validate .` exits 0
+- [ ] The run reports `0 awaiting prose` (every required page has a response)
+- [ ] No page still contains `documented from the code knowledge graph`
+- [ ] You wrote only response files — never a page under `wiki/`
+- [ ] Summary for the user: pages narrated, validate OK, how to serve
+      (`graphwiki web` or `graphwiki serve`)
+
+## CLI cheat sheet
+
+```bash
+graphwiki doctor . --backend agent
+graphwiki build . --backend agent --no-web    # emit prompts + ingest responses
+graphwiki validate .
+graphwiki web
+graphwiki serve --out wiki                     # needs mcp extra
+```
+
+Backend note: `agent` is a first-class backend — it substitutes YOU for the LLM
+in the writer's one completion call. The offline scaffold still exists as the
+per-page fallback when a response is missing (`--backend offline` for a pure
+deterministic wiki with no agent). See product README.
+
+## Additional resources
+
+- `references/invariants.md` — why agents must not traverse for generation
+- `references/page-format.md` — the `§SECTION:` response contract + what Python owns

{graphwiki-0.2.0 → graphwiki-0.3.0}/src/graphwiki/skills/graphwiki/references/invariants.md

@@ -23,8 +23,10 @@ plugged in as free-form backends.
    and citation ground truth.
 
 OpenWiki-style deepagents (shell + FS tools freely traversing the repo to write
-docs) is explicitly **WON'T-DO** on the generation path. Bounded prose-only
-work on already-scaffolded pages is the only agent role that fits.
+docs) is explicitly **WON'T-DO** on the generation path. Writing bounded
+prose-only `§SECTION:` responses to the tool's per-page prompts (`--backend
+agent`) is the only agent role that fits — you substitute for the LLM's one
+completion call, nothing more.
 
 ## Citation rule (anti-hallucination)
 
@@ -32,12 +34,11 @@ Any path-shaped inline-code token (e.g. `` `src/foo/bar.py` ``, `` `writer.py` `
 in a page must resolve to a path the graph indexed. The citation gate enforces
 this on validate when the engine is available.
 
-**Safe citation set for agents:**
+**Safe citation set for agents** (all drawn from the prompt's `# Context` block):
 
-- `resource` from frontmatter
-- basenames / paths already in **Public surface**, **Used by**, **Blast radius**,
-  **Tests**, **Child modules**, or mermaid node labels
-- symbols already listed on the page
+- `RESOURCE` from the context
+- names/paths already in `PUBLIC SURFACE`, `USED BY`, `BLAST RADIUS`, `TESTS`,
+  `CHILD MODULES`, or `MEMBERS`
 
 **Unsafe:** any new path discovered by reading the filesystem during narration.
 
@@ -46,11 +47,11 @@ this on validate when the engine is available.
 | Mode | Prose source | Network | When |
 |---|---|---|---|
 | `--backend offline` | Deterministic templates from graph facts | None | CI, scaffold, demos |
-| **This skill** | Coding assistant, facts from scaffold page | None for generation | No API; want quality prose |
+| **`--backend agent` (this skill)** | Coding assistant, facts from the prompt's `# Context` | None for generation | No API; want quality prose |
 | `--backend ollama\|nim\|…` | Model API completion | Local or cloud (gated) | Normal automated runs |
 
-Assisted mode should start from an offline scaffold so frontmatter, lists, and
-diagrams stay tool-authored.
+Agent mode reuses the offline template as the per-page fallback, so frontmatter,
+lists, and diagrams stay tool-authored no matter which pages you narrate.
 
 ## Incremental honesty
 

graphwiki-0.3.0/src/graphwiki/skills/graphwiki/references/page-format.md

@@ -0,0 +1,123 @@
+# Response format (`§SECTION:` writer contract)
+
+Under `--backend agent` you write **response files**, not pages. Python derives
+each page under `wiki/` from `(graph context + your response)`. You never open a
+page file.
+
+Default output tree: `<repo>/wiki/` (`--out` overrides).
+
+## Tree
+
+```
+wiki/
+  .ai-context.md          # index — tool-owned
+  architecture.md         # system Mermaid — tool-owned
+  log.md                  # run log — tool-owned
+  .state/                 # refresh hashes — tool-owned
+  .agent/
+    prompts/<id>.md       # tool-emitted: system prompt + context. READ ONLY.
+    responses/<id>.md     # YOU write this: the four §SECTION blocks.
+  systems/*.md            # DERIVED page (Subsystem + Module) — do not edit
+  features/*.md           # DERIVED page (Feature) — do not edit
+  entrypoints/*.md        # DERIVED page (Entrypoint) — do not edit
+  reference/*.md          # DERIVED page (API, DataModel, …) — do not edit
+```
+
+## The prompt file you read (`wiki/.agent/prompts/<id>.md`)
+
+```markdown
+<!-- graphwiki agent writer prompt: <id> — DO NOT EDIT. ... -->
+
+# System instructions
+<the writer contract: the four sections, the §SECTION: markers, the prose rules>
+
+# Context — the ONLY source of truth
+CONCEPT TYPE: <Module|Subsystem|Feature|Entrypoint|…>
+TITLE: <title>
+RESOURCE: <canonical path or symbol>
+PUBLIC SURFACE: <symbols…>        # present only if non-empty
+MEMBERS: <symbols…>
+CHILD MODULES: <names…>
+USED BY (callers): <names…>
+BLAST RADIUS (dependents): <names…>
+TESTS: <paths…>
+```
+
+The context is a fixed extract from the code knowledge graph. It is the **only**
+source of truth. Never introduce a name, path, caller, or test not present in it.
+
+## The response file you write (`wiki/.agent/responses/<id>.md`)
+
+Exactly four blocks, each opened by a line that is EXACTLY the marker (no `##`
+heading, no numbering, no frontmatter, no code fences):
+
+```text
+§SECTION: purpose
+1–2 short paragraphs: what this concept is and the responsibility it owns.
+Concrete, not boilerplate.
+
+§SECTION: architecture
+1 short paragraph: how it is structured and how it relates to what it depends on
+or is used by. If the context lists child modules or a diagram, narrate what it
+shows — Python renders the actual Mermaid; you do not.
+
+§SECTION: key_types
+A few sentences on the most important types/functions in the public surface and
+what each is for. Reference ONLY names in the context. A short bulleted list is
+allowed here (and only here). If the surface is empty, say so in one sentence.
+
+§SECTION: fit
+1 short paragraph: who calls it, what breaks if it changes (its blast radius),
+how it is tested. Ground every claim in the callers/blast-radius/tests given.
+```
+
+Parsing is on the markers: any preamble before the first `§SECTION:` and any
+unknown marker is dropped. A section you omit is filled from the offline
+template, so a partial response still yields a complete page — but an empty or
+marker-less response leaves the page on the offline stub.
+
+## What Python owns (you never write it)
+
+- The YAML frontmatter (`type`, `title`, `description` routing key, `resource`,
+  `x-callers`, `x-grounded-paths`, `x-hotspot-score`)
+- The `## Purpose & Capabilities` / `## Architecture` / `## Key Types` /
+  `## How It Fits` headings
+- Every fact panel: `**Child modules:**`, `**Public surface:**`, `**Used by:**`,
+  `**Blast radius** …`, `**Tests:**` and their list items
+- The `` ```mermaid `` diagram fences
+
+`type` is a frozen vocabulary and `description` is a routing decision ("should I
+open this?"), not a summary — both are tool-owned; do not attempt to influence
+them from a response.
+
+## Example (shape only)
+
+Prompt `# Context` says: `TITLE: writer`, `RESOURCE: src/graphwiki/writer.py`,
+`PUBLIC SURFACE: Writer, WriterConfig, WriterError`, `MEMBERS: 12 symbols`.
+
+Response `wiki/.agent/responses/writer.md`:
+
+```text
+§SECTION: purpose
+`writer` owns page narration for a single pre-assembled concept. It turns graph
+context into structured body sections, using either an OpenAI-compatible
+completion or deterministic offline templates. It is fed one concept at a time;
+it does not plan coverage or query the graph.
+
+§SECTION: architecture
+It is a thin renderer around one completion call: the config selects the backend,
+the writer serializes the context, and the parsed sections are merged with
+deterministic fact panels assembled by the caller.
+
+§SECTION: key_types
+`Writer` runs the per-page render; `WriterConfig` carries backend/model/offline
+identity; `WriterError` fails a page loud when an online completion is empty.
+
+§SECTION: fit
+It sits below planning and context assembly and above emit. Changing its section
+contract ripples to every page, so its blast radius is the whole wiki; the writer
+test suite exercises the offline, partial, and fail-loud paths.
+```
+
+Python renders the frontmatter, the four headings, and the public-surface / used-by
+/ blast-radius / tests panels around this prose.

{graphwiki-0.2.0 → graphwiki-0.3.0}/src/graphwiki/writer.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any
 
 from .types import HOME_DIR, ConceptContext, Frontmatter, Page
@@ -87,6 +88,7 @@ BACKENDS: dict[str, tuple[str, str]] = {
     "ollama": ("http://localhost:11434/v1", "gemma3"),
     "nim": ("http://localhost:8000/v1", "gemma"),
     "offline": ("", ""),
+    "agent": ("", ""),  # coding assistant writes prose; no endpoint (see AgentBridge)
     "grok": ("https://api.x.ai/v1", "grok-4"),
     "claude": ("https://api.anthropic.com/v1", "claude-opus-4-8"),
     "openai": ("https://api.openai.com/v1", "gpt-4o"),
@@ -104,6 +106,7 @@ class WriterConfig:
     api_key: str = "not-needed"  # local endpoints ignore it
     temperature: float = 0.0  # determinism-friendly
     allow_offline: bool = False  # deterministic body if no LLM
+    agent: bool = False  # coding assistant is the writer (see AgentBridge)
 
 
 class WriterError(Exception):
@@ -458,3 +461,68 @@ def _assemble_body(sections: dict[str, str], ctx: ConceptContext) -> str:
         parts.append("")
 
     return "\n".join(parts).rstrip() + "\n"
+
+
+# ── agent backend: coding assistant as a drop-in for the LLM ─────────────────
+_AGENT_PROMPT_MARK = "graphwiki agent writer prompt"
+
+
+class AgentBridge:
+    """File-backed ``Complete`` — the coding assistant IS the model.
+
+    Realizes ``--backend agent``, the true-parity path for coding assistants:
+    instead of an LLM call, each page's ``(SYSTEM_PROMPT, serialized-context)``
+    — the EXACT pair the online writer sends — is written to
+    ``<out>/.agent/prompts/<concept_id>.md``. When the assistant has already
+    written the matching ``<out>/.agent/responses/<concept_id>.md`` (raw
+    ``§SECTION:`` prose), its text is returned so the SAME
+    ``_merge_sections`` → ``_assemble_body`` → gate path renders the page — no
+    different code path from the API-key writer. A page with no response yet
+    returns "" so the offline template fills it (build stays green); it is
+    reported as ``pending`` for the handoff.
+
+    The assistant never sees frontmatter, fact lists, or Mermaid — Python
+    assembles those AFTER this returns, so agent prose cannot corrupt the
+    deterministic sections (the footgun of the old scaffold-then-edit skill).
+
+    ``key_by_context`` maps each page's serialized context back to its
+    concept_id so prompt/response files are human-addressable. Two concepts with
+    identical assembled context legitimately share a file — identical context
+    means identical prose, which is the deterministic-correct outcome.
+    """
+
+    def __init__(self, agent_dir: Path, key_by_context: dict[str, str]) -> None:
+        self.prompts = agent_dir / "prompts"
+        self.responses = agent_dir / "responses"
+        self.prompts.mkdir(parents=True, exist_ok=True)
+        self.responses.mkdir(parents=True, exist_ok=True)
+        self._key = key_by_context
+        self.pending: list[str] = []
+        self.narrated: list[str] = []
+
+    def _concept_id(self, user: str) -> str:
+        cid = self._key.get(user)
+        if cid:
+            return cid
+        import hashlib
+
+        return "ctx-" + hashlib.sha1(user.encode("utf-8")).hexdigest()[:12]
+
+    def __call__(self, system: str, user: str) -> str:
+        cid = self._concept_id(user)
+        (self.prompts / f"{cid}.md").write_text(
+            f"<!-- {_AGENT_PROMPT_MARK}: {cid} — DO NOT EDIT.\n"
+            f"     Write your prose (the four §SECTION: blocks described below)\n"
+            f"     to ../responses/{cid}.md, then re-run"
+            f" `graphwiki build --backend agent`. -->\n\n"
+            f"# System instructions\n\n{system}\n\n"
+            f"# Context — the ONLY source of truth\n\n{user}\n",
+            encoding="utf-8",
+        )
+        resp = self.responses / f"{cid}.md"
+        text = resp.read_text(encoding="utf-8").strip() if resp.is_file() else ""
+        if text:
+            self.narrated.append(cid)
+            return text
+        self.pending.append(cid)
+        return ""

graphwiki-0.2.0/src/graphwiki/skills/graphwiki/SKILL.md

@@ -1,202 +0,0 @@
----
-name: graphwiki
-description: >
-  Coding-assisted graphwiki — generate or refresh a graph-grounded code wiki
-  when no LLM API/backend is available. The coding assistant acts as the
-  prose writer only; Python still decides coverage and context. Use when the
-  user asks to "build graphwiki offline", "coding-assisted graphwiki",
-  "graphwiki without ollama/nim/api", "narrate the wiki", "rewrite offline
-  stubs", "agent-assisted wiki", or runs /graphwiki. Also use when graphwiki
-  build fails for lack of a model endpoint and the user wants quality prose
-  instead of deterministic offline templates.
----
-
-# Coding-Assisted GraphWiki
-
-Run **graphwiki** with a coding assistant (Claude Code, Grok, Cursor, Codex, …)
-as the writer when no model API is reachable. This is **not** free-form repo
-documentation (OpenWiki/deepagents style). Coverage, context, citations, and
-gates stay owned by the Python tool.
-
-## Frozen invariants (do not break)
-
-| Layer | Owner | Agent may… |
-|---|---|---|
-| What to document (coverage law) | `graphwiki plan` | Never decide, never drop a required page |
-| What facts each page gets | `graphwiki` context assembly | Never invent members/callers/paths |
-| Narrative prose | **this skill / the agent** | Rewrite only the prose under the four `##` sections |
-| Frontmatter, Mermaid, fact lists | Python / offline scaffold | **Never edit** |
-| Validation | `graphwiki validate` | Must pass before claiming done |
-
-**Anti-pattern:** grepping the repo and writing new path citations. That
-reintroduces hallucination and fails the citation gate. Ground every claim in
-facts already present on the page (frontmatter + deterministic sections).
-
-Full invariant detail: `references/invariants.md`.
-
-## Prerequisites
-
-```bash
-# Prefer uv on host
-uv tool install graphwiki          # or: uvx graphwiki …
-# Engine auto-fetches on first build (or pin --engine-bin)
-graphwiki doctor .                 # engine + index healthy; no LLM needed
-```
-
-If `doctor` fails on the engine, fix that first — the agent cannot replace the
-graph engine.
-
-## Modes
-
-### A. Assisted build (no LLM API) — default
-
-Use when Ollama/NIM/cloud are unavailable or the user wants agent-written prose.
-
-```
-1. Scaffold (deterministic, no network):
-   graphwiki build . --backend offline --no-web
-   # optional: --out PATH, --allow-defer GLOB, --engine-bin PATH
-
-2. Narrate every required page under wiki/ (see "Narration recipe").
-   Prioritize high x-hotspot-score pages first if the tree is large.
-
-3. Gate:
-   graphwiki validate .
-
-4. Optional viewer:
-   graphwiki web --no-open   # or open the URL
-```
-
-### B. Assisted update (incremental)
-
-```
-1. graphwiki update . --backend offline --no-web
-2. Narrate only pages whose body still matches the offline stub signature
-   (see "Stub detection") or that the user named.
-3. graphwiki validate .
-```
-
-### C. Editorial polish (prose only)
-
-Existing wiki already gate-valid; user wants better narrative without a rebuild.
-
-```
-1. Do NOT re-run build (preserves state hashes).
-2. Edit prose only under the four ## sections.
-3. graphwiki validate .
-```
-
-### D. Consume wiki while coding (read path)
-
-Not generation. Point the agent at `wiki/.ai-context.md` and relevant pages,
-or run `graphwiki serve` (MCP: `read_wiki_structure` / `read_wiki_contents` /
-`ask_question`). Do not invent pages in this mode.
-
-## Stub detection
-
-Offline scaffold prose is graph-grounded but thin. Identify stubs by content:
-
-```bash
-# Offline template signature (primary)
-rg -n "documented from the code knowledge graph" wiki -g '*.md'
-
-# Optional: short Architecture-only stubs
-rg -n "The graph records no internal sub-structure" wiki -g '*.md'
-```
-
-A page that still contains either phrase needs narration. After rewrite, those
-phrases must be gone.
-
-## Narration recipe (one page)
-
-Load `references/page-format.md` once; apply for every page.
-
-1. **Read** the page fully (frontmatter + body). The page *is* the context —
-   it already carries resource, callers, blast radius, public surface, tests,
-   child modules, Mermaid.
-2. **Do not** open source files to "learn more" for new citations. Optional
-   peek at `resource` only to phrase responsibility accurately; still cite only
-   names/paths already on the page.
-3. **Rewrite only** the narrative paragraphs under:
-   - `## Purpose & Capabilities`
-   - `## Architecture`
-   - `## Key Types`
-   - `## How It Fits`
-4. **Leave untouched:**
-   - Entire YAML frontmatter
-   - `**Child modules:**` lists
-   - Fenced ` ```mermaid ` blocks
-   - `**Public surface:**` / `**Used by:**` / `**Blast radius**` / `**Tests:**` lists
-5. **Prose rules** (same intent as the online writer system prompt):
-   - Concrete, not boilerplate; explain the graph facts, do not restate raw lists
-   - Reference ONLY symbols/paths already present on the page
-   - Inline-code path citations (`foo/bar.py`) must resolve to something the
-     graph indexed — safest: only cite `resource`, list basenames, or symbols
-     already shown
-   - No new frontmatter, no code fences in narrative, no inventing callers/tests
-   - Clear anti-stub floors (chars of body including deterministic sections —
-     offline scaffold already clears them; keep depth, do not shrink):
-     Subsystem ≥200, Module/Feature/Entrypoint ≥120, API/DataModel ≥80
-6. **Write** the file in place under `wiki/` (default `--out`).
-
-### Quality bar per section
-
-| Section | Write |
-|---|---|
-| Purpose & Capabilities | 1–2 short paragraphs: what it owns; why it exists |
-| Architecture | How it is structured; narrate Mermaid/children if present — do not redraw |
-| Key Types | What the important public symbols are *for* (names must already be listed) |
-| How It Fits | Callers, blast radius, tests — ground every claim in the page's lists |
-
-If a list is empty, say so plainly (leaf / no public surface / untested) — do not invent.
-
-## Batch strategy
-
-For large wikis:
-
-1. Run offline scaffold once.
-2. Sort targets by `x-hotspot-score` descending (frontmatter).
-3. Narrate in batches of 5–15 pages; after each batch run
-   `graphwiki validate .` so failures stay local.
-4. Skip deferred / non-required concepts (they may be absent from disk by design).
-
-Do not hand-create pages for concepts missing from the plan — re-run
-`graphwiki build/update --backend offline` to materialize them.
-
-## Failure handling
-
-| Symptom | Action |
-|---|---|
-| `doctor` engine missing | Fix engine (`--engine-bin` or auto-fetch); do not free-write a wiki |
-| `validate` structure/quality fail | Fix the named page; usually leftover TODO or stub-thin prose |
-| `validate` citations fail | Remove or replace the invented path token; re-validate |
-| `validate` coverage fail | Re-run offline build/update — do not invent missing pages |
-| User wants cloud/local API instead | Prefer `graphwiki build . --backend ollama\|nim\|…` over this skill |
-
-## Done criteria
-
-- [ ] `graphwiki validate .` exits 0
-- [ ] No page still contains `documented from the code knowledge graph`
-- [ ] Frontmatter and deterministic fact lists unchanged from scaffold
-- [ ] Summary for the user: page count narrated, validate OK, how to serve
-      (`graphwiki web` or `graphwiki serve`)
-
-## CLI cheat sheet
-
-```bash
-graphwiki doctor .
-graphwiki build . --backend offline --no-web
-graphwiki update . --backend offline --no-web
-graphwiki validate .
-graphwiki web
-graphwiki serve --out wiki          # needs mcp extra
-```
-
-Backend note: coding-agent CLIs are intentionally **not** `--backend` values.
-This skill is the supported agent path: scaffold offline → agent narrates →
-gates. See product README.
-
-## Additional resources
-
-- `references/invariants.md` — why agents must not traverse for generation
-- `references/page-format.md` — frontmatter + section contract + edit boundaries

graphwiki-0.2.0/src/graphwiki/skills/graphwiki/references/page-format.md

@@ -1,127 +0,0 @@
-# Wiki page format (edit contract)
-
-Default output tree: `<repo>/wiki/` (`--out` overrides).
-
-## Tree
-
-```
-wiki/
-  .ai-context.md          # index — regenerate via tool, do not hand-edit
-  architecture.md         # system Mermaid — tool-owned
-  log.md                  # run log — tool-owned
-  .state/                 # refresh hashes — tool-owned, do not edit
-  systems/*.md            # Subsystem + Module
-  features/*.md           # Feature
-  entrypoints/*.md        # Entrypoint
-  reference/*.md          # API, DataModel, Dependency, ADR, Runbook (when present)
-```
-
-## Frontmatter (never rewrite)
-
-```yaml
----
-description: <routing key — "open when…"; not a summary>
-resource: <canonical path or symbol>
-title: <concept title>
-type: Module | Subsystem | Feature | Entrypoint | …
-x-callers: […]
-x-grounded-paths: […]
-x-hotspot-score: <float or null>
----
-```
-
-- `type` is a frozen vocabulary — do not invent types.
-- `description` is a **routing decision** for agents ("should I open this?"),
-  not a prose summary. Leave the offline/tool value unless the user explicitly
-  asks to improve routing keys (then keep the same shape).
-
-## Body structure (edit boundaries)
-
-```markdown
-## Purpose & Capabilities
-
-<NARRATIVE — agent may rewrite>
-
-## Architecture
-
-<NARRATIVE — agent may rewrite>
-
-**Child modules:**          # KEEP if present
-- `…`
-
-```mermaid                 # KEEP entire fence if present
-…
-```
-
-## Key Types
-
-<NARRATIVE — agent may rewrite>
-
-**Public surface:**         # KEEP if present
-- `…`
-
-## How It Fits
-
-<NARRATIVE — agent may rewrite>
-
-**Used by:**                # KEEP if present
-- `…`
-
-**Blast radius** — …:       # KEEP if present
-- `…`
-
-**Tests:**                  # KEEP if present
-- `…`
-```
-
-### Editable
-
-- Paragraphs (and optional short bullets **only** under Key Types) that sit
-  directly under the four `##` headings, **above** the bold fact panels.
-
-### Forbidden to change
-
-- YAML frontmatter block
-- Heading titles (`## Purpose & Capabilities`, etc.)
-- Bold labels and every list item under them
-- Mermaid code fences
-- Adding new top-level `##` sections
-- Adding code-sample fences in narrative (prose only)
-
-## Offline stub signature
-
-Scaffold purpose lines look like:
-
-```text
-`{title}` is a {module|subsystem|…} documented from the code knowledge graph; its
-canonical resource is `{resource}`. …
-```
-
-Replace that entire purpose paragraph with real narrative. Same for architecture
-lines that only say "The graph records no internal sub-structure…" when richer
-context (children, mermaid, callers) is available to explain.
-
-## Example good edit (shape only)
-
-**Before (offline):**
-
-```markdown
-## Purpose & Capabilities
-
-`writer` is a module documented from the code knowledge graph; its canonical
-resource is `src/graphwiki/writer.py`. The graph associates 12 symbol(s) with it,
-of which 4 form its public surface.
-```
-
-**After (assisted):**
-
-```markdown
-## Purpose & Capabilities
-
-`writer` owns page narration for a single pre-assembled concept. It turns graph
-context into frontmatter plus structured body sections, using either an
-OpenAI-compatible completion or deterministic offline templates. Callers feed it
-one concept at a time; it does not plan coverage or query the graph.
-```
-
-Facts (resource, public surface list below) stay exactly as scaffolded.