ark

Imported from rodrgds/ark (AGENTS.md). Install upstream with npx skills add rodrgds/ark. Copyright stays with the author.

AGENTS.md — Ark

Durable operating guide for agents working on Ark. Keep this concise. It is not a changelog: record completed work in Git and keep changing release/device status in the linked docs.

Start Here

1. Run git status --short --branch; all existing changes are user-owned until proven otherwise.
2. Run bun run agent:preflight for a quick repository snapshot. Use bun run agent:preflight:native before native diagnosis/builds and bun run agent:preflight:release before a promoted build or dev-group delivery.
3. Read only the source-of-truth material relevant to the task:
   • Product or UI: PRODUCT.md, DESIGN.md.
   • Current release/device gaps: docs/v1-prep-plan.md, docs/release-readiness.md, docs/android-device-smoke.md.
   • Architecture and setup: docs/architecture.md, docs/developer/.
   • Native behavior: app.json, plugins/, modules/, patches/.
   • Commands and hooks: package.json, devenv.nix.
4. Treat TODO.md, status tables, comments, and old issue text as candidate evidence. Verify each claim against implementation, tests, generated config, and current runtime before repeating it.
5. Do not append a session recap to this file. Add only a durable rule, ownership boundary, or expensive-to-rediscover fix.

How The User Works

• A "deep dive", "everything", or "what is missing" request means inspect the complete relevant flow, not only one screen. Separate the result into verified implementation gaps, device-only proof gaps, tests to run, and stale docs. Audits are read-only until implementation is requested.
• "Fix/implement all of those" after an audit means implement the verified findings and validate them; do not spend another turn restating the report or asking avoidable questions.
• Physical-device feedback is the strongest available runtime evidence. A green typecheck, unit test, Gradle build, or emulator run does not invalidate a reproducible phone failure.
• The user prefers root-cause repairs and low tech debt. Do not accumulate retries, fallback branches, UI suppression, or release-only workarounds when the underlying failure is unknown.
• Ark is still pre-v1 and has one primary tester. Do not add compatibility code for old pre-v1 databases or backups unless explicitly requested. The current baseline rejects them.
• "Commit and push in chunks" means inspect the whole worktree, keep unrelated user changes, group commits by coherent subsystem/behavior, run the relevant gates, push, and confirm the upstream state. Never make one giant catch-all commit.
• "Build and send" means use the saved one-command delivery flow, not rediscover the Beeper room or manually reconstruct the command.

Evidence And Claims

Use the strongest accurate label:

Never call an APK "device proof" merely because it contains expected symbols or installs. Report what remains unverified whenever hardware, credentials, data packs, or external services are absent.

Native Root-Cause Loop

Use this order for crashes, black screens, hangs, heat, missing native features, or "worked in dev but not release":

1. Record device/OS, exact APK variant and commit, last-known-good commit, and minimal reproduction.
2. Run bun run agent:preflight:native; confirm disk, connected devices, cache footprint, and Git state before an expensive build.
3. Capture the first causal error with Metro/dev logs and adb logcat or Xcode. Do not diagnose from the final cascade or screenshot alone.
4. Reproduce in both dev and release when behavior differs. For release-only failures, inspect minification, Metro bundle freshness, native library/assets packaging, config plugins, and patched dependencies before adding app-level fallback code.
5. Fix the canonical source, remove abandoned workarounds, add focused regression coverage, then rerun the smallest relevant gate and the actual runtime flow.
6. Build/send only when requested. If a device remains connected, verify launch and the repaired flow before delivery.

Generated android/ and ios/ files are evidence, not the sole source of a fix. Native changes must live in app.json, plugins/, modules/, dependency patches, or another declarative owner and survive prebuild. Ark's normal scripts use expo prebuild --no-clean because SDK 57 defaults to clean regeneration; do not run a clean prebuild casually.

Canonical Ownership

Keep orchestration out of route files when an owning service/component/hook exists. The map and Settings implementations are already large; move new domain state/actions to their owner instead of growing central screens.

Product Contracts

• Ark is "Noé's Ark for the offline age": a serious, calm, offline-first survival computer, not a playful camping app. It should remain useful after initial downloads with no network.
• Production targets are iOS and Android development/release builds. Expo Go is not a production verification environment for MapLibre, llama.rn, SQLCipher, routing, ZIM, OCR, or ExecuTorch.
• Fresh installs default to System theme + System accent. Android uses Material You colors when available and Moss as deterministic fallback. OLED is selectable; Battery Reduce Mode may use it.
• Default visible tabs are Chat, Tracks, Map, Library, Settings. Tools and Notes remain available but hidden by default. Native tabs are capped at five; persisted preferences must be sanitized.
• Passphrase protection is optional and gates secure notes. It does not imply that documents, chats, tracks, maps, or RSS are locked. Optional SQLCipher protects the whole database.
• Fresh databases use the current v2 baseline; old pre-v2 databases should be cleared. Backup v3 rejects older backups rather than carrying pre-release migration debt.
• AI answers, RAG, maps, routing, sensors, downloaded content, and backups are local-first. Network use and incomplete native proof must be described precisely in UI and public copy.

UI Rules From Device Feedback

• Preserve Ark's established restrained visual system. Use PRODUCT.md and DESIGN.md; do not invent a second aesthetic during a bug fix.
• Use semantic theme classes. Native APIs, WebViews, maps, navigation, and other concrete-color consumers should subscribe to useThemeStore((state) => state.colors). Verify Light, Dark, OLED, System, and changed accents when the surface is theme-sensitive.
• Fix shared failures at the shared contract. Cursor/selection issues go first to src/components/ui/input.tsx; sheet/inset/keyboard failures go first to shared bottom-sheet and keyboard primitives; tab-shell failures go first to tab preference/layout owners.
• Shared Input deliberately lets native TextInput own text while focused. Do not restore a controlled value update on each render and reintroduce Android cursor jumps.
• Bottom-sheet actions must stay reachable above Android/iOS insets and the keyboard. Use the shared pinned footer, nested scrolling, and keyboard-aware primitives; test tall content and low-screen controls, not only the initial sheet frame.
• Settings probes must load independently with bounded timeouts and visible fallbacks. Never gate the entire page behind one native/storage/model Promise.all or leave endless "Checking..." states.
• Onboarding should queue work and advance; it must not await multi-minute map/model downloads. Active UI must consider both map-tile and routing-graph states.
• Use Expo Router VectorIcon for native tab icons. Eager icon-source generation has caused slow post-onboarding tab paint and device heat.
• Icon-only controls need accessibility labels and at least a 44x44 touch target. Check safe areas, keyboard avoidance, overflow, action visibility, and console/device logs on affected screens.

SDK 57 And Native Gotchas

• Current cohort: Expo 57.0.6, React Native 0.86.0, React 19.2.3, TypeScript 6.0.3, Expo Router 57.0.6, Uniwind 1.6.3.
• Import ThemeProvider, DarkTheme, and DefaultTheme from expo-router, not directly from @react-navigation/native; production bundles reject the latter.
• Keep the TenTap React 19 peer patch, root react-dom override, and SDK-managed Expo peers. Avoid direct expo-modules-core dependencies in app/local-module manifests unless Doctor requires it.
• Keep Worklets bundle mode and the Uniwind patch that resolves React Native through react-native/index. Recursive resolution can cause release startup stack overflows around NativeModules, copyComponentProperties, or ActivityIndicator.
• plugins/with-ark-gradle-memory.js owns the 12 GiB Gradle heap. Native builds can also consume large space in .cxx, Gradle, and intermediates; the preflight and build-send disk guard exist because "No space left on device" has masqueraded as a source failure.
• After changing a patched native dependency, force the Metro bundle and release assembly: cd android && ./gradlew :app:createBundleReleaseJsAndAssets --rerun-tasks && ./gradlew :app:assembleRelease.

Verification

Use focused checks first, then scale with blast radius:

bun run typecheck
bun run lint
bun run test
bun run check
bun run check:docs
bun run docs:build
bun run verify

• bun run verify is the source/docs gate; it does not perform native builds or device tests.
• After dependency or Expo config changes, run npx expo-doctor in addition to repository checks.
• Add focused tests for defects. In this Bun + RNTL setup, prefer const view = await render(...) and query through view; the global screen helper has failed with "render function has not been called".
• Add new lucide icons to the shared RNTL icon mock when a mount-tested surface uses them.
• For CI failures, inspect each job log first and separate code failure from toolchain/environment failure. Keep working until requested checks are green, not merely locally patched.
• Prefer focused unit/RNTL coverage for narrow state machines. Use broad route/device QA when the user asks for "all screens", "everything", production readiness, or cross-platform consistency.
• Run native, device, prebuild, Gradle, deployment, release, or external-send commands only when the user requests that scope.

Delivery

• Dev-group release build and send: bun run build-send.
• Dev/debug build and send: bun run build-send:dev.
• The script builds the correct APK, verifies the artifact exists, computes SHA-256, adopts the local Beeper session if needed, and sends to the saved WhatsApp dev group. Do not repeat the room ID or manual command in task reasoning.
• Before a promoted public build: run bun run agent:preflight:release, the proportional source gates, create fresh native artifacts, inspect them, and distinguish build proof from device smoke.
• When Git publication is requested, recheck the final diff and worktree after formatting/build generation, commit by subsystem, push, and confirm upstream. Do not stage unrelated user work.

F-Droid Release

• The F-Droid edition (pt.rgo.ark) must stay tracker-clean: the fdroidserver scanner fails on any GMS/Firebase/play-core class, defined or referenced, and on AGP's "Dependency metadata" signing block. The fdroid build runs from the committed android/ — the recipe does NOT run expo prebuild.
• GMS-free packaging is owned by the committed android/ and its config plugins, not the recipe: plugins/with-ark-fdroid-autolink.js injects an ARK_DISTRIBUTION=fdroid-gated expoAutolinking.exclude = ['expo-location','expo-notifications'] into settings.gradle (Expo autolinking ignores react-native.config.js exclusions), and plugins/with-ark-android-release.js sets dependenciesInfo { includeInApk = false; includeInBundle = false }. Run expo prebuild --no-clean and commit the regenerated android/ when these change; verify with a dexdump scan (com/google/(android/gms|firebase|android/play/core|tagmanager|analytics) and com/android/billing must be 0 defined and referenced) and an apksigner/raw-bytes check that Dependency metadata is absent.
• The fdroid JS surface is served by metro.config.js fdroid runtime shims: src/shims/expo-location.fdroid.ts (AOSP react-native-nitro-fused-location) and src/shims/expo-notifications.fdroid.ts (react-native-notify-kit). These cover the foreground surface only; background location on fdroid is a no-op flag until the native fork is extended.
• fdroid versions are tagged vX.Y.Z-fdroid on commits whose committed android/ carries the exclusions above. Plain tags (v1.0.0, v1.1.0, v1.2.0) predate them and FAIL the tracker scan; fdroiddata metadata therefore uses AutoUpdateMode: Version + UpdateCheckMode: Tags v[0-9.]+-fdroid$ and pins each current build to a full commit SHA.
• Submission lives in ~/dev/fdroiddata/metadata/pt.rgo.ark.yml on the pt.rgo.ark branch; the canonical draft mirrors it at fdroid/metadata/pt.rgo.ark.yml. A green fdroiddata GitLab pipeline is required before/after metadata changes; retrigger with an empty commit push to pt.rgo.ark.
• Do not commit unrelated user work into fdroid release commits: version bumps (e.g. versionCode/ versionName in android/app/build.gradle) must keep matching the submitted fdroiddata versionCode/CurrentVersionCode, and F-Droid metadata is not advanced by local-only edits.

Current Truthfulness Boundaries

The main unresolved risk is physical-device proof, not basic code presence. Before production claims, use the current checklists for SQLCipher migration/rekey, MapLibre downloads/restart, Valhalla routes with real graphs, large ZIM archives, OCR/PDF extraction, llama/ExecuTorch memory and cancellation, background tracks, large download recovery, TTS lifecycle, backups, and iOS native paths. docs/v1-prep-plan.md and docs/android-device-smoke.md own the changing matrix.

Writing And Product Copy

• Keep copy concise, concrete, calm, and task-first. Remove explanatory text that does not help the user act.
• Prefer familiar words and active voice. Avoid stock metaphors, marketing filler, and exposed engine jargon.
• Preserve exact technical, safety, medical, legal, API, command, citation, and proper-noun wording where precision requires it.
• Never imply that an unavailable, cached, fallback, unverified, or partial capability is healthy or production-ready. Healthy configuration states should stay quiet; show actionable problems.