@mmerterden/multi-agent-pipeline 20.8.0 → 20.8.1

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

@@ -1,6 +1,6 @@
 ---
 name: authentication
-description: "iOS sign-in with AuthenticationServices and LocalAuthentication: Sign in with Apple, passkey (WebAuthn) registration and login via ASAuthorizationPlatformPublicKeyCredentialProvider, ASAuthorizationController credential state and revocation, ASWebAuthenticationSession OAuth and third-party login, Password AutoFill, server-side identity-token validation, LAContext biometric re-authentication. Use when adding or reviewing account flows."
+description: "iOS sign-in with AuthenticationServices and LocalAuthentication: Sign in with Apple, passkey (WebAuthn) sign-up and login via ASAuthorizationPlatformPublicKeyCredentialProvider, ASAuthorizationController credential state and revocation, ASWebAuthenticationSession OAuth, third-party login, Password AutoFill, server identity-token validation, LAContext biometric re-auth prompts and policy. Use when adding or reviewing account flows."
 metadata:
   source: multi-agent-pipeline
 ---
@@ -44,7 +44,7 @@ extension WelcomeViewController: ASAuthorizationControllerPresentationContextPro
         guard let window = view.window else {
             preconditionFailure("Start Sign in with Apple only while this screen is on screen")
         }
-        return window   // ASPresentationAnchor() with no scene is deprecated in iOS 26
+        return window   // ASPresentationAnchor is UIWindow; UIWindow() is deprecated in iOS 26
     }
 }
 ```
@@ -104,22 +104,30 @@ People can revoke the app at any time under Settings > Apple Account >
 Sign-In & Security, so check on every launch:
 
 ```swift
-func verifyAppleCredential(for userID: String) {
+@MainActor
+func verifyAppleCredential(for userID: String) async {
     let provider = ASAuthorizationAppleIDProvider()
-    provider.getCredentialState(forUserID: userID) { credentialState, _ in
-        DispatchQueue.main.async {
-            switch credentialState {
-            case .authorized:  SessionStore.shared.resume()
-            case .revoked:     SessionStore.shared.signOutAndWipe()
-            case .notFound:    SessionStore.shared.presentLogin()
-            case .transferred: SessionStore.shared.migrateTransferredUser(userID)
-            @unknown default:  SessionStore.shared.presentLogin()
-            }
-        }
+    let credentialState: ASAuthorizationAppleIDProvider.CredentialState
+    do {
+        credentialState = try await provider.credentialState(forUserID: userID)
+    } catch {
+        SessionStore.shared.presentLogin()
+        return
+    }
+    switch credentialState {
+    case .authorized:  SessionStore.shared.resume()
+    case .revoked:     SessionStore.shared.signOutAndWipe()
+    case .notFound:    SessionStore.shared.presentLogin()
+    case .transferred: SessionStore.shared.migrateTransferredUser(userID)
+    @unknown default:  SessionStore.shared.presentLogin()
     }
 }
 ```
 
+The function runs on the main actor and awaits the async form of
+`getCredentialState(forUserID:completion:)`, so the session calls need no hop
+back to the main queue.
+
 `.transferred` means the app moved to a different developer team and the user
 identifier must be migrated. Also subscribe to
 `ASAuthorizationAppleIDProvider.credentialRevokedNotification` and sign the
@@ -133,6 +141,7 @@ backend and keep only what it returns:
 ```swift
 enum SessionAPI {
     struct Session: Decodable { let accessToken: String }
+    private static let transport = URLSession(configuration: .ephemeral)
 
     static func exchange(token: Data?, code: Data?) async throws {
         guard let token, let code,
@@ -144,7 +153,7 @@ enum SessionAPI {
         call.httpMethod = "POST"
         call.addValue("application/json", forHTTPHeaderField: "Content-Type")
         let body = try JSONEncoder().encode(["identity_token": jwt, "authorization_code": grant])
-        let (bytes, reply) = try await URLSession(configuration: .ephemeral).upload(for: call, from: body)
+        let (bytes, reply) = try await transport.upload(for: call, from: body)
         let status = (reply as? HTTPURLResponse)?.statusCode ?? 0
         if status != 200 { throw URLError(.userAuthenticationRequired) }
 
@@ -312,8 +321,11 @@ func confirmOwner() async -> Bool {
 }
 ```
 
-Info.plist must include `NSFaceIDUsageDescription`; without it the app crashes
-on Face ID hardware.
+Info.plist must include `NSFaceIDUsageDescription`, the same rule the
+`swift-security` skill sets for biometric keychain items. The `LAContext` header
+asks apps to supply it: its string is shown the first time the app uses Face ID,
+and once the user denies Face ID for the app, evaluations fail with
+`LAError.biometryNotAvailable`.
 
 ## Security boundaries
 
@@ -326,7 +338,7 @@ Keychain, and `LAContext.evaluatePolicy` on its own must never unlock a
 protected secret.
 
 Hand off to `swift-security`: Keychain architecture and migration,
-access-control policy design, CryptoKit, Secure Enclave, certificate pinning
+biometric-gated keychain items and their access-control policy, CryptoKit, Secure Enclave, certificate pinning
 and trust evaluation, sharing items between apps, hardening local storage, and
 mapping against OWASP MASVS/MASTG. App and device attestation belongs to `device-integrity`.
 

package/pipeline/skills/shared/external/authentication/references/keychain-biometric.md

@@ -104,7 +104,9 @@ func unlockSettings(reason: String) async throws -> Bool {
 ### Info.plist
 
 Add `NSFaceIDUsageDescription` with a sentence explaining why the app uses
-Face ID. Face ID devices crash the app if it is missing.
+Face ID. The `LAContext` header asks for this key; the system shows the string
+the first time the app uses Face ID, and evaluations fail with
+`LAError.biometryNotAvailable` once the user denies Face ID for the app.
 
 ### Tuning the context
 

package/pipeline/skills/shared/external/background-processing/SKILL.md

@@ -113,10 +113,7 @@ func perform(_ task: BGTask, _ job: @escaping @Sendable () async throws -> Void)
         let finished = (try? await job()) != nil
         task.setTaskCompleted(success: finished && !Task.isCancelled)
     }
-    task.expirationHandler = {
-        work.cancel()
-        task.setTaskCompleted(success: false)
-    }
+    task.expirationHandler = { work.cancel() }
 }
 ```
 
@@ -124,7 +121,11 @@ func perform(_ task: BGTask, _ job: @escaping @Sendable () async throws -> Void)
 processing example below reuses `perform`. Two habits matter: schedule the
 next run first, so a crash or expiry does not break the chain, and always
 install an `expirationHandler`, because the system can take the time back at
-any moment.
+any moment. The handler only cancels; the work `Task` is the one completion
+path, so `setTaskCompleted(success:)` runs exactly once, with `false` after an
+expiry. That relies on the job honouring cancellation (`URLSession` async calls
+and `Task.checkCancellation()` throw), so the `Task` ends soon after the
+handler fires.
 
 `BGTask` is not `Sendable`, yet both the work `Task` and the expiration
 handler need it, and the handler runs on a queue the framework picks. The
@@ -165,7 +166,7 @@ the app. It differs from the other two types:
 - Under resource pressure the system may end it, and tasks reporting little
   progress go first.
 - The user or the system can cancel it; the `expirationHandler` must stop the
-  work and remove partial output before completing.
+  work and remove partial output, and the cancelled work then completes once.
 - Its handler is exempt from the register-at-launch rule. `submit` expects
   an identifier that already has a handler, so register the job's identifier
   right before submitting it.
@@ -346,7 +347,8 @@ func application(_ app: UIApplication,
 - **Skipping `setTaskCompleted(success:)`.** The system schedules the app less
   often afterwards. Complete on every path, errors included.
 - **No expiration handler.** The task is killed abruptly instead of stopping
-  cleanly. Cancel the work and complete from the handler.
+  cleanly. Cancel the work from the handler and let the cancelled work report
+  `success: false`, so completion happens once.
 - **Asking too often.** A refresh every minute gets throttled hard. Use 15
   minutes or more, and remember `earliestBeginDate` is a hint.
 - **Too much work per run.** A ten-minute job inside a refresh task will not
@@ -359,7 +361,7 @@ func application(_ app: UIApplication,
 - [ ] `UIBackgroundModes` has `fetch` and/or `processing` as needed
 - [ ] Refresh and processing handlers are registered before launch completes;
       continued processing handlers are registered before their `submit`
-- [ ] `setTaskCompleted(success:)` runs on every path
+- [ ] `setTaskCompleted(success:)` runs exactly once on every path
 - [ ] `expirationHandler` cancels in-flight work
 - [ ] The handler schedules the next task
 - [ ] `earliestBeginDate` is sensible and read as a lower bound only

package/pipeline/skills/shared/external/background-processing/references/background-task-patterns.md

@@ -94,14 +94,14 @@ func backUp(_ task: BGProcessingTask, assets: [PhotoAsset]) {
             task.setTaskCompleted(success: false)
         }
     }
-    task.expirationHandler = {
-        work.cancel()
-        task.setTaskCompleted(success: false)
-    }
+    task.expirationHandler = { work.cancel() }
 }
 ```
 
-When the window closes, the saved cursor lets the next run skip what is done.
+When the window closes, the handler cancels the work, `checkCancellation()`
+throws, and the `catch` reports `success: false`: one completion path, as in
+`perform` and `handleExport`. The saved cursor lets the next run skip what is
+done.
 The `nonisolated(unsafe)` copy lets the non-`Sendable` `BGTask` be shared by
 the work `Task` and the expiration handler under Swift 6.
 
@@ -257,8 +257,8 @@ listed. GPU use also depends on the Background GPU Access entitlement.
 ### Cancellation from the Live Activity
 
 The user can stop the job from the system Live Activity. That arrives through
-`expirationHandler`: cancel the work, delete partial output, and complete with
-`success: false`.
+`expirationHandler`: cancel the work and delete partial output there; the
+cancelled work then completes with `success: false`, as `handleExport` does.
 
 ### Progress drives survival
 

package/pipeline/skills/shared/external/core-bluetooth/SKILL.md

@@ -33,8 +33,10 @@ There is no "request Bluetooth permission" call. The system asks the first
 time the app creates a manager, so create one only when the user reaches the
 feature that needs it. Then look at two things:
 
-- `manager.authorization`: `.denied` and `.restricted` stay that way until the
-  user changes Settings, so show guidance rather than retrying.
+- `CBManager.authorization` (a class property from iOS 13.1; the instance
+  property was deprecated after 13.0): `.denied` and `.restricted` stay that way
+  until the user changes Settings, so show guidance rather than retrying. Being a
+  class property, it can be read before any manager is created.
 - `manager.state`: do nothing (scan, connect, advertise, add services) until it
   is `.poweredOn`.
 

package/pipeline/skills/shared/external/core-data/SKILL.md

@@ -22,7 +22,7 @@ once and share it.
 ```swift
 import CoreData
 
-final class LibraryStore: @unchecked Sendable {
+final class LibraryStore: Sendable {
     static let shared = LibraryStore()
     let container: NSPersistentContainer
 
@@ -42,6 +42,8 @@ final class LibraryStore: @unchecked Sendable {
 }
 ```
 
+`LibraryStore` is checked `Sendable` with no `@unchecked`: its only stored
+property is a `let` of `NSPersistentContainer`, which the SDK marks `Sendable`.
 Replace `fatalError` with real recovery in shipping code. When the store syncs
 through iCloud, create an `NSPersistentCloudKitContainer` instead.
 
@@ -215,11 +217,13 @@ container.persistentStoreDescriptions = [description]
 ```swift
 final class HistoryReader: NSObject, @unchecked Sendable {
     private let container: NSPersistentContainer
+    private let worker: NSManagedObjectContext
     private let tokenKey: String            // one per target: "history.app", "history.widget"
     private var lastToken: NSPersistentHistoryToken?
 
     init(container: NSPersistentContainer, target: String) {
         self.container = container
+        self.worker = container.newBackgroundContext()
         self.tokenKey = "history.\(target)"
         super.init()
         lastToken = Self.loadToken(forKey: tokenKey)
@@ -229,7 +233,6 @@ final class HistoryReader: NSObject, @unchecked Sendable {
     }
 
     @objc private func storeChanged(_ note: Notification) {
-        let worker = container.newBackgroundContext()
         worker.perform { [self] in
             let fetch = NSPersistentHistoryChangeRequest.fetchHistory(after: lastToken)
             let history = try? worker.execute(fetch) as? NSPersistentHistoryResult
@@ -263,6 +266,13 @@ final class HistoryReader: NSObject, @unchecked Sendable {
 }
 ```
 
+`@unchecked Sendable` rests on one guarantee: after `init` (which sets
+`lastToken` before the observer is registered), `lastToken` is read and written
+only inside `worker.perform`, and one context runs its `perform` blocks one at a
+time on its private queue. Creating a new background context per notification
+would break that, because two notifications could then run on two queues at
+once.
+
 The static merge call is safe from the worker queue; calling
 `viewContext.mergeChanges(fromContextDidSave: transaction.objectIDNotification())`
 inside `viewContext.perform` is the equivalent instance form.

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

@@ -1,6 +1,6 @@
 ---
 name: coreml
-description: "Swift-side Core ML: loading .mlmodel, .mlpackage and .mlmodelc, predictions via generated classes and MLFeatureProvider, compute units, async and stateful prediction with MLState, MLTensor, MLMultiArray, Vision CoreMLRequest and VNCoreMLRequest, MLComputePlan, multi-model pipelines, deployment and profiling. Use when integrating, reviewing, deploying or profiling a Core ML model in an app. Not for Python conversion (apple-on-device-ai)."
+description: "Swift-side Core ML: loading .mlmodel, .mlpackage and .mlmodelc, predictions via generated classes and MLFeatureProvider, compute units, async and stateful prediction with MLState, MLTensor, MLMultiArray, MLComputePlan, multi-model pipelines, deployment and profiling. Use when integrating, reviewing, deploying or profiling a Core ML model in an app. Not for Python conversion (apple-on-device-ai) or Vision requests (vision-framework)."
 metadata:
   source: multi-agent-pipeline
 ---

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

@@ -1,6 +1,6 @@
 ---
 name: cryptokit
-description: "CryptoKit primitives in Swift: SHA-2 and SHA-3, HMAC, AES-GCM and ChaChaPoly, P256, P384, P521, Curve25519 and ML-DSA signatures, ECDH with HKDF, HPKE, ML-KEM and X-Wing, Secure Enclave keys. Use when hashing, encrypting, signing or exchanging keys, or migrating from CommonCrypto. Not for Keychain policy (swift-security)."
+description: "CryptoKit in Swift: SHA-2, SHA-3, HMAC, AES-GCM, ChaChaPoly, P256, P384, P521, Curve25519 and ML-DSA signatures, ECDH with HKDF, HPKE, ML-KEM, X-Wing, SecureEnclave.P256 signing and ECDH. Use when hashing, encrypting, signing or exchanging keys, or migrating from CommonCrypto. Not for Keychain policy (swift-security)."
 metadata:
   source: multi-agent-pipeline
 ---

package/pipeline/skills/shared/external/device-integrity/SKILL.md

@@ -138,12 +138,16 @@ actor AttestKeyStore {
     }
 
     private func saveKeyID(_ value: String) throws {
-        SecItemDelete(baseQuery as CFDictionary)
+        let data = Data(value.utf8)
         var item = baseQuery
-        item[kSecValueData as String] = Data(value.utf8)
+        item[kSecValueData as String] = data
         item[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
         let status = SecItemAdd(item as CFDictionary, nil)
-        guard status == errSecSuccess else { throw IntegrityError.keyNotGenerated }
+        if status == errSecSuccess { return }
+        guard status == errSecDuplicateItem else { throw IntegrityError.keyNotGenerated }
+        let updated = SecItemUpdate(baseQuery as CFDictionary,
+                                    [kSecValueData as String: data] as CFDictionary)
+        guard updated == errSecSuccess else { throw IntegrityError.keyNotGenerated }
     }
 
     private func loadKeyID() -> String? {
@@ -158,8 +162,10 @@ actor AttestKeyStore {
 }
 ```
 
-Save, load and delete all build on the same `baseQuery`, so the account
-attribute always carries the account suffix. The delete path in the
+`saveKeyID` adds the item and falls back to `SecItemUpdate` on
+`errSecDuplicateItem`, the same add-or-update rule the `swift-security` skill
+sets for every keychain save. Save, load and delete all build on the same
+`baseQuery`, so the account attribute always carries the account suffix. The delete path in the
 [rejected-key section](references/device-integrity-patterns.md#rejected-keys)
 reuses it for that reason.
 

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

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

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

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

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

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

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

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

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

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

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

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