@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/app-dev/android-foundation/scripts/device-run.test.mjs

@@ -0,0 +1,172 @@
+// device-run.sh against stand-in emulator, adb and docker binaries: the cleanup
+// owns exactly what the run started, keeps the stage's status, and treats a
+// stalled command as terminal.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT = join(dirname(fileURLToPath(import.meta.url)), 'device-run.sh');
+
+async function fakeHost() {
+  const root = mkdtempSync(join(tmpdir(), 'device-run-'));
+  const bin = join(root, 'bin');
+  const sdk = join(root, 'sdk');
+  mkdirSync(bin);
+  mkdirSync(join(sdk, 'emulator'), { recursive: true });
+  const log = join(root, 'calls.log');
+  writeFileSync(log, '');
+  const tool = (path, body) => {
+    writeFileSync(path, `#!/usr/bin/env bash\necho "$(basename "$0") $*" >> "$FAKE_LOG"\n${body}\n`);
+    chmodSync(path, 0o755);
+  };
+  tool(join(sdk, 'emulator', 'emulator'), `
+if test -n "\${FAKE_EMULATOR_IGNORES_TERM:-}"; then trap '' TERM; fi
+while :; do sleep 0.1; done`);
+  tool(join(bin, 'adb'), `
+case "$*" in
+  start-server) exit 0 ;;
+  *getprop*) if test -n "\${FAKE_ADB_HANG:-}"; then sleep 30; fi; echo 1 ;;
+esac`);
+  tool(join(bin, 'docker'), `
+case "$1" in
+  run) while test $# -gt 0; do if test "$1" = --cidfile; then echo fakecid42 > "$2"; fi; shift; done; echo fakecid42 ;;
+  port) echo 127.0.0.1:55432 ;;
+  exec) exit 0 ;;
+  rm) exit 0 ;;
+  ps) exit 0 ;;
+esac`);
+  return { root, bin, sdk, log, ports: await hostPorts() };
+}
+
+// Runners share the host network, so every port this suite hands the script is one the
+// OS reports free right now, never a fixed number another job may already hold.
+function listen(port) {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => resolve(server));
+  });
+}
+
+async function freePort() {
+  const server = await listen(0);
+  const { port } = server.address();
+  await new Promise((resolve) => server.close(resolve));
+  return port;
+}
+
+async function freeEmulatorPort() {
+  for (let port = 5554; port <= 5584; port += 2) {
+    const held = [];
+    try {
+      held.push(await listen(port), await listen(port + 1));
+      return port;
+    } catch {
+      // taken; try the next pair
+    } finally {
+      await Promise.all(held.map((server) => new Promise((resolve) => server.close(resolve))));
+    }
+  }
+  throw new Error('no free emulator port pair in 5554-5584');
+}
+
+async function hostPorts() {
+  return {
+    EMULATOR_PORT: String(await freeEmulatorPort()),
+    ANDROID_BACKEND_PORT: String(await freePort()),
+    ANDROID_METRO_PORT: String(await freePort()),
+  };
+}
+
+function run(host, { journey = ['bash', '-c', 'exit 0'], env = {} } = {}) {
+  const drop = ['bash', '-c', 'echo "drop $SHARD_DB_NAME $SHARD_ADMIN_URL" >> "$FAKE_LOG"'];
+  const result = spawnSync('bash', [SCRIPT, '--drop', ...drop, '--', ...journey], {
+    cwd: host.root,
+    encoding: 'utf8',
+    timeout: 60_000,
+    env: {
+      PATH: `${host.bin}:${process.env.PATH}`,
+      TMPDIR: host.root,
+      FAKE_LOG: host.log,
+      ANDROID_HOME: host.sdk,
+      SETUP_AVD: 'Test_Phone',
+      ...host.ports,
+      DB_NAME_PREFIX: 'app_e2e_',
+      KILL_GRACE_SECONDS: '2',
+      BOUNDED_SECONDS: '5',
+      ...env,
+    },
+  });
+  return { ...result, calls: readFileSync(host.log, 'utf8') };
+}
+
+test('a passing journey cleans up everything it started and exits 0', async () => {
+  const host = await fakeHost();
+  const marker = join(host.root, 'journey ran.txt');
+  const r = run(host, { journey: ['bash', '-c', 'echo "$ANDROID_EMULATOR_SERIAL $SHARD_DB_NAME" > "$1"', 'journey', marker] });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /original_stage_exit=0 cleanup_exit=0\n$/);
+  const port = host.ports.EMULATOR_PORT;
+  assert.match(readFileSync(marker, 'utf8'), new RegExp(`^emulator-${port} app_e2e_\\d+_\\d+\\n$`));
+  assert.match(r.calls, /^adb start-server$/m);
+  assert.ok(r.calls.indexOf('adb start-server') < r.calls.indexOf(`emulator -avd Test_Phone -port ${port}`));
+  assert.match(r.calls, new RegExp(`^emulator -avd Test_Phone -port ${port} -memory 4096 `, 'm'));
+  assert.match(r.calls, /^drop app_e2e_\d+_\d+ postgresql:\/\/postgres:postgres@127\.0\.0\.1:55432\/postgres$/m);
+  assert.match(r.calls, /^docker rm --force fakecid42$/m);
+});
+
+test('a failing journey keeps its status and still cleans up', async () => {
+  const host = await fakeHost();
+  const r = run(host, { journey: ['bash', '-c', 'exit 42'] });
+  assert.equal(r.status, 42);
+  assert.match(r.stdout, /original_stage_exit=42 cleanup_exit=0/);
+  assert.match(r.calls, /^drop app_e2e_/m);
+  assert.match(r.calls, /^docker rm --force fakecid42$/m);
+});
+
+test('an emulator that ignores TERM is killed and reported as a cleanup failure', async () => {
+  const host = await fakeHost();
+  const r = run(host, { env: { FAKE_EMULATOR_IGNORES_TERM: '1' } });
+  assert.equal(r.status, 1);
+  assert.match(r.stdout, /original_stage_exit=0 cleanup_exit=1/);
+  assert.match(r.calls, /^docker rm --force fakecid42$/m);
+});
+
+test('a stalled readiness probe ends the run with 124 and no journey', async () => {
+  const host = await fakeHost();
+  const marker = join(host.root, 'journey-ran');
+  const started = Date.now();
+  const r = run(host, { journey: ['touch', marker], env: { FAKE_ADB_HANG: '1', BOUNDED_SECONDS: '1' } });
+  assert.equal(r.status, 124);
+  assert.ok(Date.now() - started < 15_000, 'the deadline must not wait for the stalled command\'s children');
+  assert.match(r.stdout, /original_stage_exit=124 cleanup_exit=0/);
+  assert.equal(existsSync(marker), false);
+  assert.doesNotMatch(r.calls, /^drop /m, 'no database was handed to the harness, so none is dropped');
+  assert.match(r.calls, /^docker rm --force fakecid42$/m);
+});
+
+test('a busy port stops the run before anything starts', async () => {
+  const host = await fakeHost();
+  const server = await listen(Number(host.ports.ANDROID_BACKEND_PORT));
+  try {
+    const r = run(host);
+    assert.notEqual(r.status, 0);
+    assert.match(r.stdout, /cleanup_exit=0/);
+    assert.doesNotMatch(r.calls, /emulator -avd|docker run/);
+  } finally {
+    server.close();
+  }
+});
+
+test('an emulator port outside the range adb scans is refused', async () => {
+  const host = await fakeHost();
+  const r = run(host, { env: { EMULATOR_PORT: '5588' } });
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /even port in 5554-5584/);
+  assert.equal(r.calls, '');
+});

package/skills/app-dev/app-debug/LICENSE

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

package/skills/app-dev/app-debug/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: app-debug
+description: "Diagnose runtime failures in deployed Cloud Run services — 5xx/422 errors, tracebacks, Next.js SSR/hydration or Server Action failures, DB/Secret Manager connection errors, cold-start timeouts, container OOM. NOT for build or deploy failures (cloud-debug)."
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# App Debug
+
+---
+
+## Step 1: Gather Context
+
+Collect before touching logs:
+
+- **Service name** — which service? (`a1-engine`, `a1-portal`, `a1-admin`, `a1-engine-query`, `a1-forex`)
+- **Environment** — `dev` or `prod`
+- **Error description** — what is the symptom? (HTTP status, error message, UI behavior)
+- **Timestamp** — when did it start? (approximate is fine)
+- **Recent deploy?** — did a new revision go out recently?
+
+Full service names follow the pattern: `{service}-{env}` (e.g. `a1-engine-dev`, `a1-portal-prod`).
+
+---
+
+## Step 2: Fetch Log Tail
+
+**Always start with errors only.** Broaden only if errors return nothing useful.
+
+### Errors-only (start here)
+
+```bash
+gcloud logging read \
+  'resource.type="cloud_run_revision" AND resource.labels.service_name="a1-engine-dev" AND severity>=ERROR' \
+  --project cosmic-heaven-479306-v5 \
+  --limit 20 \
+  --format="value(timestamp,textPayload)"
+```
+
+Replace `a1-engine-dev` with the target service name.
+
+### Broader log tail (if errors-only is empty)
+
+```bash
+gcloud run services logs read a1-engine-dev \
+  --region us-central1 \
+  --project cosmic-heaven-479306-v5 \
+  --limit 50
+```
+
+### Check current revision and env vars
+
+```bash
+gcloud run services describe a1-engine-dev \
+  --region us-central1 \
+  --project cosmic-heaven-479306-v5 \
+  --format="yaml(spec.template.spec.containers[0].env, spec.template.spec.containers[0].resources, status.latestReadyRevisionName)"
+```
+
+### Check secret versions (if secret errors suspected)
+
+```bash
+gcloud secrets versions list database-url-a1-dev \
+  --project cosmic-heaven-479306-v5
+```
+
+---
+
+## Step 3: Classify the Error
+
+Map what you found in logs to one error class:
+
+- **App Error** — Python traceback, unhandled exception, 500 from FastAPI, Next.js render crash
+- **DB Error** — connection refused, auth failure, Tortoise config error, Cloud SQL proxy issue
+- **Secret Error** — permission denied on Secret Manager, secret not found, wrong version
+- **Config Error** — missing env var, wrong PORT, wrong Cloud SQL instance name, bad DB URL format
+- **Resource Error** — OOM kill, DEADLINE_EXCEEDED, cold start timeout, container exit code 137
+
+---
+
+## Step 4: Form Hypotheses
+
+Read `references/common-errors.md` now. Match the log output against the known patterns to confirm your hypothesis before proceeding.
+
+Then pick the top 3 causes ranked by probability based on what the logs actually show. Example:
+
+1. **(Most likely)** Wrong secret version for `database-url-a1-dev` — password mismatch after DB rotation
+2. Cloud SQL proxy not receiving connections — `CLOUD_SQL_INSTANCE` env var missing or wrong format
+3. Cold start OOM — memory limit too low, service hitting 256Mi default under load
+
+Do not list more than 3.
+
+---
+
+## Step 5: Targeted Fix
+
+For each hypothesis, apply the verify + resolve steps from `references/common-errors.md`.
+
+If the error class is **App Error** (Python traceback, Next.js render crash, unhandled exception):
+- Check the first line of the traceback — unhandled import errors appear here at startup
+- Look for `ConfigurationError` or `OperationalError` near the top — indicates Tortoise/DB init failure during lifespan startup
+- If traceback points to a specific route handler file — it's a runtime exception, not a startup issue
+- Route to Cory (backend tracebacks) or Suzzy (Next.js/frontend) with the exact traceback and file location
+
+For all other error classes (DB, Secret, Config, Resource): follow the matching pattern in `references/common-errors.md` for the exact `gcloud` commands to verify and resolve.
+
+---
+
+## Reference
+
+`references/common-errors.md` — full catalogue of known error patterns, symptoms, causes, and fix commands for this stack. Read it in Step 4; refer back in Step 5.

package/skills/app-dev/app-debug/references/common-errors.md

@@ -0,0 +1,128 @@
+# Common Runtime Errors — 1Above Stack
+
+Known error patterns for `a1-*` services on Cloud Run. Format: symptom → likely cause → fix.
+
+---
+
+## Database Errors
+
+### `FATAL: password authentication failed for user "..."`
+- **Cause:** Secret `database-url-a1-{env}` is pinned to an old version after DB password rotation, or a new secret version was added but the service wasn't redeployed.
+- **Fix:** Add new secret version with updated DB URL, then redeploy the service. Verify the revision picks up `latest` version.
+
+### `sqlalchemy.exc.OperationalError: could not connect to server: No such file or directory`
+- **Cause:** Cloud SQL Unix socket not mounted. `CLOUD_SQL_INSTANCE` env var is missing, wrong format, or Cloud SQL connection not added to the service.
+- **Fix:** Redeploy with `--add-cloudsql-instances cosmic-heaven-479306-v5:us-central1:ai-dev` and ensure `CLOUD_SQL_INSTANCE=cosmic-heaven-479306-v5:us-central1:ai-dev` is set.
+
+### `sqlalchemy.exc.OperationalError: could not connect to server: Connection refused`
+- **Cause:** TCP connection attempted instead of Unix socket, or Cloud SQL proxy not reachable. Often occurs when DB URL uses `localhost` or `127.0.0.1` instead of the socket path.
+- **Fix:** DB URL for Cloud SQL on Cloud Run must use the Unix socket format: `postgresql+asyncpg://user:pass@/dbname?host=/cloudsql/PROJECT:REGION:INSTANCE`
+
+### `tortoise.exceptions.ConfigurationError: DB URL not defined or wrong format`
+- **Cause:** Tortoise ORM initialized before the `DATABASE_URL` env var is resolved, or URL scheme is incompatible (`postgresql://` vs `postgres://` vs `asyncpg://`).
+- **Fix:** Ensure Tortoise uses `asyncpg` scheme (`postgresql+asyncpg://` or `asyncpg://`). Confirm `DATABASE_URL` is present in the revision env vars. Check `Tortoise.init()` is awaited inside the app lifespan, not at module import time.
+
+### `asyncpg.exceptions.TooManyConnectionsError`
+- **Cause:** Connection pool exhausted. Multiple cold starts creating new pools simultaneously, or pool size too large for Cloud SQL's max connection limit.
+- **Fix:** Set `maxsize` on the connection pool (e.g. `maxsize=5`). Consider Cloud SQL connection pooling via PgBouncer or reduce min-instances if connection churn is the issue.
+
+---
+
+## Secret Manager Errors
+
+### `google.api_core.exceptions.PermissionDenied: Secret Manager API ... caller does not have permission`
+- **Cause:** Cloud Run service account missing `roles/secretmanager.secretAccessor` on the project or specific secret.
+- **Fix:**
+  ```bash
+  gcloud projects add-iam-policy-binding cosmic-heaven-479306-v5 \
+    --member="serviceAccount:SA_EMAIL" \
+    --role="roles/secretmanager.secretAccessor"
+  ```
+
+### `google.api_core.exceptions.NotFound: Secret ... not found`
+- **Cause:** Secret name typo, wrong env suffix (`-dev` vs `-prod`), or secret was deleted.
+- **Fix:** List secrets to confirm correct name: `gcloud secrets list --project cosmic-heaven-479306-v5 --filter="name~a1"`. Check env var that specifies the secret name.
+
+### `Secret Manager API has not been used in project ... before`
+- **Cause:** Secret Manager API not enabled on the project (unlikely for existing project; more likely a wrong project ID).
+- **Fix:** Verify `--project cosmic-heaven-479306-v5` is correct. Enable if needed: `gcloud services enable secretmanager.googleapis.com --project cosmic-heaven-479306-v5`
+
+---
+
+## Container / Config Errors
+
+### `Container failed to start. Failed to start and then listen on the port defined by the PORT environment variable.`
+- **Cause (most common):** Application crash on startup — missing required env var, failed DB connection during init, or unhandled import error.
+- **Cause (port mismatch):** App binding to hardcoded port instead of reading `$PORT`.
+- **Fix:** Check startup logs immediately after this message. If port: ensure FastAPI runs on port `8000`, Next.js portal on `3000`, admin on `3001`. Confirm app reads `PORT` env var or matches Cloud Run's configured port.
+
+### `Revision failed, container listening on wrong port`
+- **Cause:** Cloud Run sends traffic to port 8000 (or configured port) but container is binding to a different port.
+- **Fix:** Update service port: `gcloud run services update SERVICE --port 8000 --region us-central1 --project cosmic-heaven-479306-v5`. Or fix the app to bind to `int(os.environ.get("PORT", 8000))`.
+
+### `Error: Cannot find module '...'` or `ModuleNotFoundError`
+- **Cause:** Dependency not installed in Docker image, or wrong base image used.
+- **Fix:** Rebuild and push a new image. Check `requirements.txt` / `pyproject.toml` / `package.json` includes the missing dep. This is a deploy-time issue — route to Cory or Suzzy + Watt.
+
+---
+
+## Resource / Performance Errors
+
+### `DEADLINE_EXCEEDED` on first request after idle
+- **Cause:** `min-instances=0` (default) causes cold start. Heavy initialization (DB connection pool, model loading, etc.) exceeds Cloud Run's request timeout.
+- **Fix (fast):** Set `min-instances=1` to keep one warm instance:
+  ```bash
+  gcloud run services update SERVICE-ENV \
+    --min-instances 1 \
+    --region us-central1 \
+    --project cosmic-heaven-479306-v5
+  ```
+- **Fix (proper):** Reduce startup work — lazy-load heavy resources, move initialization out of module scope.
+
+### Exit code `137` / `OOMKilled`
+- **Cause:** Container exceeded memory limit (default 256Mi on Cloud Run).
+- **Fix:** Increase memory: `gcloud run services update SERVICE-ENV --memory 1Gi --region us-central1 --project cosmic-heaven-479306-v5`. If memory keeps growing, investigate for memory leaks.
+
+### `Request timeout` / `upstream request timeout`
+- **Cause:** Request processing exceeds Cloud Run's request timeout (default 300s). Common in heavy data processing or slow DB queries.
+- **Fix:** Increase timeout: `gcloud run services update SERVICE-ENV --timeout 600 --region us-central1 --project cosmic-heaven-479306-v5`. Or break long work into async tasks.
+
+---
+
+## Next.js / Frontend Errors
+
+### `Error: Dynamic server usage: headers`
+- **Cause:** Using `headers()`, `cookies()`, or other dynamic APIs inside a component or route that Next.js attempted to statically render at build time.
+- **Fix:** Add `export const dynamic = 'force-dynamic'` at the top of the page/route file. Or move the dynamic call inside a Server Component that is not statically cached.
+
+### `Hydration failed because the initial UI does not match what was rendered on the server`
+- **Cause:** Server-rendered HTML differs from what React renders on the client. Common sources: `Date()`, `Math.random()`, `typeof window`, `localStorage` in render logic.
+- **Fix:** Wrap client-only code in `useEffect`. Use `suppressHydrationWarning` only as last resort. For timestamps: format server-side and pass as prop, or use a stable seed.
+
+### `Error: ECONNREFUSED 127.0.0.1:PORT` (Next.js Server Component or Server Action)
+- **Cause:** Server Component or Server Action making an HTTP call to an internal service using `localhost` or a hardcoded URL that isn't reachable from the Next.js container.
+- **Fix:** Use the Cloud Run service URL (not localhost). Set the backend URL via env var (e.g. `BACKEND_URL=https://a1-engine-dev-xxx-uc.a.run.app`). Confirm the env var is present in the revision.
+
+### `TypeError: Failed to fetch` / `fetch failed` in Server Action
+- **Cause:** Network call from Server Action failing. Could be DNS, wrong URL, or the target service is down.
+- **Fix:** Log the full URL being fetched. Check target service is running: `gcloud run services describe TARGET --region us-central1 --project cosmic-heaven-479306-v5`. Confirm VPC/egress config if services are VPC-internal.
+
+### `Error: cookies() was called outside a request scope`
+- **Cause:** `cookies()` called at module top level or in a static context.
+- **Fix:** Move the call inside the request handler function body, not at module scope.
+
+---
+
+## FastAPI Errors
+
+### HTTP 422 Unprocessable Entity
+- **Cause:** Request body or query params don't match the Pydantic schema. Often a client bug, but can also be a schema mismatch after an API change.
+- **Fix:** Check the response body for `detail` — it includes the exact field and validation error. Confirm client is sending the correct payload shape.
+
+### HTTP 500 with `RuntimeError: no running event loop`
+- **Cause:** Async code called from a sync context, or Tortoise ORM used before `Tortoise.init()` is awaited.
+- **Fix:** Ensure all DB operations happen inside `async def` functions. Confirm the lifespan handler initializes Tortoise before the app accepts requests.
+
+### `fastapi.exceptions.HTTPException: 401 / 403`
+- **Cause:** Auth middleware rejecting requests. JWT expired, wrong secret used to verify, or `auth-secret` mismatch between portal and engine.
+- **Fix:** Check `auth-secret` secret is the same version across both services. Verify token expiry and issuer config.

package/skills/app-dev/app-debug/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/better-auth/LICENSE

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