coding-os 0.3.2__py3-none-any.whl

scripts/refactor_agent_dual_mode.py

@@ -0,0 +1,171 @@
+"""Rewrite each agent .md SSOT to be dual-mode (composer JSON + interactive prose).
+
+Reads every src/core/thinking_os/agents/<role>.md (excluding README), locates
+the ``## Inputs you receive`` and ``## Output contract`` sections, replaces
+them with the dual-mode templates while preserving the existing JSON skeleton
+verbatim. Idempotent: re-running on an already-converted file is a no-op.
+
+Run:
+    python src/scripts/refactor_agent_dual_mode.py
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+AGENTS_DIR = Path(__file__).resolve().parent.parent / "core" / "thinking_os" / "agents"
+
+SENTINEL = "This command runs in **two modes**"
+
+INPUT_BLOCK_RE = re.compile(
+    r"^## Inputs you receive\n+```json\n\{\{ ([A-Za-z]+Input) \}\}\n```\n",
+    re.MULTILINE,
+)
+OUTPUT_HEADING_RE = re.compile(
+    r"^## Output contract\nReturn JSON matching `([A-Za-z]+Output)`\. No prose outside the JSON block\.\n+```json\n",
+    re.MULTILINE,
+)
+
+
+def render_inputs(input_name: str) -> str:
+    return f"""## Inputs you receive
+
+This command runs in **two modes** — choose based on what the user message
+already contains.
+
+**(A) Composer mode** — `cos_dispatch_formula_run` invoked this role. The user
+message contains a `{input_name}` JSON object (shape defined by the
+`input_schema` frontmatter field).
+
+**(B) Interactive mode** — user invoked the slash command and the user
+message has **no `{input_name}`-shaped JSON**. Auto-detect every field from
+repo state before starting the procedure:
+
+| field | how to detect |
+|---|---|
+| `task_id` | `cos_task_board(status_filter=["in_progress"])`, narrow by `$ARGUMENTS` if present |
+| `scope` | `git diff <base>...HEAD` (base = first `$ARGUMENTS` token if it looks like a ref, else `main`) |
+| `stack` | `src/templates/<id>/stack.yaml` of the enabled template |
+| `domain` | `cos_doc_headers_by(domain=...)` or the active task's frontmatter |
+| `nfr_targets` | `docs/_meta/nfr.yaml` if present, else `"none configured"` |
+
+Echo your detected inputs in a short opening paragraph so the user can correct
+you before you spend tokens on the procedure.
+
+"""
+
+
+def render_output_prefix(output_name: str) -> str:
+    return f"""## Output contract
+
+**Match the invocation mode**:
+
+**(A) Composer mode** — return JSON only matching `{output_name}`. No prose
+outside the fenced block:
+
+```json
+"""
+
+
+def render_output_suffix(output_name: str) -> str:
+    return f"""
+**(B) Interactive mode** — return a Markdown review with these sections:
+
+1. **Detected inputs** — one paragraph echoing task_id / scope / stack / nfr.
+2. **Summary** — one paragraph: what was done, overall verdict.
+3. **Findings or Deliverables** — bulleted; severities critical / high / medium / low / info where applicable.
+4. **Next step** — single recommended action (or "ready to hand off to <next-role>").
+
+Then append the **same `{output_name}` envelope** as a fenced ```json``` block
+at the very bottom so `cos_supervise_record_output` can parse it. Both
+audiences (human + composer) consume the same output from one emission.
+"""
+
+
+def transform(text: str) -> tuple[str, str | None]:
+    if SENTINEL in text:
+        return text, None
+
+    m_in = INPUT_BLOCK_RE.search(text)
+    m_out = OUTPUT_HEADING_RE.search(text)
+    if not m_in or not m_out:
+        return text, None
+
+    input_name = m_in.group(1)
+    output_name = m_out.group(1)
+
+    new_text = text[: m_in.start()] + render_inputs(input_name) + text[m_in.end() :]
+
+    m_out2 = OUTPUT_HEADING_RE.search(new_text)
+    if not m_out2:
+        return text, None
+
+    skeleton_start = m_out2.end()
+    close_idx = new_text.find("\n```", skeleton_start)
+    if close_idx == -1:
+        return text, None
+    close_end = close_idx + len("\n```")
+
+    new_text = (
+        new_text[: m_out2.start()]
+        + render_output_prefix(output_name)
+        + new_text[skeleton_start:close_end]
+        + render_output_suffix(output_name)
+        + new_text[close_end:]
+    )
+    return new_text, input_name.removesuffix("Input").lower()
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=AGENTS_DIR,
+        help="Agents dir (default: src/core/thinking_os/agents).",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Report what would change without writing."
+    )
+    args = parser.parse_args(argv)
+
+    rewrote: list[str] = []
+    skipped: list[str] = []
+    errors = 0
+    for md in sorted(args.root.glob("*.md")):
+        if md.name == "README.md":
+            continue
+        try:
+            original = md.read_text(encoding="utf-8")
+        except OSError as exc:
+            print(f"ERROR reading {md.name}: {exc}", file=sys.stderr)
+            errors += 1
+            continue
+        new_text, role = transform(original)
+        if role is None:
+            skipped.append(md.name)
+            continue
+        if args.dry_run:
+            rewrote.append(f"{md.name} (dry-run)")
+            continue
+        try:
+            md.write_text(new_text, encoding="utf-8")
+        except OSError as exc:
+            print(f"ERROR writing {md.name}: {exc}", file=sys.stderr)
+            errors += 1
+            continue
+        rewrote.append(md.name)
+    print(f"rewrote {len(rewrote)}: {', '.join(rewrote) or '(none)'}")
+    print(f"skipped {len(skipped)}: {', '.join(skipped) or '(none)'}")
+    if errors:
+        print(f"errors: {errors}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/refresh_skill_versions.py

@@ -0,0 +1,302 @@
+"""Check or refresh the pinned tool versions inside skill reference docs.
+
+PURPOSE:      Keep every skill's `versions.json` current against the
+              authoritative package registry so reference docs never assert a
+              stale "latest". One command replaces hand-editing N files.
+INPUT:        --root <dir>     repo root to scan (default: cwd).
+              --skill <name>   limit to one skill folder.
+              --check          report drift, exit 1 if any (CI gate).
+              --write          rewrite drifted version+checked in place.
+              --offline        validate schema only, no network.
+              --json           machine-readable summary on stdout.
+              --timeout <s>    per-request timeout (default 8).
+OUTPUT:       Human summary on stderr (progress) + table/JSON on stdout.
+              Exit 0 = in sync (or written); 1 = drift found (--check) or
+              schema error; 2 = usage error.
+DEPENDENCIES: stdlib only (urllib, json) — portable across consumer projects.
+NOTES:        A skill opts in by shipping `versions.json` next to SKILL.md:
+                {"<key>": {"ecosystem": "npm", "package": "next",
+                           "version": "16.2.7", "source": "<url>",
+                           "checked": "2026-06-04"}}
+              Fetch is pluggable per ecosystem; unknown/unreachable entries
+              are reported, never silently passed. The diff layer is pure so
+              it unit-tests without network. Spec:
+              docs/playbooks/skill-authoring.md § Version-pinning mechanism.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Callable
+
+VERSIONS_FILENAME = "versions.json"
+REQUIRED_KEYS = ("ecosystem", "package", "version")
+
+
+# --- ecosystem fetchers ------------------------------------------------------
+# Each returns the latest stable version string, or raises on failure. URLs are
+# the registry's machine-readable endpoint (see docs/playbooks/skill-authoring.md).
+
+
+def _get_json(url: str, timeout: float) -> dict:
+    req = urllib.request.Request(url, headers={"User-Agent": "coding-os-skill-refresh"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return json.loads(resp.read().decode("utf-8"))
+
+
+def _get_text(url: str, timeout: float) -> str:
+    req = urllib.request.Request(url, headers={"User-Agent": "coding-os-skill-refresh"})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return resp.read().decode("utf-8").strip()
+
+
+def _npm(pkg: str, timeout: float) -> str:
+    return _get_json(f"https://registry.npmjs.org/{pkg}/latest", timeout)["version"]
+
+
+def _pypi(pkg: str, timeout: float) -> str:
+    return _get_json(f"https://pypi.org/pypi/{pkg}/json", timeout)["info"]["version"]
+
+
+def _go(module: str, timeout: float) -> str:
+    return _get_json(f"https://proxy.golang.org/{module}/@latest", timeout)["Version"].lstrip("v")
+
+
+def _go_toolchain(_pkg: str, timeout: float) -> str:
+    data = _get_json("https://go.dev/dl/?mode=json", timeout)
+    return data[0]["version"].removeprefix("go")
+
+
+def _tag_version(tag: str) -> str:
+    # GitHub release tags carry project-specific prefixes (v1.2.3, cli-2.6.0,
+    # release-2.6.0). Extract the leading numeric version so the diff compares
+    # apples to apples; fall back to a bare v-strip when no number is present.
+    match = re.search(r"\d[\w.+-]*$", tag)
+    return match.group(0) if match else tag.strip().lstrip("v")
+
+
+def _github(repo: str, timeout: float) -> str:
+    # repo == "owner/name"; /releases/latest skips pre-releases (= stable).
+    return _tag_version(
+        _get_json(f"https://api.github.com/repos/{repo}/releases/latest", timeout)["tag_name"]
+    )
+
+
+def _endoflife(product: str, timeout: float, track: str | None = None) -> str:
+    # Newest cycle by default; track="lts" returns the newest CURRENTLY-LTS cycle.
+    # endoflife's `lts` field is polymorphic: True/False, or a date the cycle
+    # ENTERS lts — a future date means "not LTS yet", so only True or a past date
+    # counts (else a not-yet-LTS interim like Node 26 would be wrongly picked).
+    cycles = _get_json(f"https://endoflife.date/api/{product}.json", timeout)
+    if track == "lts":
+        today = _today()
+        for cycle in cycles:
+            lts = cycle.get("lts")
+            if lts is True or (isinstance(lts, str) and lts <= today):
+                return str(cycle["latest"])
+    return str(cycles[0]["latest"])
+
+
+def _k8s(_pkg: str, timeout: float) -> str:
+    return _get_text("https://dl.k8s.io/release/stable.txt", timeout).lstrip("v")
+
+
+def _wordpress(_pkg: str, timeout: float) -> str:
+    return _get_json("https://api.wordpress.org/core/version-check/1.7/", timeout)["offers"][0][
+        "version"
+    ]
+
+
+FETCHERS: dict[str, Callable[[str, float], str]] = {
+    "npm": _npm,
+    "pypi": _pypi,
+    "go": _go,
+    "gotoolchain": _go_toolchain,
+    "github": _github,
+    "endoflife": _endoflife,
+    "k8s": _k8s,
+    "wordpress": _wordpress,
+}
+
+
+# --- pure layer (unit-testable, no IO) ---------------------------------------
+
+
+class SchemaError(ValueError):
+    pass
+
+
+def validate_entry(key: str, entry: object) -> None:
+    if not isinstance(entry, dict):
+        raise SchemaError(f"{key}: entry must be an object")
+    missing = [k for k in REQUIRED_KEYS if not entry.get(k)]
+    if missing:
+        raise SchemaError(f"{key}: missing required field(s): {', '.join(missing)}")
+    eco = entry["ecosystem"]
+    if eco not in FETCHERS:
+        raise SchemaError(
+            f"{key}: unknown ecosystem '{eco}' (known: {', '.join(sorted(FETCHERS))})"
+        )
+
+
+def is_drift(pinned: str, latest: str) -> bool:
+    return pinned.strip().lstrip("v") != latest.strip().lstrip("v")
+
+
+def load_manifest(path: Path) -> dict:
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise SchemaError(f"{path}: top level must be an object of {{key: entry}}")
+    for key, entry in raw.items():
+        validate_entry(key, entry)
+    return raw
+
+
+# --- IO layer ----------------------------------------------------------------
+
+
+def find_manifests(root: Path, skill: str | None) -> list[Path]:
+    found = sorted(
+        p
+        for p in root.rglob(VERSIONS_FILENAME)
+        if "node_modules" not in p.parts and ".venv" not in p.parts
+    )
+    if skill:
+        found = [p for p in found if skill in p.parts]
+    return found
+
+
+def _today() -> str:
+    return datetime.now(timezone.utc).date().isoformat()
+
+
+def refresh_manifest(
+    path: Path,
+    *,
+    offline: bool,
+    write: bool,
+    timeout: float,
+    log: Callable[[str], None],
+) -> list[dict]:
+    """Return one result row per entry; writes the file only when write=True."""
+    manifest = load_manifest(path)
+    rows: list[dict] = []
+    changed = False
+    for key, entry in manifest.items():
+        row = {
+            "manifest": str(path),
+            "key": key,
+            "package": entry["package"],
+            "ecosystem": entry["ecosystem"],
+            "pinned": entry["version"],
+        }
+        if offline:
+            row["status"] = "schema-ok"
+            rows.append(row)
+            continue
+        try:
+            if entry["ecosystem"] == "endoflife":
+                latest = _endoflife(entry["package"], timeout, entry.get("track"))
+            else:
+                latest = FETCHERS[entry["ecosystem"]](entry["package"], timeout)
+        except (urllib.error.URLError, KeyError, IndexError, TimeoutError, ValueError) as exc:
+            row["status"] = "unreachable"
+            row["error"] = f"{type(exc).__name__}: {exc}"
+            rows.append(row)
+            log(f"  ! {key}: unreachable ({type(exc).__name__})")
+            continue
+        row["latest"] = latest
+        if is_drift(entry["version"], latest):
+            row["status"] = "drift"
+            log(f"  ~ {key}: {entry['version']} -> {latest}")
+            if write:
+                entry["version"] = latest
+                entry["checked"] = _today()
+                changed = True
+        else:
+            row["status"] = "current"
+            if write:
+                entry["checked"] = _today()
+                changed = True
+        rows.append(row)
+    if write and changed:
+        path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        log(f"  + wrote {path}")
+    return rows
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--root", default=".", type=Path)
+    parser.add_argument("--skill", default=None)
+    parser.add_argument("--check", action="store_true", help="exit 1 on drift")
+    parser.add_argument("--write", action="store_true", help="rewrite drifted versions")
+    parser.add_argument("--offline", action="store_true", help="schema check only")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    parser.add_argument("--timeout", default=8.0, type=float)
+    args = parser.parse_args(argv)
+
+    if args.check and args.write:
+        print("error: --check and --write are mutually exclusive", file=sys.stderr)
+        return 2
+
+    def log(msg: str) -> None:
+        print(msg, file=sys.stderr)
+
+    manifests = find_manifests(args.root.resolve(), args.skill)
+    if not manifests:
+        log("no versions.json manifests found")
+        if args.as_json:
+            print(json.dumps({"manifests": 0, "rows": []}))
+        return 0
+
+    log(f"scanning {len(manifests)} manifest(s){' (offline)' if args.offline else ''}...")
+    all_rows: list[dict] = []
+    schema_failed = False
+    for i, path in enumerate(manifests, 1):
+        log(f"[{i}/{len(manifests)}] {path}")
+        try:
+            all_rows.extend(
+                refresh_manifest(
+                    path, offline=args.offline, write=args.write, timeout=args.timeout, log=log
+                )
+            )
+        except SchemaError as exc:
+            schema_failed = True
+            log(f"  SCHEMA ERROR: {exc}")
+
+    drift = [r for r in all_rows if r.get("status") == "drift"]
+    unreachable = [r for r in all_rows if r.get("status") == "unreachable"]
+    if args.as_json:
+        print(
+            json.dumps(
+                {
+                    "manifests": len(manifests),
+                    "drift": len(drift),
+                    "unreachable": len(unreachable),
+                    "rows": all_rows,
+                },
+                indent=2,
+            )
+        )
+    else:
+        log(
+            f"\nsummary: {len(all_rows)} entries · {len(drift)} drift · {len(unreachable)} unreachable"
+        )
+
+    if schema_failed:
+        return 1
+    if args.check and drift:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

scripts/regen_doc_index.py

@@ -0,0 +1,209 @@
+"""Regenerate `00-index.md` for a docs directory from frontmatter.
+
+INPUT:        <docs-dir> [--all] [--dry-run].
+OUTPUT:       rewrites each dir's 00-index.md between BEGIN/END markers; exit 1 on bad dir.
+DEPENDENCIES: docs/**/*.md frontmatter.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections import defaultdict
+from datetime import date
+from pathlib import Path
+
+# This script lives at src/scripts/; the package lives at src/core/thinking_os.
+# Resolve it explicitly so `tools.docs` imports under bare python3 (no PYTHONPATH).
+_REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+_THINKING_OS = _REPO_ROOT / "src" / "core" / "thinking_os"
+sys.path.insert(0, str(_THINKING_OS))
+sys.path.insert(0, str(_THINKING_OS.parent))
+
+from tools.docs import list_doc_headers
+
+BEGIN_MARKER = "<!-- BEGIN auto-index -->"
+END_MARKER = "<!-- END auto-index -->"
+
+# Layer ordering for the rendered index — most actionable first.
+_LAYER_ORDER = [
+    "index",
+    "policy",
+    "playbook",
+    "runbook",
+    "spec",
+    "adr",
+    "postmortem",
+    "reference",
+    "task",
+]
+
+
+def _layer_sort_key(layer: str) -> tuple[int, str]:
+    if layer in _LAYER_ORDER:
+        return (_LAYER_ORDER.index(layer), layer)
+    return (len(_LAYER_ORDER), layer)
+
+
+def _link_target(index_dir: Path, header_path: Path) -> str:
+    """Return a relative POSIX path from index_dir to header_path."""
+    try:
+        rel = header_path.resolve().relative_to(index_dir.resolve())
+    except ValueError:
+        # Different drives or unrelated trees — fall back to absolute.
+        return str(header_path)
+    return rel.as_posix()
+
+
+def _render_index(directory: Path, headers: list[dict]) -> str:
+    """Build the auto-index markdown body for `directory`."""
+    grouped: dict[str, list[dict]] = defaultdict(list)
+    for header in headers:
+        # Skip the index file itself if it parsed.
+        if Path(header["path"]).name == "00-index.md":
+            continue
+        layer = header["frontmatter"].get("layer") or "reference"
+        grouped[layer].append(header)
+
+    lines: list[str] = []
+    lines.append(BEGIN_MARKER)
+    if not grouped:
+        lines.append("")
+        lines.append("_No canonical-frontmatter docs in this directory yet._")
+        lines.append(END_MARKER)
+        return "\n".join(lines) + "\n"
+
+    for layer in sorted(grouped.keys(), key=_layer_sort_key):
+        rows = grouped[layer]
+        lines.append("")
+        lines.append(f"### {layer.title()} ({len(rows)})")
+        lines.append("")
+        for header in rows:
+            link = _link_target(directory, Path(header["path"]))
+            title = header["title"] or Path(header["path"]).stem
+            updated = header["frontmatter"].get("updated") or "n/a"
+            ssot = header["frontmatter"].get("ssot") or "ref"
+            tokens = header["frontmatter"].get("tokens")
+            tag = f"`ssot:{ssot}`"
+            if tokens:
+                tag += f" `~{tokens}t`"
+            lines.append(f"- [{title}]({link}) — {tag} · updated {updated}")
+    lines.append("")
+    lines.append(END_MARKER)
+    return "\n".join(lines) + "\n"
+
+
+def _splice_into_existing(existing: str, regenerated: str) -> str:
+    """Replace the auto-index fence inside `existing`, keep the rest.
+
+    Idempotent: the boundary newlines are normalised (one blank line before the
+    fence, the post-fence tail preserved) so repeated regens never accumulate
+    blank lines at the splice seams — the old `pre + regenerated + post` form
+    grew one trailing newline per run because both `regenerated` and `post`
+    carried the post-END_MARKER newline.
+    """
+    if BEGIN_MARKER not in existing or END_MARKER not in existing:
+        return regenerated
+    pre = existing.split(BEGIN_MARKER, 1)[0].rstrip("\n")
+    post = existing.split(END_MARKER, 1)[1].strip("\n")
+    block = regenerated.strip("\n")
+    out = f"{pre}\n\n{block}\n"
+    if post:
+        out += f"\n{post}\n"
+    return out
+
+
+def regenerate(directory: Path, *, write: bool = True) -> str | None:
+    """Regenerate `00-index.md` for one directory.
+
+    Returns the new file body, or None when the directory holds no
+    canonical-frontmatter docs (caller decides whether to warn).
+    """
+    headers = list_doc_headers(directory, limit=500)
+    headers = [h for h in headers if Path(h["path"]).parent.resolve() == directory.resolve()]
+    if not headers:
+        return None
+    auto_section = _render_index(directory, headers)
+    target = directory / "00-index.md"
+    if target.exists():
+        existing = target.read_text(encoding="utf-8")
+        new_body = _splice_into_existing(existing, auto_section)
+    else:
+        # First-time index — wrap with a minimal frontmatter so it follows
+        # docs-system.md’s Navigation Rules contract. Mixed-domain dirs
+        # (e.g. /benchmarks holding ALL + INFRA + CORE files) get
+        # `domain:ALL`. A homogeneous dir keeps its
+        # single domain so cos_doc_headers_by(domain=…) routing stays
+        # tight.
+        domains = {h["frontmatter"].get("domain", "DOCS") for h in headers}
+        if len(domains) > 1:
+            domain = "ALL"
+        else:
+            domain = next(iter(domains)) or "DOCS"
+        new_body = (
+            f"<!-- domain:{domain} | layer:index | ssot:true | updated:{date.today().isoformat()} -->\n"
+            f"# {directory.name} Index\n\n"
+            "Purpose: Auto-generated routing hub for this directory.\n"
+            "Read when: Locating the canonical doc for the active task.\n"
+            "Skip when: A higher-level index already routed you to the target file.\n"
+            "Read next: any of the entries below.\n\n"
+            "> Nav: [Docs Index](../00-index.md)\n\n"
+            f"{auto_section}"
+        )
+    if write:
+        # Atomic write: the auto-regen hook fires fire-and-forget, so
+        # two concurrent regens of one dir could interleave a partial write and
+        # corrupt 00-index. tmp-in-same-dir + replace() makes the swap atomic.
+        tmp = target.with_name(target.name + ".regen.tmp")
+        tmp.write_text(new_body, encoding="utf-8")
+        tmp.replace(target)
+    return new_body
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument(
+        "directory", nargs="?", default="docs", help="Directory to index (default: docs)"
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Print the regenerated index instead of writing"
+    )
+    parser.add_argument(
+        "--all", action="store_true", help="Recurse into every subdir with ≥2 frontmatter docs"
+    )
+    args = parser.parse_args(argv)
+
+    root = Path(args.directory)
+    if not root.is_dir():
+        print(f"ERROR: not a directory: {root}", file=sys.stderr)
+        return 1
+
+    targets: list[Path]
+    if args.all:
+        # Walk every subdir; only those with ≥2 canonical docs index.
+        targets = sorted(
+            {p.parent.resolve() for p in root.rglob("*.md") if p.name != "00-index.md"}
+        )
+    else:
+        targets = [root]
+
+    written = 0
+    skipped = 0
+    for directory in targets:
+        body = regenerate(directory, write=not args.dry_run)
+        if body is None:
+            print(f"WARN: no canonical-frontmatter docs in {directory} — skipped")
+            skipped += 1
+            continue
+        if args.dry_run:
+            print(f"--- {directory}/00-index.md ---")
+            print(body)
+        else:
+            print(f"OK: regenerated {directory}/00-index.md")
+        written += 1
+    print(f"INFO: {written} written, {skipped} skipped")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))