unifi-network-maps 1.4.11__py3-none-any.whl

unifi_network_maps/render/svg_theme.py

@@ -0,0 +1,64 @@
+"""Shared SVG defs and theming."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SvgTheme:
+    link_standard: tuple[str, str]
+    link_poe: tuple[str, str]
+    node_gateway: tuple[str, str]
+    node_switch: tuple[str, str]
+    node_ap: tuple[str, str]
+    node_client: tuple[str, str]
+    node_other: tuple[str, str]
+
+
+DEFAULT_THEME = SvgTheme(
+    link_standard=("#16a085", "#2ecc71"),
+    link_poe=("#1e88e5", "#42a5f5"),
+    node_gateway=("#ffd199", "#ffb15a"),
+    node_switch=("#bfe4ff", "#8ac6ff"),
+    node_ap=("#c4f2d4", "#8ee3b4"),
+    node_client=("#e4ccff", "#c5a4ff"),
+    node_other=("#e3e3e3", "#cfcfcf"),
+)
+
+
+def svg_defs(prefix: str, theme: SvgTheme = DEFAULT_THEME) -> str:
+    gradient_prefix = f"{prefix}-" if prefix else ""
+    node_prefix = f"{prefix}-node-" if prefix else "node-"
+    return (
+        "<defs>"
+        f'<linearGradient id="{gradient_prefix}link-standard" x1="0%" y1="0%" x2="100%" y2="0%">'
+        f'<stop offset="0%" stop-color="{theme.link_standard[0]}"/>'
+        f'<stop offset="100%" stop-color="{theme.link_standard[1]}"/>'
+        "</linearGradient>"
+        f'<linearGradient id="{gradient_prefix}link-poe" x1="0%" y1="0%" x2="100%" y2="0%">'
+        f'<stop offset="0%" stop-color="{theme.link_poe[0]}"/>'
+        f'<stop offset="100%" stop-color="{theme.link_poe[1]}"/>'
+        "</linearGradient>"
+        f'<linearGradient id="{node_prefix}gateway" x1="0%" y1="0%" x2="100%" y2="100%">'
+        f'<stop offset="0%" stop-color="{theme.node_gateway[0]}"/>'
+        f'<stop offset="100%" stop-color="{theme.node_gateway[1]}"/>'
+        "</linearGradient>"
+        f'<linearGradient id="{node_prefix}switch" x1="0%" y1="0%" x2="100%" y2="100%">'
+        f'<stop offset="0%" stop-color="{theme.node_switch[0]}"/>'
+        f'<stop offset="100%" stop-color="{theme.node_switch[1]}"/>'
+        "</linearGradient>"
+        f'<linearGradient id="{node_prefix}ap" x1="0%" y1="0%" x2="100%" y2="100%">'
+        f'<stop offset="0%" stop-color="{theme.node_ap[0]}"/>'
+        f'<stop offset="100%" stop-color="{theme.node_ap[1]}"/>'
+        "</linearGradient>"
+        f'<linearGradient id="{node_prefix}client" x1="0%" y1="0%" x2="100%" y2="100%">'
+        f'<stop offset="0%" stop-color="{theme.node_client[0]}"/>'
+        f'<stop offset="100%" stop-color="{theme.node_client[1]}"/>'
+        "</linearGradient>"
+        f'<linearGradient id="{node_prefix}other" x1="0%" y1="0%" x2="100%" y2="100%">'
+        f'<stop offset="0%" stop-color="{theme.node_other[0]}"/>'
+        f'<stop offset="100%" stop-color="{theme.node_other[1]}"/>'
+        "</linearGradient>"
+        "</defs>"
+    )

unifi_network_maps/render/templates/device_port_block.md.j2

@@ -0,0 +1,5 @@
+### {{ device_name }}
+
+{{ details }}
+
+{{ ports }}

unifi_network_maps/render/templates/legend_compact.html.j2

@@ -0,0 +1,14 @@
+<table class="unifi-legend-table">
+<tbody>
+{% for row in rows %}
+  <tr><td>
+{% if row.kind == "swatch" %}
+    <span style="display:inline-block;width:12px;height:12px;background:{{ row.fill }};border:1px solid {{ row.stroke }};border-radius:2px;margin-right:6px;"></span>{{ row.label }}
+{% else %}
+    <span style="display:inline-flex;align-items:center;gap:6px;">
+      <svg width="42" height="10" viewBox="0 0 42 10" xmlns="http://www.w3.org/2000/svg" aria-hidden="true"><line x1="2" y1="5" x2="40" y2="5" stroke="{{ row.color }}" stroke-width="{{ row.width }}"{% if row.dashed %} stroke-dasharray="5 4"{% endif %} /></svg>{{ row.label }}{%- if row.bolt %} ⚡{%- endif %}</span>
+{% endif %}
+  </td></tr>
+{% endfor %}
+</tbody>
+</table>

unifi_network_maps/render/templates/lldp_device_section.md.j2

@@ -0,0 +1,15 @@
+## {{ device_name }}
+
+{{ details }}
+{% if ports_section %}
+
+{{ ports_section }}
+{% endif %}
+{% if lldp_section %}
+
+{{ lldp_section }}
+{% endif %}
+{% if clients_section %}
+
+{{ clients_section }}
+{% endif %}

unifi_network_maps/render/templates/markdown_section.md.j2

@@ -0,0 +1,3 @@
+## {{ title }}
+
+{{ body }}

unifi_network_maps/render/templates/mermaid_legend.mmd.j2

@@ -0,0 +1,30 @@
+%%{init: {"flowchart": {"nodeSpacing": {{ node_spacing }}, "rankSpacing": {{ rank_spacing }}}, "themeVariables": {"fontSize": "{{ legend_font_size }}px", "nodePadding": {{ node_padding }}}}}%%
+graph TB
+  subgraph legend["Legend"];
+    legend_gateway["Gateway"];
+    legend_switch["Switch"];
+    legend_ap["AP"];
+    legend_client["Client"];
+    legend_other["Other"];
+    legend_poe_a["PoE Link A"];
+    legend_poe_b["PoE Link B"];
+    legend_no_poe_a["Link A"];
+    legend_no_poe_b["Link B"];
+    legend_poe_a ---|⚡| legend_poe_b;
+    legend_no_poe_a --- legend_no_poe_b;
+    linkStyle 0 arrowhead:none;
+    linkStyle 1 arrowhead:none;
+  end
+  class legend_gateway node_gateway;
+  class legend_switch node_switch;
+  class legend_ap node_ap;
+  class legend_client node_client;
+  class legend_other node_other;
+  class legend_poe_a node_legend;
+  class legend_poe_b node_legend;
+  class legend_no_poe_a node_legend;
+  class legend_no_poe_b node_legend;
+{{ class_defs }}
+  classDef node_legend font-size:{{ legend_font_size }}px;
+  linkStyle 0 stroke:{{ poe_link }},stroke-width:{{ poe_link_width }}px,arrowhead:{{ poe_link_arrow }};
+  linkStyle 1 stroke:{{ standard_link }},stroke-width:{{ standard_link_width }}px,arrowhead:{{ standard_link_arrow }};

unifi_network_maps/render/templates/mkdocs_document.md.j2

@@ -0,0 +1,23 @@
+# {{ title }}
+
+{% if timestamp_line -%}
+{{ timestamp_line }}
+
+{% endif -%}
+{% if dual_style -%}
+{{ dual_style }}{% endif -%}
+{% set title = "Map" %}
+{% set body = map_block %}
+{% include "markdown_section.md.j2" %}
+
+{% if legend_title -%}
+{% set title = legend_title %}
+{% set body = legend_block %}
+{% include "markdown_section.md.j2" %}
+
+{% else -%}
+{{ legend_block }}
+
+{% endif -%}
+
+{{ device_overview }}

unifi_network_maps/render/templates/mkdocs_dual_theme_style.html.j2

@@ -0,0 +1,8 @@
+<style>
+.unifi-mermaid--light,.unifi-legend--light{display:none;}
+.unifi-mermaid--dark,.unifi-legend--dark{display:none;}
+[data-md-color-scheme="default"] .unifi-mermaid--light{display:block;}
+[data-md-color-scheme="default"] .unifi-legend--light{display:block;}
+[data-md-color-scheme="slate"] .unifi-mermaid--dark{display:block;}
+[data-md-color-scheme="slate"] .unifi-legend--dark{display:block;}
+</style>

unifi_network_maps/render/templates/mkdocs_html_block.html.j2

@@ -0,0 +1,2 @@
+<div class="{{ class_name }}"{% if data_unifi_legend %} data-unifi-legend{% endif %}>
+{{ content | safe }}</div>

unifi_network_maps/render/templates/mkdocs_legend.css.j2

@@ -0,0 +1,29 @@
+.unifi-legend-hidden,
+.unifi-legend-hidden.unifi-legend,
+.unifi-legend-hidden.unifi-legend--light,
+.unifi-legend-hidden.unifi-legend--dark {
+  display: none !important;
+}
+.unifi-legend-sidebar {
+  margin-top: 1rem;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid rgba(0, 0, 0, 0.08);
+  border-radius: 6px;
+  font-size: 0.75rem;
+}
+.unifi-legend-title {
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}
+.unifi-legend-sidebar table {
+  width: 100%;
+  border-collapse: collapse;
+}
+.unifi-legend-sidebar td,
+.unifi-legend-sidebar th {
+  border: 0;
+  padding: 0.15rem 0;
+}
+.unifi-legend-sidebar svg {
+  display: block;
+}

unifi_network_maps/render/templates/mkdocs_legend.js.j2

@@ -0,0 +1,18 @@
+document.addEventListener("DOMContentLoaded", () => {
+  const legends = document.querySelectorAll("[data-unifi-legend]");
+  const sidebar = document.querySelector(".md-sidebar--secondary .md-sidebar__scrollwrap");
+  if (!legends.length || !sidebar) {
+    return;
+  }
+  const wrapper = document.createElement("div");
+  wrapper.className = "unifi-legend-sidebar";
+  const title = document.createElement("div");
+  title.className = "unifi-legend-title";
+  title.textContent = "Legend";
+  wrapper.appendChild(title);
+  legends.forEach((legend) => {
+    wrapper.appendChild(legend.cloneNode(true));
+    legend.classList.add("unifi-legend-hidden");
+  });
+  sidebar.appendChild(wrapper);
+});

unifi_network_maps/render/templates/mkdocs_mermaid_block.md.j2

@@ -0,0 +1,4 @@
+<div class="{{ class_name }}">
+```mermaid
+{{ content }}```
+</div>

unifi_network_maps/render/templating.py

@@ -0,0 +1,19 @@
+"""Jinja2 helpers for Markdown/HTML rendering."""
+
+from __future__ import annotations
+
+from jinja2 import Environment, PackageLoader, StrictUndefined, select_autoescape
+
+_ENV = Environment(
+    loader=PackageLoader("unifi_network_maps.render", "templates"),
+    autoescape=select_autoescape(enabled_extensions=("html", "xml")),
+    trim_blocks=True,
+    lstrip_blocks=True,
+    keep_trailing_newline=True,
+    undefined=StrictUndefined,
+)
+
+
+def render_template(name: str, **context: object) -> str:
+    template = _ENV.get_template(name)
+    return template.render(**context)

unifi_network_maps/render/theme.py

@@ -0,0 +1,109 @@
+"""Theme loading for Mermaid and SVG rendering."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from .mermaid_theme import DEFAULT_THEME as DEFAULT_MERMAID_THEME
+from .mermaid_theme import MermaidTheme
+from .svg_theme import DEFAULT_THEME as DEFAULT_SVG_THEME
+from .svg_theme import SvgTheme
+
+
+def _coerce_pair(value: object, default: tuple[str, str]) -> tuple[str, str]:
+    if isinstance(value, list | tuple) and len(value) == 2:
+        left, right = value
+        if isinstance(left, str) and isinstance(right, str):
+            return (left, right)
+    if isinstance(value, dict):
+        left = value.get("from") or value.get("start")
+        right = value.get("to") or value.get("end")
+        if isinstance(left, str) and isinstance(right, str):
+            return (left, right)
+    return default
+
+
+def _coerce_color(value: object, default: str) -> str:
+    return value if isinstance(value, str) else default
+
+
+def _coerce_optional_color(value: object, default: str | None) -> str | None:
+    return value if isinstance(value, str) else default
+
+
+def _coerce_optional_int(value: object, default: int | None) -> int | None:
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    return default
+
+
+def _mermaid_theme_from_dict(data: dict, base: MermaidTheme) -> MermaidTheme:
+    nodes = data.get("nodes", {}) if isinstance(data.get("nodes"), dict) else {}
+
+    def _node(name: str) -> tuple[str, str]:
+        return (
+            _coerce_color(nodes.get(name, {}).get("fill"), getattr(base, f"node_{name}")[0]),
+            _coerce_color(nodes.get(name, {}).get("stroke"), getattr(base, f"node_{name}")[1]),
+        )
+
+    return MermaidTheme(
+        node_gateway=_node("gateway"),
+        node_switch=_node("switch"),
+        node_ap=_node("ap"),
+        node_client=_node("client"),
+        node_other=_node("other"),
+        poe_link=_coerce_color(data.get("poe_link"), base.poe_link),
+        poe_link_width=int(data.get("poe_link_width", base.poe_link_width)),
+        poe_link_arrow=_coerce_color(data.get("poe_link_arrow"), base.poe_link_arrow),
+        standard_link=_coerce_color(data.get("standard_link"), base.standard_link),
+        standard_link_width=int(data.get("standard_link_width", base.standard_link_width)),
+        standard_link_arrow=_coerce_color(
+            data.get("standard_link_arrow"), base.standard_link_arrow
+        ),
+        node_text=_coerce_optional_color(data.get("node_text"), base.node_text),
+        edge_label_border=_coerce_optional_color(
+            data.get("edge_label_border"), base.edge_label_border
+        ),
+        edge_label_border_width=_coerce_optional_int(
+            data.get("edge_label_border_width"), base.edge_label_border_width
+        ),
+    )
+
+
+def _svg_theme_from_dict(data: dict, base: SvgTheme) -> SvgTheme:
+    nodes = data.get("nodes", {}) if isinstance(data.get("nodes"), dict) else {}
+    links = data.get("links", {}) if isinstance(data.get("links"), dict) else {}
+
+    return SvgTheme(
+        link_standard=_coerce_pair(links.get("standard"), base.link_standard),
+        link_poe=_coerce_pair(links.get("poe"), base.link_poe),
+        node_gateway=_coerce_pair(nodes.get("gateway"), base.node_gateway),
+        node_switch=_coerce_pair(nodes.get("switch"), base.node_switch),
+        node_ap=_coerce_pair(nodes.get("ap"), base.node_ap),
+        node_client=_coerce_pair(nodes.get("client"), base.node_client),
+        node_other=_coerce_pair(nodes.get("other"), base.node_other),
+    )
+
+
+def load_theme(path: str | Path) -> tuple[MermaidTheme, SvgTheme]:
+    theme_path = Path(path)
+    payload = yaml.safe_load(theme_path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("Theme file must contain a YAML mapping")
+
+    mermaid_data = payload.get("mermaid", {})
+    svg_data = payload.get("svg", {})
+
+    mermaid_theme = _mermaid_theme_from_dict(mermaid_data, DEFAULT_MERMAID_THEME)
+    svg_theme = _svg_theme_from_dict(svg_data, DEFAULT_SVG_THEME)
+    return mermaid_theme, svg_theme
+
+
+def resolve_themes(theme_file: str | Path | None) -> tuple[MermaidTheme, SvgTheme]:
+    if theme_file:
+        return load_theme(theme_file)
+    return DEFAULT_MERMAID_THEME, DEFAULT_SVG_THEME

unifi_network_maps-1.4.11.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: unifi-network-maps
+Version: 1.4.11
+Summary: Dynamic UniFi -> network maps in mermaid or svg
+Author: Merlijn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/merlijntishauser/unifi-network-maps
+Project-URL: Repository, https://github.com/merlijntishauser/unifi-network-maps
+Project-URL: Issues, https://github.com/merlijntishauser/unifi-network-maps/issues
+Project-URL: Changelog, https://github.com/merlijntishauser/unifi-network-maps/blob/main/CHANGELOG.md
+Keywords: unifi,mermaid,network,topology,diagram,svg
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: unifi-controller-api==0.3.2
+Requires-Dist: python-dotenv==1.2.1
+Requires-Dist: PyYAML==6.0.3
+Requires-Dist: Jinja2==3.1.6
+Provides-Extra: dev
+Requires-Dist: Faker==40.1.2; extra == "dev"
+Requires-Dist: behave==1.3.3; extra == "dev"
+Requires-Dist: pre-commit==4.5.1; extra == "dev"
+Requires-Dist: pytest==9.0.2; extra == "dev"
+Requires-Dist: pytest-cov==7.0.0; extra == "dev"
+Requires-Dist: pyright==1.1.408; extra == "dev"
+Requires-Dist: ruff==0.14.13; extra == "dev"
+Dynamic: license-file
+
+# unifi-network-maps
+
+[![CI](https://github.com/merlijntishauser/unifi-network-maps/actions/workflows/ci.yml/badge.svg)](https://github.com/merlijntishauser/unifi-network-maps/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/merlijntishauser/unifi-network-maps/actions/workflows/codeql.yml/badge.svg)](https://github.com/merlijntishauser/unifi-network-maps/actions/workflows/codeql.yml)
+[![Publish](https://github.com/merlijntishauser/unifi-network-maps/actions/workflows/publish.yml/badge.svg)](https://github.com/merlijntishauser/unifi-network-maps/actions/workflows/publish.yml)
+[![PyPI](https://img.shields.io/pypi/v/unifi-network-maps.svg)](https://pypi.org/project/unifi-network-maps/)
+
+Dynamic UniFi network maps generated from LLDP topology. Output can be a range of options including Markdown,
+Mermaid, SVG (including an Isometric view), and MkDocs.
+
+Python 3.12+ is supported (3.13 preferred).
+
+## Installation
+
+PyPI:
+
+```bash
+pip install unifi-network-maps
+```
+
+From source:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements-build.txt
+pip install .
+```
+
+## Configuration
+
+Set environment variables (no secrets in code). The CLI loads `.env` automatically if present:
+
+```bash
+export UNIFI_URL=https://192.168.1.1
+export UNIFI_SITE=default
+export UNIFI_USER=local_admin
+export UNIFI_PASS=********
+export UNIFI_VERIFY_SSL=false
+export UNIFI_REQUEST_TIMEOUT_SECONDS=10
+```
+
+Use a custom env file:
+
+```bash
+unifi-network-maps --env-file ./site.env --stdout
+```
+
+## Quickstart
+
+Basic map (tree layout by LLDP hops):
+
+```bash
+unifi-network-maps --stdout
+```
+
+Write Markdown for notes tools:
+
+```bash
+unifi-network-maps --markdown --output ./network.md
+```
+
+## Usage
+
+Show ports + clients:
+
+```bash
+unifi-network-maps --include-ports --include-clients --stdout
+```
+
+SVG output (orthogonal layout + icons):
+
+```bash
+unifi-network-maps --format svg --output ./network.svg
+```
+
+Isometric SVG output:
+
+```bash
+unifi-network-maps --format svg-iso --output ./network.svg
+```
+
+MkDocs output (ports included, no clients):
+
+```bash
+unifi-network-maps --format mkdocs --output ./docs/unifi-network.md
+```
+
+MkDocs output with clients:
+
+```bash
+unifi-network-maps --format mkdocs --include-clients --output ./docs/unifi-network.md
+```
+
+MkDocs output with dual Mermaid blocks for Material theme switching:
+
+```bash
+unifi-network-maps --format mkdocs --mkdocs-dual-theme --output ./docs/unifi-network.md
+```
+
+LLDP tables for troubleshooting:
+
+```bash
+unifi-network-maps --format lldp-md --output ./lldp.md
+```
+
+Legend only:
+
+```bash
+unifi-network-maps --legend-only --stdout
+```
+
+## Home Assistant integration
+
+The live Home Assistant integration (Config Flow + coordinator + custom card) lives in a separate repo:
+- https://github.com/merlijntishauser/unifi-network-maps-ha
+
+## Examples (mock data)
+
+These examples are generated from `examples/mock_data.json` (safe, anonymized fixture).
+Mock generation requires dev dependencies (`pip install -r requirements-dev.txt -c constraints.txt`).
+Regenerate the fixture + SVG with `make mock-data`.
+
+Generate mock data (dev-only, uses Faker):
+
+```bash
+unifi-network-maps --generate-mock examples/mock_data.json --mock-seed 1337
+```
+
+Generate the isometric SVG:
+
+```bash
+unifi-network-maps --mock-data examples/mock_data.json   --include-ports --include-clients --format svg-iso   --output examples/output/network_ports_clients_iso.svg
+```
+
+![Isometric network example](examples/output/network_ports_clients_iso.svg)
+
+Mermaid example with ports:
+
+```mermaid
+graph TB
+  core_switch["Core Switch"] ---|"Core Switch: Port 7 (AP Attic) <-> AP Attic: Port 1 (Core Switch)"| ap_attic["AP Attic"];
+  core_switch["Core Switch"] ---|"Core Switch: Port 3 (AP Living Room) <-> AP Living Room: Port 1 (Core Switch)"| ap_living_room["AP Living Room"];
+  cloud_gateway["Cloud Gateway"] ---|"Cloud Gateway: Port 9 (Core Switch) <-> Core Switch: Port 1 (Cloud Gateway)"| core_switch["Core Switch"];
+  class cloud_gateway node_gateway;
+  class core_switch node_switch;
+  class ap_living_room node_ap;
+  class ap_attic node_ap;
+  classDef node_gateway fill:#ffe3b3,stroke:#d98300,stroke-width:1px;
+  classDef node_switch fill:#d6ecff,stroke:#3a7bd5,stroke-width:1px;
+  classDef node_ap fill:#d7f5e7,stroke:#27ae60,stroke-width:1px;
+  classDef node_client fill:#f2e5ff,stroke:#7f3fbf,stroke-width:1px;
+  classDef node_other fill:#eeeeee,stroke:#8f8f8f,stroke-width:1px;
+  classDef node_legend font-size:10px;
+  linkStyle 0 stroke:#1e88e5,stroke-width:2px,arrowhead:none;
+  linkStyle 1 stroke:#1e88e5,stroke-width:2px,arrowhead:none;
+```
+
+## MkDocs Material example
+
+See `examples/mkdocs/` for a ready-to-use setup that renders Mermaid diagrams
+with Material for MkDocs, including a sample `unifi-network` page and legend.
+
+The built-in themes live at `src/unifi_network_maps/assets/themes/default.yaml` and
+`src/unifi_network_maps/assets/themes/dark.yaml`.
+
+
+## Options
+
+The CLI groups options by category (`Source`, `Functional`, `Mermaid`, `SVG`, `Output`, `Debug`).
+
+Source:
+- `--site`: override `UNIFI_SITE`.
+- `--env-file`: load environment variables from a specific `.env` file.
+- `--mock-data`: use mock data JSON instead of the UniFi API.
+
+Mock:
+- `--generate-mock`: write mock data JSON and exit.
+- `--mock-seed`: seed for deterministic mock generation.
+- `--mock-switches`: number of switches to generate.
+- `--mock-aps`: number of access points to generate.
+- `--mock-wired-clients`: number of wired clients to generate.
+- `--mock-wireless-clients`: number of wireless clients to generate.
+
+Functional:
+- `--include-ports`: show port labels (Mermaid shows both ends; SVG shows compact labels).
+- `--include-clients`: add active wired clients as leaf nodes.
+- `--client-scope wired|wireless|all`: which client types to include (default wired).
+- `--only-unifi`: only include neighbors that are UniFi devices.
+- `--no-cache`: disable UniFi API cache reads and writes.
+
+Mermaid:
+- `--direction LR|TB`: diagram direction for Mermaid (default TB).
+- `--group-by-type`: group nodes by gateway/switch/AP in Mermaid subgraphs.
+- `--legend-scale`: scale legend font/link sizes for Mermaid outputs (default 1.0).
+- `--legend-style auto|compact|diagram`: legend rendering mode (auto uses compact for mkdocs).
+- `--legend-only`: render just the legend as a separate Mermaid graph (Mermaid only).
+
+SVG:
+- `--svg-width/--svg-height`: override SVG output dimensions.
+- `--theme-file`: load a YAML theme for Mermaid + SVG colors (see `examples/theme.yaml` and `examples/theme-dark.yaml`).
+
+Output:
+- `--format mermaid|svg|svg-iso|lldp-md|mkdocs`: output format (default mermaid).
+- `--stdout`: write output to stdout.
+- `--markdown`: wrap Mermaid output in a code fence.
+- `--mkdocs-sidebar-legend`: write assets to place the compact legend in the MkDocs right sidebar.
+- `--mkdocs-dual-theme`: render light/dark Mermaid blocks for Material theme switching.
+- `--mkdocs-timestamp-zone`: timezone for mkdocs timestamp (`Europe/Amsterdam` default; use `off` to disable).
+
+Debug:
+- `--debug-dump`: dump gateway + sample devices to stderr for debugging.
+- `--debug-sample N`: number of non-gateway devices in debug dump (default 2).
+
+## Theme file
+
+Example theme YAML (override only the values you want):
+
+```yaml
+mermaid:
+  nodes:
+    gateway:
+      fill: "#ffe3b3"
+      stroke: "#d98300"
+  poe_link: "#1e88e5"
+svg:
+  links:
+    standard:
+      from: "#2ecc71"
+      to: "#1b8f4a"
+    poe:
+      from: "#1e88e5"
+      to: "#0d47a1"
+  nodes:
+    switch:
+      from: "#d6ecff"
+      to: "#b6dcff"
+```
+
+## Notes
+
+- Default output is top-to-bottom (TB) and rendered as a hop-based tree from the gateway(s).
+- Nodes are color-coded by type (gateway/switch/AP/client) with a sensible default palette.
+- PoE links are highlighted in blue and annotated with a power icon when detected from `port_table`.
+- Wireless client links render as dashed lines to indicate the last-known upstream.
+- SVG output uses vendored device glyphs from `src/unifi_network_maps/assets/icons`.
+- Isometric SVG output uses MIT-licensed icons from `markmanx/isopacks`.
+- SVG port labels render inside child nodes for readability.
+
+
+## AI Disclosure
+
+This project used OpenAI Codex as a coding assistant for portions of the implementation and documentation.