ai-kit-python 1.4.2__py3-none-any.whl

aikit/scripts/context.py

@@ -0,0 +1,184 @@
+"""Capture manifest evidence for an installed project's verified context."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import re
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import install
+
+
+PROJECT_FACTS = "ai-kit/project.json"
+DESIGN_WORKFLOWS = {"web-design": "web-design", "ui-review": "ui-review", "design-extract": "design-extract"}
+
+
+def target_root(target: Path) -> Path:
+    target = target.absolute()
+    if install.is_link(target):
+        raise ValueError("Refusing a linked project root")
+    target = target.resolve()
+    if not target.is_dir():
+        raise ValueError("Project must be an existing directory")
+    return target
+
+
+def snapshot_plan(target: Path) -> dict:
+    """Prepare, but do not write, a manifest-evidence snapshot."""
+    target = target_root(target)
+    path = install.safe_path(target, PROJECT_FACTS)
+    if not path.is_file():
+        raise ValueError("Missing ai-kit/project.json; install AI-KIT before recording context evidence")
+    value = install.read_json(path, {})
+    if type(value.get("schema")) is not int or value["schema"] != 1:
+        raise ValueError("Unsupported project.json schema; expected schema 1")
+    if not isinstance(value.get("modules"), list) or any(not isinstance(module, dict) for module in value["modules"]):
+        raise ValueError("project.json modules must be a list of objects")
+    facts = install.detect_facts(target)
+    updated = dict(value)
+    updated["evidence"] = install.project_fact_evidence(target, facts)
+    data = (json.dumps(updated, indent=2) + "\n").encode("utf-8")
+    old = path.read_bytes()
+    return {"target": str(target), "path": PROJECT_FACTS, "old": old, "data": data,
+            "changed": old != data, "detected_modules": [module["path"] for module in facts["modules"]]}
+
+
+def apply_snapshot(plan: dict) -> bool:
+    target = Path(plan["target"])
+    path = install.safe_path(target, plan["path"])
+    actual = path.read_bytes() if path.exists() else None
+    if actual != plan["old"]:
+        raise ValueError("project.json changed after preview")
+    if not plan["changed"]:
+        return True
+    install.atomic_write(path, plan["data"])
+    return True
+
+
+def select_context(target: Path, *, path: str = ".", budget: int = 32000,
+                   workflow: str | None = None) -> dict:
+    """Select instructions by declared module scope; budgets cannot remove critical rules."""
+    target = target_root(target)
+    if type(budget) is not int or budget < 1:
+        raise ValueError("Context budget must be a positive byte count")
+    if workflow is not None and workflow not in DESIGN_WORKFLOWS:
+        raise ValueError("Unknown context workflow: " + str(workflow))
+    if path == ".":
+        relative = ""
+    else:
+        # Probe a file rather than accepting directory links through resolve().
+        install.safe_path(target, path.rstrip("/") + "/__context_probe__")
+        relative = path.strip("/")
+        if path.startswith(("/", "\\")):
+            raise ValueError("Module path must be relative")
+    facts = install.read_json(install.safe_path(target, PROJECT_FACTS), {})
+    if facts.get("schema") != 1 or not isinstance(facts.get("modules"), list):
+        raise ValueError("Missing/invalid project module map")
+    profiles, matching, scoped = set(), [], []
+    for module in facts["modules"]:
+        if not isinstance(module, dict) or not isinstance(module.get("path"), str) or not install.MODULE_PATH.fullmatch(module["path"]):
+            raise ValueError("Invalid declared module path")
+        scope = module["path"].strip("/")
+        if not scope or relative == scope or relative.startswith(scope + "/"):
+            if not isinstance(module.get("profiles"), list) or any(not isinstance(p, str) or not re.fullmatch(r"[A-Z][A-Z0-9_]*", p) for p in module["profiles"]):
+                raise ValueError("Invalid module profiles")
+            scoped.append(module)
+    # A nested declared module supersedes its parent's stack, while shared instructions still apply.
+    deepest = max((len(m["path"]) for m in scoped), default=0)
+    for module in scoped:
+        if len(module["path"]) == deepest:
+            matching.append(module["path"])
+            profiles.update(module["profiles"])
+    critical = ["AGENTS.md", "ai-kit/CORE.md", "ai-kit/settings.json", "PROJECT_CONTEXT.md",
+                "ai-kit/ENGINEERING.md", "ai-kit/SECURITY.md", "docs/DECISIONS.md"]
+    settings = install.read_json(install.safe_path(target, "ai-kit/settings.json"), {})
+    workflow_files = []
+    if workflow is not None:
+        if settings.get("web_design") is not True:
+            raise ValueError("Web Design workflow is disabled; install with --with-web-design first")
+        workflow_files = ["ai-kit/WEB-DESIGN.md", ".agents/skills/" + DESIGN_WORKFLOWS[workflow] + "/SKILL.md",
+                          *install.OPTIONAL_DOCUMENTS["web-design"]]
+        if workflow == "ui-review":
+            workflow_files.append("ai-kit/web-design/REVIEW.md")
+        elif workflow == "design-extract":
+            workflow_files.append("ai-kit/web-design/TOOLS.md")
+        elif profiles & {"LARAVEL", "FILAMENT"}:
+            workflow_files.extend(["ai-kit/web-design/LARAVEL.md", ".agents/skills/laravel-blade-ui/SKILL.md"])
+        critical.extend(workflow_files)
+    if settings.get("conventions") == "owner" and profiles & {"LARAVEL", "FILAMENT"}:
+        critical.append("ai-kit/profiles/OWNER.md")
+    # ADRs preserve architectural constraints between sessions; do not truncate them for a budget.
+    adr_dir = target / "docs/adr"
+    if install.is_link(adr_dir):
+        raise ValueError("Refusing linked ADR directory")
+    if adr_dir.is_dir():
+        critical.extend(p.relative_to(target).as_posix() for p in sorted(adr_dir.glob("*.md")) if p.name != "0000-template.md")
+    if relative:
+        parts = relative.split("/")
+        critical.extend("/".join(parts[:i]) + "/AGENTS.md" for i in range(1, len(parts) + 1))
+    required_profiles = ["ai-kit/stacks/" + p + ".md" for p in sorted(profiles)]
+    critical.extend(required_profiles)
+    selected, missing, duplicates = [], [], []
+    hashes: dict[str, str] = {}
+    for name in dict.fromkeys(critical):
+        candidate = install.safe_path(target, name)
+        if not candidate.is_file():
+            # Nested instructions and project decision records are optional; Core/settings are required.
+            if name in {"AGENTS.md", "ai-kit/CORE.md", "ai-kit/settings.json", "PROJECT_CONTEXT.md",
+                        "ai-kit/ENGINEERING.md", "ai-kit/SECURITY.md"} or name in required_profiles or name in workflow_files:
+                missing.append(name)
+            continue
+        data = candidate.read_bytes()
+        digest = hashlib.sha256(data).hexdigest()
+        if digest in hashes:
+            duplicates.append({"path": name, "same_as": hashes[digest]})
+        else:
+            hashes[digest] = name
+        selected.append({"path": name, "bytes": len(data), "sha256": digest, "critical": True})
+    if missing:
+        raise ValueError("Missing required context: " + ", ".join(missing))
+    total = sum(item["bytes"] for item in selected)
+    return {"selected": selected, "duplicates": duplicates, "modules": matching, "profiles": sorted(profiles),
+            "workflow": workflow,
+            "total_bytes": total, "budget_bytes": budget, "over_budget": total > budget,
+            "selection_complete": bool(matching),
+            "note": "Declared modules may still need bootstrap verification. Byte counts are not token counts. "
+                    "Critical rules, matching profiles and architecture decisions are retained even above budget. "
+                    "Duplicate critical files retain their scope/relative-link meaning. "
+                    "Unrelated profiles and instruction history are excluded; no files are changed."}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    snapshot = sub.add_parser("snapshot", help="Preview or record current manifest evidence in project.json")
+    snapshot.add_argument("project", type=Path)
+    snapshot.add_argument("--apply", action="store_true")
+    select = sub.add_parser("select", help="Select module instructions and measure a byte budget without writing")
+    select.add_argument("project", type=Path)
+    select.add_argument("--path", default=".", help="Relative module/directory scope")
+    select.add_argument("--budget", type=int, default=32000, help="Byte budget; critical context is never dropped")
+    select.add_argument("--workflow", choices=sorted(DESIGN_WORKFLOWS),
+                        help="Include the enabled design workflow and project design documents")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "select":
+            print(json.dumps(select_context(args.project, path=args.path, budget=args.budget,
+                                            workflow=args.workflow), indent=2))
+            return 0
+        plan = snapshot_plan(args.project)
+        print(json.dumps({"target": plan["target"], "preview": not args.apply, "changed": plan["changed"],
+                          "path": plan["path"], "detected_modules": plan["detected_modules"]}, indent=2))
+        if args.apply:
+            apply_snapshot(plan)
+        return 0
+    except (OSError, ValueError, UnicodeError, json.JSONDecodeError) as exc:
+        print(f"Context snapshot refused: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aikit/scripts/docker_test_usage.py

@@ -0,0 +1,55 @@
+"""Collect read-only Docker evidence; no pruning or volume/container deletion."""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+
+
+def command(argv: list[str]) -> str:
+    result = subprocess.run(argv, capture_output=True, text=True, timeout=60, check=True)
+    return result.stdout
+
+
+def collect(project: str, *, docker: str = "docker", run=command, builder: str | None = None) -> dict:
+    context = run([docker, "context", "show"]).strip()
+    run([docker, "info", "--format", "{{.ServerVersion}}"])
+    names = run([docker, "volume", "ls", "--filter", "label=com.docker.compose.project=" + project,
+                 "--format", "{{.Name}}"]).splitlines()
+    volumes = []
+    for name in names:
+        # Pass exact names as arguments, never as shell fragments.
+        data = json.loads(run([docker, "volume", "inspect", name]))[0]
+        labels = data.get("Labels") or {}
+        refs = run([docker, "ps", "-a", "--filter", "volume=" + name, "--format", "{{.ID}}"]).splitlines()
+        volumes.append({"name": name, "project_label": labels.get("com.docker.compose.project"),
+                        "declared_disposable": labels.get("ai-kit.disposable") == "true",
+                        "container_references": refs, "eligible_without_more_evidence": False})
+    report = {"context": context, "project": project, "volumes": volumes,
+              "disk_usage_raw": run([docker, "system", "df", "-v"]),
+              "measured_project_bytes": None,
+              "note": "Human-readable usage is evidence, not exact project ownership or a deletion plan."}
+    if builder:
+        report["builder"] = builder
+        report["build_cache_usage_raw"] = run([docker, "buildx", "du", "--builder", builder, "--format", "json"])
+        report["builder_project_ownership"] = "unverified"
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project", required=True)
+    parser.add_argument("--builder")
+    args = parser.parse_args(argv)
+    if not shutil.which("docker"):
+        parser.exit(1, "Docker client unavailable; install/configure the actual project runtime first.\n")
+    try:
+        print(json.dumps(collect(args.project, builder=args.builder), indent=2))
+        return 0
+    except (OSError, ValueError, subprocess.SubprocessError) as exc:
+        parser.exit(1, f"Docker evidence unavailable: {exc}\n")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aikit/scripts/doctor.py

@@ -0,0 +1,313 @@
+"""Offline health check for an AI-KIT-installed application project."""
+from __future__ import annotations
+
+import argparse
+from datetime import date
+import json
+import os
+from pathlib import Path
+import re
+import sys
+from urllib.parse import unquote
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import check_kit
+import install
+import router
+
+BUDGETS = {"AGENTS.md": 2500, "ai-kit/CORE.md": 3000}
+PROVIDER_FRESHNESS_DAYS = 90
+
+
+def examine(target: Path, *, root: Path = install.ROOT) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    info: list[str] = []
+    try:
+        target = target.absolute()
+        if install.is_link(target):
+            raise ValueError("Refusing a linked target root")
+        target = target.resolve()
+    except ValueError as exc:
+        return {"target": str(target), "installed_version": None, "bundle_version": None,
+                "errors": [str(exc)], "warnings": warnings, "info": info}
+    report = {"target": str(target),
+              "installed_version": None,
+              "bundle_version": (root / "VERSION").read_text(encoding="utf-8").strip(),
+              "errors": errors, "warnings": warnings, "info": info}
+    if not target.is_dir():
+        errors.append("Target is not a directory")
+        return report
+    settings = {}
+    try:
+        settings = install.read_json(target / "ai-kit" / "settings.json", {})
+        install.validate_settings(settings)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        errors.append(f"Invalid installation settings: {exc}")
+    state_path = target / "ai-kit" / ".install-state.json"
+    if not state_path.is_file():
+        errors.append("No installer state found; is AI-KIT installed in this project?")
+        return report
+    try:
+        state = install.read_json(state_path, {})
+        install.validate_state(state, target)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        errors.append(f"Invalid installer state: {exc}")
+        return report
+    report["installed_version"] = state.get("accepted_version")
+    if report["installed_version"] != report["bundle_version"]:
+        info.append("Installed baseline differs from this bundle's VERSION.")
+    records = state.get("files", {})
+    modified, adapted = [], []
+    for relative in sorted(records):
+        try:
+            path = install.safe_path(target, relative)
+        except ValueError as exc:
+            errors.append(f"Unsafe recorded path {relative}: {exc}")
+            continue
+        if not path.is_file():
+            errors.append("Missing managed file: " + relative)
+        elif install.digest(path.read_bytes()) != records[relative]["installed_hash"]:
+            (adapted if records[relative].get("local_adaptation") else modified).append(relative)
+    warnings.extend(f"Modified after installation; rerun the installer to review: {r}" for r in modified)
+    info.extend(f"Locally adapted (accepted): {r}" for r in adapted)
+    for relative, entries in sorted(state.get("managed_json", {}).items()):
+        path = target / relative
+        if not path.is_file():
+            warnings.append(f"Missing settings file with AI-KIT entries: {relative}")
+            continue
+        try:
+            current = json.loads(path.read_text(encoding="utf-8-sig"))
+            if not isinstance(current, dict):
+                raise ValueError("expected a JSON object")
+            for key, values in sorted(entries.items()):
+                for value in values:
+                    if install.merge_managed_json(current, {}, {key: [value]}) != current:
+                        warnings.append(f"AI-KIT entry missing from {relative}: {key} {value}")
+        except (OSError, ValueError, UnicodeError) as exc:
+            warnings.append(f"Cannot read AI-KIT entries in {relative}: {exc}")
+    for relative in sorted(install.project_documents(settings)):
+        try:
+            document = install.safe_path(target, relative)
+        except (OSError, ValueError) as exc:
+            errors.append(f"Unsafe project document {relative}: {exc}")
+            continue
+        if not document.is_file():
+            warnings.append("Owned project document missing: " + relative)
+    for relative, limit in BUDGETS.items():
+        path = target / relative
+        if path.is_file() and path.stat().st_size > limit:
+            warnings.append(f"Always-loaded entry exceeds budget: {relative}")
+    candidates_dir = target / "ai-kit" / ".upstream-cache" / "candidates"
+    if candidates_dir.is_dir():
+        pending = list(candidates_dir.glob("*/*.metadata.json"))
+        if pending:
+            warnings.append(f"Pending conflict candidates need review: {len(pending)}")
+    providers_dir = target / "ai-kit" / "router" / "providers"
+    provider_configs = sorted(providers_dir.glob("*.json")) if providers_dir.is_dir() else []
+    for provider in provider_configs:
+        try:
+            config = json.loads(provider.read_text(encoding="utf-8"))
+        except ValueError as exc:
+            warnings.append(f"Invalid provider configuration {provider.name}: {exc}")
+            continue
+        user_supplied = config.get("user_supplied_models") is True
+        pending = config.get("verification_status") == "pending"
+        for role, spec in config.get("roles", {}).items():
+            if "effort" in spec and spec["effort"] not in config.get("supported_efforts", {}).get(role, []):
+                warnings.append(f"Unsupported configured effort: {provider.name} role {role}")
+        verified = config.get("verified_documentation_date")
+        try:
+            verified_date = date.fromisoformat(verified) if isinstance(verified, str) else None
+        except ValueError:
+            verified_date = None
+        if user_supplied:
+            info.append(f"Provider {provider.name} uses project-supplied local models")
+        elif pending:
+            info.append(f"Provider {provider.name} verification is pending")
+        elif verified_date is None:
+            warnings.append(f"Provider {provider.name} lacks a valid verified_documentation_date")
+        elif (date.today() - verified_date).days > PROVIDER_FRESHNESS_DAYS:
+            warnings.append(f"Provider {provider.name} verification is older than "
+                            f"{PROVIDER_FRESHNESS_DAYS} days")
+    selection_path = target / "ai-kit" / "router" / "selection.json"
+    if selection_path.is_file():
+        try:
+            router.validate_selection(json.loads(selection_path.read_text(encoding="utf-8")))
+        except (OSError, ValueError, json.JSONDecodeError) as exc:
+            warnings.append(f"Invalid router selection: {exc}")
+    resolved_path = target / "ai-kit" / "router" / "resolved.json"
+    if resolved_path.is_file():
+        try:
+            resolved = json.loads(resolved_path.read_text(encoding="utf-8"))
+            if type(resolved.get("schema")) is not int or resolved["schema"] != 1:
+                raise ValueError("Unsupported resolved schema; expected schema 1")
+            if not isinstance(resolved.get("roles"), dict):
+                raise ValueError("Resolved roles must be an object")
+        except (ValueError, json.JSONDecodeError) as exc:
+            warnings.append(f"Invalid generated router config: {exc}")
+    project_json_path = target / "ai-kit" / "project.json"
+    project_value = None
+    if project_json_path.is_file():
+        try:
+            project_value = json.loads(project_json_path.read_text(encoding="utf-8"))
+            if type(project_value.get("schema")) is not int or project_value["schema"] != 1:
+                raise ValueError("Unsupported project schema; expected schema 1")
+            modules = project_value.get("modules")
+            if not isinstance(modules, list) or any(not isinstance(m, dict) for m in modules):
+                raise ValueError("Project modules must be a list of objects")
+        except (ValueError, json.JSONDecodeError) as exc:
+            warnings.append(f"Invalid project.json: {exc}")
+    context_path = target / "PROJECT_CONTEXT.md"
+    if project_value is not None and context_path.is_file():
+        try:
+            json_paths = project_module_paths(project_value)
+            context_paths = context_module_paths(context_path.read_text(encoding="utf-8"))
+            if json_paths != context_paths:
+                detail = []
+                if context_paths - json_paths:
+                    detail.append("only in context: " + ", ".join(sorted(context_paths - json_paths)))
+                if json_paths - context_paths:
+                    detail.append("only in project.json: " + ", ".join(sorted(json_paths - context_paths)))
+                warnings.append("project.json and PROJECT_CONTEXT.md module maps differ (" + "; ".join(detail) + ")")
+        except (OSError, UnicodeError) as exc:
+            warnings.append(f"Cannot compare module maps: {exc}")
+    if project_value is not None:
+        freshness_warnings(target, project_value, warnings, info)
+    warnings.extend(link_warnings(target))
+    return report
+
+
+def project_module_paths(value: dict) -> set[str]:
+    """Module paths recorded in ai-kit/project.json."""
+    paths = set()
+    for module in value.get("modules", []):
+        if isinstance(module, dict) and isinstance(module.get("path"), str):
+            paths.add(module["path"])
+    return paths
+
+
+def context_module_paths(text: str) -> set[str]:
+    """Module paths in the PROJECT_CONTEXT.md module-map table (canonical /-prefixed rows)."""
+    paths = set()
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("| /"):
+            continue
+        cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+        if cells and cells[0].startswith("/"):
+            paths.add(cells[0])
+    return paths
+
+
+def freshness_warnings(target: Path, project: dict, warnings: list[str], info: list[str]) -> None:
+    """Compare recorded module facts and manifest evidence with current filesystem facts."""
+    try:
+        facts = install.detect_facts(target)
+    except (OSError, ValueError) as exc:
+        warnings.append(f"Cannot detect current project facts: {exc}")
+        return
+    detected = {module["path"]: module for module in facts["modules"]}
+    recorded = {module["path"]: module for module in project.get("modules", [])
+                if isinstance(module.get("path"), str)}
+    for path in sorted(set(detected) - set(recorded)):
+        warnings.append("Detected module missing from project facts: " + path)
+    for path in sorted(set(recorded) - set(detected)):
+        if isinstance(recorded[path].get("manifests"), list) and recorded[path]["manifests"]:
+            warnings.append("Recorded module no longer has detected manifests: " + path)
+    for path in sorted(set(detected) & set(recorded)):
+        expected_profiles = recorded[path].get("profiles")
+        if isinstance(expected_profiles, list) and sorted(expected_profiles) != detected[path]["profiles"]:
+            warnings.append("Detected profiles differ from project facts at " + path)
+    evidence = project.get("evidence")
+    if evidence is None:
+        info.append("No project fact evidence snapshot; run aikit context snapshot TARGET --apply after bootstrap.")
+        return
+    if not isinstance(evidence, dict) or evidence.get("schema") != 1 or not isinstance(evidence.get("modules"), list):
+        warnings.append("Invalid project fact evidence; rerun aikit context snapshot TARGET --apply.")
+        return
+    try:
+        current = install.project_fact_evidence(target, facts)
+    except (OSError, ValueError) as exc:
+        warnings.append(f"Cannot refresh project fact evidence: {exc}")
+        return
+    stored = {item.get("path"): item for item in evidence["modules"] if isinstance(item, dict) and
+              isinstance(item.get("path"), str) and isinstance(item.get("manifests"), dict)}
+    observed = {item["path"]: item for item in current["modules"]}
+    for path in sorted(set(stored) | set(observed)):
+        if path not in stored:
+            warnings.append("New detected manifest evidence at " + path + "; update context after review.")
+        elif path not in observed:
+            warnings.append("Recorded manifest evidence no longer detected at " + path + "; update context after review.")
+        else:
+            if stored[path]["manifests"] != observed[path]["manifests"]:
+                warnings.append("Manifest evidence changed at " + path + "; review context facts and commands.")
+            if stored[path].get("profiles") != observed[path].get("profiles"):
+                warnings.append("Detected profiles changed at " + path + "; review context facts.")
+            if stored[path].get("commands") != observed[path].get("commands"):
+                warnings.append("Detected commands changed at " + path + "; review context facts and commands.")
+
+
+def link_warnings(target: Path) -> list[str]:
+    """Report broken relative links/anchors in the installed project's Markdown."""
+    problems = []
+    excluded = {".git", ".upstream-cache", "node_modules", "vendor", ".venv", "__pycache__"}
+    for directory, dirs, files in os.walk(target, followlinks=False):
+        dirs[:] = [d for d in dirs if d not in excluded and not install.is_link(Path(directory) / d)]
+        if Path(directory) == target / "ai-kit":
+            dirs[:] = [d for d in dirs if d != ".metrics"]
+        for name in files:
+            path = Path(directory) / name
+            if path.suffix != ".md":
+                continue
+            relative = path.relative_to(target).as_posix()
+            text = path.read_text(encoding="utf-8")
+            for link in check_kit.links(text):
+                if re.match(r"^[a-z][a-z0-9+.-]*:", link, re.I):
+                    continue
+                filename, _, anchor = unquote(link).partition("#")
+                destination = (path.parent / filename).resolve() if filename else path.resolve()
+                try:
+                    destination.relative_to(target.resolve())
+                except ValueError:
+                    problems.append(f"{relative}: link escapes project: {link}")
+                    continue
+                if not destination.exists():
+                    problems.append(f"{relative}: missing link: {link}")
+                elif anchor and destination.is_file() and destination.suffix == ".md":
+                    if anchor not in check_kit.headings(destination.read_text(encoding="utf-8")):
+                        problems.append(f"{relative}: missing heading: {link}")
+    return problems
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("target", type=Path)
+    parser.add_argument("--root", type=Path, default=install.ROOT,
+                        help="Reference distribution used for the bundle version comparison")
+    parser.add_argument("--fix", action="store_true",
+                        help="Re-run the installer to restore missing/baseline files; local edits are preserved")
+    args = parser.parse_args(argv)
+    if args.fix:
+        try:
+            plan = install.build_plan(args.target, root=args.root)
+            applied = install.apply_plan(plan)
+            report = examine(args.target, root=args.root)
+        except (OSError, ValueError, json.JSONDecodeError) as exc:
+            print(f"Fix refused: {exc}", file=sys.stderr)
+            return 1
+        print(json.dumps({"fix": {"writes": sorted(plan["actions"]),
+                                  "conflicts": sorted(plan["conflicts"]), "applied": applied},
+                          "report": report}, indent=2))
+        return 2 if (plan["conflicts"] or report["errors"]) else 0
+    try:
+        report = examine(args.target, root=args.root)
+    except OSError as exc:
+        print(f"Examination failed: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(report, indent=2))
+    return 1 if report["errors"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())