dev-guru 0.1.0__tar.gz → 0.2.0__tar.gz

dev_guru-0.2.0/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to Dev Guru are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) — [SemVer](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+---
+
+## [0.2.0] — 2026-11-03
+
+### Added
+
+- **Runs through the Ananke app facade** (`ananke-app/1`, needs Ananke 0.3.13):
+  - `dev explore` builds the graph in an idempotent Ananke run, records the run in the report manifest
+    (`ananke_run`), and registers the HTML back into that run as an artifact with its inputs;
+  - a failed build is a failed run, with its id kept as evidence.
+- **`dev sources`**: source-neutral capability discovery (internal folders, private Git, troves) with an offline
+  picker page. Works with Dex switched off.
+- **`dev learning review`**: an offline review page for an Ananke learning candidate, showing the gate status,
+  evaluation, review, provenance and a diff per destination.
+
+- **`dev diagram`**: an animated SVG of the relationships a document states (arrow lines, Mermaid flowcharts, From/To
+  tables). Every edge cites its file and line, and an edited edge that fails its citation is drawn as a hypothesis.
+  Guide: [Diagrams from documents](docs/guides/diagrams.md).
+- **`dev present`**: Markdown slides become one offline, accessible HTML deck:
+  - `lantern` and `paper` themes, responsive columns, step-by-step lists, speaker notes, keyboard navigation;
+  - bar charts as accessible SVG;
+  - embedded local images that require alt text; raw HTML is shown as text;
+  - `--check` verifies a deck. Guide: [Presentations](docs/guides/presentations.md).
+- **Publication profiles** for `dev explore` (`--profile public`): removes source, docstrings, string defaults in
+  signatures and the Git revision, so a report is safe to publish. The manifest records the profile.
+
+---
+
+## [0.1.1] — 2026-11-02
+
+### Changed
+
+- **The constellation is a 3D force-directed graph.** Imports are springs, files repel each other and packages pull
+  their files together. Drag to orbit, scroll to zoom, drag a file to pull the graph, double-click to fly to a file;
+  it turns slowly when idle. Shaded bodies, depth fog, a star field and pulses along lit imports, with labels that
+  never overlap. Drawn on a plain canvas inside the report: no WebGL, no library, no network. With reduced motion it
+  settles before the first frame and stays still.
+- Docs: the client-port design is now a plain concept page, [How Dev Guru talks to Ananke](docs/concepts/ananke-client.md).
+  PyPI links on the README, the docs home and the site.
+
+### Fixed
+
+- `.trivyignore` added, so the release workflow's Trivy gate can run.
+
+---
+
+## [0.1.0] — 2026-11-02
+
+The first release.
+
+### Added
+
+- **`dev explore`**: Ananke builds the code graph, and Dev Guru writes one interactive, offline HTML explorer plus a
+  manifest.
+  - Six views: constellation, flow (package or file level), impact rings, calls, hotspots and a narrated tour.
+  - Around them: search, a command palette, a source inspector, a light and dark theme, and URL-shareable state.
+  - Explicit downloads of the view state and of analysis requests.
+- **Report safety.**
+  - Everything is inlined, and the page sets a CSP with `connect-src 'none'`.
+  - JSON is embedded with `<`, `>`, `&` and U+2028/U+2029 escaped; untrusted text is set only with
+    `textContent`.
+  - Templates are filled in a single pass, so source code containing the template's placeholders stays data.
+  - A manifest records the renderer, the Dev Guru and Ananke versions, the input digest and the git revision.
+- **View model `dev-guru/explorer@1`**: packages, files, symbols with source snippets, resolved import, call and
+  inheritance edges, insights (most depended-on, largest, entry points, import cycles) and stated limitations.
+  Deterministic.
+- **SDK** `GuruClient(workspace).explore()` / `.export()`, sharing one service layer with the CLI.
+- **`dev doctor`**: version and capability negotiation with Ananke (`ananke-plexus>=0.3.12,<0.4`) over one explicit
+  transport, with stable error codes.
+- **Docs site** with a live demo (Dev Guru exploring its own source) and the "Lantern" theme.
+- **Release gates:**
+  - acceptance on the built wheel, including real-Chrome report journeys and a dogfood run on Dev Guru's own source;
+  - a distribution scan (gitleaks, pip-audit, GuardDog, Bandit);
+  - Trivy and build provenance.
+
+### Changed
+
+- The command is **`dev`** (it was `devguru` in the unreleased scaffold).
+
+### Fixed
+
+- Import cycles in Dev Guru itself, found by exploring it: `dev_guru` now exposes `GuruClient` lazily, and
+  `client.inprocess` imports `negotiation` directly.

{dev_guru-0.1.0 → dev_guru-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dev-guru
-Version: 0.1.0
+Version: 0.2.0
 Summary: Dev Guru: understand, improve, verify and learn from your software. A local-first developer product on the Ananke Plexus harness: Python SDK and CLI first, offline HTML reports, later a local web UI.
 Project-URL: Homepage, https://github.com/Neo-Pragnya/Dev-Guru
 Project-URL: Repository, https://github.com/Neo-Pragnya/Dev-Guru
@@ -22,7 +22,8 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: ananke-plexus<0.4,>=0.3.12
+Requires-Dist: ananke-plexus<0.4,>=0.3.13
+Requires-Dist: markdown-it-py<5,>=3
 Requires-Dist: pydantic<3,>=2.11
 Requires-Dist: rich>=13
 Requires-Dist: typer<1,>=0.16
@@ -42,10 +43,13 @@ Description-Content-Type: text/markdown
 
 # Dev Guru
 
+[![PyPI](https://img.shields.io/pypi/v/dev-guru)](https://pypi.org/project/dev-guru/)
+[![Python](https://img.shields.io/pypi/pyversions/dev-guru)](https://pypi.org/project/dev-guru/)
+
 **See your code. Understand it. Change it with confidence.**
 
 Point Dev Guru at a Python project and get **one offline HTML explorer**:
-- a living constellation of packages and files;
+- a 3D constellation of files you can orbit, where imports pull and packages cluster;
 - the flow of dependencies;
 - the blast radius of a change;
 - who calls what, and where the hotspots are;
@@ -61,14 +65,14 @@ dev explore path/to/project -o explorer.html --open
 
 ![Dev Guru running dev doctor and dev explore](docs/assets/dev-explore.svg)
 
-**[Documentation and a live demo →](https://neo-pragnya.github.io/Dev-Guru/)**: the site's hero runs the real
+**[Documentation and a live demo →](https://neo-pragnya.github.io/Dev-Guru/)** · **[Dev Guru on PyPI →](https://pypi.org/project/dev-guru/)**: the site's hero runs the real
 report of Dev Guru exploring its own source.
 
 ## What's in a report
 
 | View | Question it answers |
 | --- | --- |
-| ✦ Constellation | What's here? Files clustered by package; hover to light up imports |
+| ✦ Constellation | What's here? A 3D force-directed graph: drag to orbit, hover to light up imports |
 | ⇶ Flow | What depends on what? Entry side to foundations; cycles glow rose |
 | ◎ Impact | What breaks if this changes? Blast-radius rings over importers and callers |
 | ƒ Calls | Who calls in, and what goes out? A symbol-level ego network |
@@ -79,6 +83,16 @@ Plus search (`/`), a command palette (`Ctrl`/`⌘` `K`), a source inspector, a l
 URLs. Reports are **offline and view-only**, treat source as text, and carry a manifest with the input digest and the
 Git revision. See [report safety](docs/concepts/report-safety.md).
 
+## More than the explorer
+
+```bash
+dev present talk.md                  # Markdown slides → one offline, accessible HTML deck
+dev diagram docs/arch.md             # an animated SVG of what a document states, every edge cited
+dev explore . --profile public       # a report safe to publish: no source, docstrings or Git revision
+dev sources                          # capabilities from your folders, private Git and Dex Trove
+dev learning review NAME             # review what Ananke learned before it becomes reusable
+```
+
 ## From Python
 
 ```python
@@ -98,7 +112,7 @@ with GuruClient(workspace="path/to/project") as guru:
 | [Dex Trove](https://github.com/Neo-Pragnya/Dex-Trove) | Optional capability memory: curated skills, agents, instructions and workflows |
 
 Dev Guru never analyses code itself: every domain operation goes through one client port to Ananke, and Dex is never
-required. See [Architecture](docs/concepts/architecture.md) and [ADR-0001](docs/decisions/0001-ananke-client-port.md).
+required. See [Architecture](docs/concepts/architecture.md) and [How Dev Guru talks to Ananke](docs/concepts/ananke-client.md).
 
 ## Quality gates
 

{dev_guru-0.1.0 → dev_guru-0.2.0}/README.md

@@ -1,9 +1,12 @@
 # Dev Guru
 
+[![PyPI](https://img.shields.io/pypi/v/dev-guru)](https://pypi.org/project/dev-guru/)
+[![Python](https://img.shields.io/pypi/pyversions/dev-guru)](https://pypi.org/project/dev-guru/)
+
 **See your code. Understand it. Change it with confidence.**
 
 Point Dev Guru at a Python project and get **one offline HTML explorer**:
-- a living constellation of packages and files;
+- a 3D constellation of files you can orbit, where imports pull and packages cluster;
 - the flow of dependencies;
 - the blast radius of a change;
 - who calls what, and where the hotspots are;
@@ -19,14 +22,14 @@ dev explore path/to/project -o explorer.html --open
 
 ![Dev Guru running dev doctor and dev explore](docs/assets/dev-explore.svg)
 
-**[Documentation and a live demo →](https://neo-pragnya.github.io/Dev-Guru/)**: the site's hero runs the real
+**[Documentation and a live demo →](https://neo-pragnya.github.io/Dev-Guru/)** · **[Dev Guru on PyPI →](https://pypi.org/project/dev-guru/)**: the site's hero runs the real
 report of Dev Guru exploring its own source.
 
 ## What's in a report
 
 | View | Question it answers |
 | --- | --- |
-| ✦ Constellation | What's here? Files clustered by package; hover to light up imports |
+| ✦ Constellation | What's here? A 3D force-directed graph: drag to orbit, hover to light up imports |
 | ⇶ Flow | What depends on what? Entry side to foundations; cycles glow rose |
 | ◎ Impact | What breaks if this changes? Blast-radius rings over importers and callers |
 | ƒ Calls | Who calls in, and what goes out? A symbol-level ego network |
@@ -37,6 +40,16 @@ Plus search (`/`), a command palette (`Ctrl`/`⌘` `K`), a source inspector, a l
 URLs. Reports are **offline and view-only**, treat source as text, and carry a manifest with the input digest and the
 Git revision. See [report safety](docs/concepts/report-safety.md).
 
+## More than the explorer
+
+```bash
+dev present talk.md                  # Markdown slides → one offline, accessible HTML deck
+dev diagram docs/arch.md             # an animated SVG of what a document states, every edge cited
+dev explore . --profile public       # a report safe to publish: no source, docstrings or Git revision
+dev sources                          # capabilities from your folders, private Git and Dex Trove
+dev learning review NAME             # review what Ananke learned before it becomes reusable
+```
+
 ## From Python
 
 ```python
@@ -56,7 +69,7 @@ with GuruClient(workspace="path/to/project") as guru:
 | [Dex Trove](https://github.com/Neo-Pragnya/Dex-Trove) | Optional capability memory: curated skills, agents, instructions and workflows |
 
 Dev Guru never analyses code itself: every domain operation goes through one client port to Ananke, and Dex is never
-required. See [Architecture](docs/concepts/architecture.md) and [ADR-0001](docs/decisions/0001-ananke-client-port.md).
+required. See [Architecture](docs/concepts/architecture.md) and [How Dev Guru talks to Ananke](docs/concepts/ananke-client.md).
 
 ## Quality gates
 

{dev_guru-0.1.0 → dev_guru-0.2.0}/pyproject.toml

@@ -28,7 +28,8 @@ classifiers = [
 # Dev Guru is a client of Ananke: the harness owns analysis, execution and evidence (docs/architecture.md).
 # Keep this range in step with SUPPORTED_ANANKE in src/dev_guru/client/negotiation.py (tests/test_packaging.py).
 dependencies = [
-  "ananke-plexus>=0.3.12,<0.4",
+  "ananke-plexus>=0.3.13,<0.4",
+  "markdown-it-py>=3,<5",
   "pydantic>=2.11,<3",
   "rich>=13",
   "typer>=0.16,<1",

dev_guru-0.2.0/src/dev_guru/cli.py

@@ -0,0 +1,347 @@
+"""The ``dev`` command. CLI and SDK share one service layer (dev_guru.service)."""
+
+from __future__ import annotations
+
+import json
+import platform
+import webbrowser
+from importlib import metadata
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+
+from dev_guru import errors, service
+from dev_guru.client import TRANSPORTS, connect
+from dev_guru.version import __version__
+
+app = typer.Typer(
+    name="dev",
+    help="Dev Guru: understand, improve and verify your software, on the Ananke Plexus harness.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+err = Console(stderr=True)
+TransportOpt = Annotated[str, typer.Option(help=f"Harness transport: {', '.join(TRANSPORTS)}")]
+JsonOpt = Annotated[bool, typer.Option("--json", help="Machine-readable output")]
+
+
+def _version(value: bool) -> None:
+    if value:
+        console.print(f"dev-guru {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_version, is_eager=True, help="Show the version and exit"
+        ),
+    ] = False,
+) -> None:
+    """Dev Guru: understand, improve and verify your software, on the Ananke Plexus harness."""
+
+
+def _fail(exc: errors.GuruError, as_json: bool, code: int) -> None:
+    if as_json:
+        console.print_json(json.dumps({"ok": False, "error": exc.to_dict()}))
+    else:
+        err.print(f"[red]✗ {exc.code}: {exc.message}[/red]")
+        if exc.hint:
+            err.print(f"  [dim]{exc.hint}[/dim]")
+    raise typer.Exit(code) from exc
+
+
+def _optional(distribution: str) -> str | None:
+    try:
+        return metadata.version(distribution)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+@app.command()
+def doctor(transport: TransportOpt = "in-process", as_json: JsonOpt = False) -> None:
+    """Check the Ananke harness: installed version, supported range and the capabilities Dev Guru needs.
+
+    Exits 1 when the harness is missing or incompatible, 2 for an unknown transport.
+    """
+    try:
+        info = connect(transport).info()
+    except errors.GuruError as exc:
+        _fail(exc, as_json, 2)
+        return
+    dex = _optional("dex-trove")
+    report = {
+        "ok": info.compatible,
+        "dev_guru": __version__,
+        "python": platform.python_version(),
+        "harness": info.model_dump(),
+        "optional": {"dex-trove": dex},
+    }
+    if as_json:
+        console.print_json(json.dumps(report))
+    else:
+        mark = "[green]✓[/green]" if info.compatible else "[red]✗[/red]"
+        console.print(
+            f"dev-guru {__version__} · Python {report['python']} · transport {info.transport}"
+        )
+        console.print(
+            f"{mark} ananke-plexus {info.ananke_version or 'not installed'} (supported {info.supported_range})"
+        )
+        for cap, present in info.capabilities.items():
+            console.print(f"  {'✓' if present else '✗'} {cap}")
+        for reason in info.reasons:
+            console.print(f"  [red]{reason}[/red]")
+        console.print(f"  [dim]dex-trove: {dex or 'not installed (optional)'}[/dim]")
+    if not info.compatible:
+        raise typer.Exit(1)
+
+
+@app.command()
+def explore(
+    workspace: Annotated[Path, typer.Argument(help="Project to explore")] = Path("."),
+    output: Annotated[
+        Path, typer.Option("--output", "-o", help="Report file (a manifest is written next to it)")
+    ] = Path("dev-guru-explorer.html"),
+    name: Annotated[str | None, typer.Option(help="Project name shown in the report")] = None,
+    open_browser: Annotated[
+        bool, typer.Option("--open", help="Open the report when it's written")
+    ] = False,
+    transport: TransportOpt = "in-process",
+    profile: Annotated[
+        str,
+        typer.Option(
+            help="private (everything) or public (no source, docstrings or Git revision: safe to publish)"
+        ),
+    ] = "private",
+    as_json: JsonOpt = False,
+) -> None:
+    """Explore a codebase: Ananke builds the graph, Dev Guru writes an interactive, offline HTML explorer.
+
+    The report is one file with no network access: architecture constellation, dependency flow, impact rings,
+    call graph, hotspots, a guided tour, search and a source inspector.
+    """
+    try:
+        client = connect(transport)
+        result = service.explore(workspace, client=client, name=name, profile=profile)
+        page, sidecar = service.export_html(result, output, client=client)
+    except errors.GuruError as exc:
+        _fail(exc, as_json, 1)
+        return
+    project = result.model["project"]
+    summary = {
+        "ok": True,
+        "report": str(page),
+        "manifest": str(sidecar),
+        "input_digest": result.manifest["input_digest"],
+        "project": project,
+        "insights": {k: len(v) for k, v in result.model["insights"].items()},
+    }
+    if as_json:
+        console.print_json(json.dumps(summary))
+    else:
+        console.print(
+            f"[green]✓[/green] {project['files']} files · {project['symbols']} symbols · "
+            f"{project['imports']} imports · {project['calls']} calls → {page}"
+        )
+        cycles = len(result.model["insights"]["cycles"])
+        if cycles:
+            console.print(f"  [yellow]{cycles} import cycle(s) found; see the Flow view[/yellow]")
+        console.print(f"  [dim]manifest {sidecar} · {result.manifest['input_digest'][:19]}…[/dim]")
+    if open_browser:
+        webbrowser.open(page.resolve().as_uri())
+
+
+@app.command()
+def present(
+    slides: Annotated[
+        Path, typer.Argument(help="Markdown slides (separate slides with a line of ---)")
+    ],
+    output: Annotated[Path | None, typer.Option("--output", "-o", help="Deck file")] = None,
+    theme: Annotated[
+        str | None, typer.Option(help="lantern (dark) or paper (light); default from front matter")
+    ] = None,
+    check_only: Annotated[
+        bool, typer.Option("--check", help="Check an existing HTML deck instead of building")
+    ] = False,
+    open_browser: Annotated[
+        bool, typer.Option("--open", help="Open the deck when it's written")
+    ] = False,
+) -> None:
+    """Turn Markdown slides into one offline, accessible HTML deck (arrow keys, N for notes, print to PDF).
+
+    Raw HTML is shown as text, images must be local with alt text, charts come from ```chart JSON blocks, and the
+    page can't make network requests. --check verifies a built deck.
+    """
+    from dev_guru import present as deck
+
+    if check_only:
+        problems = deck.check(slides.read_text(encoding="utf-8"))
+        for p in problems:
+            err.print(f"[red]✗[/red] {p}")
+        if problems:
+            raise typer.Exit(1)
+        console.print(f"[green]✓[/green] {slides}: offline and accessible checks pass")
+        return
+    try:
+        page = deck.build(slides.read_text(encoding="utf-8"), slides.parent, theme=theme)
+    except (deck.DeckError, OSError) as exc:
+        err.print(
+            f"[red]✗ {escape(str(exc))}[/red]"
+        )  # the message quotes Markdown like ![alt](src)
+        raise typer.Exit(2) from exc
+    problems = deck.check(page)
+    if (
+        problems
+    ):  # a bug in the renderer, not the author's input: never write a deck that fails its own check
+        err.print("[red]✗ built deck failed its checks: " + "; ".join(problems) + "[/red]")
+        raise typer.Exit(1)
+    out = output or slides.with_suffix(".html")
+    out.write_text(page, encoding="utf-8")
+    n = page.count('class="slide"')
+    console.print(f"[green]✓[/green] {n} slides → {out}")
+    if open_browser:
+        webbrowser.open(out.resolve().as_uri())
+
+
+@app.command()
+def sources(
+    query: Annotated[str, typer.Argument(help="Words to match (optional)")] = "",
+    workspace: Annotated[
+        Path, typer.Option("--workspace", "-w", help="Project whose sources to read")
+    ] = Path("."),
+    html_out: Annotated[
+        Path | None, typer.Option("--html", help="Also write an offline picker page")
+    ] = None,
+    transport: TransportOpt = "in-process",
+    as_json: JsonOpt = False,
+) -> None:
+    """Browse capabilities from every source the project configures (internal folders, private Git, troves).
+
+    Source-neutral: Dev Guru asks Ananke's provider port; Dex Trove is just one optional source.
+    """
+    from dev_guru.reports import pages
+
+    try:
+        found = connect(transport).discover_capabilities(workspace, query)
+    except errors.GuruError as exc:
+        _fail(exc, as_json, 1)
+        return
+    rows = [c.model_dump() for c in found]
+    if html_out is not None:
+        html_out.write_text(pages.sources_page(rows), encoding="utf-8")
+    if as_json:
+        console.print_json(json.dumps(rows))
+        return
+    for c in found:
+        console.print(f"{c.identity}@{c.version}  [dim]{escape(c.summary[:80])}[/dim]")
+    console.print(f"{len(found)} capabilities" + (f" · picker: {html_out}" if html_out else ""))
+
+
+learning_app = typer.Typer(
+    help="Review what Ananke learned before it becomes reusable memory.", no_args_is_help=True
+)
+app.add_typer(learning_app, name="learning")
+
+
+@learning_app.command("review")
+def learning_review(
+    name: Annotated[str, typer.Argument(help="Candidate name (see `ananke learning list`)")],
+    workspace: Annotated[Path, typer.Option("--workspace", "-w")] = Path("."),
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="Review page (default <name>-review.html)")
+    ] = None,
+    open_browser: Annotated[bool, typer.Option("--open")] = False,
+    transport: TransportOpt = "in-process",
+    as_json: JsonOpt = False,
+) -> None:
+    """A review page for a learning candidate: gate status, evaluation, review, provenance and per-destination diff.
+
+    Reviewing changes nothing: approve with `ananke learning review` and promote with `ananke learning promote`.
+    """
+    from dev_guru.reports import pages
+
+    try:
+        cand = connect(transport).learning_candidate(workspace, name)
+    except errors.GuruError as exc:
+        _fail(exc, as_json, 1)
+        return
+    out = output or Path(f"{name}-review.html")
+    out.write_text(pages.review_page(cand.model_dump()), encoding="utf-8")
+    if as_json:
+        console.print_json(json.dumps(cand.model_dump() | {"page": str(out)}))
+    else:
+        state = (
+            "[green]ready to promote[/green]"
+            if not cand.problems
+            else "[yellow]" + escape("; ".join(cand.problems)) + "[/yellow]"
+        )
+        console.print(f"{name}: {state} → {out}")
+    if open_browser:
+        webbrowser.open(out.resolve().as_uri())
+
+
+@app.command()
+def diagram(
+    document: Annotated[Path, typer.Argument(help="An approved Markdown document")],
+    output: Annotated[
+        Path | None, typer.Option("--output", "-o", help="SVG file (default <document>.svg)")
+    ] = None,
+    model_out: Annotated[
+        Path | None, typer.Option("--model", help="Also write the editable model (JSON)")
+    ] = None,
+    from_model: Annotated[
+        Path | None, typer.Option("--from-model", help="Render an edited model instead")
+    ] = None,
+    static: Annotated[bool, typer.Option("--static", help="No animation")] = False,
+    as_json: JsonOpt = False,
+) -> None:
+    """An animated SVG of the relationships a document states, every one cited (file and line).
+
+    Reads arrow lines (A -> B: label), Mermaid flowcharts and From/To tables, never prose, so nothing is invented.
+    Edited relationships whose citation doesn't hold up are drawn as hypotheses (dashed, "?").
+    """
+    from dev_guru import diagram as dg
+
+    try:
+        text = document.read_text(encoding="utf-8")
+        model = (
+            json.loads(from_model.read_text(encoding="utf-8"))
+            if from_model
+            else dg.extract(text, document.name)
+        )
+        model = dg.verify(model, text)
+    except (dg.DiagramError, OSError, ValueError) as exc:
+        err.print(f"[red]✗ {escape(str(exc))}[/red]")
+        raise typer.Exit(2) from exc
+    svg = dg.render(model, animate=not static)
+    problems = dg.svg_problems(svg)
+    if problems:  # never write an unsafe SVG, whatever the input
+        err.print("[red]✗ " + "; ".join(problems) + "[/red]")
+        raise typer.Exit(1)
+    out = output or document.with_suffix(".svg")
+    out.write_text(svg, encoding="utf-8")
+    if model_out:
+        model_out.write_text(
+            json.dumps(model, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+    hyp = sum(1 for r in model["relations"] if r["status"] != "cited")
+    summary = {
+        "svg": str(out),
+        "entities": len(model["entities"]),
+        "relations": len(model["relations"]),
+        "hypotheses": hyp,
+    }
+    if as_json:
+        console.print_json(json.dumps(summary))
+    else:
+        console.print(
+            f"[green]✓[/green] {len(model['relations']) - hyp} cited relationships, {summary['entities']} entities"
+            + (f", [yellow]{hyp} hypotheses[/yellow]" if hyp else "")
+            + f" → {out}"
+        )