# Build an iOS and web app with Fóir: steps for coding agents

These steps are for a coding agent setting up the Tilly template for a person who wants their own iOS and web app on Fóir. The person can read the same guide for people at [foir.io/get-started/ios-template](/get-started/ios-template).

## What you're setting up

Tilly is a complete app on Fóir. It has an iPhone app in SwiftUI, a website and web app in one TanStack Start project on one Cloudflare Worker, subscriptions through RevenueCat and Stripe, and an admin console that opens inside Fóir. Your job is to get it running in the person's own Fóir project, then hand over to the adapt-tilly skill, which turns it into their product.

## Rules

- Work only in a Fóir project the person names for development. Never touch a production project.
- Ask before anything that costs money: paid AI calls, purchases, or deploying to an account.
- Keep keys out of the repository and the browser. Provider keys go in the app's credential fields in Fóir.
- Read `AGENTS.md` and `README.md` in the repository before you change anything. Where they differ from this page, they win.
- Don't build backend infrastructure. Fóir is the backend, and operations hold only the app's own logic.

## Where you need the person

Stop and ask for these. You can do the rest yourself.

- Signing in to Fóir with OAuth when you connect the MCP server, and choosing the workspace and project.
- Signing in to Cloudflare for `wrangler`.
- Their Apple Developer team, to sign the iOS app.
- Every product answer in `/adapt-tilly`. Don't invent them.

## Steps

### 1. Check the machine

You need Node 22.18 or newer and pnpm 10.33. For iOS you need a Mac with Xcode.

```
node --version
pnpm --version
xcodebuild -version
```

### 2. Get the code

Start the person's own repository from the Tilly template at [github.com/mattblr/tilly](https://github.com/mattblr/tilly), as a new repository rather than a fork, then install the dependencies. With the GitHub CLI: `gh repo create <name> --private --clone --template mattblr/tilly`.

```
pnpm install --frozen-lockfile
```

### 3. Connect Fóir

Add Fóir's MCP server, `https://mcp.foir.dev/mcp`, and ask the person to sign in with OAuth. Confirm the workspace and project with them before any write. Read the tool schemas the server gives you instead of copying tool names from elsewhere.

Copy `.env.example` to `.env` and fill in the project and tenant IDs and the site origin. Leave the key variables empty: the first push creates the keys and writes them into `.env`.

### 4. Push the schema

On a fresh project, push the schema on its own. Show the person the dry run before you apply it.

```
FOIR_BOOTSTRAP_SCHEMA_ONLY=true pnpm exec foir push --no-prune --dry-run
FOIR_BOOTSTRAP_SCHEMA_ONLY=true pnpm exec foir push --no-prune
```

### 5. Deploy and install the app

Fill in the project and tenant in `web/wrangler.jsonc`, then build and deploy with the person's Cloudflare account. When the site serves `/_foir/apps/tilly.json`, install the app, apply the operations' quotas and push the full configuration.

```
pnpm build
pnpm deploy
foir apps install <origin>/_foir/apps/tilly.json
pnpm configure:operations
pnpm configure:operations --apply
pnpm exec foir push --no-prune
```

Load the example content after a dry run. The seed takes the project ID so it can only write to that project.

```
pnpm seed --dry-run
pnpm seed --development-project <project ID>
```

### 6. Check it

```
pnpm test
pnpm build
pnpm check:web
pnpm check:public
```

On a Mac, also run the `check:ios-*` scripts and build the iOS app. Tell the person what passed and what you couldn't check. Signing in with a real account, the camera and purchases need the person and a phone.

### 7. Hand over to the product interview

Run the adapt-tilly skill (`/adapt-tilly` in Claude Code). It asks the person about their app in short rounds and writes a product brief. Then plan-foir-app turns the brief into tickets, and build-foir-app builds them. Keep the shared parts working throughout: sign-in, billing, the CMS, the console and the Fóir integrations.

## Known gaps

Fóir doesn't yet do everything the template needs. `docs/known-gaps.md` in the repository lists each gap, the workaround the template uses and how Fóir will close it. Use the documented workaround and tell the person. Don't build a replacement for a missing platform feature.

## More

- The guide for people: [foir.io/get-started/ios-template](/get-started/ios-template)
- Fóir docs: [docs.foir.dev](https://docs.foir.dev)
- Fóir's MCP server: [docs.foir.dev/ai/mcp](https://docs.foir.dev/ai/mcp)
