@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/app-dev/ios-foundation/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: ios-foundation
+description: "Set up and prove an Expo / React Native native iOS workspace from a clean checkout to a manual Login smoke on an owned iOS Simulator: isolated worktree and private caches, Xcode/runtime/CocoaPods preflight, frozen install with `pod install --deployment`, platform-scoped prebuild, an ad-hoc-signed Debug simulator build, a private simulator by exact UDID, Metro on a free port, a disposable PostgreSQL backend with owned cleanup, and the evidence record (setup proof only; feature work reports the smoke result). Use for 'set up iOS', 'build the iOS app', 'run the app on the iOS simulator', 'add iOS to the React Native app', 'prove the iOS build', or when a pod install, xcodebuild, simulator boot, Metro connection or Keychain session fails. NOT for Android (android-foundation), signing, TestFlight or App Store release, or general workflow YAML (github-actions)."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# iOS foundation
+
+Take a native Expo / React Native iOS workspace from a fresh checkout to a passing manual
+Login smoke on a simulator this run owns, then record the evidence. Use the repo's existing
+build script, native project, device harness and code-reading helper. This is a development
+foundation: not a signed release, not physical-device QA, and not iOS feature parity.
+
+Pick the mode first:
+
+- **Setup proof:** a new workspace, a toolchain, Pod, native or harness change, or a broken
+  build-to-simulator path. Run every stage and write the [evidence record](#evidence-record).
+- **Feature work:** proving a product change on the simulator in a workspace already set
+  up. Follow [Feature work](#feature-work) and report only the smoke result.
+
+## Routing
+
+| Step | Read |
+| --- | --- |
+| Shell snippets for every stage below | [references/setup.md](references/setup.md) |
+| Proving a product change on the simulator | [Feature work](#feature-work) |
+| A stage failed | [Triage](#triage) |
+| Writing up setup proof | [Evidence record](#evidence-record) |
+
+## Rules
+
+- Work in a dedicated worktree on a new branch from `origin/main`. Never overwrite or reuse
+  another checkout, and never symlink another worktree's `node_modules`, `Pods` or
+  DerivedData.
+- Tool shells keep no variables, functions or traps between calls. Write the environment
+  to `.cache/ios-env.sh` once and source it at the start of every command. Run the
+  disposable database and backend as one long-running command so its cleanup trap holds.
+- Keep every cache private to the worktree under `.cache/`: pnpm store and cache, npm,
+  `TMPDIR`, CocoaPods cache and home, DerivedData. Keep them between runs. No routine
+  `pod update`, `expo prebuild --clean`, reinstall or DerivedData deletion.
+- Read toolchain versions from the repo: the root `packageManager` and `engines`, the
+  Podfile and `Podfile.lock`, the iOS deployment target, and CONTRIBUTING. The repo is the
+  source of truth, not this skill.
+- Check that full Xcode is selected, its license is accepted, and a matching iOS Simulator
+  **runtime** is installed (`xcrun simctl list runtimes`). The SDK alone may give no
+  eligible simulator destination. If the runtime is missing, stop: installing it changes
+  shared CoreSimulator state and needs the workstation owner's permission. Never let a
+  build download it implicitly.
+- Install with `--frozen-lockfile` and `pod install --deployment`, which refuses Podfile or
+  lock changes. Plain `pod install` is only for a reviewed native change that writes a new
+  `Podfile.lock`. Open the `.xcworkspace`, not the `.xcodeproj`.
+- Native source is tracked. Regenerate only for a reviewed config or dependency change, and
+  only with `expo prebuild --platform ios`. Platformless prebuild can rewrite the Android
+  project. Review the diff to the app config, package manifest and `ios/`.
+- Keep the Podfile's reviewed download routing (for example React Native's
+  `ENTERPRISE_REPOSITORY`) after prebuild. Keep TLS verification on. Report a failed
+  download; never silently change dependency versions or global tool config. An Android
+  Maven proxy does not route CocoaPods, Git, React Native prebuilt archives or Apple
+  downloads.
+- Build Debug for a generic iOS Simulator destination with **ad-hoc signing**
+  (`CODE_SIGN_IDENTITY=-`, `CODE_SIGNING_ALLOWED=YES`) and private DerivedData. Never use
+  `CODE_SIGNING_ALLOWED=NO`: SecureStore needs a signing context for Keychain, and an
+  unsigned build fails at its first authenticated request.
+- A debug app needs Metro. A successful export or `xcodebuild` does not prove Login works.
+  Only the simulator smoke does.
+
+## Stages
+
+Run them in this order. Stop at the first failure and triage it.
+
+1. **Checkout and environment.** Add the worktree and export the private cache paths,
+   `CP_CACHE_DIR`, `CP_HOME_DIR` and the DerivedData path. Print `xcode-select -p`,
+   `xcodebuild -version`, `xcodebuild -showsdks`, `xcrun simctl list runtimes` and
+   `devicetypes`, and the node, pnpm, ruby and pod versions. Check that `pod --version`
+   matches the `COCOAPODS:` line in `Podfile.lock`. Read the repo's build script
+   and device harness for the names they expect: the scheme, the `.app` output path, the
+   bundle identifier, the database variables and the database-name prefix the harness
+   accepts.
+2. **Install.** Frozen pnpm install, then `pod install --deployment` in the iOS directory.
+3. **Runtime.** Confirm an installed runtime matches the Xcode SDK. If it does not, stop
+   and ask the workstation owner. With permission, `xcodebuild -downloadPlatform iOS`
+   (multi-GB). If `simctl list runtimes` still does not show it, import the exported image
+   with `xcodebuild -importPlatform <absolute .dmg>`. Never remove a shared runtime.
+4. **Check and build.** Run the app's unit tests, typecheck, any build-script tests,
+   `expo export --platform ios` with a placeholder `EXPO_PUBLIC_API_URL`, then the repo's iOS
+   build script (or the `xcodebuild` command in the reference) with `-jobs 2`. Keep the log and confirm the `.app` exists.
+5. **Owned simulator.** Pick an installed runtime and a compatible device type, then
+   `simctl create` a new simulator and keep the exact returned UDID. Boot it, wait with
+   `bootstatus -b`, and install the `.app`. Never use `booted` or pick an existing simulator.
+6. **Disposable backend.** In its own background shell, one command registers cleanup,
+   starts `postgres` with `--cidfile` on a random loopback port, waits for `pg_isready`,
+   seeds through the repo's device harness with a database named by its accepted prefix,
+   writes the connection to `.cache/ios-db-env.sh` for the code helper, and runs the
+   backend on its reserved port as a child it `wait`s on. Stopping the command stops the
+   backend and removes the container.
+7. **Metro and launch.** Use a free port; never stop another worker's Metro to free 8081.
+   In its own background shell, start Metro with `--localhost --port <port>` and
+   `EXPO_PUBLIC_API_URL=http://127.0.0.1:<backend-port>`. The simulator shares the Mac's
+   loopback, so use `127.0.0.1`, not Android's `10.0.2.2`. Set `RCT_jsLocation` on the owned
+   UDID only, then launch the bundle identifier. Do not use `expo run:ios` or the repo's
+   interactive `dev:ios` command: they may pick a shared simulator.
+8. **Manual Login smoke.** Send the authentication code to the fixture user's email, read
+   the code from the disposable database with the repo's helper, and enter it. Then run
+   the checks the repo's foundation journey lists (for example store or organization
+   switching without leaked context), sign out, terminate and relaunch (it must stay at
+   Login), and restart while signed in (the session must revalidate online). Do not submit
+   live payments.
+
+## Owned-resource cleanup
+
+- Clean up only what this run started: the simulator by its exact UDID
+  (`simctl shutdown`, then `simctl delete`), the container by the ID in its CID file, and
+  the backend and Metro by stopping their own commands.
+- Never use `simctl erase all`, `simctl shutdown all`, `killall Simulator`, broad `pkill`,
+  or `docker system prune`.
+- Give every Docker startup, readiness and cleanup command a 30-second limit. Treat exit
+  124 (timeout) as a terminal failure, not as "not ready yet". Retry with a new owned
+  container, never an application database.
+- Preserve the stage's original non-zero exit status even when cleanup succeeds.
+- After a `SIGKILL` or a host crash, the trap cannot run. Remove only this run's recorded
+  container ID and simulator UDID by hand, and keep the failure logs.
+- Point the database URL only at the disposable loopback container. Never at development,
+  production or another worker's database.
+- SecureStore uses the iOS Keychain. Entries can survive uninstall and reinstall with the
+  same bundle identifier, so uninstall is not sign-out. Use a newly created simulator for
+  clean-state proof.
+- Keep private dependency and build caches. Expo may rewrite `tsconfig.json` or
+  `expo-env.d.ts` while it runs; inspect and restore those changes before you commit.
+  Never commit the machine-specific `.xcode.env.local` or a loopback mirror URL.
+
+## Triage
+
+Name the earliest stage that failed:
+
+| Stage | Typical signal |
+| --- | --- |
+| Prerequisites | Xcode not selected or license not accepted, no runtime matching the SDK |
+| Install | lockfile drift, `pod install --deployment` refuses a Podfile/lock change, Ruby/CocoaPods mismatch |
+| Network | CocoaPods, Git or React Native archive download / TLS errors: fix routing, not code |
+| Export / build | Metro bundling error, `xcodebuild` compile, signing or "no eligible destination" error |
+| Simulator | `simctl create` rejects the runtime/device-type pair, `bootstatus` never completes, install fails |
+| App to Metro | red box, "No script URL provided", wrong `RCT_jsLocation` port |
+| Backend / Login | backend log errors, verification code not found in the database |
+| Keychain / session | session lost or kept unexpectedly: check ad-hoc signing and a fresh simulator |
+| Product assertion | a screen or state mismatch with a screenshot |
+
+Preserve the failure evidence. Do not repeatedly Send, Verify or Charge to turn an
+incomplete attempt into a passing screenshot. One passing run does not prove the build is
+reliable.
+
+## Feature work
+
+- Reuse the workspace's caches, Pods and DerivedData. Rerun a setup stage only when the
+  change touches what it proves (toolchain, Pods, native code, harness).
+- Build and run the smoke checks the change affects once per candidate HEAD. Rerun only
+  after a correction that affects them, or for a specific unresolved defect or uncertainty
+  that could change the delivery decision.
+- Report the source SHA, each smoke check run and its outcome or the failing stage, and the
+  cleanup result. Nothing else: no version inventory, screenshots, copied logs or earlier
+  attempts.
+- Integrated device acceptance (iPad, VoiceOver, physical devices, signing, a release device
+  campaign) runs at the release or campaign gate the spec or repo assigns it. Do not
+  recreate it per feature. Record it once, as pending, in its owning issue, never as
+  passed.
+
+## Evidence record
+
+For setup proof only. Record:
+
+- Source SHA, host OS and architecture, and the Xcode, iOS SDK, CocoaPods, Ruby, node and
+  pnpm versions.
+- The simulator runtime, device type and exact UDID (a run identifier, not a shared
+  resource), and the bundle identifier.
+- The exit status of pod install, tests, typecheck, export and the native build.
+- Each manual smoke check and its outcome.
+- The cleanup results: simulator deleted, container removed, backend and Metro stopped.
+- Earlier failed or incomplete attempts. A later pass does not erase them.
+
+State what the run does not prove: iPad layout (test an owned iPad simulator as a separate
+run; `supportsTablet` is not proof), accessibility (VoiceOver), physical devices and their
+network/TLS/signing path, auto-lock, payment recovery and browser handoffs, signing,
+TestFlight/App Store, production icons, privacy declarations and export compliance.
+Compilation is not Login evidence. Publish only sanitized evidence: no authentication codes,
+session cookies, verification rows, customer data or raw payment payloads.

package/skills/app-dev/ios-foundation/references/setup.md

@@ -0,0 +1,243 @@
+# iOS foundation: shell snippets
+
+Replace each `<placeholder>` with the repo's real value. Tool shells do not keep variables,
+functions or traps between calls: step 1 writes `.cache/ios-env.sh`, which also `cd`s into
+the worktree, and every later block starts by sourcing it by absolute path. The backend
+(step 6) and Metro (step 7) each run as one long-running command in its own background shell.
+
+## 1. Checkout and environment
+
+```bash
+set -euo pipefail
+git fetch origin main
+git worktree add -b <new-branch> ../<repo>-ios-setup origin/main
+cd ../<repo>-ios-setup
+git rev-parse HEAD
+mkdir -p .cache
+{ echo 'set -euo pipefail'; printf 'cd %q\n' "$PWD"; } > .cache/ios-env.sh
+cat >> .cache/ios-env.sh <<'ENV'
+
+# Repo-specific names, read from the repo's app config, build script and device harness.
+export APP_FILTER=<native-workspace-package>          # pnpm --filter target
+export IOS_DIR=<path/to/ios>                          # holds the Podfile and .xcworkspace
+export IOS_BUNDLE_ID=<ios-bundle-identifier>
+export IOS_APP_NAME=<Scheme>                          # the .app the build script produces
+export DB_NAME_PREFIX=<db-prefix-the-harness-accepts> # the harness rejects other names
+export DB_URL_VAR=<harness-admin-url-variable>        # e.g. SHARD_ADMIN_URL
+export DB_NAME_VAR=<harness-db-name-variable>         # e.g. SHARD_DB_NAME
+
+# Private caches.
+export PNPM_CONFIG_STORE_DIR="$PWD/.cache/pnpm-store"
+export PNPM_CONFIG_CACHE_DIR="$PWD/.cache/pnpm"
+export npm_config_cache="$PWD/.cache/npm"
+export TMPDIR="$PWD/.cache/tmp"
+export CP_CACHE_DIR="$PWD/.cache/cocoapods"
+export CP_HOME_DIR="$PWD/.cache/cocoapods-home"
+export IOS_DERIVED_DATA_PATH="$PWD/.cache/ios-derived-data"
+export IOS_APP="$IOS_DERIVED_DATA_PATH/Build/Products/Debug-iphonesimulator/$IOS_APP_NAME.app"
+
+# Run identifiers: free ports only; never stop another worker's service to free one.
+export IOS_BACKEND_PORT=<free-port>
+export IOS_METRO_PORT=<free-port>
+ENV
+source .cache/ios-env.sh
+mkdir -p "$TMPDIR" "$npm_config_cache" "$CP_CACHE_DIR" "$CP_HOME_DIR" .cache/logs
+
+xcode-select -p
+xcodebuild -version
+xcodebuild -showsdks
+xcrun simctl list runtimes
+xcrun simctl list devicetypes
+node --version; pnpm --version; ruby --version; pod --version
+grep '^COCOAPODS:' "$IOS_DIR/Podfile.lock"   # must match pod --version
+```
+
+`xcode-select -p` must point into `Xcode.app`, not CommandLineTools. The workstation owner
+selects Xcode and accepts its license; do not run `sudo xcodebuild -license` yourself.
+
+## 2. Install
+
+```bash
+source <worktree>/.cache/ios-env.sh
+pnpm install --frozen-lockfile
+(cd "$IOS_DIR" && pod install --deployment)
+```
+
+Only for a reviewed native config or dependency change, regenerate iOS alone and review
+the diff before installing pods without `--deployment`:
+
+```bash
+source <worktree>/.cache/ios-env.sh
+pnpm --filter "$APP_FILTER" exec expo prebuild \
+  --platform ios --no-install --skip-dependency-update react,react-native
+git diff -- <app-config> <app-package.json> "$IOS_DIR"
+(cd "$IOS_DIR" && pod install)
+```
+
+## 3. Runtime (only with the workstation owner's permission)
+
+```bash
+source <worktree>/.cache/ios-env.sh
+xcodebuild -downloadPlatform iOS -buildVersion <sdk-version> \
+  -architectureVariant arm64 -exportPath "$PWD/.cache/ios-runtimes"
+xcrun simctl list runtimes   # must list the runtime as available
+# Only if it is not listed: import the exported image (installs shared CoreSimulator state).
+xcodebuild -importPlatform "$PWD/.cache/ios-runtimes/<exported>.dmg"
+```
+
+## 4. Check and build
+
+```bash
+source <worktree>/.cache/ios-env.sh
+pnpm --filter "$APP_FILTER" test
+pnpm --filter "$APP_FILTER" typecheck
+node --test <path/to/build-script.test.mjs>   # if the repo tests its build script
+EXPO_PUBLIC_API_URL=https://app.invalid \
+  pnpm --filter "$APP_FILTER" exec expo export --platform ios
+<ios-build-command, e.g. pnpm build:ios> -jobs 2 2>&1 | tee .cache/logs/xcodebuild.log
+test -d "$IOS_APP"
+```
+
+`app.invalid` is an unreachable origin for bundling only. The repo's build script should run
+`xcodebuild` on the `.xcworkspace` with its scheme, `-configuration Debug`,
+`-sdk iphonesimulator`, `-destination 'generic/platform=iOS Simulator'`, `-derivedDataPath "$IOS_DERIVED_DATA_PATH"`,
+`CODE_SIGN_IDENTITY=-` and `CODE_SIGNING_ALLOWED=YES`. If the repo has no build script,
+run that `xcodebuild` command directly. Pass extra Xcode diagnostic arguments after the
+command; never override the SDK or signing.
+
+## 5. Owned simulator
+
+Pick the runtime and device type from the `simctl list` output in step 1.
+
+```bash
+source <worktree>/.cache/ios-env.sh
+IOS_RUNTIME=com.apple.CoreSimulator.SimRuntime.iOS-<x-y>
+IOS_DEVICE_TYPE=com.apple.CoreSimulator.SimDeviceType.<iPhone-model>
+IOS_SIMULATOR_UDID="$(xcrun simctl create "<repo>-ios-$(date +%s)" "$IOS_DEVICE_TYPE" "$IOS_RUNTIME")"
+printf 'export IOS_SIMULATOR_UDID=%q\n' "$IOS_SIMULATOR_UDID" >> .cache/ios-env.sh
+xcrun simctl boot "$IOS_SIMULATOR_UDID"
+xcrun simctl bootstatus "$IOS_SIMULATOR_UDID" -b
+open -a Simulator
+xcrun simctl install "$IOS_SIMULATOR_UDID" "$IOS_APP"
+```
+
+## 6. Disposable backend: one command
+
+In its own background shell. Cleanup is registered before Docker creates anything, every
+Docker command has a 30-second limit, and stopping the command (TERM or Ctrl-C) stops the
+backend and removes the container. The backend runs as a background child that the shell
+`wait`s on, so a signal runs the trap at once instead of after the backend exits.
+
+```bash
+source <worktree>/.cache/ios-env.sh
+umask 077
+RUN_DIR="$(mktemp -d "$PWD/.cache/tmp/ios-db.XXXXXX")"
+DB_ENV="$PWD/.cache/ios-db-env.sh"
+BACKEND_PID=
+bounded() {
+  node --input-type=module -e '
+    import { spawnSync } from "node:child_process";
+    const [command, ...args] = process.argv.slice(1);
+    const result = spawnSync(command, args, { stdio: "inherit", timeout: 30000 });
+    if (result.error) console.error(result.error.message);
+    process.exit(result.error?.code === "ETIMEDOUT" ? 124 : (result.status ?? 1));
+  ' -- "$@"
+}
+cleanup() {
+  status=$?
+  trap - EXIT
+  cleanup_status=0
+  if test -n "$BACKEND_PID" && kill -TERM "$BACKEND_PID" 2>/dev/null; then
+    for _ in 1 2 3 4 5 6 7 8 9 10; do kill -0 "$BACKEND_PID" 2>/dev/null || break; sleep 1; done
+    if kill -0 "$BACKEND_PID" 2>/dev/null; then kill -KILL "$BACKEND_PID"; cleanup_status=1; fi
+    wait "$BACKEND_PID" 2>/dev/null || true
+  fi
+  if test -s "$RUN_DIR/postgres.cid"; then
+    bounded docker rm --force "$(< "$RUN_DIR/postgres.cid")" || cleanup_status=$?
+  fi
+  rm -f "$DB_ENV"
+  echo "original_stage_exit=$status cleanup_exit=$cleanup_status"
+  test "$status" -ne 0 || status=$cleanup_status
+  exit "$status"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM
+bounded docker run --detach --cidfile "$RUN_DIR/postgres.cid" \
+  --publish 127.0.0.1::5432 --env POSTGRES_USER=postgres \
+  --env POSTGRES_PASSWORD=postgres --env POSTGRES_DB=postgres postgres:<version>
+CID="$(< "$RUN_DIR/postgres.cid")"
+DB_PORT="$(bounded docker port "$CID" 5432/tcp | awk -F: '{print $NF}')"
+ready=
+for _ in $(seq 1 30); do
+  if bounded docker exec "$CID" pg_isready -U postgres; then ready=1; break
+  else attempt_status=$?; test "$attempt_status" -ne 124 || exit 124; fi
+  sleep 1
+done
+test -n "$ready"
+export "$DB_URL_VAR=postgresql://postgres:postgres@127.0.0.1:$DB_PORT/postgres"
+export "$DB_NAME_VAR=${DB_NAME_PREFIX}ios_$(date +%s)"
+export DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:$DB_PORT/${!DB_NAME_VAR}"
+export TEST_DATABASE_URL="$DATABASE_URL"
+printf 'export %s=%q\n' "$DB_URL_VAR" "${!DB_URL_VAR}" "$DB_NAME_VAR" "${!DB_NAME_VAR}" \
+  DATABASE_URL "$DATABASE_URL" TEST_DATABASE_URL "$DATABASE_URL" > "$DB_ENV"
+node <path/to/device-harness.mjs> init > "$RUN_DIR/seed.log"
+# Backend env: loopback host, the reserved port, a disposable auth secret, and whatever
+# flag the repo uses to capture verification codes in the database.
+export HOST=127.0.0.1 PORT="$IOS_BACKEND_PORT" NODE_ENV=development
+<backend-env-exports>
+node <path/to/backend-server.js> > .cache/logs/backend.log 2>&1 &
+BACKEND_PID=$!
+wait "$BACKEND_PID"
+```
+
+Read the fixture user's email from the harness output or its fixture table. Never point
+these variables at development, production or another worker's database.
+
+## 7. Metro and launch
+
+In its own background shell:
+
+```bash
+source <worktree>/.cache/ios-env.sh
+EXPO_PUBLIC_API_URL="http://127.0.0.1:$IOS_BACKEND_PORT" \
+  pnpm --filter "$APP_FILTER" exec expo start --localhost --port "$IOS_METRO_PORT" \
+  > .cache/logs/metro.log 2>&1
+```
+
+Then point only the owned simulator at that Metro port and launch:
+
+```bash
+source <worktree>/.cache/ios-env.sh
+xcrun simctl spawn "$IOS_SIMULATOR_UDID" defaults write "$IOS_BUNDLE_ID" \
+  RCT_jsLocation -string "127.0.0.1:$IOS_METRO_PORT"
+xcrun simctl launch "$IOS_SIMULATOR_UDID" "$IOS_BUNDLE_ID"
+```
+
+## 8. Login smoke
+
+After tapping Send in the app with the fixture user's email, read the code from the
+disposable database with the repo's helper (step 6 wrote its connection to
+`.cache/ios-db-env.sh` and removes it on cleanup):
+
+```bash
+source <worktree>/.cache/ios-env.sh
+source <worktree>/.cache/ios-db-env.sh
+node <path/to/otp-helper.mjs> '<fixture user email>'
+```
+
+Enter the code in the simulator. Never record or publish codes, cookies, verification rows
+or session material.
+
+## 9. Cleanup
+
+Stop the backend command (its trap stops the backend and removes the container) and the
+Metro command, then remove only the owned simulator:
+
+```bash
+source <worktree>/.cache/ios-env.sh
+xcrun simctl shutdown "$IOS_SIMULATOR_UDID"
+xcrun simctl delete "$IOS_SIMULATOR_UDID"
+lsof -nP -iTCP:"$IOS_BACKEND_PORT" -iTCP:"$IOS_METRO_PORT" -sTCP:LISTEN || echo "ports free"
+git status --short   # restore Expo rewrites; never commit .xcode.env.local or a loopback mirror URL
+```

package/skills/app-dev/ios-foundation/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/app-dev/monorepo/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO