engsys 1.0.0

package/stacks/lang/typescript/skills/typescript-conventions/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: typescript-conventions
+description: TypeScript conventions for this repo (TS 5.x targeting ES2022, Node 22, pnpm workspaces). Use when writing or reviewing any *.ts file. Covers naming, type-system expectations, async/error handling, the pnpm-monorepo @smithy hoisting gotcha, and lib-DOM-for-fetch.
+---
+
+# TypeScript Conventions
+
+Applies to: `*.ts` across the repo's TypeScript packages. Target: TS 5.x → ES2022. Runtime: Node 22. Build: esbuild (or the project's bundler). Test: Vitest.
+
+> Naturalize: confirm the exact package paths, bundler, and test runner in `CLAUDE.md`. The defaults below assume a pnpm workspace shipping to a Node 22 runtime.
+
+## Core Intent
+
+- Respect existing architecture; extend abstractions before inventing new ones.
+- Readable, explicit solutions over clever ones.
+- Pure ES modules — never `require` / `module.exports` / CJS helpers.
+
+## Naming & Style
+
+- kebab-case filenames (`user-session.ts`, `data-service.ts`).
+- PascalCase for classes, interfaces, enums, type aliases. camelCase for everything else.
+- No `I`-prefix on interfaces.
+- Name for behavior/domain meaning, not implementation.
+
+## Type System
+
+- Avoid `any` (implicit or explicit). Prefer `unknown` + narrowing.
+- Discriminated unions for state machines and event payloads.
+- Centralize shared contracts in a `shared`/`common` package rather than duplicating across packages.
+- Use TS utility types (`Readonly`, `Partial`, `Record`, etc.) to express intent.
+
+## Async, Events, Errors
+
+- `async/await` with try/catch and structured errors.
+- Guard edge cases early to avoid deep nesting.
+- Route errors through the project's logging/telemetry utilities.
+
+## Architecture
+
+- Single-purpose modules.
+- Keep transport / domain / presentation layers decoupled.
+- Instantiate clients (cloud SDKs, DB clients, etc.) outside hot paths; inject for testability.
+
+## pnpm monorepo: known gotchas
+
+If the repo uses pnpm workspaces, two patterns repeatedly bite:
+
+### `@smithy/*` hoisting for the AWS SDK v3
+
+pnpm's virtual store (`.pnpm/`) is **not** traversed by TypeScript's module resolution. `@smithy/smithy-client` is the base class that provides `Client.send()` on every AWS SDK v3 client. Without hoisting you get:
+
+```
+Property 'send' does not exist on type 'SQSClient'
+Property 'send' does not exist on type 'SecretsManagerClient'
+```
+
+**Fix:** root `.npmrc` must contain:
+
+```
+public-hoist-pattern[]=@smithy*
+```
+
+Then `pnpm install`. (The same class of fix applies to any SDK that ships a base client via a separate hoisted package.)
+
+### `DOM` lib for fetch / Response / Headers
+
+Any handler that uses `fetch()`, `Response`, or `Headers` needs `"DOM"` in `tsconfig` `lib`:
+
+```json
+{ "compilerOptions": { "lib": ["ES2022", "DOM"] } }
+```
+
+Without it: `Property 'ok' does not exist on type 'Response'`.
+
+## Testing
+
+- Vitest. Add or update unit tests alongside changes.
+- Avoid brittle timing assertions; prefer fake timers or injected clocks.
+
+## Build / verification
+
+- `pnpm typecheck` at the root runs `tsc --noEmit` across packages.
+- `pnpm lint`, `pnpm test`, `pnpm build` work per-package via `pnpm -r`.
+- `esbuild` bundles for the deploy target; uses the `default` export condition.
+
+## Security
+
+- Validate external input with schema validators or type guards (prefer a `zod`-style schema layer in the shared package).
+- Parameterized queries for any persistence; never string-concatenate untrusted input into queries.
+- Secrets via the cloud secret store (Secrets Manager / Key Vault / Secret Manager), never env-var-in-code-comment.
+- Patch dependencies promptly; pin vulnerable transitives via `pnpm overrides` in root `package.json`.

package/stacks/platform/android/claude.fragment.md

@@ -0,0 +1,40 @@
+<!-- pack: platform/android -->
+## Mobile platform — Android
+
+This project ships an Android app (Kotlin / Jetpack Compose). The Kotlin/Android
+framework conventions live in the `lang/kotlin` skills (`kotlin-coroutines`,
+`jetpack-compose`, `android-testing`); Gary is the mobile experience architect.
+
+### Local Gradle gate (no CI for Android)
+
+Android has **no cloud CI for the app build** — the gate is a local `./gradlew`
+run. Run it before reporting any Android change complete:
+
+```
+./gradlew <!-- naturalize: :app: -->assembleDebug
+./gradlew <!-- naturalize: :app: -->testDebugUnitTest
+./gradlew <!-- naturalize: :app: -->lintDebug
+```
+
+Always use the project's `./gradlew` wrapper, never a global `gradle`.
+Instrumented tests (`connectedDebugAndroidTest`) need an emulator and are not part
+of the fast gate.
+
+The `pre-push-gradle.sh` hook (this pack) runs assemble + unit tests + lint
+automatically when Android files change on push. Install once per clone with
+`git config core.hooksPath .githooks`. **Do not bypass with `--no-verify`.** The
+hook reads `ANDROID_DIR`, `ANDROID_PATH_PREFIX`, and `GRADLE_MODULE` knobs.
+
+### MCP servers
+
+None required. `settings.fragment.json` allows read-only Gradle inspection
+(`./gradlew tasks`, `projects`, `help`, `dependencies`) and `adb devices` without
+prompting; it adds no Android MCP server.
+
+<!-- naturalize: record these Android project facts in the Project facts section:
+     - Gradle project root / ANDROID_DIR (dir containing ./gradlew)
+     - app module name (GRADLE_MODULE, e.g. :app)
+     - applicationId (e.g. com.example.app)
+     - minSdk / targetSdk / compileSdk
+     - product flavors / build variants, if any
+-->

package/stacks/platform/android/hooks/pre-push-gradle.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# pre-push hook — runs a fast Gradle gate when Android files are being pushed.
+# Prevents broken Android builds from reaching the default branch.
+#
+# Gate: assembleDebug + unit tests + lint (no emulator required).
+#
+# Install once per clone:
+#   git config core.hooksPath .githooks
+#
+# Naturalize the project facts below to match this repo:
+#   ANDROID_PATH_PREFIX  — repo-relative path that, when touched, should trigger the gate
+#   ANDROID_DIR          — directory containing ./gradlew (Gradle project root)
+#   GRADLE_MODULE        — the app module (e.g. ":app"); leave empty for a single-module root
+
+set -euo pipefail
+
+# --- Project facts (naturalize) ---------------------------------------------
+ANDROID_PATH_PREFIX="${ANDROID_PATH_PREFIX:-packages/android/}"
+ANDROID_DIR="${ANDROID_DIR:-packages/android}"
+GRADLE_MODULE="${GRADLE_MODULE:-:app}"
+# ----------------------------------------------------------------------------
+
+REMOTE="${1:-}"
+REMOTE_URL="${2:-}"
+
+ANDROID_CHANGED=0
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+    # New branch — compare against empty tree
+    if [[ "$remote_sha" == "0000000000000000000000000000000000000000" ]]; then
+        base=$(git hash-object -t tree /dev/null)
+    else
+        base="$remote_sha"
+    fi
+
+    if git diff --name-only "$base" "$local_sha" 2>/dev/null | grep -q "^${ANDROID_PATH_PREFIX}"; then
+        ANDROID_CHANGED=1
+        break
+    fi
+done
+
+if [[ "$ANDROID_CHANGED" -eq 0 ]]; then
+    exit 0
+fi
+
+# Resolve task names. With a module prefix, tasks are e.g. ":app:assembleDebug".
+ASSEMBLE_TASK="${GRADLE_MODULE:+$GRADLE_MODULE:}assembleDebug"
+TEST_TASK="${GRADLE_MODULE:+$GRADLE_MODULE:}testDebugUnitTest"
+LINT_TASK="${GRADLE_MODULE:+$GRADLE_MODULE:}lintDebug"
+
+GRADLEW="./gradlew"
+if [[ ! -x "${ANDROID_DIR}/${GRADLEW}" && ! -f "${ANDROID_DIR}/gradlew" ]]; then
+    echo "⚠️  No gradlew found in ${ANDROID_DIR} — skipping Android gate."
+    echo "    Naturalize ANDROID_DIR to the Gradle project root to enable it."
+    exit 0
+fi
+
+echo "🤖 Android files changed — running the Gradle gate (assemble + tests + lint)..."
+echo ""
+
+if ! (cd "$ANDROID_DIR" && ./gradlew "$ASSEMBLE_TASK" "$TEST_TASK" "$LINT_TASK" --console=plain) 2>&1; then
+    echo ""
+    echo "❌ Gradle gate failed. Fix the build/tests/lint before pushing."
+    echo "   Reproduce: (cd ${ANDROID_DIR} && ./gradlew ${ASSEMBLE_TASK} ${TEST_TASK} ${LINT_TASK})"
+    exit 1
+fi
+
+echo ""
+echo "✅ Android gate passed (assembleDebug + unit tests + lint)."
+exit 0

package/stacks/platform/android/settings.fragment.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(./gradlew tasks:*)",
+      "Bash(./gradlew projects:*)",
+      "Bash(./gradlew help:*)",
+      "Bash(./gradlew dependencies:*)",
+      "Bash(./gradlew :*:dependencies:*)",
+      "Bash(adb devices:*)"
+    ]
+  },
+  "mcpServers": {}
+}

package/stacks/platform/android/skills/android-build-conventions/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: android-build-conventions
+description: "Configure and verify Android Gradle builds: Kotlin DSL (build.gradle.kts), version catalogs (libs.versions.toml), build types and product flavors, R8/ProGuard shrinking and keep rules, signing configs, and the local build/verify gate (./gradlew assembleDebug, testDebugUnitTest, lintDebug). Use when editing Gradle build files, adding dependencies, setting up flavors/variants, configuring minification or signing, or running the Android build/test/lint gate before reporting a change complete."
+---
+
+# Android Build Conventions
+
+Configure, maintain, and verify Android builds with Gradle's Kotlin DSL targeting
+AGP 8.x+ and Gradle 8.x+. Use the version catalog as the single source of truth
+for dependencies, keep build logic declarative, and **always run the local gate**
+before reporting an Android change complete — Android typically has no cloud CI
+for the app build, so the local `./gradlew` run is the gate.
+
+## Contents
+
+- [Local Build / Verify Gate](#local-build--verify-gate)
+- [Kotlin DSL Conventions](#kotlin-dsl-conventions)
+- [Version Catalogs](#version-catalogs)
+- [Build Types and Product Flavors](#build-types-and-product-flavors)
+- [R8 / ProGuard](#r8--proguard)
+- [Signing](#signing)
+- [Convention Plugins](#convention-plugins)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+
+## Local Build / Verify Gate
+
+Run these before reporting any Android change complete. They are fast, local, and
+the de-facto gate (there is no cloud CI for the app build):
+
+```
+./gradlew assembleDebug        # compile + package the debug APK
+./gradlew testDebugUnitTest    # run JVM unit tests (src/test)
+./gradlew lintDebug            # Android Lint static analysis
+```
+
+Naturalize the module if the app isn't the root project (e.g.
+`./gradlew :app:assembleDebug`). The `pre-push-gradle.sh` hook in this pack runs
+this gate automatically when Android files change on push — **do not bypass it
+with `--no-verify`.**
+
+Notes:
+- Use the project's `./gradlew` wrapper, never a globally installed `gradle`.
+- Instrumented tests (`connectedDebugAndroidTest`) need an emulator/device and are
+  **not** part of the fast gate — run them on demand.
+- For a deeper check before release, add `./gradlew assembleRelease` (exercises
+  R8/minification).
+
+## Kotlin DSL Conventions
+
+Use `build.gradle.kts` (Kotlin DSL), not Groovy, for new build files.
+
+```kotlin
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)        // Compose compiler plugin (Kotlin 2.0+)
+}
+
+android {
+    namespace = "com.example.app"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "com.example.app"
+        minSdk = 26
+        targetSdk = 35
+        versionCode = 1
+        versionName = "1.0.0"
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    buildFeatures { compose = true }
+
+    kotlin { jvmToolchain(17) }                // pin the JDK toolchain
+}
+
+dependencies {
+    implementation(platform(libs.androidx.compose.bom))
+    implementation(libs.androidx.compose.material3)
+    implementation(libs.androidx.activity.compose)
+    testImplementation(libs.junit)
+    testImplementation(libs.turbine)
+    androidTestImplementation(libs.androidx.compose.ui.test.junit4)
+}
+```
+
+- Declare the Compose BOM with `platform(...)` so all Compose artifacts share one
+  version. Apply the Compose compiler plugin (`org.jetbrains.kotlin.plugin.compose`)
+  on Kotlin 2.0+.
+- Pin the JDK with `jvmToolchain(17)` (or the project's standard) for reproducible
+  builds across machines.
+- Prefer `implementation` over `api` unless the dependency is part of a module's
+  public API — it keeps the build graph fast.
+
+## Version Catalogs
+
+Keep all versions, libraries, and plugins in `gradle/libs.versions.toml`. This is
+the single source of truth; never hardcode versions in `build.gradle.kts`.
+
+```toml
+[versions]
+agp = "8.7.0"
+kotlin = "2.1.0"
+composeBom = "2025.01.00"
+coroutines = "1.9.0"
+turbine = "1.2.0"
+
+[libraries]
+androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
+androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }
+androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version = "1.9.3" }
+kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }
+turbine = { group = "app.cash.turbine", name = "turbine", version.ref = "turbine" }
+junit = { group = "junit", name = "junit", version = "4.13.2" }
+
+[plugins]
+android-application = { id = "com.android.application", version.ref = "agp" }
+kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+```
+
+- Reference libraries as `libs.androidx.compose.material3` and plugins as
+  `alias(libs.plugins.android.application)`.
+- Use `[bundles]` to group related dependencies that are always added together.
+- BOM-managed artifacts (Compose) omit a version — the BOM resolves it.
+
+## Build Types and Product Flavors
+
+`buildTypes` vary how the **same** code is built (debug vs release). `flavors`
+vary **what** is built (free vs paid, dev vs prod backend). Their product is a
+build *variant* (e.g. `freeDebug`).
+
+```kotlin
+android {
+    buildTypes {
+        debug {
+            applicationIdSuffix = ".debug"     // install alongside release
+            isDebuggable = true
+        }
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+            signingConfig = signingConfigs.getByName("release")
+        }
+    }
+
+    flavorDimensions += "environment"
+    productFlavors {
+        create("dev")  { dimension = "environment"; applicationIdSuffix = ".dev" }
+        create("prod") { dimension = "environment" }
+    }
+}
+```
+
+- Use `applicationIdSuffix` on debug/dev so multiple variants coexist on a device.
+- Keep flavor-specific code/resources in `src/<flavor>/` source sets.
+- Put environment config (base URLs, keys) in `buildConfigField` or resource
+  overlays, not in code branches.
+
+## R8 / ProGuard
+
+R8 is the default shrinker/optimizer/obfuscator for release builds (replaces
+ProGuard but reads the same `proguard-rules.pro` keep rules).
+
+- Enable for release: `isMinifyEnabled = true` and `isShrinkResources = true`.
+- Add **keep rules** for anything accessed reflectively: serialization models,
+  JNI, code referenced only by manifest/XML, libraries that need them.
+
+```proguard
+# Keep models used by kotlinx.serialization / Gson reflection.
+-keep,allowobfuscation class com.example.app.model.** { *; }
+# Keep enums used reflectively.
+-keepclassmembers enum * { public static **[] values(); public static ** valueOf(java.lang.String); }
+```
+
+- Most modern libraries ship **consumer keep rules**, so you usually need few
+  manual rules — add them only when release builds crash where debug doesn't.
+- Always test a **release** build before shipping; minification bugs don't appear
+  in `assembleDebug`.
+- Enable obfuscation mapping retention so crash reports can be de-obfuscated.
+
+## Signing
+
+- **Never commit keystores or passwords.** Inject signing credentials from
+  `local.properties`, environment variables, or a secrets manager.
+
+```kotlin
+val keystoreProps = Properties().apply {
+    val f = rootProject.file("keystore.properties")
+    if (f.exists()) load(f.inputStream())
+}
+
+android {
+    signingConfigs {
+        create("release") {
+            storeFile = keystoreProps["storeFile"]?.let { file(it as String) }
+            storePassword = keystoreProps["storePassword"] as String?
+            keyAlias = keystoreProps["keyAlias"] as String?
+            keyPassword = keystoreProps["keyPassword"] as String?
+        }
+    }
+}
+```
+
+- Add `keystore.properties` and `*.keystore`/`*.jks` to `.gitignore`.
+- Debug builds use the auto-generated debug keystore — fine for local work.
+
+## Convention Plugins
+
+For multi-module projects, extract shared build logic into convention plugins in
+`build-logic/` (composite build) rather than copy-pasting config across modules.
+This keeps module `build.gradle.kts` files small and consistent. Avoid the legacy
+top-level `allprojects {}`/`subprojects {}` blocks.
+
+## Common Mistakes
+
+1. **Hardcoded versions** in `build.gradle.kts` — use the version catalog.
+2. **Groovy DSL for new files** — use Kotlin DSL (`.kts`).
+3. **Not running the local gate** before reporting done — always
+   `assembleDebug` + `testDebugUnitTest` + `lintDebug`.
+4. **Using a system `gradle`** instead of `./gradlew`.
+5. **Committing keystores/passwords** — inject them; gitignore secrets.
+6. **Shipping without testing a release build** — R8 issues only surface there.
+7. **Missing keep rules** for reflective code — release crashes, debug fine.
+8. **`api` everywhere** — leaks the dependency graph and slows builds; default to
+   `implementation`.
+9. **Mismatched Compose compiler / Kotlin versions** — apply the Compose compiler
+   plugin matched to the Kotlin version (Kotlin 2.0+).
+10. **No JDK toolchain pin** — builds differ across machines; set `jvmToolchain`.
+
+## Review Checklist
+
+- [ ] Build files use Kotlin DSL (`.kts`)
+- [ ] All versions/libs/plugins live in `gradle/libs.versions.toml`
+- [ ] Compose BOM declared via `platform(...)`; compiler plugin matched to Kotlin
+- [ ] `release` build enables R8 (`isMinifyEnabled`, `isShrinkResources`)
+- [ ] Keep rules present for reflective/serialized types
+- [ ] Signing credentials injected, not committed; keystores gitignored
+- [ ] JDK toolchain pinned (`jvmToolchain`)
+- [ ] Local gate run: `assembleDebug` + `testDebugUnitTest` + `lintDebug`
+- [ ] A release build was assembled before shipping
+- [ ] Variants coexist on device (`applicationIdSuffix` on debug/dev)

package/stacks/platform/ios/claude.fragment.md

@@ -0,0 +1,24 @@
+<!-- pack: platform/ios -->
+## iOS platform
+
+This project ships an iOS app (Swift / SwiftUI). The Swift framework conventions live in the `lang/swift` skills (`swift-concurrency`, `swiftui-patterns`, `swift-testing`, `swiftdata`); Gary is the iOS experience architect.
+
+### Local xcodebuild gate (no CI for iOS)
+
+iOS has **no CI workflow** — the only gate is a local `xcodebuild`. Run it before reporting any iOS change complete:
+
+```
+xcodebuild -project <!-- naturalize: path/to/App.xcodeproj --> \
+  -scheme <!-- naturalize: scheme --> -configuration Debug \
+  -destination 'generic/platform=iOS Simulator' \
+  CODE_SIGNING_ALLOWED=NO build
+```
+
+The `pre-push-xcodebuild.sh` hook (this pack) runs SwiftLint + `xcodebuild build-for-testing` automatically when iOS files change. Install once per clone with `git config core.hooksPath .githooks`. **Do not bypass with `--no-verify`.**
+
+### MCP servers
+
+- **xcodebuildmcp** — drives Simulator builds/runs and log capture without manual copy/paste (see the `xcodebuildmcp-simulator-logs` skill). Configure `XCODEBUILDMCP_PROJECT_PATH`, `_SCHEME`, `_SIMULATOR_ID`, and `_BUNDLE_ID` in `settings.local.json`.
+- **sentry** — runtime crash/error triage for the shipped app.
+
+<!-- naturalize: record the iOS project path, scheme, bundle id, and simulator UDID in the Project facts section. -->

package/stacks/platform/ios/hooks/pre-push-xcodebuild.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# pre-push hook — runs SwiftLint + xcodebuild when iOS files are being pushed.
+# Prevents broken iOS builds from reaching CI / the default branch.
+#
+# Install once per clone:
+#   git config core.hooksPath .githooks
+#
+# Naturalize the three project facts below to match this repo:
+#   IOS_PATH_PREFIX  — repo-relative path that, when touched, should trigger a build
+#   PROJECT          — path to the .xcodeproj (or use -workspace + WORKSPACE)
+#   SCHEME           — the build scheme
+#   LINT_DIR         — directory to run swiftlint from (so .swiftlint.yml resolves)
+
+set -euo pipefail
+
+# --- Project facts (naturalize) ---------------------------------------------
+IOS_PATH_PREFIX="packages/ios/"
+PROJECT="packages/ios/App/App.xcodeproj"
+SCHEME="App"
+LINT_DIR="packages/ios/App"
+# ----------------------------------------------------------------------------
+
+REMOTE="${1:-}"
+REMOTE_URL="${2:-}"
+
+IOS_CHANGED=0
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+    # New branch — compare against empty tree
+    if [[ "$remote_sha" == "0000000000000000000000000000000000000000" ]]; then
+        base=$(git hash-object -t tree /dev/null)
+    else
+        base="$remote_sha"
+    fi
+
+    if git diff --name-only "$base" "$local_sha" 2>/dev/null | grep -q "^${IOS_PATH_PREFIX}"; then
+        IOS_CHANGED=1
+        break
+    fi
+done
+
+if [[ "$IOS_CHANGED" -eq 0 ]]; then
+    exit 0
+fi
+
+echo "📱 iOS files changed — running SwiftLint before push..."
+echo ""
+
+if command -v swiftlint &>/dev/null; then
+    # Run from the iOS project dir so .swiftlint.yml is resolved correctly
+    # and its included/excluded paths are respected.
+    if ! (cd "$LINT_DIR" && swiftlint lint --quiet --reporter emoji) 2>&1; then
+        echo ""
+        echo "❌ SwiftLint failed. Fix the violations before pushing."
+        exit 1
+    fi
+    echo "✅ SwiftLint passed."
+else
+    echo "⚠️  swiftlint not found — skipping lint (brew install swiftlint to enable)."
+fi
+
+echo ""
+echo "🔨 Running xcodebuild build-for-testing..."
+echo ""
+
+if ! xcodebuild build-for-testing \
+    -project "$PROJECT" \
+    -scheme "$SCHEME" \
+    -destination "generic/platform=iOS Simulator" \
+    -configuration Debug \
+    CODE_SIGNING_ALLOWED=NO \
+    ASSETCATALOG_COMPILER_SKIP_APP_STORE_DEPLOYMENT=YES \
+    -quiet 2>&1; then
+    echo ""
+    echo "❌ xcodebuild build-for-testing failed. Fix the build before pushing."
+    echo "   Run with more detail: xcodebuild build-for-testing -project $PROJECT -scheme $SCHEME -destination 'generic/platform=iOS Simulator' -configuration Debug CODE_SIGNING_ALLOWED=NO"
+    exit 1
+fi
+
+echo ""
+echo "✅ iOS build (including tests) passed."
+exit 0

package/stacks/platform/ios/settings.fragment.json

@@ -0,0 +1,21 @@
+{
+  "mcpServers": {
+    "xcodebuildmcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "xcodebuildmcp@latest", "mcp"],
+      "env": {
+        "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,logging",
+        "XCODEBUILDMCP_PROJECT_PATH": "<naturalize: path/to/App.xcodeproj>",
+        "XCODEBUILDMCP_SCHEME": "<naturalize: scheme>",
+        "XCODEBUILDMCP_PLATFORM": "iOS Simulator",
+        "XCODEBUILDMCP_SIMULATOR_ID": "<naturalize: simulator UDID>",
+        "XCODEBUILDMCP_BUNDLE_ID": "<naturalize: bundle id>"
+      }
+    },
+    "sentry": {
+      "type": "http",
+      "url": "https://mcp.sentry.dev/mcp"
+    }
+  }
+}

package/stacks/platform/ios/skills/xcodebuildmcp-simulator-logs/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: xcodebuildmcp-simulator-logs
+description: Use XcodeBuildMCP to run iOS simulator workflows and capture logs without manual copy/paste. Use when asked to build or run the iOS app in Simulator, inspect session defaults, start or stop simulator log capture, collect app logs for debugging, or troubleshoot StoreKit and runtime issues from simulator output.
+---
+
+# XcodeBuildMCP Simulator Logs
+
+Manage simulator runs and capture logs directly through the XcodeBuildMCP server. The user does not need to paste console output by hand.
+
+> Requires the `xcodebuildmcp` MCP server (configured in `.mcp.json`). It will prompt for approval on first use this session.
+
+## When to Use This Skill
+
+- The user wants simulator logs captured or analyzed.
+- The user asks to run or verify the iOS app in Simulator.
+- The user wants ongoing debugging without copy/pasting log output.
+- The user is troubleshooting StoreKit, auth, crash, or runtime behavior in Simulator.
+
+## Core Rules
+
+1. Before the first simulator build, run, or test call in a session, call `session_show_defaults`.
+2. If defaults are missing or wrong, discover projects and schemes first, then proceed with simulator workflows.
+3. Do **not** call `boot_sim` or `open_sim` as prerequisites for `build_run_sim` — `build_run_sim` handles boot and opening automatically.
+4. For ongoing logs, call `start_sim_log_cap` and keep the returned `logSessionId` for later retrieval.
+5. To read captured output, call `stop_sim_log_cap` with the `logSessionId`, then immediately start a new capture if continuous monitoring is needed.
+
+## Workflow: Connect to Simulator Log Stream
+
+1. `session_show_defaults` — verify active project/workspace, scheme, simulator.
+2. `start_sim_log_cap` with `subsystemFilter: app` unless broader logs are needed.
+3. Ask the user to reproduce the issue.
+4. `stop_sim_log_cap` to retrieve logs.
+5. Parse and summarize findings.
+6. If debugging continues, start a new capture immediately and keep monitoring.
+
+## Workflow: Build, Run, and Capture
+
+1. `session_show_defaults`.
+2. If defaults are valid, `build_run_sim`.
+3. Start simulator log capture.
+4. Reproduce the target scenario.
+5. Stop capture and analyze logs.
+
+## Suggested Filters
+
+- `app` — primary app and relevant runtime logs.
+- `all` — broad capture for deep investigations.
+- `swiftui` — UI lifecycle or rendering issues.
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Action |
+|---|---|---|
+| No logs captured | Capture not started or wrong filter | Start capture again with `subsystemFilter: app` or `all` |
+| `build_run_sim` fails immediately | Missing or wrong session defaults | Run `session_show_defaults`, then set/correct defaults |
+| Logs too noisy | Filter too broad | Use `subsystemFilter: app` |
+| Need continuous monitoring | Capture ended after stop | Restart capture immediately after each stop |
+
+## Notes
+
+- Session defaults reduce repeated arguments and keep simulator workflows deterministic.
+- Capture/stop cycles are the practical way to maintain ongoing visibility during iterative debugging.
+
+## Repository Scripts (if the project ships them)
+
+Some projects wrap the capture/stop cycle in helper scripts so the loop is one command. If present, check `CLAUDE.md` / `scripts/` for names like:
+
+- a `sim-log-capture` script — start, stop, pull, status, clear.
+- a topic-focused pull-and-restart script (e.g. StoreKit logs).
+
+### Recommended Usage
+
+1. Start continuous capture (`start_sim_log_cap`, or the project's capture script).
+2. Reproduce the issue in Simulator.
+3. Pull + restart capture.
+4. Inspect extracted logs (projects commonly write them under `tmp/xcodebuildmcp/`).