@topy-ai/maggie 0.7.52 → 0.7.54

package/bundled-tools/clis/maggie_feedback.py

@@ -20,6 +20,10 @@ from urllib.request import Request, urlopen
 
 
 DEFAULT_ENDPOINT = "https://feedback.noblox.app/api/feedback"
+# Both hosts accept the same anonymous contract and de-duplicate on feedbackId,
+# so a draft is offered to the next one only when the previous host failed
+# before storing it (network error or a 5xx such as Cloudflare's 52x).
+DEFAULT_ENDPOINTS = (DEFAULT_ENDPOINT, "https://feedback.cmo.so/api/feedback")
 SECRET_RE = re.compile(r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|npm_config[^=]*|authorization)\s*[=:]\s*)[^\s,;]+")
 LOCAL_PATH_RE = re.compile(
     r"(?<![A-Za-z0-9])(?:~/(?:[^\s,;:)\]}]+/)*[^\s,;:)\]}]+|"
@@ -348,28 +352,52 @@ def hosted_payload(data: dict) -> dict:
     return payload
 
 
+def submit_endpoints(value: object) -> list[str]:
+    endpoints = [value] if isinstance(value, str) else list(value or DEFAULT_ENDPOINTS)
+    result = []
+    for endpoint in endpoints:
+        endpoint = str(endpoint).rstrip("/")
+        parsed = urlparse(endpoint)
+        if parsed.scheme != "https" or not parsed.netloc:
+            raise ValueError("endpoint must be an absolute HTTPS URL")
+        if endpoint not in result:
+            result.append(endpoint)
+    return result
+
+
 def submit(args: argparse.Namespace) -> int:
     if not args.confirm:
         raise ValueError("submit requires --confirm; feedback is never sent implicitly")
     path = Path(args.feedback)
     data = read_feedback(path)
-    endpoint = args.endpoint.rstrip("/")
-    parsed = urlparse(endpoint)
-    if parsed.scheme != "https" or not parsed.netloc:
-        raise ValueError("endpoint must be an absolute HTTPS URL")
+    endpoints = submit_endpoints(args.endpoint)
     payload = hosted_payload(data)
     payload["projectContext"] = data.get("projectContext") if data.get("privacy", {}).get("projectContextAllowed") else None
-    request = Request(endpoint, data=json.dumps(payload, ensure_ascii=False).encode(), headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": "MaggieFeedback/0.1"}, method="POST")
-    try:
-        with urlopen(request, timeout=20) as response:
-            raw = response.read(1_000_000).decode("utf-8", "replace")
-            result = json.loads(raw) if raw else {}
-    except (HTTPError, URLError, TimeoutError) as error:
-        raise RuntimeError(f"feedback submission failed: {error}") from error
+    body = json.dumps(payload, ensure_ascii=False).encode()
+    failures = []
+    for endpoint in endpoints:
+        request = Request(endpoint, data=body, headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": "MaggieFeedback/0.1"}, method="POST")
+        try:
+            with urlopen(request, timeout=20) as response:
+                raw = response.read(1_000_000).decode("utf-8", "replace")
+                result = json.loads(raw) if raw else {}
+            break
+        except HTTPError as error:
+            failures.append({"endpoint": endpoint, "error": f"HTTP {error.code}"})
+            # A 4xx is the host rejecting this draft; another host would too.
+            if error.code < 500:
+                raise RuntimeError(f"feedback submission failed: {endpoint} answered HTTP {error.code}") from error
+        except (URLError, TimeoutError, OSError) as error:
+            failures.append({"endpoint": endpoint, "error": safe_text(getattr(error, "reason", error))})
+    else:
+        tried = "; ".join(f"{item['endpoint']} ({item['error']})" for item in failures)
+        raise RuntimeError(f"feedback submission failed on every endpoint: {tried}")
     ack = acknowledgement(result)
     data["submission"] = {"status": "submitted", "endpoint": endpoint, "submittedAt": now(), "acknowledgement": ack}
+    if failures:
+        data["submission"]["failedEndpoints"] = failures
     path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "acknowledgement": ack}, indent=2, ensure_ascii=False))
+    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "endpoint": endpoint, "failedEndpoints": failures, "acknowledgement": ack}, indent=2, ensure_ascii=False))
     return 0
 
 
@@ -459,6 +487,12 @@ def collect_batch(args: argparse.Namespace) -> int:
     return 0
 
 
+AREA_SUBJECT_RE = re.compile(r"^([A-Za-z][A-Za-z0-9 /&._-]{0,30}):\s+(\S.*)$")
+SCOPE_RE = re.compile(r"^[a-z]+\(([^)]{1,40})\)!?:", re.IGNORECASE)
+SKILL_HINT_RE = re.compile(r"\b(?:maggie[\w-]*|skills?|cli|mcp|codex|claude)\b", re.IGNORECASE)
+SUMMARY_ITEM_CAP = 49
+
+
 def classify_subject(subject: str, include_all: bool) -> tuple[str, str] | None:
     """Return (type, text) for one commit subject, or ``None`` to skip it."""
     merge = MERGE_PR_RE.match(subject)
@@ -474,22 +508,58 @@ def classify_subject(subject: str, include_all: bool) -> tuple[str, str] | None:
         return "bug", subject
     if PLAIN_FEATURE_RE.search(subject):
         return "improvement", subject
+    # "Area: sentence" is how many product teams describe a change; it is a
+    # change in that area even when the sentence has no recognised verb.
+    if AREA_SUBJECT_RE.match(subject):
+        return "improvement", subject
     return ("general", subject) if include_all else None
 
 
-def _summary_repos(values: list[str]) -> list[tuple[str, Path]]:
-    """Parse ``--repo [LABEL=]PATH`` values; unlabeled repositories become repo1, repo2, ..."""
+def subject_scope(subject: str) -> str:
+    """The conventional-commit scope or ``Area:`` prefix of a subject, lower-cased; ``""`` when absent."""
+    match = SCOPE_RE.match(subject)
+    if match:
+        return match.group(1).strip().lower()
+    if FIX_SUBJECT_RE.match(subject) or FEATURE_SUBJECT_RE.match(subject) or CHORE_SUBJECT_RE.match(subject):
+        return ""
+    area = AREA_SUBJECT_RE.match(subject)
+    return area.group(1).strip().lower() if area else ""
+
+
+def _summary_repos(values: list[str], default_rev: str = "") -> list[tuple[str, Path, str]]:
+    """Parse ``--repo [LABEL=]PATH[@REV]`` values; unlabeled repositories become repo1, repo2, ..."""
     repos = []
     for index, value in enumerate(values or ["."], start=1):
         label, sep, path = value.partition("=")
         if not sep or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,40}", label):
             label, path = f"repo{index}", value
-        repos.append((label, Path(path).expanduser().resolve()))
-    if len({label for label, _ in repos}) != len(repos):
+        rev = default_rev
+        head, at, tail = path.rpartition("@")
+        if at and head and not Path(path).expanduser().exists():
+            path, rev = head, tail
+        if rev and (rev.startswith("-") or not re.fullmatch(r"[A-Za-z0-9._/@{}~^:-]{1,200}", rev)):
+            raise ValueError("revision must be a branch, tag or commit such as origin/main")
+        repos.append((label, Path(path).expanduser().resolve(), rev or "HEAD"))
+    if len({label for label, _, _ in repos}) != len(repos):
         raise ValueError("--repo labels must be unique")
     return repos
 
 
+def _behind_upstream(repo: Path, rev: str) -> tuple[str, int] | None:
+    """When reading HEAD, report (upstream, commits HEAD lacks) from local refs; never fetches."""
+    if rev != "HEAD":
+        return None
+    upstream = subprocess.run(["git", "-C", str(repo), "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], capture_output=True, text=True, check=False)
+    if upstream.returncode or not upstream.stdout.strip():
+        return None
+    count = subprocess.run(["git", "-C", str(repo), "rev-list", "--count", "HEAD..@{u}"], capture_output=True, text=True, check=False)
+    try:
+        behind = int(count.stdout.strip() or 0)
+    except ValueError:
+        return None
+    return (upstream.stdout.strip(), behind) if behind else None
+
+
 def session_summary(args: argparse.Namespace) -> int:
     """Draft a reviewable batch file from commit subjects; nothing is collected or submitted."""
     since = str(args.since or "").strip()
@@ -503,32 +573,53 @@ def session_summary(args: argparse.Namespace) -> int:
     batch_id = safe_text(args.batch_id) or f"session-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
     if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
         raise ValueError("batch ID is invalid")
-    repos = _summary_repos(args.repo)
+    repos = _summary_repos(args.repo, str(getattr(args, "rev", "") or "").strip())
     include_all = bool(getattr(args, "all", False))
-    items = []
+    skill_relevant = bool(getattr(args, "skill_relevant", False))
+    skill_hint = safe_text(args.skill).lower().removeprefix("maggie-")
+    candidates = []
     skipped = 0
+    project_commits = 0
+    seen = 0
     per_repo = {}
-    for label, repo in repos:
+    warnings = []
+    for label, repo, rev in repos:
         command = ["git", "-C", str(repo), "log", "--format=%h%x1f%s"]
         if not getattr(args, "merges", False):
             command.append("--no-merges")
-        command += [f"--since={since_date}", "HEAD"] if since_date else [f"{since}..HEAD"]
+        command += [f"--since={since_date}", rev] if since_date else [f"{since}..{rev}"]
         completed = subprocess.run(command, capture_output=True, text=True, check=False)
         if completed.returncode:
-            raise ValueError(f"git log failed for {label}; check --repo and --since")
+            raise ValueError(f"git log failed for {label}; check --repo, --rev and --since")
+        lag = _behind_upstream(repo, rev)
+        if lag:
+            warnings.append(f"{label}: local HEAD is {lag[1]} commit(s) behind {lag[0]}; commits pushed from worktrees are missing. Re-run with --repo {label}=PATH@{lag[0]} (git fetch first).")
         counted = 0
         for line in completed.stdout.splitlines():
             sha, _, subject = line.partition("\x1f")
             subject = safe_text(subject)[:200]
             if not sha or not subject:
                 continue
+            seen += 1
             classified = classify_subject(subject, include_all)
             if classified is None:
                 skipped += 1
                 continue
+            scope = subject_scope(subject)
+            if skill_relevant and not (SKILL_HINT_RE.search(subject) or (skill_hint and skill_hint in subject.lower())):
+                project_commits += 1
+                continue
             kind, text = classified
             text = text[:1].upper() + text[1:] if text else subject
             commit = f"{label}@{sha}" if len(repos) > 1 else sha
+            candidates.append({"kind": kind, "text": text, "commit": commit, "scope": scope or label})
+            counted += 1
+        per_repo[label] = counted
+    grouped = len(candidates) > SUMMARY_ITEM_CAP
+    items = []
+    if not grouped:
+        for candidate in candidates:
+            commit, text, kind = candidate["commit"], candidate["text"], candidate["kind"]
             item = {
                 "type": kind,
                 "summary": text,
@@ -540,10 +631,24 @@ def session_summary(args: argparse.Namespace) -> int:
             if kind in {"bug", "improvement"}:
                 item.update({"fixed": True, "resolution": text})
             items.append(item)
-            counted += 1
-            if len(items) >= 49:
-                break
-        per_repo[label] = counted
+    else:
+        # Too many commits for one batch: one item per scope, so nothing is dropped silently.
+        scopes: dict[str, list[dict]] = {}
+        for candidate in candidates:
+            scopes.setdefault(candidate["scope"], []).append(candidate)
+        ordered = sorted(scopes.items(), key=lambda pair: (-len(pair[1]), pair[0]))
+        for scope, entries in ordered[:SUMMARY_ITEM_CAP]:
+            bugs = sum(1 for entry in entries if entry["kind"] == "bug")
+            items.append({
+                "type": "bug" if bugs * 2 > len(entries) else "improvement",
+                "summary": f"{scope}: {len(entries)} commit(s) ({bugs} fix) — keep only if a Maggie skill or CLI fell short",
+                "expected": f"{REVIEW_MARKER} what the skill or CLI should have done",
+                "actual": f"{REVIEW_MARKER} summarise the {scope} commits that came from a skill gap",
+                "validation": f"{REVIEW_MARKER} the test or check that verified the {scope} commits",
+                "evidence": [f"commit:{entry['commit']}" for entry in entries[:20]],
+            })
+        if len(ordered) > SUMMARY_ITEM_CAP:
+            warnings.append(f"{len(ordered) - SUMMARY_ITEM_CAP} scope(s) did not fit in one batch; narrow --since-date or use --skill-relevant.")
     items.append({
         "type": "feature",
         "summary": f"{REVIEW_MARKER} describe an open ask from this session, or delete this item",
@@ -557,6 +662,7 @@ def session_summary(args: argparse.Namespace) -> int:
         "phase": safe_text(args.phase) or "session-summary",
         "reviewRequired": True,
         "note": "Draft only. Remove items unrelated to Maggie skills or CLIs, replace every REVIEW: and delete the open-ask placeholder if unused. `maggie feedback batch` rejects unedited REVIEW: fields.",
+        "commits": {"seen": seen, "drafted": len(candidates), "skipped": skipped, "projectOnly": project_commits, "groupedByScope": grouped},
         "items": items,
     }
     project = Path(args.project).resolve()
@@ -567,7 +673,9 @@ def session_summary(args: argparse.Namespace) -> int:
         raise ValueError("output already exists; choose another --output or --batch-id")
     output.parent.mkdir(parents=True, exist_ok=True)
     output.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    print(json.dumps({"status": "draft-written", "batchId": batch_id, "items": len(items), "skippedCommits": skipped, "repositories": per_repo, "output": str(output), "submitted": False}, ensure_ascii=False))
+    if grouped:
+        warnings.append(f"{len(candidates)} commits exceed the {SUMMARY_ITEM_CAP}-item batch limit, so they were grouped into one item per scope.")
+    print(json.dumps({"status": "draft-written", "batchId": batch_id, "items": len(items), "commitsSeen": seen, "draftedCommits": len(candidates), "skippedCommits": skipped, "projectOnlyCommits": project_commits, "groupedByScope": grouped, "repositories": per_repo, "warnings": warnings, "output": str(output), "submitted": False}, ensure_ascii=False))
     return 0
 
 
@@ -716,7 +824,9 @@ def main() -> int:
     summary_parser.add_argument("--project", default=argparse.SUPPRESS)
     summary_parser.add_argument("--since", default="", help="git revision; commits after it are summarized")
     summary_parser.add_argument("--since-date", default="", help="ISO date/time; use across several repositories")
-    summary_parser.add_argument("--repo", action="append", default=[], help="[LABEL=]PATH of a git repository; repeat for app, backend, edge (default: current directory)")
+    summary_parser.add_argument("--repo", action="append", default=[], help="[LABEL=]PATH[@REV] of a git repository; repeat for app, backend, edge (default: current directory at HEAD)")
+    summary_parser.add_argument("--rev", default="", help="revision to read in every repository without its own @REV, e.g. origin/main")
+    summary_parser.add_argument("--skill-relevant", action="store_true", help="keep only commits that mention Maggie, a skill, a CLI or MCP (or the --skill name); count the rest as project-only")
     summary_parser.add_argument("--all", action="store_true", help="also draft unclassified and chore subjects as general items")
     summary_parser.add_argument("--merges", action="store_true", help="include merge commits (PR branch names are classified)")
     summary_parser.add_argument("--batch-id", default="")
@@ -733,7 +843,7 @@ def main() -> int:
     preview_parser.add_argument("--format", choices=("json", "markdown"), default="json")
     submit_parser = sub.add_parser("submit")
     submit_parser.add_argument("feedback")
-    submit_parser.add_argument("--endpoint", default=DEFAULT_ENDPOINT)
+    submit_parser.add_argument("--endpoint", action="append", help="HTTPS endpoint; repeat for an ordered fallback list (default: the NoBlox host, then feedback.cmo.so)")
     submit_parser.add_argument("--confirm", action="store_true")
     list_parser = sub.add_parser("list")
     list_parser.add_argument("--project", default=argparse.SUPPRESS)

package/bundled-tools/clis/maggie_live_urls.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Record where API Pull deliveries went live, from the site's sitemap.
+
+A delivered post is useful to other channels (social posts, internal links)
+only once its live URL is known. The site should report it when it publishes;
+this matcher fills the gaps from the sitemap with two rules:
+
+* additive only: a record that already has a live URL keeps it, and a record
+  that matches nothing in this run is left as it was (never marked unmatched),
+  so the match can run on a schedule;
+* the original page first: when translated copies share the slug
+  (``/blog/x`` and ``/zh-hans/blog/x``), the URL without a locale segment wins.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import xml.etree.ElementTree as ET
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlsplit
+from urllib.request import Request, urlopen
+
+LOCALE_SEGMENT = re.compile(r"^[a-z]{2}(?:[-_][a-z0-9]{2,8})?$", re.I)
+MAX_SITEMAPS = 50
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def fetch(location: str) -> str:
+    if not location.startswith(("http://", "https://")):
+        return Path(location).read_text(encoding="utf-8")
+    with urlopen(Request(location, headers={"User-Agent": "MaggieLiveUrls/1.0"}), timeout=20) as response:
+        return response.read(20_000_000).decode("utf-8", "replace")
+
+
+def sitemap_urls(location: str) -> list[str]:
+    """Every <loc> of a sitemap, following sitemap indexes (bounded)."""
+    seen: set[str] = set()
+    urls: list[str] = []
+    queue = [location]
+    while queue and len(seen) < MAX_SITEMAPS:
+        current = queue.pop(0)
+        if current in seen:
+            continue
+        seen.add(current)
+        root = ET.fromstring(fetch(current))
+        tag = root.tag.rsplit("}", 1)[-1]
+        locs = [element.text.strip() for element in root.iter() if element.tag.rsplit("}", 1)[-1] == "loc" and element.text]
+        if tag == "sitemapindex":
+            queue.extend(locs)
+        else:
+            urls.extend(locs)
+    return list(dict.fromkeys(urls))
+
+
+def has_locale_segment(url: str) -> bool:
+    parts = [part for part in urlsplit(url).path.split("/") if part]
+    return len(parts) > 1 and bool(LOCALE_SEGMENT.match(parts[0]))
+
+
+def best_match(slug: str, urls: list[str]) -> str | None:
+    candidates = [url for url in urls if [part for part in urlsplit(url).path.split("/") if part][-1:] == [slug]]
+    if not candidates:
+        return None
+    # Original before translated copies, then the shortest path.
+    return sorted(candidates, key=lambda url: (has_locale_segment(url), len(urlsplit(url).path), url))[0]
+
+
+def match(state: dict, urls: list[str]) -> dict:
+    records = state.get("content", {}) if isinstance(state.get("content"), dict) else {}
+    matched, kept, missing = [], [], []
+    for key, record in records.items():
+        if not isinstance(record, dict):
+            continue
+        if record.get("live_url"):
+            kept.append({"remote_content_id": record.get("remote_content_id") or key, "live_url": record["live_url"], "source": record.get("live_url_source", "")})
+            continue
+        slug = str(record.get("slug") or "").strip("/")
+        url = best_match(slug, urls) if slug else None
+        if url:
+            record["live_url"] = url
+            record["live_url_source"] = "sitemap"
+            record["live_url_matched_at"] = now()
+            matched.append({"remote_content_id": record.get("remote_content_id") or key, "slug": slug, "live_url": url})
+        else:
+            missing.append({"remote_content_id": record.get("remote_content_id") or key, "slug": slug})
+    return {"matched": matched, "kept": kept, "notFound": missing}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    run = sub.add_parser("match", help="fill missing live URLs of delivered posts from the sitemap (additive)")
+    run.add_argument("--project", default=".")
+    run.add_argument("--state", help="lifecycle state (default: .maggie/ai-cmo-lifecycle.json)")
+    run.add_argument("--sitemap", required=True, help="sitemap URL or file (indexes are followed)")
+    run.add_argument("--write", action="store_true", help="save the new live URLs into the state file")
+    run.add_argument("--report-body", help="write a report-state body for the newly matched posts (send with `maggie api report-state --body-file`)")
+    record = sub.add_parser("record", help="record a live URL the site reported when it published a delivered post")
+    record.add_argument("--project", default=".")
+    record.add_argument("--state")
+    record.add_argument("--content-id", required=True)
+    record.add_argument("--url", required=True)
+    args = parser.parse_args()
+    state_path = Path(args.state) if args.state else Path(args.project) / ".maggie" / "ai-cmo-lifecycle.json"
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        if args.command == "record":
+            if urlsplit(args.url).scheme not in {"http", "https"}:
+                raise ValueError("--url must be an absolute http(s) URL")
+            target = state.get("content", {}).get(args.content_id)
+            if not isinstance(target, dict):
+                raise ValueError(f"no delivered post {args.content_id} in {state_path}")
+            # The site's own report is authoritative and replaces a sitemap guess.
+            target.update({"live_url": args.url, "live_url_source": "site", "live_url_matched_at": now()})
+            state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            print(json.dumps({"status": "recorded", "remote_content_id": args.content_id, "live_url": args.url}, indent=2))
+            return 0
+        result = match(state, sitemap_urls(args.sitemap))
+        if args.write:
+            state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        if args.report_body and result["matched"]:
+            body = {"items": [{"content_id": item["remote_content_id"], "url": item["live_url"], "status": "published"} for item in result["matched"]][:500]}
+            Path(args.report_body).write_text(json.dumps(body, indent=2) + "\n", encoding="utf-8")
+        print(json.dumps({"status": "matched" if args.write else "dry-run", **{key: value for key, value in result.items()}, "counts": {key: len(value) for key, value in result.items()}}, indent=2, ensure_ascii=False))
+        return 0
+    except (OSError, ValueError, json.JSONDecodeError, ET.ParseError) as error:
+        print(f"maggie live-urls: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_localization.py

@@ -17,6 +17,7 @@ from localization_runner import generate, process_adapter
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import maggie_email_localization as email_localization
+import maggie_localization_keys as localization_keys
 
 
 def generate_job(args: argparse.Namespace) -> int:
@@ -399,6 +400,7 @@ def main() -> int:
     for name in ("stale", "glossary"):
         command = sub.add_parser(name); command.add_argument("--project", type=Path, default=Path("."))
     email_localization.add_parsers(sub)
+    localization_keys.add_parsers(sub)
     args = parser.parse_args()
     try:
         if args.command == "generate": return generate_job(args)
@@ -411,6 +413,7 @@ def main() -> int:
         if args.command == "publish": return publish(args.job, args.confirm)
         if args.command == "stale": return stale_jobs(args.project)
         if args.command in ("email-matrix", "lifecycle"): return email_localization.run(args)
+        if args.command in ("key-check", "fragments"): return localization_keys.run(args)
         return glossary(args.project)
     except (OSError, ValueError, json.JSONDecodeError) as error:
         print(f"ERROR: {error}", file=sys.stderr); return 1

package/bundled-tools/clis/maggie_localization_keys.py

@@ -0,0 +1,151 @@
+"""Translation keys for generated pages: text keys are site-wide, positions are not.
+
+A translation stored under its source text applies to every page that shows
+that text. That is right for a shared header, wrong for generic phrases on
+generated pages ("your practice" is a clinic on one page and a firm on
+another). `key-check` reads per-page translation rows and lists the texts that
+need position keys. `fragments` reads rendered HTML and lists text split
+around an inline span (a styled brand name) into pieces too short to translate
+on their own ("Can", "No.", "What").
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from html.parser import HTMLParser
+from pathlib import Path
+
+INLINE = {"span", "strong", "em", "b", "i", "a", "mark", "small", "sup", "sub", "u"}
+BLOCK = {"p", "h1", "h2", "h3", "h4", "h5", "h6", "li", "td", "th", "dt", "dd", "figcaption", "blockquote", "button", "label", "summary", "caption"}
+SKIP = {"script", "style", "noscript", "template", "svg", "code", "pre"}
+WORD = re.compile(r"[\w'’-]+", re.UNICODE)
+
+
+def load_rows(path: Path) -> list[dict]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    rows = value.get("rows", []) if isinstance(value, dict) else value
+    if not isinstance(rows, list):
+        raise ValueError("rows must be a list of {page, position?, text, translation}")
+    return [row for row in rows if isinstance(row, dict)]
+
+
+def key_check(rows: list[dict], locale: str | None = None) -> dict:
+    """Source texts whose translation differs between pages cannot share a text key."""
+    by_text: dict[str, dict[str, set[str]]] = {}
+    for row in rows:
+        if locale and row.get("locale") not in (None, locale):
+            continue
+        text = " ".join(str(row.get("text") or "").split())
+        translation = " ".join(str(row.get("translation") or "").split())
+        if not text or not translation:
+            continue
+        by_text.setdefault(text, {}).setdefault(translation, set()).add(str(row.get("page") or "?"))
+    conflicts = []
+    for text, translations in sorted(by_text.items()):
+        if len(translations) > 1:
+            pages = sorted({page for group in translations.values() for page in group})
+            conflicts.append({"text": text, "translations": {translation: sorted(group)[:5] for translation, group in translations.items()}, "pages": len(pages)})
+    shared = sum(1 for translations in by_text.values() if len({page for group in translations.values() for page in group}) > 1)
+    return {
+        "valid": not conflicts,
+        "texts": len(by_text),
+        "sharedAcrossPages": shared,
+        "needPositionKeys": len(conflicts),
+        "conflicts": conflicts[:200],
+        "advice": "Store these under per-page position keys (render the source page, then key each node by page + position with a source hash); keep text keys only as a fallback for genuinely shared text." if conflicts else "",
+    }
+
+
+class FragmentParser(HTMLParser):
+    """Collect, per block element, the run of text pieces and inline spans."""
+
+    def __init__(self, brand: re.Pattern[str]) -> None:
+        super().__init__(convert_charrefs=True)
+        self.brand = brand
+        self.stack: list[str] = []
+        self.blocks: list[list[tuple[str, str]]] = []  # (kind, text): kind is "text" or "inline"
+        self.inline_depth = 0
+        self.inline_text = ""
+        self.skip = 0
+        self.findings: list[dict] = []
+
+    def handle_starttag(self, tag: str, attrs) -> None:  # noqa: ANN001
+        if tag in SKIP:
+            self.skip += 1
+            return
+        if tag in BLOCK:
+            self.blocks.append([])
+        elif tag in INLINE and self.blocks:
+            if self.inline_depth == 0:
+                self.inline_text = ""
+            self.inline_depth += 1
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in SKIP:
+            self.skip = max(0, self.skip - 1)
+            return
+        if tag in INLINE and self.inline_depth:
+            self.inline_depth -= 1
+            if self.inline_depth == 0 and self.blocks:
+                self.blocks[-1].append(("inline", self.inline_text))
+        elif tag in BLOCK and self.blocks:
+            self.finish(self.blocks.pop())
+
+    def handle_data(self, data: str) -> None:
+        if self.skip or not self.blocks:
+            return
+        if self.inline_depth:
+            self.inline_text += data
+        elif data.strip():
+            self.blocks[-1].append(("text", data))
+
+    def finish(self, parts: list[tuple[str, str]]) -> None:
+        if not any(kind == "inline" and self.brand.search(text) for kind, text in parts):
+            return
+        sentence = " ".join(" ".join(text.split()) for _, text in parts).strip()
+        for index, (kind, text) in enumerate(parts):
+            if kind != "text":
+                continue
+            neighbours = [parts[i] for i in (index - 1, index + 1) if 0 <= i < len(parts)]
+            if not any(other_kind == "inline" and self.brand.search(other_text) for other_kind, other_text in neighbours):
+                continue
+            words = WORD.findall(text)
+            if 1 <= len(words) <= 2:
+                self.findings.append({"fragment": " ".join(text.split()), "words": len(words), "sentence": sentence[:200]})
+
+
+def fragments(paths: list[Path], brand: str) -> dict:
+    pattern = re.compile(re.escape(brand), re.I)
+    findings = []
+    for path in paths:
+        parser = FragmentParser(pattern)
+        parser.feed(path.read_text(encoding="utf-8", errors="replace"))
+        findings.extend({"file": str(path), **item} for item in parser.findings)
+    return {
+        "valid": not findings,
+        "files": len(paths),
+        "fragments": findings[:500],
+        "advice": f"Translate the whole sentence around {brand!r} as one unit (keep the span as a placeholder such as {{brand}}) instead of storing these short pieces." if findings else "",
+    }
+
+
+def add_parsers(sub: argparse._SubParsersAction) -> None:
+    keys = sub.add_parser("key-check", help="list source texts translated differently on different pages (they need per-page position keys)")
+    keys.add_argument("rows", type=Path, help='JSON rows [{"page", "position"?, "text", "translation", "locale"?}]')
+    keys.add_argument("--locale")
+    split = sub.add_parser("fragments", help="find text split around an inline brand span into pieces too short to translate")
+    split.add_argument("--html", type=Path, nargs="+", required=True, help="rendered HTML files or directories (searched for *.html)")
+    split.add_argument("--brand", required=True, help="the inline span's text, e.g. the brand name")
+
+
+def run(args: argparse.Namespace) -> int:
+    if args.command == "key-check":
+        result = key_check(load_rows(args.rows), args.locale)
+    else:
+        files: list[Path] = []
+        for item in args.html:
+            files.extend(sorted(item.rglob("*.html")) if item.is_dir() else [item])
+        result = fragments(files, args.brand)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["valid"] else 1