agentleFS
RonenMarsRonenMars/threadbase-mobile/AGENTS.md

threadbase-mobile

AGENTS.md4 starsChanged 2 days agoMITView on GitHub

Keep this file to repository-specific behavior and safeguards. Agent tooling is documented in docs/agents/tooling.md; operational diagnosis belongs in docs/troubleshooting.md. The mobile client absorbs streamer

The file

We split this AGENTS.md into the rules it gives an agent

12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep this file to repository-specific behavior and safeguards.

    line 3
  2. Very specific:

    Before committing JavaScript or TypeScript, run npx eslint on the staged JS/TS files.

    line 8
  3. Very specific:

    Never use emoji as UI icons.

    line 20
  4. Very specific:

    Every new components//*.tsx file requires a colocated *.stories.tsx in the same commit.

    line 21
  5. Very specific:

    When package.json or package-lock.json changes, run pod install in ios/ and keep package.json, package-lock.json, and ios/Podfile.lock …

    line 25
  6. Very specific:

    Treat checksum-only drift for ExpoModulesCore, ExpoWidgets, hermes-engine, and RNSentry as path noise.

    line 26
  7. Very specific:

    Every physical iOS device build/install must use scripts/dev-device.sh.

    line 27
  8. Very specific:

    Use /expo-local-ship for ordinary ship, TestFlight, build, submit, and release requests.

    line 31
  9. Very specific:

    Commit the app.json build/version bump before archive or upload.

    line 32
  10. Very specific:

    Treat every response as untrusted input.

    line 41
  11. Very specific:

    Before squash-merging with --delete-branch, verify no open PR uses that branch as its base.

    line 66
  12. Distinctive:

    Never close an issue that was not actually finished, and never leave finished work with the issue still open.

    line 83

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Threadbase Mobile — Codex Instructions

Keep this file to repository-specific behavior and safeguards. Agent tooling is documented in docs/agents/tooling.md; operational diagnosis belongs in docs/troubleshooting.md.

Verification

  • Standard checks are npm run lint, npm run typecheck, npm run test:ci, and npm run test:scripts.
  • Before committing JavaScript or TypeScript, run npx eslint on the staged JS/TS files. Errors block; warnings do not.
  • i18next/no-literal-string is an error. Put user-facing copy in translations. For technical literals, use a narrowly scoped disable with a reason; never exclude a mixed-copy file.
  • Keep finite translation choices statically visible: state, props, helpers, and option metadata carry semantic values, while the nearest presentation boundary maps them through literal t('namespace:key') calls. Do not pass translation keys as application data or hide them with preservePatterns or artificial usage manifests; npm run test:i18n uses i18next-cli status and status --unused to reject missing, incomplete, and stale keys.

E2E testing

  • Maestro flows and fixtures live in e2e/; npm run test:e2e:mock is the authoritative mock suite. Add new flows to the relevant test:e2e:* script and prefer testID over unstable visible text. The GitHub E2E workflow shards that same list across parallel jobs after one Release build per platform; do not duplicate the flow list in the workflow YAML.
  • On iOS 26.x, never use Maestro hideKeyboard; scroll instead, or use Enter only for safe single-line inputs. XCTest/SpringBoard automation crashes are simulator failures, not app crashes. See docs/troubleshooting.md.
  • Shut down any iOS simulator or Android emulator you booted before the session ends (xcrun simctl shutdown <UDID> and quit Simulator.app once nothing is booted; adb emu kill for Android). Never erase a device; leave one that was already booted as found, and only if you recorded it as booted at the start.

UI and components

  • Never use emoji as UI icons. Use phosphor-react-native in all new or touched UI.
  • Every new components/**/*.tsx file requires a colocated *.stories.tsx in the same commit. Rare exemptions require a reason in scripts/git-hooks/story-exempt.txt. Add a story when modifying an existing component if the change is small. See docs/storybook.md.

Native dependencies and builds

  • When package.json or package-lock.json changes, run pod install in ios/ and keep package.json, package-lock.json, and ios/Podfile.lock together.
  • Treat checksum-only drift for ExpoModulesCore, ExpoWidgets, hermes-engine, and RNSentry as path noise; use scripts/reset-podfile-lock-path-noise.sh rather than committing it.
  • Every physical iOS device build/install must use scripts/dev-device.sh. Never call npx expo run:ios --device directly or introduce another device-build path. The script supplies the per-target App Groups signing profiles. Simulator builds are unaffected.

Shipping

  • Use /expo-local-ship for ordinary ship, TestFlight, build, submit, and release requests.
  • Commit the app.json build/version bump before archive or upload.
  • Version bumps land through scripts/admin-merge-pr.sh, never by pushing directly to main. Follow the branch and commit formats in docs/deployment.md.
  • /ship-expo-cloud is opt-in only. Invoke it only when the user explicitly types that command, and obtain confirmation before any EAS build or submit command.
  • Before deploying to QA, Beta, or Production via the respective workflows, always ask which platform(s) to deploy to: iOS, Android, or both. Do not assume or default to all; get explicit confirmation of the platform choice in every deployment request unless the user specified it in their message.

Server compatibility

The mobile client absorbs streamer evolution: a newer server may degrade a screen but must not crash the app.

  • Treat every response as untrusted input. Narrow unknown statuses and fall back to idle; do not rely on TypeScript exhaustiveness at the wire boundary.
  • Missing optional fields omit only the affected UI.
  • Probe GET /api/info and GET /api/config/feature-flags; hide or explain unsupported features instead of throwing. A failed probe means the feature is off.
  • Report malformed data while keeping the rest of the screen alive. Do not invent client-side repair shims or pin a minimum server version.

Session ownership terms

  • External: a session the streamer discovered but does not own (ownership: 'external', isExternalSession). The app shows it read-only: it never sends input to it and never takes it over.
  • The user-facing word is "External", never "Observed". The session tier and its i18n key are external; the read-only capability flag is isExternalOnly and its locale key is externalOnly.
  • Allowed actions on an External session: favorite, rename, and terminate. Terminate calls POST /sessions/:id/terminate, asks for confirmation first, and is offered only while the process is alive.
  • Managed: a session the streamer spawned.
  • View only: a provider without live control, so its sessions can't be typed into. Shown as the "View only" chip; code names the flag externalOnly / isExternalOnly, shared with External sessions.

Encryption (E2EE)

A server whose record carries serverPublicKey is pinned: its traffic is sealed and must never silently fall back to plaintext. See docs/e2ee-client.md.

  • retryable in services/e2ee/context.ts is true for exactly E2EE_CTX_UNKNOWN and E2EE_TRANSIENT. Every other code is a hard refusal to surface, never to retry — and a 429 arriving after a hard refusal is the server reacting to our own retries, not new information.
  • A sealed socket that receives a non-binary frame throws. React Native delivers binary frames as ArrayBuffer, not Uint8Array; convert, never widen the accepted shape to strings.
  • A pairing that gets no message 2 is a failed pairing, not a plaintext success. This is what protects a user whose streamer sits behind an edge gate.
  • Contexts are never rekeyed in place: a new key is a new context. Socket contexts die with the socket; the REST context rolls over on 24h / 1 GiB / every foreground with a 10 s drain.

Repository workflows

  • PR titles use type(scope)?: imperative summary with feat, fix, chore, docs, test, ci, perf, or refactor; branches use the matching type/kebab-case-summary. Work explicitly targeting integration-merge-354-355-376 uses that branch as its base and rebases onto its latest tip.
  • Before squash-merging with --delete-branch, verify no open PR uses that branch as its base; preserve a non-leaf branch until dependents are retargeted or merged.
  • GitHub issue and triage conventions are delegated to docs/agents/issue-tracker.md and docs/agents/triage-labels.md. Domain documentation uses one root CONTEXT.md plus docs/adr/; see docs/agents/domain.md.

Headless Linux agents

Headless Linux cannot run native builds, CocoaPods, shipping scripts, Maestro, or device/simulator tooling. It can run the JS checks and Expo Web.

For browser smoke tests, start the bundled mock streamer from e2e/mock-server.js; because it has no CORS headers, front it with a development-only CORS proxy outside the repository. Expo Web is an early spike with expected native-only gaps; see docs/expo-web-support.md.

Issue status updates

Any change traceable to an existing issue ends with a status update on that issue — code, docs, tests, config, a revert, or a deletion all count. The issue is the record; a commit message, a PR body, or a chat reply is not a substitute.

  • Completed — close the issue, with a comment naming what landed and where (PR or commit).
  • Partly completed — leave it open and comment with what is done, what remains, and anything the remainder now depends on.
  • Not done — leave it open and comment with why: blocked, superseded, out of scope, or a precondition that has to change first.

Never close an issue that was not actually finished, and never leave finished work with the issue still open. If one change resolves several issues, update each of them.

Product claims

Threadbase's one hosted service is the optional Threadbase relay, which carries end-to-end encrypted traffic and stays off in stable streamer releases. Otherwise the app talks only to streamers the user runs, and README.md and docs/FEATURES.md state that as fact. Before writing or changing anything about relays, hosted backends, self-hosting, or where data goes, read docs/no-hosted-service.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.