@mmerterden/multi-agent-pipeline 14.2.1 → 14.2.2

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

@@ -0,0 +1,302 @@
+---
+name: localization-reuse-map
+description: >-
+  Produce a per-screen localization-reuse map for one redesigned screen (iOS / Android / web) so content
+  management can decide whether existing translations can be reused. For one screen it ties each UI element to
+  its NEW (redesign) localization key + values, its LEGACY key + values per platform, AND the content team's
+  ACTUAL final copy (CMS) read live from Figma Dev Mode annotations  -  old key, new key, old translations, new
+  translations, CMS copy  -  recommends a reuse verdict (reuse / review / new) the content team confirms, renders
+  a visual key-to-UI overlay plus a per-key red-box screenpiece for every table row, and publishes a Confluence
+  page LIVE (idempotent  -  re-running a screen updates its page in place). New side = the redesign app's key
+  usage + the authored/suggested translation values + the design component registry; legacy side = the legacy
+  app's keys (iOS `"Key".localized` / Android `@string/Key` / web `t('key')` i18n calls) and its label
+  service; CMS side = Figma annotations
+  via REST API / MCP / local fallback. Also scans the implemented screen for error and dynamic keys the registry
+  misses. Use it when mapping a redesigned screen's strings to the legacy ones for reuse, one screen at a time.
+  Trigger phrases  -  "localization reuse map", "map old keys to new keys for this screen", "which legacy
+  translations can we reuse", "reuse existing translations", "CMS copy from Figma annotations", "localization
+  excel", "CMS import sheet", "/localization-reuse-map".
+---
+
+# Localization Reuse Map  -  old↔new localization map for one screen
+
+Produces, for **one redesigned screen**, the table content management needs: every UI element with its
+**new** key + translations, its **legacy** key + translations per platform, and the content team's **actual
+CMS copy** (Figma annotations), plus a **recommended** reuse verdict, a **visual key↔UI overlay**, and a
+**per-key screenpiece** (a red-box crop showing where that key lives on screen) embedded in each table row  -  
+published **live** as a Confluence page. The skill **recommends; the content team decides**.
+
+**Detail:** [reference/sources-and-recipes.md](reference/sources-and-recipes.md) (data model + exact
+per-source retrieval recipes, incl. CMS annotations + the implemented-screen scan) ·
+[reference/format-and-output.md](reference/format-and-output.md) (verdict taxonomy + mapping JSON schema +
+CMS columns + Confluence output) · [reference/publish-and-snapshot.md](reference/publish-and-snapshot.md)
+(publish live to Confluence + the `localizations/` PR + snapshot the resources in-repo).
+**Input shape:** [example-mapping.json](example-mapping.json).
+
+## Project configuration  -  resolve these first
+Nothing about any one company is baked in. Establish these once per project (ask the user, or read them from
+the project's own docs) and reuse them for every screen:
+
+| What | Used for | Example |
+|---|---|---|
+| Specs repo + design-export path | screen frames, `components-used.md`, `screenshot.png`, `tree.json` | `design-export/<project>/screens/<slug>/` |
+| Resources root | authored/suggested new values + the component registry | `resources/Localization/Suggested/<Key>.json` |
+| Legacy label endpoint + headers | refreshing the legacy value snapshot | `--endpoint` + `--headers-file` |
+| Legacy key prefix (if any) | display-only re-prefixing in the table | mapping `legacyKeyPrefix` |
+| Web i18n convention (legacy AND new, if either is a web app) | which call form + key-file shape the tracer/scanner look for | `t('key')` / `$t('key')` reading `locales/<lang>.json` |
+| Confluence base URL / space / parent | publishing | `CONFLUENCE_BASE_URL` / `_SPACE` / `_PARENT` |
+| CMS bucket taxonomy | the spreadsheet's Property Group / Module | `--taxonomy cms-taxonomy.json` |
+| Document language | template chrome + author-written fields | `--ui-lang en` (default) / `tr` |
+
+Secrets stay in a keychain item or a `--headers-file`, never in the mapping, the docs, or argv.
+
+## Scope
+One screen per run, every platform the screen exists on; publishes the map **live to Confluence** (idempotent
+update-in-place) and optionally to the specs repo's `localizations/` as a PR  -  the user is asked which target
++ space/formats. Out: cross-screen rollups and minting/defining new keys (that is the resource-authoring flow,
+not this skill).
+
+## Invariants  -  read before running
+- **One screen per run.** The unit is a screen; keys owned by a *reusable component* are flagged, not
+  re-mapped  -  they are mapped once where that component is mapped.
+- **The skill recommends; the content team decides** the reuse call. Never present a verdict as final.
+- **Never invent a legacy value.** Legacy translations are backend-served  -  fetch them or leave the Old
+  column blank with a note. Blank beats a guess. (See sources-and-recipes "Legacy translation values".)
+- **Never invent a CMS value.** The CMS column is the content team's *actual* copy  -  fetch it from the Figma
+  annotation or leave it blank. The annotation is authoritative as their final copy; it is shown
+  **additively** (it never overwrites the `new` value), and a CMS≠new difference is surfaced (⚠), not hidden.
+- **Figma is live-first.** The CMS annotations + overlay are fetched from the Figma **REST API** (or MCP),
+  falling back to the in-repo design export only when neither is reachable  -  because Figma is edited
+  continuously and the snapshot can be stale.
+- **Read-only across every source.** This skill produces an artifact; it edits no repo and defines no key.
+  (The only writes are the Confluence page it publishes and the optional `localizations/` PR.)
+- **Author the document in the content team's language.** The author-supplied `element` labels and `note`
+  annotations must match the chrome language (`--ui-lang`)  -  they are the only free text in the doc, so a
+  mixed-language run reads as half-translated. Only keys and translation values stay verbatim.
+
+## Sources (self-contained  -  no other skill required)
+Retrieval is a **cross-reference, not a skim**  -  that distinction is the whole skill. Full recipes:
+[reference/sources-and-recipes.md](reference/sources-and-recipes.md).
+- **New keys**  -  cross-reference three: the design export's `screens/<frame>/components-used.md` (which
+  components, **all** state frames) **×** each component's registry `<node>.json → localizationKeys` (keys it
+  renders internally, often absent from screen code) **×** the screen's code (what it wires). Union; tag
+  screen-specific / component-owned / shared.
+- **New values**  -  the authored per-key source (`Suggested/<Key>.json`, 8 langs):
+  `scripts/resolve-new-values.py --langs all --catalog <shipped catalog>`. **Always pass
+  `--catalog`.** The Suggested tree is a generated snapshot and goes stale the moment a key is
+  added upstream, so a missing file means "not in this snapshot", never "this key is
+  unauthored". With the catalog the script resolves the value anyway and reports that the
+  snapshot needs `snapshot-resources.sh`; without it every stale key reads as needing authoring.
+- **CMS values (content team's actual copy)**  -  Figma Dev Mode annotations, fetched **live**:
+  `scripts/fetch-annotations.py --mapping <map>.json` (REST primary → `--from-mcp` → `--local` fallback).
+  Map each annotation to its row by `nodeId` → fill `cms:{tr,en}`. Blank when not yet annotated.
+- **Error / dynamic keys the cross-reference misses**  -  scan the *implemented* screen:
+  `scripts/scan-screen-keys.py --screen-path <dir>` → error/validation/alert + dynamic/`String(format:)`/
+  variable-`.localized` keys (categorized). Fold the `error`/`dynamic` hits into the mapping.
+- **Legacy keys**  -  **trace the screen**, don't skim: iOS VC→VM→**cell presentation models**
+  (`"Key".localized`); Android layout `@string/Key`; web component→ `t('key')`/`$t('key')` call site,
+  key resolved against the legacy app's `locales/<lang>.json` (or equivalent i18n catalog). The screen's
+  spec names the legacy entry class/component.
+- **Legacy values**  -  the in-repo label snapshot (offline, no network per run):
+  `scripts/resolve-legacy-values.py --snapshot-root <resources>/Localization/Legacy --keys "..." --langs all`.
+  Refresh the snapshot (the only network step) with `scripts/fetch-legacy-labels.py --endpoint ...
+  --headers-file ...`. `--live` to verify; `--plist-root` last-resort.
+- **A legacy key prefix** the backend stores but the app strips is kept out of the mapping and re-added for
+  display via the mapping's `legacyKeyPrefix` (`Continue` → displayed `Mobile-Continue`).
+- **Screenshot**  -  the design export's `screens/<frame>/screenshot.png`.
+- **Overlay (key↔UI image)**  -  `scripts/render-overlay.py --mapping <map>.json` (REST primary → `--spec`
+  MCP). Embedded in the page as a "key map" section; needs headless Chrome (falls back to `.html`).
+- **Per-key screenpieces (keyshots)**  -  `scripts/render-key-shots.py --mapping <map>.json` (same REST /
+  `--spec` modes and the same row↔node matcher as the overlay): one red-box crop per matched row →
+  `keyshots/keyshot__<NN>__<key>.png` + `<slug>.keyshots.manifest.json`; the table's "Screenshot"
+  cells embed them. Unmatched rows render "  -  ", never a guessed crop.
+- **Document language**  -  `--ui-lang en` (default) or `tr`.
+
+*Figma: for **structure** (components, nodes, screenshot) the in-repo design export is the source. For **CMS
+annotations + the overlay** the live **REST API** is primary (token in keychain `FIGMA_ACCESS_TOKEN`) with
+**MCP** (Dev Mode) as the no-rate-limit alternative; the export is the offline fallback.*
+
+## Decision rules
+- Verdict per row: **reuse** (same function + same/equivalent value, or a clean shared key on both legacy
+  platforms) · **review** (same function but value / key / cross-platform drift) · **new** (no legacy
+  counterpart). Full table in format-and-output.md.
+- Key owned by a reusable component, not the screen → flag it (`(owned by ...)`), don't double-map.
+- Legacy keys differ across the platforms present (iOS/Android/web) → keep every column that has one,
+  default to **review** (drift to resolve).
+- A `tr` value equal to its `en` value → note it (untranslated) regardless of verdict.
+- **CMS value present and ≠ the `new` value** → the renderer marks it ⚠; call it out in the note (the content
+  team's final copy diverged from the mock). CMS is additive context for the verdict, not a verdict input.
+- **Dynamic key** that can't be statically resolved → map it with `verdict: review` + a "dynamic  -  enumerate
+  at runtime" note; never drop it.
+
+## Procedure
+
+*Ask the user up front for what's missing* (interactive): the implemented **screen path**, the **Figma
+file key + node-ids** (or confirm the design-export slug), and at publish time the **Confluence target**
+(space / parent / formats). Don't block on what you can derive; ask only for gaps.
+
+1. **Enumerate new keys + elements (cross-reference).** From the design export get the screen's components
+   (all state frames) + screenshot; read each component's registry `localizationKeys`; read the screen's
+   code for wired keys. Union → one element per key, tagged screen/component/shared.
+2. **Scan the implemented screen for the keys the cross-reference misses** (script):
+   `python3 scripts/scan-screen-keys.py --screen-path <dir>` → fold the **error** + **dynamic** hits into the
+   element list (the static union is blind to them); diff `static` hits vs the registry union.
+3. **Resolve new values** (script): `python3 scripts/resolve-new-values.py --resources-root <resources>
+   --keys "<all keys>" --langs all --catalog <shipped catalog>`. Only a key absent from BOTH the
+   snapshot and the catalog is genuinely unauthored; anything the catalog resolved means the
+   snapshot is stale (refresh it, do not open authoring requests).
+4. **Fetch CMS copy from Figma annotations** (script): `python3 scripts/fetch-annotations.py --mapping
+   <map>.json` (REST primary → `--from-mcp` → `--local`). Map each annotation to its row by `nodeId`
+   (store `cmsNodeId`) → fill `cms:{tr,en}`. Leave blank where unannotated; flag TR-without-EN.
+5. **Trace legacy keys, every platform** (sources-and-recipes recipes): the spec's legacy reference →
+   VM → cell presentation models (iOS); layout `@string/` (Android). Don't stop at the VM.
+6. **Resolve legacy values** (script): `python3 scripts/resolve-legacy-values.py --snapshot-root
+   <resources>/Localization/Legacy --keys "<legacy keys>" --langs all` (offline snapshot; refresh it with
+   `fetch-legacy-labels.py` when needed). Absent → leave blank + note.
+7. **Assemble the mapping JSON** (schema in format-and-output.md)  -  one row per element: new/legacy keys +
+   8-lang `new`/`legacy` values + `cms`/`cmsNodeId` + a recommended `verdict` + `note`. Add `screenshot`,
+   `figmaFileKey`, and `legacyKeyPrefix` when the backend uses one.
+8. **Render the key↔UI overlay** (script): `python3 scripts/render-overlay.py --mapping <map>.json --out
+   <dir>` → `<slug>.overlay.png`; set the mapping's top-level `overlay` to that filename. **The overlay does
+   NOT need annotations**  -  with zero CMS annotations it still maps every keyed element to its spot on the
+   screen (gray "awaiting copy" cards). **Card numbers = table row numbers:** each card (and its dot) is
+   numbered by the matched row's position in `mapping.rows`, i.e. the same number `build-artifact` prints in
+   the table  -  so a mark on the screen and its table row always agree (they are NOT renumbered by layout
+   order). Pick the geometry source in this order:
+   - **REST** (`--mapping` with `figmaFileKey` + the real **frame node**): full per-label geometry. Get the
+     frame's true node-id from the design export screen's `tree.json` **root `nodeId`** (the folder-name
+     suffix and any id in the old map are often stale/wrong  -  verify the node's text is actually this
+     screen's). A frame may include background content (the screen shown as a sheet over another)  -  the
+     non-matching nodes are dropped automatically.
+   - **`--spec` (screenshot-anchored, no token / when REST geometry is noisy or unavailable)**  -  the reliable
+     fallback the agent drives: read each visible element's box **off the clean screenshot**, set that row's
+     `cmsNodeId` to a synthetic id (`n1`, `n2`, ...), and emit a spec page `{fileKey, pages:[{nodeId, image:
+     "<screenshot dataURL>", frame:{w,h}, nodes:[{id:"n1", characters:"<on-screen text>", x,y,w,h, side}]}]}`.
+     `render-overlay` anchors each card by `cmsNodeId` → exact key, positions from the real render.
+   - **`side: "left" | "right"` per node (default left)**  -  put a card on the side of the frame its target sits
+     on, so the connector stays short and doesn't cross the whole screen. Essential for **two-column layouts**:
+     flag the right-column entries `"side":"right"` and they render as a right-hand card column with mirrored
+     connectors; the left column stays left. Cards on each side are numbered and stacked independently.
+   - The export's `tree.json` alone is **component-instance level** (no per-label geometry)  -  use it for the
+     frame node-id, not for label boxes. No Chrome → `.html` fallback.
+
+   **Mark component-owned keys on the overlay too.** A screen is mostly reusable-component instances
+   (list rows, promotion grids, summary cards) whose keys the screen code never wires  -  but the content team
+   still sees that copy on this screen. Map them here (this is where the component is used), each flagged
+   `(owned by <Component>)` in its `note`, and anchor them on the screenshot. Pull the component's keys from
+   its registry `<node>.json → localizationKeys`. These are the keys a plain screen-code scan is blind to.
+
+   **One screen, several states → several screenshots, one composite overlay.** A key like an "Added" badge or
+   a "Remove" link only appears in one state, not the default mock. Render one overlay per state (each
+   `--spec` a different screenshot with that state's `cmsNodeId`s  -  `render-overlay` cards only the rows whose
+   node matches that spec, so reusing a row's `cmsNodeId` across states is fine), then **vertically
+   composite** the per-state overlays into one PNG (pad to max width, dark `#1e1e1e` gutter) and set that as
+   the mapping's `overlay`  -  `build-artifact` embeds a single overlay, so the composite is how all states
+   reach the doc. Keep the standalone per-state PNGs beside it.
+
+   **Isolate one component variant when you want a clean render of it:** exported **library** node-ids go
+   **stale** once the Figma file re-versions (`/components` may return 0, `/images` returns `null`). Don't
+   chase them  -  the current screen **frame** node still renders, so walk its live node tree
+   (`GET /files/<key>/nodes?ids=<frame>&depth=6`) for the `INSTANCE` whose `name` is the component, render
+   **that** instance id, and take per-label boxes from its own text nodes' `absoluteBoundingBox` (× the render
+   `scale`). No live token / render fails → just **crop the variant out of a state screenshot**; a crop of the
+   real card is an equally valid variant image.
+
+   **Interactive  -  guide the developer here:** if no annotations were found, say so and tell them you'll map
+   keys to UI by reading the screen; confirm the **screen state** (which mock/screenshot) and that the
+   anchored element list looks right before rendering.
+9. **Render the per-key screenpieces (keyshots)** (script): `python3 scripts/render-key-shots.py --mapping
+   <map>.json --out <dir> [--slug <slug>]` → `keyshots/keyshot__<NN>__<key>.png` (one red-box crop per
+   matched row; **NN = the table row number**, same numbering as the overlay cards) +
+   `<slug>.keyshots.manifest.json`. Reuses the overlay's geometry inputs verbatim: REST (visible text nodes
+   only  -  ancestor-visibility + opacity filtered) or the same `--spec` file(s) you built for step 8
+   (repeatable  -  one per screen state; `image` may be a file path, e.g. the committed `screenshot.png`).
+   Set the mapping's top-level `keyshots` to the manifest filename; rows the geometry can't match land in
+   the manifest's `missing` and their table cells render "  -  ". Detail in
+   [reference/format-and-output.md](reference/format-and-output.md).
+10. **Build the artifacts** (script): `python3 scripts/build-artifact.py <mapping>.json --out <dir>` →
+    `<slug>.md` + `<slug>.confluence.xml` + `<slug>.preview.html` (CMS columns + the overlay key-map section
+    + the per-key "Screenshot" table cells when `keyshots` is set).
+    Add `--docx` / `--pdf` (or `--all`) for the content team  -  `.docx` is pure-stdlib/offline; `.pdf` uses an
+    installed renderer (LibreOffice → Chrome → wkhtmltopdf), skipped with a note if none is present.
+11. **Build the CMS import spreadsheet** (script): `python3 scripts/build-spreadsheet.py <mapping>.json --out
+    <dir>` → `<slug>.localization.xlsx`  -  a **real Excel file** (an OOXML zip written with the Python **stdlib
+    only**, no pip / no network, the same trick `build-artifact.py` uses for `.docx`; add `--csv` for a CSV
+    alongside, `--csv-only` when Excel isn't wanted). One row per key in the content team's CMS-import columns:
+    **Channel** · **Property Group** / **Property Module** (deduced from the key namespace  -  bucket names come
+    from `--taxonomy`; a row overrides with `propertyGroup` / `propertyModule`) · **Key** (our `newKey`,
+    component tag stripped) · **EN / TR / AR Value** (our authored `new` values) · **Anotation EN / TR** (the
+    content team's CMS Figma annotations  -  `cms.en` / `cms.tr`). This file is attached to the Confluence page
+    at publish (step 13). Format detail in [reference/format-and-output.md](reference/format-and-output.md).
+12. **Fidelity check  -  GATE before publish** (script): `python3 scripts/verify-map.py --mapping <map>.json
+    --screen-path <dir> [--resources-root <res>]`. Reconciles the map against the **real screen code**:
+    **UNVERIFIED** keys (a `newKey` not wired anywhere) → fix or drop; **wired-but-unmapped** keys (a
+    localization-key reference in code with no row) → add rows, it's a coverage gap; **value gaps** /
+    **untranslated** (tr==en) → resolve or note. Exit code 2 = hard issues  -  don't publish until clean (or a
+    waiver is conscious). This is what catches a stale/typo'd key or a missed downstream state before it ships.
+13. **Publish** ([reference/publish-and-snapshot.md](reference/publish-and-snapshot.md))  -  ask the user which
+    target(s): **(A) Confluence, live & idempotent**  -  `python3 scripts/publish-confluence.py --xml
+    <slug>.confluence.xml --screen "<name>" --screenshot screenshot.png --overlay <slug>.overlay.png
+    --keyshots <slug>.keyshots.manifest.json --attach <slug>.localization.xlsx` (Server/DC Bearer from the
+    keychain; base URL / space / parent from flags or `CONFLUENCE_*` env; updates the screen's page **in
+    place** on re-run). The `--attach` file rides along as a page attachment and, being a spreadsheet, also
+    gets a `view-file` macro so it **renders inline**. **(B) specs-repo PR**  -  copy the canonical set (incl.
+    `<slug>.localization.xlsx`, the manifest and `keyshots/`) into `localizations/<slug>/` and open an
+    additive PR.
+
+*(Pipeline  -  runs **after** the screen spec: dev generates spec → generates this map → publishes. Resources
+are read from the in-repo snapshot when present; refresh it with `scripts/snapshot-resources.sh`.)*
+
+## Verification
+- **Run `verify-map.py` (the fidelity gate)**  -  it reconciles the map against the real screen code and is
+  the scripted form of "counts must reconcile": every `newKey` is wired (or component/dynamic-exempt), no
+  localization-key reference in code is left unmapped, no fabricated/empty values. Fix what it flags before
+  publishing. `scan-screen-keys.py` error/dynamic hits must be accounted for as rows.
+- Every row has a `verdict`; no Old **or CMS** value is fabricated (blank or sourced only).
+- `build-artifact.py` runs clean; the `.md` carries the header + legend + totals + the fixed column order
+  including the CMS columns.
+- The overlay PNG was produced (or a `.html` fallback noted) and is referenced by the mapping's `overlay`.
+- **The keyshots were rendered**  -  `render-key-shots.py` wrote one PNG per matched row, the mapping's
+  `keyshots` names the manifest, every non-"  -  " Screenshot cell resolves to a file that exists, and nothing in
+  `keyshots/` is orphaned. Renaming a key or reordering rows renumbers `NN`: **re-render, never hand-rename.**
+- **The CMS spreadsheet was built**  -  `build-spreadsheet.py` wrote `<slug>.localization.xlsx` with one row per
+  key (row count = `mapping.rows`), the fixed 9 columns, and it is `--attach`ed at publish. Values come from
+  `new`, annotations from `cms`  -  never fabricated (blank where unsourced, same rule as the doc).
+- Publishing is **idempotent**: a second `publish-confluence.py` run on the same screen reports `updated`
+  (version-bump) of the **same** page id  -  never a duplicate.
+
+## Pitfalls
+- A large specs repo's recursive Git tree truncates (~43k paths)  -  use `gh search code`, not the tree API.
+- New key namespace ≠ legacy flat key (`SignUpAccountDetails.ContinueButton` vs `Continue`)  -  "reuse" means
+  reuse the *value* (or alias the legacy key), not that the strings match.
+- Form-field labels often live in shared input-cell models, not the screen file  -  the Android layout is the
+  reliable place to read them.
+- Legacy values are backend-served  -  blank Old columns are an expected state, not an error. **Likewise blank
+  CMS columns**  -  not every node is annotated yet.
+- Error/validation/alert + dynamic keys are invisible to the static cross-reference  -  run
+  `scan-screen-keys.py`, or they silently vanish from the map.
+- **A rendered frame PNG is not guaranteed to share the frame's `absoluteBoundingBox` origin.**
+  Building a `--spec` from REST geometry by subtracting the frame's absolute x/y from each text
+  node's absolute x/y drifted every box by tens of pixels against the image the `/images`
+  endpoint returned  -  boxes landed a row below their target, which looks plausible enough to
+  ship and is wrong. Verify one crop by eye before trusting a batch, and prefer boxes read off
+  the actual screenshot (the `--spec` path the skill documents) over coordinates derived from
+  two different sources.
+- **A key missing from the Suggested snapshot is not an unauthored key.** The snapshot is a
+  generated mirror; upstream additions land in the shipped catalog first. Concluding "needs
+  authoring" from the snapshot alone produced a batch of authoring requests for keys that were
+  already live in all eight languages  -  the values were recoverable from the catalog the whole
+  time. Pass `--catalog`, and when it answers, refresh the snapshot rather than filing anything.
+- **Never anchor a keyshot by value across a whole file.** A row whose label isn't drawn on
+  its own frames is tempting to recover by searching every frame for that text  -  but short
+  labels ("Türkiye", "Cancel", "Continue") recur on unrelated screens, and the crop then
+  boxes the wrong element with full confidence. That is strictly worse than "  -  ", because the
+  content team believes it. Recover only via the row's own `cmsNodeId` (the node the content
+  team annotated), and when you hand nodes to `render-key-shots --spec`, **omit
+  `characters`**  -  with text present the renderer falls back to value matching and an
+  unrelated row can bind to your node. "Text exists somewhere in the file" is not evidence
+  that it is the same element.
+- Confluence **Server/DC → Bearer PAT** (keychain `CONFLUENCE_API_TOKEN`) is not Cloud `user:token`; page
+  lookup uses the DB-backed `content?title=` query, not CQL (CQL's index lags a fresh page → duplicate).
+- Never commit a label-service token, Confluence PAT or Figma token into a mapping, a taxonomy file or these
+  docs  -  keychain items and `--headers-file` exist for that.

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

@@ -0,0 +1,144 @@
+{
+  "screen": "Sign Up  -  Account Details",
+  "platforms": [
+    "ios",
+    "android",
+    "web"
+  ],
+  "figmaFileKey": "9XbExampleFigmaKey00",
+  "figmaNodes": [
+    "1024:4096",
+    "1024:4112"
+  ],
+  "screenshot": "screenshot.png",
+  "overlay": "sign-up-account-details.overlay.png",
+  "keyshots": "sign-up-account-details.keyshots.manifest.json",
+  "legacyKeyPrefix": "",
+  "rows": [
+    {
+      "element": "Screen title (top bar)",
+      "newKey": "SignUpAccountDetails.ScreenTitle",
+      "new": {
+        "en": "Create your account",
+        "tr": "Hesabını oluştur",
+        "ar": "أنشئ حسابك",
+        "de": "Konto erstellen",
+        "es": "Crea tu cuenta",
+        "fr": "Créez votre compte",
+        "it": "Crea il tuo account",
+        "ru": "Создайте аккаунт"
+      },
+      "legacyKeyIOS": "(nav title)",
+      "legacyKeyAndroid": "SignUp",
+      "legacy": {
+        "en": "Sign up",
+        "tr": "Kayıt ol"
+      },
+      "verdict": "review",
+      "note": "Legacy said 'Sign up', the redesign says 'Create your account'. iOS set the title in code, so there is no legacy key to trace.",
+      "cms": {
+        "en": "Create your account",
+        "tr": "Hesabını oluştur"
+      },
+      "cmsNodeId": "1024:4130",
+      "cmsSource": "figma-rest"
+    },
+    {
+      "element": "Email field label",
+      "newKey": "SignUpAccountDetails.EmailLabel",
+      "new": {
+        "en": "Email address",
+        "tr": "E-posta adresi"
+      },
+      "legacyKeyIOS": "EmailAddress",
+      "legacyKeyAndroid": "EmailAddress",
+      "legacyKeyWeb": "EmailAddress",
+      "legacy": {
+        "en": "Email address",
+        "tr": "E-posta adresi"
+      },
+      "verdict": "reuse",
+      "note": "One shared legacy key on all three platforms, identical value  -  adopt it.",
+      "cms": {
+        "en": "Email address",
+        "tr": "E-posta adresi"
+      },
+      "cmsNodeId": "1024:4134",
+      "cmsSource": "figma-rest"
+    },
+    {
+      "element": "Email field placeholder",
+      "newKey": "SignUpAccountDetails.EmailPlaceholder",
+      "new": {
+        "en": "name@example.com",
+        "tr": "ad@ornek.com"
+      },
+      "legacyKeyIOS": "",
+      "legacyKeyAndroid": "",
+      "legacy": {},
+      "verdict": "new",
+      "note": "The legacy form had no placeholder."
+    },
+    {
+      "element": "Password strength hint (owned by PasswordField)",
+      "newKey": "PasswordField.StrengthHint",
+      "new": {
+        "en": "Use at least 8 characters",
+        "tr": "En az 8 karakter kullan"
+      },
+      "legacyKeyIOS": "PasswordRule",
+      "legacyKeyAndroid": "PasswordMinLength",
+      "legacy": {
+        "en": "Password must be at least 8 characters.",
+        "tr": "Şifre en az 8 karakter olmalıdır."
+      },
+      "verdict": "review",
+      "note": "(owned by PasswordField)  -  mapped here because this is where the component is used. Legacy keys drift across platforms and the wording was shortened.",
+      "cms": {
+        "en": "Use 8 characters or more",
+        "tr": "8 karakter veya daha fazla kullan"
+      },
+      "cmsNodeId": "1024:4142",
+      "cmsSource": "figma-rest"
+    },
+    {
+      "element": "Duplicate-email error",
+      "newKey": "SignUpAccountDetails.ErrorEmailTaken",
+      "new": {
+        "en": "This email is already registered",
+        "tr": "Bu e-posta zaten kayıtlı"
+      },
+      "legacyKeyIOS": "EmailAlreadyExists",
+      "legacyKeyAndroid": "EmailAlreadyExsists",
+      "legacy": {
+        "en": "An account with this email already exists.",
+        "tr": "Bu e-posta ile bir hesap zaten var."
+      },
+      "verdict": "review",
+      "note": "Cross-platform key drift (the Android key carries a typo); wording changed. Found by scan-screen-keys.py, not by the static cross-reference."
+    },
+    {
+      "element": "Primary CTA",
+      "newKey": "SignUpAccountDetails.ContinueButton",
+      "new": {
+        "en": "Continue",
+        "tr": "Devam et"
+      },
+      "legacyKeyIOS": "Continue",
+      "legacyKeyAndroid": "Continue",
+      "legacyKeyWeb": "signup.continue_button",
+      "legacy": {
+        "en": "Continue",
+        "tr": "Devam"
+      },
+      "verdict": "review",
+      "note": "Shared value; tr wording differs slightly ('Devam' vs 'Devam et'), and the web key is namespaced (t('continue_button') inside useTranslation('signup')) while iOS/Android share a flat 'Continue'  -  cross-platform key drift, not a value problem.",
+      "cms": {
+        "en": "Continue",
+        "tr": "Devam et"
+      },
+      "cmsNodeId": "1024:4150",
+      "cmsSource": "figma-rest"
+    }
+  ]
+}

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

@@ -0,0 +1,156 @@
+# Verdict taxonomy, mapping schema & output
+
+> Bundled detail for [../SKILL.md](../SKILL.md). How to classify each row, the JSON the build script
+> consumes, and the artifacts it produces. Input shape: [../example-mapping.json](../example-mapping.json).
+
+## Verdict taxonomy (recommendation; content team confirms)
+
+| Verdict | When | What it tells the content team |
+|---|---|---|
+| ✅ **reuse** | Same function **and** same/equivalent value (or a clean shared key on both legacy platforms) | Adopt the legacy value/key  -  translators don't re-translate |
+| 🔶 **review** | Same function but value drift, wording change, cross-platform key drift, or thin legacy language coverage | Same element exists  -  you decide whether to reuse the value or take the new copy |
+| 🆕 **new** | No legacy counterpart (new functionality / new business rule) | Mint a new key + value |
+
+Edge calls to catch in the note: a `tr` value equal to `en` (untranslated); legacy present in only some
+languages (e.g. en/tr only); a key owned by a reusable component (flag, don't double-map); a legacy key on
+only one platform; **a CMS (content-team) value that differs from the new design value** (the renderer marks
+it ⚠  -  call it out so the content team knows their final copy diverged from the mock).
+
+## Mapping JSON schema (input to `scripts/build-artifact.py`)
+
+```jsonc
+{
+  "screen": "Sign Up  -  Account Details",                     // required
+  "platforms": ["ios", "android", "web"],
+  "figmaNodes": ["1024:4096", "1024:4112"],
+  "figmaFileKey": "AbCdEf123",                               // optional; enables live annotation fetch / overlay
+  "screenshot": "screenshot.png",                            // optional; rendered in section Screen
+  "overlay": "<slug>.overlay.png",                           // optional; key↔UI image (render-overlay.py) → section key map
+  "keyshots": "<slug>.keyshots.manifest.json",               // optional; per-key screenpiece manifest (render-key-shots.py)
+                                                             //   → fills the Summary "Screenshot" cells
+  "rows": [                                                  // required
+    {
+      "element": "Continue button",                         // the UI element label
+      "newKey": "SignUpAccountDetails.ContinueButton",       // "(owned by ...)" if not screen-owned
+      "new":    {"en":"Continue","tr":"Devam Et","ar":"...","de":"...","es":"...","fr":"...","it":"...","ru":"..."},
+      "legacyKeyIOS": "Continue",                            // "" → renders "  -  "
+      "legacyKeyAndroid": "Continue",
+      "legacyKeyWeb": "Continue",                            // "" or omitted → renders "  -  "; only when the legacy app has a web frontend
+      "legacy": {"en":"Continue","tr":"Devam","ar":"...", ...},   // 8 langs; "" where service-only
+      "cms":    {"tr":"Devam Et","en":"Continue"},           // optional; content team's ACTUAL copy (Figma annotation)
+      "cmsNodeId": "1024:4150",                              // optional; the Figma node the annotation sits on
+      "cmsSource": "figma-rest",                             // optional; figma-rest | figma-mcp | local | none
+      "verdict": "review",                                   // reuse | review | new
+      "note": "Legacy tr 'Devam' vs new 'Devam Et'."
+    }
+  ]
+}
+```
+Fill `new` with `resolve-new-values.py --langs all`, `legacy` with `resolve-legacy-values.py --langs all`,
+and `cms` from `fetch-annotations.py` (the content team's Final UX Writing TR/EN; see
+[sources-and-recipes.md](sources-and-recipes.md)). The renderer shows **en/tr** old/new **+ CMS tr/en** in the
+summary, and **all 8** old/new **plus every CMS language present** in the details  -  so keep the `new`/`legacy`
+maps fully 8-keyed; `cms` is whatever the content team annotated (usually tr+en).
+
+**CMS columns + drift.** `cms` is the content team's *actual* final copy and is shown additively  -  it does
+**not** overwrite `new`. When a `cms` value differs from the `new` (design/resources) value for the same
+language, the renderer marks the cell **⚠** and counts it as a CMS difference in the header.
+Blank `cms` is expected (no annotation yet)  -  never invent one.
+
+**Author `element` and `note` in the content team's own language**  -  pick it once (`--ui-lang` sets the
+template chrome to match) and stay consistent. These two author-written fields are the only free text in the
+doc, so a mixed-language run reads as half-translated. `newKey` / legacy keys and the translation values stay
+verbatim.
+
+## Output  -  artifacts (one mapping)
+
+`build-artifact.py <mapping>.json --out <dir>` always writes these three:
+- **`<slug>.md`**  -  Markdown mirror (PR / quick read).
+- **`<slug>.confluence.xml`**  -  Confluence **storage format**: section Screen (`<ac:image>`), section key map (the overlay
+  `<ac:image>` when `overlay` is set), section Summary (Old en/tr · New en/tr · **CMS tr/en** + verdict, `status`
+  macros, `info`-macro legend + counts + drift note, and  -  when `keyshots` is set  -  a per-row
+  **Screenshot** cell embedding that key's red-box screenpiece by attachment filename), section Details
+  (per-element tables: all 8 langs Old/New + CMS). This is exactly the REST API's `body.storage.value`.
+- **`<slug>.preview.html`**  -  standalone browser preview (open locally before upload).
+
+Two more are **opt-in**, for handing the map to the content team as a file (not a Confluence page):
+- **`<slug>.docx`** (`--docx`)  -  a Word document with the same section Screen / section Summary / section Details layout
+  (landscape, verdict-shaded cells, embedded screenshot, RTL on the Arabic rows). Generated with the
+  **Python stdlib only**  -  a `.docx` is a ZIP of OOXML, so there is no third-party dependency and no network.
+- **`<slug>.pdf`** (`--pdf`)  -  a read-only share copy. Multilingual (Arabic + Cyrillic + Latin) PDF needs real
+  font shaping, so it is **not** hand-rolled: the script drives whatever renderer the machine has, in order
+  of table fidelity  -  LibreOffice `soffice` (docx→pdf) → Chrome/Chromium headless (html→pdf) → `wkhtmltopdf`.
+  If none is installed the PDF is **skipped** with a note pointing at the `.docx` / `.html` (still no pip, no
+  network). `--all` writes every format.
+
+Layout = **summary (en/tr at a glance) + details (all 8)**  -  the "best of both worlds": devs scan the
+summary, the content team works the per-element language tables. The `.docx`/`.pdf` mirror the same two levels.
+
+## Per-key screenpieces (keyshots)  -  the "Screenshot" column
+
+`scripts/render-key-shots.py --mapping <map>.json --out <dir>` renders, for **every matched row**, a cropped
+band of the screen with a **red box around exactly that element** (ported from the web skill's
+`render-key-shots.mjs`)  -  so the table shows the content team *where each key lives on screen* without
+hunting through the full overlay. Files land in `<out>/keyshots/keyshot__<NN>__<key>.png`, where **NN is
+the row's 1-based position in `mapping.rows`**  -  the same number the Summary table and the overlay cards
+use, so shot ↔ card ↔ row always agree. A manifest (`<slug>.keyshots.manifest.json`) lists
+`shots` (row → file) and `missing` (rows with no visible matched node  -  their cells render "  -  ", never a
+guessed crop).
+
+Geometry comes from the same two modes as the overlay: **REST** (walks the frame's node tree with
+**ancestor-visibility + cumulative-opacity** filtering, so a hidden variant's stale bbox never lands the
+red box on the wrong content) or **`--spec`** (repeatable  -  one per screen state; the overlay-compatible
+spec shape, whose `image` may be a **data URL or a file path** relative to the spec file). Rows are matched
+to nodes with the overlay's matcher (`cmsNodeId` first, else normalized value), so the three renderers can
+never disagree about which node a key is. Set the mapping's top-level `"keyshots"` to the manifest filename
+and `build-artifact.py` fills the **Screenshot** column in all four formats (Confluence XML by
+attachment filename, `.md`/`.preview.html` by relative path, `.docx` embedded). No headless Chrome →
+per-shot `.html` fallbacks (marked in the manifest; not embeddable).
+
+## CMS import spreadsheet (Excel attachment)
+
+`scripts/build-spreadsheet.py <mapping>.json --out <dir>` writes **`<slug>.localization.xlsx`**  -  the flat
+sheet the content team imports into the CMS, attached to the Confluence page (and, being a spreadsheet, also
+rendered inline via a `view-file` macro). It is a **real `.xlsx`**: an OOXML zip assembled with the Python
+**stdlib only** (`zipfile` + inline-string XML)  -  no pip, no LibreOffice, no network, exactly like the
+`.docx` path. `--csv` writes a UTF-8 (BOM) CSV alongside; `--csv-only` skips the xlsx when a CSV is all that's
+wanted.
+
+**One row per mapping row**, in this fixed column order (matches the content team's sheet):
+
+| Column | Source | Notes |
+|---|---|---|
+| **Channel** | constant `Mobile` | the delivery channel these strings belong to; override with `--channel` |
+| **Property Group** | deduced from the key namespace | default buckets `Core` / `Domains` / `Errors` / `Lookups`; rename them with `--taxonomy`, or override per row with `propertyGroup` |
+| **Property Module** | deduced from the key namespace | `Fields` / `Validation` / `Common` / `<domain>`; row override `propertyModule` |
+| **Key** | `row.newKey` | our new key, verbatim; a trailing `(owned by ...)` component tag is stripped |
+| **EN / TR / AR Value** | `row.new.en` / `.tr` / `.ar` | our **Suggested** values (resolve-new-values.py) |
+| **Anotation EN / TR** | `row.cms.en` / `.tr` | the content team's **CMS Figma annotations** (fetch-annotations.py); blank when unannotated |
+
+**Group/Module deduction** is a best-effort heuristic on the key: `error*`→`Errors`, `lookup`→`Lookups`,
+`validation`→`Core/Validation`, `field|placeholder|hint|label`→`Core/Fields`, a recognized feature word
+(auth/login, account/profile, checkout/payment, search...)→`Domains/<domain>`, else `Core/Common`. Every bucket
+name and every domain word list comes from `--taxonomy <file>` (merged over those defaults), because no two
+CMS instances name their buckets alike. When the agent knows better still, set
+`propertyGroup`/`propertyModule` on the row and the script uses those verbatim. **Values/annotations are never fabricated**  -  blank cells mean unsourced, same rule as
+the doc (`new` for values, `cms` for annotations).
+
+## Publishing  -  live, idempotent
+
+Automated by **`scripts/publish-confluence.py`** (full recipe in
+[publish-and-snapshot.md](publish-and-snapshot.md)). It uploads the `<slug>.confluence.xml` body to a
+Confluence **Server/DC** instance with a **Bearer PAT** (keychain `CONFLUENCE_API_TOKEN`), and is **idempotent
+by title**  -  re-running on a screen **updates the same page in place** (version-bump), never duplicating it.
+It attaches `screenshot.png` + the overlay PNG + (via `--keyshots`) every per-key screenpiece PNG (the
+storage `<ac:image>` tags reference them by filename).
+The target base URL / space / parent come from `--base-url` / `--space` / `--parent` or the matching
+`CONFLUENCE_*` environment variables, and are **asked from the user** when neither is set.
+
+```bash
+python3 publish-confluence.py --xml <slug>.confluence.xml --screen "<name>" \
+    --screenshot screenshot.png --overlay <slug>.overlay.png \
+    --keyshots <slug>.keyshots.manifest.json                      # [--space <SPACE> --parent <id>] [--title ...]
+```
+`build-artifact.py ... --print-upload` prints this exact command (plus the equivalent raw Bearer `curl`).
+Manual fallback: paste `<slug>.confluence.xml` into the page's storage editor and attach the two images by
+filename.