@mmerterden/multi-agent-pipeline 8.6.2 → 10.0.6

package/pipeline/skills/shared/external/swift-architecture/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "swift-architecture",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "A small SwiftUI travel app has three CRUD screens, async loading from a service, simple search, and one edit sheet. The team wants to start with TCA because it sounds more testable. Review the architecture choice for Swift 6.3 and recommend the smallest pattern that still keeps the code testable.",
+      "expected_output": "A scope-aware architecture review that recommends MV with @Observable as the default starting point, explains when MVVM or TCA would become justified, and keeps detailed SwiftUI state wiring out of scope except for handoff notes.",
+      "files": [],
+      "expectations": [
+        "Recommends starting with MV and @Observable for the described small-to-medium SwiftUI app instead of defaulting to TCA.",
+        "Explains the upgrade triggers for MVVM or TCA in terms of transformed view state, deterministic state transitions, side effects, feature composition, or testing pressure.",
+        "Keeps dependencies injected rather than created inside views or stores.",
+        "Mentions @MainActor for UI-observed Observable state or otherwise preserves Swift 6 data-race safety.",
+        "Routes detailed SwiftUI state ownership and sheet/navigation implementation to swiftui-patterns or swiftui-navigation instead of expanding this skill's scope."
+      ]
+    },
+    {
+      "id": 1,
+      "prompt": "We're migrating an iOS 16 UIKit-heavy app that uses Coordinators, ObservableObject view models, and a few VIPER modules. New features are SwiftUI, but the old modules are still shipping. Write a migration plan that modernizes Observation without forcing one architecture everywhere.",
+      "expected_output": "An incremental migration plan that replaces ObservableObject with @Observable where iOS 17+ is available, preserves Coordinator or VIPER boundaries for legacy UIKit modules, and allows different modules to adopt MV, MVVM, or TCA where justified.",
+      "files": [],
+      "expectations": [
+        "Describes ObservableObject to @Observable migration using State for owned observable objects, plain properties for read-only injected objects, and Bindable only when bindings are needed.",
+        "Treats VIPER as a legacy or strict-boundary maintenance pattern rather than the default for new SwiftUI work.",
+        "Keeps Coordinators for UIKit or hybrid complex navigation but recommends NavigationStack/path routing for pure SwiftUI flows.",
+        "Allows architecture to vary by feature module while warning against mixing patterns inconsistently inside a single module.",
+        "Identifies sibling handoffs for detailed concurrency diagnostics, navigation routing, and Swift Testing implementation."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "A product lead asks for one architecture memo covering SwiftUI state ownership, deep links and tab routing, actor isolation errors, app-wide module boundaries, and test strategy. Split what belongs in swift-architecture versus adjacent skills, then give the architecture-level recommendations.",
+      "expected_output": "A boundary-routing memo that keeps architecture selection, module boundaries, dependency direction, and migration strategy in swift-architecture while routing detailed SwiftUI state, navigation, concurrency, and test harness mechanics to sibling skills.",
+      "files": [],
+      "expectations": [
+        "Keeps pattern selection, module boundaries, dependency direction, and migration strategy in swift-architecture scope.",
+        "Routes detailed SwiftUI @State/@Bindable/@Environment ownership and view composition to swiftui-patterns.",
+        "Routes deep links, tabs, sheets, NavigationStack, and route-model implementation to swiftui-navigation.",
+        "Routes actor isolation, Sendable, strict-concurrency diagnostics, and default MainActor isolation details to swift-concurrency.",
+        "Routes detailed Swift Testing syntax, fixtures, parameterized tests, and suite organization to swift-testing.",
+        "Still provides a concise architecture-level recommendation rather than only listing handoffs."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/swift-charts/SKILL.md

@@ -1,16 +1,15 @@
 ---
 name: swift-charts
-description: "Implement, review, or improve data visualizations using Swift Charts. Use when building bar, line, area, point, pie, or donut charts; when adding chart selection, scrolling, or annotations; when plotting functions with vectorized BarPlot, LinePlot, AreaPlot, or PointPlot; when customizing axes, scales, legends, or foregroundStyle grouping; or when creating specialized visualizations like heat maps, Gantt charts, stacked/grouped bars, sparklines, or threshold lines."
+description: "Implement, review, or improve data visualizations using Swift Charts. Use when building bar, line, area, point, pie, donut, or iOS 26 3D charts; when adding chart selection, scrolling, annotations, axes, scales, legends, or foregroundStyle grouping; when plotting functions with BarPlot, LinePlot, AreaPlot, PointPlot, Chart3D, or SurfacePlot; or when creating heat maps, Gantt charts, grouped bars, sparklines, threshold lines, or spatial visualizations."
 ---
 
 # Swift Charts
 
 Build data visualizations with Swift Charts targeting iOS 26+. Compose marks
-inside a `Chart` container, configure axes and scales with view modifiers, and
-use vectorized plots for large datasets.
+inside `Chart` or `Chart3D`, configure axes and scales with view modifiers, and
+use vectorized plots or 3D plots when the data calls for them.
 
-See `references/charts-patterns.md` for extended patterns, accessibility, and
-theming guidance.
+See [references/charts-patterns.md](references/charts-patterns.md) for extended patterns, 3D charts, accessibility, and theming guidance.
 
 ## Contents
 
@@ -25,6 +24,7 @@ theming guidance.
 - [Annotations](#annotations)
 - [Legend](#legend)
 - [Vectorized Plots (iOS 18+)](#vectorized-plots-ios-18)
+- [3D Charts (iOS 26+)](#3d-charts-ios-26)
 - [Common Mistakes](#common-mistakes)
 - [Review Checklist](#review-checklist)
 - [References](#references)
@@ -35,13 +35,13 @@ theming guidance.
 
 1. Define data as an `Identifiable` struct or use `id:` key path.
 2. Choose mark type(s): `BarMark`, `LineMark`, `PointMark`, `AreaMark`,
-   `RuleMark`, `RectangleMark`, or `SectorMark`.
-3. Wrap marks in a `Chart` container.
+   `RuleMark`, `RectangleMark`, `SectorMark`, or `SurfacePlot`.
+3. Wrap 2D marks in `Chart`; use `Chart3D` only for real spatial or surface data.
 4. Encode visual channels: `.foregroundStyle(by:)`, `.symbol(by:)`, `.lineStyle(by:)`.
 5. Configure axes with `.chartXAxis` / `.chartYAxis`.
 6. Set scale domains with `.chartXScale(domain:)` / `.chartYScale(domain:)`.
 7. Add selection, scrolling, or annotations as needed.
-8. For 1000+ data points, use vectorized plots (`BarPlot`, `LinePlot`, etc.).
+8. For 1000+ 2D data points, use vectorized plots (`BarPlot`, `LinePlot`, etc.).
 
 ### 2. Review existing chart code
 
@@ -157,7 +157,7 @@ RectangleMark(x: .value("Hour", item.hour), y: .value("Day", item.day))
 ```
 
 ### SectorMark (iOS 17+)
-
+Use `SectorMark` for strictly positive values; filter, aggregate, or explain zero/negative values outside the pie or donut.
 ```swift
 // Pie chart
 Chart(data, id: \.name) { item in
@@ -232,7 +232,7 @@ AreaMark(...).foregroundStyle(                                         // Gradie
 ```swift
 @State private var selectedDate: Date?
 @State private var selectedRange: ClosedRange<Date>?
-@State private var selectedAngle: String?
+@State private var selectedAngle: Double?
 
 // Point selection
 Chart(data) { item in
@@ -243,7 +243,7 @@ Chart(data) { item in
 // Range selection
 .chartXSelection(range: $selectedRange)
 
-// Angular selection (pie/donut)
+// Angular selection binds the plottable angle value; derive the category from ranges.
 .chartAngleSelection(value: $selectedAngle)
 ```
 
@@ -282,7 +282,7 @@ BarMark(x: .value("Month", item.month), y: .value("Sales", item.sales))
 .chartLegend(.hidden)                                           // Hide
 .chartLegend(position: .bottom, alignment: .center, spacing: 10) // Position
 .chartLegend(position: .bottom) {                                // Custom
-    HStack(spacing: 16) {
+    HStack {
         ForEach(categories, id: \.self) { cat in
             Label(cat, systemImage: "circle.fill").font(.caption)
         }
@@ -322,29 +322,31 @@ BarPlot(data, x: .value("X", \.x), y: .value("Y", \.y))
     .opacity(0.8)                // Value modifier second
 ```
 
-## Common Mistakes
+## 3D Charts (iOS 26+)
 
-### 1. Using ObservableObject instead of @Observable
+Use `Chart3D` for spatial data or bivariate surfaces, not as a decorative
+replacement for ordinary 2D categorical or time-series charts. `Chart3D`
+accepts `SurfacePlot` plus 3D initializers of `PointMark`, `RuleMark`, and
+`RectangleMark`.
 
 ```swift
-// WRONG
-class ChartModel: ObservableObject {
-    @Published var data: [Sale] = []
-}
-struct ChartView: View {
-    @StateObject private var model = ChartModel()
-}
+@State private var pose: Chart3DPose = .default
 
-// CORRECT
-@Observable class ChartModel {
-    var data: [Sale] = []
-}
-struct ChartView: View {
-    @State private var model = ChartModel()
+Chart3D {
+    SurfacePlot(x: "x", y: "y", z: "z") { x, z in
+        sin(2 * x) * cos(2 * z)
+    }
+    .foregroundStyle(.heightBased)
 }
+.chartXScale(domain: -2...2)
+.chartYScale(domain: -1...1)
+.chartZScale(domain: -2...2)
+.chart3DPose($pose)
 ```
 
-### 2. Missing series parameter for multi-line charts
+## Common Mistakes
+
+### 1. Missing series parameter for multi-line charts
 
 ```swift
 // WRONG -- all points connect into one line
@@ -363,7 +365,7 @@ Chart {
 }
 ```
 
-### 3. Too many SectorMark slices
+### 2. Too many SectorMark slices
 
 ```swift
 // WRONG -- 20 tiny sectors are unreadable
@@ -378,7 +380,7 @@ Chart(groupedData, id: \.name) { item in
 }
 ```
 
-### 4. Missing scale domain when zero-baseline matters
+### 3. Missing scale domain when zero-baseline matters
 
 ```swift
 // WRONG -- axis starts at ~95; small changes look dramatic
@@ -393,7 +395,7 @@ Chart(data) {
 .chartYScale(domain: 0...100)
 ```
 
-### 5. Static foregroundStyle overriding data encoding
+### 4. Static foregroundStyle overriding data encoding
 
 ```swift
 // WRONG -- static color overrides by-value encoding
@@ -406,7 +408,7 @@ BarMark(x: .value("X", item.x), y: .value("Y", item.y))
     .foregroundStyle(by: .value("Category", item.category))
 ```
 
-### 6. Individual marks for 10,000+ data points
+### 5. Individual marks for 10,000+ data points
 
 ```swift
 // WRONG -- creates 10,000 mark views; slow
@@ -420,7 +422,7 @@ Chart {
 }
 ```
 
-### 7. Fixed chart height breaking Dynamic Type
+### 6. Fixed chart height breaking Dynamic Type
 
 ```swift
 // WRONG -- clips axis labels at large text sizes
@@ -432,7 +434,7 @@ Chart(data) { ... }
     .frame(minHeight: 200, maxHeight: 400)
 ```
 
-### 8. KeyPath modifier after value modifier on vectorized plots
+### 7. KeyPath modifier after value modifier on vectorized plots
 
 ```swift
 // WRONG -- compiler error
@@ -446,7 +448,7 @@ BarPlot(data, x: .value("X", \.x), y: .value("Y", \.y))
     .opacity(0.8)
 ```
 
-### 9. Missing accessibility labels
+### 8. Missing accessibility labels
 
 ```swift
 // WRONG -- VoiceOver users get no context
@@ -462,19 +464,26 @@ Chart(data) { item in
 }
 ```
 
+### 9. Treating angle selection as category selection
+
+`chartAngleSelection(value:)` binds the selected plottable angle value. For
+pie and donut charts, map that numeric value through cumulative sector ranges
+before comparing it to a category label.
+
 ## Review Checklist
 
 - [ ] Data model uses `Identifiable` or chart uses `id:` key path
-- [ ] Model uses `@Observable` with `@State`, not `ObservableObject`
 - [ ] Mark type matches goal (bar=comparison, line=trend, sector=proportion)
 - [ ] Multi-series lines use `series:` parameter or `.foregroundStyle(by:)`
 - [ ] Axes configured with appropriate labels, ticks, and grid lines
 - [ ] Scale domain set explicitly when zero-baseline matters
-- [ ] Pie/donut limited to 5-7 sectors; small values grouped into "Other"
+- [ ] Pie/donut uses positive values, 5-7 sectors, and "Other" grouping
 - [ ] Selection binding type matches axis data type (`Date?` for date axis)
+- [ ] Pie/donut angle selection maps numeric angle values back to categories
 - [ ] Scrollable charts set `.chartXVisibleDomain(length:)` for viewport
 - [ ] Vectorized plots used for datasets exceeding 1000 points
 - [ ] KeyPath modifiers applied before value modifiers on vectorized plots
+- [ ] `Chart3D` used only for real 3D data or surfaces, with z scale and pose reviewed
 - [ ] Accessibility labels added to marks for VoiceOver
 - [ ] Chart tested with Dynamic Type and Dark Mode
 - [ ] Legend visible and positioned, or intentionally hidden
@@ -482,6 +491,9 @@ Chart(data) { item in
 
 ## References
 
-- Extended patterns: `references/charts-patterns.md`
-- Apple docs: [Swift Charts](https://sosumi.ai/documentation/Charts)
-- Apple docs: [Creating a chart using Swift Charts](https://sosumi.ai/documentation/Charts/Creating-a-chart-using-Swift-Charts)
+- Extended patterns: [references/charts-patterns.md](references/charts-patterns.md)
+- Apple docs: [Swift Charts](https://sosumi.ai/documentation/charts)
+- Apple docs: [Creating a chart using Swift Charts](https://sosumi.ai/documentation/charts/Creating-a-chart-using-Swift-Charts)
+- Apple docs: [Swift Charts updates](https://sosumi.ai/documentation/updates/swiftcharts)
+- Apple docs: [Chart3D](https://sosumi.ai/documentation/charts/Chart3D)
+- Apple docs: [SurfacePlot](https://sosumi.ai/documentation/charts/SurfacePlot)

package/pipeline/skills/shared/external/swift-charts/evals/evals.json

@@ -0,0 +1,47 @@
+{
+  "skill_name": "swift-charts",
+  "evals": [
+    {
+      "id": 0,
+      "name": "chart3d-surface-setup",
+      "prompt": "We are targeting iOS 26 and need an interactive scientific visualization for z-depth data: render y = sin(2x) * cos(2z) as a 3D surface, keep the axes stable, and let the user inspect the view. What Swift Charts API should we use and what code shape should I start from?",
+      "expected_output": "Recommends Chart3D with SurfacePlot, labels x/y/z correctly, sets explicit x/y/z scale domains, binds Chart3DPose for inspection, and avoids using a 2D LinePlot/AreaPlot for the bivariate surface.",
+      "files": [],
+      "expectations": [
+        "Uses Chart3D and SurfacePlot for the iOS 26 bivariate surface instead of a 2D Chart with LinePlot or AreaPlot.",
+        "Shows or describes SurfacePlot with x, y, and z labels and a closure of the form y = f(x, z).",
+        "Sets or recommends explicit chartXScale, chartYScale, and chartZScale domains for stable comparisons.",
+        "Mentions Chart3DPose or chart3DPose for interactive inspection.",
+        "Notes that Chart3D should be used for real spatial or surface data, not as decoration for ordinary 2D charts."
+      ]
+    },
+    {
+      "id": 1,
+      "name": "angle-selection-review",
+      "prompt": "Review this Swift Charts donut snippet: `@State private var selectedProduct: String?`; each `SectorMark(angle: .value(\"Sales\", item.sales))` sets opacity by comparing `selectedProduct == item.name`; the chart ends with `.chartAngleSelection(value: $selectedProduct)`. It compiles strangely. What is wrong and how should we fix the selection model?",
+      "expected_output": "Explains that chartAngleSelection binds the selected plottable angle value, uses a numeric binding such as Double?, maps the value back to a category with cumulative sector ranges, and keeps normal SectorMark pie/donut readability guidance.",
+      "files": [],
+      "expectations": [
+        "States that chartAngleSelection(value:) binds a Plottable angle value rather than the sector's category string.",
+        "Replaces the String? selection binding with a numeric angle binding such as Double?.",
+        "Maps the selected angle through cumulative sales/value ranges to derive the selected product/category.",
+        "Keeps SectorMark readability guidance such as positive values, limiting to 5-7 sectors, or grouping small slices into Other.",
+        "Does not route this bug to generic SwiftUI state management as the primary fix."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "boundary-routing",
+      "prompt": "A dashboard request mixes Swift Charts, MapKit annotations, NavigationStack deep links, async data loading, @Observable model ownership, and a custom VoiceOver audit. Split what belongs in the swift-charts skill versus adjacent Apple skills, then give the chart-specific recommendations.",
+      "expected_output": "Keeps chart construction, marks, axes/scales, selection/scrolling, vectorized plots, Chart3D, and chart accessibility basics in swift-charts while routing map annotations, navigation, data loading, Observation architecture, and detailed accessibility audits to sibling skills.",
+      "files": [],
+      "expectations": [
+        "Keeps Swift Charts chart type selection, marks, axes/scales, legends, annotations, selection, scrolling, vectorized plots, and Chart3D guidance in swift-charts scope.",
+        "Routes MapKit annotations or map overlays to MapKit guidance rather than treating them as chart marks.",
+        "Routes NavigationStack/deep-link implementation to swiftui-navigation.",
+        "Routes async networking/data loading and @Observable model ownership details to the appropriate networking, concurrency, or SwiftUI architecture skills.",
+        "Routes a deep VoiceOver/accessibility audit to ios-accessibility while still giving chart-specific label, color, Dynamic Type, and audio graph considerations."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/swift-charts/references/charts-patterns.md

@@ -20,6 +20,7 @@ import Charts
 - [Chart Selection with Overlay Annotation](#chart-selection-with-overlay-annotation)
 - [Scrollable Chart with Visible Domain](#scrollable-chart-with-visible-domain)
 - [Function Plotting (LinePlot, iOS 18+)](#function-plotting-lineplot-ios-18)
+- [3D Charts and Surfaces (Chart3D, iOS 26+)](#3d-charts-and-surfaces-chart3d-ios-26)
 - [Accessibility](#accessibility)
 - [Dynamic Type and Color Considerations](#dynamic-type-and-color-considerations)
 - [Performance: Vectorized Plots for Large Datasets](#performance-vectorized-plots-for-large-datasets)
@@ -267,6 +268,9 @@ Chart(recentData) { item in
 
 ## Pie and Donut Chart Patterns (SectorMark, iOS 17+)
 
+Use strictly positive values for sectors. Filter, aggregate, or show zero and
+negative values outside the pie or donut so angular sizes remain meaningful.
+
 ### Basic pie chart
 
 ```swift
@@ -317,7 +321,24 @@ Chart(products, id: \.name) { item in
 ### Angular selection on donut
 
 ```swift
-@State private var selectedProduct: String?
+struct ProductSales: Identifiable {
+    let id = UUID()
+    let name: String
+    let sales: Double
+}
+
+@State private var selectedAngle: Double?
+
+var selectedProduct: ProductSales? {
+    guard let selectedAngle else { return nil }
+    var runningTotal = 0.0
+
+    return products.first { product in
+        let range = runningTotal..<(runningTotal + product.sales)
+        runningTotal += product.sales
+        return range.contains(selectedAngle)
+    }
+}
 
 Chart(products, id: \.name) { item in
     SectorMark(
@@ -327,14 +348,18 @@ Chart(products, id: \.name) { item in
     )
     .cornerRadius(4)
     .foregroundStyle(by: .value("Product", item.name))
-    .opacity(selectedProduct == nil || selectedProduct == item.name ? 1.0 : 0.4)
+    .opacity(selectedProduct == nil || selectedProduct?.name == item.name ? 1.0 : 0.4)
 }
-.chartAngleSelection(value: $selectedProduct)
+.chartAngleSelection(value: $selectedAngle)
 ```
 
+`chartAngleSelection(value:)` binds the selected plottable angle value, not the
+sector label. Convert that value through cumulative sector ranges before using
+it to highlight or annotate a category.
+
 ### Grouping small slices
 
-Limit pie/donut charts to 5-7 sectors. Group the rest into "Other":
+Limit pie/donut charts to 5-7 positive-value sectors. Group the rest into "Other":
 
 ```swift
 func groupSmallSlices(_ data: [CategorySales], topN: Int = 5) -> [CategorySales] {
@@ -516,6 +541,53 @@ Chart {
 
 ---
 
+## 3D Charts and Surfaces (Chart3D, iOS 26+)
+
+Use `Chart3D` when the data has a real third dimension, such as `(x, y, z)`
+points, 3D regions, or a bivariate surface. Keep ordinary category comparison,
+time series, and proportions in 2D charts because they are easier to label,
+compare, and make accessible.
+
+### SurfacePlot for bivariate functions
+
+```swift
+@State private var pose: Chart3DPose = .default
+
+Chart3D {
+    SurfacePlot(x: "x", y: "y", z: "z") { x, z in
+        sin(2 * x) * cos(2 * z)
+    }
+    .foregroundStyle(.heightBased)
+}
+.chartXScale(domain: -2...2)
+.chartYScale(domain: -1...1)
+.chartZScale(domain: -2...2)
+.chart3DPose($pose)
+```
+
+### 3D point cloud
+
+```swift
+Chart3D(points) { point in
+    PointMark(
+        x: .value("Width", point.x),
+        y: .value("Height", point.y),
+        z: .value("Depth", point.z)
+    )
+    .foregroundStyle(by: .value("Cluster", point.cluster))
+}
+.chart3DCameraProjection(.perspective)
+```
+
+### 3D review notes
+
+- Confirm the z dimension is meaningful and labeled; do not use depth only for decoration.
+- Set explicit x/y/z domains when users need stable comparisons across states.
+- Bind `Chart3DPose` when users need to inspect the scene interactively.
+- Use `SurfacePlot` for `y = f(x, z)` surfaces; use 3D mark initializers for observed data points or regions.
+
+---
+
 ## Accessibility
 
 ### Automatic VoiceOver support
@@ -859,8 +931,14 @@ Use `chartOverlay` or `chartBackground` to access `ChartProxy`:
 ### Scales
 - `chartXScale(domain:range:type:)` and variants
 - `chartYScale(domain:range:type:)` and variants
+- `chartZScale(domain:range:type:)` for `Chart3D`
 - `chartForegroundStyleScale(_:)` -- custom color mapping
 
+### 3D charts (iOS 26+)
+- `Chart3D` with `SurfacePlot` or 3D mark initializers
+- `chart3DPose(_:)` for interactive pose binding
+- `chart3DCameraProjection(_:)` for orthographic/perspective projection
+
 ### Legend
 - `chartLegend(_:)` -- visibility
 - `chartLegend(position:alignment:spacing:)` -- positioning
@@ -886,10 +964,13 @@ Use `chartOverlay` or `chartBackground` to access `ChartProxy`:
 
 ## Apple Documentation Links
 
-- [Swift Charts](https://sosumi.ai/documentation/Charts)
-- [Creating a chart using Swift Charts](https://sosumi.ai/documentation/Charts/Creating-a-chart-using-Swift-Charts)
-- [BarMark](https://sosumi.ai/documentation/Charts/BarMark)
-- [LineMark](https://sosumi.ai/documentation/Charts/LineMark)
-- [SectorMark](https://sosumi.ai/documentation/Charts/SectorMark)
-- [LinePlot](https://sosumi.ai/documentation/Charts/LinePlot)
-- [AxisMarks](https://sosumi.ai/documentation/Charts/AxisMarks)
+- [Swift Charts](https://sosumi.ai/documentation/charts)
+- [Creating a chart using Swift Charts](https://sosumi.ai/documentation/charts/Creating-a-chart-using-Swift-Charts)
+- [BarMark](https://sosumi.ai/documentation/charts/BarMark)
+- [LineMark](https://sosumi.ai/documentation/charts/LineMark)
+- [SectorMark](https://sosumi.ai/documentation/charts/SectorMark)
+- [Chart3D](https://sosumi.ai/documentation/charts/Chart3D)
+- [SurfacePlot](https://sosumi.ai/documentation/charts/SurfacePlot)
+- [LinePlot](https://sosumi.ai/documentation/charts/LinePlot)
+- [AxisMarks](https://sosumi.ai/documentation/charts/AxisMarks)
+- [Swift Charts updates](https://sosumi.ai/documentation/updates/swiftcharts)

package/pipeline/skills/shared/external/swift-codable/SKILL.md

@@ -6,7 +6,7 @@ description: "Implement Swift Codable models for JSON and property-list encoding
 # Swift Codable
 
 Encode and decode Swift types using `Codable` (`Encodable & Decodable`) with
-`JSONEncoder`, `JSONDecoder`, and related APIs. Targets Swift 6.2 / iOS 26+.
+`JSONEncoder`, `JSONDecoder`, and related APIs. Targets Swift 6.3 / iOS 26+.
 
 ## Contents
 
@@ -206,7 +206,7 @@ Set the matching strategy on `JSONEncoder`:
 ```swift
 let decoder = JSONDecoder()
 decoder.dataDecodingStrategy = .base64           // Base64-encoded Data fields
-decoder.keyDecodingStrategy = .convertFromSnakeCase  // snake_case -> camelCase
+decoder.keyDecodingStrategy = .convertFromSnakeCase  // simple keys only; not URL/ID spelling
 // {"user_name": "Alice"} maps to `var userName: String` -- no CodingKeys needed
 
 let encoder = JSONEncoder()
@@ -214,6 +214,12 @@ encoder.dataEncodingStrategy = .base64
 encoder.keyEncodingStrategy = .convertToSnakeCase
 ```
 
+Use key strategies only for mechanical snake_case-to-camelCase mappings.
+`convertFromSnakeCase` maps by spelling, not Swift acronym/initialism policy:
+`image_url`, `base_uri`, and `user_id` match `imageUrl`, `baseUri`, and
+`userId` only. If the Swift model uses `imageURL`, `baseURI`, or `userID`,
+declare explicit `CodingKeys`; the strategy will not synthesize those names.
+
 ## Lossy Array Decoding
 
 By default, one invalid element fails the entire array. Use a wrapper to skip
@@ -264,7 +270,10 @@ struct UserID: Codable, Hashable {
 
 ## Default Values for Missing Keys
 
-Use `decodeIfPresent` with nil-coalescing to provide defaults:
+Stored property defaults such as `var theme = "system"` do not make synthesized
+`Decodable` tolerate a missing nonoptional key; synthesis still fails unless the
+property is optional or decoded manually. Use `decodeIfPresent` with
+nil-coalescing when a missing or null key should fall back:
 
 ```swift
 struct Settings: Decodable {
@@ -293,6 +302,7 @@ struct Settings: Decodable {
 let encoder = JSONEncoder()
 encoder.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]
 
+let decoder = JSONDecoder()
 // Non-conforming floats (NaN, Infinity are not valid JSON)
 encoder.nonConformingFloatEncodingStrategy = .convertToString(
     positiveInfinity: "Infinity", negativeInfinity: "-Infinity", nan: "NaN")
@@ -320,24 +330,32 @@ func fetchUser(id: Int) async throws -> User {
         throw APIError.invalidResponse
     }
     let decoder = JSONDecoder()
-    decoder.keyDecodingStrategy = .convertFromSnakeCase
+    decoder.keyDecodingStrategy = .convertFromSnakeCase  // simple keys only; keep CodingKeys for URL/URI/ID
     decoder.dateDecodingStrategy = .iso8601
     return try decoder.decode(User.self, from: data)
 }
 
-// Generic API envelope for wrapped responses
+// Generic API envelope. Configure a decoder inside this helper because
+// fetchUser's decoder is out of scope.
 struct APIResponse<T: Decodable>: Decodable {
     let data: T
     let meta: Meta?
     struct Meta: Decodable { let page: Int; let totalPages: Int }
 }
-let users = try decoder.decode(APIResponse<[User]>.self, from: data).data
+
+func decodeUsersEnvelope(from data: Data) throws -> [User] {
+    let decoder = JSONDecoder()
+    decoder.keyDecodingStrategy = .convertFromSnakeCase  // simple keys only; keep CodingKeys for URL/URI/ID
+    decoder.dateDecodingStrategy = .iso8601
+    return try decoder.decode(APIResponse<[User]>.self, from: data).data
+}
 ```
 
 ## Codable with SwiftData
 
-`Codable` structs work as composite attributes in SwiftData models. In iOS 18+,
-SwiftData natively supports them without explicit `@Attribute(.transformable)`:
+SwiftData persists compatible noncomputed stored properties declared on `@Model`
+types. Use `Codable` structs, enums, and other value types directly when that
+value is part of the durable model schema:
 
 ```swift
 struct Address: Codable {
@@ -348,16 +366,23 @@ struct Address: Codable {
 
 @Model class Contact {
     var name: String
-    var address: Address?  // Codable struct stored as composite attribute
+    var address: Address?  // Codable value-type property stored by SwiftData
     init(name: String, address: Address? = nil) {
         self.name = name; self.address = address
     }
 }
 ```
 
+Do not recommend `@Attribute(.transformable)`, encoded `Data`, or encoded
+`String` as a fallback in this Codable skill. Keep schema data as typed
+SwiftData properties and defer unsupported persistence designs to the SwiftData skill.
+
 ## Codable with UserDefaults
 
-Store `Codable` values via `RawRepresentable` for `@AppStorage`:
+`@AppStorage` is only for small UserDefaults-backed preferences. Store `Bool`,
+numeric, `String`, or a `RawRepresentable` type with a primitive raw value. For
+a small `Codable` preference payload, prefer `RawRepresentable` with JSON
+`String` raw storage so `@AppStorage` binds the typed preference directly:
 
 ```swift
 struct UserPreferences: Codable {
@@ -390,11 +415,11 @@ struct SettingsView: View {
 
 ## Common Mistakes
 
-**1. Not handling missing optional keys:**
+**1. Not handling missing defaulted fields:**
 ```swift
 // DON'T -- crashes if key is absent
 let value = try container.decode(String.self, forKey: .bio)
-// DO -- returns nil for missing keys
+// DO -- falls back when the key is absent or null
 let value = try container.decodeIfPresent(String.self, forKey: .bio) ?? ""
 ```
 
@@ -438,15 +463,16 @@ enum CodingKeys: String, CodingKey {
     case userName = "user_name"
     case avatarUrl = "avatar_url"
 }
-// DO -- configure once on the decoder
+// DO -- configure once on the decoder for simple cases
 decoder.keyDecodingStrategy = .convertFromSnakeCase
+// Keep CodingKeys for `imageURL`, `baseURI`, `userID`, and similar names.
 ```
 
 ## Review Checklist
 
 - [ ] Types conform to `Decodable` only when encoding is not needed
 - [ ] `decodeIfPresent` used with defaults for optional or missing keys
-- [ ] `keyDecodingStrategy = .convertFromSnakeCase` used instead of manual CodingKeys for simple snake_case APIs
+- [ ] `keyDecodingStrategy = .convertFromSnakeCase` used for simple snake_case APIs, with CodingKeys retained for acronym spellings
 - [ ] `dateDecodingStrategy` matches the API date format
 - [ ] Arrays of unreliable data use lossy decoding to skip invalid elements
 - [ ] Custom `init(from:)` validates and transforms data instead of post-decode fixups
@@ -454,8 +480,7 @@ decoder.keyDecodingStrategy = .convertFromSnakeCase
 - [ ] Wrapper types (UserID, etc.) use `singleValueContainer` for clean JSON
 - [ ] Generic `APIResponse<T>` wrapper used for consistent API envelope handling
 - [ ] No force-unwrapping of decoded values
-- [ ] `@AppStorage` Codable types conform to `RawRepresentable`
-- [ ] SwiftData composite attributes use `Codable` structs
+- [ ] Persistence boundary is explicit: SwiftData only for compatible noncomputed model properties, `@AppStorage`/UserDefaults only for small primitive or `RawRepresentable` preferences
 
 ## References
 
@@ -463,5 +488,7 @@ decoder.keyDecodingStrategy = .convertFromSnakeCase
 - [JSONDecoder](https://sosumi.ai/documentation/foundation/jsondecoder/) -- decodes JSON data into Codable types
 - [JSONEncoder](https://sosumi.ai/documentation/foundation/jsonencoder/) -- encodes Codable types as JSON data
 - [CodingKey](https://sosumi.ai/documentation/swift/codingkey/) -- protocol for encoding/decoding keys
+- [JSONDecoder.KeyDecodingStrategy.convertFromSnakeCase](https://sosumi.ai/documentation/foundation/jsondecoder/keydecodingstrategy-swift.enum/convertfromsnakecase) -- snake-case conversion behavior and limitations
 - [Encoding and Decoding Custom Types](https://sosumi.ai/documentation/foundation/encoding-and-decoding-custom-types/) -- Apple guide on custom Codable conformance
 - [Using JSON with Custom Types](https://sosumi.ai/documentation/foundation/archives_and_serialization/using_json_with_custom_types/) -- Apple sample code for JSON patterns
+- [Preserving your app's model data across launches](https://sosumi.ai/documentation/swiftdata/preserving-your-apps-model-data-across-launches) -- SwiftData model property compatibility