Build your first feature

Beginner walkthrough

Prerequisites: Read the two beginner guides below, finish Mobile local setup, and open this repository at its root in your editor. Mobile settings belong in apps/mobile/.env.local; Expo does not read the root .env. The preview needs a reachable backend for real data.

Quick terms: a workspace is one team's separate users, data, and settings. The server is the trusted backend; keep provider keys out of browser and phone code. A migration is a versioned database change that creates or updates tables. An AI model is the engine that answers; the model catalog is the server's list of available model IDs and prices. A provider is an outside service such as an AI, email, or billing service. An entitlement is a grant that lets a workspace use a feature. A webhook is a message one service sends to another service's URL.

1. Open .agents/skills/add-a-mobile-screen/SKILL.md — or ask your coding agent to follow it — and create one small screen, for example apps/mobile/app/(app)/ideas.tsx with its logic in apps/mobile/src/ideas/.

2. Open the new screen on your device through the running preview and confirm it renders for a signed-in member.

3. Check a signed-out and a second-workspace account — anything that must stay private must come back denied or absent, because the server enforces the boundary.

For custom code, name the screen, the data it shows, who may see it and the errors to handle. Give your coding agent this task and ask it to read AGENTS.md, .ai/PROJECT_CONTEXT.md and the .ai/ mirrors of the files it will touch; list files and checks before editing; and show you the diff. Use sample values; never paste a real secret.

• Before you start
• Terminal basics
• Mobile local setup
• Agent workflow & project memory

Create the screen

Add a route file under apps/mobile/app/(app)/ — Expo Router turns the file into a screen inside the signed-in stack. Compose it from apps/mobile/src/ui primitives (Screen, Card, Title, Detail, AppButton) so it inherits the app's spacing, type and colors.

apps/mobile/app/(app)/ideas.tsx
apps/mobile/src/ideas/index.ts
apps/mobile/src/ideas/index.test.ts

Read and write through the typed client

Fetch through apps/mobile/src/api/client.ts, which attaches the stored session to each request against EXPO_PUBLIC_API_URL and returns typed errors. Keep payloads identical to the web contract — the same endpoints serve both clients.

If the screen reads workspace data, wrap the call with the helpers in apps/mobile/src/offline/ so a network failure can fall back to the cached copy — only on a network error, never after an auth or permission error.

Let the server decide ownership

The server resolves the signed-in member and the active workspace and scopes every record by workspaceId. The app displays what the server returns; it never sends a workspace id the server should trust.

If the data you need has no endpoint, add it on the backend first — business rules live on the server. A hidden button in the app does not enforce access.

Verify access and recovery

Check a signed-in member, a member of another workspace, a signed-out session and airplane mode: member data appears, foreign data is denied, a signed-out device returns to sign-in, and the offline copy serves only on a network error.

• Offline read cache
• Mobile security checklist

Polish the states

Give the screen loading, empty and error states through the shared primitives, add every new string to all four i18n catalogs, and wire the route into home or settings navigation so a member can actually find it.