factorio-mod-workshop 0.1.0__py3-none-any.whl

fmw/cli.py

@@ -0,0 +1,1431 @@
+"""fmw command line interface.
+
+Every command accepts --json so an agent can consume structured output;
+without it the output is compact human-readable text.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+import yaml
+
+from . import discover, help as helptext, store, threadstate, tracker
+from .config import WORKSPACE_ENV, Workspace, WorkspaceError, template_dir
+from .portal import Portal, PortalError, abbrev_tag, parse_marker
+
+URL_RE = re.compile(r"mods\.factorio\.com/mod/([^/\s]+)(?:/discussion/([0-9a-f]{24}))?")
+
+
+def out(data, as_json: bool, text: str | None = None) -> None:
+    if as_json:
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+    elif text is not None:
+        print(text)
+
+
+def parse_target(value: str) -> tuple[str | None, str | None]:
+    """Accept a mod name, a thread id, or any mods.factorio.com URL."""
+    m = URL_RE.search(value)
+    if m:
+        return m.group(1), m.group(2)
+    if re.fullmatch(r"[0-9a-f]{24}", value):
+        return None, value
+    return value, None
+
+
+def with_marker(t: dict) -> dict:
+    """Annotate a cached thread summary with its derived title marker."""
+    m = parse_marker(t.get("title", ""))
+    return {
+        **t,
+        "marker": m.marker,
+        "resolved_on_portal": m.resolved,
+        "wrong_on_portal": m.wrong,
+        "clean_title": m.clean,
+    }
+
+
+class Detection(NamedTuple):
+    mod: str | None
+    source: str          # how it was determined, for the announcement
+    candidates: list     # mods below cwd when the answer was ambiguous
+
+
+def detect_mod_from_cwd(ws: Workspace, start: Path | None = None) -> Detection:
+    """Infer which mod the user is working on from the current directory.
+
+    Three cases, in order of confidence:
+
+    1. An info.json in the cwd or an ancestor - that is what defines a mod.
+    2. The cwd sits inside a checkout recorded by `fmi discover`.
+    3. The cwd *contains* exactly one recorded checkout. This is the normal
+       Factorio single-mod repository, where the git root wraps a directory
+       that must be named after the mod. Ambiguous when the cwd contains
+       several - a monorepo root - and then no mod is inferred.
+    """
+    cwd = (start or Path.cwd()).resolve()
+    for d in [cwd, *cwd.parents]:
+        info = d / "info.json"
+        if info.is_file():
+            try:
+                name = json.loads(info.read_text()).get("name")
+            except (json.JSONDecodeError, UnicodeDecodeError, OSError):
+                name = None
+            if name:
+                return Detection(name, str(info), [])
+
+    paths = {name: Path(p).resolve() for name, p in ws.load_paths().items() if p}
+    for name, path in paths.items():
+        if cwd == path or path in cwd.parents:
+            return Detection(name, str(path), [])
+
+    below = sorted(name for name, path in paths.items() if cwd in path.parents)
+    if len(below) == 1:
+        return Detection(below[0], f"the only mod under {cwd}", below)
+    return Detection(None, "", below)
+
+
+def announce(detection: Detection, stream=None) -> None:
+    """Say which scope was chosen, including when nothing was inferred.
+
+    Silence on the fallback path is how a plausible answer about the wrong
+    scope goes unnoticed, so both branches report.
+    """
+    stream = stream or sys.stderr
+    if detection.mod:
+        print(f"(using {detection.mod}, detected from {detection.source})", file=stream)
+    elif detection.candidates:
+        print(f"(cwd contains {len(detection.candidates)} mods - too ambiguous to narrow; "
+              "name one explicitly)", file=stream)
+
+
+def open_ws(args) -> Workspace:
+    try:
+        return Workspace.open(getattr(args, "workspace", None))
+    except WorkspaceError as exc:
+        sys.exit(str(exc))
+
+
+def resolve_mods(ws: Workspace, names: list[str], all_flag: bool, quiet: bool = False) -> list[str]:
+    registry = ws.load_mods()["mods"]
+    if not names and not all_flag:
+        # Working inside a mod checkout is a clear enough signal to act on just
+        # that mod. Always say which way it went, so neither the narrow scope
+        # nor the fallback to every mod is a surprise.
+        detection = detect_mod_from_cwd(ws)
+        if not quiet:
+            announce(detection)
+        if detection.mod:
+            return [detection.mod]
+    if all_flag or not names:
+        chosen = [n for n, m in registry.items() if m.get("on_portal") is not False]
+        if not all_flag and not names:
+            chosen = [n for n in chosen if registry[n].get("maintained") != "frozen"]
+        return chosen
+    resolved = []
+    for n in names:
+        mod, _ = parse_target(n)
+        if mod:
+            resolved.append(mod)
+    return resolved
+
+
+# ----------------------------------------------------------------------
+# commands
+# ----------------------------------------------------------------------
+def cmd_init(args) -> None:
+    path = Path(args.path).expanduser().resolve()
+    copied, skipped = [], []
+    with template_dir() as template:
+        if not template.is_dir():
+            sys.exit(f"Bundled template directory is missing or unreadable: {template}")
+        for src in sorted(template.rglob("*")):
+            if src.is_dir():
+                continue
+            rel = src.relative_to(template)
+            dst = path / rel
+            if dst.exists():
+                skipped.append(str(rel))
+                continue
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dst)
+            copied.append(str(rel))
+    if not copied and not skipped:
+        sys.exit("Bundled template directory is empty - the installation is broken.")
+    for sub in ("cache", "tracker", "notes"):
+        (path / sub).mkdir(parents=True, exist_ok=True)
+
+    if args.json:
+        out({"workspace": str(path), "copied": copied, "kept": skipped}, True)
+        return
+    print(f"Workspace ready at {path}")
+    for rel in copied:
+        print(f"  + {rel}")
+    for rel in skipped:
+        print(f"  = {rel} (kept, already present)")
+    print("\nNext:")
+    print(f"  fmw launcher --workspace {path}   # one-time: puts `fmw` on your PATH, pinned to this workspace")
+    print(f"  $EDITOR {path / 'config.yaml'}   # set mod_repos")
+    print("  fmw discover")
+    if not (path / ".git").exists():
+        print("\nTip: `git init` inside it to version your mod data separately.")
+
+
+WINDOWS = os.name == "nt"
+
+# Pins a workspace so `fmw` runs from anywhere - typically from inside a mod
+# repository - without setting FMW_WORKSPACE by hand. A value already in the
+# environment still wins, so one-off overrides keep working.
+LAUNCHER_SH = """#!/usr/bin/env sh
+# Generated by `fmw launcher`. Regenerate if either directory moves.
+# POSIX sh, so it works under bash, zsh, dash, ash and friends.
+set -e
+
+: "${{FMW_WORKSPACE:={workspace}}}"
+export FMW_WORKSPACE
+
+exec {runner} "$@"
+"""
+
+LAUNCHER_CMD = """@echo off
+rem Generated by `fmw launcher`. Regenerate if either directory moves.
+if not defined FMW_WORKSPACE set "FMW_WORKSPACE={workspace}"
+{runner} %*
+"""
+
+
+def _path_dirs() -> list[Path]:
+    return [Path(p).expanduser() for p in os.environ.get("PATH", "").split(os.pathsep) if p]
+
+
+def _bin_candidates() -> list[Path]:
+    """Conventional per-user executable directories for this platform."""
+    if WINDOWS:
+        # Where `uv tool install` places shims, plus the Unix-style fallback
+        # uv also honours.
+        appdata = os.environ.get("APPDATA")
+        dirs = [Path(appdata) / "uv" / "bin"] if appdata else []
+        return dirs + [Path.home() / ".local" / "bin"]
+    return [Path.home() / ".local" / "bin", Path.home() / "bin"]
+
+
+def _default_bin_dir() -> tuple[Path, bool]:
+    """Pick a directory to install the launcher into, and whether it is on PATH."""
+    on_path = _path_dirs()
+    for candidate in _bin_candidates():
+        if candidate in on_path:
+            return candidate, True
+    return _bin_candidates()[0], False
+
+
+def _path_hint(directory: Path) -> str:
+    """How to put `directory` on PATH, in the user's actual shell."""
+    if WINDOWS:
+        return f'  setx PATH "%PATH%;{directory}"'
+    shell = Path(os.environ.get("SHELL", "sh")).name
+    profile = {
+        "zsh": "~/.zshrc",
+        "bash": "~/.bashrc",
+        "fish": "~/.config/fish/config.fish",
+    }.get(shell, "your shell profile")
+    if shell == "fish":
+        return f"  fish_add_path {directory}"
+    return f"  echo 'export PATH=\"{directory}:$PATH\"' >> {profile}"
+
+
+def _is_ephemeral_install(path: Path) -> bool:
+    """True if the interpreter lives in a throwaway environment.
+
+    `uvx` builds the package into ~/.cache/uv/archive-v0/<hash>/ and that
+    directory is removed by `uv cache prune`, so baking its path into a
+    launcher produces a wrapper that works until the next cache cleanup.
+    """
+    return "archive-v0" in path.parts
+
+
+def _under_uv_tool_dir(path: Path) -> bool:
+    """True if `path` belongs to a `uv tool install` environment."""
+    roots = []
+    env = os.environ.get("UV_TOOL_DIR")
+    if env:
+        roots.append(Path(env).expanduser())
+    if WINDOWS:
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            roots.append(Path(appdata) / "uv" / "tools")
+    else:
+        roots.append(Path.home() / ".local" / "share" / "uv" / "tools")
+    for root in roots:
+        try:
+            path.relative_to(root.resolve())
+            return True
+        except (ValueError, OSError):
+            continue
+    return False
+
+
+def cmd_launcher(args) -> None:
+    ws = open_ws(args)
+    venv_bin = Path(sys.executable).parent
+    if _is_ephemeral_install(venv_bin):
+        sys.exit(
+            f"Refusing to write a launcher pointing at {venv_bin}.\n"
+            "This looks like an ephemeral `uvx` environment, which `uv cache prune` "
+            "deletes - the launcher would break silently.\n"
+            "For a persistent install use:  uv tool install "
+            "git+https://github.com/AivanF/factorio-mod-workshop\n"
+            f"then set the workspace with:  export FMW_WORKSPACE={ws.root}"
+        )
+    console = venv_bin / ("fmw.exe" if WINDOWS else "fmw")
+    runner = f'"{console}"' if console.exists() else f'"{sys.executable}" -m fmw.cli'
+
+    warn_path = False
+    if args.out:
+        dest = Path(args.out).expanduser()
+    else:
+        bin_dir, on_path = _default_bin_dir()
+        warn_path = not on_path
+        dest = bin_dir / (f"{args.name}.cmd" if WINDOWS else args.name)
+
+    if dest.exists() and not args.force:
+        extra = ""
+        if dest.is_symlink() and _under_uv_tool_dir(dest.resolve()):
+            extra = (
+                "\nThat is the shim from `uv tool install`, so `fmw` already works everywhere; "
+                f"you only need the workspace:\n  export FMW_WORKSPACE={ws.root}\n"
+                "Or install this wrapper under another name with --name."
+            )
+        sys.exit(
+            f"{dest} already exists. Pass --force to overwrite, or --out/--name to "
+            f"choose another.{extra}"
+        )
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    template = LAUNCHER_CMD if WINDOWS else LAUNCHER_SH
+    dest.write_text(template.format(workspace=ws.root, runner=runner))
+    if not WINDOWS:
+        dest.chmod(0o755)
+
+    if args.json:
+        out({"launcher": str(dest), "workspace": str(ws.root), "runner": runner,
+             "on_path": not warn_path}, True)
+        return
+    print(f"Installed {dest}")
+    print(f"  workspace: {ws.root}")
+    print(f"  runner:    {runner}")
+    if warn_path:
+        print(f"\n{dest.parent} is not on your PATH. Add it:")
+        print(_path_hint(dest.parent))
+    else:
+        print(f"\n`{dest.name}` is now runnable from any directory.")
+
+
+# Files `fmw init` copies that stay owned by the tool: they document the current
+# schema, so a workspace created before a schema change keeps teaching the old
+# one. config.yaml is deliberately absent - it becomes yours on first edit.
+TEMPLATE_MANAGED = ("README.md", "tracker/README.md", "config.example.yaml", ".gitignore")
+
+
+def outdated_template_files(ws) -> list[str]:
+    stale = []
+    with template_dir() as template:
+        if not template.is_dir():
+            return []
+        for rel in TEMPLATE_MANAGED:
+            src, dst = template / rel, ws.root / rel
+            if not src.is_file():
+                continue
+            if not dst.exists() or dst.read_text() != src.read_text():
+                stale.append(rel)
+    return stale
+
+
+def cmd_upgrade(args) -> None:
+    """Refresh the tool-owned documentation inside a workspace.
+
+    Only files listed in TEMPLATE_MANAGED are touched; your registry, tickets,
+    thread judgements, cache and config.yaml are never rewritten.
+    """
+    ws = open_ws(args)
+    changed = []
+    with template_dir() as template:
+        if not template.is_dir():
+            sys.exit(f"Bundled templates not found: {template}")
+        for rel in TEMPLATE_MANAGED:
+            src, dst = template / rel, ws.root / rel
+            if not src.is_file():
+                continue
+            new_text = src.read_text()
+            if dst.exists() and dst.read_text() == new_text:
+                continue
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            action = "updated" if dst.exists() else "added"
+            if not args.dry_run:
+                dst.write_text(new_text)
+            changed.append(f"{action} {rel}")
+    # mods.yaml: bring `maintained` onto the current vocabulary.
+    registry = ws.load_mods()          # load_mods already normalises on read
+    raw = yaml.safe_load(ws.mods_file.read_text()) if ws.mods_file.exists() else None
+    if raw:
+        for name, entry in (raw.get("mods") or {}).items():
+            before = entry.get("maintained")
+            after = discover.normalise_maintained(before)
+            if before != after:
+                changed.append(f"maintained: {name}  {before!r} -> {after}")
+    if not args.dry_run and any(c.startswith("maintained:") for c in changed):
+        ws.save_mods(registry)
+
+    ticket_changes = migrate_tickets(ws, dry_run=args.dry_run)
+    changed += [f"ticket {old} -> {new}" for old, new in ticket_changes]
+
+    if args.json:
+        out({"changed": changed, "dry_run": args.dry_run}, True)
+        return
+    for c in changed:
+        print(f"  {c}")
+    if not changed:
+        print("Workspace is already current.")
+    elif args.dry_run:
+        print(f"{len(changed)} change(s) pending. Re-run without --dry-run.")
+    else:
+        print(f"{len(changed)} change(s) applied. Your tickets, judgements and cache "
+              "keep their content.")
+
+
+def cmd_repo(args) -> None:
+    """Manage the directories `fmw discover` looks in."""
+    ws = open_ws(args)
+    if args.repo_cmd == "add":
+        path = Path(args.path).expanduser()
+        if not path.is_dir():
+            sys.exit(f"Not a directory: {path}")
+        found, _ = discover.scan_local([path])
+        repos = ws.edit_mod_repos(add=args.path)
+        if args.json:
+            out({"repos": repos, "found": [e["name"] for e in found]}, True)
+            return
+        print(f"Added {args.path} ({len(found)} mod(s) found)")
+        for e in found:
+            print(f"  {e['name']}  {e['local_version']}")
+        print("\nRun `fmw discover` to add them to the registry.")
+        return
+
+    if args.repo_cmd == "remove":
+        before = ws.mod_repos()
+        repos = ws.edit_mod_repos(remove=args.path)
+        if args.json:
+            out({"repos": repos, "removed": len(before) - len(repos)}, True)
+            return
+        if len(repos) == len(before):
+            print(f"{args.path} was not listed. Current repositories:")
+            for r in repos:
+                print(f"  {r}")
+        else:
+            print(f"Removed {args.path}. Registry entries are kept - "
+                  "delete them from mods.yaml if you want them gone.")
+        return
+
+    repos = ws.mod_repos()
+    paths = ws.load_paths()
+    if args.json:
+        out({"repos": [
+            {"path": r,
+             "mods": sorted(n for n, p in paths.items()
+                            if str(Path(p)).startswith(str(Path(r).expanduser().resolve())))}
+            for r in repos]}, True)
+        return
+    if not repos:
+        print("No repositories configured. Add one with `fmw repo add <path>`.")
+        return
+    for r in repos:
+        root = str(Path(r).expanduser().resolve())
+        mods = sorted(n for n, p in paths.items() if str(Path(p)).startswith(root))
+        print(f"{r}")
+        print(f"  {len(mods)} mod(s): {', '.join(mods) if mods else '- run `fmw discover`'}")
+
+
+def cmd_discover(args) -> None:
+    ws = open_ws(args)
+    roots = [Path(r) for r in args.scan] if args.scan else []
+    if not roots:
+        cfg = ws.load_config()
+        roots = [Path(r) for r in (cfg.get("mod_repos") or [])]
+    if not roots:
+        sys.exit("Nothing to scan. Pass --scan DIR or set mod_repos in workspace/config.yaml")
+
+    entries, warnings = discover.scan_local(roots, max_depth=args.max_depth)
+    if not args.no_portal:
+        with Portal() as portal:
+            warnings += discover.enrich_from_portal(portal, entries)
+
+    paths = discover.sync_paths(ws, entries)
+    registry = discover.build_registry(ws.load_mods(), entries)
+    discover.strip_legacy_paths(registry)
+    ws.save_mods(registry)
+
+    if args.json:
+        out({"found": len(entries), "warnings": warnings,
+             "mods": registry["mods"], "paths": paths}, True)
+        return
+    print(f"Registered {len(entries)} mods in {ws.mods_file}")
+    print(f"Local checkout paths in {ws.paths_file}")
+    for w in warnings:
+        print(f"  ! {w}")
+    print("Review `maintained:` (active/frozen/unknown) and `notes:` for each mod.")
+
+
+def cmd_mods(args) -> None:
+    ws = open_ws(args)
+    mods = ws.load_mods()["mods"]
+    if args.maintained:
+        mods = {k: v for k, v in mods.items() if v.get("maintained") == args.maintained}
+    if args.json:
+        paths = ws.load_paths()
+        out({k: {**v, "path": paths.get(k, "")} for k, v in mods.items()}, True)
+        return
+
+    def cell(value) -> str:
+        return str(value) if value not in (None, "", 0) else "-"
+
+    # Single-row header: a two-row one with spanning labels falls apart as soon
+    # as the terminal wraps. Abbreviations are expanded in the legend below.
+    print(
+        f"{'':<2}{'mod':<38} {'maint':<8} {'v.loc':<9} {'v.mp':<9} "
+        f"{'F.loc':<6} {'F.mp':<6} {'dl':>9}"
+    )
+    differing = 0
+    for name, m in mods.items():
+        loc, mp = m.get("local_version"), m.get("portal_version")
+        # Only flag it. Why the two differ is not inferable: unreleased work,
+        # an out-of-date checkout, or a deliberate local edit all look alike.
+        mark = ""
+        if loc and mp and loc != mp:
+            mark = "~"
+            differing += 1
+        print(
+            f"{mark:<2}{name:<38} {str(m.get('maintained', '?')):<8} "
+            f"{cell(loc):<9} {cell(mp):<9} "
+            f"{cell(m.get('factorio_version')):<6} {cell(m.get('portal_factorio_version')):<6} "
+            f"{cell(m.get('downloads')):>9}"
+        )
+    print(f"\n{len(mods)} mods   "
+          "v = mod version, F = Factorio version, loc = local checkout, "
+          "mp = mod portal, dl = downloads")
+    if differing:
+        print(f"~ = local and published versions differ ({differing} mods). Reasons vary and are "
+              "not inferable from the numbers - ask the maintainer before changing such a checkout.")
+
+    unchecked = [
+        n for n, m in mods.items()
+        if m.get("on_portal") is not False and not m.get("portal_version")
+    ]
+    if unchecked:
+        print(
+            f"{len(unchecked)} mods have no portal data yet (portal columns show '-'). "
+            "Run `fmw discover` without --no-portal to fill them in."
+        )
+    unpublished = [n for n, m in mods.items() if m.get("on_portal") is False]
+    if unpublished:
+        print(f"Not published on the portal: {', '.join(unpublished)}")
+
+
+def cmd_sync(args) -> None:
+    ws = open_ws(args)
+    names = resolve_mods(ws, args.mods, args.all)
+    if not names:
+        sys.exit("No mods selected. Run `fmw discover` first, or name a mod explicitly.")
+
+    report: dict = {"mods": {}}
+    with Portal() as portal:
+        for mod in names:
+            try:
+                threads, warns = portal.thread_list(mod)
+            except PortalError as exc:
+                report["mods"][mod] = {"error": str(exc)}
+                if not args.json:
+                    print(f"{mod}: ERROR {exc}")
+                continue
+
+            changes = store.diff_lists(store.load_list(ws, mod), threads)
+            store.save_list(ws, mod, threads, warns)
+            store.append_changelog(ws, mod, changes)
+
+            fetched = []
+            if not args.no_threads:
+                have = store.cached_thread_ids(ws, mod)
+                touched = {c["id"] for c in changes}
+                todo = [t for t in threads if t.id in touched or t.id not in have]
+                for t in todo:
+                    store.save_thread(ws, portal.thread(mod, t.id))
+                    fetched.append(t.id)
+
+            drift = _status_drift(ws, mod, threads)
+            report["mods"][mod] = {
+                "threads": len(threads),
+                "changes": changes,
+                "fetched": fetched,
+                "warnings": warns,
+                "drift": drift,
+            }
+            if not args.json:
+                head = f"{mod}: {len(threads)} threads"
+                if changes:
+                    head += f", {len(changes)} change(s)"
+                print(head)
+                for c in changes:
+                    mark = "NEW " if c["kind"] == "new_thread" else "REPLY"
+                    print(f"  {mark} [{c.get('tag','')}] {c['title']}  ({c.get('author')}, {c.get('at','')[:16]})")
+                    print(f"        https://mods.factorio.com/mod/{mod}/discussion/{c['id']}")
+                for w in warns:
+                    print(f"  ! {w}")
+                for d in drift:
+                    print(f"  ~ {d}")
+    if args.json:
+        out(report, True)
+
+
+def require_mod(ws: Workspace, value: str | None) -> str:
+    """A mod name from the argument, or inferred from the current directory."""
+    if value:
+        mod, _ = parse_target(value)
+        if mod:
+            return mod
+    detection = detect_mod_from_cwd(ws)
+    announce(detection)
+    if detection.mod:
+        return detection.mod
+    sys.exit("No mod given, and the current directory does not identify one.")
+
+
+def _status_drift(ws, mod: str, threads) -> list[str]:
+    """Where the portal title and the ticket disagree about being done.
+
+    The two are maintained by hand in different places, so they drift; each
+    direction means a different piece of unfinished work.
+    """
+    index = tracker.index_by_thread(tracker.load_all(ws, mod))
+    notes: list[str] = []
+    for t in threads:
+        tickets = index.get(t.id)
+        if not tickets:
+            continue
+        m = parse_marker(t.title)
+        open_ones = [i for i in tickets if i.meta.get("status") in tracker.open_statuses()]
+        if m.resolved and open_ones:
+            notes.append(
+                f"thread marked '{m.marker}' but ticket "
+                f"{', '.join(i.id for i in open_ones)} is still open: {m.clean[:44]}"
+            )
+        elif not m.resolved and tickets and not open_ones:
+            notes.append(
+                f"ticket {', '.join(i.id for i in tickets)} is done but the thread "
+                f"is not marked: {m.clean[:44]}"
+            )
+    return notes
+
+
+def cmd_threads(args) -> None:
+    ws = open_ws(args)
+    mod = require_mod(ws, args.mod)
+    data = store.load_list(ws, mod)
+    if not data:
+        sys.exit(f"No cached threads for {mod}. Run `fmw sync {mod}` first.")
+    threads = data["threads"]
+    if args.tag:
+        want = args.tag.lower()
+        threads = [t for t in threads
+                   if t["tag"].lower().startswith(want) or abbrev_tag(t["tag"]).startswith(want)]
+    if args.limit:
+        threads = threads[: args.limit]
+
+    index = tracker.index_by_thread(tracker.load_all(ws, mod))
+    states = threadstate.load(ws, mod)
+
+    if args.json:
+        out({
+            "mod": mod,
+            "fetched_at": data["fetched_at"],
+            "threads": [
+                {**with_marker(t),
+                 "state": states.get(t["id"], threadstate.ThreadState()).to_dict(),
+                 "tickets": [{"id": i.id, "kind": i.meta.get("kind", ""),
+                              "status": i.meta.get("status", ""),
+                              "title": i.meta.get("title", "")}
+                             for i in index.get(t["id"], [])]}
+                for t in threads
+            ],
+        }, True)
+        return
+
+    print(f"{mod} - {len(threads)} threads (cached {data['fetched_at'][:16]})")
+    print(f"{'tag':<5} {'last-msg':<11} {'re':>2}  title")
+    for t in threads:
+        # The title is printed verbatim: any [FIXED] / (fixed) marker is part
+        # of it, so a separate resolved flag would only restate what is there.
+        print(f"{abbrev_tag(t['tag']):<5} {t['last_at'][:10]:<11} {t['reply_count']:>2}  {t['title']}")
+        st = states.get(t["id"], threadstate.ThreadState())
+        bits = [b for b in (st.triage if st.triage != "pending" else "", st.cls) if b]
+        if st.needs_response:
+            bits.append("needs-response")
+        if st.duplicate_of:
+            bits.append(f"dup-of {st.duplicate_of}")
+        suffix = f"  [{', '.join(bits)}]" if bits else ""
+        print(f"{'':<5} {t['id']}  by {t['author']}{suffix}")
+        for i in index.get(t["id"], []):
+            state = f"{i.meta.get('kind','?')}/{i.meta.get('status','?')}"
+            print(f"{'':<5} -> {i.id}  {state:<21} {i.meta.get('title','')}")
+    print("\nre = replies, last-msg = newest message, -> = ticket citing this thread")
+
+
+def cmd_thread(args) -> None:
+    ws = open_ws(args)
+    mod, tid = parse_target(args.target)
+    if tid is None:
+        sys.exit("Give a thread id or a discussion URL.")
+    if mod is None:
+        mod = store.find_thread_mod(ws, tid)
+    data = None
+    if not args.refresh and mod:
+        data = store.load_thread(ws, mod, tid)
+    if data is None:
+        if not mod:
+            sys.exit(
+                "Unknown thread: not in the cache and no mod given. "
+                "Pass the full discussion URL, or run `fmw sync <mod>` first."
+            )
+        with Portal() as portal:
+            thread = portal.thread(mod, tid)
+        store.save_thread(ws, thread)
+        data = store.load_thread(ws, mod, tid)
+
+    if args.json:
+        out(data, True)
+        return
+    print(f"# {data['title']}")
+    print(f"_{data['mod']} - {data['tag']} - {data['url']}_\n")
+    for m in data["messages"]:
+        edited = f" (edited {m['edited_at'][:16]})" if m.get("edited_at") else ""
+        print(f"## {m['author']} - {m['posted_at'][:16]}{edited}")
+        print(m["body"])
+        print()
+
+
+def cmd_changes(args) -> None:
+    ws = open_ws(args)
+    names = resolve_mods(ws, args.mods, args.all)
+    records = []
+    for mod in names:
+        records.extend(store.read_changelog(ws, mod, args.since))
+    records.sort(key=lambda r: r.get("at") or "", reverse=True)
+    if args.json:
+        out(records, True)
+        return
+    if not records:
+        print("No recorded changes." + (f" (since {args.since})" if args.since else ""))
+        return
+    print(f"{'seen':<11} {'posted':<11} what")
+    for r in records:
+        mark = "NEW  " if r["kind"] == "new_thread" else "REPLY"
+        print(f"{r.get('seen_at','')[:10]:<11} {r.get('at','')[:10]:<11} "
+              f"{mark} {r['mod']} [{abbrev_tag(r.get('tag',''))}] {r['title']}")
+        print(f"{'':<23}https://mods.factorio.com/mod/{r['mod']}/discussion/{r['id']}")
+    print("\nseen = when fmw detected it (what --since filters on), "
+          "posted = when the message was written")
+
+
+def cmd_track_new(args) -> None:
+    ws = open_ws(args)
+    mod, tid = parse_target(args.target) if args.target else (None, None)
+    if tid and not mod:
+        mod = store.find_thread_mod(ws, tid)
+    if not mod:
+        mod = require_mod(ws, None)
+
+    sources = list(args.source or [])
+    extra: dict = {}
+    title = args.title
+    if tid:
+        sources.append(f"portal:{tid}")
+        cached = store.load_thread(ws, mod, tid)
+        if cached:
+            m = parse_marker(cached.get("title", ""))
+            # Default the title to the thread's, minus the maintainer's marker,
+            # so creating a ticket from a thread needs no retyping.
+            title = title or m.clean
+            extra["portal_tag"] = cached.get("tag", "")
+            if m.marker:
+                extra["portal_marker"] = m.marker
+                extra["portal_resolved"] = m.resolved
+    if not title:
+        sys.exit("Give a title, or a thread whose title can be used.")
+
+    mods = [mod] + [m for m in (args.also or []) if m != mod]
+    item = tracker.create(
+        ws, mods=mods, title=title, kind=args.kind, status=args.status,
+        sources=sources, extra=extra or None,
+    )
+    if args.json:
+        out({**item.meta, "path": str(item.path)}, True)
+        return
+    print(f"{item.id}  {item.path}")
+
+
+def migrate_tickets(ws, dry_run: bool = False) -> list:
+    """Bring tickets written by earlier versions up to the current schema."""
+    items = tracker.load_all(ws)
+    taken = {i.id for i in items if tracker.ID_RE.match(i.id)}
+    changed, warnings = [], []
+    for item in items:
+        before = dict(item.meta)
+        if "mod" in item.meta:
+            item.meta = {("mods" if k == "mod" else k):
+                         ([v] if k == "mod" else v) for k, v in item.meta.items()}
+        kind = item.meta.get("kind")
+        if kind in tracker.LEGACY_KINDS:
+            item.meta["kind"] = tracker.LEGACY_KINDS[kind]
+        elif kind and kind not in tracker.KINDS:
+            warnings.append(f"{item.id}: kind {kind!r} has no equivalent - set it by hand")
+        old_path = item.path
+        if not tracker.ID_RE.match(str(item.meta.get("id", ""))):
+            ident = tracker.new_id(taken)
+            taken.add(ident)
+            item.meta["id"] = ident
+            item.path = old_path.parent / f"{ident}-{tracker.slugify(item.meta.get('title',''), 40)}.md"
+        if item.meta != before or item.path != old_path:
+            if not dry_run:
+                item.save()
+                if item.path != old_path:
+                    old_path.unlink()
+            changed.append((str(old_path.name), str(item.path.name)))
+    return changed
+
+
+def cmd_track_list(args) -> None:
+    ws = open_ws(args)
+    mod = args.mod
+    if not mod:
+        detection = detect_mod_from_cwd(ws)
+        if not args.json:
+            announce(detection)
+        mod = detection.mod
+    items = tracker.load_all(ws, mod)
+    if args.kind:
+        items = [i for i in items if i.meta.get("kind") == args.kind]
+    if args.status:
+        items = [i for i in items if i.meta.get("status") == args.status]
+    elif args.open:
+        items = [i for i in items if i.meta.get("status") in tracker.open_statuses()]
+    if args.json:
+        out([{**i.meta, "path": str(i.path)} for i in items], True)
+        return
+    for i in items:
+        mods = "+".join(i.mods)
+        print(f"{i.id}  [{i.meta.get('kind','?'):<7}] [{i.meta.get('status','?'):<12}] {mods:<30} {i.meta.get('title','')}")
+    print(f"\n{len(items)} items")
+
+
+def cmd_testplan(args) -> None:
+    """Collect every awaiting-test fix into one document.
+
+    Each Factorio run is expensive, so the point is to verify a batch of fixes
+    in a single session rather than one per fix.
+    """
+    ws = open_ws(args)
+    mods = resolve_mods(ws, args.mods, args.all, quiet=args.json)
+    batch: list[dict] = []
+    for mod in mods:
+        for item in tracker.load_all(ws, mod):
+            if item.meta.get("status") != "needs-testing":
+                continue
+            batch.append(
+                {
+                    "mod": mod,
+                    "id": item.id,
+                    "title": item.meta.get("title", item.id),
+                    "kind": item.meta.get("kind", ""),
+                    "severity": item.meta.get("severity", ""),
+                    "fixed_in": item.meta.get("fixed_in", ""),
+                    "path": str(item.path),
+                    "plan": tracker.test_plan(item),
+                    "threads": sorted(item.portal_threads()),
+                }
+            )
+
+    if args.json:
+        out({"items": batch, "mods": sorted({b["mod"] for b in batch})}, True)
+        return
+    if not batch:
+        print("Nothing awaiting testing. Set an item's status to `needs-testing` once it is fixed but unverified.")
+        return
+
+    by_mod: dict[str, list[dict]] = {}
+    for b in batch:
+        by_mod.setdefault(b["mod"], []).append(b)
+
+    print(f"# Test plan - {len(batch)} fix(es) across {len(by_mod)} mod(s)\n")
+    for mod, items in by_mod.items():
+        version = ws.load_mods()["mods"].get(mod, {}).get("local_version", "")
+        print(f"## {mod}" + (f" (local {version})" if version else ""))
+        paths = ws.load_paths()
+        if paths.get(mod):
+            print(f"_{paths[mod]}_")
+        print()
+        for i, b in enumerate(items, 1):
+            head = f"{i}. {b['title']}"
+            tags = [t for t in (b["kind"], b["severity"]) if t]
+            if tags:
+                head += f"  [{', '.join(tags)}]"
+            print(head)
+            print(b["plan"] and indent(b["plan"]) or "   _no test plan written yet_")
+            for tid in b["threads"]:
+                print(f"   thread: https://mods.factorio.com/mod/{mod}/discussion/{tid}")
+            print(f"   item:   {b['path']}")
+            print()
+    print("After verifying, set each item to `status: fixed`, then `released` once published.")
+
+
+def indent(text: str, prefix: str = "   ") -> str:
+    return "\n".join(prefix + line if line.strip() else line for line in text.splitlines())
+
+
+def _changes_from(args) -> dict:
+    changes: dict = {}
+    if args.triage:
+        changes["triage"] = args.triage
+    if args.set_class:
+        changes["cls"] = args.set_class
+    if args.note is not None:
+        changes["note"] = args.note
+    if args.needs_response:
+        changes["needs_response"] = True
+    if args.responded:
+        changes["needs_response"] = False
+    return changes
+
+
+def cmd_mark_bulk(args) -> None:
+    """Apply one judgement to every pending thread older than a cutoff.
+
+    Long-dormant threads accumulate faster than they can be reviewed one at a
+    time; without a bulk path the inbox never empties and stops being trusted.
+    """
+    ws = open_ws(args)
+    changes = _changes_from(args)
+    if not changes:
+        sys.exit("Give something to set, e.g. --triage handled.")
+    touched: list[dict] = []
+    mods = resolve_mods(ws, args.targets, args.all, quiet=args.json)
+    if not args.targets and not args.all:
+        print(f"Sweeping {len(mods)} mod(s). Name mods explicitly, or --all to be sure.",
+              file=sys.stderr)
+    for mod in mods:
+        data = store.load_list(ws, mod)
+        if not data:
+            continue
+        states = threadstate.load(ws, mod)
+        for t in data["threads"]:
+            if t["last_at"][:10] >= args.before:
+                continue
+            st = states.get(t["id"], threadstate.ThreadState())
+            if st.triage != "pending" or st.needs_response:
+                continue  # never silently overwrite a decision already made
+            if args.tag and not t["tag"].lower().startswith(args.tag.lower()):
+                continue
+            for key, value in changes.items():
+                setattr(st, key, value)
+            states[t["id"]] = st
+            touched.append({"mod": mod, "id": t["id"], "title": t["title"]})
+        threadstate.save(ws, mod, states)
+
+    if args.json:
+        out({"changed": touched, "count": len(touched)}, True)
+        return
+    for t in touched[:10]:
+        print(f"  {t['mod']} {t['id']}  {t['title'][:56]}")
+    if len(touched) > 10:
+        print(f"  ... and {len(touched) - 10} more")
+    print(f"{len(touched)} thread(s) updated (already-decided threads left alone)")
+
+
+def cmd_mark(args) -> None:
+    """Record your judgement about a thread."""
+    ws = open_ws(args)
+    if args.before:
+        return cmd_mark_bulk(args)
+    if len(args.targets) != 1:
+        sys.exit("Give exactly one thread id or URL, or --before DATE for a bulk update.")
+    mod, tid = parse_target(args.targets[0])
+    if not tid:
+        sys.exit("Give a thread id or a discussion URL.")
+    if not mod:
+        mod = store.find_thread_mod(ws, tid)
+    if not mod:
+        sys.exit(f"Thread {tid} is not in the cache. Run `fmw sync` first.")
+
+    changes: dict = {}
+    if args.triage:
+        changes["triage"] = args.triage
+    if args.set_class:
+        changes["cls"] = args.set_class
+    if args.note is not None:
+        changes["note"] = args.note
+    if args.duplicate_of:
+        changes["duplicate_of"] = args.duplicate_of
+        changes.setdefault("cls", "duplicate")
+        changes.setdefault("triage", "handled")
+    if args.needs_response:
+        changes["needs_response"] = True
+    if args.responded:
+        changes["needs_response"] = False
+        state = threadstate.get(ws, mod, tid)
+        tickets = tracker.index_by_thread(tracker.load_all(ws, mod)).get(tid, [])
+        pending = threadstate.pending_announcements(state, tickets)
+        if pending:
+            changes["announced"] = sorted(set(state.announced) | set(pending))
+    if not changes:
+        sys.exit("Nothing to change. Pass --triage/--class/--note/--needs-response/--responded.")
+
+    state = threadstate.update(ws, mod, tid, **changes)
+    if args.json:
+        out({"mod": mod, "thread": tid, **state.to_dict()}, True)
+        return
+    bits = [f"triage={state.triage}"]
+    if state.needs_response:
+        bits.append("needs-response")
+    if state.cls:
+        bits.append(f"class={state.cls}")
+    if state.duplicate_of:
+        bits.append(f"duplicate-of={state.duplicate_of}")
+    print(f"{mod} {tid}: " + ", ".join(bits))
+
+
+def collect_inbox(ws, mods, all_items, include_resolved: bool = False):
+    """Threads still asking for a decision, plus the count hidden as resolved.
+
+    The single definition of "awaiting triage", shared by `inbox` and `status`
+    so the dashboard number always matches the list you work from. A thread
+    with a ticket stays listed - the ticket tracks the code change, not the
+    conversation, which may still need a reply or a classification.
+    """
+    registry = ws.load_mods()["mods"]
+    ticket_index = tracker.index_by_thread(all_items)
+    out: list[dict] = []
+    hidden_resolved = 0
+    for mod in mods:
+        data = store.load_list(ws, mod)
+        if not data:
+            continue
+        states = threadstate.load(ws, mod)
+        for t in data["threads"]:
+            st = states.get(t["id"], threadstate.ThreadState())
+            m = parse_marker(t["title"])
+            tickets = ticket_index.get(t["id"], [])
+            reason = threadstate.reply_reason(st, tickets)
+            if st.triage == "ignored":
+                continue
+            if st.triage == "handled" and not reason:
+                continue
+            if st.triage == "pending" and m.resolved and not tickets:
+                hidden_resolved += 1
+                if not include_resolved:
+                    continue
+            out.append({
+                "mod": mod, "id": t["id"], "title": m.clean or t["title"],
+                "tag": t["tag"], "last_at": t["last_at"], "replies": t["reply_count"],
+                "needs_response": bool(reason), "reply_reason": reason,
+                "triage": st.triage,
+                "class": st.cls, "marker": m.marker, "wrong": m.wrong,
+                "tickets": [i.id for i in tickets],
+                "downloads": registry.get(mod, {}).get("downloads") or 0,
+            })
+    return out, hidden_resolved
+
+
+def _snippet(text: str, needle: str, width: int = 88) -> str:
+    """The first matching line, trimmed around the match."""
+    for line in text.splitlines():
+        pos = line.lower().find(needle)
+        if pos < 0:
+            continue
+        line = line.strip()
+        pos = line.lower().find(needle)
+        if len(line) <= width:
+            return line
+        start = max(0, pos - width // 3)
+        return ("..." if start else "") + line[start:start + width] + "..."
+    return ""
+
+
+def cmd_search(args) -> None:
+    """Find threads and tickets mentioning a phrase.
+
+    Grouping duplicate reports is the workflow this tool exists for, and it
+    needs one command that answers "has anyone said this before" with thread
+    ids you can hand straight to `fmw thread`.
+    """
+    ws = open_ws(args)
+    mods = resolve_mods(ws, args.mods, args.all, quiet=args.json)
+    needle = args.query.lower()
+    hits: list[dict] = []
+
+    if args.where in ("threads", "both"):
+        for mod in mods:
+            for path in sorted((ws.mod_cache_dir(mod) / "threads").glob("*.json")):
+                data = json.loads(path.read_text())
+                bodies = [m for m in data["messages"] if needle in m.get("body", "").lower()]
+                in_title = needle in data.get("title", "").lower()
+                if not bodies and not in_title:
+                    continue
+                # Prefer a body match for the snippet; echoing the title back
+                # under the title is noise.
+                hits.append({
+                    "kind": "thread", "id": data["id"], "mod": mod,
+                    "title": data.get("title", ""), "tag": data.get("tag", ""),
+                    "snippet": _snippet(bodies[0]["body"], needle) if bodies else "",
+                    "matched_authors": sorted({m["author"] for m in bodies}),
+                    "matched_title": in_title,
+                })
+
+    if args.where in ("tickets", "both"):
+        for item in tracker.load_all(ws):
+            if mods and not any(m in mods for m in item.mods):
+                continue
+            blob = f"{item.meta.get('title','')}\n{item.body}"
+            if needle not in blob.lower():
+                continue
+            hits.append({
+                "kind": "ticket", "id": item.id, "mod": "+".join(item.mods),
+                "title": item.meta.get("title", ""),
+                "tag": f"{item.meta.get('kind','?')}/{item.meta.get('status','?')}",
+                "snippet": _snippet(blob, needle), "path": str(item.path),
+            })
+
+    if args.json:
+        out({"query": args.query, "hits": hits, "count": len(hits)}, True)
+        return
+    if not hits:
+        print(f"No match for {args.query!r} in {len(mods)} mod(s).")
+        return
+    for h in hits[: args.limit]:
+        label = "ticket" if h["kind"] == "ticket" else "thread"
+        print(f"{label} {h['id']}  {h['mod']}  [{h['tag'][:18]}]")
+        print(f"       {h['title'][:80]}")
+        if h["snippet"]:
+            who = f"  ({', '.join(h['matched_authors'])})" if h.get("matched_authors") else ""
+            print(f"       > {h['snippet']}{who}")
+    if len(hits) > args.limit:
+        print(f"... {len(hits) - args.limit} more (--limit N)")
+    print(f"\n{len(hits)} match(es). Read one with `fmw thread <id>`.")
+
+
+def cmd_inbox(args) -> None:
+    """Everything awaiting a decision, threads and tickets in one view."""
+    ws = open_ws(args)
+    mods = resolve_mods(ws, args.mods, args.all, quiet=args.json)
+    all_items = tracker.load_all(ws)
+    threads_out, hidden_resolved = collect_inbox(ws, mods, all_items, args.all_threads)
+
+    open_tickets = [
+        i for i in all_items
+        if i.meta.get("status") in tracker.open_statuses()
+        and (args.all or not mods or any(m in mods for m in i.mods))
+    ]
+
+    if args.json:
+        out({"threads": threads_out, "hidden_resolved": hidden_resolved, "tickets": [
+            {**i.meta, "path": str(i.path)} for i in open_tickets]}, True)
+        return
+
+    needs_reply = [t for t in threads_out if t["needs_response"]]
+    undecided = [t for t in threads_out if not t["needs_response"]]
+    # Bugs before ideas, then a busier mod outranks a quiet one, then recency.
+    undecided.sort(key=lambda t: (t["tag"] != "Bugs", -t["downloads"], t["last_at"]), reverse=False)
+    undecided.sort(key=lambda t: t["last_at"], reverse=True)
+
+    def line(t):
+        flags = "".join([
+            "T" if t["tickets"] else " ",
+            "R" if t["needs_response"] else " ",
+            "!" if t["wrong"] else " ",
+        ])
+        return (f"  {flags} [{t['tag'][:5]:<5}] {t['last_at'][:10]} {t['replies']:>2}r  "
+                f"{t['title'][:58]}\n      {t['id']}  {t['mod']}")
+
+    if needs_reply:
+        print(f"== You owe a reply ({len(needs_reply)}) ==")
+        for t in needs_reply:
+            print(line(t))
+            if t["reply_reason"].startswith("released"):
+                print(f"      fix shipped, reporter not told - {t['reply_reason']}")
+        print()
+    awaiting = [i for i in open_tickets if i.meta.get("status") == "needs-testing"]
+    if awaiting:
+        print(f"== Awaiting your testing ({len(awaiting)}) - run `fmw testplan` ==")
+        for i in awaiting:
+            print(f"  {i.id}  {'+'.join(i.mods)}: {i.meta.get('title','')}")
+        print()
+    working = [i for i in open_tickets if i.meta.get("status") != "needs-testing"]
+    if working:
+        print(f"== Open tickets ({len(working)}) ==")
+        for i in working:
+            print(f"  {i.id}  [{i.meta.get('status','?'):<12}] {'+'.join(i.mods)}: {i.meta.get('title','')}")
+        print()
+    if undecided:
+        extra = f", {hidden_resolved} hidden as resolved on the portal" if hidden_resolved else ""
+        print(f"== Threads awaiting triage ({len(undecided)}{extra}) ==")
+        for t in undecided[: args.limit]:
+            print(line(t))
+        if len(undecided) > args.limit:
+            print(f"  ... {len(undecided) - args.limit} more (--limit N)")
+        print()
+    if not (needs_reply or open_tickets or undecided):
+        print("Inbox clear.")
+        return
+    print("T = has a ticket, R = you owe a reply, ! = reporter was mistaken")
+    print("Next: `fmw mark <thread> --triage handled` or `fmw track new <thread>`")
+
+
+def cmd_help(args) -> None:
+    """Prose help, without needing the repository checked out."""
+    if args.all:
+        print(helptext.OVERVIEW)
+        for name in sorted(helptext.TOPICS):
+            print(f"\n{'=' * 72}\nfmw help {name}\n{'=' * 72}\n")
+            print(helptext.TOPICS[name].rstrip())
+        for name in sorted(helptext.COMMANDS):
+            print(f"\n{'=' * 72}\nfmw {name}\n{'=' * 72}\n")
+            print(helptext.COMMANDS[name].rstrip())
+        return
+    if args.command:
+        if args.command in helptext.TOPICS:
+            print(helptext.TOPICS[args.command].rstrip())
+            return
+        text = helptext.COMMANDS.get(args.command)
+        if not text:
+            known = ", ".join(sorted({*helptext.COMMANDS, *helptext.TOPICS}))
+            sys.exit(f"No such command or topic: {args.command}.\nKnown: {known}")
+        print(f"fmw {args.command}\n")
+        print(text.rstrip())
+        print(f"\nFlags: fmw {args.command} --help")
+        return
+    print(helptext.OVERVIEW)
+
+
+def cmd_status(args) -> None:
+    ws = open_ws(args)
+    registry = ws.load_mods()["mods"]
+    items = tracker.load_all(ws)
+    open_items = [i for i in items if i.meta.get("status") in tracker.open_statuses()]
+    in_scope = [n for n, m in registry.items()
+                if m.get("on_portal") is not False and m.get("maintained") != "frozen"]
+    threads_out, hidden_resolved = collect_inbox(ws, in_scope, items)
+    replies_owed = sum(1 for t in threads_out if t["needs_response"])
+    summary = {
+        "workspace": str(ws.root),
+        "mods": len(registry),
+        # Two different senses of "maintained" used to share one label here.
+        "mods_marked_active": sum(1 for m in registry.values() if m.get("maintained") == "active"),
+        "mods_in_default_scope": len(in_scope),
+        "tracker_items": len(items),
+        "open_items": len(open_items),
+        "awaiting_test": sum(1 for i in items if i.meta.get("status") == "needs-testing"),
+        "replies_owed": replies_owed,
+        "awaiting_triage": len(threads_out),
+        "hidden_as_resolved": hidden_resolved,
+    }
+    stale = outdated_template_files(ws)
+    summary["stale_workspace_docs"] = stale
+    summary["workspace_under_git"] = (ws.root / ".git").is_dir()
+    if args.json:
+        out(summary, True)
+        return
+    for k, v in summary.items():
+        if k in ("stale_workspace_docs", "workspace_under_git"):
+            continue
+        print(f"{k:<22} {v}")
+    if stale:
+        print(f"\n! {len(stale)} workspace doc(s) describe an older schema "
+              f"({', '.join(stale)}). Run `fmw upgrade`.")
+    if not summary["workspace_under_git"]:
+        print(f"\n! {ws.root} is not a git repository. Your tickets and thread "
+              "judgements are the only irreplaceable data here; `git init` there.")
+
+
+# ----------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="fmw",
+        description=helptext.OVERVIEW,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--workspace", help="workspace directory (overrides $FMW_WORKSPACE; no implicit default)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def common(sp):
+        """Options accepted both before and after the subcommand.
+
+        argparse only matches a parent-level option before the subcommand, so
+        `fmw --workspace X status` works but `fmw status --workspace X` does
+        not. Repeating it on each subparser fixes that; SUPPRESS is required so
+        an absent flag does not overwrite the value parsed by the parent.
+        """
+        sp.add_argument("--workspace", default=argparse.SUPPRESS,
+                        help="workspace directory (overrides $FMW_WORKSPACE)")
+        sp.add_argument("--json", action="store_true", help="machine-readable output")
+        return sp
+
+    def add(name, fn, help_):
+        # The prose lives in help.py and surfaces through --help, so there is
+        # no second copy to fall out of step with the code.
+        sp = sub.add_parser(
+            name, help=help_,
+            description=helptext.COMMANDS.get(name),
+            formatter_class=argparse.RawDescriptionHelpFormatter,
+        )
+        sp.set_defaults(func=fn)
+        return common(sp)
+
+    sp = add("init", cmd_init, "create a workspace directory")
+    sp.add_argument("path", help="where to create it (no default: be explicit)")
+
+    rp = sub.add_parser("repo", help="manage the directories holding your mods",
+                        description=helptext.COMMANDS.get("repo"),
+                        formatter_class=argparse.RawDescriptionHelpFormatter)
+    rsub = rp.add_subparsers(dest="repo_cmd")
+    rp.set_defaults(func=cmd_repo, repo_cmd="list")
+    ra = rsub.add_parser("add", help="register a directory to scan for mods")
+    ra.set_defaults(func=cmd_repo); ra.add_argument("path"); common(ra)
+    rr = rsub.add_parser("remove", help="stop scanning a directory")
+    rr.set_defaults(func=cmd_repo); rr.add_argument("path"); common(rr)
+    rl = rsub.add_parser("list", help="show configured repositories")
+    rl.set_defaults(func=cmd_repo); common(rl)
+    common(rp)
+
+    sp = add("discover", cmd_discover, "find mods in your repos and read their portal metadata")
+    sp.add_argument("--scan", nargs="*", metavar="DIR",
+                    help="scan these directories just this once, without registering them "
+                         "(use `fmw repo add` to keep one)")
+    sp.add_argument("--no-portal", action="store_true", help="skip portal API lookups")
+    sp.add_argument("--max-depth", type=int, default=2,
+                    help="how deep below each root to look for info.json (default: 2)")
+
+    sp = add("mods", cmd_mods, "list the mod registry")
+    sp.add_argument("--maintained", choices=discover.MAINTAINED,
+                    help="filter by maintained value")
+
+    sp = add("sync", cmd_sync, "fetch discussions and report what changed")
+    sp.add_argument("mods", nargs="*", help="mods to sync; inferred from the cwd if omitted")
+    sp.add_argument("--all", action="store_true", help="include mods marked frozen")
+    sp.add_argument("--no-threads", action="store_true", help="only refresh the thread list")
+
+    sp = add("threads", cmd_threads, "list cached threads of a mod")
+    sp.add_argument("mod", nargs="?", help="mod name; inferred from the current directory if omitted")
+    sp.add_argument("--tag", help="filter by tag name or abbreviation, e.g. bug / idea")
+    sp.add_argument("--limit", type=int)
+
+    sp = add("thread", cmd_thread, "print a full discussion thread")
+    sp.add_argument("target", help="thread id or discussion URL")
+    sp.add_argument("--refresh", action="store_true", help="re-fetch instead of using cache")
+
+    sp = add("changes", cmd_changes, "replay recorded portal changes")
+    sp.add_argument("mods", nargs="*")
+    sp.add_argument("--all", action="store_true")
+    sp.add_argument("--since", metavar="ISO",
+                    help="only changes detected on or after this time (detection time, not post time)")
+
+    sp = add("search", cmd_search, "find threads and tickets mentioning a phrase")
+    sp.add_argument("query")
+    sp.add_argument("mods", nargs="*", help="mods to search; inferred from the cwd if omitted")
+    sp.add_argument("--all", action="store_true", help="search every mod")
+    sp.add_argument("--where", choices=("threads", "tickets", "both"), default="both",
+                    help="what to search (default: both)")
+    sp.add_argument("--limit", type=int, default=20, help="max results to print")
+
+    sp = add("inbox", cmd_inbox, "everything awaiting a decision, threads and tickets")
+    sp.add_argument("mods", nargs="*", help="mods to show; inferred from the cwd if omitted")
+    sp.add_argument("--all", action="store_true", help="every mod, including frozen ones")
+    sp.add_argument("--all-threads", action="store_true",
+                    help="include threads the portal title already marks resolved")
+    sp.add_argument("--limit", type=int, default=20, help="max untriaged threads to list")
+
+    sp = add("mark", cmd_mark, "record your judgement about a thread")
+    sp.add_argument("targets", nargs="*",
+                    help="a thread id or URL; with --before, the mods to sweep instead")
+    sp.add_argument("--before", metavar="YYYY-MM-DD",
+                    help="bulk mode: apply to every still-pending thread last active before this date")
+    sp.add_argument("--tag", help="bulk mode: restrict to a portal tag")
+    sp.add_argument("--all", action="store_true", help="bulk mode: every mod")
+    sp.add_argument("--triage", choices=threadstate.TRIAGE,
+                    help="how you have dealt with the conversation")
+    sp.add_argument("--class", dest="set_class", choices=threadstate.CLASSES,
+                    help="what the thread really is, regardless of its portal tag")
+    sp.add_argument("--note", help="why you decided that")
+    sp.add_argument("--duplicate-of", help="another thread id this repeats")
+    sp.add_argument("--needs-response", action="store_true", help="you owe the reporter a reply")
+    sp.add_argument("--responded", action="store_true", help="clear the reply flag")
+
+    sp = add("testplan", cmd_testplan, "collect every awaiting-test fix into one document")
+    sp.add_argument("mods", nargs="*", help="mods to include; inferred from the cwd if omitted")
+    sp.add_argument("--all", action="store_true", help="every mod, including frozen ones")
+
+    sp = sub.add_parser("help", help="prose help for a command, or an overview")
+    sp.set_defaults(func=cmd_help)
+    sp.add_argument("command", nargs="?",
+                    help="a command, or a topic: workspace, workflow")
+    sp.add_argument("--all", action="store_true",
+                    help="print every command's help at once (one call, for agents)")
+    sp.add_argument("--json", action="store_true", help=argparse.SUPPRESS)
+    sp.add_argument("--workspace", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+
+    sp = add("status", cmd_status, "workspace overview")
+
+    sp = add("upgrade", cmd_upgrade,
+             "bring a workspace to the current schema: docs, mods.yaml, tickets")
+    sp.add_argument("--dry-run", action="store_true", help="report what would change")
+
+    sp = add("launcher", cmd_launcher, "install a PATH wrapper pinning a workspace")
+    sp.add_argument("--name", default="fmw", help="command name to install (default: fmw)")
+    sp.add_argument("--out", help="exact path to write instead of a PATH directory")
+    sp.add_argument("--force", action="store_true", help="overwrite an existing file")
+
+    tp = sub.add_parser("track", help="tickets: code changes, error or feature",
+                        description=helptext.COMMANDS.get("track"),
+                        formatter_class=argparse.RawDescriptionHelpFormatter)
+    tsub = tp.add_subparsers(dest="track_cmd", required=True)
+
+    tn = tsub.add_parser("new", help="create a tracker item")
+    tn.set_defaults(func=cmd_track_new)
+    tn.add_argument("target", nargs="?", help="thread id/URL, or a mod name; inferred from the current directory if omitted")
+    tn.add_argument("title", nargs="?", help="defaults to the thread's title without its marker")
+    tn.add_argument("--also", action="append", help="another mod this ticket applies to")
+    tn.add_argument("--kind", default="error", choices=tracker.KINDS)
+    tn.add_argument("--status", default="new", choices=tracker.STATUSES)
+    tn.add_argument("--source", action="append", help="extra source, e.g. discord:<url>")
+    common(tn)
+
+    tl = tsub.add_parser("list", help="list tracker items")
+    tl.set_defaults(func=cmd_track_list)
+    tl.add_argument("mod", nargs="?", help="mod name; inferred from the current directory if omitted")
+    tl.add_argument("--kind", choices=tracker.KINDS)
+    tl.add_argument("--status", choices=tracker.STATUSES)
+    tl.add_argument("--open", action="store_true", help="only unresolved items")
+    common(tl)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()