coding-os 0.3.2__py3-none-any.whl

core/skills/search/references/grep.md

@@ -0,0 +1,76 @@
+# Grep Reference — Search Skill
+
+## Default excludes (always apply)
+
+```bash
+EXCL="--exclude-dir=.git --exclude-dir=node_modules --exclude-dir=dist \
+  --exclude-dir=build --exclude-dir=__pycache__ --exclude-dir=.next \
+  --exclude-dir=vendor --exclude-dir=.coding-os \
+  --exclude='*.lock' --exclude='*.min.*' --exclude='*.map'"
+```
+
+## Core flags
+
+| Need | Flags | Example |
+|---|---|---|
+| Literal string (no regex) | `-F` | `grep -rnF "foo.bar" . $EXCL` |
+| Recursive + follow symlinks | `-R` | use `-R` in this repo (has symlinks) |
+| Files only | `-l` | `grep -rlF "x" . $EXCL` |
+| Files only, NUL-safe for xargs | `-lZ` | `grep -rlZF "x" . $EXCL \| xargs -0` |
+| Multiple patterns | `-e` | `grep -rnF -e "A" -e "B" . $EXCL` |
+| Skip binaries | `-I` | `grep -rnFI "x" . $EXCL` |
+| Case-insensitive | `-i` | `grep -rnFi "x" . $EXCL` |
+| Whole word | `-w` | `grep -rnFw "foo" . $EXCL` |
+| Context lines | `-C N` | `grep -rnF -C 2 "x" . $EXCL` |
+| Extended regex | `-E` | `grep -rnE "foo[0-9]+" . $EXCL` |
+| Count matches | pipe wc | `grep -rnF "x" . $EXCL \| wc -l` |
+| Pattern starts with `-` | use `-e` | `grep -rnF -e "-flag" . $EXCL` |
+
+## Variant families (check all before editing)
+
+| Original | Also check |
+|---|---|
+| `MyClass` | `my_class`, `MY_CLASS`, `"MyClass"`, `'MyClass'`, in imports |
+| `myFunction` | `my_function`, `MY_FUNCTION`, `my-function` |
+| `FEATURE_FLAG` | `feature_flag`, `feature-flag`, `"FEATURE_FLAG"` |
+| `old-route` | `old_route`, `oldRoute`, `/old-route` |
+
+Multi-variant scan:
+```bash
+grep -rnF -e "MyClass" -e "my_class" -e "MY_CLASS" . $EXCL
+```
+
+## Replace options
+
+**Option A — sed** (only when OLD/NEW have no `|`, `&`, `\`, newlines):
+```bash
+grep -rlZF "OLD" . $EXCL | xargs -0 sed -i.bak 's|OLD|NEW|g'
+find . -name '*.bak' -delete
+```
+
+**Option B — Python** (any string, always safe):
+```bash
+export OLD='OLD_STRING' NEW='NEW_STRING'
+grep -rlZF "$OLD" . $EXCL | xargs -0 python3 -c '
+import os, sys, pathlib
+old, new = os.environ["OLD"], os.environ["NEW"]
+for f in sys.argv[1:]:
+    p = pathlib.Path(f)
+    try: t = p.read_text(encoding="utf-8")
+    except UnicodeDecodeError: continue
+    if old in t: p.write_text(t.replace(old, new), encoding="utf-8")
+'
+```
+
+Use Option B when OLD/NEW contain `/`, `|`, `&`, `\`, or newlines. Prefer B for complex strings.
+
+## Failure modes
+
+| Symptom | Fix |
+|---|---|
+| grep finds more after edit | Missed variants — expand scan |
+| sed corrupts file | Metachar in string — switch to Python Option B |
+| Missing `.md`/`.yaml` files | Add `--include='*.md'` scope |
+| Too much noise | Add `--include='*.py'` path prefix |
+| No match but symbol exists | Check case, try `-R` not `-r`, check `-I` skip |
+| Symlinked file not found | Use `-R` (follows all symlinks) |

core/skills/search/scripts/verify-count.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Pre/post search-count verification for rename + cross-cutting edits.
+# Use BEFORE a rename to lock the ground-truth count, then AFTER to
+# assert zero remaining matches.
+#
+# Usage:
+#   bash verify-count.sh before "TASK-XXX" "old_symbol"
+#       → prints baseline count + saves snapshot
+#   bash verify-count.sh after "TASK-XXX" "old_symbol"
+#       → re-counts; fails (exit 1) if any match remains
+#
+# Designed to be the assertion the `search` skill describes.
+
+set -euo pipefail
+
+# Safety: ensure core POSIX tools resolvable even when caller PATH is restricted.
+export PATH="/usr/bin:/bin:/usr/local/bin:${PATH:-}"
+
+if [ $# -lt 3 ]; then
+  echo "usage: $0 {before|after} <slug> <pattern> [extra grep flags...]" >&2
+  exit 2
+fi
+
+PHASE="$1"
+SLUG="$2"
+PATTERN="$3"
+shift 3
+EXTRA_FLAGS=("$@")
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+AGENT_DIR="${COS_AGENT_DIR:-${COS_STATE_DIR:-$REPO_ROOT/.coding-os}/${COS_AGENT:-shared}}"
+mkdir -p "$AGENT_DIR/search-snapshots"
+SNAP="$AGENT_DIR/search-snapshots/${SLUG}.count"
+
+# Run the count. Use git grep when in a repo (respects .gitignore,
+# fast). Fall back to grep -r.
+count() {
+  if [ -d "$REPO_ROOT/.git" ]; then
+    git -C "$REPO_ROOT" grep -c "${EXTRA_FLAGS[@]+"${EXTRA_FLAGS[@]}"}" -F "$PATTERN" 2>/dev/null | awk -F: '{s+=$2} END {print s+0}'
+  else
+    grep -rc "${EXTRA_FLAGS[@]+"${EXTRA_FLAGS[@]}"}" -F "$PATTERN" "$REPO_ROOT" 2>/dev/null | awk -F: '{s+=$2} END {print s+0}'
+  fi
+}
+
+case "$PHASE" in
+  before)
+    n=$(count)
+    echo "$n" > "$SNAP"
+    echo "[search verify-count] BEFORE: $n matches for '$PATTERN' saved to $SNAP"
+    if [ "$n" -eq 0 ]; then
+      echo "[search verify-count] WARNING: baseline is already 0 — nothing to rename?" >&2
+    fi
+    ;;
+  after)
+    n=$(count)
+    if [ ! -f "$SNAP" ]; then
+      echo "[search verify-count] ERROR: no baseline at $SNAP. Run 'before' first." >&2
+      exit 2
+    fi
+    baseline=$(cat "$SNAP")
+    echo "[search verify-count] BEFORE: $baseline | AFTER: $n"
+    if [ "$n" -gt 0 ]; then
+      echo "[search verify-count] FAIL: $n match(es) remain for '$PATTERN'" >&2
+      echo "Run: git grep -F '$PATTERN'  to see remaining sites" >&2
+      exit 1
+    fi
+    echo "[search verify-count] OK: all $baseline match(es) cleared."
+    ;;
+  *)
+    echo "phase must be 'before' or 'after', got: $PHASE" >&2
+    exit 2
+    ;;
+esac

core/skills/search-infra/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: search-infra
+description: Design and operate full-text and vector search infrastructure — inverted-index engines (Elasticsearch/OpenSearch, Meilisearch, Typesense), analyzers and tokenization, relevance tuning (BM25, boosting, synonyms), faceting, and semantic/vector search (embeddings, ANN indexes, hybrid retrieval). Use when adding a search box, choosing a search engine, designing an index mapping and analyzer chain, tuning relevance, building autocomplete, deciding keyword vs vector vs hybrid retrieval, or keeping a search index in sync with the source database. Boundary vs db-design — db-design owns the durable transactional source of truth (normalized PostgreSQL schema, known-key indexes, migrations, ACID); this skill owns the derived denormalized search index built FROM that source for ranked free-text/semantic retrieval, where the engine is eventually-consistent, rebuildable, and never the system of record. Defers cache concerns to redis and RAG prompt assembly to llm-patterns.
+tier: architecture
+domain: [data, backend]
+last_reviewed: "2026-06-14"
+---
+
+# Search Infrastructure — Ranked Retrieval Done Right
+
+A practical guide to building search that returns the *relevant* result, not just a matching row. Covers classic full-text (inverted index, BM25) and modern semantic (embeddings, vector ANN) retrieval, and the index-sync discipline that keeps either honest. Stack-agnostic; recipes target Elasticsearch/OpenSearch, Meilisearch, Typesense, and pgvector/Qdrant as the reference engines.
+
+## When to Use This Skill
+
+- Adding a search box, autocomplete, or "find similar" to a product.
+- Choosing a search engine — managed Elastic vs Meilisearch vs Typesense vs Postgres FTS vs a vector DB.
+- Designing an index mapping: which fields are searchable, which are filters, which analyzer.
+- Tuning relevance — results are "technically matching but useless", boosting, synonyms, typo tolerance.
+- Deciding keyword vs vector vs hybrid retrieval for a given query distribution.
+- Keeping the search index consistent with the database that owns the data.
+
+Skip when: the lookup is by exact key / known field on a small set — that is a database index (`WHERE id = ?`), see db-design, not a search engine. Search earns its complexity only for ranked, fuzzy, or free-text retrieval.
+
+## The Index Is Derived, Never the Source of Truth
+
+The single most important rule: **the search index is a denormalized, rebuildable projection of data that lives authoritatively elsewhere** (the transactional DB). It is eventually consistent and disposable.
+
+- Never write user data *only* to the search engine. If the index is lost, it must be reconstructable from the source of truth by a full reindex.
+- The index is *denormalized on purpose* — flatten the joins at index time so query time is a single fast lookup. This is the opposite of the normalized source schema (db-design owns that), and that is correct.
+- Accept eventual consistency: a document may be ~seconds stale after a write. If a use case cannot tolerate any staleness, read it from the DB, not the index.
+
+## Keeping the Index in Sync — The Hard Part
+
+Search bugs are usually sync bugs. Three strategies, increasing robustness:
+
+1. **Dual-write** (handler writes DB then index) — simplest, but the two can diverge on partial failure. Avoid for anything important (same dual-write hazard as messaging-queues).
+2. **Outbox / CDC** — DB write emits an event (transactional outbox or change-data-capture like Debezium); a consumer updates the index. Robust, eventually consistent, the production default.
+3. **Periodic full reindex** — rebuild from scratch on a schedule and on demand. Always have this path; it is the disaster-recovery floor and how a mapping change ships.
+
+**Reindex without downtime: alias swap.** Build into a new index, then atomically repoint a read alias from old → new. Never reindex in place against live traffic.
+
+## Full-Text — Analyzer Chain Decides Everything
+
+Relevance is mostly determined *at index time* by the analyzer (how text becomes searchable tokens), not at query time.
+
+- **Tokenization + normalization**: lowercase, strip punctuation, split on word boundaries. The query must use the *same* analyzer as the field, or "iPhone" won't match "iphone".
+- **Stemming / lemmatization**: "running" → "run" so a search for "run" hits it. Language-specific; the wrong language analyzer silently kills recall.
+- **Stop words**: dropping "the/a/of" shrinks the index, but breaks phrase queries like "to be or not to be" — tune per corpus.
+- **Synonyms**: "laptop" ⇄ "notebook". A synonym graph at index or query time is the highest-leverage relevance fix for domain vocabulary.
+- **N-grams / edge-grams**: power autocomplete and typo tolerance — index prefixes so "lap" matches "laptop" as the user types.
+
+### Relevance scoring — BM25 and boosts
+
+- **BM25** is the default ranking function (term frequency × inverse document frequency, length-normalized). It is what modern engines use out of the box; understand it before fighting it.
+- **Field boosts**: a match in `title` should outrank a match in `body` — boost the field. This is the most common, highest-impact tuning knob.
+- **Measure relevance, don't eyeball it.** Build a judgment set (queries → known-good results) and track nDCG/MRR; tune against the metric, not against the one query a stakeholder complained about.
+
+## Vector / Semantic Search — When Keywords Aren't Enough
+
+Keyword search fails when the query and document use *different words for the same idea* ("car" vs "automobile", a question vs a statement). Embedding-based retrieval fixes that.
+
+- **Embeddings**: a model maps text → a high-dimensional vector; semantically similar text lands nearby. Query and documents embed with the *same* model — mismatched models give garbage.
+- **ANN index**: exact nearest-neighbor is too slow at scale; an approximate index (HNSW, IVF) trades a little recall for huge speed. Tune `ef`/`nprobe` for the recall/latency point needed.
+- **Hybrid retrieval** is usually best: run BM25 *and* vector search, fuse the rankings (Reciprocal Rank Fusion). Keyword nails exact terms/IDs; vector catches paraphrase. Neither alone wins across a realistic query mix.
+- **Chunking matters** for long documents: embed passages, not whole docs, or the vector averages into mush. This is also the retrieval half of RAG — but assembling retrieved chunks into a grounded LLM prompt is llm-patterns, not this skill.
+
+## Faceting, Filtering, Pagination
+
+- **Filters are not queries.** A filter (`category = "shoes"`, `price < 100`) is a boolean include/exclude with no relevance contribution and is cacheable — keep it out of the scoring query for speed.
+- **Facets** = filter counts for the UI ("Shoes (42)"). Compute as aggregations; they drive the filter sidebar.
+- **Paginate with `search_after` / cursors**, not deep `from/offset` — deep offset pagination forces the engine to sort the whole prefix and degrades hard past a few thousand results.
+
+## Anti-Patterns (reject in review, fix on sight)
+
+- **Search engine as system of record** — user data only in Elastic; one node loss = data loss.
+- **Query analyzer ≠ index analyzer** — silent zero-recall; the field and the query must analyze identically.
+- **Dual-write sync with no reconciliation** — index drifts from the DB and nobody notices until a user does.
+- **Reindexing in place on live traffic** — partial results during rebuild; use alias swap.
+- **Tuning relevance by eyeballing one query** — fix one, break ten; measure with a judgment set.
+- **Vector-only for everything** — fails on exact IDs, SKUs, error codes; hybrid beats pure vector on mixed queries.
+- **Deep offset pagination** — `from: 10000` melts the engine; use `search_after`.
+- **Embedding whole long documents** — meaning averages out; chunk into passages.
+- **Stop words stripped under a phrase-query feature** — breaks "to be or not to be".
+
+## Tools per surface (2026 defaults)
+
+| Need | Default | Alternatives |
+|---|---|---|
+| General full-text at scale | Elasticsearch / OpenSearch | Solr |
+| Fast, low-ops, typo-tolerant search | Meilisearch, Typesense | Algolia (hosted) |
+| Search inside an existing Postgres | Postgres FTS (`tsvector`) + `pg_trgm` | ParadeDB |
+| Vector / semantic | pgvector, Qdrant, Weaviate | Milvus, Elasticsearch kNN |
+| Embeddings model | provider embedding API / open model | sentence-transformers |
+| CDC sync DB → index | Debezium, logical replication | transactional outbox + consumer |
+
+## Pairs With
+
+- **db-design** — the normalized, transactional source of truth; this skill is the derived denormalized index built from it. The sync seam between them is the whole relationship.
+- **redis** — caching hot queries/facets in front of the engine; ephemeral, not the index itself.
+- **llm-patterns** — vector retrieval is the "R" of RAG; this skill owns retrieval, llm-patterns owns prompt assembly and grounding.
+- **messaging-queues** — the CDC/outbox event stream that drives index sync; same dual-write hazard, same outbox cure.
+- **observability** — query latency, recall metrics, reindex duration, and index-lag are the search golden signals.
+
+## See also
+
+- Elasticsearch: *The Definitive Guide* — analysis, relevance, BM25.
+- *Relevant Search* (Turnbull & Berryman) — analyzer chains, boosting, judgment-set tuning.
+- HNSW paper (Malkov & Yashunin) — the dominant ANN index.
+- *Introduction to Information Retrieval* (Manning et al.) — inverted index, ranking, evaluation (nDCG/MRR).

core/skills/security-mobile/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: security-mobile
+description: Mobile-specific security per OWASP MASVS v2 (Mobile Application Security Verification Standard). Use when designing or reviewing secure storage (Keychain/Keystore vs SharedPreferences/UserDefaults), certificate pinning, root/jailbreak detection, biometric authentication, deep-link injection defenses, IPC hardening, runtime application self-protection (RASP) basics. Targets React Native (bare) on iOS + Android. Pairs with auth-patterns (auth-side hardening) and security-web (server-side hardening).
+tier: cross-cutting
+domain: [mobile, security]
+last_reviewed: "2026-05-11"
+
+---
+
+# Mobile Security — MASVS-Aligned Patterns
+
+For React Native bare apps targeting iOS 16+ and Android 14+. Aligned with OWASP MASVS v2.0 (the 2024 update). Targets the realistic threat model of a consumer mobile app — not a banking app under nation-state attack, but a real app with payments, PII, and user accounts where a breach hurts.
+
+## When to Use This Skill
+
+- Storing tokens / credentials / secrets on the device.
+- Choosing certificate pinning strategy (or whether to pin at all).
+- Adding root/jailbreak detection.
+- Designing biometric prompts for sensitive ops.
+- Reviewing native-module surface area.
+- Planning what NOT to log/screenshot/leak.
+- Auditing third-party SDKs for risky permissions.
+- Pre-flight before App Store / Play Store submission.
+
+For server-side / API-side security, see `security-web`. For auth flows specifically, see `auth-patterns`.
+
+## The Threat Model — Realistic Priorities
+
+Mobile threat ranking for a consumer app (high → low priority):
+
+1. **Lost device, no biometric / weak passcode** → app session compromised. Mitigation: biometric gate on launch + on sensitive ops; idle timeout; remote logout.
+2. **Phishing → credential theft** → standard password takeover. Mitigation: passkeys (phishing-proof), magic-link with same-device check.
+3. **Malicious / compromised library on the client** → can read in-memory state. Mitigation: minimize deps, audit weekly, prefer first-party libs.
+4. **Insecure data at rest** → device backup or filesystem inspection leaks tokens / PII. Mitigation: Keychain/Keystore for all secrets, encrypted DB for sensitive PII.
+5. **MITM on hostile networks** → tampered responses. Mitigation: TLS + (selectively) certificate pinning; refuse insecure connections.
+6. **Reverse engineering for cloning / cheating** → app logic exposed. Mitigation: server-authoritative gameplay, minimal client trust, R8/ProGuard for Android.
+7. **Replay of intercepted requests** → repeated actions. Mitigation: TLS, idempotency keys (api-design skill).
+8. **Side-channel via screenshots / app switcher** → sensitive data leaks via screenshots, voice-over, etc. Mitigation: redact sensitive views in inactive state.
+
+**NOT realistic for most consumer apps**: nation-state attackers, kernel-level malware, hardware tampering. Don't waste effort on these unless your threat model demands them.
+
+## Secure Storage — MASVS L1 + L2
+
+### What Goes Where
+
+| Data | Where | Why |
+|---|---|---|
+| Auth session tokens / refresh tokens | **Keychain (iOS) / Keystore (Android)** via react-native-keychain | OS-level encryption, biometric gate available |
+| OAuth tokens | Same as above | Same |
+| Encryption keys you own | Keychain / Keystore | Same |
+| TOTP shared secret | Server-side encrypted (KMS) — NOT on device | Device compromise = no 2FA bypass |
+| User PII (name, email) | Encrypted DB (op-sqlite + SQLCipher) OR plain DB if not sensitive | Tradeoff |
+| App preferences (theme, language) | MMKV / AsyncStorage (unencrypted) | Not sensitive |
+| Cached server data | MMKV / SQLite / TanStack Query persister | Performance vs sensitivity tradeoff |
+| Analytics queue | MMKV / file | Non-sensitive |
+| **NEVER** | files in app sandbox (anyone with backup access reads), localStorage equivalents (AsyncStorage for tokens), URL params (history) | |
+
+### Keychain (iOS) via react-native-keychain
+
+```typescript
+import * as Keychain from 'react-native-keychain';
+
+// Store
+await Keychain.setGenericPassword('session', sessionToken, {
+  accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_ANY_OR_DEVICE_PASSCODE,
+  accessible:    Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
+  storage:       Keychain.STORAGE_TYPE.AES_GCM,
+  service:       'com.app.session',  // namespace
+});
+
+// Retrieve (prompts biometric if required)
+const creds = await Keychain.getGenericPassword({
+  service: 'com.app.session',
+  authenticationPrompt: { title: 'Unlock', subtitle: 'Use Face ID' },
+});
+const token = creds ? creds.password : null;
+
+// Delete on logout
+await Keychain.resetGenericPassword({ service: 'com.app.session' });
+```
+
+Key options:
+
+- **`ACCESS_CONTROL.BIOMETRY_ANY_OR_DEVICE_PASSCODE`** — biometric required, passcode fallback. The right default for "unlock app" scenarios.
+- **`ACCESS_CONTROL.BIOMETRY_CURRENT_SET`** — invalidates if user changes biometry (stronger; some legitimate cases like banking).
+- **`ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY`** — readable only when device is unlocked, never backed up to iCloud/Google.
+- **`STORAGE_TYPE.AES_GCM`** — symmetric AES; modern default.
+
+### Android Keystore
+
+react-native-keychain wraps Android Keystore automatically. The `accessControl` and `accessible` options translate to BIOMETRIC_STRONG and EncryptedSharedPreferences-style storage.
+
+For raw access (rare): use `react-native-keychain` or `react-native-encrypted-storage`. NEVER `AsyncStorage` or `MMKV` (non-encrypted variant) for tokens.
+
+### MMKV for Encrypted Non-Token Data
+
+```typescript
+import { MMKV } from 'react-native-mmkv';
+
+// Encrypted instance (key derived per-install, stored in Keychain)
+const secureKey = await getOrCreateMmkvKey();  // helper that uses Keychain
+const encryptedMmkv = new MMKV({
+  id: 'sensitive-cache',
+  encryptionKey: secureKey,
+});
+
+encryptedMmkv.set('user_settings', JSON.stringify(settings));
+```
+
+For PII-heavy data (chat history, financial records), use SQLite with SQLCipher (op-sqlite supports this).
+
+## TLS + Certificate Pinning
+
+### TLS Baseline
+
+- **HTTPS everywhere**. Refuse `http://` connections at the framework level.
+- **iOS App Transport Security** (`Info.plist`):
+  ```xml
+  <key>NSAppTransportSecurity</key>
+  <dict>
+      <key>NSAllowsArbitraryLoads</key>
+      <false/>
+  </dict>
+  ```
+  Don't whitelist domains for ATS exception unless you have to (e.g., legacy partner API).
+- **Android Network Security Config** (`res/xml/network_security_config.xml`):
+  ```xml
+  <network-security-config>
+      <base-config cleartextTrafficPermitted="false">
+          <trust-anchors>
+              <certificates src="system" />
+          </trust-anchors>
+      </base-config>
+  </network-security-config>
+  ```
+  Reference in `AndroidManifest.xml`: `android:networkSecurityConfig="@xml/network_security_config"`.
+
+### Certificate Pinning — When to Pin
+
+Pinning protects against rogue CAs (a real risk in some networks). It also creates BREAKAGE risk: if your cert rotates and the pinned hash is stale, every user is locked out.
+
+**Pin when**:
+- App handles money or PII at high stakes (banking, healthcare, authentication infrastructure).
+- You can guarantee certificate rotation coordination (CI updates the app + the API in lockstep).
+
+**Don't pin when**:
+- Standard consumer app, no critical data flow.
+- You can't operationally manage rotation (you'll DDoS yourself with broken updates).
+
+### How to Pin
+
+Pin the SUBJECT PUBLIC KEY HASH (SPKI), not the full certificate. SPKI survives cert rotation as long as you keep the same key.
+
+```typescript
+// react-native-ssl-pinning OR axios + custom adapter
+import { fetch as pinnedFetch } from 'react-native-ssl-pinning';
+
+const res = await pinnedFetch('https://api.app.com/lessons', {
+  method: 'GET',
+  sslPinning: {
+    certs: ['cert-spki-sha256'],   // base64-encoded SHA-256 of SPKI
+  },
+  headers: { Authorization: `Bearer ${token}` },
+});
+```
+
+**Pin two keys** (current + backup) so rotation is non-breaking. Generate the backup key, store it offline, swap to it during rotation.
+
+### Pin Failure Behavior
+
+DON'T just throw. Show user "Connection couldn't be verified — please update the app." Log to your error reporter. Provide an unpinned fallback if you have a graceful recovery path (most apps shouldn't).
+
+## Biometric Auth (Local UX Gate, NOT Server Trust)
+
+Biometrics on the client are a UX gate — they unlock locally-stored tokens. They are NOT proof to the server that the user is who they claim. The server still relies on the actual session token / WebAuthn signature.
+
+```typescript
+import * as Keychain from 'react-native-keychain';
+
+async function unlockApp(): Promise<string | null> {
+  try {
+    const creds = await Keychain.getGenericPassword({
+      service: 'com.app.session',
+      authenticationPrompt: {
+        title: 'Unlock',
+        subtitle: 'Use Face ID to access your account',
+        cancel: 'Use passcode',
+      },
+    });
+    return creds ? creds.password : null;
+  } catch (e: any) {
+    if (e.code === 'AuthenticationFailed' || e.code === 'UserCanceled') {
+      return null;
+    }
+    throw e;
+  }
+}
+```
+
+Re-prompt cadence:
+
+- App cold launch → always.
+- App backgrounded > 60 seconds → re-prompt.
+- Sensitive op (transfer money, view 2FA codes) → re-prompt every time.
+
+## Detecting Root / Jailbreak
+
+OWASP MASVS L2: should detect tampered runtime. For most consumer apps this is overkill; add when:
+
+- App handles money or compliance-required data.
+- You've seen abuse from rooted devices.
+
+```typescript
+import JailMonkey from 'jail-monkey';
+
+if (JailMonkey.isJailBroken()) {
+  // Soft block: warn user, refuse to enable sensitive features.
+  // Hard block: refuse to launch (some banks do this; loses legitimate users with rooted dev devices).
+}
+```
+
+JailMonkey checks: presence of `Cydia.app` (iOS), `su` binary (Android), busybox, write to `/system`, etc. Not bulletproof — determined attackers bypass it. Use as a deterrent + a server-side signal (clients with elevated risk get extra verification).
+
+## Deep Link Injection
+
+Deep links can carry malicious payloads. Validate every parameter:
+
+```typescript
+// linking.ts
+config: {
+  screens: {
+    Lesson: {
+      path: 'lessons/:lessonId',
+      parse: {
+        lessonId: (raw: string) => {
+          if (!/^lsn_[a-zA-Z0-9]{8,32}$/.test(raw)) {
+            throw new Error('invalid lesson id');
+          }
+          return raw;
+        },
+      },
+    },
+    PasswordReset: {
+      path: 'auth/reset/:token',
+      parse: {
+        token: (raw: string) => {
+          if (!/^[A-Za-z0-9_-]{32,128}$/.test(raw)) {
+            throw new Error('invalid reset token');
+          }
+          return raw;
+        },
+      },
+    },
+  },
+},
+```
+
+For deep links that authenticate the user (magic link, password reset), additional rules:
+
+- Reject if NOT served via HTTPS app link (refuse custom scheme for these).
+- Server-side: token is single-use, short-lived, scoped to action.
+- Client: render a "this will sign you in as user@example.com — confirm?" screen before action; defeat clickjacking.
+
+## App Switcher / Background Redaction
+
+iOS takes a screenshot for the app switcher. If sensitive data is on screen, the screenshot lives in the cache.
+
+```typescript
+import { useEffect, useState } from 'react';
+import { AppState } from 'react-native';
+
+export function useBackgroundRedaction(): boolean {
+  const [redact, setRedact] = useState(false);
+  useEffect(() => {
+    const sub = AppState.addEventListener('change', (s) => {
+      // 'inactive' is the correct trigger for the switcher screenshot.
+      setRedact(s !== 'active');
+    });
+    return () => sub.remove();
+  }, []);
+  return redact;
+}
+
+// In sensitive screens:
+const redact = useBackgroundRedaction();
+return redact ? <RedactedView /> : <RealView />;
+```
+
+Android: optionally `setFlags(WindowManager.LayoutParams.FLAG_SECURE)` to prevent screenshots and screen recording entirely. Use sparingly — frustrating in normal use.
+
+## Logging Hygiene
+
+NEVER log:
+
+- Auth tokens (Authorization header, cookies).
+- Passwords (even hashed).
+- TOTP codes / backup codes.
+- Session IDs.
+- PII: full names, emails, phone, addresses, payment details, government IDs.
+- Long IDs that uniquely identify users (use a hash or a short stub).
+
+Patterns to enforce:
+
+```typescript
+// Strip sensitive headers from API client logs.
+api.interceptors.request.use((cfg) => {
+  if (__DEV__) console.log('[api]', cfg.method, cfg.url);  // NO body, NO headers
+  return cfg;
+});
+
+// In the framework error reporter:
+Sentry.init({
+  beforeBreadcrumb(breadcrumb) {
+    if (breadcrumb.category === 'http') {
+      delete breadcrumb.data?.request_body;
+      delete breadcrumb.data?.response_body;
+    }
+    return breadcrumb;
+  },
+  beforeSend(event) {
+    return scrubPII(event);
+  },
+});
+
+// Strip in release builds:
+// babel-plugin-transform-remove-console: removes all console.* in production.
+```
+
+## SDKs — Audit Risky Permissions
+
+Many third-party SDKs request more than they need. On every dependency add:
+
+1. Read the SDK's permission requirements.
+2. Verify in the merged manifest (`./gradlew app:dependencies` + look at the rendered AndroidManifest).
+3. Check for: `READ_PHONE_STATE`, `ACCESS_FINE_LOCATION`, `READ_CONTACTS`, `RECORD_AUDIO`, `READ_EXTERNAL_STORAGE`, `BIND_ACCESSIBILITY_SERVICE`.
+4. If the SDK adds a permission your app doesn't need, find an alternative or use the manifest `<uses-permission tools:node="remove" />` to strip it.
+
+Common offenders: certain ad SDKs, some analytics SDKs, push notification wrappers that ask for location. Stick to first-party / well-known options when possible (Firebase, Sentry, Notifee).
+
+## Native Module Surface — Threat Vector
+
+A native module is direct OS access from JS. Audit yours and any third-party ones for:
+
+- Arbitrary file read/write (a malicious JS could exfiltrate any file the app can read).
+- Arbitrary command execution (`exec`, `Runtime.exec`).
+- Network calls bypassing your TLS config.
+- Plain-text credential storage.
+
+For modules you write: validate inputs at the JS↔native boundary; never trust JS-side strings/numbers.
+
+```swift
+// iOS
+@objc(set:value:resolve:reject:)
+func set(_ key: String, value: String, resolve: ..., reject: ...) {
+  guard key.count <= 256, value.count <= 16384 else {
+    reject("BAD_INPUT", "size limit", nil)
+    return
+  }
+  // ... safe operation
+}
+```
+
+## Pre-Submission Security Review
+
+Use [assets/mobile-security-checklist.md](assets/mobile-security-checklist.md) before TestFlight/Play Internal. Run an automated scan with **MobSF** (Mobile Security Framework) on the release build — catches common issues (cleartext traffic, debuggable=true, weak crypto).
+
+For more thorough audit: OWASP MASVS L1 covers consumer apps; L2 + L3 are for high-risk apps (banking, government).
+
+## Common Mobile-Security Mistakes
+
+1. **Tokens in AsyncStorage / unencrypted MMKV** — trivially read via filesystem inspection or backup.
+2. **TOTP secret on device** — device compromise = 2FA bypass.
+3. **No biometric prompt for sensitive ops** — lost-phone scenario gives full access.
+4. **Pinning without rotation strategy** — DDoS yourself the day cert renews.
+5. **Pin failure throws raw error** — confuses users who can't update.
+6. **Deep-link params not validated** — path traversal, SQLi via QR code.
+7. **Logging Authorization header** in production traces — leaks session tokens to Sentry / Crashlytics.
+8. **Sensitive views not redacted on background** — screenshot cache leak.
+9. **Backup not excluded for sensitive files** — iCloud / Google backup = data leak.
+10. **Debuggable=true in release** — anyone can attach a debugger and inspect memory.
+11. **No R8/ProGuard** on Android release — class names leaked, easier reversing.
+12. **Trusting client-side auth flags** — `if (user.isAdmin)` on the client is meaningless; server must check.
+13. **Cleartext fallback in network config** — defeats TLS purpose.
+14. **WebView with `setAllowFileAccess(true)`** — trivial file read from page JS.
+15. **Insecure WebView origin checks** — postMessage from any page wins.
+
+## Source Material
+
+- *OWASP MASVS v2.0* (2024 release) — primary standard.
+- *OWASP MSTG* (Mobile Security Testing Guide) — practical patterns per requirement.
+- Apple — *App Security Overview* + *Keychain Services Programming Guide*.
+- Android — *App Security Best Practices* + *Network Security Configuration*.
+- *MobSF* (Mobile Security Framework) — automated scanner.
+- React Native Security: <https://reactnative.dev/docs/security>