snapdoczilla-mcp 1.0.0__tar.gz

snapdoczilla_mcp-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.html-new/
+__pycache__/
+*.tmp
+
+# Python packaging
+dist/
+build/
+*.egg-info/

snapdoczilla_mcp-1.0.0/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.

snapdoczilla_mcp-1.0.0/PKG-INFO

@@ -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/PYPI.md

@@ -0,0 +1,73 @@
+# 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/examples/shop/api/src/index.js

@@ -0,0 +1,6 @@
+const express = require("express");
+const productos = require("./routes/productos");
+const app = express();
+app.use(express.json());
+app.use("/api/productos", productos);
+app.listen(3000);

snapdoczilla_mcp-1.0.0/examples/shop/api/src/routes/productos.js

@@ -0,0 +1,6 @@
+const router = require("express").Router();
+const db = [];
+router.get("/", (req, res) => res.json(db));
+router.post("/", (req, res) => { db.push(req.body); res.status(201).json(req.body); });
+router.delete("/:id", (req, res) => res.status(204).end());
+module.exports = router;

snapdoczilla_mcp-1.0.0/examples/shop/web/src/components/ProductCard.jsx

@@ -0,0 +1,9 @@
+export default function ProductCard({ nombre, precio, onAgregar }) {
+  return (
+    <div className="card">
+      <h3>{nombre}</h3>
+      <p>${precio}</p>
+      <button onClick={() => onAgregar(nombre)}>Agregar</button>
+    </div>
+  );
+}

snapdoczilla_mcp-1.0.0/examples/shop/web/src/pages/Catalogo.jsx

@@ -0,0 +1,7 @@
+import { useEffect, useState } from "react";
+import ProductCard from "../components/ProductCard";
+export default function Catalogo() {
+  const [productos, setProductos] = useState([]);
+  useEffect(() => { fetch("/api/productos").then(r => r.json()).then(setProductos); }, []);
+  return productos.map(p => <ProductCard key={p.nombre} {...p} onAgregar={n => console.log(n)} />);
+}

snapdoczilla_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "snapdoczilla-mcp"
+dynamic = ["version"]
+description = "MCP server for SnapDoczilla: offline docs-as-code (MkDocs + Mermaid) for any backend and frontend, written by your AI agent."
+readme = "PYPI.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Julio Varas Contreras", email = "jvarascontreras@gmail.com" }]
+keywords = ["mcp", "model-context-protocol", "documentation", "docs-as-code", "mkdocs", "mermaid", "adr", "offline", "ai-agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Documentation",
+]
+dependencies = ["mcp>=2.0,<3"]
+
+[project.scripts]
+snapdoczilla-mcp = "snapdoczilla_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/julvc/skills"
+Repository = "https://github.com/julvc/skills"
+Issues = "https://github.com/julvc/skills/issues"
+
+[tool.hatch.version]
+path = "src/snapdoczilla_mcp/__init__.py"
+
+# The skill folder stays the single source of truth; the wheel carries a copy of it.
+[tool.hatch.build.targets.wheel]
+packages = ["src/snapdoczilla_mcp"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/snapdoczilla" = "snapdoczilla_mcp/skill"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "skills/snapdoczilla", "tests/mcp_smoke.py", "PYPI.md", "LICENSE", "server.json"]

snapdoczilla_mcp-1.0.0/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.julvc/snapdoczilla",
+  "title": "SnapDoczilla",
+  "description": "Offline docs-as-code for any backend and frontend: a MkDocs site in your repo, by your AI agent.",
+  "repository": {
+    "url": "https://github.com/julvc/skills",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "snapdoczilla-mcp",
+      "version": "1.0.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

snapdoczilla_mcp-1.0.0/skills/snapdoczilla/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-1.0.0/skills/snapdoczilla/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-1.0.0/skills/snapdoczilla/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-1.0.0/skills/snapdoczilla/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-1.0.0/skills/snapdoczilla/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-1.0.0/skills/snapdoczilla/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-1.0.0/skills/snapdoczilla/assets/documentation/requirements.txt

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

snapdoczilla_mcp-1.0.0/skills/snapdoczilla/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-1.0.0/skills/snapdoczilla/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-1.0.0/skills/snapdoczilla/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