@mmerterden/multi-agent-pipeline 20.5.0 → 20.7.0

package/pipeline/skills/shared/external/compose-navigation/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: compose-navigation
 description: "Implement type-safe navigation in Jetpack Compose using Navigation 2.8+ with @Serializable routes, NavHost, typed composable routes, nested navigation graphs, deep links, BackHandler, type-safe argument passing, and bottom navigation with NavigationBar integration. Use when building Compose navigation, adding new screens, handling deep links, or implementing bottom nav patterns."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Compose Navigation
@@ -487,7 +489,7 @@ fun EditScreen(
 
 ## Review Checklist
 
-- [ ] All routes are `@Serializable` data classes or objects
+- [ ] All routes are `@Serializable` data classes or objects, and the kotlinx-serialization plugin is applied in build.gradle.kts
 - [ ] `NavController` stays at NavHost level; screens receive navigation lambdas
 - [ ] Route arguments are primitives or enums only
 - [ ] Bottom navigation uses `saveState`/`restoreState`/`launchSingleTop`
@@ -496,4 +498,3 @@ fun EditScreen(
 - [ ] Predictive back is enabled in manifest for Android 14+
 - [ ] Nested graphs use `navigation<>()` with explicit start destination
 - [ ] No navigation calls inside composable body without guard
-- [ ] kotlinx-serialization plugin is applied in build.gradle.kts

package/pipeline/skills/shared/external/compose-testing/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: compose-testing
 description: "Test Jetpack Compose UI with createComposeRule, semantic matchers (onNodeWithText, onNodeWithTag, onNodeWithContentDescription), actions (performClick, performTextInput, performScrollTo), assertions (assertIsDisplayed, assertExists, assertTextEquals), screenshot testing with Roborazzi or Paparazzi, ViewModel testing with Turbine, TestDispatcher, and runTest patterns. Use when writing Compose UI tests, ViewModel tests, or screenshot tests."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Compose Testing

package/pipeline/skills/shared/external/council/SKILL.md

@@ -7,6 +7,7 @@ description: |
   Triggers on: "should we X or Y", "second opinion", "is this worth it",
   "ship now or wait", requests for dissent or multiple perspectives.
 metadata:
+  source: multi-agent-pipeline
   version: 1.0.0
 ---
 

package/pipeline/skills/shared/external/css-modern/SKILL.md

@@ -2,6 +2,7 @@
 name: css-modern
 description: "Modern CSS: container queries, nesting, @layer, Grid/Flexbox patterns, custom properties, animations, and transitions. Use when writing or reviewing modern CSS: layout, container queries, custom properties, animation."
 metadata:
+  source: multi-agent-pipeline
   tags: [css, grid, flexbox, container-queries, nesting, animations, frontend]
   version: "2025.1"
 ---

package/pipeline/skills/shared/external/database-patterns/SKILL.md

@@ -2,6 +2,7 @@
 name: database-patterns
 description: "Database patterns: SQL best practices (PostgreSQL), indexing, query optimization, migrations, schema design, ORMs (SQLAlchemy, Prisma, Drizzle). Use when designing a schema, writing migrations, or a query needs optimising."
 metadata:
+  source: multi-agent-pipeline
   tags: [database, sql, postgresql, prisma, drizzle, sqlalchemy, backend]
   version: "2025.1"
 ---

package/pipeline/skills/shared/external/evidence-github/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: evidence-github
 description: Search GitHub for facts an analysis can cite - a known issue in a dependency, the PR that fixed it, what a release actually changed, prior art for a pattern. Use when a spec, review or triage needs to know whether a problem is already known upstream.
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # GitHub as evidence

package/pipeline/skills/shared/external/evidence-registry/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: evidence-registry
 description: Check a package's real version, deprecation status and release notes on npm, PyPI, Maven Central or Swift Package Index. Use when a spec or review depends on what a dependency currently is rather than what a lockfile said months ago. Keyless HTTP, works on every platform.
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Package registries as evidence

package/pipeline/skills/shared/external/gradle-kotlin-dsl/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: gradle-kotlin-dsl
 description: "Configure Android builds with Gradle Kotlin DSL, version catalogs (libs.versions.toml), convention plugins (build-logic module), common configurations for android library/compose/testing, build variants, flavors, signing configs, R8/ProGuard rules, and build performance optimization including configuration cache and parallel execution. Use when setting up Gradle builds, adding dependencies, creating convention plugins, or optimizing build times."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # Gradle Kotlin DSL

package/pipeline/skills/shared/external/html-semantic/SKILL.md

@@ -2,6 +2,7 @@
 name: html-semantic
 description: "Semantic HTML5: elements, forms with validation and accessibility, SEO best practices, structured data, Open Graph, Twitter Cards. Use when writing or reviewing markup, forms or document structure for semantics, accessibility and SEO."
 metadata:
+  source: multi-agent-pipeline
   tags: [html, semantic, seo, forms, open-graph, structured-data, frontend]
   version: "2025.1"
 ---

package/pipeline/skills/shared/external/humanizer/SKILL.md

@@ -6,6 +6,7 @@ description: |
   mechanical structure, and sycophantic tone. Use when editing text, writing
   documentation, commit messages, PR descriptions, or any user-facing content.
 metadata:
+  source: multi-agent-pipeline
   version: 1.2.0
 ---
 

package/pipeline/skills/shared/external/ios-coding-standard/SKILL.md

@@ -3,6 +3,7 @@ name: ios-coding-standard
 description: "The iOS coding-standard rule registry: 99 stable-ID rules across readability, security, service layer, business rules, concurrency, testing, module boundaries, naming and visibility, each with a severity and enforcement kind. Use when writing or reviewing Swift and you need the project rule rather than an opinion, or on a persistence, logging or business-rule-placement question."
 user-invocable: true
 metadata:
+  source: multi-agent-pipeline
   standards-registry: references/rules.yml
 ---
 

package/pipeline/skills/shared/external/ios-module-structure/SKILL.md

@@ -3,6 +3,7 @@ name: ios-module-structure
 description: "The ios-module-structure rule registry: stable-ID rules over where a declaration lives, what its file is called and what its folder must contain beside it, plus a checker that runs them against one module. Use when auditing or refactoring a module's tree, or when a review wants a rule ID rather than a preference about layout."
 user-invocable: true
 metadata:
+  source: multi-agent-pipeline
   standards-registry: references/rules.yml
 ---
 

package/pipeline/skills/shared/external/ios-security/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ios-security
 description: "Secure iOS apps with Keychain Services, CryptoKit encryption, biometric authentication (Face ID, Touch ID), Secure Enclave key storage, LAContext, App Transport Security (ATS), certificate pinning, data protection classes, and secure coding patterns. Use when implementing app security features, auditing privacy manifests, configuring App Transport Security, securing keychain access, adding biometric authentication, or encrypting sensitive data with CryptoKit."
+metadata:
+  source: multi-agent-pipeline
 ---
 
 # iOS Security

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

@@ -1,294 +1,102 @@
 ---
 name: localization-reuse-map
-description: >-
-  Builds a per-screen localization-reuse map for one redesigned screen (iOS, Android, web): pairs each
-  UI element's new key and values with the legacy key per platform and the live CMS copy from Figma Dev
-  Mode annotations, recommends reuse, review or new for the content team to confirm, renders a key-to-UI
-  overlay, publishes a Confluence page, and flags error and dynamic keys the registry misses. Use when
-  mapping one redesigned screen's strings to legacy ones. Triggers - localization reuse map, map old
-  keys to new keys, reuse legacy translations, CMS copy from Figma annotations, localization excel, CMS
-  import sheet, /localization-reuse-map.
+description: "Localization reuse map for one redesigned screen on iOS, Android and web: new keys set against each platform's legacy key, legacy values and the Figma-annotation CMS copy, with a reuse / review / new verdict, a key overlay, per-key shots, a CMS import sheet and a Confluence page. Use it to map old keys onto new ones, reuse legacy translations, pull CMS copy out of Figma annotations, or build a localization excel or CMS import sheet; also answers to /localization-reuse-map. Not for several screens at once, and not for minting or defining new keys (the resource-authoring flow)."
+metadata:
+  version: 1.0.0
+  source: multi-agent-pipeline
 ---
 
-# Localization Reuse Map  -  old↔new localization map for one screen
+# localization-reuse-map
 
-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**.
+One run covers one redesigned screen on every platform where it exists. The output is a table with a row per UI element that answers a single question for the content team: can this string reuse what the legacy app already ships, does it need a human look, or is it genuinely new?
 
-**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).
+Scope rules that hold for every run:
 
-## 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:
+- **One screen per run.** Rolling several screens into one map is out of scope.
+- **Recommend, never decide.** The verdict column only suggests. The decision belongs to the content team, so no verdict is ever presented as settled.
+- **Never invent a value.** A backend serves the legacy translations; either fetch them, or keep the Old column empty and add a note. CMS copy comes from the Figma annotation or stays blank. A blank cell is better than a guess.
+- **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.
+- **Chrome language.** Author-written `element` labels and `note` text follow `--ui-lang`; keys and translation values stay verbatim.
 
-| 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
+It is not a key-minting tool: new keys and their values belong to the resource-authoring flow.
 
-*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.
+## Project settings
 
-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.
+Nothing company-specific is built in. Establish these once per project (read them from the project's docs or ask), then reuse them for every screen:
 
-   **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.
+| Setting | What it is | Example |
+|---|---|---|
+| Specs repo + design export | Screen frames, `components-used.md`, `screenshot.png`, `tree.json` | `design-export/<project>/screens/<slug>/` |
+| Resources root | Suggested new values and the component registry | `resources/Localization/Suggested/<Key>.json` |
+| Legacy label endpoint | For refreshing the legacy snapshot | `--endpoint` + `--headers-file` |
+| Legacy key prefix | Display-only prefix the backend stores | mapping `legacyKeyPrefix`, e.g. `Mobile-` |
+| Web i18n convention | For legacy and/or new web apps | `t('key')` / `$t('key')`, keys in `locales/<lang>.json` |
+| Confluence target | Base URL, space, parent page | `CONFLUENCE_BASE_URL` / `CONFLUENCE_SPACE` / `CONFLUENCE_PARENT` |
+| CMS taxonomy | Property Group / Module buckets in the spreadsheet | `--taxonomy cms-taxonomy.json` |
+| Document language | Headings, legend and labels | `--ui-lang en` (default) or `tr` |
+
+Secrets live only in a keychain item or a `--headers-file`. They never go into the mapping, the taxonomy file, the docs or a command line.
+
+At the start, ask the user only for what is still unknown: where the implemented screen lives, the Figma file key and node-ids (or a confirmed design-export slug), and, once it is time to publish, the Confluence target and the formats wanted.
+
+## Where this sits
+
+After the screen spec exists: screen spec, then this map, then publish. If the repo holds a snapshot, the registry and the Suggested files are taken from it (see [publish-and-snapshot](reference/publish-and-snapshot.md)).
+
+## Steps
+
+The helpers in `scripts/` use nothing beyond the Python 3 standard library, apart from one bash script. Commands and how each source is traced are covered in [sources-and-recipes](reference/sources-and-recipes.md).
+
+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.
+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).
+8. **Overlay.** Run `render-overlay.py --out <dir> --mapping <map>.json`; it produces `<slug>.overlay.png`, which the mapping's `overlay` field then names.
+9. **Key screenshots.** Run `render-key-shots.py --out <dir> --mapping <map>.json [--slug]`; it fills `keyshots/` and writes the manifest, which the mapping's `keyshots` field then names.
+10. **Artifacts.** `build-artifact.py <map>.json --out <dir>` (add `--docx`, `--pdf` or `--all` on request).
+11. **Spreadsheet.** `build-spreadsheet.py <map>.json --out <dir>` (add `--csv` or `--csv-only`).
+12. **Gate.** Run `verify-map.py --screen-path <dir> --mapping <map>.json [--resources-root <res>]`. Exit code 2 stops publishing.
+13. **Publish.** Ask which target(s): (A) Confluence via `publish-confluence.py`, (B) a specs-repo PR under `localizations/<slug>/`, or both. Details: [publish-and-snapshot](reference/publish-and-snapshot.md).
+
+When the Figma frame carries no annotations, say so, explain that keys will be mapped by reading the screen, and confirm the screen state (mock or screenshot) and the anchored element list with the user before rendering.
+
+## Choosing a verdict
+
+| Verdict | When |
+|---|---|
+| `reuse` | Same function and the same or an equivalent value, or a single clean key that both legacy platforms share. The team adopts the legacy value or key and orders no new translation. |
+| `review` | Same function, but the value drifted, the wording changed, the legacy key differs across platforms, or legacy covers too few languages. The team chooses. |
+| `new` | Nothing in legacy corresponds to it, because the feature or the business rule is new. Both a key and a value have to be minted. |
+
+Edge cases:
+
+- **Component-owned key**: note `(owned by <Component>)`; 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.
+- **Dynamic key** that cannot be resolved statically: map it with `verdict: review` and a note "dynamic - enumerate at runtime". Never drop it.
+- **Partial legacy**: legacy covers only some languages (en and tr, for instance), or only one platform has a legacy key; record that in the note.
+- **What reuse means**: reusing the value, or aliasing the legacy key. It is not string equality between a namespaced new key and a flat legacy key.
+
+## Done means
+
+- Each row carries a `verdict`, and no Old or CMS value is made up; an empty Old or CMS cell is an acceptable state.
+- `verify-map.py` passes: every `newKey` is wired (or exempt as component-owned or dynamic), no wired key is unmapped, no empty or invented values, and every `error`/`dynamic` hit from `scan-screen-keys.py` is a row.
+- `build-artifact.py` ran clean; the `.md` has the header, legend, totals and the fixed column order including the CMS columns.
+- The overlay PNG exists (or the `.html` fallback is noted) and the mapping's `overlay` names it.
+- One keyshot PNG per matched row; the mapping's `keyshots` names the manifest; every non-dash Screenshot cell resolves to a file; `keyshots/` holds no orphans. Renaming a key or reordering rows renumbers the files, so re-render instead of renaming by hand.
+- The spreadsheet has one row per mapping row and the nine fixed columns, values from `new` and annotations from `cms`, and is attached at publish.
+- A second publish reports `updated` and bumps the version of the existing page id; it never creates another page.
+
+## References
+
+- [sources-and-recipes](reference/sources-and-recipes.md): the origin of every column, legacy tracing on each platform, overlay and keyshot geometry, pitfalls.
+- [format-and-output](reference/format-and-output.md): the mapping schema, artifact formats, spreadsheet columns and the script reference.
+- [publish-and-snapshot](reference/publish-and-snapshot.md): the snapshot that keeps reads in one repo, Confluence publishing, and the specs-repo PR.
+- [example mapping](example-mapping.json): a neutral mapping of nine rows that covers each edge case listed above.