renforge 0.1.0__tar.gz

renforge-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+build/
+dist/
+coverage/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+node_modules/
+*.tsbuildinfo
+.DS_Store
+*.tmp
+*.log
+logs/
+examples/demo_game/.cache/
+examples/demo_game/saves/
+examples/demo_game/error.log
+examples/demo_game/*.rpyc.bak
+examples/demo_game/game/cache/
+examples/demo_game/game/saves/
+examples/demo_game/.renforge/
+examples/demo_game/log.txt
+examples/demo_game/game/renforge_bridge.rpyc.bak
+# Bridge source injected at runtime by the launcher (the .rpyc is caught by *.rpyc)
+renforge_bridge.rpy
+examples/demo_game/game/gui/*.png
+examples/demo_game/game/gui/**/*.png
+!examples/demo_game/game/gui/bubble.png
+!examples/demo_game/game/gui/thoughtbubble.png
+
+# Internal working docs (reviews, competitive analysis, plans) — keep private
+docs/
+
+# Ren'Py / RenForge runtime artifacts
+*.rpyc
+*.rpymc
+*.rpyb
+cache/
+saves/
+log.txt
+traceback.txt
+errors.txt
+.renforge/
+screens

renforge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RenForge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

renforge-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: renforge
+Version: 0.1.0
+Summary: MCP server, CLI, and web dashboard for Ren'Py visual-novel development
+Project-URL: Homepage, https://github.com/alex-jordan547/renforge-mcp
+Project-URL: Repository, https://github.com/alex-jordan547/renforge-mcp
+Project-URL: Issues, https://github.com/alex-jordan547/renforge-mcp/issues
+Author: RenForge contributors
+License: MIT
+License-File: LICENSE
+Keywords: game-dev,mcp,model-context-protocol,renpy,visual-novel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: fastmcp
+Requires-Dist: fastmcp>=2.0.0; extra == 'fastmcp'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Provides-Extra: ui
+Requires-Dist: starlette>=0.31; extra == 'ui'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'ui'
+Requires-Dist: watchfiles>=0.22; extra == 'ui'
+Description-Content-Type: text/markdown
+
+# RenForge
+
+RenForge is an **MCP (Model Context Protocol) server, CLI, and web dashboard**
+for working with [Ren'Py](https://www.renpy.org/) visual-novel projects.
+
+It lets an AI agent — or a human via the dashboard — inspect a project, launch
+and drive a running game, read/write game state, capture screenshots, generate
+translations, find orphaned assets, run builds, and search Ren'Py's docs.
+
+> Status: **alpha**, actively developed. The core surfaces (MCP tools, in-game
+> bridge, CLI, dashboard) are functional; APIs may still change.
+
+## What it does
+
+- **Project inspection** — summarize structure, scan scripts/labels/assets,
+  parse lint output.
+- **Live game control** — launch a project with an injected in-game bridge, then
+  advance dialogue, list/select choices, evaluate expressions, get/set store
+  variables, poll pushed events, and capture frames the model can literally see.
+- **Autopilot** — auto-play the game across branches and report label coverage
+  and crashes.
+- **Assets & translations** — find orphaned/missing image+audio assets, list
+  languages, compute translation stats, generate/update `game/tl/<lang>/` files,
+  export dialogue as text.
+- **Builds** — package desktop distributions and web builds.
+- **Docs** — search and read Ren'Py's offline documentation.
+- **Web dashboard** — Starlette + WebSocket UI with a live story map, activity
+  log, autopilot coverage, lint view, and game-state controls.
+
+## Quick start
+
+Requires Python 3.11+. With [uv](https://docs.astral.sh/uv/) installed, no
+setup is needed:
+
+```bash
+# Start the web dashboard on your project
+uvx --from "renforge[ui]" renforge ui --project /path/to/your/game
+
+# Or add the MCP server to Claude Code
+claude mcp add renforge -- uvx --from "renforge[fastmcp]" renforge serve --project /path/to/your/game
+```
+
+For Claude Desktop (or any MCP client using JSON config):
+
+```json
+{
+  "mcpServers": {
+    "renforge": {
+      "command": "uvx",
+      "args": [
+        "--from", "renforge[fastmcp]", "renforge",
+        "serve", "--project", "/path/to/your/game"
+      ]
+    }
+  }
+}
+```
+
+Prefer pip? `pip install "renforge[fastmcp,ui]"` gives you the `renforge` CLI.
+
+## Install (dev)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[fastmcp]"  # full MCP runtime (fastmcp)
+pip install -e ".[ui]"       # dashboard (starlette, uvicorn, watchfiles)
+pip install -e ".[test]"     # pytest
+```
+
+The base install only requires `mcp>=1.0.0`; the server falls back to a
+compatibility mode with a clear message if `fastmcp` is not installed.
+
+## Usage
+
+### CLI
+
+```bash
+renforge --version
+renforge inspect <project>      # lightweight project summary (JSON)
+renforge serve [--project .]    # start the MCP server (stdio transport)
+renforge ui --project <project> [--port 8765]   # start the web dashboard
+```
+
+### MCP server
+
+`renforge serve` exposes the tools below to any MCP client. A subset:
+
+- `renforge_inspect_project`, `renforge_scan_project`, `renforge_parse_lint`
+- `renforge_launch`, `renforge_stop`
+- `renforge_game_state`, `renforge_advance`, `renforge_list_choices`,
+  `renforge_select_choice`, `renforge_eval`, `renforge_get_var`,
+  `renforge_set_var`, `renforge_poll_events`, `renforge_screenshot`
+- `renforge_autopilot`
+- `renforge_assets`, `renforge_languages`, `renforge_translation_stats`,
+  `renforge_generate_translations`, `renforge_export_dialogue`
+- `renforge_web_build`, `renforge_distribute`
+- `renforge_search_docs`, `renforge_get_doc`, `renforge_list_docs`
+
+### Live control
+
+`renforge_launch` injects a bridge into `<project>/game/` (removed on teardown)
+and starts the game. Live tools require a display — under WSLg it works
+directly; headless CI should wrap the call with `xvfb-run`.
+
+### Web dashboard
+
+`renforge ui --project <project>` serves a dashboard (default `127.0.0.1:8765`)
+with a story map, activity log, autopilot coverage, lint view, and live game
+controls over WebSocket.
+
+## Examples
+
+A small sample project lives in `examples/demo_game/`.
+
+## Architecture
+
+```
+src/renforge/
+  cli.py            # argparse entrypoint (inspect / serve / ui)
+  server.py         # MCP app bootstrap + fallback + tool registration
+  bridge/           # in-game .rpy bridge, launcher, and client
+  tools/
+    live.py         # running-game control (launch, eval, screenshot, ...)
+    project_ops.py  # assets, translations, builds, docs
+    static.py       # inspect / scan / parse-lint
+  ui/               # Starlette dashboard (server, ws, graph, activity, poller)
+  util/             # filesystem + subprocess helpers
+  sdk.py            # Ren'Py SDK download/cache
+  scanner.py        # script/label/asset scanning
+  lint.py           # lint runner + parsing
+  autopilot.py      # branch auto-play + coverage
+  translation.py    # translation generation/stats
+```
+
+Packaging uses `hatchling`; the console script is
+`renforge = renforge.cli:main`.
+
+## License
+
+MIT

renforge-0.1.0/README.md

@@ -0,0 +1,141 @@
+# RenForge
+
+RenForge is an **MCP (Model Context Protocol) server, CLI, and web dashboard**
+for working with [Ren'Py](https://www.renpy.org/) visual-novel projects.
+
+It lets an AI agent — or a human via the dashboard — inspect a project, launch
+and drive a running game, read/write game state, capture screenshots, generate
+translations, find orphaned assets, run builds, and search Ren'Py's docs.
+
+> Status: **alpha**, actively developed. The core surfaces (MCP tools, in-game
+> bridge, CLI, dashboard) are functional; APIs may still change.
+
+## What it does
+
+- **Project inspection** — summarize structure, scan scripts/labels/assets,
+  parse lint output.
+- **Live game control** — launch a project with an injected in-game bridge, then
+  advance dialogue, list/select choices, evaluate expressions, get/set store
+  variables, poll pushed events, and capture frames the model can literally see.
+- **Autopilot** — auto-play the game across branches and report label coverage
+  and crashes.
+- **Assets & translations** — find orphaned/missing image+audio assets, list
+  languages, compute translation stats, generate/update `game/tl/<lang>/` files,
+  export dialogue as text.
+- **Builds** — package desktop distributions and web builds.
+- **Docs** — search and read Ren'Py's offline documentation.
+- **Web dashboard** — Starlette + WebSocket UI with a live story map, activity
+  log, autopilot coverage, lint view, and game-state controls.
+
+## Quick start
+
+Requires Python 3.11+. With [uv](https://docs.astral.sh/uv/) installed, no
+setup is needed:
+
+```bash
+# Start the web dashboard on your project
+uvx --from "renforge[ui]" renforge ui --project /path/to/your/game
+
+# Or add the MCP server to Claude Code
+claude mcp add renforge -- uvx --from "renforge[fastmcp]" renforge serve --project /path/to/your/game
+```
+
+For Claude Desktop (or any MCP client using JSON config):
+
+```json
+{
+  "mcpServers": {
+    "renforge": {
+      "command": "uvx",
+      "args": [
+        "--from", "renforge[fastmcp]", "renforge",
+        "serve", "--project", "/path/to/your/game"
+      ]
+    }
+  }
+}
+```
+
+Prefer pip? `pip install "renforge[fastmcp,ui]"` gives you the `renforge` CLI.
+
+## Install (dev)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[fastmcp]"  # full MCP runtime (fastmcp)
+pip install -e ".[ui]"       # dashboard (starlette, uvicorn, watchfiles)
+pip install -e ".[test]"     # pytest
+```
+
+The base install only requires `mcp>=1.0.0`; the server falls back to a
+compatibility mode with a clear message if `fastmcp` is not installed.
+
+## Usage
+
+### CLI
+
+```bash
+renforge --version
+renforge inspect <project>      # lightweight project summary (JSON)
+renforge serve [--project .]    # start the MCP server (stdio transport)
+renforge ui --project <project> [--port 8765]   # start the web dashboard
+```
+
+### MCP server
+
+`renforge serve` exposes the tools below to any MCP client. A subset:
+
+- `renforge_inspect_project`, `renforge_scan_project`, `renforge_parse_lint`
+- `renforge_launch`, `renforge_stop`
+- `renforge_game_state`, `renforge_advance`, `renforge_list_choices`,
+  `renforge_select_choice`, `renforge_eval`, `renforge_get_var`,
+  `renforge_set_var`, `renforge_poll_events`, `renforge_screenshot`
+- `renforge_autopilot`
+- `renforge_assets`, `renforge_languages`, `renforge_translation_stats`,
+  `renforge_generate_translations`, `renforge_export_dialogue`
+- `renforge_web_build`, `renforge_distribute`
+- `renforge_search_docs`, `renforge_get_doc`, `renforge_list_docs`
+
+### Live control
+
+`renforge_launch` injects a bridge into `<project>/game/` (removed on teardown)
+and starts the game. Live tools require a display — under WSLg it works
+directly; headless CI should wrap the call with `xvfb-run`.
+
+### Web dashboard
+
+`renforge ui --project <project>` serves a dashboard (default `127.0.0.1:8765`)
+with a story map, activity log, autopilot coverage, lint view, and live game
+controls over WebSocket.
+
+## Examples
+
+A small sample project lives in `examples/demo_game/`.
+
+## Architecture
+
+```
+src/renforge/
+  cli.py            # argparse entrypoint (inspect / serve / ui)
+  server.py         # MCP app bootstrap + fallback + tool registration
+  bridge/           # in-game .rpy bridge, launcher, and client
+  tools/
+    live.py         # running-game control (launch, eval, screenshot, ...)
+    project_ops.py  # assets, translations, builds, docs
+    static.py       # inspect / scan / parse-lint
+  ui/               # Starlette dashboard (server, ws, graph, activity, poller)
+  util/             # filesystem + subprocess helpers
+  sdk.py            # Ren'Py SDK download/cache
+  scanner.py        # script/label/asset scanning
+  lint.py           # lint runner + parsing
+  autopilot.py      # branch auto-play + coverage
+  translation.py    # translation generation/stats
+```
+
+Packaging uses `hatchling`; the console script is
+`renforge = renforge.cli:main`.
+
+## License
+
+MIT

renforge-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "renforge"
+version = "0.1.0"
+description = "MCP server, CLI, and web dashboard for Ren'Py visual-novel development"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "RenForge contributors" }]
+keywords = ["renpy", "mcp", "model-context-protocol", "visual-novel", "game-dev"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Games/Entertainment",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "mcp>=1.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/alex-jordan547/renforge-mcp"
+Repository = "https://github.com/alex-jordan547/renforge-mcp"
+Issues = "https://github.com/alex-jordan547/renforge-mcp/issues"
+
+[project.optional-dependencies]
+fastmcp = ["fastmcp>=2.0.0"]
+test = ["pytest>=8"]
+ui = ["starlette>=0.31", "uvicorn[standard]>=0.30", "watchfiles>=0.22"]
+
+[project.scripts]
+renforge = "renforge.cli:main"
+
+[tool.hatch.build]
+include = ["src/renforge", "src/renforge/**/*.rpy", "src/renforge/ui/static/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/renforge"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/renforge"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

renforge-0.1.0/src/renforge/__init__.py

@@ -0,0 +1,4 @@
+"""RenForge package."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

renforge-0.1.0/src/renforge/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

renforge-0.1.0/src/renforge/activity_log.py

@@ -0,0 +1,93 @@
+"""Activity feed helpers for MCP tool calls."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+
+def _coerce_project_root(project_root: str | Path) -> Path:
+    return Path(project_root).expanduser().resolve()
+
+
+def _coerce_files_touched(value: Any) -> list[str]:
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, (list, tuple, set)):
+        return [str(item) for item in value if isinstance(item, (str, Path))]
+    return []
+
+
+def _coerce_result_payload(result: Any) -> Any:
+    if isinstance(result, dict) and "ok" in result:
+        return result
+    if isinstance(result, (str, int, float, bool, list, type(None))):
+        return result
+    return str(result)
+
+
+def _coerce_payload(value: Any) -> Any:
+    if isinstance(value, (str, int, float, bool, type(None))):
+        return value
+    if isinstance(value, list):
+        return [_coerce_payload(item) for item in value]
+    if isinstance(value, dict):
+        return {str(k): _coerce_payload(v) for k, v in value.items()}
+    if isinstance(value, set):
+        return sorted(str(item) for item in value)
+    if isinstance(value, tuple):
+        return [_coerce_payload(item) for item in value]
+    return str(value)
+
+
+def summarize_result(result: Any) -> dict[str, Any]:
+    if isinstance(result, dict):
+        ok = result.get("ok", not isinstance(result.get("error"), str))
+        files_touched: list[str] = []
+        for key in ("files_touched", "files", "changed_files", "changed", "file_touches"):
+            candidate = result.get(key)
+            if candidate:
+                files_touched = _coerce_files_touched(candidate)
+                break
+        return {"ok": bool(ok), "files_touched": files_touched, "result": result}
+
+    if isinstance(result, (str, int, float, bool, list, type(None))):
+        return {"ok": True, "files_touched": [], "result": result}
+
+    return {"ok": True, "files_touched": [], "result": str(result)}
+
+
+def log_tool_call(
+    project_root: str | Path,
+    name: str,
+    params: dict[str, Any],
+    duration_ms: float,
+    result: Any,
+    files_touched: list[str] | None = None,
+) -> None:
+    summary = summarize_result(result)
+    entry = {
+        "ts": int(time.time() * 1000),
+        "name": name,
+        "params": _coerce_payload(params),
+        "duration_ms": duration_ms,
+        "ok": summary["ok"],
+        "result": _coerce_result_payload(summary["result"]),
+        "files_touched": files_touched or summary["files_touched"],
+    }
+
+    root = _coerce_project_root(project_root)
+    if not root.exists() or not root.is_dir():
+        return
+    path = root / ".renforge" / "activity.jsonl"
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = json.dumps(entry, ensure_ascii=False, separators=(",", ":"))
+    with path.open("a", encoding="utf-8") as file_obj:
+        file_obj.write(payload)
+        file_obj.write("\n")
+        file_obj.flush()
+        os.fsync(file_obj.fileno())

renforge-0.1.0/src/renforge/assets.py

@@ -0,0 +1,149 @@
+"""Asset analysis: find orphaned and missing images/audio in a Ren'Py project.
+
+Heuristic and deliberately conservative — Ren'Py's image resolution is dynamic
+(``show eileen happy`` maps to a defined image or a file like
+``images/eileen happy.png``), so this reports *likely* orphans/missing rather
+than a proof. It reads the ``game/`` tree and the ``.rpy`` sources; the engine
+stays the source of truth via ``lint``.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".webp", ".gif", ".avif", ".tga", ".bmp"}
+AUDIO_EXTS = {".ogg", ".opus", ".mp3", ".wav", ".flac", ".m4a", ".aac", ".mp2", ".wma"}
+VIDEO_EXTS = {".webm", ".mp4", ".ogv", ".avi", ".mkv", ".mov", ".mpg", ".mpeg", ".flv"}
+ASSET_EXTS = IMAGE_EXTS | AUDIO_EXTS | VIDEO_EXTS
+
+_QUOTED_RE = re.compile(r"""["']([^"'\n]+?)["']""")
+_IMAGE_DEF_RE = re.compile(r"^\s*image\s+([^\n=:]+?)\s*(?:=|:)")
+_SCENE_SHOW_RE = re.compile(r"^\s*(?:scene|show)\s+(.+?)\s*(?:#.*)?$")
+# Tokens that end the image-name part of a scene/show statement.
+_SHOW_STOP = {"at", "with", "as", "behind", "onlayer", "zorder", "expression"}
+
+
+def _game_dir(project_path: str | Path) -> Path:
+    return Path(project_path).expanduser().resolve() / "game"
+
+
+def _iter_rpy(game: Path):
+    for root, _dirs, files in os.walk(game):
+        for name in files:
+            if name.endswith(".rpy"):
+                yield Path(root) / name
+
+
+def _image_name_from_show(rest: str) -> str:
+    tokens = rest.split()
+    keep: list[str] = []
+    for tok in tokens:
+        if tok in _SHOW_STOP:
+            break
+        keep.append(tok)
+    return " ".join(keep)
+
+
+def analyze_assets(project_path: str | Path) -> dict[str, Any]:
+    game = _game_dir(project_path)
+    result: dict[str, Any] = {
+        "asset_files": [],
+        "orphans": [],
+        "missing_files": [],
+        "undefined_images": [],
+    }
+    if not game.is_dir():
+        result["error"] = f"no game/ directory under {project_path}"
+        return result
+
+    # 1. Asset files on disk (relative to game/, posix-style).
+    disk_files: list[str] = []
+    for root, _dirs, files in os.walk(game):
+        for name in files:
+            if Path(name).suffix.lower() in ASSET_EXTS:
+                rel = (Path(root) / name).relative_to(game).as_posix()
+                disk_files.append(rel)
+    disk_files.sort()
+    result["asset_files"] = disk_files
+
+    # 2. References from the scripts.
+    quoted: set[str] = set()
+    defined_images: set[str] = set()
+    shown_images: set[str] = set()
+    for rpy in _iter_rpy(game):
+        try:
+            text = rpy.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        for line in text.splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            for m in _QUOTED_RE.finditer(line):
+                quoted.add(m.group(1))
+            dm = _IMAGE_DEF_RE.match(line)
+            if dm:
+                defined_images.add(dm.group(1).strip())
+            sm = _SCENE_SHOW_RE.match(line)
+            if sm:
+                name = _image_name_from_show(sm.group(1))
+                if name:
+                    shown_images.add(name)
+
+    quoted_basenames = {Path(q).name for q in quoted}
+
+    def _referenced(rel: str) -> bool:
+        base = Path(rel).name
+        stem = Path(rel).stem  # image name candidate, e.g. "eileen happy"
+        if rel in quoted or base in quoted_basenames:
+            return True
+        if any(q.endswith(rel) or q.endswith(base) for q in quoted):
+            return True
+        # Image files referenced via `scene/show <name>` or `image <name>`.
+        if Path(rel).suffix.lower() in IMAGE_EXTS:
+            if stem in shown_images or stem in defined_images:
+                return True
+        return False
+
+    result["orphans"] = [rel for rel in disk_files if not _referenced(rel)]
+
+    # 3. Missing: quoted references that look like *developer* asset paths but
+    #    aren't on disk. We skip substitution patterns ("[prefix_]...") and the
+    #    gui/ tree, whose images the GUI framework generates or renders by
+    #    default — flagging those would be noise, not actionable findings.
+    disk_set = set(disk_files)
+    disk_basenames = {Path(f).name for f in disk_files}
+    for q in sorted(quoted):
+        if "[" in q or "]" in q:
+            continue
+        if q.startswith("gui/"):
+            continue
+        if Path(q).suffix.lower() in ASSET_EXTS:
+            if q not in disk_set and Path(q).name not in disk_basenames:
+                result["missing_files"].append(q)
+
+    # 4. Images shown but neither defined nor backed by a file (Ren'Py would use
+    #    a placeholder). Reported separately as a soft signal.
+    disk_stems = {Path(f).stem for f in disk_files if Path(f).suffix.lower() in IMAGE_EXTS}
+    for name in sorted(shown_images):
+        if name in defined_images:
+            continue
+        # A single-tag show may resolve to "<first-tag>.png"; check tag stems too.
+        first = name.split()[0] if name.split() else name
+        if name in disk_stems or first in disk_stems or first in defined_images:
+            continue
+        result["undefined_images"].append(name)
+
+    result["summary"] = {
+        "asset_count": len(disk_files),
+        "orphan_count": len(result["orphans"]),
+        "missing_count": len(result["missing_files"]),
+        "undefined_image_count": len(result["undefined_images"]),
+    }
+    return result
+
+
+__all__ = ["analyze_assets"]