@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/localization-reuse-map/SKILL.md

@@ -18,7 +18,7 @@ Scope rules that hold for every run:
 - **CMS copy is additive.** The annotation holds the copy the content team signed off. It sits in its own columns and never overwrites `new`. When it differs from `new`, the difference is shown with a warning mark, not hidden.
 - **Figma live first.** CMS annotations and overlay geometry are read from Figma, over REST or through Figma MCP. The design export kept in the repo may be out of date, so it is used only if neither live route works.
 - **Read-only everywhere** except two writes: the Confluence page and, optionally, a pull request that adds `localizations/<slug>/` to the specs repo.
-- **Components are mapped once.** When a reusable component owns a key, the row is flagged `(owned by <Component>)` instead of being mapped again on each screen where the component appears.
+- **Components are mapped once.** When a reusable component owns a key, the row's `newKey` carries `(owned by <Component>)` instead of the key being mapped again on each screen where the component appears.
 - **Chrome language.** Author-written `element` labels and `note` text follow `--ui-lang`; keys and translation values stay verbatim.
 
 It is not a key-minting tool: new keys and their values belong to the resource-authoring flow.
@@ -53,7 +53,7 @@ The helpers in `scripts/` use nothing beyond the Python 3 standard library, apar
 1. **Enumerate new keys.** Take the union of three sources: the design export's `components-used.md` across every state frame, each component's registry `localizationKeys`, and the keys the screen code wires. Tag each key screen-specific, component-owned or shared. Every key is confirmed by comparing sources, never lifted from one of them.
 2. **Catch what the cross-reference misses.** Run `scan-screen-keys.py --screen-path <dir>`. Each `error` and `dynamic` hit becomes a mapping row; compare the `static` hits with the union from step 1.
 3. **New values.** Run `resolve-new-values.py --keys "<all>" --resources-root <res> --langs all --catalog <shipped catalog>`; `--catalog` is never optional.
-4. **CMS copy.** Run `fetch-annotations.py --mapping <map>.json`, falling back from REST to `--from-mcp` and then `--local`. Fill `cms` and `cmsNodeId` on each row, and send any TR without EN back to the content team.
+4. **CMS copy.** Run `fetch-annotations.py --mapping <map>.json [--local <export-screen-dir>]`: it reads REST and falls back to `--local` when REST fails. When REST is rate-limited or has no token, dump the annotations through Figma MCP and run it again with `--from-mcp <dump>.json`. Fill `cms` and `cmsNodeId` on each row, and send any TR without EN back to the content team.
 5. **Trace legacy keys** per platform: spec, then view controller, view model and cell presentation models on iOS; layout `@string/` on Android; call sites on web.
 6. **Legacy values.** Run `resolve-legacy-values.py --keys "<legacy>" --snapshot-root <res>/Localization/Legacy --langs all`; if the snapshot is out of date, `fetch-legacy-labels.py` refreshes it. A value that cannot be found stays blank and gets a note.
 7. **Assemble the mapping JSON**: one row per element, plus `screenshot`, `figmaFileKey` and `legacyKeyPrefix` where they apply. Schema: [format-and-output](reference/format-and-output.md).
@@ -76,7 +76,7 @@ When the Figma frame carries no annotations, say so, explain that keys will be m
 
 Edge cases:
 
-- **Component-owned key**: note `(owned by <Component>)`; do not map it twice.
+- **Component-owned key**: suffix the `newKey` with `(owned by <Component>)`, where the gate looks for it (a note alone does not exempt the row); do not map it twice.
 - **Legacy keys differ across platforms**: keep every platform column that has a key, default to `review`.
 - **`tr` equals `en`**: note it as untranslated whatever the verdict.
 - **CMS present and different from `new`**: the renderer adds the warning mark; mention it in the note. CMS copy is context, not an input to the verdict.

package/pipeline/skills/shared/external/localization-reuse-map/example-mapping.json

@@ -74,7 +74,7 @@
     },
     {
       "element": "Password strength hint (owned by PasswordField)",
-      "newKey": "PasswordField.StrengthHint",
+      "newKey": "PasswordField.StrengthHint (owned by PasswordField)",
       "new": {
         "en": "Use at least 8 characters",
         "tr": "En az 8 karakter kullan"

package/pipeline/skills/shared/external/localization-reuse-map/reference/format-and-output.md

@@ -45,7 +45,7 @@ Keep `new` and `legacy` fully eight-keyed. The summary table shows old and new `
 | 1 | Nav title with no iOS legacy key (`(nav title)` marker) | review |
 | 2 | One shared key, identical on all three platforms | reuse |
 | 3 | Placeholder with no legacy counterpart | new |
-| 4 | Component-owned `PasswordField.StrengthHint` with cross-platform key drift | review |
+| 4 | Component-owned `PasswordField.StrengthHint (owned by PasswordField)` with cross-platform key drift | review |
 | 5 | Duplicate-email error found only by the scanner; the Android key has a typo | review |
 | 6 | CTA whose web key is namespaced (`signup.continue_button`) | review |
 | 7 | `tr` equal to `en` in the redesign source | reuse, flagged untranslated |
@@ -72,7 +72,7 @@ The `--ui-lang` switch (`en` default, `tr`) changes headings, legend, labels and
 
 ## Overlay and keyshots
 
-- `render-overlay.py` writes `<slug>.overlay.png` (or `<slug>.overlay.html` when no Chrome, Chromium or Edge is installed) and `<slug>.overlay.manifest.json` with `screen`, `file`, `fileKey`, `nodeId`, `cardCount`, `annotatedCount`, `width`, `height`, `scale`. Pink cards carry CMS copy; gray cards show the on-screen text and await copy.
+- `render-overlay.py` writes `<slug>.overlay.png` (or `<slug>.overlay.html` when no Chrome, Chromium or Edge is installed) and `<slug>.overlay.manifest.json` with `screen`, `file`, `fileKey`, `nodeId`, `cardCount`, `annotatedCount`, `width`, `height`, `scale`. Pink cards carry CMS copy; gray cards show the on-screen text and await copy. `--ui-lang en/tr` (default `en`) sets the card labels.
 - `render-key-shots.py` writes `keyshots/keyshot__<NN>__<key>.png` (or `.html` crops with `"fallback": "html"`) and `<slug>.keyshots.manifest.json` with `screen`, `slug`, `pad`, `scale`, `dir`, `shots[]` (`row`, `key`, `element`, `file`, `pageNode`, `cropW`, `cropH`) and `missing[]` (`row`, `key`, `reason`).
 
 ## CMS import spreadsheet
@@ -84,7 +84,8 @@ Nine fixed columns, spelled exactly like this:
 `Channel`, `Property Group`, `Property Module`, `Key`, `EN Value`, `TR Value`, `AR Value`, `Anotation EN`, `Anotation TR`
 
 - `Channel` comes from `--channel` (default `Mobile`).
-- `Key` is `newKey` with any `(owned by ...)` suffix removed.
+- `Key` is `newKey` with its trailing marker removed: any parenthesised suffix such as `(owned by ...)` or `(component: ...)`.
+- A row whose key is empty after that, starts with `(dynamic`, or contains a `<placeholder>` has no literal key to import: it is left out of the sheet and listed on stderr.
 - Values come from `new.en/tr/ar`, annotations from `cms.en/tr`; missing means blank.
 - Property Group and Module: row overrides win (each fills its own half). Otherwise the key decides, in order: contains `error` gives Errors; `lookup` gives Lookups; `validation`, `invalid` or a `.valid` ending gives Core / Validation; `field`, `placeholder`, `hint` or `label` gives Core / Fields; a first namespace segment or any word matching a domain list gives the domain group (`Domains`) and the domain name; anything else is Core / Common.
 - Default domains: auth (auth, login, signin, sign-in, register, signup, otp, password), account (account, profile, settings, preferences), checkout (checkout, cart, payment, billing, order), search (search, filter, results). A `--taxonomy` JSON object is merged one level deep over these defaults.
@@ -95,14 +96,14 @@ Nine fixed columns, spelled exactly like this:
 
 | Check | Hard? |
 |---|---|
-| Each `newKey` is wired in the screen code (exact match), or exempt as component-owned or dynamic. A key whose last segment only appears as a word is `weak`; neither is `unverified` | unverified: hard |
+| Each `newKey` is wired in the screen code (exact match), or exempt as component-owned or dynamic. A `LocalizationStringKey` chain counts as a key only with two or more segments, so `extension LocalizationStringKey.Checkin` is not one. A key whose last segment only appears as a word is `weak`; neither is `unverified` | unverified: hard |
 | Keys the code wires that no row maps (`codeKeysNotInMap`) | hard |
 | `reuse` / `review` row without any legacy `en` or `tr` value | hard |
-| Non-`new` row with an empty `new.tr` | soft |
+| Non-`new` row with an empty or whitespace-only `new.tr` | soft |
 | `new.tr` equal to `new.en` (untranslated) | soft |
 | With `--resources-root`: no `Suggested/<Key>.json` in the snapshot or the source layout | soft |
 
-A row is dynamic-exempt when its key starts with `(dynamic`, contains a `<placeholder>`, its element mentions dynamic, or its note says "enumerate at runtime". Exit 2 when any hard issue exists; publish only after fixing them (drop or fix UNVERIFIED keys, add rows for wired-but-unmapped keys) or after a conscious, stated waiver.
+A row is component-exempt when its `newKey` carries a marker naming the owner: `(owned by <Component>)`, `(component ...)` or the Turkish synonym `(bilesen ...)` written with a Turkish s-cedilla (U+015F); the element and note text do not count. A row is dynamic-exempt when its key starts with `(dynamic`, contains a `<placeholder>`, its element mentions dynamic (or the Turkish synonym "dinamik"), or its note says "enumerate at runtime". Folders named `.git` or `Generated` are skipped when scanning; `.github` and similar names are read. Exit 2 when any hard issue exists; publish only after fixing them (drop or fix UNVERIFIED keys, add rows for wired-but-unmapped keys) or after a conscious, stated waiver.
 
 ## Script reference
 
@@ -113,7 +114,7 @@ A row is dynamic-exempt when its key starts with `(dynamic`, contains a `<placeh
 | `resolve-legacy-values.py` | `--keys` (required), `--langs`, `--snapshot-root`, `--live`, `--endpoint`, `--header K=V`, `--headers-file`, `--env`, `--status-field`, `--fail-status CODE=message`, `--timeout`, `--plist-root`, `--prefix` |
 | `fetch-legacy-labels.py` | `--out`, `--endpoint` (both required), `--header`, `--headers-file`, `--langs` (default `all`), `--env`, `--status-field`, `--fail-status`, `--timeout` |
 | `fetch-annotations.py` | `--file`, `--nodes`, `--mapping`, `--from-mcp`, `--local`, `--source auto/rest/mcp/local`, `--token`, `--ca-file`, `--out` |
-| `render-overlay.py` | `--mapping` (required), `--spec`, `--file`, `--nodes`, `--scale`, `--token`, `--ca-file`, `--out`, `--slug` |
+| `render-overlay.py` | `--mapping` (required), `--spec`, `--file`, `--nodes`, `--scale`, `--token`, `--ca-file`, `--out`, `--slug`, `--ui-lang en/tr` |
 | `render-key-shots.py` | `--mapping` (required), `--spec` (repeatable), `--file`, `--nodes`, `--pad` (default 150), `--scale`, `--token`, `--ca-file`, `--out`, `--slug` |
 | `build-artifact.py` | `mapping` (or `-`), `--out`, `--slug`, `--ui-lang en/tr`, `--docx`, `--pdf`, `--all`, `--print-upload` |
 | `build-spreadsheet.py` | `mapping` (or `-`), `--out`, `--slug`, `--channel`, `--taxonomy`, `--csv`, `--csv-only` |

package/pipeline/skills/shared/external/localization-reuse-map/reference/publish-and-snapshot.md

@@ -55,11 +55,11 @@ python3 scripts/publish-confluence.py \
 - **Transport**: `curl` carries every request. The Authorization header is written to a temporary config file with mode 600, handed over with `-K` and removed at the end; JSON bodies also travel through a temporary file.
 - **Idempotent**: the lookup is `GET /rest/api/content?spaceKey=&title=&type=page&expand=version&limit=5`, which reads the database rather than the CQL index. A hit is updated with `PUT` and the next version number, reported as `updated (vN->vN+1)`; a miss is created with `POST` below the parent and reported as `created`. A second run lands on the same page id.
 - **Attachments**: the screenshot first, then the overlay, then each `.png` listed in the keyshots manifest, then every `--attach` file. When a file of that name is already attached, a new version is uploaded to `.../child/attachment/<id>/data` instead of adding a second copy.
-- **Inline spreadsheet**: an `--attach` file with the extension `.xlsx`, `.xls`, `.csv`, `.docx` or `.pdf` is additionally shown on the page: a heading "CMS Aktarım Dosyası" is appended, then one `view-file` macro per such file.
+- **Inline spreadsheet**: an `--attach` file with the extension `.xlsx`, `.xls`, `.csv`, `.docx` or `.pdf` is additionally shown on the page: a heading is appended (`--embed-heading`, default "CMS Import File"; pass the team's own wording, for example a Turkish title, to change it), then one `view-file` macro per such file.
 - **Dry run**: with `--dry-run` nothing is sent; the script prints base, space, parent, title, body size, the attachment list and the action it would take.
 - **Output**: a JSON object with `action`, `id`, `title`, `attachments` and `url`.
 
-Running `build-artifact.py --print-upload` shows the publish command that fits the mapping, plus a hand-written Bearer `curl` version of it that pulls the token out of the keychain. When neither route works, paste the storage XML into the Confluence editor and attach the images under their file names; the XML already points at them by name.
+Running `build-artifact.py --print-upload` shows the publish command that fits the mapping, plus a hand-written Bearer `curl` version of it that pulls the token out of the keychain. File paths in the command are joined with `--out` (overlay, screenshot and keyshots manifest are looked up next to the mapping first), every argument is shell-quoted, and the curl config is created under `umask 077`. When neither route works, paste the storage XML into the Confluence editor and attach the images under their file names; the XML already points at them by name.
 
 ## Option B: specs-repo pull request
 

package/pipeline/skills/shared/external/localization-reuse-map/reference/sources-and-recipes.md

@@ -46,7 +46,7 @@ python3 scripts/resolve-new-values.py --keys "<k1>,<k2>" --resources-root <res>
   --catalog <path/to/shipped/Localizable.xcstrings>
 ```
 
-Always pass `--catalog`. A missing Suggested file means "not in this snapshot", not "unauthored": the snapshot can lag the shipped catalog. With the catalog the value still resolves and the script names the stale snapshot so it can be refreshed with `snapshot-resources.sh`. Only a key absent from both the snapshot and the catalog is truly unauthored. Never open an authoring request for a key the catalog resolved.
+Always pass `--catalog`. A missing Suggested file means "not in this snapshot", not "unauthored": the snapshot can lag the shipped catalog. With the catalog the value still resolves and the script names the stale snapshot so it can be refreshed with `snapshot-resources.sh`. Only a key absent from both the snapshot and the catalog is truly unauthored. A catalog entry that is empty, or has no value in any requested language, counts as absent: the lookup then tries the normalised key form and otherwise lists the key as unresolved. Never open an authoring request for a key the catalog resolved.
 
 ## CMS copy (Figma annotations)
 
@@ -58,6 +58,8 @@ python3 scripts/fetch-annotations.py --out _annotations.json --from-mcp <raw-mcp
 python3 scripts/fetch-annotations.py --out _annotations.json --local <design-export>/screens/<frame>
 ```
 
+The default source is REST; when it fails and `--local` is given, the export's `tree.json` is read instead. `--from-mcp` is never tried automatically: after a rate limit (HTTP 429), dump the annotations through Figma MCP and rerun with that file. Node-ids in the URL form `1024-4150` are read as `1024:4150`; an annotation without a node-id is kept as its own entry, never merged with another.
+
 Pair every annotation with its row through `nodeId`: the id is saved in the row as `cmsNodeId`, and the copy goes into `cms: {tr, en}`. An element without an annotation keeps a blank CMS cell. The script lists nodes that have TR but no EN; send those back to the content team.
 
 ## Legacy keys: trace, do not skim
@@ -91,6 +93,7 @@ python3 scripts/resolve-legacy-values.py --keys "Continue,EmailAddress" \
 
 - Reading the snapshot needs no network. `fetch-legacy-labels.py` refreshes it and is the only step that goes online.
 - `--live` checks against the service directly; if the live call fails, the script falls back to the snapshot, then to the plists.
+- With none of `--snapshot-root`, `--plist-root` or `--endpoint`, the script stops with a message naming them.
 - `--plist-root` reads the bundled `<lang>.lproj/language.plist` as a last resort. It is usually a stale subset, so a hit from it deserves a note.
 - **Backend prefix.** When the backend stores `Mobile-Continue` but the app asks for `Continue`, pass `--prefix Mobile-`, keep the mapping keys bare, and set the mapping's `legacyKeyPrefix` so the table shows the full stored key.
 
@@ -108,7 +111,7 @@ The overlay does not depend on annotations. With zero annotations every keyed el
   "nodes": [{"id": "n1", "x": 16, "y": 64, "w": 220, "h": 28, "side": "left"}]}]}
 ```
 
-`image` is either a data URL or a PNG path, resolved from the folder of the spec file. `side` is `left` (default) or `right`: it puts the card on the side where its target sits, which two-column layouts need. Each side is numbered and stacked independently, and right-side connectors are mirrored.
+Every page needs `frame` with numeric `w` and `h`; a page without it stops the script with an error naming the page. `render-overlay.py` draws only the first page and warns when there are more; `render-key-shots.py` reads every page. `image` is either a data URL or a PNG path, resolved from the folder of the spec file. `side` is `left` (default) or `right`: it puts the card on the side where its target sits, which two-column layouts need. Each side is numbered and stacked independently, and right-side connectors are mirrored.
 
 The export's `tree.json` stops at component instances and carries no geometry per label, so take only the frame node-id from it.
 

package/pipeline/skills/shared/external/localization-reuse-map/scripts/_shared.py

@@ -0,0 +1,100 @@
+"""Key patterns, mapping-row marker rules and text helpers shared by the scripts.
+
+Every script that scans keys, names output files or orders languages imports
+this module, so the scanner, the gate, the CMS sheet and the overlay agree on
+what a wired key is, which rows are component-owned or dynamic, which files are
+source, how a screen name becomes a file slug and which order languages take.
+"""
+import os
+import re
+
+EXTENSIONS = {".swift", ".kt", ".kts", ".xml", ".ts", ".tsx", ".js", ".jsx", ".vue"}
+SKIP_DIRS = {".git", "Generated"}
+LANGS = ["en", "tr", "ar"] + sorted(["ru", "it", "fr", "es", "de"])
+
+WORD = "A-Za-z0-9_"
+IDENT = rf"[A-Za-z_][{WORD}]*"
+LSK = re.compile(rf"LocalizationStringKey((?:\.{IDENT})+)")
+LITERAL_KEY = re.compile(rf"\"([{WORD}.]+)\"\.localized\b")
+WEB_T = re.compile(r"(?<![\w$])t\(\s*(['\"])([A-Za-z0-9_.\-]+)\1")
+WEB_DOLLAR_T = re.compile(r"\$t\(\s*(['\"])([A-Za-z0-9_.\-]+)\1")
+INTERPOLATION = re.compile(r"\\\(|\$\{|\$[A-Za-z_]")
+
+TRAILING_MARKER = re.compile(r"\s*\([^()]*\)\s*$")
+COMPONENT_MARKER = re.compile(r"\([^)]*(owned by|bile\u015fen|component)[^)]*\)", re.IGNORECASE)
+PLACEHOLDER = re.compile(r"<[^<>]+>")
+DYNAMIC_WORDS = ("dynamic", "dinamik")
+RUNTIME_NOTE = "enumerate at runtime"
+
+XML_INVALID = re.compile("[\x00-\x08\x0b\x0c\x0e-\x1f]")
+
+
+def strip_accessor(chain):
+    segments = chain.strip(".").split(".")
+    while segments and segments[-1].startswith("localized"):
+        segments.pop()
+    return ".".join(segments)
+
+
+def lsk_keys(text):
+    for hit in LSK.finditer(text):
+        key = strip_accessor(hit.group(1))
+        if key.count(".") >= 1:
+            yield key
+
+
+def is_interpolated(literal):
+    return bool(INTERPOLATION.search(literal))
+
+
+def normalize_key(key):
+    return ".".join(seg[:1].upper() + seg[1:] for seg in key.split("."))
+
+
+def source_files(root):
+    if os.path.isfile(root):
+        yield root
+        return
+    for current, dirs, files in os.walk(root):
+        relative = os.path.relpath(current, root)
+        parts = [] if relative == os.curdir else relative.split(os.sep)
+        if SKIP_DIRS.intersection(parts):
+            dirs[:] = []
+            continue
+        for name in sorted(files):
+            if os.path.splitext(name)[1] in EXTENSIONS:
+                yield os.path.join(current, name)
+
+
+def raw_key(row):
+    return str(row.get("newKey") or "").strip()
+
+
+def clean_key(new_key):
+    text = str(new_key or "").strip()
+    if text.startswith("(dynamic"):
+        return text
+    return TRAILING_MARKER.sub("", text)
+
+
+def is_component(row):
+    return bool(COMPONENT_MARKER.search(raw_key(row)))
+
+
+def key_is_dynamic(key):
+    return key.startswith("(dynamic") or bool(PLACEHOLDER.search(key))
+
+
+def is_dynamic(row, key):
+    element = str(row.get("element") or "").lower()
+    note = str(row.get("note") or "").lower()
+    return key_is_dynamic(key) or any(word in element for word in DYNAMIC_WORDS) or RUNTIME_NOTE in note
+
+
+def xml_text(value):
+    return XML_INVALID.sub("", str(value))
+
+
+def slug(text):
+    value = re.sub(r"[\W_]+", "-", str(text or "").strip().lower()).strip("-")
+    return value or "screen"

package/pipeline/skills/shared/external/localization-reuse-map/scripts/build-artifact.py

@@ -11,6 +11,7 @@ import html
 import json
 import os
 import re
+import shlex
 import shutil
 import struct
 import subprocess
@@ -22,7 +23,8 @@ import zipfile
 from collections import namedtuple
 from xml.sax.saxutils import escape, quoteattr
 
-LANGS = ["en", "tr", "ar"] + sorted(["ru", "it", "fr", "es", "de"])
+from _shared import LANGS, slug, xml_text
+
 WARN = "\u26a0\ufe0f"
 DASH = "-"
 VERDICTS = ("reuse", "review", "new")
@@ -120,11 +122,6 @@ def look(row):
     return LOOKS.get(row.get("verdict"), UNKNOWN_LOOK)
 
 
-def slug(text):
-    value = re.sub(r"[\W_]+", "-", str(text or "").strip().lower()).strip("-")
-    return value or "screen"
-
-
 def norm(value):
     text = unicodedata.normalize("NFC", str(value or "")).strip()
     text = re.sub(r"\s+", " ", text)
@@ -189,8 +186,12 @@ def load_keyshots(mapping, mapping_dir, out_dir):
     return shots
 
 
+def xml_escape(value):
+    return escape(xml_text(value))
+
+
 def node(name, attrs=(), *children):
-    opening = name + "".join(f" {k}={quoteattr(str(v))}" for k, v in attrs)
+    opening = name + "".join(f" {k}={quoteattr(xml_text(v))}" for k, v in attrs)
     if not children:
         return f"<{opening}/>"
     return f"<{opening}>{''.join(children)}</{name}>"
@@ -291,12 +292,12 @@ class Doc:
         return storage_macro(
             "status",
             node("ac:parameter", [("ac:name", "colour")], look(row).status),
-            node("ac:parameter", [("ac:name", "title")], escape(self.verdict(row))),
+            node("ac:parameter", [("ac:name", "title")], xml_escape(self.verdict(row))),
         )
 
     def xml(self):
         t, m = self.t, self.m
-        e = escape
+        e = xml_escape
 
         def heading(label):
             return f"<h2>{e(t[label])}</h2>"
@@ -504,7 +505,7 @@ def para(text, bold=False, size=None, rtl=False):
     if rtl:
         styling.append(w("rtl"))
     run = [w("rPr", *styling)] if styling else []
-    run.append(node("w:t", [("xml:space", "preserve")], escape(str(text))))
+    run.append(node("w:t", [("xml:space", "preserve")], xml_escape(text)))
     lead = [w("pPr", w("bidi"))] if rtl else []
     return w("p", *lead, w("r", *run))
 
@@ -663,17 +664,21 @@ def chrome_candidates():
 
 def pdf_libreoffice(docx_path, out_dir):
     binaries = [shutil.which("soffice"), shutil.which("libreoffice"), mac_app("LibreOffice", "soffice")]
-    expected = os.path.splitext(docx_path)[0] + ".pdf"
+    name = os.path.splitext(os.path.basename(docx_path))[0] + ".pdf"
     for binary in binaries:
         if not (binary and os.path.isfile(binary)):
             continue
-        try:
-            subprocess.run([binary, "--headless", "--convert-to", "pdf", "--outdir", out_dir, docx_path],
-                           capture_output=True, timeout=180)
-        except (OSError, subprocess.SubprocessError):
-            continue
-        if os.path.isfile(expected) and os.path.getsize(expected) > 0:
-            return expected
+        with tempfile.TemporaryDirectory() as scratch:
+            try:
+                subprocess.run([binary, "--headless", "--convert-to", "pdf", "--outdir", scratch, docx_path],
+                               capture_output=True, timeout=180)
+            except (OSError, subprocess.SubprocessError):
+                continue
+            rendered = os.path.join(scratch, name)
+            if os.path.isfile(rendered) and os.path.getsize(rendered) > 0:
+                target = os.path.join(out_dir, name)
+                shutil.copyfile(rendered, target)
+                return target
     return None
 
 
@@ -698,7 +703,7 @@ def pdf_chrome(preview_path, pdf_path):
             with tempfile.TemporaryDirectory() as profile:
                 if os.path.exists(pdf_path):
                     os.remove(pdf_path)
-                argv = [chrome, headless, "--disable-gpu", f"--user-data-dir={profile}", "--no-pdf-header-footer",
+                argv = [chrome, headless, "--no-sandbox", "--disable-gpu", f"--user-data-dir={profile}", "--no-pdf-header-footer",
                         f"--print-to-pdf={pdf_path}", page]
                 try:
                     proc = subprocess.Popen(argv, stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)
@@ -721,17 +726,31 @@ def pdf_wkhtml(preview_path, pdf_path):
     return pdf_path if os.path.isfile(pdf_path) and os.path.getsize(pdf_path) > 0 else None
 
 
-def print_upload(name, mapping, screen):
+def upload_path(name, mapping_dir, out_dir):
+    if os.path.isabs(name):
+        return name
+    for folder in (mapping_dir, out_dir):
+        if os.path.exists(os.path.join(folder, name)):
+            return os.path.join(folder, name)
+    return os.path.join(out_dir, name)
+
+
+def print_upload(name, mapping, screen, mapping_dir, out_dir):
     prefix = os.environ.get("LOCALIZATION_PAGE_PREFIX", "Localization")
-    flags = [f"--xml {name}.confluence.xml", f'--screen "{screen}"']
-    flags += [f"--{field} {mapping[field]}" for field in ("screenshot", "overlay", "keyshots") if mapping.get(field)]
-    flags.append(f"--attach {name}.localization.xlsx")
+    quote = shlex.quote
+    flags = [f"--xml {quote(os.path.join(out_dir, name + '.confluence.xml'))}", f"--screen {quote(str(screen))}"]
+    flags += [
+        f"--{field} {quote(upload_path(str(mapping[field]), mapping_dir, out_dir))}"
+        for field in ("screenshot", "overlay", "keyshots") if mapping.get(field)
+    ]
+    flags.append(f"--attach {quote(os.path.join(out_dir, name + '.localization.xlsx'))}")
     print(" \\\n  ".join(["python3 scripts/publish-confluence.py"] + flags))
     print()
+    title = json.dumps(f"{prefix} - {screen}", ensure_ascii=False).replace("'", "'\\''")
     print("# The same call by hand, for Server/DC with a Bearer PAT read from the keychain (argv never sees the token):")
-    print("#   printf 'header = \"Authorization: Bearer %s\"\\n' \"$(security find-generic-password -s CONFLUENCE_API_TOKEN -w)\" > auth.curlrc; chmod 600 auth.curlrc")
+    print("#   (umask 077 && rm -f auth.curlrc && printf 'header = \"Authorization: Bearer %s\"\\n' \"$(security find-generic-password -s CONFLUENCE_API_TOKEN -w)\" > auth.curlrc)")
     print("#   curl -sS -K auth.curlrc -X POST -H 'Content-Type: application/json' \"$CONFLUENCE_BASE_URL/rest/api/content\" \\")
-    print(f"#     --data '{{\"type\":\"page\",\"title\":\"{prefix} - {screen}\",\"space\":{{\"key\":\"'$CONFLUENCE_SPACE'\"}},"
+    print(f"#     --data '{{\"type\":\"page\",\"title\":{title},\"space\":{{\"key\":\"'$CONFLUENCE_SPACE'\"}},"
           "\"ancestors\":[{\"id\":\"'$CONFLUENCE_PARENT'\"}],\"body\":{\"storage\":{\"value\":\"...\",\"representation\":\"storage\"}}}'")
     print("#   rm auth.curlrc")
 
@@ -797,7 +816,7 @@ def main():
         make_pdf(docx_path, out_dir, stem, keep_docx)
 
     if opts.print_upload:
-        print_upload(stem, mapping, mapping.get("screen"))
+        print_upload(stem, mapping, mapping.get("screen"), mapping_dir, out_dir)
 
 
 if __name__ == "__main__":

package/pipeline/skills/shared/external/localization-reuse-map/scripts/build-spreadsheet.py

@@ -15,6 +15,8 @@ import sys
 import zipfile
 from xml.sax.saxutils import escape
 
+from _shared import clean_key, key_is_dynamic, slug, xml_text
+
 COLUMNS = [
     "Channel", "Property Group", "Property Module", "Key",
     "EN Value", "TR Value", "AR Value", "Anotation EN", "Anotation TR",
@@ -37,11 +39,6 @@ DEFAULT_TAXONOMY = {
 }
 
 
-def slug(text):
-    value = re.sub(r"[\W_]+", "-", str(text or "").strip().lower()).strip("-")
-    return value or "screen"
-
-
 def read_json(source):
     with open(source, encoding="utf-8") as stream:
         return json.load(stream)
@@ -62,12 +59,6 @@ def load_taxonomy(path):
     return taxonomy
 
 
-def clean_key(new_key):
-    text = str(new_key or "")
-    cut = text.find("(owned by")
-    return (text[:cut] if cut >= 0 else text).strip()
-
-
 def bucket(key, taxonomy):
     lowered = key.lower()
     if "error" in lowered:
@@ -88,9 +79,12 @@ def bucket(key, taxonomy):
 
 
 def table_rows(mapping, channel, taxonomy):
-    out = []
-    for row in mapping.get("rows") or []:
+    out, skipped = [], []
+    for number, row in enumerate(mapping.get("rows") or [], 1):
         key = clean_key(row.get("newKey"))
+        if not key or key_is_dynamic(key):
+            skipped.append((number, key))
+            continue
         group, module = bucket(key, taxonomy)
         if row.get("propertyGroup"):
             group = row["propertyGroup"]
@@ -103,7 +97,7 @@ def table_rows(mapping, channel, taxonomy):
             new.get("en") or "", new.get("tr") or "", new.get("ar") or "",
             cms.get("en") or "", cms.get("tr") or "",
         ])
-    return out
+    return out, skipped
 
 
 def column_letter(index):
@@ -137,7 +131,7 @@ def part(root, attrs, *children):
 
 
 def cell(ref, value, style):
-    text = escape(str(value)).replace("\n", "
")
+    text = escape(xml_text(value)).replace("\n", "
")
     attrs = [("r", ref), ("t", "inlineStr")]
     if style:
         attrs.append(("s", style))
@@ -276,7 +270,7 @@ def main():
     if not isinstance(mapping, dict) or "rows" not in mapping:
         cli.error("mapping must be a JSON object with rows")
 
-    rows = table_rows(mapping, opts.channel, load_taxonomy(opts.taxonomy))
+    rows, skipped = table_rows(mapping, opts.channel, load_taxonomy(opts.taxonomy))
     stem = opts.slug or slug(mapping.get("screen"))
     os.makedirs(opts.target_dir, exist_ok=True)
 
@@ -294,6 +288,10 @@ def main():
     summary = {"slug": stem, "rows": len(rows), "columns": COLUMNS, "channel": opts.channel, "written": produced}
     json.dump(summary, sys.stdout, indent=2, ensure_ascii=False)
     sys.stdout.write("\n")
+    if skipped:
+        print(f"# {len(skipped)} row(s) left out of the sheet: no literal key (empty, dynamic or <placeholder>)", file=sys.stderr)
+        for number, key in skipped:
+            print(f"#   row {number}: {key or '(empty)'}", file=sys.stderr)
 
 
 if __name__ == "__main__":

package/pipeline/skills/shared/external/localization-reuse-map/scripts/fetch-annotations.py

@@ -24,8 +24,12 @@ TR_RE = re.compile("^(?:tr|tr[kc]e|t[\u00fcu]rk[\u00e7c]e)\\s*" + SEP + "\\s*(.+
 EN_RE = re.compile("^(?:en|eng|ing|[i\u0130]ngilizce)\\s*" + SEP + "\\s*(.+)$", re.IGNORECASE)
 
 
+URL_NODE_ID = re.compile(r"^\d+-\d+$")
+
+
 def canon_id(node_id):
-    return str(node_id).strip().replace("-", ":")
+    text = "" if node_id is None else str(node_id).strip()
+    return text.replace("-", ":") if URL_NODE_ID.match(text) else text
 
 
 def split_lang(text):
@@ -68,7 +72,7 @@ def pick_label(labels):
 def record(node_id, name, node_type, design_text, labels):
     raw, parsed = pick_label(labels)
     return {
-        "nodeId": canon_id(node_id),
+        "nodeId": canon_id(node_id) or None,
         "name": name,
         "type": node_type,
         "designText": design_text,
@@ -246,10 +250,13 @@ def main():
 
     source, found, files, audited = pick_source(opts, cli, file_key, nodes)
 
-    first_seen = {}
+    unique, seen = [], set()
     for item in found:
-        first_seen.setdefault(item["nodeId"], item)
-    unique = list(first_seen.values())
+        if item["nodeId"]:
+            if item["nodeId"] in seen:
+                continue
+            seen.add(item["nodeId"])
+        unique.append(item)
 
     def having(lang):
         return sum(1 for entry in unique if entry[lang])

package/pipeline/skills/shared/external/localization-reuse-map/scripts/fetch-legacy-labels.py

@@ -11,7 +11,8 @@ import os
 import sys
 import urllib.request
 
-ALL_LANGS = ["en", "tr", "ar"] + sorted(["ru", "it", "fr", "es", "de"])
+from _shared import LANGS as ALL_LANGS
+
 
 
 def parse_langs(value):

package/pipeline/skills/shared/external/localization-reuse-map/scripts/publish-confluence.py

@@ -16,10 +16,10 @@ import subprocess
 import sys
 import tempfile
 import urllib.parse
-from xml.sax.saxutils import quoteattr
+from xml.sax.saxutils import escape, quoteattr
 
 EMBED_EXTENSIONS = {".xlsx", ".xls", ".csv", ".docx", ".pdf"}
-EMBED_HEADING = "CMS Aktar\u0131m Dosyas\u0131"
+EMBED_HEADING = "CMS Import File"
 CONTENT = "/rest/api/content"
 
 
@@ -82,8 +82,8 @@ def view_file_macro(path):
     return f'<p><ac:structured-macro ac:name="view-file">{parameter}</ac:structured-macro></p>'
 
 
-def embed_block(files):
-    return f"<h2>{EMBED_HEADING}</h2>" + "".join(map(view_file_macro, files))
+def embed_block(files, heading):
+    return f"<h2>{escape(heading)}</h2>" + "".join(map(view_file_macro, files))
 
 
 def keyshot_files(manifest_path):
@@ -113,6 +113,7 @@ def build_cli():
     cli.add_argument("--parent", default=os.environ.get("CONFLUENCE_PARENT"), help="id of the parent page")
     cli.add_argument("--token", help="Bearer PAT; CONFLUENCE_API_TOKEN or the keychain is safer since other processes can read argv")
     cli.add_argument("--keychain-name", default="CONFLUENCE_API_TOKEN", help="keychain service that stores the PAT")
+    cli.add_argument("--embed-heading", default=EMBED_HEADING, help="heading above the embedded spreadsheet / document previews")
     cli.add_argument("--dry-run", action="store_true", help="report the planned actions without touching Confluence")
     return cli
 
@@ -174,7 +175,7 @@ def main():
         body = stream.read()
     embedded = [p for p in opts.attach if os.path.splitext(p)[1].lower() in EMBED_EXTENSIONS]
     if embedded:
-        body += embed_block(embedded)
+        body += embed_block(embedded, opts.embed_heading)
 
     if opts.dry_run:
         plan = {