ui-design-workbench-cli 0.5.0__py3-none-any.whl

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/uidw_mcp.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""Optional local stdio MCP facade over the deterministic UIDW CLI core."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+import uidw
+from native_render_registry import native_render_status
+from scoped_context import apply_patch_file, build_scoped_context
+
+
+SERVER_INSTRUCTIONS = (
+    "Start with ui_project, then call ui_scope for one screen or a small finding set. "
+    "If ui_project returns setupRequired, ask the user only for low, medium, or high, then call "
+    "ui_configure with that choice before continuing. "
+    "Do not request or embed the complete UI IR when bounded context is sufficient. "
+    "Use ui_prepare_job for review, proposal, or implementation handoffs. Review and proposal work "
+    "must preserve immutable baseline UI and return sparse ui-ir.patch.json operations; application "
+    "source changes require an explicit implementation request. Use ui_build_preview for projection "
+    "checks only; do not infer UI/UX findings unless the user explicitly requests a review. "
+    "For Android or Apple visual accuracy, call ui_native_status and never describe source projection as a native render. "
+    "Native builds, simulators, and captures are explicit-only operations."
+)
+
+
+def _root(value: str | None, default: Path) -> Path:
+    path = Path(value).expanduser().resolve() if value else default.resolve()
+    if not path.is_dir():
+        raise ValueError(f"Repository directory does not exist: {path}")
+    return path
+
+
+def _ir(root: Path, value: str | None) -> tuple[Path, dict[str, Any]]:
+    return uidw.load_ir_argument(uidw.state_paths(root), Path(value).expanduser() if value else None)
+
+
+def project_summary(repo: str | None, default_repo: Path) -> dict[str, Any]:
+    root = _root(repo, default_repo)
+    initialization, paths, config = uidw.ensure_initialized(root)
+    ir = uidw.load_project_ir(paths) or {}
+    configuration = uidw.configuration_context(config)
+    setup_required = bool(configuration.get("setupRequired"))
+    return {
+        "status": initialization.get("status"),
+        "cache": initialization.get("initialization", {}).get("status"),
+        "repoRoot": str(root),
+        "uiIrFile": str(paths["ir"]),
+        "contextFile": str(paths["context"]),
+        "screens": [{"id": item.get("id"), "name": item.get("name"), "platform": item.get("platform")} for item in ir.get("screens", [])],
+        "findingCount": len(ir.get("review", {}).get("audit", {}).get("findings", [])),
+        "setupRequired": setup_required,
+        "detailLevel": configuration.get("detailLevel"),
+        "detailChoices": ["low", "medium", "high"] if setup_required else [],
+        "questionsForUser": configuration.get("questionsForUser", []),
+        "uiModeEnabled": bool(config.get(uidw.UI_MODE_KEY, {}).get("enabled")),
+        "next": (
+            "Ask the user to choose low, medium, or high, then call ui_configure."
+            if setup_required
+            else "Use ui_scope for one screen or a small finding set; do not read the full IR."
+        ),
+    }
+
+
+def scoped_payload(
+    repo: str | None,
+    default_repo: Path,
+    ui_ir_file: str | None,
+    screen_ids: list[str],
+    finding_ids: list[str],
+    max_tokens: int,
+) -> dict[str, Any]:
+    root = _root(repo, default_repo)
+    ir_path, ir = _ir(root, ui_ir_file)
+    return build_scoped_context(
+        ir,
+        screen_ids=screen_ids,
+        finding_ids=finding_ids,
+        token_budget=max_tokens,
+        ui_ir_file=str(ir_path),
+    )
+
+
+def compact_workbench_result(result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        key: result.get(key)
+        for key in ("version", "status", "previewFile", "url", "workflow", "initialization")
+        if result.get(key) is not None
+    }
+
+
+def configure_detail(repo: str | None, default_repo: Path, detail: str) -> dict[str, Any]:
+    root = _root(repo, default_repo)
+    normalized = detail.strip().lower()
+    if normalized not in {"low", "medium", "high"}:
+        return {
+            "status": "blocked",
+            "error": "detail must be low, medium, or high",
+            "detailChoices": ["low", "medium", "high"],
+        }
+    result = uidw.configure_project(root, "set", "detail", normalized)
+    configuration = result.get("configuration", {})
+    return {
+        "status": result.get("status"),
+        "repoRoot": result.get("repoRoot"),
+        "setupRequired": bool(configuration.get("setupRequired")),
+        "detailLevel": configuration.get("detailLevel"),
+        "mockData": configuration.get(uidw.MOCK_DATA_KEY),
+        "contextFile": result.get("contextFile"),
+        "next": "Use ui_scope, then ui_build_preview when the requested screens are ready.",
+    }
+
+
+def build_preview(
+    repo: str | None,
+    default_repo: Path,
+    ui_ir_file: str | None,
+    output_dir: str | None,
+    level: str,
+) -> dict[str, Any]:
+    root = _root(repo, default_repo)
+    paths = uidw.state_paths(root)
+    configuration = uidw.configuration_context(uidw.load_config(paths["config"]))
+    if configuration.get("setupRequired"):
+        return {
+            "status": "needs-setup",
+            "setupRequired": True,
+            "detailChoices": ["low", "medium", "high"],
+            "questionsForUser": configuration.get("questionsForUser", []),
+            "next": "Ask the user to choose low, medium, or high, then call ui_configure.",
+        }
+
+    ir_path, _ = _ir(root, ui_ir_file)
+    destination = Path(output_dir).expanduser().resolve() if output_dir else ir_path.parent / "workbench"
+    cached_ir = paths["ir"].resolve()
+    allow_draft = ir_path.resolve() == cached_ir
+    try:
+        result = uidw.build_workbench(
+            root,
+            ir_path,
+            destination,
+            level,
+            allow_draft,
+            "generic",
+            False,
+            None,
+            None,
+            None,
+            None,
+            None,
+        )
+    except (RuntimeError, ValueError, OSError) as exc:
+        return {
+            "status": "blocked",
+            "error": str(exc),
+            "uiIrFile": str(ir_path),
+            "next": "Resolve the reported IR or fidelity problem, then call ui_build_preview again.",
+        }
+    return compact_workbench_result(result)
+
+
+def create_server(default_repo: Path, name: str = "UI Design Workbench") -> Any:
+    try:
+        from mcp.server import MCPServer
+    except ImportError as exc:
+        raise RuntimeError(
+            "MCP support is optional. Install it with `pip install \"ui-design-workbench-cli[mcp]\"` "
+            "or `pip install \"mcp>=2,<3\"`. The regular uidw CLI does not require it."
+        ) from exc
+
+    server = MCPServer(
+        name,
+        version=uidw.CLI_VERSION,
+        instructions=SERVER_INSTRUCTIONS,
+    )
+
+    @server.tool()
+    def ui_project(repo: str = "") -> dict[str, Any]:
+        """Get a compact cached UI catalog and the next bounded action."""
+        return project_summary(repo or None, default_repo)
+
+    @server.tool()
+    def ui_configure(detail: str, repo: str = "") -> dict[str, Any]:
+        """Set the required low, medium, or high preview detail after the user chooses it."""
+        return configure_detail(repo or None, default_repo, detail)
+
+    @server.tool()
+    def ui_scope(
+        screen_ids: list[str],
+        finding_ids: list[str],
+        repo: str = "",
+        ui_ir_file: str = "",
+        max_tokens: int = 4000,
+    ) -> dict[str, Any]:
+        """Read complete UI evidence only for named screens/findings."""
+        return scoped_payload(repo or None, default_repo, ui_ir_file or None, screen_ids, finding_ids, max_tokens)
+
+    @server.tool()
+    def ui_prepare_job(
+        kind: str,
+        finding_ids: list[str],
+        repo: str = "",
+        ui_ir_file: str = "",
+        output_file: str = "",
+        scope: str = "current",
+        direct: bool = False,
+    ) -> dict[str, Any]:
+        """Prepare a portable bounded job plus context and ui-ir.patch.json."""
+        root = _root(repo or None, default_repo)
+        ir_path, ir = _ir(root, ui_ir_file or None)
+        if kind not in {"expert", "proposal", "implementation"}:
+            raise ValueError("kind must be expert, proposal, or implementation")
+        output = Path(output_file).expanduser().resolve() if output_file else ir_path.parent / f"ui-agent-job-{kind}.json"
+        return uidw.prepare_agent_job(root, ir_path, ir, kind, output, identifiers=finding_ids, scope=scope, direct=direct)
+
+    @server.tool()
+    def ui_apply_patch(
+        patch_file: str,
+        repo: str = "",
+        ui_ir_file: str = "",
+        output_file: str = "",
+    ) -> dict[str, Any]:
+        """Validate and apply sparse review/proposal operations without touching baseline UI."""
+        root = _root(repo or None, default_repo)
+        ir_path, _ = _ir(root, ui_ir_file or None)
+        output = Path(output_file).expanduser().resolve() if output_file else ir_path.with_name("ui-ir.patched.json")
+        return apply_patch_file(ir_path, Path(patch_file).expanduser(), output)
+
+    @server.tool()
+    def ui_build_preview(
+        repo: str = "",
+        ui_ir_file: str = "",
+        output_dir: str = "",
+        level: str = "quick",
+    ) -> dict[str, Any]:
+        """Render and projection-check the HTML workbench; never auto-review UX."""
+        return build_preview(repo or None, default_repo, ui_ir_file or None, output_dir or None, level)
+
+    @server.tool()
+    def ui_native_status(repo: str = "", platform: str = "all") -> dict[str, Any]:
+        """Discover native Android/Apple render providers without executing builds or simulators."""
+        if platform not in {"all", "android", "apple"}:
+            raise ValueError("platform must be all, android, or apple")
+        root = _root(repo or None, default_repo)
+        return native_render_status(root, uidw.state_paths(root)["native"], platform)
+
+    @server.tool()
+    def ui_fidelity(identifier: str, repo: str = "", ui_ir_file: str = "") -> dict[str, Any]:
+        """Explain one node/evidence id without returning the complete IR."""
+        root = _root(repo or None, default_repo)
+        _, ir = _ir(root, ui_ir_file or None)
+        return uidw.fidelity_command(ir, "explain", identifier, None, "json")
+
+    return server
+
+
+def run_server(default_repo: Path, name: str = "UI Design Workbench") -> None:
+    create_server(default_repo, name).run()
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Local stdio MCP server for UI Design Workbench")
+    parser.add_argument("--repo", type=Path, default=Path.cwd())
+    parser.add_argument("--name", default="UI Design Workbench")
+    return parser.parse_args(argv)
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        run_server(args.repo.resolve(), args.name)
+    except (RuntimeError, ValueError, OSError) as exc:
+        print(f"uidw mcp: {exc}", file=sys.stderr)
+        return 3
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/validate_platform_profiles.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Validate platform-profile selection and node standard references in UI IR."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+from quality_common import framework_adapters, node_screen_map, platform_family, profile_catalog, read_json, target_families, write_json
+
+
+def validate_profiles(ir: dict[str, Any]) -> dict[str, Any]:
+    catalog = profile_catalog()
+    profiles = catalog.get("profiles", {})
+    adapters = catalog.get("frameworkAdapters", {})
+    families = target_families(ir)
+    selected = ir.get("design", {}).get("standardProfiles", {})
+    issues: list[dict[str, Any]] = []
+    resolved: dict[str, Any] = {}
+
+    if not families:
+        supported = ", ".join(sorted({str(item.get("family")) for item in profiles.values() if isinstance(item, dict) and item.get("family")}))
+        issues.append({"code": "target-platform-missing", "severity": "error", "message": f"design.targetPlatforms must resolve to a supported family: {supported}."})
+
+    for adapter_id in sorted(framework_adapters(ir)):
+        adapter = adapters[adapter_id]
+        if adapter.get("requiresExplicitTarget") and not ir.get("design", {}).get("targetPlatforms"):
+            issues.append({"code": "framework-target-ambiguous", "severity": "error", "adapter": adapter_id, "message": f"{adapter_id} requires explicit design.targetPlatforms."})
+
+    for family in sorted(families):
+        selection = selected.get(family)
+        if not isinstance(selection, dict):
+            issues.append({"code": "profile-missing", "severity": "error", "family": family, "message": f"Missing design.standardProfiles.{family}."})
+            continue
+        profile_id = selection.get("id")
+        if profile_id == "project":
+            if not selection.get("reason"):
+                issues.append({"code": "project-profile-unreasoned", "severity": "error", "family": family, "message": "A project profile needs a reason and evidence."})
+            else:
+                resolved[family] = {**selection, "family": family, "standardRefPrefixes": ["project."]}
+            continue
+        profile = profiles.get(profile_id)
+        if not profile or profile.get("family") != family:
+            issues.append({"code": "profile-invalid", "severity": "error", "family": family, "profile": profile_id, "message": f"Profile {profile_id!r} does not belong to {family}."})
+            continue
+        resolved[family] = {**profile, "id": profile_id, "source": selection.get("source")}
+
+    decisions = {item.get("id") for item in ir.get("design", {}).get("decisions", []) if isinstance(item, dict)}
+    screen_families = {str(screen.get("id")): platform_family(screen.get("platform")) for screen in ir.get("screens", [])}
+    node_screens = node_screen_map(ir)
+    for node_id, node in ir.get("nodes", {}).items():
+        if node.get("type") == "spacer" or node.get("decisionId") in decisions:
+            continue
+        shared = str(node.get("standardRef", ""))
+        per_platform = node.get("standardRefs", {}) if isinstance(node.get("standardRefs"), dict) else {}
+        node_families = {screen_families.get(screen_id) for screen_id in node_screens.get(str(node_id), set())}
+        node_families.discard(None)
+        node_families = node_families or families
+        for family in sorted(node_families):
+            profile = resolved.get(family)
+            if not profile:
+                continue
+            ref = str(per_platform.get(family, shared))
+            prefixes = tuple(profile.get("standardRefPrefixes", []))
+            if not ref.startswith(prefixes):
+                issues.append({"code": "standard-ref-mismatch", "severity": "error", "family": family, "node": node_id, "ref": ref or None, "allowedPrefixes": list(prefixes), "message": f"Node {node_id} lacks a {family} standard reference or decision."})
+
+    return {
+        "version": 1,
+        "status": "blocked" if any(item["severity"] == "error" for item in issues) else "pass",
+        "targetFamilies": sorted(families),
+        "frameworkAdapters": sorted(framework_adapters(ir)),
+        "resolvedProfiles": resolved,
+        "issues": issues,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("ir", help="Path to ui-ir.json")
+    parser.add_argument("--output", required=True, help="Path for platform-profile-report.json")
+    parser.add_argument("--strict", action="store_true", help="Exit non-zero when the report is blocked")
+    args = parser.parse_args()
+    report = validate_profiles(read_json(args.ir))
+    write_json(args.output, report)
+    print(Path(args.output).resolve())
+    return 2 if args.strict and report["status"] != "pass" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/visual_regression.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""Compare preview screenshots and optional geometry snapshots with explicit tolerances."""
+
+from __future__ import annotations
+
+import argparse
+import math
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    from PIL import Image
+except ImportError:  # pragma: no cover - depends on the selected workspace runtime
+    Image = None
+
+from quality_common import read_json, write_json
+
+
+def compare_images(baseline_path: str, candidate_path: str, channel_tolerance: int, diff_path: str | None) -> dict[str, Any]:
+    baseline = Image.open(baseline_path).convert("RGBA")
+    candidate = Image.open(candidate_path).convert("RGBA")
+    if baseline.size != candidate.size:
+        return {"status": "fail", "baselineSize": list(baseline.size), "candidateSize": list(candidate.size), "reason": "image-size-mismatch"}
+
+    total = baseline.width * baseline.height
+    changed = 0
+    absolute_sum = 0
+    maximum = 0
+    bounds = [baseline.width, baseline.height, -1, -1]
+    overlay = Image.new("RGBA", baseline.size, (0, 0, 0, 0)) if diff_path else None
+    overlay_pixels = overlay.load() if overlay else None
+
+    baseline_data = baseline.get_flattened_data() if hasattr(baseline, "get_flattened_data") else baseline.getdata()
+    candidate_data = candidate.get_flattened_data() if hasattr(candidate, "get_flattened_data") else candidate.getdata()
+    for index, (before, after) in enumerate(zip(baseline_data, candidate_data)):
+        differences = tuple(abs(int(before[channel]) - int(after[channel])) for channel in range(4))
+        pixel_max = max(differences)
+        absolute_sum += sum(differences)
+        maximum = max(maximum, pixel_max)
+        if pixel_max <= channel_tolerance:
+            continue
+        changed += 1
+        x = index % baseline.width
+        y = index // baseline.width
+        bounds[0] = min(bounds[0], x)
+        bounds[1] = min(bounds[1], y)
+        bounds[2] = max(bounds[2], x)
+        bounds[3] = max(bounds[3], y)
+        if overlay_pixels is not None:
+            overlay_pixels[x, y] = (239, 68, 68, 220)
+
+    if overlay and diff_path:
+        target = Path(diff_path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        highlighted = candidate.copy()
+        highlighted.alpha_composite(overlay)
+        highlighted.save(target)
+
+    return {
+        "status": "pass",
+        "baselineSize": list(baseline.size),
+        "candidateSize": list(candidate.size),
+        "channelTolerance": channel_tolerance,
+        "changedPixels": changed,
+        "changedRatio": round(changed / total, 8) if total else 0,
+        "meanAbsoluteError": round(absolute_sum / (total * 4), 5) if total else 0,
+        "maximumChannelError": maximum,
+        "changedBounds": None if changed == 0 else bounds,
+    }
+
+
+def compare_geometry(baseline_path: str, candidate_path: str, tolerance: float) -> dict[str, Any]:
+    baseline = read_json(baseline_path)
+    candidate = read_json(candidate_path)
+    before = baseline.get("elements", {})
+    after = candidate.get("elements", {})
+    missing = sorted(set(before) - set(after))
+    unexpected = sorted(set(after) - set(before))
+    changes: list[dict[str, Any]] = []
+    for key in sorted(set(before) & set(after)):
+        first, second = before[key], after[key]
+        if first is None or second is None:
+            if first != second:
+                changes.append({"element": key, "field": "presence", "before": first, "after": second})
+            continue
+        for field in ("x", "y", "width", "height"):
+            a, b = first.get(field), second.get(field)
+            if isinstance(a, (int, float)) and isinstance(b, (int, float)) and math.fabs(a - b) > tolerance:
+                changes.append({"element": key, "field": field, "before": a, "after": b, "delta": round(b - a, 3)})
+        for field in ("visible", "overflowX", "overflowY"):
+            if first.get(field) != second.get(field):
+                changes.append({"element": key, "field": field, "before": first.get(field), "after": second.get(field)})
+    overlaps = candidate.get("overlaps", [])
+    return {
+        "status": "fail" if missing or unexpected or changes or overlaps else "pass",
+        "toleranceCssPx": tolerance,
+        "missingElements": missing,
+        "unexpectedElements": unexpected,
+        "changes": changes,
+        "candidateOverlaps": overlaps,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--baseline", required=True, help="Approved PNG screenshot")
+    parser.add_argument("--candidate", required=True, help="Candidate PNG screenshot")
+    parser.add_argument("--output", required=True, help="Path for visual-regression.json")
+    parser.add_argument("--diff-image", help="Optional highlighted PNG output")
+    parser.add_argument("--baseline-geometry", help="Approved geometry JSON from smoke_preview.js")
+    parser.add_argument("--candidate-geometry", help="Candidate geometry JSON from smoke_preview.js")
+    parser.add_argument("--channel-tolerance", type=int, default=12)
+    parser.add_argument("--max-changed-ratio", type=float, default=.005)
+    parser.add_argument("--max-mean-error", type=float, default=1.0)
+    parser.add_argument("--geometry-tolerance", type=float, default=1.0)
+    parser.add_argument("--strict", action="store_true", help="Exit non-zero when thresholds fail")
+    args = parser.parse_args()
+    if Image is None:
+        parser.error("Pillow is required for pixel comparison; use a workspace Python runtime that provides PIL.")
+    if bool(args.baseline_geometry) != bool(args.candidate_geometry):
+        parser.error("Provide both --baseline-geometry and --candidate-geometry")
+
+    image_report = compare_images(args.baseline, args.candidate, max(0, args.channel_tolerance), args.diff_image)
+    image_pass = image_report.get("status") == "pass" and image_report.get("changedRatio", 1) <= args.max_changed_ratio and image_report.get("meanAbsoluteError", float("inf")) <= args.max_mean_error
+    geometry_report = compare_geometry(args.baseline_geometry, args.candidate_geometry, max(0, args.geometry_tolerance)) if args.baseline_geometry else None
+    geometry_pass = geometry_report is None or geometry_report.get("status") == "pass"
+    report = {
+        "version": 1,
+        "status": "pass" if image_pass and geometry_pass else "fail",
+        "thresholds": {"maxChangedRatio": args.max_changed_ratio, "maxMeanAbsoluteError": args.max_mean_error, "geometryToleranceCssPx": args.geometry_tolerance},
+        "image": image_report,
+        "geometry": geometry_report,
+    }
+    write_json(args.output, report)
+    print(f"Visual regression: {report['status']} | changed={image_report.get('changedRatio', 1):.4%}")
+    return 2 if args.strict and report["status"] != "pass" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ui_design_workbench_cli-0.5.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: ui-design-workbench-cli
+Version: 0.5.0
+Summary: Repository UI indexing, graph, preview, and deterministic review CLI
+Author: Elgreed
+Project-URL: Homepage, https://github.com/Elgreed/ui-design-workbench
+Project-URL: Repository, https://github.com/Elgreed/ui-design-workbench
+Project-URL: Changelog, https://github.com/Elgreed/ui-design-workbench/blob/main/CHANGELOG.md
+Keywords: agent-skills,ui,ux,design-review,code-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == "mcp"
+
+# UI Design Workbench
+
+[Русская версия](README.ru.md) · [Changelog](CHANGELOG.md) · [Release guide](RELEASING.md)
+
+Turn repository UI source into an offline interactive HTML workbench—without building or running the application.
+
+```text
+UI source → cached UI map → strict UI IR → interactive HTML
+```
+
+Use it to understand unfamiliar UI, inspect screens and navigation, verify a reconstruction, or run an explicit UI/UX review.
+
+## Install
+
+Requires Python 3.10+ and [`pipx`](https://pipx.pypa.io/).
+
+```sh
+pipx install ui-design-workbench-cli
+uidw install-skill codex
+```
+
+`install-skill` also supports `claude`, `cursor`, `gemini`, `copilot`, `opencode`, `agents`, and `all`.
+
+Optional local MCP support:
+
+```sh
+pipx inject ui-design-workbench-cli "mcp>=2,<3"
+```
+
+Verify the installation:
+
+```sh
+uidw --version
+uidw doctor
+```
+
+## Quick start
+
+Choose preview detail once:
+
+```sh
+uidw --repo <repo> config setup
+```
+
+Build and open the source-derived workbench:
+
+```sh
+uidw --repo <repo> workbench --output-dir <artifacts> --level full --open
+```
+
+Run a UI/UX audit only when product critique is wanted:
+
+```sh
+uidw --repo <repo> review --output-dir <review-dir> --level full
+```
+
+`workbench` and `check` validate the projection. Only `review` creates UI/UX findings.
+
+## What it provides
+
+- Screen, route, component, token, theme, and state inventory.
+- Standalone HTML with source links and reconstructed navigation.
+- Incremental scans that reprocess only changed UI files.
+- Property-level evidence and explicit unsupported gaps instead of guessed UI.
+- Sparse review patches and a separate, authorized source-apply step.
+- Structural Android and Apple resource projection, plus discovery of available native capture paths.
+
+Supported source families include Web, React, Vue, Svelte, Jetpack Compose, Android Views XML, SwiftUI, Storyboard/XIB, WinUI/WPF, and Flutter.
+
+## Main commands
+
+| Command | Purpose |
+| --- | --- |
+| `uidw doctor` | Check installation and optional dependencies |
+| `uidw --repo <repo> context --json` | Read compact cached project context |
+| `uidw --repo <repo> scope ...` | Prepare bounded context for a screen or finding |
+| `uidw --repo <repo> patch ...` | Validate or apply sparse review-artifact changes |
+| `uidw --repo <repo> workbench ...` | Build and validate the HTML projection |
+| `uidw --repo <repo> native status` | Discover native Android/Apple render providers without running them |
+| `uidw --repo <repo> check ...` | Repeat projection checks without a UI/UX audit |
+| `uidw --repo <repo> review ...` | Start an explicit UI/UX review |
+| `uidw --repo <repo> fidelity ...` | Inspect source evidence and adapter limits |
+| `uidw --repo <repo> mcp` | Start the optional local stdio MCP server |
+
+Run `uidw help overview`, `uidw help advanced`, or `uidw <command> --help` for details.
+
+## Accuracy and safety
+
+- HTML is a static source projection, not proof of runtime or pixel parity.
+- Android and Apple translation remains structural until a source-matched native capture exists.
+- Unsupported bindings, custom drawing, runtime data, and platform behavior remain explicit gaps.
+- Preview and review keep application source read-only; applying a proposal is a separate step.
+- Derived cache and review state live outside the target repository by default.
+
+## Upgrade
+
+```sh
+pipx upgrade ui-design-workbench-cli
+uidw install-skill codex
+```
+
+A Windows `.exe` is not published yet. PyPI + `pipx` is the primary cross-platform installation path.
+
+## Documentation
+
+- [Changelog](CHANGELOG.md)
+- [Release and distribution guide](RELEASING.md)
+- [Agent integrations](references/agent-integrations.md)
+- [Fidelity contract](references/fidelity.md)
+- [Native rendering](references/native-rendering.md)
+- [IR schema](references/ir-schema.md)
+- [Review workflow](references/review-workflow.md)
+
+Current CLI version: `0.5.0`.