snapdoczilla-mcp 1.0.0__py3-none-any.whl

snapdoczilla_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""SnapDoczilla MCP server: offline docs-as-code driven by your AI agent."""
+
+__version__ = "1.0.0"

snapdoczilla_mcp/core.py

@@ -0,0 +1,377 @@
+"""Deterministic helpers behind the SnapDoczilla MCP tools (no MCP imports here).
+
+The model writes the documentation. This module does the parts that must not
+depend on a model: locating the repo, running the bundled installer and the
+strict HTML build, tracking the last documented commit per area, and keeping
+every write inside ``documentation/source/``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+MAX_OUTPUT = 4000
+MAX_PAGE_BYTES = 1_000_000
+HASH_RE = re.compile(r"^[0-9a-f]{7,64}$")
+LANG_RE = re.compile(r"^[A-Za-z]{2,3}([_-][A-Za-z0-9]{2,8})?$")
+AREA_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+PAGE_RE = re.compile(r"^[\w.-]+(/[\w.-]+)*\.md$")
+
+
+class SnapDoczillaError(Exception):
+    """A problem the model can read and act on."""
+
+
+# --------------------------------------------------------------------------- #
+# Locating things
+# --------------------------------------------------------------------------- #
+
+def skill_dir() -> Path:
+    """Folder with scripts/ and assets/: bundled in the wheel, or the repo checkout in dev."""
+    here = Path(__file__).resolve().parent
+    for candidate in (here / "skill", here.parents[1] / "skills" / "snapdoczilla"):
+        if (candidate / "scripts" / "install.sh").is_file():
+            return candidate
+    raise SnapDoczillaError("The bundled SnapDoczilla skill files are missing; reinstall snapdoczilla-mcp.")
+
+
+def bash_exe() -> str:
+    """bash for the bundled .sh scripts. On Windows only Git for Windows' bash (never WSL's)."""
+    if os.name == "nt":
+        roots = [os.environ.get(v) for v in ("ProgramFiles", "ProgramFiles(x86)", "LOCALAPPDATA")]
+        candidates = [Path(r) / sub / "bin" / "bash.exe" for r in roots if r for sub in ("Git", "Programs/Git")]
+        git = shutil.which("git")
+        if git:
+            candidates.append(Path(git).resolve().parent.parent / "bin" / "bash.exe")
+        for c in candidates:
+            if c.is_file():
+                return str(c)
+        raise SnapDoczillaError("Git for Windows (which ships bash) was not found. Install it from https://git-scm.com.")
+    found = shutil.which("bash")
+    if not found:
+        raise SnapDoczillaError("bash was not found on PATH.")
+    return found
+
+
+def _run(cmd: list[str], cwd: Path | None = None, timeout: int = 60) -> tuple[int, str]:
+    """Run a command with stdin closed: stdin belongs to the MCP protocol, children must not read it."""
+    extra: dict[str, Any] = {}
+    if os.name == "nt":
+        extra["creationflags"] = 0x08000000  # CREATE_NO_WINDOW
+    try:
+        p = subprocess.run(
+            cmd, cwd=cwd, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+            text=True, encoding="utf-8", errors="replace", timeout=timeout, **extra,
+        )
+    except FileNotFoundError:
+        raise SnapDoczillaError(f"Command not found: {cmd[0]}") from None
+    except subprocess.TimeoutExpired:
+        raise SnapDoczillaError(f"Timed out after {timeout}s: {' '.join(cmd[:3])} ...") from None
+    return p.returncode, p.stdout
+
+
+def _git(repo: Path, *args: str, timeout: int = 60) -> tuple[int, str]:
+    return _run(["git", "-C", str(repo), *args], timeout=timeout)
+
+
+def _tail(text: str, limit: int = MAX_OUTPUT) -> str:
+    text = text.strip()
+    return text if len(text) <= limit else "...[truncated]...\n" + text[-limit:]
+
+
+def resolve_repo(path: str) -> Path:
+    if not path or not str(path).strip():
+        raise SnapDoczillaError("repo is required: the path of a git repository.")
+    p = Path(str(path).strip()).expanduser()
+    if not p.is_dir():
+        raise SnapDoczillaError(f"Not a directory: {p}")
+    rc, out = _git(p, "rev-parse", "--show-toplevel")
+    if rc != 0:
+        raise SnapDoczillaError(f"{p} is not inside a git repository.")
+    return Path(out.strip())
+
+
+def _doc(repo: Path) -> Path:
+    return repo / "documentation"
+
+
+def _installed(repo: Path) -> bool:
+    d = _doc(repo)
+    return (d / "mkdocs.yml").is_file() and (d / "update.sh").is_file()
+
+
+def _require_installed(repo: Path) -> Path:
+    if not _installed(repo):
+        raise SnapDoczillaError("SnapDoczilla is not installed in this repo. Call snapdoczilla_install first.")
+    return _doc(repo)
+
+
+def read_areas(doc: Path) -> list[tuple[str, str]]:
+    conf = doc / "areas.conf"
+    if not conf.is_file():
+        raise SnapDoczillaError("documentation/areas.conf is missing.")
+    areas = []
+    for line in conf.read_text(encoding="utf-8").splitlines():
+        s = line.strip()
+        if s and not s.startswith("#") and "=" in s:
+            name, path = s.split("=", 1)
+            areas.append((name.strip(), path.strip()))
+    return areas
+
+
+def _area_path(doc: Path, area: str) -> str:
+    areas = dict(read_areas(doc))
+    if area not in areas:
+        raise SnapDoczillaError(f"Unknown area '{area}'. Areas in areas.conf: {', '.join(areas) or '(none)'}")
+    return areas[area]
+
+
+def _last_sync(doc: Path, area: str) -> str | None:
+    marker = doc / f".last-sync-{area}"
+    if not marker.is_file():
+        return None
+    value = marker.read_text(encoding="utf-8").strip()
+    return value if HASH_RE.match(value) else None
+
+
+# --------------------------------------------------------------------------- #
+# Tools
+# --------------------------------------------------------------------------- #
+
+def status(repo_path: str) -> dict[str, Any]:
+    repo = resolve_repo(repo_path)
+    doc = _doc(repo)
+    installed = _installed(repo)
+    _, head = _git(repo, "rev-parse", "--short", "HEAD")
+    result: dict[str, Any] = {
+        "repo": str(repo),
+        "head": head.strip() or None,
+        "installed": installed,
+        "foreign_documentation_dir": doc.exists() and not installed,
+    }
+    if result["foreign_documentation_dir"]:
+        result["next_step"] = (
+            "documentation/ exists but was not created by SnapDoczilla. Stop and ask the user before touching it."
+        )
+        return result
+    if not installed:
+        result["next_step"] = "Call snapdoczilla_install (choose the areas from the repo layout), then write the base pages."
+        return result
+
+    areas = []
+    for name, path in read_areas(doc):
+        last = _last_sync(doc, name)
+        behind = None
+        if last:
+            rc, out = _git(repo, "rev-list", "--count", f"{last}..HEAD", "--", path, ":!documentation")
+            behind = int(out.strip()) if rc == 0 and out.strip().isdigit() else None
+        areas.append({
+            "name": name, "path": path, "last_sync": last, "commits_not_documented": behind,
+            "has_area_rules": (doc / f"AGENT-RULES-{name}.md").is_file(),
+        })
+    src = doc / "source"
+    pages = sorted(p.relative_to(src).as_posix() for p in src.rglob("*.md")) if src.is_dir() else []
+    adr_numbers = [int(m.group(1)) for p in pages if (m := re.match(r"adr/(\d{4})-", p))]
+    result.update({
+        "areas": areas,
+        "pages": pages,
+        "next_adr_number": f"{max(adr_numbers, default=0) + 1:04d}",
+        "html_built": (doc / "html" / "index.html").is_file(),
+    })
+    stale = [a["name"] for a in areas if a["commits_not_documented"]]
+    never = [a["name"] for a in areas if a["last_sync"] is None]
+    if never:
+        result["next_step"] = f"Areas never documented: {', '.join(never)}. Write their pages, build, then mark_synced."
+    elif stale:
+        result["next_step"] = f"Out of date: {', '.join(stale)}. Call snapdoczilla_changes_since_sync for each."
+    else:
+        result["next_step"] = "Everything is documented up to HEAD."
+    return result
+
+
+def install(repo_path: str, project_name: str, language: str = "en",
+            areas: dict[str, str] | None = None, ui_areas: list[str] | None = None) -> dict[str, Any]:
+    repo = resolve_repo(repo_path)
+    name = (project_name or "").strip()
+    if not name or any(ord(c) < 32 for c in name) or '"' in name:
+        raise SnapDoczillaError('project_name must be non-empty, single-line, and contain no double quotes.')
+    if not LANG_RE.match(language or ""):
+        raise SnapDoczillaError("language must be a code such as 'en' or 'es'.")
+    if _installed(repo):
+        raise SnapDoczillaError("SnapDoczilla is already installed here. Nothing was changed.")
+    if _doc(repo).exists():
+        raise SnapDoczillaError("documentation/ already exists and was not created by SnapDoczilla. Ask the user first.")
+
+    clean_areas = _validate_areas(repo, areas) if areas else None
+    ui = list(ui_areas or [])
+    if clean_areas is not None:
+        unknown = [a for a in ui if a not in clean_areas]
+        if unknown:
+            raise SnapDoczillaError(f"ui_areas not in areas: {', '.join(unknown)}")
+    elif ui:
+        raise SnapDoczillaError("ui_areas requires areas.")
+
+    # install.sh substitutes the name through sed with '|' as delimiter: escape sed's specials.
+    sed_safe = name.replace("\\", "\\\\").replace("&", "\\&").replace("|", "\\|")
+    script = (skill_dir() / "scripts" / "install.sh").as_posix()
+    rc, out = _run([bash_exe(), script, repo.as_posix(), sed_safe, language], timeout=180)
+    if rc != 0:
+        raise SnapDoczillaError(f"install.sh failed (exit {rc}):\n{_tail(out)}")
+
+    doc = _doc(repo)
+    notes: list[str] = []
+    if "WARNING" in out:
+        notes.append(next((l for l in out.splitlines() if "WARNING" in l), "Mermaid could not be downloaded."))
+    if clean_areas is not None:
+        header = [l for l in (doc / "areas.conf").read_text(encoding="utf-8").splitlines() if l.strip().startswith("#")]
+        lines = header + [f"{n}={p}" for n, p in clean_areas.items()]
+        (doc / "areas.conf").write_text("\n".join(lines) + "\n", encoding="utf-8", newline="\n")
+        template = doc / "AGENT-RULES-COMPONENTS.md"
+        for a in ui:
+            shutil.copyfile(template, doc / f"AGENT-RULES-{a}.md")
+        if not ui and template.is_file():
+            template.unlink()
+        notes.append(f"areas.conf written with: {', '.join(clean_areas)}")
+    else:
+        notes.append("areas.conf still has the default area code=.; edit it if the repo has separate back/front parts.")
+    return {
+        "installed": True,
+        "documentation_dir": str(doc),
+        "notes": notes,
+        "next_step": "Call snapdoczilla_get_rules, write the base pages with snapdoczilla_write_page "
+                     "(index, getting-started, architecture, api if any), then snapdoczilla_build_html and snapdoczilla_mark_synced.",
+    }
+
+
+def _validate_areas(repo: Path, areas: dict[str, str]) -> dict[str, str]:
+    clean: dict[str, str] = {}
+    for name, path in areas.items():
+        if not AREA_RE.match(name):
+            raise SnapDoczillaError(f"Invalid area name '{name}': use letters, digits, '-' or '_'.")
+        p = path.strip().replace("\\", "/")
+        if not p or p.startswith("/") or re.match(r"^[A-Za-z]:", p) or ".." in p.split("/") or "=" in p or "\n" in p:
+            raise SnapDoczillaError(f"Invalid path for area '{name}': must be relative to the repo root.")
+        if not (repo / p).is_dir():
+            raise SnapDoczillaError(f"Path for area '{name}' is not a directory in the repo: {p}")
+        clean[name] = p
+    return clean
+
+
+def get_rules(repo_path: str, area: str | None = None) -> dict[str, Any]:
+    repo = resolve_repo(repo_path)
+    doc = _require_installed(repo)
+    names = ["AGENT-RULES.md"]
+    if area:
+        _area_path(doc, area)
+        extra = f"AGENT-RULES-{area}.md"
+        if (doc / extra).is_file():
+            names.append(extra)
+    return {"rules": {n: (doc / n).read_text(encoding="utf-8") for n in names if (doc / n).is_file()}}
+
+
+def changes_since_sync(repo_path: str, area: str) -> dict[str, Any]:
+    repo = resolve_repo(repo_path)
+    doc = _require_installed(repo)
+    path = _area_path(doc, area)
+    last = _last_sync(doc, area)
+    base: dict[str, Any] = {"area": area, "area_path": path, "last_sync": last}
+    if last is None:
+        return {**base, "first_generation": True,
+                "hint": f"No sync marker: analyze '{path}' fully, then mark_synced."}
+    rc, _ = _git(repo, "cat-file", "-e", f"{last}^{{commit}}")
+    if rc != 0:
+        return {**base, "first_generation": True,
+                "hint": "The recorded commit no longer exists (history rewritten). Treat as a full pass."}
+    spec = [f"{last}..HEAD", "--", path, ":!documentation"]
+    _, names = _git(repo, "diff", "--name-status", *spec)
+    _, stat = _git(repo, "diff", "--stat", *spec)
+    _, log = _git(repo, "log", "--oneline", "-n", "30", *spec)
+    files = names.strip().splitlines()
+    return {
+        **base, "first_generation": False,
+        "changed_files": files[:200], "changed_files_truncated": len(files) > 200,
+        "summary": _tail(stat, 1500), "commits": log.strip().splitlines(),
+        "hint": "Read only these files, update only the affected pages. Only committed changes are listed.",
+    }
+
+
+def write_page(repo_path: str, page: str, content: str, nav_title: str | None = None) -> dict[str, Any]:
+    repo = resolve_repo(repo_path)
+    doc = _require_installed(repo)
+    parts = page.split("/")
+    if (not PAGE_RE.match(page) or any(p.startswith(".") for p in parts) or parts[0] == "assets"):
+        raise SnapDoczillaError("page must be a relative .md path such as 'architecture.md' or 'adr/0002-use-queue.md'.")
+    if "\x00" in content or len(content.encode("utf-8")) > MAX_PAGE_BYTES:
+        raise SnapDoczillaError("content must not contain NUL characters and must be under 1 MB.")
+    src = (doc / "source").resolve()
+    target = (src / page).resolve()
+    if not target.is_relative_to(src):
+        raise SnapDoczillaError("page escapes documentation/source/.")
+    created = not target.exists()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8", newline="\n")
+    nav_added = False
+    if nav_title:
+        nav_added = _add_to_nav(doc / "mkdocs.yml", page, nav_title)
+    return {
+        "page": page, "created": created, "nav_added": nav_added,
+        "reminder": "Every page must be in nav: or the strict build fails." if created and not nav_added else None,
+    }
+
+
+def _add_to_nav(mkdocs: Path, page: str, title: str) -> bool:
+    if "\n" in title or "\r" in title:
+        raise SnapDoczillaError("nav_title must be a single line.")
+    raw = mkdocs.read_bytes().decode("utf-8")
+    nl = "\r\n" if "\r\n" in raw else "\n"
+    lines = raw.split(nl)
+    start = next((i for i, l in enumerate(lines) if l.rstrip() == "nav:"), None)
+    if start is None:
+        raise SnapDoczillaError("No top-level 'nav:' in documentation/mkdocs.yml; add the entry by hand.")
+    last, j = start, start + 1
+    while j < len(lines):
+        l = lines[j]
+        if l.strip() == "":
+            j += 1
+        elif l[0] in " \t-":
+            if page in re.split(r"[\s:'\"]+", l):
+                return False
+            last, j = j, j + 1
+        else:
+            break
+    indent = re.match(r"\s*", lines[start + 1]).group(0) if start + 1 < len(lines) and lines[start + 1].strip() else "  "
+    lines.insert(last + 1, f"{indent or '  '}- {json.dumps(title, ensure_ascii=False)}: {page}")
+    mkdocs.write_bytes(nl.join(lines).encode("utf-8"))
+    return True
+
+
+def build_html(repo_path: str) -> dict[str, Any]:
+    repo = resolve_repo(repo_path)
+    doc = _require_installed(repo)
+    rc, out = _run([bash_exe(), (doc / "update.sh").as_posix(), "--html-only"], cwd=repo, timeout=900)
+    problems = [l.strip() for l in out.splitlines() if re.search(r"\b(WARNING|ERROR)\b|Aborted|could not be found", l)]
+    return {
+        "ok": rc == 0,
+        "index": str(doc / "html" / "index.html"),
+        "problems": problems[:40],
+        "output_tail": _tail(out),
+        "hint": None if rc == 0 else
+        "The previous html/ was kept. Fix the cause (nav, links, snippet paths); never loosen mkdocs.yml to get green.",
+    }
+
+
+def mark_synced(repo_path: str, area: str) -> dict[str, Any]:
+    repo = resolve_repo(repo_path)
+    doc = _require_installed(repo)
+    _area_path(doc, area)
+    rc, out = _git(repo, "rev-parse", "HEAD")
+    if rc != 0 or not HASH_RE.match(out.strip()):
+        raise SnapDoczillaError("The repo has no commits yet; commit something first.")
+    (doc / f".last-sync-{area}").write_text(out.strip() + "\n", encoding="utf-8", newline="\n")
+    return {"area": area, "last_sync": out.strip()}

snapdoczilla_mcp/server.py

@@ -0,0 +1,130 @@
+"""SnapDoczilla MCP server (stdio). Run with ``snapdoczilla-mcp`` or ``uvx snapdoczilla-mcp``."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Annotated, Any
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from . import __version__, core
+
+INSTRUCTIONS = """\
+SnapDoczilla keeps offline docs-as-code (MkDocs Material + local Mermaid) inside a git repo.
+YOU write the documentation from the real code; these tools do the deterministic parts.
+This server does not read source code: use your client's own file tools for that.
+
+Workflow
+1. snapdoczilla_status(repo): installed? which areas are out of date?
+2. Not installed: snapdoczilla_install (choose areas from the repo layout), then write the base pages.
+3. Installed: snapdoczilla_changes_since_sync(area), read ONLY the changed code, update ONLY the affected pages.
+4. snapdoczilla_get_rules before writing, and follow it (language, never invent, embed real code).
+5. snapdoczilla_write_page writes inside documentation/source/ only and can add the page to nav.
+6. snapdoczilla_build_html is strict: fix every reported problem, never loosen the config.
+7. snapdoczilla_mark_synced once an area is documented up to HEAD.
+Never commit or push. Anything you cannot verify in the code is flagged as "to be confirmed".
+"""
+
+mcp = MCPServer("snapdoczilla", instructions=INSTRUCTIONS, version=__version__)
+
+Repo = Annotated[str, Field(description="Absolute path of the git repository (any folder inside it works).")]
+Area = Annotated[str, Field(description="Area name from documentation/areas.conf, e.g. 'back' or 'front'.")]
+
+READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False)
+WRITES_DOCS = ToolAnnotations(readOnlyHint=False, destructiveHint=False, idempotentHint=True, openWorldHint=False)
+
+
+async def _off_loop(fn, *args) -> dict[str, Any]:
+    """Blocking work (git, bash, mkdocs) runs in a thread so the protocol loop keeps answering."""
+    try:
+        return await asyncio.to_thread(fn, *args)
+    except core.SnapDoczillaError as exc:
+        raise ToolError(str(exc)) from None  # expected problems: show the model the real message
+
+
+@mcp.tool(name="snapdoczilla_status", annotations=READ_ONLY)
+async def snapdoczilla_status(repo: Repo) -> dict[str, Any]:
+    """Report whether SnapDoczilla is installed in the repo, its areas, how many commits each area is
+    behind its docs, the existing pages, the next ADR number and the suggested next step. Call this first."""
+    return await _off_loop(core.status, repo)
+
+
+@mcp.tool(name="snapdoczilla_install",
+          annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, idempotentHint=False, openWorldHint=True))
+async def snapdoczilla_install(
+    repo: Repo,
+    project_name: Annotated[str, Field(description="Human name shown as the site title.")],
+    language: Annotated[str, Field(description="Docs language code: 'en', 'es', ...")] = "en",
+    areas: Annotated[dict[str, str] | None, Field(
+        description="Code areas as {name: path relative to the repo root}, e.g. {'back': 'backend/', 'front': 'frontend/'}. "
+                    "Omit for a single area covering the whole repo.")] = None,
+    ui_areas: Annotated[list[str] | None, Field(
+        description="Names from `areas` that contain UI components; they get component-page rules.")] = None,
+) -> dict[str, Any]:
+    """Install the documentation scaffold into documentation/ (templates, update script, pre-push reminder)
+    and download Mermaid once (needs internet). Refuses to touch an existing documentation/ folder."""
+    return await _off_loop(core.install, repo, project_name, language, areas, ui_areas)
+
+
+@mcp.tool(name="snapdoczilla_get_rules", annotations=READ_ONLY)
+async def snapdoczilla_get_rules(repo: Repo, area: Annotated[str | None, Field(
+        description="Also return this area's AGENT-RULES-<area>.md when it exists.")] = None) -> dict[str, Any]:
+    """Return the rules the documentation must follow (language, tone, page layout, no invention)."""
+    return await _off_loop(core.get_rules, repo, area)
+
+
+@mcp.tool(name="snapdoczilla_changes_since_sync", annotations=READ_ONLY)
+async def snapdoczilla_changes_since_sync(repo: Repo, area: Area) -> dict[str, Any]:
+    """List the files, commits and diffstat of an area since its last documented commit, so only the
+    affected pages are updated. With no previous sync it says to analyze the whole area."""
+    return await _off_loop(core.changes_since_sync, repo, area)
+
+
+@mcp.tool(name="snapdoczilla_write_page", annotations=WRITES_DOCS)
+async def snapdoczilla_write_page(
+    repo: Repo,
+    page: Annotated[str, Field(description="Path inside documentation/source/, e.g. 'architecture.md' or 'adr/0002-use-queue.md'.")],
+    content: Annotated[str, Field(description="Full Markdown of the page. Embed real code with --8<-- \"path/from/repo/root\".")],
+    nav_title: Annotated[str | None, Field(
+        description="Menu title. Pass it when creating a page so it is added to nav (the strict build needs that).")] = None,
+) -> dict[str, Any]:
+    """Create or overwrite one Markdown page. Writes are confined to documentation/source/."""
+    return await _off_loop(core.write_page, repo, page, content, nav_title)
+
+
+@mcp.tool(name="snapdoczilla_build_html", annotations=WRITES_DOCS)
+async def snapdoczilla_build_html(repo: Repo) -> dict[str, Any]:
+    """Rebuild documentation/html with a strict MkDocs build (no AI agent is invoked). The first run creates a
+    local venv and installs MkDocs, which takes a minute or two and needs internet. A failed build keeps the old html."""
+    return await _off_loop(core.build_html, repo)
+
+
+@mcp.tool(name="snapdoczilla_mark_synced", annotations=WRITES_DOCS)
+async def snapdoczilla_mark_synced(repo: Repo, area: Area) -> dict[str, Any]:
+    """Record the current HEAD as the last documented commit of an area. Call it after the area's pages are updated."""
+    return await _off_loop(core.mark_synced, repo, area)
+
+
+@mcp.prompt(name="document_project", title="Document this project with SnapDoczilla")
+def document_project(language: str = "en") -> str:
+    return (
+        f"Document this repository with SnapDoczilla in {language}. Start with snapdoczilla_status. "
+        "Install if needed, write the base pages from the real code (read it with your file tools), "
+        "build the HTML, fix every reported problem, mark each area as synced, then summarize what "
+        "was created and what is flagged as to be confirmed. Do not commit or push."
+    )
+
+
+def main() -> None:
+    if "--version" in sys.argv[1:]:
+        print(__version__)
+        return
+    mcp.run()  # stdio; stdout is reserved for the protocol
+
+
+if __name__ == "__main__":
+    main()

snapdoczilla_mcp/skill/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: snapdoczilla
+description: SnapDoczilla - sets up and maintains technical documentation for any repository (any backend, any frontend) as a 100% offline HTML site that lives inside the repo - no Confluence, no servers, no CI. Readers double-click documentation/html/index.html; any dev refreshes it with one command. Built with MkDocs Material, local Mermaid diagrams and react.dev-style component pages that embed real source code and real usage. Use it whenever the user wants to document a project or codebase, set up "docs as code", generate or update architecture/API/ADR/onboarding docs, document frontend components, or asks to "document this project" / "documenta este proyecto" / "actualiza la documentación" - even if they don't name SnapDoczilla or MkDocs. Also use it when a repo already has documentation/update.sh and the user asks to update the docs.
+---
+
+# SnapDoczilla
+
+Leaves a documentation system in the repo that **anyone reads with a double click** (no install, no internet) and **any dev updates with one command**.
+
+`SKILL_DIR` below means the folder that contains this `SKILL.md`.
+
+## Scope
+
+**What it documents** — any stack, as long as the code is in the repo:
+
+| Area | Pages produced | Source of truth |
+|---|---|---|
+| Any project | `index.md` (what it is, stack, versions), `getting-started.md` (requirements, run, test), `adr/0001-*.md` | build files, README, config |
+| Backend | `architecture.md` (layers, integrations, main flows in Mermaid), `api.md` (endpoints grouped by resource), data model if there is one | routes/controllers, services, clients, migrations/schemas |
+| Frontend | screen/route map, `src/` structure, state management, **component pages** (what it is, props/events/slots, real usage, real code) | router, views/pages, components, stores |
+
+Where to look, by stack (not exhaustive — read whatever the repo actually uses):
+
+| Stack | Endpoints / routes | Run & build |
+|---|---|---|
+| Spring / Java | `@RestController`, `@*Mapping`, `@HttpExchange`/Feign clients | `pom.xml`, `build.gradle`, `application.*` |
+| Node (Express, Nest, Fastify) | `router.get(...)`, `@Controller`/`@Get` | `package.json` scripts |
+| Python (FastAPI, Django, Flask) | `@app.get`, `urls.py`, `@bp.route` | `pyproject.toml`, `requirements*.txt`, `manage.py` |
+| .NET | `[ApiController]`, `MapGet` | `*.csproj`, `appsettings*.json` |
+| Go / PHP / Ruby | `http.HandleFunc`/router libs, `routes/*.php`, `config/routes.rb` | `go.mod`, `composer.json`, `Gemfile` |
+| Vue / React / Angular / Svelte | `router/`, `app/` or `pages/` dirs, `*.routes.ts` | `package.json`, `vite.config.*`, `angular.json` |
+
+**What it deliberately does not do:** screenshots or live demos (they force running the app and go stale on their own), hosting or publishing, replacing OpenAPI/Swagger (it links to it), inventing behavior the code doesn't show.
+
+## Why it's designed this way
+
+- **Everything inside the repo.** Docs travel with the code and are reviewed in the same PRs.
+- **The HTML is committed.** Non-technical readers and new devs open `documentation/html/index.html`. The cost is big diffs in `html/`; accepted in exchange for zero setup.
+- **Source code is never pasted.** Pages embed the real file at build time (`--8<-- "path"`), so they can't drift; if a file moves, the build fails naming it.
+- **The agent assists, humans approve.** It writes the base and incremental updates; people review `git diff`. Anything it cannot verify is flagged as "to be confirmed".
+- **Areas are independent.** `back`, `front`, etc. each have their own sync marker and command, so a frontend dev never regenerates backend docs.
+
+## Pick a flow
+
+| Situation | Flow |
+|---|---|
+| No `documentation/mkdocs.yml` yet and the user wants docs | **A. Install** |
+| `documentation/` exists and they want it refreshed | **B. Update** |
+| They want one component documented | **C. Component page** |
+
+If the repo already has a `documentation/` folder that was **not** made by SnapDoczilla (no `mkdocs.yml` + `update.sh`), stop and ask before touching it.
+
+## A. Install
+
+1. **Check prerequisites** — report what's missing, never install anything global: `git` (must be a git repo), `python3`/`python`, `bash` (on Windows it ships with Git for Windows). An agent CLI (`claude`, `codex`, `opencode`…) is only needed for one-command updates later; `--html-only` works without it.
+2. **Detect areas.** Look for `backend/`, `frontend/`, `api/`, `web/`, `apps/*`, `packages/*`, `src/`. One block → a single area `code=.`. Clearly separate parts → one area each (`back=backend/`, `front=frontend/`). Ask only if the split is not evident.
+3. **Pick the docs language:** the language the user is writing in, unless they ask for another (`en`, `es`, …).
+4. **Run the installer** (copies templates, downloads Mermaid once, adds `.gitignore`/`.gitattributes` lines; refuses to overwrite an existing install):
+   ```bash
+   bash "$SKILL_DIR/scripts/install.sh" "<repo-root>" "<Project name>" <lang>
+   ```
+5. **Write `documentation/areas.conf`** with the detected areas (`name=path`).
+6. **UI areas:** copy `documentation/AGENT-RULES-COMPONENTS.md` to `documentation/AGENT-RULES-<area>.md` (e.g. `AGENT-RULES-front.md`); per-area rules are picked up automatically. No UI area → delete the template.
+7. **Generate the first content** in `documentation/source/`, following `AGENT-RULES.md` (and each area's rules) and the Scope table above. For UI areas, write 2–3 component pages for representative components (ask which, or pick the most reused). Read real code; don't invent. Add every page to `nav:` in `mkdocs.yml`.
+8. **Existing docs** (md, docx, pdf) are context for the *why*, never a substitute for reading code. Convert docx/pdf to Markdown before reading, and never copy secrets or tokens they may contain.
+9. **Mark sync:** for each area, `git rev-parse HEAD > documentation/.last-sync-<area>`.
+10. **Build and verify:**
+    ```bash
+    bash documentation/update.sh --html-only
+    ```
+    First build installs MkDocs into `documentation/.venv` (1–2 min, needs internet). `snippet ... could not be found` → fix that path. If Chrome/Edge is available, open `html/architecture.html` headless with `--allow-file-access-from-files --dump-dom` and check there are more `<svg` than on a page without diagrams (Material adds ~7 icons).
+11. **Hand over** a short summary: what was created, how to read it, how to update it (below), what is flagged as to be confirmed. **Do not commit or push** — that is the user's call.
+
+## B. Update
+
+- **From a terminal:** `documentation/update.cmd` (Windows double-click) or `./documentation/update.sh [--<area>] [--html-only]`. It sends the diff since `.last-sync-<area>` to an agent CLI, which edits only `source/`, then rebuilds the HTML (atomically: a failed build never empties `html/`). Default CLI is Claude Code with tools restricted to `documentation/source/`; set `DOCS_LLM` to use another agent:
+
+  | Agent | `DOCS_LLM` |
+  |---|---|
+  | Claude Code | *(unset — default)* |
+  | Codex CLI | `codex exec --full-auto` |
+  | OpenCode | `opencode run` |
+  | Gemini CLI | `gemini --yolo -p` |
+  | Other | any non-interactive command that takes the prompt as its last argument |
+
+  Only the Claude default restricts writable paths; with other agents rely on their sandbox and review `git diff`.
+- **Inside this session (any agent, incl. Antigravity):** read `AGENT-RULES*.md`, run `git diff <hash in .last-sync-<area>>..HEAD -- <area path>`, edit only the affected pages, run `bash documentation/update.sh --html-only`, then `git rev-parse HEAD > documentation/.last-sync-<area>`.
+- Check line-range snippets (`path:START:END`) when their source file changed: they don't fail when they drift, they just show the wrong lines.
+
+## C. Component page
+
+Follow `AGENT-RULES-COMPONENTS.md`: what it is → how it works → API → **real usage example** → **real source code** → things to know. Read the component *and* its real consumers; the usage example comes from an existing screen (if none exists, label it as illustrative). Incomplete component (empty files, `console.log`, commented-out code) → say so in a `!!! warning` block. Add the page to `nav:`.
+
+## Good to know
+
+- Diagrams are ```` ```mermaid ```` blocks. The fence class is `diagram` on purpose: it stops Material from loading Mermaid from the internet; `assets/diagrams.js` renders them with the local copy.
+- Builds are `--strict` with `validation` set to `warn`: a page missing from `nav:`, a broken link or a missing snippet fails the build (and the previous `html/` stays). Fix the cause; never loosen the config to get a green build.
+- `install.sh` sets `repo_url`/`edit_uri` from the `origin` remote (GitHub/GitLab) so every page gets an "edit this page" button; other hosts are skipped silently.
+- Readers get a light/dark toggle; diagrams redraw in the matching theme.
+- The user wants it on the web too? `html/` is a static site: point them to the GitHub Pages workflow in the SnapDoczilla README instead of adding hosting yourself.
+- `requirements.txt` pins `mkdocs<2` and `mkdocs-material<10` (MkDocs 2.0 breaks plugins).
+- First run needs internet (pip + one Mermaid download); reading never does.
+- Merge conflict in `html/`: resolve the `.md` files, rerun `--html-only`, commit the result. Never hand-merge HTML.
+- Suggest naming **one docs owner** who reviews, while any dev can run the update.

snapdoczilla_mcp/skill/assets/documentation/AGENT-RULES-COMPONENTS.md

@@ -0,0 +1,47 @@
+# Rules for the agent: UI component pages
+
+Template for UI areas (Vue, React, Svelte, Angular, …). The skill copies it as `AGENT-RULES-<area>.md`
+for each UI area. These rules apply on top of `AGENT-RULES.md` (including its language).
+
+## Required structure of a component page
+
+One page per component (`<area>/<name>.md`, added to `nav:`), with these sections in this order:
+
+1. **What it is and what it's for** (2–4 lines a non-technical reader understands) + where it appears in the app.
+2. **How it works** (Mermaid diagram or a short list; visible business rules).
+3. **Component API**: tables of *Props*, *Events* and *Slots* (or the framework's equivalents): name, type, default, description. Taken from the code, never guessed.
+4. **Usage example from this project** — required. REAL code from the repo.
+5. **Source code** — required. REAL code from the repo.
+6. **Things to know**: dependencies (hooks/composables, stores, constants, endpoints) and tech debt or non-obvious behavior.
+
+## Embedding real code (never copy-paste)
+
+`pymdownx.snippets` inserts the current file at build time, so the page never drifts.
+
+````markdown
+=== "Usage"
+
+    ```tsx title="Screen.tsx"
+    --8<-- "src/screens/Screen.tsx"
+    ```
+
+=== "Code"
+
+    ```tsx title="Button.tsx"
+    --8<-- "src/components/Button.tsx"
+    ```
+````
+
+- Paths are relative to the repo root. Line range: `--8<-- "path:START:END"`.
+- Prefer whole files. Use ranges only to pull one usage line out of a big file, and **re-check the range** whenever that file changes.
+- Files over ~150 lines: wrap them in `??? note "Full source"` (content indented 4 spaces).
+- Build fails with "snippet ... could not be found" → the file moved or was renamed: fix the path.
+- An example that doesn't exist in the project must be labeled as illustrative.
+
+## Maturity
+
+If the component is incomplete (empty files, `console.log`, commented-out code), say so in a `!!! warning` block listing what's missing. Never document as working what doesn't work.
+
+## No screenshots or live demos
+
+They force running the app and go stale on their own.

snapdoczilla_mcp/skill/assets/documentation/AGENT-RULES.md

@@ -0,0 +1,17 @@
+# Rules for the agent that updates this documentation
+
+- **Documentation language: {{LANGUAGE}}.** Write every page, heading and marker in this language. Technical, direct tone.
+- **Edit only `documentation/source/`** (plus the `nav:` in `documentation/mkdocs.yml` when adding a page). Never touch code, `html/` or other folders.
+- Document only what exists in the code. Anything you cannot verify gets a `> ⚠️` "to be confirmed" note (written in the documentation language). Never invent endpoints, tables or credentials (use `{PLACEHOLDER}`). Never copy secrets, tokens or passwords.
+- Diagrams: ```` ```mermaid ```` blocks inside the `.md` files (they render offline).
+- Real code in the docs: never paste it; embed it with `--8<-- "path/from/repo/root"` (see `AGENT-RULES-COMPONENTS.md`).
+- Base pages (keep the file names; every new page also goes into `nav:`):
+  - `index.md`: what the project is, stack and versions.
+  - `getting-started.md`: requirements, how to run and test, taken from real files (README, build, config). If an existing README contradicts the real build, point out the discrepancy.
+  - `architecture.md`: layers, integrations and main flows, with Mermaid.
+  - `api.md`: only if the project exposes an API; read the real routes/controllers.
+  - `adr/NNNN-title.md`: one decision per file (Context, Decision, Consequences). New ADRs only for real architecture decisions (new library, database change, new pattern).
+- Incremental updates: change only the pages affected by the diff; don't rewrite what is still valid.
+- Keep the last line of `index.md` as `Last sync: <short hash> (<date>)` (translated to the documentation language).
+- Code areas and their paths live in `areas.conf`.
+- The build runs with `--strict`: every page must be listed in `nav:`, and every link and snippet path must resolve. A failed build keeps the previous `html/`; fix the cause and rebuild.

snapdoczilla_mcp/skill/assets/documentation/README.md

@@ -0,0 +1,8 @@
+# Project documentation (SnapDoczilla)
+
+- **Read:** open `documentation/html/index.html` with a double click. No install, no internet.
+- **Update:** `documentation/update.cmd` (Windows) or `./documentation/update.sh`. Options: `--<area>` (see `areas.conf`) or `--html-only` (no agent). Review the changes and commit.
+- Editable source: `documentation/source/*.md`. Rules for the agent: `documentation/AGENT-RULES*.md`.
+- To update you need Git (with bash), Python 3 and an agent CLI: Claude Code by default, or another one via `DOCS_LLM` (e.g. `DOCS_LLM="codex exec --full-auto"`). No agent: `--html-only`.
+
+Generated with [SnapDoczilla](https://github.com/julvc/skills).

snapdoczilla_mcp/skill/assets/documentation/areas.conf

@@ -0,0 +1,9 @@
+# Code areas documented and synced independently.
+# Format:  name=path   (path relative to the repo root; "." = whole repo)
+# Each area gets its own .last-sync-<name> marker and may have its own rules in
+# AGENT-RULES-<name>.md. Update one area with:  update.sh --<name>
+#
+# Examples:
+#   back=backend/
+#   front=frontend/
+code=.

snapdoczilla_mcp/skill/assets/documentation/mkdocs.yml

@@ -0,0 +1,60 @@
+site_name: "{{PROJECT}}"
+docs_dir: source
+site_dir: html
+use_directory_urls: false   # lets html/index.html open with a double click (file://)
+
+validation:                 # with update.sh --strict these fail the build instead of passing silently
+  omitted_files: warn       # a page that is not in nav
+  unrecognized_links: warn
+  absolute_links: warn
+
+theme:
+  name: material
+  language: {{LANG}}
+  features:
+    - content.code.copy     # "copy" button on every code block
+    - content.action.edit   # "edit this page" button (needs repo_url + edit_uri, set by install.sh)
+    - navigation.sections
+  palette:                  # light/dark toggle, starts with the reader's OS preference
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-night
+        name: Dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-sunny
+        name: Light mode
+
+plugins:
+  - search
+  - offline   # search works without a server
+
+extra_javascript:
+  - assets/mermaid.min.js   # local copy (downloaded by install.sh): diagrams without internet
+  - assets/diagrams.js
+
+markdown_extensions:
+  - tables
+  - admonition
+  - attr_list
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.snippets:
+      # Embeds REAL repo code on every build:  --8<-- "path/from/repo/root"
+      # Line range:  --8<-- "path:START:END".  The build runs from documentation/.
+      base_path: [".."]
+      check_paths: true      # a moved/deleted file fails the build, naming it
+  - pymdownx.superfences:
+      custom_fences:
+        # class "diagram" (not "mermaid") so Material never tries to load mermaid from the internet
+        - name: mermaid
+          class: diagram
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+nav:
+  - Home: index.md

snapdoczilla_mcp/skill/assets/documentation/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs>=1.6,<2
+mkdocs-material>=9.7,<10

snapdoczilla_mcp/skill/assets/documentation/source/assets/diagrams.js

@@ -0,0 +1,31 @@
+// Turns ```mermaid blocks (rendered as <pre class="diagram">) into SVG diagrams.
+// Uses the local assets/mermaid.min.js: no internet needed. Follows the light/dark toggle.
+(function () {
+  function theme() {
+    return document.body.getAttribute("data-md-color-scheme") === "slate" ? "dark" : "default";
+  }
+  function draw() {
+    if (!window.mermaid) return;
+    document.querySelectorAll("pre.diagram").forEach(function (pre) {
+      var div = document.createElement("div");
+      div.className = "mermaid";
+      div.dataset.source = pre.textContent;
+      pre.replaceWith(div);
+    });
+    var diagrams = document.querySelectorAll("div.mermaid");
+    if (!diagrams.length) return;
+    diagrams.forEach(function (div) {
+      div.removeAttribute("data-processed");
+      div.textContent = div.dataset.source;
+    });
+    window.mermaid.initialize({ startOnLoad: false, theme: theme() });
+    window.mermaid.run({ nodes: diagrams });
+  }
+  function start() {
+    draw();
+    // redraw with the matching theme when the reader toggles light/dark
+    new MutationObserver(draw).observe(document.body, { attributeFilter: ["data-md-color-scheme"] });
+  }
+  if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", start);
+  else start();
+})();

snapdoczilla_mcp/skill/assets/documentation/source/index.md

@@ -0,0 +1,6 @@
+# {{PROJECT}}
+
+> Placeholder created by SnapDoczilla. The agent replaces it with real content.
+
+---
+Last sync: pending

snapdoczilla_mcp/skill/assets/documentation/update.cmd

@@ -0,0 +1,4 @@
+@echo off
+rem Double-click on Windows. Needs Git for Windows (ships bash). Optional args: --<area> --html-only
+bash "%~dp0update.sh" %*
+pause

snapdoczilla_mcp/skill/assets/documentation/update.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# SnapDoczilla: (1) an agent CLI updates documentation/source from the code that changed,
+# (2) the HTML site in documentation/html is rebuilt.
+#   ./documentation/update.sh               -> every area in areas.conf: agent + HTML
+#   ./documentation/update.sh --<area>      -> one area only (e.g. --front)
+#   ./documentation/update.sh --html-only   -> HTML only (after editing .md by hand; no agent)
+# Agent: Claude Code by default. Another one: DOCS_LLM="codex exec --full-auto" | "opencode run" | "gemini --yolo -p"
+# (any non-interactive command that takes the prompt as its last argument).
+set -euo pipefail
+
+DOC_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(git -C "$DOC_DIR" rev-parse --show-toplevel)"
+CONF="$DOC_DIR/areas.conf"
+[ -f "$CONF" ] || { echo "ERROR: missing $CONF"; exit 1; }
+
+# "name=path" lines, without comments or blanks
+LINES="$(grep -v -E '^[[:space:]]*(#|$)' "$CONF")"
+ALL="$(echo "$LINES" | cut -d= -f1)"
+path_of() { echo "$LINES" | grep -E "^$1=" | head -1 | cut -d= -f2-; }
+
+AREAS="$ALL"; HTML_ONLY=0
+for a in "$@"; do
+  if [ "$a" = "--html-only" ]; then HTML_ONLY=1
+  elif echo "$ALL" | grep -qx -- "${a#--}"; then AREAS="${a#--}"
+  else echo "Unknown option: $a (areas: $(echo $ALL | tr '\n' ' '), --html-only)"; exit 1
+  fi
+done
+
+# --- 1. Agent: incremental update since the last documented commit of each area ---
+if [ "$HTML_ONLY" -eq 0 ]; then
+  LLM="${DOCS_LLM:-claude}"
+  command -v "${LLM%% *}" >/dev/null || { echo "ERROR: '${LLM%% *}' not found. Install it, set DOCS_LLM or use --html-only."; exit 1; }
+  for AREA in $AREAS; do
+    AREA_PATH="$(path_of "$AREA")"
+    STATE="$DOC_DIR/.last-sync-$AREA"
+    RULES="documentation/AGENT-RULES.md"
+    [ -f "$DOC_DIR/AGENT-RULES-$AREA.md" ] && RULES="$RULES and documentation/AGENT-RULES-$AREA.md"
+    BASE="$(cat "$STATE" 2>/dev/null || echo "")"
+    if [ -n "$BASE" ]; then
+      SCOPE="Changes since commit $BASE: run 'git diff $BASE..HEAD --stat -- $AREA_PATH :!documentation' and read only the relevant files. Update only the affected pages."
+    else
+      SCOPE="First generation for this area: analyze '$AREA_PATH' fully."
+    fi
+    PROMPT="Follow the rules in $RULES and update documentation/source. Area: $AREA ($AREA_PATH). $SCOPE Edit only documentation/source/ and the nav of documentation/mkdocs.yml."
+    echo ">> Documenting area: $AREA ($AREA_PATH)"
+    if [ -z "${DOCS_LLM:-}" ]; then
+      # Claude Code: tools restricted to documentation/source/
+      (cd "$ROOT" && claude -p "$PROMPT" \
+        --allowedTools "Read,Grep,Glob,Bash(git diff:*),Bash(git log:*),Edit(documentation/source/**),Edit(documentation/mkdocs.yml),Write(documentation/source/**)")
+    else
+      # ponytail: word splitting on purpose (DOCS_LLM = command + flags); review git diff afterwards
+      (cd "$ROOT" && $DOCS_LLM "$PROMPT")
+    fi
+    git -C "$ROOT" rev-parse HEAD > "$STATE"
+  done
+fi
+
+# --- 2. HTML: MkDocs goes into a local venv the first time (system Python untouched) ---
+PY="$(command -v python3 || command -v python || command -v py || true)"
+[ -n "$PY" ] || { echo "ERROR: Python 3 not found."; exit 1; }
+if [ ! -d "$DOC_DIR/.venv" ]; then "$PY" -m venv "$DOC_DIR/.venv"; fi
+VPY="$DOC_DIR/.venv/Scripts/python"; [ -x "$VPY" ] || [ -f "$VPY.exe" ] || VPY="$DOC_DIR/.venv/bin/python"
+"$VPY" -m pip install -q -r "$DOC_DIR/requirements.txt"
+# Built from documentation/ so snippets (base_path "..") resolve from the repo root.
+# Built into a temp dir and swapped in only on success: a failed build never empties html/.
+# --strict (never with -q: -q hides the warnings strict counts): broken links, missing snippets or pages left out of nav fail the build.
+rm -rf "$DOC_DIR/.html-new"
+(cd "$DOC_DIR" && "$VPY" -m mkdocs build --strict -f mkdocs.yml -d .html-new)
+rm -rf "$DOC_DIR/html" && mv "$DOC_DIR/.html-new" "$DOC_DIR/html"
+
+# enable the pre-push reminder (idempotent)
+[ -d "$ROOT/.githooks" ] && git -C "$ROOT" config core.hooksPath .githooks
+
+echo "OK. Open documentation/html/index.html and review 'git status documentation/' before committing."

snapdoczilla_mcp/skill/assets/githooks/pre-push

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# SnapDoczilla: only warns (never blocks the push) when code changed without docs.
+conf=documentation/areas.conf
+[ -f "$conf" ] || exit 0
+grep -v -E '^[[:space:]]*(#|$)' "$conf" | while IFS== read -r area path; do
+  last="$(cat "documentation/.last-sync-$area" 2>/dev/null)" || continue
+  n="$(git rev-list --count "$last"..HEAD -- "$path" ':!documentation' 2>/dev/null || echo 0)"
+  if [ "$n" -gt 0 ]; then
+    echo "Docs reminder ($area): $n commit(s) not documented yet. Run: documentation/update.cmd --$area (or ./documentation/update.sh --$area)" >&2
+  fi
+done
+exit 0

snapdoczilla_mcp/skill/scripts/install.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# SnapDoczilla installer: sets up the offline documentation system in a repo.
+# Usage: install.sh <repo-root> "<Project name>" [language: en|es|...]   (default: en)
+# Never overwrites an existing documentation/mkdocs.yml or .githooks/pre-push.
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REPO="${1:?Usage: install.sh <repo-root> \"<Project name>\" [en|es|...]}"
+NAME="${2:?Missing project name}"
+LANG_CODE="${3:-en}"
+case "$LANG_CODE" in en) LANGUAGE="English" ;; es) LANGUAGE="Spanish (español)" ;; *) LANGUAGE="$LANG_CODE" ;; esac
+DEST="$REPO/documentation"
+
+git -C "$REPO" rev-parse --show-toplevel >/dev/null 2>&1 || { echo "ERROR: $REPO is not a git repository"; exit 1; }
+[ -e "$DEST/mkdocs.yml" ] && { echo "ERROR: $DEST is already set up. Nothing was changed."; exit 1; }
+
+mkdir -p "$DEST" "$REPO/.githooks"
+cp -R "$SKILL_DIR/assets/documentation/." "$DEST/"
+[ -e "$REPO/.githooks/pre-push" ] || cp "$SKILL_DIR/assets/githooks/pre-push" "$REPO/.githooks/pre-push"
+chmod +x "$DEST/update.sh" "$REPO/.githooks/pre-push"
+
+# project name and language into templates (sed without -i: portable across macOS/Linux/Git Bash)
+for f in "$DEST/mkdocs.yml" "$DEST/source/index.md" "$DEST/AGENT-RULES.md"; do
+  sed -e "s|{{PROJECT}}|$NAME|g" -e "s|{{LANG}}|$LANG_CODE|g" -e "s|{{LANGUAGE}}|$LANGUAGE|g" "$f" > "$f.tmp" && mv "$f.tmp" "$f"
+done
+
+# "edit this page" button: derive the web URL from the git remote (GitHub/GitLab; others skipped)
+REMOTE="$(git -C "$REPO" remote get-url origin 2>/dev/null || true)"
+WEB="$(echo "$REMOTE" | sed -E -e 's#^git@([^:]+):#https://\1/#' -e 's#^(https?://)[^@/]+@#\1#' -e 's#\.git$##')"
+BRANCH="$(git -C "$REPO" symbolic-ref --short HEAD 2>/dev/null || echo main)"
+case "$WEB" in
+  https://github.com/*) EDIT="edit/$BRANCH/documentation/source/" ;;
+  https://gitlab.*|https://*gitlab*) EDIT="-/edit/$BRANCH/documentation/source/" ;;
+  *) EDIT="" ;;
+esac
+[ -n "$EDIT" ] && printf '\nrepo_url: %s\nedit_uri: %s\n' "$WEB" "$EDIT" >> "$DEST/mkdocs.yml"
+
+# the local venv and temp build dir are not versioned; the generated HTML is (read with zero setup)
+GI="$REPO/.gitignore"
+grep -qs '^documentation/.venv/' "$GI" || printf '\n# SnapDoczilla: local venv and temp build dir\ndocumentation/.venv/\ndocumentation/.html-new/\n' >> "$GI"
+
+# scripts must keep LF line endings (with CRLF, bash fails on Linux/macOS/Git Bash)
+GA="$REPO/.gitattributes"
+grep -qs 'SnapDoczilla' "$GA" || printf '\n# SnapDoczilla\ndocumentation/*.sh text eol=lf\n.githooks/* text eol=lf\ndocumentation/source/assets/mermaid.min.js -text\n' >> "$GA"
+
+# local Mermaid copy: diagrams render without internet (downloaded once)
+MERMAID="$DEST/source/assets/mermaid.min.js"
+if ! curl -fsSL -o "$MERMAID" "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"; then
+  rm -f "$MERMAID"
+  echo "WARNING: could not download Mermaid. Save https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js as $MERMAID"
+fi
+
+echo "SnapDoczilla installed in $DEST"

snapdoczilla_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: snapdoczilla-mcp
+Version: 1.0.0
+Summary: MCP server for SnapDoczilla: offline docs-as-code (MkDocs + Mermaid) for any backend and frontend, written by your AI agent.
+Project-URL: Homepage, https://github.com/julvc/skills
+Project-URL: Repository, https://github.com/julvc/skills
+Project-URL: Issues, https://github.com/julvc/skills/issues
+Author-email: Julio Varas Contreras <jvarascontreras@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adr,ai-agents,docs-as-code,documentation,mcp,mermaid,mkdocs,model-context-protocol,offline
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2.0
+Description-Content-Type: text/markdown
+
+# SnapDoczilla MCP server
+
+<!-- mcp-name: io.github.julvc/snapdoczilla -->
+
+Offline **docs-as-code** for any backend and any frontend, driven by your AI agent. SnapDoczilla keeps a
+`documentation/` folder inside your repo: a static HTML site (MkDocs Material, local Mermaid diagrams, ADRs,
+API map and component pages with **real code and real usage**) that anyone opens with a double click and any dev
+refreshes with one command.
+
+This MCP server gives your agent the deterministic half of that workflow. **The agent writes the docs from your
+code; the server installs, tracks what changed since the last documented commit, writes pages safely, and builds the site.**
+
+## Install
+
+Needs `uv` (for `uvx`), `git`, and `bash` (on Windows: [Git for Windows](https://git-scm.com)). Building the site
+also needs Python 3 on `PATH`, and internet the first time (MkDocs and Mermaid are downloaded once).
+
+**Claude Code**
+
+```bash
+claude mcp add snapdoczilla -- uvx snapdoczilla-mcp
+```
+
+**Claude Desktop, Cursor and other clients that use `mcpServers` JSON**
+
+```json
+{
+  "mcpServers": {
+    "snapdoczilla": {
+      "command": "uvx",
+      "args": ["snapdoczilla-mcp"]
+    }
+  }
+}
+```
+
+**Codex CLI** (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.snapdoczilla]
+command = "uvx"
+args = ["snapdoczilla-mcp"]
+```
+
+This server does **not** read your source code. Your client does, with its own file tools (Claude Code, Cursor and
+Codex have them; in Claude Desktop add a filesystem server).
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `snapdoczilla_status` | Installed? Areas, commits not yet documented per area, existing pages, next ADR number, suggested next step. Start here. |
+| `snapdoczilla_install` | Scaffolds `documentation/` (templates, update script, pre-push reminder), writes `areas.conf`, downloads Mermaid once. Refuses to touch a `documentation/` it did not create. |
+| `snapdoczilla_get_rules` | Returns the rules the pages must follow (language, never invent, embed real code). |
+| `snapdoczilla_changes_since_sync` | Files, commits and diffstat of an area since its last documented commit, so only affected pages are updated. |
+| `snapdoczilla_write_page` | Creates or overwrites one Markdown page, confined to `documentation/source/`, and adds it to `nav`. |
+| `snapdoczilla_build_html` | Strict MkDocs build into `documentation/html/`. A failed build keeps the previous site. No AI agent is invoked. |
+| `snapdoczilla_mark_synced` | Records HEAD as the last documented commit of an area. |
+
+There is also a prompt, `document_project`, that starts the whole flow.
+
+## Typical use
+
+Ask your agent: *"Document this project"* (or *"update the docs"*). It checks status, installs if needed, reads the
+real code, writes the pages, builds, and marks the areas as synced. It never commits or pushes: you review `git diff`.
+
+## Also available as a plain Agent Skill
+
+The same workflow ships as a [`SKILL.md`](https://github.com/julvc/skills/blob/main/skills/snapdoczilla/SKILL.md)
+for Claude Code, Codex, OpenCode, Gemini CLI and more. See the
+[repository](https://github.com/julvc/skills) for screenshots, the `examples/shop` result and the full documentation.
+
+MIT License.

snapdoczilla_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+snapdoczilla_mcp/__init__.py,sha256=7xJnUoaw8KITZZYJAFOeE8vQv_6H_R7NsXsDu_33TvU,100
+snapdoczilla_mcp/core.py,sha256=zSfQQPqGsN0aMLsxDC7OaEF2Xjrk8Jhqge4TVwzDRTE,16452
+snapdoczilla_mcp/server.py,sha256=fbapdB7wAUcX-NBVLGbUQZ1jpspwCmIneIB7t16Pggg,6890
+snapdoczilla_mcp/skill/SKILL.md,sha256=sR6NCfXPPg7sbbiFpZ_Zds_N2NFr-ANea3pRbmLwoI8,9438
+snapdoczilla_mcp/skill/assets/documentation/AGENT-RULES-COMPONENTS.md,sha256=OaWmq3Ihtto_xPTVcw-kXGafOoqrGw4RkEouH9wp3dc,2098
+snapdoczilla_mcp/skill/assets/documentation/AGENT-RULES.md,sha256=KxEeyuMqHaG5KwBbWl-15TluBkiiio2UcYnoX5ii50I,1901
+snapdoczilla_mcp/skill/assets/documentation/README.md,sha256=u0pOGEgTr8iFg3Thhr3ZMXTuLrSVbu75It7O0-EhwZA,672
+snapdoczilla_mcp/skill/assets/documentation/areas.conf,sha256=wQX9vly1f_Oh4GNUDUqVqEkZYf48m65attD1hX-wQZo,330
+snapdoczilla_mcp/skill/assets/documentation/mkdocs.yml,sha256=eJ7KsssXCmzLBeftLJZ17bw2MwJ3y2Kcy6zXuUPa1RA,1937
+snapdoczilla_mcp/skill/assets/documentation/requirements.txt,sha256=vHu_GuQRZln8BfaLeBl8kQbNPYIhnRTzgZKM3ujlq5I,40
+snapdoczilla_mcp/skill/assets/documentation/update.cmd,sha256=tHqMbSJZq4Xch48Kzx4dswebw8ixiM_UhKlAjbsBylg,142
+snapdoczilla_mcp/skill/assets/documentation/update.sh,sha256=rZH_qp4mM_WrY9ZhmeBEhyICgTyriw4z_-hFi_5YKIA,4080
+snapdoczilla_mcp/skill/assets/documentation/source/index.md,sha256=j2vgL6cGFvBQWOVF0Y4H6sHMlJDhXoUvYp1pDONV-jU,119
+snapdoczilla_mcp/skill/assets/documentation/source/assets/diagrams.js,sha256=6_Zbt-8PWk1mPkoa6Ea8RU0EQx3NZ8i3wsjdnUrzU9M,1272
+snapdoczilla_mcp/skill/assets/githooks/pre-push,sha256=NionJvHfUMk7-4q_FSt1kVQ324i6xW1BNAMsAOwlY_4,593
+snapdoczilla_mcp/skill/scripts/install.sh,sha256=bhFuSbJSoiH_U81vA0f3wZfIKy2oPdkXtur66Q89asY,3011
+snapdoczilla_mcp-1.0.0.dist-info/METADATA,sha256=Xz_mgwsln4UUZRxPTnwAMsxcjQU6fQRYgwnRq97LGvw,4078
+snapdoczilla_mcp-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+snapdoczilla_mcp-1.0.0.dist-info/entry_points.txt,sha256=yQaudz0Vh12GB2N1aXlnXLTFl-7R5ykFKr3814W--kY,66
+snapdoczilla_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=0Eqe_4w7RQ9PGOLFHwTprUB_0tKfjv9Oj0T0uwR5B0I,2014
+snapdoczilla_mcp-1.0.0.dist-info/RECORD,,

snapdoczilla_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

snapdoczilla_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+snapdoczilla-mcp = snapdoczilla_mcp.server:main

snapdoczilla_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+Copyright (c) 2026 Julio Andrés Varas Contreras. All rights reserved.
+
+This software, the source code, and its associated documentation are the exclusive property of the author.
+
+Any copying, reproduction, modification, distribution, publication, sublicensing, and/or sale of this code or any part of it, whether in its original or modified form, for commercial or non-commercial purposes, is strictly prohibited without the prior, express, and written consent of the author.
+
+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 AUTHOR 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.
+
+====================================================================================================================================
+
+Copyright (c) 2026 Julio Andrés Varas Contreras. Todos los derechos reservados.
+
+Este software, el código fuente y su documentación asociada son propiedad exclusiva del autor.
+
+Queda estrictamente prohibida la copia, reproducción, modificación, distribución, publicación, sublicencia y/o venta de este código o cualquier parte del mismo, ya sea en formato original o modificado, con fines comerciales o no comerciales, sin el consentimiento previo, expreso y por escrito del autor.
+
+EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITADO A GARANTÍAS DE COMERCIALIZACIÓN, IDONEIDAD PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO EL AUTOR SERÁ RESPONSABLE DE NINGUNA RECLAMACIÓN, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO TIPO, QUE SURJA DE O EN CONEXIÓN CON EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.