@mmerterden/multi-agent-pipeline 20.6.0 → 20.7.0

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

@@ -1,156 +1,124 @@
-# Verdict taxonomy, mapping schema & output
+# Mapping format and outputs
 
-> 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).
+The mapping JSON is the single source every renderer reads. The scripts add nothing of their own: what is not in the mapping does not appear in the table, the spreadsheet or the page.
 
-## Verdict taxonomy (recommendation; content team confirms)
+## Mapping schema
 
-| Verdict | When | What it tells the content team |
+Top level:
+
+| Key | Required | Meaning |
 |---|---|---|
-| ✅ **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 |
+| `screen` | yes | Screen name; the file slug is derived from it |
+| `platforms` | no | e.g. `["ios", "android", "web"]` |
+| `figmaNodes` | no | Array of frame node-ids |
+| `figmaFileKey` | no | Enables the live annotation fetch and the REST overlay |
+| `screenshot` | no | Screen image, relative to the mapping |
+| `overlay` | no | Overlay PNG name |
+| `keyshots` | no | Keyshots manifest name |
+| `legacyKeyPrefix` | no | Prepended to legacy keys for display only |
+| `rows` | yes | One object per UI element |
+
+Row:
+
+| Key | Meaning |
+|---|---|
+| `element` | Human label for the UI element, in the `--ui-lang` language |
+| `newKey` | Redesign key; may carry `(owned by <Component>)` |
+| `new` | Eight-language map: `en`, `tr`, `ar`, `de`, `es`, `fr`, `it`, `ru` |
+| `legacyKeyIOS`, `legacyKeyAndroid`, `legacyKeyWeb` | Legacy key per platform. Empty or omitted renders a dash. Web only when the legacy app has a web frontend. A value in parentheses such as `(nav title)` is a marker and is shown as is |
+| `legacy` | Eight-language map; `""` where the value is only served by the backend and was not fetched |
+| `cms` | Optional; usually `tr` and `en` from the Figma annotation |
+| `cmsNodeId` | Optional; the annotated (or synthetic spec) node-id |
+| `cmsSource` | Optional: `figma-rest`, `figma-mcp`, `local` or `none` |
+| `verdict` | `reuse`, `review` or `new` |
+| `note` | Reasoning, edge-case flags, `(owned by ...)`, "dynamic - enumerate at runtime" |
+| `propertyGroup`, `propertyModule` | Optional spreadsheet-only overrides |
+
+Keep `new` and `legacy` fully eight-keyed. The summary table shows old and new `en`/`tr` plus CMS `tr`/`en`; the details section shows all eight languages plus every CMS language present.
+
+### The example
+
+[`../example-mapping.json`](../example-mapping.json) maps a neutral "Sign Up - Account Details" screen in nine rows, with `legacyKeyPrefix: "Mobile-"`:
+
+| # | Case | Verdict |
 |---|---|---|
-| **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.
+| 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 |
+| 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 |
+| 8 | CMS-only `tr` that differs from `new` | new |
+| 9 | Dynamic `Error.<field>Required` | review, "enumerate at runtime" |
+
+## Rendered artifacts
+
+`build-artifact.py <map>.json --out <dir>` always writes three files, and more on request:
+
+| File | Contents |
+|---|---|
+| `<slug>.md` | Title, intro, platforms and Figma nodes, screenshot, optional key-map image, summary with counts, drift note, pipe table (pipes escaped, newlines flattened, keyshot as a relative image), per-row detail tables |
+| `<slug>.confluence.xml` | Storage format, the value of `body.storage.value`: header paragraph, an `info` macro with the legend (status macros), counts, CMS line and drift note; a Screen section (`<ac:image ac:height="500">`); a key-map section (`<ac:image ac:width="900">`); the summary table with keyshots (`<ac:image ac:width="240">`) referenced by attachment name, keys in `<code>`, status macros; per-row details with an eight-language Old / New / CMS table |
+| `<slug>.preview.html` | Standalone page with sections 1 Screen, 2 Summary, 3 Details and coloured verdict badges. Absolute image paths become `file://` URLs; bare names stay relative |
+| `<slug>.docx` (`--docx`) | Word document built with the standard library: landscape A4, screenshot, overlay and keyshot thumbnails, verdict-shaded cells, a pink cell for drifting CMS TR, right-to-left Arabic rows |
+| `<slug>.pdf` (`--pdf`) | LibreOffice from the docx, then headless Chrome from the preview, then `wkhtmltopdf`. With none of them installed the PDF is skipped with a note naming the file to share instead |
+
+`--all` means `--docx --pdf`. Summary columns in order: `#`, UI element, Screenshot, New key, Legacy iOS, Legacy Android, Legacy Web, Old en, Old tr, New en, New tr, CMS TR, CMS EN, Verdict, Note. Detail columns: Lang, Old (legacy), New (redesign), CMS. Verdict colours on Confluence: reuse Green, review Yellow, new Blue, anything else Grey.
+
+A CMS value counts as drifting when both it and `new` are non-empty and they still differ after Unicode NFC normalisation, whitespace collapsing, stripping a trailing `.`, `:` or ellipsis, and lowercasing. Drifting cells carry a warning sign.
+
+The `--ui-lang` switch (`en` default, `tr`) changes headings, legend, labels and column names; keys and values are never translated.
+
+## 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-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
+
+`build-spreadsheet.py <map>.json --out <dir>` writes `<slug>.localization.xlsx`, a real Excel workbook built with the standard library (sheet `Localization`, styled and frozen header row, autofilter). `--csv` adds a UTF-8 CSV with BOM; `--csv-only` skips the xlsx. One row per key, attached to the Confluence page at publish time.
+
+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.
+- 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.
+
+## Fidelity gate
+
+`verify-map.py --mapping <map>.json --screen-path <dir> [--resources-root <res>] [--out report.json]` is count reconciliation as a script.
+
+| 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 |
+| 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 |
+| `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.
+
+## Script reference
+
+| Script | Key flags |
+|---|---|
+| `scan-screen-keys.py` | `--screen-path` (required), `--out`, `--category all/error/dynamic/static` |
+| `resolve-new-values.py` | `--keys`, `--keys-file` (`-` for stdin), `--resources-root` or `--suggested-dir`, `--domain localization/accessibility`, `--catalog`, `--report-source`, `--langs` (default `en,tr`, or `all`) |
+| `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-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` |
+| `verify-map.py` | `--mapping`, `--screen-path` (both required), `--resources-root`, `--out` |
+| `publish-confluence.py` | see [publish-and-snapshot](publish-and-snapshot.md) |
+| `snapshot-resources.sh` | `<resources-root> <specs-root>` |
+
+`all` languages means `en, tr, ar, de, es, fr, it, ru` in every script. Every script derives the same slug from `screen`: lowercase, each run of non-letter, non-digit characters becomes one `-`, leading and trailing dashes trimmed, `screen` when nothing is left. `--slug` overrides it on any script. Figma tokens resolve from `--token`, then `FIGMA_ACCESS_TOKEN`, then `FIGMA_TOKEN`, then the macOS keychain item `FIGMA_ACCESS_TOKEN`; prefer the environment or keychain, since argv is visible to other processes.

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

@@ -1,108 +1,78 @@
-# Publish to <specs-repo> & the in-repo resource snapshot
+# Publishing and the resources snapshot
 
-> Bundled detail for [../SKILL.md](../SKILL.md). How the generated artifact lands in `<specs-repo>`, and
-> how the redesign resources get snapshotted there so the whole flow is **single-repo** (like `design-export`).
+## One repo to read from
 
-## Single-repo model  -  why snapshot into <specs-repo>
+The component registry and the Suggested translations are kept in their own resources repo. So that every lookup happens in a single place, a snapshot of both is copied into the specs repo under `resources/`, beside the design export:
 
-The skill reads four sources. Three already live in `<specs-repo>` (`design-export/`, legacy iOS/Android,
-the live label service over the network). The fourth  -  the redesign **component registry** and **Suggested
-translations**  -  lives in `<resources-repo>`. Snapshotting those two into `<specs-repo>`
-(exactly as `design-export/` is a manual/CI snapshot of Figma) removes the cross-repo round-trip: every
-read is one repo.
-
-**Layout** (top-level, mirroring `design-export`'s convention):
 ```
 <specs-repo>/
-├── design-export/                      # existing (Figma snapshot)
-├── resources/                         # NEW snapshot  -  all data the mapper needs, in-repo
-│   ├── Figma/Components/<node>.json   # component registry (localizationKeys, componentName)
-│   ├── Localization/Suggested/<Key>.json   # NEW translation values (8 langs)
-│   └── Localization/Legacy/<lang>.json     # LEGACY values  -  label snapshot (flat key→value, one file per language)
-└── localizations/                     # NEW  -  the maps this skill publishes
-    └── <screen-slug>/
-        ├── <screen-slug>.md           # the reuse map
-        ├── <screen-slug>.confluence.xml
-        ├── <screen-slug>.overlay.png  # key↔UI overlay (when produced)
-        ├── <screen-slug>.keyshots.manifest.json  # per-key screenpiece index (when produced)
-        ├── keyshots/                  # per-key red-box screenpieces (render-key-shots.py)
-        │   └── keyshot__<NN>__<key>.png
-        └── screenshot.png
+  resources/
+    Figma/Components/<node>.json
+    Localization/Suggested/<Key>.json
+    Localization/Legacy/<lang>.json
+  localizations/<screen-slug>/
+    <slug>.md
+    <slug>.confluence.xml
+    <slug>.overlay.png
+    <slug>.keyshots.manifest.json
+    <slug>.localization.xlsx
+    screenshot.png
+    keyshots/   (one keyshot__<NN>__<key>.png per row)
 ```
 
-**Refresh**  -  two steps, both "like a `design-export` update" (run by CI or manually):
+### Refreshing it
+
+The refresh has two parts. The first runs locally, the second needs the network:
+
 ```bash
-# 1. registry + new (Suggested) values  -  local copy from <resources-repo> (no network)
 scripts/snapshot-resources.sh <resources-repo-root> <specs-repo-root>
-# 2. legacy values  -  the ONLY network step: fetch the legacy labels for all 8 languages
-scripts/fetch-legacy-labels.py --out <specs-repo>/resources/Localization/Legacy --langs all
+python3 scripts/fetch-legacy-labels.py --langs all \
+  --out <specs-repo-root>/resources/Localization/Legacy \
+  --endpoint '<label-url-with-{lang}>' --headers-file <headers.json>
 ```
-With the snapshot in place every read is in-repo  -  **no live label round-trip per run**:
-- new values: `resolve-new-values.py --resources-root <specs-repo>/resources` (Suggested lives there)
-- legacy values: `resolve-legacy-values.py --snapshot-root <specs-repo>/resources/Localization/Legacy`
-  (offline; `--live` only to verify/refresh, `--plist-root` as last resort).
 
-## Publishing a screen's map (the skill's last step)
+`snapshot-resources.sh` copies `Resources/Figma/Components` and `Resources/Localization/LocalizationStrings/Sources/Suggested` with `rsync -a --delete`; a key or component deleted upstream therefore drops out of the snapshot as well. If either source folder is missing, the script stops with `missing source dir: <dir>`. `fetch-legacy-labels.py` saves a flat `<lang>.json` for every language, sorted by key, and leaves each key exactly as the service stores it, prefix and all. Credential headers belong in `--headers-file` and must not appear on the command line. The refreshed snapshot is committed like any design-export refresh.
 
-Two destinations; **ask the user which** (and the target space/parent/formats)  -  they are not mutually
-exclusive:
+### Guardrails
 
-### A) Confluence  -  live & idempotent (`scripts/publish-confluence.py`)
+- The skill only adds: its writes are limited to `localizations/` and `resources/`.
+- Legacy source, `design-export/` and `specs/` are never modified.
+- `resources/` is a generated copy. Refresh it with the scripts; do not edit it by hand.
+
+## Option A: Confluence (live page)
 
 ```bash
-python3 scripts/publish-confluence.py --xml "$OUT/$SLUG.confluence.xml" --screen "<name>" \
-    --screenshot "$OUT/screenshot.png" --overlay "$OUT/$SLUG.overlay.png" \
-    --keyshots "$OUT/$SLUG.keyshots.manifest.json" \
-    --attach "$OUT/$SLUG.localization.xlsx"
-#   defaults: --base $CONFLUENCE_BASE_URL  --space <SPACE>  --parent <PARENT-ID>  --title "<prefix>  -  <name>"
+python3 scripts/publish-confluence.py \
+  --xml <slug>.confluence.xml --screen "<Screen name>" \
+  --overlay <slug>.overlay.png --screenshot screenshot.png \
+  --keyshots <slug>.keyshots.manifest.json \
+  --attach <slug>.localization.xlsx
 ```
-- **Target configuration.** Nothing about your wiki is baked in: pass `--base-url` / `--space` / `--parent`,
-  or set `CONFLUENCE_BASE_URL` / `CONFLUENCE_SPACE` / `CONFLUENCE_PARENT` once in the environment. Without a
-  target the script refuses rather than guessing. `--title-prefix` (env `LOCALIZATION_PAGE_PREFIX`) sets the
-  wording of the default page title.
-- **Server/DC Bearer auth** (NOT Atlassian Cloud `user:token`): the PAT is read from the macOS keychain item
-  **`CONFLUENCE_API_TOKEN`** and passed to `curl` via a `chmod 600` `-K` config (never on the argv). HTTP goes
-  through `curl` so a corporate TLS proxy's trust store is honored (Python `urllib` fails cert verification
-  there).
-- **Idempotent by title.** It looks the page up via the DB-backed `GET /rest/api/content?spaceKey=...&title=...`
-  (NOT CQL `/content/search`, whose async index lags a fresh page and would create a duplicate). Found →
-  **PUT `version+1`, updating the same page in place**; absent → **POST create** under `--parent`. Re-running
-  the mapper on a screen refreshes its page; it never duplicates.
-- **Attachments.** `screenshot.png` + the overlay PNG are attached (create, or update-by-filename if present);
-  the storage `<ac:image><ri:attachment ri:filename="...">` tags resolve to them. Filenames must match what
-  `build-artifact.py` embedded (its basenames). **`--keyshots <manifest>`** attaches every per-key screenpiece
-  PNG listed in `$SLUG.keyshots.manifest.json` (render-key-shots.py)  -  without it the Summary table's
-  "Screenshot" cells reference attachments that don't exist and render as broken images.
-  **`--attach <file>` (repeatable)** attaches any extra document
-- pass `$SLUG.localization.xlsx` (the CMS import sheet, build-spreadsheet.py); office/spreadsheet files also
-  get a `view-file` macro appended to the body so they **render inline** under a "CMS transfer file" heading.
-- The skill asks the user for the space / parent / title when the environment doesn't already pin them.
-- `build-artifact.py ... --print-upload` prints the exact command (plus the raw Bearer `curl`) for copy-paste.
-
-### B) <specs-repo> PR (in-repo record  -  optional)
-
-Place the canonical set under `localizations/<slug>/` and open an additive PR:
+
+- **Target**: `--base` / `--base-url`, `--space` and `--parent`, or the variables `CONFLUENCE_BASE_URL`, `CONFLUENCE_SPACE` and `CONFLUENCE_PARENT`.
+- **Title**: `--title` when given; otherwise `<prefix> - <screen>`, with the prefix taken from `--title-prefix`, then `LOCALIZATION_PAGE_PREFIX`, then the default `Localization`.
+- **Token**: a Server / Data Center personal access token, sent as a Bearer header. The script tries `--token`, then `CONFLUENCE_API_TOKEN`, then the macOS keychain service given by `--keychain-name` (default `CONFLUENCE_API_TOKEN`). Use the keychain where possible, because other processes can read argv.
+- **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.
+- **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.
+
+## Option B: specs-repo pull request
+
+Place the canonical files in `<specs-repo>/localizations/<slug>/`: the Markdown `<slug>.md`, the storage body `<slug>.confluence.xml`, the overlay `<slug>.overlay.png`, `screenshot.png`, the manifest `<slug>.keyshots.manifest.json` with its `keyshots/` folder, and the sheet `<slug>.localization.xlsx`. Then:
+
 ```bash
-SLUG=sign-up-account-details
-DST="$SPECS/localizations/$SLUG"; mkdir -p "$DST"
-cp "$OUT/$SLUG".{md,confluence.xml} "$OUT/$SLUG.overlay.png" "$OUT/screenshot.png" \
-   "$OUT/$SLUG.keyshots.manifest.json" "$DST"/ 2>/dev/null
-[ -d "$OUT/keyshots" ] && cp -R "$OUT/keyshots" "$DST"/   # per-key screenpieces (md embeds them relatively)
-cd "$SPECS" && git switch -c "loc-map/$SLUG" \
-  && git add "localizations/$SLUG" \
-  && git commit -m "localizations: $SLUG reuse map" \
-  && git push -u origin "loc-map/$SLUG" \
-  && gh pr create --title "Localization reuse map  -  $SLUG" \
-       --body "Generated by the localization-reuse-map skill; screenshot + overlay included." --fill
+git checkout -b loc-map/<slug>
+git add localizations/<slug>
+git commit --message "localizations: <slug> reuse map"
+git push --set-upstream origin loc-map/<slug>
+gh pr create --body "<summary, counts, gate result>" --title "Localization reuse map - <slug>"
 ```
-- The `.md` is the human-readable map (images embedded by filename  -  keep the PNGs beside it so they render
-  on GitHub). The `.confluence.xml` is the storage-format payload Confluence consumes.
-- **Merge policy:** additive (new files under `localizations/`) → auto-/admin-merge cleanly.
-- Need a file for the content team? Re-run `build-artifact.py` with `--docx` / `--pdf` / `--all` (CMS columns
-  + overlay embedded). Keep these heavy binaries **out** of the PR  -  share them directly.
-
-## Guardrails
-- **Additive only.** This flow creates files under `localizations/` and `resources/`; it never edits
-  legacy source, `design-export/`, or `specs/`.
-- The `resources/` snapshot is **generated, not authored**  -  never hand-edit it; refresh it from
-  `<resources-repo>` (its source of truth), same as `design-export/` is refreshed from Figma.
+
+Because the PR adds files and touches nothing else, it merges without conflicts. Keep the large `.docx` and `.pdf` files out of it and send them to people directly.
+
+A screen may go through both options. Before publishing, ask which option or options to use, the Confluence space, and which formats are wanted.