@ketecode/loom 0.1.0 → 0.2.0

package/skills/ios-platform-features/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ios-platform-features
+description: Adopts recent Apple platform APIs in an existing app without dropping older OS versions, covering the Liquid Glass design (glassEffect, GlassEffectContainer, glass button styles, UIGlassEffect, UIDesignRequiresCompatibility), the on-device Foundation Models framework with SystemLanguageModel availability, LanguageModelSession, @Generable guided generation and the Tool protocol, #available checks with real fallbacks, and layered Icon Composer app icons. Use when an iOS, iPadOS or macOS app is moving to the iOS 26 or later SDK, adding an Apple Intelligence text feature that runs on device, gating a new API behind an availability check, or replacing an AppIcon asset catalog with an .icon file.
+license: MIT
+compatibility: Any Agent Skills host. Needs Xcode 26 or later with the matching SDKs; Foundation Models features need an Apple Intelligence capable device or Mac to test on. APIs change between SDK releases, so every name must be checked against developer.apple.com for the SDK in use.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "xcodebuild"
+  kete-loom/owner: "Kete-org"
+---
+
+# iOS platform features
+
+Bring an app onto Apple's newest APIs while it keeps working on every OS version it still supports. General Swift style lives in the Swift and SwiftUI skills; this skill is about new platform surfaces and gating them.
+
+## 0. Before you start
+
+1. Read the deployment target (target, General, Minimum Deployments, or `IPHONEOS_DEPLOYMENT_TARGET`) and the Xcode and SDK version (`xcodebuild -version`, `xcodebuild -showsdks`).
+2. **Verify every API against Apple's documentation for that SDK before you write it.** Open the symbol page on developer.apple.com and read its availability line. Apple renames and deprecates these APIs between major releases (for example, the iOS 27 SDK adds `LanguageModelError`, `SystemLanguageModel.Error` and `LanguageModelSession.Error` alongside the iOS 26 `LanguageModelSession.GenerationError`). If you cannot confirm a name, say so and do not guess.
+3. Build once and run the tests before changing anything. Record warnings.
+
+## 1. Availability rules (apply to every feature below)
+
+- Gate code with `if #available(iOS 26, *) { ... } else { ... }` and types or members with `@available(iOS 26, *)`. Use the matching macOS, visionOS or watchOS versions for those targets.
+- Every gated path has a real fallback that a user on the older OS can use. Hiding a button is a fallback only if the feature is optional.
+- Keep gated code in small wrappers (one view modifier, one service type), not scattered `#available` checks.
+- Test both branches: a simulator on the newest OS and one on the oldest supported OS.
+- Raising the deployment target is a product decision. **Stop and ask the user** before doing it to avoid writing a fallback.
+
+## 2. Liquid Glass
+
+Building with the iOS 26 SDK gives standard components (navigation bars, tab bars, toolbars, sheets, buttons, sliders) the new material automatically.
+
+1. Rebuild and walk every screen on an iOS 26+ simulator. Look for custom backgrounds on bars, toolbars, split views and sheets that fight the system material, and remove them first.
+2. For custom controls, prefer the system button styles: SwiftUI `.buttonStyle(.glass)` and `.buttonStyle(.glassProminent)`; UIKit `UIButton.Configuration.glass()`, `.prominentGlass()`, `.clearGlass()`, `.prominentClearGlass()`.
+3. Only then use the effect directly: `.glassEffect()` (default `.regular` in a capsule), `.glassEffect(.regular.tint(.orange).interactive(), in: .rect(cornerRadius: 16))`. Apply it after the modifiers that set the view's appearance. UIKit uses `UIGlassEffect` in a `UIVisualEffectView`; AppKit uses `NSGlassEffectView`.
+4. Group nearby glass views in `GlassEffectContainer(spacing:)` for performance and morphing; use `glassEffectID(_:in:)` with a `@Namespace` for morph transitions and `glassEffectUnion(id:namespace:)` to merge shapes at rest.
+5. Use glass sparingly: controls and navigation, never content such as list rows or cards of text.
+6. Content scrolling under a custom bar: use `safeAreaBar(edge:...)` (SwiftUI) or `UIScrollEdgeElementContainerInteraction` (UIKit) to get the scroll edge effect.
+7. Wrap custom glass in one modifier that falls back on older OS versions:
+
+```swift
+extension View {
+    @ViewBuilder func appGlass() -> some View {
+        if #available(iOS 26, *) { self.glassEffect() }
+        else { self.background(.ultraThinMaterial, in: Capsule()) }
+    }
+}
+```
+
+8. Check legibility with Reduce Transparency, Increase Contrast and Reduce Motion on, in light and dark mode.
+9. The `UIDesignRequiresCompatibility` Info.plist key keeps the pre-Liquid Glass look only for builds made with the Xcode 26 SDKs. Apple has said builds made with the Xcode 27 SDKs ignore it, whatever the deployment target. Do not offer it as a fix on Xcode 27 or later; tell the user the redesign cannot be postponed past that SDK.
+
+## 3. Foundation Models (on-device language model)
+
+Read `references/foundation-models.md` before writing code; it has the session, guided generation and tool patterns.
+
+1. Decide whether the task fits a small on-device model: summarising, extracting fields, classifying, rewriting or tagging the user's own content. It is not a source of world knowledge or facts. **Stop and ask** if the feature needs accurate facts, long documents or heavy reasoning.
+2. Check `SystemLanguageModel.default.availability` every time before offering the feature, and handle each `.unavailable` reason: `.deviceNotEligible` (hide the feature), `.appleIntelligenceNotEnabled` (explain how to turn it on), `.modelNotReady` (try later; the model may be downloading).
+3. Prefer guided generation (`@Generable` types with `@Guide` constraints) over parsing free text.
+4. Give the model app data through a `Tool` only when it must decide what to fetch; otherwise put the data in the prompt.
+5. Handle errors: context window exceeded, guardrail violation, unsupported language or locale, and concurrent requests on one session. Use the error type your SDK documents.
+6. Keep the user in control: show generated text as a draft they can edit or discard, never act on it automatically.
+7. If the project builds with the iOS 27 SDK or later, read Apple's "Foundation Models updates" page first (it lists the `LanguageModel` protocol for other models, `PrivateCloudComputeLanguageModel`, image input, `LanguageModelSession.DynamicProfile` and the new error types); do not assume iOS 26 signatures still apply. `PrivateCloudComputeLanguageModel` and server models are not on-device: **stop and ask** before using them, and describe the feature accordingly.
+
+## 4. App icons with Icon Composer
+
+1. Open Icon Composer from Xcode (Xcode, Open Developer Tool, Icon Composer). Import layers as SVG (PNG for unsupported features), up to four groups, back to front. Leave out blur, shadow, background and the mask; Icon Composer and the system add them.
+2. Check the default, dark and mono (clear and tinted) appearances in the canvas.
+3. Add the `.icon` file to the app target and make the App Icon name in the target's General tab match the file name without extension (usually `AppIcon`).
+4. When the target has an `.icon` file, Xcode uses it instead of an `AppIcon` asset set of the same name and generates the images older OS versions show; a different icon per OS version is not supported. Check the icon on the oldest supported OS, and **ask the user** before deleting the old asset set.
+5. tvOS and visionOS targets still use asset catalogs.
+
+## 5. Verify
+
+1. Build for every platform the app supports and fix new availability warnings.
+2. Run on the newest and the oldest supported OS. Exercise each new feature and its fallback.
+3. Foundation Models: test on a real eligible device, with Apple Intelligence off, and with an unsupported language.
+4. Run the test suite. Add a test for each fallback path you can reach (for example, a fake model service behind a protocol).
+
+## Never
+
+- Never call an API without checking it on developer.apple.com for the SDK in use.
+- Never ship a Foundation Models feature without a path for every unavailable reason.
+- Never send the user's content to a server while describing the feature as on-device.
+- Never cover text-heavy content with glass or stack glass on glass.
+- Never raise the deployment target silently.
+
+## Report back
+
+```
+SDK / deployment target: <Xcode version, SDK, min OS>
+Adopted: <feature> | <files> | <availability gate> | <fallback>
+Verified on: <OS versions and devices>, tests: <command and result>
+APIs checked against docs: <list>; could not confirm: <list>
+Open questions: <deployment target, icon fallback, design decisions>
+```

package/skills/ios-platform-features/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add an on-device summary of the user's notes with Apple's Foundation Models framework, with a fallback when Apple Intelligence is off",
+    "We rebuilt with the iOS 26 SDK, how do we adopt Liquid Glass in our custom toolbar and keep iOS 17 working?",
+    "Replace our AppIcon asset catalog with an Icon Composer .icon file that has dark and tinted variants",
+    "Use @Generable guided generation to extract event details from an email on device",
+    "Wrap glassEffect and GlassEffectContainer in availability checks so the app still builds for iOS 18"
+  ],
+  "should_not_trigger": [
+    "Migrate our Swift package to the Swift 6 language mode and fix Sendable warnings",
+    "Our SwiftUI view keeps resetting its state when the parent redraws",
+    "Call the Claude API from our iOS app's backend to answer support questions",
+    "Write Swift Testing tests for our actor-based cache",
+    "Make our iOS app's icon buttons readable by VoiceOver and fix focus order"
+  ]
+}

package/skills/ios-platform-features/references/foundation-models.md

@@ -0,0 +1,90 @@
+# Foundation Models patterns (iOS 26 SDK)
+
+Signatures shown are the iOS 26 forms; newer SDKs add overloads (metadata, context options, dynamic profiles) and a separate error type. Re-check each symbol page for the SDK you build with.
+
+## Availability
+
+```swift
+import FoundationModels
+
+enum SummaryAvailability { case ready, hidden, needsAppleIntelligence, tryLater }
+
+func summaryAvailability() -> SummaryAvailability {
+    switch SystemLanguageModel.default.availability {
+    case .available: return .ready
+    case .unavailable(.deviceNotEligible): return .hidden
+    case .unavailable(.appleIntelligenceNotEnabled): return .needsAppleIntelligence
+    case .unavailable(.modelNotReady): return .tryLater
+    case .unavailable: return .hidden // future reasons: fail closed
+    }
+}
+```
+
+Re-check availability when the app returns to the foreground; it can change.
+
+## Session
+
+```swift
+let session = LanguageModelSession(instructions: """
+    You summarise the user's notes in two sentences. Use only the text given.
+    """)
+let response = try await session.respond(to: noteText)
+let summary = response.content
+```
+
+- A session keeps a transcript; reuse it for a multi-turn conversation, create a new one for unrelated requests.
+- One request at a time per session; check `session.isResponding` before sending another.
+- Call `session.prewarm(promptPrefix:)` when you know a request is coming (for example, when the sheet opens).
+- Stream into the UI with `for try await partial in session.streamResponse(to: prompt) { ... }`.
+
+## Guided generation
+
+```swift
+@Generable
+struct ExtractedEvent {
+    @Guide(description: "Short event title")
+    var title: String
+    @Guide(description: "Attendee first names", .count(0...10))
+    var attendees: [String]
+}
+
+let result = try await session.respond(to: emailText, generating: ExtractedEvent.self)
+let event = result.content
+```
+
+- The framework constrains decoding to the type, so you do not parse JSON yourself.
+- Keep types small and flat; each property and guide adds to the prompt.
+- Enums marked `@Generable` give you classification.
+
+## Tool calling
+
+```swift
+struct FindContacts: Tool {
+    let name = "findContacts"
+    let description = "Finds contacts whose name matches a query"
+
+    @Generable
+    struct Arguments {
+        @Guide(description: "Part of the contact's name")
+        let query: String
+    }
+
+    func call(arguments: Arguments) async throws -> [String] {
+        try await contactStore.names(matching: arguments.query) // your code, with its own permission checks
+    }
+}
+
+let session = LanguageModelSession(tools: [FindContacts()], instructions: "Help the user find contacts.")
+```
+
+- `Tool` requires `name`, `description`, an `Arguments` type (usually `@Generable`) and `call(arguments:) async throws -> Output`, where `Output` conforms to `PromptRepresentable` (a `String` or a `@Generable` type).
+- Tool definitions count against the context window; register only the tools a session needs.
+- A tool runs with the app's permissions. Check authorisation inside `call` and never let a tool perform a destructive action without the user confirming in the UI.
+
+## Errors (iOS 26 SDK)
+
+`LanguageModelSession.GenerationError` cases include `exceededContextWindowSize`, `guardrailViolation`, `unsupportedLanguageOrLocale`, `concurrentRequests`, `decodingFailure`, `assetsUnavailable`, `rateLimited`, `refusal` and `unsupportedGuide`. On context overflow, start a new session with a shorter summary of the conversation. On a guardrail violation or refusal, show a neutral message and let the user edit the input. The iOS 27 SDK adds `LanguageModelError` (model errors), `SystemLanguageModel.Error` (on-device model errors) and `LanguageModelSession.Error` (session errors); read their symbol pages for the case names before catching them.
+
+## Testing
+
+Put the model behind a small protocol (`protocol Summariser { func summarise(_: String) async throws -> String }`) so unit tests use a fake and UI tests can force each availability state. Evaluate real output on a device with a fixed set of sample inputs before shipping.

package/skills/jvm-sql-mappers/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: jvm-sql-mappers
+description: Writes and reviews SQL-first data access on the JVM without an ORM session, using MyBatis XML or annotation mappers with dynamic SQL and resultMaps, jOOQ's generated typesafe DSL, or Kotlin Exposed DSL and DAO tables, plus explicit transaction boundaries, HikariCP pool sizing, JDBC batch inserts and loading child rows without one query per parent. Use when a Java or Kotlin service uses MyBatis, jOOQ or Exposed rather than JPA, a mapper or query builder produces the wrong or slow SQL, ${} string substitution needs auditing for injection, bulk inserts are slow, or the connection pool times out under load.
+license: MIT
+compatibility: Any Agent Skills host. Needs the project's JDK build tool (Gradle or Maven) and its test runner; integration tests need the target database, ideally through Testcontainers.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# JVM SQL mappers: MyBatis, jOOQ, Exposed
+
+You write the SQL (or a typed DSL of it) and the library maps rows to objects. No lazy loading and no dirty checking: what you query is what runs. For JPA or Hibernate entities use the JPA skill instead.
+
+## 0. Before you start
+
+1. Identify the library and version from the build file (`org.mybatis`, `mybatis-spring-boot-starter`, `org.jooq`, `org.jetbrains.exposed`) and the database and driver.
+2. Exposed 1.0 moved packages to `org.jetbrains.exposed.v1.*` (core, jdbc, r2dbc, dao). Check which the project imports and follow the docs for that major version.
+3. Find how transactions are managed: Spring `@Transactional`, jOOQ `transaction { }`, Exposed `transaction { }`, or manual `SqlSession`.
+4. Run the existing tests once. Turn on SQL logging (MyBatis `logImpl`, jOOQ `executeLogging`, Exposed `addLogger(StdOutSqlLogger)`) while you work so you see the real statements.
+
+Read `references/examples.md` for complete mapper, DSL and batching snippets.
+
+## 1. Rules for every library
+
+1. **Bind every value.** Values go in as bind parameters: MyBatis `#{param}`, jOOQ `DSL.val`/typed conditions, Exposed column comparisons. Never build SQL by string concatenation.
+2. **Identifiers that must be dynamic** (sort column, table suffix) come from an allow-list in code, never from the request. This is the only acceptable use of MyBatis `${}` or jOOQ `DSL.field(name(...))` from input.
+3. **Select only the columns you use.** No `select *` in mappers; it breaks when columns are added and wastes I/O.
+4. **One transaction per unit of work**, started at the service layer, short, and never open across a remote call or user think time.
+5. **Paginate** with keyset (`WHERE id > :last ORDER BY id LIMIT :n`) for large or deep lists; `OFFSET` only for small pages.
+6. **Schema changes** go through migrations (Flyway or Liquibase), never `SchemaUtils.create` or `ddl` at app start in production.
+
+## 2. MyBatis
+
+- Put SQL in mapper XML (namespace = mapper interface) or annotations for one-liners. Map with explicit `<resultMap>`; turn on `mapUnderscoreToCamelCase` only if the project already relies on it.
+- Dynamic SQL: `<where>` (drops leading AND/OR), `<if test>`, `<choose>/<when>/<otherwise>`, `<set>` for partial updates, `<foreach>` for `IN` lists. An empty list in `<foreach>` produces `IN ()`: guard it with `<if test="ids != null and !ids.isEmpty()">` or return early in code.
+- Audit every `${}`: each one must be an allow-listed identifier. Replace any other with `#{}`.
+- Avoid N+1: a nested `<collection select="...">` runs one query per parent. Prefer a join with a nested `<collection>` resultMap (with `<id>` columns so rows collapse correctly), or load children in a second query with `IN (...)` and group in code.
+- Batching: open the session with `ExecutorType.BATCH` (or a separate batch `SqlSessionTemplate` in Spring), call the insert in a loop, `flushStatements()` every 500 to 1000 rows, commit once. A multi-row `<foreach>` `INSERT ... VALUES` works for moderate sizes but hits parameter limits on large ones.
+- Generated keys: `useGeneratedKeys="true" keyProperty="id"`.
+
+## 3. jOOQ
+
+- Generate code from the real schema (the jOOQ codegen plugin against a migrated database, or from Flyway scripts via the DDL database) and commit the config, not hand-written table classes.
+- Use one `DSLContext` configured with the pool's `DataSource` and the correct `SQLDialect`.
+- Fetch into records or projections: `fetchInto(Dto.class)`, `fetch(Records.mapping(Dto::new))`.
+- Nested children without N+1: `multiset(select(...).from(CHILD).where(CHILD.PARENT_ID.eq(PARENT.ID)))` mapped with `convertFrom`, or a join plus `fetchGroups`.
+- Transactions: `dsl.transaction(cfg -> { DSL.using(cfg)... })`, or Spring's transaction manager if jOOQ is wired with Spring Boot's starter. Do not mix both styles in one call path.
+- Batching: `dsl.batchInsert(records)` or `dsl.batch(query).bind(...).bind(...).execute()`; for very large loads, the Loader API (`loadInto`).
+- Plain SQL templates (`DSL.field("...")`) are an escape hatch; pass values as `{0}` bind arguments, never concatenated.
+
+## 4. Kotlin Exposed
+
+- DSL: `object Users : LongIdTable("users") { val email = varchar("email", 255).uniqueIndex() }`; query with `Users.selectAll().where { Users.email eq e }`.
+- DAO: `class User(id: EntityID<Long>) : LongEntity(id) { companion object : LongEntityClass<User>(Users) }`. DAO references are lazy: load children eagerly with `.with(User::orders)` or `load(...)` to avoid N+1.
+- Every query runs inside `transaction(db) { }`. With coroutines on JDBC, use `suspendTransaction { }` on Exposed 1.x (`newSuspendedTransaction` on 0.x, deprecated in 1.0). It takes no `CoroutineContext`, so call it inside `withContext(Dispatchers.IO) { }`; blocking JDBC must not run on `Dispatchers.Default` or the main thread. For non-blocking drivers use the `exposed-r2dbc` module.
+- Batching: `Users.batchInsert(rows) { row -> this[Users.email] = row.email }`.
+- For any of the three libraries, JDBC batches only become multi-row inserts if the driver rewrites them: add `rewriteBatchedStatements=true` to a MySQL Connector/J URL, `reWriteBatchedInserts=true` to a PostgreSQL (pgjdbc) URL.
+- Spring: use the Exposed Spring starter's transaction manager so `@Transactional` and `transaction {}` share a connection.
+
+## 5. HikariCP
+
+- Start small: `maximumPoolSize` about 10 per instance (the default) and raise it only with evidence. Total connections across all instances must stay under the database's limit minus admin headroom.
+- Set `maxLifetime` (default 30 min) a little shorter than any database, proxy or firewall connection cutoff. `keepaliveTime` (default 2 min in current releases, minimum 30 s) must be shorter than any idle cutoff; lower it only if a firewall drops idle connections sooner.
+- `connectionTimeout` (default 30 s) is how long a caller waits for a connection. Timeouts under load usually mean long transactions or leaked connections, not a small pool: set `leakDetectionThreshold` (off by default, minimum 2000 ms; for example 60000 ms) in staging to find the leak.
+- Defaults above are from the current HikariCP README; earlier releases had `keepaliveTime` off (0) by default, so check the version in use.
+
+## 6. Verify
+
+1. Integration tests run against the same database engine (Testcontainers), not H2 standing in for PostgreSQL or MySQL.
+2. For each changed query, log the generated SQL and run `EXPLAIN` on it with realistic data; confirm it uses the intended index.
+3. For N+1 fixes, assert the statement count in a test (a counting `DataSource` proxy or the library's listener), not just the result.
+4. For batching, time a load of 10,000 rows before and after.
+5. Run the full test suite.
+
+## Stop and ask the user
+
+- A dynamic identifier cannot be allow-listed because callers pass arbitrary column names.
+- A fix needs a schema change or a new index on a large production table.
+- Switching libraries (for example MyBatis to jOOQ) or major versions.
+
+## Never
+
+- Never use `${}` or string concatenation with request data.
+- Never hold a transaction or connection open across an HTTP call or message wait.
+- Never raise the pool size to hide a connection leak.
+
+## Report back
+
+```
+Library / DB: <MyBatis|jOOQ|Exposed version>, <database>
+Changed queries: <mapper or method> | <problem> | <fix> | <statements before/after>
+Injection audit: <each ${} or plain-SQL use and its status>
+Pool: <settings changed and why>
+Tests: <command> -> <result>; EXPLAIN checked for: <queries>
+```

package/skills/jvm-sql-mappers/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Our MyBatis mapper uses ${orderBy} from the request, make it injection-safe",
+    "The MyBatis nested collection select runs one query per order, fix the N+1",
+    "Load orders with their line items in one jOOQ query using multiset",
+    "Bulk inserting 50k rows with Kotlin Exposed takes minutes, speed it up with batchInsert",
+    "HikariCP 'Connection is not available, request timed out after 30000ms' under load in our jOOQ service"
+  ],
+  "should_not_trigger": [
+    "Fix LazyInitializationException on a Hibernate @OneToMany association",
+    "Our Postgres query is slow, read this EXPLAIN ANALYZE output",
+    "Add a Flyway migration for a new column in our Spring Data JPA entity",
+    "Write a Ktor route that returns JSON with kotlinx.serialization",
+    "Fix N+1 queries in our EF Core DbContext with Include"
+  ]
+}

package/skills/jvm-sql-mappers/references/examples.md

@@ -0,0 +1,129 @@
+# Examples: MyBatis, jOOQ, Exposed
+
+Each snippet shows one pattern from SKILL.md. Adapt names to the project; check the API against the docs for the library version in use.
+
+## MyBatis: dynamic search with a safe sort column
+
+```xml
+<mapper namespace="com.example.order.OrderMapper">
+  <resultMap id="orderWithLines" type="com.example.order.Order">
+    <id property="id" column="o_id"/>
+    <result property="status" column="o_status"/>
+    <collection property="lines" ofType="com.example.order.OrderLine">
+      <id property="id" column="l_id"/>
+      <result property="sku" column="l_sku"/>
+      <result property="quantity" column="l_qty"/>
+    </collection>
+  </resultMap>
+
+  <select id="search" resultMap="orderWithLines">
+    SELECT o.id o_id, o.status o_status, l.id l_id, l.sku l_sku, l.quantity l_qty
+    FROM orders o LEFT JOIN order_lines l ON l.order_id = o.id
+    <where>
+      <if test="status != null">AND o.status = #{status}</if>
+      <if test="customerIds != null and !customerIds.isEmpty()">
+        AND o.customer_id IN
+        <foreach item="cid" collection="customerIds" open="(" separator="," close=")">#{cid}</foreach>
+      </if>
+    </where>
+    ORDER BY ${sortColumn}, o.id
+  </select>
+</mapper>
+```
+
+```java
+// The only ${} input: chosen from a fixed map, never from the raw request.
+private static final Map<String, String> SORTS = Map.of("created", "o.created_at", "total", "o.total");
+String sortColumn = SORTS.getOrDefault(request.sort(), "o.created_at");
+```
+
+Joins with collections multiply rows; paginate parents first (select the page of order ids, then join lines for those ids).
+
+## MyBatis: batch insert
+
+```java
+try (SqlSession session = sqlSessionFactory.openSession(ExecutorType.BATCH)) {
+    OrderLineMapper mapper = session.getMapper(OrderLineMapper.class);
+    int n = 0;
+    for (OrderLine line : lines) {
+        mapper.insert(line);
+        if (++n % 500 == 0) session.flushStatements();
+    }
+    session.commit();
+}
+```
+
+In Spring, define a second `SqlSessionTemplate` with `ExecutorType.BATCH` and use it inside the service's `@Transactional` method.
+
+## jOOQ: parent with children in one query
+
+```java
+List<OrderDto> orders = dsl
+    .select(
+        ORDERS.ID, ORDERS.STATUS,
+        multiset(
+            select(ORDER_LINES.SKU, ORDER_LINES.QUANTITY)
+                .from(ORDER_LINES)
+                .where(ORDER_LINES.ORDER_ID.eq(ORDERS.ID))
+        ).convertFrom(r -> r.map(Records.mapping(LineDto::new))))
+    .from(ORDERS)
+    .where(ORDERS.CUSTOMER_ID.eq(customerId))
+    .orderBy(ORDERS.ID)
+    .limit(50)
+    .fetch(Records.mapping(OrderDto::new));
+```
+
+## jOOQ: transaction and batch
+
+```java
+dsl.transaction(cfg -> {
+    DSLContext tx = DSL.using(cfg);
+    tx.batchInsert(lineRecords).execute();
+    tx.update(ORDERS).set(ORDERS.STATUS, "READY").where(ORDERS.ID.eq(orderId)).execute();
+});
+```
+
+## Exposed: DSL query, eager DAO load, batch insert (1.x packages)
+
+```kotlin
+import org.jetbrains.exposed.v1.core.and
+import org.jetbrains.exposed.v1.core.dao.id.LongIdTable
+import org.jetbrains.exposed.v1.core.eq
+import org.jetbrains.exposed.v1.jdbc.transactions.transaction
+import org.jetbrains.exposed.v1.jdbc.batchInsert
+import org.jetbrains.exposed.v1.jdbc.selectAll
+
+object Orders : LongIdTable("orders") {
+    val customerId = long("customer_id").index()
+    val status = varchar("status", 20)
+}
+
+fun openOrders(customer: Long) = transaction {
+    Orders.selectAll()
+        .where { (Orders.customerId eq customer) and (Orders.status eq "OPEN") }
+        .map { it[Orders.id].value to it[Orders.status] }
+}
+
+fun saveLines(lines: List<LineInput>) = transaction {
+    OrderLines.batchInsert(lines) { line ->
+        this[OrderLines.orderId] = line.orderId
+        this[OrderLines.sku] = line.sku
+    }
+}
+```
+
+DAO eager loading: `Order.find { Orders.customerId eq id }.with(Order::lines)`.
+
+Import paths above follow the Exposed 1.0 migration guide (core table types under `v1.core`, JDBC operations under `v1.jdbc`); confirm each import in the docs for the exact version, and use the 0.x `org.jetbrains.exposed.sql.*` packages if the project has not migrated.
+
+## HikariCP (Spring Boot properties)
+
+```properties
+spring.datasource.hikari.maximum-pool-size=10
+spring.datasource.hikari.connection-timeout=30000
+spring.datasource.hikari.max-lifetime=1500000
+spring.datasource.hikari.keepalive-time=300000
+spring.datasource.hikari.leak-detection-threshold=60000
+```
+
+`max-lifetime` here assumes an infrastructure idle cutoff above 25 minutes; set it below whatever your database or proxy enforces. Leak detection is for staging and diagnosis; it logs a stack trace for connections held longer than the threshold.

package/skills/mobile-accessibility/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: mobile-accessibility
+description: Makes native iOS and Android screens usable with VoiceOver and TalkBack by fixing labels, traits and roles, grouping and reading order, focus moves after navigation, Dynamic Type and sp font scaling, 44pt and 48dp touch targets and colour contrast, across SwiftUI, UIKit, Jetpack Compose and Android Views, then proving it with Accessibility Inspector, Accessibility Scanner and automated audits in UI tests. Use when a native mobile screen must work with a screen reader, large text or switch access, an app store or customer audit flagged accessibility issues, or accessibility checks need adding to XCUITest, Espresso or Compose tests.
+license: MIT
+compatibility: Any Agent Skills host. Testing needs Xcode (Accessibility Inspector, XCUITest) or Android Studio with an emulator or device (Accessibility Scanner, Espresso or Compose UI tests).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Mobile accessibility
+
+Fix native iOS and Android UI so people using a screen reader, large text, switch control or low vision can finish every task. For web pages use the web accessibility skill; for React Native or Flutter, apply the same rules through that framework's accessibility props.
+
+## 0. Before you start
+
+1. Find the UI toolkit per screen: SwiftUI, UIKit, Jetpack Compose or Android Views. Many apps mix them.
+2. List the critical journeys (sign in, search, checkout, settings). Audit those first, not every screen.
+3. Ask the user whether a target standard applies (WCAG 2.2 AA is the usual reference for mobile, and some contracts or laws name it). Do not claim legal compliance; report findings against the criteria.
+
+## 1. Audit each screen in this order
+
+For every screen, check and record each item:
+
+1. **Every control has a name.** Icon-only buttons, images that carry meaning and custom views need a label. Decorative images are hidden from assistive tech.
+2. **Role and state are announced.** A tappable row says "button", a toggle says on/off, a selected tab says selected, a heading is a heading.
+3. **Grouping.** A card with title, price and rating is read as one element, not five swipes.
+4. **Reading and focus order** follows the visual order. After a screen change, sheet or error, focus moves to the new content.
+5. **Text scales.** At the largest accessibility text size nothing is clipped or overlapped; layouts wrap or scroll instead of truncating.
+6. **Touch targets** are at least 44 x 44 pt on iOS (Human Interface Guidelines) and 48 x 48 dp on Android (Material). Expand the hit area rather than the visible icon if needed.
+7. **Contrast** is at least 4.5:1 for body text and 3:1 for large text and essential icons or control borders (WCAG 1.4.3, 1.4.11). Never convey state by colour alone.
+8. **Motion and transparency** respect Reduce Motion and Reduce Transparency (iOS) and Remove animations (Android).
+9. **Custom gestures** (swipe to delete, long press) also have an accessible action.
+
+## 2. Fix with the platform API
+
+Use the native control first: a real `Button`/`Toggle` gets role, state and focus for free. Add modifiers only where a native control is not possible.
+
+| Need | SwiftUI | UIKit | Compose | Android Views |
+|---|---|---|---|---|
+| Name | `.accessibilityLabel("Delete")` | `accessibilityLabel` | `Modifier.semantics { contentDescription = "Delete" }` or `Icon(contentDescription=)` | `android:contentDescription` |
+| Hide decorative | `.accessibilityHidden(true)`, `Image(decorative:)` | `isAccessibilityElement = false` | `contentDescription = null` | `importantForAccessibility="no"` |
+| Role/state | `.accessibilityAddTraits(.isButton)`, `.accessibilityValue` | `accessibilityTraits`, `accessibilityValue` | `Modifier.semantics { role = Role.Button; stateDescription = "On" }`, `Modifier.toggleable` | `ViewCompat.setAccessibilityDelegate`, `stateDescription` |
+| Heading | `.accessibilityAddTraits(.isHeader)` | `.header` trait | `Modifier.semantics { heading() }` | `android:accessibilityHeading="true"` |
+| Group | `.accessibilityElement(children: .combine)` | container view as one element with a combined label | `Modifier.semantics(mergeDescendants = true) {}` or `clickable` on the row | `android:focusable="true"` on the parent, `screenReaderFocusable` |
+| Order | `.accessibilitySortPriority` | `accessibilityElements` array | `Modifier.semantics { traversalIndex = 1f; isTraversalGroup = true }` | `android:accessibilityTraversalBefore/After` |
+| Move focus | `@AccessibilityFocusState` | `UIAccessibility.post(notification: .screenChanged, argument: view)` | `Modifier.semantics { paneTitle = "..." }` on the new pane; `FocusRequester` moves input focus, which TalkBack may not follow, so check on a device | `view.sendAccessibilityEvent` or `performAccessibilityAction(ACTION_ACCESSIBILITY_FOCUS)` |
+| Announce | `AccessibilityNotification.Announcement("Saved").post()` | `UIAccessibility.post(notification: .announcement, argument:)` | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` | `android:accessibilityLiveRegion="polite"` |
+| Custom action | `.accessibilityAction(named: "Delete") {}` | `accessibilityCustomActions` | `Modifier.semantics { customActions = listOf(...) }` | `ViewCompat.addAccessibilityAction` |
+| Text scaling | `.font(.body)` text styles, `@ScaledMetric` | `UIFont.preferredFont(forTextStyle:)` + `adjustsFontForContentSizeCategory = true` | `sp` units via `MaterialTheme.typography` | `sp` for `textSize`, avoid fixed `dp` heights on text |
+| Touch target | `.frame(minWidth: 44, minHeight: 44)` + `.contentShape(Rectangle())` | override `point(inside:with:)` or larger frame | `Modifier.minimumInteractiveComponentSize()` (Material 3 does this for its components) | `minWidth`/`minHeight` 48dp or `TouchDelegate` |
+
+Label rules:
+
+- Say what it does, not what it looks like: "Delete message", not "trash can". Do not add "button" to a label; the role says it.
+- Keep labels short and put the important word first. Put extra guidance in a hint (`accessibilityHint`) only when the action is not obvious.
+- Localise labels with the rest of the strings.
+
+## 3. Verify
+
+1. **Manual screen reader pass** of each critical journey: VoiceOver on iOS (Settings, Accessibility, VoiceOver, or the Accessibility Shortcut), TalkBack on Android. Swipe through every element; activate every control; complete the task without looking.
+2. **Largest text size**: iOS Settings, Accessibility, Display and Text Size, Larger Text; Android Settings, Display, Font size (and Display size). Use Xcode's Environment Overrides or the Compose `@Preview(fontScale = 2f)` while iterating.
+3. **Inspectors**: Xcode's Accessibility Inspector (Audit tab, and inspect an element's label, traits and frame); Android's Accessibility Scanner app on a device or emulator.
+4. **Automated checks in UI tests**, so regressions fail CI:
+   - iOS 17+ XCUITest: `try app.performAccessibilityAudit()` on each critical screen; narrow with `for: [.contrast, .dynamicType, .hitRegion]` and filter known false positives in the issue handler (return `true` to ignore an issue), with a comment why.
+   - Espresso: add `androidx.test.espresso:espresso-accessibility` and call `AccessibilityChecks.enable()` in the test setup.
+   - Compose 1.8+: add `androidx.compose.ui:ui-test-junit4-accessibility`, call `composeTestRule.enableAccessibilityChecks()` on an `AndroidComposeTestRule`; checks run on actions, or call `onRoot().tryPerformAccessibilityChecks()`.
+5. Rerun the tests and the manual pass after every fix.
+
+Automated audits catch only part of the real problems (they cannot judge whether a label makes sense or a journey can be finished). A clean audit never replaces the screen reader pass.
+
+## Stop and ask the user
+
+- A fix would change the visual design (bigger targets, colours that pass contrast, text wrapping onto more lines). Show the before and after and let design decide how, not whether.
+- A custom control (chart, canvas, game view, map) has no obvious accessible equivalent; propose a text summary or alternative view first.
+- The project has no UI test target and adding one is a large change.
+
+## Never
+
+- Never hide a focusable, interactive element from assistive tech to silence an audit warning.
+- Never cap or disable Dynamic Type or font scaling (`maximumContentSizeCategory`, fixed `dp` text) to save a layout, unless the user agrees for that specific element and the content stays readable another way.
+- Never put the same label on several different controls in one screen ("Button", "Image", "More").
+- Never rely on a tooltip, colour or position alone to convey meaning.
+
+## Report back
+
+```
+Screens audited: <list>
+Issues: <id> | <screen> | <criterion, e.g. name, order, target size> | <severity: blocker/major/minor> | <fix or status>
+Verified with: <VoiceOver/TalkBack pass, largest text, Inspector/Scanner, UI test audits added (test names)>
+Open: <items needing design decisions or not fixed>
+```

package/skills/mobile-accessibility/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "VoiceOver reads our SwiftUI product card as five separate items, make it one element with a sensible label",
+    "TalkBack just says 'unlabelled button' on all the icon buttons in our Compose toolbar",
+    "At the largest Dynamic Type size our UIKit settings screen clips text, fix it so it scales",
+    "Add automated accessibility audits to our XCUITest and Espresso suites so regressions fail CI",
+    "Accessibility Scanner flags touch target too small and low contrast on our Android login screen"
+  ],
+  "should_not_trigger": [
+    "Make our React web checkout pass WCAG 2.2 AA with keyboard navigation and axe",
+    "Our Compose LazyColumn janks when scrolling, reduce recomposition",
+    "Migrate this SwiftUI screen from ObservableObject to @Observable",
+    "Write XCTest unit tests for the login view model with a fake network client",
+    "Translate the Android app strings into Arabic and support right-to-left layouts"
+  ]
+}