@mmerterden/multi-agent-pipeline 20.8.0 → 20.8.2

package/pipeline/skills/shared/external/cloudkit-sync/SKILL.md

@@ -307,6 +307,48 @@ func moveToCloud(_ local: URL) {
 Watch for changes with an `NSMetadataQuery` whose search scope is
 `NSMetadataQueryUbiquitousDocumentsScope` or `NSMetadataQueryUbiquitousDataScope`.
 
+### Coordinated reads and writes
+
+The iCloud daemon reads and writes files in the ubiquity container at the same
+time as the app, so every direct access to a ubiquitous file goes through
+`NSFileCoordinator`. Do the file work only inside the accessor block and only
+with the URL it passes in, which can differ from the one requested. A
+coordinated read of a ubiquitous item waits for its contents to download
+unless `.immediatelyAvailableMetadataOnly` is passed. Coordination blocks the
+calling thread, so keep it off the main actor.
+
+```swift
+nonisolated func readCoordinated(_ url: URL) throws -> Data {
+    var coordinationError: NSError?
+    var result: Result<Data, any Error> = .failure(CocoaError(.fileReadUnknown))
+    NSFileCoordinator().coordinate(readingItemAt: url, options: [], error: &coordinationError) { safeURL in
+        result = Result { try Data(contentsOf: safeURL) }
+    }
+    if let coordinationError { throw coordinationError }
+    return try result.get()
+}
+
+nonisolated func writeCoordinated(_ data: Data, to url: URL) throws {
+    var coordinationError: NSError?
+    var writeError: (any Error)?
+    NSFileCoordinator().coordinate(writingItemAt: url, options: .forReplacing, error: &coordinationError) { safeURL in
+        do { try data.write(to: safeURL, options: .atomic) } catch { writeError = error }
+    }
+    if let coordinationError { throw coordinationError }
+    if let writeError { throw writeError }
+}
+```
+
+An object that keeps a file open (an editor, a live preview) adopts
+`NSFilePresenter` so it hears about changes, moves and deletions that iCloud
+makes: implement `presentedItemURL`, return a private `OperationQueue` from
+`presentedItemOperationQueue` (the main queue invites deadlocks), react in
+`presentedItemDidChange()`, and pair `NSFileCoordinator.addFilePresenter(_:)`
+with `removeFilePresenter(_:)`. Create the presenter's own coordinators with
+`NSFileCoordinator(filePresenter:)` so it is not told about its own writes.
+`UIDocument` already does all of this, so a document-based app gets
+coordination by subclassing it.
+
 ## Account status
 
 Check the account before any sync, and listen for `.CKAccountChanged`.
@@ -393,6 +435,7 @@ func merged(_ error: CKError) -> CKRecord? {
 - [ ] `.userDeletedZone` handled
 - [ ] SwiftData review gives both the model-compatibility and schema-rollout verdicts
 - [ ] Key-value store external-change notification observed
+- [ ] Ubiquitous files read and written through `NSFileCoordinator`; open files have an `NSFilePresenter`
 - [ ] Encryption review mentions: references cannot be encrypted, encrypted fields cannot be queried or sorted, assets are encrypted already
 - [ ] `CKSyncEngine` state serialization saved (iOS 17+)
 

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/core-nfc/SKILL.md

@@ -259,6 +259,37 @@ rejects the capture. Always connect before sending any command. The `select`, `i
 block reads, MIFARE and FeliCa calls), which is written out in the
 [patterns reference](references/nfc-patterns.md).
 
+### Session configuration (iOS 26.4)
+
+iOS 26.4 adds `NFCTagReaderSession.Configuration`, a value that carries the
+polling options plus optional subsets of the ISO 7816 select identifiers and
+FeliCa system codes from Info.plist (entries not listed there are dropped; an
+empty array means all of them). `init(configuration:delegate:queue:)` builds a
+session from it and, unlike `init?(pollingOption:delegate:queue:)`, is not
+failable; the older initializer is deprecated as of 26.4.
+`restartPolling(configuration:)` restarts discovery with a different
+configuration for that one restart only: a later plain `restartPolling()` goes
+back to the configuration the session was created with. The new initializer,
+like the old one, is unavailable to app extensions. Keep `init?(pollingOption:delegate:queue:)` behind an
+availability check while the deployment target is below 26.4.
+
+```swift
+@available(iOS 26.4, *)
+func makeTransitSession(delegate: any NFCTagReaderSessionDelegate) -> NFCTagReaderSession {
+    let config = NFCTagReaderSession.Configuration(
+        pollingOption: [.iso14443, .iso18092],
+        iso7816SelectIdentifiers: ["A000000000000001"],
+        feliCaSystemCodes: []
+    )
+    return NFCTagReaderSession(configuration: config, delegate: delegate, queue: nil)
+}
+
+@available(iOS 26.4, *)
+func pollOnlyFeliCa(_ session: NFCTagReaderSession) {
+    session.restartPolling(configuration: .init(pollingOption: .iso18092))
+}
+```
+
 ## Writing NDEF
 
 Query the status first. Only `.readWrite` tags accept a write; anything else

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/ios-coding-standard/references/rules.yml

@@ -457,7 +457,7 @@ rules:
       Scene, ViewModel, AnalyticsTracking, UseCase, Repository (+protocol +mock), Mapper +
       models  -  each present when its responsibility exists. In a converted module the screen's
       Output enum lives contract-side, not here, and a module-local CoordinatorEvent or
-      LocalizedText aggregator is pre-conversion residue reported as debt. Report a missing file
+      copy aggregator (`<Screen>Copy`) is pre-conversion residue reported as debt. Report a missing file
       whose responsibility leaked elsewhere AND a ceremonial empty file.
 
   - id: STRUCT-03
@@ -1129,7 +1129,7 @@ rules:
             "**/*+Modifiers.swift",
           ],
       }
-    scope_reason: SwiftUI copy surface (LocalizedText); UIKit modules localise through a different seam
+    scope_reason: SwiftUI copy surface (`<Screen>Copy`); UIKit modules localise through a different seam
     title: All user copy goes through the screen's copy surface
     severity: important
     enforcement: judgement

package/pipeline/skills/shared/external/ios-module-structure/modules/_TEMPLATE.yml

@@ -85,7 +85,7 @@ roles:
 #    screen.viewmodelaction:  "Presentation/Models/*ViewModelAction.swift"
 #    screen.viewmodelstate:   "Presentation/Models/*ViewModelState.swift"
 #  Multi-target packages (STRUCT-21):
-#    target.configurator:     "Sources/*/Configuration/*DependencyConfigurator.swift"
+#    target.configurator:     "Sources/*/Configuration/*DependencyRegistrar.swift"
   screen.root: # e.g. "Sources/*/Screens/*"
   screen.entry:
   screen.viewmodel:

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.
@@ -32,7 +32,7 @@ Nothing company-specific is built in. Establish these once per project (read the
 | 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-` |
+| Legacy key prefix | Display-only prefix the backend stores | mapping `legacyKeyPrefix`, e.g. `App-` |
 | 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` |
@@ -51,9 +51,9 @@ After the screen spec exists: screen spec, then this map, then publish. If the r
 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.
+2. **Catch what the cross-reference misses.** First find the type the project generates its keys into (for example `grep -rhoE '\b[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*\.[A-Za-z_]+' <dir> | cut -d. -f1 | sort | uniq -c | sort -rn`) and set it as `"keyType"` in the mapping; the built-in default `L10n` is only a fallback, and a project that uses another accessor gets its real keys missed or downgraded to weak. Then run `scan-screen-keys.py --screen-path <dir> --key-type <KeyType>`. A `WARNING: no key chain of ...` line on stderr means the type is wrong: fix it before going on. 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).
@@ -61,7 +61,7 @@ The helpers in `scripts/` use nothing beyond the Python 3 standard library, apar
 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.
+12. **Gate.** Run `verify-map.py --screen-path <dir> --mapping <map>.json [--resources-root <res>]`, with the accessor from step 2 in the mapping's `keyType` (or passed as `--key-type <KeyType>`). Exit code 2 stops publishing. A PASS that carries the key type `WARNING` is not a pass: set the accessor and run it again.
 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.
@@ -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

@@ -6,7 +6,8 @@
   "screenshot": "screenshot.png",
   "overlay": "sign-up-account-details.overlay.png",
   "keyshots": "sign-up-account-details.keyshots.manifest.json",
-  "legacyKeyPrefix": "Mobile-",
+  "legacyKeyPrefix": "App-",
+  "keyType": "L10n",
   "rows": [
     {
       "element": "Screen title (top bar)",
@@ -74,7 +75,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

@@ -16,6 +16,7 @@ Top level:
 | `overlay` | no | Overlay PNG name |
 | `keyshots` | no | Keyshots manifest name |
 | `legacyKeyPrefix` | no | Prepended to legacy keys for display only |
+| `keyType` | no | The project's key accessor type, a string or a list of strings (for example `"Strings"` or `["Strings", "A11y"]`); `verify-map.py` uses it when `--key-type` is not given, else `L10n`. Any other JSON type stops the gate with exit 2 |
 | `rows` | yes | One object per UI element |
 
 Row:
@@ -34,18 +35,18 @@ Row:
 | `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.
+Keep `new` and `legacy` keyed by every language the project ships. The summary table shows old and new `en`/`tr` plus CMS `tr`/`en`; the details section shows every language of the mapping (or the `--langs` list) 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-"`:
+[`../example-mapping.json`](../example-mapping.json) maps a neutral "Sign Up - Account Details" screen in nine rows, with `legacyKeyPrefix: "App-"`:
 
 | # | Case | Verdict |
 |---|---|---|
 | 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 |
@@ -59,7 +60,7 @@ Keep `new` and `legacy` fully eight-keyed. The summary table shows old and new `
 | 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>.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 Old / New / CMS table per language |
 | `<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 |
@@ -72,7 +73,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 +85,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,30 +97,30 @@ 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 chain of the key type (`--key-type`, default `L10n`) counts as a key only with two or more segments, so `extension L10n.Profile` is not one. A key whose last segment only appears as a word is `weak`; neither is `unverified`. When no chain of the key type is found but Swift or Kotlin code has chains rooted at a common accessor name or ending in `.localized`, a `keyTypeWarning` names those roots; set the key type and rerun | 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
 
 | 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` |
+| `scan-screen-keys.py` | `--screen-path` (required), `--out`, `--category all/error/dynamic/static`, `--key-type` (repeatable or comma list, default `L10n`) |
+| `resolve-new-values.py` | `--keys`, `--keys-file` (`-` for stdin), `--resources-root` or `--suggested-dir`, `--domain localization/accessibility`, `--catalog`, `--report-source`, `--langs` (default `all`) |
+| `resolve-legacy-values.py` | `--keys` (required), `--langs` (default `all`), `--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` |
+| `fetch-annotations.py` | `--file`, `--nodes`, `--mapping`, `--from-mcp`, `--local`, `--source auto/rest/mcp/local`, `--ca-file`, `--out` |
+| `render-overlay.py` | `--mapping` (required), `--spec`, `--file`, `--nodes`, `--scale`, `--ca-file`, `--out`, `--slug`, `--ui-lang en/tr` |
+| `render-key-shots.py` | `--mapping` (required), `--spec` (repeatable), `--file`, `--nodes`, `--pad` (default 150), `--scale`, `--ca-file`, `--out`, `--slug` |
+| `build-artifact.py` | `mapping` (or `-`), `--out`, `--slug`, `--ui-lang en/tr`, `--docx`, `--pdf`, `--all`, `--print-upload`, `--langs` (default `all`) |
 | `build-spreadsheet.py` | `mapping` (or `-`), `--out`, `--slug`, `--channel`, `--taxonomy`, `--csv`, `--csv-only` |
-| `verify-map.py` | `--mapping`, `--screen-path` (both required), `--resources-root`, `--out` |
+| `verify-map.py` | `--mapping`, `--screen-path` (both required), `--resources-root`, `--out`, `--key-type` (else the mapping's `keyType`, else `L10n`) |
 | `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.
+`--langs` takes a comma list, used in the order given, or `all`: every language present in the data the script reads (the mapping rows, the Suggested files and catalog, the snapshot or plist folder, or for `fetch-legacy-labels.py` the snapshot it refreshes), `en` first and the rest sorted, and `en` alone when the data names none. 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 `FIGMA_ACCESS_TOKEN`, then `FIGMA_TOKEN`, then the macOS keychain item `FIGMA_ACCESS_TOKEN`. `--token` is refused with exit 2, since argv is visible to other processes.

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

@@ -51,15 +51,15 @@ python3 scripts/publish-confluence.py \
 
 - **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.
+- **Token**: a Server / Data Center personal access token, sent as a Bearer header. The script reads `CONFLUENCE_API_TOKEN`, then the macOS keychain service given by `--keychain-name` (default `CONFLUENCE_API_TOKEN`). `--token` is refused with exit 2, 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. Each request is bounded: `--connect-timeout 15` and `--max-time 120` for curl, and the script stops waiting for curl after 150 seconds.
 - **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

@@ -21,32 +21,32 @@ A screen's keys come from three places, and each one misses something the others
 
 1. **Design export**: read `screens/<frame>/components-used.md` of each state frame the screen has (default, error, loading, filled...).
 2. **Component registry**: each used component's `<node>.json -> localizationKeys`. These are keys the component renders internally, and they are often absent from the screen code.
-3. **Screen code**: on iOS, each call site of `LocalizationStringKey.<Namespace>.<leaf>` counts as one element.
+3. **Screen code**: on iOS, each call site of `<KeyType>.<Namespace>.<leaf>` counts as one element, where `<KeyType>` is the type the project generates its keys into. Pass it to `scan-screen-keys.py` and `verify-map.py` with `--key-type <Name>` (repeatable, or a comma list), or set `"keyType"` in the mapping for `verify-map.py`; the default is `L10n`.
 
 Take the union and tag every key: screen-specific, component-owned, or shared (a reusable component or a shared primitive).
 
-Registry caveat: a shared component such as `HeaderMain` or `BottomActions` may list keys that this screen never shows, since the screen supplies its own title. Check the code before a registry key goes into the map.
+Registry caveat: a shared component such as `ScreenHeader` or `ActionFooter` may list keys that this screen never shows, since the screen supplies its own title. Check the code before a registry key goes into the map.
 
 ### Keys the union cannot see
 
 Error, validation and alert strings, and keys assembled at runtime, rarely appear in the design export or the registry. Run the scanner on the implemented screen:
 
 ```bash
-python3 scripts/scan-screen-keys.py --out scan.json --screen-path <screen-dir>
+python3 scripts/scan-screen-keys.py --out scan.json --screen-path <screen-dir> --key-type <KeyType>
 ```
 
 Every `error` and `dynamic` hit becomes a row. Compare the `static` hits with the union; whatever remains is a key the code wires but the map lacks. Skipping this step drops those strings silently.
 
 ## New values
 
-Values are authored per key in `Suggested/<Key>.json`, in eight languages, and they are shared by all platforms: one value per key, only the key usage differs per platform.
+Values are authored per key in `Suggested/<Key>.json`, one entry per language the project ships, and they are shared by all platforms: one value per key, only the key usage differs per platform.
 
 ```bash
 python3 scripts/resolve-new-values.py --keys "<k1>,<k2>" --resources-root <res> --langs all \
   --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
@@ -86,13 +88,14 @@ The same element can carry different keys per platform (`AgentaUserAlreadyAdded`
 
 ```bash
 python3 scripts/resolve-legacy-values.py --keys "Continue,EmailAddress" \
-  --snapshot-root resources/Localization/Legacy --langs all --prefix Mobile-
+  --snapshot-root resources/Localization/Legacy --langs all --prefix App-
 ```
 
 - 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.
+- **Backend prefix.** When the backend stores `App-Continue` but the app asks for `Continue`, pass `--prefix App-`, keep the mapping keys bare, and set the mapping's `legacyKeyPrefix` so the table shows the full stored key.
 
 ## Overlay geometry
 
@@ -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.
 
@@ -135,5 +138,5 @@ Geometry reuses the overlay inputs: REST (visible text only, filtered for ancest
 - **Stale snapshot.** Missing from Suggested is not unauthored; pass `--catalog` and refresh the snapshot instead of filing requests.
 - **Value anchoring.** Never anchor a keyshot by value across a whole file: short labels recur on unrelated screens and give a confidently wrong crop, which is worse than a dash. Recover a row only through its own `cmsNodeId`, and leave `characters` out of nodes handed to `render-key-shots.py --spec`, because text present turns value matching back on and can bind an unrelated row.
 - **Confluence auth.** Server / Data Center takes a Bearer PAT (keychain `CONFLUENCE_API_TOKEN`), not the Cloud `user:token` form. Pages are looked up with the `content?title=` query, which reads the database; CQL is avoided because its index lags and leads to duplicate pages.
-- **Secrets.** Never commit a label-service token, Confluence PAT or Figma token into a mapping, a taxonomy file or the docs.
+- **Secrets.** Never commit a label-service token, Confluence PAT or Figma token into a mapping, a taxonomy file or the docs. No script takes a token on the command line: `--token` exits 2, because other processes can read argv. Use the environment variable or the keychain item each script names.
 - **TLS proxies.** Publishing runs through `curl` so a corporate proxy's trust store is honoured (Python `urllib` fails verification there). The token goes in a `chmod 600` config passed with `-K`, never on argv. For the Figma scripts behind such a proxy, export the system roots with `security find-certificate -a -p > roots.pem` and pass `--ca-file roots.pem`.